# 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