MCIASSRV(1)

NAME
mciassrv - MCIAS authentication server

SYNOPSIS
mciassrv -config path

DESCRIPTION
mciassrv is the MCIAS (Metacircular Identity and Access System) authentication server. It provides a single-sign-on (SSO) and identity and access management (IAM) service for personal applications.

mciassrv reads a TOML configuration file, derives the AES-256 master encryption key, loads or generates an Ed25519 signing key, opens the SQLite database, applies any pending schema migrations, and starts an HTTPS listener.

If the grpc_addr field is set in the configuration file, a gRPC/TLS listener is also started on the specified address. Both listeners share the same signing key, database connection, and configuration.

OPTIONS

-config path
    Path to the TOML configuration file. Defaults to mcias.toml in the current directory.

CONFIGURATION
The configuration file is in TOML format. See /etc/mcias/mcias.conf (or dist/mcias.conf.example in the source tree) for a fully-commented reference configuration.

The following sections are recognised:

[server]

    listen_addr
        (required) Host and port for the HTTPS REST listener. Example: "0.0.0.0:8443".

    grpc_addr
        (optional) Host and port for the gRPC/TLS listener. If omitted, gRPC is disabled. Example: "0.0.0.0:9443".

    tls_cert
        (required) Path to the TLS certificate file in PEM format.

    tls_key
        (required) Path to the TLS private key file in PEM format.

[database]

    path
        (required) Path to the SQLite database file. WAL mode and foreign key enforcement are enabled automatically.

[tokens]

    issuer
        (required) Issuer claim embedded in every JWT. Use the base URL of your MCIAS server.

    default_expiry
        (optional, default 168h) Token expiry for interactive logins. Go duration string.

    admin_expiry
        (optional, default 8h) Token expiry for tokens with the "admin" role.

    service_expiry
        (optional, default 8760h) Token expiry for system account tokens.

[argon2]

    time
        (optional, default 3) Argon2id time cost. Must be >= 2 (OWASP 2023 minimum).

    memory
        (optional, default 65536) Argon2id memory cost in KiB. Must be >= 65536 (64 MB, OWASP 2023 minimum).

    threads
        (optional, default 4) Argon2id parallelism.

[master_key]
    Exactly one of the following must be set:

    passphrase_env
        Name of the environment variable containing the master key passphrase. The passphrase is read at startup and the environment variable is immediately cleared.

    keyfile
        Path to a file containing exactly 32 bytes of raw AES-256 key material.

REST API
mciassrv exposes the following REST endpoints over HTTPS:

GET /v1/health
    Returns "{"status":"ok"}" with HTTP 200. No authentication required.

GET /v1/keys/public
    Returns the Ed25519 public key as a JWK. No authentication required.

POST /v1/auth/login
    Authenticates a user and issues a JWT. Body: JSON with username, password, and optionally totp_code. Returns token and expires_at.

POST /v1/auth/logout
    Revokes the current JWT. Requires a valid Bearer token. Returns HTTP 204.

POST /v1/auth/renew
    Renews the current JWT, revoking the old one. Requires a valid Bearer token. Returns token and expires_at.

POST /v1/token/validate
    Validates a submitted token and returns its claims.

DELETE /v1/token/{jti}
    Revokes a token by JTI. Requires admin role.

POST /v1/accounts
    Creates a new account. Requires admin role.

GET /v1/accounts
    Lists all accounts (no credential fields in response). Requires admin role.

GET /v1/accounts/{id}
    Returns a single account. Requires admin role.

PATCH /v1/accounts/{id}
    Updates an account. Requires admin role.

DELETE /v1/accounts/{id}
    Soft-deletes an account and revokes all its tokens. Requires admin role.

GET /v1/accounts/{id}/roles
    Returns the role set for an account. Requires admin role.

PUT /v1/accounts/{id}/roles
    Replaces the role set for an account. Requires admin role.

POST /v1/auth/totp/enroll
    Generates a TOTP secret and returns the otpauth URI. Requires authentication.

POST /v1/auth/totp/confirm
    Confirms TOTP enrollment. Requires authentication.

DELETE /v1/auth/totp
    Removes TOTP from an account. Requires admin role.

GET /v1/accounts/{id}/pgcreds
    Returns the Postgres credentials for an account (decrypted). Requires admin role.

PUT /v1/accounts/{id}/pgcreds
    Sets Postgres credentials for an account. Requires admin role.

SIGNALS

SIGINT, SIGTERM
    Initiate graceful shutdown. In-flight requests are drained for up to 15 seconds before the server exits.

EXIT STATUS

FILES

/etc/mcias/mcias.conf
    Default configuration file location.

/etc/mcias/server.crt
    TLS certificate (operator-supplied).

/etc/mcias/server.key
    TLS private key (operator-supplied).

/var/lib/mcias/mcias.db
    SQLite database.

/etc/systemd/system/mcias.service
    systemd service unit.

SEE ALSO
mciasctl(1), mciasdb(1), mciasgrpcctl(1)

SECURITY
mciassrv enforces TLS 1.2 as the minimum protocol version. All JWTs are signed with Ed25519; the alg header is validated before any other processing to defeat algorithm confusion attacks. Password hashing uses Argon2id with parameters meeting or exceeding the OWASP 2023 recommendations. Credential fields (password hashes, TOTP secrets, Postgres passwords) are never included in any API response.