fix(federation): address #494 review findings (FED-M2-04)

H1: Replace HS256/HMAC signing with real JWK signing (ES256/RS256/ES384)
    via jose SignJWT. Algorithm derived from JWK kty/crv. Provisioner
    password dropped as signing input; kept only as optional env var for
    PBES2-decrypt path at startup.
H2: Clamp cert TTL to 900s (15 min) in both DTO validator and issueCert().
    Default changed to 300s (5 min). @Max reduced to 15*60.
H3: Real CSR validation via @peculiar/x509: parse PEM, verify self-
    signature, reject weak keys (RSA<2048, bad EC curves), reject MD5/SHA-1.
    New validateCsr() throws CaServiceError code INVALID_CSR on failure.
H4: Replace hardcoded \x24 DER length in federation.tpl with dynamic
    printf "%c" (len ...) encoding. Add UUID-shape validation for grantId
    and subjectUserId in buildOtt() with code INVALID_GRANT_ID.
H5: Load JWK into KeyObject once (lazy, cached). provisionerKeyJson raw
    string not stored as class field. provisionerPassword not stored.

M1: Set JWT sub to CSR CN (extracted via @peculiar/x509) instead of URL.
M2: Add jti: crypto.randomUUID() to OTT claims.
M3: Drop top-level sha claim; keep only step.sha.
M4: extractSerial() throws CaServiceError code CERT_PARSE instead of
    returning 'unknown' on failure.
M5: Set timeout: 5000 on https.RequestOptions + req.setTimeout(5000).
M6: OTT signature verified with jose.jwtVerify in tests. Added real P-256
    CSR test via @peculiar/x509 generator. Added provisionerPassword
    leak-check test.
M7: Constructor validates STEP_CA_URL must be https://.

Verification: typecheck ✓, 385 tests pass (16 new), lint ✓, format ✓.

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

.woodpecker/ci.yml

@@ -46,28 +46,18 @@ steps:
   test:
     image: *node_image
     environment:
-      # Avoid the namespace-level Woodpecker DB service named "postgres".
+      DATABASE_URL: postgresql://mosaic:mosaic@postgres:5432/mosaic
-      # The Kubernetes backend exposes service containers by step name.
-      DATABASE_URL: postgresql://mosaic:mosaic@ci-postgres:5432/mosaic
     commands:
       - *enable_pnpm
       # Install postgresql-client for pg_isready
       - apk add --no-cache postgresql-client
-      # Wait up to 60s for CI postgres to be ready; fail fast if it never comes up.
+      # Wait up to 30s for postgres to be ready
       - |
-        ready=0
+        for i in $(seq 1 30); do
-        for i in $(seq 1 60); do
+          pg_isready -h postgres -p 5432 -U mosaic && break
-          if pg_isready -h ci-postgres -p 5432 -U mosaic; then
+          echo "Waiting for postgres ($i/30)..."
-            ready=1
-            break
-          fi
-          echo "Waiting for ci-postgres ($i/60)..."
           sleep 1
         done
-        if [ "$ready" -ne 1 ]; then
-          echo "ci-postgres did not become ready" >&2
-          exit 1
-        fi
       # Run migrations (DATABASE_URL is set in environment above)
       - pnpm --filter @mosaicstack/db run db:migrate
       # Run all tests
@@ -76,7 +66,7 @@ steps:
       - typecheck
 
 services:
-  ci-postgres:
+  postgres:
     image: pgvector/pgvector:pg17
     environment:
       POSTGRES_USER: mosaic

.woodpecker/publish.yml

@@ -114,31 +114,6 @@ steps:
     depends_on:
       - build
 
-  build-appservice:
-    image: gcr.io/kaniko-project/executor:debug
-    environment:
-      REGISTRY_USER:
-        from_secret: gitea_username
-      REGISTRY_PASS:
-        from_secret: gitea_password
-      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
-      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
-      CI_COMMIT_SHA: ${CI_COMMIT_SHA}
-    commands:
-      - mkdir -p /kaniko/.docker
-      - echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$REGISTRY_USER\",\"password\":\"$REGISTRY_PASS\"}}}" > /kaniko/.docker/config.json
-      - |
-        DESTINATIONS="--destination git.mosaicstack.dev/mosaicstack/stack/appservice:sha-${CI_COMMIT_SHA:0:7}"
-        if [ "$CI_COMMIT_BRANCH" = "main" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/appservice:latest"
-        fi
-        if [ -n "$CI_COMMIT_TAG" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/appservice:$CI_COMMIT_TAG"
-        fi
-        /kaniko/executor --context . --dockerfile docker/appservice.Dockerfile $DESTINATIONS
-    depends_on:
-      - build
-
   build-web:
     image: gcr.io/kaniko-project/executor:debug
     environment:

README.md

@@ -58,8 +58,6 @@ mosaic yolo pi               # Pi in yolo mode
 
 The launcher verifies your config, checks for `SOUL.md`, injects your `AGENTS.md` standards into the runtime, and forwards all arguments.
 
-Pi launches default to a token-lean skill posture: `mosaic pi` passes `--no-skills` so Pi does not preload every global skill description into the system prompt. Use `MOSAIC_PI_SKILL_MODE=all mosaic pi` for the legacy all-skills catalog, or `MOSAIC_PI_SKILL_MODE=discover mosaic pi` to let Pi use its native settings/project skill discovery.
-
 ### TUI & Gateway
 
 ```bash

apps/appservice/package.json

@@ -1,35 +0,0 @@
-{
-  "name": "@mosaicstack/mosaic-as",
-  "version": "0.0.1",
-  "type": "module",
-  "private": true,
-  "repository": {
-    "type": "git",
-    "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
-    "directory": "apps/appservice"
-  },
-  "main": "dist/main.js",
-  "bin": {
-    "mosaic-as": "dist/main.js",
-    "mosaic-as-registration": "dist/registration-main.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "lint": "eslint src",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run --passWithNoTests",
-    "dev": "tsx watch src/main.ts"
-  },
-  "dependencies": {
-    "@mosaicstack/appservice": "workspace:*"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "tsx": "^4.19.0",
-    "typescript": "^5.8.0",
-    "vitest": "^2.0.0"
-  },
-  "files": [
-    "dist"
-  ]
-}

apps/appservice/src/__tests__/server.test.ts

@@ -1,152 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-
-import { AppserviceDaemon } from '../server.js';
-import type { DaemonConfig, DaemonRequest } from '../server.js';
-
-const cfg: DaemonConfig = {
-  homeserverUrl: 'https://hs.example',
-  domain: 'hs.example',
-  asToken: 'as-secret',
-  hsToken: 'hs-secret',
-  bridgeTokens: ['bridge-secret'],
-};
-
-const jsonResponse = (status: number, body: unknown): Response =>
-  new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } });
-
-const request = (overrides: Partial<DaemonRequest>): DaemonRequest => ({
-  method: 'GET',
-  path: '/',
-  searchParams: new URLSearchParams(),
-  body: undefined,
-  ...overrides,
-});
-
-const makeDaemon = () => {
-  const fetchMock = vi.fn(async (_input: URL | string) => jsonResponse(200, { event_id: '$sent' }));
-  const daemon = new AppserviceDaemon(cfg, fetchMock as unknown as typeof fetch, () => {});
-  return { daemon, fetchMock };
-};
-
-describe('AppserviceDaemon routing', () => {
-  it('serves health unauthenticated', async () => {
-    const { daemon } = makeDaemon();
-    expect((await daemon.handle(request({ path: '/health' }))).status).toBe(200);
-  });
-
-  it('404s unknown paths', async () => {
-    const { daemon } = makeDaemon();
-    expect((await daemon.handle(request({ path: '/nope' }))).status).toBe(404);
-  });
-
-  it('transactions require the hs_token', async () => {
-    const { daemon } = makeDaemon();
-    const bad = await daemon.handle(
-      request({
-        method: 'PUT',
-        path: '/_matrix/app/v1/transactions/t1',
-        authorizationHeader: 'Bearer wrong',
-        body: { events: [] },
-      }),
-    );
-    expect(bad.status).toBe(403);
-    const ok = await daemon.handle(
-      request({
-        method: 'PUT',
-        path: '/_matrix/app/v1/transactions/t1',
-        authorizationHeader: 'Bearer hs-secret',
-        body: { events: [{ type: 'm.room.message', event_id: '$e' }] },
-      }),
-    );
-    expect(ok.status).toBe(200);
-  });
-
-  it('bridge requires a bridge token (hs/as tokens do not work)', async () => {
-    const { daemon } = makeDaemon();
-    for (const token of [undefined, 'Bearer hs-secret', 'Bearer as-secret', 'Bearer nope']) {
-      const res = await daemon.handle(
-        request({
-          method: 'POST',
-          path: '/bridge/v1/messages',
-          authorizationHeader: token,
-          body: {},
-        }),
-      );
-      expect(res.status).toBe(403);
-    }
-  });
-
-  it('bridge message sends as the agent and returns the event id', async () => {
-    const { daemon, fetchMock } = makeDaemon();
-    const res = await daemon.handle(
-      request({
-        method: 'POST',
-        path: '/bridge/v1/messages',
-        authorizationHeader: 'Bearer bridge-secret',
-        body: { room_id: '!r:hs.example', agent: 'pi0-web1', body: 'hi', thread_root: '$req' },
-      }),
-    );
-    expect(res.status).toBe(200);
-    expect(res.body.event_id).toBe('$sent');
-    const sendCall = fetchMock.mock.calls
-      .map((c) => new URL(String(c[0])))
-      .find((u) => u.pathname.includes('/send/m.room.message/'));
-    expect(sendCall).toBeDefined();
-    expect(sendCall!.searchParams.get('user_id')).toBe('@agent-pi0-web1:hs.example');
-  });
-
-  it('bridge rejects invalid payloads with 400', async () => {
-    const { daemon } = makeDaemon();
-    const res = await daemon.handle(
-      request({
-        method: 'POST',
-        path: '/bridge/v1/messages',
-        authorizationHeader: 'Bearer bridge-secret',
-        body: { room_id: 'bad', agent: 'pi0', body: 'x' },
-      }),
-    );
-    expect(res.status).toBe(400);
-  });
-
-  it('bridge typing endpoint works', async () => {
-    const { daemon, fetchMock } = makeDaemon();
-    const res = await daemon.handle(
-      request({
-        method: 'POST',
-        path: '/bridge/v1/typing',
-        authorizationHeader: 'Bearer bridge-secret',
-        body: { room_id: '!r:hs.example', agent: 'pi0-web1', typing: true },
-      }),
-    );
-    expect(res.status).toBe(200);
-    const typingCall = fetchMock.mock.calls
-      .map((c) => new URL(String(c[0])))
-      .find((u) => u.pathname.includes('/typing/'));
-    expect(typingCall).toBeDefined();
-  });
-
-  it('authenticated unknown bridge sub-paths return 405, never fall through', async () => {
-    const { daemon } = makeDaemon();
-    const res = await daemon.handle(
-      request({
-        method: 'GET',
-        path: '/bridge/v1/unknown',
-        authorizationHeader: 'Bearer bridge-secret',
-      }),
-    );
-    expect(res.status).toBe(405);
-  });
-
-  it('empty bridge token list denies everything', async () => {
-    const daemon = new AppserviceDaemon({ ...cfg, bridgeTokens: [] }, undefined, () => {});
-    const res = await daemon.handle(
-      request({
-        method: 'POST',
-        path: '/bridge/v1/typing',
-        authorizationHeader: 'Bearer bridge-secret',
-        body: {},
-      }),
-    );
-    expect(res.status).toBe(403);
-  });
-});

apps/appservice/src/config.ts

@@ -1,23 +0,0 @@
-import type { DaemonConfig } from './server.js';
-
-const required = (name: string): string => {
-  const value = process.env[name];
-  if (!value) throw new Error(`missing required env var ${name}`);
-  return value;
-};
-
-export function configFromEnv(): DaemonConfig & { port: number } {
-  return {
-    homeserverUrl: required('MOSAIC_AS_HOMESERVER_URL'),
-    domain: required('MOSAIC_AS_DOMAIN'),
-    asToken: required('MOSAIC_AS_TOKEN'),
-    hsToken: required('MOSAIC_HS_TOKEN'),
-    userPrefix: process.env.MOSAIC_AS_USER_PREFIX ?? 'agent-',
-    senderLocalpart: process.env.MOSAIC_AS_SENDER_LOCALPART ?? 'mosaic-as',
-    bridgeTokens: (process.env.MOSAIC_AS_BRIDGE_TOKENS ?? '')
-      .split(',')
-      .map((t) => t.trim())
-      .filter(Boolean),
-    port: Number(process.env.MOSAIC_AS_PORT ?? 8008),
-  };
-}

apps/appservice/src/main.ts

@@ -1,67 +0,0 @@
-import http from 'node:http';
-
-import { configFromEnv } from './config.js';
-import { AppserviceDaemon } from './server.js';
-
-const cfg = configFromEnv();
-const daemon = new AppserviceDaemon(cfg);
-
-const MAX_BODY_BYTES = 1024 * 1024;
-
-const server = http.createServer((req, res) => {
-  const chunks: Buffer[] = [];
-  let received = 0;
-  let rejected = false;
-  req.on('data', (chunk: Buffer) => {
-    received += chunk.length;
-    if (received > MAX_BODY_BYTES) {
-      rejected = true;
-      res.writeHead(413, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ errcode: 'M_TOO_LARGE', error: 'request body too large' }));
-      req.destroy();
-      return;
-    }
-    chunks.push(chunk);
-  });
-  req.on('end', () => {
-    if (rejected) return;
-    void (async () => {
-      const url = new URL(req.url ?? '/', 'http://localhost');
-      let body: unknown;
-      try {
-        const raw = Buffer.concat(chunks).toString();
-        body = raw ? JSON.parse(raw) : undefined;
-      } catch {
-        res.writeHead(400, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ errcode: 'M_NOT_JSON', error: 'invalid json' }));
-        return;
-      }
-      const result = await daemon.handle({
-        method: req.method ?? 'GET',
-        path: url.pathname,
-        searchParams: url.searchParams,
-        authorizationHeader: req.headers.authorization,
-        body,
-      });
-      res.writeHead(result.status, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify(result.body));
-    })().catch((error: unknown) => {
-      console.error('request failed:', error);
-      if (res.headersSent) {
-        res.destroy();
-        return;
-      }
-      res.writeHead(500, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ error: 'internal error' }));
-    });
-  });
-});
-
-server.listen(cfg.port, () => {
-  console.log(
-    `mosaic-as listening on :${cfg.port} (homeserver ${cfg.homeserverUrl}, domain ${cfg.domain})`,
-  );
-  if (cfg.bridgeTokens.length === 0) {
-    console.warn('WARNING: MOSAIC_AS_BRIDGE_TOKENS is empty — bridge API will deny all requests');
-  }
-});

apps/appservice/src/registration-main.ts

@@ -1,10 +0,0 @@
-import { buildRegistration, registrationToYaml } from '@mosaicstack/appservice';
-
-import { configFromEnv } from './config.js';
-
-// Prints the Synapse registration YAML (mosaic-as.yaml) for the current env.
-// Usage: MOSAIC_AS_URL=http://mosaic-as:8008 mosaic-as-registration > mosaic-as.yaml
-const cfg = configFromEnv();
-const url = process.env.MOSAIC_AS_URL;
-if (!url) throw new Error('missing required env var MOSAIC_AS_URL');
-process.stdout.write(registrationToYaml(buildRegistration(cfg, { url })));

apps/appservice/src/server.ts

@@ -1,124 +0,0 @@
-import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
-
-import {
-  AppserviceIntent,
-  TransactionHandler,
-  validateBridgeMessage,
-  validateBridgeTyping,
-} from '@mosaicstack/appservice';
-import type { AppserviceConfig, MatrixEvent } from '@mosaicstack/appservice';
-
-export interface DaemonConfig extends AppserviceConfig {
-  /** Bearer tokens accepted on /bridge/v1/* (one per agent-comms host daemon). */
-  bridgeTokens: string[];
-}
-
-export interface DaemonRequest {
-  method: string;
-  /** URL path without query string. */
-  path: string;
-  searchParams: URLSearchParams;
-  authorizationHeader?: string;
-  body: unknown;
-}
-
-export interface DaemonResponse {
-  status: number;
-  body: Record<string, unknown>;
-}
-
-// Compare equal-length HMAC digests so neither content nor LENGTH of the
-// stored secret is observable through timing.
-const HMAC_KEY = randomBytes(32);
-const digest = (value: string): Buffer => createHmac('sha256', HMAC_KEY).update(value).digest();
-
-const safeEqual = (a: string, b: string): boolean => timingSafeEqual(digest(a), digest(b));
-
-const TXN_PATH = /^\/_matrix\/app\/v1\/transactions\/([^/]+)$/;
-
-/**
- * HTTP-framework-agnostic request router for the mosaic-as daemon: the
- * Application Service transactions endpoint (Synapse-facing) plus the
- * internal bridge API v1 (agent-comms daemon-facing). main.ts binds this to
- * node:http; tests drive it directly.
- */
-export class AppserviceDaemon {
-  readonly intent: AppserviceIntent;
-  private readonly transactions: TransactionHandler;
-
-  constructor(
-    private readonly cfg: DaemonConfig,
-    fetchImpl?: typeof fetch,
-    private readonly log: (line: string) => void = (line) => console.log(line),
-  ) {
-    this.intent = new AppserviceIntent(cfg, fetchImpl);
-    this.transactions = new TransactionHandler({
-      hsToken: cfg.hsToken,
-      onEvent: (event) => this.onEvent(event),
-      onError: (error, txnId) => this.log(`txn ${txnId} handler error: ${String(error)}`),
-    });
-  }
-
-  /** v1: the daemon only observes; room logic lives in the agent-comms daemons. */
-  private onEvent(event: MatrixEvent): void {
-    if (event.type === 'm.room.message') {
-      this.log(
-        `event ${event.event_id ?? '?'} in ${event.room_id ?? '?'} from ${event.sender ?? '?'}`,
-      );
-    }
-  }
-
-  private bridgeAuthorized(authorizationHeader: string | undefined): boolean {
-    if (!authorizationHeader?.startsWith('Bearer ')) return false;
-    const presented = authorizationHeader.slice('Bearer '.length);
-    return this.cfg.bridgeTokens.some((token) => safeEqual(presented, token));
-  }
-
-  async handle(req: DaemonRequest): Promise<DaemonResponse> {
-    if (req.method === 'GET' && req.path === '/health') {
-      return { status: 200, body: { ok: true } };
-    }
-
-    const txnMatch = req.method === 'PUT' ? TXN_PATH.exec(req.path) : null;
-    if (txnMatch?.[1] !== undefined) {
-      return this.transactions.handle(txnMatch[1], req.body, {
-        authorizationHeader: req.authorizationHeader,
-        accessTokenParam: req.searchParams.get('access_token') ?? undefined,
-      });
-    }
-
-    if (req.path.startsWith('/bridge/v1/')) {
-      if (!this.bridgeAuthorized(req.authorizationHeader)) {
-        return { status: 403, body: { errcode: 'M_FORBIDDEN', error: 'bad bridge token' } };
-      }
-      try {
-        if (req.method === 'POST' && req.path === '/bridge/v1/messages') {
-          validateBridgeMessage(req.body);
-          const eventId = await this.intent.sendAsAgent({
-            roomId: req.body.room_id,
-            agent: req.body.agent,
-            body: req.body.body,
-            threadRoot: req.body.thread_root,
-            msgtype: req.body.msgtype,
-            extraContent: req.body.extra_content,
-          });
-          return { status: 200, body: { event_id: eventId ?? null } };
-        }
-        if (req.method === 'POST' && req.path === '/bridge/v1/typing') {
-          validateBridgeTyping(req.body);
-          await this.intent.setTyping(req.body.room_id, req.body.agent, req.body.typing);
-          return { status: 200, body: {} };
-        }
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        this.log(`bridge error ${req.method} ${req.path}: ${message}`);
-        return { status: 400, body: { error: message } };
-      }
-      // Explicit: never fall out of the authenticated bridge block, so future
-      // sub-paths cannot accidentally route around the auth guard above.
-      return { status: 405, body: { error: 'unsupported bridge method/path' } };
-    }
-
-    return { status: 404, body: { error: 'not found' } };
-  }
-}

apps/appservice/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "dist",
-    "rootDir": "src"
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}

apps/gateway/package.json

@@ -73,7 +73,6 @@
     "rxjs": "^7.8.0",
     "socket.io": "^4.8.0",
     "uuid": "^11.0.0",
-    "undici": "^7.24.6",
     "zod": "^4.3.6"
   },
   "devDependencies": {

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

@@ -1,243 +0,0 @@
-/**
- * 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/__tests__/integration/federation-m2.integration.test.ts

@@ -1,483 +0,0 @@
-/**
- * Federation M2 integration tests (FED-M2-09).
- *
- * Covers MILESTONES.md acceptance tests #1, #2, #3, #5, #7, #8.
- *
- * Prerequisites:
- *   docker compose -f docker-compose.federated.yml --profile federated up -d
- *
- * Run DB-only tests (no Step-CA):
- *   FEDERATED_INTEGRATION=1 BETTER_AUTH_SECRET=test-secret pnpm --filter @mosaicstack/gateway test \
- *     src/__tests__/integration/federation-m2.integration.test.ts
- *
- * Run all tests including Step-CA-dependent ones:
- *   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.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
- */
-
-import * as crypto from 'node:crypto';
-import { afterAll, beforeAll, describe, expect, it } from 'vitest';
-import { Test } from '@nestjs/testing';
-import { GoneException } from '@nestjs/common';
-import { Pkcs10CertificateRequestGenerator, X509Certificate as PeculiarX509 } from '@peculiar/x509';
-import {
-  createDb,
-  type Db,
-  type DbHandle,
-  federationPeers,
-  federationGrants,
-  federationEnrollmentTokens,
-  inArray,
-  eq,
-} from '@mosaicstack/db';
-import * as schema from '@mosaicstack/db';
-import { seal } from '@mosaicstack/auth';
-import { DB } from '../../database/database.module.js';
-import { GrantsService } from '../../federation/grants.service.js';
-import { EnrollmentService } from '../../federation/enrollment.service.js';
-import { CaService } from '../../federation/ca.service.js';
-import { FederationScopeError } from '../../federation/scope-schema.js';
-
-const run = process.env['FEDERATED_INTEGRATION'] === '1';
-const stepCaRun = run && process.env['STEP_CA_AVAILABLE'] === '1';
-
-const PG_URL = 'postgresql://mosaic:mosaic@localhost:5433/mosaic';
-
-// ---------------------------------------------------------------------------
-// Helpers for test data isolation
-// ---------------------------------------------------------------------------
-
-/** Unique run prefix to identify rows created by this test run. */
-const RUN_ID = crypto.randomUUID();
-
-/** Insert a minimal user row to satisfy the FK on federation_grants.subject_user_id. */
-async function insertTestUser(db: Db, id: string): Promise<void> {
-  await db
-    .insert(schema.users)
-    .values({
-      id,
-      name: `test-user-${id}`,
-      email: `test-${id}@federation-test.invalid`,
-      emailVerified: false,
-    })
-    .onConflictDoNothing();
-}
-
-/** Insert a minimal peer row to satisfy the FK on federation_grants.peer_id. */
-async function insertTestPeer(db: Db, id: string, suffix: string = ''): Promise<void> {
-  await db
-    .insert(federationPeers)
-    .values({
-      id,
-      commonName: `test-peer-${RUN_ID}-${suffix}`,
-      displayName: `Test Peer ${suffix}`,
-      certPem: '-----BEGIN CERTIFICATE-----\nMOCK\n-----END CERTIFICATE-----\n',
-      certSerial: `test-serial-${id}`,
-      certNotAfter: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000),
-      state: 'pending',
-    })
-    .onConflictDoNothing();
-}
-
-// ---------------------------------------------------------------------------
-// DB-only test module (CaService mocked so env vars not required)
-// ---------------------------------------------------------------------------
-
-function buildDbModule(db: Db) {
-  return Test.createTestingModule({
-    providers: [
-      { provide: DB, useValue: db },
-      GrantsService,
-      {
-        provide: CaService,
-        useValue: {
-          issueCert: async () => {
-            throw new Error('CaService.issueCert should not be called in DB-only tests');
-          },
-        },
-      },
-      EnrollmentService,
-    ],
-  }).compile();
-}
-
-// ---------------------------------------------------------------------------
-// Test suite — DB-only (no Step-CA)
-// ---------------------------------------------------------------------------
-
-describe.skipIf(!run)('federation M2 — DB-only tests', () => {
-  let handle: DbHandle;
-  let db: Db;
-  let grantsService: GrantsService;
-
-  /** IDs created during this run — cleaned up in afterAll. */
-  const createdGrantIds: string[] = [];
-  const createdPeerIds: string[] = [];
-  const createdUserIds: string[] = [];
-
-  beforeAll(async () => {
-    process.env['BETTER_AUTH_SECRET'] ??= 'test-integration-sealing-key-not-for-prod';
-
-    handle = createDb(PG_URL);
-    db = handle.db;
-
-    const moduleRef = await buildDbModule(db);
-    grantsService = moduleRef.get(GrantsService);
-  });
-
-  afterAll(async () => {
-    // Clean up in FK-safe order: tokens → grants → peers → users
-    if (db && createdGrantIds.length > 0) {
-      await db
-        .delete(federationEnrollmentTokens)
-        .where(inArray(federationEnrollmentTokens.grantId, createdGrantIds))
-        .catch((e: unknown) => console.error('[federation-m2-test cleanup]', e));
-      await db
-        .delete(federationGrants)
-        .where(inArray(federationGrants.id, createdGrantIds))
-        .catch((e: unknown) => console.error('[federation-m2-test cleanup]', e));
-    }
-    if (db && createdPeerIds.length > 0) {
-      await db
-        .delete(federationPeers)
-        .where(inArray(federationPeers.id, createdPeerIds))
-        .catch((e: unknown) => console.error('[federation-m2-test 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-test cleanup]', e));
-    }
-    if (handle)
-      await handle.close().catch((e: unknown) => console.error('[federation-m2-test cleanup]', e));
-  });
-
-  // -------------------------------------------------------------------------
-  // #1 — grant create writes a pending row
-  // -------------------------------------------------------------------------
-  it('#1 — createGrant writes a pending row to DB', async () => {
-    const userId = crypto.randomUUID();
-    const peerId = crypto.randomUUID();
-    const validScope = {
-      resources: ['tasks'],
-      excluded_resources: [],
-      max_rows_per_query: 100,
-    };
-
-    await insertTestUser(db, userId);
-    await insertTestPeer(db, peerId, 'test1');
-    createdUserIds.push(userId);
-    createdPeerIds.push(peerId);
-
-    const grant = await grantsService.createGrant({
-      subjectUserId: userId,
-      scope: validScope,
-      peerId,
-    });
-
-    createdGrantIds.push(grant.id);
-
-    // Verify the row exists in DB with correct shape
-    const [row] = await db
-      .select()
-      .from(federationGrants)
-      .where(eq(federationGrants.id, grant.id))
-      .limit(1);
-
-    expect(row).toBeDefined();
-    expect(row?.status).toBe('pending');
-    expect(row?.peerId).toBe(peerId);
-    expect(row?.subjectUserId).toBe(userId);
-    const storedScope = row?.scope as Record<string, unknown>;
-    expect(storedScope['resources']).toEqual(['tasks']);
-    expect(storedScope['max_rows_per_query']).toBe(100);
-  }, 15_000);
-
-  // -------------------------------------------------------------------------
-  // #7 — scope with unknown resource type rejected
-  // -------------------------------------------------------------------------
-  it('#7 — createGrant rejects scope with unknown resource type', async () => {
-    const userId = crypto.randomUUID();
-    const peerId = crypto.randomUUID();
-    const invalidScope = {
-      resources: ['totally_unknown_resource'],
-      excluded_resources: [],
-      max_rows_per_query: 100,
-    };
-
-    await insertTestUser(db, userId);
-    await insertTestPeer(db, peerId, 'test7');
-    createdUserIds.push(userId);
-    createdPeerIds.push(peerId);
-
-    await expect(
-      grantsService.createGrant({
-        subjectUserId: userId,
-        scope: invalidScope,
-        peerId,
-      }),
-    ).rejects.toThrow(FederationScopeError);
-  }, 15_000);
-
-  // -------------------------------------------------------------------------
-  // #8 — listGrants returns accurate status for grants in various states
-  // -------------------------------------------------------------------------
-  it('#8 — listGrants returns accurate status for grants in various states', async () => {
-    const userId = crypto.randomUUID();
-    const peerId = crypto.randomUUID();
-    const validScope = {
-      resources: ['notes'],
-      excluded_resources: [],
-      max_rows_per_query: 50,
-    };
-
-    await insertTestUser(db, userId);
-    await insertTestPeer(db, peerId, 'test8');
-    createdUserIds.push(userId);
-    createdPeerIds.push(peerId);
-
-    // Create two pending grants via GrantsService
-    const grantA = await grantsService.createGrant({
-      subjectUserId: userId,
-      scope: validScope,
-      peerId,
-    });
-    const grantB = await grantsService.createGrant({
-      subjectUserId: userId,
-      scope: { resources: ['tasks'], excluded_resources: [], max_rows_per_query: 50 },
-      peerId,
-    });
-    createdGrantIds.push(grantA.id, grantB.id);
-
-    // Insert a third grant directly in 'revoked' state to test status variety
-    const [grantC] = await db
-      .insert(federationGrants)
-      .values({
-        id: crypto.randomUUID(),
-        subjectUserId: userId,
-        peerId,
-        scope: validScope,
-        status: 'revoked',
-        revokedAt: new Date(),
-      })
-      .returning();
-    createdGrantIds.push(grantC!.id);
-
-    // List all grants for this peer
-    const allForPeer = await grantsService.listGrants({ peerId });
-
-    const ourGrantIds = new Set([grantA.id, grantB.id, grantC!.id]);
-    const ourGrants = allForPeer.filter((g) => ourGrantIds.has(g.id));
-    expect(ourGrants).toHaveLength(3);
-
-    const pendingGrants = ourGrants.filter((g) => g.status === 'pending');
-    const revokedGrants = ourGrants.filter((g) => g.status === 'revoked');
-    expect(pendingGrants).toHaveLength(2);
-    expect(revokedGrants).toHaveLength(1);
-
-    // Status-filtered query
-    const pendingOnly = await grantsService.listGrants({ peerId, status: 'pending' });
-    const ourPending = pendingOnly.filter((g) => ourGrantIds.has(g.id));
-    expect(ourPending.every((g) => g.status === 'pending')).toBe(true);
-
-    // Verify peer list from DB also shows the peer rows with correct state
-    const peers = await db.select().from(federationPeers).where(eq(federationPeers.id, peerId));
-    expect(peers).toHaveLength(1);
-    expect(peers[0]?.state).toBe('pending');
-  }, 15_000);
-
-  // -------------------------------------------------------------------------
-  // #5 — client_key_pem encrypted at rest
-  // -------------------------------------------------------------------------
-  it('#5 — clientKeyPem stored in DB is a sealed ciphertext (not a valid PEM)', async () => {
-    const peerId = crypto.randomUUID();
-    const rawPem = '-----BEGIN PRIVATE KEY-----\nMOCK\n-----END PRIVATE KEY-----\n';
-    const sealed = seal(rawPem);
-
-    await db.insert(federationPeers).values({
-      id: peerId,
-      commonName: `test-peer-${RUN_ID}-sealed`,
-      displayName: 'Sealed Key Test Peer',
-      certPem: '-----BEGIN CERTIFICATE-----\nMOCK\n-----END CERTIFICATE-----\n',
-      certSerial: `test-serial-sealed-${peerId}`,
-      certNotAfter: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000),
-      state: 'pending',
-      clientKeyPem: sealed,
-    });
-    createdPeerIds.push(peerId);
-
-    const [row] = await db
-      .select()
-      .from(federationPeers)
-      .where(eq(federationPeers.id, peerId))
-      .limit(1);
-
-    expect(row).toBeDefined();
-    // The stored value must NOT be a valid PEM — it's a sealed ciphertext blob
-    expect(row?.clientKeyPem).toBeDefined();
-    expect(row?.clientKeyPem?.startsWith('-----BEGIN')).toBe(false);
-    // The sealed value should be non-trivial (at least 20 chars)
-    expect((row?.clientKeyPem ?? '').length).toBeGreaterThan(20);
-  }, 15_000);
-});
-
-// ---------------------------------------------------------------------------
-// Test suite — Step-CA gated
-// ---------------------------------------------------------------------------
-
-describe.skipIf(!stepCaRun)('federation M2 — Step-CA tests', () => {
-  let handle: DbHandle;
-  let db: Db;
-  let grantsService: GrantsService;
-  let enrollmentService: EnrollmentService;
-
-  const createdGrantIds: string[] = [];
-  const createdPeerIds: string[] = [];
-  const createdUserIds: string[] = [];
-
-  beforeAll(async () => {
-    handle = createDb(PG_URL);
-    db = handle.db;
-
-    // Use real CaService — env vars (STEP_CA_URL, STEP_CA_PROVISIONER_KEY_JSON,
-    // STEP_CA_ROOT_CERT_PATH) must be set when STEP_CA_AVAILABLE=1
-    const moduleRef = await Test.createTestingModule({
-      providers: [{ provide: DB, useValue: db }, CaService, GrantsService, EnrollmentService],
-    }).compile();
-
-    grantsService = moduleRef.get(GrantsService);
-    enrollmentService = moduleRef.get(EnrollmentService);
-  });
-
-  afterAll(async () => {
-    if (db && createdGrantIds.length > 0) {
-      await db
-        .delete(federationEnrollmentTokens)
-        .where(inArray(federationEnrollmentTokens.grantId, createdGrantIds))
-        .catch((e: unknown) => console.error('[federation-m2-test cleanup]', e));
-      await db
-        .delete(federationGrants)
-        .where(inArray(federationGrants.id, createdGrantIds))
-        .catch((e: unknown) => console.error('[federation-m2-test cleanup]', e));
-    }
-    if (db && createdPeerIds.length > 0) {
-      await db
-        .delete(federationPeers)
-        .where(inArray(federationPeers.id, createdPeerIds))
-        .catch((e: unknown) => console.error('[federation-m2-test 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-test cleanup]', e));
-    }
-    if (handle)
-      await handle.close().catch((e: unknown) => console.error('[federation-m2-test cleanup]', e));
-  });
-
-  /** Generate a P-256 key pair and PKCS#10 CSR, returning the CSR as PEM. */
-  async function generateCsrPem(cn: string): Promise<string> {
-    const alg = { name: 'ECDSA', namedCurve: 'P-256', hash: 'SHA-256' };
-    const keyPair = await crypto.subtle.generateKey(alg, true, ['sign', 'verify']);
-    const csr = await Pkcs10CertificateRequestGenerator.create({
-      name: `CN=${cn}`,
-      keys: keyPair,
-      signingAlgorithm: alg,
-    });
-    return csr.toString('pem');
-  }
-
-  // -------------------------------------------------------------------------
-  // #2 — enrollment signs CSR and returns cert
-  // -------------------------------------------------------------------------
-  it('#2 — redeem returns a certPem containing a valid PEM certificate', async () => {
-    const userId = crypto.randomUUID();
-    const peerId = crypto.randomUUID();
-    const validScope = {
-      resources: ['tasks'],
-      excluded_resources: [],
-      max_rows_per_query: 100,
-    };
-
-    await insertTestUser(db, userId);
-    await insertTestPeer(db, peerId, 'ca-test2');
-    createdUserIds.push(userId);
-    createdPeerIds.push(peerId);
-
-    const grant = await grantsService.createGrant({
-      subjectUserId: userId,
-      scope: validScope,
-      peerId,
-    });
-    createdGrantIds.push(grant.id);
-
-    const { token } = await enrollmentService.createToken({
-      grantId: grant.id,
-      peerId,
-      ttlSeconds: 900,
-    });
-
-    const csrPem = await generateCsrPem(`gateway-test-${RUN_ID.slice(0, 8)}`);
-    const result = await enrollmentService.redeem(token, csrPem);
-
-    expect(result.certPem).toContain('-----BEGIN CERTIFICATE-----');
-    expect(result.certChainPem).toContain('-----BEGIN CERTIFICATE-----');
-
-    // Verify the issued cert parses cleanly
-    const cert = new PeculiarX509(result.certPem);
-    expect(cert.serialNumber).toBeTruthy();
-  }, 30_000);
-
-  // -------------------------------------------------------------------------
-  // #3 — token single-use; second attempt returns GoneException
-  // -------------------------------------------------------------------------
-  it('#3 — second redeem of the same token throws GoneException', async () => {
-    const userId = crypto.randomUUID();
-    const peerId = crypto.randomUUID();
-    const validScope = {
-      resources: ['notes'],
-      excluded_resources: [],
-      max_rows_per_query: 50,
-    };
-
-    await insertTestUser(db, userId);
-    await insertTestPeer(db, peerId, 'ca-test3');
-    createdUserIds.push(userId);
-    createdPeerIds.push(peerId);
-
-    const grant = await grantsService.createGrant({
-      subjectUserId: userId,
-      scope: validScope,
-      peerId,
-    });
-    createdGrantIds.push(grant.id);
-
-    const { token } = await enrollmentService.createToken({
-      grantId: grant.id,
-      peerId,
-      ttlSeconds: 900,
-    });
-
-    const csrPem = await generateCsrPem(`gateway-test-replay-${RUN_ID.slice(0, 8)}`);
-
-    // First redeem must succeed
-    const result = await enrollmentService.redeem(token, csrPem);
-    expect(result.certPem).toContain('-----BEGIN CERTIFICATE-----');
-
-    // Second redeem with the same token must be rejected
-    await expect(enrollmentService.redeem(token, csrPem)).rejects.toThrow(GoneException);
-  }, 30_000);
-});

apps/gateway/src/agent/provider-credentials.service.ts

@@ -1,10 +1,62 @@
 import { Inject, Injectable, Logger } from '@nestjs/common';
-import { seal, unseal } from '@mosaicstack/auth';
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
 import type { Db } from '@mosaicstack/db';
 import { providerCredentials, eq, and } from '@mosaicstack/db';
 import { DB } from '../database/database.module.js';
 import type { ProviderCredentialSummaryDto } from './provider-credentials.dto.js';
 
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 12; // 96-bit IV for GCM
+const TAG_LENGTH = 16; // 128-bit auth tag
+
+/**
+ * Derive a 32-byte AES-256 key from BETTER_AUTH_SECRET using SHA-256.
+ * The secret is assumed to be set in the environment.
+ */
+function deriveEncryptionKey(): Buffer {
+  const secret = process.env['BETTER_AUTH_SECRET'];
+  if (!secret) {
+    throw new Error('BETTER_AUTH_SECRET is not set — cannot derive encryption key');
+  }
+  return createHash('sha256').update(secret).digest();
+}
+
+/**
+ * Encrypt a plain-text value using AES-256-GCM.
+ * Output format: base64(iv + authTag + ciphertext)
+ */
+function encrypt(plaintext: string): string {
+  const key = deriveEncryptionKey();
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+
+  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+
+  // Combine iv (12) + authTag (16) + ciphertext and base64-encode
+  const combined = Buffer.concat([iv, authTag, encrypted]);
+  return combined.toString('base64');
+}
+
+/**
+ * Decrypt a value encrypted by `encrypt()`.
+ * Throws on authentication failure (tampered data).
+ */
+function decrypt(encoded: string): string {
+  const key = deriveEncryptionKey();
+  const combined = Buffer.from(encoded, 'base64');
+
+  const iv = combined.subarray(0, IV_LENGTH);
+  const authTag = combined.subarray(IV_LENGTH, IV_LENGTH + TAG_LENGTH);
+  const ciphertext = combined.subarray(IV_LENGTH + TAG_LENGTH);
+
+  const decipher = createDecipheriv(ALGORITHM, key, iv);
+  decipher.setAuthTag(authTag);
+
+  const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  return decrypted.toString('utf8');
+}
+
 @Injectable()
 export class ProviderCredentialsService {
   private readonly logger = new Logger(ProviderCredentialsService.name);
@@ -22,7 +74,7 @@ export class ProviderCredentialsService {
     value: string,
     metadata?: Record<string, unknown>,
   ): Promise<void> {
-    const encryptedValue = seal(value);
+    const encryptedValue = encrypt(value);
 
     await this.db
       .insert(providerCredentials)
@@ -70,7 +122,7 @@ export class ProviderCredentialsService {
     }
 
     try {
-      return unseal(row.encryptedValue);
+      return decrypt(row.encryptedValue);
     } catch (err) {
       this.logger.error(
         `Failed to decrypt credential for user=${userId} provider=${provider}`,

apps/gateway/src/database/database.module.ts

@@ -1,21 +1,8 @@
 import { mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import {
+import { Global, Inject, Module, type OnApplicationShutdown } from '@nestjs/common';
-  Global,
+import { createDb, createPgliteDb, type Db, type DbHandle } from '@mosaicstack/db';
-  Inject,
-  Logger,
-  Module,
-  type OnApplicationShutdown,
-  type OnModuleInit,
-} from '@nestjs/common';
-import {
-  createDb,
-  createPgliteDb,
-  runPgliteMigrations,
-  type Db,
-  type DbHandle,
-} from '@mosaicstack/db';
 import { createStorageAdapter, type StorageAdapter } from '@mosaicstack/storage';
 import type { MosaicConfig } from '@mosaicstack/config';
 import { MOSAIC_CONFIG } from '../config/config.module.js';
@@ -52,37 +39,12 @@ export const STORAGE_ADAPTER = 'STORAGE_ADAPTER';
   ],
   exports: [DB, STORAGE_ADAPTER],
 })
-export class DatabaseModule implements OnApplicationShutdown, OnModuleInit {
+export class DatabaseModule implements OnApplicationShutdown {
-  private readonly logger = new Logger(DatabaseModule.name);
-
   constructor(
     @Inject(DB_HANDLE) private readonly handle: DbHandle,
     @Inject(STORAGE_ADAPTER) private readonly storageAdapter: StorageAdapter,
-    @Inject(MOSAIC_CONFIG) private readonly config: MosaicConfig,
   ) {}
 
-  // Migrations must complete before any module that injects DB starts serving
-  // requests. NestJS awaits onModuleInit before app.listen(), and modules that
-  // inject DB are initialized after this one — so all DB-dependent code sees a
-  // populated schema before the first HTTP request lands.
-  //
-  // Local (PGlite) tier: we run gateway-DB migrations explicitly here. The
-  // storage adapter writes to a separate PGlite directory and only manages its
-  // own KV tables, so we still call its migrate() afterwards.
-  //
-  // Postgres tier: PostgresAdapter.migrate() already calls runMigrations() on
-  // the same DATABASE_URL, so a single call covers both the gateway DB and
-  // the storage tables. We deliberately do NOT call runMigrations() here to
-  // avoid opening a second short-lived connection and doubling startup cost.
-  async onModuleInit(): Promise<void> {
-    if (this.config.tier === 'local') {
-      this.logger.log('Applying PGlite schema migrations...');
-      await runPgliteMigrations(this.handle);
-    }
-    this.logger.log(`Initializing storage adapter (${this.storageAdapter.name})...`);
-    await this.storageAdapter.migrate();
-  }
-
   async onApplicationShutdown(): Promise<void> {
     await Promise.all([this.handle.close(), this.storageAdapter.close()]);
   }

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

@@ -1,401 +0,0 @@
-/**
- * Unit tests for EnrollmentService — federation enrollment token flow (FED-M2-07).
- *
- * Coverage:
- *  createToken:
- *   - inserts token row with correct grantId, peerId, and future expiresAt
- *   - returns { token, expiresAt } with a 64-char hex token
- *   - clamps ttlSeconds to 900
- *
- *  redeem — error paths:
- *   - NotFoundException when token row not found
- *   - GoneException when token already used (usedAt set)
- *   - GoneException when token expired (expiresAt < now)
- *   - GoneException when grant status is not pending
- *
- *  redeem — success path:
- *   - atomically claims token BEFORE cert issuance (claim → issueCert → tx)
- *   - calls CaService.issueCert with correct args
- *   - activates grant + updates peer + writes audit log inside a transaction
- *   - returns { certPem, certChainPem }
- *
- *  redeem — replay protection:
- *   - GoneException when claim UPDATE returns empty array (concurrent request won)
- */
-
-import 'reflect-metadata';
-import { describe, it, expect, vi, beforeEach, beforeAll } from 'vitest';
-import { GoneException, NotFoundException } from '@nestjs/common';
-import type { Db } from '@mosaicstack/db';
-import { EnrollmentService } from '../enrollment.service.js';
-import { makeSelfSignedCert } from './helpers/test-cert.js';
-
-// ---------------------------------------------------------------------------
-// Test constants
-// ---------------------------------------------------------------------------
-
-const GRANT_ID = 'g1111111-1111-1111-1111-111111111111';
-const PEER_ID = 'p2222222-2222-2222-2222-222222222222';
-const USER_ID = 'u3333333-3333-3333-3333-333333333333';
-const TOKEN = 'a'.repeat(64); // 64-char hex
-
-// Real self-signed EC P-256 cert — populated once in beforeAll.
-// Required because EnrollmentService.extractCertNotAfter calls new X509Certificate(certPem)
-// with strict parsing (PR #501 HIGH-2: no silent fallback).
-let REAL_CERT_PEM: string;
-
-const MOCK_CHAIN_PEM = () => REAL_CERT_PEM + REAL_CERT_PEM;
-const MOCK_SERIAL = 'ABCD1234';
-
-beforeAll(async () => {
-  REAL_CERT_PEM = await makeSelfSignedCert();
-});
-
-// ---------------------------------------------------------------------------
-// Factory helpers
-// ---------------------------------------------------------------------------
-
-function makeTokenRow(overrides: Partial<Record<string, unknown>> = {}) {
-  return {
-    token: TOKEN,
-    grantId: GRANT_ID,
-    peerId: PEER_ID,
-    expiresAt: new Date(Date.now() + 60_000), // 1 min from now
-    usedAt: null,
-    createdAt: new Date(),
-    ...overrides,
-  };
-}
-
-function makeGrant(overrides: Partial<Record<string, unknown>> = {}) {
-  return {
-    id: GRANT_ID,
-    peerId: PEER_ID,
-    subjectUserId: USER_ID,
-    scope: { resources: ['tasks'], excluded_resources: [], max_rows_per_query: 100 },
-    status: 'pending',
-    expiresAt: null,
-    createdAt: new Date(),
-    revokedAt: null,
-    revokedReason: null,
-    ...overrides,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Mock DB builder
-// ---------------------------------------------------------------------------
-
-function makeDb({
-  tokenRows = [makeTokenRow()],
-  // claimedRows is returned by the .returning() on the token-claim UPDATE.
-  // Empty array = concurrent request won the race (GoneException).
-  claimedRows = [{ token: TOKEN }],
-}: {
-  tokenRows?: unknown[];
-  claimedRows?: unknown[];
-} = {}) {
-  // insert().values() — for createToken (outer db, not tx)
-  const insertValues = vi.fn().mockResolvedValue(undefined);
-  const insertMock = vi.fn().mockReturnValue({ values: insertValues });
-
-  // select().from().where().limit() — for fetching the token row
-  const limitSelect = vi.fn().mockResolvedValue(tokenRows);
-  const whereSelect = vi.fn().mockReturnValue({ limit: limitSelect });
-  const fromSelect = vi.fn().mockReturnValue({ where: whereSelect });
-  const selectMock = vi.fn().mockReturnValue({ from: fromSelect });
-
-  // update().set().where().returning() — for the atomic token claim (outer db)
-  const returningMock = vi.fn().mockResolvedValue(claimedRows);
-  const whereClaimUpdate = vi.fn().mockReturnValue({ returning: returningMock });
-  const setClaimMock = vi.fn().mockReturnValue({ where: whereClaimUpdate });
-  const claimUpdateMock = vi.fn().mockReturnValue({ set: setClaimMock });
-
-  // transaction(cb) — cb receives txMock; txMock has update + insert
-  //
-  // The tx mock must support two tx.update() call patterns (CRIT-2, PR #501):
-  //   1. Grant activation:  .update().set().where().returning() → resolves to [{ id }]
-  //   2. Peer update:       .update().set().where()             → resolves to undefined
-  //
-  // We achieve this by making txWhereUpdate return an object with BOTH a thenable
-  // interface (so `await tx.update().set().where()` works) AND a .returning() method.
-  const txGrantActivatedRow = { id: GRANT_ID };
-  const txReturningMock = vi.fn().mockResolvedValue([txGrantActivatedRow]);
-  const txWhereUpdate = vi.fn().mockReturnValue({
-    // .returning() for grant activation (first tx.update call)
-    returning: txReturningMock,
-    // thenables so `await tx.update().set().where()` also works for peer update
-    then: (resolve: (v: undefined) => void) => resolve(undefined),
-    catch: () => undefined,
-    finally: () => undefined,
-  });
-  const txSetMock = vi.fn().mockReturnValue({ where: txWhereUpdate });
-  const txUpdateMock = vi.fn().mockReturnValue({ set: txSetMock });
-  const txInsertValues = vi.fn().mockResolvedValue(undefined);
-  const txInsertMock = vi.fn().mockReturnValue({ values: txInsertValues });
-  const txMock = { update: txUpdateMock, insert: txInsertMock };
-  const transactionMock = vi
-    .fn()
-    .mockImplementation(async (cb: (tx: typeof txMock) => Promise<void>) => cb(txMock));
-
-  return {
-    insert: insertMock,
-    select: selectMock,
-    update: claimUpdateMock,
-    transaction: transactionMock,
-    _mocks: {
-      insertValues,
-      insertMock,
-      limitSelect,
-      whereSelect,
-      fromSelect,
-      selectMock,
-      returningMock,
-      whereClaimUpdate,
-      setClaimMock,
-      claimUpdateMock,
-      txInsertValues,
-      txInsertMock,
-      txWhereUpdate,
-      txReturningMock,
-      txSetMock,
-      txUpdateMock,
-      txMock,
-      transactionMock,
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Mock CaService
-// ---------------------------------------------------------------------------
-
-function makeCaService() {
-  return {
-    // REAL_CERT_PEM is populated by beforeAll — safe to reference via closure here
-    // because makeCaService() is only called after the suite's beforeAll runs.
-    issueCert: vi.fn().mockImplementation(async () => ({
-      certPem: REAL_CERT_PEM,
-      certChainPem: MOCK_CHAIN_PEM(),
-      serialNumber: MOCK_SERIAL,
-    })),
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Mock GrantsService
-// ---------------------------------------------------------------------------
-
-function makeGrantsService(grantOverrides: Partial<Record<string, unknown>> = {}) {
-  return {
-    getGrant: vi.fn().mockResolvedValue(makeGrant(grantOverrides)),
-    activateGrant: vi.fn().mockResolvedValue(makeGrant({ status: 'active' })),
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Helper: build service under test
-// ---------------------------------------------------------------------------
-
-function buildService({
-  db = makeDb(),
-  caService = makeCaService(),
-  grantsService = makeGrantsService(),
-}: {
-  db?: ReturnType<typeof makeDb>;
-  caService?: ReturnType<typeof makeCaService>;
-  grantsService?: ReturnType<typeof makeGrantsService>;
-} = {}) {
-  return new EnrollmentService(db as unknown as Db, caService as never, grantsService as never);
-}
-
-// ---------------------------------------------------------------------------
-// Tests: createToken
-// ---------------------------------------------------------------------------
-
-describe('EnrollmentService.createToken', () => {
-  it('inserts a token row and returns { token, expiresAt }', async () => {
-    const db = makeDb();
-    const service = buildService({ db });
-
-    const result = await service.createToken({
-      grantId: GRANT_ID,
-      peerId: PEER_ID,
-      ttlSeconds: 900,
-    });
-
-    expect(result.token).toHaveLength(64); // 32 bytes hex
-    expect(result.expiresAt).toBeDefined();
-    expect(new Date(result.expiresAt).getTime()).toBeGreaterThan(Date.now());
-    expect(db._mocks.insertValues).toHaveBeenCalledWith(
-      expect.objectContaining({ grantId: GRANT_ID, peerId: PEER_ID }),
-    );
-  });
-
-  it('clamps ttlSeconds to 900', async () => {
-    const db = makeDb();
-    const service = buildService({ db });
-
-    const before = Date.now();
-    const result = await service.createToken({
-      grantId: GRANT_ID,
-      peerId: PEER_ID,
-      ttlSeconds: 9999,
-    });
-    const after = Date.now();
-
-    const expiresMs = new Date(result.expiresAt).getTime();
-    // Should be at most 900s from now
-    expect(expiresMs - before).toBeLessThanOrEqual(900_000 + 100);
-    expect(expiresMs - after).toBeGreaterThanOrEqual(0);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Tests: redeem — error paths
-// ---------------------------------------------------------------------------
-
-describe('EnrollmentService.redeem — error paths', () => {
-  it('throws NotFoundException when token row not found', async () => {
-    const db = makeDb({ tokenRows: [] });
-    const service = buildService({ db });
-
-    await expect(service.redeem(TOKEN, '---CSR---')).rejects.toBeInstanceOf(NotFoundException);
-  });
-
-  it('throws GoneException when usedAt is set (already redeemed)', async () => {
-    const db = makeDb({ tokenRows: [makeTokenRow({ usedAt: new Date(Date.now() - 1000) })] });
-    const service = buildService({ db });
-
-    await expect(service.redeem(TOKEN, '---CSR---')).rejects.toBeInstanceOf(GoneException);
-  });
-
-  it('throws GoneException when token has expired', async () => {
-    const db = makeDb({ tokenRows: [makeTokenRow({ expiresAt: new Date(Date.now() - 1000) })] });
-    const service = buildService({ db });
-
-    await expect(service.redeem(TOKEN, '---CSR---')).rejects.toBeInstanceOf(GoneException);
-  });
-
-  it('throws GoneException when grant status is not pending', async () => {
-    const db = makeDb();
-    const grantsService = makeGrantsService({ status: 'active' });
-    const service = buildService({ db, grantsService });
-
-    await expect(service.redeem(TOKEN, '---CSR---')).rejects.toBeInstanceOf(GoneException);
-  });
-
-  it('throws GoneException when token claim UPDATE returns empty array (concurrent replay)', async () => {
-    const db = makeDb({ claimedRows: [] });
-    const caService = makeCaService();
-    const grantsService = makeGrantsService();
-    const service = buildService({ db, caService, grantsService });
-
-    await expect(service.redeem(TOKEN, '---CSR---')).rejects.toBeInstanceOf(GoneException);
-  });
-
-  it('does NOT call issueCert when token claim fails (no double minting)', async () => {
-    const db = makeDb({ claimedRows: [] });
-    const caService = makeCaService();
-    const service = buildService({ db, caService });
-
-    await expect(service.redeem(TOKEN, '---CSR---')).rejects.toBeInstanceOf(GoneException);
-    expect(caService.issueCert).not.toHaveBeenCalled();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Tests: redeem — success path
-// ---------------------------------------------------------------------------
-
-describe('EnrollmentService.redeem — success path', () => {
-  let db: ReturnType<typeof makeDb>;
-  let caService: ReturnType<typeof makeCaService>;
-  let grantsService: ReturnType<typeof makeGrantsService>;
-  let service: EnrollmentService;
-
-  beforeEach(() => {
-    db = makeDb();
-    caService = makeCaService();
-    grantsService = makeGrantsService();
-    service = buildService({ db, caService, grantsService });
-  });
-
-  it('claims token BEFORE calling issueCert (prevents double minting)', async () => {
-    const callOrder: string[] = [];
-    db._mocks.returningMock.mockImplementation(async () => {
-      callOrder.push('claim');
-      return [{ token: TOKEN }];
-    });
-    caService.issueCert.mockImplementation(async () => {
-      callOrder.push('issueCert');
-      return { certPem: REAL_CERT_PEM, certChainPem: MOCK_CHAIN_PEM(), serialNumber: MOCK_SERIAL };
-    });
-
-    await service.redeem(TOKEN, '---CSR---');
-
-    expect(callOrder).toEqual(['claim', 'issueCert']);
-  });
-
-  it('calls CaService.issueCert with grantId, subjectUserId, csrPem, ttlSeconds=300', async () => {
-    await service.redeem(TOKEN, '---CSR---');
-
-    expect(caService.issueCert).toHaveBeenCalledWith(
-      expect.objectContaining({
-        grantId: GRANT_ID,
-        subjectUserId: USER_ID,
-        csrPem: '---CSR---',
-        ttlSeconds: 300,
-      }),
-    );
-  });
-
-  it('runs activate grant + peer update + audit inside a transaction', async () => {
-    await service.redeem(TOKEN, '---CSR---');
-
-    expect(db._mocks.transactionMock).toHaveBeenCalledOnce();
-    // tx.update called twice: activate grant + update peer
-    expect(db._mocks.txUpdateMock).toHaveBeenCalledTimes(2);
-    // tx.insert called once: audit log
-    expect(db._mocks.txInsertMock).toHaveBeenCalledOnce();
-  });
-
-  it('activates grant (sets status=active) inside the transaction', async () => {
-    await service.redeem(TOKEN, '---CSR---');
-
-    expect(db._mocks.txSetMock).toHaveBeenCalledWith(expect.objectContaining({ status: 'active' }));
-  });
-
-  it('updates the federationPeers row with certPem, certSerial, state=active inside the transaction', async () => {
-    await service.redeem(TOKEN, '---CSR---');
-
-    expect(db._mocks.txSetMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        certPem: REAL_CERT_PEM,
-        certSerial: MOCK_SERIAL,
-        state: 'active',
-      }),
-    );
-  });
-
-  it('inserts an audit log row inside the transaction', async () => {
-    await service.redeem(TOKEN, '---CSR---');
-
-    expect(db._mocks.txInsertValues).toHaveBeenCalledWith(
-      expect.objectContaining({
-        peerId: PEER_ID,
-        grantId: GRANT_ID,
-        verb: 'enrollment',
-      }),
-    );
-  });
-
-  it('returns { certPem, certChainPem } from CaService', async () => {
-    const result = await service.redeem(TOKEN, '---CSR---');
-
-    expect(result).toEqual({
-      certPem: REAL_CERT_PEM,
-      certChainPem: MOCK_CHAIN_PEM(),
-    });
-  });
-});

apps/gateway/src/federation/__tests__/federation.controller.spec.ts

@@ -1,212 +0,0 @@
-/**
- * Unit tests for FederationController (FED-M2-08).
- *
- * Coverage:
- *  - listGrants: delegates to GrantsService with query params
- *  - createGrant: delegates to GrantsService, validates body
- *  - generateToken: returns enrollmentUrl containing the token
- *  - listPeers: returns DB rows
- */
-
-import 'reflect-metadata';
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { NotFoundException } from '@nestjs/common';
-import type { Db } from '@mosaicstack/db';
-import { FederationController } from '../federation.controller.js';
-import type { GrantsService } from '../grants.service.js';
-import type { EnrollmentService } from '../enrollment.service.js';
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-const GRANT_ID = 'g1111111-1111-1111-1111-111111111111';
-const PEER_ID = 'p2222222-2222-2222-2222-222222222222';
-const USER_ID = 'u3333333-3333-3333-3333-333333333333';
-
-const MOCK_GRANT = {
-  id: GRANT_ID,
-  peerId: PEER_ID,
-  subjectUserId: USER_ID,
-  scope: { resources: ['tasks'], operations: ['list'] },
-  status: 'pending' as const,
-  expiresAt: null,
-  createdAt: new Date('2026-01-01T00:00:00Z'),
-  revokedAt: null,
-  revokedReason: null,
-};
-
-const MOCK_PEER = {
-  id: PEER_ID,
-  commonName: 'test-peer',
-  displayName: 'Test Peer',
-  certPem: '',
-  certSerial: 'pending',
-  certNotAfter: new Date(0),
-  clientKeyPem: null,
-  state: 'pending' as const,
-  endpointUrl: null,
-  createdAt: new Date('2026-01-01T00:00:00Z'),
-  updatedAt: new Date('2026-01-01T00:00:00Z'),
-};
-
-// ---------------------------------------------------------------------------
-// DB mock builder
-// ---------------------------------------------------------------------------
-
-function makeDbMock(rows: unknown[] = []) {
-  const orderBy = vi.fn().mockResolvedValue(rows);
-  const where = vi.fn().mockReturnValue({ orderBy });
-  const from = vi.fn().mockReturnValue({ where, orderBy });
-  const select = vi.fn().mockReturnValue({ from });
-
-  return {
-    select,
-    from,
-    where,
-    orderBy,
-    insert: vi.fn(),
-    update: vi.fn(),
-    delete: vi.fn(),
-  } as unknown as Db;
-}
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-
-describe('FederationController', () => {
-  let db: Db;
-  let grantsService: GrantsService;
-  let enrollmentService: EnrollmentService;
-  let controller: FederationController;
-
-  beforeEach(() => {
-    db = makeDbMock([MOCK_PEER]);
-
-    grantsService = {
-      createGrant: vi.fn().mockResolvedValue(MOCK_GRANT),
-      getGrant: vi.fn().mockResolvedValue(MOCK_GRANT),
-      listGrants: vi.fn().mockResolvedValue([MOCK_GRANT]),
-      revokeGrant: vi.fn().mockResolvedValue({ ...MOCK_GRANT, status: 'revoked' }),
-      activateGrant: vi.fn(),
-      expireGrant: vi.fn(),
-    } as unknown as GrantsService;
-
-    enrollmentService = {
-      createToken: vi.fn().mockResolvedValue({
-        token: 'abc123def456abc123def456abc123def456abc123def456abc123def456ab12',
-        expiresAt: '2026-01-01T00:15:00.000Z',
-      }),
-      redeem: vi.fn(),
-    } as unknown as EnrollmentService;
-
-    controller = new FederationController(db, grantsService, enrollmentService);
-  });
-
-  // ─── Grant management ──────────────────────────────────────────────────
-
-  describe('listGrants', () => {
-    it('delegates to GrantsService with provided query params', async () => {
-      const query = { peerId: PEER_ID, status: 'pending' as const };
-      const result = await controller.listGrants(query);
-
-      expect(grantsService.listGrants).toHaveBeenCalledWith(query);
-      expect(result).toEqual([MOCK_GRANT]);
-    });
-
-    it('delegates to GrantsService with empty filters', async () => {
-      const result = await controller.listGrants({});
-
-      expect(grantsService.listGrants).toHaveBeenCalledWith({});
-      expect(result).toEqual([MOCK_GRANT]);
-    });
-  });
-
-  describe('createGrant', () => {
-    it('delegates to GrantsService and returns created grant', async () => {
-      const body = {
-        peerId: PEER_ID,
-        subjectUserId: USER_ID,
-        scope: { resources: ['tasks'], operations: ['list'] },
-      };
-
-      const result = await controller.createGrant(body);
-
-      expect(grantsService.createGrant).toHaveBeenCalledWith(body);
-      expect(result).toEqual(MOCK_GRANT);
-    });
-  });
-
-  describe('getGrant', () => {
-    it('delegates to GrantsService with provided ID', async () => {
-      const result = await controller.getGrant(GRANT_ID);
-
-      expect(grantsService.getGrant).toHaveBeenCalledWith(GRANT_ID);
-      expect(result).toEqual(MOCK_GRANT);
-    });
-  });
-
-  describe('revokeGrant', () => {
-    it('delegates to GrantsService with id and reason', async () => {
-      const result = await controller.revokeGrant(GRANT_ID, { reason: 'test reason' });
-
-      expect(grantsService.revokeGrant).toHaveBeenCalledWith(GRANT_ID, 'test reason');
-      expect(result).toMatchObject({ status: 'revoked' });
-    });
-
-    it('delegates without reason when omitted', async () => {
-      await controller.revokeGrant(GRANT_ID, {});
-
-      expect(grantsService.revokeGrant).toHaveBeenCalledWith(GRANT_ID, undefined);
-    });
-  });
-
-  describe('generateToken', () => {
-    it('returns enrollmentUrl containing the token', async () => {
-      const token = 'abc123def456abc123def456abc123def456abc123def456abc123def456ab12';
-      vi.mocked(enrollmentService.createToken).mockResolvedValueOnce({
-        token,
-        expiresAt: '2026-01-01T00:15:00.000Z',
-      });
-
-      const result = await controller.generateToken(GRANT_ID, { ttlSeconds: 900 });
-
-      expect(result.token).toBe(token);
-      expect(result.enrollmentUrl).toContain(token);
-      expect(result.enrollmentUrl).toContain('/api/federation/enrollment/');
-    });
-
-    it('creates token via EnrollmentService with correct grantId and peerId', async () => {
-      await controller.generateToken(GRANT_ID, { ttlSeconds: 300 });
-
-      expect(enrollmentService.createToken).toHaveBeenCalledWith({
-        grantId: GRANT_ID,
-        peerId: PEER_ID,
-        ttlSeconds: 300,
-      });
-    });
-
-    it('throws NotFoundException when grant does not exist', async () => {
-      vi.mocked(grantsService.getGrant).mockRejectedValueOnce(
-        new NotFoundException(`Grant ${GRANT_ID} not found`),
-      );
-
-      await expect(controller.generateToken(GRANT_ID, { ttlSeconds: 900 })).rejects.toThrow(
-        NotFoundException,
-      );
-    });
-  });
-
-  // ─── Peer management ───────────────────────────────────────────────────
-
-  describe('listPeers', () => {
-    it('returns DB rows ordered by commonName', async () => {
-      const result = await controller.listPeers();
-
-      expect(db.select).toHaveBeenCalled();
-      // The DB mock resolves with [MOCK_PEER]
-      expect(result).toEqual([MOCK_PEER]);
-    });
-  });
-});

apps/gateway/src/federation/__tests__/grants.service.spec.ts

@@ -1,351 +0,0 @@
-/**
- * Unit tests for GrantsService — federation grants CRUD + status transitions (FED-M2-06).
- *
- * Coverage:
- *  - createGrant: validates scope via parseFederationScope
- *  - createGrant: inserts with status 'pending'
- *  - getGrant: returns grant when found
- *  - getGrant: throws NotFoundException when not found
- *  - listGrants: no filters returns all grants
- *  - listGrants: filters by peerId
- *  - listGrants: filters by subjectUserId
- *  - listGrants: filters by status
- *  - listGrants: multiple filters combined
- *  - activateGrant: pending → active works
- *  - activateGrant: non-pending throws ConflictException
- *  - revokeGrant: active → revoked works, sets revokedAt
- *  - revokeGrant: non-active throws ConflictException
- *  - expireGrant: active → expired works
- *  - expireGrant: non-active throws ConflictException
- */
-
-import 'reflect-metadata';
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { ConflictException, NotFoundException } from '@nestjs/common';
-import type { Db } from '@mosaicstack/db';
-import { GrantsService } from '../grants.service.js';
-import { FederationScopeError } from '../scope-schema.js';
-
-// ---------------------------------------------------------------------------
-// Minimal valid federation scope for testing
-// ---------------------------------------------------------------------------
-const VALID_SCOPE = {
-  resources: ['tasks'] as const,
-  excluded_resources: [],
-  max_rows_per_query: 100,
-};
-
-const PEER_ID = 'a1111111-1111-1111-1111-111111111111';
-const USER_ID = 'u2222222-2222-2222-2222-222222222222';
-const GRANT_ID = 'g3333333-3333-3333-3333-333333333333';
-
-// ---------------------------------------------------------------------------
-// Build a mock DB that mimics chained Drizzle query builder calls
-// ---------------------------------------------------------------------------
-
-function makeMockGrant(overrides: Partial<Record<string, unknown>> = {}) {
-  return {
-    id: GRANT_ID,
-    peerId: PEER_ID,
-    subjectUserId: USER_ID,
-    scope: VALID_SCOPE,
-    status: 'pending',
-    expiresAt: null,
-    createdAt: new Date('2026-01-01T00:00:00Z'),
-    revokedAt: null,
-    revokedReason: null,
-    ...overrides,
-  };
-}
-
-function makeDb(
-  overrides: {
-    insertReturning?: unknown[];
-    selectRows?: unknown[];
-    updateReturning?: unknown[];
-  } = {},
-) {
-  const insertReturning = overrides.insertReturning ?? [makeMockGrant()];
-  const selectRows = overrides.selectRows ?? [makeMockGrant()];
-  const updateReturning = overrides.updateReturning ?? [makeMockGrant({ status: 'active' })];
-
-  // Drizzle returns a chainable builder; we need to mock the full chain.
-  const returningInsert = vi.fn().mockResolvedValue(insertReturning);
-  const valuesInsert = vi.fn().mockReturnValue({ returning: returningInsert });
-  const insertMock = vi.fn().mockReturnValue({ values: valuesInsert });
-
-  // select().from().where().limit()
-  const limitSelect = vi.fn().mockResolvedValue(selectRows);
-  const whereSelect = vi.fn().mockReturnValue({ limit: limitSelect });
-  // from returns something that is both thenable (for full-table select) and has .where()
-  const fromSelect = vi.fn().mockReturnValue({
-    where: whereSelect,
-    limit: limitSelect,
-    // Make it thenable for listGrants with no filters (await db.select().from(federationGrants))
-    then: (resolve: (v: unknown) => unknown) => resolve(selectRows),
-  });
-  const selectMock = vi.fn().mockReturnValue({ from: fromSelect });
-
-  const returningUpdate = vi.fn().mockResolvedValue(updateReturning);
-  const whereUpdate = vi.fn().mockReturnValue({ returning: returningUpdate });
-  const setMock = vi.fn().mockReturnValue({ where: whereUpdate });
-  const updateMock = vi.fn().mockReturnValue({ set: setMock });
-
-  return {
-    insert: insertMock,
-    select: selectMock,
-    update: updateMock,
-    // Expose internals for assertions
-    _mocks: {
-      insertReturning,
-      valuesInsert,
-      insertMock,
-      limitSelect,
-      whereSelect,
-      fromSelect,
-      selectMock,
-      returningUpdate,
-      whereUpdate,
-      setMock,
-      updateMock,
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-
-describe('GrantsService', () => {
-  let db: ReturnType<typeof makeDb>;
-  let service: GrantsService;
-
-  beforeEach(() => {
-    db = makeDb();
-    service = new GrantsService(db as unknown as Db);
-  });
-
-  // ─── createGrant ──────────────────────────────────────────────────────────
-
-  describe('createGrant', () => {
-    it('calls parseFederationScope — rejects an invalid scope', async () => {
-      const invalidScope = { resources: [], max_rows_per_query: 0 };
-      await expect(
-        service.createGrant({ peerId: PEER_ID, subjectUserId: USER_ID, scope: invalidScope }),
-      ).rejects.toBeInstanceOf(FederationScopeError);
-    });
-
-    it('inserts a grant with status pending and returns it', async () => {
-      const result = await service.createGrant({
-        peerId: PEER_ID,
-        subjectUserId: USER_ID,
-        scope: VALID_SCOPE,
-      });
-
-      expect(db._mocks.valuesInsert).toHaveBeenCalledWith(
-        expect.objectContaining({ status: 'pending', peerId: PEER_ID, subjectUserId: USER_ID }),
-      );
-      expect(result.status).toBe('pending');
-    });
-
-    it('passes expiresAt as a Date when provided', async () => {
-      await service.createGrant({
-        peerId: PEER_ID,
-        subjectUserId: USER_ID,
-        scope: VALID_SCOPE,
-        expiresAt: '2027-01-01T00:00:00Z',
-      });
-
-      expect(db._mocks.valuesInsert).toHaveBeenCalledWith(
-        expect.objectContaining({ expiresAt: expect.any(Date) }),
-      );
-    });
-
-    it('sets expiresAt to null when not provided', async () => {
-      await service.createGrant({ peerId: PEER_ID, subjectUserId: USER_ID, scope: VALID_SCOPE });
-
-      expect(db._mocks.valuesInsert).toHaveBeenCalledWith(
-        expect.objectContaining({ expiresAt: null }),
-      );
-    });
-  });
-
-  // ─── getGrant ─────────────────────────────────────────────────────────────
-
-  describe('getGrant', () => {
-    it('returns the grant when found', async () => {
-      const result = await service.getGrant(GRANT_ID);
-      expect(result.id).toBe(GRANT_ID);
-    });
-
-    it('throws NotFoundException when no rows returned', async () => {
-      db = makeDb({ selectRows: [] });
-      service = new GrantsService(db as unknown as Db);
-      await expect(service.getGrant(GRANT_ID)).rejects.toBeInstanceOf(NotFoundException);
-    });
-  });
-
-  // ─── listGrants ───────────────────────────────────────────────────────────
-
-  describe('listGrants', () => {
-    it('queries without where clause when no filters provided', async () => {
-      const result = await service.listGrants({});
-      expect(Array.isArray(result)).toBe(true);
-    });
-
-    it('applies peerId filter', async () => {
-      await service.listGrants({ peerId: PEER_ID });
-      expect(db._mocks.whereSelect).toHaveBeenCalled();
-    });
-
-    it('applies subjectUserId filter', async () => {
-      await service.listGrants({ subjectUserId: USER_ID });
-      expect(db._mocks.whereSelect).toHaveBeenCalled();
-    });
-
-    it('applies status filter', async () => {
-      await service.listGrants({ status: 'active' });
-      expect(db._mocks.whereSelect).toHaveBeenCalled();
-    });
-
-    it('applies multiple filters combined', async () => {
-      await service.listGrants({ peerId: PEER_ID, status: 'pending' });
-      expect(db._mocks.whereSelect).toHaveBeenCalled();
-    });
-  });
-
-  // ─── activateGrant ────────────────────────────────────────────────────────
-
-  describe('activateGrant', () => {
-    it('transitions pending → active and returns updated grant', async () => {
-      db = makeDb({
-        selectRows: [makeMockGrant({ status: 'pending' })],
-        updateReturning: [makeMockGrant({ status: 'active' })],
-      });
-      service = new GrantsService(db as unknown as Db);
-
-      const result = await service.activateGrant(GRANT_ID);
-
-      expect(db._mocks.setMock).toHaveBeenCalledWith({ status: 'active' });
-      expect(result.status).toBe('active');
-    });
-
-    it('throws ConflictException when grant is already active', async () => {
-      db = makeDb({ selectRows: [makeMockGrant({ status: 'active' })] });
-      service = new GrantsService(db as unknown as Db);
-
-      await expect(service.activateGrant(GRANT_ID)).rejects.toBeInstanceOf(ConflictException);
-    });
-
-    it('throws ConflictException when grant is revoked', async () => {
-      db = makeDb({ selectRows: [makeMockGrant({ status: 'revoked' })] });
-      service = new GrantsService(db as unknown as Db);
-
-      await expect(service.activateGrant(GRANT_ID)).rejects.toBeInstanceOf(ConflictException);
-    });
-
-    it('throws ConflictException when grant is expired', async () => {
-      db = makeDb({ selectRows: [makeMockGrant({ status: 'expired' })] });
-      service = new GrantsService(db as unknown as Db);
-
-      await expect(service.activateGrant(GRANT_ID)).rejects.toBeInstanceOf(ConflictException);
-    });
-  });
-
-  // ─── revokeGrant ──────────────────────────────────────────────────────────
-
-  describe('revokeGrant', () => {
-    it('transitions active → revoked and sets revokedAt', async () => {
-      const revokedAt = new Date();
-      db = makeDb({
-        selectRows: [makeMockGrant({ status: 'active' })],
-        updateReturning: [makeMockGrant({ status: 'revoked', revokedAt })],
-      });
-      service = new GrantsService(db as unknown as Db);
-
-      const result = await service.revokeGrant(GRANT_ID, 'test reason');
-
-      expect(db._mocks.setMock).toHaveBeenCalledWith(
-        expect.objectContaining({
-          status: 'revoked',
-          revokedAt: expect.any(Date),
-          revokedReason: 'test reason',
-        }),
-      );
-      expect(result.status).toBe('revoked');
-    });
-
-    it('sets revokedReason to null when not provided', async () => {
-      db = makeDb({
-        selectRows: [makeMockGrant({ status: 'active' })],
-        updateReturning: [makeMockGrant({ status: 'revoked', revokedAt: new Date() })],
-      });
-      service = new GrantsService(db as unknown as Db);
-
-      await service.revokeGrant(GRANT_ID);
-
-      expect(db._mocks.setMock).toHaveBeenCalledWith(
-        expect.objectContaining({ revokedReason: null }),
-      );
-    });
-
-    it('throws ConflictException when grant is pending', async () => {
-      db = makeDb({ selectRows: [makeMockGrant({ status: 'pending' })] });
-      service = new GrantsService(db as unknown as Db);
-
-      await expect(service.revokeGrant(GRANT_ID)).rejects.toBeInstanceOf(ConflictException);
-    });
-
-    it('throws ConflictException when grant is already revoked', async () => {
-      db = makeDb({ selectRows: [makeMockGrant({ status: 'revoked' })] });
-      service = new GrantsService(db as unknown as Db);
-
-      await expect(service.revokeGrant(GRANT_ID)).rejects.toBeInstanceOf(ConflictException);
-    });
-
-    it('throws ConflictException when grant is expired', async () => {
-      db = makeDb({ selectRows: [makeMockGrant({ status: 'expired' })] });
-      service = new GrantsService(db as unknown as Db);
-
-      await expect(service.revokeGrant(GRANT_ID)).rejects.toBeInstanceOf(ConflictException);
-    });
-  });
-
-  // ─── expireGrant ──────────────────────────────────────────────────────────
-
-  describe('expireGrant', () => {
-    it('transitions active → expired and returns updated grant', async () => {
-      db = makeDb({
-        selectRows: [makeMockGrant({ status: 'active' })],
-        updateReturning: [makeMockGrant({ status: 'expired' })],
-      });
-      service = new GrantsService(db as unknown as Db);
-
-      const result = await service.expireGrant(GRANT_ID);
-
-      expect(db._mocks.setMock).toHaveBeenCalledWith({ status: 'expired' });
-      expect(result.status).toBe('expired');
-    });
-
-    it('throws ConflictException when grant is pending', async () => {
-      db = makeDb({ selectRows: [makeMockGrant({ status: 'pending' })] });
-      service = new GrantsService(db as unknown as Db);
-
-      await expect(service.expireGrant(GRANT_ID)).rejects.toBeInstanceOf(ConflictException);
-    });
-
-    it('throws ConflictException when grant is already expired', async () => {
-      db = makeDb({ selectRows: [makeMockGrant({ status: 'expired' })] });
-      service = new GrantsService(db as unknown as Db);
-
-      await expect(service.expireGrant(GRANT_ID)).rejects.toBeInstanceOf(ConflictException);
-    });
-
-    it('throws ConflictException when grant is revoked', async () => {
-      db = makeDb({ selectRows: [makeMockGrant({ status: 'revoked' })] });
-      service = new GrantsService(db as unknown as Db);
-
-      await expect(service.expireGrant(GRANT_ID)).rejects.toBeInstanceOf(ConflictException);
-    });
-  });
-});

apps/gateway/src/federation/__tests__/helpers/test-cert.ts

@@ -1,138 +0,0 @@
-/**
- * Test helpers for generating real X.509 PEM certificates in unit tests.
- *
- * PR #501 (FED-M2-11) introduced strict `new X509Certificate(certPem)` parsing
- * in both EnrollmentService.extractCertNotAfter and CaService.issueCert — dummy
- * cert strings now throw `error:0680007B:asn1 encoding routines::header too long`.
- *
- * These helpers produce minimal but cryptographically valid self-signed EC P-256
- * certificates via @peculiar/x509 + Node.js webcrypto, suitable for test mocks.
- *
- * Two variants:
- *  - makeSelfSignedCert()          Plain cert — satisfies node:crypto X509Certificate parse.
- *  - makeMosaicIssuedCert(opts)    Cert with custom Mosaic OID extensions — satisfies the
- *                                  CRIT-1 OID presence + value checks in CaService.issueCert.
- */
-
-import { webcrypto } from 'node:crypto';
-import {
-  X509CertificateGenerator,
-  Extension,
-  KeyUsagesExtension,
-  KeyUsageFlags,
-  BasicConstraintsExtension,
-  cryptoProvider,
-} from '@peculiar/x509';
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Encode a string as an ASN.1 UTF8String TLV:
- *   0x0C (tag) + 1-byte length (for strings ≤ 127 bytes) + UTF-8 bytes.
- *
- * CaService.issueCert reads the extension value as:
- *   decoder.decode(grantIdExt.value.slice(2))
- * i.e. it skips the tag + length byte and decodes the remainder as UTF-8.
- * So we must produce exactly this encoding as the OCTET STRING content.
- */
-function encodeUtf8String(value: string): Uint8Array {
-  const utf8 = new TextEncoder().encode(value);
-  if (utf8.length > 127) {
-    throw new Error('encodeUtf8String: value too long for single-byte length encoding');
-  }
-  const buf = new Uint8Array(2 + utf8.length);
-  buf[0] = 0x0c; // ASN.1 UTF8String tag
-  buf[1] = utf8.length;
-  buf.set(utf8, 2);
-  return buf;
-}
-
-// ---------------------------------------------------------------------------
-// Mosaic OID constants (must match production CaService)
-// ---------------------------------------------------------------------------
-
-const OID_MOSAIC_GRANT_ID = '1.3.6.1.4.1.99999.1';
-const OID_MOSAIC_SUBJECT_USER_ID = '1.3.6.1.4.1.99999.2';
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * Generate a minimal self-signed EC P-256 certificate valid for 1 day.
- * CN=harness-test, no custom extensions.
- *
- * Suitable for:
- *  - EnrollmentService.extractCertNotAfter (just needs parseable PEM)
- *  - Any mock that returns certPem / certChainPem without OID checks
- */
-export async function makeSelfSignedCert(): Promise<string> {
-  // Ensure @peculiar/x509 uses Node.js webcrypto (available as globalThis.crypto in Node 19+,
-  // but we set it explicitly here to be safe on all Node 18+ versions).
-  cryptoProvider.set(webcrypto as unknown as Parameters<typeof cryptoProvider.set>[0]);
-
-  const alg = { name: 'ECDSA', namedCurve: 'P-256', hash: 'SHA-256' } as const;
-  const keys = await webcrypto.subtle.generateKey(alg, false, ['sign', 'verify']);
-
-  const now = new Date();
-  const tomorrow = new Date(now.getTime() + 86_400_000);
-
-  const cert = await X509CertificateGenerator.createSelfSigned({
-    serialNumber: '01',
-    name: 'CN=harness-test',
-    notBefore: now,
-    notAfter: tomorrow,
-    signingAlgorithm: alg,
-    keys,
-    extensions: [
-      new BasicConstraintsExtension(false),
-      new KeyUsagesExtension(KeyUsageFlags.digitalSignature),
-    ],
-  });
-
-  return cert.toString('pem');
-}
-
-/**
- * Generate a self-signed EC P-256 certificate that contains the two custom
- * Mosaic OID extensions required by CaService.issueCert's CRIT-1 check:
- *   OID 1.3.6.1.4.1.99999.1  → mosaic_grant_id   (value = grantId)
- *   OID 1.3.6.1.4.1.99999.2  → mosaic_subject_user_id (value = subjectUserId)
- *
- * The extension value encoding matches the production parser's `.slice(2)` assumption:
- * each extension value is an OCTET STRING wrapping an ASN.1 UTF8String TLV.
- */
-export async function makeMosaicIssuedCert(opts: {
-  grantId: string;
-  subjectUserId: string;
-}): Promise<string> {
-  // Ensure @peculiar/x509 uses Node.js webcrypto.
-  cryptoProvider.set(webcrypto as unknown as Parameters<typeof cryptoProvider.set>[0]);
-
-  const alg = { name: 'ECDSA', namedCurve: 'P-256', hash: 'SHA-256' } as const;
-  const keys = await webcrypto.subtle.generateKey(alg, false, ['sign', 'verify']);
-
-  const now = new Date();
-  const tomorrow = new Date(now.getTime() + 86_400_000);
-
-  const cert = await X509CertificateGenerator.createSelfSigned({
-    serialNumber: '01',
-    name: 'CN=mosaic-issued-test',
-    notBefore: now,
-    notAfter: tomorrow,
-    signingAlgorithm: alg,
-    keys,
-    extensions: [
-      new BasicConstraintsExtension(false),
-      new KeyUsagesExtension(KeyUsageFlags.digitalSignature),
-      // mosaic_grant_id — OID 1.3.6.1.4.1.99999.1
-      new Extension(OID_MOSAIC_GRANT_ID, false, encodeUtf8String(opts.grantId)),
-      // mosaic_subject_user_id — OID 1.3.6.1.4.1.99999.2
-      new Extension(OID_MOSAIC_SUBJECT_USER_ID, false, encodeUtf8String(opts.subjectUserId)),
-    ],
-  });
-
-  return cert.toString('pem');
-}

apps/gateway/src/federation/__tests__/peer-key.spec.ts

@@ -1,63 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { sealClientKey, unsealClientKey } from '../peer-key.util.js';
-
-const TEST_SECRET = 'test-secret-for-peer-key-unit-tests-only';
-
-const TEST_PEM = `-----BEGIN PRIVATE KEY-----
-MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7o4qne60TB3wo
-pCOW8QqstpxEBpnFo37JxLYEJbpE3gUlJajsHv9UWRQ7m5B7n+MBXwTCQqMEY8Wl
-kHv9tGgz1YGwzBjNKxPJXE6pPTXQ1Oa0VB9l3qHdqF5HtZoJzE0c6dO8HJ5YUVL
------END PRIVATE KEY-----`;
-
-let savedSecret: string | undefined;
-
-beforeEach(() => {
-  savedSecret = process.env['BETTER_AUTH_SECRET'];
-  process.env['BETTER_AUTH_SECRET'] = TEST_SECRET;
-});
-
-afterEach(() => {
-  if (savedSecret === undefined) {
-    delete process.env['BETTER_AUTH_SECRET'];
-  } else {
-    process.env['BETTER_AUTH_SECRET'] = savedSecret;
-  }
-});
-
-describe('peer-key seal/unseal', () => {
-  it('round-trip: unsealClientKey(sealClientKey(pem)) returns original pem', () => {
-    const sealed = sealClientKey(TEST_PEM);
-    const roundTripped = unsealClientKey(sealed);
-    expect(roundTripped).toBe(TEST_PEM);
-  });
-
-  it('non-determinism: sealClientKey produces different ciphertext each call', () => {
-    const sealed1 = sealClientKey(TEST_PEM);
-    const sealed2 = sealClientKey(TEST_PEM);
-    expect(sealed1).not.toBe(sealed2);
-  });
-
-  it('at-rest: sealed output does not contain plaintext PEM content', () => {
-    const sealed = sealClientKey(TEST_PEM);
-    expect(sealed).not.toContain('PRIVATE KEY');
-    expect(sealed).not.toContain(
-      'MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7o4qne60TB3wo',
-    );
-  });
-
-  it('tamper: flipping a byte in the sealed payload causes unseal to throw', () => {
-    const sealed = sealClientKey(TEST_PEM);
-    const buf = Buffer.from(sealed, 'base64');
-    // Flip a byte in the middle of the buffer (past IV and authTag)
-    const midpoint = Math.floor(buf.length / 2);
-    buf[midpoint] = buf[midpoint]! ^ 0xff;
-    const tampered = buf.toString('base64');
-    expect(() => unsealClientKey(tampered)).toThrow();
-  });
-
-  it('missing secret: unsealClientKey throws when BETTER_AUTH_SECRET is unset', () => {
-    const sealed = sealClientKey(TEST_PEM);
-    delete process.env['BETTER_AUTH_SECRET'];
-    expect(() => unsealClientKey(sealed)).toThrow('BETTER_AUTH_SECRET is not set');
-  });
-});

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

@@ -20,10 +20,9 @@
  */
 
 import 'reflect-metadata';
-import { describe, it, expect, vi, beforeEach, beforeAll, type Mock } from 'vitest';
+import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
 import { jwtVerify, exportJWK, generateKeyPair } from 'jose';
 import { Pkcs10CertificateRequestGenerator } from '@peculiar/x509';
-import { makeMosaicIssuedCert } from './__tests__/helpers/test-cert.js';
 
 // ---------------------------------------------------------------------------
 // Mock node:https BEFORE importing CaService so the mock is in place when
@@ -75,11 +74,6 @@ const FAKE_CA_PEM = FAKE_CERT_PEM;
 const GRANT_ID = 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11';
 const SUBJECT_USER_ID = 'b1ffcd00-0d1c-5f09-cc7e-7cc0ce491b22';
 
-// Real self-signed cert containing both Mosaic OID extensions — populated in beforeAll.
-// Required because CaService.issueCert performs CRIT-1 OID presence/value checks on the
-// response cert (PR #501 — strict parsing, no silent fallback).
-let realIssuedCertPem: string;
-
 // ---------------------------------------------------------------------------
 // Generate a real EC P-256 key pair and CSR for integration-style tests
 // ---------------------------------------------------------------------------
@@ -200,15 +194,6 @@ function makeHttpsMock(statusCode: number, body: unknown, errorMsg?: string): vo
 describe('CaService', () => {
   let service: CaService;
 
-  beforeAll(async () => {
-    // Generate a cert with the two Mosaic OIDs so that CaService.issueCert's
-    // CRIT-1 OID checks pass when mock step-ca returns it as `crt`.
-    realIssuedCertPem = await makeMosaicIssuedCert({
-      grantId: GRANT_ID,
-      subjectUserId: SUBJECT_USER_ID,
-    });
-  });
-
   beforeEach(() => {
     vi.clearAllMocks();
     service = new CaService();
@@ -241,9 +226,9 @@ describe('CaService', () => {
 
     // Now test that the service's validateCsr accepts it.
     // We call it indirectly via issueCert with a successful mock.
-    makeHttpsMock(200, { crt: realIssuedCertPem, certChain: [realIssuedCertPem, FAKE_CA_PEM] });
+    makeHttpsMock(200, { crt: FAKE_CERT_PEM, certChain: [FAKE_CERT_PEM, FAKE_CA_PEM] });
     const result = await service.issueCert(makeReq({ csrPem: realCsrPem }));
-    expect(result.certPem).toBe(realIssuedCertPem);
+    expect(result.certPem).toBe(FAKE_CERT_PEM);
   });
 
   it('throws INVALID_CSR for a malformed PEM-shaped CSR', async () => {
@@ -266,14 +251,14 @@ describe('CaService', () => {
   it('returns IssuedCertDto on success (certChain present)', async () => {
     if (!realCsrPem) realCsrPem = await generateRealCsr();
     makeHttpsMock(200, {
-      crt: realIssuedCertPem,
+      crt: FAKE_CERT_PEM,
-      certChain: [realIssuedCertPem, FAKE_CA_PEM],
+      certChain: [FAKE_CERT_PEM, FAKE_CA_PEM],
     });
 
     const result = await service.issueCert(makeReq());
 
-    expect(result.certPem).toBe(realIssuedCertPem);
+    expect(result.certPem).toBe(FAKE_CERT_PEM);
-    expect(result.certChainPem).toContain(realIssuedCertPem);
+    expect(result.certChainPem).toContain(FAKE_CERT_PEM);
     expect(result.certChainPem).toContain(FAKE_CA_PEM);
     expect(typeof result.serialNumber).toBe('string');
   });
@@ -285,14 +270,14 @@ describe('CaService', () => {
   it('builds certChainPem from crt+ca when certChain is absent', async () => {
     if (!realCsrPem) realCsrPem = await generateRealCsr();
     makeHttpsMock(200, {
-      crt: realIssuedCertPem,
+      crt: FAKE_CERT_PEM,
       ca: FAKE_CA_PEM,
     });
 
     const result = await service.issueCert(makeReq());
 
-    expect(result.certPem).toBe(realIssuedCertPem);
+    expect(result.certPem).toBe(FAKE_CERT_PEM);
-    expect(result.certChainPem).toContain(realIssuedCertPem);
+    expect(result.certChainPem).toContain(FAKE_CERT_PEM);
     expect(result.certChainPem).toContain(FAKE_CA_PEM);
   });
 
@@ -302,12 +287,12 @@ describe('CaService', () => {
 
   it('falls back to certPem alone when certChain and ca are absent', async () => {
     if (!realCsrPem) realCsrPem = await generateRealCsr();
-    makeHttpsMock(200, { crt: realIssuedCertPem });
+    makeHttpsMock(200, { crt: FAKE_CERT_PEM });
 
     const result = await service.issueCert(makeReq());
 
-    expect(result.certPem).toBe(realIssuedCertPem);
+    expect(result.certPem).toBe(FAKE_CERT_PEM);
-    expect(result.certChainPem).toBe(realIssuedCertPem);
+    expect(result.certChainPem).toBe(FAKE_CERT_PEM);
   });
 
   // -------------------------------------------------------------------------
@@ -413,7 +398,7 @@ describe('CaService', () => {
           statusCode: 200,
           on: (event: string, cb: (chunk?: Buffer) => void) => {
             if (event === 'data') {
-              cb(Buffer.from(JSON.stringify({ crt: realIssuedCertPem })));
+              cb(Buffer.from(JSON.stringify({ crt: FAKE_CERT_PEM })));
             }
             if (event === 'end') {
               cb();
@@ -570,7 +555,7 @@ describe('CaService', () => {
           statusCode: 200,
           on: (event: string, cb: (chunk?: Buffer) => void) => {
             if (event === 'data') {
-              cb(Buffer.from(JSON.stringify({ crt: realIssuedCertPem })));
+              cb(Buffer.from(JSON.stringify({ crt: FAKE_CERT_PEM })));
             }
             if (event === 'end') {
               cb();

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, X509Certificate } from '@peculiar/x509';
+import { Pkcs10CertificateRequest } from '@peculiar/x509';
 import type { IssueCertRequestDto } from './ca.dto.js';
 import { IssuedCertDto } from './ca.dto.js';
 
@@ -624,51 +624,6 @@ 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/client/__tests__/federation-client.service.spec.ts

@@ -1,553 +0,0 @@
-/**
- * Unit tests for FederationClientService (FED-M3-08).
- *
- * HTTP mocking strategy:
- *   undici MockAgent is used to intercept outbound HTTP requests.  The service
- *   uses `undici.fetch` with a `dispatcher` option, so MockAgent is set as the
- *   global dispatcher and all requests flow through it.
- *
- *   Because the service builds one `undici.Agent` per peer and passes it as
- *   the dispatcher on every fetch call, we cannot intercept at the Agent level
- *   in unit tests without significant refactoring.  Instead, we set the global
- *   dispatcher to a MockAgent and override the service's `doRequest` indirection
- *   by spying on the internal fetch call.
- *
- *   For the cert/key wiring, we use the real `sealClientKey` function from
- *   peer-key.util.ts with a test secret — no stubs.
- *
- * Sealed-key setup:
- *   Each test (or beforeAll) calls `sealClientKey(TEST_PRIVATE_KEY_PEM)` with
- *   BETTER_AUTH_SECRET set to a deterministic test value so that
- *   `unsealClientKey` in the service recovers the original PEM.
- */
-
-import 'reflect-metadata';
-import { describe, it, expect, vi, beforeEach, afterEach, beforeAll, afterAll } from 'vitest';
-import { MockAgent, setGlobalDispatcher, getGlobalDispatcher } from 'undici';
-import type { Dispatcher } from 'undici';
-import { writeFileSync, unlinkSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import type { Db } from '@mosaicstack/db';
-import { FederationClientService, FederationClientError } from '../federation-client.service.js';
-import { sealClientKey } from '../../peer-key.util.js';
-
-// ---------------------------------------------------------------------------
-// Test constants
-// ---------------------------------------------------------------------------
-
-const TEST_SECRET = 'test-secret-for-federation-client-spec-only';
-const PEER_ID = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
-const ENDPOINT = 'https://peer.example.com';
-
-// Minimal valid RSA/EC private key PEM — does NOT need to be a real key for
-// unit tests because we only verify it round-trips through seal/unseal, not
-// that it actually negotiates TLS (MockAgent handles that).
-const TEST_PRIVATE_KEY_PEM = `-----BEGIN PRIVATE KEY-----
-MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDummyKeyForTests
------END PRIVATE KEY-----`;
-
-// Minimal self-signed cert PEM (dummy — only used for mTLS Agent construction)
-const TEST_CERT_PEM = `-----BEGIN CERTIFICATE-----
-MIIBdummyCertForFederationClientTests==
------END CERTIFICATE-----`;
-
-const TEST_CERT_SERIAL = 'ABCDEF1234567890';
-
-// ---------------------------------------------------------------------------
-// Sealed key (computed once in beforeAll)
-// ---------------------------------------------------------------------------
-
-let SEALED_KEY: string;
-
-// Path to a stub Step-CA root cert file written in beforeAll. The cert is never
-// actually used to negotiate TLS in unit tests (MockAgent + spy on resolveEntry
-// short-circuit the network), but loadStepCaRoot() requires the file to exist.
-const STUB_CA_PEM_PATH = join(tmpdir(), 'federation-client-spec-ca.pem');
-const STUB_CA_PEM = `-----BEGIN CERTIFICATE-----
-MIIBdummyCAforFederationClientSpecOnly==
------END CERTIFICATE-----
-`;
-
-// ---------------------------------------------------------------------------
-// Peer row factory
-// ---------------------------------------------------------------------------
-
-function makePeerRow(overrides: Partial<Record<string, unknown>> = {}) {
-  return {
-    id: PEER_ID,
-    commonName: 'peer-example-com',
-    displayName: 'Test Peer',
-    certPem: TEST_CERT_PEM,
-    certSerial: TEST_CERT_SERIAL,
-    certNotAfter: new Date('2030-01-01T00:00:00Z'),
-    clientKeyPem: SEALED_KEY,
-    state: 'active' as const,
-    endpointUrl: ENDPOINT,
-    lastSeenAt: null,
-    createdAt: new Date('2026-01-01T00:00:00Z'),
-    revokedAt: null,
-    ...overrides,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Mock DB builder
-// ---------------------------------------------------------------------------
-
-function makeDb(selectRows: unknown[] = [makePeerRow()]): Db {
-  const limitSelect = vi.fn().mockResolvedValue(selectRows);
-  const whereSelect = vi.fn().mockReturnValue({ limit: limitSelect });
-  const fromSelect = vi.fn().mockReturnValue({ where: whereSelect });
-  const selectMock = vi.fn().mockReturnValue({ from: fromSelect });
-
-  return {
-    select: selectMock,
-    insert: vi.fn(),
-    update: vi.fn(),
-    delete: vi.fn(),
-    transaction: vi.fn(),
-  } as unknown as Db;
-}
-
-// ---------------------------------------------------------------------------
-// Helpers for MockAgent HTTP interception
-// ---------------------------------------------------------------------------
-
-/**
- * Create a MockAgent + MockPool for the peer endpoint, set it as the global
- * dispatcher, and return both for per-test configuration.
- */
-function makeMockAgent() {
-  const mockAgent = new MockAgent({ connections: 1 });
-  mockAgent.disableNetConnect();
-  setGlobalDispatcher(mockAgent);
-  const pool = mockAgent.get(ENDPOINT);
-  return { mockAgent, pool };
-}
-
-/**
- * Build a FederationClientService with a mock DB and a spy on the internal
- * fetch so we can intercept at the HTTP layer via MockAgent.
- *
- * The service calls `fetch(url, { dispatcher: agent })` where `agent` is the
- * mTLS undici.Agent built from the peer's cert+key.  To make MockAgent work,
- * we need the fetch dispatcher to be the MockAgent, not the per-peer Agent.
- *
- * Strategy: we replace the private `resolveEntry` result's `agent` field with
- * the MockAgent's pool, so fetch uses our interceptor.  We do this by spying
- * on `resolveEntry` and returning a controlled entry.
- */
-function makeService(db: Db, mockPool: Dispatcher): FederationClientService {
-  const svc = new FederationClientService(db);
-
-  // Override resolveEntry to inject MockAgent pool as the dispatcher
-  vi.spyOn(
-    svc as unknown as { resolveEntry: (peerId: string) => Promise<unknown> },
-    'resolveEntry',
-  ).mockImplementation(async (_peerId: string) => {
-    // Still call DB (via the real logic) to exercise peer validation,
-    // but return mock pool as the agent.
-    // For simplicity in unit tests, directly return a controlled entry.
-    return {
-      agent: mockPool,
-      endpointUrl: ENDPOINT,
-      certPem: TEST_CERT_PEM,
-      certSerial: TEST_CERT_SERIAL,
-    };
-  });
-
-  return svc;
-}
-
-// ---------------------------------------------------------------------------
-// Test setup
-// ---------------------------------------------------------------------------
-
-let originalDispatcher: Dispatcher;
-
-beforeAll(() => {
-  // Seal the test key once — requires BETTER_AUTH_SECRET
-  const saved = process.env['BETTER_AUTH_SECRET'];
-  process.env['BETTER_AUTH_SECRET'] = TEST_SECRET;
-  try {
-    SEALED_KEY = sealClientKey(TEST_PRIVATE_KEY_PEM);
-  } finally {
-    if (saved === undefined) {
-      delete process.env['BETTER_AUTH_SECRET'];
-    } else {
-      process.env['BETTER_AUTH_SECRET'] = saved;
-    }
-  }
-  writeFileSync(STUB_CA_PEM_PATH, STUB_CA_PEM, 'utf8');
-});
-
-afterAll(() => {
-  try {
-    unlinkSync(STUB_CA_PEM_PATH);
-  } catch {
-    // best-effort cleanup
-  }
-});
-
-beforeEach(() => {
-  originalDispatcher = getGlobalDispatcher();
-  process.env['BETTER_AUTH_SECRET'] = TEST_SECRET;
-  process.env['STEP_CA_ROOT_CERT_PATH'] = STUB_CA_PEM_PATH;
-});
-
-afterEach(() => {
-  setGlobalDispatcher(originalDispatcher);
-  vi.restoreAllMocks();
-  delete process.env['BETTER_AUTH_SECRET'];
-  delete process.env['STEP_CA_ROOT_CERT_PATH'];
-});
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/** Successful list response body */
-const LIST_BODY = {
-  items: [{ id: '1', title: 'Task One' }],
-  nextCursor: undefined,
-  _partial: false,
-};
-
-/** Successful get response body */
-const GET_BODY = {
-  item: { id: '1', title: 'Task One' },
-  _partial: false,
-};
-
-/** Successful capabilities response body */
-const CAP_BODY = {
-  resources: ['tasks'],
-  excluded_resources: [],
-  max_rows_per_query: 100,
-  supported_verbs: ['list', 'get', 'capabilities'] as const,
-};
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-
-describe('FederationClientService', () => {
-  // ─── Successful verb calls ─────────────────────────────────────────────────
-
-  describe('list()', () => {
-    it('returns parsed typed response on success', async () => {
-      const db = makeDb();
-      const { mockAgent, pool } = makeMockAgent();
-      const svc = makeService(db, pool);
-
-      pool
-        .intercept({
-          path: '/api/federation/v1/list/tasks',
-          method: 'POST',
-        })
-        .reply(200, LIST_BODY, { headers: { 'content-type': 'application/json' } });
-
-      const result = await svc.list(PEER_ID, 'tasks', {});
-
-      expect(result.items).toHaveLength(1);
-      expect(result.items[0]).toMatchObject({ id: '1', title: 'Task One' });
-
-      await mockAgent.close();
-    });
-  });
-
-  describe('get()', () => {
-    it('returns parsed typed response on success', async () => {
-      const db = makeDb();
-      const { mockAgent, pool } = makeMockAgent();
-      const svc = makeService(db, pool);
-
-      pool
-        .intercept({
-          path: '/api/federation/v1/get/tasks/1',
-          method: 'POST',
-        })
-        .reply(200, GET_BODY, { headers: { 'content-type': 'application/json' } });
-
-      const result = await svc.get(PEER_ID, 'tasks', '1', {});
-
-      expect(result.item).toMatchObject({ id: '1', title: 'Task One' });
-
-      await mockAgent.close();
-    });
-  });
-
-  describe('capabilities()', () => {
-    it('returns parsed capabilities response on success', async () => {
-      const db = makeDb();
-      const { mockAgent, pool } = makeMockAgent();
-      const svc = makeService(db, pool);
-
-      pool
-        .intercept({
-          path: '/api/federation/v1/capabilities',
-          method: 'GET',
-        })
-        .reply(200, CAP_BODY, { headers: { 'content-type': 'application/json' } });
-
-      const result = await svc.capabilities(PEER_ID);
-
-      expect(result.resources).toContain('tasks');
-      expect(result.max_rows_per_query).toBe(100);
-
-      await mockAgent.close();
-    });
-  });
-
-  // ─── HTTP error surfaces ──────────────────────────────────────────────────
-
-  describe('non-2xx responses', () => {
-    it('surfaces 403 as FederationClientError({ status: 403, code: "FORBIDDEN" })', async () => {
-      const db = makeDb();
-      const { mockAgent, pool } = makeMockAgent();
-      const svc = makeService(db, pool);
-
-      pool.intercept({ path: '/api/federation/v1/list/tasks', method: 'POST' }).reply(
-        403,
-        { error: { code: 'forbidden', message: 'Access denied' } },
-        {
-          headers: { 'content-type': 'application/json' },
-        },
-      );
-
-      await expect(svc.list(PEER_ID, 'tasks', {})).rejects.toMatchObject({
-        status: 403,
-        code: 'FORBIDDEN',
-        peerId: PEER_ID,
-      });
-
-      await mockAgent.close();
-    });
-
-    it('surfaces 404 as FederationClientError({ status: 404, code: "HTTP_404" })', async () => {
-      const db = makeDb();
-      const { mockAgent, pool } = makeMockAgent();
-      const svc = makeService(db, pool);
-
-      pool.intercept({ path: '/api/federation/v1/get/tasks/999', method: 'POST' }).reply(
-        404,
-        { error: { code: 'not_found', message: 'Not found' } },
-        {
-          headers: { 'content-type': 'application/json' },
-        },
-      );
-
-      await expect(svc.get(PEER_ID, 'tasks', '999', {})).rejects.toMatchObject({
-        status: 404,
-        code: 'HTTP_404',
-        peerId: PEER_ID,
-      });
-
-      await mockAgent.close();
-    });
-  });
-
-  // ─── Network error ─────────────────────────────────────────────────────────
-
-  describe('network errors', () => {
-    it('surfaces network error as FederationClientError({ code: "NETWORK" })', async () => {
-      const db = makeDb();
-      const { mockAgent, pool } = makeMockAgent();
-      const svc = makeService(db, pool);
-
-      pool
-        .intercept({ path: '/api/federation/v1/capabilities', method: 'GET' })
-        .replyWithError(new Error('ECONNREFUSED'));
-
-      await expect(svc.capabilities(PEER_ID)).rejects.toMatchObject({
-        code: 'NETWORK',
-        peerId: PEER_ID,
-      });
-
-      await mockAgent.close();
-    });
-  });
-
-  // ─── Invalid response body ─────────────────────────────────────────────────
-
-  describe('invalid response body', () => {
-    it('surfaces as FederationClientError({ code: "INVALID_RESPONSE" }) when body shape is wrong', async () => {
-      const db = makeDb();
-      const { mockAgent, pool } = makeMockAgent();
-      const svc = makeService(db, pool);
-
-      // capabilities returns wrong shape (missing required fields)
-      pool
-        .intercept({ path: '/api/federation/v1/capabilities', method: 'GET' })
-        .reply(200, { totally: 'wrong' }, { headers: { 'content-type': 'application/json' } });
-
-      await expect(svc.capabilities(PEER_ID)).rejects.toMatchObject({
-        code: 'INVALID_RESPONSE',
-        peerId: PEER_ID,
-      });
-
-      await mockAgent.close();
-    });
-  });
-
-  // ─── Peer DB validation ────────────────────────────────────────────────────
-
-  describe('peer validation (without resolveEntry spy)', () => {
-    /**
-     * These tests exercise the real `resolveEntry` path — no spy on resolveEntry.
-     */
-
-    it('throws PEER_NOT_FOUND when peer is not in DB', async () => {
-      // DB returns empty array (peer not found)
-      const db = makeDb([]);
-      const svc = new FederationClientService(db);
-
-      await expect(svc.capabilities(PEER_ID)).rejects.toMatchObject({
-        code: 'PEER_NOT_FOUND',
-        peerId: PEER_ID,
-      });
-    });
-
-    it('throws PEER_INACTIVE when peer state is not "active"', async () => {
-      const db = makeDb([makePeerRow({ state: 'suspended' })]);
-      const svc = new FederationClientService(db);
-
-      await expect(svc.capabilities(PEER_ID)).rejects.toMatchObject({
-        code: 'PEER_INACTIVE',
-        peerId: PEER_ID,
-      });
-    });
-  });
-
-  // ─── Cache behaviour ───────────────────────────────────────────────────────
-
-  describe('cache behaviour', () => {
-    it('hits cache on second call — only one DB lookup happens', async () => {
-      // Verify cache by calling the private resolveEntry directly twice and
-      // asserting the DB was queried only once. This avoids the HTTP layer,
-      // which would require either a real network or per-peer Agent rewiring
-      // that the cache invariant doesn't depend on.
-      const db = makeDb();
-      const selectSpy = vi.spyOn(db, 'select');
-      const svc = new FederationClientService(db);
-      const resolveEntry = (
-        svc as unknown as { resolveEntry: (peerId: string) => Promise<unknown> }
-      ).resolveEntry.bind(svc);
-
-      const first = await resolveEntry(PEER_ID);
-      const second = await resolveEntry(PEER_ID);
-
-      expect(first).toBe(second);
-      expect(selectSpy).toHaveBeenCalledTimes(1);
-    });
-
-    it('serializes concurrent resolveEntry calls — only one DB lookup', async () => {
-      const db = makeDb();
-      const selectSpy = vi.spyOn(db, 'select');
-      const svc = new FederationClientService(db);
-      const resolveEntry = (
-        svc as unknown as {
-          resolveEntry: (peerId: string) => Promise<unknown>;
-        }
-      ).resolveEntry.bind(svc);
-
-      const [a, b] = await Promise.all([resolveEntry(PEER_ID), resolveEntry(PEER_ID)]);
-      expect(a).toBe(b);
-      expect(selectSpy).toHaveBeenCalledTimes(1);
-    });
-
-    it('flushPeer destroys the evicted Agent so old TLS connections close', async () => {
-      const db = makeDb();
-      const svc = new FederationClientService(db);
-      const resolveEntry = (
-        svc as unknown as {
-          resolveEntry: (peerId: string) => Promise<{ agent: { destroy: () => Promise<void> } }>;
-        }
-      ).resolveEntry.bind(svc);
-
-      const entry = await resolveEntry(PEER_ID);
-      const destroySpy = vi.spyOn(entry.agent, 'destroy').mockResolvedValue();
-
-      svc.flushPeer(PEER_ID);
-      expect(destroySpy).toHaveBeenCalledTimes(1);
-    });
-
-    it('flushPeer() invalidates cache — next call re-reads DB', async () => {
-      const db = makeDb();
-      const { mockAgent, pool } = makeMockAgent();
-      const svc = makeService(db, pool);
-
-      pool
-        .intercept({ path: '/api/federation/v1/capabilities', method: 'GET' })
-        .reply(200, CAP_BODY, { headers: { 'content-type': 'application/json' } })
-        .times(2);
-
-      // First call — populates cache (via mock resolveEntry)
-      await svc.capabilities(PEER_ID);
-
-      // Flush the cache
-      svc.flushPeer(PEER_ID);
-
-      // The spy on resolveEntry is still active — check it's called again after flush
-      const resolveEntrySpy = vi.spyOn(
-        svc as unknown as { resolveEntry: (peerId: string) => Promise<unknown> },
-        'resolveEntry',
-      );
-
-      // Second call after flush — should call resolveEntry again
-      await svc.capabilities(PEER_ID);
-
-      // resolveEntry should have been called once after we started spying (post-flush)
-      expect(resolveEntrySpy).toHaveBeenCalledTimes(1);
-
-      await mockAgent.close();
-    });
-  });
-
-  // ─── loadStepCaRoot env-var guard ─────────────────────────────────────────
-
-  describe('loadStepCaRoot() env-var guard', () => {
-    it('throws PEER_MISCONFIGURED when STEP_CA_ROOT_CERT_PATH is not set', async () => {
-      delete process.env['STEP_CA_ROOT_CERT_PATH'];
-      const db = makeDb();
-      const svc = new FederationClientService(db);
-      const resolveEntry = (
-        svc as unknown as {
-          resolveEntry: (peerId: string) => Promise<unknown>;
-        }
-      ).resolveEntry.bind(svc);
-
-      await expect(resolveEntry(PEER_ID)).rejects.toMatchObject({
-        code: 'PEER_MISCONFIGURED',
-      });
-    });
-  });
-
-  // ─── FederationClientError class ──────────────────────────────────────────
-
-  describe('FederationClientError', () => {
-    it('is instanceof Error and FederationClientError', () => {
-      const err = new FederationClientError({
-        code: 'PEER_NOT_FOUND',
-        message: 'test',
-        peerId: PEER_ID,
-      });
-      expect(err).toBeInstanceOf(Error);
-      expect(err).toBeInstanceOf(FederationClientError);
-      expect(err.name).toBe('FederationClientError');
-    });
-
-    it('carries status, code, and peerId', () => {
-      const err = new FederationClientError({
-        status: 403,
-        code: 'FORBIDDEN',
-        message: 'forbidden',
-        peerId: PEER_ID,
-      });
-      expect(err.status).toBe(403);
-      expect(err.code).toBe('FORBIDDEN');
-      expect(err.peerId).toBe(PEER_ID);
-    });
-  });
-});

apps/gateway/src/federation/client/federation-client.service.ts

@@ -1,500 +0,0 @@
-/**
- * FederationClientService — outbound mTLS client for federation requests (FED-M3-08).
- *
- * Dials peer gateways over mTLS using the cert+sealed-key stored in `federation_peers`,
- * invokes federation verbs (list / get / capabilities), and surfaces all failure modes
- * as typed `FederationClientError` instances.
- *
- * ## Error code taxonomy
- *
- * | Code               | When                                                          |
- * | ------------------ | ------------------------------------------------------------- |
- * | PEER_NOT_FOUND     | No row in federation_peers for the given peerId               |
- * | PEER_INACTIVE      | Peer row exists but state !== 'active'                        |
- * | PEER_MISCONFIGURED | Peer row is active but missing endpointUrl or clientKeyPem    |
- * | NETWORK            | undici threw a connection / TLS / timeout error               |
- * | HTTP_{status}      | Peer returned a non-2xx response (e.g. HTTP_403, HTTP_404)    |
- * | FORBIDDEN          | Peer returned 403 (convenience alias alongside HTTP_403)      |
- * | INVALID_RESPONSE   | Response body failed Zod schema validation                    |
- *
- * ## Cache strategy
- *
- * Per-peer `undici.Agent` instances are cached in a `Map<peerId, AgentCacheEntry>` for
- * the lifetime of the service instance.  The cache is keyed on peerId (UUID).
- *
- * Cache invalidation:
- *  - `flushPeer(peerId)` — removes the entry immediately.  M5/M6 MUST call this on
- *    cert rotation or peer revocation events so the next request re-reads the DB and
- *    builds a fresh TLS Agent with the new cert material.
- *  - On cache miss: re-reads the DB, checks state === 'active', rebuilds Agent.
- *
- * Cache does NOT auto-expire.  The service is expected to be a singleton scoped to the
- * NestJS application lifecycle; flushing on revocation/rotation is the only invalidation
- * path by design (avoids redundant DB round-trips on the hot path).
- */
-
-import { Injectable, Inject, Logger } from '@nestjs/common';
-import { readFileSync } from 'node:fs';
-import { Agent, fetch as undiciFetch } from 'undici';
-import type { Dispatcher } from 'undici';
-import { z } from 'zod';
-import { type Db, eq, federationPeers } from '@mosaicstack/db';
-import {
-  FederationListResponseSchema,
-  FederationGetResponseSchema,
-  FederationCapabilitiesResponseSchema,
-  FederationErrorEnvelopeSchema,
-  type FederationListResponse,
-  type FederationGetResponse,
-  type FederationCapabilitiesResponse,
-} from '@mosaicstack/types';
-import { DB } from '../../database/database.module.js';
-import { unsealClientKey } from '../peer-key.util.js';
-
-// ---------------------------------------------------------------------------
-// Error taxonomy
-// ---------------------------------------------------------------------------
-
-/**
- * Client-side error code set.  Distinct from the server-side `FederationErrorCode`
- * (which lives in `@mosaicstack/types`) because the client has additional failure
- * modes (PEER_NOT_FOUND, PEER_INACTIVE, PEER_MISCONFIGURED, NETWORK) that the
- * server never emits.
- */
-export type FederationClientErrorCode =
-  | 'PEER_NOT_FOUND'
-  | 'PEER_INACTIVE'
-  | 'PEER_MISCONFIGURED'
-  | 'NETWORK'
-  | 'FORBIDDEN'
-  | 'INVALID_RESPONSE'
-  | `HTTP_${number}`;
-
-export interface FederationClientErrorOptions {
-  status?: number;
-  code: FederationClientErrorCode;
-  message: string;
-  peerId: string;
-  cause?: unknown;
-}
-
-/**
- * Thrown by FederationClientService on every failure path.
- * Callers can dispatch on `error.code` for programmatic handling.
- */
-export class FederationClientError extends Error {
-  readonly status?: number;
-  readonly code: FederationClientErrorCode;
-  readonly peerId: string;
-  readonly cause?: unknown;
-
-  constructor(opts: FederationClientErrorOptions) {
-    super(opts.message);
-    this.name = 'FederationClientError';
-    this.status = opts.status;
-    this.code = opts.code;
-    this.peerId = opts.peerId;
-    this.cause = opts.cause;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Internal cache types
-// ---------------------------------------------------------------------------
-
-interface AgentCacheEntry {
-  agent: Agent;
-  endpointUrl: string;
-  certPem: string;
-  certSerial: string;
-}
-
-// ---------------------------------------------------------------------------
-// Service
-// ---------------------------------------------------------------------------
-
-@Injectable()
-export class FederationClientService {
-  private readonly logger = new Logger(FederationClientService.name);
-
-  /**
-   * Per-peer undici Agent cache.
-   * Key = peerId (UUID string).
-   *
-   * Values are either a resolved `AgentCacheEntry` or an in-flight
-   * `Promise<AgentCacheEntry>` (promise-cache pattern).  Storing the promise
-   * prevents duplicate DB lookups and duplicate key-unseal operations when two
-   * requests for the same peer arrive before the first build completes.
-   *
-   * Flush via `flushPeer(peerId)` on cert rotation / peer revocation (M5/M6).
-   */
-  private readonly cache = new Map<string, AgentCacheEntry | Promise<AgentCacheEntry>>();
-
-  /**
-   * Step-CA root cert PEM, loaded once from `STEP_CA_ROOT_CERT_PATH`.
-   * Used as the trust anchor for peer server certificates so federation TLS is
-   * pinned to our PKI, not the public trust store. Lazily loaded on first use
-   * so unit tests that don't exercise the agent path can run without the env var.
-   */
-  private cachedCaPem: string | null = null;
-
-  constructor(@Inject(DB) private readonly db: Db) {}
-
-  // -------------------------------------------------------------------------
-  // Public verb API
-  // -------------------------------------------------------------------------
-
-  /**
-   * Invoke the `list` verb on a remote peer.
-   *
-   * @param peerId   UUID of the peer row in `federation_peers`.
-   * @param resource Resource path, e.g. "tasks".
-   * @param request  Free-form body sent as JSON in the POST body.
-   * @returns Parsed `FederationListResponse<T>`.
-   */
-  async list<T>(
-    peerId: string,
-    resource: string,
-    request: Record<string, unknown>,
-  ): Promise<FederationListResponse<T>> {
-    const { endpointUrl, agent } = await this.resolveEntry(peerId);
-    const url = `${endpointUrl}/api/federation/v1/list/${encodeURIComponent(resource)}`;
-    const body = await this.doPost(peerId, url, agent, request);
-    return this.parseWith<FederationListResponse<T>>(
-      peerId,
-      body,
-      FederationListResponseSchema(z.unknown()),
-    );
-  }
-
-  /**
-   * Invoke the `get` verb on a remote peer.
-   *
-   * @param peerId   UUID of the peer row in `federation_peers`.
-   * @param resource Resource path, e.g. "tasks".
-   * @param id       Resource identifier.
-   * @param request  Free-form body sent as JSON in the POST body.
-   * @returns Parsed `FederationGetResponse<T>`.
-   */
-  async get<T>(
-    peerId: string,
-    resource: string,
-    id: string,
-    request: Record<string, unknown>,
-  ): Promise<FederationGetResponse<T>> {
-    const { endpointUrl, agent } = await this.resolveEntry(peerId);
-    const url = `${endpointUrl}/api/federation/v1/get/${encodeURIComponent(resource)}/${encodeURIComponent(id)}`;
-    const body = await this.doPost(peerId, url, agent, request);
-    return this.parseWith<FederationGetResponse<T>>(
-      peerId,
-      body,
-      FederationGetResponseSchema(z.unknown()),
-    );
-  }
-
-  /**
-   * Invoke the `capabilities` verb on a remote peer.
-   *
-   * @param peerId UUID of the peer row in `federation_peers`.
-   * @returns Parsed `FederationCapabilitiesResponse`.
-   */
-  async capabilities(peerId: string): Promise<FederationCapabilitiesResponse> {
-    const { endpointUrl, agent } = await this.resolveEntry(peerId);
-    const url = `${endpointUrl}/api/federation/v1/capabilities`;
-    const body = await this.doGet(peerId, url, agent);
-    return this.parseWith<FederationCapabilitiesResponse>(
-      peerId,
-      body,
-      FederationCapabilitiesResponseSchema,
-    );
-  }
-
-  // -------------------------------------------------------------------------
-  // Cache management
-  // -------------------------------------------------------------------------
-
-  /**
-   * Flush the cached Agent for a specific peer.
-   *
-   * M5/M6 MUST call this on:
-   *  - cert rotation events (so new cert material is picked up)
-   *  - peer revocation events (so future requests fail at PEER_INACTIVE)
-   *
-   * After flushing, the next call to `list`, `get`, or `capabilities` for
-   * this peer will re-read the DB and rebuild the Agent.
-   */
-  flushPeer(peerId: string): void {
-    const entry = this.cache.get(peerId);
-    if (entry === undefined) {
-      return;
-    }
-    this.cache.delete(peerId);
-    if (!(entry instanceof Promise)) {
-      // best-effort destroy; promise-cached entries skip destroy because
-      // the in-flight build owns its own Agent which will be GC'd when the
-      // owning request handles the rejection from the cache miss
-      entry.agent.destroy().catch(() => {
-        // intentionally ignored — destroy errors are not actionable
-      });
-    }
-    this.logger.log(`Cache flushed for peer ${peerId}`);
-  }
-
-  // -------------------------------------------------------------------------
-  // Internal helpers
-  // -------------------------------------------------------------------------
-
-  /**
-   * Load and cache the Step-CA root cert PEM from `STEP_CA_ROOT_CERT_PATH`.
-   * Throws `FederationClientError` if the env var is unset or the file cannot
-   * be read — mTLS to a peer without a pinned trust anchor would silently
-   * fall back to the public trust store.
-   */
-  private loadStepCaRoot(): string {
-    if (this.cachedCaPem !== null) {
-      return this.cachedCaPem;
-    }
-    const path = process.env['STEP_CA_ROOT_CERT_PATH'];
-    if (!path) {
-      throw new FederationClientError({
-        code: 'PEER_MISCONFIGURED',
-        message: 'STEP_CA_ROOT_CERT_PATH is not set; refusing to dial peer without pinned CA trust',
-        peerId: '',
-      });
-    }
-    try {
-      const pem = readFileSync(path, 'utf8');
-      this.cachedCaPem = pem;
-      return pem;
-    } catch (err) {
-      throw new FederationClientError({
-        code: 'PEER_MISCONFIGURED',
-        message: `Failed to read STEP_CA_ROOT_CERT_PATH (${path})`,
-        peerId: '',
-        cause: err,
-      });
-    }
-  }
-
-  /**
-   * Resolve the cache entry for a peer, reading DB on miss.
-   *
-   * Uses a promise-cache pattern: concurrent callers for the same uncached
-   * `peerId` all `await` the same in-flight `Promise<AgentCacheEntry>` so
-   * only one DB lookup and one key-unseal ever runs per peer per cache miss.
-   * The promise is replaced with the concrete entry on success, or deleted on
-   * rejection so a transient error does not poison the cache permanently.
-   *
-   * Throws `FederationClientError` with appropriate code if the peer is not
-   * found, is inactive, or is missing required fields.
-   */
-  private async resolveEntry(peerId: string): Promise<AgentCacheEntry> {
-    const cached = this.cache.get(peerId);
-    if (cached) {
-      return cached; // Promise or concrete entry — both are awaitable
-    }
-
-    const inflight = this.buildEntry(peerId).then(
-      (entry) => {
-        this.cache.set(peerId, entry); // replace promise with concrete value
-        return entry;
-      },
-      (err: unknown) => {
-        this.cache.delete(peerId); // don't poison the cache with a rejected promise
-        throw err;
-      },
-    );
-
-    this.cache.set(peerId, inflight);
-    return inflight;
-  }
-
-  /**
-   * Build the `AgentCacheEntry` for a peer by reading the DB, validating the
-   * peer's state, unsealing the private key, and constructing the mTLS Agent.
-   *
-   * Throws `FederationClientError` with appropriate code if the peer is not
-   * found, is inactive, or is missing required fields.
-   */
-  private async buildEntry(peerId: string): Promise<AgentCacheEntry> {
-    // DB lookup
-    const [peer] = await this.db
-      .select()
-      .from(federationPeers)
-      .where(eq(federationPeers.id, peerId))
-      .limit(1);
-
-    if (!peer) {
-      throw new FederationClientError({
-        code: 'PEER_NOT_FOUND',
-        message: `Federation peer ${peerId} not found`,
-        peerId,
-      });
-    }
-
-    if (peer.state !== 'active') {
-      throw new FederationClientError({
-        code: 'PEER_INACTIVE',
-        message: `Federation peer ${peerId} is not active (state: ${peer.state})`,
-        peerId,
-      });
-    }
-
-    if (!peer.endpointUrl || !peer.clientKeyPem) {
-      throw new FederationClientError({
-        code: 'PEER_MISCONFIGURED',
-        message: `Federation peer ${peerId} is missing endpointUrl or clientKeyPem`,
-        peerId,
-      });
-    }
-
-    // Unseal the private key
-    let privateKeyPem: string;
-    try {
-      privateKeyPem = unsealClientKey(peer.clientKeyPem);
-    } catch (err) {
-      throw new FederationClientError({
-        code: 'PEER_MISCONFIGURED',
-        message: `Failed to unseal client key for peer ${peerId}`,
-        peerId,
-        cause: err,
-      });
-    }
-
-    // Build mTLS agent — pin trust to Step-CA root so we never accept
-    // a peer cert signed by a public CA (defense against MITM with a
-    // publicly-trusted DV cert for the peer's hostname).
-    const agent = new Agent({
-      connect: {
-        cert: peer.certPem,
-        key: privateKeyPem,
-        ca: this.loadStepCaRoot(),
-        // rejectUnauthorized: true is the undici default for HTTPS
-      },
-    });
-
-    const entry: AgentCacheEntry = {
-      agent,
-      endpointUrl: peer.endpointUrl,
-      certPem: peer.certPem,
-      certSerial: peer.certSerial,
-    };
-
-    this.logger.log(`Agent cached for peer ${peerId} (serial: ${peer.certSerial})`);
-
-    return entry;
-  }
-
-  /**
-   * Execute a POST request with a JSON body.
-   * Returns the parsed response body as an unknown value.
-   * Throws `FederationClientError` on network errors and non-2xx responses.
-   */
-  private async doPost(
-    peerId: string,
-    url: string,
-    agent: Dispatcher,
-    body: Record<string, unknown>,
-  ): Promise<unknown> {
-    return this.doRequest(peerId, url, agent, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(body),
-    });
-  }
-
-  /**
-   * Execute a GET request.
-   * Returns the parsed response body as an unknown value.
-   * Throws `FederationClientError` on network errors and non-2xx responses.
-   */
-  private async doGet(peerId: string, url: string, agent: Dispatcher): Promise<unknown> {
-    return this.doRequest(peerId, url, agent, { method: 'GET' });
-  }
-
-  private async doRequest(
-    peerId: string,
-    url: string,
-    agent: Dispatcher,
-    init: { method: string; headers?: Record<string, string>; body?: string },
-  ): Promise<unknown> {
-    let response: Awaited<ReturnType<typeof undiciFetch>>;
-
-    try {
-      response = await undiciFetch(url, {
-        ...init,
-        dispatcher: agent,
-      });
-    } catch (err) {
-      throw new FederationClientError({
-        code: 'NETWORK',
-        message: `Network error calling peer ${peerId} at ${url}: ${err instanceof Error ? err.message : String(err)}`,
-        peerId,
-        cause: err,
-      });
-    }
-
-    const rawBody = await response.text().catch(() => '');
-
-    if (!response.ok) {
-      const status = response.status;
-
-      // Attempt to parse as federation error envelope
-      let serverMessage = `HTTP ${status}`;
-      try {
-        const json: unknown = JSON.parse(rawBody);
-        const result = FederationErrorEnvelopeSchema.safeParse(json);
-        if (result.success) {
-          serverMessage = result.data.error.message;
-        }
-      } catch {
-        // Not valid JSON or not a federation envelope — use generic message
-      }
-
-      // Specific code for 403 (most actionable for callers); generic HTTP_{n} for others
-      const code: FederationClientErrorCode = status === 403 ? 'FORBIDDEN' : `HTTP_${status}`;
-
-      throw new FederationClientError({
-        status,
-        code,
-        message: `Peer ${peerId} returned ${status}: ${serverMessage}`,
-        peerId,
-      });
-    }
-
-    try {
-      return JSON.parse(rawBody) as unknown;
-    } catch (err) {
-      throw new FederationClientError({
-        code: 'INVALID_RESPONSE',
-        message: `Peer ${peerId} returned non-JSON body`,
-        peerId,
-        cause: err,
-      });
-    }
-  }
-
-  /**
-   * Parse and validate a response body against a Zod schema.
-   *
-   * For list/get, callers pass the result of `FederationListResponseSchema(z.unknown())`
-   * so that the envelope structure is validated without requiring a concrete item schema
-   * at the client level.  The generic `T` provides compile-time typing.
-   *
-   * Throws `FederationClientError({ code: 'INVALID_RESPONSE' })` on parse failure.
-   */
-  private parseWith<T>(peerId: string, body: unknown, schema: z.ZodTypeAny): T {
-    const result = schema.safeParse(body);
-    if (!result.success) {
-      const issues = result.error.issues
-        .map((e: z.ZodIssue) => `[${e.path.join('.') || 'root'}] ${e.message}`)
-        .join('; ');
-      throw new FederationClientError({
-        code: 'INVALID_RESPONSE',
-        message: `Peer ${peerId} returned invalid response shape: ${issues}`,
-        peerId,
-      });
-    }
-    return result.data as T;
-  }
-}

apps/gateway/src/federation/client/index.ts

@@ -1,13 +0,0 @@
-/**
- * Federation client barrel — re-exports for FederationModule consumers.
- *
- * M3-09 (QuerySourceService) and future milestones should import from here,
- * not directly from the implementation file.
- */
-
-export {
-  FederationClientService,
-  FederationClientError,
-  type FederationClientErrorCode,
-  type FederationClientErrorOptions,
-} from './federation-client.service.js';

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

@@ -1,54 +0,0 @@
-/**
- * EnrollmentController — federation enrollment HTTP layer (FED-M2-07).
- *
- * Routes:
- *   POST /api/federation/enrollment/tokens   — admin creates a single-use token
- *   POST /api/federation/enrollment/:token   — unauthenticated; token IS the auth
- */
-
-import {
-  Body,
-  Controller,
-  HttpCode,
-  HttpStatus,
-  Inject,
-  Param,
-  Post,
-  UseGuards,
-} from '@nestjs/common';
-import { AdminGuard } from '../admin/admin.guard.js';
-import { EnrollmentService } from './enrollment.service.js';
-import { CreateEnrollmentTokenDto, RedeemEnrollmentTokenDto } from './enrollment.dto.js';
-
-@Controller('api/federation/enrollment')
-export class EnrollmentController {
-  constructor(@Inject(EnrollmentService) private readonly enrollmentService: EnrollmentService) {}
-
-  /**
-   * Admin-only: generate a single-use enrollment token for a pending grant.
-   * The token should be distributed out-of-band to the remote peer operator.
-   *
-   * POST /api/federation/enrollment/tokens
-   */
-  @Post('tokens')
-  @UseGuards(AdminGuard)
-  @HttpCode(HttpStatus.CREATED)
-  async createToken(@Body() dto: CreateEnrollmentTokenDto) {
-    return this.enrollmentService.createToken(dto);
-  }
-
-  /**
-   * Unauthenticated: remote peer redeems a token by submitting its CSR.
-   * The token itself is the credential — no session or bearer token required.
-   *
-   * POST /api/federation/enrollment/:token
-   *
-   * Returns the signed leaf cert and full chain PEM on success.
-   * Returns 410 Gone if the token was already used or has expired.
-   */
-  @Post(':token')
-  @HttpCode(HttpStatus.OK)
-  async redeem(@Param('token') token: string, @Body() dto: RedeemEnrollmentTokenDto) {
-    return this.enrollmentService.redeem(token, dto.csrPem);
-  }
-}

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

@@ -1,35 +0,0 @@
-/**
- * DTOs for the federation enrollment flow (FED-M2-07).
- *
- * CreateEnrollmentTokenDto  — admin generates a single-use enrollment token
- * RedeemEnrollmentTokenDto  — remote peer submits CSR to redeem the token
- */
-
-import { IsInt, IsNotEmpty, IsOptional, IsString, IsUUID, Max, Min } from 'class-validator';
-
-export class CreateEnrollmentTokenDto {
-  /** UUID of the federation grant this token will activate on redemption. */
-  @IsUUID()
-  grantId!: string;
-
-  /** UUID of the peer record that will receive the issued cert on redemption. */
-  @IsUUID()
-  peerId!: string;
-
-  /**
-   * Token lifetime in seconds. Default 900 (15 min). Min 60. Max 900.
-   * After this time the token is rejected even if unused.
-   */
-  @IsOptional()
-  @IsInt()
-  @Min(60)
-  @Max(900)
-  ttlSeconds: number = 900;
-}
-
-export class RedeemEnrollmentTokenDto {
-  /** PEM-encoded PKCS#10 Certificate Signing Request from the remote peer. */
-  @IsString()
-  @IsNotEmpty()
-  csrPem!: string;
-}

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

@@ -1,281 +0,0 @@
-/**
- * EnrollmentService — single-use enrollment token lifecycle (FED-M2-07).
- *
- * Responsibilities:
- *  1. Generate time-limited single-use enrollment tokens (admin action).
- *  2. Redeem a token: validate → atomically claim token → issue cert via
- *     CaService → transactionally activate grant + update peer + write audit.
- *
- * Replay protection: the token is claimed (UPDATE WHERE used_at IS NULL) BEFORE
- * cert issuance. This prevents double cert minting on concurrent requests.
- * If cert issuance fails after claim, the token is consumed and the grant
- * stays pending — admin must create a new grant.
- */
-
-import {
-  BadRequestException,
-  ConflictException,
-  GoneException,
-  Inject,
-  Injectable,
-  Logger,
-  NotFoundException,
-} from '@nestjs/common';
-import * as crypto from 'node:crypto';
-// X509Certificate is available as a named export in Node.js ≥ 15.6
-const { X509Certificate } = crypto;
-import {
-  type Db,
-  and,
-  eq,
-  isNull,
-  sql,
-  federationEnrollmentTokens,
-  federationGrants,
-  federationPeers,
-  federationAuditLog,
-} from '@mosaicstack/db';
-import { DB } from '../database/database.module.js';
-import { CaService } from './ca.service.js';
-import { GrantsService } from './grants.service.js';
-import { FederationScopeError } from './scope-schema.js';
-import type { CreateEnrollmentTokenDto } from './enrollment.dto.js';
-
-export interface EnrollmentTokenResult {
-  token: string;
-  expiresAt: string;
-}
-
-export interface RedeemResult {
-  certPem: string;
-  certChainPem: string;
-}
-
-@Injectable()
-export class EnrollmentService {
-  private readonly logger = new Logger(EnrollmentService.name);
-
-  constructor(
-    @Inject(DB) private readonly db: Db,
-    private readonly caService: CaService,
-    private readonly grantsService: GrantsService,
-  ) {}
-
-  /**
-   * Generate a single-use enrollment token for an admin to distribute
-   * out-of-band to the remote peer operator.
-   */
-  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);
-
-    await this.db.insert(federationEnrollmentTokens).values({
-      token,
-      grantId: dto.grantId,
-      peerId: dto.peerId,
-      expiresAt,
-    });
-
-    this.logger.log(
-      `Enrollment token created — grantId=${dto.grantId} peerId=${dto.peerId} expiresAt=${expiresAt.toISOString()}`,
-    );
-
-    return { token, expiresAt: expiresAt.toISOString() };
-  }
-
-  /**
-   * Redeem an enrollment token.
-   *
-   * Full flow:
-   *  1. Fetch token row — NotFoundException if not found
-   *  2. usedAt set → GoneException (already used)
-   *  3. expiresAt < now → GoneException (expired)
-   *  4. Load grant — verify status is 'pending'
-   *  5. Atomically claim token (UPDATE WHERE used_at IS NULL RETURNING token)
-   *     — if no rows returned, concurrent request won → GoneException
-   *  6. Issue cert via CaService (network call, outside transaction)
-   *     — if this fails, token is consumed; grant stays pending; admin must recreate
-   *  7. Transaction: activate grant + update peer record + write audit log
-   *  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 [fetchedRow] = await this.db
-        .select()
-        .from(federationEnrollmentTokens)
-        .where(eq(federationEnrollmentTokens.token, token))
-        .limit(1);
-
-      if (!fetchedRow) {
-        throw new NotFoundException('Enrollment token not found');
-      }
-      row = fetchedRow;
-
-      // 2. Already used?
-      if (row.usedAt !== null) {
-        throw new GoneException('Enrollment token has already been used');
-      }
-
-      // 3. Expired?
-      if (row.expiresAt < new Date()) {
-        throw new GoneException('Enrollment token has expired');
-      }
-
-      // 4. Load grant and verify it is still pending
-      let grant;
-      try {
-        grant = await this.grantsService.getGrant(row.grantId);
-      } catch (err) {
-        if (err instanceof FederationScopeError) {
-          throw new BadRequestException(err.message);
-        }
-        throw err;
-      }
-
-      if (grant.status !== 'pending') {
-        throw new GoneException(
-          `Grant ${row.grantId} is no longer pending (status: ${grant.status})`,
-        );
-      }
-
-      // 5. Atomically claim the token BEFORE cert issuance to prevent double-minting.
-      // WHERE used_at IS NULL ensures only one concurrent request wins.
-      // Using .returning() works on both node-postgres and PGlite without rowCount inspection.
-      const claimed = await this.db
-        .update(federationEnrollmentTokens)
-        .set({ usedAt: sql`NOW()` })
-        .where(
-          and(
-            eq(federationEnrollmentTokens.token, token),
-            isNull(federationEnrollmentTokens.usedAt),
-          ),
-        )
-        .returning({ token: federationEnrollmentTokens.token });
-
-      if (claimed.length === 0) {
-        throw new GoneException('Enrollment token has already been used (concurrent request)');
-      }
-
-      // 6. Issue certificate via CaService (network call — outside any transaction).
-      // If this throws, the token is already consumed. The grant stays pending.
-      // Admin must revoke the grant and create a new one.
-      let issued;
-      try {
-        issued = await this.caService.issueCert({
-          csrPem,
-          grantId: row.grantId,
-          subjectUserId: grant.subjectUserId,
-          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.slice(0, 8)}... was claimed — grant ${row.grantId} is stranded pending`,
-          err instanceof Error ? err.stack : String(err),
-        );
-        if (err instanceof FederationScopeError) {
-          throw new BadRequestException((err as Error).message);
-        }
-        throw err;
-      }
-
-      // 7. Atomically activate grant, update peer record, and write audit log.
-      const certNotAfter = this.extractCertNotAfter(issued.certPem);
-      await this.db.transaction(async (tx) => {
-        // CRIT-2: Guard activation with WHERE status='pending' to prevent double-activation.
-        const [activated] = await tx
-          .update(federationGrants)
-          .set({ status: 'active' })
-          .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({
-            certPem: issued.certPem,
-            certSerial: issued.serialNumber,
-            certNotAfter,
-            state: 'active',
-          })
-          .where(and(eq(federationPeers.id, row!.peerId), eq(federationPeers.state, 'pending')));
-
-        await tx.insert(federationAuditLog).values({
-          requestId: crypto.randomUUID(),
-          peerId: row!.peerId,
-          grantId: row!.grantId,
-          verb: 'enrollment',
-          resource: 'federation_grant',
-          statusCode: 200,
-          outcome: 'allowed',
-        });
-      });
-
-      this.logger.log(
-        `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.
-   * HIGH-2: No silent fallback — a cert that cannot be parsed should fail loud.
-   */
-  private extractCertNotAfter(certPem: string): Date {
-    const cert = new X509Certificate(certPem);
-    return new Date(cert.validTo);
-  }
-}

apps/gateway/src/federation/federation-admin.dto.ts

@@ -1,39 +0,0 @@
-/**
- * DTOs for the federation admin controller (FED-M2-08).
- */
-
-import { IsInt, IsNotEmpty, IsOptional, IsString, IsUrl, Max, Min } from 'class-validator';
-
-export class CreatePeerKeypairDto {
-  @IsString()
-  @IsNotEmpty()
-  commonName!: string;
-
-  @IsString()
-  @IsNotEmpty()
-  displayName!: string;
-
-  @IsOptional()
-  @IsUrl()
-  endpointUrl?: string;
-}
-
-export class StorePeerCertDto {
-  @IsString()
-  @IsNotEmpty()
-  certPem!: string;
-}
-
-export class GenerateEnrollmentTokenDto {
-  @IsOptional()
-  @IsInt()
-  @Min(60)
-  @Max(900)
-  ttlSeconds: number = 900;
-}
-
-export class RevokeGrantBodyDto {
-  @IsOptional()
-  @IsString()
-  reason?: string;
-}

apps/gateway/src/federation/federation.controller.ts

@@ -1,266 +0,0 @@
-/**
- * FederationController — admin REST API for federation management (FED-M2-08).
- *
- * Routes (all under /api/admin/federation, all require AdminGuard):
- *
- *   Grant management:
- *     POST   /api/admin/federation/grants
- *     GET    /api/admin/federation/grants
- *     GET    /api/admin/federation/grants/:id
- *     PATCH  /api/admin/federation/grants/:id/revoke
- *     POST   /api/admin/federation/grants/:id/tokens
- *
- *   Peer management:
- *     GET    /api/admin/federation/peers
- *     POST   /api/admin/federation/peers/keypair
- *     PATCH  /api/admin/federation/peers/:id/cert
- *
- * NOTE: The enrollment REDEMPTION endpoint (POST /api/federation/enrollment/:token)
- * is handled by EnrollmentController — not duplicated here.
- */
-
-import {
-  Body,
-  Controller,
-  Get,
-  HttpCode,
-  HttpStatus,
-  Inject,
-  NotFoundException,
-  Param,
-  Patch,
-  Post,
-  Query,
-  UseGuards,
-} from '@nestjs/common';
-import { webcrypto } from 'node:crypto';
-import { X509Certificate } from 'node:crypto';
-import { Pkcs10CertificateRequestGenerator } from '@peculiar/x509';
-import { type Db, eq, federationPeers } from '@mosaicstack/db';
-import { DB } from '../database/database.module.js';
-import { AdminGuard } from '../admin/admin.guard.js';
-import { GrantsService } from './grants.service.js';
-import { EnrollmentService } from './enrollment.service.js';
-import { sealClientKey } from './peer-key.util.js';
-import { CreateGrantDto, ListGrantsDto } from './grants.dto.js';
-import {
-  CreatePeerKeypairDto,
-  GenerateEnrollmentTokenDto,
-  RevokeGrantBodyDto,
-  StorePeerCertDto,
-} from './federation-admin.dto.js';
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Convert an ArrayBuffer to a Base64 string (for PEM encoding).
- */
-function arrayBufferToBase64(buf: ArrayBuffer): string {
-  const bytes = new Uint8Array(buf);
-  let binary = '';
-  for (const b of bytes) {
-    binary += String.fromCharCode(b);
-  }
-  return Buffer.from(binary, 'binary').toString('base64');
-}
-
-/**
- * Wrap a Base64 string in PEM armour.
- */
-function toPem(label: string, b64: string): string {
-  const lines = b64.match(/.{1,64}/g) ?? [];
-  return `-----BEGIN ${label}-----\n${lines.join('\n')}\n-----END ${label}-----\n`;
-}
-
-// ---------------------------------------------------------------------------
-// Controller
-// ---------------------------------------------------------------------------
-
-@Controller('api/admin/federation')
-@UseGuards(AdminGuard)
-export class FederationController {
-  constructor(
-    @Inject(DB) private readonly db: Db,
-    @Inject(GrantsService) private readonly grantsService: GrantsService,
-    @Inject(EnrollmentService) private readonly enrollmentService: EnrollmentService,
-  ) {}
-
-  // ─── Grant management ────────────────────────────────────────────────────
-
-  /**
-   * POST /api/admin/federation/grants
-   * Create a new grant in pending state.
-   */
-  @Post('grants')
-  @HttpCode(HttpStatus.CREATED)
-  async createGrant(@Body() body: CreateGrantDto) {
-    return this.grantsService.createGrant(body);
-  }
-
-  /**
-   * GET /api/admin/federation/grants
-   * List grants with optional filters.
-   */
-  @Get('grants')
-  async listGrants(@Query() query: ListGrantsDto) {
-    return this.grantsService.listGrants(query);
-  }
-
-  /**
-   * GET /api/admin/federation/grants/:id
-   * Get a single grant by ID.
-   */
-  @Get('grants/:id')
-  async getGrant(@Param('id') id: string) {
-    return this.grantsService.getGrant(id);
-  }
-
-  /**
-   * PATCH /api/admin/federation/grants/:id/revoke
-   * Revoke an active grant.
-   */
-  @Patch('grants/:id/revoke')
-  async revokeGrant(@Param('id') id: string, @Body() body: RevokeGrantBodyDto) {
-    return this.grantsService.revokeGrant(id, body.reason);
-  }
-
-  /**
-   * POST /api/admin/federation/grants/:id/tokens
-   * Generate a single-use enrollment token for a pending grant.
-   * Returns the token plus an enrollmentUrl the operator shares out-of-band.
-   */
-  @Post('grants/:id/tokens')
-  @HttpCode(HttpStatus.CREATED)
-  async generateToken(@Param('id') id: string, @Body() body: GenerateEnrollmentTokenDto) {
-    const grant = await this.grantsService.getGrant(id);
-
-    const result = await this.enrollmentService.createToken({
-      grantId: id,
-      peerId: grant.peerId,
-      ttlSeconds: body.ttlSeconds ?? 900,
-    });
-
-    const baseUrl = process.env['BETTER_AUTH_URL'] ?? 'http://localhost:14242';
-    const enrollmentUrl = `${baseUrl}/api/federation/enrollment/${result.token}`;
-
-    return {
-      token: result.token,
-      expiresAt: result.expiresAt,
-      enrollmentUrl,
-    };
-  }
-
-  // ─── Peer management ─────────────────────────────────────────────────────
-
-  /**
-   * GET /api/admin/federation/peers
-   * List all federation peer rows.
-   */
-  @Get('peers')
-  async listPeers() {
-    return this.db.select().from(federationPeers).orderBy(federationPeers.commonName);
-  }
-
-  /**
-   * POST /api/admin/federation/peers/keypair
-   * Generate a new peer entry with EC P-256 key pair and a PKCS#10 CSR.
-   *
-   * Flow:
-   *  1. Generate EC P-256 key pair via webcrypto
-   *  2. Generate a self-signed CSR via @peculiar/x509
-   *  3. Export private key as PEM
-   *  4. sealClientKey(privatePem) → sealed blob
-   *  5. Insert pending peer row
-   *  6. Return { peerId, csrPem }
-   */
-  @Post('peers/keypair')
-  @HttpCode(HttpStatus.CREATED)
-  async createPeerKeypair(@Body() body: CreatePeerKeypairDto) {
-    // 1. Generate EC P-256 key pair via Web Crypto
-    const keyPair = await webcrypto.subtle.generateKey(
-      { name: 'ECDSA', namedCurve: 'P-256' },
-      true, // extractable
-      ['sign', 'verify'],
-    );
-
-    // 2. Generate PKCS#10 CSR
-    const csr = await Pkcs10CertificateRequestGenerator.create({
-      name: `CN=${body.commonName}`,
-      keys: keyPair,
-      signingAlgorithm: { name: 'ECDSA', hash: 'SHA-256' },
-    });
-
-    const csrPem = csr.toString('pem');
-
-    // 3. Export private key as PKCS#8 PEM
-    const pkcs8Der = await webcrypto.subtle.exportKey('pkcs8', keyPair.privateKey);
-    const privatePem = toPem('PRIVATE KEY', arrayBufferToBase64(pkcs8Der));
-
-    // 4. Seal the private key
-    const sealed = sealClientKey(privatePem);
-
-    // 5. Insert pending peer row
-    const [peer] = await this.db
-      .insert(federationPeers)
-      .values({
-        commonName: body.commonName,
-        displayName: body.displayName,
-        certPem: '',
-        certSerial: 'pending',
-        certNotAfter: new Date(0),
-        clientKeyPem: sealed,
-        state: 'pending',
-        endpointUrl: body.endpointUrl,
-      })
-      .returning();
-
-    return {
-      peerId: peer!.id,
-      csrPem,
-    };
-  }
-
-  /**
-   * PATCH /api/admin/federation/peers/:id/cert
-   * Store a signed certificate after enrollment completes.
-   *
-   * Flow:
-   *  1. Parse the cert to extract serial and notAfter
-   *  2. Update the peer row with cert data + state='active'
-   *  3. Return the updated peer row
-   */
-  @Patch('peers/:id/cert')
-  async storePeerCert(@Param('id') id: string, @Body() body: StorePeerCertDto) {
-    // Ensure peer exists
-    const [existing] = await this.db
-      .select({ id: federationPeers.id })
-      .from(federationPeers)
-      .where(eq(federationPeers.id, id))
-      .limit(1);
-
-    if (!existing) {
-      throw new NotFoundException(`Peer ${id} not found`);
-    }
-
-    // 1. Parse cert
-    const x509 = new X509Certificate(body.certPem);
-    const certSerial = x509.serialNumber;
-    const certNotAfter = new Date(x509.validTo);
-
-    // 2. Update peer
-    const [updated] = await this.db
-      .update(federationPeers)
-      .set({
-        certPem: body.certPem,
-        certSerial,
-        certNotAfter,
-        state: 'active',
-      })
-      .where(eq(federationPeers.id, id))
-      .returning();
-
-    return updated;
-  }
-}

apps/gateway/src/federation/federation.module.ts

@@ -1,29 +1,8 @@
 import { Module } from '@nestjs/common';
-import { AdminGuard } from '../admin/admin.guard.js';
 import { CaService } from './ca.service.js';
-import { EnrollmentController } from './enrollment.controller.js';
-import { EnrollmentService } from './enrollment.service.js';
-import { FederationController } from './federation.controller.js';
-import { GrantsService } from './grants.service.js';
-import { FederationClientService } from './client/index.js';
-import { FederationAuthGuard } from './server/index.js';
 
 @Module({
-  controllers: [EnrollmentController, FederationController],
+  providers: [CaService],
-  providers: [
+  exports: [CaService],
-    AdminGuard,
-    CaService,
-    EnrollmentService,
-    GrantsService,
-    FederationClientService,
-    FederationAuthGuard,
-  ],
-  exports: [
-    CaService,
-    EnrollmentService,
-    GrantsService,
-    FederationClientService,
-    FederationAuthGuard,
-  ],
 })
 export class FederationModule {}

apps/gateway/src/federation/grants.dto.ts

@@ -1,36 +0,0 @@
-import { IsDateString, IsIn, IsObject, IsOptional, IsString, IsUUID } from 'class-validator';
-
-export class CreateGrantDto {
-  @IsUUID()
-  peerId!: string;
-
-  @IsUUID()
-  subjectUserId!: string;
-
-  @IsObject()
-  scope!: Record<string, unknown>;
-
-  @IsOptional()
-  @IsDateString()
-  expiresAt?: string;
-}
-
-export class ListGrantsDto {
-  @IsOptional()
-  @IsUUID()
-  peerId?: string;
-
-  @IsOptional()
-  @IsUUID()
-  subjectUserId?: string;
-
-  @IsOptional()
-  @IsIn(['pending', 'active', 'revoked', 'expired'])
-  status?: 'pending' | 'active' | 'revoked' | 'expired';
-}
-
-export class RevokeGrantDto {
-  @IsOptional()
-  @IsString()
-  reason?: string;
-}

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

@@ -1,190 +0,0 @@
-/**
- * Federation grants service — CRUD + status transitions (FED-M2-06).
- *
- * Business logic only. CSR/cert work is handled by M2-07.
- *
- * Status lifecycle:
- *   pending → active   (activateGrant, called by M2-07 enrollment controller after cert signed)
- *   active  → revoked  (revokeGrant)
- *   active  → expired  (expireGrant, called by M6 scheduler)
- */
-
-import { ConflictException, Inject, Injectable, NotFoundException } from '@nestjs/common';
-import { type Db, and, eq, federationGrants, federationPeers } from '@mosaicstack/db';
-import { DB } from '../database/database.module.js';
-import { parseFederationScope } from './scope-schema.js';
-import type { CreateGrantDto, ListGrantsDto } from './grants.dto.js';
-
-export type Grant = typeof federationGrants.$inferSelect;
-export type Peer = typeof federationPeers.$inferSelect;
-export type GrantWithPeer = Grant & { peer: Peer };
-
-@Injectable()
-export class GrantsService {
-  constructor(@Inject(DB) private readonly db: Db) {}
-
-  /**
-   * Create a new grant in `pending` state.
-   * Validates the scope against the federation scope JSON schema before inserting.
-   */
-  async createGrant(dto: CreateGrantDto): Promise<Grant> {
-    // Throws FederationScopeError (a plain Error subclass) on invalid scope.
-    parseFederationScope(dto.scope);
-
-    const [grant] = await this.db
-      .insert(federationGrants)
-      .values({
-        peerId: dto.peerId,
-        subjectUserId: dto.subjectUserId,
-        scope: dto.scope,
-        status: 'pending',
-        expiresAt: dto.expiresAt != null ? new Date(dto.expiresAt) : null,
-      })
-      .returning();
-
-    return grant!;
-  }
-
-  /**
-   * Fetch a single grant by ID. Throws NotFoundException if not found.
-   */
-  async getGrant(id: string): Promise<Grant> {
-    const [grant] = await this.db
-      .select()
-      .from(federationGrants)
-      .where(eq(federationGrants.id, id))
-      .limit(1);
-
-    if (!grant) {
-      throw new NotFoundException(`Grant ${id} not found`);
-    }
-
-    return grant;
-  }
-
-  /**
-   * Fetch a single grant by ID, joined with its associated peer row.
-   * Used by FederationAuthGuard to perform grant status + cert serial checks
-   * in a single DB round-trip.
-   *
-   * Throws NotFoundException if the grant does not exist.
-   * Throws NotFoundException if the associated peer row is missing (data integrity issue).
-   */
-  async getGrantWithPeer(id: string): Promise<GrantWithPeer> {
-    const rows = await this.db
-      .select()
-      .from(federationGrants)
-      .innerJoin(federationPeers, eq(federationGrants.peerId, federationPeers.id))
-      .where(eq(federationGrants.id, id))
-      .limit(1);
-
-    const row = rows[0];
-    if (!row) {
-      throw new NotFoundException(`Grant ${id} not found`);
-    }
-
-    return {
-      ...row.federation_grants,
-      peer: row.federation_peers,
-    };
-  }
-
-  /**
-   * List grants with optional filters for peerId, subjectUserId, and status.
-   */
-  async listGrants(filters: ListGrantsDto): Promise<Grant[]> {
-    const conditions = [];
-
-    if (filters.peerId != null) {
-      conditions.push(eq(federationGrants.peerId, filters.peerId));
-    }
-    if (filters.subjectUserId != null) {
-      conditions.push(eq(federationGrants.subjectUserId, filters.subjectUserId));
-    }
-    if (filters.status != null) {
-      conditions.push(eq(federationGrants.status, filters.status));
-    }
-
-    if (conditions.length === 0) {
-      return this.db.select().from(federationGrants);
-    }
-
-    return this.db
-      .select()
-      .from(federationGrants)
-      .where(and(...conditions));
-  }
-
-  /**
-   * Transition a grant from `pending` → `active`.
-   * Called by M2-07 enrollment controller after cert is signed.
-   * Throws ConflictException if the grant is not in `pending` state.
-   */
-  async activateGrant(id: string): Promise<Grant> {
-    const grant = await this.getGrant(id);
-
-    if (grant.status !== 'pending') {
-      throw new ConflictException(
-        `Grant ${id} cannot be activated: expected status 'pending', got '${grant.status}'`,
-      );
-    }
-
-    const [updated] = await this.db
-      .update(federationGrants)
-      .set({ status: 'active' })
-      .where(eq(federationGrants.id, id))
-      .returning();
-
-    return updated!;
-  }
-
-  /**
-   * Transition a grant from `active` → `revoked`.
-   * Sets revokedAt and optionally revokedReason.
-   * Throws ConflictException if the grant is not in `active` state.
-   */
-  async revokeGrant(id: string, reason?: string): Promise<Grant> {
-    const grant = await this.getGrant(id);
-
-    if (grant.status !== 'active') {
-      throw new ConflictException(
-        `Grant ${id} cannot be revoked: expected status 'active', got '${grant.status}'`,
-      );
-    }
-
-    const [updated] = await this.db
-      .update(federationGrants)
-      .set({
-        status: 'revoked',
-        revokedAt: new Date(),
-        revokedReason: reason ?? null,
-      })
-      .where(eq(federationGrants.id, id))
-      .returning();
-
-    return updated!;
-  }
-
-  /**
-   * Transition a grant from `active` → `expired`.
-   * Intended for use by the M6 scheduler.
-   * Throws ConflictException if the grant is not in `active` state.
-   */
-  async expireGrant(id: string): Promise<Grant> {
-    const grant = await this.getGrant(id);
-
-    if (grant.status !== 'active') {
-      throw new ConflictException(
-        `Grant ${id} cannot be expired: expected status 'active', got '${grant.status}'`,
-      );
-    }
-
-    const [updated] = await this.db
-      .update(federationGrants)
-      .set({ status: 'expired' })
-      .where(eq(federationGrants.id, id))
-      .returning();
-
-    return updated!;
-  }
-}

apps/gateway/src/federation/oid.util.ts

@@ -1,146 +0,0 @@
-/**
- * Shared OID extraction helpers for Mosaic federation certificates.
- *
- * Custom OID registry (PRD §6, docs/federation/SETUP.md):
- *   1.3.6.1.4.1.99999.1  — mosaic_grant_id
- *   1.3.6.1.4.1.99999.2  — mosaic_subject_user_id
- *
- * The encoding convention: each extension value is an OCTET STRING wrapping
- * an ASN.1 UTF8String TLV:
- *   0x0C (tag) + 1-byte length + UTF-8 bytes
- *
- * CaService encodes values this way via encodeUtf8String(), and this module
- * decodes them with the corresponding `.slice(2)` to skip tag + length byte.
- *
- * This module is intentionally pure — no NestJS, no DB, no network I/O.
- */
-
-import { X509Certificate } from '@peculiar/x509';
-
-// ---------------------------------------------------------------------------
-// OID constants
-// ---------------------------------------------------------------------------
-
-export const OID_MOSAIC_GRANT_ID = '1.3.6.1.4.1.99999.1';
-export const OID_MOSAIC_SUBJECT_USER_ID = '1.3.6.1.4.1.99999.2';
-
-// ---------------------------------------------------------------------------
-// Extraction result types
-// ---------------------------------------------------------------------------
-
-export interface MosaicOids {
-  grantId: string;
-  subjectUserId: string;
-}
-
-export type OidExtractionResult =
-  | { ok: true; value: MosaicOids }
-  | {
-      ok: false;
-      error: 'MISSING_GRANT_ID' | 'MISSING_SUBJECT_USER_ID' | 'PARSE_ERROR';
-      detail?: string;
-    };
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-const decoder = new TextDecoder();
-
-/**
- * Decode an extension value encoded as ASN.1 UTF8String TLV
- * (tag 0x0C + 1-byte length + UTF-8 bytes).
- * Validates tag, length byte, and buffer bounds before decoding.
- * Throws a descriptive Error on malformed input; caller wraps in try/catch.
- */
-function decodeUtf8StringTlv(value: ArrayBuffer): string {
-  const bytes = new Uint8Array(value);
-
-  // Need at least tag + length bytes
-  if (bytes.length < 2) {
-    throw new Error(`UTF8String TLV too short: expected at least 2 bytes, got ${bytes.length}`);
-  }
-
-  // Tag byte must be 0x0C (ASN.1 UTF8String)
-  if (bytes[0] !== 0x0c) {
-    throw new Error(
-      `UTF8String TLV tag mismatch: expected 0x0C, got 0x${bytes[0]!.toString(16).toUpperCase()}`,
-    );
-  }
-
-  // Only single-byte length form is supported (values 0–127); long form not needed
-  // for OID strings of this length.
-  const declaredLength = bytes[1]!;
-  if (declaredLength > 127) {
-    throw new Error(
-      `UTF8String TLV uses long-form length (0x${declaredLength.toString(16).toUpperCase()}), which is not supported`,
-    );
-  }
-
-  // Declared length must match actual remaining bytes
-  if (declaredLength !== bytes.length - 2) {
-    throw new Error(
-      `UTF8String TLV length mismatch: declared ${declaredLength}, actual ${bytes.length - 2}`,
-    );
-  }
-
-  // Skip: tag (1 byte) + length (1 byte)
-  return decoder.decode(bytes.slice(2));
-}
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * Extract Mosaic custom OIDs (grantId, subjectUserId) from an X.509 certificate
- * already parsed via @peculiar/x509.
- *
- * Returns `{ ok: true, value: MosaicOids }` on success, or
- * `{ ok: false, error: <code>, detail? }` on any failure — never throws.
- */
-export function extractMosaicOids(cert: X509Certificate): OidExtractionResult {
-  try {
-    const grantIdExt = cert.getExtension(OID_MOSAIC_GRANT_ID);
-    if (!grantIdExt) {
-      return { ok: false, error: 'MISSING_GRANT_ID' };
-    }
-
-    const subjectUserIdExt = cert.getExtension(OID_MOSAIC_SUBJECT_USER_ID);
-    if (!subjectUserIdExt) {
-      return { ok: false, error: 'MISSING_SUBJECT_USER_ID' };
-    }
-
-    const grantId = decodeUtf8StringTlv(grantIdExt.value);
-    const subjectUserId = decodeUtf8StringTlv(subjectUserIdExt.value);
-
-    return {
-      ok: true,
-      value: { grantId, subjectUserId },
-    };
-  } catch (err) {
-    return {
-      ok: false,
-      error: 'PARSE_ERROR',
-      detail: err instanceof Error ? err.message : String(err),
-    };
-  }
-}
-
-/**
- * Parse a PEM-encoded certificate and extract Mosaic OIDs.
- * Returns an OidExtractionResult — never throws.
- */
-export function extractMosaicOidsFromPem(certPem: string): OidExtractionResult {
-  let cert: X509Certificate;
-  try {
-    cert = new X509Certificate(certPem);
-  } catch (err) {
-    return {
-      ok: false,
-      error: 'PARSE_ERROR',
-      detail: err instanceof Error ? err.message : String(err),
-    };
-  }
-  return extractMosaicOids(cert);
-}

apps/gateway/src/federation/peer-key.util.ts

@@ -1,9 +0,0 @@
-import { seal, unseal } from '@mosaicstack/auth';
-
-export function sealClientKey(privateKeyPem: string): string {
-  return seal(privateKeyPem);
-}
-
-export function unsealClientKey(sealedKey: string): string {
-  return unseal(sealedKey);
-}

apps/gateway/src/federation/server/__tests__/federation-auth.guard.spec.ts

@@ -1,521 +0,0 @@
-/**
- * Unit tests for FederationAuthGuard (FED-M3-03).
- *
- * Coverage:
- *  - Missing cert (no TLS socket / no getPeerCertificate) → 401
- *  - Cert parse failure (corrupt DER raw bytes) → 401
- *  - Missing grantId OID → 401
- *  - Missing subjectUserId OID → 401
- *  - Grant not found (GrantsService throws NotFoundException) → 403
- *  - Grant in `pending` status → 403
- *  - Grant in `revoked` status → 403
- *  - Grant in `expired` status → 403
- *  - Cert serial mismatch → 403
- *  - Happy path: active grant + matching cert serial → context attached, returns true
- */
-
-import 'reflect-metadata';
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import type { ExecutionContext } from '@nestjs/common';
-import { NotFoundException } from '@nestjs/common';
-import { FederationAuthGuard } from '../federation-auth.guard.js';
-import { makeMosaicIssuedCert } from '../../__tests__/helpers/test-cert.js';
-import type { GrantsService, GrantWithPeer } from '../../grants.service.js';
-
-// ---------------------------------------------------------------------------
-// Test constants
-// ---------------------------------------------------------------------------
-
-const GRANT_ID = 'a1111111-1111-1111-1111-111111111111';
-const USER_ID = 'b2222222-2222-2222-2222-222222222222';
-const PEER_ID = 'c3333333-3333-3333-3333-333333333333';
-
-// Node.js TLS serialNumber is uppercase hex (no colons)
-const CERT_SERIAL_HEX = '01';
-
-const VALID_SCOPE = { resources: ['tasks'], max_rows_per_query: 100 };
-
-// ---------------------------------------------------------------------------
-// Mock builders
-// ---------------------------------------------------------------------------
-
-/**
- * Build a minimal GrantWithPeer-shaped mock.
- */
-function makeGrantWithPeer(overrides: Partial<GrantWithPeer> = {}): GrantWithPeer {
-  return {
-    id: GRANT_ID,
-    peerId: PEER_ID,
-    subjectUserId: USER_ID,
-    scope: VALID_SCOPE,
-    status: 'active',
-    expiresAt: null,
-    createdAt: new Date('2026-01-01T00:00:00Z'),
-    revokedAt: null,
-    revokedReason: null,
-    peer: {
-      id: PEER_ID,
-      commonName: 'test-peer',
-      displayName: 'Test Peer',
-      certPem: '',
-      certSerial: CERT_SERIAL_HEX,
-      certNotAfter: new Date(Date.now() + 86_400_000),
-      clientKeyPem: null,
-      state: 'active',
-      endpointUrl: null,
-      lastSeenAt: null,
-      createdAt: new Date('2026-01-01T00:00:00Z'),
-      revokedAt: null,
-    },
-    ...overrides,
-  };
-}
-
-/**
- * Build a mock ExecutionContext with a pre-built TLS peer certificate.
- *
- * `certPem` — PEM string to present as the raw DER cert (converted to Buffer).
- *             Pass null to simulate "no cert presented".
- * `certSerialHex` — serialNumber string returned by the TLS socket.
- *                   Node.js returns uppercase hex.
- * `hasTlsSocket` — if false, raw.socket has no getPeerCertificate (plain HTTP).
- */
-function makeContext(opts: {
-  certPem: string | null;
-  certSerialHex?: string;
-  hasTlsSocket?: boolean;
-}): {
-  ctx: ExecutionContext;
-  statusMock: ReturnType<typeof vi.fn>;
-  sendMock: ReturnType<typeof vi.fn>;
-} {
-  const { certPem, certSerialHex = CERT_SERIAL_HEX, hasTlsSocket = true } = opts;
-
-  // Build peerCert object that Node.js TLS socket.getPeerCertificate() returns
-  let peerCert: Record<string, unknown>;
-  if (certPem === null) {
-    // Simulate no cert: Node.js returns object with empty string fields
-    peerCert = { raw: null, serialNumber: '' };
-  } else {
-    // Convert PEM to DER Buffer (strip headers + base64 decode)
-    const b64 = certPem
-      .replace(/-----BEGIN CERTIFICATE-----/, '')
-      .replace(/-----END CERTIFICATE-----/, '')
-      .replace(/\s+/g, '');
-    const raw = Buffer.from(b64, 'base64');
-    peerCert = { raw, serialNumber: certSerialHex };
-  }
-
-  const getPeerCertificate = vi.fn().mockReturnValue(peerCert);
-
-  const socket = hasTlsSocket ? { getPeerCertificate } : {}; // No getPeerCertificate → non-TLS
-
-  // Fastify reply mocks
-  const sendMock = vi.fn().mockReturnValue(undefined);
-  const headerMock = vi.fn().mockReturnValue({ send: sendMock });
-  const statusMock = vi.fn().mockReturnValue({ header: headerMock });
-
-  const request = {
-    raw: {
-      socket,
-    },
-  };
-
-  const reply = {
-    status: statusMock,
-  };
-
-  const ctx = {
-    switchToHttp: () => ({
-      getRequest: () => request,
-      getResponse: () => reply,
-    }),
-  } as unknown as ExecutionContext;
-
-  return { ctx, statusMock, sendMock };
-}
-
-/**
- * Build a mock GrantsService.
- */
-function makeGrantsService(
-  overrides: Partial<Pick<GrantsService, 'getGrantWithPeer'>> = {},
-): GrantsService {
-  return {
-    getGrantWithPeer: vi.fn().mockResolvedValue(makeGrantWithPeer()),
-    ...overrides,
-  } as unknown as GrantsService;
-}
-
-// ---------------------------------------------------------------------------
-// Test suite
-// ---------------------------------------------------------------------------
-
-describe('FederationAuthGuard', () => {
-  let certPem: string;
-
-  beforeEach(async () => {
-    // Generate a real Mosaic-issued cert with the standard OIDs
-    certPem = await makeMosaicIssuedCert({ grantId: GRANT_ID, subjectUserId: USER_ID });
-  });
-
-  // ── 401: No TLS socket ────────────────────────────────────────────────────
-
-  it('returns 401 when there is no TLS socket (plain HTTP connection)', async () => {
-    const { ctx, statusMock, sendMock } = makeContext({
-      certPem: certPem,
-      hasTlsSocket: false,
-    });
-
-    const guard = new FederationAuthGuard(makeGrantsService());
-    const result = await guard.canActivate(ctx);
-
-    expect(result).toBe(false);
-    expect(statusMock).toHaveBeenCalledWith(401);
-    expect(sendMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        error: expect.objectContaining({ code: 'unauthorized', message: expect.any(String) }),
-      }),
-    );
-  });
-
-  // ── 401: Cert not presented ───────────────────────────────────────────────
-
-  it('returns 401 when the peer did not present a certificate', async () => {
-    const { ctx, statusMock, sendMock } = makeContext({ certPem: null });
-
-    const guard = new FederationAuthGuard(makeGrantsService());
-    const result = await guard.canActivate(ctx);
-
-    expect(result).toBe(false);
-    expect(statusMock).toHaveBeenCalledWith(401);
-    expect(sendMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        error: expect.objectContaining({ code: 'unauthorized', message: expect.any(String) }),
-      }),
-    );
-  });
-
-  // ── 401: Cert parse failure ───────────────────────────────────────────────
-
-  it('returns 401 when the certificate DER bytes are corrupt', async () => {
-    // Build context with a cert that has garbage DER bytes
-    const corruptPem = '-----BEGIN CERTIFICATE-----\naW52YWxpZA==\n-----END CERTIFICATE-----';
-    const { ctx, statusMock, sendMock } = makeContext({ certPem: corruptPem });
-
-    const guard = new FederationAuthGuard(makeGrantsService());
-    const result = await guard.canActivate(ctx);
-
-    expect(result).toBe(false);
-    expect(statusMock).toHaveBeenCalledWith(401);
-    expect(sendMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        error: expect.objectContaining({ code: 'unauthorized', message: expect.any(String) }),
-      }),
-    );
-  });
-
-  // ── 401: Missing grantId OID ─────────────────────────────────────────────
-
-  it('returns 401 when the cert is missing the grantId OID', async () => {
-    // makeSelfSignedCert produces a cert without any Mosaic OIDs
-    const { makeSelfSignedCert } = await import('../../__tests__/helpers/test-cert.js');
-    const plainCert = await makeSelfSignedCert();
-    const { ctx, statusMock, sendMock } = makeContext({ certPem: plainCert });
-
-    const guard = new FederationAuthGuard(makeGrantsService());
-    const result = await guard.canActivate(ctx);
-
-    expect(result).toBe(false);
-    expect(statusMock).toHaveBeenCalledWith(401);
-    expect(sendMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        error: expect.objectContaining({ code: 'unauthorized', message: expect.any(String) }),
-      }),
-    );
-  });
-
-  // ── 401: Missing subjectUserId OID ───────────────────────────────────────
-
-  it('returns 401 when the cert has grantId OID but is missing subjectUserId OID', async () => {
-    // Build a cert with only the grantId OID by importing cert generator internals
-    const { webcrypto } = await import('node:crypto');
-    const {
-      X509CertificateGenerator,
-      Extension,
-      KeyUsagesExtension,
-      KeyUsageFlags,
-      BasicConstraintsExtension,
-      cryptoProvider,
-    } = await import('@peculiar/x509');
-
-    cryptoProvider.set(webcrypto as unknown as Parameters<typeof cryptoProvider.set>[0]);
-
-    const alg = { name: 'ECDSA', namedCurve: 'P-256', hash: 'SHA-256' } as const;
-    const keys = await webcrypto.subtle.generateKey(alg, false, ['sign', 'verify']);
-    const now = new Date();
-    const tomorrow = new Date(now.getTime() + 86_400_000);
-
-    // Encode grantId only — missing subjectUserId extension
-    const utf8 = new TextEncoder().encode(GRANT_ID);
-    const encoded = new Uint8Array(2 + utf8.length);
-    encoded[0] = 0x0c;
-    encoded[1] = utf8.length;
-    encoded.set(utf8, 2);
-
-    const cert = await X509CertificateGenerator.createSelfSigned({
-      serialNumber: '01',
-      name: 'CN=partial-oid-test',
-      notBefore: now,
-      notAfter: tomorrow,
-      signingAlgorithm: alg,
-      keys,
-      extensions: [
-        new BasicConstraintsExtension(false),
-        new KeyUsagesExtension(KeyUsageFlags.digitalSignature),
-        new Extension('1.3.6.1.4.1.99999.1', false, encoded), // grantId only
-      ],
-    });
-
-    const { ctx, statusMock, sendMock } = makeContext({ certPem: cert.toString('pem') });
-
-    const guard = new FederationAuthGuard(makeGrantsService());
-    const result = await guard.canActivate(ctx);
-
-    expect(result).toBe(false);
-    expect(statusMock).toHaveBeenCalledWith(401);
-    expect(sendMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        error: expect.objectContaining({ code: 'unauthorized', message: expect.any(String) }),
-      }),
-    );
-  });
-
-  // ── 403: Grant not found ─────────────────────────────────────────────────
-
-  it('returns 403 when the grantId from the cert does not exist in DB', async () => {
-    const grantsService = makeGrantsService({
-      getGrantWithPeer: vi
-        .fn()
-        .mockRejectedValue(new NotFoundException(`Grant ${GRANT_ID} not found`)),
-    });
-
-    const { ctx, statusMock, sendMock } = makeContext({ certPem });
-
-    const guard = new FederationAuthGuard(grantsService);
-    const result = await guard.canActivate(ctx);
-
-    expect(result).toBe(false);
-    expect(statusMock).toHaveBeenCalledWith(403);
-    expect(sendMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        error: expect.objectContaining({ code: 'forbidden', message: 'Federation access denied' }),
-      }),
-    );
-  });
-
-  // ── 403: Grant in `pending` status ───────────────────────────────────────
-
-  it('returns 403 when the grant is in pending status', async () => {
-    const grantsService = makeGrantsService({
-      getGrantWithPeer: vi.fn().mockResolvedValue(makeGrantWithPeer({ status: 'pending' })),
-    });
-
-    const { ctx, statusMock, sendMock } = makeContext({ certPem });
-
-    const guard = new FederationAuthGuard(grantsService);
-    const result = await guard.canActivate(ctx);
-
-    expect(result).toBe(false);
-    expect(statusMock).toHaveBeenCalledWith(403);
-    expect(sendMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        error: expect.objectContaining({ code: 'forbidden', message: 'Federation access denied' }),
-      }),
-    );
-  });
-
-  // ── 403: Grant in `revoked` status ───────────────────────────────────────
-
-  it('returns 403 when the grant is in revoked status', async () => {
-    const grantsService = makeGrantsService({
-      getGrantWithPeer: vi
-        .fn()
-        .mockResolvedValue(makeGrantWithPeer({ status: 'revoked', revokedAt: new Date() })),
-    });
-
-    const { ctx, statusMock, sendMock } = makeContext({ certPem });
-
-    const guard = new FederationAuthGuard(grantsService);
-    const result = await guard.canActivate(ctx);
-
-    expect(result).toBe(false);
-    expect(statusMock).toHaveBeenCalledWith(403);
-    expect(sendMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        error: expect.objectContaining({ code: 'forbidden', message: 'Federation access denied' }),
-      }),
-    );
-  });
-
-  // ── 403: Grant in `expired` status ───────────────────────────────────────
-
-  it('returns 403 when the grant is in expired status', async () => {
-    const grantsService = makeGrantsService({
-      getGrantWithPeer: vi.fn().mockResolvedValue(makeGrantWithPeer({ status: 'expired' })),
-    });
-
-    const { ctx, statusMock, sendMock } = makeContext({ certPem });
-
-    const guard = new FederationAuthGuard(grantsService);
-    const result = await guard.canActivate(ctx);
-
-    expect(result).toBe(false);
-    expect(statusMock).toHaveBeenCalledWith(403);
-    expect(sendMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        error: expect.objectContaining({ code: 'forbidden', message: 'Federation access denied' }),
-      }),
-    );
-  });
-
-  // ── 403: Cert serial mismatch ─────────────────────────────────────────────
-
-  it('returns 403 when the cert serial does not match the registered peer cert serial', async () => {
-    // Return a grant whose peer has a different stored serial
-    const grantsService = makeGrantsService({
-      getGrantWithPeer: vi.fn().mockResolvedValue(
-        makeGrantWithPeer({
-          peer: {
-            id: PEER_ID,
-            commonName: 'test-peer',
-            displayName: 'Test Peer',
-            certPem: '',
-            certSerial: 'DEADBEEF', // different from CERT_SERIAL_HEX='01'
-            certNotAfter: new Date(Date.now() + 86_400_000),
-            clientKeyPem: null,
-            state: 'active',
-            endpointUrl: null,
-            lastSeenAt: null,
-            createdAt: new Date('2026-01-01T00:00:00Z'),
-            revokedAt: null,
-          },
-        }),
-      ),
-    });
-
-    // Context presents cert with serial '01' but DB has 'DEADBEEF'
-    const { ctx, statusMock, sendMock } = makeContext({ certPem, certSerialHex: '01' });
-
-    const guard = new FederationAuthGuard(grantsService);
-    const result = await guard.canActivate(ctx);
-
-    expect(result).toBe(false);
-    expect(statusMock).toHaveBeenCalledWith(403);
-    expect(sendMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        error: expect.objectContaining({ code: 'forbidden', message: 'Federation access denied' }),
-      }),
-    );
-  });
-
-  // ── 403: subjectUserId cert/DB mismatch (CRIT-1 regression test) ─────────
-
-  it('returns 403 when the cert subjectUserId does not match the DB grant subjectUserId', async () => {
-    // Build a cert that claims an attacker's subjectUserId
-    const attackerSubjectUserId = 'attacker-user-id';
-    const attackerCertPem = await makeMosaicIssuedCert({
-      grantId: GRANT_ID,
-      subjectUserId: attackerSubjectUserId,
-    });
-
-    // DB returns a grant with the legitimate USER_ID
-    const grantsService = makeGrantsService({
-      getGrantWithPeer: vi.fn().mockResolvedValue(makeGrantWithPeer({ subjectUserId: USER_ID })),
-    });
-
-    // Cert presents attacker-user-id but DB has USER_ID — should be rejected
-    const { ctx, statusMock, sendMock } = makeContext({
-      certPem: attackerCertPem,
-      certSerialHex: CERT_SERIAL_HEX,
-    });
-
-    const guard = new FederationAuthGuard(grantsService);
-    const result = await guard.canActivate(ctx);
-
-    expect(result).toBe(false);
-    expect(statusMock).toHaveBeenCalledWith(403);
-    expect(sendMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        error: expect.objectContaining({ code: 'forbidden', message: 'Federation access denied' }),
-      }),
-    );
-  });
-
-  // ── Happy path ────────────────────────────────────────────────────────────
-
-  it('returns true and attaches federationContext on happy path', async () => {
-    const grant = makeGrantWithPeer({
-      status: 'active',
-      peer: {
-        id: PEER_ID,
-        commonName: 'test-peer',
-        displayName: 'Test Peer',
-        certPem: '',
-        certSerial: CERT_SERIAL_HEX,
-        certNotAfter: new Date(Date.now() + 86_400_000),
-        clientKeyPem: null,
-        state: 'active',
-        endpointUrl: null,
-        lastSeenAt: null,
-        createdAt: new Date('2026-01-01T00:00:00Z'),
-        revokedAt: null,
-      },
-    });
-
-    const grantsService = makeGrantsService({
-      getGrantWithPeer: vi.fn().mockResolvedValue(grant),
-    });
-
-    // Build context manually to capture what gets set on request.federationContext
-    const b64 = certPem
-      .replace(/-----BEGIN CERTIFICATE-----/, '')
-      .replace(/-----END CERTIFICATE-----/, '')
-      .replace(/\s+/g, '');
-    const raw = Buffer.from(b64, 'base64');
-    const peerCert = { raw, serialNumber: CERT_SERIAL_HEX };
-
-    const sendMock = vi.fn().mockReturnValue(undefined);
-    const headerMock = vi.fn().mockReturnValue({ send: sendMock });
-    const statusMock = vi.fn().mockReturnValue({ header: headerMock });
-
-    const request: Record<string, unknown> = {
-      raw: {
-        socket: { getPeerCertificate: vi.fn().mockReturnValue(peerCert) },
-      },
-    };
-
-    const reply = { status: statusMock };
-
-    const ctx = {
-      switchToHttp: () => ({
-        getRequest: () => request,
-        getResponse: () => reply,
-      }),
-    } as unknown as ExecutionContext;
-
-    const guard = new FederationAuthGuard(grantsService);
-    const result = await guard.canActivate(ctx);
-
-    expect(result).toBe(true);
-    expect(statusMock).not.toHaveBeenCalled();
-
-    // Verify the context was attached correctly
-    expect(request['federationContext']).toEqual({
-      grantId: GRANT_ID,
-      subjectUserId: USER_ID,
-      peerId: PEER_ID,
-      scope: VALID_SCOPE,
-    });
-  });
-});

apps/gateway/src/federation/server/federation-auth.guard.ts

@@ -1,212 +0,0 @@
-/**
- * FederationAuthGuard — NestJS CanActivate guard for inbound federation requests.
- *
- * Validates the mTLS client certificate presented by a peer gateway, extracts
- * custom OIDs to identify the grant + subject user, loads the grant from DB,
- * asserts it is active, and verifies the cert serial against the registered peer
- * cert serial as a defense-in-depth measure.
- *
- * On success, attaches `request.federationContext` for downstream verb controllers.
- * On failure, responds with the federation wire-format error envelope (not raw
- * NestJS exception JSON) to match the federation protocol contract.
- *
- * ## Cert-serial check decision
- * The guard validates that the inbound client cert's serial number matches the
- * `certSerial` stored on the associated `federation_peers` row. This is a
- * defense-in-depth measure: even if the mTLS handshake is compromised at the
- * transport layer (e.g. misconfigured TLS terminator that forwards arbitrary
- * client certs), an attacker cannot replay a cert with a different serial than
- * what was registered during enrollment. This check is NOT loosened because:
- *  1. It is O(1) — no additional DB round-trip (peerId is on the grant row,
- *     so we join to federationPeers in the same query).
- *  2. Cert renewal MUST update the stored serial — enforced by M6 scheduler.
- *  3. The OID-only path (without serial check) would allow any cert from the
- *     same CA bearing the same grantId OID to succeed after cert compromise.
- *
- * ## FastifyRequest typing path
- * NestJS + Fastify wraps the raw Node.js IncomingMessage in a FastifyRequest.
- * The underlying TLS socket is accessed via `request.raw.socket`, which is a
- * `tls.TLSSocket` when the server is listening on HTTPS. In development/test
- * the gateway may run over plain HTTP, in which case `getPeerCertificate` is
- * not available. The guard safely handles both cases by checking for the
- * method's existence before calling it.
- *
- * Note: The guard reads the peer certificate from the *already-completed*
- * TLS handshake via `socket.getPeerCertificate(detailed=true)`. This relies
- * on the server being configured with `requestCert: true` at the TLS level
- * so Fastify/Node.js requests the client cert during the handshake.
- * The guard does NOT verify the cert chain itself — that is handled by the
- * TLS layer (Node.js `rejectUnauthorized: true` with the CA cert pinned).
- */
-
-import {
-  type CanActivate,
-  type ExecutionContext,
-  Inject,
-  Injectable,
-  Logger,
-} from '@nestjs/common';
-import type { FastifyReply, FastifyRequest } from 'fastify';
-import * as tls from 'node:tls';
-import { X509Certificate } from '@peculiar/x509';
-import { FederationForbiddenError, FederationUnauthorizedError } from '@mosaicstack/types';
-import { extractMosaicOids } from '../oid.util.js';
-import { GrantsService } from '../grants.service.js';
-import type { FederationContext } from './federation-context.js';
-import './federation-context.js'; // side-effect import: applies FastifyRequest module augmentation
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Send a federation wire-format error response directly on the Fastify reply.
- * Returns false — callers return this value from canActivate.
- */
-function sendFederationError(
-  reply: FastifyReply,
-  error: FederationUnauthorizedError | FederationForbiddenError,
-): boolean {
-  const statusCode = error.code === 'unauthorized' ? 401 : 403;
-  void reply.status(statusCode).header('content-type', 'application/json').send(error.toEnvelope());
-  return false;
-}
-
-// ---------------------------------------------------------------------------
-// Guard
-// ---------------------------------------------------------------------------
-
-@Injectable()
-export class FederationAuthGuard implements CanActivate {
-  private readonly logger = new Logger(FederationAuthGuard.name);
-
-  constructor(@Inject(GrantsService) private readonly grantsService: GrantsService) {}
-
-  async canActivate(context: ExecutionContext): Promise<boolean> {
-    const http = context.switchToHttp();
-    const request = http.getRequest<FastifyRequest>();
-    const reply = http.getResponse<FastifyReply>();
-
-    // ── Step 1: Extract peer certificate from TLS socket ────────────────────
-    const rawSocket = request.raw.socket;
-
-    // Check TLS socket: getPeerCertificate is only available on TLS connections.
-    if (
-      !rawSocket ||
-      typeof (rawSocket as Partial<tls.TLSSocket>).getPeerCertificate !== 'function'
-    ) {
-      this.logger.warn('No TLS socket — client cert unavailable (non-mTLS connection)');
-      return sendFederationError(
-        reply,
-        new FederationUnauthorizedError('Client certificate required'),
-      );
-    }
-
-    const tlsSocket = rawSocket as tls.TLSSocket;
-    const peerCert = tlsSocket.getPeerCertificate(true);
-
-    // Node.js returns an object with empty string fields when no cert was presented.
-    if (!peerCert || !peerCert.raw) {
-      this.logger.warn('Peer certificate not presented (mTLS handshake did not supply cert)');
-      return sendFederationError(
-        reply,
-        new FederationUnauthorizedError('Client certificate required'),
-      );
-    }
-
-    // ── Step 2: Parse the DER-encoded certificate via @peculiar/x509 ────────
-    let cert: X509Certificate;
-    try {
-      // peerCert.raw is a Buffer containing the DER-encoded cert
-      cert = new X509Certificate(peerCert.raw);
-    } catch (err) {
-      this.logger.warn(
-        `Failed to parse peer certificate: ${err instanceof Error ? err.message : String(err)}`,
-      );
-      return sendFederationError(
-        reply,
-        new FederationUnauthorizedError('Client certificate could not be parsed'),
-      );
-    }
-
-    // ── Step 3: Extract Mosaic custom OIDs ──────────────────────────────────
-    const oidResult = extractMosaicOids(cert);
-
-    if (!oidResult.ok) {
-      const message =
-        oidResult.error === 'MISSING_GRANT_ID'
-          ? 'Client certificate is missing required OID: mosaic_grant_id (1.3.6.1.4.1.99999.1)'
-          : oidResult.error === 'MISSING_SUBJECT_USER_ID'
-            ? 'Client certificate is missing required OID: mosaic_subject_user_id (1.3.6.1.4.1.99999.2)'
-            : `Client certificate OID extraction failed: ${oidResult.detail ?? 'unknown error'}`;
-      this.logger.warn(`OID extraction failure [${oidResult.error}]: ${message}`);
-      return sendFederationError(reply, new FederationUnauthorizedError(message));
-    }
-
-    const { grantId, subjectUserId } = oidResult.value;
-
-    // ── Step 4: Load grant from DB ───────────────────────────────────────────
-    let grant: Awaited<ReturnType<GrantsService['getGrantWithPeer']>>;
-    try {
-      grant = await this.grantsService.getGrantWithPeer(grantId);
-    } catch {
-      // getGrantWithPeer throws NotFoundException when not found
-      this.logger.warn(`Grant not found: ${grantId}`);
-      return sendFederationError(reply, new FederationForbiddenError('Federation access denied'));
-    }
-
-    // ── Step 5: Assert grant is active ──────────────────────────────────────
-    if (grant.status !== 'active') {
-      this.logger.warn(`Grant ${grantId} is not active — status=${grant.status}`);
-      return sendFederationError(reply, new FederationForbiddenError('Federation access denied'));
-    }
-
-    // ── Step 5b: Validate cert-extracted subjectUserId against DB (CRIT-1) ──
-    // The cert claim is untrusted input; the DB row is authoritative.
-    if (subjectUserId !== grant.subjectUserId) {
-      this.logger.warn(`subjectUserId mismatch for grant ${grantId}`);
-      return sendFederationError(reply, new FederationForbiddenError('Federation access denied'));
-    }
-
-    // ── Step 6: Defense-in-depth — cert serial must match registered peer ───
-    // The serial number from Node.js TLS is upper-case hex without colons.
-    // The @peculiar/x509 serialNumber is decimal. We compare using the native
-    // Node.js crypto cert serial which is uppercase hex, matching DB storage.
-    // Both are derived from the peerCert.serialNumber Node.js provides.
-    const inboundSerial: string = peerCert.serialNumber ?? '';
-
-    if (!grant.peer.certSerial) {
-      // Peer row exists but has no stored serial — something is wrong with enrollment
-      this.logger.error(`Peer ${grant.peerId} has no stored certSerial — enrollment incomplete`);
-      return sendFederationError(reply, new FederationForbiddenError('Federation access denied'));
-    }
-
-    // Normalize both to uppercase for comparison (Node.js serialNumber is
-    // already uppercase hex; DB value was stored from extractSerial() which
-    // returns crypto.X509Certificate.serialNumber — also uppercase hex).
-    if (inboundSerial.toUpperCase() !== grant.peer.certSerial.toUpperCase()) {
-      this.logger.warn(
-        `Cert serial mismatch for grant ${grantId}: ` +
-          `inbound=${inboundSerial} registered=${grant.peer.certSerial}`,
-      );
-      return sendFederationError(reply, new FederationForbiddenError('Federation access denied'));
-    }
-
-    // ── Step 7: Attach FederationContext to request ──────────────────────────
-    // Use grant.subjectUserId from DB (authoritative) — not the cert-extracted value.
-    const federationContext: FederationContext = {
-      grantId,
-      subjectUserId: grant.subjectUserId,
-      peerId: grant.peerId,
-      scope: grant.scope as Record<string, unknown>,
-    };
-
-    request.federationContext = federationContext;
-
-    this.logger.debug(
-      `Federation auth OK — grantId=${grantId} peerId=${grant.peerId} subjectUserId=${grant.subjectUserId}`,
-    );
-
-    return true;
-  }
-}

apps/gateway/src/federation/server/federation-context.ts

@@ -1,39 +0,0 @@
-/**
- * FederationContext — attached to inbound federation requests after successful
- * mTLS + grant validation by FederationAuthGuard.
- *
- * Downstream verb controllers access this via `request.federationContext`.
- */
-
-/**
- * Augment FastifyRequest so TypeScript knows about the federation context
- * property that FederationAuthGuard attaches on success.
- */
-declare module 'fastify' {
-  interface FastifyRequest {
-    federationContext?: FederationContext;
-  }
-}
-
-/**
- * Typed context object attached to the request by FederationAuthGuard.
- * Carries all data extracted from the mTLS cert + grant DB row needed
- * by downstream federation verb handlers.
- */
-export interface FederationContext {
-  /** The federation grant ID extracted from OID 1.3.6.1.4.1.99999.1 */
-  grantId: string;
-
-  /** The local subject user whose data is accessible under this grant */
-  subjectUserId: string;
-
-  /** The peer gateway ID (from the grant's peerId FK) */
-  peerId: string;
-
-  /**
-   * Grant scope — determines which resources the peer may query.
-   * Typed as Record<string, unknown> because the full scope schema lives in
-   * scope-schema.ts; downstream handlers should narrow via parseFederationScope.
-   */
-  scope: Record<string, unknown>;
-}

apps/gateway/src/federation/server/index.ts

@@ -1,13 +0,0 @@
-/**
- * Federation server-side barrel — inbound request handling.
- *
- * Exports the mTLS auth guard and the FederationContext interface
- * for use by verb controllers (M3-05/06/07).
- *
- * Usage:
- *   import { FederationAuthGuard } from './server/index.js';
- *   @UseGuards(FederationAuthGuard)
- */
-
-export { FederationAuthGuard } from './federation-auth.guard.js';
-export type { FederationContext } from './federation-context.js';

deploy/portainer/federated-test.stack.yml

@@ -36,12 +36,6 @@
 #   tested locally — gateway boots, imports resolve, tier-detector runs.
 #   Update digest here when promoting a new build.
 #
-# HEALTHCHECK NOTE (2026-04-21)
-#   Switched from busybox wget to node http.get on 127.0.0.1 (not localhost) to
-#   avoid IPv6 resolution issues on Alpine. Retries increased to 5 and
-#   start_period to 60s to cover the NestJS/GC cold-start window (~40-50s).
-#   restart_policy set to `any` so SIGTERM/clean-exit also triggers restart.
-#
 # NOTE: This is a TEST template — production deployments use a separate
 #       parameterised template with stricter resource limits and secrets.
 
@@ -82,7 +76,7 @@ services:
     deploy:
       replicas: 1
       restart_policy:
-        condition: any
+        condition: on-failure
         delay: 5s
         max_attempts: 3
       labels:
@@ -94,15 +88,11 @@ services:
         - 'traefik.http.routers.${STACK_NAME}.tls.certresolver=letsencrypt'
         - 'traefik.http.services.${STACK_NAME}.loadbalancer.server.port=3000'
     healthcheck:
-      test:
+      test: ['CMD', 'wget', '-qO-', 'http://localhost:3000/health']
-        - 'CMD'
-        - 'node'
-        - '-e'
-        - "require('http').get('http://127.0.0.1:3000/health',r=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"
       interval: 30s
       timeout: 5s
-      retries: 5
+      retries: 3
-      start_period: 60s
+      start_period: 20s
     depends_on:
       - postgres
       - valkey

docker/appservice.Dockerfile

@@ -1,28 +0,0 @@
-FROM node:22-alpine AS base
-ENV PNPM_HOME="/pnpm"
-ENV PATH="$PNPM_HOME:$PATH"
-RUN corepack enable
-
-FROM base AS builder
-WORKDIR /app
-# Copy workspace manifests first for layer-cached install
-COPY pnpm-workspace.yaml pnpm-lock.yaml package.json ./
-COPY apps/appservice/package.json ./apps/appservice/
-COPY packages/ ./packages/
-COPY plugins/ ./plugins/
-RUN pnpm install --frozen-lockfile
-COPY . .
-RUN pnpm turbo run build --filter @mosaicstack/mosaic-as...
-RUN pnpm --filter @mosaicstack/mosaic-as --prod deploy --legacy /deploy
-
-FROM base AS runner
-WORKDIR /app
-ENV NODE_ENV=production
-COPY --from=builder /deploy/node_modules ./node_modules
-COPY --from=builder /deploy/package.json ./package.json
-COPY --from=builder /app/apps/appservice/dist ./dist
-USER node
-EXPOSE 8008
-HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=5 \
-  CMD ["node", "-e", "require('http').get('http://127.0.0.1:8008/health',r=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"]
-CMD ["node", "dist/main.js"]

docs/TASKS.md

@@ -22,15 +22,14 @@
 
 These are MVP-level checks that don't belong to any single workstream. Updated by the orchestrator at each session.
 
-| id         | status      | description                                                                                              | notes                                                                                                                         |
+| id      | status      | description                                                                                              | notes                                                                                   |
-| ---------- | ----------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| ------- | ----------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| MVP-T01    | done        | Author MVP-level manifest at `docs/MISSION-MANIFEST.md`                                                  | This session (2026-04-19); PR pending                                                                                         |
+| MVP-T01 | done        | Author MVP-level manifest at `docs/MISSION-MANIFEST.md`                                                  | This session (2026-04-19); PR pending                                                   |
-| MVP-T02    | done        | Archive install-ux-v2 mission state to `docs/archive/missions/install-ux-v2-20260405/`                   | IUV-M03 retroactively closed (shipped via PR #446 + releases 0.0.27→0.0.29)                                                   |
+| MVP-T02 | done        | Archive install-ux-v2 mission state to `docs/archive/missions/install-ux-v2-20260405/`                   | IUV-M03 retroactively closed (shipped via PR #446 + releases 0.0.27→0.0.29)             |
-| MVP-T03    | done        | Land federation v1 planning artifacts on `main`                                                          | PR #468 merged 2026-04-19 (commit `66512550`)                                                                                 |
+| MVP-T03 | done        | Land federation v1 planning artifacts on `main`                                                          | PR #468 merged 2026-04-19 (commit `66512550`)                                           |
-| MVP-T04    | not-started | Sync `.mosaic/orchestrator/mission.json` MVP slot with this manifest (milestone enumeration, etc.)       | Coord state file; consider whether to repopulate via `mosaic coord` or accept hand-edit                                       |
+| MVP-T04 | not-started | Sync `.mosaic/orchestrator/mission.json` MVP slot with this manifest (milestone enumeration, etc.)       | Coord state file; consider whether to repopulate via `mosaic coord` or accept hand-edit |
-| MVP-T05    | in-progress | Kick off W1 / FED-M1 — federated tier infrastructure                                                     | Session 16 (2026-04-19): FED-M1-01 in-progress on `feat/federation-m1-tier-config`                                            |
+| MVP-T05 | in-progress | Kick off W1 / FED-M1 — federated tier infrastructure                                                     | Session 16 (2026-04-19): FED-M1-01 in-progress on `feat/federation-m1-tier-config`      |
-| MVP-T06    | not-started | Declare additional workstreams (web dashboard, TUI/CLI parity, remote control, etc.) as scope solidifies | Track each new workstream by adding a row to the Workstream Rollup                                                            |
+| MVP-T06 | not-started | Declare additional workstreams (web dashboard, TUI/CLI parity, remote control, etc.) as scope solidifies | Track each new workstream by adding a row to the Workstream Rollup                      |
-| T-A292E96F | in-progress | Fix Mosaic Gitea PR metadata/login wrapper regression for U-Connect merge preflight                      | Kanban `t_a292e96f`; branch `fix/t-a292e96f-gitea-pr-metadata`; scratchpad `docs/scratchpads/t-a292e96f-gitea-pr-metadata.md` |
 
 ## Pointer to Active Workstream
 

docs/federation/ADMIN-CLI.md

@@ -1,106 +0,0 @@
-# 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:** M3 active — mTLS handshake + list/get/capabilities verbs + scope enforcement
+**Phase:** M2 active — Step-CA + grant schema + admin CLI; parallel test-deploy workstream stood up
-**Current Milestone:** FED-M3
+**Current Milestone:** FED-M2
-**Progress:** 2 / 7 milestones
+**Progress:** 1 / 7 milestones
 **Status:** active
-**Last Updated:** 2026-04-21 (M2 closed via PR #503, tag `fed-v0.2.0-m2`, issue #461 closed; M3 decomposed into 14 tasks)
+**Last Updated:** 2026-04-21 (M2 decomposed; mos-test-1/-2 designated as federation E2E test hosts)
 **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            | done        | (PRs #483-#503)    | #461  | 2026-04-21 | 2026-04-21 |
+| 2   | FED-M2 | Step-CA + grant schema + admin CLI            | in-progress | (decomposition)    | #461  | 2026-04-21 | —          |
-| 3   | FED-M3 | mTLS handshake + list/get + scope enforcement | in-progress | (decomposition)    | #462  | 2026-04-21 | —          |
+| 3   | FED-M3 | mTLS handshake + list/get + scope enforcement | not-started | —                  | #462  | —          | —          |
 | 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  | —          | —          |
@@ -85,24 +85,17 @@ Key design references:
 
 ## Session History
 
-| Session | Date                    | Runtime | Outcome                                                                                                                               |
+| Session | Date       | Runtime | Outcome                                                               |
-| ------- | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| ------- | ---------- | ------- | --------------------------------------------------------------------- |
-| S1      | 2026-04-19              | claude  | PRD authored, MILESTONES decomposed, 7 issues filed                                                                                   |
+| 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`                                                                 |
+| 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-M3 active. Decomposition landed in `docs/federation/TASKS.md` (M3-01..M3-14, ~100K estimate). Tracking issue #462.
+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.
 
-Execution plan (parallel where possible):
+Parallel execution plan:
 
-- **Foundation**: M3-01 (DTOs in `packages/types/src/federation/`) starts immediately — sonnet subagent on `feat/federation-m3-types`. Blocks all server + client work.
+- **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.
-- **Server stream** (after M3-01): M3-03 (AuthGuard) + M3-04 (ScopeService) in series, then M3-05 / M3-06 / M3-07 (verbs) in parallel.
+- **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.
-- **Client stream** (after M3-01, parallel with server): M3-08 (FederationClient) → M3-09 (QuerySourceService).
+- **Re-converge** at M2-10 (E2E test) once both workstreams ready.
-- **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,96 +70,6 @@ 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
@@ -208,12 +118,6 @@ docker compose -f docker-compose.federated.yml logs valkey-federated
 
 If Valkey is running, verify your firewall allows 6380. On macOS, Docker Desktop may require binding to `host.docker.internal` instead of `localhost`.
 
-## Key rotation (deferred)
-
-Federation peer private keys (`federation_peers.client_key_pem`) are sealed at rest using AES-256-GCM with a key derived from `BETTER_AUTH_SECRET` via SHA-256. If `BETTER_AUTH_SECRET` is rotated, all sealed `client_key_pem` values in the database become unreadable and must be re-sealed with the new key before rotation completes.
-
-The full key rotation procedure (decrypt all rows with old key, re-encrypt with new key, atomically swap the secret) is out of scope for M2. Operators must not rotate `BETTER_AUTH_SECRET` without a migration plan for all sealed federation peer keys.
-
 ## OID Assignments — Mosaic Internal OID Arc
 
 Mosaic uses the private enterprise arc `1.3.6.1.4.1.99999` for custom X.509

docs/federation/TASKS.md

@@ -63,21 +63,21 @@ 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                                                                                                                                                        |
+| id        | status      | description                                                                                                                                                                                      | issue | agent  | branch                             | depends_on       | estimate | notes                                                                                                                                                                                                                                                                                                                                                                                                 |
-| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------ | ---------------------------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------ | ---------------------------------- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 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-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-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-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-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-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-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-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-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-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-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-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-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-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-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-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-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-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-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-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-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-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-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-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-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.                                                                 |
+| 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.                                                                                                                                                                                                                                                                                     |
 
 **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,38 +85,7 @@ Goal: An admin can create a federation grant; counterparty enrolls; cert is sign
 
 ## Milestone 3 — mTLS handshake + list/get + scope enforcement (FED-M3)
 
-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.
+_Deferred. Issue #462._
-
-> **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/git-wrapper-rollup-20260526.md

@@ -1,33 +0,0 @@
-# Git Wrapper Rollup — 2026-05-26
-
-## Objective
-
-Consolidate pending Mosaic wrapper fixes after `mosaic update` reported the local framework package was already current (`@mosaicstack/mosaic 0.0.30`) but the installed `~/.config/mosaic/tools` wrappers still lacked the open Gitea/Woodpecker wrapper patches.
-
-## Scope
-
-Roll up the open wrapper-related Gitea PR branches into one integration branch:
-
-- PR #513: `pr-ci-wait.sh` stdin collision fix.
-- PR #518: Gitea PR metadata/merge preflight hardening.
-- PR #521: Gitea merge fallback + unsafe PR-number rejection.
-- PR #522: Woodpecker credential/pagination fixes and CI Postgres service collision fix.
-- PR #523: explicit Gitea repo/login args and `eval` removal for PR/issue creation.
-
-## Conflict resolutions
-
-- Kept array-based command construction where possible instead of reintroducing `eval`.
-- Kept explicit `--repo OWNER/REPO --login mosaicstack` Gitea arguments for `tea` calls.
-- Combined PR merge API fallback behavior from metadata hardening and empty-identity fallback branches.
-- Preserved numeric PR-number validation for `pr-merge.sh`.
-
-## Verification checklist
-
-- `bash -n` on changed shell scripts.
-- Wrapper smoke checks from a clean worktree.
-- Gitea PR verification after push.
-- CI status checked through Gitea/Woodpecker.
-
-## Notes
-
-`mosaic update` did not install these fixes because the package registry still reports `@mosaicstack/mosaic 0.0.30` as current. The source patches must merge/release before normal framework update will carry them.

docs/scratchpads/mvp-20260312.md

@@ -612,44 +612,3 @@ 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)

docs/scratchpads/t-a292e96f-gitea-pr-metadata.md

@@ -1,53 +0,0 @@
-# t_a292e96f — Gitea PR metadata wrapper fix
-
-## Objective
-
-Repair Mosaic git wrappers so Gitea PR metadata and merge preflight work for U-Connect PRs on `git.uscllc.com` without selecting the unrelated `git.mosaicstack.dev` tea login.
-
-## Findings
-
-- Reproduced the failure from `/src/uconnect-worktrees/t_39ce717c-authentik-smoke-gate` with the current `pr-metadata.sh`:
-  - PR #1905 returned JSON with `number=null`, `baseRefName=""`, `headRefName=""`.
-  - PR #1908 returned JSON with `number=null`, `baseRefName=""`, `headRefName=""`.
-- Root cause: the wrapper treated HTTP/API error payloads as PR payloads and normalized missing fields to empty strings.
-- The credential loader can return a non-working `git.uscllc.com` API token in this environment, while host-specific `~/.git-credentials` basic auth succeeds. The wrapper now falls back by host before normalization.
-- `tea login list` has only `git.mosaicstack.dev` configured here; `pr-merge.sh` previously forced `--login mosaicstack`, which is invalid for `git.uscllc.com` and caused `Login name mosaicstack does not exist`.
-
-## Changes
-
-- `packages/mosaic/framework/tools/git/detect-platform.sh`
-  - Added `get_gitea_basic_auth <host>` to retrieve host-specific HTTPS credentials from `~/.git-credentials` without printing secrets.
-- `packages/mosaic/framework/tools/git/pr-metadata.sh`
-  - Uses strict bash mode.
-  - Checks Gitea HTTP status and fails nonzero on API errors/non-JSON instead of emitting empty branch fields.
-  - Falls back from token auth to host-specific basic auth.
-  - Normalizes standard `head.ref`/`base.ref` and fallback branch fields.
-  - Requires non-empty `headRefName` and `baseRefName`.
-  - Preserves GitHub `gh pr view` behavior.
-- `packages/mosaic/framework/tools/git/pr-merge.sh`
-  - Reads metadata once for base-branch policy preflight.
-  - Selects a `tea` login only when its configured URL matches the repo host.
-  - Falls back to authenticated Gitea merge API when no matching `tea` login exists, avoiding the wrong `mosaicstack` login for USC repos.
-  - Keeps squash-only and main-only merge policy.
-- `packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh`
-  - Added fixture-based regression harness for standard Gitea fields, fallback branch fields, `refs/pull/<n>/head` plus `head.label` normalization, and API error payloads.
-
-## Documentation / changelog note
-
-This repository currently has no root `CHANGELOG.md`; the scratchpad and `docs/TASKS.md` carry the task-level change record for this wrapper fix.
-
-## Verification log
-
-- Red regression check: copied the new `test-pr-metadata-gitea.sh` harness next to `origin/main` wrapper scripts and ran it with `MOSAIC_TEST_WORK_DIR=$PWD/.mosaic-test-work/pr-metadata-gitea-red`; it failed as expected with `headRefName=''` and `baseRefName=''` on the fixture API-error path.
-- `bash -n packages/mosaic/framework/tools/git/{detect-platform.sh,pr-metadata.sh,pr-merge.sh,test-pr-metadata-gitea.sh}`: passed.
-- `shellcheck -x -P . -e SC1090 packages/mosaic/framework/tools/git/{detect-platform.sh,pr-metadata.sh,pr-merge.sh,test-pr-metadata-gitea.sh}`: passed.
-- `MOSAIC_TEST_WORK_DIR=$PWD/.mosaic-test-work/pr-metadata-gitea packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh`: passed; verifies standard Gitea fields, fallback branch fields, `refs/pull/<n>/head` label normalization, and nonzero API-error handling.
-- Installed wrapper parity: `/home/hermes/.config/mosaic/tools/git/{detect-platform.sh,pr-metadata.sh,pr-merge.sh}` byte-match the PR source copies after validation, so active U-Connect wrapper invocations use the same fix while source PR review runs.
-- Live sanitized U-Connect metadata from `/src/uconnect` with `MOSAIC_CREDENTIALS_FILE=/src/jarvis-brain/credentials.json`:
-  - PR #1905: `number=1905`, `baseRefName=main`, `headRefName=edith/t_39ce717c-authentik-smoke-gate`, `state=open`, `host=git.uscllc.com`.
-  - PR #1908: `number=1908`, `baseRefName=main`, `headRefName=fix/t_23fa9e1d-portal-health-backend`, `state=closed`, `host=git.uscllc.com`.
-- Merge preflight dry runs from installed wrappers:
-  - PR #1905: `Dry run: would merge PR #1905 on git.uscllc.com with authenticated Gitea API fallback (base=main, method=squash).`
-  - PR #1908: `Dry run: would merge PR #1908 on git.uscllc.com with authenticated Gitea API fallback (base=main, method=squash).`
-- PR: `https://git.mosaicstack.dev/mosaicstack/stack/pulls/518`, branch `fix/t-a292e96f-gitea-pr-metadata`.
-- CI: Recent PR/push pipelines failed before clone/test execution due Woodpecker/Kubernetes PVC API timeout: `dial tcp 10.43.0.1:443: i/o timeout`. No repository test step executed in CI; local targeted verification above remains clean.

docs/scratchpads/t_301e4e3b-pr-merge-gitea-empty-uid.md

@@ -1,31 +0,0 @@
-# Scratchpad: t_301e4e3b pr-merge.sh Gitea empty-uid fallback
-
-## Task
-
-Implement a narrow hardening in `packages/mosaic/framework/tools/git/pr-merge.sh` so Gitea merges recover from the known non-interactive `tea pr merge` identity failure: `user does not exist [uid: 0, name: ]`.
-
-## Constraints
-
-- Preserve Mosaic policy gates: squash-only, base branch `main`, queue guard unless explicitly skipped.
-- Preserve the existing authenticated Gitea API fallback when no tea login exists.
-- Do not fallback on arbitrary tea failures.
-- Do not expose tokens or credential-bearing remotes.
-- Scope is limited to the merge wrapper plus focused test/support/scratchpad files.
-
-## External issue
-
-- Gitea issue #520: Harden pr-merge.sh Gitea empty-uid fallback
-
-## Plan
-
-1. Add a focused shell regression harness with mocked `tea` and `curl` proving the known empty uid/name failure must fall back to Gitea API.
-2. Watch the harness fail on current code.
-3. Implement helper functions in `pr-merge.sh` for redacted command display, known failure classification, and authenticated Gitea API merge fallback.
-4. Keep unknown `tea` failures blocking by replaying stderr and exiting non-zero.
-5. Run syntax, shellcheck if available, focused regression, and repo quality gates before push/PR.
-
-## Session log
-
-- 2026-05-22: Read Kanban context, Mosaic global/repo instructions, created isolated branch `fix/t_301e4e3b-pr-merge-gitea-empty-uid`, and opened Gitea issue #520 using the Mosaic issue wrapper/API fallback.
-- 2026-05-22: Added regression harness and watched it fail on current behavior with `user does not exist [uid: 0, name: ]`; implemented narrow fallback and verified known-empty-identity fallback, arbitrary tea failure blocking, and no-tea-login API fallback paths.
-- 2026-05-22: Validation passed for `bash -n`, `shellcheck -x`, focused shell harness, `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, and `pnpm --filter @mosaicstack/mosaic test`. Full `pnpm test` exposed an out-of-scope gateway DB setup failure (`relation "messages" does not exist`) in `apps/gateway/src/__tests__/cross-user-isolation.test.ts`.

docs/scratchpads/t_5aab9cc8-pr-merge-eval-injection.md

@@ -1,48 +0,0 @@
-# t_5aab9cc8 — pr-merge.sh eval injection remediation
-
-## Objective
-
-Remediate PR #521 review blocker: `packages/mosaic/framework/tools/git/pr-merge.sh` must reject non-numeric PR numbers before metadata lookup/merge and must not use `eval` for GitHub merge execution.
-
-## Scope
-
-- Shell wrapper only: `packages/mosaic/framework/tools/git/pr-merge.sh`
-- Focused regression harness: `packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh`
-- No API/frontend/infra surfaces.
-
-## Acceptance Criteria
-
-- AC1: `PR_NUMBER` is validated as digits-only immediately after required-argument parsing, before metadata lookup.
-- AC2: GitHub merge path uses a quoted argv array, not command-string construction plus `eval`.
-- AC3: Focused tests prove PR-number metacharacters are rejected and cannot execute injected shell commands on GitHub path.
-- AC4: Focused tests prove PR-number metacharacters are rejected on Gitea path before tea/curl merge calls.
-- AC5: Existing Gitea empty-uid fallback behavior remains green.
-- AC6: Syntax, shellcheck where available, focused harness, and relevant repo gates are rerun or absence documented.
-
-## Plan
-
-1. Add failing regression tests for GitHub eval injection and Gitea invalid PR rejection.
-2. Implement fail-closed PR number validation before metadata lookup.
-3. Replace GitHub `eval` command with argv array execution.
-4. Run required validation and update this scratchpad with evidence.
-5. Commit, queue-guard, push branch, update PR #521.
-
-## TDD Log
-
-- RED: `AGENT_WORK_ROOT="$HERMES_KANBAN_WORKSPACE/work" bash packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh` failed on vulnerable code with `Expected GitHub metacharacter PR number to be rejected` and showed the injected PR number reached the GitHub merge path.
-- GREEN: Added digits-only validation before metadata lookup and replaced GitHub `eval` with an argv array. The focused harness now passes and verifies invalid PR numbers are rejected before GitHub `gh` calls and before Gitea `tea`/`curl` calls.
-
-## Validation Evidence
-
-- PASS: `AGENT_WORK_ROOT="$HERMES_KANBAN_WORKSPACE/work" bash -n packages/mosaic/framework/tools/git/pr-merge.sh packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh`
-- PASS: `shellcheck -x packages/mosaic/framework/tools/git/pr-merge.sh packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh`
-- PASS: `AGENT_WORK_ROOT="$HERMES_KANBAN_WORKSPACE/work" bash packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh`
-- PASS: `pnpm --filter @mosaicstack/mosaic... build`
-- PASS: `pnpm --filter @mosaicstack/mosaic lint`
-- PASS: `pnpm --filter @mosaicstack/mosaic typecheck`
-- PASS: `pnpm --filter @mosaicstack/mosaic test` — 32 files / 291 tests passed.
-- REVIEW: `/home/hermes/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` could not run due Codex 401 Unauthorized. Independent delegate review completed read-only with PASS / no blockers; non-blocking suggestion to assert GitHub mock log remains empty was applied.
-
-## Risks / Blockers
-
-- No active blockers.

eslint.config.mjs

@@ -30,7 +30,6 @@ export default tseslint.config(
             'apps/gateway/vitest.config.ts',
             'packages/storage/vitest.config.ts',
             'packages/mosaic/__tests__/*.ts',
-            'tools/federation-harness/*.ts',
           ],
         },
       },

packages/appservice/package.json

@@ -1,36 +0,0 @@
-{
-  "name": "@mosaicstack/appservice",
-  "version": "0.0.1",
-  "type": "module",
-  "repository": {
-    "type": "git",
-    "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
-    "directory": "packages/appservice"
-  },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    }
-  },
-  "scripts": {
-    "build": "tsc",
-    "lint": "eslint src",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run --passWithNoTests"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.8.0",
-    "vitest": "^2.0.0"
-  },
-  "publishConfig": {
-    "registry": "https://git.mosaicstack.dev/api/packages/mosaicstack/npm/",
-    "access": "public"
-  },
-  "files": [
-    "dist"
-  ]
-}

packages/appservice/src/__tests__/appservice.test.ts

@@ -1,230 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-
-import { validateBridgeMessage, validateBridgeTyping } from '../bridge.dto.js';
-import { AppserviceIntent, MatrixApiError } from '../intent.js';
-import { buildRegistration, registrationToYaml } from '../registration.js';
-import { TransactionHandler } from '../transactions.js';
-import type { AppserviceConfig, MatrixEvent } from '../types.js';
-
-const cfg: AppserviceConfig = {
-  homeserverUrl: 'https://hs.example',
-  domain: 'hs.example',
-  asToken: 'as-secret',
-  hsToken: 'hs-secret',
-};
-
-const jsonResponse = (status: number, body: unknown): Response =>
-  new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } });
-
-describe('TransactionHandler', () => {
-  const makeHandler = (onEvent = vi.fn()) => ({
-    onEvent,
-    handler: new TransactionHandler({ hsToken: 'hs-secret', onEvent }),
-  });
-
-  it('rejects a bad hs_token with M_FORBIDDEN', async () => {
-    const { handler, onEvent } = makeHandler();
-    const res = await handler.handle(
-      't1',
-      { events: [{ type: 'm.room.message' }] },
-      { authorizationHeader: 'Bearer wrong' },
-    );
-    expect(res.status).toBe(403);
-    expect(res.body.errcode).toBe('M_FORBIDDEN');
-    expect(onEvent).not.toHaveBeenCalled();
-  });
-
-  it('accepts Bearer auth and legacy access_token param', async () => {
-    const { handler } = makeHandler();
-    expect(
-      (await handler.handle('t1', { events: [] }, { authorizationHeader: 'Bearer hs-secret' }))
-        .status,
-    ).toBe(200);
-    expect(
-      (await handler.handle('t2', { events: [] }, { accessTokenParam: 'hs-secret' })).status,
-    ).toBe(200);
-  });
-
-  it('processes events once per txnId (idempotent retries)', async () => {
-    const { handler, onEvent } = makeHandler();
-    const body = { events: [{ type: 'm.room.message', event_id: '$e1' }] };
-    await handler.handle('t1', body, { authorizationHeader: 'Bearer hs-secret' });
-    const retry = await handler.handle('t1', body, { authorizationHeader: 'Bearer hs-secret' });
-    expect(retry.status).toBe(200);
-    expect(onEvent).toHaveBeenCalledTimes(1);
-  });
-
-  it('a throwing event handler does not fail the transaction', async () => {
-    const onError = vi.fn();
-    const handler = new TransactionHandler({
-      hsToken: 'hs-secret',
-      onEvent: () => {
-        throw new Error('boom');
-      },
-      onError,
-    });
-    const res = await handler.handle(
-      't1',
-      { events: [{ type: 'x' }, { type: 'y' }] },
-      { authorizationHeader: 'Bearer hs-secret' },
-    );
-    expect(res.status).toBe(200);
-    expect(onError).toHaveBeenCalledTimes(2);
-  });
-});
-
-describe('AppserviceIntent', () => {
-  it('derives namespaced user ids and rejects bad slugs', () => {
-    const intent = new AppserviceIntent(cfg);
-    expect(intent.agentUserId('pi0-web1')).toBe('@agent-pi0-web1:hs.example');
-    expect(intent.agentUserId('Pi0-Web1')).toBe('@agent-pi0-web1:hs.example');
-    expect(() => intent.agentUserId('../evil')).toThrow();
-    expect(() => intent.agentUserId('')).toThrow();
-  });
-
-  it('uses uuid transaction ids', async () => {
-    const calls: string[] = [];
-    const fetchMock = vi.fn(async (input: URL | string) => {
-      calls.push(new URL(String(input)).pathname);
-      return jsonResponse(200, {});
-    });
-    const intent = new AppserviceIntent(cfg, fetchMock as unknown as typeof fetch);
-    await intent.sendAsAgent({ roomId: '!r:hs.example', agent: 'pi0', body: 'x' });
-    const send = calls.find((p) => p.includes('/send/m.room.message/'));
-    expect(send).toMatch(/mosaic-as-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
-  });
-
-  it('registers once, impersonates via user_id, threads replies', async () => {
-    const calls: Array<{ url: URL; init: RequestInit }> = [];
-    const fetchMock = vi.fn(async (input: URL | string, init?: RequestInit) => {
-      calls.push({ url: new URL(String(input)), init: init ?? {} });
-      return jsonResponse(200, { event_id: '$sent' });
-    });
-    const intent = new AppserviceIntent(cfg, fetchMock as unknown as typeof fetch);
-
-    const eventId = await intent.sendAsAgent({
-      roomId: '!room:hs.example',
-      agent: 'pi0-web1',
-      body: 'hello',
-      threadRoot: '$req',
-    });
-    await intent.sendAsAgent({ roomId: '!room:hs.example', agent: 'pi0-web1', body: 'again' });
-
-    expect(eventId).toBe('$sent');
-    const paths = calls.map((c) => c.url.pathname);
-    expect(paths.filter((p) => p.endsWith('/register'))).toHaveLength(1); // cached
-    expect(paths.filter((p) => p.includes('/join'))).toHaveLength(1); // cached
-
-    const send = calls.find((c) => c.url.pathname.includes('/send/m.room.message/'));
-    expect(send).toBeDefined();
-    expect(send!.url.searchParams.get('user_id')).toBe('@agent-pi0-web1:hs.example');
-    const content = JSON.parse(String(send!.init.body)) as Record<string, unknown>;
-    const rel = content['m.relates_to'] as Record<string, unknown>;
-    expect(rel.rel_type).toBe('m.thread');
-    expect(rel.event_id).toBe('$req');
-    expect(rel.is_falling_back).toBe(true);
-    expect(
-      calls.every(
-        (c) => (c.init.headers as Record<string, string>).Authorization === 'Bearer as-secret',
-      ),
-    ).toBe(true);
-  });
-
-  it('tolerates M_USER_IN_USE and surfaces other register errors', async () => {
-    const inUse = vi.fn(async () =>
-      jsonResponse(400, { errcode: 'M_USER_IN_USE', error: 'taken' }),
-    );
-    const intent = new AppserviceIntent(cfg, inUse as unknown as typeof fetch);
-    await expect(intent.ensureRegistered('pi0-web1')).resolves.toBe('@agent-pi0-web1:hs.example');
-
-    const denied = vi.fn(async () =>
-      jsonResponse(401, { errcode: 'M_UNKNOWN_TOKEN', error: 'nope' }),
-    );
-    const intent2 = new AppserviceIntent(cfg, denied as unknown as typeof fetch);
-    await expect(intent2.ensureRegistered('pi0-web1')).rejects.toThrow(MatrixApiError);
-  });
-
-  it('invites then joins on M_FORBIDDEN join', async () => {
-    const paths: string[] = [];
-    const fetchMock = vi.fn(async (input: URL | string) => {
-      const url = new URL(String(input));
-      paths.push(url.pathname);
-      if (url.pathname.endsWith('/join') && paths.filter((p) => p.endsWith('/join')).length === 1) {
-        return jsonResponse(403, { errcode: 'M_FORBIDDEN', error: 'not invited' });
-      }
-      return jsonResponse(200, {});
-    });
-    const intent = new AppserviceIntent(cfg, fetchMock as unknown as typeof fetch);
-    await intent.ensureJoined('!room:hs.example', 'pi0-web1');
-    expect(paths.filter((p) => p.endsWith('/invite'))).toHaveLength(1);
-    expect(paths.filter((p) => p.endsWith('/join'))).toHaveLength(2);
-  });
-});
-
-describe('registration', () => {
-  it('builds an exclusive escaped user namespace', () => {
-    const reg = buildRegistration(cfg, { url: 'http://mosaic-as:8008' });
-    expect(reg.namespaces.users[0]).toEqual({
-      regex: '@agent-.*:hs\\.example',
-      exclusive: true,
-    });
-    expect(reg.rate_limited).toBe(false);
-    const yaml = registrationToYaml(reg);
-    expect(yaml).toContain("sender_localpart: 'mosaic-as'");
-    expect(yaml).toContain("as_token: 'as-secret'");
-    expect(yaml).toContain('exclusive: true');
-  });
-});
-
-describe('registration hardening', () => {
-  it('rejects control characters in registration values', () => {
-    const reg = buildRegistration(
-      { ...cfg, asToken: 'abc\nhttp_injected: true' },
-      { url: 'http://mosaic-as:8008' },
-    );
-    expect(() => registrationToYaml(reg)).toThrow(/control characters/);
-  });
-
-  it('escapes single quotes in token values', () => {
-    const reg = buildRegistration({ ...cfg, asToken: "it's" }, { url: 'http://mosaic-as:8008' });
-    expect(registrationToYaml(reg)).toContain("as_token: 'it''s'");
-  });
-});
-
-describe('bridge DTOs', () => {
-  it('validates message and typing payloads', () => {
-    expect(() =>
-      validateBridgeMessage({ room_id: '!r:hs', agent: 'pi0', body: 'x' }),
-    ).not.toThrow();
-    expect(() => validateBridgeMessage({ room_id: 'bad', agent: 'pi0', body: 'x' })).toThrow();
-    expect(() => validateBridgeMessage({ room_id: '!r:hs', agent: '', body: 'x' })).toThrow();
-    expect(() => validateBridgeMessage({ room_id: '!r:hs', agent: '../evil', body: 'x' })).toThrow(
-      /agent must match/,
-    );
-    expect(() =>
-      validateBridgeTyping({ room_id: '!r:hs', agent: 'pi0', typing: true }),
-    ).not.toThrow();
-    expect(() => validateBridgeTyping({ room_id: '!r:hs', agent: 'pi0', typing: 'yes' })).toThrow();
-  });
-});
-
-describe('event shape', () => {
-  it('transaction events flow through to the handler', async () => {
-    const seen: MatrixEvent[] = [];
-    const handler = new TransactionHandler({
-      hsToken: 'hs-secret',
-      onEvent: (e) => void seen.push(e),
-    });
-    await handler.handle(
-      't1',
-      {
-        events: [
-          { type: 'm.room.message', room_id: '!r:hs', sender: '@u:hs', content: { body: 'hi' } },
-        ],
-      },
-      { authorizationHeader: 'Bearer hs-secret' },
-    );
-    expect(seen).toHaveLength(1);
-    expect(seen[0]!.content?.body).toBe('hi');
-  });
-});

packages/appservice/src/bridge.dto.ts

@@ -1,52 +0,0 @@
-/** DTOs for the internal bridge API consumed by agent-comms host daemons. */
-
-export interface BridgeMessageDto {
-  room_id: string;
-  /** Agent slug (localpart suffix), e.g. "pi0-web1". */
-  agent: string;
-  body: string;
-  thread_root?: string;
-  msgtype?: string;
-  /** Optional protocol payload merged into content (e.g. org.uscllc.agent). */
-  extra_content?: Record<string, unknown>;
-}
-
-export interface BridgeTypingDto {
-  room_id: string;
-  agent: string;
-  typing: boolean;
-}
-
-const AGENT_SLUG_RE = /^[a-z0-9][a-z0-9_.-]*$/;
-
-const assertAgentSlug = (agent: unknown): void => {
-  if (typeof agent !== 'string' || !AGENT_SLUG_RE.test(agent.toLowerCase())) {
-    throw new Error('agent must match [a-z0-9][a-z0-9_.-]*');
-  }
-};
-
-export function validateBridgeMessage(input: unknown): asserts input is BridgeMessageDto {
-  const o = input as Partial<BridgeMessageDto> | null | undefined;
-  if (!o || typeof o !== 'object') throw new Error('payload must be an object');
-  if (typeof o.room_id !== 'string' || !o.room_id.startsWith('!'))
-    throw new Error('room_id must be a Matrix room id');
-  assertAgentSlug(o.agent);
-  if (typeof o.body !== 'string') throw new Error('body must be a string');
-  if (o.thread_root !== undefined && typeof o.thread_root !== 'string')
-    throw new Error('thread_root must be a string');
-  if (
-    o.extra_content !== undefined &&
-    (typeof o.extra_content !== 'object' || o.extra_content === null)
-  ) {
-    throw new Error('extra_content must be an object');
-  }
-}
-
-export function validateBridgeTyping(input: unknown): asserts input is BridgeTypingDto {
-  const o = input as Partial<BridgeTypingDto> | null | undefined;
-  if (!o || typeof o !== 'object') throw new Error('payload must be an object');
-  if (typeof o.room_id !== 'string' || !o.room_id.startsWith('!'))
-    throw new Error('room_id must be a Matrix room id');
-  assertAgentSlug(o.agent);
-  if (typeof o.typing !== 'boolean') throw new Error('typing must be a boolean');
-}

packages/appservice/src/index.ts

@@ -1,15 +0,0 @@
-export { AppserviceIntent, MatrixApiError } from './intent.js';
-export type { SendMessageOptions } from './intent.js';
-export { TransactionHandler } from './transactions.js';
-export type { TransactionHandlerOptions } from './transactions.js';
-export { buildRegistration, registrationToYaml } from './registration.js';
-export type { RegistrationOptions } from './registration.js';
-export { validateBridgeMessage, validateBridgeTyping } from './bridge.dto.js';
-export type { BridgeMessageDto, BridgeTypingDto } from './bridge.dto.js';
-export type {
-  AppserviceConfig,
-  EventHandler,
-  HandlerResult,
-  MatrixEvent,
-  Transaction,
-} from './types.js';

packages/appservice/src/intent.ts

@@ -1,184 +0,0 @@
-import crypto from 'node:crypto';
-
-import type { AppserviceConfig } from './types.js';
-
-export interface SendMessageOptions {
-  roomId: string;
-  /** Agent slug, e.g. "pi0-web1" -> @agent-pi0-web1:domain */
-  agent: string;
-  body: string;
-  /** Request event id to thread off (m.thread, spec v1.4). */
-  threadRoot?: string;
-  msgtype?: string;
-  /** Extra content keys merged into the message content (e.g. org.uscllc.agent). */
-  extraContent?: Record<string, unknown>;
-}
-
-export class MatrixApiError extends Error {
-  constructor(
-    readonly status: number,
-    readonly errcode: string | undefined,
-    message: string,
-  ) {
-    super(message);
-    this.name = 'MatrixApiError';
-  }
-}
-
-type FetchLike = typeof fetch;
-
-/**
- * Acts on the homeserver as appservice-namespaced virtual users
- * (Application Service API: as_token auth + user_id impersonation).
- */
-export class AppserviceIntent {
-  private readonly registered = new Set<string>();
-  private readonly joined = new Set<string>();
-  private readonly fetchImpl: FetchLike;
-
-  constructor(
-    private readonly cfg: AppserviceConfig,
-    fetchImpl?: FetchLike,
-  ) {
-    this.fetchImpl = fetchImpl ?? fetch;
-  }
-
-  get userPrefix(): string {
-    return this.cfg.userPrefix ?? 'agent-';
-  }
-
-  get senderUserId(): string {
-    return `@${this.cfg.senderLocalpart ?? 'mosaic-as'}:${this.cfg.domain}`;
-  }
-
-  agentLocalpart(agent: string): string {
-    const slug = agent.toLowerCase();
-    if (!/^[a-z0-9][a-z0-9_.-]*$/.test(slug)) {
-      throw new Error(`invalid agent slug: ${agent}`);
-    }
-    return `${this.userPrefix}${slug}`;
-  }
-
-  agentUserId(agent: string): string {
-    return `@${this.agentLocalpart(agent)}:${this.cfg.domain}`;
-  }
-
-  private async request(
-    method: string,
-    path: string,
-    options: { userId?: string; body?: unknown } = {},
-  ): Promise<Record<string, unknown>> {
-    const url = new URL(this.cfg.homeserverUrl.replace(/\/$/, '') + path);
-    if (options.userId) {
-      url.searchParams.set('user_id', options.userId);
-    }
-    const res = await this.fetchImpl(url, {
-      method,
-      headers: {
-        Authorization: `Bearer ${this.cfg.asToken}`,
-        'Content-Type': 'application/json',
-      },
-      body: options.body === undefined ? undefined : JSON.stringify(options.body),
-    });
-    const text = await res.text();
-    const data = (text ? JSON.parse(text) : {}) as Record<string, unknown>;
-    if (!res.ok) {
-      throw new MatrixApiError(
-        res.status,
-        typeof data.errcode === 'string' ? data.errcode : undefined,
-        `${method} ${path} -> ${res.status}: ${text.slice(0, 300)}`,
-      );
-    }
-    return data;
-  }
-
-  /** Register the virtual user if it does not exist yet. Idempotent. */
-  async ensureRegistered(agent: string): Promise<string> {
-    const localpart = this.agentLocalpart(agent);
-    const userId = this.agentUserId(agent);
-    if (this.registered.has(userId)) return userId;
-    try {
-      await this.request('POST', '/_matrix/client/v3/register', {
-        body: { type: 'm.login.application_service', username: localpart },
-      });
-    } catch (err) {
-      if (!(err instanceof MatrixApiError && err.errcode === 'M_USER_IN_USE')) {
-        throw err;
-      }
-    }
-    this.registered.add(userId);
-    return userId;
-  }
-
-  /** Join the agent to a room; on invite-only rooms the AS sender invites first. */
-  async ensureJoined(roomId: string, agent: string): Promise<void> {
-    const userId = await this.ensureRegistered(agent);
-    const key = `${userId} ${roomId}`;
-    if (this.joined.has(key)) return;
-    const room = encodeURIComponent(roomId);
-    try {
-      await this.request('POST', `/_matrix/client/v3/rooms/${room}/join`, { userId, body: {} });
-    } catch (err) {
-      if (!(err instanceof MatrixApiError && err.errcode === 'M_FORBIDDEN')) throw err;
-      await this.request('POST', `/_matrix/client/v3/rooms/${room}/invite`, {
-        userId: this.senderUserId,
-        body: { user_id: userId },
-      });
-      await this.request('POST', `/_matrix/client/v3/rooms/${room}/join`, { userId, body: {} });
-    }
-    this.joined.add(key);
-  }
-
-  /** Send a message AS the agent's virtual user. */
-  async sendAsAgent(options: SendMessageOptions): Promise<string | undefined> {
-    const userId = this.agentUserId(options.agent);
-    await this.ensureJoined(options.roomId, options.agent);
-    const content: Record<string, unknown> = {
-      msgtype: options.msgtype ?? 'm.text',
-      body: options.body,
-      ...options.extraContent,
-    };
-    if (options.threadRoot) {
-      content['m.relates_to'] = {
-        rel_type: 'm.thread',
-        event_id: options.threadRoot,
-        is_falling_back: true,
-        'm.in_reply_to': { event_id: options.threadRoot },
-      };
-    }
-    const txn = `mosaic-as-${crypto.randomUUID()}`;
-    const room = encodeURIComponent(options.roomId);
-    const res = await this.request(
-      'PUT',
-      `/_matrix/client/v3/rooms/${room}/send/m.room.message/${txn}`,
-      { userId, body: content },
-    );
-    return typeof res.event_id === 'string' ? res.event_id : undefined;
-  }
-
-  /** Set the agent's typing indicator in a room. */
-  async setTyping(
-    roomId: string,
-    agent: string,
-    typing: boolean,
-    timeoutMs = 30000,
-  ): Promise<void> {
-    const userId = await this.ensureRegistered(agent);
-    const room = encodeURIComponent(roomId);
-    const user = encodeURIComponent(userId);
-    await this.request('PUT', `/_matrix/client/v3/rooms/${room}/typing/${user}`, {
-      userId,
-      body: typing ? { typing: true, timeout: timeoutMs } : { typing: false },
-    });
-  }
-
-  /** Set display name for an agent's virtual user. */
-  async setDisplayName(agent: string, displayName: string): Promise<void> {
-    const userId = await this.ensureRegistered(agent);
-    const user = encodeURIComponent(userId);
-    await this.request('PUT', `/_matrix/client/v3/profile/${user}/displayname`, {
-      userId,
-      body: { displayname: displayName },
-    });
-  }
-}

packages/appservice/src/registration.ts

@@ -1,76 +0,0 @@
-import type { AppserviceConfig } from './types.js';
-
-export interface RegistrationOptions {
-  /** Unique appservice id in Synapse. Default: "mosaic-as". */
-  id?: string;
-  /** URL where Synapse reaches the appservice, e.g. http://mosaic-as:8008 */
-  url: string;
-  /** Alias namespace regex prefix. Default: "#mosaic-". */
-  aliasPrefix?: string;
-}
-
-const escapeRegex = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-
-/**
- * Build the Synapse appservice registration document (mosaic-as.yaml).
- * Deployment (infrastructure repo) serializes this to YAML and mounts it via
- * app_service_config_files.
- */
-export function buildRegistration(cfg: AppserviceConfig, options: RegistrationOptions) {
-  const prefix = cfg.userPrefix ?? 'agent-';
-  return {
-    id: options.id ?? 'mosaic-as',
-    url: options.url,
-    as_token: cfg.asToken,
-    hs_token: cfg.hsToken,
-    sender_localpart: cfg.senderLocalpart ?? 'mosaic-as',
-    rate_limited: false,
-    namespaces: {
-      users: [
-        {
-          regex: `@${escapeRegex(prefix)}.*:${escapeRegex(cfg.domain)}`,
-          exclusive: true,
-        },
-      ],
-      aliases: [
-        {
-          regex: `${escapeRegex(options.aliasPrefix ?? '#mosaic-')}.*:${escapeRegex(cfg.domain)}`,
-          exclusive: false,
-        },
-      ],
-      rooms: [],
-    },
-  };
-}
-
-const assertYamlSafe = (field: string, value: string): string => {
-  // Tokens/urls/ids are single-line opaque strings; control characters would
-  // let a crafted value terminate the scalar and inject YAML keys.
-  if (/[\r\n\x00-\x08\x0b-\x1f]/.test(value)) {
-    throw new Error(`registration field ${field} contains control characters`);
-  }
-  return value.replace(/'/g, "''");
-};
-
-/** Minimal YAML serialization for the flat registration document. */
-export function registrationToYaml(registration: ReturnType<typeof buildRegistration>): string {
-  const ns = registration.namespaces;
-  const nsBlock = (entries: Array<{ regex: string; exclusive: boolean }>): string =>
-    entries.length === 0
-      ? ' []'
-      : '\n' +
-        entries.map((e) => `    - regex: '${e.regex}'\n      exclusive: ${e.exclusive}`).join('\n');
-  return [
-    `id: '${assertYamlSafe('id', registration.id)}'`,
-    `url: '${assertYamlSafe('url', registration.url)}'`,
-    `as_token: '${assertYamlSafe('as_token', registration.as_token)}'`,
-    `hs_token: '${assertYamlSafe('hs_token', registration.hs_token)}'`,
-    `sender_localpart: '${assertYamlSafe('sender_localpart', registration.sender_localpart)}'`,
-    `rate_limited: ${registration.rate_limited}`,
-    'namespaces:',
-    `  users:${nsBlock(ns.users)}`,
-    `  aliases:${nsBlock(ns.aliases)}`,
-    `  rooms:${nsBlock(ns.rooms)}`,
-    '',
-  ].join('\n');
-}

packages/appservice/src/transactions.ts

@@ -1,89 +0,0 @@
-import { timingSafeEqual } from 'node:crypto';
-
-import type { EventHandler, HandlerResult, Transaction } from './types.js';
-
-const MAX_SEEN_TXN_IDS = 1000;
-
-function safeTokenCompare(presented: string | undefined, expected: string): boolean {
-  if (presented === undefined) return false;
-  const a = Buffer.from(presented);
-  const b = Buffer.from(expected);
-  if (a.length !== b.length) {
-    // Compare against a same-length dummy so length is not a timing oracle.
-    timingSafeEqual(a, Buffer.alloc(a.length));
-    return false;
-  }
-  return timingSafeEqual(a, b);
-}
-
-export interface TransactionHandlerOptions {
-  hsToken: string;
-  onEvent: EventHandler;
-  /** Called for handler errors; events are at-most-once, errors must not 500. */
-  onError?: (error: unknown, txnId: string) => void;
-}
-
-/**
- * Framework-agnostic handler for the Application Service transactions API
- * (PUT /_matrix/app/v1/transactions/{txnId}). Host apps (Fastify/Nest) wrap
- * this in a route.
- *
- * Spec requirements covered: hs_token verification (Authorization: Bearer,
- * with legacy ?access_token fallback), txnId idempotency, always-200 on
- * accepted transactions (homeserver retries on any other status).
- *
- * KNOWN LIMITATION: the txnId dedupe ring is in-process memory only. After a
- * restart the homeserver may redeliver pending transactions — event handlers
- * must be idempotent (delivery is at-least-once across process lifetimes).
- */
-export class TransactionHandler {
-  private readonly seen: string[] = [];
-  private readonly seenSet = new Set<string>();
-
-  constructor(private readonly options: TransactionHandlerOptions) {}
-
-  authorized(
-    authorizationHeader: string | undefined,
-    accessTokenParam: string | undefined,
-  ): boolean {
-    const bearer = authorizationHeader?.startsWith('Bearer ')
-      ? authorizationHeader.slice('Bearer '.length)
-      : undefined;
-    const presented = bearer ?? accessTokenParam;
-    return safeTokenCompare(presented, this.options.hsToken);
-  }
-
-  async handle(
-    txnId: string,
-    body: unknown,
-    auth: { authorizationHeader?: string; accessTokenParam?: string },
-  ): Promise<HandlerResult> {
-    if (!this.authorized(auth.authorizationHeader, auth.accessTokenParam)) {
-      return { status: 403, body: { errcode: 'M_FORBIDDEN', error: 'bad hs_token' } };
-    }
-    if (this.seenSet.has(txnId)) {
-      return { status: 200, body: {} };
-    }
-    this.markSeen(txnId);
-    const txn = (body ?? {}) as Partial<Transaction>;
-    for (const event of txn.events ?? []) {
-      try {
-        await this.options.onEvent(event);
-      } catch (error) {
-        // A failing handler must not fail the transaction: the homeserver
-        // would retry the whole batch forever.
-        this.options.onError?.(error, txnId);
-      }
-    }
-    return { status: 200, body: {} };
-  }
-
-  private markSeen(txnId: string): void {
-    this.seen.push(txnId);
-    this.seenSet.add(txnId);
-    while (this.seen.length > MAX_SEEN_TXN_IDS) {
-      const evicted = this.seen.shift();
-      if (evicted !== undefined) this.seenSet.delete(evicted);
-    }
-  }
-}

packages/appservice/src/types.ts

@@ -1,35 +0,0 @@
-export interface AppserviceConfig {
-  /** Homeserver client-server API base, e.g. https://chat.uscllc.com */
-  homeserverUrl: string;
-  /** Server name used in user IDs, e.g. chat.uscllc.com */
-  domain: string;
-  /** Token the appservice presents to the homeserver (as_token). */
-  asToken: string;
-  /** Token the homeserver presents to the appservice (hs_token). */
-  hsToken: string;
-  /** Localpart prefix owned by this appservice. Default: "agent-". */
-  userPrefix?: string;
-  /** The appservice's own sender user localpart. Default: "mosaic-as". */
-  senderLocalpart?: string;
-}
-
-export interface MatrixEvent {
-  type: string;
-  event_id?: string;
-  room_id?: string;
-  sender?: string;
-  state_key?: string;
-  content?: Record<string, unknown>;
-  origin_server_ts?: number;
-}
-
-export interface Transaction {
-  events: MatrixEvent[];
-}
-
-export type EventHandler = (event: MatrixEvent) => void | Promise<void>;
-
-export interface HandlerResult {
-  status: number;
-  body: Record<string, unknown>;
-}

packages/appservice/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "dist",
-    "rootDir": "src"
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}

packages/auth/src/index.ts

@@ -10,4 +10,3 @@ export {
   type SsoTeamSyncConfig,
   type SupportedSsoProviderId,
 } from './sso.js';
-export { seal, unseal } from './seal.js';

packages/auth/src/seal.ts

@@ -1,52 +0,0 @@
-import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
-
-const ALGORITHM = 'aes-256-gcm';
-const IV_LENGTH = 12; // 96-bit IV for GCM
-const TAG_LENGTH = 16; // 128-bit auth tag
-
-/**
- * Derive a 32-byte AES-256 key from BETTER_AUTH_SECRET using SHA-256.
- * Throws if BETTER_AUTH_SECRET is not set.
- */
-function deriveKey(): Buffer {
-  const secret = process.env['BETTER_AUTH_SECRET'];
-  if (!secret) {
-    throw new Error('BETTER_AUTH_SECRET is not set — cannot derive encryption key');
-  }
-  return createHash('sha256').update(secret).digest();
-}
-
-/**
- * Seal a plaintext string using AES-256-GCM.
- * Output format: base64(IV || authTag || ciphertext)
- */
-export function seal(plaintext: string): string {
-  const key = deriveKey();
-  const iv = randomBytes(IV_LENGTH);
-  const cipher = createCipheriv(ALGORITHM, key, iv);
-
-  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
-  const authTag = cipher.getAuthTag();
-
-  const combined = Buffer.concat([iv, authTag, encrypted]);
-  return combined.toString('base64');
-}
-
-/**
- * Unseal a value sealed by `seal()`.
- * Throws on authentication failure (tampered data) or if BETTER_AUTH_SECRET is unset.
- */
-export function unseal(encoded: string): string {
-  const key = deriveKey();
-  const combined = Buffer.from(encoded, 'base64');
-
-  const iv = combined.subarray(0, IV_LENGTH);
-  const authTag = combined.subarray(IV_LENGTH, IV_LENGTH + TAG_LENGTH);
-  const ciphertext = combined.subarray(IV_LENGTH + TAG_LENGTH);
-
-  const decipher = createDecipheriv(ALGORITHM, key, iv);
-  decipher.setAuthTag(authTag);
-
-  const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
-  return decrypted.toString('utf8');
-}

packages/db/drizzle/0009_federation_grant_pending.sql

@@ -1,2 +0,0 @@
-ALTER TYPE "public"."grant_status" ADD VALUE 'pending' BEFORE 'active';--> statement-breakpoint
-ALTER TABLE "federation_grants" ALTER COLUMN "status" SET DEFAULT 'pending';

packages/db/drizzle/0010_federation_enrollment_tokens.sql

@@ -1,11 +0,0 @@
-CREATE TABLE "federation_enrollment_tokens" (
-	"token" text PRIMARY KEY NOT NULL,
-	"grant_id" uuid NOT NULL,
-	"peer_id" uuid NOT NULL,
-	"expires_at" timestamp with time zone NOT NULL,
-	"used_at" timestamp with time zone,
-	"created_at" timestamp with time zone DEFAULT now() NOT NULL
-);
---> statement-breakpoint
-ALTER TABLE "federation_enrollment_tokens" ADD CONSTRAINT "federation_enrollment_tokens_grant_id_federation_grants_id_fk" FOREIGN KEY ("grant_id") REFERENCES "public"."federation_grants"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "federation_enrollment_tokens" ADD CONSTRAINT "federation_enrollment_tokens_peer_id_federation_peers_id_fk" FOREIGN KEY ("peer_id") REFERENCES "public"."federation_peers"("id") ON DELETE cascade ON UPDATE no action;

packages/db/drizzle/meta/_journal.json

@@ -64,20 +64,6 @@
       "when": 1776822435828,
       "tag": "0008_smart_lyja",
       "breakpoints": true
-    },
-    {
-      "idx": 9,
-      "version": "7",
-      "when": 1745280000000,
-      "tag": "0009_federation_grant_pending",
-      "breakpoints": true
-    },
-    {
-      "idx": 10,
-      "version": "7",
-      "when": 1745366400000,
-      "tag": "0010_federation_enrollment_tokens",
-      "breakpoints": true
     }
   ]
-}
+}

packages/db/package.json

@@ -42,7 +42,6 @@
     "access": "public"
   },
   "files": [
-    "dist",
+    "dist"
-    "drizzle"
   ]
 }

packages/db/src/client-pglite.ts

@@ -1,12 +1,10 @@
 import { PGlite } from '@electric-sql/pglite';
-import { vector } from '@electric-sql/pglite/vector';
 import { drizzle } from 'drizzle-orm/pglite';
 import * as schema from './schema.js';
 import type { DbHandle } from './client.js';
 
 export function createPgliteDb(dataDir: string): DbHandle {
-  // pgvector extension is required by migration 0001 (insights.embedding column).
+  const client = new PGlite(dataDir);
-  const client = new PGlite(dataDir, { extensions: { vector } });
   const db = drizzle(client, { schema });
   return {
     db: db as unknown as DbHandle['db'],

packages/db/src/federation.ts

@@ -17,5 +17,4 @@ export {
   federationPeers,
   federationGrants,
   federationAuditLog,
-  federationEnrollmentTokens,
 } from './schema.js';

packages/db/src/index.ts

@@ -1,6 +1,6 @@
 export { createDb, type Db, type DbHandle } from './client.js';
 export { createPgliteDb } from './client-pglite.js';
-export { runMigrations, runPgliteMigrations } from './migrate.js';
+export { runMigrations } from './migrate.js';
 export * from './schema.js';
 export * from './federation.js';
 export {

packages/db/src/migrate.test.ts

@@ -1,70 +0,0 @@
-import { mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { sql } from 'drizzle-orm';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { createPgliteDb } from './client-pglite.js';
-import { runPgliteMigrations } from './migrate.js';
-import type { DbHandle } from './client.js';
-
-interface PgliteExec {
-  exec(query: string): Promise<unknown>;
-}
-
-describe('runPgliteMigrations', () => {
-  let dataDir: string;
-  let handle: DbHandle;
-
-  beforeEach(() => {
-    dataDir = mkdtempSync(join(tmpdir(), 'mosaic-db-migrate-test-'));
-    handle = createPgliteDb(dataDir);
-  });
-
-  afterEach(async () => {
-    await handle.close();
-    rmSync(dataDir, { recursive: true, force: true });
-  });
-
-  it('creates the BetterAuth tables required by the gateway', async () => {
-    await runPgliteMigrations(handle);
-
-    const result = (await handle.db.execute(sql`
-      SELECT table_name FROM information_schema.tables
-      WHERE table_schema = 'public'
-      ORDER BY table_name
-    `)) as unknown as { rows: Array<{ table_name: string }> };
-
-    const tables = result.rows.map((r) => r.table_name);
-
-    // Auth tables — required for sign-in / bootstrap to function.
-    expect(tables).toContain('users');
-    expect(tables).toContain('sessions');
-    expect(tables).toContain('accounts');
-    expect(tables).toContain('verifications');
-
-    // Schema sanity check — admin token table consumed by mosaic gateway config.
-    expect(tables).toContain('admin_tokens');
-  });
-
-  it('is idempotent — running twice does not error', async () => {
-    await runPgliteMigrations(handle);
-    await expect(runPgliteMigrations(handle)).resolves.toBeUndefined();
-  });
-
-  it('surfaces statement-level error context on failure and leaves no ledger row', async () => {
-    // Pre-create a `users` table that conflicts with migration 0000's CREATE TABLE,
-    // forcing it to fail without IF NOT EXISTS.
-    const client = (handle.db as unknown as { $client: PgliteExec }).$client;
-    await client.exec('CREATE TABLE users (sentinel text)');
-
-    await expect(runPgliteMigrations(handle)).rejects.toThrow(
-      /migration hash=[a-f0-9]+ statement #\d+ failed/,
-    );
-
-    // Ledger should be empty — partial application must not pretend to be complete.
-    const ledger = (await handle.db.execute(
-      sql`SELECT count(*)::int AS count FROM drizzle.__drizzle_migrations`,
-    )) as unknown as { rows: Array<{ count: number }> };
-    expect(ledger.rows[0]?.count).toBe(0);
-  });
-});

packages/db/src/migrate.ts

@@ -1,109 +1,18 @@
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { sql } from 'drizzle-orm';
+import { drizzle } from 'drizzle-orm/postgres-js';
-import { drizzle as drizzlePostgres } from 'drizzle-orm/postgres-js';
+import { migrate } from 'drizzle-orm/postgres-js/migrator';
-import { migrate as migratePostgres } from 'drizzle-orm/postgres-js/migrator';
-import { readMigrationFiles } from 'drizzle-orm/migrator';
 import postgres from 'postgres';
 import { DEFAULT_DATABASE_URL } from './defaults.js';
-import type { DbHandle } from './client.js';
-
-interface PgliteExecutor {
-  exec(query: string): Promise<unknown>;
-}
-
-interface ExecuteRows<T> {
-  rows: T[];
-}
-
-function migrationsFolder(): string {
-  const here = dirname(fileURLToPath(import.meta.url));
-  return resolve(here, '../drizzle');
-}
 
 export async function runMigrations(url?: string): Promise<void> {
   const connectionString = url ?? process.env['DATABASE_URL'] ?? DEFAULT_DATABASE_URL;
-  const sqlClient = postgres(connectionString, { max: 1 });
+  const sql = postgres(connectionString, { max: 1 });
-  const db = drizzlePostgres(sqlClient);
+  const db = drizzle(sql);
+  const __dirname = dirname(fileURLToPath(import.meta.url));
   try {
-    // TODO: postgres-tier first-install also fails because (a) Drizzle wraps every
+    await migrate(db, { migrationsFolder: resolve(__dirname, '../drizzle') });
-    // migration in one transaction (breaks 0009's ALTER TYPE ADD VALUE → SET DEFAULT
-    // sequence) and (b) drizzle/meta/_journal.json has 0009 ordered before 0008,
-    // which the postgres-js migrator skips by `created_at < folderMillis`. The
-    // PGlite path below sidesteps both. A follow-up should either share the
-    // per-statement loop (see runPgliteMigrations) or fix the journal ordering.
-    await migratePostgres(db, { migrationsFolder: migrationsFolder() });
   } finally {
-    await sqlClient.end();
+    await sql.end();
-  }
-}
-
-// Apply Drizzle migrations against an embedded PGlite database.
-//
-// We don't reuse drizzle's pglite migrator because it wraps ALL migrations in
-// one outer transaction, which breaks Postgres' `check_safe_enum_use` rule —
-// e.g. migration 0009 does `ALTER TYPE ADD VALUE 'pending'` then references
-// `'pending'` as a default in the same tx. PGlite's `exec()` runs each
-// statement under the Simple Query protocol, autocommitting between them.
-//
-// We still write to the standard `drizzle.__drizzle_migrations` ledger so the
-// result is interoperable with `runMigrations()` on a postgres-backed deploy
-// (modulo the journal-ordering bug noted above).
-//
-// We skip-by-hash rather than skip-by-folderMillis (which is what Drizzle's
-// postgres-js migrator does). That's deliberate — out-of-order timestamps in
-// `_journal.json` won't silently drop migrations.
-//
-// Failure model: each statement autocommits, and the ledger row is written
-// only after all statements in a migration succeed. A crash mid-migration
-// leaves the prefix applied with no ledger entry, so the next boot will
-// replay those statements and fail loudly on "already exists". Recovery:
-// drop the partially-applied objects, or insert the migration's hash into
-// `drizzle.__drizzle_migrations` manually. The error log identifies which
-// statement of which migration was the culprit.
-export async function runPgliteMigrations(handle: DbHandle): Promise<void> {
-  const client = (handle.db as unknown as { $client?: PgliteExecutor }).$client;
-  if (!client || typeof client.exec !== 'function') {
-    throw new Error('runPgliteMigrations: handle.db is not backed by a PGlite client');
-  }
-
-  await client.exec('CREATE SCHEMA IF NOT EXISTS drizzle');
-  await client.exec(`
-    CREATE TABLE IF NOT EXISTS drizzle.__drizzle_migrations (
-      id SERIAL PRIMARY KEY,
-      hash text NOT NULL,
-      created_at bigint
-    )
-  `);
-
-  const appliedRows = (await handle.db.execute(
-    sql`SELECT hash FROM drizzle.__drizzle_migrations`,
-  )) as unknown as ExecuteRows<{ hash: string }>;
-  const applied = new Set(appliedRows.rows.map((r) => r.hash));
-
-  const migrations = readMigrationFiles({ migrationsFolder: migrationsFolder() });
-  for (const migration of migrations) {
-    if (applied.has(migration.hash)) continue;
-
-    // Run each statement-breakpoint chunk in its own exec() call so PGlite
-    // commits between statements — this is what lets `ALTER TYPE ADD VALUE`
-    // become visible before a subsequent statement references the new value.
-    for (const [stmtIdx, stmt] of migration.sql.entries()) {
-      const trimmed = stmt.trim();
-      if (!trimmed) continue;
-      try {
-        await client.exec(trimmed);
-      } catch (err) {
-        const cause = err instanceof Error ? err.message : String(err);
-        throw new Error(
-          `runPgliteMigrations: migration hash=${migration.hash} statement #${stmtIdx} failed: ${cause}\n` +
-            `Statement: ${trimmed.slice(0, 200)}${trimmed.length > 200 ? '…' : ''}`,
-          { cause: err },
-        );
-      }
-    }
-    await handle.db.execute(
-      sql`INSERT INTO drizzle.__drizzle_migrations (hash, created_at) VALUES (${migration.hash}, ${migration.folderMillis})`,
-    );
   }
 }

packages/db/src/schema.ts

@@ -604,12 +604,11 @@ export const peerStateEnum = pgEnum('peer_state', ['pending', 'active', 'suspend
 
 /**
  * Lifecycle state of a federation grant.
- * - pending: created but not yet activated (awaiting cert enrollment, M2-07)
  * - active:  grant is in effect
  * - revoked: manually revoked before expiry
  * - expired: natural expiry (expires_at passed)
  */
-export const grantStatusEnum = pgEnum('grant_status', ['pending', 'active', 'revoked', 'expired']);
+export const grantStatusEnum = pgEnum('grant_status', ['active', 'revoked', 'expired']);
 
 /**
  * A registered peer gateway identified by its Step-CA certificate CN.
@@ -697,7 +696,7 @@ export const federationGrants = pgTable(
     scope: jsonb('scope').notNull(),
 
     /** Current grant lifecycle state. */
-    status: grantStatusEnum('status').notNull().default('pending'),
+    status: grantStatusEnum('status').notNull().default('active'),
 
     /** Optional hard expiry. NULL means the grant does not expire automatically. */
     expiresAt: timestamp('expires_at', { withTimezone: true }),
@@ -778,34 +777,3 @@ export const federationAuditLog = pgTable(
     index('federation_audit_log_created_at_idx').on(t.createdAt.desc()),
   ],
 );
-
-/**
- * Single-use enrollment tokens — M2-07.
- *
- * An admin creates a token (with a TTL) and hands it out-of-band to the
- * remote peer operator.  The peer redeems it exactly once by posting its
- * CSR to POST /api/federation/enrollment/:token.  The token is atomically
- * marked as used to prevent replay attacks.
- */
-export const federationEnrollmentTokens = pgTable('federation_enrollment_tokens', {
-  /** 32-byte hex token — crypto.randomBytes(32).toString('hex') */
-  token: text('token').primaryKey(),
-
-  /** The federation grant this enrollment activates. */
-  grantId: uuid('grant_id')
-    .notNull()
-    .references(() => federationGrants.id, { onDelete: 'cascade' }),
-
-  /** The peer record that will be updated on successful enrollment. */
-  peerId: uuid('peer_id')
-    .notNull()
-    .references(() => federationPeers.id, { onDelete: 'cascade' }),
-
-  /** Hard expiry — token rejected after this time even if not used. */
-  expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
-
-  /** NULL until the token is redeemed.  Set atomically to prevent replay. */
-  usedAt: timestamp('used_at', { withTimezone: true }),
-
-  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
-});

packages/mosaic/framework/tools/_lib/credentials.sh

@@ -52,20 +52,6 @@ _mosaic_sync_woodpecker_env() {
   printf '%s\n' "$expected" > "$env_file"
 }
 
-# Load legacy flat Woodpecker credentials (.woodpecker.url / .woodpecker.token).
-# Some environments export WOODPECKER_INSTANCE=mosaic, but the current
-# credentials.json may still use the legacy flat schema. Treat "mosaic" as the
-# default flat instance when a nested .woodpecker.mosaic object is absent.
-_mosaic_load_woodpecker_legacy() {
-  export WOODPECKER_URL="$(_mosaic_read_cred '.woodpecker.url')"
-  export WOODPECKER_TOKEN="$(_mosaic_read_cred '.woodpecker.token')"
-  export WOODPECKER_INSTANCE="${WOODPECKER_INSTANCE:-mosaic}"
-  WOODPECKER_URL="${WOODPECKER_URL%/}"
-  [[ -n "$WOODPECKER_URL" ]] || { echo "Error: woodpecker.url not found" >&2; return 1; }
-  [[ -n "$WOODPECKER_TOKEN" ]] || { echo "Error: woodpecker.token not found" >&2; return 1; }
-  _mosaic_sync_woodpecker_env "$WOODPECKER_INSTANCE" "$WOODPECKER_URL" "$WOODPECKER_TOKEN"
-}
-
 load_credentials() {
   local service="$1"
 
@@ -169,14 +155,7 @@ EOF
       ;;
     woodpecker-*)
       local wp_instance="${service#woodpecker-}"
-      # credentials.json is authoritative — always read from it, ignore env.
+      # credentials.json is authoritative — always read from it, ignore env
-      # Backward compatibility: the default Mosaic Woodpecker instance may be
-      # stored in the legacy flat schema (.woodpecker.url/.token) instead of
-      # .woodpecker.mosaic.url/.token.
-      if [[ "$wp_instance" == "mosaic" ]] && [[ -z "$(_mosaic_read_cred '.woodpecker.mosaic.url')" ]] && [[ -n "$(_mosaic_read_cred '.woodpecker.url')" ]]; then
-        WOODPECKER_INSTANCE="mosaic" _mosaic_load_woodpecker_legacy
-        return $?
-      fi
       export WOODPECKER_URL="$(_mosaic_read_cred ".woodpecker.${wp_instance}.url")"
       export WOODPECKER_TOKEN="$(_mosaic_read_cred ".woodpecker.${wp_instance}.token")"
       export WOODPECKER_INSTANCE="$wp_instance"
@@ -187,10 +166,7 @@ EOF
       _mosaic_sync_woodpecker_env "$wp_instance" "$WOODPECKER_URL" "$WOODPECKER_TOKEN"
       ;;
     woodpecker)
-      # Resolve default instance, then load it. If WOODPECKER_INSTANCE is set to
+      # Resolve default instance, then load it
-      # "mosaic" by a shell/profile but credentials.json still uses the legacy
-      # flat .woodpecker.url/.token schema, load the flat credentials instead of
-      # failing with "woodpecker.mosaic.url not found".
       local wp_default
       wp_default="${WOODPECKER_INSTANCE:-$(_mosaic_read_cred '.woodpecker.default')}"
       if [[ -z "$wp_default" ]]; then
@@ -198,18 +174,18 @@ EOF
         local legacy_url
         legacy_url="$(_mosaic_read_cred '.woodpecker.url')"
         if [[ -n "$legacy_url" ]]; then
-          _mosaic_load_woodpecker_legacy
+          export WOODPECKER_URL="${WOODPECKER_URL:-$legacy_url}"
+          export WOODPECKER_TOKEN="${WOODPECKER_TOKEN:-$(_mosaic_read_cred '.woodpecker.token')}"
+          WOODPECKER_URL="${WOODPECKER_URL%/}"
+          [[ -n "$WOODPECKER_URL" ]] || { echo "Error: woodpecker.url not found" >&2; return 1; }
+          [[ -n "$WOODPECKER_TOKEN" ]] || { echo "Error: woodpecker.token not found" >&2; return 1; }
         else
           echo "Error: woodpecker.default not set and no WOODPECKER_INSTANCE env var" >&2
           echo "Available instances: $(jq -r '.woodpecker | keys | join(", ")' "$MOSAIC_CREDENTIALS_FILE" 2>/dev/null)" >&2
           return 1
         fi
       else
-        if [[ "$wp_default" == "mosaic" ]] && [[ -z "$(_mosaic_read_cred '.woodpecker.mosaic.url')" ]] && [[ -n "$(_mosaic_read_cred '.woodpecker.url')" ]]; then
+        load_credentials "woodpecker-${wp_default}"
-          WOODPECKER_INSTANCE="mosaic" _mosaic_load_woodpecker_legacy
-        else
-          load_credentials "woodpecker-${wp_default}"
-        fi
       fi
       ;;
     cloudflare-*)

packages/mosaic/framework/tools/git/ci-queue-wait.sh

@@ -137,7 +137,7 @@ gitea_get_branch_head_sha() {
     local branch="$3"
     local token="$4"
     local url="https://${host}/api/v1/repos/${repo}/branches/${branch}"
-    curl -fsSL -H "Authorization: token ${token}" "$url" | python3 -c '
+    curl -fsS -H "Authorization: token ${token}" "$url" | python3 -c '
 import json, sys
 data = json.load(sys.stdin)
 commit = data.get("commit") or {}
@@ -151,7 +151,7 @@ gitea_get_commit_status_json() {
     local sha="$3"
     local token="$4"
     local url="https://${host}/api/v1/repos/${repo}/commits/${sha}/status"
-    curl -fsSL -H "Authorization: token ${token}" "$url"
+    curl -fsS -H "Authorization: token ${token}" "$url"
 }
 
 while [[ $# -gt 0 ]]; do

packages/mosaic/framework/tools/git/detect-platform.sh

@@ -74,16 +74,6 @@ get_repo_name() {
     echo "${repo_info##*/}"
 }
 
-get_repo_slug() {
-    get_repo_info
-}
-
-get_gitea_repo_args() {
-    local repo
-    repo=$(get_repo_slug) || return 1
-    printf -- '--repo %q --login %q' "$repo" "${GITEA_LOGIN:-mosaicstack}"
-}
-
 get_remote_host() {
     local remote_url
     remote_url=$(git remote get-url origin 2>/dev/null || true)
@@ -113,28 +103,16 @@ get_gitea_token() {
     if [[ -f "$cred_loader" ]]; then
         local token
         token=$(
-            # shellcheck source=/dev/null
             source "$cred_loader"
-            # Host-specific wrapper resolution must not inherit caller/global GITEA_*.
-            # load_credentials intentionally preserves existing env vars for interactive use,
-            # but metadata/merge wrappers need credentials matching the remote host.
-            unset GITEA_TOKEN GITEA_URL
             case "$host" in
                 git.mosaicstack.dev) load_credentials gitea-mosaicstack 2>/dev/null ;;
                 git.uscllc.com)      load_credentials gitea-usc 2>/dev/null ;;
                 *)
-                    local matched=false
                     for svc in gitea-mosaicstack gitea-usc; do
-                        unset GITEA_TOKEN GITEA_URL
                         load_credentials "$svc" 2>/dev/null || continue
-                        if [[ "${GITEA_URL:-}" == "https://$host" || "${GITEA_URL:-}" == "http://$host" || "${GITEA_URL:-}" == *"//$host" ]]; then
+                        [[ "${GITEA_URL:-}" == *"$host"* ]] && break
-                            matched=true
-                            break
-                        fi
-                    done
-                    if [[ "$matched" != true ]]; then
                         unset GITEA_TOKEN GITEA_URL
-                    fi
+                    done
                     ;;
             esac
             echo "${GITEA_TOKEN:-}"
@@ -145,12 +123,10 @@ get_gitea_token() {
         fi
     fi
 
-    # 2. GITEA_TOKEN env var (only when GITEA_URL, if present, matches the remote host)
+    # 2. GITEA_TOKEN env var (may be set by caller)
     if [[ -n "${GITEA_TOKEN:-}" ]]; then
-        if [[ -z "${GITEA_URL:-}" || "${GITEA_URL:-}" == "https://$host" || "${GITEA_URL:-}" == "http://$host" || "${GITEA_URL:-}" == *"//$host" ]]; then
+        echo "$GITEA_TOKEN"
-            echo "$GITEA_TOKEN"
+        return 0
-            return 0
-        fi
     fi
 
     # 3. ~/.git-credentials file
@@ -167,37 +143,6 @@ get_gitea_token() {
     return 1
 }
 
-# Resolve HTTPS basic auth credentials for a Gitea host from ~/.git-credentials.
-# Prints "username:password" for direct curl -u consumption. Callers must not log it.
-get_gitea_basic_auth() {
-    local host="$1"
-    local creds="$HOME/.git-credentials"
-    if [[ ! -f "$creds" ]]; then
-        return 1
-    fi
-
-    python3 - "$host" "$creds" <<'PY'
-import sys
-from pathlib import Path
-from urllib.parse import unquote, urlparse
-
-host = sys.argv[1]
-creds = Path(sys.argv[2])
-
-for line in creds.read_text(encoding="utf-8").splitlines():
-    parsed = urlparse(line.strip())
-    if parsed.hostname != host:
-        continue
-    username = unquote(parsed.username or "")
-    password = unquote(parsed.password or "")
-    if username and password:
-        print(f"{username}:{password}")
-        raise SystemExit(0)
-
-raise SystemExit(1)
-PY
-}
-
 # If script is run directly (not sourced), output the platform
 if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
     detect_platform

packages/mosaic/framework/tools/git/issue-comment.sh

@@ -53,7 +53,7 @@ if [[ "$PLATFORM" == "github" ]]; then
     gh issue comment "$ISSUE_NUMBER" --body "$COMMENT"
     echo "Added comment to GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
-    tea issue comment "$ISSUE_NUMBER" "$COMMENT" $(get_gitea_repo_args)
+    tea issue comment "$ISSUE_NUMBER" "$COMMENT"
     echo "Added comment to Gitea issue #$ISSUE_NUMBER"
 else
     echo "Error: Unknown platform"

packages/mosaic/framework/tools/git/issue-create.sh

@@ -112,22 +112,20 @@ PLATFORM=$(detect_platform)
 
 case "$PLATFORM" in
     github)
-        CMD=(gh issue create --title "$TITLE")
+        CMD="gh issue create --title \"$TITLE\""
-        [[ -n "$BODY" ]] && CMD+=(--body "$BODY")
+        [[ -n "$BODY" ]] && CMD="$CMD --body \"$BODY\""
-        [[ -n "$LABELS" ]] && CMD+=(--label "$LABELS")
+        [[ -n "$LABELS" ]] && CMD="$CMD --label \"$LABELS\""
-        [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
+        [[ -n "$MILESTONE" ]] && CMD="$CMD --milestone \"$MILESTONE\""
-        "${CMD[@]}"
+        eval "$CMD"
         ;;
     gitea)
         if command -v tea >/dev/null 2>&1; then
-            REPO_SLUG=$(get_repo_slug)
+            CMD="tea issue create --title \"$TITLE\""
-            REPO_ARGS=(--repo "$REPO_SLUG" --login "${GITEA_LOGIN:-mosaicstack}")
+            [[ -n "$BODY" ]] && CMD="$CMD --description \"$BODY\""
-            CMD=(tea issue create "${REPO_ARGS[@]}" --title "$TITLE")
+            [[ -n "$LABELS" ]] && CMD="$CMD --labels \"$LABELS\""
-            [[ -n "$BODY" ]] && CMD+=(--description "$BODY")
-            [[ -n "$LABELS" ]] && CMD+=(--labels "$LABELS")
             # tea accepts milestone by name directly (verified 2026-02-05)
-            [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
+            [[ -n "$MILESTONE" ]] && CMD="$CMD --milestone \"$MILESTONE\""
-            if "${CMD[@]}"; then
+            if eval "$CMD"; then
                 exit 0
             fi
             echo "Warning: tea issue create failed, trying Gitea API fallback..." >&2

packages/mosaic/framework/tools/git/issue-list.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # issue-list.sh - List issues on Gitea or GitHub
-# Usage: issue-list.sh [-r owner/repo] [-s state] [-l label] [-m milestone] [-a assignee]
+# Usage: issue-list.sh [-s state] [-l label] [-m milestone] [-a assignee]
 
 set -e
 
@@ -13,7 +13,6 @@ LABEL=""
 MILESTONE=""
 ASSIGNEE=""
 LIMIT=100
-REPO_OVERRIDE=""
 
 usage() {
     cat <<EOF
@@ -27,14 +26,12 @@ Options:
     -m, --milestone NAME    Filter by milestone name
     -a, --assignee USER     Filter by assignee
     -n, --limit N           Maximum issues to show (default: 100)
-    -r, --repo OWNER/REPO   Repository slug (default: infer from git origin)
     -h, --help              Show this help message
 
 Examples:
     $(basename "$0")                          # List open issues
     $(basename "$0") -s all -l bug            # All issues with 'bug' label
     $(basename "$0") -m "0.2.0"               # Issues in milestone 0.2.0
-    $(basename "$0") --repo ddk/ai-bma         # List issues from anywhere
 EOF
     exit 1
 }
@@ -62,10 +59,6 @@ while [[ $# -gt 0 ]]; do
             LIMIT="$2"
             shift 2
             ;;
-        -r|--repo)
-            REPO_OVERRIDE="$2"
-            shift 2
-            ;;
         -h|--help)
             usage
             ;;
@@ -76,34 +69,25 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
-if [[ -n "$REPO_OVERRIDE" ]]; then
+PLATFORM=$(detect_platform)
-    REPO_INFO="$REPO_OVERRIDE"
-    PLATFORM=$(detect_platform 2>/dev/null || echo gitea)
-else
-    PLATFORM=$(detect_platform)
-    REPO_INFO=$(get_repo_info)
-fi
-
-if [[ -z "$REPO_INFO" || "$REPO_INFO" == error:* ]]; then
-    echo "Error: Could not determine repository from git origin. Run from a repo or pass --repo." >&2
-    exit 1
-fi
 
 case "$PLATFORM" in
     github)
-        CMD=(gh issue list --repo "$REPO_INFO" --state "$STATE" --limit "$LIMIT")
+        CMD="gh issue list --state $STATE --limit $LIMIT"
-        [[ -n "$LABEL" ]] && CMD+=(--label "$LABEL")
+        [[ -n "$LABEL" ]] && CMD="$CMD --label \"$LABEL\""
-        [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
+        [[ -n "$MILESTONE" ]] && CMD="$CMD --milestone \"$MILESTONE\""
-        [[ -n "$ASSIGNEE" ]] && CMD+=(--assignee "$ASSIGNEE")
+        [[ -n "$ASSIGNEE" ]] && CMD="$CMD --assignee \"$ASSIGNEE\""
-        "${CMD[@]}"
+        eval "$CMD"
         ;;
     gitea)
-        CMD=(tea issues list --repo "$REPO_INFO" --login "${GITEA_LOGIN:-mosaicstack}" --state "$STATE" --limit "$LIMIT")
+        CMD="tea issues list --state $STATE --limit $LIMIT"
-        [[ -n "$LABEL" ]] && CMD+=(--labels "$LABEL")
+        [[ -n "$LABEL" ]] && CMD="$CMD --labels \"$LABEL\""
-        [[ -n "$MILESTONE" ]] && CMD+=(--milestones "$MILESTONE")
+        [[ -n "$MILESTONE" ]] && CMD="$CMD --milestones \"$MILESTONE\""
-        # Note: tea may not support assignee filter directly in all versions.
+        # Note: tea may not support assignee filter directly
-        [[ -n "$ASSIGNEE" ]] && echo "Note: Assignee filtering may require manual review for Gitea" >&2
+        eval "$CMD"
-        "${CMD[@]}"
+        if [[ -n "$ASSIGNEE" ]]; then
+            echo "Note: Assignee filtering may require manual review for Gitea" >&2
+        fi
         ;;
     *)
         echo "Error: Could not detect git platform" >&2

packages/mosaic/framework/tools/git/issue-reopen.sh

@@ -52,9 +52,9 @@ if [[ "$PLATFORM" == "github" ]]; then
     echo "Reopened GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     if [[ -n "$COMMENT" ]]; then
-        tea issue comment "$ISSUE_NUMBER" "$COMMENT" $(get_gitea_repo_args)
+        tea issue comment "$ISSUE_NUMBER" "$COMMENT"
     fi
-    tea issue reopen "$ISSUE_NUMBER" $(get_gitea_repo_args)
+    tea issue reopen "$ISSUE_NUMBER"
     echo "Reopened Gitea issue #$ISSUE_NUMBER"
 else
     echo "Error: Unknown platform"

packages/mosaic/framework/tools/git/issue-view.sh

@@ -67,7 +67,7 @@ if [[ "$PLATFORM" == "github" ]]; then
     gh issue view "$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     if command -v tea >/dev/null 2>&1; then
-        if tea issue "$ISSUE_NUMBER" $(get_gitea_repo_args); then
+        if tea issue "$ISSUE_NUMBER"; then
             exit 0
         fi
         echo "Warning: tea issue view failed, trying Gitea API fallback..." >&2

packages/mosaic/framework/tools/git/pr-ci-wait.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # pr-ci-wait.sh - Wait for PR CI status to reach terminal state (GitHub/Gitea)
-# Usage: pr-ci-wait.sh -n <pr_number> [-r owner/repo] [-t timeout_sec] [-i interval_sec]
+# Usage: pr-ci-wait.sh -n <pr_number> [-t timeout_sec] [-i interval_sec]
 
 set -euo pipefail
 
@@ -10,7 +10,6 @@ source "$SCRIPT_DIR/detect-platform.sh"
 PR_NUMBER=""
 TIMEOUT_SEC=1800
 INTERVAL_SEC=15
-REPO_OVERRIDE=""
 
 usage() {
     cat <<EOF
@@ -18,14 +17,12 @@ Usage: $(basename "$0") -n <pr_number> [-t timeout_sec] [-i interval_sec]
 
 Options:
   -n, --number NUMBER      PR number (required)
-  -r, --repo OWNER/REPO    Repository slug (default: infer from git origin)
   -t, --timeout SECONDS    Max wait time in seconds (default: 1800)
   -i, --interval SECONDS   Poll interval in seconds (default: 15)
   -h, --help               Show this help
 
 Examples:
   $(basename "$0") -n 643
-  $(basename "$0") -n 643 --repo ddk/ai-bma
   $(basename "$0") -n 643 -t 900 -i 10
 EOF
 }
@@ -33,19 +30,12 @@ EOF
 # get_remote_host and get_gitea_token are provided by detect-platform.sh
 
 extract_state_from_status_json() {
-    # Capture piped JSON BEFORE invoking `python3 - <<PY`. The heredoc binds
+    python3 - <<'PY'
-    # stdin to the Python program text — so json.load(sys.stdin) inside would
-    # try to re-read stdin after `-` already consumed it for the program,
-    # yielding EOF and returning "unknown" every time. Pass payload via env.
-    local payload
-    payload=$(cat)
-    PR_CI_STATUS_JSON="$payload" python3 - <<'PY'
 import json
-import os
 import sys
 
 try:
-    payload = json.loads(os.environ.get("PR_CI_STATUS_JSON", ""))
+    payload = json.load(sys.stdin)
 except Exception:
     print("unknown")
     raise SystemExit(0)
@@ -76,16 +66,12 @@ PY
 }
 
 print_status_summary() {
-    # Same stdin-collision fix as extract_state_from_status_json above.
+    python3 - <<'PY'
-    local payload
-    payload=$(cat)
-    PR_CI_STATUS_JSON="$payload" python3 - <<'PY'
 import json
-import os
 import sys
 
 try:
-    payload = json.loads(os.environ.get("PR_CI_STATUS_JSON", ""))
+    payload = json.load(sys.stdin)
 except Exception:
     print("[pr-ci-wait] status payload unavailable")
     raise SystemExit(0)
@@ -109,7 +95,7 @@ PY
 }
 
 github_get_pr_head_sha() {
-    gh pr view "$PR_NUMBER" --repo "$OWNER/$REPO" --json headRefOid --jq '.headRefOid'
+    gh pr view "$PR_NUMBER" --json headRefOid --jq '.headRefOid'
 }
 
 github_get_commit_status_json() {
@@ -124,7 +110,7 @@ gitea_get_pr_head_sha() {
     local repo="$2"
     local token="$3"
     local url="https://${host}/api/v1/repos/${repo}/pulls/${PR_NUMBER}"
-    curl -fsSL -H "Authorization: token ${token}" "$url" | python3 -c '
+    curl -fsS -H "Authorization: token ${token}" "$url" | python3 -c '
 import json, sys
 data = json.load(sys.stdin)
 print((data.get("head") or {}).get("sha", ""))
@@ -137,7 +123,7 @@ gitea_get_commit_status_json() {
     local token="$3"
     local sha="$4"
     local url="https://${host}/api/v1/repos/${repo}/commits/${sha}/status"
-    curl -fsSL -H "Authorization: token ${token}" "$url"
+    curl -fsS -H "Authorization: token ${token}" "$url"
 }
 
 while [[ $# -gt 0 ]]; do
@@ -146,10 +132,6 @@ while [[ $# -gt 0 ]]; do
             PR_NUMBER="$2"
             shift 2
             ;;
-        -r|--repo)
-            REPO_OVERRIDE="$2"
-            shift 2
-            ;;
         -t|--timeout)
             TIMEOUT_SEC="$2"
             shift 2
@@ -181,21 +163,10 @@ if ! [[ "$TIMEOUT_SEC" =~ ^[0-9]+$ ]] || ! [[ "$INTERVAL_SEC" =~ ^[0-9]+$ ]]; th
     exit 1
 fi
 
-if [[ -n "$REPO_OVERRIDE" ]]; then
+detect_platform > /dev/null
-    REPO_INFO="$REPO_OVERRIDE"
-    PLATFORM=$(detect_platform 2>/dev/null || echo gitea)
-else
-    detect_platform > /dev/null
-    REPO_INFO=$(get_repo_info)
-fi
 
-if [[ -z "$REPO_INFO" || "$REPO_INFO" == error:* || "$REPO_INFO" != */* ]]; then
+OWNER=$(get_repo_owner)
-    echo "Error: Could not determine repository from git origin. Run from a repo or pass --repo owner/repo." >&2
+REPO=$(get_repo_name)
-    exit 1
-fi
-
-OWNER=${REPO_INFO%%/*}
-REPO=${REPO_INFO##*/}
 START_TS=$(date +%s)
 DEADLINE_TS=$((START_TS + TIMEOUT_SEC))
 
@@ -211,7 +182,10 @@ if [[ "$PLATFORM" == "github" ]]; then
     fi
     echo "[pr-ci-wait] Platform=github PR=#${PR_NUMBER} head_sha=${HEAD_SHA}"
 elif [[ "$PLATFORM" == "gitea" ]]; then
-    HOST=$(get_remote_host 2>/dev/null || echo "git.mosaicstack.dev")
+    HOST=$(get_remote_host) || {
+        echo "Error: Could not determine remote host." >&2
+        exit 1
+    }
     TOKEN=$(get_gitea_token "$HOST") || {
         echo "Error: Gitea token not found. Set GITEA_TOKEN or configure ~/.git-credentials." >&2
         exit 1
@@ -221,7 +195,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
         echo "Error: Could not resolve head SHA for PR #$PR_NUMBER." >&2
         exit 1
     fi
-    echo "[pr-ci-wait] Platform=gitea host=${HOST} repo=${OWNER}/${REPO} PR=#${PR_NUMBER} head_sha=${HEAD_SHA}"
+    echo "[pr-ci-wait] Platform=gitea host=${HOST} PR=#${PR_NUMBER} head_sha=${HEAD_SHA}"
 else
     echo "Error: Unsupported platform '${PLATFORM}'." >&2
     exit 1

packages/mosaic/framework/tools/git/pr-close.sh

@@ -52,9 +52,9 @@ if [[ "$PLATFORM" == "github" ]]; then
     echo "Closed GitHub PR #$PR_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     if [[ -n "$COMMENT" ]]; then
-        tea pr comment "$PR_NUMBER" "$COMMENT" $(get_gitea_repo_args)
+        tea pr comment "$PR_NUMBER" "$COMMENT"
     fi
-    tea pr close "$PR_NUMBER" $(get_gitea_repo_args)
+    tea pr close "$PR_NUMBER"
     echo "Closed Gitea PR #$PR_NUMBER"
 else
     echo "Error: Unknown platform"

packages/mosaic/framework/tools/git/pr-create.sh

@@ -17,51 +17,6 @@ MILESTONE=""
 DRAFT=false
 ISSUE=""
 
-# get_remote_host, get_gitea_token, get_repo_info, and get_gitea_repo_args are provided by detect-platform.sh
-
-gitea_pr_create_api() {
-    local host repo token url payload
-    host=$(get_remote_host) || {
-        echo "Error: could not determine remote host for API fallback" >&2
-        return 1
-    }
-    repo=$(get_repo_info) || {
-        echo "Error: could not determine repo owner/name for API fallback" >&2
-        return 1
-    }
-    token=$(get_gitea_token "$host") || {
-        echo "Error: Gitea token not found for API fallback (set GITEA_TOKEN or configure ~/.git-credentials)" >&2
-        return 1
-    }
-
-    if [[ -n "$LABELS" || -n "$MILESTONE" || "$DRAFT" == true ]]; then
-        echo "Warning: API fallback applies title/body/head/base only; labels/milestone/draft require authenticated tea setup." >&2
-    fi
-
-    payload=$(TITLE="$TITLE" BODY="$BODY" HEAD_BRANCH="$HEAD_BRANCH" BASE_BRANCH="$BASE_BRANCH" python3 - <<'PY'
-import json
-import os
-
-payload = {
-    "title": os.environ["TITLE"],
-    "head": os.environ["HEAD_BRANCH"],
-    "base": os.environ["BASE_BRANCH"] or "main",
-}
-body = os.environ.get("BODY", "")
-if body:
-    payload["body"] = body
-print(json.dumps(payload))
-PY
-)
-
-    url="https://${host}/api/v1/repos/${repo}/pulls"
-    curl -fsS -X POST \
-      -H "Authorization: token ${token}" \
-      -H "Content-Type: application/json" \
-      -d "$payload" \
-      "$url"
-}
-
 usage() {
     cat <<EOF
 Usage: $(basename "$0") [OPTIONS]
@@ -163,37 +118,33 @@ PLATFORM=$(detect_platform)
 
 case "$PLATFORM" in
     github)
-        CMD=(gh pr create --title "$TITLE")
+        CMD="gh pr create --title \"$TITLE\""
-        [[ -n "$BODY" ]] && CMD+=(--body "$BODY")
+        [[ -n "$BODY" ]] && CMD="$CMD --body \"$BODY\""
-        [[ -n "$BASE_BRANCH" ]] && CMD+=(--base "$BASE_BRANCH")
+        [[ -n "$BASE_BRANCH" ]] && CMD="$CMD --base \"$BASE_BRANCH\""
-        [[ -n "$HEAD_BRANCH" ]] && CMD+=(--head "$HEAD_BRANCH")
+        [[ -n "$HEAD_BRANCH" ]] && CMD="$CMD --head \"$HEAD_BRANCH\""
-        [[ -n "$LABELS" ]] && CMD+=(--label "$LABELS")
+        [[ -n "$LABELS" ]] && CMD="$CMD --label \"$LABELS\""
-        [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
+        [[ -n "$MILESTONE" ]] && CMD="$CMD --milestone \"$MILESTONE\""
-        [[ "$DRAFT" == true ]] && CMD+=(--draft)
+        [[ "$DRAFT" == true ]] && CMD="$CMD --draft"
-        "${CMD[@]}"
+        eval "$CMD"
         ;;
     gitea)
-        # tea pull create syntax. Always pass --repo because tea repo inference
+        # tea pull create syntax
-        # is unreliable in Mosaic worktrees/profile shells. Use arrays instead
+        CMD="tea pr create --title \"$TITLE\""
-        # of eval so markdown backticks/body content are not shell-executed.
+        [[ -n "$BODY" ]] && CMD="$CMD --description \"$BODY\""
-        REPO_SLUG=$(get_repo_slug)
+        [[ -n "$BASE_BRANCH" ]] && CMD="$CMD --base \"$BASE_BRANCH\""
-        REPO_ARGS=(--repo "$REPO_SLUG" --login "${GITEA_LOGIN:-mosaicstack}")
+        [[ -n "$HEAD_BRANCH" ]] && CMD="$CMD --head \"$HEAD_BRANCH\""
-        CMD=(tea pr create "${REPO_ARGS[@]}" --title "$TITLE")
-        [[ -n "$BODY" ]] && CMD+=(--description "$BODY")
-        [[ -n "$BASE_BRANCH" ]] && CMD+=(--base "$BASE_BRANCH")
-        [[ -n "$HEAD_BRANCH" ]] && CMD+=(--head "$HEAD_BRANCH")
 
         # Handle labels for tea
         if [[ -n "$LABELS" ]]; then
             # tea may use --labels flag
-            CMD+=(--labels "$LABELS")
+            CMD="$CMD --labels \"$LABELS\""
         fi
 
         # Handle milestone for tea
         if [[ -n "$MILESTONE" ]]; then
-            MILESTONE_ID=$(tea milestones list "${REPO_ARGS[@]}" 2>/dev/null | grep -E "^\s*[0-9]+" | grep "$MILESTONE" | awk '{print $1}' | head -1)
+            MILESTONE_ID=$(tea milestones list 2>/dev/null | grep -E "^\s*[0-9]+" | grep "$MILESTONE" | awk '{print $1}' | head -1)
             if [[ -n "$MILESTONE_ID" ]]; then
-                CMD+=(--milestone "$MILESTONE_ID")
+                CMD="$CMD --milestone $MILESTONE_ID"
             else
                 echo "Warning: Could not find milestone '$MILESTONE', creating without milestone" >&2
             fi
@@ -204,11 +155,7 @@ case "$PLATFORM" in
             echo "Note: Draft PR may not be supported by your tea version" >&2
         fi
 
-        if "${CMD[@]}"; then
+        eval "$CMD"
-            exit 0
-        fi
-        echo "Warning: tea pr create failed, trying Gitea API fallback..." >&2
-        gitea_pr_create_api
         ;;
     *)
         echo "Error: Could not detect git platform" >&2

packages/mosaic/framework/tools/git/pr-diff.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # pr-diff.sh - Get the diff for a pull request on GitHub or Gitea
-# Usage: pr-diff.sh -n <pr_number> [-r owner/repo] [-o <output_file>]
+# Usage: pr-diff.sh -n <pr_number> [-o <output_file>]
 
 set -e
 
@@ -10,7 +10,6 @@ source "$SCRIPT_DIR/detect-platform.sh"
 # Parse arguments
 PR_NUMBER=""
 OUTPUT_FILE=""
-REPO_OVERRIDE=""
 
 while [[ $# -gt 0 ]]; do
     case $1 in
@@ -22,16 +21,11 @@ while [[ $# -gt 0 ]]; do
             OUTPUT_FILE="$2"
             shift 2
             ;;
-        -r|--repo)
-            REPO_OVERRIDE="$2"
-            shift 2
-            ;;
         -h|--help)
-            echo "Usage: pr-diff.sh -n <pr_number> [-r owner/repo] [-o <output_file>]"
+            echo "Usage: pr-diff.sh -n <pr_number> [-o <output_file>]"
             echo ""
             echo "Options:"
             echo "  -n, --number   PR number (required)"
-            echo "  -r, --repo     Repository slug (default: infer from git origin)"
             echo "  -o, --output   Output file (optional, prints to stdout if omitted)"
             echo "  -h, --help     Show this help"
             exit 0
@@ -48,30 +42,31 @@ if [[ -z "$PR_NUMBER" ]]; then
     exit 1
 fi
 
-if [[ -n "$REPO_OVERRIDE" ]]; then
+detect_platform > /dev/null
-    REPO_INFO="$REPO_OVERRIDE"
-    PLATFORM=$(detect_platform 2>/dev/null || echo gitea)
-else
-    detect_platform > /dev/null
-    REPO_INFO=$(get_repo_info)
-fi
-
-if [[ -z "$REPO_INFO" || "$REPO_INFO" == error:* ]]; then
-    echo "Error: Could not determine repository from git origin. Run from a repo or pass --repo." >&2
-    exit 1
-fi
 
 if [[ "$PLATFORM" == "github" ]]; then
     if [[ -n "$OUTPUT_FILE" ]]; then
-        gh pr diff "$PR_NUMBER" --repo "$REPO_INFO" > "$OUTPUT_FILE"
+        gh pr diff "$PR_NUMBER" > "$OUTPUT_FILE"
     else
-        gh pr diff "$PR_NUMBER" --repo "$REPO_INFO"
+        gh pr diff "$PR_NUMBER"
     fi
 elif [[ "$PLATFORM" == "gitea" ]]; then
     # tea doesn't have a direct diff command — use the API
-    HOST=$(get_remote_host 2>/dev/null || echo "git.mosaicstack.dev")
+    OWNER=$(get_repo_owner)
+    REPO=$(get_repo_name)
+    REMOTE_URL=$(git remote get-url origin 2>/dev/null)
 
-    DIFF_URL="https://${HOST}/api/v1/repos/${REPO_INFO}/pulls/${PR_NUMBER}.diff"
+    # Extract host from remote URL
+    if [[ "$REMOTE_URL" == https://* ]]; then
+        HOST=$(echo "$REMOTE_URL" | sed -E 's|https://([^/]+)/.*|\1|')
+    elif [[ "$REMOTE_URL" == git@* ]]; then
+        HOST=$(echo "$REMOTE_URL" | sed -E 's|git@([^:]+):.*|\1|')
+    else
+        echo "Error: Cannot determine host from remote URL" >&2
+        exit 1
+    fi
+
+    DIFF_URL="https://${HOST}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}.diff"
 
     GITEA_API_TOKEN=$(get_gitea_token "$HOST" || true)
 

packages/mosaic/framework/tools/git/pr-list.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # pr-list.sh - List pull requests on Gitea or GitHub
-# Usage: pr-list.sh [-r owner/repo] [-s state] [-l label] [-a author]
+# Usage: pr-list.sh [-s state] [-l label] [-a author]
 
 set -e
 
@@ -12,7 +12,6 @@ STATE="open"
 LABEL=""
 AUTHOR=""
 LIMIT=100
-REPO_OVERRIDE=""
 
 usage() {
     cat <<EOF
@@ -25,14 +24,12 @@ Options:
     -l, --label LABEL       Filter by label
     -a, --author USER       Filter by author
     -n, --limit N           Maximum PRs to show (default: 100)
-    -r, --repo OWNER/REPO   Repository slug (default: infer from git origin)
     -h, --help              Show this help message
 
 Examples:
     $(basename "$0")                          # List open PRs
     $(basename "$0") -s all                   # All PRs
     $(basename "$0") -s merged -a username    # Merged PRs by user
-    $(basename "$0") --repo ddk/ai-bma         # List PRs from anywhere
 EOF
     exit 1
 }
@@ -56,10 +53,6 @@ while [[ $# -gt 0 ]]; do
             LIMIT="$2"
             shift 2
             ;;
-        -r|--repo)
-            REPO_OVERRIDE="$2"
-            shift 2
-            ;;
         -h|--help)
             usage
             ;;
@@ -70,30 +63,18 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
-if [[ -n "$REPO_OVERRIDE" ]]; then
+PLATFORM=$(detect_platform)
-    REPO_INFO="$REPO_OVERRIDE"
-    # Explicit --repo is primarily for Gitea wrappers; if a git origin is present,
-    # still honor GitHub detection for cross-platform behavior.
-    PLATFORM=$(detect_platform 2>/dev/null || echo gitea)
-else
-    PLATFORM=$(detect_platform)
-    REPO_INFO=$(get_repo_info)
-fi
-
-if [[ -z "$REPO_INFO" || "$REPO_INFO" == error:* ]]; then
-    echo "Error: Could not determine repository from git origin. Run from a repo or pass --repo." >&2
-    exit 1
-fi
 
 case "$PLATFORM" in
     github)
-        CMD=(gh pr list --repo "$REPO_INFO" --state "$STATE" --limit "$LIMIT")
+        CMD="gh pr list --state $STATE --limit $LIMIT"
-        [[ -n "$LABEL" ]] && CMD+=(--label "$LABEL")
+        [[ -n "$LABEL" ]] && CMD="$CMD --label \"$LABEL\""
-        [[ -n "$AUTHOR" ]] && CMD+=(--author "$AUTHOR")
+        [[ -n "$AUTHOR" ]] && CMD="$CMD --author \"$AUTHOR\""
-        "${CMD[@]}"
+        eval "$CMD"
         ;;
     gitea)
-        CMD=(tea pr list --repo "$REPO_INFO" --login "${GITEA_LOGIN:-mosaicstack}" --state "$STATE" --limit "$LIMIT")
+        # tea pr list - note: tea uses 'pulls' subcommand in some versions
+        CMD="tea pr list --state $STATE --limit $LIMIT"
 
         # tea filtering may be limited
         if [[ -n "$LABEL" ]]; then
@@ -103,7 +84,7 @@ case "$PLATFORM" in
             echo "Note: Author filtering may require manual review for Gitea" >&2
         fi
 
-        "${CMD[@]}"
+        eval "$CMD"
         ;;
     *)
         echo "Error: Could not detect git platform" >&2

packages/mosaic/framework/tools/git/pr-merge.sh

@@ -2,10 +2,9 @@
 # pr-merge.sh - Merge pull requests on Gitea or GitHub
 # Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d] [--skip-queue-guard]
 
-set -euo pipefail
+set -e
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=packages/mosaic/framework/tools/git/detect-platform.sh
 source "$SCRIPT_DIR/detect-platform.sh"
 
 # Default values
@@ -13,7 +12,6 @@ PR_NUMBER=""
 MERGE_METHOD="squash"
 DELETE_BRANCH=false
 SKIP_QUEUE_GUARD=false
-DRY_RUN=false
 
 usage() {
     cat <<EOF
@@ -26,7 +24,6 @@ Options:
     -m, --method METHOD     Merge method: squash only (default: squash)
     -d, --delete-branch     Delete the head branch after merge
         --skip-queue-guard  Skip CI queue guard wait before merge
-        --dry-run           Run metadata/login preflight without merging
     -h, --help              Show this help message
 
 Examples:
@@ -57,11 +54,6 @@ while [[ $# -gt 0 ]]; do
             SKIP_QUEUE_GUARD=true
             shift
             ;;
-        --dry-run)
-            DRY_RUN=true
-            SKIP_QUEUE_GUARD=true
-            shift
-            ;;
         -h|--help)
             usage
             ;;
@@ -77,18 +69,12 @@ if [[ -z "$PR_NUMBER" ]]; then
     usage
 fi
 
-if [[ ! "$PR_NUMBER" =~ ^[0-9]+$ ]]; then
-    echo "Error: Invalid PR number '$PR_NUMBER'. PR number must contain digits only." >&2
-    exit 1
-fi
-
 if [[ "$MERGE_METHOD" != "squash" ]]; then
     echo "Error: Mosaic policy enforces squash merge only. Received '$MERGE_METHOD'." >&2
     exit 1
 fi
 
-PR_METADATA="$("$SCRIPT_DIR/pr-metadata.sh" -n "$PR_NUMBER")"
+BASE_BRANCH="$("$SCRIPT_DIR/pr-metadata.sh" -n "$PR_NUMBER" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("baseRefName") or "").strip())')"
-BASE_BRANCH="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("baseRefName") or "").strip())')"
 if [[ "$BASE_BRANCH" != "main" ]]; then
     echo "Error: Mosaic policy allows merges only for PRs targeting 'main' (found '$BASE_BRANCH')." >&2
     exit 1
@@ -106,163 +92,21 @@ PLATFORM=$(detect_platform)
 OWNER=$(get_repo_owner)
 REPO=$(get_repo_name)
 
-find_tea_login_for_host() {
-    local host="$1"
-    local logins_json
-
-    command -v tea >/dev/null 2>&1 || return 1
-    logins_json=$(tea login list --output json 2>/dev/null) || return 1
-    TEA_LOGINS_JSON="$logins_json" python3 - "$host" <<'PY'
-import json
-import os
-import sys
-
-host = sys.argv[1]
-try:
-    logins = json.loads(os.environ.get("TEA_LOGINS_JSON", "[]"))
-except Exception:
-    raise SystemExit(1)
-
-for login in logins if isinstance(logins, list) else []:
-    url = str(login.get("url") or login.get("URL") or "")
-    name = str(login.get("name") or login.get("Name") or "")
-    if url.rstrip("/").endswith(host) and name:
-        print(name)
-        raise SystemExit(0)
-
-raise SystemExit(1)
-PY
-}
-
-is_known_tea_empty_identity_failure() {
-    local error_file="$1"
-
-    python3 - "$error_file" <<'PY'
-import re
-import sys
-
-with open(sys.argv[1], encoding="utf-8", errors="replace") as handle:
-    error = handle.read()
-
-known_empty_identity = re.search(
-    r"user does not exist.*\[.*uid:\s*0,\s*name:\s*\]",
-    error,
-    flags=re.IGNORECASE | re.DOTALL,
-)
-raise SystemExit(0 if known_empty_identity else 1)
-PY
-}
-
-merge_gitea_with_api() {
-    local host="$1" api_url token basic_auth body_file raw_code payload
-    api_url="https://${host}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}/merge"
-    mkdir -p "${AGENT_WORK_ROOT:-/home/hermes/agent-work}"
-    body_file=$(mktemp "${AGENT_WORK_ROOT:-/home/hermes/agent-work}/pr-merge-api-response.XXXXXX")
-    payload='{"Do":"squash"}'
-
-    token=$(get_gitea_token "$host" || true)
-    if [[ -n "$token" ]]; then
-        raw_code=$(curl -sS -w '%{http_code}' -o "$body_file" \
-            -X POST \
-            -H "Authorization: token $token" \
-            -H 'Content-Type: application/json' \
-            -d "$payload" \
-            "$api_url" || true)
-        if [[ "$raw_code" =~ ^2 ]]; then
-            rm -f "$body_file"
-            return 0
-        fi
-    fi
-
-    basic_auth=$(get_gitea_basic_auth "$host" || true)
-    if [[ -n "$basic_auth" ]]; then
-        raw_code=$(curl -sS -w '%{http_code}' -o "$body_file" \
-            -X POST \
-            -u "$basic_auth" \
-            -H 'Content-Type: application/json' \
-            -d "$payload" \
-            "$api_url" || true)
-        if [[ "$raw_code" =~ ^2 ]]; then
-            rm -f "$body_file"
-            return 0
-        fi
-    fi
-
-    python3 - "${raw_code:-000}" "$body_file" <<'PY' >&2
-import json
-import sys
-code, path = sys.argv[1], sys.argv[2]
-try:
-    with open(path, encoding="utf-8", errors="replace") as handle:
-        raw = handle.read(500)
-    data = json.loads(raw) if raw else {}
-    message = data.get("message") or data.get("error") or raw or "empty response"
-except Exception:
-    try:
-        message = open(path, encoding="utf-8", errors="replace").read(500) or "empty response"
-    except Exception:
-        message = "unreadable response"
-print(f"Error: Gitea API merge failed with HTTP {code}: {message}")
-PY
-    rm -f "$body_file"
-    return 1
-}
-
-if [[ "$DRY_RUN" == true ]]; then
-    if [[ "$PLATFORM" == "gitea" ]]; then
-        HOST=$(get_remote_host) || {
-            echo "Error: Cannot determine host from origin remote URL" >&2
-            exit 1
-        }
-        TEA_LOGIN="${GITEA_LOGIN:-$(find_tea_login_for_host "$HOST" || true)}"
-        if [[ -n "$TEA_LOGIN" ]]; then
-            echo "Dry run: would merge PR #$PR_NUMBER on $HOST with tea login '$TEA_LOGIN' (base=$BASE_BRANCH, method=squash)."
-        else
-            echo "Dry run: would merge PR #$PR_NUMBER on $HOST with authenticated Gitea API fallback (base=$BASE_BRANCH, method=squash)."
-        fi
-    else
-        echo "Dry run: would merge PR #$PR_NUMBER on $PLATFORM (base=$BASE_BRANCH, method=squash)."
-    fi
-    exit 0
-fi
-
 case "$PLATFORM" in
     github)
-        cmd=(gh pr merge "$PR_NUMBER" --squash)
+        CMD="gh pr merge $PR_NUMBER --squash"
-        [[ "$DELETE_BRANCH" == true ]] && cmd+=(--delete-branch)
+        [[ "$DELETE_BRANCH" == true ]] && CMD="$CMD --delete-branch"
-        "${cmd[@]}"
+        eval "$CMD"
         ;;
     gitea)
-        HOST=$(get_remote_host) || {
+        CMD="tea pr merge $PR_NUMBER --style squash --repo $OWNER/$REPO --login ${GITEA_LOGIN:-mosaicstack}"
-            echo "Error: Cannot determine host from origin remote URL" >&2
-            exit 1
-        }
-        TEA_LOGIN="${GITEA_LOGIN:-$(find_tea_login_for_host "$HOST" || true)}"
-
-        if [[ -n "$TEA_LOGIN" ]]; then
-            mkdir -p "${AGENT_WORK_ROOT:-/home/hermes/agent-work}"
-            TEA_ERROR_FILE=$(mktemp "${AGENT_WORK_ROOT:-/home/hermes/agent-work}/pr-merge-tea-error.XXXXXX")
-            if tea pr merge "$PR_NUMBER" --style squash --repo "$OWNER/$REPO" --login "$TEA_LOGIN" 2> "$TEA_ERROR_FILE"; then
-                rm -f "$TEA_ERROR_FILE"
-            elif is_known_tea_empty_identity_failure "$TEA_ERROR_FILE"; then
-                cat "$TEA_ERROR_FILE" >&2
-                echo "Known tea empty identity failure detected; using authenticated Gitea API merge fallback." >&2
-                rm -f "$TEA_ERROR_FILE"
-                merge_gitea_with_api "$HOST"
-            else
-                cat "$TEA_ERROR_FILE" >&2
-                rm -f "$TEA_ERROR_FILE"
-                exit 1
-            fi
-        else
-            echo "No tea login configured for $HOST; using authenticated Gitea API merge fallback." >&2
-            merge_gitea_with_api "$HOST"
-        fi
 
         # Delete branch after merge if requested
         if [[ "$DELETE_BRANCH" == true ]]; then
             echo "Note: Branch deletion after merge may need to be done separately with tea" >&2
         fi
+
+        eval "$CMD"
         ;;
     *)
         echo "Error: Could not detect git platform" >&2

packages/mosaic/framework/tools/git/pr-metadata.sh

@@ -2,10 +2,9 @@
 # pr-metadata.sh - Get PR metadata as JSON on GitHub or Gitea
 # Usage: pr-metadata.sh -n <pr_number> [-o <output_file>]
 
-set -euo pipefail
+set -e
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=packages/mosaic/framework/tools/git/detect-platform.sh
 source "$SCRIPT_DIR/detect-platform.sh"
 
 # Parse arguments
@@ -32,7 +31,7 @@ while [[ $# -gt 0 ]]; do
             exit 0
             ;;
         *)
-            echo "Unknown option: $1" >&2
+            echo "Unknown option: $1"
             exit 1
             ;;
     esac
@@ -43,168 +42,56 @@ if [[ -z "$PR_NUMBER" ]]; then
     exit 1
 fi
 
-write_metadata() {
-    local metadata="$1"
-    if [[ -n "$OUTPUT_FILE" ]]; then
-        printf '%s\n' "$metadata" > "$OUTPUT_FILE"
-    else
-        printf '%s\n' "$metadata"
-    fi
-}
-
-curl_gitea_pull() {
-    local api_url="$1"
-    local token basic_auth raw_code body_file http_code
-    body_file=$(mktemp)
-
-    token=$(get_gitea_token "$HOST" || true)
-    if [[ -n "$token" ]]; then
-        raw_code=$(curl -sS -w '%{http_code}' -o "$body_file" -H "Authorization: token $token" "$api_url" || true)
-        if [[ "$raw_code" =~ ^2 ]]; then
-            cat "$body_file"
-            rm -f "$body_file"
-            return 0
-        fi
-        http_code="$raw_code"
-    fi
-
-    basic_auth=$(get_gitea_basic_auth "$HOST" || true)
-    if [[ -n "$basic_auth" ]]; then
-        raw_code=$(curl -sS -w '%{http_code}' -o "$body_file" -u "$basic_auth" "$api_url" || true)
-        if [[ "$raw_code" =~ ^2 ]]; then
-            cat "$body_file"
-            rm -f "$body_file"
-            return 0
-        fi
-        http_code="$raw_code"
-    fi
-
-    if [[ -z "${http_code:-}" ]]; then
-        raw_code=$(curl -sS -w '%{http_code}' -o "$body_file" "$api_url" || true)
-        http_code="$raw_code"
-    fi
-
-    python3 - "$http_code" "$body_file" <<'PY' >&2
-import json
-import sys
-
-code, path = sys.argv[1], sys.argv[2]
-try:
-    data = json.load(open(path, encoding="utf-8"))
-    message = data.get("message") or data.get("error") or "unknown API error"
-except Exception:
-    message = open(path, encoding="utf-8", errors="replace").read()[:200] or "empty response"
-print(f"Error: Gitea pull request API request failed with HTTP {code}: {message}")
-PY
-    rm -f "$body_file"
-    return 1
-}
-
 detect_platform > /dev/null
 
 if [[ "$PLATFORM" == "github" ]]; then
     METADATA=$(gh pr view "$PR_NUMBER" --json number,title,body,state,author,headRefName,baseRefName,files,labels,assignees,milestone,createdAt,updatedAt,url,isDraft)
-    write_metadata "$METADATA"
+
+    if [[ -n "$OUTPUT_FILE" ]]; then
+        echo "$METADATA" > "$OUTPUT_FILE"
+    else
+        echo "$METADATA"
+    fi
 elif [[ "$PLATFORM" == "gitea" ]]; then
     OWNER=$(get_repo_owner)
     REPO=$(get_repo_name)
-    HOST=$(get_remote_host) || {
+    REMOTE_URL=$(git remote get-url origin 2>/dev/null)
-        echo "Error: Cannot determine host from origin remote URL" >&2
-        exit 1
-    }
 
-    API_URL="https://${HOST}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}"
+    # Extract host from remote URL
-    if [[ -n "${MOSAIC_GITEA_PR_METADATA_RAW_FILE:-}" ]]; then
+    if [[ "$REMOTE_URL" == https://* ]]; then
-        RAW=$(cat "$MOSAIC_GITEA_PR_METADATA_RAW_FILE")
+        HOST=$(echo "$REMOTE_URL" | sed -E 's|https://([^/]+)/.*|\1|')
+    elif [[ "$REMOTE_URL" == git@* ]]; then
+        HOST=$(echo "$REMOTE_URL" | sed -E 's|git@([^:]+):.*|\1|')
     else
-        RAW=$(curl_gitea_pull "$API_URL")
+        echo "Error: Cannot determine host from remote URL" >&2
+        exit 1
     fi
 
-    # Normalize Gitea response to match GitHub's expected metadata schema.
+    API_URL="https://${HOST}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}"
-    METADATA=$(printf '%s' "$RAW" | python3 -c "
-import json
-import sys
 
-def first_non_empty(*values):
+    GITEA_API_TOKEN=$(get_gitea_token "$HOST" || true)
-    for value in values:
-        if value is None:
-            continue
-        if isinstance(value, str):
-            value = value.strip()
-        if value:
-            return value
-    return ''
 
-def nested(data, *keys):
+    if [[ -n "$GITEA_API_TOKEN" ]]; then
-    current = data
+        RAW=$(curl -sS -H "Authorization: token $GITEA_API_TOKEN" "$API_URL")
-    for key in keys:
+    else
-        if not isinstance(current, dict):
+        RAW=$(curl -sS "$API_URL")
-            return None
+    fi
-        current = current.get(key)
-    return current
-
-try:
-    data = json.load(sys.stdin)
-except json.JSONDecodeError as exc:
-    print(f'Error: Gitea API returned non-JSON response: {exc}', file=sys.stderr)
-    sys.exit(1)
-
-if not isinstance(data, dict):
-    print('Error: Gitea API returned an unexpected non-object response', file=sys.stderr)
-    sys.exit(1)
-
-if data.get('message') and not data.get('number'):
-    print(f\"Error: Gitea API error: {data.get('message')}\", file=sys.stderr)
-    sys.exit(1)
-
-head_ref = first_non_empty(
-    nested(data, 'head', 'ref'),
-    nested(data, 'head', 'name'),
-    nested(data, 'head', 'branch'),
-    data.get('head_branch'),
-    data.get('head_ref'),
-    nested(data, 'head', 'label'),
-    data.get('head_label'),
-)
-if isinstance(head_ref, str) and head_ref.startswith('refs/pull/'):
-    head_ref = first_non_empty(
-        nested(data, 'head', 'label'),
-        data.get('head_label'),
-        nested(data, 'head', 'name'),
-        nested(data, 'head', 'branch'),
-        data.get('head_branch'),
-        data.get('head_ref'),
-        head_ref,
-    )
-base_ref = first_non_empty(
-    nested(data, 'base', 'ref'),
-    nested(data, 'base', 'name'),
-    nested(data, 'base', 'branch'),
-    data.get('base_branch'),
-    data.get('base_ref'),
-    data.get('base_label'),
-)
-
-if not head_ref or not base_ref:
-    available = ', '.join(sorted(data.keys()))
-    print(
-        'Error: Unable to resolve non-empty Gitea PR head/base refs '
-        f'(headRefName={head_ref!r}, baseRefName={base_ref!r}; keys={available})',
-        file=sys.stderr,
-    )
-    sys.exit(1)
 
+    # Normalize Gitea response to match our expected schema
+    METADATA=$(echo "$RAW" | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
 normalized = {
     'number': data.get('number'),
     'title': data.get('title'),
     'body': data.get('body', ''),
     'state': data.get('state'),
-    'author': nested(data, 'user', 'login') or '',
+    'author': data.get('user', {}).get('login', ''),
-    'headRefName': head_ref,
+    'headRefName': data.get('head', {}).get('ref', ''),
-    'baseRefName': base_ref,
+    'baseRefName': data.get('base', {}).get('ref', ''),
-    'labels': [l.get('name', '') for l in data.get('labels', []) if isinstance(l, dict)],
+    'labels': [l.get('name', '') for l in data.get('labels', [])],
-    'assignees': [a.get('login', '') for a in data.get('assignees', []) if isinstance(a, dict)],
+    'assignees': [a.get('login', '') for a in data.get('assignees', [])],
-    'milestone': nested(data, 'milestone', 'title') or '',
+    'milestone': data.get('milestone', {}).get('title', '') if data.get('milestone') else '',
     'createdAt': data.get('created_at', ''),
     'updatedAt': data.get('updated_at', ''),
     'url': data.get('html_url', ''),
@@ -215,7 +102,11 @@ normalized = {
 json.dump(normalized, sys.stdout, indent=2)
 ")
 
-    write_metadata "$METADATA"
+    if [[ -n "$OUTPUT_FILE" ]]; then
+        echo "$METADATA" > "$OUTPUT_FILE"
+    else
+        echo "$METADATA"
+    fi
 else
     echo "Error: Unknown platform" >&2
     exit 1

packages/mosaic/framework/tools/git/pr-review.sh

@@ -85,7 +85,7 @@ if [[ "$PLATFORM" == "github" ]]; then
 elif [[ "$PLATFORM" == "gitea" ]]; then
     case $ACTION in
         approve)
-            tea pr approve "$PR_NUMBER" $(get_gitea_repo_args) ${COMMENT:+--comment "$COMMENT"}
+            tea pr approve "$PR_NUMBER" ${COMMENT:+--comment "$COMMENT"}
             echo "Approved Gitea PR #$PR_NUMBER"
             ;;
         request-changes)
@@ -93,7 +93,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
                 echo "Error: Comment required for request-changes"
                 exit 1
             fi
-            tea pr reject "$PR_NUMBER" $(get_gitea_repo_args) --comment "$COMMENT"
+            tea pr reject "$PR_NUMBER" --comment "$COMMENT"
             echo "Requested changes on Gitea PR #$PR_NUMBER"
             ;;
         comment)
@@ -101,7 +101,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
                 echo "Error: Comment required"
                 exit 1
             fi
-            tea pr comment "$PR_NUMBER" "$COMMENT" $(get_gitea_repo_args)
+            tea pr comment "$PR_NUMBER" "$COMMENT"
             echo "Added comment to Gitea PR #$PR_NUMBER"
             ;;
         *)

packages/mosaic/framework/tools/git/pr-view.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # pr-view.sh - View pull request details on GitHub or Gitea
-# Usage: pr-view.sh -n <pr_number> [-r owner/repo]
+# Usage: pr-view.sh -n <pr_number>
 
 set -e
 
@@ -9,7 +9,6 @@ source "$SCRIPT_DIR/detect-platform.sh"
 
 # Parse arguments
 PR_NUMBER=""
-REPO_OVERRIDE=""
 
 while [[ $# -gt 0 ]]; do
     case $1 in
@@ -17,16 +16,11 @@ while [[ $# -gt 0 ]]; do
             PR_NUMBER="$2"
             shift 2
             ;;
-        -r|--repo)
-            REPO_OVERRIDE="$2"
-            shift 2
-            ;;
         -h|--help)
-            echo "Usage: pr-view.sh -n <pr_number> [-r owner/repo]"
+            echo "Usage: pr-view.sh -n <pr_number>"
             echo ""
             echo "Options:"
             echo "  -n, --number   PR number (required)"
-            echo "  -r, --repo     Repository slug (default: infer from git origin)"
             echo "  -h, --help     Show this help"
             exit 0
             ;;
@@ -42,23 +36,12 @@ if [[ -z "$PR_NUMBER" ]]; then
     exit 1
 fi
 
-if [[ -n "$REPO_OVERRIDE" ]]; then
+detect_platform
-    REPO_INFO="$REPO_OVERRIDE"
-    PLATFORM=$(detect_platform 2>/dev/null || echo gitea)
-else
-    PLATFORM=$(detect_platform)
-    REPO_INFO=$(get_repo_info)
-fi
-
-if [[ -z "$REPO_INFO" || "$REPO_INFO" == error:* ]]; then
-    echo "Error: Could not determine repository from git origin. Run from a repo or pass --repo." >&2
-    exit 1
-fi
 
 if [[ "$PLATFORM" == "github" ]]; then
-    gh pr view "$PR_NUMBER" --repo "$REPO_INFO"
+    gh pr view "$PR_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
-    tea pr "$PR_NUMBER" --repo "$REPO_INFO" --login "${GITEA_LOGIN:-mosaicstack}"
+    tea pr "$PR_NUMBER"
 else
     echo "Error: Unknown platform"
     exit 1

packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh

@@ -1,254 +0,0 @@
-#!/bin/bash
-# Regression harness for pr-merge.sh Gitea non-interactive tea empty identity fallback.
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_ROOT="${AGENT_WORK_ROOT:-/home/hermes/agent-work}"
-SANDBOX="$WORK_ROOT/pr-merge-empty-uid-test-$$"
-MOCK_BIN="$SANDBOX/bin"
-REPO_DIR="$SANDBOX/repo"
-LOG_FILE="$SANDBOX/mock.log"
-
-cleanup() {
-    rm -rf "$SANDBOX"
-}
-trap cleanup EXIT
-
-mkdir -p "$MOCK_BIN" "$REPO_DIR"
-: > "$LOG_FILE"
-
-cat > "$MOCK_BIN/tea" <<'EOF'
-#!/bin/bash
-set -euo pipefail
-printf 'tea %q ' "$@" >> "$PR_MERGE_TEST_LOG"
-printf '\n' >> "$PR_MERGE_TEST_LOG"
-if [[ "$*" == *"pr merge"* ]]; then
-    echo 'user does not exist [uid: 0, name: ]' >&2
-    exit 1
-fi
-exit 0
-EOF
-chmod +x "$MOCK_BIN/tea"
-
-cat > "$MOCK_BIN/curl" <<'EOF'
-#!/bin/bash
-set -euo pipefail
-printf 'curl %q ' "$@" >> "$PR_MERGE_TEST_LOG"
-printf '\n' >> "$PR_MERGE_TEST_LOG"
-args=" $* "
-out_file=""
-write_code=false
-post_data=""
-prev=""
-for arg in "$@"; do
-    if [[ "$prev" == "-o" ]]; then
-        out_file="$arg"
-        prev=""
-        continue
-    fi
-    if [[ "$prev" == "-d" ]]; then
-        post_data="$arg"
-        prev=""
-        continue
-    fi
-    if [[ "$arg" == "-o" ]]; then
-        prev="-o"
-        continue
-    fi
-    if [[ "$arg" == "-d" ]]; then
-        prev="-d"
-        continue
-    fi
-    if [[ "$arg" == "-w" ]]; then
-        write_code=true
-    fi
-done
-emit_response() {
-    local body="$1"
-    if [[ -n "$out_file" ]]; then
-        printf '%s' "$body" > "$out_file"
-    else
-        printf '%s' "$body"
-    fi
-    if [[ "$write_code" == true ]]; then
-        printf '200'
-    fi
-}
-if [[ "$args" == *"/api/v1/repos/mosaicstack/stack/pulls/123"* && "$args" != *"/api/v1/repos/mosaicstack/stack/pulls/123/merge"* ]]; then
-    emit_response '{"number":123,"title":"mock","state":"open","user":{"login":"tester"},"head":{"ref":"feature/mock"},"base":{"ref":"main"},"labels":[],"assignees":[],"html_url":"https://git.mosaicstack.dev/mosaicstack/stack/pulls/123","mergeable":true}'
-    exit 0
-fi
-if [[ "$args" == *"-X POST"* && "$args" == *"/api/v1/repos/mosaicstack/stack/pulls/123/merge"* ]]; then
-    if [[ "$post_data" != '{"Do":"squash"}' ]]; then
-        echo "unexpected merge payload: $post_data" >&2
-        exit 96
-    fi
-    emit_response '{"merged":true,"message":"mock merge complete"}'
-    exit 0
-fi
-echo "unexpected curl invocation: $*" >&2
-exit 97
-EOF
-chmod +x "$MOCK_BIN/curl"
-
-cd "$REPO_DIR"
-git init -q
-git remote add origin https://git.mosaicstack.dev/mosaicstack/stack.git
-
-export PATH="$MOCK_BIN:$PATH"
-export PR_MERGE_TEST_LOG="$LOG_FILE"
-export GITEA_LOGIN="git.mosaicstack.dev"
-export GITEA_TOKEN="redacted-test-token"
-
-OUTPUT="$SANDBOX/output.log"
-if ! "$SCRIPT_DIR/pr-merge.sh" -n 123 -m squash --skip-queue-guard > "$OUTPUT" 2>&1; then
-    echo "Expected pr-merge.sh to recover via Gitea API fallback." >&2
-    echo "--- output ---" >&2
-    sed 's/redacted-test-token/***REDACTED***/g' "$OUTPUT" >&2
-    echo "--- mock log ---" >&2
-    sed 's/redacted-test-token/***REDACTED***/g' "$LOG_FILE" >&2
-    exit 1
-fi
-
-if ! grep -q '/api/v1/repos/mosaicstack/stack/pulls/123/merge' "$LOG_FILE"; then
-    echo "Expected authenticated Gitea merge API endpoint to be called." >&2
-    sed 's/redacted-test-token/***REDACTED***/g' "$LOG_FILE" >&2
-    exit 1
-fi
-
-if grep -q 'redacted-test-token' "$OUTPUT"; then
-    echo "Token leaked to pr-merge.sh output." >&2
-    exit 1
-fi
-
-cat > "$MOCK_BIN/tea" <<'EOF'
-#!/bin/bash
-set -euo pipefail
-printf 'tea %q ' "$@" >> "$PR_MERGE_TEST_LOG"
-printf '\n' >> "$PR_MERGE_TEST_LOG"
-if [[ "$*" == *"pr merge"* ]]; then
-    echo 'tea network timeout' >&2
-    exit 2
-fi
-exit 0
-EOF
-chmod +x "$MOCK_BIN/tea"
-: > "$LOG_FILE"
-if "$SCRIPT_DIR/pr-merge.sh" -n 123 -m squash --skip-queue-guard > "$OUTPUT" 2>&1; then
-    echo "Expected arbitrary tea failure to remain blocking." >&2
-    exit 1
-fi
-if grep -q '/api/v1/repos/mosaicstack/stack/pulls/123/merge' "$LOG_FILE"; then
-    echo "Arbitrary tea failure unexpectedly used Gitea API merge fallback." >&2
-    sed 's/redacted-test-token/***REDACTED***/g' "$LOG_FILE" >&2
-    exit 1
-fi
-if ! grep -q 'tea network timeout' "$OUTPUT"; then
-    echo "Expected arbitrary tea error to be preserved in output." >&2
-    sed 's/redacted-test-token/***REDACTED***/g' "$OUTPUT" >&2
-    exit 1
-fi
-
-cat > "$MOCK_BIN/tea" <<'EOF'
-#!/bin/bash
-set -euo pipefail
-printf 'tea %q ' "$@" >> "$PR_MERGE_TEST_LOG"
-printf '\n' >> "$PR_MERGE_TEST_LOG"
-if [[ "$*" == *"login list"* ]]; then
-    echo '[]'
-    exit 0
-fi
-if [[ "$*" == *"pr merge"* ]]; then
-    echo 'tea merge should not run without a configured host login' >&2
-    exit 99
-fi
-exit 0
-EOF
-chmod +x "$MOCK_BIN/tea"
-unset GITEA_LOGIN
-: > "$LOG_FILE"
-if ! "$SCRIPT_DIR/pr-merge.sh" -n 123 -m squash --skip-queue-guard > "$OUTPUT" 2>&1; then
-    echo "Expected missing tea login to use authenticated Gitea API fallback." >&2
-    sed 's/redacted-test-token/***REDACTED***/g' "$OUTPUT" >&2
-    sed 's/redacted-test-token/***REDACTED***/g' "$LOG_FILE" >&2
-    exit 1
-fi
-if ! grep -q '/api/v1/repos/mosaicstack/stack/pulls/123/merge' "$LOG_FILE"; then
-    echo "Expected missing tea login path to call Gitea API merge endpoint." >&2
-    sed 's/redacted-test-token/***REDACTED***/g' "$LOG_FILE" >&2
-    exit 1
-fi
-
-SENTINEL="$SANDBOX/injected-sentinel"
-INJECTION="123; touch $SENTINEL #"
-
-cat > "$MOCK_BIN/gh" <<'EOF'
-#!/bin/bash
-set -euo pipefail
-printf 'gh %q ' "$@" >> "$PR_MERGE_TEST_LOG"
-printf '\n' >> "$PR_MERGE_TEST_LOG"
-if [[ "$*" == *"pr view"* ]]; then
-    cat <<'JSON'
-{"number":123,"title":"mock","baseRefName":"main","headRefName":"feature/mock"}
-JSON
-    exit 0
-fi
-if [[ "$*" == *"pr merge"* ]]; then
-    exit 0
-fi
-echo "unexpected gh invocation: $*" >&2
-exit 98
-EOF
-chmod +x "$MOCK_BIN/gh"
-
-cd "$REPO_DIR"
-git remote set-url origin https://github.com/mosaicstack/stack.git
-: > "$LOG_FILE"
-rm -f "$SENTINEL"
-if "$SCRIPT_DIR/pr-merge.sh" -n "$INJECTION" -m squash --skip-queue-guard > "$OUTPUT" 2>&1; then
-    echo "Expected GitHub metacharacter PR number to be rejected." >&2
-    sed 's/redacted-test-token/***REDACTED***/g' "$OUTPUT" >&2
-    exit 1
-fi
-if [[ -e "$SENTINEL" ]]; then
-    echo "GitHub metacharacter PR number executed injected shell command." >&2
-    exit 1
-fi
-if [[ -s "$LOG_FILE" ]]; then
-    echo "GitHub metacharacter PR number should be rejected before gh calls." >&2
-    sed 's/redacted-test-token/***REDACTED***/g' "$LOG_FILE" >&2
-    exit 1
-fi
-if ! grep -q 'Invalid PR number' "$OUTPUT"; then
-    echo "Expected invalid PR number error for GitHub metacharacter input." >&2
-    sed 's/redacted-test-token/***REDACTED***/g' "$OUTPUT" >&2
-    exit 1
-fi
-
-cd "$REPO_DIR"
-git remote set-url origin https://git.mosaicstack.dev/mosaicstack/stack.git
-export GITEA_LOGIN="git.mosaicstack.dev"
-: > "$LOG_FILE"
-rm -f "$SENTINEL"
-if "$SCRIPT_DIR/pr-merge.sh" -n "$INJECTION" -m squash --skip-queue-guard > "$OUTPUT" 2>&1; then
-    echo "Expected Gitea metacharacter PR number to be rejected." >&2
-    sed 's/redacted-test-token/***REDACTED***/g' "$OUTPUT" >&2
-    exit 1
-fi
-if [[ -e "$SENTINEL" ]]; then
-    echo "Gitea metacharacter PR number executed injected shell command." >&2
-    exit 1
-fi
-if [[ -s "$LOG_FILE" ]]; then
-    echo "Gitea metacharacter PR number should be rejected before tea/curl calls." >&2
-    sed 's/redacted-test-token/***REDACTED***/g' "$LOG_FILE" >&2
-    exit 1
-fi
-if ! grep -q 'Invalid PR number' "$OUTPUT"; then
-    echo "Expected invalid PR number error for Gitea metacharacter input." >&2
-    sed 's/redacted-test-token/***REDACTED***/g' "$OUTPUT" >&2
-    exit 1
-fi
-
-echo "pr-merge.sh Gitea fallback regression passed"

packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh

@@ -1,87 +0,0 @@
-#!/usr/bin/env bash
-# Regression harness for Gitea PR metadata normalization.
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-metadata-gitea}"
-REPO_DIR="$WORK_DIR/repo"
-FIXTURE_DIR="$WORK_DIR/fixtures"
-
-rm -rf "$WORK_DIR"
-mkdir -p "$REPO_DIR" "$FIXTURE_DIR"
-
-git -C "$REPO_DIR" init -q
-git -C "$REPO_DIR" remote add origin https://git.uscllc.com/USC/uconnect.git
-
-cat > "$FIXTURE_DIR/gitea-standard.json" <<'JSON'
-{
-  "number": 1905,
-  "title": "Smoke gate fix",
-  "state": "open",
-  "user": {"login": "edith"},
-  "head": {"ref": "edith/t_39ce717c-authentik-smoke-gate"},
-  "base": {"ref": "main"},
-  "labels": [{"name": "ci"}],
-  "assignees": [{"login": "edith"}],
-  "html_url": "https://git.uscllc.com/USC/uconnect/pulls/1905"
-}
-JSON
-
-cat > "$FIXTURE_DIR/gitea-fallback.json" <<'JSON'
-{
-  "number": 1908,
-  "title": "Fallback branch fields",
-  "state": "open",
-  "user": {"login": "edith"},
-  "head_branch": "fix/fallback-head",
-  "base_branch": "main",
-  "html_url": "https://git.uscllc.com/USC/uconnect/pulls/1908"
-}
-JSON
-
-cat > "$FIXTURE_DIR/gitea-refs-pull-label.json" <<'JSON'
-{
-  "number": 1908,
-  "title": "Closed merged PR with synthetic pull ref",
-  "state": "closed",
-  "user": {"login": "edith"},
-  "head": {"ref": "refs/pull/1908/head", "label": "fix/t_23fa9e1d-portal-health-backend"},
-  "base": {"ref": "main"},
-  "html_url": "https://git.uscllc.com/USC/uconnect/pulls/1908"
-}
-JSON
-
-cat > "$FIXTURE_DIR/gitea-error.json" <<'JSON'
-{"message": "user does not exist [uid: 0, name: ]", "url": "https://git.uscllc.com/api/swagger"}
-JSON
-
-run_case() {
-    local fixture="$1" expected_number="$2" expected_head="$3"
-    local output
-    output=$(cd "$REPO_DIR" && MOSAIC_GITEA_PR_METADATA_RAW_FILE="$fixture" "$SCRIPT_DIR/pr-metadata.sh" -n "$expected_number")
-    PR_METADATA_OUTPUT="$output" python3 - "$expected_number" "$expected_head" <<'PY'
-import json
-import os
-import sys
-
-data = json.loads(os.environ["PR_METADATA_OUTPUT"])
-expected_number = int(sys.argv[1])
-expected_head = sys.argv[2]
-assert data["number"] == expected_number, data
-assert data["baseRefName"] == "main", data
-assert data["headRefName"] == expected_head, data
-PY
-}
-
-run_case "$FIXTURE_DIR/gitea-standard.json" 1905 edith/t_39ce717c-authentik-smoke-gate
-run_case "$FIXTURE_DIR/gitea-fallback.json" 1908 fix/fallback-head
-run_case "$FIXTURE_DIR/gitea-refs-pull-label.json" 1908 fix/t_23fa9e1d-portal-health-backend
-
-if cd "$REPO_DIR" && MOSAIC_GITEA_PR_METADATA_RAW_FILE="$FIXTURE_DIR/gitea-error.json" "$SCRIPT_DIR/pr-metadata.sh" -n 1909 >/dev/null 2>"$WORK_DIR/error.log"; then
-    echo "Expected API error fixture to fail" >&2
-    exit 1
-fi
-grep -q "Gitea API error" "$WORK_DIR/error.log"
-
-echo "Gitea PR metadata regression harness passed"

packages/mosaic/framework/tools/woodpecker/pipeline-list.sh

@@ -50,7 +50,7 @@ REPO_ID=$(wp_resolve_repo_id "$REPO") || exit 1
 
 response=$(curl -sk -w "\n%{http_code}" \
   -H "Authorization: Bearer $WOODPECKER_TOKEN" \
-  "${WOODPECKER_URL}/api/repos/${REPO_ID}/pipelines?perPage=${LIMIT}")
+  "${WOODPECKER_URL}/api/repos/${REPO_ID}/pipelines?per_page=${LIMIT}")
 
 http_code=$(echo "$response" | tail -n1)
 body=$(echo "$response" | sed '$d')

packages/mosaic/framework/tools/woodpecker/pipeline-status.sh

@@ -64,7 +64,7 @@ _wp_fetch() {
 
 if [[ -z "$NUMBER" ]]; then
   # Get latest pipeline number from list, then fetch full detail
-  list_body=$(_wp_fetch "${WOODPECKER_URL}/api/repos/${REPO_ID}/pipelines?perPage=1") || exit 1
+  list_body=$(_wp_fetch "${WOODPECKER_URL}/api/repos/${REPO_ID}/pipelines?per_page=1") || exit 1
   NUMBER=$(echo "$list_body" | jq -r '.[0].number // empty')
   if [[ -z "$NUMBER" ]]; then
     echo "Error: No pipelines found" >&2

packages/mosaic/src/cli.ts

@@ -18,7 +18,6 @@ import { registerUninstallCommand } from './commands/uninstall.js';
 // prdy is registered via launch.ts
 import { registerLaunchCommands } from './commands/launch.js';
 import { registerAuthCommand } from './commands/auth.js';
-import { registerFederationCommand } from './commands/federation.js';
 import { registerGatewayCommand } from './commands/gateway.js';
 import {
   backgroundUpdateCheck,
@@ -337,10 +336,6 @@ registerAuthCommand(program);
 
 registerGatewayCommand(program);
 
-// ─── federation ───────────────────────────────────────────────────────
-
-registerFederationCommand(program);
-
 // ─── agent ─────────────────────────────────────────────────────────────
 
 registerAgentCommand(program);

packages/mosaic/src/commands/federation.ts

@@ -1,410 +0,0 @@
-/**
- * `mosaic federation` command group — federation grant + peer management (FED-M2-08).
- *
- * All HTTP calls go to the local gateway admin API using an admin token
- * resolved from CLI options or meta.json.
- *
- * Subcommands:
- *   grant create --peer-id <uuid> --user-id <uuid> --scope <json> [--expires-at <iso>]
- *   grant list   [--peer-id <uuid>] [--user-id <uuid>] [--status pending|active|revoked|expired]
- *   grant show   <id>
- *   grant revoke <id> [--reason <text>]
- *   grant token  <id> [--ttl 900]
- *
- *   peer list
- *   peer add <enrollment-url>
- */
-
-import type { Command } from 'commander';
-import { readMeta } from './gateway/daemon.js';
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-interface FedParentOpts {
-  host: string;
-  port: string;
-  token?: string;
-  json?: boolean;
-}
-
-interface ResolvedOpts {
-  baseUrl: string;
-  token?: string;
-  json: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function resolveOpts(raw: FedParentOpts): ResolvedOpts {
-  const meta = readMeta();
-  const host = raw.host ?? meta?.host ?? 'localhost';
-  const port = parseInt(raw.port, 10) || meta?.port || 14242;
-  const token = raw.token ?? meta?.adminToken;
-  return {
-    baseUrl: `http://${host}:${port.toString()}`,
-    token,
-    json: raw.json ?? false,
-  };
-}
-
-function requireToken(opts: ResolvedOpts): string {
-  if (!opts.token) {
-    console.error(
-      'Error: admin token required. Use -t/--token <token> or ensure meta.json has adminToken.',
-    );
-    process.exit(1);
-  }
-  return opts.token;
-}
-
-async function apiRequest<T>(
-  opts: ResolvedOpts,
-  method: string,
-  path: string,
-  body?: unknown,
-): Promise<T> {
-  const token = requireToken(opts);
-  const url = `${opts.baseUrl}${path}`;
-
-  const res = await fetch(url, {
-    method,
-    headers: {
-      'Content-Type': 'application/json',
-      Authorization: `Bearer ${token}`,
-    },
-    body: body !== undefined ? JSON.stringify(body) : undefined,
-  });
-
-  const text = await res.text();
-
-  if (!res.ok) {
-    let message = text;
-    try {
-      const parsed = JSON.parse(text) as { message?: string };
-      message = parsed.message ?? text;
-    } catch {
-      // use raw text
-    }
-    throw new Error(`HTTP ${res.status.toString()}: ${message}`);
-  }
-
-  if (!text) return undefined as unknown as T;
-  return JSON.parse(text) as T;
-}
-
-function printJson(data: unknown, useJson: boolean): void {
-  if (useJson) {
-    console.log(JSON.stringify(data, null, 2));
-  }
-}
-
-function printTable(rows: Record<string, unknown>[]): void {
-  if (rows.length === 0) {
-    console.log('(none)');
-    return;
-  }
-  for (const row of rows) {
-    for (const [key, val] of Object.entries(row)) {
-      console.log(`  ${key}: ${String(val ?? '')}`);
-    }
-    console.log('');
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Command registration
-// ---------------------------------------------------------------------------
-
-export function registerFederationCommand(program: Command): void {
-  const fed = program
-    .command('federation')
-    .alias('fed')
-    .description('Manage federation grants and peers')
-    .option('-h, --host <host>', 'Gateway host', 'localhost')
-    .option('-p, --port <port>', 'Gateway port', '14242')
-    .option('-t, --token <token>', 'Admin token')
-    .option('--json', 'Machine-readable JSON output')
-    .action(() => fed.outputHelp());
-
-  // ─── grant subcommands ─────────────────────────────────────────────────
-
-  const grant = fed
-    .command('grant')
-    .description('Manage federation grants')
-    .action(() => grant.outputHelp());
-
-  grant
-    .command('create')
-    .description('Create a new federation grant')
-    .requiredOption('--peer-id <uuid>', 'Peer UUID')
-    .requiredOption('--user-id <uuid>', 'Subject user UUID')
-    .requiredOption('--scope <json>', 'Grant scope as JSON string')
-    .option('--expires-at <iso>', 'Optional expiry (ISO 8601)')
-    .action(
-      async (cmdOpts: { peerId: string; userId: string; scope: string; expiresAt?: string }) => {
-        const opts = resolveOpts(fed.opts() as FedParentOpts);
-        try {
-          let scope: Record<string, unknown>;
-          try {
-            scope = JSON.parse(cmdOpts.scope) as Record<string, unknown>;
-          } catch {
-            console.error('Error: --scope must be valid JSON');
-            process.exit(1);
-          }
-
-          const body: Record<string, unknown> = {
-            peerId: cmdOpts.peerId,
-            subjectUserId: cmdOpts.userId,
-            scope,
-          };
-          if (cmdOpts.expiresAt) body['expiresAt'] = cmdOpts.expiresAt;
-
-          const result = await apiRequest<Record<string, unknown>>(
-            opts,
-            'POST',
-            '/api/admin/federation/grants',
-            body,
-          );
-
-          if (opts.json) {
-            printJson(result, true);
-          } else {
-            console.log(`Grant created: ${String(result['id'])}`);
-            console.log(`  Peer:   ${String(result['peerId'])}`);
-            console.log(`  User:   ${String(result['subjectUserId'])}`);
-            console.log(`  Status: ${String(result['status'])}`);
-          }
-        } catch (err) {
-          console.error(err instanceof Error ? err.message : String(err));
-          process.exit(1);
-        }
-      },
-    );
-
-  grant
-    .command('list')
-    .description('List federation grants')
-    .option('--peer-id <uuid>', 'Filter by peer UUID')
-    .option('--user-id <uuid>', 'Filter by subject user UUID')
-    .option('--status <status>', 'Filter by status (pending|active|revoked|expired)')
-    .action(async (cmdOpts: { peerId?: string; userId?: string; status?: string }) => {
-      const opts = resolveOpts(fed.opts() as FedParentOpts);
-      try {
-        const params = new URLSearchParams();
-        if (cmdOpts.peerId) params.set('peerId', cmdOpts.peerId);
-        if (cmdOpts.userId) params.set('subjectUserId', cmdOpts.userId);
-        if (cmdOpts.status) params.set('status', cmdOpts.status);
-
-        const qs = params.toString() ? `?${params.toString()}` : '';
-        const result = await apiRequest<Record<string, unknown>[]>(
-          opts,
-          'GET',
-          `/api/admin/federation/grants${qs}`,
-        );
-
-        if (opts.json) {
-          printJson(result, true);
-        } else {
-          console.log(`Grants (${result.length.toString()}):\n`);
-          printTable(result);
-        }
-      } catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-      }
-    });
-
-  grant
-    .command('show <id>')
-    .description('Get a single grant by ID')
-    .action(async (id: string) => {
-      const opts = resolveOpts(fed.opts() as FedParentOpts);
-      try {
-        const result = await apiRequest<Record<string, unknown>>(
-          opts,
-          'GET',
-          `/api/admin/federation/grants/${id}`,
-        );
-
-        if (opts.json) {
-          printJson(result, true);
-        } else {
-          for (const [key, val] of Object.entries(result)) {
-            console.log(`  ${key}: ${String(val ?? '')}`);
-          }
-        }
-      } catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-      }
-    });
-
-  grant
-    .command('revoke <id>')
-    .description('Revoke an active grant')
-    .option('--reason <text>', 'Revocation reason')
-    .action(async (id: string, cmdOpts: { reason?: string }) => {
-      const opts = resolveOpts(fed.opts() as FedParentOpts);
-      try {
-        const body: Record<string, unknown> = {};
-        if (cmdOpts.reason) body['reason'] = cmdOpts.reason;
-
-        const result = await apiRequest<Record<string, unknown>>(
-          opts,
-          'PATCH',
-          `/api/admin/federation/grants/${id}/revoke`,
-          body,
-        );
-
-        if (opts.json) {
-          printJson(result, true);
-        } else {
-          console.log(`Grant ${id} revoked.`);
-          if (result['revokedReason']) console.log(`  Reason: ${String(result['revokedReason'])}`);
-        }
-      } catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-      }
-    });
-
-  grant
-    .command('token <id>')
-    .description('Generate a single-use enrollment token for a grant')
-    .option('--ttl <seconds>', 'Token lifetime in seconds (60-900)', '900')
-    .action(async (id: string, cmdOpts: { ttl: string }) => {
-      const opts = resolveOpts(fed.opts() as FedParentOpts);
-      try {
-        const ttlSeconds = parseInt(cmdOpts.ttl, 10) || 900;
-        const result = await apiRequest<{
-          token: string;
-          expiresAt: string;
-          enrollmentUrl: string;
-        }>(opts, 'POST', `/api/admin/federation/grants/${id}/tokens`, { ttlSeconds });
-
-        if (opts.json) {
-          printJson(result, true);
-        } else {
-          console.log('Enrollment token generated:');
-          console.log(`  Token:         ${result.token}`);
-          console.log(`  Expires at:    ${result.expiresAt}`);
-          console.log(`  Enrollment URL: ${result.enrollmentUrl}`);
-          console.log('');
-          console.log('Share the enrollment URL with the remote peer operator.');
-        }
-      } catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-      }
-    });
-
-  // ─── peer subcommands ──────────────────────────────────────────────────
-
-  const peer = fed
-    .command('peer')
-    .description('Manage federation peers')
-    .action(() => peer.outputHelp());
-
-  peer
-    .command('list')
-    .description('List all federation peers')
-    .action(async () => {
-      const opts = resolveOpts(fed.opts() as FedParentOpts);
-      try {
-        const result = await apiRequest<Record<string, unknown>[]>(
-          opts,
-          'GET',
-          '/api/admin/federation/peers',
-        );
-
-        if (opts.json) {
-          printJson(result, true);
-        } else {
-          console.log(`Peers (${result.length.toString()}):\n`);
-          printTable(result);
-        }
-      } catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-      }
-    });
-
-  peer
-    .command('add <enrollment-url>')
-    .description('Enroll as a peer using a remote enrollment URL')
-    .action(async (enrollmentUrl: string) => {
-      const opts = resolveOpts(fed.opts() as FedParentOpts);
-      try {
-        // 1. Validate enrollment URL
-        let parsedUrl: URL;
-        try {
-          parsedUrl = new URL(enrollmentUrl);
-        } catch {
-          console.error(`Error: invalid enrollment URL: ${enrollmentUrl}`);
-          process.exit(1);
-        }
-
-        if (parsedUrl.protocol !== 'https:' && parsedUrl.protocol !== 'http:') {
-          console.error('Error: enrollment URL must use http or https');
-          process.exit(1);
-        }
-
-        const hostname = parsedUrl.hostname;
-        const commonName = hostname.replace(/\./g, '-');
-
-        console.log(`Enrolling as peer with remote: ${enrollmentUrl}`);
-        console.log(`  Common name: ${commonName}`);
-
-        // 2. Generate key pair and CSR via local gateway
-        console.log('Generating key pair and CSR...');
-        const keypairResult = await apiRequest<{ peerId: string; csrPem: string }>(
-          opts,
-          'POST',
-          '/api/admin/federation/peers/keypair',
-          { commonName, displayName: hostname },
-        );
-
-        const { peerId, csrPem } = keypairResult;
-        console.log(`  Peer ID: ${peerId}`);
-
-        // 3. Submit CSR to remote enrollment endpoint
-        console.log('Submitting CSR to remote enrollment endpoint...');
-        const remoteRes = await fetch(enrollmentUrl, {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ csrPem }),
-        });
-
-        if (!remoteRes.ok) {
-          const errText = await remoteRes.text();
-          throw new Error(`Remote enrollment failed (${remoteRes.status.toString()}): ${errText}`);
-        }
-
-        const remoteResult = (await remoteRes.json()) as { certPem: string; certChainPem: string };
-
-        if (!remoteResult.certPem) {
-          throw new Error('Remote enrollment response missing certPem');
-        }
-
-        // 4. Store the signed certificate in the local gateway
-        console.log('Storing signed certificate...');
-        await apiRequest<Record<string, unknown>>(
-          opts,
-          'PATCH',
-          `/api/admin/federation/peers/${peerId}/cert`,
-          { certPem: remoteResult.certPem },
-        );
-
-        console.log(`\nPeer enrolled successfully.`);
-        console.log(`  ID:    ${peerId}`);
-        console.log(`  State: active`);
-      } catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-      }
-    });
-}

packages/mosaic/src/commands/git-wrapper-redirects.spec.ts

@@ -1,22 +0,0 @@
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { describe, expect, it } from 'vitest';
-
-const packageRoot = join(import.meta.dirname, '..', '..');
-const gitToolsDir = join(packageRoot, 'framework', 'tools', 'git');
-
-function readGitTool(scriptName: string): string {
-  return readFileSync(join(gitToolsDir, scriptName), 'utf-8');
-}
-
-describe('Gitea git wrapper API calls', () => {
-  it.each(['ci-queue-wait.sh', 'pr-ci-wait.sh'])(
-    '%s follows Gitea API redirects before parsing JSON',
-    (scriptName) => {
-      const script = readGitTool(scriptName);
-
-      expect(script).not.toContain('curl -fsS -H "Authorization: token');
-      expect(script).toContain('curl -fsSL -H "Authorization: token');
-    },
-  );
-});

packages/mosaic/src/commands/launch.spec.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach, afterEach, type MockInstance } from 'vitest';
 import { Command } from 'commander';
-import { buildPiSkillArgs, registerRuntimeLaunchers, type RuntimeLaunchHandler } from './launch.js';
+import { registerRuntimeLaunchers, type RuntimeLaunchHandler } from './launch.js';
 
 /**
  * Tests for the commander wiring between `mosaic <runtime>` / `mosaic yolo <runtime>`
@@ -22,8 +22,6 @@ function buildProgram(handler: RuntimeLaunchHandler): Command {
   return program;
 }
 
-const fakeSkills = ['--skill', '/skills/test-driven-development', '--skill', '/skills/pdf'];
-
 // `process.exit` returns `never`, so vi.spyOn demands a replacement with the
 // same signature. We throw from the mock to short-circuit into test-land.
 const exitThrows = (): never => {
@@ -65,30 +63,6 @@ describe('registerRuntimeLaunchers — non-yolo subcommands', () => {
   });
 });
 
-describe('buildPiSkillArgs', () => {
-  it('defaults to disabling Pi skill discovery to keep startup context small', () => {
-    expect(buildPiSkillArgs([], {}, fakeSkills)).toEqual(['--no-skills']);
-  });
-
-  it('keeps explicit user skills while disabling automatic discovery', () => {
-    expect(buildPiSkillArgs(['--skill', '/tmp/custom'], {}, fakeSkills)).toEqual(['--no-skills']);
-  });
-
-  it('supports legacy all-skills mode without double-loading settings skills', () => {
-    expect(buildPiSkillArgs([], { MOSAIC_PI_SKILL_MODE: 'all' }, fakeSkills)).toEqual([
-      '--no-skills',
-      '--skill',
-      '/skills/test-driven-development',
-      '--skill',
-      '/skills/pdf',
-    ]);
-  });
-
-  it('supports native Pi discovery when explicitly requested', () => {
-    expect(buildPiSkillArgs([], { MOSAIC_PI_SKILL_MODE: 'discover' }, fakeSkills)).toEqual([]);
-  });
-});
-
 describe('registerRuntimeLaunchers — yolo <runtime>', () => {
   let mockExit: MockInstance<typeof process.exit>;
   let mockError: MockInstance<typeof console.error>;