stack/docs/federation/ADMIN-CLI.md

Mosaic Federation — Admin CLI Reference

Available since: FED-M2

Grant Management

Create a grant

mosaic federation grant create --user <userId> --peer <peerId> --scope <scope-file.json>

The scope file defines what resources and rows the peer may access:

{
  "resources": ["tasks", "notes"],
  "excluded_resources": ["credentials"],
  "max_rows_per_query": 100
}

Valid resource values: tasks, notes, credentials, teams, users

List grants

mosaic federation grant list [--peer <peerId>] [--status pending|active|revoked|expired]

Shows all federation grants, optionally filtered by peer or status.

Show a grant

mosaic federation grant show <grantId>

Display details of a single grant, including its scope, activation timestamp, and status.

Revoke a grant

mosaic federation grant revoke <grantId> [--reason "Reason text"]

Revoke an active grant immediately. Revoked grants cannot be reactivated. The optional reason is stored in the audit log.

Generate enrollment token

mosaic federation grant token <grantId> [--ttl <seconds>]

Generate a single-use enrollment token for the grant. The default TTL is 900 seconds (15 minutes); maximum 15 minutes.

Output includes the token and the full enrollment URL for the peer to use.

Peer Management

Add a peer (remote enrollment)

mosaic federation peer add <enrollment-url>

Enroll a remote peer using the enrollment URL obtained from a grant token. The command:

1. Generates a P-256 ECDSA keypair locally
2. Creates a certificate signing request (CSR)
3. Submits the CSR to the enrollment URL
4. Verifies the returned certificate includes the correct custom OIDs (grant ID and subject user ID)
5. Seals the private key at rest using BETTER_AUTH_SECRET
6. Stores the peer record and sealed key in the local gateway database

Once enrollment completes, the peer can authenticate using the certificate and private key.

List peers

mosaic federation peer list

Shows all enrolled peers, including their certificate fingerprints and activation status.

REST API Reference

All CLI commands call the local gateway admin API. Equivalent REST endpoints:

CLI Command	REST Endpoint	Method
grant create	/api/admin/federation/grants	POST
grant list	/api/admin/federation/grants	GET
grant show	/api/admin/federation/grants/:id	GET
grant revoke	/api/admin/federation/grants/:id/revoke	PATCH
grant token	/api/admin/federation/grants/:id/tokens	POST
peer list	/api/admin/federation/peers	GET
peer add	/api/admin/federation/peers/keypair + enrollment + /api/admin/federation/peers/:id/cert	POST, POST, PATCH

Security Notes

• Enrollment tokens are single-use and expire in 15 minutes (not configurable beyond 15 minutes)
• Peer private keys are encrypted at rest using AES-256-GCM, keyed from BETTER_AUTH_SECRET
• Custom OIDs in issued certificates are verified post-issuance: the grant ID and subject user ID must match the certificate extensions
• Grant activation is atomic — concurrent enrollment attempts for the same grant are rejected
• Revoked grants cannot be activated; peers attempting to use a revoked grant's token will be rejected