Kyle Isom
7ede54afb2
- Add auth/login and auth/logout to mciasgrpcctl, calling the existing AuthService.Login/Logout RPCs; password is always prompted interactively (term.ReadPassword), never accepted as a flag, raw bytes zeroed after use - Add proto/mcias/v1/policy.proto with PolicyService (List, Create, Get, Update, Delete policy rules) - Regenerate gen/mcias/v1/ stubs to include policy - Implement internal/grpcserver/policyservice.go delegating to the same db layer as the REST policy handlers - Register PolicyService in grpcserver.go - Add policy list/create/get/update/delete to mciasgrpcctl - Update mciasgrpcctl man page with new commands Security: auth login uses the same interactive password prompt pattern as mciasctl; password never appears in process args, shell history, or logs; raw bytes zeroed after string conversion (same as REST CLI and REST server). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
150 lines
4.1 KiB
Groff
150 lines
4.1 KiB
Groff
.Dd March 12, 2026
|
|
.Dt MCIASGRPCCTL 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm mciasgrpcctl
|
|
.Nd MCIAS gRPC admin CLI
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl server Ar addr
|
|
.Op Fl token Ar jwt
|
|
.Op Fl cacert Ar path
|
|
.Ar command
|
|
.Op Ar subcommand
|
|
.Op Ar flags
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is the gRPC companion to
|
|
.Xr mciasctl 1 .
|
|
It connects to the gRPC/TLS listener of a running
|
|
.Xr mciassrv 1
|
|
instance and provides subcommands mirroring the REST admin CLI.
|
|
.Pp
|
|
The gRPC listener must be enabled in the mciassrv configuration
|
|
.Pq Sy grpc_addr
|
|
for
|
|
.Nm
|
|
to connect.
|
|
.Pp
|
|
Authentication is performed using a bearer JWT passed as gRPC metadata.
|
|
The token must have the
|
|
.Qq admin
|
|
role for most operations.
|
|
.Sh OPTIONS
|
|
.Bl -tag -width Ds
|
|
.It Fl server Ar addr
|
|
gRPC server address in
|
|
.Ar host:port
|
|
format.
|
|
Default:
|
|
.Qq mcias.metacircular.net:9443 .
|
|
.It Fl token Ar jwt
|
|
Bearer token for authentication.
|
|
Can also be set with the
|
|
.Ev MCIAS_TOKEN
|
|
environment variable.
|
|
.It Fl cacert Ar path
|
|
Path to a CA certificate in PEM format for TLS verification.
|
|
Useful when mciassrv uses a self-signed certificate.
|
|
.El
|
|
.Sh COMMANDS
|
|
.Ss Informational (no authentication required)
|
|
.Bl -tag -width Ds
|
|
.It Nm Ic health
|
|
Calls the Health RPC.
|
|
Prints
|
|
.Qq ok
|
|
and exits 0 if the server is healthy.
|
|
.It Nm Ic pubkey
|
|
Returns the server's Ed25519 public key as a JWK.
|
|
.El
|
|
.Ss auth
|
|
.Bl -tag -width Ds
|
|
.It Nm Ic auth Ic login Fl username Ar name Op Fl totp Ar code
|
|
Authenticates with the server and prints the bearer token to stdout.
|
|
The password is always prompted interactively.
|
|
Suitable for use in scripts:
|
|
.Bd -literal -offset indent
|
|
export MCIAS_TOKEN=$(mciasgrpcctl auth login -username alice)
|
|
.Ed
|
|
.It Nm Ic auth Ic logout
|
|
Revokes the current bearer token.
|
|
.El
|
|
.Ss account
|
|
.Bl -tag -width Ds
|
|
.It Nm Ic account Ic list
|
|
Lists all accounts.
|
|
.It Nm Ic account Ic create Fl username Ar name Fl password Ar pass Op Fl type Ar human|system
|
|
Creates a new account.
|
|
.It Nm Ic account Ic get Fl id Ar uuid
|
|
Returns the account with the given UUID.
|
|
.It Nm Ic account Ic update Fl id Ar uuid Fl status Ar active|inactive
|
|
Updates account status.
|
|
.It Nm Ic account Ic delete Fl id Ar uuid
|
|
Soft-deletes the account and revokes all its tokens.
|
|
.El
|
|
.Ss role
|
|
.Bl -tag -width Ds
|
|
.It Nm Ic role Ic list Fl id Ar uuid
|
|
Lists roles for the account.
|
|
.It Nm Ic role Ic set Fl id Ar uuid Fl roles Ar role1,role2,...
|
|
Replaces the role set for the account.
|
|
.El
|
|
.Ss token
|
|
.Bl -tag -width Ds
|
|
.It Nm Ic token Ic validate Fl token Ar jwt
|
|
Validates the given token and prints its claims.
|
|
.It Nm Ic token Ic issue Fl id Ar uuid
|
|
Issues a new service token for a system account.
|
|
.It Nm Ic token Ic revoke Fl jti Ar jti
|
|
Revokes the token with the given JTI.
|
|
.El
|
|
.Ss pgcreds
|
|
.Bl -tag -width Ds
|
|
.It Nm Ic pgcreds Ic get Fl id Ar uuid
|
|
Returns the Postgres credentials for the account.
|
|
.It Nm Ic pgcreds Ic set Fl id Ar uuid Fl host Ar host Op Fl port Ar port Fl db Ar db Fl user Ar user Fl password Ar pass
|
|
Sets Postgres credentials for the account.
|
|
.El
|
|
.Ss policy
|
|
.Bl -tag -width Ds
|
|
.It Nm Ic policy Ic list
|
|
Lists all policy rules.
|
|
.It Nm Ic policy Ic create Fl description Ar str Fl json Ar file Op Fl priority Ar n Op Fl not-before Ar rfc3339 Op Fl expires-at Ar rfc3339
|
|
Creates a new policy rule.
|
|
.Ar file
|
|
must be a path to a file containing a JSON rule body.
|
|
.It Nm Ic policy Ic get Fl id Ar id
|
|
Returns the policy rule with the given ID.
|
|
.It Nm Ic policy Ic update Fl id Ar id Op Fl priority Ar n Op Fl enabled Ar true|false Op Fl not-before Ar rfc3339 Op Fl expires-at Ar rfc3339 Op Fl clear-not-before Op Fl clear-expires-at
|
|
Applies a partial update to a policy rule.
|
|
.It Nm Ic policy Ic delete Fl id Ar id
|
|
Permanently removes a policy rule.
|
|
.El
|
|
.Sh ENVIRONMENT
|
|
.Bl -tag -width Ds
|
|
.It Ev MCIAS_TOKEN
|
|
Bearer token used for authentication when
|
|
.Fl token
|
|
is not specified.
|
|
.El
|
|
.Sh EXAMPLES
|
|
Check server health over gRPC:
|
|
.Bd -literal -offset indent
|
|
mciasgrpcctl -server auth.example.com:9443 -cacert /etc/mcias/ca.crt health
|
|
.Ed
|
|
.Pp
|
|
Using grpcurl as an alternative client:
|
|
.Bd -literal -offset indent
|
|
grpcurl -cacert /etc/mcias/ca.crt \\
|
|
-H "authorization: Bearer $TOKEN" \\
|
|
auth.example.com:9443 \\
|
|
mcias.v1.AdminService/Health
|
|
.Ed
|
|
.Sh EXIT STATUS
|
|
.Ex -std
|
|
.Sh SEE ALSO
|
|
.Xr mciassrv 1 ,
|
|
.Xr mciasctl 1 ,
|
|
.Xr mciasdb 1
|