Add client package.

client/README.org

@@ -0,0 +1,177 @@
+#+TITLE: MCIAS Client SDK
+
+The MCIAS Client SDK provides a Go client for interacting with the Metacircular Identity and Access System (MCIAS). It allows applications to authenticate users and retrieve database credentials from an MCIAS server.
+
+* Installation
+
+#+BEGIN_SRC bash
+go get git.wntrmute.dev/kyle/mcias/client
+#+END_SRC
+
+* Usage
+
+** Creating a Client
+
+#+BEGIN_SRC go
+import "git.wntrmute.dev/kyle/mcias/client"
+
+// Create a client with default settings (connects to http://localhost:8080)
+c := client.NewClient()
+
+// Create a client with custom settings
+c := client.NewClient(
+    client.WithBaseURL("https://mcias.example.com"),
+    client.WithUsername("username"),
+    client.WithToken("existing-token"),
+)
+#+END_SRC
+
+** Authentication
+
+*** Password Authentication
+
+#+BEGIN_SRC go
+ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+defer cancel()
+
+tokenResp, err := c.LoginWithPassword(ctx, "username", "password")
+if err != nil {
+    log.Fatalf("Failed to login: %v", err)
+}
+
+fmt.Printf("Authenticated with token: %s\n", tokenResp.Token)
+fmt.Printf("Token expires at: %s\n", time.Unix(tokenResp.Expires, 0).Format(time.RFC3339))
+
+// Check if TOTP verification is required
+if tokenResp.TOTPEnabled {
+    fmt.Println("TOTP verification required")
+    // See TOTP Verification section
+}
+#+END_SRC
+
+*** Token Authentication
+
+#+BEGIN_SRC go
+ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+defer cancel()
+
+tokenResp, err := c.LoginWithToken(ctx, "username", "existing-token")
+if err != nil {
+    log.Fatalf("Failed to login with token: %v", err)
+}
+
+fmt.Printf("Authenticated with token: %s\n", tokenResp.Token)
+fmt.Printf("Token expires at: %s\n", time.Unix(tokenResp.Expires, 0).Format(time.RFC3339))
+#+END_SRC
+
+*** TOTP Verification
+
+If TOTP is enabled for a user, you'll need to verify a TOTP code after password authentication:
+
+#+BEGIN_SRC go
+ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+defer cancel()
+
+totpResp, err := c.VerifyTOTP(ctx, "username", "123456") // Replace with actual TOTP code
+if err != nil {
+    log.Fatalf("Failed to verify TOTP: %v", err)
+}
+
+fmt.Printf("TOTP verified, token: %s\n", totpResp.Token)
+fmt.Printf("Token expires at: %s\n", time.Unix(totpResp.Expires, 0).Format(time.RFC3339))
+#+END_SRC
+
+** Retrieving Database Credentials
+
+Once authenticated, you can retrieve database credentials:
+
+#+BEGIN_SRC go
+ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+defer cancel()
+
+dbCreds, err := c.GetDatabaseCredentials(ctx)
+if err != nil {
+    log.Fatalf("Failed to get database credentials: %v", err)
+}
+
+fmt.Printf("Database Host: %s\n", dbCreds.Host)
+fmt.Printf("Database Port: %d\n", dbCreds.Port)
+fmt.Printf("Database Name: %s\n", dbCreds.Name)
+fmt.Printf("Database User: %s\n", dbCreds.User)
+fmt.Printf("Database Password: %s\n", dbCreds.Password)
+#+END_SRC
+
+* Complete Example
+
+Here's a complete example showing the authentication flow and database credential retrieval:
+
+#+BEGIN_SRC go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "time"
+
+    "git.wntrmute.dev/kyle/mcias/client"
+)
+
+func main() {
+    // Create a new client
+    c := client.NewClient()
+
+    // Create a context with timeout
+    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+    defer cancel()
+
+    // Authenticate with username and password
+    tokenResp, err := c.LoginWithPassword(ctx, "username", "password")
+    if err != nil {
+        log.Fatalf("Failed to login: %v", err)
+    }
+
+    fmt.Printf("Authenticated with token: %s\n", tokenResp.Token)
+    fmt.Printf("Token expires at: %s\n", time.Unix(tokenResp.Expires, 0).Format(time.RFC3339))
+
+    // If TOTP is enabled, verify the TOTP code
+    if tokenResp.TOTPEnabled {
+        fmt.Println("TOTP is enabled, please enter your TOTP code")
+        var totpCode string
+        fmt.Scanln(&totpCode)
+
+        totpResp, err := c.VerifyTOTP(ctx, "username", totpCode)
+        if err != nil {
+            log.Fatalf("Failed to verify TOTP: %v", err)
+        }
+
+        fmt.Printf("TOTP verified, new token: %s\n", totpResp.Token)
+        fmt.Printf("Token expires at: %s\n", time.Unix(totpResp.Expires, 0).Format(time.RFC3339))
+    }
+
+    // Get database credentials
+    dbCreds, err := c.GetDatabaseCredentials(ctx)
+    if err != nil {
+        log.Fatalf("Failed to get database credentials: %v", err)
+    }
+
+    fmt.Printf("Database Host: %s\n", dbCreds.Host)
+    fmt.Printf("Database Port: %d\n", dbCreds.Port)
+    fmt.Printf("Database Name: %s\n", dbCreds.Name)
+    fmt.Printf("Database User: %s\n", dbCreds.User)
+    fmt.Printf("Database Password: %s\n", dbCreds.Password)
+}
+#+END_SRC
+
+* Error Handling
+
+All methods return errors that should be checked. The errors include detailed information about what went wrong, including API error messages when available.
+
+* Configuration Options
+
+The client can be configured with the following options:
+
+- =WithBaseURL(baseURL string)=: Sets the base URL of the MCIAS server (default: "http://localhost:8080")
+- =WithHTTPClient(httpClient *http.Client)=: Sets a custom HTTP client (default: http.Client with 10s timeout)
+- =WithToken(token string)=: Sets an authentication token
+- =WithUsername(username string)=: Sets a username