# mcias-client (Go)

Go client library for the [MCIAS](../../README.md) identity and access management API.

## Requirements

- Go 1.21+

## Installation

```sh
go get git.wntrmute.dev/kyle/mcias/clients/go
```

## Quick Start

```go
import mciasgoclient "git.wntrmute.dev/kyle/mcias/clients/go"

// Connect to the MCIAS server.
client, err := mciasgoclient.New("https://auth.example.com", mciasgoclient.Options{})
if err != nil {
    log.Fatal(err)
}

// Authenticate.
token, expiresAt, err := client.Login("alice", "s3cret", "")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("token expires at %s\n", expiresAt)

// The token is stored in the client automatically.
// Call authenticated endpoints...
accounts, err := client.ListAccounts()

// Revoke the token when done.
if err := client.Logout(); err != nil {
    log.Fatal(err)
}
```

## Custom CA Certificate

```go
client, err := mciasgoclient.New("https://auth.example.com", mciasgoclient.Options{
    CACertPath: "/etc/mcias/ca.pem",
})
```

## Error Handling

All methods return typed errors:

```go
_, _, err := client.Login("alice", "wrongpass", "")
switch {
case errors.Is(err, new(mciasgoclient.MciasAuthError)):
    // 401 — wrong credentials or token invalid
case errors.Is(err, new(mciasgoclient.MciasForbiddenError)):
    // 403 — insufficient role
case errors.Is(err, new(mciasgoclient.MciasNotFoundError)):
    // 404 — resource not found
case errors.Is(err, new(mciasgoclient.MciasInputError)):
    // 400 — malformed request
case errors.Is(err, new(mciasgoclient.MciasConflictError)):
    // 409 — conflict (e.g. duplicate username)
case errors.Is(err, new(mciasgoclient.MciasServerError)):
    // 5xx — unexpected server error
}
```

All error types embed `MciasError` which carries `StatusCode int` and
`Message string`.

## Thread Safety

`Client` is safe for concurrent use from multiple goroutines. The internal
token is protected by `sync.RWMutex`.

## Running Tests

```sh
go test -race ./...
```