107 lines
3.9 KiB
Markdown
107 lines
3.9 KiB
Markdown
# Mosaic Federation — Admin CLI Reference
|
|
|
|
Available since: FED-M2
|
|
|
|
## Grant Management
|
|
|
|
### Create a grant
|
|
|
|
```bash
|
|
mosaic federation grant create --user <userId> --peer <peerId> --scope <scope-file.json>
|
|
```
|
|
|
|
The scope file defines what resources and rows the peer may access:
|
|
|
|
```json
|
|
{
|
|
"resources": ["tasks", "notes"],
|
|
"excluded_resources": ["credentials"],
|
|
"max_rows_per_query": 100
|
|
}
|
|
```
|
|
|
|
Valid resource values: `tasks`, `notes`, `credentials`, `teams`, `users`
|
|
|
|
### List grants
|
|
|
|
```bash
|
|
mosaic federation grant list [--peer <peerId>] [--status pending|active|revoked|expired]
|
|
```
|
|
|
|
Shows all federation grants, optionally filtered by peer or status.
|
|
|
|
### Show a grant
|
|
|
|
```bash
|
|
mosaic federation grant show <grantId>
|
|
```
|
|
|
|
Display details of a single grant, including its scope, activation timestamp, and status.
|
|
|
|
### Revoke a grant
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|