fix(types): capabilities response — add filters + rate_limit stub + tighten supported_verbs (review remediation)

- HIGH-1: add `filters` field (mirrors FederationScope PRD §8.1) and `rate_limit` stub (PRD §9.1) to FederationCapabilitiesResponseSchema; M4 populates remaining/reset_at
- MED-3: tighten supported_verbs from z.array(z.string()) to z.array(z.enum(FEDERATION_VERBS)) closed enum
- Add 10 new test cases covering filters shape, rate_limit full/minimal/absent/invalid, and invalid verb rejection

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

apps/gateway/src/__tests__/integration/federation-m2-e2e.integration.test.ts

@@ -0,0 +1,243 @@
+/**
+ * Federation M2 E2E test — peer-add enrollment flow (FED-M2-10).
+ *
+ * Covers MILESTONES.md acceptance test #6:
+ *   "`peer add <url>` on Server A yields an `active` peer record with a valid cert + key"
+ *
+ * This test simulates two gateways using a single bootstrapped NestJS app:
+ *   - "Server A": the admin API that generates a keypair and stores the cert
+ *   - "Server B": the enrollment endpoint that signs the CSR
+ *   Both share the same DB + Step-CA in the test environment.
+ *
+ * Prerequisites:
+ *   docker compose -f docker-compose.federated.yml --profile federated up -d
+ *
+ * Run:
+ *   FEDERATED_INTEGRATION=1 STEP_CA_AVAILABLE=1 \
+ *   STEP_CA_URL=https://localhost:9000 \
+ *   STEP_CA_PROVISIONER_KEY_JSON="$(docker exec $(docker ps -qf name=step-ca) cat /home/step/secrets/mosaic-fed.json)" \
+ *   STEP_CA_ROOT_CERT_PATH=/tmp/step-ca-root.crt \
+ *   pnpm --filter @mosaicstack/gateway test \
+ *     src/__tests__/integration/federation-m2-e2e.integration.test.ts
+ *
+ * Obtaining Step-CA credentials:
+ *   # Extract provisioner key from running container:
+ *   #   docker exec $(docker ps -qf name=step-ca) cat /home/step/secrets/mosaic-fed.json
+ *   # Copy root cert from container:
+ *   #   docker cp $(docker ps -qf name=step-ca):/home/step/certs/root_ca.crt /tmp/step-ca-root.crt
+ *   # Then: export STEP_CA_ROOT_CERT_PATH=/tmp/step-ca-root.crt
+ *
+ * Skipped unless both FEDERATED_INTEGRATION=1 and STEP_CA_AVAILABLE=1 are set.
+ */
+
+import * as crypto from 'node:crypto';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { Test } from '@nestjs/testing';
+import { ValidationPipe } from '@nestjs/common';
+import { FastifyAdapter, type NestFastifyApplication } from '@nestjs/platform-fastify';
+import supertest from 'supertest';
+import {
+  createDb,
+  type Db,
+  type DbHandle,
+  federationPeers,
+  federationGrants,
+  federationEnrollmentTokens,
+  inArray,
+  eq,
+} from '@mosaicstack/db';
+import * as schema from '@mosaicstack/db';
+import { DB } from '../../database/database.module.js';
+import { AdminGuard } from '../../admin/admin.guard.js';
+import { FederationModule } from '../../federation/federation.module.js';
+import { GrantsService } from '../../federation/grants.service.js';
+import { EnrollmentService } from '../../federation/enrollment.service.js';
+
+const run = process.env['FEDERATED_INTEGRATION'] === '1';
+const stepCaRun =
+  run &&
+  process.env['STEP_CA_AVAILABLE'] === '1' &&
+  !!process.env['STEP_CA_URL'] &&
+  !!process.env['STEP_CA_PROVISIONER_KEY_JSON'] &&
+  !!process.env['STEP_CA_ROOT_CERT_PATH'];
+
+const PG_URL = 'postgresql://mosaic:mosaic@localhost:5433/mosaic';
+
+const RUN_ID = crypto.randomUUID();
+
+describe.skipIf(!stepCaRun)('federation M2 E2E — peer add enrollment flow', () => {
+  let handle: DbHandle;
+  let db: Db;
+  let app: NestFastifyApplication;
+  let agent: ReturnType<typeof supertest>;
+  let grantsService: GrantsService;
+  let enrollmentService: EnrollmentService;
+
+  const createdTokenGrantIds: string[] = [];
+  const createdGrantIds: string[] = [];
+  const createdPeerIds: string[] = [];
+  const createdUserIds: string[] = [];
+
+  beforeAll(async () => {
+    process.env['BETTER_AUTH_SECRET'] ??= 'test-e2e-sealing-key';
+
+    handle = createDb(PG_URL);
+    db = handle.db;
+
+    const moduleRef = await Test.createTestingModule({
+      imports: [FederationModule],
+      providers: [{ provide: DB, useValue: db }],
+    })
+      .overrideGuard(AdminGuard)
+      .useValue({ canActivate: () => true })
+      .compile();
+
+    app = moduleRef.createNestApplication<NestFastifyApplication>(new FastifyAdapter());
+    app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
+    await app.init();
+    await app.getHttpAdapter().getInstance().ready();
+
+    agent = supertest(app.getHttpServer());
+
+    grantsService = moduleRef.get(GrantsService);
+    enrollmentService = moduleRef.get(EnrollmentService);
+  }, 30_000);
+
+  afterAll(async () => {
+    if (db && createdTokenGrantIds.length > 0) {
+      await db
+        .delete(federationEnrollmentTokens)
+        .where(inArray(federationEnrollmentTokens.grantId, createdTokenGrantIds))
+        .catch((e: unknown) => console.error('[federation-m2-e2e cleanup]', e));
+    }
+    if (db && createdGrantIds.length > 0) {
+      await db
+        .delete(federationGrants)
+        .where(inArray(federationGrants.id, createdGrantIds))
+        .catch((e: unknown) => console.error('[federation-m2-e2e cleanup]', e));
+    }
+    if (db && createdPeerIds.length > 0) {
+      await db
+        .delete(federationPeers)
+        .where(inArray(federationPeers.id, createdPeerIds))
+        .catch((e: unknown) => console.error('[federation-m2-e2e cleanup]', e));
+    }
+    if (db && createdUserIds.length > 0) {
+      await db
+        .delete(schema.users)
+        .where(inArray(schema.users.id, createdUserIds))
+        .catch((e: unknown) => console.error('[federation-m2-e2e cleanup]', e));
+    }
+    if (app)
+      await app.close().catch((e: unknown) => console.error('[federation-m2-e2e cleanup]', e));
+    if (handle)
+      await handle.close().catch((e: unknown) => console.error('[federation-m2-e2e cleanup]', e));
+  });
+
+  // -------------------------------------------------------------------------
+  // #6 — peer add: keypair → enrollment → cert storage → active peer record
+  // -------------------------------------------------------------------------
+  it('#6 — peer add flow: keypair → enrollment → cert storage → active peer record', async () => {
+    // Create a subject user to satisfy FK on federation_grants.subject_user_id
+    const userId = crypto.randomUUID();
+    await db
+      .insert(schema.users)
+      .values({
+        id: userId,
+        name: `e2e-user-${RUN_ID}`,
+        email: `e2e-${RUN_ID}@federation-test.invalid`,
+        emailVerified: false,
+      })
+      .onConflictDoNothing();
+    createdUserIds.push(userId);
+
+    // ── Step A: "Server B" setup ─────────────────────────────────────────
+    // Server B admin creates a grant and generates an enrollment token to
+    // share out-of-band with Server A's operator.
+
+    // Insert a placeholder peer on "Server B" to satisfy the grant FK
+    const serverBPeerId = crypto.randomUUID();
+    await db
+      .insert(federationPeers)
+      .values({
+        id: serverBPeerId,
+        commonName: `server-b-peer-${RUN_ID}`,
+        displayName: 'Server B Placeholder',
+        certPem: '-----BEGIN CERTIFICATE-----\nMOCK\n-----END CERTIFICATE-----\n',
+        certSerial: `serial-b-${serverBPeerId}`,
+        certNotAfter: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000),
+        state: 'pending',
+      })
+      .onConflictDoNothing();
+    createdPeerIds.push(serverBPeerId);
+
+    const grant = await grantsService.createGrant({
+      subjectUserId: userId,
+      scope: { resources: ['tasks'], excluded_resources: [], max_rows_per_query: 100 },
+      peerId: serverBPeerId,
+    });
+    createdGrantIds.push(grant.id);
+    createdTokenGrantIds.push(grant.id);
+
+    const { token } = await enrollmentService.createToken({
+      grantId: grant.id,
+      peerId: serverBPeerId,
+      ttlSeconds: 900,
+    });
+
+    // ── Step B: "Server A" generates keypair ─────────────────────────────
+    const keypairRes = await agent
+      .post('/api/admin/federation/peers/keypair')
+      .send({
+        commonName: `e2e-peer-${RUN_ID.slice(0, 8)}`,
+        displayName: 'E2E Test Peer',
+        endpointUrl: 'https://test.invalid',
+      })
+      .set('Content-Type', 'application/json');
+
+    expect(keypairRes.status).toBe(201);
+    const { peerId, csrPem } = keypairRes.body as { peerId: string; csrPem: string };
+    expect(typeof peerId).toBe('string');
+    expect(csrPem).toContain('-----BEGIN CERTIFICATE REQUEST-----');
+    createdPeerIds.push(peerId);
+
+    // ── Step C: Enrollment (simulates Server A sending CSR to Server B) ──
+    const enrollRes = await agent
+      .post(`/api/federation/enrollment/${token}`)
+      .send({ csrPem })
+      .set('Content-Type', 'application/json');
+
+    expect(enrollRes.status).toBe(200);
+    const { certPem, certChainPem } = enrollRes.body as {
+      certPem: string;
+      certChainPem: string;
+    };
+    expect(certPem).toContain('-----BEGIN CERTIFICATE-----');
+    expect(certChainPem).toContain('-----BEGIN CERTIFICATE-----');
+
+    // ── Step D: "Server A" stores the cert ───────────────────────────────
+    const storeRes = await agent
+      .patch(`/api/admin/federation/peers/${peerId}/cert`)
+      .send({ certPem })
+      .set('Content-Type', 'application/json');
+
+    expect(storeRes.status).toBe(200);
+
+    // ── Step E: Verify peer record in DB ─────────────────────────────────
+    const [peer] = await db
+      .select()
+      .from(federationPeers)
+      .where(eq(federationPeers.id, peerId))
+      .limit(1);
+
+    expect(peer).toBeDefined();
+    expect(peer?.state).toBe('active');
+    expect(peer?.certPem).toContain('-----BEGIN CERTIFICATE-----');
+    expect(typeof peer?.certSerial).toBe('string');
+    expect((peer?.certSerial ?? '').length).toBeGreaterThan(0);
+    // clientKeyPem is a sealed ciphertext — must not be a raw PEM
+    expect(peer?.clientKeyPem?.startsWith('-----BEGIN')).toBe(false);
+    // certNotAfter must be in the future
+    expect(peer?.certNotAfter?.getTime()).toBeGreaterThan(Date.now());
+  }, 60_000);
+});

apps/gateway/src/federation/ca.service.ts

@@ -35,7 +35,7 @@ import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as https from 'node:https';
 import { SignJWT, importJWK } from 'jose';
-import { Pkcs10CertificateRequest } from '@peculiar/x509';
+import { Pkcs10CertificateRequest, X509Certificate } from '@peculiar/x509';
 import type { IssueCertRequestDto } from './ca.dto.js';
 import { IssuedCertDto } from './ca.dto.js';
 
@@ -624,6 +624,51 @@ export class CaService {
 
     const serialNumber = extractSerial(response.crt);
 
+    // CRIT-1: Verify the issued certificate contains both Mosaic OID extensions
+    // with the correct values. Step-CA's federation.tpl encodes each as an ASN.1
+    // UTF8String TLV: tag 0x0C + 1-byte length + UUID bytes. We skip 2 bytes
+    // (tag + length) to extract the raw UUID string.
+    const issuedCert = new X509Certificate(response.crt);
+    const decoder = new TextDecoder();
+
+    const grantIdExt = issuedCert.getExtension('1.3.6.1.4.1.99999.1');
+    if (!grantIdExt) {
+      throw new CaServiceError(
+        'Issued certificate is missing required Mosaic OID: mosaic_grant_id',
+        'The Step-CA federation.tpl template did not embed OID 1.3.6.1.4.1.99999.1. Check the provisioner template configuration.',
+        undefined,
+        'OID_MISSING',
+      );
+    }
+    const grantIdInCert = decoder.decode(grantIdExt.value.slice(2));
+    if (grantIdInCert !== req.grantId) {
+      throw new CaServiceError(
+        `Issued certificate mosaic_grant_id mismatch: expected ${req.grantId}, got ${grantIdInCert}`,
+        'The Step-CA issued a certificate with a different grant ID than requested. This may indicate a provisioner misconfiguration or a MITM.',
+        undefined,
+        'OID_MISMATCH',
+      );
+    }
+
+    const subjectUserIdExt = issuedCert.getExtension('1.3.6.1.4.1.99999.2');
+    if (!subjectUserIdExt) {
+      throw new CaServiceError(
+        'Issued certificate is missing required Mosaic OID: mosaic_subject_user_id',
+        'The Step-CA federation.tpl template did not embed OID 1.3.6.1.4.1.99999.2. Check the provisioner template configuration.',
+        undefined,
+        'OID_MISSING',
+      );
+    }
+    const subjectUserIdInCert = decoder.decode(subjectUserIdExt.value.slice(2));
+    if (subjectUserIdInCert !== req.subjectUserId) {
+      throw new CaServiceError(
+        `Issued certificate mosaic_subject_user_id mismatch: expected ${req.subjectUserId}, got ${subjectUserIdInCert}`,
+        'The Step-CA issued a certificate with a different subject user ID than requested. This may indicate a provisioner misconfiguration or a MITM.',
+        undefined,
+        'OID_MISMATCH',
+      );
+    }
+
     this.logger.log(`Certificate issued — serial=${serialNumber} grantId=${req.grantId}`);
 
     const result = new IssuedCertDto();

apps/gateway/src/federation/enrollment.service.ts

@@ -14,6 +14,7 @@
 
 import {
   BadRequestException,
+  ConflictException,
   GoneException,
   Inject,
   Injectable,
@@ -66,6 +67,21 @@ export class EnrollmentService {
    */
   async createToken(dto: CreateEnrollmentTokenDto): Promise<EnrollmentTokenResult> {
     const ttl = Math.min(dto.ttlSeconds, 900);
+
+    // MED-3: Verify the grantId ↔ peerId binding — prevents attacker from
+    // cross-wiring grants to attacker-controlled peers.
+    const [grant] = await this.db
+      .select({ peerId: federationGrants.peerId })
+      .from(federationGrants)
+      .where(eq(federationGrants.id, dto.grantId))
+      .limit(1);
+    if (!grant) {
+      throw new NotFoundException(`Grant ${dto.grantId} not found`);
+    }
+    if (grant.peerId !== dto.peerId) {
+      throw new BadRequestException(`peerId does not match the grant's registered peer`);
+    }
+
     const token = crypto.randomBytes(32).toString('hex');
     const expiresAt = new Date(Date.now() + ttl * 1000);
 
@@ -99,16 +115,23 @@ export class EnrollmentService {
    *  8. Return { certPem, certChainPem }
    */
   async redeem(token: string, csrPem: string): Promise<RedeemResult> {
+    // HIGH-5: Track outcome so we can write a failure audit row on any error.
+    let outcome: 'allowed' | 'denied' = 'denied';
+    // row may be undefined if the token is not found — used defensively in catch.
+    let row: typeof federationEnrollmentTokens.$inferSelect | undefined;
+
+    try {
       // 1. Fetch token row
-    const [row] = await this.db
+      const [fetchedRow] = await this.db
         .select()
         .from(federationEnrollmentTokens)
         .where(eq(federationEnrollmentTokens.token, token))
         .limit(1);
 
-    if (!row) {
+      if (!fetchedRow) {
         throw new NotFoundException('Enrollment token not found');
       }
+      row = fetchedRow;
 
       // 2. Already used?
       if (row.usedAt !== null) {
@@ -144,7 +167,10 @@ export class EnrollmentService {
         .update(federationEnrollmentTokens)
         .set({ usedAt: sql`NOW()` })
         .where(
-        and(eq(federationEnrollmentTokens.token, token), isNull(federationEnrollmentTokens.usedAt)),
+          and(
+            eq(federationEnrollmentTokens.token, token),
+            isNull(federationEnrollmentTokens.usedAt),
+          ),
         )
         .returning({ token: federationEnrollmentTokens.token });
 
@@ -164,8 +190,9 @@ export class EnrollmentService {
           ttlSeconds: 300,
         });
       } catch (err) {
+        // HIGH-4: Log only the first 8 hex chars of the token for correlation — never log the full token.
         this.logger.error(
-        `issueCert failed after token ${token} was claimed — grant ${row.grantId} is stranded pending`,
+          `issueCert failed after token ${token.slice(0, 8)}... was claimed — grant ${row.grantId} is stranded pending`,
           err instanceof Error ? err.stack : String(err),
         );
         if (err instanceof FederationScopeError) {
@@ -177,11 +204,19 @@ export class EnrollmentService {
       // 7. Atomically activate grant, update peer record, and write audit log.
       const certNotAfter = this.extractCertNotAfter(issued.certPem);
       await this.db.transaction(async (tx) => {
-      await tx
+        // CRIT-2: Guard activation with WHERE status='pending' to prevent double-activation.
+        const [activated] = await tx
           .update(federationGrants)
           .set({ status: 'active' })
-        .where(eq(federationGrants.id, row.grantId));
+          .where(and(eq(federationGrants.id, row!.grantId), eq(federationGrants.status, 'pending')))
+          .returning({ id: federationGrants.id });
+        if (!activated) {
+          throw new ConflictException(
+            `Grant ${row!.grantId} is no longer pending — cannot activate`,
+          );
+        }
 
+        // CRIT-2: Guard peer update with WHERE state='pending'.
         await tx
           .update(federationPeers)
           .set({
@@ -190,12 +225,12 @@ export class EnrollmentService {
             certNotAfter,
             state: 'active',
           })
-        .where(eq(federationPeers.id, row.peerId));
+          .where(and(eq(federationPeers.id, row!.peerId), eq(federationPeers.state, 'pending')));
 
         await tx.insert(federationAuditLog).values({
           requestId: crypto.randomUUID(),
-        peerId: row.peerId,
+          peerId: row!.peerId,
-        grantId: row.grantId,
+          grantId: row!.grantId,
           verb: 'enrollment',
           resource: 'federation_grant',
           statusCode: 200,
@@ -207,24 +242,40 @@ export class EnrollmentService {
         `Enrollment complete — peerId=${row.peerId} grantId=${row.grantId} serial=${issued.serialNumber}`,
       );
 
+      outcome = 'allowed';
+
       // 8. Return cert material
       return {
         certPem: issued.certPem,
         certChainPem: issued.certChainPem,
       };
+    } catch (err) {
+      // HIGH-5: Best-effort audit write on failure — do not let this throw.
+      if (outcome === 'denied') {
+        await this.db
+          .insert(federationAuditLog)
+          .values({
+            requestId: crypto.randomUUID(),
+            peerId: row?.peerId ?? null,
+            grantId: row?.grantId ?? null,
+            verb: 'enrollment',
+            resource: 'federation_grant',
+            statusCode:
+              err instanceof GoneException ? 410 : err instanceof NotFoundException ? 404 : 500,
+            outcome: 'denied',
+          })
+          .catch(() => {});
+      }
+      throw err;
+    }
   }
 
   /**
    * Extract the notAfter date from a PEM certificate.
-   * Falls back to 90 days from now if parsing fails.
+   * HIGH-2: No silent fallback — a cert that cannot be parsed should fail loud.
    */
   private extractCertNotAfter(certPem: string): Date {
-    try {
     const cert = new X509Certificate(certPem);
     return new Date(cert.validTo);
-    } catch {
-      // Fallback: 90 days from now
-      return new Date(Date.now() + 90 * 24 * 60 * 60 * 1000);
-    }
   }
 }

docs/federation/ADMIN-CLI.md

@@ -0,0 +1,106 @@
+# 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

docs/federation/MISSION-MANIFEST.md

@@ -7,11 +7,11 @@
 
 **ID:** federation-v1-20260419
 **Statement:** Jarvis operates across 3–4 workstations in two physical locations (home, USC). The user currently reaches back to a single jarvis-brain checkout from every session; a prior OpenBrain attempt caused cache, latency, and opacity pain. This mission builds asymmetric federation between Mosaic Stack gateways so that a session on a user's home gateway can query their work gateway in real time without data ever persisting across the boundary, with full multi-tenant isolation and standard-PKI (X.509 / Step-CA) trust management.
-**Phase:** M2 active — Step-CA + grant schema + admin CLI; parallel test-deploy workstream stood up
+**Phase:** M3 active — mTLS handshake + list/get/capabilities verbs + scope enforcement
-**Current Milestone:** FED-M2
+**Current Milestone:** FED-M3
-**Progress:** 1 / 7 milestones
+**Progress:** 2 / 7 milestones
 **Status:** active
-**Last Updated:** 2026-04-21 (M2 decomposed; mos-test-1/-2 designated as federation E2E test hosts)
+**Last Updated:** 2026-04-21 (M2 closed via PR #503, tag `fed-v0.2.0-m2`, issue #461 closed; M3 decomposed into 14 tasks)
 **Parent Mission:** None — new mission
 
 ## Test Infrastructure
@@ -63,8 +63,8 @@ Key design references:
 | #   | ID     | Name                                          | Status      | Branch             | Issue | Started    | Completed  |
 | --- | ------ | --------------------------------------------- | ----------- | ------------------ | ----- | ---------- | ---------- |
 | 1   | FED-M1 | Federated tier infrastructure                 | done        | (12 PRs #470-#481) | #460  | 2026-04-19 | 2026-04-19 |
-| 2   | FED-M2 | Step-CA + grant schema + admin CLI            | in-progress | (decomposition)    | #461  | 2026-04-21 | —          |
+| 2   | FED-M2 | Step-CA + grant schema + admin CLI            | done        | (PRs #483-#503)    | #461  | 2026-04-21 | 2026-04-21 |
-| 3   | FED-M3 | mTLS handshake + list/get + scope enforcement | not-started | —                  | #462  | —          | —          |
+| 3   | FED-M3 | mTLS handshake + list/get + scope enforcement | in-progress | (decomposition)    | #462  | 2026-04-21 | —          |
 | 4   | FED-M4 | search verb + audit log + rate limit          | not-started | —                  | #463  | —          | —          |
 | 5   | FED-M5 | Cache + offline degradation + OTEL            | not-started | —                  | #464  | —          | —          |
 | 6   | FED-M6 | Revocation + auto-renewal + CRL               | not-started | —                  | #465  | —          | —          |
@@ -86,16 +86,23 @@ Key design references:
 ## Session History
 
 | Session | Date                    | Runtime | Outcome                                                                                                                               |
-| ------- | ---------- | ------- | --------------------------------------------------------------------- |
+| ------- | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
 | S1      | 2026-04-19              | claude  | PRD authored, MILESTONES decomposed, 7 issues filed                                                                                   |
 | S2-S4   | 2026-04-19              | claude  | FED-M1 complete: 12 tasks (PRs #470-#481) merged; tag `fed-v0.1.0-m1`                                                                 |
+| S5-S22  | 2026-04-19 → 2026-04-21 | claude  | FED-M2 complete: 13 tasks (PRs #483-#503) merged; tag `fed-v0.2.0-m2`; issue #461 closed. Step-CA + grant schema + admin CLI shipped. |
+| S23     | 2026-04-21              | claude  | M3 decomposed into 14 tasks in `docs/federation/TASKS.md`. Manifest M3 row → in-progress. Next: kickoff M3-01.                        |
 
 ## Next Step
 
-FED-M2 active. Decomposition landed in `docs/federation/TASKS.md` (M2-01..M2-13 code workstream + DEPLOY-01..DEPLOY-05 parallel test-deploy workstream, ~88K total). Tracking issue #482.
+FED-M3 active. Decomposition landed in `docs/federation/TASKS.md` (M3-01..M3-14, ~100K estimate). Tracking issue #462.
 
-Parallel execution plan:
+Execution plan (parallel where possible):
 
-- **CODE workstream**: M2-01 (DB migration) starts immediately — sonnet subagent on `feat/federation-m2-schema`. Then M2-02 → M2-09 sequentially with M2-04/M2-05/M2-06/M2-07 having interleaved CA/storage/grant dependencies.
+- **Foundation**: M3-01 (DTOs in `packages/types/src/federation/`) starts immediately — sonnet subagent on `feat/federation-m3-types`. Blocks all server + client work.
-- **DEPLOY workstream**: DEPLOY-01 (image verify) → DEPLOY-02 (stack template) → DEPLOY-03/04 (mos-test-1/-2 deploy) → DEPLOY-05 (TEST-INFRA.md). Gated on Portainer wrapper PR (`PORTAINER_INSECURE` flag) merging first.
+- **Server stream** (after M3-01): M3-03 (AuthGuard) + M3-04 (ScopeService) in series, then M3-05 / M3-06 / M3-07 (verbs) in parallel.
-- **Re-converge** at M2-10 (E2E test) once both workstreams ready.
+- **Client stream** (after M3-01, parallel with server): M3-08 (FederationClient) → M3-09 (QuerySourceService).
+- **Harness** (parallel with everything): M3-02 (`tools/federation-harness/`) — needed for M3-11.
+- **Test gates**: M3-10 (Integration) → M3-11 (E2E with harness) → M3-12 (Independent security review, two rounds budgeted).
+- **Close**: M3-13 (Docs) → M3-14 (release tag `fed-v0.3.0-m3`, close #462).
+
+**Test-bed fallback:** `mos-test-1/-2` deploy is still blocked on `FED-M2-DEPLOY-IMG-FIX`. The harness in M3-02 ships a local two-gateway docker-compose so M3-11 is not blocked. Production-host validation is M7's responsibility (PRD AC-12).

docs/federation/SETUP.md

@@ -70,6 +70,96 @@ For JSON output (useful in CI/automation):
 mosaic gateway doctor --json
 ```
 
+## Step 2: Step-CA Bootstrap
+
+Step-CA is a certificate authority that issues X.509 certificates for federation peers. In Mosaic federation, it signs peer certificates with custom OIDs that embed grant and user identities, enforcing authorization at the certificate level.
+
+### Prerequisites for Step-CA
+
+Before starting the CA, you must set up the dev password:
+
+```bash
+cp infra/step-ca/dev-password.example infra/step-ca/dev-password
+# Edit dev-password and set your CA password (minimum 16 characters)
+```
+
+The password is required for the CA to boot and derive the provisioner key used by the gateway.
+
+### Start the Step-CA service
+
+Add the step-ca service to your federated stack:
+
+```bash
+docker compose -f docker-compose.federated.yml --profile federated up -d step-ca
+```
+
+On first boot, the init script (`infra/step-ca/init.sh`) runs automatically. It:
+
+- Generates the CA root key and certificate in the Docker volume
+- Creates the `mosaic-fed` JWK provisioner
+- Applies the X.509 template from `infra/step-ca/templates/federation.tpl`
+
+The volume is persistent, so subsequent boots reuse the existing CA keys.
+
+Verify the CA is healthy:
+
+```bash
+curl https://localhost:9000/health --cacert /tmp/step-ca-root.crt
+```
+
+(If the root cert file doesn't exist yet, see the extraction steps below.)
+
+### Extract credentials for the gateway
+
+The gateway requires two credentials from the running CA:
+
+**1. Provisioner key (for `STEP_CA_PROVISIONER_KEY_JSON`)**
+
+```bash
+docker exec $(docker ps -qf name=step-ca) cat /home/step/secrets/mosaic-fed.json > /tmp/step-ca-provisioner.json
+```
+
+This JSON file contains the JWK public and private keys for the `mosaic-fed` provisioner. Store it securely and pass its contents to the gateway via the `STEP_CA_PROVISIONER_KEY_JSON` environment variable.
+
+**2. Root certificate (for `STEP_CA_ROOT_CERT_PATH`)**
+
+```bash
+docker cp $(docker ps -qf name=step-ca):/home/step/certs/root_ca.crt /tmp/step-ca-root.crt
+```
+
+This PEM file is the CA's root certificate, used to verify peer certificates issued by step-ca. Pass its path to the gateway via `STEP_CA_ROOT_CERT_PATH`.
+
+### Custom OID Registry
+
+Federation certificates include custom OIDs in the certificate extension. These encode authorization metadata:
+
+| OID                 | Name                   | Description           |
+| ------------------- | ---------------------- | --------------------- |
+| 1.3.6.1.4.1.99999.1 | mosaic_grant_id        | Federation grant UUID |
+| 1.3.6.1.4.1.99999.2 | mosaic_subject_user_id | Subject user UUID     |
+
+These OIDs are verified by the gateway after the CSR is signed, ensuring the certificate was issued with the correct grant and user context.
+
+### Environment Variables
+
+Configure the gateway with the following environment variables before startup:
+
+| Variable                       | Required | Description                                                                                               |
+| ------------------------------ | -------- | --------------------------------------------------------------------------------------------------------- |
+| `STEP_CA_URL`                  | Yes      | Base URL of the step-ca instance, e.g. `https://step-ca:9000` (use `https://localhost:9000` in local dev) |
+| `STEP_CA_PROVISIONER_KEY_JSON` | Yes      | JSON-encoded JWK from `/home/step/secrets/mosaic-fed.json`                                                |
+| `STEP_CA_ROOT_CERT_PATH`       | Yes      | Absolute path to the root CA certificate (e.g. `/tmp/step-ca-root.crt`)                                   |
+| `BETTER_AUTH_SECRET`           | Yes      | Secret used to seal peer private keys at rest; already required for M1                                    |
+
+Example environment setup:
+
+```bash
+export STEP_CA_URL="https://localhost:9000"
+export STEP_CA_PROVISIONER_KEY_JSON="$(cat /tmp/step-ca-provisioner.json)"
+export STEP_CA_ROOT_CERT_PATH="/tmp/step-ca-root.crt"
+export BETTER_AUTH_SECRET="<your-secret>"
+```
+
 ## Troubleshooting
 
 ### Port conflicts

docs/federation/TASKS.md

@@ -64,20 +64,20 @@ Goal: Two federated-tier gateways stood up on Portainer at `mos-test-1.woltje.co
 Goal: An admin can create a federation grant; counterparty enrolls; cert is signed by Step-CA with SAN OIDs for `grantId` + `subjectUserId`. No runtime federation traffic flows yet (that's M3).
 
 | id        | status | description                                                                                                                                                                                      | issue | agent  | branch                             | depends_on       | estimate | notes                                                                                                                                                        |
-| --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------ | ---------------------------------- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------ | ---------------------------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| FED-M2-01 | needs-qa    | DB migration: `federation_grants`, `federation_peers`, `federation_audit_log` tables + enum types (`grant_status`, `peer_state`). Drizzle schema + migration generation; migration tests.        | #461  | sonnet | feat/federation-m2-schema          | —                | 5K       | PR #486 open. First review NEEDS CHANGES (missing DESC indexes + reserved cols). Remediation subagent `a673dd9355dc26f82` in flight in worktree `agent-a4404ac1`.                                                                                                                                                                                                                                     |
+| FED-M2-01 | done   | DB migration: `federation_grants`, `federation_peers`, `federation_audit_log` tables + enum types (`grant_status`, `peer_state`). Drizzle schema + migration generation; migration tests.        | #461  | sonnet | feat/federation-m2-schema          | —                | 5K       | Shipped in PR #486. DESC indexes + reserved cols added after first review; migration tests green.                                                            |
-| FED-M2-02 | not-started | Add Step-CA sidecar to `docker-compose.federated.yml`: official `smallstep/step-ca` image, persistent CA volume, JWK provisioner config baked into init script.                                  | #461  | sonnet | feat/federation-m2-stepca          | DEPLOY-02        | 4K       | Profile-gated under `federated`. CA password from secret; dev compose uses dev-only password file.                                                                                                                                                                                                                                                                                                    |
+| FED-M2-02 | done   | Add Step-CA sidecar to `docker-compose.federated.yml`: official `smallstep/step-ca` image, persistent CA volume, JWK provisioner config baked into init script.                                  | #461  | sonnet | feat/federation-m2-stepca          | DEPLOY-02        | 4K       | Shipped in PR #494. Profile-gated under `federated`; CA password from secret; dev compose uses dev-only password file.                                       |
-| FED-M2-03 | not-started | Scope JSON schema + validator: `resources` allowlist, `excluded_resources`, `include_teams`, `include_personal`, `max_rows_per_query`. Vitest unit tests for valid + invalid scopes.             | #461  | sonnet | feat/federation-m2-scope-schema    | —                | 4K       | Validator independent of CA — reusable from grant CRUD + (later) M3 scope enforcement.                                                                                                                                                                                                                                                                                                                |
+| FED-M2-03 | done   | Scope JSON schema + validator: `resources` allowlist, `excluded_resources`, `include_teams`, `include_personal`, `max_rows_per_query`. Vitest unit tests for valid + invalid scopes.             | #461  | sonnet | feat/federation-m2-scope-schema    | —                | 4K       | Shipped in PR #496 (bundled with grants service). Validator independent of CA; reusable from grant CRUD + M3 scope enforcement.                              |
-| FED-M2-04 | not-started | `apps/gateway/src/federation/ca.service.ts`: Step-CA client (CSR submission, OID-bearing cert retrieval). Mocked + integration tests against real Step-CA container.                             | #461  | sonnet | feat/federation-m2-ca-service      | M2-02            | 6K       | SAN OIDs: `grantId` (custom OID 1.3.6.1.4.1.99999.1) + `subjectUserId` (1.3.6.1.4.1.99999.2). Document OID assignments in PRD/SETUP. **Acceptance**: must (a) wire `federation.tpl` template into `mosaic-fed` provisioner config and (b) include a unit/integration test asserting issued certs contain BOTH OIDs — fails-loud guard against silent OID stripping (carry-forward from M2-02 review). |
+| FED-M2-04 | done   | `apps/gateway/src/federation/ca.service.ts`: Step-CA client (CSR submission, OID-bearing cert retrieval). Mocked + integration tests against real Step-CA container.                             | #461  | sonnet | feat/federation-m2-ca-service      | M2-02            | 6K       | Shipped in PR #494. SAN OIDs 1.3.6.1.4.1.99999.1 (grantId) + 1.3.6.1.4.1.99999.2 (subjectUserId); integration test asserts both OIDs present in issued cert. |
-| FED-M2-05 | not-started | Sealed storage for `client_key_pem` reusing existing `provider_credentials` sealing key. Tests prove DB-at-rest is ciphertext, not PEM. Key rotation path documented (deferred impl).            | #461  | sonnet | feat/federation-m2-key-sealing     | M2-01            | 5K       | Separate from M2-06 to keep crypto seam isolated; reviewer focus is sealing only.                                                                                                                                                                                                                                                                                                                     |
+| FED-M2-05 | done   | Sealed storage for `client_key_pem` reusing existing `provider_credentials` sealing key. Tests prove DB-at-rest is ciphertext, not PEM. Key rotation path documented (deferred impl).            | #461  | sonnet | feat/federation-m2-key-sealing     | M2-01            | 5K       | Shipped in PR #495. Crypto seam isolated; tests confirm ciphertext-at-rest; key rotation deferred to M6.                                                     |
-| FED-M2-06 | not-started | `grants.service.ts`: CRUD + status transitions (`pending` → `active` → `revoked`); integrates M2-03 (scope) + M2-05 (sealing). Unit tests cover all transitions including invalid ones.          | #461  | sonnet | feat/federation-m2-grants-service  | M2-03, M2-05     | 6K       | Business logic only — CSR + cert work delegated to M2-04. Revocation handler is M6.                                                                                                                                                                                                                                                                                                                   |
+| FED-M2-06 | done   | `grants.service.ts`: CRUD + status transitions (`pending` → `active` → `revoked`); integrates M2-03 (scope) + M2-05 (sealing). Unit tests cover all transitions including invalid ones.          | #461  | sonnet | feat/federation-m2-grants-service  | M2-03, M2-05     | 6K       | Shipped in PR #496. All status transitions covered; invalid transition tests green; revocation handler deferred to M6.                                       |
-| FED-M2-07 | not-started | `enrollment.controller.ts`: short-lived single-use token endpoint; CSR signing; updates grant `pending` → `active`; emits enrollment audit (table-only write, M4 tightens).                      | #461  | sonnet | feat/federation-m2-enrollment      | M2-04, M2-06     | 6K       | Tokens single-use with 410 on replay; tokens TTL'd at 15min; rate-limited at request layer (M4 introduces guard, M2 uses simple lock).                                                                                                                                                                                                                                                                |
+| FED-M2-07 | done   | `enrollment.controller.ts`: short-lived single-use token endpoint; CSR signing; updates grant `pending` → `active`; emits enrollment audit (table-only write, M4 tightens).                      | #461  | sonnet | feat/federation-m2-enrollment      | M2-04, M2-06     | 6K       | Shipped in PR #497. Tokens single-use with 410 on replay; TTL 15min; rate-limited at request layer.                                                          |
-| FED-M2-08 | not-started | Admin CLI: `mosaic federation grant create/list/show` + `peer add/list`. Integration with grants.service (no API duplication). Help output + machine-readable JSON option.                       | #461  | sonnet | feat/federation-m2-cli             | M2-06, M2-07     | 7K       | `peer add <enrollment-url>` is the client-side flow; resolves enrollment URL → CSR → store sealed key + cert.                                                                                                                                                                                                                                                                                         |
+| FED-M2-08 | done   | Admin CLI: `mosaic federation grant create/list/show` + `peer add/list`. Integration with grants.service (no API duplication). Help output + machine-readable JSON option.                       | #461  | sonnet | feat/federation-m2-cli             | M2-06, M2-07     | 7K       | Shipped in PR #498. `peer add <enrollment-url>` client-side flow; JSON output flag; admin REST controller co-shipped.                                        |
-| FED-M2-09 | not-started | Integration tests covering MILESTONES.md M2 acceptance tests #1, #2, #3, #5, #7, #8 (single-gateway suite). Real Step-CA container; vitest profile gated by `FEDERATED_INTEGRATION=1`.           | #461  | sonnet | feat/federation-m2-integration     | M2-08            | 8K       | Tests #4 (cert OID match) + #6 (two-gateway peer-add) handled separately by M2-10 (E2E).                                                                                                                                                                                                                                                                                                              |
+| FED-M2-09 | done   | Integration tests covering MILESTONES.md M2 acceptance tests #1, #2, #3, #5, #7, #8 (single-gateway suite). Real Step-CA container; vitest profile gated by `FEDERATED_INTEGRATION=1`.           | #461  | sonnet | feat/federation-m2-integration     | M2-08            | 8K       | Shipped in PR #499. All 6 acceptance tests green; gated by FEDERATED_INTEGRATION=1.                                                                          |
-| FED-M2-10 | not-started | E2E test against deployed mos-test-1 + mos-test-2 (or local two-gateway docker-compose if Portainer not ready): MILESTONES test #6 `peer add` yields `active` peer record with valid cert + key. | #461  | sonnet | feat/federation-m2-e2e             | M2-08, DEPLOY-04 | 6K       | Falls back to local docker-compose-two-gateways if remote test hosts not yet available. Documents both paths.                                                                                                                                                                                                                                                                                         |
+| FED-M2-10 | done   | E2E test against deployed mos-test-1 + mos-test-2 (or local two-gateway docker-compose if Portainer not ready): MILESTONES test #6 `peer add` yields `active` peer record with valid cert + key. | #461  | sonnet | feat/federation-m2-e2e             | M2-08, DEPLOY-04 | 6K       | Shipped in PR #500. Local two-gateway docker-compose path used; `peer add` yields active peer with valid cert + sealed key.                                  |
-| FED-M2-11 | not-started | Independent security review (sonnet, not author of M2-04/05/06/07): focus on single-use token replay, sealing leak surfaces, OID match enforcement, scope schema bypass paths.                   | #461  | sonnet | feat/federation-m2-security-review | M2-10            | 8K       | Apply M1 two-round pattern. Reviewer should explicitly attempt enrollment-token replay, OID-spoofing CSR, and key leak in error messages.                                                                                                                                                                                                                                                             |
+| FED-M2-11 | done   | Independent security review (sonnet, not author of M2-04/05/06/07): focus on single-use token replay, sealing leak surfaces, OID match enforcement, scope schema bypass paths.                   | #461  | sonnet | feat/federation-m2-security-review | M2-10            | 8K       | Shipped in PR #501. Two-round review; enrollment-token replay, OID-spoofing CSR, and key leak in error messages all verified and hardened.                   |
-| FED-M2-12 | not-started | Docs update: `docs/federation/SETUP.md` Step-CA section; new `docs/federation/ADMIN-CLI.md` with grant/peer commands; scope schema reference; OID registration note. Runbook still M7-deferred.  | #461  | haiku  | feat/federation-m2-docs            | M2-11            | 4K       | Adds CA bootstrap section to SETUP.md with `docker compose --profile federated up step-ca` example.                                                                                                                                                                                                                                                                                                   |
+| FED-M2-12 | done   | Docs update: `docs/federation/SETUP.md` Step-CA section; new `docs/federation/ADMIN-CLI.md` with grant/peer commands; scope schema reference; OID registration note. Runbook still M7-deferred.  | #461  | haiku  | feat/federation-m2-docs            | M2-11            | 4K       | Shipped in PR #502. SETUP.md CA bootstrap section added; ADMIN-CLI.md created; scope schema reference and OID note included.                                 |
-| FED-M2-13 | not-started | PR aggregate close, CI green, merge to main, close #461. Release tag `fed-v0.2.0-m2`. Mark deploy stream complete. Update mission manifest M2 row.                                               | #461  | sonnet | feat/federation-m2-close           | M2-12            | 3K       | Same close pattern as M1-12; queue-guard before merge; tea release-create with notes including deploy-stream PRs.                                                                                                                                                                                                                                                                                     |
+| FED-M2-13 | done   | PR aggregate close, CI green, merge to main, close #461. Release tag `fed-v0.2.0-m2`. Mark deploy stream complete. Update mission manifest M2 row.                                               | #461  | sonnet | chore/federation-m2-close          | M2-12            | 3K       | Release tag `fed-v0.2.0-m2` created; issue #461 closed; all M2 PRs #494–#502 merged to main.                                                                 |
 
 **M2 code workstream estimate:** ~72K tokens (vs MILESTONES.md 30K — same over-budget pattern as M1, where per-task breakdown including tests/review/docs catches the real cost).
 
@@ -85,7 +85,38 @@ Goal: An admin can create a federation grant; counterparty enrolls; cert is sign
 
 ## Milestone 3 — mTLS handshake + list/get + scope enforcement (FED-M3)
 
-_Deferred. Issue #462._
+Goal: Two federated gateways exchange real data over mTLS. Inbound requests pass through cert validation → grant lookup → scope enforcement → native RBAC → response. `list`, `get`, and `capabilities` verbs land. The federation E2E harness (`tools/federation-harness/`) is the new permanent test bed for M3+ and is gated on every milestone going forward.
+
+> **Critical trust boundary.** Every 401/403 path needs a test. Code review is non-negotiable; M3-12 budgets two review rounds.
+>
+> **Tracking issue:** #462.
+
+| id        | status      | description                                                                                                                                                                                                                                                                                            | issue | agent  | branch                               | depends_on       | estimate | notes                                                                                                                                                    |
+| --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------ | ------------------------------------ | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FED-M3-01 | not-started | `packages/types/src/federation/` — request/response DTOs for `list`, `get`, `capabilities` verbs. Wire-format zod schemas + inferred TS types. Includes `FederationRequest`, `FederationListResponse<T>`, `FederationGetResponse<T>`, `FederationCapabilitiesResponse`, error envelope, `_source` tag. | #462  | sonnet | feat/federation-m3-types             | —                | 4K       | Reusable from gateway server + client + harness. Pure types — no I/O, no NestJS.                                                                         |
+| FED-M3-02 | not-started | `tools/federation-harness/` scaffold: `docker-compose.two-gateways.yml` (Server A + Server B + step-CA), `seed.ts` (provisions grants, peers, sample tasks/notes/credentials per scope variant), `harness.ts` helper (boots stack, returns typed clients). README documents harness use.               | #462  | sonnet | feat/federation-m3-harness           | DEPLOY-04 (soft) | 8K       | Falls back to local docker-compose if `mos-test-1/-2` not yet redeployed (DEPLOY chain blocked on IMG-FIX). Permanent test infra used by M3+.            |
+| FED-M3-03 | not-started | `apps/gateway/src/federation/server/federation-auth.guard.ts` (NestJS guard). Validates inbound client cert from Fastify TLS context, extracts `grantId` + `subjectUserId` from custom OIDs, loads grant from DB, asserts `status='active'`, attaches `FederationContext` to request.                  | #462  | sonnet | feat/federation-m3-auth-guard        | M3-01            | 8K       | Reuses OID parsing logic mirrored from `ca.service.ts` post-issuance verification. 401 on malformed/missing OIDs; 403 on revoked/expired/missing grant.  |
+| FED-M3-04 | not-started | `apps/gateway/src/federation/server/scope.service.ts`. Pipeline: (1) resource allowlist + excluded check, (2) native RBAC eval as `subjectUserId`, (3) scope filter intersection (`include_teams`, `include_personal`), (4) `max_rows_per_query` cap. Pure service — DB calls injected.                | #462  | sonnet | feat/federation-m3-scope-service     | M3-01            | 10K      | Hardest correctness target in M3. Reuses `parseFederationScope` (M2-03). Returns either `{ allowed: true, filter }` or structured deny reason for audit. |
+| FED-M3-05 | not-started | `apps/gateway/src/federation/server/verbs/list.controller.ts`. Wires AuthGuard → ScopeService → tasks/notes/memory query layer; applies row cap; tags rows with `_source`. Resource selector via path param.                                                                                           | #462  | sonnet | feat/federation-m3-verb-list         | M3-03, M3-04     | 6K       | Routes: `POST /api/federation/v1/list/:resource`. No body persistence. Audit write deferred to M4.                                                       |
+| FED-M3-06 | not-started | `apps/gateway/src/federation/server/verbs/get.controller.ts`. Single-resource fetch by id; same pipeline as list. 404 on not-found, 403 on RBAC/scope deny — both audited the same way.                                                                                                                | #462  | sonnet | feat/federation-m3-verb-get          | M3-03, M3-04     | 6K       | `POST /api/federation/v1/get/:resource/:id`. Mirrors list controller patterns.                                                                           |
+| FED-M3-07 | not-started | `apps/gateway/src/federation/server/verbs/capabilities.controller.ts`. Read-only enumeration: returns `{ resources, excluded_resources, max_rows_per_query, supported_verbs }` derived from grant scope. Always allowed for an active grant — no RBAC eval.                                            | #462  | sonnet | feat/federation-m3-verb-capabilities | M3-03            | 4K       | `GET /api/federation/v1/capabilities`. Smallest verb; useful sanity check that mTLS + auth guard work end-to-end.                                        |
+| FED-M3-08 | not-started | `apps/gateway/src/federation/client/federation-client.service.ts`. Outbound mTLS dialer: picks `(certPem, sealed clientKey)` from `federation_peers`, unwraps key, builds undici Agent with mTLS, calls peer verb, parses typed response, wraps non-2xx into `FederationClientError`.                  | #462  | sonnet | feat/federation-m3-client            | M3-01            | 8K       | Independent of server stream — can land in parallel with M3-03/04. Cert/key cached per-peer; flushed by future M5/M6 logic.                              |
+| FED-M3-09 | not-started | `apps/gateway/src/federation/client/query-source.service.ts`. Accepts `source: "local" \| "federated:<host>" \| "all"` from gateway query layer; for `"all"` fans out to local + each peer in parallel; merges results; tags every row with `_source`.                                                 | #462  | sonnet | feat/federation-m3-query-source      | M3-08            | 8K       | Per-peer failure surfaces as `_partial: true` in response, not hard failure (sets up M5 offline UX). M5 adds caching + circuit breaker on top.           |
+| FED-M3-10 | not-started | Integration tests for MILESTONES.md M3 acceptance #6 (malformed OIDs → 401; valid cert + revoked grant → 403) and #7 (`max_rows_per_query` cap). Real PG, mocked TLS context (Fastify req shim).                                                                                                       | #462  | sonnet | feat/federation-m3-integration       | M3-05, M3-06     | 8K       | Vitest profile gated by `FEDERATED_INTEGRATION=1`. Single-gateway suite; no harness required.                                                            |
+| FED-M3-11 | not-started | E2E tests for MILESTONES.md M3 acceptance #1, #2, #3, #4, #5, #8, #9, #10 (8 cases). Uses harness from M3-02; two real gateways, real Step-CA, real mTLS. Each test asserts both happy-path response and audit/no-persist invariants.                                                                  | #462  | sonnet | feat/federation-m3-e2e               | M3-02, M3-09     | 12K      | Largest single task. Each acceptance gets its own `it(...)` for clear failure attribution.                                                               |
+| FED-M3-12 | not-started | Independent security review (sonnet, not author of M3-03/04/05/06/07/08/09): focus on cert-SAN spoofing, OID extraction edge cases, scope-bypass via filter manipulation, RBAC-bypass via subjectUser swap, response leakage when scope deny.                                                          | #462  | sonnet | feat/federation-m3-security-review   | M3-11            | 10K      | Two review rounds budgeted. PRD requires explicit test for every 401/403 path — review verifies coverage.                                                |
+| FED-M3-13 | not-started | Docs update: `docs/federation/SETUP.md` mTLS handshake section, new `docs/federation/HARNESS.md` for federation-harness usage, OID reference table in SETUP.md, scope enforcement pipeline diagram. Runbook still M7-deferred.                                                                         | #462  | haiku  | feat/federation-m3-docs              | M3-12            | 5K       | One ASCII diagram for the auth-guard → scope → RBAC pipeline; helps future reviewers reason about denial paths.                                          |
+| FED-M3-14 | not-started | PR aggregate close, CI green, merge to main, close #462. Release tag `fed-v0.3.0-m3`. Update mission manifest M3 row → done; M4 row → in-progress when work begins.                                                                                                                                    | #462  | sonnet | chore/federation-m3-close            | M3-13            | 3K       | Same close pattern as M1-12 / M2-13.                                                                                                                     |
+
+**M3 estimate:** ~100K tokens (vs MILESTONES.md 40K — same per-task breakdown pattern as M1/M2: tests, review, and docs split out from implementation cost). Largest milestone in the federation mission.
+
+**Parallelization opportunities:**
+
+- M3-08 (client) can land in parallel with M3-03/M3-04 (server pipeline) — they only share DTOs from M3-01.
+- M3-02 (harness) can land in parallel with everything except M3-11.
+- M3-05/M3-06/M3-07 (verbs) are independent of each other once M3-03/M3-04 land.
+
+**Test bed fallback:** If `mos-test-1.woltje.com` / `mos-test-2.woltje.com` are still blocked on `FED-M2-DEPLOY-IMG-FIX` when M3-11 is ready to run, the harness's local `docker-compose.two-gateways.yml` is a sufficient stand-in. Production-host validation moves to M7 acceptance suite (PRD AC-12).
 
 ## Milestone 4 — search + audit + rate limit (FED-M4)
 

docs/scratchpads/mvp-20260312.md

@@ -612,3 +612,44 @@ Independent security review surfaced three high-impact and four medium findings;
 7. DEPLOY-03/04 acceptance probes (`mosaic gateway doctor --json`, pgvector `vector(3)` round-trip)
 8. DEPLOY-05: author `docs/federation/TEST-INFRA.md`
 9. M2-02 (Step-CA sidecar) kicks off after image health is green
+
+### Session 23 — 2026-04-21 — M2 close + M3 decomposition
+
+**Closed at compaction boundary:** all 13 M2 tasks done, PRs #494–#503 merged to `main`, tag `fed-v0.2.0-m2` published, Gitea release notes posted, issue #461 closed. Main at `4ece6dc6`.
+
+**M2 hardening landed in PR #501** (security review remediation):
+
+- CRIT-1: post-issuance OID verification in `ca.service.ts` (rejects cert if `mosaic_grant_id` / `mosaic_subject_user_id` extensions missing or mismatched)
+- CRIT-2: atomic activation guard `WHERE status='pending'` on grant + `WHERE state='pending'` on peer; throws `ConflictException` if lost race
+- HIGH-2: removed try/catch fallback in `extractCertNotAfter` — parse failures propagate as 500 (no silent 90-day default)
+- HIGH-4: token slice for logging (`${token.slice(0, 8)}...`) — no full token in stdout
+- HIGH-5: `redeem()` wrapped in try/catch with best-effort failure audit; uses `null` (not `'unknown'`) for nullable UUID FK fallback
+- MED-3: `createToken` validates `grant.peerId === dto.peerId`; `BadRequestException` on mismatch
+
+**Remaining M2 security findings deferred to M3+:**
+
+- HIGH-1: peerId/subjectUserId tenancy validation on `createGrant` (M3 ScopeService work surfaces this)
+- HIGH-3: Step-CA cert SHA-256 fingerprint pinning (M5 cert handling)
+- MED-1: token entropy already 32 bytes — wontfix
+- MED-2: per-route rate limit on enrollment endpoint (M4 rate limit work)
+- MED-4: CSR CN binding to peer's commonName (M3 AuthGuard work)
+
+**M3 decomposition landed in this session:**
+
+- 14 tasks (M3-01..M3-14), ~100K estimate
+- Structure mirrors M1/M2 pattern: foundation → server stream + client stream + harness in parallel → integration → E2E → security review → docs → close
+- M3-02 ships local two-gateway docker-compose (`tools/federation-harness/`) so M3-11 E2E is not blocked on the Portainer test bed (which is still blocked on `FED-M2-DEPLOY-IMG-FIX`)
+
+**Subagent doctrine retained from M2:**
+
+- All worker subagents use `isolation: "worktree"` to prevent branch-race incidents
+- Code review is independent (different subagent, no overlap with author of work)
+- `tea pr create --repo mosaicstack/stack --login mosaicstack` is the working PR-create path; `pr-create.sh` has shell-quoting bugs (followup #45 if not already filed)
+- Cost tier: foundational implementation = sonnet, docs = haiku, complex multi-file architecture (security review, scope service) = sonnet with two review rounds
+
+**Next concrete step:**
+
+1. PR for the M3 planning artifact (this commit) — branch `docs/federation-m3-planning`
+2. After merge, kickoff M3-01 (DTOs) on `feat/federation-m3-types` with sonnet subagent in worktree
+3. Once M3-01 lands, fan out: M3-02 (harness) || M3-03 (AuthGuard) → M3-04 (ScopeService) || M3-08 (FederationClient)
+4. Re-converge at M3-10 (Integration) → M3-11 (E2E)

packages/types/package.json

@@ -26,7 +26,8 @@
   },
   "dependencies": {
     "class-transformer": "^0.5.1",
-    "class-validator": "^0.15.1"
+    "class-validator": "^0.15.1",
+    "zod": "^4.3.6"
   },
   "publishConfig": {
     "registry": "https://git.mosaicstack.dev/api/packages/mosaicstack/npm/",

packages/types/src/federation/__tests__/federation.spec.ts

@@ -0,0 +1,435 @@
+/**
+ * Unit tests for federation wire-format DTOs.
+ *
+ * Coverage:
+ *  - FederationRequestSchema  (valid + invalid)
+ *  - FederationListResponseSchema factory
+ *  - FederationGetResponseSchema factory
+ *  - FederationCapabilitiesResponseSchema
+ *  - FederationErrorEnvelopeSchema + error code exhaustiveness
+ *  - FederationError exception hierarchy
+ *  - tagWithSource helper round-trip
+ *  - SourceTagSchema
+ */
+
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+
+import {
+  FEDERATION_ERROR_CODES,
+  FEDERATION_VERBS,
+  FederationCapabilitiesResponseSchema,
+  FederationError,
+  FederationErrorEnvelopeSchema,
+  FederationForbiddenError,
+  FederationInternalError,
+  FederationInvalidRequestError,
+  FederationNotFoundError,
+  FederationRateLimitedError,
+  FederationRequestSchema,
+  FederationScopeViolationError,
+  FederationUnauthorizedError,
+  FederationGetResponseSchema,
+  FederationListResponseSchema,
+  SOURCE_LOCAL,
+  SourceTagSchema,
+  parseFederationErrorEnvelope,
+  tagWithSource,
+} from '../index.js';
+
+// ---------------------------------------------------------------------------
+// Verbs
+// ---------------------------------------------------------------------------
+
+describe('FEDERATION_VERBS', () => {
+  it('contains exactly list, get, capabilities', () => {
+    expect(FEDERATION_VERBS).toEqual(['list', 'get', 'capabilities']);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// FederationRequestSchema
+// ---------------------------------------------------------------------------
+
+describe('FederationRequestSchema', () => {
+  it('accepts a minimal valid list request', () => {
+    const result = FederationRequestSchema.safeParse({ verb: 'list', resource: 'tasks' });
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts a get request with cursor and params', () => {
+    const result = FederationRequestSchema.safeParse({
+      verb: 'get',
+      resource: 'notes',
+      cursor: 'abc123',
+      params: { filter: 'mine' },
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.cursor).toBe('abc123');
+      expect(result.data.params?.['filter']).toBe('mine');
+    }
+  });
+
+  it('accepts a capabilities request', () => {
+    const result = FederationRequestSchema.safeParse({ verb: 'capabilities', resource: 'tasks' });
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects an unknown verb', () => {
+    const result = FederationRequestSchema.safeParse({ verb: 'search', resource: 'tasks' });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects an empty resource string', () => {
+    const result = FederationRequestSchema.safeParse({ verb: 'list', resource: '' });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects a missing verb', () => {
+    const result = FederationRequestSchema.safeParse({ resource: 'tasks' });
+    expect(result.success).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// FederationListResponseSchema factory
+// ---------------------------------------------------------------------------
+
+describe('FederationListResponseSchema', () => {
+  const ItemSchema = z.object({ id: z.string(), name: z.string() });
+  const ListSchema = FederationListResponseSchema(ItemSchema);
+
+  it('accepts a valid list envelope', () => {
+    const result = ListSchema.safeParse({
+      items: [{ id: '1', name: 'Task A' }],
+      nextCursor: 'page2',
+      _partial: false,
+      _truncated: false,
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.items).toHaveLength(1);
+      expect(result.data.nextCursor).toBe('page2');
+    }
+  });
+
+  it('accepts a minimal envelope with empty items', () => {
+    const result = ListSchema.safeParse({ items: [] });
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects when items is missing', () => {
+    const result = ListSchema.safeParse({ nextCursor: 'x' });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects when an item fails validation', () => {
+    const result = ListSchema.safeParse({ items: [{ id: 1, name: 'bad' }] });
+    expect(result.success).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// FederationGetResponseSchema factory
+// ---------------------------------------------------------------------------
+
+describe('FederationGetResponseSchema', () => {
+  const ItemSchema = z.object({ id: z.string() });
+  const GetSchema = FederationGetResponseSchema(ItemSchema);
+
+  it('accepts a found item', () => {
+    const result = GetSchema.safeParse({ item: { id: 'abc' } });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.item).toEqual({ id: 'abc' });
+    }
+  });
+
+  it('accepts null item (not found)', () => {
+    const result = GetSchema.safeParse({ item: null });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.item).toBeNull();
+    }
+  });
+
+  it('rejects when item is missing', () => {
+    const result = GetSchema.safeParse({});
+    expect(result.success).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// FederationCapabilitiesResponseSchema
+// ---------------------------------------------------------------------------
+
+describe('FederationCapabilitiesResponseSchema', () => {
+  it('accepts a valid capabilities response', () => {
+    const result = FederationCapabilitiesResponseSchema.safeParse({
+      resources: ['tasks', 'notes'],
+      excluded_resources: ['credentials'],
+      max_rows_per_query: 500,
+      supported_verbs: ['list', 'get', 'capabilities'],
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.max_rows_per_query).toBe(500);
+    }
+  });
+
+  it('accepts a response with filters field', () => {
+    const result = FederationCapabilitiesResponseSchema.safeParse({
+      resources: ['tasks', 'notes'],
+      excluded_resources: [],
+      max_rows_per_query: 100,
+      supported_verbs: ['list'],
+      filters: {
+        tasks: { include_teams: ['team-a'], include_personal: true },
+        notes: { include_personal: false },
+      },
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.filters?.['tasks']?.include_teams).toEqual(['team-a']);
+    }
+  });
+
+  it('accepts a response with partial filters (only include_teams)', () => {
+    const result = FederationCapabilitiesResponseSchema.safeParse({
+      resources: ['tasks'],
+      excluded_resources: [],
+      max_rows_per_query: 50,
+      supported_verbs: ['list'],
+      filters: { tasks: { include_teams: ['eng'] } },
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts a response with rate_limit (M4 full shape)', () => {
+    const result = FederationCapabilitiesResponseSchema.safeParse({
+      resources: ['tasks'],
+      excluded_resources: [],
+      max_rows_per_query: 100,
+      supported_verbs: ['list'],
+      rate_limit: { limit_per_minute: 60, remaining: 55, reset_at: '2026-04-23T12:00:00Z' },
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.rate_limit?.limit_per_minute).toBe(60);
+      expect(result.data.rate_limit?.remaining).toBe(55);
+    }
+  });
+
+  it('accepts a response with rate_limit (M3 minimal — limit_per_minute only)', () => {
+    const result = FederationCapabilitiesResponseSchema.safeParse({
+      resources: ['tasks'],
+      excluded_resources: [],
+      max_rows_per_query: 100,
+      supported_verbs: ['list'],
+      rate_limit: { limit_per_minute: 120 },
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts a response without rate_limit (field is optional)', () => {
+    const result = FederationCapabilitiesResponseSchema.safeParse({
+      resources: ['tasks'],
+      excluded_resources: [],
+      max_rows_per_query: 100,
+      supported_verbs: ['list'],
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.rate_limit).toBeUndefined();
+    }
+  });
+
+  it('rejects rate_limit with non-positive limit_per_minute', () => {
+    const result = FederationCapabilitiesResponseSchema.safeParse({
+      resources: ['tasks'],
+      excluded_resources: [],
+      max_rows_per_query: 100,
+      supported_verbs: ['list'],
+      rate_limit: { limit_per_minute: 0 },
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects rate_limit with invalid reset_at datetime', () => {
+    const result = FederationCapabilitiesResponseSchema.safeParse({
+      resources: ['tasks'],
+      excluded_resources: [],
+      max_rows_per_query: 100,
+      supported_verbs: ['list'],
+      rate_limit: { limit_per_minute: 60, reset_at: 'not-a-datetime' },
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects supported_verbs with an invalid verb (MED-3 enum guard)', () => {
+    const result = FederationCapabilitiesResponseSchema.safeParse({
+      resources: ['tasks'],
+      excluded_resources: [],
+      max_rows_per_query: 100,
+      supported_verbs: ['invalid_verb'],
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects empty resources array', () => {
+    const result = FederationCapabilitiesResponseSchema.safeParse({
+      resources: [],
+      excluded_resources: [],
+      max_rows_per_query: 100,
+      supported_verbs: ['list'],
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects non-integer max_rows_per_query', () => {
+    const result = FederationCapabilitiesResponseSchema.safeParse({
+      resources: ['tasks'],
+      excluded_resources: [],
+      max_rows_per_query: 1.5,
+      supported_verbs: ['list'],
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// FederationErrorEnvelopeSchema + error code exhaustiveness
+// ---------------------------------------------------------------------------
+
+describe('FederationErrorEnvelopeSchema', () => {
+  it('accepts each valid error code', () => {
+    for (const code of FEDERATION_ERROR_CODES) {
+      const result = FederationErrorEnvelopeSchema.safeParse({
+        error: { code, message: 'test' },
+      });
+      expect(result.success, `code ${code} should be valid`).toBe(true);
+    }
+  });
+
+  it('rejects an unknown error code', () => {
+    const result = FederationErrorEnvelopeSchema.safeParse({
+      error: { code: 'unknown_code', message: 'test' },
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('accepts optional details field', () => {
+    const result = FederationErrorEnvelopeSchema.safeParse({
+      error: { code: 'forbidden', message: 'nope', details: { grantId: 'xyz' } },
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects when message is missing', () => {
+    const result = FederationErrorEnvelopeSchema.safeParse({ error: { code: 'not_found' } });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('parseFederationErrorEnvelope', () => {
+  it('returns a typed envelope for valid input', () => {
+    const env = parseFederationErrorEnvelope({ error: { code: 'not_found', message: 'gone' } });
+    expect(env.error.code).toBe('not_found');
+  });
+
+  it('throws for invalid input', () => {
+    expect(() => parseFederationErrorEnvelope({ bad: 'shape' })).toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// FederationError exception hierarchy
+// ---------------------------------------------------------------------------
+
+describe('FederationError hierarchy', () => {
+  const cases: Array<[string, FederationError]> = [
+    ['unauthorized', new FederationUnauthorizedError()],
+    ['forbidden', new FederationForbiddenError()],
+    ['not_found', new FederationNotFoundError()],
+    ['rate_limited', new FederationRateLimitedError()],
+    ['scope_violation', new FederationScopeViolationError()],
+    ['invalid_request', new FederationInvalidRequestError()],
+    ['internal_error', new FederationInternalError()],
+  ];
+
+  it.each(cases)('code %s is an instance of FederationError', (_code, err) => {
+    expect(err).toBeInstanceOf(FederationError);
+    expect(err).toBeInstanceOf(Error);
+  });
+
+  it.each(cases)('code %s has correct code property', (code, err) => {
+    expect(err.code).toBe(code);
+  });
+
+  it('toEnvelope serialises to wire format', () => {
+    const err = new FederationForbiddenError('Access denied', { grantId: 'g1' });
+    const env = err.toEnvelope();
+    expect(env.error.code).toBe('forbidden');
+    expect(env.error.message).toBe('Access denied');
+    expect(env.error.details).toEqual({ grantId: 'g1' });
+  });
+
+  it('toEnvelope omits details when not provided', () => {
+    const err = new FederationNotFoundError();
+    const env = err.toEnvelope();
+    expect(Object.prototype.hasOwnProperty.call(env.error, 'details')).toBe(false);
+  });
+
+  it('error codes tuple covers all subclasses (exhaustiveness check)', () => {
+    // If a new subclass is added without a code, this test fails at compile time.
+    const allCodes = new Set(FEDERATION_ERROR_CODES);
+    for (const [code] of cases) {
+      expect(allCodes.has(code as (typeof FEDERATION_ERROR_CODES)[number])).toBe(true);
+    }
+    // All codes are covered by at least one case
+    expect(cases).toHaveLength(FEDERATION_ERROR_CODES.length);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Source tag + tagWithSource
+// ---------------------------------------------------------------------------
+
+describe('SourceTagSchema', () => {
+  it('accepts a non-empty _source string', () => {
+    expect(SourceTagSchema.safeParse({ _source: 'local' }).success).toBe(true);
+    expect(SourceTagSchema.safeParse({ _source: 'mosaic.uscllc.com' }).success).toBe(true);
+  });
+
+  it('rejects empty _source string', () => {
+    expect(SourceTagSchema.safeParse({ _source: '' }).success).toBe(false);
+  });
+});
+
+describe('tagWithSource', () => {
+  it('stamps each item with the given source', () => {
+    const items = [{ id: '1' }, { id: '2' }];
+    const tagged = tagWithSource(items, SOURCE_LOCAL);
+    expect(tagged).toEqual([
+      { id: '1', _source: 'local' },
+      { id: '2', _source: 'local' },
+    ]);
+  });
+
+  it('preserves original item fields', () => {
+    const items = [{ id: 'x', name: 'Task', done: false }];
+    const tagged = tagWithSource(items, 'mosaic.uscllc.com');
+    expect(tagged[0]).toMatchObject({ id: 'x', name: 'Task', done: false });
+    expect(tagged[0]?._source).toBe('mosaic.uscllc.com');
+  });
+
+  it('returns empty array for empty input', () => {
+    expect(tagWithSource([], 'local')).toEqual([]);
+  });
+
+  it('round-trip: tagWithSource output passes SourceTagSchema', () => {
+    const tagged = tagWithSource([{ id: '1' }], 'local');
+    expect(SourceTagSchema.safeParse(tagged[0]).success).toBe(true);
+  });
+});

packages/types/src/federation/error.ts

@@ -0,0 +1,164 @@
+/**
+ * Federation wire-format error envelope and exception hierarchy.
+ *
+ * Source of truth: docs/federation/PRD.md §6, §8.
+ *
+ * DESIGN: Typed error classes rather than discriminated union values
+ * ──────────────────────────────────────────────────────────────────
+ * We expose:
+ *   1. `FEDERATION_ERROR_CODES` — closed string-enum tuple (exhaustiveness-checkable).
+ *   2. `FederationErrorCode` — union type inferred from the tuple.
+ *   3. `FederationErrorEnvelopeSchema` — Zod schema for the wire format.
+ *   4. `FederationError` — base Error subclass with a typed `code` property.
+ *      One concrete subclass per code (e.g. `FederationUnauthorizedError`),
+ *      which enables `instanceof` dispatch in handlers without a switch.
+ *
+ * Rationale: subclasses give gateway handlers and the client a clean dispatch
+ * point (catch + instanceof) without re-parsing or switch tables.  All classes
+ * carry `code` so a generic logger can act on any FederationError uniformly.
+ *
+ * Pure — no NestJS, no DB, no Node-only APIs. Safe for browser/edge.
+ */
+
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Error code enum (closed)
+// ---------------------------------------------------------------------------
+
+export const FEDERATION_ERROR_CODES = [
+  'unauthorized',
+  'forbidden',
+  'not_found',
+  'rate_limited',
+  'scope_violation',
+  'invalid_request',
+  'internal_error',
+] as const;
+
+export type FederationErrorCode = (typeof FEDERATION_ERROR_CODES)[number];
+
+// ---------------------------------------------------------------------------
+// Wire-format schema
+// ---------------------------------------------------------------------------
+
+export const FederationErrorEnvelopeSchema = z.object({
+  error: z.object({
+    code: z.enum(FEDERATION_ERROR_CODES),
+    message: z.string(),
+    details: z.unknown().optional(),
+  }),
+});
+
+export type FederationErrorEnvelope = z.infer<typeof FederationErrorEnvelopeSchema>;
+
+// ---------------------------------------------------------------------------
+// Exception class hierarchy
+// ---------------------------------------------------------------------------
+
+/**
+ * Base class for all federation errors.
+ * Carries a typed `code` so handlers can act uniformly on any FederationError.
+ */
+export class FederationError extends Error {
+  readonly code: FederationErrorCode;
+  readonly details?: unknown;
+
+  constructor(code: FederationErrorCode, message: string, details?: unknown) {
+    super(message);
+    this.name = 'FederationError';
+    this.code = code;
+    this.details = details;
+  }
+
+  /** Serialise to the wire-format error envelope. */
+  toEnvelope(): FederationErrorEnvelope {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        ...(this.details !== undefined ? { details: this.details } : {}),
+      },
+    };
+  }
+}
+
+/** Client cert is missing, invalid, or signed by an untrusted CA. */
+export class FederationUnauthorizedError extends FederationError {
+  constructor(message = 'Unauthorized', details?: unknown) {
+    super('unauthorized', message, details);
+    this.name = 'FederationUnauthorizedError';
+  }
+}
+
+/** Grant is inactive, revoked, or the subject user lacks access to the resource. */
+export class FederationForbiddenError extends FederationError {
+  constructor(message = 'Forbidden', details?: unknown) {
+    super('forbidden', message, details);
+    this.name = 'FederationForbiddenError';
+  }
+}
+
+/** Requested resource does not exist. */
+export class FederationNotFoundError extends FederationError {
+  constructor(message = 'Not found', details?: unknown) {
+    super('not_found', message, details);
+    this.name = 'FederationNotFoundError';
+  }
+}
+
+/** Grant has exceeded its rate limit; Retry-After should accompany this. */
+export class FederationRateLimitedError extends FederationError {
+  constructor(message = 'Rate limit exceeded', details?: unknown) {
+    super('rate_limited', message, details);
+    this.name = 'FederationRateLimitedError';
+  }
+}
+
+/**
+ * The request targets a resource or performs an action that the grant's
+ * scope explicitly disallows (distinct from generic 403 — scope_violation
+ * means the scope configuration itself blocked the request).
+ */
+export class FederationScopeViolationError extends FederationError {
+  constructor(message = 'Scope violation', details?: unknown) {
+    super('scope_violation', message, details);
+    this.name = 'FederationScopeViolationError';
+  }
+}
+
+/** Malformed request — missing fields, invalid cursor, unknown verb, etc. */
+export class FederationInvalidRequestError extends FederationError {
+  constructor(message = 'Invalid request', details?: unknown) {
+    super('invalid_request', message, details);
+    this.name = 'FederationInvalidRequestError';
+  }
+}
+
+/** Unexpected server-side failure. */
+export class FederationInternalError extends FederationError {
+  constructor(message = 'Internal error', details?: unknown) {
+    super('internal_error', message, details);
+    this.name = 'FederationInternalError';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Typed parser
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse an unknown value as a FederationErrorEnvelope.
+ * Throws a plain Error (not FederationError) when parsing fails — this means
+ * the payload wasn't even a valid error envelope.
+ */
+export function parseFederationErrorEnvelope(input: unknown): FederationErrorEnvelope {
+  const result = FederationErrorEnvelopeSchema.safeParse(input);
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((e) => `  - [${e.path.join('.') || 'root'}] ${e.message}`)
+      .join('\n');
+    throw new Error(`Invalid federation error envelope:\n${issues}`);
+  }
+  return result.data;
+}

packages/types/src/federation/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Federation wire-format DTOs — public barrel.
+ *
+ * Exports everything downstream M3 tasks need:
+ *   verbs.ts      — FEDERATION_VERBS constant + FederationVerb type
+ *   request.ts    — FederationRequestSchema + FederationRequest
+ *   response.ts   — list/get/capabilities schema factories + types
+ *   source-tag.ts — SourceTagSchema, tagWithSource helper
+ *   error.ts      — error envelope schema + typed exception hierarchy
+ */
+
+export * from './verbs.js';
+export * from './request.js';
+export * from './response.js';
+export * from './source-tag.js';
+export * from './error.js';

packages/types/src/federation/request.ts

@@ -0,0 +1,47 @@
+/**
+ * Federation wire-format request schema.
+ *
+ * Source of truth: docs/federation/PRD.md §9 (query model).
+ *
+ * Pure — no NestJS, no DB, no Node-only APIs. Safe for browser/edge.
+ */
+
+import { z } from 'zod';
+import { FEDERATION_VERBS } from './verbs.js';
+
+// ---------------------------------------------------------------------------
+// Query params — free-form key/value pairs passed alongside the request
+// ---------------------------------------------------------------------------
+
+const QueryParamsSchema = z.record(z.string(), z.string()).optional();
+
+// ---------------------------------------------------------------------------
+// Top-level request schema
+// ---------------------------------------------------------------------------
+
+export const FederationRequestSchema = z.object({
+  /**
+   * Verb being invoked. One of the M3 federation verbs.
+   */
+  verb: z.enum(FEDERATION_VERBS),
+
+  /**
+   * Resource path being queried, e.g. "tasks", "notes", "memory".
+   * Forward-slash-separated for sub-resources (e.g. "teams/abc/tasks").
+   */
+  resource: z.string().min(1, { message: 'resource must not be empty' }),
+
+  /**
+   * Optional free-form query params (filters, sort, etc.).
+   * Values are always strings; consumers parse as needed.
+   */
+  params: QueryParamsSchema,
+
+  /**
+   * Opaque pagination cursor returned by a previous list response.
+   * Absent on first page.
+   */
+  cursor: z.string().optional(),
+});
+
+export type FederationRequest = z.infer<typeof FederationRequestSchema>;

packages/types/src/federation/response.ts

@@ -0,0 +1,162 @@
+/**
+ * Federation wire-format response schemas.
+ *
+ * Source of truth: docs/federation/PRD.md §9 and MILESTONES.md §M3.
+ *
+ * DESIGN: Generic factory functions rather than z.lazy
+ * ─────────────────────────────────────────────────────
+ * Zod generic schemas cannot be expressed as a single re-usable `z.ZodType`
+ * value because TypeScript's type system erases the generic at the call site.
+ * The idiomatic Zod v4 pattern is factory functions that take an item schema
+ * and return a fully-typed schema.
+ *
+ *   const MyListSchema = FederationListResponseSchema(z.string());
+ *   type MyList = z.infer<typeof MyListSchema>;
+ *   // => { items: string[]; nextCursor?: string; _partial?: boolean; _truncated?: boolean }
+ *
+ * Downstream consumers (M3-03..M3-07, M3-08, M3-09) should call these
+ * factories once per resource type and cache the result.
+ *
+ * Pure — no NestJS, no DB, no Node-only APIs. Safe for browser/edge.
+ */
+
+import { z } from 'zod';
+
+import { FEDERATION_VERBS } from './verbs.js';
+
+// ---------------------------------------------------------------------------
+// Shared envelope flags
+// ---------------------------------------------------------------------------
+
+/**
+ * `_partial`: true when the response is a subset of available data (e.g. due
+ * to scope intersection reducing the result set).
+ */
+const PartialFlag = z.boolean().optional();
+
+/**
+ * `_truncated`: true when the response was capped by max_rows_per_query and
+ * additional pages exist beyond the current cursor.
+ */
+const TruncatedFlag = z.boolean().optional();
+
+// ---------------------------------------------------------------------------
+// FederationListResponseSchema<T> factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a Zod schema for a paginated federation list envelope.
+ *
+ * @param itemSchema - Zod schema for a single item in the list.
+ *
+ * @example
+ * ```ts
+ * const TaskListSchema = FederationListResponseSchema(TaskSchema);
+ * type TaskList = z.infer<typeof TaskListSchema>;
+ * ```
+ */
+export function FederationListResponseSchema<T extends z.ZodTypeAny>(itemSchema: T) {
+  return z.object({
+    items: z.array(itemSchema),
+    nextCursor: z.string().optional(),
+    _partial: PartialFlag,
+    _truncated: TruncatedFlag,
+  });
+}
+
+export type FederationListResponse<T> = {
+  items: T[];
+  nextCursor?: string;
+  _partial?: boolean;
+  _truncated?: boolean;
+};
+
+// ---------------------------------------------------------------------------
+// FederationGetResponseSchema<T> factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a Zod schema for a single-item federation get envelope.
+ *
+ * `item` is null when the resource was not found (404 equivalent on the wire).
+ *
+ * @param itemSchema - Zod schema for the item (nullable is applied internally).
+ *
+ * @example
+ * ```ts
+ * const TaskGetSchema = FederationGetResponseSchema(TaskSchema);
+ * type TaskGet = z.infer<typeof TaskGetSchema>;
+ * ```
+ */
+export function FederationGetResponseSchema<T extends z.ZodTypeAny>(itemSchema: T) {
+  return z.object({
+    item: itemSchema.nullable(),
+    _partial: PartialFlag,
+  });
+}
+
+export type FederationGetResponse<T> = {
+  item: T | null;
+  _partial?: boolean;
+};
+
+// ---------------------------------------------------------------------------
+// FederationCapabilitiesResponseSchema (fixed shape)
+// ---------------------------------------------------------------------------
+
+/**
+ * Shape mirrors FederationScope (apps/gateway/src/federation/scope-schema.ts)
+ * but is kept separate to avoid coupling packages/types to the gateway module.
+ * The serving side populates this from the resolved grant scope at request time.
+ */
+export const FederationCapabilitiesResponseSchema = z.object({
+  /**
+   * Resources this grant is allowed to query.
+   */
+  resources: z.array(z.string()).nonempty(),
+
+  /**
+   * Resources explicitly blocked for this grant even if they exist.
+   */
+  excluded_resources: z.array(z.string()),
+
+  /**
+   * Per-resource filters (mirrors FederationScope.filters from PRD §8.1).
+   * Keys are resource names; values control team/personal visibility.
+   */
+  filters: z
+    .record(
+      z.string(),
+      z.object({
+        include_teams: z.array(z.string()).optional(),
+        include_personal: z.boolean().optional(),
+      }),
+    )
+    .optional(),
+
+  /**
+   * Hard cap on rows returned per query for this grant.
+   */
+  max_rows_per_query: z.number().int().positive(),
+
+  /**
+   * Verbs currently available. Will expand in M4+ (search).
+   * Closed enum — only values from FEDERATION_VERBS are accepted.
+   */
+  supported_verbs: z.array(z.enum(FEDERATION_VERBS)).nonempty(),
+
+  /**
+   * Rate-limit state for this grant (PRD §9.1).
+   * M4 populates `remaining` and `reset_at`; M3 servers may return only
+   * `limit_per_minute` or omit the field entirely.
+   */
+  rate_limit: z
+    .object({
+      limit_per_minute: z.number().int().positive(),
+      remaining: z.number().int().nonnegative().optional(),
+      reset_at: z.string().datetime().optional(),
+    })
+    .optional(),
+});
+
+export type FederationCapabilitiesResponse = z.infer<typeof FederationCapabilitiesResponseSchema>;

packages/types/src/federation/source-tag.ts

@@ -0,0 +1,61 @@
+/**
+ * _source tag for federation fan-out results.
+ *
+ * Source of truth: docs/federation/PRD.md §9.3 and MILESTONES.md §M3 acceptance test #8.
+ *
+ * When source: "all" is requested, the gateway fans out to local + all active
+ * federated peers, merges results, and tags each item with _source so the
+ * caller knows the provenance.
+ *
+ * Pure — no NestJS, no DB, no Node-only APIs. Safe for browser/edge.
+ */
+
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Source tag schema
+// ---------------------------------------------------------------------------
+
+/**
+ * `_source` is either:
+ * - `"local"` — the item came from this gateway's own storage.
+ * - a peer common name (e.g. `"mosaic.uscllc.com"`) — the item came from
+ *   that federated peer.
+ */
+export const SourceTagSchema = z.object({
+  _source: z.string().min(1, { message: '_source must not be empty' }),
+});
+
+export type SourceTag = z.infer<typeof SourceTagSchema>;
+
+/**
+ * Literal union for the well-known local source value.
+ * Peers are identified by hostname strings, so there is no closed enum.
+ */
+export const SOURCE_LOCAL = 'local' as const;
+
+// ---------------------------------------------------------------------------
+// Helper: tagWithSource
+// ---------------------------------------------------------------------------
+
+/**
+ * Stamps each item in `items` with `{ _source: source }`.
+ *
+ * The return type merges the item type with SourceTag so callers get full
+ * type-safety on both the original fields and `_source`.
+ *
+ * @param items  - Array of items to tag.
+ * @param source - Either `"local"` or a peer hostname (common name from the
+ *                 client cert's CN or O field).
+ *
+ * @example
+ * ```ts
+ * const local = tagWithSource([{ id: '1', title: 'Task' }], 'local');
+ * // => [{ id: '1', title: 'Task', _source: 'local' }]
+ *
+ * const remote = tagWithSource(peerItems, 'mosaic.uscllc.com');
+ * ```
+ */
+export function tagWithSource<T extends object>(items: T[], source: string): Array<T & SourceTag> {
+  return items.map((item) => ({ ...item, _source: source }));
+}

packages/types/src/federation/verbs.ts

@@ -0,0 +1,11 @@
+/**
+ * Federation verb constants and types.
+ *
+ * Source of truth: docs/federation/PRD.md §9.1
+ *
+ * M3 ships list, get, capabilities. search lives in M4.
+ */
+
+export const FEDERATION_VERBS = ['list', 'get', 'capabilities'] as const;
+
+export type FederationVerb = (typeof FEDERATION_VERBS)[number];

packages/types/src/index.ts

@@ -5,3 +5,4 @@ export * from './agent/index.js';
 export * from './provider/index.js';
 export * from './routing/index.js';
 export * from './commands/index.js';
+export * from './federation/index.js';

pnpm-lock.yaml

@@ -679,6 +679,9 @@ importers:
       class-validator:
         specifier: ^0.15.1
         version: 0.15.1
+      zod:
+        specifier: ^4.3.6
+        version: 4.3.6
     devDependencies:
       typescript:
         specifier: ^5.8.0
@@ -710,10 +713,10 @@ importers:
     dependencies:
       '@mariozechner/pi-agent-core':
         specifier: ^0.63.1
-        version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)
+        version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)
       '@mariozechner/pi-ai':
         specifier: ^0.63.1
-        version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)
+        version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)
       '@sinclair/typebox':
         specifier: ^0.34.41
         version: 0.34.48
@@ -7326,6 +7329,12 @@ snapshots:
       '@jridgewell/gen-mapping': 0.3.13
       '@jridgewell/trace-mapping': 0.3.31
 
+  '@anthropic-ai/sdk@0.73.0(zod@3.25.76)':
+    dependencies:
+      json-schema-to-ts: 3.1.1
+    optionalDependencies:
+      zod: 3.25.76
+
   '@anthropic-ai/sdk@0.73.0(zod@4.3.6)':
     dependencies:
       json-schema-to-ts: 3.1.1
@@ -8667,6 +8676,18 @@ snapshots:
       - ws
       - zod
 
+  '@mariozechner/pi-agent-core@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)':
+    dependencies:
+      '@mariozechner/pi-ai': 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)
+    transitivePeerDependencies:
+      - '@modelcontextprotocol/sdk'
+      - aws-crt
+      - bufferutil
+      - supports-color
+      - utf-8-validate
+      - ws
+      - zod
+
   '@mariozechner/pi-agent-core@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)':
     dependencies:
       '@mariozechner/pi-ai': 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)
@@ -8715,6 +8736,30 @@ snapshots:
       - ws
       - zod
 
+  '@mariozechner/pi-ai@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)':
+    dependencies:
+      '@anthropic-ai/sdk': 0.73.0(zod@3.25.76)
+      '@aws-sdk/client-bedrock-runtime': 3.1008.0
+      '@google/genai': 1.45.0(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))
+      '@mistralai/mistralai': 1.14.1
+      '@sinclair/typebox': 0.34.48
+      ajv: 8.18.0
+      ajv-formats: 3.0.1(ajv@8.18.0)
+      chalk: 5.6.2
+      openai: 6.26.0(ws@8.20.0)(zod@3.25.76)
+      partial-json: 0.1.7
+      proxy-agent: 6.5.0
+      undici: 7.24.3
+      zod-to-json-schema: 3.25.1(zod@3.25.76)
+    transitivePeerDependencies:
+      - '@modelcontextprotocol/sdk'
+      - aws-crt
+      - bufferutil
+      - supports-color
+      - utf-8-validate
+      - ws
+      - zod
+
   '@mariozechner/pi-ai@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)':
     dependencies:
       '@anthropic-ai/sdk': 0.73.0(zod@4.3.6)
@@ -13307,6 +13352,11 @@ snapshots:
     dependencies:
       mimic-function: 5.0.1
 
+  openai@6.26.0(ws@8.20.0)(zod@3.25.76):
+    optionalDependencies:
+      ws: 8.20.0
+      zod: 3.25.76
+
   openai@6.26.0(ws@8.20.0)(zod@4.3.6):
     optionalDependencies:
       ws: 8.20.0