fix(git-tools): harden gitea pr metadata wrappers

Merge pull request 'fix(db): bootstrap migrations on local-tier gateway startup' (#510 ) from fix/db-bootstrap-migrations into main
fix(db): bootstrap migrations on local-tier gateway startup
2026-05-22 11:23:36 -05:00 · 2026-05-04 22:13:14 +00:00 · 2026-05-04 17:06:50 -05:00 · 2026-04-25 13:27:20 +00:00 · 2026-04-25 06:33:37 -05:00 · 2026-04-25 06:33:37 -05:00
27 changed files with 2860 additions and 184 deletions
--- a/apps/gateway/package.json
+++ b/apps/gateway/package.json
@@ -73,6 +73,7 @@
    "rxjs": "^7.8.0",
    "socket.io": "^4.8.0",
    "uuid": "^11.0.0",
    "undici": "^7.24.6",
    "zod": "^4.3.6"
  },
  "devDependencies": {
--- a/apps/gateway/src/database/database.module.ts
+++ b/apps/gateway/src/database/database.module.ts
@@ -1,8 +1,21 @@
 import { mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { Global, Inject, Module, type OnApplicationShutdown } from '@nestjs/common';
+import {
-import { createDb, createPgliteDb, type Db, type DbHandle } from '@mosaicstack/db';
+  Global,
  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';
@@ -39,12 +52,37 @@ export const STORAGE_ADAPTER = 'STORAGE_ADAPTER';
  ],
  exports: [DB, STORAGE_ADAPTER],
 })
-export class DatabaseModule implements OnApplicationShutdown {
+export class DatabaseModule implements OnApplicationShutdown, OnModuleInit {
  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()]);
  }
--- a/apps/gateway/src/federation/client/tests/federation-client.service.spec.ts
+++ b/apps/gateway/src/federation/client/tests/federation-client.service.spec.ts
@@ -0,0 +1,553 @@
 /**
 * 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);
    });
  });
 });
--- a/apps/gateway/src/federation/client/federation-client.service.ts
+++ b/apps/gateway/src/federation/client/federation-client.service.ts
@@ -0,0 +1,500 @@
 /**
 * 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;
  }
 }
--- a/apps/gateway/src/federation/client/index.ts
+++ b/apps/gateway/src/federation/client/index.ts
@@ -0,0 +1,13 @@
 /**
 * 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';
--- a/apps/gateway/src/federation/federation.module.ts
+++ b/apps/gateway/src/federation/federation.module.ts
@@ -5,10 +5,25 @@ 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: [AdminGuard, CaService, EnrollmentService, GrantsService],
+  providers: [
-  exports: [CaService, EnrollmentService, GrantsService],
+    AdminGuard,
    CaService,
    EnrollmentService,
    GrantsService,
    FederationClientService,
    FederationAuthGuard,
  ],
  exports: [
    CaService,
    EnrollmentService,
    GrantsService,
    FederationClientService,
    FederationAuthGuard,
  ],
 })
 export class FederationModule {}
--- a/apps/gateway/src/federation/grants.service.ts
+++ b/apps/gateway/src/federation/grants.service.ts
@@ -10,12 +10,14 @@
 */
 import { ConflictException, Inject, Injectable, NotFoundException } from '@nestjs/common';
-import { type Db, and, eq, federationGrants } from '@mosaicstack/db';
+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 {
@@ -60,6 +62,33 @@ export class GrantsService {
    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.
   */
--- a/apps/gateway/src/federation/oid.util.ts
+++ b/apps/gateway/src/federation/oid.util.ts
@@ -0,0 +1,146 @@
 /**
 * 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);
 }
--- a/apps/gateway/src/federation/server/tests/federation-auth.guard.spec.ts
+++ b/apps/gateway/src/federation/server/tests/federation-auth.guard.spec.ts
@@ -0,0 +1,521 @@
 /**
 * 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,
    });
  });
 });
--- a/apps/gateway/src/federation/server/federation-auth.guard.ts
+++ b/apps/gateway/src/federation/server/federation-auth.guard.ts
@@ -0,0 +1,212 @@
 /**
 * 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;
  }
 }
--- a/apps/gateway/src/federation/server/federation-context.ts
+++ b/apps/gateway/src/federation/server/federation-context.ts
@@ -0,0 +1,39 @@
 /**
 * 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>;
 }
--- a/apps/gateway/src/federation/server/index.ts
+++ b/apps/gateway/src/federation/server/index.ts
@@ -0,0 +1,13 @@
 /**
 * 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';
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -30,6 +30,7 @@ These are MVP-level checks that don't belong to any single workstream. Updated b
 | 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-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
--- a/docs/scratchpads/t-a292e96f-gitea-pr-metadata.md
+++ b/docs/scratchpads/t-a292e96f-gitea-pr-metadata.md
@@ -0,0 +1,53 @@
 # 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.
--- a/packages/db/package.json
+++ b/packages/db/package.json
@@ -42,6 +42,7 @@
    "access": "public"
  },
  "files": [
-    "dist"
+    "dist",
    "drizzle"
  ]
 }
--- a/packages/db/src/client-pglite.ts
+++ b/packages/db/src/client-pglite.ts
@@ -1,10 +1,12 @@
 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 {
-  const client = new PGlite(dataDir);
+  // pgvector extension is required by migration 0001 (insights.embedding column).
  const client = new PGlite(dataDir, { extensions: { vector } });
  const db = drizzle(client, { schema });
  return {
    db: db as unknown as DbHandle['db'],
--- a/packages/db/src/index.ts
+++ b/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 } from './migrate.js';
+export { runMigrations, runPgliteMigrations } from './migrate.js';
 export * from './schema.js';
 export * from './federation.js';
 export {
--- a/packages/db/src/migrate.test.ts
+++ b/packages/db/src/migrate.test.ts
@@ -0,0 +1,70 @@
 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);
  });
 });
--- a/packages/db/src/migrate.ts
+++ b/packages/db/src/migrate.ts
@@ -1,18 +1,109 @@
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { drizzle } from 'drizzle-orm/postgres-js';
+import { sql } from 'drizzle-orm';
-import { migrate } from 'drizzle-orm/postgres-js/migrator';
+import { drizzle as drizzlePostgres } from 'drizzle-orm/postgres-js';
 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 sql = postgres(connectionString, { max: 1 });
+  const sqlClient = postgres(connectionString, { max: 1 });
-  const db = drizzle(sql);
+  const db = drizzlePostgres(sqlClient);
  const __dirname = dirname(fileURLToPath(import.meta.url));
  try {
-    await migrate(db, { migrationsFolder: resolve(__dirname, '../drizzle') });
+    // TODO: postgres-tier first-install also fails because (a) Drizzle wraps every
    // 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 sql.end();
+    await sqlClient.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})`,
    );
  }
 }
--- a/packages/mosaic/framework/tools/git/detect-platform.sh
+++ b/packages/mosaic/framework/tools/git/detect-platform.sh
@@ -103,16 +103,28 @@ 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
                        load_credentials "$svc" 2>/dev/null || continue
                        [[ "${GITEA_URL:-}" == *"$host"* ]] && break
                        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
                            matched=true
                            break
                        fi
                    done
                    if [[ "$matched" != true ]]; then
                        unset GITEA_TOKEN GITEA_URL
                    fi
                    ;;
            esac
            echo "${GITEA_TOKEN:-}"
@@ -123,11 +135,13 @@ get_gitea_token() {
        fi
    fi
-    # 2. GITEA_TOKEN env var (may be set by caller)
+    # 2. GITEA_TOKEN env var (only when GITEA_URL, if present, matches the remote host)
    if [[ -n "${GITEA_TOKEN:-}" ]]; then
        if [[ -z "${GITEA_URL:-}" || "${GITEA_URL:-}" == "https://$host" || "${GITEA_URL:-}" == "http://$host" || "${GITEA_URL:-}" == *"//$host" ]]; then
            echo "$GITEA_TOKEN"
            return 0
        fi
    fi
    # 3. ~/.git-credentials file
    local creds="$HOME/.git-credentials"
@@ -143,6 +157,37 @@ 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
--- a/packages/mosaic/framework/tools/git/pr-merge.sh
+++ b/packages/mosaic/framework/tools/git/pr-merge.sh
@@ -2,9 +2,10 @@
 # pr-merge.sh - Merge pull requests on Gitea or GitHub
 # Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d] [--skip-queue-guard]
-set -e
+set -euo pipefail
 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
@@ -12,6 +13,7 @@ PR_NUMBER=""
 MERGE_METHOD="squash"
 DELETE_BRANCH=false
 SKIP_QUEUE_GUARD=false
 DRY_RUN=false
 usage() {
    cat <<EOF
@@ -24,6 +26,7 @@ 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:
@@ -54,6 +57,11 @@ while [[ $# -gt 0 ]]; do
            SKIP_QUEUE_GUARD=true
            shift
            ;;
        --dry-run)
            DRY_RUN=true
            SKIP_QUEUE_GUARD=true
            shift
            ;;
        -h|--help)
            usage
            ;;
@@ -74,7 +82,8 @@ if [[ "$MERGE_METHOD" != "squash" ]]; then
    exit 1
 fi
-BASE_BRANCH="$("$SCRIPT_DIR/pr-metadata.sh" -n "$PR_NUMBER" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("baseRefName") or "").strip())')"
+PR_METADATA="$("$SCRIPT_DIR/pr-metadata.sh" -n "$PR_NUMBER")"
 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
@@ -92,21 +101,122 @@ 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
 }
 merge_gitea_with_api() {
    local host="$1" api_url token basic_auth body_file raw_code payload
    body_file=$(mktemp)
    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:
    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 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"
+        GH_ARGS=(pr merge "$PR_NUMBER" --squash)
-        [[ "$DELETE_BRANCH" == true ]] && CMD="$CMD --delete-branch"
+        [[ "$DELETE_BRANCH" == true ]] && GH_ARGS+=(--delete-branch)
-        eval "$CMD"
+        gh "${GH_ARGS[@]}"
        ;;
    gitea)
-        CMD="tea pr merge $PR_NUMBER --style squash --repo $OWNER/$REPO --login ${GITEA_LOGIN:-mosaicstack}"
+        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
            tea pr merge "$PR_NUMBER" --style squash --repo "$OWNER/$REPO" --login "$TEA_LOGIN"
        else
            echo "No tea login configured for $HOST; using authenticated Gitea API merge fallback." >&2
            merge_gitea_with_api "$HOST" "https://${HOST}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}/merge"
        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
--- a/packages/mosaic/framework/tools/git/pr-metadata.sh
+++ b/packages/mosaic/framework/tools/git/pr-metadata.sh
@@ -2,9 +2,10 @@
 # pr-metadata.sh - Get PR metadata as JSON on GitHub or Gitea
 # Usage: pr-metadata.sh -n <pr_number> [-o <output_file>]
-set -e
+set -euo pipefail
 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
@@ -31,7 +32,7 @@ while [[ $# -gt 0 ]]; do
            exit 0
            ;;
        *)
-            echo "Unknown option: $1"
+            echo "Unknown option: $1" >&2
            exit 1
            ;;
    esac
@@ -42,56 +43,168 @@ 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)
-    REMOTE_URL=$(git remote get-url origin 2>/dev/null)
+    HOST=$(get_remote_host) || {
-
+        echo "Error: Cannot determine host from origin remote URL" >&2
    # 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
+    }
    API_URL="https://${HOST}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}"
-
+    if [[ -n "${MOSAIC_GITEA_PR_METADATA_RAW_FILE:-}" ]]; then
-    GITEA_API_TOKEN=$(get_gitea_token "$HOST" || true)
+        RAW=$(cat "$MOSAIC_GITEA_PR_METADATA_RAW_FILE")
    if [[ -n "$GITEA_API_TOKEN" ]]; then
        RAW=$(curl -sS -H "Authorization: token $GITEA_API_TOKEN" "$API_URL")
    else
-        RAW=$(curl -sS "$API_URL")
+        RAW=$(curl_gitea_pull "$API_URL")
    fi
-    # Normalize Gitea response to match our expected schema
+    # Normalize Gitea response to match GitHub's expected metadata schema.
-    METADATA=$(echo "$RAW" | python3 -c "
+    METADATA=$(printf '%s' "$RAW" | python3 -c "
-import json, sys
+import json
 import sys
 def first_non_empty(*values):
    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):
    current = data
    for key in keys:
        if not isinstance(current, dict):
            return None
        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)
 normalized = {
    'number': data.get('number'),
    'title': data.get('title'),
    'body': data.get('body', ''),
    'state': data.get('state'),
-    'author': data.get('user', {}).get('login', ''),
+    'author': nested(data, 'user', 'login') or '',
-    'headRefName': data.get('head', {}).get('ref', ''),
+    'headRefName': head_ref,
-    'baseRefName': data.get('base', {}).get('ref', ''),
+    'baseRefName': base_ref,
-    'labels': [l.get('name', '') for l in data.get('labels', [])],
+    'labels': [l.get('name', '') for l in data.get('labels', []) if isinstance(l, dict)],
-    'assignees': [a.get('login', '') for a in data.get('assignees', [])],
+    'assignees': [a.get('login', '') for a in data.get('assignees', []) if isinstance(a, dict)],
-    'milestone': data.get('milestone', {}).get('title', '') if data.get('milestone') else '',
+    'milestone': nested(data, 'milestone', 'title') or '',
    'createdAt': data.get('created_at', ''),
    'updatedAt': data.get('updated_at', ''),
    'url': data.get('html_url', ''),
@@ -102,11 +215,7 @@ normalized = {
 json.dump(normalized, sys.stdout, indent=2)
 ")
-    if [[ -n "$OUTPUT_FILE" ]]; then
+    write_metadata "$METADATA"
        echo "$METADATA" > "$OUTPUT_FILE"
    else
        echo "$METADATA"
    fi
 else
    echo "Error: Unknown platform" >&2
    exit 1
--- a/packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh
+++ b/packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh
@@ -0,0 +1,87 @@
 #!/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"
--- a/packages/storage/src/migrate-tier.integration.test.ts
+++ b/packages/storage/src/migrate-tier.integration.test.ts
@@ -16,8 +16,15 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { users, teams, teamMembers, conversations, messages } from '@mosaicstack/db';
+import {
-import { createPgliteDbWithVector, runPgliteMigrations } from './test-utils/pglite-with-vector.js';
+  users,
  teams,
  teamMembers,
  conversations,
  messages,
  createPgliteDb,
  runPgliteMigrations,
 } from '@mosaicstack/db';
 import postgres from 'postgres';
 import { afterAll, describe, expect, it } from 'vitest';
@@ -102,11 +109,8 @@ describe.skipIf(!run)('migrate-tier — PGlite → federated PG', () => {
    /* ---- 1. Create a temp PGlite db ---------------------------------- */
    pgliteDataDir = await fs.mkdtemp(path.join(os.tmpdir(), 'fed-m1-08-'));
-    const handle = createPgliteDbWithVector(pgliteDataDir);
+    const handle = createPgliteDb(pgliteDataDir);
-
+    await runPgliteMigrations(handle);
    // Run Drizzle migrations against PGlite.
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    await runPgliteMigrations(handle.db as any);
    /* ---- 2. Seed representative data --------------------------------- */
--- a/packages/storage/src/test-utils/pglite-with-vector.ts
+++ b/packages/storage/src/test-utils/pglite-with-vector.ts
@@ -1,52 +0,0 @@
 /**
 * Test-only helpers for creating a PGlite database with the pgvector extension
 * and running Drizzle migrations against it.
 *
 * These are intentionally NOT exported from @mosaicstack/db to avoid pulling
 * the WASM vector bundle into the public API surface.
 */
 import { createRequire } from 'node:module';
 import { dirname, resolve } from 'node:path';
 import { PGlite } from '@electric-sql/pglite';
 import { vector } from '@electric-sql/pglite/vector';
 import { drizzle } from 'drizzle-orm/pglite';
 import { migrate as migratePglite } from 'drizzle-orm/pglite/migrator';
 import type { PgliteDatabase } from 'drizzle-orm/pglite';
 import * as schema from '@mosaicstack/db';
 import type { DbHandle } from '@mosaicstack/db';
 /**
 * Create a PGlite DB handle with the pgvector extension loaded.
 * Required for running Drizzle migrations that include `CREATE EXTENSION vector`.
 */
 export function createPgliteDbWithVector(dataDir: string): DbHandle {
  const client = new PGlite(dataDir, { extensions: { vector } });
  const db = drizzle(client, { schema });
  return {
    db: db as unknown as DbHandle['db'],
    close: async () => {
      await client.close();
    },
  };
 }
 /**
 * Run Drizzle migrations against an already-open PGlite database handle.
 * Resolves the migrations folder from @mosaicstack/db's installed location.
 *
 * @param db  A PgliteDatabase instance (from drizzle-orm/pglite).
 */
 export async function runPgliteMigrations(
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  db: PgliteDatabase<any>,
 ): Promise<void> {
  // Resolve @mosaicstack/db package root to locate its drizzle migrations folder.
  const _require = createRequire(import.meta.url);
  const dbPkgMain = _require.resolve('@mosaicstack/db');
  // dbPkgMain → …/packages/db/dist/index.js  →  dirname = dist/
  // go up one level from dist/ to find the sibling drizzle/ folder
  const migrationsFolder = resolve(dirname(dbPkgMain), '../drizzle');
  await migratePglite(db, { migrationsFolder });
 }
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -179,6 +179,9 @@ importers:
      socket.io:
        specifier: ^4.8.0
        version: 4.8.3
      undici:
        specifier: ^7.24.6
        version: 7.24.6
      uuid:
        specifier: ^11.0.0
        version: 11.1.0
@@ -713,10 +716,10 @@ importers:
    dependencies:
      '@mariozechner/pi-agent-core':
        specifier: ^0.63.1
-        version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)
+        version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)
      '@mariozechner/pi-ai':
        specifier: ^0.63.1
-        version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)
+        version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)
      '@sinclair/typebox':
        specifier: ^0.34.41
        version: 0.34.48
@@ -6993,10 +6996,6 @@ packages:
    resolution: {integrity: sha512-gBLkYIlEnSp8pFbT64yFgGE6UIB9tAkhukC23PmMDCe5Nd+cRqKxSjw5y54MK2AZMgZfJWMaNE4nYUHgi1XEOw==}
    engines: {node: '>=18.17'}
  undici@7.24.3:
    resolution: {integrity: sha512-eJdUmK/Wrx2d+mnWWmwwLRyA7OQCkLap60sk3dOK4ViZR7DKwwptwuIvFBg2HaiP9ESaEdhtpSymQPvytpmkCA==}
    engines: {node: '>=20.18.1'}
  undici@7.24.6:
    resolution: {integrity: sha512-Xi4agocCbRzt0yYMZGMA6ApD7gvtUFaxm4ZmeacWI4cZxaF6C+8I8QfofC20NAePiB/IcvZmzkJ7XPa471AEtA==}
    engines: {node: '>=20.18.1'}
@@ -7329,12 +7328,6 @@ snapshots:
      '@jridgewell/gen-mapping': 0.3.13
      '@jridgewell/trace-mapping': 0.3.31
  '@anthropic-ai/sdk@0.73.0(zod@3.25.76)':
    dependencies:
      json-schema-to-ts: 3.1.1
    optionalDependencies:
      zod: 3.25.76
  '@anthropic-ai/sdk@0.73.0(zod@4.3.6)':
    dependencies:
      json-schema-to-ts: 3.1.1
@@ -8676,18 +8669,6 @@ snapshots:
      - ws
      - zod
  '@mariozechner/pi-agent-core@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)':
    dependencies:
      '@mariozechner/pi-ai': 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)
    transitivePeerDependencies:
      - '@modelcontextprotocol/sdk'
      - aws-crt
      - bufferutil
      - supports-color
      - utf-8-validate
      - ws
      - zod
  '@mariozechner/pi-agent-core@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)':
    dependencies:
      '@mariozechner/pi-ai': 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)
@@ -8736,30 +8717,6 @@ snapshots:
      - ws
      - zod
  '@mariozechner/pi-ai@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)':
    dependencies:
      '@anthropic-ai/sdk': 0.73.0(zod@3.25.76)
      '@aws-sdk/client-bedrock-runtime': 3.1008.0
      '@google/genai': 1.45.0(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))
      '@mistralai/mistralai': 1.14.1
      '@sinclair/typebox': 0.34.48
      ajv: 8.18.0
      ajv-formats: 3.0.1(ajv@8.18.0)
      chalk: 5.6.2
      openai: 6.26.0(ws@8.20.0)(zod@3.25.76)
      partial-json: 0.1.7
      proxy-agent: 6.5.0
      undici: 7.24.3
      zod-to-json-schema: 3.25.1(zod@3.25.76)
    transitivePeerDependencies:
      - '@modelcontextprotocol/sdk'
      - aws-crt
      - bufferutil
      - supports-color
      - utf-8-validate
      - ws
      - zod
  '@mariozechner/pi-ai@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)':
    dependencies:
      '@anthropic-ai/sdk': 0.73.0(zod@4.3.6)
@@ -8773,7 +8730,7 @@ snapshots:
      openai: 6.26.0(ws@8.20.0)(zod@4.3.6)
      partial-json: 0.1.7
      proxy-agent: 6.5.0
-      undici: 7.24.3
+      undici: 7.24.6
      zod-to-json-schema: 3.25.1(zod@4.3.6)
    transitivePeerDependencies:
      - '@modelcontextprotocol/sdk'
@@ -12632,7 +12589,7 @@ snapshots:
      saxes: 6.0.0
      symbol-tree: 3.2.4
      tough-cookie: 6.0.1
-      undici: 7.24.3
+      undici: 7.24.6
      w3c-xmlserializer: 5.0.0
      webidl-conversions: 8.0.1
      whatwg-mimetype: 5.0.0
@@ -13352,11 +13309,6 @@ snapshots:
    dependencies:
      mimic-function: 5.0.1
  openai@6.26.0(ws@8.20.0)(zod@3.25.76):
    optionalDependencies:
      ws: 8.20.0
      zod: 3.25.76
  openai@6.26.0(ws@8.20.0)(zod@4.3.6):
    optionalDependencies:
      ws: 8.20.0
@@ -14488,8 +14440,6 @@ snapshots:
  undici@6.21.3: {}
  undici@7.24.3: {}
  undici@7.24.6: {}
  unhomoglyph@1.0.6: {}
--- a/scratchpads/fix-db-bootstrap-migrations.md
+++ b/scratchpads/fix-db-bootstrap-migrations.md
@@ -0,0 +1,125 @@
 # fix(db): bootstrap migrations on local-tier gateway startup
 ## Problem
 Fresh `mosaic gateway install` (npm-installed) leaves the gateway DB schema empty:
 ```
 relation "users" does not exist
 ```
 Sign-in 500s, `auth users create` says "Not signed in", `admin/bootstrap setup`
 also fails — every entry point queries `users` before doing anything else.
 ## Scope
 This PR fixes the **local (PGlite) tier** end-to-end. The postgres-tier path
 has additional pre-existing bugs (see "Known issues, out of scope" below) and
 needs a separate change with real Postgres validation.
 ## Root causes addressed (5 stacked bugs on the local-tier path)
 1. **`packages/db/package.json` `files: ["dist"]`** — the `drizzle/` SQL
   migrations folder is excluded from the published tarball. Even if a
   migrate runner existed, it would have nothing to apply.
 2. **`packages/db/src/migrate.ts`** only supports `postgres-js`. Local-tier
   gateways use embedded PGlite, which can't be reached over a postgres wire
   protocol — so `runMigrations()` is unusable for the local tier.
 3. **`apps/gateway/src/database/database.module.ts`** never invokes
   migrations at startup. The module creates the DB handle and storage
   adapter, but no consumer calls `.migrate()` on either. `mosaic storage
 migrate` CLI even claims "pglite runs schema setup automatically on first
   connection via `adapter.migrate()`" — but `adapter.migrate()` is only
   called by tests, never at runtime.
 4. **`createPgliteDb` does not load the pgvector extension.** Migration 0001
   declares `CREATE EXTENSION IF NOT EXISTS vector;` for the
   `insights.embedding` column. Bare PGlite has no pgvector — the migration
   fails on extension control file lookup.
 5. **Drizzle's PG migrator wraps every migration in one outer transaction.**
   Migration 0009 does `ALTER TYPE grant_status ADD VALUE 'pending'` and then
   `ALTER TABLE federation_grants ALTER COLUMN status SET DEFAULT 'pending'`.
   Postgres' `check_safe_enum_use` rejects the second statement because the
   new enum value isn't committed yet. Splitting the migration into two
   files doesn't help — drizzle batches all migrations into one outer tx.
 ## Fix
 - `packages/db/package.json` — ship `drizzle/` in `files`.
 - `packages/db/src/client-pglite.ts` — load `@electric-sql/pglite/vector`.
 - `packages/db/src/migrate.ts` — add `runPgliteMigrations(handle)`. Walks the
  Drizzle journal and runs each statement-breakpoint chunk through PGlite's
  `client.exec()` (Simple Query protocol → autocommit per statement). Writes
  to the standard `drizzle.__drizzle_migrations` ledger so the result is
  interoperable with `runMigrations()` on a postgres-backed deployment.
  Per-statement try/catch surfaces which statement of which migration failed
  and the ledger row is only written on full success.
 - `packages/db/src/index.ts` — re-export.
 - `apps/gateway/src/database/database.module.ts` — implement `OnModuleInit`:
  - Local tier → `runPgliteMigrations(handle)`, then `storageAdapter.migrate()`
    (the local storage adapter has its own kv tables in a separate PGlite dir).
  - Postgres tier → `storageAdapter.migrate()` only, since
    `PostgresAdapter.migrate()` already calls `runMigrations(url)` against
    the same DATABASE_URL — we deliberately don't double-call.
  NestJS awaits `onModuleInit` before `app.listen()`, so DB-dependent modules
  see a populated schema before any HTTP traffic is accepted.
 - `packages/storage/src/test-utils/pglite-with-vector.ts` — **deleted**.
  The "intentionally not exported" rationale is moot now that migration 0001
  forces pgvector load anyway. `migrate-tier.integration.test.ts` switched
  to `createPgliteDb` + `runPgliteMigrations` from `@mosaicstack/db`.
 ## Tests
 `packages/db/src/migrate.test.ts`:
 - Verifies `runPgliteMigrations` creates the BetterAuth tables (the original
  failure mode).
 - Idempotence (transitively re-runs migration 0009).
 - Partial-failure: pre-creates a conflicting `users` table, asserts the
  thrown error includes statement context (`hash=… statement #N failed`)
  and that no ledger row was written.
 ## QA evidence
 End-to-end on a fresh PGlite install:
 - `[DatabaseModule] Applying PGlite schema migrations...` then
  `Initializing storage adapter (pglite)...` in startup log.
 - `GET /api/bootstrap/status` → `{"needsSetup":true}` HTTP 200 (was 500
  with `relation "users" does not exist`).
 - `POST /api/bootstrap/setup` with empty body → HTTP 400 with Zod
  validation error (was 500), confirming the request reached the
  validator past the table-existence check.
 ## Known issues, out of scope (file separately)
 - **Postgres-tier first install is still broken.** `runMigrations()` uses
  Drizzle's `migratePostgres`, which has the same outer-transaction problem
  as PGlite's migrator. A fresh standalone-tier install would also fail at
  migration 0009. Inline TODO in `migrate.ts:31-35` flags this. Fixing it
  needs either (a) a shared per-statement loop reused for both drivers, or
  (b) splitting migration 0009.
 - **`drizzle/meta/_journal.json` has 0009 ordered before 0008** (`when`
  values `1745280000000` < `1776822435828`). `migratePostgres` skips by
  `created_at < folderMillis`, so on a postgres deployment that already
  applied 0008, 0009 would be skipped forever. Our hash-based skip in the
  PGlite path sidesteps this.
 - **No advisory lock around the migration loop.** Two gateway processes
  pointed at the same DATABASE_URL would race. PGlite is single-process by
  file lock so the local tier is fine; postgres-tier deployments should add
  `pg_advisory_lock(<deterministic-id>)` around the loop in a follow-up.
 - **`mosaic storage migrate` CLI message is misleading** — it claims
  "automatic on first connection via adapter.migrate()" but the adapter
  doesn't self-migrate. With this PR the gateway invokes it explicitly, but
  the CLI message could still be tightened.
 - **Crash mid-migration leaves a partial-state PGlite DB without a ledger
  row.** Detected loudly on next boot (the replay errors on "already
  exists"), but recovery is manual (drop the partially-applied objects or
  insert the migration hash into `drizzle.__drizzle_migrations`). A robust
  fix would add a "started_at" column to a sidecar table to detect
  half-applied state and refuse to start with actionable guidance.
Author	SHA1	Message	Date
Hermes Agent	a665c0ac4c	fix(git-tools): harden gitea pr metadata wrappers Some checks failed ci/woodpecker/push/ci Pipeline failed Details ci/woodpecker/pr/ci Pipeline failed Details	2026-05-22 11:23:36 -05:00
jason.woltje	755df9079e	Merge pull request 'fix(db): bootstrap migrations on local-tier gateway startup' (#510 ) from fix/db-bootstrap-migrations into main	2026-05-04 22:13:14 +00:00
jason.woltje	ac5650d9f9	fix(db): bootstrap migrations on local-tier gateway startup Fresh `mosaic gateway install` (npm) left the gateway DB schema empty — sign-in 500'd with `relation "users" does not exist`, and every entry point (auth, bootstrap setup) failed because they all query the users table first. Five stacked bugs on the local (PGlite) tier: 1. `packages/db/package.json` `files: ["dist"]` excluded the `drizzle/` SQL migrations from the published tarball. 2. `runMigrations()` only supports postgres-js — unusable for embedded PGlite. 3. `apps/gateway/src/database/database.module.ts` never invoked migrations at startup. 4. `createPgliteDb` didn't load pgvector, so migration 0001's `CREATE EXTENSION vector` failed. 5. Drizzle's PG migrator wraps every migration in one outer transaction, which trips Postgres' `check_safe_enum_use` on migration 0009 (`ALTER TYPE ADD VALUE 'pending'` → `SET DEFAULT 'pending'` in the same tx). Changes: - Ship `drizzle/` in the published tarball. - `createPgliteDb` loads `@electric-sql/pglite/vector`. - New `runPgliteMigrations(handle)` walks the Drizzle journal and runs each statement-breakpoint chunk through PGlite's `client.exec()` (autocommit per statement). Records into `drizzle.__drizzle_migrations` for interop with the postgres-js path. Per-statement try/catch surfaces which statement of which migration failed. - `DatabaseModule` runs migrations in `OnModuleInit` before `app.listen()`. Local tier: explicit `runPgliteMigrations` then `storageAdapter.migrate()`. Postgres tier: just `storageAdapter.migrate()`, which already calls `runMigrations(url)` internally — no double-call. - Removed `packages/storage/src/test-utils/pglite-with-vector.ts`. The "intentionally not exported" rationale is moot now that migration 0001 forces pgvector load anyway. The integration test uses `createPgliteDb` + `runPgliteMigrations` from `@mosaicstack/db`. Tests: BetterAuth tables exist after migrate; idempotent (re-runs 0009); partial-failure surfaces statement-level context and leaves no ledger row. QA on a fresh PGlite install: - `Applying PGlite schema migrations...` then `Initializing storage adapter (pglite)...` in startup log. - `GET /api/bootstrap/status` → `{"needsSetup":true}` HTTP 200 (was 500). - `POST /api/bootstrap/setup` reaches Zod validator (was 500). Scope: this PR fixes the local (PGlite) tier. Postgres-tier first install still has the outer-transaction problem and a journal ordering bug (0009's `when` < 0008's). Documented inline as TODO and in the scratchpad — needs a separate change with real-Postgres validation. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-04 17:06:50 -05:00
jason.woltje	bd83f86740	Merge pull request 'feat(federation): mTLS AuthGuard with OID-based grant resolution (FED-M3-03)' (#509 ) from feat/federation-m3-auth-guard into main All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-04-25 13:27:20 +00:00
Jarvis	0af3e218a1	fix(federation/auth-guard): remediate CRIT-1/CRIT-2 + HIGH-1..4 review findings All checks were successful ci/woodpecker/pr/ci Pipeline was successful Details ci/woodpecker/push/ci Pipeline was successful Details - CRIT-1: Validate cert subjectUserId against grant.subjectUserId from DB; use authoritative DB value in FederationContext - CRIT-2: Add @Inject(GrantsService) decorator (tsx/esbuild requirement) - HIGH-1: Validate UTF8String TLV tag, length, and bounds in OID parser - HIGH-2: Collapse all 403 wire messages to a generic string to prevent grant enumeration; keep internal logger detail - HIGH-3: Assert federation wire envelope shape in all guard tests - HIGH-4: Regression test for subjectUserId cert/DB mismatch Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-25 06:33:37 -05:00
Jarvis	b01c9b3bb0	feat(federation): mTLS AuthGuard with OID-based grant resolution (FED-M3-03) Adds FederationAuthGuard that validates inbound mTLS client certs on federation API routes. Extracts custom OIDs (grantId, subjectUserId), loads the grant+peer from DB in one query, asserts active status, and validates cert serial as defense-in-depth. Attaches FederationContext to requests on success and uses federation wire-format error envelopes (not raw NestJS exceptions) for 401/403 responses. New files: - apps/gateway/src/federation/oid.util.ts — shared OID extraction (no dupe ASN.1 logic) - apps/gateway/src/federation/server/federation-auth.guard.ts — guard impl - apps/gateway/src/federation/server/federation-context.ts — FederationContext type + module augment - apps/gateway/src/federation/server/index.ts — barrel export - apps/gateway/src/federation/server/__tests__/federation-auth.guard.spec.ts — 11 unit tests Modified: - apps/gateway/src/federation/grants.service.ts — adds getGrantWithPeer() with join - apps/gateway/src/federation/federation.module.ts — registers FederationAuthGuard as provider Closes #462 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-25 06:33:37 -05:00
jason.woltje	b67f2c9f08	Merge pull request 'feat(federation): outbound mTLS FederationClient (FED-M3-08)' (#508 ) from feat/federation-m3-client into main All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-04-24 04:30:29 +00:00
Jarvis	37675ae3f2	fix(federation/client): serialize cache fills, destroy evicted Agent, cover env-var guard All checks were successful ci/woodpecker/pr/ci Pipeline was successful Details ci/woodpecker/push/ci Pipeline was successful Details - HIGH-A: resolveEntry now uses promise-cache pattern so concurrent callers serialize on a single in-flight build, eliminating duplicate key material in heap and duplicate DB round-trips - HIGH-B: flushPeer destroys the evicted undici Agent so stale TLS connections close on cert rotation - MED-C: add regression test for PEER_MISCONFIGURED when STEP_CA_ROOT_CERT_PATH is unset Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-23 22:56:57 -05:00
Jarvis	a4a6769a6d	fix(federation/client): pin Step-CA root, fix lockfile, harden cache test All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/pr/ci Pipeline was successful Details CRIT-1: regenerate pnpm-lock.yaml so apps/gateway resolves undici@7.24.6 (prior PR pushed package.json without lockfile update; CI failed with ERR_PNPM_OUTDATED_LOCKFILE). Incidentally cleans 57 lines of stale peer-dep entries. CRIT-2: cache-hit test no longer swallows resolveEntry errors. Calls the private method directly twice and asserts identity equality plus a single DB select, removing the silent-failure path the prior assertion allowed. HIGH-1: mTLS Agent now pins Step-CA root via STEP_CA_ROOT_CERT_PATH. Without the env var resolveEntry throws PEER_MISCONFIGURED, refusing to dial peers against the public trust store. PEM is read once and cached on the service instance. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-04-23 22:30:09 -05:00
Jarvis	21650fb194	feat(federation): outbound mTLS FederationClient (FED-M3-08) Some checks failed ci/woodpecker/push/ci Pipeline failed Details ci/woodpecker/pr/ci Pipeline failed Details Implements FederationClientService — a NestJS injectable that dials peer gateways over mTLS (undici Agent with cert+sealed-key from federation_peers), invokes list/get/capabilities verbs, validates responses via Zod, and surfaces all failure modes as typed FederationClientError with a coherent error code taxonomy (PEER_NOT_FOUND, PEER_INACTIVE, PEER_MISCONFIGURED, NETWORK, FORBIDDEN, HTTP_{status}, INVALID_RESPONSE). Per-peer Agent instances are cached in a Map for the service lifetime; flushPeer(peerId) invalidates the cache for M5/M6 cert rotation and revocation events. Wired into FederationModule providers + exports so QuerySourceService (M3-09) can inject it. 13 unit tests covering all required scenarios via undici MockAgent + real sealClientKey/unsealClientKey round-trip. Closes #462 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-23 22:16:52 -05:00
jason.woltje	89c733e0b9	feat(federation): two-gateway test harness scaffold (FED-M3-02) (#505 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-04-24 03:01:25 +00:00