mcias/client/README.org

#+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