mcias/man/man1/mciassrv.1

.Dd March 11, 2026
.Dt MCIASSRV 1
.Os
.Sh NAME
.Nm mciassrv
.Nd MCIAS authentication server
.Sh SYNOPSIS
.Nm
.Fl config
.Ar path
.Sh DESCRIPTION
.Nm
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.
.Pp
.Nm
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.
.Pp
If the
.Sy 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.
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl config Ar path
Path to the TOML configuration file.
Defaults to
.Pa mcias.toml
in the current directory.
.El
.Sh CONFIGURATION
The configuration file is in TOML format.
See
.Pa /etc/mcias/mcias.conf
(or
.Pa dist/mcias.conf.example
in the source tree) for a fully-commented reference configuration.
.Pp
The following sections are recognised:
.Bl -tag -width Ds
.It Sy [server]
.Bl -tag -width Ds
.It Sy listen_addr
.Pq required
Host and port for the HTTPS REST listener.
Example:
.Qq 0.0.0.0:8443 .
.It Sy grpc_addr
.Pq optional
Host and port for the gRPC/TLS listener.
If omitted, gRPC is disabled.
Example:
.Qq 0.0.0.0:9443 .
.It Sy tls_cert
.Pq required
Path to the TLS certificate file in PEM format.
.It Sy tls_key
.Pq required
Path to the TLS private key file in PEM format.
.El
.It Sy [database]
.Bl -tag -width Ds
.It Sy path
.Pq required
Path to the SQLite database file.
WAL mode and foreign key enforcement are enabled automatically.
.El
.It Sy [tokens]
.Bl -tag -width Ds
.It Sy issuer
.Pq required
Issuer claim embedded in every JWT.
Use the base URL of your MCIAS server.
.It Sy default_expiry
.Pq optional, default 720h
Token expiry for interactive logins.
Go duration string.
.It Sy admin_expiry
.Pq optional, default 8h
Token expiry for tokens with the
.Qq admin
role.
.It Sy service_expiry
.Pq optional, default 8760h
Token expiry for system account tokens.
.El
.It Sy [argon2]
.Bl -tag -width Ds
.It Sy time
.Pq optional, default 3
Argon2id time cost.
Must be >= 2 (OWASP 2023 minimum).
.It Sy memory
.Pq optional, default 65536
Argon2id memory cost in KiB.
Must be >= 65536 (64 MB, OWASP 2023 minimum).
.It Sy threads
.Pq optional, default 4
Argon2id parallelism.
.El
.It Sy [master_key]
Exactly one of the following must be set:
.Bl -tag -width Ds
.It Sy 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.
.It Sy keyfile
Path to a file containing exactly 32 bytes of raw AES-256 key material.
.El
.El
.Sh REST API
.Nm
exposes the following REST endpoints over HTTPS:
.Bl -tag -width Ds
.It GET /v1/health
Returns
.Qq {"status":"ok"}
with HTTP 200.
No authentication required.
.It GET /v1/keys/public
Returns the Ed25519 public key as a JWK.
No authentication required.
.It POST /v1/auth/login
Authenticates a user and issues a JWT.
Body: JSON with
.Sy username ,
.Sy password ,
and optionally
.Sy totp_code .
Returns
.Sy token
and
.Sy expires_at .
.It POST /v1/auth/logout
Revokes the current JWT.
Requires a valid Bearer token.
Returns HTTP 204.
.It POST /v1/auth/renew
Renews the current JWT, revoking the old one.
Requires a valid Bearer token.
Returns
.Sy token
and
.Sy expires_at .
.It POST /v1/token/validate
Validates a submitted token and returns its claims.
.It DELETE /v1/token/{jti}
Revokes a token by JTI.
Requires admin role.
.It POST /v1/accounts
Creates a new account.
Requires admin role.
.It GET /v1/accounts
Lists all accounts (no credential fields in response).
Requires admin role.
.It GET /v1/accounts/{id}
Returns a single account.
Requires admin role.
.It PATCH /v1/accounts/{id}
Updates an account.
Requires admin role.
.It DELETE /v1/accounts/{id}
Soft-deletes an account and revokes all its tokens.
Requires admin role.
.It GET /v1/accounts/{id}/roles
Returns the role set for an account.
Requires admin role.
.It PUT /v1/accounts/{id}/roles
Replaces the role set for an account.
Requires admin role.
.It POST /v1/auth/totp/enroll
Generates a TOTP secret and returns the otpauth URI.
Requires authentication.
.It POST /v1/auth/totp/confirm
Confirms TOTP enrollment.
Requires authentication.
.It DELETE /v1/auth/totp
Removes TOTP from an account.
Requires admin role.
.It GET /v1/accounts/{id}/pgcreds
Returns the Postgres credentials for an account (decrypted).
Requires admin role.
.It PUT /v1/accounts/{id}/pgcreds
Sets Postgres credentials for an account.
Requires admin role.
.El
.Sh SIGNALS
.Bl -tag -width Ds
.It Dv SIGINT , SIGTERM
Initiate graceful shutdown.
In-flight requests are drained for up to 15 seconds before the server exits.
.El
.Sh EXIT STATUS
.Ex -std
.Sh FILES
.Bl -tag -width Ds
.It Pa /etc/mcias/mcias.conf
Default configuration file location.
.It Pa /etc/mcias/server.crt
TLS certificate (operator-supplied).
.It Pa /etc/mcias/server.key
TLS private key (operator-supplied).
.It Pa /var/lib/mcias/mcias.db
SQLite database.
.It Pa /etc/systemd/system/mcias.service
systemd service unit.
.El
.Sh SEE ALSO
.Xr mciasctl 1 ,
.Xr mciasdb 1 ,
.Xr mciasgrpcctl 1
.Sh SECURITY
.Nm
enforces TLS 1.2 as the minimum protocol version.
All JWTs are signed with Ed25519; the
.Sy 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.