fix(#707): scope session GC retention

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

.gitignore

@@ -9,3 +9,16 @@ coverage
 *.tsbuildinfo
 .pnpm-store
 docs/reports/
+
+# Step-CA dev password — real file is gitignored; commit only the .example
+infra/step-ca/dev-password
+
+# Scratch dirs created by the framework git-wrapper shell test harnesses
+.mosaic-test-work/
+
+# Transient config files vite/vitest/esbuild write next to a *.config.ts while
+# loading it, then unlink. They are untracked but were not ignored, so turbo's
+# package traversal hashed them and intermittently failed CI with "Package
+# traversal error: ... .timestamp-*.mjs: No such file or directory" when the
+# file vanished mid-scan. Ignoring them removes the race.
+*.timestamp-*.mjs

.npmrc

@@ -1 +1,5 @@
 @mosaicstack:registry=https://git.mosaicstack.dev/api/packages/mosaicstack/npm/
+# Pin the pnpm store to the same path the ci-base image warms (Dockerfile.ci),
+# so the pipeline `pnpm install --prefer-offline` consumes the baked store
+# instead of repopulating a fresh one.
+store-dir=/root/.local/share/pnpm/store

.prettierignore

@@ -5,3 +5,5 @@ pnpm-lock.yaml
 **/drizzle
 **/.next
 .claude/
+docs/tess/TASKS.md
+docs/scratchpads/

.woodpecker/ci-image.yml

@@ -0,0 +1,40 @@
+# Build & push the pre-baked CI base image (Dockerfile.ci) to the Gitea
+# registry CI already publishes to. Reuses the exact kaniko + auth pattern
+# from publish.yml (REGISTRY_USER/REGISTRY_PASS from_secret, /kaniko/.docker
+# config.json). Other pipelines (ci.yml, publish.yml) pull `ci-base:latest`
+# for their install step.
+#
+# Rebuild ONLY when the dependency set or the image recipe changes — a normal
+# code push must not trigger a 25-min image build. `path` applies to push/PR
+# events; `event: tag` (releases) rebuilds unconditionally so a tagged release
+# always ships a fresh base.
+when:
+  - event: tag
+  - event: [push, manual]
+    branch: main
+    path:
+      include:
+        - 'pnpm-lock.yaml'
+        - 'Dockerfile.ci'
+
+steps:
+  build-ci-base:
+    image: gcr.io/kaniko-project/executor:debug
+    environment:
+      REGISTRY_USER:
+        from_secret: gitea_username
+      REGISTRY_PASS:
+        from_secret: gitea_password
+      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
+      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
+      CI_COMMIT_SHA: ${CI_COMMIT_SHA}
+    commands:
+      - mkdir -p /kaniko/.docker
+      - echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$REGISTRY_USER\",\"password\":\"$REGISTRY_PASS\"}}}" > /kaniko/.docker/config.json
+      - |
+        # Lockfile-hash tag: an immutable identity for the exact dep set baked
+        # into this image. `:latest` is the mutable pointer pipelines consume.
+        LOCK_HASH=$(sha256sum pnpm-lock.yaml | cut -c1-12)
+        DESTINATIONS="--destination git.mosaicstack.dev/mosaicstack/stack/ci-base:latest"
+        DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/ci-base:lock-$LOCK_HASH"
+        /kaniko/executor --context . --dockerfile Dockerfile.ci $DESTINATIONS

.woodpecker/ci.yml

@@ -1,9 +1,20 @@
+# &node_image is the pre-baked CI base built by .woodpecker/ci-image.yml:
+# node:24-alpine + python3/make/g++/postgresql-client + pnpm + a warm pnpm
+# store. The install step resolves from the baked store (--prefer-offline)
+# instead of paying a ~731s cold fetch + native compile every run.
 variables:
-  - &node_image 'node:22-alpine'
+  - &node_image 'git.mosaicstack.dev/mosaicstack/stack/ci-base:latest'
   - &enable_pnpm 'corepack enable'
 
 when:
-  - event: [push, pull_request, manual]
+  # PR + manual CI run on any branch — the pull_request pipeline is the merge gate.
+  # push CI is restricted to protected branches (main) so a feature-branch push no
+  # longer fires a redundant SECOND pipeline alongside its PR pipeline. This ~halves
+  # CI load on the storage-constrained runner with zero loss of gating (branch
+  # protection requires no push/ci status context; main still gets full push CI).
+  - event: [pull_request, manual]
+  - event: push
+    branch: main
 
 # Turbo remote cache (turbo.mosaicstack.dev) is configured via Woodpecker
 # repository-level environment variables (TURBO_API, TURBO_TEAM, TURBO_TOKEN).
@@ -15,8 +26,21 @@ steps:
     image: *node_image
     commands:
       - corepack enable
-      - apk add --no-cache python3 make g++
-      - pnpm install --frozen-lockfile
+      # python3/make/g++ are baked into ci-base; --prefer-offline resolves from
+      # the baked pnpm store.
+      - pnpm install --frozen-lockfile --prefer-offline
+
+  # Blocking gate: public framework package must contain no operator-specific
+  # personal data or private $HOME defaults. Runs early (no node_modules needed).
+  sanitization:
+    image: *node_image
+    commands:
+      - apk add --no-cache bash
+      - bash packages/mosaic/framework/tools/quality/scripts/verify-sanitized.sh
+      # Resident line-count ceiling over framework-owned resident files
+      # (Constitution + dispatcher + each RUNTIME.md slice). See DESIGN §7 / R9.
+      - bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh --self-test
+      - bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh
 
   typecheck:
     image: *node_image
@@ -25,6 +49,7 @@ steps:
       - pnpm typecheck
     depends_on:
       - install
+      - sanitization
 
   # lint, format, and test are independent — run in parallel after typecheck
   lint:
@@ -46,18 +71,27 @@ steps:
   test:
     image: *node_image
     environment:
-      DATABASE_URL: postgresql://mosaic:mosaic@postgres:5432/mosaic
+      # Avoid the namespace-level Woodpecker DB service named "postgres".
+      # The Kubernetes backend exposes service containers by step name.
+      DATABASE_URL: postgresql://mosaic:mosaic@ci-postgres:5432/mosaic
     commands:
       - *enable_pnpm
-      # Install postgresql-client for pg_isready
-      - apk add --no-cache postgresql-client
-      # Wait up to 30s for postgres to be ready
+      # postgresql-client (pg_isready) is baked into ci-base.
+      # Wait up to 60s for CI postgres to be ready; fail fast if it never comes up.
       - |
-        for i in $(seq 1 30); do
-          pg_isready -h postgres -p 5432 -U mosaic && break
-          echo "Waiting for postgres ($i/30)..."
+        ready=0
+        for i in $(seq 1 60); do
+          if pg_isready -h ci-postgres -p 5432 -U mosaic; then
+            ready=1
+            break
+          fi
+          echo "Waiting for ci-postgres ($i/60)..."
           sleep 1
         done
+        if [ "$ready" -ne 1 ]; then
+          echo "ci-postgres did not become ready" >&2
+          exit 1
+        fi
       # Run migrations (DATABASE_URL is set in environment above)
       - pnpm --filter @mosaicstack/db run db:migrate
       # Run all tests
@@ -66,7 +100,7 @@ steps:
       - typecheck
 
 services:
-  postgres:
+  ci-postgres:
     image: pgvector/pgvector:pg17
     environment:
       POSTGRES_USER: mosaic

.woodpecker/publish.yml

@@ -2,8 +2,27 @@
 # Runs only on main branch push/tag
 
 variables:
-  - &node_image 'node:22-alpine'
+  # Pre-baked CI base (see .woodpecker/ci-image.yml): node:24-alpine +
+  # toolchain + warm pnpm store. Kills the second cold install publish pays.
+  - &node_image 'git.mosaicstack.dev/mosaicstack/stack/ci-base:latest'
   - &enable_pnpm 'corepack enable'
+  # Heavy kaniko image builds (~25 min) — gate them so a merge that only touches
+  # the npm-only CLI (@mosaicstack/mosaic) or docs does NOT rebuild the platform
+  # images (gateway/appservice/web do not depend on @mosaicstack/mosaic). Releases
+  # (tags) always build everything. Exclude-list keeps the default SAFE: any
+  # non-excluded change still builds, so no transitive dep can silently go stale.
+  # (Woodpecker: `when` entries are OR'd; `path` applies to push/PR only — hence
+  # the separate `event: tag` entry.)
+  - &image_build_when
+    - event: tag
+    - event: [push, manual]
+      branch: main
+      path:
+        exclude:
+          - 'packages/mosaic/**'
+          - 'docs/**'
+          - '**/*.md'
+          - '.woodpecker/**'
 
 when:
   - branch: [main]
@@ -14,7 +33,8 @@ steps:
     image: *node_image
     commands:
       - corepack enable
-      - pnpm install --frozen-lockfile
+      # Resolve from the baked pnpm store instead of a cold network fetch.
+      - pnpm install --frozen-lockfile --prefer-offline
 
   build:
     image: *node_image
@@ -26,6 +46,15 @@ steps:
 
   publish-npm:
     image: *node_image
+    # Publish only when a publishable package changed (or on a release tag); a
+    # pure-docs merge runs no publish. Cheap step, but gated for cleanliness.
+    when:
+      - event: tag
+      - event: [push, manual]
+        branch: main
+        path:
+          include:
+            - 'packages/**'
     environment:
       NPM_TOKEN:
         from_secret: gitea_token
@@ -91,6 +120,7 @@ steps:
 
   build-gateway:
     image: gcr.io/kaniko-project/executor:debug
+    when: *image_build_when
     environment:
       REGISTRY_USER:
         from_secret: gitea_username
@@ -114,8 +144,35 @@ steps:
     depends_on:
       - build
 
+  build-appservice:
+    image: gcr.io/kaniko-project/executor:debug
+    when: *image_build_when
+    environment:
+      REGISTRY_USER:
+        from_secret: gitea_username
+      REGISTRY_PASS:
+        from_secret: gitea_password
+      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
+      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
+      CI_COMMIT_SHA: ${CI_COMMIT_SHA}
+    commands:
+      - mkdir -p /kaniko/.docker
+      - echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$REGISTRY_USER\",\"password\":\"$REGISTRY_PASS\"}}}" > /kaniko/.docker/config.json
+      - |
+        DESTINATIONS="--destination git.mosaicstack.dev/mosaicstack/stack/appservice:sha-${CI_COMMIT_SHA:0:7}"
+        if [ "$CI_COMMIT_BRANCH" = "main" ]; then
+          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/appservice:latest"
+        fi
+        if [ -n "$CI_COMMIT_TAG" ]; then
+          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/appservice:$CI_COMMIT_TAG"
+        fi
+        /kaniko/executor --context . --dockerfile docker/appservice.Dockerfile $DESTINATIONS
+    depends_on:
+      - build
+
   build-web:
     image: gcr.io/kaniko-project/executor:debug
+    when: *image_build_when
     environment:
       REGISTRY_USER:
         from_secret: gitea_username

Dockerfile.ci

@@ -0,0 +1,45 @@
+# Pre-baked CI base image for Woodpecker pipelines.
+#
+# Purpose: eliminate the cold `pnpm install` that dominates every pipeline
+# (~731s median). This image ships the native toolchain (no per-run `apk add`)
+# AND a warm, content-addressable pnpm store with the dependency-tree tarballs
+# already fetched at build time. `pnpm fetch` only populates the store from the
+# lockfile — it does NOT run the native node-gyp builds (better-sqlite3,
+# node-pty, sqlite3, canvas, sharp); those still compile at `pnpm install`,
+# which is exactly why the musl toolchain stays baked into this image. A
+# pipeline `pnpm install --frozen-lockfile --prefer-offline` then resolves
+# tarballs from local hard-links (no network) and compiles natives against the
+# already-present toolchain, in tens of seconds instead of ~731s.
+#
+# Rebuilt only when `pnpm-lock.yaml` or this Dockerfile change
+# (see .woodpecker/ci-image.yml).
+#
+# Node version is pinned to 24 (Active LTS). This is the follow-up bump from
+# node:22 — sequenced AFTER the CI cache work landed so the runtime change
+# carries zero cache variables. node:26 stays held until it reaches LTS
+# (Oct 2026); the Current line risks native-module (node-gyp) breakage on a
+# runner that compiles better-sqlite3 / canvas / sharp / node-pty from source.
+FROM node:24-alpine
+
+# Native toolchain required to compile node-gyp deps on musl, plus the
+# postgresql-client used by the test step's pg_isready readiness probe. `bash`
+# is baked here too — the sanitization step in ci.yml otherwise does a per-run
+# `apk add bash`.
+RUN apk add --no-cache python3 make g++ postgresql-client bash
+
+# Pin pnpm to the repo's packageManager version via corepack.
+RUN corepack enable && corepack prepare pnpm@10.6.2 --activate
+
+WORKDIR /app
+
+# Pin the store location so the pipeline can point `store-dir` at the same path.
+ENV PNPM_HOME=/root/.local/share/pnpm
+RUN pnpm config set store-dir /root/.local/share/pnpm/store
+
+# Warm the store. `pnpm fetch` populates the content-addressable store with the
+# dependency tarballs directly from the lockfile (no package.json / workspace
+# needed), so a baked store stays valid until the lockfile changes. Note:
+# `fetch` does NOT compile native modules — that happens later at `pnpm install`
+# in the pipeline, against the toolchain baked above.
+COPY pnpm-lock.yaml ./
+RUN pnpm fetch --frozen-lockfile

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mosaic Stack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

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

apps/appservice/package.json

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

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

@@ -0,0 +1,388 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { AppserviceDaemon } from '../server.js';
+import type { DaemonConfig, DaemonRequest } from '../server.js';
+
+const AGENTS_TYPE = 'org.uscllc.mosaic_as.agents';
+
+const cfg: DaemonConfig = {
+  homeserverUrl: 'https://hs.example',
+  domain: 'hs.example',
+  asToken: 'as-secret',
+  hsToken: 'hs-secret',
+  bridgeTokens: ['bridge-secret'],
+};
+
+const jsonResponse = (status: number, body: unknown): Response =>
+  new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } });
+
+const request = (overrides: Partial<DaemonRequest>): DaemonRequest => ({
+  method: 'GET',
+  path: '/',
+  searchParams: new URLSearchParams(),
+  body: undefined,
+  ...overrides,
+});
+
+const makeDaemon = () => {
+  const fetchMock = vi.fn(async (_input: URL | string) => jsonResponse(200, { event_id: '$sent' }));
+  const daemon = new AppserviceDaemon(cfg, fetchMock as unknown as typeof fetch, () => {});
+  return { daemon, fetchMock };
+};
+
+describe('AppserviceDaemon routing', () => {
+  it('serves health unauthenticated', async () => {
+    const { daemon } = makeDaemon();
+    expect((await daemon.handle(request({ path: '/health' }))).status).toBe(200);
+  });
+
+  it('404s unknown paths', async () => {
+    const { daemon } = makeDaemon();
+    expect((await daemon.handle(request({ path: '/nope' }))).status).toBe(404);
+  });
+
+  it('transactions require the hs_token', async () => {
+    const { daemon } = makeDaemon();
+    const bad = await daemon.handle(
+      request({
+        method: 'PUT',
+        path: '/_matrix/app/v1/transactions/t1',
+        authorizationHeader: 'Bearer wrong',
+        body: { events: [] },
+      }),
+    );
+    expect(bad.status).toBe(403);
+    const ok = await daemon.handle(
+      request({
+        method: 'PUT',
+        path: '/_matrix/app/v1/transactions/t1',
+        authorizationHeader: 'Bearer hs-secret',
+        body: { events: [{ type: 'm.room.message', event_id: '$e' }] },
+      }),
+    );
+    expect(ok.status).toBe(200);
+  });
+
+  it('bridge requires a bridge token (hs/as tokens do not work)', async () => {
+    const { daemon } = makeDaemon();
+    for (const token of [undefined, 'Bearer hs-secret', 'Bearer as-secret', 'Bearer nope']) {
+      const res = await daemon.handle(
+        request({
+          method: 'POST',
+          path: '/bridge/v1/messages',
+          authorizationHeader: token,
+          body: {},
+        }),
+      );
+      expect(res.status).toBe(403);
+    }
+  });
+
+  it('bridge message sends as the agent and returns the event id', async () => {
+    const { daemon, fetchMock } = makeDaemon();
+    const res = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/messages',
+        authorizationHeader: 'Bearer bridge-secret',
+        body: { room_id: '!r:hs.example', agent: 'pi0-web1', body: 'hi', thread_root: '$req' },
+      }),
+    );
+    expect(res.status).toBe(200);
+    expect(res.body.event_id).toBe('$sent');
+    const sendCall = fetchMock.mock.calls
+      .map((c) => new URL(String(c[0])))
+      .find((u) => u.pathname.includes('/send/m.room.message/'));
+    expect(sendCall).toBeDefined();
+    expect(sendCall!.searchParams.get('user_id')).toBe('@agent-pi0-web1:hs.example');
+  });
+
+  it('bridge rejects invalid payloads with 400', async () => {
+    const { daemon } = makeDaemon();
+    const res = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/messages',
+        authorizationHeader: 'Bearer bridge-secret',
+        body: { room_id: 'bad', agent: 'pi0', body: 'x' },
+      }),
+    );
+    expect(res.status).toBe(400);
+  });
+
+  it('bridge typing endpoint works', async () => {
+    const { daemon, fetchMock } = makeDaemon();
+    const res = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/typing',
+        authorizationHeader: 'Bearer bridge-secret',
+        body: { room_id: '!r:hs.example', agent: 'pi0-web1', typing: true },
+      }),
+    );
+    expect(res.status).toBe(200);
+    const typingCall = fetchMock.mock.calls
+      .map((c) => new URL(String(c[0])))
+      .find((u) => u.pathname.includes('/typing/'));
+    expect(typingCall).toBeDefined();
+  });
+
+  it('authenticated unknown bridge sub-paths return 405, never fall through', async () => {
+    const { daemon } = makeDaemon();
+    const res = await daemon.handle(
+      request({
+        method: 'GET',
+        path: '/bridge/v1/unknown',
+        authorizationHeader: 'Bearer bridge-secret',
+      }),
+    );
+    expect(res.status).toBe(405);
+  });
+
+  it('provisions a room as the AS sender with space linking', async () => {
+    const calls: Array<{ url: URL; body: unknown }> = [];
+    const fetchMock = vi.fn(async (input: URL | string, init?: RequestInit) => {
+      const url = new URL(String(input));
+      calls.push({ url, body: init?.body ? JSON.parse(String(init.body)) : undefined });
+      if (url.pathname.endsWith('/createRoom'))
+        return jsonResponse(200, { room_id: '!new:hs.example' });
+      return jsonResponse(200, {});
+    });
+    const daemon = new AppserviceDaemon(cfg, fetchMock as unknown as typeof fetch, () => {});
+    const res = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/provision/rooms',
+        authorizationHeader: 'Bearer bridge-secret',
+        body: {
+          name: 'proj-x',
+          alias: 'mosaic-proj-x',
+          invite: ['@jason.woltje:hs.example'],
+          space_id: '!space:hs.example',
+        },
+      }),
+    );
+    expect(res.status).toBe(200);
+    expect(res.body.room_id).toBe('!new:hs.example');
+    expect(res.body.space_linked).toBe(true);
+    const create = calls.find((c) => c.url.pathname.endsWith('/createRoom'));
+    expect(create!.url.searchParams.get('user_id')).toBe('@mosaic-as:hs.example');
+    const body = create!.body as Record<string, unknown>;
+    expect(body.room_alias_name).toBe('mosaic-proj-x');
+    expect((body.power_level_content_override as Record<string, unknown>).users).toEqual({
+      '@mosaic-as:hs.example': 100,
+    });
+    expect(calls.some((c) => c.url.pathname.includes('/state/m.space.child/'))).toBe(true);
+    expect(calls.some((c) => c.url.pathname.includes('/state/m.space.parent/'))).toBe(true);
+  });
+
+  it('space-link failure still returns the room id (no orphan)', async () => {
+    const fetchMock = vi.fn(async (input: URL | string) => {
+      const url = new URL(String(input));
+      if (url.pathname.endsWith('/createRoom'))
+        return jsonResponse(200, { room_id: '!new:hs.example' });
+      if (url.pathname.includes('/state/m.space.child/'))
+        return jsonResponse(403, { errcode: 'M_FORBIDDEN', error: 'no PL in space' });
+      return jsonResponse(200, {});
+    });
+    const daemon = new AppserviceDaemon(cfg, fetchMock as unknown as typeof fetch, () => {});
+    const res = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/provision/rooms',
+        authorizationHeader: 'Bearer bridge-secret',
+        body: { name: 'proj-x', space_id: '!space:hs.example' },
+      }),
+    );
+    expect(res.status).toBe(200);
+    expect(res.body.room_id).toBe('!new:hs.example');
+    expect(res.body.space_linked).toBe(false);
+    expect(String(res.body.space_error)).toContain('403');
+  });
+
+  it('invite list cap enforced', async () => {
+    const { daemon } = makeDaemon();
+    const res = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/provision/rooms',
+        authorizationHeader: 'Bearer bridge-secret',
+        body: { name: 'x', invite: Array.from({ length: 51 }, (_, i) => `@u${i}:hs`) },
+      }),
+    );
+    expect(res.status).toBe(400);
+  });
+
+  it('provision rejects bad payloads and requires auth', async () => {
+    const { daemon } = makeDaemon();
+    const noAuth = await daemon.handle(
+      request({ method: 'POST', path: '/bridge/v1/provision/rooms', body: { name: 'x' } }),
+    );
+    expect(noAuth.status).toBe(403);
+    const bad = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/provision/rooms',
+        authorizationHeader: 'Bearer bridge-secret',
+        body: { name: '', alias: 'BAD ALIAS' },
+      }),
+    );
+    expect(bad.status).toBe(400);
+  });
+
+  // A daemon whose fetch mock backs account_data with a mutable in-test object,
+  // so register/verify/revoke round-trip through the (faked) homeserver.
+  const makeAgentDaemon = () => {
+    const accountData: { value: Record<string, unknown> | null } = { value: null };
+    const fetchMock = vi.fn(async (input: URL | string, init?: RequestInit) => {
+      const url = new URL(String(input));
+      const path = url.pathname;
+      if (path.includes(`/account_data/${AGENTS_TYPE}`)) {
+        if (init?.method === 'PUT') {
+          accountData.value = JSON.parse(String(init.body)) as Record<string, unknown>;
+          return jsonResponse(200, {});
+        }
+        if (accountData.value === null) {
+          return jsonResponse(404, { errcode: 'M_NOT_FOUND', error: 'not found' });
+        }
+        return jsonResponse(200, accountData.value);
+      }
+      if (path.endsWith('/register')) return jsonResponse(200, { user_id: 'whatever' });
+      if (path.includes('/send/m.room.message/')) return jsonResponse(200, { event_id: '$sent' });
+      return jsonResponse(200, {});
+    });
+    const daemon = new AppserviceDaemon(cfg, fetchMock as unknown as typeof fetch, () => {});
+    return { daemon, fetchMock };
+  };
+
+  const registerAgent = async (
+    daemon: AppserviceDaemon,
+    body: Record<string, unknown> = { alias: 'pi0', host: 'web1' },
+  ) =>
+    daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/agents',
+        authorizationHeader: 'Bearer bridge-secret',
+        body,
+      }),
+    );
+
+  it('host token registers an agent and returns agent_user_id + bridge_token', async () => {
+    const { daemon, fetchMock } = makeAgentDaemon();
+    const res = await registerAgent(daemon, { alias: 'pi0', host: 'web1' });
+    expect(res.status).toBe(200);
+    expect(res.body.agent_user_id).toBe('@agent-pi0-web1:hs.example');
+    expect(String(res.body.bridge_token).startsWith('magt_')).toBe(true);
+    const registerCall = fetchMock.mock.calls
+      .map((c) => new URL(String(c[0])))
+      .find((u) => u.pathname.endsWith('/register'));
+    expect(registerCall).toBeDefined();
+  });
+
+  it('register requires a HOST token (agent token and no token are 403)', async () => {
+    const { daemon } = makeAgentDaemon();
+    const minted = await registerAgent(daemon);
+    const agentToken = String(minted.body.bridge_token);
+
+    const asAgent = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/agents',
+        authorizationHeader: `Bearer ${agentToken}`,
+        body: { alias: 'pi1', host: 'web2' },
+      }),
+    );
+    expect(asAgent.status).toBe(403);
+
+    const noAuth = await daemon.handle(
+      request({ method: 'POST', path: '/bridge/v1/agents', body: { alias: 'pi1', host: 'web2' } }),
+    );
+    expect(noAuth.status).toBe(403);
+  });
+
+  it('agent-scoped token may send as itself but not as another agent', async () => {
+    const { daemon } = makeAgentDaemon();
+    const minted = await registerAgent(daemon, { alias: 'pi0', host: 'web1' });
+    const agentToken = String(minted.body.bridge_token);
+
+    const self = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/messages',
+        authorizationHeader: `Bearer ${agentToken}`,
+        body: { room_id: '!r:hs.example', agent: 'pi0-web1', body: 'hi' },
+      }),
+    );
+    expect(self.status).toBe(200);
+
+    const other = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/messages',
+        authorizationHeader: `Bearer ${agentToken}`,
+        body: { room_id: '!r:hs.example', agent: 'pi9-web9', body: 'hi' },
+      }),
+    );
+    expect(other.status).toBe(403);
+    expect(other.body.error).toBe('token not scoped to this agent');
+  });
+
+  it('revoked agent token is rejected on messages', async () => {
+    const { daemon } = makeAgentDaemon();
+    const minted = await registerAgent(daemon, { alias: 'pi0', host: 'web1' });
+    const agentToken = String(minted.body.bridge_token);
+
+    const revoke = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/agents/revoke',
+        authorizationHeader: 'Bearer bridge-secret',
+        body: { agent_user_id: '@agent-pi0-web1:hs.example' },
+      }),
+    );
+    expect(revoke.status).toBe(200);
+    expect(revoke.body.revoked).toBe(1);
+
+    const afterRevoke = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/messages',
+        authorizationHeader: `Bearer ${agentToken}`,
+        body: { room_id: '!r:hs.example', agent: 'pi0-web1', body: 'hi' },
+      }),
+    );
+    expect(afterRevoke.status).toBe(403);
+  });
+
+  it('GET /bridge/v1/agents lists registered agents (host only)', async () => {
+    const { daemon } = makeAgentDaemon();
+    await registerAgent(daemon, { alias: 'pi0', host: 'web1', display_name: 'Pi Zero' });
+
+    const res = await daemon.handle(
+      request({
+        method: 'GET',
+        path: '/bridge/v1/agents',
+        authorizationHeader: 'Bearer bridge-secret',
+      }),
+    );
+    expect(res.status).toBe(200);
+    const agents = res.body.agents as Array<Record<string, unknown>>;
+    expect(agents).toHaveLength(1);
+    expect(agents[0]?.agent_user_id).toBe('@agent-pi0-web1:hs.example');
+    expect(agents[0]?.display_name).toBe('Pi Zero');
+  });
+
+  it('empty bridge token list denies everything', async () => {
+    const daemon = new AppserviceDaemon({ ...cfg, bridgeTokens: [] }, undefined, () => {});
+    const res = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/typing',
+        authorizationHeader: 'Bearer bridge-secret',
+        body: {},
+      }),
+    );
+    expect(res.status).toBe(403);
+  });
+});

apps/appservice/src/config.ts

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

apps/appservice/src/main.ts

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

apps/appservice/src/registration-main.ts

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

apps/appservice/src/server.ts

@@ -0,0 +1,225 @@
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+
+import {
+  AgentTokenStore,
+  AppserviceIntent,
+  TransactionHandler,
+  validateBridgeMessage,
+  validateBridgeTyping,
+  validateProvisionRoom,
+  validateRegisterAgent,
+  validateRevokeAgent,
+} from '@mosaicstack/appservice';
+import type { AppserviceConfig, MatrixEvent } from '@mosaicstack/appservice';
+
+export interface DaemonConfig extends AppserviceConfig {
+  /** Bearer tokens accepted on /bridge/v1/* (one per agent-comms host daemon). */
+  bridgeTokens: string[];
+}
+
+export interface DaemonRequest {
+  method: string;
+  /** URL path without query string. */
+  path: string;
+  searchParams: URLSearchParams;
+  authorizationHeader?: string;
+  body: unknown;
+}
+
+export interface DaemonResponse {
+  status: number;
+  body: Record<string, unknown>;
+}
+
+// Compare equal-length HMAC digests so neither content nor LENGTH of the
+// stored secret is observable through timing.
+const HMAC_KEY = randomBytes(32);
+const digest = (value: string): Buffer => createHmac('sha256', HMAC_KEY).update(value).digest();
+
+const safeEqual = (a: string, b: string): boolean => timingSafeEqual(digest(a), digest(b));
+
+const TXN_PATH = /^\/_matrix\/app\/v1\/transactions\/([^/]+)$/;
+
+/**
+ * Resolved identity for an authenticated /bridge/v1/* caller. Host principals
+ * (the agent-comms host daemons) are unrestricted; agent principals are scoped
+ * to a single virtual user and may only act as themselves.
+ */
+export type BridgePrincipal = { kind: 'host' } | { kind: 'agent'; agentUserId: string } | null;
+
+/**
+ * HTTP-framework-agnostic request router for the mosaic-as daemon: the
+ * Application Service transactions endpoint (Synapse-facing) plus the
+ * internal bridge API v1 (agent-comms daemon-facing). main.ts binds this to
+ * node:http; tests drive it directly.
+ */
+export class AppserviceDaemon {
+  readonly intent: AppserviceIntent;
+  private readonly transactions: TransactionHandler;
+  private readonly agents: AgentTokenStore;
+
+  constructor(
+    private readonly cfg: DaemonConfig,
+    fetchImpl?: typeof fetch,
+    private readonly log: (line: string) => void = (line) => console.log(line),
+  ) {
+    this.intent = new AppserviceIntent(cfg, fetchImpl);
+    this.agents = new AgentTokenStore(this.intent);
+    this.transactions = new TransactionHandler({
+      hsToken: cfg.hsToken,
+      onEvent: (event) => this.onEvent(event),
+      onError: (error, txnId) => this.log(`txn ${txnId} handler error: ${String(error)}`),
+    });
+  }
+
+  /** v1: the daemon only observes; room logic lives in the agent-comms daemons. */
+  private onEvent(event: MatrixEvent): void {
+    if (event.type === 'm.room.message') {
+      this.log(
+        `event ${event.event_id ?? '?'} in ${event.room_id ?? '?'} from ${event.sender ?? '?'}`,
+      );
+    }
+  }
+
+  /** Resolve the calling principal, or null when unauthorized. Fail-closed:
+   * host tokens win (timing-safe compare); otherwise a magt_* bearer is looked
+   * up in the agent token store; anything else is rejected. */
+  private async bridgeAuthorized(
+    authorizationHeader: string | undefined,
+  ): Promise<BridgePrincipal> {
+    if (!authorizationHeader?.startsWith('Bearer ')) return null;
+    const presented = authorizationHeader.slice('Bearer '.length);
+    if (this.cfg.bridgeTokens.some((token) => safeEqual(presented, token))) {
+      return { kind: 'host' };
+    }
+    const agentUserId = await this.agents.verifyToken(presented);
+    if (agentUserId) return { kind: 'agent', agentUserId };
+    return null;
+  }
+
+  async handle(req: DaemonRequest): Promise<DaemonResponse> {
+    if (req.method === 'GET' && req.path === '/health') {
+      return { status: 200, body: { ok: true } };
+    }
+
+    const txnMatch = req.method === 'PUT' ? TXN_PATH.exec(req.path) : null;
+    if (txnMatch?.[1] !== undefined) {
+      return this.transactions.handle(txnMatch[1], req.body, {
+        authorizationHeader: req.authorizationHeader,
+        accessTokenParam: req.searchParams.get('access_token') ?? undefined,
+      });
+    }
+
+    if (req.path.startsWith('/bridge/v1/')) {
+      const principal = await this.bridgeAuthorized(req.authorizationHeader);
+      if (!principal) {
+        return { status: 403, body: { errcode: 'M_FORBIDDEN', error: 'bad bridge token' } };
+      }
+      try {
+        if (req.method === 'POST' && req.path === '/bridge/v1/agents') {
+          if (principal.kind !== 'host') {
+            return {
+              status: 403,
+              body: { errcode: 'M_FORBIDDEN', error: 'agents cannot register agents' },
+            };
+          }
+          validateRegisterAgent(req.body);
+          const { agentUserId, token } = await this.agents.register({
+            alias: req.body.alias,
+            host: req.body.host,
+            displayName: req.body.display_name,
+          });
+          this.log(`registered agent ${agentUserId}`);
+          return { status: 200, body: { agent_user_id: agentUserId, bridge_token: token } };
+        }
+        if (req.method === 'POST' && req.path === '/bridge/v1/agents/revoke') {
+          if (principal.kind !== 'host') {
+            return {
+              status: 403,
+              body: { errcode: 'M_FORBIDDEN', error: 'agents cannot revoke agents' },
+            };
+          }
+          validateRevokeAgent(req.body);
+          const revoked = await this.agents.revoke(req.body.agent_user_id);
+          this.log(`revoked ${revoked} token(s) for ${req.body.agent_user_id}`);
+          return { status: 200, body: { revoked } };
+        }
+        if (req.method === 'GET' && req.path === '/bridge/v1/agents') {
+          if (principal.kind !== 'host') {
+            return {
+              status: 403,
+              body: { errcode: 'M_FORBIDDEN', error: 'agents cannot list agents' },
+            };
+          }
+          const agents = await this.agents.list();
+          return { status: 200, body: { agents } };
+        }
+        if (req.method === 'POST' && req.path === '/bridge/v1/messages') {
+          validateBridgeMessage(req.body);
+          if (
+            principal.kind === 'agent' &&
+            this.intent.agentUserId(req.body.agent) !== principal.agentUserId
+          ) {
+            return {
+              status: 403,
+              body: { errcode: 'M_FORBIDDEN', error: 'token not scoped to this agent' },
+            };
+          }
+          const eventId = await this.intent.sendAsAgent({
+            roomId: req.body.room_id,
+            agent: req.body.agent,
+            body: req.body.body,
+            threadRoot: req.body.thread_root,
+            msgtype: req.body.msgtype,
+            extraContent: req.body.extra_content,
+          });
+          return { status: 200, body: { event_id: eventId ?? null } };
+        }
+        if (req.method === 'POST' && req.path === '/bridge/v1/typing') {
+          validateBridgeTyping(req.body);
+          if (
+            principal.kind === 'agent' &&
+            this.intent.agentUserId(req.body.agent) !== principal.agentUserId
+          ) {
+            return {
+              status: 403,
+              body: { errcode: 'M_FORBIDDEN', error: 'token not scoped to this agent' },
+            };
+          }
+          await this.intent.setTyping(req.body.room_id, req.body.agent, req.body.typing);
+          return { status: 200, body: {} };
+        }
+        if (req.method === 'POST' && req.path === '/bridge/v1/provision/rooms') {
+          validateProvisionRoom(req.body);
+          const result = await this.intent.createRoom({
+            name: req.body.name,
+            alias: req.body.alias,
+            topic: req.body.topic,
+            invite: req.body.invite,
+            spaceId: req.body.space_id,
+          });
+          this.log(
+            `provisioned room ${result.roomId} (${req.body.name}) space_linked=${result.spaceLinked}`,
+          );
+          return {
+            status: 200,
+            body: {
+              room_id: result.roomId,
+              space_linked: result.spaceLinked,
+              ...(result.spaceError ? { space_error: result.spaceError } : {}),
+            },
+          };
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.log(`bridge error ${req.method} ${req.path}: ${message}`);
+        return { status: 400, body: { error: message } };
+      }
+      // Explicit: never fall out of the authenticated bridge block, so future
+      // sub-paths cannot accidentally route around the auth guard above.
+      return { status: 405, body: { error: 'unsupported bridge method/path' } };
+    }
+
+    return { status: 404, body: { error: 'not found' } };
+  }
+}

apps/appservice/tsconfig.json

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

apps/gateway/package.json

@@ -56,6 +56,7 @@
     "@opentelemetry/sdk-metrics": "^2.6.0",
     "@opentelemetry/sdk-node": "^0.213.0",
     "@opentelemetry/semantic-conventions": "^1.40.0",
+    "@peculiar/x509": "^2.0.0",
     "@sinclair/typebox": "^0.34.48",
     "better-auth": "^1.5.5",
     "bullmq": "^5.71.0",
@@ -64,6 +65,7 @@
     "dotenv": "^17.3.1",
     "fastify": "^5.0.0",
     "ioredis": "^5.10.0",
+    "jose": "^6.2.2",
     "node-cron": "^4.2.1",
     "openai": "^6.32.0",
     "postgres": "^3.4.8",
@@ -71,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": {

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

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

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

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

apps/gateway/src/admin/admin-health.controller.ts

@@ -20,7 +20,7 @@ export class AdminHealthController {
   async check(): Promise<HealthStatusDto> {
     const [database, cache] = await Promise.all([this.checkDatabase(), this.checkCache()]);
 
-    const sessions = this.agentService.listSessions();
+    const sessions = this.agentService.listAllSessionsForSystem();
     const providers = this.providerService.listProviders();
 
     const allOk = database.status === 'ok' && cache.status === 'ok';

apps/gateway/src/agent/__tests__/agent-service-ownership.test.ts

@@ -0,0 +1,142 @@
+import { ForbiddenException } from '@nestjs/common';
+import { describe, expect, it, vi } from 'vitest';
+import { AgentService, type AgentSession } from '../agent.service.js';
+import type { ActorTenantScope } from '../../auth/session-scope.js';
+
+const CONVERSATION_ID = '22222222-2222-4222-8222-222222222222';
+const OWNER_SCOPE: ActorTenantScope = { userId: 'owner-user', tenantId: 'owner-tenant' };
+const FOREIGN_SCOPE: ActorTenantScope = { userId: 'foreign-user', tenantId: 'foreign-tenant' };
+
+type AgentServiceInternals = {
+  sessions: Map<string, AgentSession>;
+  creating: Map<string, Promise<AgentSession>>;
+};
+
+function makeService(): AgentService {
+  return new AgentService(
+    {} as never,
+    {} as never,
+    {} as never,
+    { available: false } as never,
+    {} as never,
+    {} as never,
+    {} as never,
+    null,
+    null,
+    { collect: vi.fn().mockResolvedValue(undefined) } as never,
+  );
+}
+
+function internals(service: AgentService): AgentServiceInternals {
+  return service as unknown as AgentServiceInternals;
+}
+
+function makeSession(scope: ActorTenantScope = OWNER_SCOPE): AgentSession {
+  return {
+    id: CONVERSATION_ID,
+    provider: 'test-provider',
+    modelId: 'test-model',
+    piSession: {
+      thinkingLevel: 'off',
+      getAvailableThinkingLevels: vi.fn().mockReturnValue(['off', 'low', 'high']),
+      setThinkingLevel: vi.fn(),
+      abort: vi.fn().mockResolvedValue(undefined),
+      prompt: vi.fn().mockResolvedValue(undefined),
+      dispose: vi.fn(),
+      getSessionStats: vi.fn(),
+      getContextUsage: vi.fn(),
+    } as unknown as AgentSession['piSession'],
+    listeners: new Set(),
+    unsubscribe: vi.fn(),
+    createdAt: Date.now(),
+    promptCount: 0,
+    channels: new Set(),
+    skillPromptAdditions: [],
+    sandboxDir: '/tmp/tess-session-ownership-test',
+    allowedTools: null,
+    userId: scope.userId,
+    tenantId: scope.tenantId,
+    metrics: {
+      tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+      modelSwitches: 0,
+      messageCount: 0,
+      lastActivityAt: new Date('2026-07-12T00:00:00Z').toISOString(),
+    },
+  };
+}
+
+describe('AgentService owner/tenant scope enforcement', () => {
+  it('allows owner-scoped operations and rejects foreign scopes for seeded sessions', async () => {
+    const service = makeService();
+    const session = makeSession();
+    internals(service).sessions.set(CONVERSATION_ID, session);
+
+    expect(service.getSession(CONVERSATION_ID, OWNER_SCOPE)).toBe(session);
+    expect(service.getSession(CONVERSATION_ID, FOREIGN_SCOPE)).toBeUndefined();
+    expect(service.getSessionInfo(CONVERSATION_ID, FOREIGN_SCOPE)).toBeUndefined();
+    expect(service.listSessions(OWNER_SCOPE)).toHaveLength(1);
+    expect(service.listSessions(FOREIGN_SCOPE)).toEqual([]);
+
+    service.addChannel(CONVERSATION_ID, 'websocket:owner', OWNER_SCOPE);
+    expect(session.channels.has('websocket:owner')).toBe(true);
+    expect(() => service.addChannel(CONVERSATION_ID, 'websocket:foreign', FOREIGN_SCOPE)).toThrow(
+      ForbiddenException,
+    );
+    expect(() => service.removeChannel(CONVERSATION_ID, 'websocket:owner', FOREIGN_SCOPE)).toThrow(
+      ForbiddenException,
+    );
+
+    expect(() =>
+      service.updateSessionModel(CONVERSATION_ID, 'foreign-model', FOREIGN_SCOPE),
+    ).toThrow(ForbiddenException);
+    service.updateSessionModel(CONVERSATION_ID, 'owner-model', OWNER_SCOPE);
+    expect(session.modelId).toBe('owner-model');
+
+    expect(() =>
+      service.applyAgentConfig(CONVERSATION_ID, 'agent-foreign', 'Foreign Agent', FOREIGN_SCOPE),
+    ).toThrow(ForbiddenException);
+    service.applyAgentConfig(CONVERSATION_ID, 'agent-owner', 'Owner Agent', OWNER_SCOPE);
+    expect(session.agentConfigId).toBe('agent-owner');
+
+    expect(() => service.onEvent(CONVERSATION_ID, vi.fn(), FOREIGN_SCOPE)).toThrow(
+      ForbiddenException,
+    );
+    const cleanup = service.onEvent(CONVERSATION_ID, vi.fn(), OWNER_SCOPE);
+    cleanup();
+
+    await expect(
+      service.prompt(CONVERSATION_ID, 'foreign prompt', FOREIGN_SCOPE),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    await service.prompt(CONVERSATION_ID, 'owner prompt', OWNER_SCOPE);
+    expect(session.piSession.prompt).toHaveBeenCalledWith('owner prompt');
+
+    await expect(service.destroySession(CONVERSATION_ID, FOREIGN_SCOPE)).rejects.toBeInstanceOf(
+      ForbiddenException,
+    );
+    expect(internals(service).sessions.has(CONVERSATION_ID)).toBe(true);
+
+    await service.destroySession(CONVERSATION_ID, OWNER_SCOPE);
+    expect(session.piSession.dispose).toHaveBeenCalled();
+    expect(internals(service).sessions.has(CONVERSATION_ID)).toBe(false);
+  });
+
+  it('checks owner/tenant scope before returning an in-flight session creation', async () => {
+    const service = makeService();
+    const session = makeSession();
+    internals(service).creating.set(CONVERSATION_ID, Promise.resolve(session));
+
+    await expect(
+      service.createSession(CONVERSATION_ID, {
+        userId: FOREIGN_SCOPE.userId,
+        tenantId: FOREIGN_SCOPE.tenantId,
+      }),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+
+    await expect(
+      service.createSession(CONVERSATION_ID, {
+        userId: OWNER_SCOPE.userId,
+        tenantId: OWNER_SCOPE.tenantId,
+      }),
+    ).resolves.toBe(session);
+  });
+});

apps/gateway/src/agent/__tests__/session-ownership.test.ts

@@ -0,0 +1,262 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { ForbiddenException, NotFoundException } from '@nestjs/common';
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('../agent.service.js', () => ({ AgentService: class AgentService {} }));
+vi.mock('../../commands/command-executor.service.js', () => ({
+  CommandExecutorService: class CommandExecutorService {},
+}));
+vi.mock('../routing/routing-engine.service.js', () => ({
+  RoutingEngineService: class RoutingEngineService {},
+}));
+
+import { SessionsController } from '../sessions.controller.js';
+import { ChatController } from '../../chat/chat.controller.js';
+import { ChatGateway } from '../../chat/chat.gateway.js';
+import type { AgentSession } from '../agent.service.js';
+import type { SessionInfoDto } from '../session.dto.js';
+
+const USER_A = { id: 'user-a', tenantId: 'tenant-a' };
+const USER_B = { id: 'user-b', tenantId: 'tenant-b' };
+const CONVERSATION_ID = '11111111-1111-4111-8111-111111111111';
+
+function makeSessionInfo(overrides?: Partial<SessionInfoDto>): SessionInfoDto {
+  return {
+    id: CONVERSATION_ID,
+    provider: 'test-provider',
+    modelId: 'test-model',
+    createdAt: new Date('2026-07-12T00:00:00Z').toISOString(),
+    promptCount: 0,
+    channels: [],
+    durationMs: 0,
+    metrics: {
+      tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+      modelSwitches: 0,
+      messageCount: 0,
+      lastActivityAt: new Date('2026-07-12T00:00:00Z').toISOString(),
+    },
+    ...overrides,
+  };
+}
+
+function makeAgentSession(owner = USER_A): AgentSession {
+  return {
+    id: CONVERSATION_ID,
+    provider: 'test-provider',
+    modelId: 'test-model',
+    piSession: {
+      thinkingLevel: 'off',
+      getAvailableThinkingLevels: vi.fn().mockReturnValue(['off', 'low', 'high']),
+      setThinkingLevel: vi.fn(),
+      abort: vi.fn().mockResolvedValue(undefined),
+      prompt: vi.fn().mockResolvedValue(undefined),
+      dispose: vi.fn(),
+      getSessionStats: vi.fn(),
+      getContextUsage: vi.fn(),
+    } as unknown as AgentSession['piSession'],
+    listeners: new Set(),
+    unsubscribe: vi.fn(),
+    createdAt: Date.now(),
+    promptCount: 0,
+    channels: new Set(),
+    skillPromptAdditions: [],
+    sandboxDir: '/tmp',
+    allowedTools: null,
+    userId: owner.id,
+    tenantId: owner.tenantId,
+    metrics: {
+      tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+      modelSwitches: 0,
+      messageCount: 0,
+      lastActivityAt: new Date('2026-07-12T00:00:00Z').toISOString(),
+    },
+  };
+}
+
+function makeScopedAgentService() {
+  const foreign = makeAgentSession(USER_A);
+  return {
+    listSessions: vi.fn((scope?: { userId: string; tenantId?: string }) =>
+      scope?.userId === USER_B.id ? [] : [makeSessionInfo({ id: foreign.id })],
+    ),
+    getSessionInfo: vi.fn((_id: string, scope?: { userId: string; tenantId?: string }) =>
+      scope?.userId === USER_B.id ? undefined : makeSessionInfo({ id: foreign.id }),
+    ),
+    destroySession: vi.fn(),
+    getSession: vi.fn((_id: string, scope?: { userId: string; tenantId?: string }) =>
+      scope?.userId === USER_B.id ? undefined : foreign,
+    ),
+    createSession: vi.fn().mockRejectedValue(new ForbiddenException('Session scope mismatch')),
+    onEvent: vi.fn(() => vi.fn()),
+    addChannel: vi.fn(),
+    removeChannel: vi.fn(),
+    recordMessage: vi.fn(),
+    prompt: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+describe('TESS-M1-SEC-002 AgentService ownership boundary', () => {
+  it('requires explicit owner+tenant scope on protected session operations', () => {
+    const source = readFileSync(resolve('src/agent/agent.service.ts'), 'utf8');
+
+    expect(source).toContain('getSession(sessionId: string, scope: ActorTenantScope)');
+    expect(source).toContain('listSessions(scope: ActorTenantScope)');
+    expect(source).toContain('getSessionInfo(sessionId: string, scope: ActorTenantScope)');
+    expect(source).toContain(
+      'addChannel(sessionId: string, channel: string, scope: ActorTenantScope)',
+    );
+    expect(source).toContain(
+      'removeChannel(sessionId: string, channel: string, scope: ActorTenantScope)',
+    );
+    expect(source).toContain(
+      'async prompt(sessionId: string, message: string, scope: ActorTenantScope)',
+    );
+    expect(source).toContain('scope: ActorTenantScope,');
+    expect(source).toContain('async destroySession(sessionId: string, scope: ActorTenantScope)');
+    expect(source).not.toContain('scope?: ActorTenantScope');
+  });
+});
+
+describe('TESS-M1-SEC-002 REST session ownership and tenant binding', () => {
+  it('lists only sessions owned by the authenticated owner+tenant scope', () => {
+    const agentService = makeScopedAgentService();
+    const controller = new SessionsController(agentService as never);
+
+    expect(controller.list(USER_B)).toEqual({ sessions: [], total: 0 });
+    expect(agentService.listSessions).toHaveBeenCalledWith({
+      userId: USER_B.id,
+      tenantId: USER_B.tenantId,
+    });
+  });
+
+  it('does not reveal another owner/tenant session by guessed id', () => {
+    const agentService = makeScopedAgentService();
+    const controller = new SessionsController(agentService as never);
+
+    expect(() => controller.findOne(CONVERSATION_ID, USER_B)).toThrow(NotFoundException);
+    expect(agentService.getSessionInfo).toHaveBeenCalledWith(CONVERSATION_ID, {
+      userId: USER_B.id,
+      tenantId: USER_B.tenantId,
+    });
+  });
+
+  it('does not terminate another owner/tenant session by guessed id', async () => {
+    const agentService = makeScopedAgentService();
+    const controller = new SessionsController(agentService as never);
+
+    await expect(controller.destroy(CONVERSATION_ID, USER_B)).rejects.toBeInstanceOf(
+      NotFoundException,
+    );
+    expect(agentService.destroySession).not.toHaveBeenCalled();
+  });
+});
+
+describe('TESS-M1-SEC-002 REST chat send ownership and tenant binding', () => {
+  it('does not send a prompt into another owner/tenant session by guessed conversationId', async () => {
+    const agentService = makeScopedAgentService();
+    const controller = new ChatController(agentService as never);
+
+    await expect(
+      controller.chat({ conversationId: CONVERSATION_ID, content: 'take over' }, USER_B),
+    ).rejects.toMatchObject({ status: 404 });
+
+    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
+      userId: USER_B.id,
+      tenantId: USER_B.tenantId,
+    });
+    expect(agentService.prompt).not.toHaveBeenCalled();
+  });
+});
+
+describe('TESS-M1-SEC-002 WebSocket session ownership and tenant binding', () => {
+  function makeGateway(agentService = makeScopedAgentService()) {
+    const brain = {
+      conversations: {
+        findById: vi.fn().mockResolvedValue(undefined),
+        create: vi.fn().mockResolvedValue(undefined),
+        update: vi.fn().mockResolvedValue(undefined),
+        findMessages: vi.fn().mockResolvedValue([]),
+        addMessage: vi.fn().mockResolvedValue(undefined),
+      },
+    };
+    const commandRegistry = { getManifest: vi.fn().mockReturnValue([]) };
+    const commandExecutor = { execute: vi.fn() };
+    const routingEngine = {
+      resolve: vi.fn().mockResolvedValue({ provider: 'test', model: 'test-model' }),
+    };
+    const gateway = new ChatGateway(
+      agentService as never,
+      {} as never,
+      brain as never,
+      commandRegistry as never,
+      commandExecutor as never,
+      routingEngine as never,
+    );
+    return { gateway, agentService };
+  }
+
+  function makeSocket() {
+    return {
+      id: 'socket-b',
+      connected: true,
+      data: { user: USER_B, session: { id: 'auth-session-b', userId: USER_B.id } },
+      emit: vi.fn(),
+      disconnect: vi.fn(),
+    };
+  }
+
+  it('does not attach or send to another owner/tenant session by guessed conversationId', async () => {
+    const { gateway, agentService } = makeGateway();
+    const socket = makeSocket();
+
+    await gateway.handleMessage(socket as never, {
+      conversationId: CONVERSATION_ID,
+      content: 'attach to foreign session',
+    });
+
+    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
+      userId: USER_B.id,
+      tenantId: USER_B.tenantId,
+    });
+    expect(agentService.onEvent).not.toHaveBeenCalled();
+    expect(agentService.addChannel).not.toHaveBeenCalled();
+    expect(agentService.prompt).not.toHaveBeenCalled();
+    expect(socket.emit).toHaveBeenCalledWith(
+      'error',
+      expect.objectContaining({ conversationId: CONVERSATION_ID }),
+    );
+  });
+
+  it('does not mutate thinking level on another owner/tenant session', () => {
+    const { gateway, agentService } = makeGateway();
+    const socket = makeSocket();
+
+    gateway.handleSetThinking(socket as never, { conversationId: CONVERSATION_ID, level: 'high' });
+
+    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
+      userId: USER_B.id,
+      tenantId: USER_B.tenantId,
+    });
+    expect(socket.emit).toHaveBeenCalledWith(
+      'error',
+      expect.objectContaining({ conversationId: CONVERSATION_ID }),
+    );
+  });
+
+  it('does not terminate another owner/tenant session over WebSocket abort', async () => {
+    const { gateway, agentService } = makeGateway();
+    const socket = makeSocket();
+
+    await gateway.handleAbort(socket as never, { conversationId: CONVERSATION_ID });
+
+    expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
+      userId: USER_B.id,
+      tenantId: USER_B.tenantId,
+    });
+    expect(socket.emit).toHaveBeenCalledWith(
+      'error',
+      expect.objectContaining({ conversationId: CONVERSATION_ID }),
+    );
+  });
+});

apps/gateway/src/agent/agent.service.ts

@@ -1,4 +1,11 @@
-import { Inject, Injectable, Logger, Optional, type OnModuleDestroy } from '@nestjs/common';
+import {
+  ForbiddenException,
+  Inject,
+  Injectable,
+  Logger,
+  Optional,
+  type OnModuleDestroy,
+} from '@nestjs/common';
 import {
   createAgentSession,
   DefaultResourceLoader,
@@ -28,6 +35,7 @@ import type { SessionInfoDto, SessionMetrics } from './session.dto.js';
 import { SystemOverrideService } from '../preferences/system-override.service.js';
 import { PreferencesService } from '../preferences/preferences.service.js';
 import { SessionGCService } from '../gc/session-gc.service.js';
+import type { ActorTenantScope } from '../auth/session-scope.js';
 
 /** A single message from DB conversation history, used for context injection. */
 export interface ConversationHistoryMessage {
@@ -68,6 +76,8 @@ export interface AgentSessionOptions {
   agentConfigId?: string;
   /** ID of the user who owns this session. Used for preferences and system override lookups. */
   userId?: string;
+  /** Server-derived tenant scope that owns this session. Falls back to userId for solo users. */
+  tenantId?: string;
   /**
    * Prior conversation messages to inject as context when resuming a session.
    * These messages are formatted and prepended to the system prompt so the
@@ -94,6 +104,8 @@ export interface AgentSession {
   allowedTools: string[] | null;
   /** User ID that owns this session, used for preference lookups. */
   userId?: string;
+  /** Server-derived tenant scope that owns this session. Falls back to userId for solo users. */
+  tenantId?: string;
   /** Agent config ID applied to this session, if any (M5-001). */
   agentConfigId?: string;
   /** Human-readable agent name applied to this session, if any (M5-001). */
@@ -174,12 +186,20 @@ export class AgentService implements OnModuleDestroy {
       .filter((t) => t.length > 0);
   }
 
-  async createSession(sessionId: string, options?: AgentSessionOptions): Promise<AgentSession> {
+  async createSession(sessionId: string, options: AgentSessionOptions): Promise<AgentSession> {
+    const scope = this.scopeFromOptions(options);
     const existing = this.sessions.get(sessionId);
-    if (existing) return existing;
+    if (existing) {
+      this.assertSessionScope(existing, scope);
+      return existing;
+    }
 
     const inflight = this.creating.get(sessionId);
-    if (inflight) return inflight;
+    if (inflight) {
+      const session = await inflight;
+      this.assertSessionScope(session, scope);
+      return session;
+    }
 
     const promise = this.doCreateSession(sessionId, options).finally(() => {
       this.creating.delete(sessionId);
@@ -342,6 +362,7 @@ export class AgentService implements OnModuleDestroy {
       sandboxDir,
       allowedTools,
       userId: mergedOptions?.userId,
+      tenantId: this.tenantIdFor(mergedOptions?.userId, mergedOptions?.tenantId),
       agentConfigId: mergedOptions?.agentConfigId,
       agentName: resolvedAgentName,
       metrics: {
@@ -473,38 +494,70 @@ export class AgentService implements OnModuleDestroy {
     return this.providerService.getDefaultModel() ?? null;
   }
 
-  getSession(sessionId: string): AgentSession | undefined {
-    return this.sessions.get(sessionId);
+  getSession(sessionId: string, scope: ActorTenantScope): AgentSession | undefined {
+    const session = this.sessions.get(sessionId);
+    if (!session || !this.sessionMatchesScope(session, scope)) return undefined;
+    return session;
   }
 
-  listSessions(): SessionInfoDto[] {
+  listSessions(scope: ActorTenantScope): SessionInfoDto[] {
     const now = Date.now();
-    return Array.from(this.sessions.values()).map((s) => ({
-      id: s.id,
-      provider: s.provider,
-      modelId: s.modelId,
-      ...(s.agentName ? { agentName: s.agentName } : {}),
-      createdAt: new Date(s.createdAt).toISOString(),
-      promptCount: s.promptCount,
-      channels: Array.from(s.channels),
-      durationMs: now - s.createdAt,
-      metrics: { ...s.metrics },
-    }));
+    return Array.from(this.sessions.values())
+      .filter((s) => this.sessionMatchesScope(s, scope))
+      .map((s) => this.toSessionInfo(s, now));
   }
 
-  getSessionInfo(sessionId: string): SessionInfoDto | undefined {
+  listAllSessionsForSystem(): SessionInfoDto[] {
+    const now = Date.now();
+    return Array.from(this.sessions.values()).map((s) => this.toSessionInfo(s, now));
+  }
+
+  getSessionInfo(sessionId: string, scope: ActorTenantScope): SessionInfoDto | undefined {
     const s = this.sessions.get(sessionId);
-    if (!s) return undefined;
+    if (!s || !this.sessionMatchesScope(s, scope)) return undefined;
+    return this.toSessionInfo(s);
+  }
+
+  private scopeFromOptions(options: AgentSessionOptions): ActorTenantScope {
+    if (!options.userId) {
+      throw new ForbiddenException('Session owner scope is required');
+    }
     return {
-      id: s.id,
-      provider: s.provider,
-      modelId: s.modelId,
-      ...(s.agentName ? { agentName: s.agentName } : {}),
-      createdAt: new Date(s.createdAt).toISOString(),
-      promptCount: s.promptCount,
-      channels: Array.from(s.channels),
-      durationMs: Date.now() - s.createdAt,
-      metrics: { ...s.metrics },
+      userId: options.userId,
+      tenantId: this.tenantIdFor(options.userId, options.tenantId) ?? options.userId,
+    };
+  }
+
+  private tenantIdFor(
+    userId: string | undefined,
+    tenantId: string | undefined,
+  ): string | undefined {
+    return tenantId ?? userId;
+  }
+
+  private sessionMatchesScope(session: AgentSession, scope: ActorTenantScope): boolean {
+    return (
+      session.userId === scope.userId && (session.tenantId ?? session.userId) === scope.tenantId
+    );
+  }
+
+  private assertSessionScope(session: AgentSession, scope: ActorTenantScope): void {
+    if (!this.sessionMatchesScope(session, scope)) {
+      throw new ForbiddenException('Session does not belong to the current owner/tenant scope');
+    }
+  }
+
+  private toSessionInfo(session: AgentSession, now = Date.now()): SessionInfoDto {
+    return {
+      id: session.id,
+      provider: session.provider,
+      modelId: session.modelId,
+      ...(session.agentName ? { agentName: session.agentName } : {}),
+      createdAt: new Date(session.createdAt).toISOString(),
+      promptCount: session.promptCount,
+      channels: Array.from(session.channels),
+      durationMs: now - session.createdAt,
+      metrics: { ...session.metrics },
     };
   }
 
@@ -553,9 +606,10 @@ export class AgentService implements OnModuleDestroy {
    * not reconstructed — the model is used on the next createSession call for
    * the same conversationId when the session is torn down or a new one is created.
    */
-  updateSessionModel(sessionId: string, modelId: string): void {
+  updateSessionModel(sessionId: string, modelId: string, scope: ActorTenantScope): void {
     const session = this.sessions.get(sessionId);
     if (!session) return;
+    this.assertSessionScope(session, scope);
     const prev = session.modelId;
     session.modelId = modelId;
     this.recordModelSwitch(sessionId);
@@ -572,48 +626,51 @@ export class AgentService implements OnModuleDestroy {
     sessionId: string,
     agentConfigId: string,
     agentName: string,
+    scope: ActorTenantScope,
     modelId?: string,
   ): void {
     const session = this.sessions.get(sessionId);
     if (!session) return;
+    this.assertSessionScope(session, scope);
     session.agentConfigId = agentConfigId;
     session.agentName = agentName;
     if (modelId) {
-      this.updateSessionModel(sessionId, modelId);
+      this.updateSessionModel(sessionId, modelId, scope);
     }
     this.logger.log(
       `Session ${sessionId}: agent switched to "${agentName}" (${agentConfigId}) (M5-003)`,
     );
   }
 
-  addChannel(sessionId: string, channel: string): void {
+  addChannel(sessionId: string, channel: string, scope: ActorTenantScope): void {
     const session = this.sessions.get(sessionId);
-    if (session) {
-      session.channels.add(channel);
-    }
+    if (!session) return;
+    this.assertSessionScope(session, scope);
+    session.channels.add(channel);
   }
 
-  removeChannel(sessionId: string, channel: string): void {
+  removeChannel(sessionId: string, channel: string, scope: ActorTenantScope): void {
     const session = this.sessions.get(sessionId);
-    if (session) {
-      session.channels.delete(channel);
-    }
+    if (!session) return;
+    this.assertSessionScope(session, scope);
+    session.channels.delete(channel);
   }
 
-  async prompt(sessionId: string, message: string): Promise<void> {
+  async prompt(sessionId: string, message: string, scope: ActorTenantScope): Promise<void> {
     const session = this.sessions.get(sessionId);
     if (!session) {
       throw new Error(`No agent session found: ${sessionId}`);
     }
+    this.assertSessionScope(session, scope);
     session.promptCount += 1;
 
     // Prepend session-scoped system override if present (renew TTL on each turn)
     let effectiveMessage = message;
     if (this.systemOverride) {
-      const override = await this.systemOverride.get(sessionId);
+      const override = await this.systemOverride.get(sessionId, scope);
       if (override) {
         effectiveMessage = `[System Override]\n${override}\n\n${message}`;
-        await this.systemOverride.renew(sessionId);
+        await this.systemOverride.renew(sessionId, scope);
         this.logger.debug(`Applied system override for session ${sessionId}`);
       }
     }
@@ -629,16 +686,28 @@ export class AgentService implements OnModuleDestroy {
     }
   }
 
-  onEvent(sessionId: string, listener: (event: AgentSessionEvent) => void): () => void {
+  onEvent(
+    sessionId: string,
+    listener: (event: AgentSessionEvent) => void,
+    scope: ActorTenantScope,
+  ): () => void {
     const session = this.sessions.get(sessionId);
     if (!session) {
       throw new Error(`No agent session found: ${sessionId}`);
     }
+    this.assertSessionScope(session, scope);
     session.listeners.add(listener);
     return () => session.listeners.delete(listener);
   }
 
-  async destroySession(sessionId: string): Promise<void> {
+  async destroySession(sessionId: string, scope: ActorTenantScope): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+    this.assertSessionScope(session, scope);
+    await this.destroySessionForSystem(sessionId);
+  }
+
+  private async destroySessionForSystem(sessionId: string): Promise<void> {
     const session = this.sessions.get(sessionId);
     if (!session) return;
     this.logger.log(`Destroying agent session ${sessionId}`);
@@ -667,7 +736,7 @@ export class AgentService implements OnModuleDestroy {
 
   async onModuleDestroy(): Promise<void> {
     this.logger.log('Shutting down all agent sessions');
-    const stops = Array.from(this.sessions.keys()).map((id) => this.destroySession(id));
+    const stops = Array.from(this.sessions.keys()).map((id) => this.destroySessionForSystem(id));
     const results = await Promise.allSettled(stops);
     for (const result of results) {
       if (result.status === 'rejected') {

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

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

apps/gateway/src/agent/sessions.controller.ts

@@ -10,6 +10,8 @@ import {
   UseGuards,
 } from '@nestjs/common';
 import { AuthGuard } from '../auth/auth.guard.js';
+import { CurrentUser } from '../auth/current-user.decorator.js';
+import { scopeFromUser, type AuthenticatedUserLike } from '../auth/session-scope.js';
 import { AgentService } from './agent.service.js';
 
 @Controller('api/sessions')
@@ -18,23 +20,24 @@ export class SessionsController {
   constructor(@Inject(AgentService) private readonly agentService: AgentService) {}
 
   @Get()
-  list() {
-    const sessions = this.agentService.listSessions();
+  list(@CurrentUser() user: AuthenticatedUserLike) {
+    const sessions = this.agentService.listSessions(scopeFromUser(user));
     return { sessions, total: sessions.length };
   }
 
   @Get(':id')
-  findOne(@Param('id') id: string) {
-    const info = this.agentService.getSessionInfo(id);
+  findOne(@Param('id') id: string, @CurrentUser() user: AuthenticatedUserLike) {
+    const info = this.agentService.getSessionInfo(id, scopeFromUser(user));
     if (!info) throw new NotFoundException('Session not found');
     return info;
   }
 
   @Delete(':id')
   @HttpCode(HttpStatus.NO_CONTENT)
-  async destroy(@Param('id') id: string) {
-    const info = this.agentService.getSessionInfo(id);
+  async destroy(@Param('id') id: string, @CurrentUser() user: AuthenticatedUserLike) {
+    const scope = scopeFromUser(user);
+    const info = this.agentService.getSessionInfo(id, scope);
     if (!info) throw new NotFoundException('Session not found');
-    await this.agentService.destroySession(id);
+    await this.agentService.destroySession(id, scope);
   }
 }

apps/gateway/src/app.module.ts

@@ -24,6 +24,7 @@ import { GCModule } from './gc/gc.module.js';
 import { ReloadModule } from './reload/reload.module.js';
 import { WorkspaceModule } from './workspace/workspace.module.js';
 import { QueueModule } from './queue/queue.module.js';
+import { FederationModule } from './federation/federation.module.js';
 import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler';
 
 @Module({
@@ -52,6 +53,7 @@ import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler';
     QueueModule,
     ReloadModule,
     WorkspaceModule,
+    FederationModule,
   ],
   controllers: [HealthController],
   providers: [

apps/gateway/src/auth/session-scope.ts

@@ -0,0 +1,24 @@
+export interface AuthenticatedUserLike {
+  id: string;
+  tenantId?: string | null;
+  teamId?: string | null;
+  organizationId?: string | null;
+  orgId?: string | null;
+}
+
+export interface ActorTenantScope {
+  userId: string;
+  tenantId: string;
+}
+
+/**
+ * Build the immutable server-derived scope used for Tess session operations.
+ * Current Mosaic auth is user-scoped; future org/team claims can populate one
+ * of the tenant fields without allowing clients to choose another tenant.
+ */
+export function scopeFromUser(user: AuthenticatedUserLike): ActorTenantScope {
+  return {
+    userId: user.id,
+    tenantId: user.tenantId ?? user.teamId ?? user.organizationId ?? user.orgId ?? user.id,
+  };
+}

apps/gateway/src/chat/__tests__/chat-security.test.ts

@@ -12,7 +12,8 @@ describe('Chat controller source hardening', () => {
     const source = readFileSync(resolve('src/chat/chat.controller.ts'), 'utf8');
 
     expect(source).toContain('@UseGuards(AuthGuard)');
-    expect(source).toContain('@CurrentUser() user: { id: string }');
+    expect(source).toContain('@CurrentUser() user: AuthenticatedUserLike');
+    expect(source).toContain('const scope = scopeFromUser(user);');
   });
 });
 

apps/gateway/src/chat/chat.controller.ts

@@ -3,8 +3,10 @@ import {
   Post,
   Body,
   Logger,
+  ForbiddenException,
   HttpException,
   HttpStatus,
+  NotFoundException,
   Inject,
   UseGuards,
 } from '@nestjs/common';
@@ -13,6 +15,7 @@ import { Throttle } from '@nestjs/throttler';
 import { AgentService } from '../agent/agent.service.js';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';
+import { scopeFromUser, type AuthenticatedUserLike } from '../auth/session-scope.js';
 import { v4 as uuid } from 'uuid';
 import { ChatRequestDto } from './chat.dto.js';
 
@@ -32,16 +35,23 @@ export class ChatController {
   @Throttle({ default: { limit: 10, ttl: 60_000 } })
   async chat(
     @Body() body: ChatRequestDto,
-    @CurrentUser() user: { id: string },
+    @CurrentUser() user: AuthenticatedUserLike,
   ): Promise<ChatResponse> {
     const conversationId = body.conversationId ?? uuid();
+    const scope = scopeFromUser(user);
 
     try {
-      let agentSession = this.agentService.getSession(conversationId);
+      let agentSession = this.agentService.getSession(conversationId, scope);
       if (!agentSession) {
-        agentSession = await this.agentService.createSession(conversationId);
+        agentSession = await this.agentService.createSession(conversationId, {
+          userId: scope.userId,
+          tenantId: scope.tenantId,
+        });
       }
     } catch (err) {
+      if (err instanceof ForbiddenException) {
+        throw new NotFoundException('Session not found');
+      }
       this.logger.error(
         `Session creation failed for conversation=${conversationId}`,
         err instanceof Error ? err.stack : String(err),
@@ -60,20 +70,27 @@ export class ChatController {
         reject(new Error('Agent response timed out'));
       }, 120_000);
 
-      const cleanup = this.agentService.onEvent(conversationId, (event: AgentSessionEvent) => {
-        if (event.type === 'message_update' && event.assistantMessageEvent.type === 'text_delta') {
-          responseText += event.assistantMessageEvent.delta;
-        }
-        if (event.type === 'agent_end') {
-          clearTimeout(timer);
-          cleanup();
-          resolve();
-        }
-      });
+      const cleanup = this.agentService.onEvent(
+        conversationId,
+        (event: AgentSessionEvent) => {
+          if (
+            event.type === 'message_update' &&
+            event.assistantMessageEvent.type === 'text_delta'
+          ) {
+            responseText += event.assistantMessageEvent.delta;
+          }
+          if (event.type === 'agent_end') {
+            clearTimeout(timer);
+            cleanup();
+            resolve();
+          }
+        },
+        scope,
+      );
     });
 
     try {
-      await this.agentService.prompt(conversationId, body.content);
+      await this.agentService.prompt(conversationId, body.content, scope);
       await done;
     } catch (err) {
       if (err instanceof HttpException) throw err;

apps/gateway/src/chat/chat.gateway-auth.ts

@@ -1,3 +1,4 @@
+import { timingSafeEqual } from 'node:crypto';
 import type { IncomingHttpHeaders } from 'node:http';
 import { fromNodeHeaders } from 'better-auth/node';
 
@@ -12,6 +13,19 @@ export interface SessionAuth {
   };
 }
 
+export function validateDiscordServiceToken(
+  candidate: unknown,
+  expected: string | undefined,
+): boolean {
+  if (typeof candidate !== 'string' || !expected) return false;
+  const candidateBuffer = Buffer.from(candidate);
+  const expectedBuffer = Buffer.from(expected);
+  return (
+    candidateBuffer.length === expectedBuffer.length &&
+    timingSafeEqual(candidateBuffer, expectedBuffer)
+  );
+}
+
 export async function validateSocketSession(
   headers: IncomingHttpHeaders,
   auth: SessionAuth,

apps/gateway/src/chat/chat.gateway-command-approval.spec.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { SlashCommandPayload } from '@mosaicstack/types';
+import { ChatGateway } from './chat.gateway.js';
+
+const payload: SlashCommandPayload = {
+  command: 'gc',
+  conversationId: 'conversation-1',
+  approvalId: 'approval-1',
+};
+
+function buildGateway(commandExecutor: {
+  execute: ReturnType<typeof vi.fn>;
+  createApproval: ReturnType<typeof vi.fn>;
+}): ChatGateway {
+  return new ChatGateway(
+    {} as never,
+    {} as never,
+    {} as never,
+    {} as never,
+    commandExecutor as never,
+    {} as never,
+  );
+}
+
+describe('ChatGateway command approval ingress', () => {
+  it('passes the client approval ID through to command execution while deriving the actor server-side', async (): Promise<void> => {
+    const commandExecutor = {
+      execute: vi.fn().mockResolvedValue({ ...payload, success: true }),
+      createApproval: vi.fn(),
+    };
+    const gateway = buildGateway(commandExecutor);
+    const client = { data: { user: { id: 'admin-1' } }, emit: vi.fn() };
+
+    await gateway.handleCommandExecute(client as never, payload);
+
+    expect(commandExecutor.execute).toHaveBeenCalledWith(payload, {
+      userId: 'admin-1',
+      tenantId: 'admin-1',
+    });
+    expect(client.emit).toHaveBeenCalledWith(
+      'command:result',
+      expect.objectContaining({ success: true }),
+    );
+  });
+
+  it('issues a durable approval only for the authenticated actor', async (): Promise<void> => {
+    const commandExecutor = {
+      execute: vi.fn(),
+      createApproval: vi.fn().mockResolvedValue({
+        approvalId: 'approval-1',
+        expiresAt: '2026-07-12T00:05:00.000Z',
+      }),
+    };
+    const gateway = buildGateway(commandExecutor);
+    const client = { data: { user: { id: 'admin-1' } }, emit: vi.fn() };
+
+    await gateway.handleCommandApproval(client as never, {
+      command: 'gc',
+      conversationId: 'conversation-1',
+    });
+
+    expect(commandExecutor.createApproval).toHaveBeenCalledWith(
+      { command: 'gc', conversationId: 'conversation-1' },
+      { userId: 'admin-1', tenantId: 'admin-1' },
+    );
+    expect(client.emit).toHaveBeenCalledWith('command:approval', {
+      command: 'gc',
+      conversationId: 'conversation-1',
+      success: true,
+      approvalId: 'approval-1',
+      expiresAt: '2026-07-12T00:05:00.000Z',
+    });
+  });
+});

apps/gateway/src/chat/chat.gateway.ts

@@ -11,10 +11,16 @@ import {
 } from '@nestjs/websockets';
 import { Server, Socket } from 'socket.io';
 import type { AgentSessionEvent } from '@mariozechner/pi-coding-agent';
+import {
+  verifyDiscordIngressEnvelope,
+  type DiscordIngressEnvelope,
+  type DiscordIngressPayload,
+} from '@mosaicstack/discord-plugin';
 import type { Auth } from '@mosaicstack/auth';
 import type { Brain } from '@mosaicstack/brain';
 import type {
   SetThinkingPayload,
+  SlashCommandApprovalResultPayload,
   SlashCommandPayload,
   SystemReloadPayload,
   RoutingDecisionInfo,
@@ -22,13 +28,19 @@ import type {
 } from '@mosaicstack/types';
 import { AgentService, type ConversationHistoryMessage } from '../agent/agent.service.js';
 import { AUTH } from '../auth/auth.tokens.js';
+import {
+  scopeFromUser,
+  type ActorTenantScope,
+  type AuthenticatedUserLike,
+} from '../auth/session-scope.js';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { CommandRegistryService } from '../commands/command-registry.service.js';
 import { CommandExecutorService } from '../commands/command-executor.service.js';
 import { RoutingEngineService } from '../agent/routing/routing-engine.service.js';
 import { v4 as uuid } from 'uuid';
 import { ChatSocketMessageDto } from './chat.dto.js';
-import { validateSocketSession } from './chat.gateway-auth.js';
+import { validateDiscordServiceToken, validateSocketSession } from './chat.gateway-auth.js';
+import { DiscordReplayProtector } from '../plugin/discord-replay-protector.js';
 
 /** Per-client state tracking streaming accumulation for persistence. */
 interface ClientSession {
@@ -40,6 +52,8 @@ interface ClientSession {
   toolCalls: Array<{ toolCallId: string; toolName: string; args: unknown; isError: boolean }>;
   /** Tool calls in-flight (started but not ended yet). */
   pendingToolCalls: Map<string, { toolName: string; args: unknown }>;
+  /** Server-derived owner/tenant scope for this socket's conversation attachment. */
+  scope: ActorTenantScope;
   /** Last routing decision made for this session (M4-008) */
   lastRoutingDecision?: RoutingDecisionInfo;
 }
@@ -50,6 +64,37 @@ interface ClientSession {
  */
 const modelOverrides = new Map<string, string>();
 
+function isDiscordIngressEnvelope(value: unknown): value is DiscordIngressEnvelope {
+  if (typeof value !== 'object' || value === null) return false;
+  const envelope = value as { payload?: unknown; signature?: unknown };
+  if (
+    typeof envelope.signature !== 'string' ||
+    typeof envelope.payload !== 'object' ||
+    envelope.payload === null
+  ) {
+    return false;
+  }
+  const payload = envelope.payload as Record<string, unknown>;
+  return [
+    payload['correlationId'],
+    payload['messageId'],
+    payload['guildId'],
+    payload['channelId'],
+    payload['userId'],
+    payload['conversationId'],
+    payload['content'],
+  ].every((field: unknown): boolean => typeof field === 'string');
+}
+
+function isChatSocketMessage(value: unknown): value is ChatSocketMessageDto {
+  if (typeof value !== 'object' || value === null) return false;
+  const payload = value as { content?: unknown; conversationId?: unknown };
+  return (
+    typeof payload.content === 'string' &&
+    (payload.conversationId === undefined || typeof payload.conversationId === 'string')
+  );
+}
+
 @WebSocketGateway({
   cors: {
     origin: process.env['GATEWAY_CORS_ORIGIN'] ?? 'http://localhost:3000',
@@ -62,6 +107,7 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
 
   private readonly logger = new Logger(ChatGateway.name);
   private readonly clientSessions = new Map<string, ClientSession>();
+  private readonly discordReplayProtector = new DiscordReplayProtector();
 
   constructor(
     @Inject(AgentService) private readonly agentService: AgentService,
@@ -77,6 +123,13 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
   }
 
   async handleConnection(client: Socket): Promise<void> {
+    const serviceToken = client.handshake.auth['discordServiceToken'];
+    if (validateDiscordServiceToken(serviceToken, process.env['DISCORD_SERVICE_TOKEN'])) {
+      client.data.discordService = true;
+      this.logger.log(`Authenticated Discord service connected: ${client.id}`);
+      return;
+    }
+
     const session = await validateSocketSession(client.handshake.headers, this.auth);
     if (!session) {
       this.logger.warn(`Rejected unauthenticated WebSocket client: ${client.id}`);
@@ -87,8 +140,6 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     client.data.user = session.user;
     client.data.session = session.session;
     this.logger.log(`Client connected: ${client.id}`);
-
-    // Broadcast command manifest to the newly connected client
     client.emit('commands:manifest', { manifest: this.commandRegistry.getManifest() });
   }
 
@@ -97,25 +148,80 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     const session = this.clientSessions.get(client.id);
     if (session) {
       session.cleanup();
-      this.agentService.removeChannel(session.conversationId, `websocket:${client.id}`);
+      this.agentService.removeChannel(
+        session.conversationId,
+        `websocket:${client.id}`,
+        session.scope,
+      );
       this.clientSessions.delete(client.id);
     }
   }
 
+  private getClientScope(client: Socket): ActorTenantScope | null {
+    const user = client.data.user as AuthenticatedUserLike | undefined;
+    if (!user?.id) return null;
+    return scopeFromUser(user);
+  }
+
+  private modelOverrideKey(conversationId: string, scope: ActorTenantScope): string {
+    return `${scope.tenantId}:${scope.userId}:${conversationId}`;
+  }
+
+  private scopesEqual(a: ActorTenantScope, b: ActorTenantScope): boolean {
+    return a.userId === b.userId && a.tenantId === b.tenantId;
+  }
+
   @SubscribeMessage('message')
   async handleMessage(
     @ConnectedSocket() client: Socket,
-    @MessageBody() data: ChatSocketMessageDto,
+    @MessageBody() rawData: unknown,
   ): Promise<void> {
+    let discordIngress: DiscordIngressPayload | null = null;
+    let data: ChatSocketMessageDto;
+    if (client.data.discordService) {
+      if (!isDiscordIngressEnvelope(rawData)) {
+        this.logger.warn(`Rejected malformed Discord ingress from ${client.id}`);
+        return;
+      }
+      discordIngress = this.resolveDiscordIngress(client, rawData);
+      if (!discordIngress) return;
+      data = { conversationId: discordIngress.conversationId, content: discordIngress.content };
+    } else {
+      if (!isChatSocketMessage(rawData)) {
+        this.logger.warn(`Rejected malformed chat message from ${client.id}`);
+        return;
+      }
+      data = rawData;
+    }
     const conversationId = data.conversationId ?? uuid();
-    const userId = (client.data.user as { id: string } | undefined)?.id;
+    const discordServiceUserId = process.env['DISCORD_SERVICE_USER_ID'];
+    if (discordIngress && !discordServiceUserId) {
+      this.logger.warn(
+        `Rejected Discord ingress without configured service owner from ${client.id}`,
+      );
+      return;
+    }
+    const scope = discordIngress
+      ? {
+          userId: discordServiceUserId!,
+          tenantId: process.env['DISCORD_SERVICE_TENANT_ID'] ?? discordServiceUserId!,
+        }
+      : this.getClientScope(client);
+    if (!scope) {
+      client.emit('error', { conversationId, error: 'Authenticated user scope is required.' });
+      return;
+    }
+    const userId = scope.userId;
+    const correlationId = discordIngress?.correlationId;
 
-    this.logger.log(`Message from ${client.id} in conversation ${conversationId}`);
+    this.logger.log(
+      `Message from ${client.id} in conversation ${conversationId}${correlationId ? ` correlation=${correlationId}` : ''}`,
+    );
 
     // Ensure agent session exists for this conversation
     let sessionRoutingDecision: RoutingDecisionInfo | undefined;
     try {
-      let agentSession = this.agentService.getSession(conversationId);
+      let agentSession = this.agentService.getSession(conversationId, scope);
       if (!agentSession) {
         // When resuming an existing conversation, load prior messages to inject as context (M1-004)
         const conversationHistory = await this.loadConversationHistory(conversationId, userId);
@@ -135,7 +241,7 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
         let resolvedProvider = data.provider;
         let resolvedModelId = data.modelId;
 
-        const modelOverride = modelOverrides.get(conversationId);
+        const modelOverride = modelOverrides.get(this.modelOverrideKey(conversationId, scope));
         if (modelOverride) {
           // /model override bypasses routing engine (M4-007)
           resolvedModelId = modelOverride;
@@ -172,6 +278,7 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
           modelId: resolvedModelId,
           agentConfigId: data.agentId,
           userId,
+          tenantId: scope.tenantId,
           conversationHistory: conversationHistory.length > 0 ? conversationHistory : undefined,
         });
 
@@ -213,6 +320,13 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
             content: data.content,
             metadata: {
               timestamp: new Date().toISOString(),
+              ...(correlationId
+                ? {
+                    correlationId,
+                    discordMessageId: discordIngress?.messageId,
+                    discordUserId: discordIngress?.userId,
+                  }
+                : {}),
             },
           },
           userId,
@@ -232,9 +346,13 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     }
 
     // Subscribe to agent events and relay to client
-    const cleanup = this.agentService.onEvent(conversationId, (event: AgentSessionEvent) => {
-      this.relayEvent(client, conversationId, event);
-    });
+    const cleanup = this.agentService.onEvent(
+      conversationId,
+      (event: AgentSessionEvent) => {
+        this.relayEvent(client, conversationId, event);
+      },
+      scope,
+    );
 
     // Preserve routing decision from the existing client session if we didn't get a new one
     const prevClientSession = this.clientSessions.get(client.id);
@@ -246,16 +364,17 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
       assistantText: '',
       toolCalls: [],
       pendingToolCalls: new Map(),
+      scope,
       lastRoutingDecision: routingDecisionToStore,
     });
 
     // Track channel connection
-    this.agentService.addChannel(conversationId, `websocket:${client.id}`);
+    this.agentService.addChannel(conversationId, `websocket:${client.id}`, scope);
 
     // Send session info so the client knows the model/provider (M4-008: include routing decision)
     // Include agentName when a named agent config is active (M5-001)
     {
-      const agentSession = this.agentService.getSession(conversationId);
+      const agentSession = this.agentService.getSession(conversationId, scope);
       if (agentSession) {
         const piSession = agentSession.piSession;
         client.emit('session:info', {
@@ -271,11 +390,21 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     }
 
     // Send acknowledgment
-    client.emit('message:ack', { conversationId, messageId: uuid() });
+    client.emit('message:ack', {
+      conversationId,
+      messageId: uuid(),
+      ...(correlationId
+        ? {
+            correlationId,
+            discordMessageId: discordIngress?.messageId,
+            discordUserId: discordIngress?.userId,
+          }
+        : {}),
+    });
 
     // Dispatch to agent
     try {
-      await this.agentService.prompt(conversationId, data.content);
+      await this.agentService.prompt(conversationId, data.content, scope);
     } catch (err) {
       this.logger.error(
         `Agent prompt failed for client=${client.id}, conversation=${conversationId}`,
@@ -293,7 +422,16 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     @ConnectedSocket() client: Socket,
     @MessageBody() data: SetThinkingPayload,
   ): void {
-    const session = this.agentService.getSession(data.conversationId);
+    const scope = this.getClientScope(client);
+    if (!scope) {
+      client.emit('error', {
+        conversationId: data.conversationId,
+        error: 'Authenticated user scope is required.',
+      });
+      return;
+    }
+
+    const session = this.agentService.getSession(data.conversationId, scope);
     if (!session) {
       client.emit('error', {
         conversationId: data.conversationId,
@@ -334,7 +472,13 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     const conversationId = data.conversationId;
     this.logger.log(`Abort requested by ${client.id} for conversation ${conversationId}`);
 
-    const session = this.agentService.getSession(conversationId);
+    const scope = this.getClientScope(client);
+    if (!scope) {
+      client.emit('error', { conversationId, error: 'Authenticated user scope is required.' });
+      return;
+    }
+
+    const session = this.agentService.getSession(conversationId, scope);
     if (!session) {
       client.emit('error', {
         conversationId,
@@ -363,11 +507,45 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     @ConnectedSocket() client: Socket,
     @MessageBody() payload: SlashCommandPayload,
   ): Promise<void> {
-    const userId = (client.data.user as { id: string } | undefined)?.id ?? 'unknown';
-    const result = await this.commandExecutor.execute(payload, userId);
+    const scope = this.getClientScope(client);
+    if (!scope) {
+      client.emit('command:result', {
+        command: payload.command,
+        conversationId: payload.conversationId,
+        success: false,
+        message: 'Authenticated user scope is required.',
+      });
+      return;
+    }
+
+    const result = await this.commandExecutor.execute(payload, scope);
     client.emit('command:result', result);
   }
 
+  @SubscribeMessage('command:approve')
+  async handleCommandApproval(
+    @ConnectedSocket() client: Socket,
+    @MessageBody() payload: SlashCommandPayload,
+  ): Promise<void> {
+    const scope = this.getClientScope(client);
+    const approval = scope ? await this.commandExecutor.createApproval(payload, scope) : null;
+    const result: SlashCommandApprovalResultPayload = approval
+      ? {
+          command: payload.command,
+          conversationId: payload.conversationId,
+          success: true,
+          approvalId: approval.approvalId,
+          expiresAt: approval.expiresAt,
+        }
+      : {
+          command: payload.command,
+          conversationId: payload.conversationId,
+          success: false,
+          message: 'Not authorized to approve this command.',
+        };
+    client.emit('command:approval', result);
+  }
+
   broadcastReload(payload: SystemReloadPayload): void {
     this.server.emit('system:reload', payload);
     this.logger.log('Broadcasted system:reload to all connected clients');
@@ -380,18 +558,23 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
    * M5-005: Emits session:info to clients subscribed to this conversation when a model is set.
    * M5-007: Records a model switch in session metrics.
    */
-  setModelOverride(conversationId: string, modelName: string | null): void {
+  setModelOverride(
+    conversationId: string,
+    modelName: string | null,
+    scope: ActorTenantScope,
+  ): void {
+    const key = this.modelOverrideKey(conversationId, scope);
     if (modelName) {
-      modelOverrides.set(conversationId, modelName);
+      modelOverrides.set(key, modelName);
       this.logger.log(`Model override set: conversation=${conversationId} model="${modelName}"`);
 
       // M5-002: Update the live session's modelId so session:info reflects the new model immediately
-      this.agentService.updateSessionModel(conversationId, modelName);
+      this.agentService.updateSessionModel(conversationId, modelName, scope);
 
       // M5-005: Broadcast session:info to all clients subscribed to this conversation
-      this.broadcastSessionInfo(conversationId);
+      this.broadcastSessionInfo(conversationId, scope);
     } else {
-      modelOverrides.delete(conversationId);
+      modelOverrides.delete(key);
       this.logger.log(`Model override cleared: conversation=${conversationId}`);
     }
   }
@@ -399,8 +582,8 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
   /**
    * Return the active model override for a conversation, or undefined if none.
    */
-  getModelOverride(conversationId: string): string | undefined {
-    return modelOverrides.get(conversationId);
+  getModelOverride(conversationId: string, scope: ActorTenantScope): string | undefined {
+    return modelOverrides.get(this.modelOverrideKey(conversationId, scope));
   }
 
   /**
@@ -409,9 +592,10 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
    */
   broadcastSessionInfo(
     conversationId: string,
+    scope: ActorTenantScope,
     extra?: { agentName?: string; routingDecision?: RoutingDecisionInfo },
   ): void {
-    const agentSession = this.agentService.getSession(conversationId);
+    const agentSession = this.agentService.getSession(conversationId, scope);
     if (!agentSession) return;
 
     const piSession = agentSession.piSession;
@@ -428,7 +612,7 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
 
     // Emit to all clients currently subscribed to this conversation
     for (const [clientId, session] of this.clientSessions) {
-      if (session.conversationId === conversationId) {
+      if (session.conversationId === conversationId && this.scopesEqual(session.scope, scope)) {
         const socket = this.server.sockets.sockets.get(clientId);
         if (socket?.connected) {
           socket.emit('session:info', payload);
@@ -442,6 +626,39 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
    * Creates it if absent — safe to call concurrently since a duplicate insert
    * would fail on the PK constraint and be caught here.
    */
+  private resolveDiscordIngress(
+    client: Socket,
+    envelope: DiscordIngressEnvelope,
+  ): DiscordIngressPayload | null {
+    const payload = verifyDiscordIngressEnvelope(
+      envelope,
+      process.env['DISCORD_SERVICE_TOKEN'] ?? '',
+      {
+        guildIds: this.readDiscordAllowlist('DISCORD_ALLOWED_GUILD_IDS'),
+        channelIds: this.readDiscordAllowlist('DISCORD_ALLOWED_CHANNEL_IDS'),
+        userIds: this.readDiscordAllowlist('DISCORD_ALLOWED_USER_IDS'),
+      },
+    );
+    if (!payload) {
+      this.logger.warn(`Rejected invalid Discord ingress envelope from ${client.id}`);
+      return null;
+    }
+    if (!this.discordReplayProtector.claim(payload.messageId)) {
+      this.logger.warn(
+        `Rejected replayed Discord message=${payload.messageId} correlation=${payload.correlationId}`,
+      );
+      return null;
+    }
+    return payload;
+  }
+
+  private readDiscordAllowlist(name: string): string[] {
+    return (process.env[name] ?? '')
+      .split(',')
+      .map((id: string): string => id.trim())
+      .filter((id: string): boolean => id.length > 0);
+  }
+
   private async ensureConversation(conversationId: string, userId: string): Promise<void> {
     try {
       const existing = await this.brain.conversations.findById(conversationId, userId);
@@ -550,7 +767,10 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
 
       case 'agent_end': {
         // Gather usage stats from the Pi session
-        const agentSession = this.agentService.getSession(conversationId);
+        const activeClientSession = this.clientSessions.get(client.id);
+        const agentSession = activeClientSession
+          ? this.agentService.getSession(conversationId, activeClientSession.scope)
+          : undefined;
         const piSession = agentSession?.piSession;
         const stats = piSession?.getSessionStats();
         const contextUsage = piSession?.getContextUsage();

apps/gateway/src/commands/command-authorization.service.spec.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+import type { CommandDef, SlashCommandPayload } from '@mosaicstack/types';
+import { CommandAuthorizationService } from './command-authorization.service.js';
+
+const adminCommand: CommandDef = {
+  name: 'gc',
+  description: 'GC',
+  aliases: [],
+  scope: 'admin',
+  execution: 'socket',
+  available: true,
+};
+const payload: SlashCommandPayload = { command: 'gc', conversationId: 'conversation-1' };
+
+function createService(role: string): CommandAuthorizationService {
+  const entries = new Map<string, string>();
+  const db = {
+    select: () => ({ from: () => ({ where: () => ({ limit: async () => [{ role }] }) }) }),
+  };
+  const redis = {
+    get: async (key: string) => entries.get(key) ?? null,
+    set: async (key: string, value: string) => {
+      entries.set(key, value);
+    },
+    del: async (key: string) => Number(entries.delete(key)),
+  };
+  return new CommandAuthorizationService(db as never, redis);
+}
+
+describe('CommandAuthorizationService', () => {
+  it('consumes one exact actor-bound approval once', async (): Promise<void> => {
+    const service = createService('admin');
+    const approval = await service.createApproval(adminCommand, payload, 'admin-1');
+    expect(approval).not.toBeNull();
+    expect(
+      (await service.authorize(adminCommand, payload, 'admin-1', approval!.approvalId)).allowed,
+    ).toBe(true);
+    expect(
+      (await service.authorize(adminCommand, payload, 'admin-1', approval!.approvalId)).allowed,
+    ).toBe(false);
+  });
+
+  it('rejects an approval when the structured action is mutated', async (): Promise<void> => {
+    const service = createService('admin');
+    const approval = await service.createApproval(adminCommand, payload, 'admin-1');
+    const mutated = { ...payload, conversationId: 'other-conversation' };
+    expect(approval).not.toBeNull();
+    expect(
+      (await service.authorize(adminCommand, mutated, 'admin-1', approval!.approvalId)).allowed,
+    ).toBe(false);
+  });
+
+  it('denies an admin command to a member before approval is considered', async (): Promise<void> => {
+    const service = createService('member');
+    const approval = await service.createApproval(adminCommand, payload, 'member-1');
+    expect(approval).toBeNull();
+    expect(
+      (await service.authorize(adminCommand, payload, 'member-1', 'forged-approval-id')).allowed,
+    ).toBe(false);
+  });
+});

apps/gateway/src/commands/command-authorization.service.ts

@@ -0,0 +1,138 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { Inject, Injectable } from '@nestjs/common';
+import { eq, users as usersTable, type Db } from '@mosaicstack/db';
+import type { CommandDef, SlashCommandPayload } from '@mosaicstack/types';
+import { DB } from '../database/database.module.js';
+import { COMMANDS_REDIS } from './commands.tokens.js';
+
+export type CommandRole = 'admin' | 'member' | 'viewer';
+
+export interface CommandApproval {
+  approvalId: string;
+  actionDigest: string;
+  actorId: string;
+  command: string;
+  expiresAt: string;
+}
+
+export interface CommandAuthorizationResult {
+  allowed: boolean;
+  reason?: string;
+}
+
+@Injectable()
+export class CommandAuthorizationService {
+  constructor(
+    @Inject(DB) private readonly db: Db,
+    @Inject(COMMANDS_REDIS)
+    private readonly redis: {
+      get(key: string): Promise<string | null>;
+      set(key: string, value: string, ...args: string[]): Promise<unknown>;
+      del(key: string): Promise<number>;
+    },
+  ) {}
+
+  async authorize(
+    command: CommandDef,
+    payload: SlashCommandPayload,
+    actorId: string,
+    approvalId?: string,
+  ): Promise<CommandAuthorizationResult> {
+    const role = await this.resolveRole(actorId);
+    if (!role || !this.hasScope(role, command.scope)) {
+      return { allowed: false, reason: 'not authorized for this command scope' };
+    }
+    if (command.scope !== 'admin') return { allowed: true };
+    if (!approvalId) return { allowed: false, reason: 'durable approval is required' };
+    const actionDigest = this.actionDigest(command.name, payload);
+    const approved = await this.consumeApproval(approvalId, actorId, actionDigest);
+    return approved
+      ? { allowed: true }
+      : {
+          allowed: false,
+          reason: 'approval is invalid, expired, replayed, or does not match this action',
+        };
+  }
+
+  async createApproval(
+    command: CommandDef,
+    payload: SlashCommandPayload,
+    actorId: string,
+  ): Promise<CommandApproval | null> {
+    const role = await this.resolveRole(actorId);
+    if (!role || command.scope !== 'admin' || !this.hasScope(role, command.scope)) return null;
+
+    const approvalId = randomUUID();
+    const expiresAt = new Date(Date.now() + 5 * 60_000).toISOString();
+    const approval: CommandApproval = {
+      approvalId,
+      actionDigest: this.actionDigest(command.name, payload),
+      actorId,
+      command: command.name,
+      expiresAt,
+    };
+    await this.redis.set(this.key(approvalId), JSON.stringify(approval), 'EX', '300');
+    return approval;
+  }
+
+  private async resolveRole(actorId: string): Promise<CommandRole | null> {
+    const [user] = await this.db
+      .select({ role: usersTable.role })
+      .from(usersTable)
+      .where(eq(usersTable.id, actorId))
+      .limit(1);
+    const role = user?.role;
+    return role === 'admin' || role === 'member' || role === 'viewer' ? role : null;
+  }
+
+  private hasScope(role: CommandRole, scope: CommandDef['scope']): boolean {
+    if (role === 'admin') return true;
+    return role === 'member' && (scope === 'core' || scope === 'agent');
+  }
+
+  private async consumeApproval(
+    approvalId: string,
+    actorId: string,
+    actionDigest: string,
+  ): Promise<boolean> {
+    const key = this.key(approvalId);
+    const encoded = await this.redis.get(key);
+    if (!encoded) return false;
+    const parsed: unknown = JSON.parse(encoded);
+    if (
+      !this.isApproval(parsed) ||
+      parsed.actorId !== actorId ||
+      parsed.actionDigest !== actionDigest ||
+      Date.parse(parsed.expiresAt) <= Date.now()
+    )
+      return false;
+    return (await this.redis.del(key)) === 1;
+  }
+
+  private actionDigest(command: string, payload: SlashCommandPayload): string {
+    return createHash('sha256')
+      .update(
+        JSON.stringify({
+          command,
+          args: payload.args?.trim() ?? '',
+          conversationId: payload.conversationId,
+        }),
+      )
+      .digest('hex');
+  }
+
+  private isApproval(value: unknown): value is CommandApproval {
+    return (
+      typeof value === 'object' &&
+      value !== null &&
+      'approvalId' in value &&
+      'actionDigest' in value &&
+      'actorId' in value &&
+      'expiresAt' in value
+    );
+  }
+
+  private key(approvalId: string): string {
+    return `tess:command-approval:${approvalId}`;
+  }
+}

apps/gateway/src/commands/command-executor-p8012.spec.ts

@@ -89,6 +89,7 @@ function buildService(): CommandExecutorService {
 describe('CommandExecutorService — P8-012 commands', () => {
   let service: CommandExecutorService;
   const userId = 'user-123';
+  const userScope = { userId, tenantId: userId };
   const conversationId = 'conv-456';
 
   beforeEach(() => {
@@ -99,7 +100,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
   // /provider login — missing provider name
   it('/provider login with no provider name returns usage error', async () => {
     const payload: SlashCommandPayload = { command: 'provider', args: 'login', conversationId };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(false);
     expect(result.message).toContain('Usage: /provider login');
     expect(result.command).toBe('provider');
@@ -112,7 +113,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
       args: 'login anthropic',
       conversationId,
     };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.command).toBe('provider');
     expect(result.message).toContain('anthropic');
@@ -138,7 +139,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
   // /provider with no args — returns usage
   it('/provider with no args returns usage message', async () => {
     const payload: SlashCommandPayload = { command: 'provider', conversationId };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.message).toContain('Usage: /provider');
   });
@@ -146,7 +147,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
   // /provider list
   it('/provider list returns success', async () => {
     const payload: SlashCommandPayload = { command: 'provider', args: 'list', conversationId };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.command).toBe('provider');
   });
@@ -154,7 +155,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
   // /provider logout with no name — usage error
   it('/provider logout with no name returns error', async () => {
     const payload: SlashCommandPayload = { command: 'provider', args: 'logout', conversationId };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(false);
     expect(result.message).toContain('Usage: /provider logout');
   });
@@ -166,7 +167,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
       args: 'unknown',
       conversationId,
     };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(false);
     expect(result.message).toContain('Unknown subcommand');
   });
@@ -174,7 +175,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
   // /mission status
   it('/mission status returns stub message', async () => {
     const payload: SlashCommandPayload = { command: 'mission', args: 'status', conversationId };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.command).toBe('mission');
     expect(result.message).toContain('Mission status');
@@ -183,7 +184,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
   // /mission with no args
   it('/mission with no args returns status stub', async () => {
     const payload: SlashCommandPayload = { command: 'mission', conversationId };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.message).toContain('Mission status');
   });
@@ -195,7 +196,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
       args: 'set my-mission-123',
       conversationId,
     };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.message).toContain('my-mission-123');
   });
@@ -203,7 +204,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
   // /agent list
   it('/agent list returns stub message', async () => {
     const payload: SlashCommandPayload = { command: 'agent', args: 'list', conversationId };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.command).toBe('agent');
     expect(result.message).toContain('agent');
@@ -212,7 +213,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
   // /agent with no args
   it('/agent with no args returns usage', async () => {
     const payload: SlashCommandPayload = { command: 'agent', conversationId };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.message).toContain('Usage: /agent');
   });
@@ -224,7 +225,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
       args: 'my-agent-id',
       conversationId,
     };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.message).toContain('my-agent-id');
   });
@@ -232,7 +233,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
   // /prdy
   it('/prdy returns PRD wizard message', async () => {
     const payload: SlashCommandPayload = { command: 'prdy', conversationId };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.command).toBe('prdy');
     expect(result.message).toContain('mosaic prdy');
@@ -241,7 +242,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
   // /tools
   it('/tools returns tools stub message', async () => {
     const payload: SlashCommandPayload = { command: 'tools', conversationId };
-    const result = await service.execute(payload, userId);
+    const result = await service.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.command).toBe('tools');
     expect(result.message).toContain('tools');

apps/gateway/src/commands/command-executor-tess-security.spec.ts

@@ -0,0 +1,109 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { SlashCommandPayload } from '@mosaicstack/types';
+import { CommandAuthorizationService } from './command-authorization.service.js';
+import { CommandExecutorService } from './command-executor.service.js';
+
+const registry = {
+  getManifest: vi.fn(() => ({
+    version: 1,
+    commands: [
+      {
+        name: 'gc',
+        description: 'System-wide garbage collection',
+        aliases: [],
+        scope: 'admin' as const,
+        execution: 'socket' as const,
+        available: true,
+      },
+    ],
+    skills: [],
+  })),
+};
+
+const sessionGc = {
+  sweepOrphans: vi.fn().mockResolvedValue({ orphanedSessions: 1, totalCleaned: [], duration: 1 }),
+};
+
+const scope = (userId: string) => ({ userId, tenantId: 'tenant-1' });
+
+const authorization = {
+  authorize: vi.fn((_command: unknown, _payload: unknown, actorId: string) =>
+    Promise.resolve(
+      actorId === 'member-1'
+        ? { allowed: false, reason: 'durable approval is required' }
+        : { allowed: false, reason: 'not authorized for this command scope' },
+    ),
+  ),
+};
+
+function buildExecutor(authorizationService: unknown = authorization): CommandExecutorService {
+  return new CommandExecutorService(
+    registry as never,
+    { getSession: vi.fn() } as never,
+    { clear: vi.fn(), set: vi.fn() } as never,
+    sessionGc as never,
+    { set: vi.fn() } as never,
+    { agents: {} } as never,
+    null,
+    null,
+    null,
+    authorizationService as never,
+  );
+}
+
+function createDurableAuthorization(): CommandAuthorizationService {
+  const entries = new Map<string, string>();
+  const db = {
+    select: () => ({ from: () => ({ where: () => ({ limit: async () => [{ role: 'admin' }] }) }) }),
+  };
+  const redis = {
+    get: async (key: string) => entries.get(key) ?? null,
+    set: async (key: string, value: string) => {
+      entries.set(key, value);
+    },
+    del: async (key: string) => Number(entries.delete(key)),
+  };
+  return new CommandAuthorizationService(db as never, redis);
+}
+
+describe('TESS-M1-SEC-001 command authorization abuse cases', () => {
+  const payload: SlashCommandPayload = { command: 'gc', conversationId: 'conversation-1' };
+
+  beforeEach((): void => {
+    vi.clearAllMocks();
+  });
+
+  it('denies a forged admin identity and does not execute a system-wide command', async (): Promise<void> => {
+    const result = await buildExecutor().execute(payload, scope('admin-forged-by-client'));
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('not authorized');
+    expect(sessionGc.sweepOrphans).not.toHaveBeenCalled();
+  });
+
+  it('denies a privileged command without a server-bound durable approval', async (): Promise<void> => {
+    const result = await buildExecutor().execute(payload, scope('member-1'));
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('approval');
+    expect(sessionGc.sweepOrphans).not.toHaveBeenCalled();
+  });
+
+  it('executes an admin command only after a valid durable approval is issued and supplied', async (): Promise<void> => {
+    const executor = buildExecutor(createDurableAuthorization());
+
+    const adminScope = scope('admin-1');
+    const denied = await executor.execute(payload, adminScope);
+    const approval = await executor.createApproval(payload, adminScope);
+    const approved = await executor.execute(
+      { ...payload, approvalId: approval?.approvalId },
+      adminScope,
+    );
+
+    expect(denied.success).toBe(false);
+    expect(denied.message).toContain('approval');
+    expect(approval).not.toBeNull();
+    expect(approved.success).toBe(true);
+    expect(sessionGc.sweepOrphans).toHaveBeenCalledOnce();
+  });
+});

apps/gateway/src/commands/command-executor.service.ts

@@ -3,6 +3,7 @@ import type { QueueHandle } from '@mosaicstack/queue';
 import type { Brain } from '@mosaicstack/brain';
 import type { SlashCommandPayload, SlashCommandResultPayload } from '@mosaicstack/types';
 import { AgentService } from '../agent/agent.service.js';
+import type { ActorTenantScope } from '../auth/session-scope.js';
 import { ChatGateway } from '../chat/chat.gateway.js';
 import { SessionGCService } from '../gc/session-gc.service.js';
 import { SystemOverrideService } from '../preferences/system-override.service.js';
@@ -10,6 +11,7 @@ import { ReloadService } from '../reload/reload.service.js';
 import { McpClientService } from '../mcp-client/mcp-client.service.js';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { COMMANDS_REDIS } from './commands.tokens.js';
+import { CommandAuthorizationService } from './command-authorization.service.js';
 import { CommandRegistryService } from './command-registry.service.js';
 
 @Injectable()
@@ -32,10 +34,17 @@ export class CommandExecutorService {
     @Optional()
     @Inject(McpClientService)
     private readonly mcpClient: McpClientService | null,
+    @Optional()
+    @Inject(CommandAuthorizationService)
+    private readonly authorization: CommandAuthorizationService | null = null,
   ) {}
 
-  async execute(payload: SlashCommandPayload, userId: string): Promise<SlashCommandResultPayload> {
+  async execute(
+    payload: SlashCommandPayload,
+    scope: ActorTenantScope,
+  ): Promise<SlashCommandResultPayload> {
     const { command, args, conversationId } = payload;
+    const userId = scope.userId;
 
     const def = this.registry.getManifest().commands.find((c) => c.name === command);
     if (!def) {
@@ -47,14 +56,24 @@ export class CommandExecutorService {
       };
     }
 
+    const authorization = await this.authorization?.authorize(
+      def,
+      payload,
+      userId,
+      payload.approvalId,
+    );
+    if (authorization && !authorization.allowed) {
+      return { command, conversationId, success: false, message: authorization.reason };
+    }
+
     try {
       switch (command) {
         case 'model':
-          return await this.handleModel(args ?? null, conversationId);
+          return await this.handleModel(args ?? null, conversationId, scope);
         case 'thinking':
           return await this.handleThinking(args ?? null, conversationId);
         case 'system':
-          return await this.handleSystem(args ?? null, conversationId);
+          return await this.handleSystem(args ?? null, conversationId, scope);
         case 'new':
           return {
             command,
@@ -83,18 +102,17 @@ export class CommandExecutorService {
             success: true,
             message: 'Retry last message requested.',
           };
-        case 'gc': {
-          // Admin-only: system-wide GC sweep across all sessions
-          const result = await this.sessionGC.sweepOrphans();
+        case 'gc':
+          // Global retention requires a separate, authorized and audited job.
+          // Session cleanup is performed only through the session lifecycle.
           return {
             command: 'gc',
-            success: true,
-            message: `GC sweep complete: ${result.orphanedSessions} orphaned sessions cleaned in ${result.duration}ms.`,
+            success: false,
+            message: 'Global GC is disabled pending an authorized retention job.',
             conversationId,
           };
-        }
         case 'agent':
-          return await this.handleAgent(args ?? null, conversationId, userId);
+          return await this.handleAgent(args ?? null, conversationId, scope);
         case 'provider':
           return await this.handleProvider(args ?? null, userId, conversationId);
         case 'mission':
@@ -143,13 +161,22 @@ export class CommandExecutorService {
     }
   }
 
+  async createApproval(payload: SlashCommandPayload, scope: ActorTenantScope) {
+    const def = this.registry
+      .getManifest()
+      .commands.find((command) => command.name === payload.command);
+    if (!def || !this.authorization) return null;
+    return this.authorization.createApproval(def, payload, scope.userId);
+  }
+
   private async handleModel(
     args: string | null,
     conversationId: string,
+    scope: ActorTenantScope,
   ): Promise<SlashCommandResultPayload> {
     if (!args || args.trim().length === 0) {
       // Show current override or usage hint
-      const currentOverride = this.chatGateway?.getModelOverride(conversationId);
+      const currentOverride = this.chatGateway?.getModelOverride(conversationId, scope);
       if (currentOverride) {
         return {
           command: 'model',
@@ -171,7 +198,7 @@ export class CommandExecutorService {
 
     // /model clear removes the override and re-enables automatic routing
     if (modelName === 'clear') {
-      this.chatGateway?.setModelOverride(conversationId, null);
+      this.chatGateway?.setModelOverride(conversationId, null, scope);
       return {
         command: 'model',
         conversationId,
@@ -181,9 +208,9 @@ export class CommandExecutorService {
     }
 
     // Set the sticky per-session override (M4-007)
-    this.chatGateway?.setModelOverride(conversationId, modelName);
+    this.chatGateway?.setModelOverride(conversationId, modelName, scope);
 
-    const session = this.agentService.getSession(conversationId);
+    const session = this.agentService.getSession(conversationId, scope);
     if (!session) {
       return {
         command: 'model',
@@ -224,10 +251,11 @@ export class CommandExecutorService {
   private async handleSystem(
     args: string | null,
     conversationId: string,
+    scope: ActorTenantScope,
   ): Promise<SlashCommandResultPayload> {
     if (!args || args.trim().length === 0) {
       // Clear the override when called with no args
-      await this.systemOverride.clear(conversationId);
+      await this.systemOverride.clear(conversationId, scope);
       return {
         command: 'system',
         conversationId,
@@ -236,7 +264,7 @@ export class CommandExecutorService {
       };
     }
 
-    await this.systemOverride.set(conversationId, args.trim());
+    await this.systemOverride.set(conversationId, args.trim(), scope);
     return {
       command: 'system',
       conversationId,
@@ -248,8 +276,9 @@ export class CommandExecutorService {
   private async handleAgent(
     args: string | null,
     conversationId: string,
-    userId: string,
+    scope: ActorTenantScope,
   ): Promise<SlashCommandResultPayload> {
+    const userId = scope.userId;
     if (!args) {
       return {
         command: 'agent',
@@ -338,11 +367,14 @@ export class CommandExecutorService {
         conversationId,
         agentConfig.id,
         agentConfig.name,
+        scope,
         agentConfig.model ?? undefined,
       );
 
       // Broadcast updated session:info so TUI TopBar reflects new agent/model
-      this.chatGateway?.broadcastSessionInfo(conversationId, { agentName: agentConfig.name });
+      this.chatGateway?.broadcastSessionInfo(conversationId, scope, {
+        agentName: agentConfig.name,
+      });
 
       this.logger.log(
         `Agent switched to "${agentConfig.name}" (${agentConfig.id}) for conversation ${conversationId} (M5-003)`,

apps/gateway/src/commands/commands.integration.spec.ts

@@ -159,6 +159,7 @@ describe('CommandExecutorService — integration', () => {
   let registry: CommandRegistryService;
   let executor: CommandExecutorService;
   const userId = 'user-integ-001';
+  const userScope = { userId, tenantId: userId };
   const conversationId = 'conv-integ-001';
 
   beforeEach(() => {
@@ -170,28 +171,26 @@ describe('CommandExecutorService — integration', () => {
   // Unknown command returns error
   it('unknown command returns success:false with descriptive message', async () => {
     const payload: SlashCommandPayload = { command: 'nonexistent', conversationId };
-    const result = await executor.execute(payload, userId);
+    const result = await executor.execute(payload, userScope);
     expect(result.success).toBe(false);
     expect(result.message).toContain('nonexistent');
     expect(result.command).toBe('nonexistent');
   });
 
-  // /gc handler calls SessionGCService.sweepOrphans (admin-only, no userId arg)
-  it('/gc calls SessionGCService.sweepOrphans without arguments', async () => {
+  it('/gc refuses an unaudited global sweep', async () => {
     const payload: SlashCommandPayload = { command: 'gc', conversationId };
-    const result = await executor.execute(payload, userId);
-    expect(mockSessionGC.sweepOrphans).toHaveBeenCalledWith();
-    expect(result.success).toBe(true);
-    expect(result.message).toContain('GC sweep complete');
-    expect(result.message).toContain('3 orphaned sessions');
+    const result = await executor.execute(payload, userScope);
+    expect(mockSessionGC.sweepOrphans).not.toHaveBeenCalled();
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('disabled pending an authorized retention job');
   });
 
   // /system with args calls SystemOverrideService.set
   it('/system with text calls SystemOverrideService.set', async () => {
     const override = 'You are a helpful assistant.';
     const payload: SlashCommandPayload = { command: 'system', args: override, conversationId };
-    const result = await executor.execute(payload, userId);
-    expect(mockSystemOverride.set).toHaveBeenCalledWith(conversationId, override);
+    const result = await executor.execute(payload, userScope);
+    expect(mockSystemOverride.set).toHaveBeenCalledWith(conversationId, override, userScope);
     expect(result.success).toBe(true);
     expect(result.message).toContain('override set');
   });
@@ -199,8 +198,8 @@ describe('CommandExecutorService — integration', () => {
   // /system with no args clears the override
   it('/system with no args calls SystemOverrideService.clear', async () => {
     const payload: SlashCommandPayload = { command: 'system', conversationId };
-    const result = await executor.execute(payload, userId);
-    expect(mockSystemOverride.clear).toHaveBeenCalledWith(conversationId);
+    const result = await executor.execute(payload, userScope);
+    expect(mockSystemOverride.clear).toHaveBeenCalledWith(conversationId, userScope);
     expect(result.success).toBe(true);
     expect(result.message).toContain('cleared');
   });
@@ -212,7 +211,7 @@ describe('CommandExecutorService — integration', () => {
       args: 'claude-3-opus',
       conversationId,
     };
-    const result = await executor.execute(payload, userId);
+    const result = await executor.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.command).toBe('model');
     expect(result.message).toContain('claude-3-opus');
@@ -221,7 +220,7 @@ describe('CommandExecutorService — integration', () => {
   // /thinking with valid level returns success
   it('/thinking with valid level returns success', async () => {
     const payload: SlashCommandPayload = { command: 'thinking', args: 'high', conversationId };
-    const result = await executor.execute(payload, userId);
+    const result = await executor.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.message).toContain('high');
   });
@@ -229,7 +228,7 @@ describe('CommandExecutorService — integration', () => {
   // /thinking with invalid level returns usage message
   it('/thinking with invalid level returns usage message', async () => {
     const payload: SlashCommandPayload = { command: 'thinking', args: 'invalid', conversationId };
-    const result = await executor.execute(payload, userId);
+    const result = await executor.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.message).toContain('Usage:');
   });
@@ -237,7 +236,7 @@ describe('CommandExecutorService — integration', () => {
   // /new command returns success
   it('/new returns success', async () => {
     const payload: SlashCommandPayload = { command: 'new', conversationId };
-    const result = await executor.execute(payload, userId);
+    const result = await executor.execute(payload, userScope);
     expect(result.success).toBe(true);
     expect(result.command).toBe('new');
   });
@@ -245,7 +244,7 @@ describe('CommandExecutorService — integration', () => {
   // /reload without reloadService returns failure
   it('/reload without ReloadService returns failure', async () => {
     const payload: SlashCommandPayload = { command: 'reload', conversationId };
-    const result = await executor.execute(payload, userId);
+    const result = await executor.execute(payload, userScope);
     expect(result.success).toBe(false);
     expect(result.message).toContain('ReloadService');
   });
@@ -255,7 +254,7 @@ describe('CommandExecutorService — integration', () => {
   for (const cmd of stubCommands) {
     it(`/${cmd} returns success (stub)`, async () => {
       const payload: SlashCommandPayload = { command: cmd, conversationId };
-      const result = await executor.execute(payload, userId);
+      const result = await executor.execute(payload, userScope);
       expect(result.success).toBe(true);
       expect(result.command).toBe(cmd);
     });

apps/gateway/src/commands/commands.module.ts

@@ -3,6 +3,7 @@ import { createQueue, type QueueHandle } from '@mosaicstack/queue';
 import { ChatModule } from '../chat/chat.module.js';
 import { GCModule } from '../gc/gc.module.js';
 import { ReloadModule } from '../reload/reload.module.js';
+import { CommandAuthorizationService } from './command-authorization.service.js';
 import { CommandExecutorService } from './command-executor.service.js';
 import { CommandRegistryService } from './command-registry.service.js';
 import { COMMANDS_REDIS } from './commands.tokens.js';
@@ -24,6 +25,7 @@ const COMMANDS_QUEUE_HANDLE = 'COMMANDS_QUEUE_HANDLE';
       inject: [COMMANDS_QUEUE_HANDLE],
     },
     CommandRegistryService,
+    CommandAuthorizationService,
     CommandExecutorService,
   ],
   exports: [CommandRegistryService, CommandExecutorService],

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 { createDb, createPgliteDb, type Db, type DbHandle } from '@mosaicstack/db';
+import {
+  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()]);
   }

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,57 @@
+/**
+ * DTOs for the Step-CA client service (FED-M2-04).
+ *
+ * IssueCertRequestDto  — input to CaService.issueCert()
+ * IssuedCertDto        — output from CaService.issueCert()
+ */
+
+import { IsInt, IsNotEmpty, IsOptional, IsString, IsUUID, Max, Min } from 'class-validator';
+
+export class IssueCertRequestDto {
+  /**
+   * PEM-encoded PKCS#10 Certificate Signing Request.
+   * The CSR must already include the desired SANs.
+   */
+  @IsString()
+  @IsNotEmpty()
+  csrPem!: string;
+
+  /**
+   * UUID of the federation_grants row this certificate is being issued for.
+   * Embedded as the `mosaic_grant_id` custom OID extension.
+   */
+  @IsUUID()
+  grantId!: string;
+
+  /**
+   * UUID of the local user on whose behalf the cert is being issued.
+   * Embedded as the `mosaic_subject_user_id` custom OID extension.
+   */
+  @IsUUID()
+  subjectUserId!: string;
+
+  /**
+   * Requested certificate validity in seconds.
+   * Hard cap: 900 s (15 minutes). Default: 300 s (5 minutes).
+   * The service will always clamp to 900 s regardless of this value.
+   */
+  @IsOptional()
+  @IsInt()
+  @Min(60)
+  @Max(15 * 60)
+  ttlSeconds: number = 300;
+}
+
+export class IssuedCertDto {
+  /** PEM-encoded leaf certificate returned by step-ca. */
+  certPem!: string;
+
+  /**
+   * PEM-encoded full certificate chain (leaf + intermediates + root).
+   * Falls back to `certPem` when step-ca returns no `certChain` field.
+   */
+  certChainPem!: string;
+
+  /** Decimal serial number string of the issued certificate. */
+  serialNumber!: string;
+}

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

@@ -0,0 +1,592 @@
+/**
+ * Unit tests for CaService — Step-CA client (FED-M2-04).
+ *
+ * Coverage:
+ *  - Happy path: returns IssuedCertDto with certPem, certChainPem, serialNumber
+ *  - certChainPem fallback: falls back to certPem when certChain absent
+ *  - certChainPem from ca field: uses crt+ca when certChain absent but ca present
+ *  - HTTP 401: throws CaServiceError with cause + remediation
+ *  - HTTP non-401 error: throws CaServiceError
+ *  - Malformed CSR: throws before HTTP call (INVALID_CSR)
+ *  - Non-JSON response: throws CaServiceError
+ *  - HTTPS connection error: throws CaServiceError
+ *  - JWT custom claims: mosaic_grant_id and mosaic_subject_user_id present in OTT payload
+ *    verified with jose.jwtVerify (real signature check)
+ *  - CaServiceError: has cause + remediation properties
+ *  - Missing crt in response: throws CaServiceError
+ *  - Real CSR validation: valid P-256 CSR passes; malformed CSR fails with INVALID_CSR
+ *  - provisionerPassword never appears in CaServiceError messages
+ *  - HTTPS-only enforcement: http:// URL throws in constructor
+ */
+
+import 'reflect-metadata';
+import { describe, it, expect, vi, beforeEach, beforeAll, type Mock } from 'vitest';
+import { jwtVerify, exportJWK, generateKeyPair } from 'jose';
+import { Pkcs10CertificateRequestGenerator } from '@peculiar/x509';
+import { makeMosaicIssuedCert } from './__tests__/helpers/test-cert.js';
+
+// ---------------------------------------------------------------------------
+// Mock node:https BEFORE importing CaService so the mock is in place when
+// the module is loaded. Vitest/ESM require vi.mock at the top level.
+// ---------------------------------------------------------------------------
+
+vi.mock('node:https', () => {
+  const mockRequest = vi.fn();
+  const mockAgent = vi.fn().mockImplementation(() => ({}));
+  return {
+    default: { request: mockRequest, Agent: mockAgent },
+    request: mockRequest,
+    Agent: mockAgent,
+  };
+});
+
+vi.mock('node:fs', () => {
+  const mockReadFileSync = vi
+    .fn()
+    .mockReturnValue('-----BEGIN CERTIFICATE-----\nFAKEROOT\n-----END CERTIFICATE-----\n');
+  return {
+    default: { readFileSync: mockReadFileSync },
+    readFileSync: mockReadFileSync,
+  };
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+// Real self-signed EC P-256 certificate generated with openssl for testing.
+// openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes -keyout /dev/null \
+//   -out /dev/stdout -subj "/CN=test" -days 1
+const FAKE_CERT_PEM = `-----BEGIN CERTIFICATE-----
+MIIBdDCCARmgAwIBAgIUM+iUJSayN+PwXkyVN6qwSY7sr6gwCgYIKoZIzj0EAwIw
+DzENMAsGA1UEAwwEdGVzdDAeFw0yNjA0MjIwMzE5MTlaFw0yNjA0MjMwMzE5MTla
+MA8xDTALBgNVBAMMBHRlc3QwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAR21kHL
+n1GmFQ4TEBw3EA53pD+2McIBf5WcoHE+x0eMz5DpRKJe0ksHwOVN5Yev5d57kb+4
+MvG1LhbHCB/uQo8So1MwUTAdBgNVHQ4EFgQUPq0pdIGiQ7pLBRXICS8GTliCrLsw
+HwYDVR0jBBgwFoAUPq0pdIGiQ7pLBRXICS8GTliCrLswDwYDVR0TAQH/BAUwAwEB
+/zAKBggqhkjOPQQDAgNJADBGAiEAypJqyC6S77aQ3eEXokM6sgAsD7Oa3tJbCbVm
+zG3uJb0CIQC1w+GE+Ad0OTR5Quja46R1RjOo8ydpzZ7Fh4rouAiwEw==
+-----END CERTIFICATE-----
+`;
+
+// Use a second copy of the same cert for the CA field in tests.
+const FAKE_CA_PEM = FAKE_CERT_PEM;
+
+const GRANT_ID = 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11';
+const SUBJECT_USER_ID = 'b1ffcd00-0d1c-5f09-cc7e-7cc0ce491b22';
+
+// Real self-signed cert containing both Mosaic OID extensions — populated in beforeAll.
+// Required because CaService.issueCert performs CRIT-1 OID presence/value checks on the
+// response cert (PR #501 — strict parsing, no silent fallback).
+let realIssuedCertPem: string;
+
+// ---------------------------------------------------------------------------
+// Generate a real EC P-256 key pair and CSR for integration-style tests
+// ---------------------------------------------------------------------------
+
+// We generate this once at module level so it's available to all tests.
+// The key pair and CSR PEM are populated asynchronously in the test that needs them.
+
+let realCsrPem: string;
+
+async function generateRealCsr(): Promise<string> {
+  const { privateKey, publicKey } = await generateKeyPair('ES256');
+  // Export public key JWK for potential verification (not used here but confirms key is exportable)
+  await exportJWK(publicKey);
+
+  // Use @peculiar/x509 to build a proper CSR
+  const csr = await Pkcs10CertificateRequestGenerator.create({
+    name: 'CN=test.federation.local',
+    signingAlgorithm: { name: 'ECDSA', hash: 'SHA-256' },
+    keys: { privateKey, publicKey },
+  });
+
+  return csr.toString('pem');
+}
+
+// ---------------------------------------------------------------------------
+// Setup env before importing service
+// We use an EC P-256 key pair here so the JWK-based signing works.
+// The key pair is generated once and stored in module-level vars.
+// ---------------------------------------------------------------------------
+
+// Real EC P-256 test JWK (test-only, never used in production).
+// Generated with node webcrypto for use in unit tests.
+const TEST_EC_PRIVATE_JWK = {
+  key_ops: ['sign'],
+  ext: true,
+  kty: 'EC',
+  x: 'Xq2RjZctcPcUMU14qfjs3MtZTmFk8z1lFGQyypgXZOU',
+  y: 't8w9Cbt4RVmR47Wnb_i5cLwefEnMcvwse049zu9Rl_E',
+  crv: 'P-256',
+  d: 'TM6N79w1HE-PiML5Td4mbXfJaLHEaZrVyVrrwlJv7q8',
+  kid: 'test-ec-kid',
+};
+
+const TEST_EC_PUBLIC_JWK = {
+  key_ops: ['verify'],
+  ext: true,
+  kty: 'EC',
+  x: 'Xq2RjZctcPcUMU14qfjs3MtZTmFk8z1lFGQyypgXZOU',
+  y: 't8w9Cbt4RVmR47Wnb_i5cLwefEnMcvwse049zu9Rl_E',
+  crv: 'P-256',
+  kid: 'test-ec-kid',
+};
+
+process.env['STEP_CA_URL'] = 'https://step-ca:9000';
+process.env['STEP_CA_PROVISIONER_KEY_JSON'] = JSON.stringify(TEST_EC_PRIVATE_JWK);
+process.env['STEP_CA_ROOT_CERT_PATH'] = '/fake/root.pem';
+
+// Import AFTER env is set and mocks are registered
+import * as httpsModule from 'node:https';
+import { CaService, CaServiceError } from './ca.service.js';
+import type { IssueCertRequestDto } from './ca.dto.js';
+
+// ---------------------------------------------------------------------------
+// Helper to build a mock https.request that simulates step-ca
+// ---------------------------------------------------------------------------
+
+function makeHttpsMock(statusCode: number, body: unknown, errorMsg?: string): void {
+  const mockReq = {
+    write: vi.fn(),
+    end: vi.fn(),
+    on: vi.fn(),
+    setTimeout: vi.fn(),
+  };
+
+  (httpsModule.request as unknown as Mock).mockImplementation(
+    (
+      _options: unknown,
+      callback: (res: {
+        statusCode: number;
+        on: (event: string, cb: (chunk?: Buffer) => void) => void;
+      }) => void,
+    ) => {
+      const mockRes = {
+        statusCode,
+        on: (event: string, cb: (chunk?: Buffer) => void) => {
+          if (event === 'data') {
+            if (body !== undefined) {
+              cb(Buffer.from(typeof body === 'string' ? body : JSON.stringify(body)));
+            }
+          }
+          if (event === 'end') {
+            cb();
+          }
+        },
+      };
+
+      if (errorMsg) {
+        // Simulate a connection error via the req.on('error') handler
+        mockReq.on.mockImplementation((event: string, cb: (err: Error) => void) => {
+          if (event === 'error') {
+            setImmediate(() => cb(new Error(errorMsg)));
+          }
+        });
+      } else {
+        // Normal flow: call the response callback
+        setImmediate(() => callback(mockRes));
+      }
+
+      return mockReq;
+    },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('CaService', () => {
+  let service: CaService;
+
+  beforeAll(async () => {
+    // Generate a cert with the two Mosaic OIDs so that CaService.issueCert's
+    // CRIT-1 OID checks pass when mock step-ca returns it as `crt`.
+    realIssuedCertPem = await makeMosaicIssuedCert({
+      grantId: GRANT_ID,
+      subjectUserId: SUBJECT_USER_ID,
+    });
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    service = new CaService();
+  });
+
+  function makeReq(overrides: Partial<IssueCertRequestDto> = {}): IssueCertRequestDto {
+    // Use a real CSR if available; fall back to a minimal placeholder
+    const defaultCsr = realCsrPem ?? makeFakeCsr();
+    return {
+      csrPem: defaultCsr,
+      grantId: GRANT_ID,
+      subjectUserId: SUBJECT_USER_ID,
+      ttlSeconds: 300,
+      ...overrides,
+    };
+  }
+
+  function makeFakeCsr(): string {
+    // A structurally valid-looking CSR header/footer (body will fail crypto verify)
+    return `-----BEGIN CERTIFICATE REQUEST-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0000000000000000AAAA\n-----END CERTIFICATE REQUEST-----\n`;
+  }
+
+  // -------------------------------------------------------------------------
+  // Real CSR generation — runs once and populates realCsrPem
+  // -------------------------------------------------------------------------
+
+  it('generates a real P-256 CSR that passes validateCsr', async () => {
+    realCsrPem = await generateRealCsr();
+    expect(realCsrPem).toMatch(/BEGIN CERTIFICATE REQUEST/);
+
+    // Now test that the service's validateCsr accepts it.
+    // We call it indirectly via issueCert with a successful mock.
+    makeHttpsMock(200, { crt: realIssuedCertPem, certChain: [realIssuedCertPem, FAKE_CA_PEM] });
+    const result = await service.issueCert(makeReq({ csrPem: realCsrPem }));
+    expect(result.certPem).toBe(realIssuedCertPem);
+  });
+
+  it('throws INVALID_CSR for a malformed PEM-shaped CSR', async () => {
+    const malformedCsr =
+      '-----BEGIN CERTIFICATE REQUEST-----\nTm90QVJlYWxDU1I=\n-----END CERTIFICATE REQUEST-----\n';
+
+    await expect(service.issueCert(makeReq({ csrPem: malformedCsr }))).rejects.toSatisfy(
+      (err: unknown) => {
+        if (!(err instanceof CaServiceError)) return false;
+        expect(err.code).toBe('INVALID_CSR');
+        return true;
+      },
+    );
+  });
+
+  // -------------------------------------------------------------------------
+  // Happy path
+  // -------------------------------------------------------------------------
+
+  it('returns IssuedCertDto on success (certChain present)', async () => {
+    if (!realCsrPem) realCsrPem = await generateRealCsr();
+    makeHttpsMock(200, {
+      crt: realIssuedCertPem,
+      certChain: [realIssuedCertPem, FAKE_CA_PEM],
+    });
+
+    const result = await service.issueCert(makeReq());
+
+    expect(result.certPem).toBe(realIssuedCertPem);
+    expect(result.certChainPem).toContain(realIssuedCertPem);
+    expect(result.certChainPem).toContain(FAKE_CA_PEM);
+    expect(typeof result.serialNumber).toBe('string');
+  });
+
+  // -------------------------------------------------------------------------
+  // certChainPem fallback — certChain absent, ca field present
+  // -------------------------------------------------------------------------
+
+  it('builds certChainPem from crt+ca when certChain is absent', async () => {
+    if (!realCsrPem) realCsrPem = await generateRealCsr();
+    makeHttpsMock(200, {
+      crt: realIssuedCertPem,
+      ca: FAKE_CA_PEM,
+    });
+
+    const result = await service.issueCert(makeReq());
+
+    expect(result.certPem).toBe(realIssuedCertPem);
+    expect(result.certChainPem).toContain(realIssuedCertPem);
+    expect(result.certChainPem).toContain(FAKE_CA_PEM);
+  });
+
+  // -------------------------------------------------------------------------
+  // certChainPem fallback — no certChain, no ca field
+  // -------------------------------------------------------------------------
+
+  it('falls back to certPem alone when certChain and ca are absent', async () => {
+    if (!realCsrPem) realCsrPem = await generateRealCsr();
+    makeHttpsMock(200, { crt: realIssuedCertPem });
+
+    const result = await service.issueCert(makeReq());
+
+    expect(result.certPem).toBe(realIssuedCertPem);
+    expect(result.certChainPem).toBe(realIssuedCertPem);
+  });
+
+  // -------------------------------------------------------------------------
+  // HTTP 401
+  // -------------------------------------------------------------------------
+
+  it('throws CaServiceError on HTTP 401', async () => {
+    if (!realCsrPem) realCsrPem = await generateRealCsr();
+    makeHttpsMock(401, { message: 'Unauthorized' });
+
+    await expect(service.issueCert(makeReq())).rejects.toSatisfy((err: unknown) => {
+      if (!(err instanceof CaServiceError)) return false;
+      expect(err.message).toMatch(/401/);
+      expect(err.remediation).toBeTruthy();
+      return true;
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // HTTP non-401 error (e.g. 422)
+  // -------------------------------------------------------------------------
+
+  it('throws CaServiceError on HTTP 422', async () => {
+    if (!realCsrPem) realCsrPem = await generateRealCsr();
+    makeHttpsMock(422, { message: 'Unprocessable Entity' });
+
+    await expect(service.issueCert(makeReq())).rejects.toBeInstanceOf(CaServiceError);
+  });
+
+  // -------------------------------------------------------------------------
+  // Malformed CSR — throws before HTTP call
+  // -------------------------------------------------------------------------
+
+  it('throws CaServiceError for malformed CSR without making HTTP call', async () => {
+    const requestSpy = vi.spyOn(httpsModule, 'request');
+
+    await expect(service.issueCert(makeReq({ csrPem: 'not-a-valid-csr' }))).rejects.toBeInstanceOf(
+      CaServiceError,
+    );
+
+    expect(requestSpy).not.toHaveBeenCalled();
+  });
+
+  // -------------------------------------------------------------------------
+  // Non-JSON response
+  // -------------------------------------------------------------------------
+
+  it('throws CaServiceError when step-ca returns non-JSON', async () => {
+    if (!realCsrPem) realCsrPem = await generateRealCsr();
+    makeHttpsMock(200, 'this is not json');
+
+    await expect(service.issueCert(makeReq())).rejects.toSatisfy((err: unknown) => {
+      if (!(err instanceof CaServiceError)) return false;
+      expect(err.message).toMatch(/non-JSON/);
+      return true;
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // HTTPS connection error
+  // -------------------------------------------------------------------------
+
+  it('throws CaServiceError on HTTPS connection error', async () => {
+    if (!realCsrPem) realCsrPem = await generateRealCsr();
+    makeHttpsMock(0, undefined, 'connect ECONNREFUSED 127.0.0.1:9000');
+
+    await expect(service.issueCert(makeReq())).rejects.toSatisfy((err: unknown) => {
+      if (!(err instanceof CaServiceError)) return false;
+      expect(err.message).toMatch(/HTTPS connection/);
+      expect(err.cause).toBeInstanceOf(Error);
+      return true;
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // JWT custom claims: mosaic_grant_id and mosaic_subject_user_id
+  // Verified with jose.jwtVerify for real signature verification (M6)
+  // -------------------------------------------------------------------------
+
+  it('OTT contains mosaic_grant_id, mosaic_subject_user_id, and jti; signature verifies with jose', async () => {
+    if (!realCsrPem) realCsrPem = await generateRealCsr();
+
+    let capturedBody: Record<string, unknown> | undefined;
+
+    const mockReq = {
+      write: vi.fn((data: string) => {
+        capturedBody = JSON.parse(data) as Record<string, unknown>;
+      }),
+      end: vi.fn(),
+      on: vi.fn(),
+      setTimeout: vi.fn(),
+    };
+
+    (httpsModule.request as unknown as Mock).mockImplementation(
+      (
+        _options: unknown,
+        callback: (res: {
+          statusCode: number;
+          on: (event: string, cb: (chunk?: Buffer) => void) => void;
+        }) => void,
+      ) => {
+        const mockRes = {
+          statusCode: 200,
+          on: (event: string, cb: (chunk?: Buffer) => void) => {
+            if (event === 'data') {
+              cb(Buffer.from(JSON.stringify({ crt: realIssuedCertPem })));
+            }
+            if (event === 'end') {
+              cb();
+            }
+          },
+        };
+        setImmediate(() => callback(mockRes));
+        return mockReq;
+      },
+    );
+
+    await service.issueCert(makeReq({ csrPem: realCsrPem }));
+
+    expect(capturedBody).toBeDefined();
+    const ott = capturedBody!['ott'] as string;
+    expect(typeof ott).toBe('string');
+
+    // Verify JWT structure
+    const parts = ott.split('.');
+    expect(parts).toHaveLength(3);
+
+    // Decode payload without signature check first
+    const payloadJson = Buffer.from(parts[1]!, 'base64url').toString('utf8');
+    const payload = JSON.parse(payloadJson) as Record<string, unknown>;
+
+    expect(payload['mosaic_grant_id']).toBe(GRANT_ID);
+    expect(payload['mosaic_subject_user_id']).toBe(SUBJECT_USER_ID);
+    expect(typeof payload['jti']).toBe('string'); // M2: jti present
+    expect(payload['jti']).toMatch(/^[0-9a-f-]{36}$/); // UUID format
+
+    // M3: top-level sha should NOT be present; step.sha should be present
+    expect(payload['sha']).toBeUndefined();
+    const step = payload['step'] as Record<string, unknown> | undefined;
+    expect(step?.['sha']).toBeDefined();
+
+    // M6: Verify signature with jose.jwtVerify using the public key
+    const { importJWK: importJose } = await import('jose');
+    const publicKey = await importJose(TEST_EC_PUBLIC_JWK, 'ES256');
+    const verified = await jwtVerify(ott, publicKey);
+    expect(verified.payload['mosaic_grant_id']).toBe(GRANT_ID);
+  });
+
+  // -------------------------------------------------------------------------
+  // CaServiceError has cause + remediation
+  // -------------------------------------------------------------------------
+
+  it('CaServiceError carries cause and remediation', () => {
+    const cause = new Error('original error');
+    const err = new CaServiceError('something went wrong', 'fix it like this', cause);
+
+    expect(err).toBeInstanceOf(Error);
+    expect(err).toBeInstanceOf(CaServiceError);
+    expect(err.message).toBe('something went wrong');
+    expect(err.remediation).toBe('fix it like this');
+    expect(err.cause).toBe(cause);
+    expect(err.name).toBe('CaServiceError');
+  });
+
+  // -------------------------------------------------------------------------
+  // Missing crt in response
+  // -------------------------------------------------------------------------
+
+  it('throws CaServiceError when response is missing the crt field', async () => {
+    if (!realCsrPem) realCsrPem = await generateRealCsr();
+    makeHttpsMock(200, { ca: FAKE_CA_PEM });
+
+    await expect(service.issueCert(makeReq())).rejects.toSatisfy((err: unknown) => {
+      if (!(err instanceof CaServiceError)) return false;
+      expect(err.message).toMatch(/missing the "crt" field/);
+      return true;
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // M6: provisionerPassword must never appear in CaServiceError messages
+  // -------------------------------------------------------------------------
+
+  it('provisionerPassword does not appear in any CaServiceError message', async () => {
+    // Temporarily set a recognizable password to test against
+    const originalPassword = process.env['STEP_CA_PROVISIONER_PASSWORD'];
+    process.env['STEP_CA_PROVISIONER_PASSWORD'] = 'super-secret-password-12345';
+
+    // Generate a bad CSR to trigger an error path
+    const caughtErrors: CaServiceError[] = [];
+    try {
+      await service.issueCert(makeReq({ csrPem: 'not-a-csr' }));
+    } catch (err) {
+      if (err instanceof CaServiceError) {
+        caughtErrors.push(err);
+      }
+    }
+
+    // Also try HTTP 401 path
+    if (!realCsrPem) realCsrPem = await generateRealCsr();
+    makeHttpsMock(401, { message: 'Unauthorized' });
+    try {
+      await service.issueCert(makeReq({ csrPem: realCsrPem }));
+    } catch (err) {
+      if (err instanceof CaServiceError) {
+        caughtErrors.push(err);
+      }
+    }
+
+    for (const err of caughtErrors) {
+      expect(err.message).not.toContain('super-secret-password-12345');
+      if (err.remediation) {
+        expect(err.remediation).not.toContain('super-secret-password-12345');
+      }
+    }
+
+    process.env['STEP_CA_PROVISIONER_PASSWORD'] = originalPassword;
+  });
+
+  // -------------------------------------------------------------------------
+  // M7: HTTPS-only enforcement in constructor
+  // -------------------------------------------------------------------------
+
+  it('throws in constructor if STEP_CA_URL uses http://', () => {
+    const originalUrl = process.env['STEP_CA_URL'];
+    process.env['STEP_CA_URL'] = 'http://step-ca:9000';
+
+    expect(() => new CaService()).toThrow(CaServiceError);
+
+    process.env['STEP_CA_URL'] = originalUrl;
+  });
+
+  // -------------------------------------------------------------------------
+  // TTL clamp: ttlSeconds is clamped to 900 s (15 min) maximum
+  // -------------------------------------------------------------------------
+
+  it('clamps ttlSeconds to 900 s regardless of input', async () => {
+    if (!realCsrPem) realCsrPem = await generateRealCsr();
+
+    let capturedBody: Record<string, unknown> | undefined;
+
+    const mockReq = {
+      write: vi.fn((data: string) => {
+        capturedBody = JSON.parse(data) as Record<string, unknown>;
+      }),
+      end: vi.fn(),
+      on: vi.fn(),
+      setTimeout: vi.fn(),
+    };
+
+    (httpsModule.request as unknown as Mock).mockImplementation(
+      (
+        _options: unknown,
+        callback: (res: {
+          statusCode: number;
+          on: (event: string, cb: (chunk?: Buffer) => void) => void;
+        }) => void,
+      ) => {
+        const mockRes = {
+          statusCode: 200,
+          on: (event: string, cb: (chunk?: Buffer) => void) => {
+            if (event === 'data') {
+              cb(Buffer.from(JSON.stringify({ crt: realIssuedCertPem })));
+            }
+            if (event === 'end') {
+              cb();
+            }
+          },
+        };
+        setImmediate(() => callback(mockRes));
+        return mockReq;
+      },
+    );
+
+    // Request 86400 s — should be clamped to 900
+    await service.issueCert(makeReq({ ttlSeconds: 86400 }));
+
+    expect(capturedBody).toBeDefined();
+    const validity = capturedBody!['validity'] as Record<string, unknown>;
+    expect(validity['duration']).toBe('900s');
+  });
+});

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

@@ -0,0 +1,680 @@
+/**
+ * CaService — Step-CA client for federation grant certificate issuance.
+ *
+ * Responsibilities:
+ *  1. Build a JWK-provisioner One-Time Token (OTT) signed with the provisioner
+ *     private key (ES256/ES384/RS256 per JWK kty/crv) carrying Mosaic-specific
+ *     claims (`mosaic_grant_id`, `mosaic_subject_user_id`, `step.sha`) per the
+ *     step-ca JWK provisioner protocol.
+ *  2. POST the CSR + OTT to the step-ca `/1.0/sign` endpoint over HTTPS,
+ *     pinning the trust to the CA root cert supplied via env.
+ *  3. Return an IssuedCertDto containing the leaf cert, full chain, and
+ *     serial number.
+ *
+ * Environment variables (all required at runtime — validated in constructor):
+ *   STEP_CA_URL                   https://step-ca:9000
+ *   STEP_CA_PROVISIONER_KEY_JSON  JWK provisioner private key (JSON)
+ *   STEP_CA_ROOT_CERT_PATH        Absolute path to the CA root PEM
+ *
+ * Optional (only used for JWK PBES2 decrypt at startup if key is encrypted):
+ *   STEP_CA_PROVISIONER_PASSWORD  JWK provisioner password (raw string)
+ *
+ * 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
+ *
+ * Fail-loud contract:
+ *   Every error path throws CaServiceError with a human-readable `remediation`
+ *   field. Silent OID-stripping is NEVER allowed — if the sign response does
+ *   not include the cert, we throw rather than return a cert that may be
+ *   missing the custom extensions.
+ */
+
+import { Injectable, Logger } from '@nestjs/common';
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as https from 'node:https';
+import { SignJWT, importJWK } from 'jose';
+import { Pkcs10CertificateRequest, X509Certificate } from '@peculiar/x509';
+import type { IssueCertRequestDto } from './ca.dto.js';
+import { IssuedCertDto } from './ca.dto.js';
+
+// ---------------------------------------------------------------------------
+// Custom error class
+// ---------------------------------------------------------------------------
+
+export class CaServiceError extends Error {
+  readonly cause: unknown;
+  readonly remediation: string;
+  readonly code?: string;
+
+  constructor(message: string, remediation: string, cause?: unknown, code?: string) {
+    super(message);
+    this.name = 'CaServiceError';
+    this.cause = cause;
+    this.remediation = remediation;
+    this.code = code;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal types
+// ---------------------------------------------------------------------------
+
+interface StepSignResponse {
+  crt: string;
+  ca?: string;
+  certChain?: string[];
+}
+
+interface JwkKey {
+  kty: string;
+  kid?: string;
+  use?: string;
+  alg?: string;
+  k?: string; // symmetric
+  n?: string; // RSA
+  e?: string;
+  d?: string;
+  x?: string; // EC
+  y?: string;
+  crv?: string;
+  [key: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** UUID regex for validation */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Derive the JWT algorithm string from a JWK's kty/crv fields.
+ * EC P-256 → ES256, EC P-384 → ES384, RSA → RS256.
+ */
+function algFromJwk(jwk: JwkKey): string {
+  if (jwk.alg) return jwk.alg;
+  if (jwk.kty === 'EC') {
+    if (jwk.crv === 'P-384') return 'ES384';
+    return 'ES256'; // default for P-256 and Ed25519-style EC keys
+  }
+  if (jwk.kty === 'RSA') return 'RS256';
+  throw new CaServiceError(
+    `Unsupported JWK kty: ${jwk.kty}`,
+    'STEP_CA_PROVISIONER_KEY_JSON must be an EC (P-256/P-384) or RSA JWK private key.',
+  );
+}
+
+/**
+ * Compute SHA-256 fingerprint of the DER-encoded CSR body.
+ * step-ca uses this as the `step.sha` claim to bind the OTT to a specific CSR.
+ */
+function csrFingerprint(csrPem: string): string {
+  // Strip PEM headers and decode base64 body
+  const b64 = csrPem
+    .replace(/-----BEGIN CERTIFICATE REQUEST-----/, '')
+    .replace(/-----END CERTIFICATE REQUEST-----/, '')
+    .replace(/\s+/g, '');
+
+  let derBuf: Buffer;
+  try {
+    derBuf = Buffer.from(b64, 'base64');
+  } catch (err) {
+    throw new CaServiceError(
+      'Failed to base64-decode the CSR PEM body',
+      'Verify that csrPem is a valid PKCS#10 PEM-encoded certificate request.',
+      err,
+    );
+  }
+
+  if (derBuf.length === 0) {
+    throw new CaServiceError(
+      'CSR PEM decoded to empty buffer — malformed input',
+      'Provide a valid non-empty PKCS#10 PEM-encoded certificate request.',
+    );
+  }
+
+  return crypto.createHash('sha256').update(derBuf).digest('hex');
+}
+
+/**
+ * Send a JSON POST to the step-ca sign endpoint.
+ * Returns the parsed response body or throws CaServiceError.
+ */
+function httpsPost(url: string, body: unknown, agent: https.Agent): Promise<StepSignResponse> {
+  return new Promise((resolve, reject) => {
+    const bodyStr = JSON.stringify(body);
+    const parsed = new URL(url);
+
+    const options: https.RequestOptions = {
+      hostname: parsed.hostname,
+      port: parsed.port ? parseInt(parsed.port, 10) : 443,
+      path: parsed.pathname,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(bodyStr),
+      },
+      agent,
+      timeout: 5000,
+    };
+
+    const req = https.request(options, (res) => {
+      const chunks: Buffer[] = [];
+      res.on('data', (chunk: Buffer) => chunks.push(chunk));
+      res.on('end', () => {
+        const raw = Buffer.concat(chunks).toString('utf8');
+
+        if (res.statusCode === 401) {
+          reject(
+            new CaServiceError(
+              `step-ca returned HTTP 401 — invalid or expired OTT`,
+              'Check STEP_CA_PROVISIONER_KEY_JSON. Ensure the mosaic-fed provisioner is configured in the CA.',
+            ),
+          );
+          return;
+        }
+
+        if (res.statusCode && res.statusCode >= 400) {
+          reject(
+            new CaServiceError(
+              `step-ca returned HTTP ${res.statusCode}: ${raw.slice(0, 256)}`,
+              `Review the step-ca logs. Status ${res.statusCode} may indicate a CSR policy violation or misconfigured provisioner.`,
+            ),
+          );
+          return;
+        }
+
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(raw) as unknown;
+        } catch (err) {
+          reject(
+            new CaServiceError(
+              'step-ca returned a non-JSON response',
+              'Verify STEP_CA_URL points to a running step-ca instance and that TLS is properly configured.',
+              err,
+            ),
+          );
+          return;
+        }
+
+        resolve(parsed as StepSignResponse);
+      });
+    });
+
+    req.setTimeout(5000, () => {
+      req.destroy(new Error('Request timed out after 5000ms'));
+    });
+
+    req.on('error', (err: Error) => {
+      reject(
+        new CaServiceError(
+          `HTTPS connection to step-ca failed: ${err.message}`,
+          'Ensure STEP_CA_URL is reachable and STEP_CA_ROOT_CERT_PATH points to the correct CA root certificate.',
+          err,
+        ),
+      );
+    });
+
+    req.write(bodyStr);
+    req.end();
+  });
+}
+
+/**
+ * Extract a decimal serial number from a PEM certificate.
+ * Throws CaServiceError on failure — never silently returns 'unknown'.
+ */
+function extractSerial(certPem: string): string {
+  let cert: crypto.X509Certificate;
+  try {
+    cert = new crypto.X509Certificate(certPem);
+  } catch (err) {
+    throw new CaServiceError(
+      'Failed to parse the issued certificate PEM',
+      'The certificate returned by step-ca could not be parsed. Check that step-ca is returning a valid PEM certificate.',
+      err,
+      'CERT_PARSE',
+    );
+  }
+  return cert.serialNumber;
+}
+
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+
+@Injectable()
+export class CaService {
+  private readonly logger = new Logger(CaService.name);
+
+  private readonly caUrl: string;
+  private readonly rootCertPath: string;
+  private readonly httpsAgent: https.Agent;
+  private readonly jwk: JwkKey;
+  private cachedPrivateKey: crypto.KeyObject | null = null;
+  private readonly jwtAlg: string;
+  private readonly kid: string;
+
+  constructor() {
+    const caUrl = process.env['STEP_CA_URL'];
+    const provisionerKeyJson = process.env['STEP_CA_PROVISIONER_KEY_JSON'];
+    const rootCertPath = process.env['STEP_CA_ROOT_CERT_PATH'];
+
+    if (!caUrl) {
+      throw new CaServiceError(
+        'STEP_CA_URL is not set',
+        'Set STEP_CA_URL to the base URL of the step-ca instance, e.g. https://step-ca:9000',
+      );
+    }
+
+    // Enforce HTTPS-only URL
+    let parsedUrl: URL;
+    try {
+      parsedUrl = new URL(caUrl);
+    } catch (err) {
+      throw new CaServiceError(
+        `STEP_CA_URL is not a valid URL: ${caUrl}`,
+        'Set STEP_CA_URL to a valid HTTPS URL, e.g. https://step-ca:9000',
+        err,
+      );
+    }
+    if (parsedUrl.protocol !== 'https:') {
+      throw new CaServiceError(
+        `STEP_CA_URL must use HTTPS — got: ${parsedUrl.protocol}`,
+        'Set STEP_CA_URL to an https:// URL. Unencrypted connections to the CA are not permitted.',
+      );
+    }
+
+    if (!provisionerKeyJson) {
+      throw new CaServiceError(
+        'STEP_CA_PROVISIONER_KEY_JSON is not set',
+        'Set STEP_CA_PROVISIONER_KEY_JSON to the JSON-encoded JWK for the mosaic-fed provisioner.',
+      );
+    }
+    if (!rootCertPath) {
+      throw new CaServiceError(
+        'STEP_CA_ROOT_CERT_PATH is not set',
+        'Set STEP_CA_ROOT_CERT_PATH to the absolute path of the step-ca root CA certificate PEM file.',
+      );
+    }
+
+    // Parse JWK once — do NOT store the raw JSON string as a class field
+    let jwk: JwkKey;
+    try {
+      jwk = JSON.parse(provisionerKeyJson) as JwkKey;
+    } catch (err) {
+      throw new CaServiceError(
+        'STEP_CA_PROVISIONER_KEY_JSON is not valid JSON',
+        'Set STEP_CA_PROVISIONER_KEY_JSON to the JSON-serialised JWK object for the mosaic-fed provisioner.',
+        err,
+      );
+    }
+
+    // Derive algorithm from JWK metadata
+    const jwtAlg = algFromJwk(jwk);
+    const kid = jwk.kid ?? 'mosaic-fed';
+
+    // Import the JWK into a native KeyObject — fail loudly if it cannot be loaded.
+    // We do this synchronously here by calling the async importJWK via a blocking workaround.
+    // Actually importJWK is async, so we store it for use during token building.
+    // We keep the raw jwk object for later async import inside buildOtt.
+    // NOTE: We do NOT store provisionerKeyJson string as a class field.
+    this.jwk = jwk;
+    this.jwtAlg = jwtAlg;
+    this.kid = kid;
+
+    this.caUrl = caUrl;
+    this.rootCertPath = rootCertPath;
+
+    // Read the root cert and pin it for all HTTPS connections.
+    let rootCert: string;
+    try {
+      rootCert = fs.readFileSync(this.rootCertPath, 'utf8');
+    } catch (err) {
+      throw new CaServiceError(
+        `Cannot read STEP_CA_ROOT_CERT_PATH: ${rootCertPath}`,
+        'Ensure the file exists and is readable by the gateway process.',
+        err,
+      );
+    }
+
+    this.httpsAgent = new https.Agent({
+      ca: rootCert,
+      rejectUnauthorized: true,
+    });
+
+    this.logger.log(`CaService initialised — CA URL: ${this.caUrl}`);
+  }
+
+  /**
+   * Lazily import the private key from JWK on first use.
+   * The key is cached in cachedPrivateKey after first import.
+   */
+  private async getPrivateKey(): Promise<crypto.KeyObject> {
+    if (this.cachedPrivateKey !== null) return this.cachedPrivateKey;
+    try {
+      const key = await importJWK(this.jwk, this.jwtAlg);
+      // importJWK returns KeyLike (crypto.KeyObject | Uint8Array) — in Node.js it's KeyObject
+      this.cachedPrivateKey = key as unknown as crypto.KeyObject;
+      return this.cachedPrivateKey;
+    } catch (err) {
+      throw new CaServiceError(
+        'Failed to import STEP_CA_PROVISIONER_KEY_JSON as a cryptographic key',
+        'Ensure STEP_CA_PROVISIONER_KEY_JSON contains a valid JWK private key (EC P-256/P-384 or RSA).',
+        err,
+      );
+    }
+  }
+
+  /**
+   * Build the JWK-provisioner OTT signed with the provisioner private key.
+   * Algorithm is derived from the JWK kty/crv fields.
+   */
+  private async buildOtt(params: {
+    csrPem: string;
+    grantId: string;
+    subjectUserId: string;
+    ttlSeconds: number;
+    csrCn: string;
+  }): Promise<string> {
+    const { csrPem, grantId, subjectUserId, ttlSeconds, csrCn } = params;
+
+    // Validate UUID shape for grant id and subject user id
+    if (!UUID_RE.test(grantId)) {
+      throw new CaServiceError(
+        `grantId is not a valid UUID: ${grantId}`,
+        'Provide a valid UUID (RFC 4122) for grantId.',
+        undefined,
+        'INVALID_GRANT_ID',
+      );
+    }
+    if (!UUID_RE.test(subjectUserId)) {
+      throw new CaServiceError(
+        `subjectUserId is not a valid UUID: ${subjectUserId}`,
+        'Provide a valid UUID (RFC 4122) for subjectUserId.',
+        undefined,
+        'INVALID_GRANT_ID',
+      );
+    }
+
+    const sha = csrFingerprint(csrPem);
+    const now = Math.floor(Date.now() / 1000);
+    const privateKey = await this.getPrivateKey();
+
+    const ott = await new SignJWT({
+      iss: this.kid,
+      sub: csrCn, // M1: set sub to identity from CSR CN
+      aud: [`${this.caUrl}/1.0/sign`],
+      iat: now,
+      nbf: now - 30, // 30 s clock-skew tolerance
+      exp: now + Math.min(ttlSeconds, 3600), // OTT validity ≤ 1 h
+      jti: crypto.randomUUID(), // M2: unique token ID
+      // step.sha is the canonical field name used in the template — M3: keep only step.sha
+      step: { sha },
+      // Mosaic custom claims consumed by federation.tpl
+      mosaic_grant_id: grantId,
+      mosaic_subject_user_id: subjectUserId,
+    })
+      .setProtectedHeader({ alg: this.jwtAlg, typ: 'JWT', kid: this.kid })
+      .sign(privateKey);
+
+    return ott;
+  }
+
+  /**
+   * Validate a PEM-encoded CSR using @peculiar/x509.
+   * Verifies the self-signature, key type/size, and signature algorithm.
+   * Optionally verifies that the CSR's SANs match the expected set.
+   *
+   * Throws CaServiceError with code 'INVALID_CSR' on failure.
+   */
+  private async validateCsr(pem: string, expectedSans?: string[]): Promise<string> {
+    let csr: Pkcs10CertificateRequest;
+    try {
+      csr = new Pkcs10CertificateRequest(pem);
+    } catch (err) {
+      throw new CaServiceError(
+        'Failed to parse CSR PEM as a valid PKCS#10 certificate request',
+        'Provide a valid PEM-encoded PKCS#10 CSR.',
+        err,
+        'INVALID_CSR',
+      );
+    }
+
+    // Verify self-signature
+    let valid: boolean;
+    try {
+      valid = await csr.verify();
+    } catch (err) {
+      throw new CaServiceError(
+        'CSR signature verification threw an error',
+        'The CSR self-signature could not be verified. Ensure the CSR is properly formed.',
+        err,
+        'INVALID_CSR',
+      );
+    }
+    if (!valid) {
+      throw new CaServiceError(
+        'CSR self-signature is invalid',
+        'The CSR must be self-signed with the corresponding private key.',
+        undefined,
+        'INVALID_CSR',
+      );
+    }
+
+    // Validate signature algorithm — reject MD5 and SHA-1
+    // signatureAlgorithm is HashedAlgorithm which extends Algorithm.
+    // Cast through unknown to access .name and .hash.name without DOM lib globals.
+    const sigAlgAny = csr.signatureAlgorithm as unknown as {
+      name?: string;
+      hash?: { name?: string };
+    };
+    const sigAlgName = (sigAlgAny.name ?? '').toLowerCase();
+    const hashName = (sigAlgAny.hash?.name ?? '').toLowerCase();
+    if (
+      sigAlgName.includes('md5') ||
+      sigAlgName.includes('sha1') ||
+      hashName === 'sha-1' ||
+      hashName === 'sha1'
+    ) {
+      throw new CaServiceError(
+        `CSR uses a forbidden signature algorithm: ${sigAlgAny.name ?? 'unknown'}`,
+        'Use SHA-256 or stronger. MD5 and SHA-1 are not permitted.',
+        undefined,
+        'INVALID_CSR',
+      );
+    }
+
+    // Validate public key algorithm and strength via the algorithm descriptor on the key.
+    // csr.publicKey.algorithm is type Algorithm (WebCrypto) — use name-based checks.
+    // We cast to an extended interface to access curve/modulus info without DOM globals.
+    const pubKeyAlgo = csr.publicKey.algorithm as {
+      name: string;
+      namedCurve?: string;
+      modulusLength?: number;
+    };
+    const keyAlgoName = pubKeyAlgo.name;
+
+    if (keyAlgoName === 'RSASSA-PKCS1-v1_5' || keyAlgoName === 'RSA-PSS') {
+      const modulusLength = pubKeyAlgo.modulusLength ?? 0;
+      if (modulusLength < 2048) {
+        throw new CaServiceError(
+          `CSR RSA key is too short: ${modulusLength} bits (minimum 2048)`,
+          'Use an RSA key of at least 2048 bits.',
+          undefined,
+          'INVALID_CSR',
+        );
+      }
+    } else if (keyAlgoName === 'ECDSA') {
+      const namedCurve = pubKeyAlgo.namedCurve ?? '';
+      const allowedCurves = new Set(['P-256', 'P-384']);
+      if (!allowedCurves.has(namedCurve)) {
+        throw new CaServiceError(
+          `CSR EC key uses disallowed curve: ${namedCurve}`,
+          'Use EC P-256 or P-384. Other curves are not permitted.',
+          undefined,
+          'INVALID_CSR',
+        );
+      }
+    } else if (keyAlgoName === 'Ed25519') {
+      // Ed25519 is explicitly allowed
+    } else {
+      throw new CaServiceError(
+        `CSR uses unsupported key algorithm: ${keyAlgoName}`,
+        'Use EC (P-256/P-384), Ed25519, or RSA (≥2048 bit) keys.',
+        undefined,
+        'INVALID_CSR',
+      );
+    }
+
+    // Extract SANs if expectedSans provided
+    if (expectedSans && expectedSans.length > 0) {
+      // Get SANs from CSR extensions
+      const sanExtension = csr.extensions?.find(
+        (ext) => ext.type === '2.5.29.17', // Subject Alternative Name OID
+      );
+      const csrSans: string[] = [];
+      if (sanExtension) {
+        // Parse the raw SAN extension — store as stringified for comparison
+        // @peculiar/x509 exposes SANs through the parsed extension
+        const sanExt = sanExtension as { names?: Array<{ type: string; value: string }> };
+        if (sanExt.names) {
+          for (const name of sanExt.names) {
+            csrSans.push(name.value);
+          }
+        }
+      }
+
+      const csrSanSet = new Set(csrSans);
+      const expectedSanSet = new Set(expectedSans);
+      const missing = expectedSans.filter((s) => !csrSanSet.has(s));
+      const extra = csrSans.filter((s) => !expectedSanSet.has(s));
+
+      if (missing.length > 0 || extra.length > 0) {
+        throw new CaServiceError(
+          `CSR SANs do not match expected set. Missing: [${missing.join(', ')}], Extra: [${extra.join(', ')}]`,
+          'The CSR must include exactly the SANs specified in the issuance request.',
+          undefined,
+          'INVALID_CSR',
+        );
+      }
+    }
+
+    // Return the CN from the CSR subject for use as JWT sub
+    const cn = csr.subjectName.getField('CN')?.[0] ?? '';
+    return cn;
+  }
+
+  /**
+   * Submit a CSR to step-ca and return the issued certificate.
+   *
+   * Throws `CaServiceError` on any failure (network, auth, malformed input).
+   * Never silently swallows errors — fail-loud is a hard contract per M2-02 review.
+   */
+  async issueCert(req: IssueCertRequestDto): Promise<IssuedCertDto> {
+    // Clamp TTL to 15-minute maximum (H2)
+    const ttl = Math.min(req.ttlSeconds ?? 300, 900);
+
+    this.logger.debug(
+      `issueCert — grantId=${req.grantId} subjectUserId=${req.subjectUserId} ttl=${ttl}s`,
+    );
+
+    // Validate CSR — real cryptographic validation (H3)
+    const csrCn = await this.validateCsr(req.csrPem);
+
+    const ott = await this.buildOtt({
+      csrPem: req.csrPem,
+      grantId: req.grantId,
+      subjectUserId: req.subjectUserId,
+      ttlSeconds: ttl,
+      csrCn,
+    });
+
+    const signUrl = `${this.caUrl}/1.0/sign`;
+    const requestBody = {
+      csr: req.csrPem,
+      ott,
+      validity: {
+        duration: `${ttl}s`,
+      },
+    };
+
+    this.logger.debug(`Posting CSR to ${signUrl}`);
+    const response = await httpsPost(signUrl, requestBody, this.httpsAgent);
+
+    if (!response.crt) {
+      throw new CaServiceError(
+        'step-ca sign response missing the "crt" field',
+        'This is unexpected — the step-ca instance may be misconfigured or running an incompatible version.',
+      );
+    }
+
+    // Build certChainPem: prefer certChain array, fall back to ca field, fall back to crt alone.
+    let certChainPem: string;
+    if (response.certChain && response.certChain.length > 0) {
+      certChainPem = response.certChain.join('\n');
+    } else if (response.ca) {
+      certChainPem = response.crt + '\n' + response.ca;
+    } else {
+      certChainPem = response.crt;
+    }
+
+    const serialNumber = extractSerial(response.crt);
+
+    // CRIT-1: Verify the issued certificate contains both Mosaic OID extensions
+    // with the correct values. Step-CA's federation.tpl encodes each as an ASN.1
+    // UTF8String TLV: tag 0x0C + 1-byte length + UUID bytes. We skip 2 bytes
+    // (tag + length) to extract the raw UUID string.
+    const issuedCert = new X509Certificate(response.crt);
+    const decoder = new TextDecoder();
+
+    const grantIdExt = issuedCert.getExtension('1.3.6.1.4.1.99999.1');
+    if (!grantIdExt) {
+      throw new CaServiceError(
+        'Issued certificate is missing required Mosaic OID: mosaic_grant_id',
+        'The Step-CA federation.tpl template did not embed OID 1.3.6.1.4.1.99999.1. Check the provisioner template configuration.',
+        undefined,
+        'OID_MISSING',
+      );
+    }
+    const grantIdInCert = decoder.decode(grantIdExt.value.slice(2));
+    if (grantIdInCert !== req.grantId) {
+      throw new CaServiceError(
+        `Issued certificate mosaic_grant_id mismatch: expected ${req.grantId}, got ${grantIdInCert}`,
+        'The Step-CA issued a certificate with a different grant ID than requested. This may indicate a provisioner misconfiguration or a MITM.',
+        undefined,
+        'OID_MISMATCH',
+      );
+    }
+
+    const subjectUserIdExt = issuedCert.getExtension('1.3.6.1.4.1.99999.2');
+    if (!subjectUserIdExt) {
+      throw new CaServiceError(
+        'Issued certificate is missing required Mosaic OID: mosaic_subject_user_id',
+        'The Step-CA federation.tpl template did not embed OID 1.3.6.1.4.1.99999.2. Check the provisioner template configuration.',
+        undefined,
+        'OID_MISSING',
+      );
+    }
+    const subjectUserIdInCert = decoder.decode(subjectUserIdExt.value.slice(2));
+    if (subjectUserIdInCert !== req.subjectUserId) {
+      throw new CaServiceError(
+        `Issued certificate mosaic_subject_user_id mismatch: expected ${req.subjectUserId}, got ${subjectUserIdInCert}`,
+        'The Step-CA issued a certificate with a different subject user ID than requested. This may indicate a provisioner misconfiguration or a MITM.',
+        undefined,
+        'OID_MISMATCH',
+      );
+    }
+
+    this.logger.log(`Certificate issued — serial=${serialNumber} grantId=${req.grantId}`);
+
+    const result = new IssuedCertDto();
+    result.certPem = response.crt;
+    result.certChainPem = certChainPem;
+    result.serialNumber = serialNumber;
+    return result;
+  }
+}

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);
+    });
+  });
+});

apps/gateway/src/federation/client/__tests__/query-source.service.spec.ts

@@ -0,0 +1,255 @@
+import 'reflect-metadata';
+import { describe, expect, it, vi } from 'vitest';
+import type { Db } from '@mosaicstack/db';
+import type { FederationListResponse } from '@mosaicstack/types';
+import {
+  FederationClientError,
+  type FederationClientService,
+} from '../federation-client.service.js';
+import { type QuerySourceError, QuerySourceService } from '../query-source.service.js';
+
+interface TestRow {
+  id: string;
+  title: string;
+}
+
+interface PeerRow {
+  id: string;
+  commonName: string;
+  endpointUrl: string | null;
+  clientKeyPem: string | null;
+  state: 'active' | 'pending' | 'suspended' | 'revoked';
+}
+
+const LOCAL_ROWS: TestRow[] = [
+  { id: 'local-1', title: 'Local One' },
+  { id: 'local-2', title: 'Local Two' },
+];
+
+const PEER_A: PeerRow = {
+  id: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
+  commonName: 'peer-a',
+  endpointUrl: 'https://peer-a.example.com',
+  clientKeyPem: 'sealed-key-a',
+  state: 'active',
+};
+
+const PEER_B: PeerRow = {
+  id: 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb',
+  commonName: 'peer-b',
+  endpointUrl: 'https://peer-b.example.com',
+  clientKeyPem: 'sealed-key-b',
+  state: 'active',
+};
+
+const PEER_LOCALHOST: PeerRow = {
+  id: 'cccccccc-cccc-cccc-cccc-cccccccccccc',
+  commonName: 'peer-localhost',
+  endpointUrl: 'https://localhost:3001',
+  clientKeyPem: 'sealed-key-c',
+  state: 'active',
+};
+
+function makeDb(activePeers: PeerRow[]): Db {
+  const orderBy = vi.fn().mockResolvedValue(activePeers);
+  const where = vi.fn().mockReturnValue({ orderBy });
+  const from = vi.fn().mockReturnValue({ where });
+  const select = vi.fn().mockReturnValue({ from });
+
+  return {
+    select,
+    insert: vi.fn(),
+    update: vi.fn(),
+    delete: vi.fn(),
+    transaction: vi.fn(),
+  } as unknown as Db;
+}
+
+function makeFederationClient(
+  list: (
+    peerId: string,
+    resource: string,
+    request: Record<string, unknown>,
+  ) => Promise<FederationListResponse<TestRow>>,
+): FederationClientService {
+  return {
+    list: list as unknown as FederationClientService['list'],
+  } as FederationClientService;
+}
+
+function makeLocalResponse(rows: TestRow[] = LOCAL_ROWS): Promise<FederationListResponse<TestRow>> {
+  return Promise.resolve({ items: rows });
+}
+
+describe('QuerySourceService', () => {
+  it('routes source="local" to the local executor and tags rows as local', async () => {
+    const list = vi.fn(async (): Promise<FederationListResponse<TestRow>> => ({ items: [] }));
+    const service = new QuerySourceService(makeDb([PEER_A]), makeFederationClient(list));
+
+    const result = await service.list<TestRow>({
+      source: 'local',
+      resource: 'tasks',
+      request: { cursor: 'ignored-for-local-test' },
+      local: () => makeLocalResponse(),
+    });
+
+    expect(result).toEqual({
+      items: [
+        { id: 'local-1', title: 'Local One', _source: 'local' },
+        { id: 'local-2', title: 'Local Two', _source: 'local' },
+      ],
+    });
+    expect(list).not.toHaveBeenCalled();
+  });
+
+  it('routes source="federated:<host>" to the matching active peer and tags rows with peer commonName', async () => {
+    const list = vi.fn(
+      async (): Promise<FederationListResponse<TestRow>> => ({
+        items: [{ id: 'remote-1', title: 'Remote One' }],
+      }),
+    );
+    const service = new QuerySourceService(makeDb([PEER_A, PEER_B]), makeFederationClient(list));
+
+    const result = await service.list<TestRow>({
+      source: 'federated:peer-b.example.com',
+      resource: 'tasks',
+      request: { status: 'open' },
+      local: () => makeLocalResponse(),
+    });
+
+    expect(result).toEqual({
+      items: [{ id: 'remote-1', title: 'Remote One', _source: 'peer-b' }],
+    });
+    expect(list).toHaveBeenCalledWith(PEER_B.id, 'tasks', { status: 'open' });
+  });
+
+  it('matches federated hosts by endpoint host including non-default port', async () => {
+    const list = vi.fn(
+      async (): Promise<FederationListResponse<TestRow>> => ({
+        items: [{ id: 'remote-port', title: 'Remote Port' }],
+      }),
+    );
+    const service = new QuerySourceService(makeDb([PEER_LOCALHOST]), makeFederationClient(list));
+
+    const result = await service.list<TestRow>({
+      source: 'federated:localhost:3001',
+      resource: 'tasks',
+      request: {},
+      local: () => makeLocalResponse(),
+    });
+
+    expect(result).toEqual({
+      items: [{ id: 'remote-port', title: 'Remote Port', _source: 'peer-localhost' }],
+    });
+    expect(list).toHaveBeenCalledWith(PEER_LOCALHOST.id, 'tasks', {});
+  });
+
+  it('fans out source="all" to local plus every active outbound peer in parallel and merges tagged rows', async () => {
+    const callOrder: string[] = [];
+    const list = vi.fn(async (peerId: string): Promise<FederationListResponse<TestRow>> => {
+      callOrder.push(`remote-start:${peerId}`);
+      await Promise.resolve();
+      return {
+        items: [{ id: `remote-${peerId.slice(0, 1)}`, title: `Remote ${peerId.slice(0, 1)}` }],
+      };
+    });
+    const service = new QuerySourceService(makeDb([PEER_A, PEER_B]), makeFederationClient(list));
+
+    const result = await service.list<TestRow>({
+      source: 'all',
+      resource: 'tasks',
+      request: { limit: 25 },
+      local: async () => {
+        callOrder.push('local-start');
+        await Promise.resolve();
+        return { items: [{ id: 'local-1', title: 'Local One' }] };
+      },
+    });
+
+    expect(result).toEqual({
+      items: [
+        { id: 'local-1', title: 'Local One', _source: 'local' },
+        { id: 'remote-a', title: 'Remote a', _source: 'peer-a' },
+        { id: 'remote-b', title: 'Remote b', _source: 'peer-b' },
+      ],
+    });
+    expect(list).toHaveBeenCalledTimes(2);
+    expect(callOrder).toEqual([
+      'local-start',
+      `remote-start:${PEER_A.id}`,
+      `remote-start:${PEER_B.id}`,
+    ]);
+  });
+
+  it('marks source="all" as partial and truncated when any subquery returns a cursor', async () => {
+    const list = vi.fn(
+      async (): Promise<FederationListResponse<TestRow>> => ({
+        items: [{ id: 'remote-a', title: 'Remote A' }],
+        nextCursor: 'remote-next',
+      }),
+    );
+    const service = new QuerySourceService(makeDb([PEER_A]), makeFederationClient(list));
+
+    const result = await service.list<TestRow>({
+      source: 'all',
+      resource: 'tasks',
+      request: {},
+      local: () => makeLocalResponse([{ id: 'local-1', title: 'Local One' }]),
+    });
+
+    expect(result).toEqual({
+      items: [
+        { id: 'local-1', title: 'Local One', _source: 'local' },
+        { id: 'remote-a', title: 'Remote A', _source: 'peer-a' },
+      ],
+      _partial: true,
+      _truncated: true,
+    });
+  });
+
+  it('returns _partial=true for source="all" when one peer fails without dropping successful sources', async () => {
+    const list = vi.fn(async (peerId: string): Promise<FederationListResponse<TestRow>> => {
+      if (peerId === PEER_B.id) {
+        throw new FederationClientError({
+          code: 'NETWORK',
+          message: 'peer unavailable',
+          peerId,
+        });
+      }
+      return { items: [{ id: 'remote-a', title: 'Remote A' }] };
+    });
+    const service = new QuerySourceService(makeDb([PEER_A, PEER_B]), makeFederationClient(list));
+
+    const result = await service.list<TestRow>({
+      source: 'all',
+      resource: 'tasks',
+      request: {},
+      local: () => makeLocalResponse([{ id: 'local-1', title: 'Local One' }]),
+    });
+
+    expect(result).toEqual({
+      items: [
+        { id: 'local-1', title: 'Local One', _source: 'local' },
+        { id: 'remote-a', title: 'Remote A', _source: 'peer-a' },
+      ],
+      _partial: true,
+    });
+  });
+
+  it('throws QuerySourceError when a federated host does not match an active outbound peer', async () => {
+    const list = vi.fn(async (): Promise<FederationListResponse<TestRow>> => ({ items: [] }));
+    const service = new QuerySourceService(makeDb([PEER_A]), makeFederationClient(list));
+
+    await expect(
+      service.list<TestRow>({
+        source: 'federated:missing.example.com',
+        resource: 'tasks',
+        request: {},
+        local: () => makeLocalResponse(),
+      }),
+    ).rejects.toMatchObject({
+      name: 'QuerySourceError',
+      code: 'PEER_NOT_FOUND',
+    } satisfies Partial<QuerySourceError>);
+  });
+});

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;
+  }
+}

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

@@ -0,0 +1,23 @@
+/**
+ * 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';
+export {
+  QuerySourceService,
+  QuerySourceError,
+  type QuerySource,
+  type QuerySourceErrorCode,
+  type QuerySourceErrorOptions,
+  type QuerySourceListOptions,
+  type QuerySourceListResponse,
+  type LocalListExecutor,
+} from './query-source.service.js';

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

@@ -0,0 +1,261 @@
+/**
+ * QuerySourceService — gateway query source router (FED-M3-09).
+ *
+ * Accepts the federation query-layer `source` selector and routes list-style
+ * reads to local storage, one federated peer, or all active outbound peers.
+ *
+ * `source: "all"` is intentionally tolerant of per-peer failures: local data
+ * and successful peer responses are returned, and the envelope is marked
+ * `_partial: true`.  Local failures still reject because there is no safe local
+ * fallback and the gateway's own storage is expected to be authoritative.
+ */
+
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import { and, eq, federationPeers, isNotNull, type Db } from '@mosaicstack/db';
+import {
+  SOURCE_LOCAL,
+  tagWithSource,
+  type FederationListResponse,
+  type SourceTag,
+} from '@mosaicstack/types';
+import { DB } from '../../database/database.module.js';
+import { FederationClientService } from './federation-client.service.js';
+
+export type QuerySource = 'local' | 'all' | `federated:${string}`;
+
+export type QuerySourceErrorCode = 'INVALID_SOURCE' | 'PEER_NOT_FOUND';
+
+export interface QuerySourceErrorOptions {
+  code: QuerySourceErrorCode;
+  message: string;
+  source: string;
+}
+
+export class QuerySourceError extends Error {
+  readonly code: QuerySourceErrorCode;
+  readonly source: string;
+
+  constructor(opts: QuerySourceErrorOptions) {
+    super(opts.message);
+    this.name = 'QuerySourceError';
+    this.code = opts.code;
+    this.source = opts.source;
+  }
+}
+
+export type LocalListExecutor<T extends object> = () => Promise<FederationListResponse<T> | T[]>;
+
+export interface QuerySourceListOptions<T extends object> {
+  source: QuerySource;
+  resource: string;
+  request?: Record<string, unknown>;
+  local: LocalListExecutor<T>;
+}
+
+export type QuerySourceListResponse<T extends object> = FederationListResponse<T & SourceTag>;
+
+interface OutboundPeer {
+  id: string;
+  commonName: string;
+  endpointUrl: string;
+}
+
+interface TaggedList<T extends object> {
+  items: Array<T & SourceTag>;
+  partial: boolean;
+  truncated: boolean;
+  nextCursor?: string;
+}
+
+@Injectable()
+export class QuerySourceService {
+  private readonly logger = new Logger(QuerySourceService.name);
+
+  constructor(
+    @Inject(DB) private readonly db: Db,
+    @Inject(FederationClientService) private readonly federationClient: FederationClientService,
+  ) {}
+
+  async list<T extends object>(
+    options: QuerySourceListOptions<T>,
+  ): Promise<QuerySourceListResponse<T>> {
+    const request = options.request ?? {};
+
+    if (options.source === 'local') {
+      const local = await this.runLocal(options.local);
+      return this.toResponse(this.tagList(local, SOURCE_LOCAL));
+    }
+
+    if (options.source === 'all') {
+      return this.listAll(options.resource, request, options.local);
+    }
+
+    if (options.source.startsWith('federated:')) {
+      const host = options.source.slice('federated:'.length).trim();
+      if (!host) {
+        throw new QuerySourceError({
+          code: 'INVALID_SOURCE',
+          message: 'Federated source must include a host after federated:',
+          source: options.source,
+        });
+      }
+
+      const peer = await this.findPeerByHost(host, options.source);
+      const remote = await this.federationClient.list<T>(peer.id, options.resource, request);
+      return this.toResponse(this.tagList(remote, peer.commonName));
+    }
+
+    throw new QuerySourceError({
+      code: 'INVALID_SOURCE',
+      message: `Unsupported query source: ${options.source}`,
+      source: options.source,
+    });
+  }
+
+  private async listAll<T extends object>(
+    resource: string,
+    request: Record<string, unknown>,
+    local: LocalListExecutor<T>,
+  ): Promise<QuerySourceListResponse<T>> {
+    const peers = await this.listActiveOutboundPeers();
+
+    const localPromise = this.runLocal(local).then((response) =>
+      this.tagList(response, SOURCE_LOCAL),
+    );
+    const remotePromises = peers.map(async (peer: OutboundPeer): Promise<TaggedList<T> | null> => {
+      try {
+        const response = await this.federationClient.list<T>(peer.id, resource, request);
+        return this.tagList(response, peer.commonName);
+      } catch (error: unknown) {
+        this.logger.warn(
+          `Federated query to peer ${peer.commonName} (${peer.id}) failed; returning partial all-source response: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+        return null;
+      }
+    });
+
+    const [localResult, ...remoteResults] = await Promise.all([localPromise, ...remotePromises]);
+    const successfulRemoteResults = remoteResults.filter(
+      (result: TaggedList<T> | null): result is TaggedList<T> => result !== null,
+    );
+    const allResults = [localResult, ...successfulRemoteResults];
+    const peerFailure = successfulRemoteResults.length !== peers.length;
+
+    return this.mergeTaggedLists(allResults, peerFailure);
+  }
+
+  private async runLocal<T extends object>(
+    local: LocalListExecutor<T>,
+  ): Promise<FederationListResponse<T>> {
+    const response = await local();
+    if (Array.isArray(response)) {
+      return { items: response };
+    }
+    return response;
+  }
+
+  private tagList<T extends object>(
+    response: FederationListResponse<T>,
+    source: string,
+  ): TaggedList<T> {
+    return {
+      items: tagWithSource(response.items, source),
+      partial: response._partial === true,
+      truncated: response._truncated === true || response.nextCursor !== undefined,
+      nextCursor: response.nextCursor,
+    };
+  }
+
+  private mergeTaggedLists<T extends object>(
+    lists: Array<TaggedList<T>>,
+    peerFailure: boolean,
+  ): QuerySourceListResponse<T> {
+    const items = lists.flatMap((list: TaggedList<T>) => list.items);
+    const partial =
+      peerFailure ||
+      lists.some((list: TaggedList<T>) => list.partial || list.nextCursor !== undefined);
+    const truncated = lists.some((list: TaggedList<T>) => list.truncated);
+
+    const response: QuerySourceListResponse<T> = { items };
+    if (partial) {
+      response._partial = true;
+    }
+    if (truncated) {
+      response._truncated = true;
+    }
+    return response;
+  }
+
+  private toResponse<T extends object>(tagged: TaggedList<T>): QuerySourceListResponse<T> {
+    const response: QuerySourceListResponse<T> = {
+      items: tagged.items,
+    };
+    if (tagged.nextCursor !== undefined) {
+      response.nextCursor = tagged.nextCursor;
+    }
+    if (tagged.partial) {
+      response._partial = true;
+    }
+    if (tagged.truncated) {
+      response._truncated = true;
+    }
+    return response;
+  }
+
+  private async findPeerByHost(sourceHost: string, source: string): Promise<OutboundPeer> {
+    const host = normalizeHost(sourceHost);
+    const peers = await this.listActiveOutboundPeers();
+    const peer = peers.find((candidate: OutboundPeer) => {
+      const commonName = normalizeHost(candidate.commonName);
+      const endpointHosts = endpointHostKeys(candidate.endpointUrl).map((endpointHost: string) =>
+        normalizeHost(endpointHost),
+      );
+      return commonName === host || endpointHosts.includes(host);
+    });
+
+    if (!peer) {
+      throw new QuerySourceError({
+        code: 'PEER_NOT_FOUND',
+        message: `No active outbound federation peer matches source ${source}`,
+        source,
+      });
+    }
+
+    return peer;
+  }
+
+  private async listActiveOutboundPeers(): Promise<OutboundPeer[]> {
+    const rows = await this.db
+      .select({
+        id: federationPeers.id,
+        commonName: federationPeers.commonName,
+        endpointUrl: federationPeers.endpointUrl,
+      })
+      .from(federationPeers)
+      .where(
+        and(
+          eq(federationPeers.state, 'active'),
+          isNotNull(federationPeers.endpointUrl),
+          isNotNull(federationPeers.clientKeyPem),
+        ),
+      )
+      .orderBy(federationPeers.commonName);
+
+    return rows.filter((row): row is OutboundPeer => typeof row.endpointUrl === 'string');
+  }
+}
+
+function normalizeHost(host: string): string {
+  return host.trim().toLowerCase();
+}
+
+function endpointHostKeys(endpointUrl: string): string[] {
+  try {
+    const url = new URL(endpointUrl);
+    return Array.from(new Set([url.host, url.hostname].filter((host: string) => host.length > 0)));
+  } catch {
+    return [];
+  }
+}

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,38 @@
+import { Module } from '@nestjs/common';
+import { AdminGuard } from '../admin/admin.guard.js';
+import { CaService } from './ca.service.js';
+import { EnrollmentController } from './enrollment.controller.js';
+import { EnrollmentService } from './enrollment.service.js';
+import { FederationController } from './federation.controller.js';
+import { CapabilitiesController } from './server/verbs/capabilities.controller.js';
+import { GrantsService } from './grants.service.js';
+import { FederationClientService, QuerySourceService } from './client/index.js';
+import { FederationAuthGuard, FederationScopeService } from './server/index.js';
+import { ListController } from './server/verbs/list.controller.js';
+import { FederationListQueryService } from './server/verbs/list-query.service.js';
+
+@Module({
+  controllers: [EnrollmentController, FederationController, CapabilitiesController, ListController],
+  providers: [
+    AdminGuard,
+    CaService,
+    EnrollmentService,
+    GrantsService,
+    FederationClientService,
+    QuerySourceService,
+    FederationAuthGuard,
+    FederationScopeService,
+    FederationListQueryService,
+  ],
+  exports: [
+    CaService,
+    EnrollmentService,
+    GrantsService,
+    FederationClientService,
+    QuerySourceService,
+    FederationAuthGuard,
+    FederationScopeService,
+    FederationListQueryService,
+  ],
+})
+export class FederationModule {}

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

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

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

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

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

@@ -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);
+}

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

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

apps/gateway/src/federation/scope-schema.spec.ts

@@ -0,0 +1,187 @@
+/**
+ * Unit tests for FederationScopeSchema and parseFederationScope.
+ *
+ * Coverage:
+ *  - Valid: minimal scope
+ *  - Valid: full PRD §8.1 example
+ *  - Valid: resources + excluded_resources (no overlap)
+ *  - Invalid: empty resources
+ *  - Invalid: unknown resource value
+ *  - Invalid: resources / excluded_resources intersection
+ *  - Invalid: filter key not in resources
+ *  - Invalid: max_rows_per_query = 0
+ *  - Invalid: max_rows_per_query = 10001
+ *  - Invalid: not an object / null
+ *  - Defaults: include_personal defaults to true; excluded_resources defaults to []
+ *  - Sentinel: console.warn fires for sensitive resources
+ */
+
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import {
+  parseFederationScope,
+  FederationScopeError,
+  FederationScopeSchema,
+} from './scope-schema.js';
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('parseFederationScope — valid inputs', () => {
+  it('accepts a minimal scope (resources + max_rows_per_query only)', () => {
+    const scope = parseFederationScope({
+      resources: ['tasks'],
+      max_rows_per_query: 100,
+    });
+    expect(scope.resources).toEqual(['tasks']);
+    expect(scope.max_rows_per_query).toBe(100);
+    expect(scope.excluded_resources).toEqual([]);
+    expect(scope.filters).toBeUndefined();
+  });
+
+  it('accepts the full PRD §8.1 example', () => {
+    const scope = parseFederationScope({
+      resources: ['tasks', 'notes', 'memory'],
+      filters: {
+        tasks: { include_teams: ['team_uuid_1', 'team_uuid_2'], include_personal: true },
+        notes: { include_personal: true, include_teams: [] },
+        memory: { include_personal: true },
+      },
+      excluded_resources: ['credentials', 'api_keys'],
+      max_rows_per_query: 500,
+    });
+    expect(scope.resources).toEqual(['tasks', 'notes', 'memory']);
+    expect(scope.excluded_resources).toEqual(['credentials', 'api_keys']);
+    expect(scope.filters?.tasks?.include_teams).toEqual(['team_uuid_1', 'team_uuid_2']);
+    expect(scope.max_rows_per_query).toBe(500);
+  });
+
+  it('accepts a scope with excluded_resources and no filter overlap', () => {
+    const scope = parseFederationScope({
+      resources: ['tasks', 'notes'],
+      excluded_resources: ['memory'],
+      max_rows_per_query: 250,
+    });
+    expect(scope.resources).toEqual(['tasks', 'notes']);
+    expect(scope.excluded_resources).toEqual(['memory']);
+  });
+});
+
+describe('parseFederationScope — defaults', () => {
+  it('defaults excluded_resources to []', () => {
+    const scope = parseFederationScope({ resources: ['tasks'], max_rows_per_query: 1 });
+    expect(scope.excluded_resources).toEqual([]);
+  });
+
+  it('defaults include_personal to true when filter is provided without it', () => {
+    const scope = parseFederationScope({
+      resources: ['tasks'],
+      filters: { tasks: { include_teams: ['t1'] } },
+      max_rows_per_query: 10,
+    });
+    expect(scope.filters?.tasks?.include_personal).toBe(true);
+  });
+});
+
+describe('parseFederationScope — invalid inputs', () => {
+  it('throws FederationScopeError for empty resources array', () => {
+    expect(() => parseFederationScope({ resources: [], max_rows_per_query: 100 })).toThrow(
+      FederationScopeError,
+    );
+  });
+
+  it('throws for unknown resource value in resources', () => {
+    expect(() =>
+      parseFederationScope({ resources: ['unknown_resource'], max_rows_per_query: 100 }),
+    ).toThrow(FederationScopeError);
+  });
+
+  it('throws when resources and excluded_resources intersect', () => {
+    expect(() =>
+      parseFederationScope({
+        resources: ['tasks', 'memory'],
+        excluded_resources: ['memory'],
+        max_rows_per_query: 100,
+      }),
+    ).toThrow(FederationScopeError);
+  });
+
+  it('throws when filters references a resource not in resources', () => {
+    expect(() =>
+      parseFederationScope({
+        resources: ['tasks'],
+        filters: { notes: { include_personal: true } },
+        max_rows_per_query: 100,
+      }),
+    ).toThrow(FederationScopeError);
+  });
+
+  it('throws for max_rows_per_query = 0', () => {
+    expect(() => parseFederationScope({ resources: ['tasks'], max_rows_per_query: 0 })).toThrow(
+      FederationScopeError,
+    );
+  });
+
+  it('throws for max_rows_per_query = 10001', () => {
+    expect(() => parseFederationScope({ resources: ['tasks'], max_rows_per_query: 10001 })).toThrow(
+      FederationScopeError,
+    );
+  });
+
+  it('throws for null input', () => {
+    expect(() => parseFederationScope(null)).toThrow(FederationScopeError);
+  });
+
+  it('throws for non-object input (string)', () => {
+    expect(() => parseFederationScope('not-an-object')).toThrow(FederationScopeError);
+  });
+});
+
+describe('parseFederationScope — sentinel warning', () => {
+  it('emits console.warn when resources includes "credentials"', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    parseFederationScope({
+      resources: ['tasks', 'credentials'],
+      max_rows_per_query: 100,
+    });
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining(
+        '[FederationScope] WARNING: scope grants sensitive resource "credentials"',
+      ),
+    );
+  });
+
+  it('emits console.warn when resources includes "api_keys"', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    parseFederationScope({
+      resources: ['tasks', 'api_keys'],
+      max_rows_per_query: 100,
+    });
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining(
+        '[FederationScope] WARNING: scope grants sensitive resource "api_keys"',
+      ),
+    );
+  });
+
+  it('does NOT emit console.warn for non-sensitive resources', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    parseFederationScope({ resources: ['tasks', 'notes', 'memory'], max_rows_per_query: 100 });
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe('FederationScopeSchema — boundary values', () => {
+  it('accepts max_rows_per_query = 1 (lower bound)', () => {
+    const result = FederationScopeSchema.safeParse({ resources: ['tasks'], max_rows_per_query: 1 });
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts max_rows_per_query = 10000 (upper bound)', () => {
+    const result = FederationScopeSchema.safeParse({
+      resources: ['tasks'],
+      max_rows_per_query: 10000,
+    });
+    expect(result.success).toBe(true);
+  });
+});

apps/gateway/src/federation/scope-schema.ts

@@ -0,0 +1,147 @@
+/**
+ * Federation grant scope schema and validator.
+ *
+ * Source of truth: docs/federation/PRD.md §8.1
+ *
+ * This module is intentionally pure — no DB, no NestJS, no CA wiring.
+ * It is reusable from grant CRUD (M2-06) and scope enforcement (M3+).
+ */
+
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Allowlist of federation resources (canonical — M3+ will extend this list)
+// ---------------------------------------------------------------------------
+export const FEDERATION_RESOURCE_VALUES = [
+  'tasks',
+  'notes',
+  'memory',
+  'credentials',
+  'api_keys',
+] as const;
+
+export type FederationResource = (typeof FEDERATION_RESOURCE_VALUES)[number];
+
+/**
+ * Sensitive resources require explicit admin approval (PRD §8.4).
+ * The parser warns when these appear in `resources`; M2-06 grant CRUD
+ * will add a hard gate on top of this warning.
+ */
+const SENSITIVE_RESOURCES: ReadonlySet<FederationResource> = new Set(['credentials', 'api_keys']);
+
+// ---------------------------------------------------------------------------
+// Sub-schemas
+// ---------------------------------------------------------------------------
+
+const ResourceArraySchema = z
+  .array(z.enum(FEDERATION_RESOURCE_VALUES))
+  .nonempty({ message: 'resources must contain at least one value' })
+  .refine((arr) => new Set(arr).size === arr.length, {
+    message: 'resources must not contain duplicate values',
+  });
+
+const ResourceFilterSchema = z.object({
+  include_teams: z.array(z.string()).optional(),
+  include_personal: z.boolean().default(true),
+});
+
+// ---------------------------------------------------------------------------
+// Top-level schema
+// ---------------------------------------------------------------------------
+
+export const FederationScopeSchema = z
+  .object({
+    resources: ResourceArraySchema,
+
+    excluded_resources: z
+      .array(z.enum(FEDERATION_RESOURCE_VALUES))
+      .default([])
+      .refine((arr) => new Set(arr).size === arr.length, {
+        message: 'excluded_resources must not contain duplicate values',
+      }),
+
+    filters: z.record(z.string(), ResourceFilterSchema).optional(),
+
+    max_rows_per_query: z
+      .number()
+      .int({ message: 'max_rows_per_query must be an integer' })
+      .min(1, { message: 'max_rows_per_query must be at least 1' })
+      .max(10000, { message: 'max_rows_per_query must be at most 10000' }),
+  })
+  .superRefine((data, ctx) => {
+    const resourceSet = new Set(data.resources);
+
+    // Intersection guard: a resource cannot be both granted and excluded
+    for (const r of data.excluded_resources) {
+      if (resourceSet.has(r)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Resource "${r}" appears in both resources and excluded_resources`,
+          path: ['excluded_resources'],
+        });
+      }
+    }
+
+    // Filter keys must be a subset of resources
+    if (data.filters) {
+      for (const key of Object.keys(data.filters)) {
+        if (!resourceSet.has(key as FederationResource)) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `filters key "${key}" references a resource not present in resources`,
+            path: ['filters', key],
+          });
+        }
+      }
+    }
+  });
+
+export type FederationScope = z.infer<typeof FederationScopeSchema>;
+
+// ---------------------------------------------------------------------------
+// Error class
+// ---------------------------------------------------------------------------
+
+export class FederationScopeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'FederationScopeError';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Typed parser
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse and validate an unknown value as a FederationScope.
+ *
+ * Throws `FederationScopeError` with aggregated Zod issues on failure.
+ *
+ * Emits `console.warn` when sensitive resources (`credentials`, `api_keys`)
+ * are present in `resources` — per PRD §8.4, these require explicit admin
+ * approval. M2-06 grant CRUD will add a hard gate on top of this warning.
+ */
+export function parseFederationScope(input: unknown): FederationScope {
+  const result = FederationScopeSchema.safeParse(input);
+
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((e) => `  - [${e.path.join('.') || 'root'}] ${e.message}`)
+      .join('\n');
+    throw new FederationScopeError(`Invalid federation scope:\n${issues}`);
+  }
+
+  const scope = result.data;
+
+  // Sentinel warning for sensitive resources (PRD §8.4)
+  for (const resource of scope.resources) {
+    if (SENSITIVE_RESOURCES.has(resource)) {
+      console.warn(
+        `[FederationScope] WARNING: scope grants sensitive resource "${resource}". Per PRD §8.4 this requires explicit admin approval and is logged.`,
+      );
+    }
+  }
+
+  return scope;
+}

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,
+    });
+  });
+});

apps/gateway/src/federation/server/__tests__/scope.service.spec.ts

@@ -0,0 +1,324 @@
+/**
+ * Unit tests for FederationScopeService (FED-M3-04).
+ *
+ * Coverage:
+ *  - resource allowlist deny
+ *  - excluded resource deny
+ *  - invalid scope deny
+ *  - invalid requested limit deny
+ *  - native RBAC deny as subjectUserId
+ *  - scope/native filter intersection for personal and team rows
+ *  - native RBAC personal deny wins over scope include_personal allow/default
+ *  - max_rows_per_query cap
+ */
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { FederationScopeService, type FederationNativeRbacEvaluator } from '../scope.service.js';
+import type { FederationContext } from '../federation-context.js';
+
+const GRANT_ID = 'grant-1';
+const PEER_ID = 'peer-1';
+const SUBJECT_USER_ID = 'user-1';
+
+function makeContext(scope: Record<string, unknown>): FederationContext {
+  return {
+    grantId: GRANT_ID,
+    peerId: PEER_ID,
+    subjectUserId: SUBJECT_USER_ID,
+    scope,
+  };
+}
+
+function makeNativeRbac(
+  result: Awaited<ReturnType<FederationNativeRbacEvaluator['evaluateReadAccess']>>,
+): FederationNativeRbacEvaluator {
+  return {
+    evaluateReadAccess: vi.fn().mockResolvedValue(result),
+  };
+}
+
+describe('FederationScopeService', () => {
+  let service: FederationScopeService;
+
+  beforeEach(() => {
+    service = new FederationScopeService();
+  });
+
+  it('allows a granted resource and returns a capped query filter', async () => {
+    const nativeRbac = makeNativeRbac({
+      allowed: true,
+      access: { includePersonal: true, teamIds: ['team-1', 'team-2'] },
+    });
+
+    const result = await service.evaluateAccess({
+      context: makeContext({
+        resources: ['tasks'],
+        filters: { tasks: { include_teams: ['team-1', 'team-3'], include_personal: true } },
+        max_rows_per_query: 50,
+      }),
+      resource: 'tasks',
+      requestedLimit: 500,
+      nativeRbac,
+    });
+
+    expect(result).toEqual({
+      allowed: true,
+      filter: {
+        resource: 'tasks',
+        subjectUserId: SUBJECT_USER_ID,
+        includePersonal: true,
+        teamIds: ['team-1'],
+        limit: 50,
+        maxRowsPerQuery: 50,
+      },
+    });
+    expect(nativeRbac.evaluateReadAccess).toHaveBeenCalledWith({
+      grantId: GRANT_ID,
+      peerId: PEER_ID,
+      subjectUserId: SUBJECT_USER_ID,
+      resource: 'tasks',
+    });
+  });
+
+  it('defaults absent resource filters to native RBAC personal and team visibility', async () => {
+    const result = await service.evaluateAccess({
+      context: makeContext({ resources: ['notes'], max_rows_per_query: 100 }),
+      resource: 'notes',
+      nativeRbac: makeNativeRbac({
+        allowed: true,
+        access: { includePersonal: true, teamIds: ['team-1', 'team-2'] },
+      }),
+    });
+
+    expect(result).toMatchObject({
+      allowed: true,
+      filter: {
+        includePersonal: true,
+        teamIds: ['team-1', 'team-2'],
+        limit: 100,
+      },
+    });
+  });
+
+  it('honors include_personal false even when native RBAC allows personal rows', async () => {
+    const result = await service.evaluateAccess({
+      context: makeContext({
+        resources: ['memory'],
+        filters: { memory: { include_personal: false } },
+        max_rows_per_query: 25,
+      }),
+      resource: 'memory',
+      nativeRbac: makeNativeRbac({
+        allowed: true,
+        access: { includePersonal: true, teamIds: [] },
+      }),
+    });
+
+    expect(result).toMatchObject({
+      allowed: true,
+      filter: {
+        includePersonal: false,
+        teamIds: [],
+      },
+    });
+  });
+
+  it('does not leak personal rows when scope allows personal but native RBAC denies personal', async () => {
+    const result = await service.evaluateAccess({
+      context: makeContext({
+        resources: ['tasks'],
+        filters: { tasks: { include_personal: true } },
+        max_rows_per_query: 25,
+      }),
+      resource: 'tasks',
+      nativeRbac: makeNativeRbac({
+        allowed: true,
+        access: { includePersonal: false, teamIds: ['team-1'] },
+      }),
+    });
+
+    expect(result).toMatchObject({
+      allowed: true,
+      filter: {
+        includePersonal: false,
+        teamIds: ['team-1'],
+      },
+    });
+  });
+
+  it('does not widen native RBAC when scope includes teams the user cannot access', async () => {
+    const result = await service.evaluateAccess({
+      context: makeContext({
+        resources: ['tasks'],
+        filters: { tasks: { include_teams: ['team-2'], include_personal: false } },
+        max_rows_per_query: 25,
+      }),
+      resource: 'tasks',
+      nativeRbac: makeNativeRbac({
+        allowed: true,
+        access: { includePersonal: true, teamIds: ['team-1'] },
+      }),
+    });
+
+    expect(result).toMatchObject({
+      allowed: true,
+      filter: {
+        includePersonal: false,
+        teamIds: [],
+      },
+    });
+  });
+
+  it('denies invalid grant scope before RBAC evaluation', async () => {
+    const nativeRbac = makeNativeRbac({
+      allowed: true,
+      access: { includePersonal: true, teamIds: [] },
+    });
+
+    const result = await service.evaluateAccess({
+      context: makeContext({ resources: [], max_rows_per_query: 100 }),
+      resource: 'tasks',
+      nativeRbac,
+    });
+
+    expect(result).toMatchObject({
+      allowed: false,
+      deny: {
+        code: 'invalid_scope',
+        stage: 'scope_parse',
+        statusCode: 400,
+        grantId: GRANT_ID,
+        subjectUserId: SUBJECT_USER_ID,
+        resource: 'tasks',
+      },
+    });
+    expect(nativeRbac.evaluateReadAccess).not.toHaveBeenCalled();
+  });
+
+  it('denies unsupported resource names before RBAC evaluation', async () => {
+    const nativeRbac = makeNativeRbac({
+      allowed: true,
+      access: { includePersonal: true, teamIds: [] },
+    });
+
+    const result = await service.evaluateAccess({
+      context: makeContext({ resources: ['tasks'], max_rows_per_query: 100 }),
+      resource: 'unknown_resource',
+      nativeRbac,
+    });
+
+    expect(result).toMatchObject({
+      allowed: false,
+      deny: {
+        code: 'invalid_resource',
+        stage: 'resource_allowlist',
+        statusCode: 403,
+      },
+    });
+    expect(nativeRbac.evaluateReadAccess).not.toHaveBeenCalled();
+  });
+
+  it('denies resources explicitly present in excluded_resources before allowlist miss', async () => {
+    const nativeRbac = makeNativeRbac({
+      allowed: true,
+      access: { includePersonal: true, teamIds: [] },
+    });
+
+    const result = await service.evaluateAccess({
+      context: makeContext({
+        resources: ['tasks'],
+        excluded_resources: ['credentials'],
+        max_rows_per_query: 100,
+      }),
+      resource: 'credentials',
+      nativeRbac,
+    });
+
+    expect(result).toMatchObject({
+      allowed: false,
+      deny: {
+        code: 'resource_excluded',
+        stage: 'resource_exclusion',
+        statusCode: 403,
+        resource: 'credentials',
+      },
+    });
+    expect(nativeRbac.evaluateReadAccess).not.toHaveBeenCalled();
+  });
+
+  it('denies supported resources that are not granted by scope', async () => {
+    const nativeRbac = makeNativeRbac({
+      allowed: true,
+      access: { includePersonal: true, teamIds: [] },
+    });
+
+    const result = await service.evaluateAccess({
+      context: makeContext({ resources: ['tasks'], max_rows_per_query: 100 }),
+      resource: 'notes',
+      nativeRbac,
+    });
+
+    expect(result).toMatchObject({
+      allowed: false,
+      deny: {
+        code: 'resource_not_granted',
+        stage: 'resource_allowlist',
+        statusCode: 403,
+        resource: 'notes',
+      },
+    });
+    expect(nativeRbac.evaluateReadAccess).not.toHaveBeenCalled();
+  });
+
+  it('denies invalid requested row limits before RBAC evaluation', async () => {
+    const nativeRbac = makeNativeRbac({
+      allowed: true,
+      access: { includePersonal: true, teamIds: [] },
+    });
+
+    const result = await service.evaluateAccess({
+      context: makeContext({ resources: ['tasks'], max_rows_per_query: 100 }),
+      resource: 'tasks',
+      requestedLimit: 0,
+      nativeRbac,
+    });
+
+    expect(result).toMatchObject({
+      allowed: false,
+      deny: {
+        code: 'invalid_limit',
+        stage: 'row_cap',
+        statusCode: 400,
+        details: { requestedLimit: 0 },
+      },
+    });
+    expect(nativeRbac.evaluateReadAccess).not.toHaveBeenCalled();
+  });
+
+  it('denies when native RBAC rejects subjectUserId access to the resource', async () => {
+    const result = await service.evaluateAccess({
+      context: makeContext({ resources: ['tasks'], max_rows_per_query: 100 }),
+      resource: 'tasks',
+      nativeRbac: makeNativeRbac({
+        allowed: false,
+        reason: 'read:tasks denied',
+        details: { permission: 'tasks:read' },
+      }),
+    });
+
+    expect(result).toEqual({
+      allowed: false,
+      deny: {
+        code: 'native_rbac_denied',
+        stage: 'native_rbac',
+        statusCode: 403,
+        message: 'read:tasks denied',
+        grantId: GRANT_ID,
+        peerId: PEER_ID,
+        subjectUserId: SUBJECT_USER_ID,
+        resource: 'tasks',
+        details: { permission: 'tasks:read' },
+      },
+    });
+  });
+});

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;
+  }
+}

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>;
+}

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

@@ -0,0 +1,31 @@
+/**
+ * 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 { FederationScopeService } from './scope.service.js';
+export type { FederationContext } from './federation-context.js';
+export type {
+  FederationNativeRbacAccess,
+  FederationNativeRbacAllowedResult,
+  FederationNativeRbacDeniedResult,
+  FederationNativeRbacEvaluator,
+  FederationNativeRbacRequest,
+  FederationNativeRbacResult,
+  FederationScopeAllowedResult,
+  FederationScopeDeniedResult,
+  FederationScopeDenyCode,
+  FederationScopeDenyDetails,
+  FederationScopeDenyReason,
+  FederationScopeDenyStage,
+  FederationScopeEvaluationInput,
+  FederationScopeEvaluationResult,
+  FederationScopeQueryFilter,
+} from './scope.service.js';

apps/gateway/src/federation/server/scope.service.ts

@@ -0,0 +1,272 @@
+/**
+ * FederationScopeService — M3 server-side scope enforcement pipeline.
+ *
+ * Pure trust-boundary service: it validates the grant scope, asks an injected
+ * native RBAC evaluator what the subject user can read locally, intersects that
+ * answer with the federation scope filters, and returns a query filter for the
+ * verb controllers. The service performs no DB calls directly.
+ */
+
+import { Injectable } from '@nestjs/common';
+import {
+  FEDERATION_RESOURCE_VALUES,
+  type FederationResource,
+  FederationScopeError,
+  parseFederationScope,
+} from '../scope-schema.js';
+import type { FederationContext } from './federation-context.js';
+
+const federationResourceSet: ReadonlySet<string> = new Set<string>(FEDERATION_RESOURCE_VALUES);
+
+export type FederationScopeDenyStage =
+  | 'scope_parse'
+  | 'resource_allowlist'
+  | 'resource_exclusion'
+  | 'native_rbac'
+  | 'row_cap';
+
+export type FederationScopeDenyCode =
+  | 'invalid_scope'
+  | 'invalid_resource'
+  | 'resource_not_granted'
+  | 'resource_excluded'
+  | 'native_rbac_denied'
+  | 'invalid_limit';
+
+export type FederationScopeDenyStatus = 400 | 403;
+
+export interface FederationScopeDenyDetails {
+  readonly [key: string]: string | number | boolean | readonly string[];
+}
+
+export interface FederationScopeDenyReason {
+  readonly code: FederationScopeDenyCode;
+  readonly stage: FederationScopeDenyStage;
+  readonly statusCode: FederationScopeDenyStatus;
+  readonly message: string;
+  readonly grantId: string;
+  readonly peerId: string;
+  readonly subjectUserId: string;
+  readonly resource: string;
+  readonly details?: FederationScopeDenyDetails;
+}
+
+export interface FederationNativeRbacRequest {
+  readonly grantId: string;
+  readonly peerId: string;
+  readonly subjectUserId: string;
+  readonly resource: FederationResource;
+}
+
+export interface FederationNativeRbacAccess {
+  /** Whether this user may read personal rows for this resource. */
+  readonly includePersonal: boolean;
+
+  /** Team IDs this user may read for this resource under native RBAC. */
+  readonly teamIds: readonly string[];
+}
+
+export interface FederationNativeRbacAllowedResult {
+  readonly allowed: true;
+  readonly access: FederationNativeRbacAccess;
+}
+
+export interface FederationNativeRbacDeniedResult {
+  readonly allowed: false;
+  readonly reason?: string;
+  readonly details?: FederationScopeDenyDetails;
+}
+
+export type FederationNativeRbacResult =
+  | FederationNativeRbacAllowedResult
+  | FederationNativeRbacDeniedResult;
+
+export interface FederationNativeRbacEvaluator {
+  evaluateReadAccess(request: FederationNativeRbacRequest): Promise<FederationNativeRbacResult>;
+}
+
+export interface FederationScopeEvaluationInput {
+  readonly context: FederationContext;
+  readonly resource: string;
+  readonly requestedLimit?: number;
+  readonly nativeRbac: FederationNativeRbacEvaluator;
+}
+
+export interface FederationScopeQueryFilter {
+  readonly resource: FederationResource;
+  readonly subjectUserId: string;
+  readonly includePersonal: boolean;
+  readonly teamIds: readonly string[];
+  readonly limit: number;
+  readonly maxRowsPerQuery: number;
+}
+
+export interface FederationScopeAllowedResult {
+  readonly allowed: true;
+  readonly filter: FederationScopeQueryFilter;
+}
+
+export interface FederationScopeDeniedResult {
+  readonly allowed: false;
+  readonly deny: FederationScopeDenyReason;
+}
+
+export type FederationScopeEvaluationResult =
+  | FederationScopeAllowedResult
+  | FederationScopeDeniedResult;
+
+function isFederationResource(resource: string): resource is FederationResource {
+  return federationResourceSet.has(resource);
+}
+
+function uniqueStrings(values: readonly string[]): readonly string[] {
+  return Array.from(new Set<string>(values));
+}
+
+function intersectTeamIds(
+  nativeTeamIds: readonly string[],
+  scopedTeamIds: readonly string[] | undefined,
+): readonly string[] {
+  const uniqueNativeTeamIds = uniqueStrings(nativeTeamIds);
+
+  if (scopedTeamIds === undefined) {
+    return uniqueNativeTeamIds;
+  }
+
+  const nativeSet = new Set<string>(uniqueNativeTeamIds);
+  return uniqueStrings(scopedTeamIds).filter((teamId: string): boolean => nativeSet.has(teamId));
+}
+
+function makeDenyReason(params: {
+  readonly code: FederationScopeDenyCode;
+  readonly stage: FederationScopeDenyStage;
+  readonly statusCode?: FederationScopeDenyStatus;
+  readonly message: string;
+  readonly context: FederationContext;
+  readonly resource: string;
+  readonly details?: FederationScopeDenyDetails;
+}): FederationScopeDeniedResult {
+  return {
+    allowed: false,
+    deny: {
+      code: params.code,
+      stage: params.stage,
+      statusCode: params.statusCode ?? 403,
+      message: params.message,
+      grantId: params.context.grantId,
+      peerId: params.context.peerId,
+      subjectUserId: params.context.subjectUserId,
+      resource: params.resource,
+      ...(params.details !== undefined ? { details: params.details } : {}),
+    },
+  };
+}
+
+@Injectable()
+export class FederationScopeService {
+  async evaluateAccess(
+    input: FederationScopeEvaluationInput,
+  ): Promise<FederationScopeEvaluationResult> {
+    const { context, resource, requestedLimit, nativeRbac } = input;
+
+    let scope: ReturnType<typeof parseFederationScope>;
+    try {
+      scope = parseFederationScope(context.scope);
+    } catch (error: unknown) {
+      const message =
+        error instanceof FederationScopeError
+          ? 'Federation grant scope is invalid'
+          : 'Federation grant scope could not be parsed';
+      const details = error instanceof Error ? { reason: error.message } : undefined;
+      return makeDenyReason({
+        code: 'invalid_scope',
+        stage: 'scope_parse',
+        statusCode: 400,
+        message,
+        context,
+        resource,
+        ...(details !== undefined ? { details } : {}),
+      });
+    }
+
+    if (!isFederationResource(resource)) {
+      return makeDenyReason({
+        code: 'invalid_resource',
+        stage: 'resource_allowlist',
+        message: 'Requested federation resource is not supported',
+        context,
+        resource,
+        details: { supportedResources: FEDERATION_RESOURCE_VALUES },
+      });
+    }
+
+    if (scope.excluded_resources.includes(resource)) {
+      return makeDenyReason({
+        code: 'resource_excluded',
+        stage: 'resource_exclusion',
+        message: 'Requested federation resource is explicitly excluded by grant scope',
+        context,
+        resource,
+      });
+    }
+
+    if (!scope.resources.includes(resource)) {
+      return makeDenyReason({
+        code: 'resource_not_granted',
+        stage: 'resource_allowlist',
+        message: 'Requested federation resource is not granted by scope',
+        context,
+        resource,
+        details: { grantedResources: scope.resources },
+      });
+    }
+
+    if (requestedLimit !== undefined && (!Number.isInteger(requestedLimit) || requestedLimit < 1)) {
+      return makeDenyReason({
+        code: 'invalid_limit',
+        stage: 'row_cap',
+        statusCode: 400,
+        message: 'Requested row limit must be a positive integer',
+        context,
+        resource,
+        details: { requestedLimit },
+      });
+    }
+
+    const nativeResult = await nativeRbac.evaluateReadAccess({
+      grantId: context.grantId,
+      peerId: context.peerId,
+      subjectUserId: context.subjectUserId,
+      resource,
+    });
+
+    if (!nativeResult.allowed) {
+      return makeDenyReason({
+        code: 'native_rbac_denied',
+        stage: 'native_rbac',
+        message: nativeResult.reason ?? 'Subject user is not allowed to read this resource',
+        context,
+        resource,
+        ...(nativeResult.details !== undefined ? { details: nativeResult.details } : {}),
+      });
+    }
+
+    const scopeFilter = scope.filters?.[resource];
+    const includePersonal =
+      Boolean(scopeFilter?.include_personal ?? true) && nativeResult.access.includePersonal;
+    const teamIds = intersectTeamIds(nativeResult.access.teamIds, scopeFilter?.include_teams);
+    const limit = Math.min(requestedLimit ?? scope.max_rows_per_query, scope.max_rows_per_query);
+
+    return {
+      allowed: true,
+      filter: {
+        resource,
+        subjectUserId: context.subjectUserId,
+        includePersonal,
+        teamIds,
+        limit,
+        maxRowsPerQuery: scope.max_rows_per_query,
+      },
+    };
+  }
+}

apps/gateway/src/federation/server/verbs/__tests__/capabilities.controller.spec.ts

@@ -0,0 +1,88 @@
+import 'reflect-metadata';
+import { RequestMethod } from '@nestjs/common';
+import { describe, expect, it } from 'vitest';
+import type { FastifyRequest } from 'fastify';
+import { FederationCapabilitiesResponseSchema, FEDERATION_VERBS } from '@mosaicstack/types';
+import { FederationScopeError } from '../../../scope-schema.js';
+import { FederationAuthGuard } from '../../federation-auth.guard.js';
+import { CapabilitiesController } from '../capabilities.controller.js';
+
+const VALID_SCOPE = {
+  resources: ['tasks', 'notes'],
+  excluded_resources: ['credentials'],
+  max_rows_per_query: 250,
+} as const;
+
+const DEFAULTED_SCOPE = {
+  resources: ['memory'],
+  max_rows_per_query: 10,
+} as const;
+
+function makeRequest(scope: Record<string, unknown>): FastifyRequest {
+  return {
+    federationContext: {
+      grantId: 'grant-1',
+      peerId: 'peer-1',
+      subjectUserId: 'user-1',
+      scope,
+    },
+  } as FastifyRequest;
+}
+
+describe('CapabilitiesController', () => {
+  it('declares GET /api/federation/v1/capabilities', () => {
+    expect(Reflect.getMetadata('path', CapabilitiesController)).toBe(
+      'api/federation/v1/capabilities',
+    );
+    expect(Reflect.getMetadata('path', CapabilitiesController.prototype.getCapabilities)).toBe('/');
+    expect(Reflect.getMetadata('method', CapabilitiesController.prototype.getCapabilities)).toBe(
+      RequestMethod.GET,
+    );
+  });
+
+  it('is protected only by FederationAuthGuard', () => {
+    const guards = Reflect.getMetadata('__guards__', CapabilitiesController) as unknown[];
+
+    expect(guards).toEqual([FederationAuthGuard]);
+  });
+
+  it('returns resources, excluded resources, max rows, and M3 supported verbs from the active grant scope', () => {
+    const controller = new CapabilitiesController();
+
+    const response = controller.getCapabilities(makeRequest(VALID_SCOPE));
+
+    expect(response).toEqual({
+      resources: ['tasks', 'notes'],
+      excluded_resources: ['credentials'],
+      max_rows_per_query: 250,
+      supported_verbs: [...FEDERATION_VERBS],
+    });
+    expect(FederationCapabilitiesResponseSchema.safeParse(response).success).toBe(true);
+  });
+
+  it('applies scope defaults without RBAC or resource filtering', () => {
+    const controller = new CapabilitiesController();
+
+    const response = controller.getCapabilities(makeRequest(DEFAULTED_SCOPE));
+
+    expect(response).toEqual({
+      resources: ['memory'],
+      excluded_resources: [],
+      max_rows_per_query: 10,
+      supported_verbs: ['list', 'get', 'capabilities'],
+    });
+  });
+
+  it('rejects invalid scope state instead of returning an invalid capabilities contract', () => {
+    const controller = new CapabilitiesController();
+
+    expect(() =>
+      controller.getCapabilities(
+        makeRequest({
+          resources: [],
+          max_rows_per_query: 0,
+        }),
+      ),
+    ).toThrow(FederationScopeError);
+  });
+});

apps/gateway/src/federation/server/verbs/__tests__/list-query.service.spec.ts

@@ -0,0 +1,428 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import {
+  createPgliteDb,
+  insights,
+  missionTasks,
+  missions,
+  preferences,
+  projects,
+  runPgliteMigrations,
+  teams,
+  users,
+  type Db,
+  type DbHandle,
+} from '@mosaicstack/db';
+import type { FederationScopeQueryFilter } from '../../scope.service.js';
+import { FederationListQueryService } from '../list-query.service.js';
+
+const TASK_FILTER: FederationScopeQueryFilter = {
+  resource: 'tasks',
+  subjectUserId: 'user-1',
+  includePersonal: true,
+  teamIds: [],
+  limit: 2,
+  maxRowsPerQuery: 2,
+};
+
+const SUBJECT_USER_ID = 'fed-m3-05-subject';
+const OTHER_USER_ID = 'fed-m3-05-other';
+const TEAM_ID = '05000000-0000-4000-8000-000000000001';
+const UNAUTHORIZED_TEAM_ID = '05000000-0000-4000-8000-000000000002';
+const PERSONAL_PROJECT_ID = '05000000-0000-4000-8000-000000000101';
+const TEAM_PROJECT_ID = '05000000-0000-4000-8000-000000000102';
+const UNAUTHORIZED_PROJECT_ID = '05000000-0000-4000-8000-000000000103';
+const PERSONAL_MISSION_ID = '05000000-0000-4000-8000-000000000201';
+const TEAM_MISSION_ID = '05000000-0000-4000-8000-000000000202';
+const UNAUTHORIZED_MISSION_ID = '05000000-0000-4000-8000-000000000203';
+const SUBJECT_TEAM_NOTE_ID = '05000000-0000-4000-8000-000000000301';
+const OTHER_TEAM_NOTE_ID = '05000000-0000-4000-8000-000000000302';
+const SUBJECT_PERSONAL_NOTE_ID = '05000000-0000-4000-8000-000000000303';
+const SUBJECT_UNAUTHORIZED_NOTE_ID = '05000000-0000-4000-8000-000000000304';
+const INSIGHT_ONE_ID = '05000000-0000-4000-8000-000000000401';
+const INSIGHT_TWO_ID = '05000000-0000-4000-8000-000000000402';
+const PREFERENCE_ONE_ID = '05000000-0000-4000-8000-000000000501';
+const PREFERENCE_TWO_ID = '05000000-0000-4000-8000-000000000502';
+
+let dbHandle: DbHandle | undefined;
+
+function makeService() {
+  return new FederationListQueryService({} as Db);
+}
+
+function makeDbService() {
+  if (!dbHandle) {
+    throw new Error('test DB not initialized');
+  }
+  return new FederationListQueryService(dbHandle.db);
+}
+
+async function seedNotesFixture() {
+  if (!dbHandle) {
+    throw new Error('test DB not initialized');
+  }
+
+  await dbHandle.db.insert(users).values([
+    {
+      id: SUBJECT_USER_ID,
+      name: 'Federation Subject',
+      email: `${SUBJECT_USER_ID}@example.test`,
+      emailVerified: false,
+    },
+    {
+      id: OTHER_USER_ID,
+      name: 'Federation Other',
+      email: `${OTHER_USER_ID}@example.test`,
+      emailVerified: false,
+    },
+  ]);
+
+  await dbHandle.db.insert(teams).values([
+    {
+      id: TEAM_ID,
+      name: 'FED-M3-05 Team',
+      slug: 'fed-m3-05-team',
+      ownerId: SUBJECT_USER_ID,
+      managerId: SUBJECT_USER_ID,
+    },
+    {
+      id: UNAUTHORIZED_TEAM_ID,
+      name: 'FED-M3-05 Unauthorized Team',
+      slug: 'fed-m3-05-unauthorized-team',
+      ownerId: OTHER_USER_ID,
+      managerId: OTHER_USER_ID,
+    },
+  ]);
+
+  await dbHandle.db.insert(projects).values([
+    {
+      id: PERSONAL_PROJECT_ID,
+      name: 'FED-M3-05 Personal Project',
+      ownerId: SUBJECT_USER_ID,
+      ownerType: 'user',
+    },
+    {
+      id: TEAM_PROJECT_ID,
+      name: 'FED-M3-05 Team Project',
+      teamId: TEAM_ID,
+      ownerType: 'team',
+    },
+    {
+      id: UNAUTHORIZED_PROJECT_ID,
+      name: 'FED-M3-05 Unauthorized Project',
+      teamId: UNAUTHORIZED_TEAM_ID,
+      ownerType: 'team',
+    },
+  ]);
+
+  await dbHandle.db.insert(missions).values([
+    {
+      id: PERSONAL_MISSION_ID,
+      name: 'FED-M3-05 Personal Mission',
+      projectId: PERSONAL_PROJECT_ID,
+      userId: SUBJECT_USER_ID,
+    },
+    {
+      id: TEAM_MISSION_ID,
+      name: 'FED-M3-05 Team Mission',
+      projectId: TEAM_PROJECT_ID,
+      userId: SUBJECT_USER_ID,
+    },
+    {
+      id: UNAUTHORIZED_MISSION_ID,
+      name: 'FED-M3-05 Unauthorized Mission',
+      projectId: UNAUTHORIZED_PROJECT_ID,
+      userId: SUBJECT_USER_ID,
+    },
+  ]);
+
+  await dbHandle.db.insert(missionTasks).values([
+    {
+      id: SUBJECT_TEAM_NOTE_ID,
+      missionId: TEAM_MISSION_ID,
+      userId: SUBJECT_USER_ID,
+      notes: 'subject note on team mission',
+      createdAt: new Date('2026-06-24T03:00:00.000Z'),
+      updatedAt: new Date('2026-06-24T03:00:00.000Z'),
+    },
+    {
+      id: OTHER_TEAM_NOTE_ID,
+      missionId: TEAM_MISSION_ID,
+      userId: OTHER_USER_ID,
+      notes: 'other user note on team mission',
+      createdAt: new Date('2026-06-24T02:00:00.000Z'),
+      updatedAt: new Date('2026-06-24T02:00:00.000Z'),
+    },
+    {
+      id: SUBJECT_PERSONAL_NOTE_ID,
+      missionId: PERSONAL_MISSION_ID,
+      userId: SUBJECT_USER_ID,
+      notes: 'subject note on personal mission',
+      createdAt: new Date('2026-06-24T01:00:00.000Z'),
+      updatedAt: new Date('2026-06-24T01:00:00.000Z'),
+    },
+    {
+      id: SUBJECT_UNAUTHORIZED_NOTE_ID,
+      missionId: UNAUTHORIZED_MISSION_ID,
+      userId: SUBJECT_USER_ID,
+      notes: 'subject note outside grant-visible missions',
+      createdAt: new Date('2026-06-24T04:00:00.000Z'),
+      updatedAt: new Date('2026-06-24T04:00:00.000Z'),
+    },
+  ]);
+
+  const memoryCreatedAt = new Date('2026-06-24T05:00:00.000Z');
+  await dbHandle.db.insert(insights).values([
+    {
+      id: INSIGHT_ONE_ID,
+      userId: SUBJECT_USER_ID,
+      content: 'first insight',
+      source: 'agent',
+      createdAt: memoryCreatedAt,
+      updatedAt: memoryCreatedAt,
+    },
+    {
+      id: INSIGHT_TWO_ID,
+      userId: SUBJECT_USER_ID,
+      content: 'second insight',
+      source: 'agent',
+      createdAt: memoryCreatedAt,
+      updatedAt: memoryCreatedAt,
+    },
+  ]);
+
+  await dbHandle.db.insert(preferences).values([
+    {
+      id: PREFERENCE_ONE_ID,
+      userId: SUBJECT_USER_ID,
+      key: 'fed-m3-05-pref-1',
+      value: { enabled: true },
+      createdAt: memoryCreatedAt,
+      updatedAt: memoryCreatedAt,
+    },
+    {
+      id: PREFERENCE_TWO_ID,
+      userId: SUBJECT_USER_ID,
+      key: 'fed-m3-05-pref-2',
+      value: { enabled: false },
+      createdAt: memoryCreatedAt,
+      updatedAt: memoryCreatedAt,
+    },
+  ]);
+}
+
+function stubRows(
+  service: FederationListQueryService,
+  ...pages: Array<Array<Record<string, unknown>>>
+) {
+  const mock = vi.fn();
+  for (const page of pages) {
+    mock.mockResolvedValueOnce(page);
+  }
+  (
+    service as unknown as {
+      listAllRows: (
+        _filter: FederationScopeQueryFilter,
+        _rowLimit: number,
+        _cursor: unknown,
+      ) => Promise<Array<Record<string, unknown>>>;
+    }
+  ).listAllRows = mock;
+  return mock;
+}
+
+describe('FederationListQueryService', () => {
+  beforeAll(async () => {
+    dbHandle = createPgliteDb(`memory://fed-m3-05-list-${Date.now()}`);
+    await runPgliteMigrations(dbHandle);
+    await seedNotesFixture();
+  });
+
+  afterAll(async () => {
+    await dbHandle?.close();
+    dbHandle = undefined;
+  });
+
+  it('denies sensitive resources in native RBAC for M3 list reads', async () => {
+    const service = makeService();
+
+    await expect(
+      service.evaluateReadAccess({
+        grantId: 'grant-1',
+        peerId: 'peer-1',
+        subjectUserId: 'user-1',
+        resource: 'credentials',
+      }),
+    ).resolves.toMatchObject({
+      allowed: false,
+      reason: 'credentials federation list access is not implemented in M3',
+    });
+  });
+
+  it('allows personal memory reads without requiring team lookup', async () => {
+    const service = makeService();
+
+    await expect(
+      service.evaluateReadAccess({
+        grantId: 'grant-1',
+        peerId: 'peer-1',
+        subjectUserId: 'user-1',
+        resource: 'memory',
+      }),
+    ).resolves.toEqual({
+      allowed: true,
+      access: { includePersonal: true, teamIds: [] },
+    });
+  });
+
+  it('applies the scope row cap and returns an opaque next cursor when truncated', async () => {
+    const service = makeService();
+    const listAllRows = stubRows(
+      service,
+      [
+        { id: '3', createdAt: new Date('2026-06-24T03:00:00.000Z') },
+        { id: '2', createdAt: new Date('2026-06-24T02:00:00.000Z') },
+        { id: '1', createdAt: new Date('2026-06-24T01:00:00.000Z') },
+      ],
+      [{ id: '1', createdAt: new Date('2026-06-24T01:00:00.000Z') }],
+    );
+
+    const firstPage = await service.list({ filter: TASK_FILTER });
+
+    expect(firstPage).toEqual({
+      items: [
+        { id: '3', createdAt: new Date('2026-06-24T03:00:00.000Z') },
+        { id: '2', createdAt: new Date('2026-06-24T02:00:00.000Z') },
+      ],
+      truncated: true,
+      nextCursor: expect.any(String),
+    });
+
+    expect(listAllRows).toHaveBeenNthCalledWith(1, TASK_FILTER, 3, undefined);
+
+    const secondPage = await service.list({ filter: TASK_FILTER, cursor: firstPage.nextCursor });
+    expect(secondPage).toEqual({
+      items: [{ id: '1', createdAt: new Date('2026-06-24T01:00:00.000Z') }],
+      truncated: false,
+    });
+    expect(listAllRows).toHaveBeenNthCalledWith(
+      2,
+      TASK_FILTER,
+      3,
+      expect.objectContaining({ id: '2' }),
+    );
+  });
+
+  it('rejects invalid cursors instead of falling back to the first page', async () => {
+    const service = makeService();
+    stubRows(service, [{ id: '1' }]);
+
+    await expect(service.list({ filter: TASK_FILTER, cursor: 'not-base64-json' })).rejects.toThrow(
+      'Invalid federation list cursor',
+    );
+  });
+
+  it('throws when a truncated page cannot encode a resumable cursor', async () => {
+    const service = makeService();
+    stubRows(service, [
+      { id: '2', createdAt: 'not-a-date' },
+      { id: '1', createdAt: 'not-a-date' },
+    ]);
+
+    await expect(service.list({ filter: { ...TASK_FILTER, limit: 1 } })).rejects.toThrow(
+      'Federation list cursor cannot be encoded',
+    );
+  });
+
+  it('throws on unsupported resources instead of crashing pagination', async () => {
+    const service = makeService();
+
+    await expect(
+      service.list({
+        filter: {
+          ...TASK_FILTER,
+          resource: 'unknown-resource' as FederationScopeQueryFilter['resource'],
+        },
+      }),
+    ).rejects.toThrow('Unsupported federation list resource');
+  });
+
+  it('does not leak another user mission task notes through team-scoped note reads', async () => {
+    const service = makeDbService();
+
+    const result = await service.list({
+      filter: {
+        resource: 'notes',
+        subjectUserId: SUBJECT_USER_ID,
+        includePersonal: false,
+        teamIds: [TEAM_ID],
+        limit: 10,
+        maxRowsPerQuery: 10,
+      },
+    });
+
+    const ids = result.items.map((item) => item['id']);
+    expect(ids).toEqual([SUBJECT_TEAM_NOTE_ID]);
+    expect(ids).not.toContain(OTHER_TEAM_NOTE_ID);
+  });
+
+  it('does not return subject personal mission task notes when includePersonal is false', async () => {
+    const service = makeDbService();
+
+    const result = await service.list({
+      filter: {
+        resource: 'notes',
+        subjectUserId: SUBJECT_USER_ID,
+        includePersonal: false,
+        teamIds: [TEAM_ID],
+        limit: 10,
+        maxRowsPerQuery: 10,
+      },
+    });
+
+    expect(result.items.map((item) => item['id'])).not.toContain(SUBJECT_PERSONAL_NOTE_ID);
+  });
+
+  it('does not return subject notes from missions outside the grant-visible project set', async () => {
+    const service = makeDbService();
+
+    const result = await service.list({
+      filter: {
+        resource: 'notes',
+        subjectUserId: SUBJECT_USER_ID,
+        includePersonal: true,
+        teamIds: [TEAM_ID],
+        limit: 10,
+        maxRowsPerQuery: 10,
+      },
+    });
+
+    const ids = result.items.map((item) => item['id']);
+    expect(ids).toContain(SUBJECT_PERSONAL_NOTE_ID);
+    expect(ids).toContain(SUBJECT_TEAM_NOTE_ID);
+    expect(ids).not.toContain(SUBJECT_UNAUTHORIZED_NOTE_ID);
+    expect(ids).not.toContain(OTHER_TEAM_NOTE_ID);
+  });
+
+  it('paginates memory deterministically across insights and preferences', async () => {
+    const service = makeDbService();
+    const filter: FederationScopeQueryFilter = {
+      resource: 'memory',
+      subjectUserId: SUBJECT_USER_ID,
+      includePersonal: true,
+      teamIds: [],
+      limit: 2,
+      maxRowsPerQuery: 2,
+    };
+
+    const firstPage = await service.list({ filter });
+    const secondPage = await service.list({ filter, cursor: firstPage.nextCursor });
+    const firstPageIds = firstPage.items.map((item) => item['id']);
+    const secondPageIds = secondPage.items.map((item) => item['id']);
+    const allIds = [...firstPageIds, ...secondPageIds];
+
+    expect(firstPage).toMatchObject({ truncated: true, nextCursor: expect.any(String) });
+    expect(firstPageIds).toEqual([INSIGHT_TWO_ID, INSIGHT_ONE_ID]);
+    expect(secondPageIds).toEqual([PREFERENCE_TWO_ID, PREFERENCE_ONE_ID]);
+    expect(new Set(allIds).size).toBe(allIds.length);
+  });
+});

apps/gateway/src/federation/server/verbs/__tests__/list.controller.spec.ts

@@ -0,0 +1,188 @@
+import 'reflect-metadata';
+import { RequestMethod } from '@nestjs/common';
+import type { FastifyRequest } from 'fastify';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { FederationAuthGuard } from '../../federation-auth.guard.js';
+import type {
+  FederationScopeEvaluationResult,
+  FederationScopeQueryFilter,
+} from '../../scope.service.js';
+import { ListController } from '../list.controller.js';
+import type { FederationListQueryResult } from '../list-query.service.js';
+
+const FEDERATION_CONTEXT = {
+  grantId: 'grant-1',
+  peerId: 'peer-1',
+  subjectUserId: 'user-1',
+  scope: { resources: ['tasks'], max_rows_per_query: 25 },
+};
+
+const TASK_FILTER: FederationScopeQueryFilter = {
+  resource: 'tasks',
+  subjectUserId: 'user-1',
+  includePersonal: true,
+  teamIds: ['team-1'],
+  limit: 10,
+  maxRowsPerQuery: 25,
+};
+
+function makeRequest(): FastifyRequest {
+  return { federationContext: FEDERATION_CONTEXT } as unknown as FastifyRequest;
+}
+
+function allowedScope(
+  filter: FederationScopeQueryFilter = TASK_FILTER,
+): FederationScopeEvaluationResult {
+  return { allowed: true, filter };
+}
+
+function makeController(opts?: {
+  scopeResult?: FederationScopeEvaluationResult;
+  queryResult?: FederationListQueryResult;
+}) {
+  const scope = {
+    evaluateAccess: vi.fn().mockResolvedValue(opts?.scopeResult ?? allowedScope()),
+  };
+  const query = {
+    evaluateReadAccess: vi.fn(),
+    list: vi.fn().mockResolvedValue(
+      opts?.queryResult ?? {
+        items: [
+          {
+            id: 'task-1',
+            title: 'Federated task',
+            createdAt: new Date('2026-06-24T00:00:00.000Z'),
+          },
+        ],
+        truncated: false,
+      },
+    ),
+  };
+
+  return {
+    controller: new ListController(scope as never, query as never),
+    scope,
+    query,
+  };
+}
+
+describe('ListController', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('declares POST /api/federation/v1/list/:resource protected only by FederationAuthGuard', () => {
+    expect(Reflect.getMetadata('path', ListController)).toBe('api/federation/v1/list');
+    expect(Reflect.getMetadata('path', ListController.prototype.list)).toBe(':resource');
+    expect(Reflect.getMetadata('method', ListController.prototype.list)).toBe(RequestMethod.POST);
+    expect(Reflect.getMetadata('__guards__', ListController)).toEqual([FederationAuthGuard]);
+  });
+
+  it('runs AuthGuard context through ScopeService and returns local-source tagged rows', async () => {
+    const { controller, scope, query } = makeController();
+
+    const response = await controller.list('tasks', makeRequest(), { limit: 10 });
+
+    expect(scope.evaluateAccess).toHaveBeenCalledWith({
+      context: FEDERATION_CONTEXT,
+      resource: 'tasks',
+      requestedLimit: 10,
+      nativeRbac: query,
+    });
+    expect(query.list).toHaveBeenCalledWith({ filter: TASK_FILTER, cursor: undefined });
+    expect(response).toEqual({
+      items: [
+        {
+          id: 'task-1',
+          title: 'Federated task',
+          createdAt: new Date('2026-06-24T00:00:00.000Z'),
+          _source: 'local',
+        },
+      ],
+    });
+  });
+
+  it('preserves pagination metadata when row cap truncates the query layer result', async () => {
+    const { controller } = makeController({
+      queryResult: {
+        items: [{ id: 'task-1' }],
+        nextCursor: 'cursor-2',
+        truncated: true,
+      },
+    });
+
+    const response = await controller.list('tasks', makeRequest(), { cursor: 'cursor-1' });
+
+    expect(response).toEqual({
+      items: [{ id: 'task-1', _source: 'local' }],
+      nextCursor: 'cursor-2',
+      _truncated: true,
+    });
+  });
+
+  it('returns a federation error envelope when auth guard context is missing', async () => {
+    const { controller, scope, query } = makeController();
+
+    await expect(
+      controller.list('tasks', {} as unknown as FastifyRequest, {}),
+    ).rejects.toMatchObject({
+      response: {
+        error: {
+          code: 'unauthorized',
+          message: 'Federation context missing',
+        },
+      },
+      status: 401,
+    });
+    expect(scope.evaluateAccess).not.toHaveBeenCalled();
+    expect(query.list).not.toHaveBeenCalled();
+  });
+
+  it('returns a federation error envelope when scope evaluation denies access', async () => {
+    const { controller, query } = makeController({
+      scopeResult: {
+        allowed: false,
+        deny: {
+          code: 'resource_excluded',
+          stage: 'resource_exclusion',
+          statusCode: 403,
+          message: 'Requested federation resource is explicitly excluded by grant scope',
+          grantId: 'grant-1',
+          peerId: 'peer-1',
+          subjectUserId: 'user-1',
+          resource: 'credentials',
+        },
+      },
+    });
+
+    await expect(controller.list('credentials', makeRequest(), {})).rejects.toMatchObject({
+      response: {
+        error: {
+          code: 'scope_violation',
+          message: 'Requested federation resource is explicitly excluded by grant scope',
+        },
+      },
+      status: 403,
+    });
+    expect(query.list).not.toHaveBeenCalled();
+  });
+
+  it('rejects malformed request body fields before querying storage', async () => {
+    const { controller, scope, query } = makeController();
+
+    await expect(controller.list('tasks', makeRequest(), { cursor: 123 })).rejects.toMatchObject({
+      response: { error: { code: 'invalid_request' } },
+      status: 400,
+    });
+    await expect(controller.list('tasks', makeRequest(), { limit: false })).rejects.toMatchObject({
+      response: { error: { code: 'invalid_request' } },
+      status: 400,
+    });
+    await expect(controller.list('tasks', makeRequest(), { limit: 'abc' })).rejects.toMatchObject({
+      response: { error: { code: 'invalid_request' } },
+      status: 400,
+    });
+    expect(scope.evaluateAccess).not.toHaveBeenCalled();
+    expect(query.list).not.toHaveBeenCalled();
+  });
+});

apps/gateway/src/federation/server/verbs/capabilities.controller.ts

@@ -0,0 +1,38 @@
+/**
+ * Federation capabilities verb (FED-M3-07).
+ *
+ * Returns the read-only capability envelope for the active grant attached by
+ * FederationAuthGuard. This endpoint intentionally does not invoke native RBAC
+ * or ScopeService: an active grant is enough to ask what the grant allows.
+ */
+
+import { Controller, Get, Req, UseGuards } from '@nestjs/common';
+import type { FastifyRequest } from 'fastify';
+import {
+  FEDERATION_VERBS,
+  type FederationCapabilitiesResponse,
+  type FederationVerb,
+} from '@mosaicstack/types';
+import { parseFederationScope } from '../../scope-schema.js';
+import { FederationAuthGuard } from '../federation-auth.guard.js';
+import '../federation-context.js';
+
+@Controller('api/federation/v1/capabilities')
+@UseGuards(FederationAuthGuard)
+export class CapabilitiesController {
+  @Get()
+  getCapabilities(@Req() request: FastifyRequest): FederationCapabilitiesResponse {
+    if (!request.federationContext) {
+      throw new Error('Federation context missing after auth guard');
+    }
+
+    const scope = parseFederationScope(request.federationContext.scope);
+
+    return {
+      resources: [...scope.resources],
+      excluded_resources: [...scope.excluded_resources],
+      max_rows_per_query: scope.max_rows_per_query,
+      supported_verbs: [...FEDERATION_VERBS] satisfies FederationVerb[],
+    };
+  }
+}

apps/gateway/src/federation/server/verbs/list-query.service.ts

@@ -0,0 +1,408 @@
+/**
+ * Federation list query layer (FED-M3-05).
+ *
+ * Read-only DB adapter used by ListController after FederationAuthGuard and
+ * FederationScopeService have established the subject user, allowed resource,
+ * native-RBAC intersection, and row cap. Audit writes are intentionally
+ * deferred to M4.
+ */
+
+import { Inject, Injectable } from '@nestjs/common';
+import {
+  and,
+  desc,
+  eq,
+  inArray,
+  insights,
+  isNotNull,
+  lt,
+  missionTasks,
+  missions,
+  or,
+  preferences,
+  projects,
+  tasks,
+  teamMembers,
+  type Db,
+} from '@mosaicstack/db';
+import type {
+  FederationNativeRbacEvaluator,
+  FederationNativeRbacRequest,
+  FederationNativeRbacResult,
+  FederationScopeQueryFilter,
+} from '../scope.service.js';
+import { DB } from '../../../database/database.module.js';
+
+export interface FederationListQueryRequest {
+  readonly filter: FederationScopeQueryFilter;
+  readonly cursor?: string;
+}
+
+export interface FederationListQueryResult<T extends object = Record<string, unknown>> {
+  readonly items: T[];
+  readonly nextCursor?: string;
+  readonly truncated: boolean;
+}
+
+type CursorSource = 'insights' | 'preferences';
+const CURSOR_SOURCE = Symbol('federationCursorSource');
+
+type RowObject = Record<string, unknown> & { readonly [CURSOR_SOURCE]?: CursorSource };
+
+interface KeysetCursor {
+  readonly createdAt: Date;
+  readonly id: string;
+  readonly source?: CursorSource;
+}
+
+function encodeCursor(row: RowObject): string {
+  const createdAt = row['createdAt'];
+  const id = row['id'];
+  if (!(createdAt instanceof Date) || typeof id !== 'string') {
+    throw new Error('Federation list cursor cannot be encoded');
+  }
+
+  const source = row[CURSOR_SOURCE];
+  return Buffer.from(
+    JSON.stringify({ createdAt: createdAt.toISOString(), id, ...(source ? { source } : {}) }),
+    'utf8',
+  ).toString('base64url');
+}
+
+function decodeCursor(cursor: string | undefined): KeysetCursor | undefined {
+  if (cursor === undefined) {
+    return undefined;
+  }
+
+  try {
+    const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')) as unknown;
+    if (typeof parsed !== 'object' || parsed === null) {
+      throw new Error('cursor must be an object');
+    }
+
+    const { createdAt, id, source } = parsed as {
+      createdAt?: unknown;
+      id?: unknown;
+      source?: unknown;
+    };
+    if (typeof createdAt !== 'string' || typeof id !== 'string' || id.length === 0) {
+      throw new Error('cursor is missing createdAt or id');
+    }
+    if (source !== undefined && source !== 'insights' && source !== 'preferences') {
+      throw new Error('cursor source is invalid');
+    }
+
+    const date = new Date(createdAt);
+    if (Number.isNaN(date.getTime())) {
+      throw new Error('cursor createdAt is invalid');
+    }
+
+    return { createdAt: date, id, ...(source ? { source } : {}) };
+  } catch {
+    throw new Error('Invalid federation list cursor');
+  }
+}
+
+function paginate<T extends RowObject>(rows: T[], limit: number): FederationListQueryResult<T> {
+  const page = rows.slice(0, limit);
+  const hasMore = rows.length > limit;
+  const nextCursor = hasMore ? encodeCursor(page[page.length - 1] ?? {}) : undefined;
+
+  return {
+    items: page,
+    truncated: hasMore,
+    ...(nextCursor !== undefined ? { nextCursor } : {}),
+  };
+}
+
+function markCursorSource<T extends RowObject>(row: T, source: CursorSource): T {
+  Object.defineProperty(row, CURSOR_SOURCE, {
+    value: source,
+    enumerable: false,
+    configurable: false,
+  });
+  return row;
+}
+
+function sortRows(rows: RowObject[]): RowObject[] {
+  return [...rows].sort((a, b) => {
+    const aTime = a['createdAt'] instanceof Date ? a['createdAt'].getTime() : 0;
+    const bTime = b['createdAt'] instanceof Date ? b['createdAt'].getTime() : 0;
+    if (aTime !== bTime) {
+      return bTime - aTime;
+    }
+    return String(b['id'] ?? '').localeCompare(String(a['id'] ?? ''));
+  });
+}
+
+@Injectable()
+export class FederationListQueryService implements FederationNativeRbacEvaluator {
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  async evaluateReadAccess(
+    request: FederationNativeRbacRequest,
+  ): Promise<FederationNativeRbacResult> {
+    if (request.resource === 'credentials' || request.resource === 'api_keys') {
+      return {
+        allowed: false,
+        reason: `${request.resource} federation list access is not implemented in M3`,
+        details: { resource: request.resource },
+      };
+    }
+
+    if (request.resource === 'memory') {
+      return { allowed: true, access: { includePersonal: true, teamIds: [] } };
+    }
+
+    const teamIds = await this.listSubjectTeamIds(request.subjectUserId);
+    return { allowed: true, access: { includePersonal: true, teamIds } };
+  }
+
+  async list<T extends RowObject = RowObject>(
+    request: FederationListQueryRequest,
+  ): Promise<FederationListQueryResult<T>> {
+    const cursor = decodeCursor(request.cursor);
+    const rows = await this.listAllRows(request.filter, request.filter.limit + 1, cursor);
+    return paginate(rows as T[], request.filter.limit);
+  }
+
+  private async listAllRows(
+    filter: FederationScopeQueryFilter,
+    rowLimit: number,
+    cursor: KeysetCursor | undefined,
+  ): Promise<RowObject[]> {
+    switch (filter.resource) {
+      case 'tasks':
+        return this.listTasks(filter, rowLimit, cursor);
+      case 'notes':
+        return this.listNotes(filter, rowLimit, cursor);
+      case 'memory':
+        return this.listMemory(filter, rowLimit, cursor);
+      case 'credentials':
+      case 'api_keys':
+        return [];
+      default:
+        throw new Error(`Unsupported federation list resource: ${String(filter.resource)}`);
+    }
+  }
+
+  private async listSubjectTeamIds(subjectUserId: string): Promise<string[]> {
+    const rows = await this.db
+      .select({ teamId: teamMembers.teamId })
+      .from(teamMembers)
+      .where(eq(teamMembers.userId, subjectUserId));
+
+    return rows.map((row) => row.teamId);
+  }
+
+  private async listAccessibleProjectIds(filter: FederationScopeQueryFilter): Promise<string[]> {
+    const clauses = [];
+    if (filter.includePersonal) {
+      clauses.push(and(eq(projects.ownerType, 'user'), eq(projects.ownerId, filter.subjectUserId)));
+    }
+    if (filter.teamIds.length > 0) {
+      clauses.push(
+        and(eq(projects.ownerType, 'team'), inArray(projects.teamId, [...filter.teamIds])),
+      );
+    }
+
+    if (clauses.length === 0) {
+      return [];
+    }
+
+    const rows = await this.db
+      .select({ id: projects.id })
+      .from(projects)
+      .where(clauses.length === 1 ? clauses[0] : or(...clauses));
+
+    return rows.map((row) => row.id);
+  }
+
+  private async listMissionIds(projectIds: readonly string[]): Promise<string[]> {
+    if (projectIds.length === 0) {
+      return [];
+    }
+
+    const rows = await this.db
+      .select({ id: missions.id })
+      .from(missions)
+      .where(inArray(missions.projectId, [...projectIds]));
+
+    return rows.map((row) => row.id);
+  }
+
+  private async listTasks(
+    filter: FederationScopeQueryFilter,
+    rowLimit: number,
+    cursor: KeysetCursor | undefined,
+  ): Promise<RowObject[]> {
+    const projectIds = await this.listAccessibleProjectIds(filter);
+    const missionIds = await this.listMissionIds(projectIds);
+    const clauses = [];
+
+    if (projectIds.length > 0) {
+      clauses.push(inArray(tasks.projectId, projectIds));
+    }
+    if (missionIds.length > 0) {
+      clauses.push(inArray(tasks.missionId, missionIds));
+    }
+
+    if (clauses.length === 0) {
+      return [];
+    }
+
+    const scopeClause = clauses.length === 1 ? clauses[0] : or(...clauses);
+    const cursorClause = cursor
+      ? or(
+          lt(tasks.createdAt, cursor.createdAt),
+          and(eq(tasks.createdAt, cursor.createdAt), lt(tasks.id, cursor.id)),
+        )
+      : undefined;
+
+    const rows = await this.db
+      .select({
+        id: tasks.id,
+        title: tasks.title,
+        description: tasks.description,
+        status: tasks.status,
+        priority: tasks.priority,
+        projectId: tasks.projectId,
+        missionId: tasks.missionId,
+        assignee: tasks.assignee,
+        tags: tasks.tags,
+        dueDate: tasks.dueDate,
+        metadata: tasks.metadata,
+        createdAt: tasks.createdAt,
+        updatedAt: tasks.updatedAt,
+      })
+      .from(tasks)
+      .where(and(scopeClause, cursorClause))
+      .orderBy(desc(tasks.createdAt), desc(tasks.id))
+      .limit(rowLimit);
+
+    return sortRows(rows as RowObject[]);
+  }
+
+  private async listNotes(
+    filter: FederationScopeQueryFilter,
+    rowLimit: number,
+    cursor: KeysetCursor | undefined,
+  ): Promise<RowObject[]> {
+    const projectIds = await this.listAccessibleProjectIds(filter);
+    const missionIds = await this.listMissionIds(projectIds);
+
+    if (missionIds.length === 0) {
+      return [];
+    }
+
+    // mission_tasks rows are user-scoped even when the mission belongs to a team.
+    // Team visibility can narrow the mission set, but it must never widen the
+    // query to other users' mission task notes.
+    const scopeClause = and(
+      eq(missionTasks.userId, filter.subjectUserId),
+      inArray(missionTasks.missionId, missionIds),
+    );
+    const cursorClause = cursor
+      ? or(
+          lt(missionTasks.createdAt, cursor.createdAt),
+          and(eq(missionTasks.createdAt, cursor.createdAt), lt(missionTasks.id, cursor.id)),
+        )
+      : undefined;
+
+    const rows = await this.db
+      .select({
+        id: missionTasks.id,
+        missionId: missionTasks.missionId,
+        taskId: missionTasks.taskId,
+        status: missionTasks.status,
+        content: missionTasks.notes,
+        createdAt: missionTasks.createdAt,
+        updatedAt: missionTasks.updatedAt,
+      })
+      .from(missionTasks)
+      .where(and(scopeClause, cursorClause, isNotNull(missionTasks.notes)))
+      .orderBy(desc(missionTasks.createdAt), desc(missionTasks.id))
+      .limit(rowLimit);
+
+    return sortRows(rows.filter((row) => row.content !== '') as RowObject[]);
+  }
+
+  private async listMemory(
+    filter: FederationScopeQueryFilter,
+    rowLimit: number,
+    cursor: KeysetCursor | undefined,
+  ): Promise<RowObject[]> {
+    if (!filter.includePersonal) {
+      return [];
+    }
+    if (cursor && cursor.source === undefined) {
+      throw new Error('Invalid federation list cursor');
+    }
+
+    const rows: RowObject[] = [];
+
+    // Memory spans two physical tables. To keep pagination deterministic and
+    // resumable without a SQL UNION, M3 emits a fixed block order: all insights
+    // first, then preferences. The opaque cursor records which table produced
+    // the boundary row, so the next page never re-applies one table's keyset to
+    // the other table (which could duplicate/skip rows at equal timestamps).
+    if (cursor?.source !== 'preferences') {
+      const insightCursorClause = cursor
+        ? or(
+            lt(insights.createdAt, cursor.createdAt),
+            and(eq(insights.createdAt, cursor.createdAt), lt(insights.id, cursor.id)),
+          )
+        : undefined;
+      const insightRows = await this.db
+        .select({
+          id: insights.id,
+          kind: insights.source,
+          content: insights.content,
+          category: insights.category,
+          relevanceScore: insights.relevanceScore,
+          metadata: insights.metadata,
+          createdAt: insights.createdAt,
+          updatedAt: insights.updatedAt,
+        })
+        .from(insights)
+        .where(and(eq(insights.userId, filter.subjectUserId), insightCursorClause))
+        .orderBy(desc(insights.createdAt), desc(insights.id))
+        .limit(rowLimit);
+
+      rows.push(...(insightRows as RowObject[]).map((row) => markCursorSource(row, 'insights')));
+    }
+
+    const remaining = rowLimit - rows.length;
+    if (remaining <= 0) {
+      return rows;
+    }
+
+    const preferenceCursorClause =
+      cursor?.source === 'preferences'
+        ? or(
+            lt(preferences.createdAt, cursor.createdAt),
+            and(eq(preferences.createdAt, cursor.createdAt), lt(preferences.id, cursor.id)),
+          )
+        : undefined;
+    const preferenceRows = await this.db
+      .select({
+        id: preferences.id,
+        kind: preferences.category,
+        key: preferences.key,
+        value: preferences.value,
+        source: preferences.source,
+        mutable: preferences.mutable,
+        createdAt: preferences.createdAt,
+        updatedAt: preferences.updatedAt,
+      })
+      .from(preferences)
+      .where(and(eq(preferences.userId, filter.subjectUserId), preferenceCursorClause))
+      .orderBy(desc(preferences.createdAt), desc(preferences.id))
+      .limit(remaining);
+
+    rows.push(
+      ...(preferenceRows as RowObject[]).map((row) => markCursorSource(row, 'preferences')),
+    );
+    return rows;
+  }
+}

apps/gateway/src/federation/server/verbs/list.controller.ts

@@ -0,0 +1,147 @@
+/**
+ * Federation list verb (FED-M3-05).
+ *
+ * POST /api/federation/v1/list/:resource
+ *
+ * Pipeline: FederationAuthGuard attaches the active grant context, then
+ * FederationScopeService enforces grant scope + native RBAC intersection, then
+ * the read-only query layer returns capped rows tagged with `_source`. Read
+ * audit-log writes are deferred to M4; this controller does not persist request
+ * or response bodies.
+ */
+
+import {
+  Body,
+  Controller,
+  HttpException,
+  Inject,
+  Param,
+  Post,
+  Req,
+  UseGuards,
+} from '@nestjs/common';
+import type { FastifyRequest } from 'fastify';
+import {
+  FederationInvalidRequestError,
+  FederationScopeViolationError,
+  FederationUnauthorizedError,
+  SOURCE_LOCAL,
+  tagWithSource,
+  type FederationListResponse,
+  type SourceTag,
+} from '@mosaicstack/types';
+import { FederationAuthGuard } from '../federation-auth.guard.js';
+import '../federation-context.js';
+import { FederationScopeService } from '../scope.service.js';
+import { FederationListQueryService } from './list-query.service.js';
+
+interface FederationListRequestBody {
+  readonly limit?: unknown;
+  readonly cursor?: unknown;
+}
+
+type FederatedRow = Record<string, unknown> & SourceTag;
+
+function parseLimit(body: FederationListRequestBody | undefined): number | undefined {
+  if (body?.limit === undefined) {
+    return undefined;
+  }
+
+  const parsed =
+    typeof body.limit === 'number'
+      ? body.limit
+      : typeof body.limit === 'string' && body.limit.trim().length > 0
+        ? Number(body.limit)
+        : Number.NaN;
+
+  if (!Number.isSafeInteger(parsed) || parsed < 1) {
+    throw new HttpException(
+      new FederationInvalidRequestError(
+        'Federation list limit must be a positive integer',
+      ).toEnvelope(),
+      400,
+    );
+  }
+
+  return parsed;
+}
+
+function parseCursor(body: FederationListRequestBody | undefined): string | undefined {
+  if (body?.cursor === undefined) {
+    return undefined;
+  }
+  if (typeof body.cursor === 'string') {
+    return body.cursor;
+  }
+  throw new HttpException(
+    new FederationInvalidRequestError('Federation list cursor must be a string').toEnvelope(),
+    400,
+  );
+}
+
+@Controller('api/federation/v1/list')
+@UseGuards(FederationAuthGuard)
+export class ListController {
+  constructor(
+    @Inject(FederationScopeService) private readonly scope: FederationScopeService,
+    @Inject(FederationListQueryService) private readonly query: FederationListQueryService,
+  ) {}
+
+  @Post(':resource')
+  async list(
+    @Param('resource') resource: string,
+    @Req() request: FastifyRequest,
+    @Body() body?: FederationListRequestBody,
+  ): Promise<FederationListResponse<FederatedRow>> {
+    if (!request.federationContext) {
+      throw new HttpException(
+        new FederationUnauthorizedError('Federation context missing').toEnvelope(),
+        401,
+      );
+    }
+
+    const requestedLimit = parseLimit(body);
+    const cursor = parseCursor(body);
+    const scopeResult = await this.scope.evaluateAccess({
+      context: request.federationContext,
+      resource,
+      requestedLimit,
+      nativeRbac: this.query,
+    });
+
+    if (!scopeResult.allowed) {
+      const ErrorClass =
+        scopeResult.deny.statusCode === 400
+          ? FederationInvalidRequestError
+          : FederationScopeViolationError;
+      throw new HttpException(
+        new ErrorClass(scopeResult.deny.message, scopeResult.deny).toEnvelope(),
+        scopeResult.deny.statusCode,
+      );
+    }
+
+    let result: Awaited<ReturnType<FederationListQueryService['list']>>;
+    try {
+      result = await this.query.list({ filter: scopeResult.filter, cursor });
+    } catch (error: unknown) {
+      if (error instanceof Error && error.message === 'Invalid federation list cursor') {
+        throw new HttpException(
+          new FederationInvalidRequestError('Federation list cursor is invalid').toEnvelope(),
+          400,
+        );
+      }
+      throw error;
+    }
+
+    const response: FederationListResponse<FederatedRow> = {
+      items: tagWithSource(result.items, SOURCE_LOCAL),
+    };
+    if (result.nextCursor !== undefined) {
+      response.nextCursor = result.nextCursor;
+    }
+    if (result.truncated) {
+      response._truncated = true;
+    }
+    return response;
+  }
+}

apps/gateway/src/gc/session-gc.service.spec.ts

@@ -12,7 +12,12 @@ type MockRedis = {
 describe('SessionGCService', () => {
   let service: SessionGCService;
   let mockRedis: MockRedis;
-  let mockLogService: { logs: { promoteToWarm: ReturnType<typeof vi.fn> } };
+  let mockLogService: {
+    logs: {
+      promoteSessionToWarm: ReturnType<typeof vi.fn>;
+      promoteToWarm: ReturnType<typeof vi.fn>;
+    };
+  };
 
   /**
    * Helper: build a scan mock that returns all provided keys in a single
@@ -30,6 +35,7 @@ describe('SessionGCService', () => {
 
     mockLogService = {
       logs: {
+        promoteSessionToWarm: vi.fn().mockResolvedValue(0),
         promoteToWarm: vi.fn().mockResolvedValue(0),
       },
     };
@@ -64,49 +70,18 @@ describe('SessionGCService', () => {
     expect(result.sessionId).toBe('test-session-id');
   });
 
-  it('fullCollect() deletes all session keys', async () => {
-    mockRedis.scan = makeScanMock(['mosaic:session:abc:system', 'mosaic:session:xyz:foo']);
-    const result = await service.fullCollect();
-    expect(mockRedis.del).toHaveBeenCalled();
-    expect(result.valkeyKeys).toBe(2);
+  it('collect() demotes logs only for the requested session', async () => {
+    await service.collect('owned-session');
+
+    expect(mockLogService.logs.promoteSessionToWarm).toHaveBeenCalledWith(
+      'owned-session',
+      expect.any(Date),
+    );
+    expect(mockLogService.logs.promoteToWarm).not.toHaveBeenCalled();
   });
 
-  it('fullCollect() with no keys returns 0 valkeyKeys', async () => {
-    mockRedis.scan = makeScanMock([]);
-    const result = await service.fullCollect();
-    expect(result.valkeyKeys).toBe(0);
-    expect(mockRedis.del).not.toHaveBeenCalled();
-  });
-
-  it('fullCollect() returns duration', async () => {
-    const result = await service.fullCollect();
-    expect(result.duration).toBeGreaterThanOrEqual(0);
-  });
-
-  it('sweepOrphans() extracts unique session IDs and collects them', async () => {
-    // First scan call returns the global session list; subsequent calls return
-    // per-session keys during collect().
-    mockRedis.scan = vi
-      .fn()
-      .mockResolvedValueOnce([
-        '0',
-        ['mosaic:session:abc:system', 'mosaic:session:abc:messages', 'mosaic:session:xyz:system'],
-      ])
-      // collect('abc') scan
-      .mockResolvedValueOnce(['0', ['mosaic:session:abc:system', 'mosaic:session:abc:messages']])
-      // collect('xyz') scan
-      .mockResolvedValueOnce(['0', ['mosaic:session:xyz:system']]);
-    mockRedis.del.mockResolvedValue(1);
-
-    const result = await service.sweepOrphans();
-    expect(result.orphanedSessions).toBeGreaterThanOrEqual(0);
-    expect(result.duration).toBeGreaterThanOrEqual(0);
-  });
-
-  it('sweepOrphans() returns empty when no session keys', async () => {
-    mockRedis.scan = makeScanMock([]);
-    const result = await service.sweepOrphans();
-    expect(result.orphanedSessions).toBe(0);
-    expect(result.totalCleaned).toHaveLength(0);
+  it('does not expose automatic global GC entry points', () => {
+    expect('fullCollect' in service).toBe(false);
+    expect('sweepOrphans' in service).toBe(false);
   });
 });

apps/gateway/src/gc/session-gc.service.ts

@@ -1,4 +1,4 @@
-import { Inject, Injectable, Logger, type OnModuleInit } from '@nestjs/common';
+import { Inject, Injectable } from '@nestjs/common';
 import type { QueueHandle } from '@mosaicstack/queue';
 import type { LogService } from '@mosaicstack/log';
 import { LOG_SERVICE } from '../log/log.tokens.js';
@@ -13,49 +13,13 @@ export interface GCResult {
   };
 }
 
-export interface GCSweepResult {
-  orphanedSessions: number;
-  totalCleaned: GCResult[];
-  duration: number;
-}
-
-export interface FullGCResult {
-  valkeyKeys: number;
-  logsDemoted: number;
-  jobsPurged: number;
-  tempFilesRemoved: number;
-  duration: number;
-}
-
 @Injectable()
-export class SessionGCService implements OnModuleInit {
-  private readonly logger = new Logger(SessionGCService.name);
-
+export class SessionGCService {
   constructor(
     @Inject(REDIS) private readonly redis: QueueHandle['redis'],
     @Inject(LOG_SERVICE) private readonly logService: LogService,
   ) {}
 
-  onModuleInit(): void {
-    // Fire-and-forget: run full GC asynchronously so it does not block the
-    // NestJS bootstrap chain.  Cold-start GC typically takes 100–500 ms
-    // depending on Valkey key count; deferring it removes that latency from
-    // the TTFB of the first HTTP request.
-    this.fullCollect()
-      .then((result) => {
-        this.logger.log(
-          `Full GC complete: ${result.valkeyKeys} Valkey keys, ` +
-            `${result.logsDemoted} logs demoted, ` +
-            `${result.jobsPurged} jobs purged, ` +
-            `${result.tempFilesRemoved} temp dirs removed ` +
-            `(${result.duration}ms)`,
-        );
-      })
-      .catch((err: unknown) => {
-        this.logger.error('Cold-start GC failed', err instanceof Error ? err.stack : String(err));
-      });
-  }
-
   /**
    * Scan Valkey for all keys matching a pattern using SCAN (non-blocking).
    * KEYS is avoided because it blocks the Valkey event loop for the full scan
@@ -86,79 +50,13 @@ export class SessionGCService implements OnModuleInit {
       result.cleaned.valkeyKeys = valkeyKeys.length;
     }
 
-    // 2. PG: demote hot-tier agent_logs for this session to warm
-    const cutoff = new Date(); // demote all hot logs for this session
-    const logsDemoted = await this.logService.logs.promoteToWarm(cutoff);
+    // 2. PG: demote hot-tier agent logs for this session only.
+    const cutoff = new Date();
+    const logsDemoted = await this.logService.logs.promoteSessionToWarm(sessionId, cutoff);
     if (logsDemoted > 0) {
       result.cleaned.logsDemoted = logsDemoted;
     }
 
     return result;
   }
-
-  /**
-   * Sweep GC — find orphaned artifacts from dead sessions.
-   * System-wide operation: only call from admin-authorized paths or internal
-   * scheduled jobs.  Individual session cleanup is handled by collect().
-   */
-  async sweepOrphans(): Promise<GCSweepResult> {
-    const start = Date.now();
-    const cleaned: GCResult[] = [];
-
-    // 1. Find all session-scoped Valkey keys (non-blocking SCAN)
-    const allSessionKeys = await this.scanKeys('mosaic:session:*');
-
-    // Extract unique session IDs from keys
-    const sessionIds = new Set<string>();
-    for (const key of allSessionKeys) {
-      const match = key.match(/^mosaic:session:([^:]+):/);
-      if (match) sessionIds.add(match[1]!);
-    }
-
-    // 2. For each session ID, collect stale keys
-    for (const sessionId of sessionIds) {
-      const gcResult = await this.collect(sessionId);
-      if (Object.keys(gcResult.cleaned).length > 0) {
-        cleaned.push(gcResult);
-      }
-    }
-
-    return {
-      orphanedSessions: cleaned.length,
-      totalCleaned: cleaned,
-      duration: Date.now() - start,
-    };
-  }
-
-  /**
-   * Full GC — aggressive collection for cold start.
-   * Assumes no sessions survived the restart.
-   */
-  async fullCollect(): Promise<FullGCResult> {
-    const start = Date.now();
-
-    // 1. Valkey: delete ALL session-scoped keys (non-blocking SCAN)
-    const sessionKeys = await this.scanKeys('mosaic:session:*');
-    if (sessionKeys.length > 0) {
-      await this.redis.del(...sessionKeys);
-    }
-
-    // 2. NOTE: channel keys are NOT collected on cold start
-    //    (discord/telegram plugins may reconnect and resume)
-
-    // 3. PG: demote stale hot-tier logs older than 24h to warm
-    const hotCutoff = new Date(Date.now() - 24 * 60 * 60 * 1000);
-    const logsDemoted = await this.logService.logs.promoteToWarm(hotCutoff);
-
-    // 4. No summarization job purge API available yet
-    const jobsPurged = 0;
-
-    return {
-      valkeyKeys: sessionKeys.length,
-      logsDemoted,
-      jobsPurged,
-      tempFilesRemoved: 0,
-      duration: Date.now() - start,
-    };
-  }
 }

apps/gateway/src/log/cron.service.ts

@@ -6,11 +6,10 @@ import {
   type OnModuleDestroy,
 } from '@nestjs/common';
 import { SummarizationService } from './summarization.service.js';
-import { SessionGCService } from '../gc/session-gc.service.js';
 import {
   QueueService,
-  QUEUE_SUMMARIZATION,
   QUEUE_GC,
+  QUEUE_SUMMARIZATION,
   QUEUE_TIER_MANAGEMENT,
 } from '../queue/queue.service.js';
 import type { Worker } from 'bullmq';
@@ -23,14 +22,12 @@ export class CronService implements OnModuleInit, OnModuleDestroy {
 
   constructor(
     @Inject(SummarizationService) private readonly summarization: SummarizationService,
-    @Inject(SessionGCService) private readonly sessionGC: SessionGCService,
     @Inject(QueueService) private readonly queueService: QueueService,
   ) {}
 
   async onModuleInit(): Promise<void> {
     const summarizationSchedule = process.env['SUMMARIZATION_CRON'] ?? '0 */6 * * *'; // every 6 hours
     const tierManagementSchedule = process.env['TIER_MANAGEMENT_CRON'] ?? '0 3 * * *'; // daily at 3am
-    const gcSchedule = process.env['SESSION_GC_CRON'] ?? '0 4 * * *'; // daily at 4am
 
     // M6-003: Summarization repeatable job
     await this.queueService.addRepeatableJob(
@@ -56,15 +53,12 @@ export class CronService implements OnModuleInit, OnModuleDestroy {
     });
     this.registeredWorkers.push(tierWorker);
 
-    // M6-004: GC repeatable job
-    await this.queueService.addRepeatableJob(QUEUE_GC, 'session-gc', {}, gcSchedule);
-    const gcWorker = this.queueService.registerWorker(QUEUE_GC, async () => {
-      await this.sessionGC.sweepOrphans();
-    });
-    this.registeredWorkers.push(gcWorker);
+    // Retire any repeatable global GC schedule created by older deployments.
+    // Session cleanup is now triggered only by an authorized session lifecycle operation.
+    await this.queueService.removeRepeatableJobs(QUEUE_GC, 'session-gc');
 
     this.logger.log(
-      `BullMQ jobs scheduled: summarization="${summarizationSchedule}", tier="${tierManagementSchedule}", gc="${gcSchedule}"`,
+      `BullMQ jobs scheduled: summarization="${summarizationSchedule}", tier="${tierManagementSchedule}"`,
     );
   }
 

apps/gateway/src/mcp/mcp.controller.ts

@@ -3,7 +3,11 @@ import { Logger } from '@nestjs/common';
 import { fromNodeHeaders } from 'better-auth/node';
 import type { Auth } from '@mosaicstack/auth';
 import type { NestFastifyApplication } from '@nestjs/platform-fastify';
-import type { McpService } from './mcp.service.js';
+import {
+  createMcpActorContext,
+  deriveMcpToolScopesForUser,
+  type McpService,
+} from './mcp.service.js';
 import { AUTH } from '../auth/auth.tokens.js';
 
 /**
@@ -67,14 +71,25 @@ async function handleMcpRequest(
     return;
   }
 
-  const userId = result.user.id;
+  const authUser = result.user as {
+    id: string;
+    role?: string | null;
+    tenantId?: string | null;
+    organizationId?: string | null;
+  };
+  const actor = createMcpActorContext({
+    userId: authUser.id,
+    role: authUser.role,
+    tenantId: authUser.tenantId ?? authUser.organizationId ?? undefined,
+    scopes: deriveMcpToolScopesForUser({ role: authUser.role }),
+  });
 
   // ─── Session routing ─────────────────────────────────────────────────────
   const sessionId = req.raw.headers['mcp-session-id'];
 
   if (typeof sessionId === 'string' && sessionId.length > 0) {
     // Existing session request
-    const transport = mcpService.getSession(sessionId);
+    const transport = mcpService.getSession(sessionId, actor);
     if (!transport) {
       logger.warn(`MCP session not found: ${sessionId}`);
       reply.raw.writeHead(404, { 'Content-Type': 'application/json' });
@@ -112,8 +127,10 @@ async function handleMcpRequest(
   }
 
   // Create new session and handle this initializing request
-  const { transport } = mcpService.createSession(userId);
-  logger.log(`New MCP session created for user ${userId}`);
+  const { transport } = mcpService.createSession(actor);
+  logger.log(
+    `New MCP session created for actor=${actor.userId} tenant=${actor.tenantId} correlation=${actor.correlationId}`,
+  );
 
   await transport.handleRequest(req.raw, reply.raw, body);
 }

apps/gateway/src/mcp/mcp.service.spec.ts

@@ -0,0 +1,461 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Brain } from '@mosaicstack/brain';
+import type { Memory } from '@mosaicstack/memory';
+import type { EmbeddingService } from '../memory/embedding.service.js';
+import type { CoordService } from '../coord/coord.service.js';
+import {
+  assertMcpToolAuthorized,
+  createMcpActorContext,
+  deriveMcpToolScopesForUser,
+  MCP_TOOL_SCOPES,
+  McpService,
+  type McpToolName,
+} from './mcp.service.js';
+
+type ToolResult = { content: Array<{ type: 'text'; text: string }> };
+type ToolHandler = (params: Record<string, unknown>) => Promise<ToolResult>;
+
+interface CapturedTool {
+  inputSchema: z.ZodType;
+  handler: ToolHandler;
+}
+
+function makeCapturingServer(): { server: McpServer; tools: Map<string, CapturedTool> } {
+  const tools = new Map<string, CapturedTool>();
+  const server = {
+    registerTool(name: string, config: { inputSchema: z.ZodType }, handler: ToolHandler): void {
+      tools.set(name, { inputSchema: config.inputSchema, handler });
+    },
+  };
+  return { server: server as unknown as McpServer, tools };
+}
+
+function makeService(opts?: {
+  projects?: Array<Record<string, unknown> & { id: string; ownerId?: string | null }>;
+  missions?: Array<
+    Record<string, unknown> & { id: string; projectId?: string | null; userId?: string | null }
+  >;
+  tasks?: Array<
+    Record<string, unknown> & {
+      id: string;
+      projectId?: string | null;
+      missionId?: string | null;
+      status?: string;
+    }
+  >;
+}) {
+  const projects = opts?.projects ?? [];
+  const missions = opts?.missions ?? [];
+  const tasks = opts?.tasks ?? [];
+  const brain = {
+    projects: {
+      findAll: vi.fn(async () => projects),
+      findById: vi.fn(async (id: string) => projects.find((project) => project.id === id) ?? null),
+    },
+    tasks: {
+      findAll: vi.fn(async () => tasks),
+      findById: vi.fn(async (id: string) => tasks.find((task) => task.id === id) ?? null),
+      findByProject: vi.fn(async (projectId: string) =>
+        tasks.filter((task) => task.projectId === projectId),
+      ),
+      findByMission: vi.fn(async (missionId: string) =>
+        tasks.filter((task) => task.missionId === missionId),
+      ),
+      findByStatus: vi.fn(async (status: string) => tasks.filter((task) => task.status === status)),
+      create: vi.fn(async (task: Record<string, unknown>) => ({ id: 'task-1', ...task })),
+      update: vi.fn(async (id: string, updates: Record<string, unknown>) => ({ id, ...updates })),
+    },
+    missions: {
+      findAll: vi.fn(async () => missions),
+      findById: vi.fn(async (id: string) => missions.find((mission) => mission.id === id) ?? null),
+      findByProject: vi.fn(async (projectId: string) =>
+        missions.filter((mission) => mission.projectId === projectId),
+      ),
+    },
+    conversations: {
+      findAll: vi.fn(async (userId: string) => [{ id: 'conversation-1', userId }]),
+    },
+  } as unknown as Brain;
+
+  const memory = {
+    insights: {
+      searchByEmbedding: vi.fn(async (userId: string) => [{ id: 'insight-1', userId }]),
+      create: vi.fn(async (insight: Record<string, unknown>) => ({ id: 'insight-2', ...insight })),
+    },
+    preferences: {
+      findByUser: vi.fn(async (userId: string) => [{ key: 'theme', userId }]),
+      findByUserAndCategory: vi.fn(async (userId: string, category: string) => [
+        { key: 'theme', userId, category },
+      ]),
+      upsert: vi.fn(async (preference: Record<string, unknown>) => ({
+        id: 'pref-1',
+        ...preference,
+      })),
+    },
+  } as unknown as Memory;
+
+  const embeddings = {
+    available: true,
+    embed: vi.fn(async () => [0.1, 0.2, 0.3]),
+  } as unknown as EmbeddingService;
+
+  const coord = {
+    getMissionStatus: vi.fn(async () => null),
+    listTasks: vi.fn(async () => []),
+    getTaskStatus: vi.fn(async () => null),
+  } as unknown as CoordService;
+
+  return {
+    service: new McpService(brain, memory, embeddings, coord),
+    brain: brain as unknown as {
+      conversations: { findAll: ReturnType<typeof vi.fn> };
+      tasks: {
+        create: ReturnType<typeof vi.fn>;
+        update: ReturnType<typeof vi.fn>;
+      };
+    },
+    memory: memory as unknown as {
+      insights: { searchByEmbedding: ReturnType<typeof vi.fn> };
+    },
+    coord: coord as unknown as {
+      listTasks: ReturnType<typeof vi.fn>;
+    },
+  };
+}
+
+function getTool(tools: Map<string, CapturedTool>, name: McpToolName): CapturedTool {
+  const tool = tools.get(name);
+  if (!tool) throw new Error(`Missing captured tool ${name}`);
+  return tool;
+}
+
+function makeMemberActor(userId = 'authenticated-user') {
+  return createMcpActorContext({
+    userId,
+    role: 'member',
+    scopes: deriveMcpToolScopesForUser({ role: 'member' }),
+  });
+}
+
+function makeAdminActor(userId = 'admin-user', tenantId?: string) {
+  return createMcpActorContext({
+    userId,
+    tenantId,
+    role: 'admin',
+    scopes: deriveMcpToolScopesForUser({ role: 'admin' }),
+  });
+}
+
+function makePlatformAdminActor(userId = 'platform-admin-user') {
+  return createMcpActorContext({
+    userId,
+    role: 'platform-admin',
+    scopes: deriveMcpToolScopesForUser({ role: 'platform-admin' }),
+  });
+}
+
+describe('MCP actor identity and tool scope enforcement', () => {
+  it('derives immutable actor, tenant, channel, correlation, and explicit tool scopes server-side', () => {
+    const actor = createMcpActorContext({
+      userId: ' user-authenticated ',
+      role: 'member',
+      scopes: deriveMcpToolScopesForUser({ role: 'member' }),
+    });
+
+    expect(actor.userId).toBe('user-authenticated');
+    expect(actor.tenantId).toBe('user:user-authenticated');
+    expect(actor.role).toBe('member');
+    expect(actor.channel).toBe('mcp');
+    expect(actor.correlationId).toMatch(/[0-9a-f-]{36}/i);
+    expect(actor.scopes.has(MCP_TOOL_SCOPES.memory_search)).toBe(true);
+    expect(actor.scopes.has(MCP_TOOL_SCOPES.coord_list_tasks)).toBe(false);
+    expect(
+      deriveMcpToolScopesForUser({ role: 'admin' }).has(MCP_TOOL_SCOPES.coord_list_tasks),
+    ).toBe(false);
+    expect(
+      deriveMcpToolScopesForUser({ role: 'platform-admin' }).has(MCP_TOOL_SCOPES.coord_list_tasks),
+    ).toBe(true);
+  });
+
+  it('fails closed when scopes are not supplied by the authenticated context policy', () => {
+    const actor = createMcpActorContext({ userId: 'user-authenticated' });
+
+    expect(actor.scopes.size).toBe(0);
+    expect(() => assertMcpToolAuthorized(actor, 'memory_search', { query: 'notes' })).toThrow(
+      'MCP tool scope denied: memory:insight:read',
+    );
+  });
+
+  it('fails closed when a tool caller supplies actor or tenant identity fields', () => {
+    const actor = createMcpActorContext({ userId: 'user-authenticated' });
+
+    expect(() =>
+      assertMcpToolAuthorized(actor, 'memory_search', {
+        userId: 'victim-user',
+        query: 'private data',
+      }),
+    ).toThrow('MCP caller-controlled identity field is forbidden: userId');
+
+    expect(() =>
+      assertMcpToolAuthorized(actor, 'coord_list_tasks', {
+        tenantId: 'victim-tenant',
+        projectPath: '/tmp/project',
+      }),
+    ).toThrow('MCP caller-controlled identity field is forbidden: tenantId');
+
+    expect(() =>
+      assertMcpToolAuthorized(actor, 'brain_create_task', {
+        title: 'forged org',
+        organizationId: 'victim-org',
+      }),
+    ).toThrow('MCP caller-controlled identity field is forbidden: organizationId');
+
+    expect(() =>
+      assertMcpToolAuthorized(actor, 'brain_update_task', {
+        title: 'forged team',
+        teamId: 'victim-team',
+      }),
+    ).toThrow('MCP caller-controlled identity field is forbidden: teamId');
+  });
+
+  it('fails closed when the server-derived actor lacks the required per-tool scope', () => {
+    const actor = createMcpActorContext({ userId: 'user-authenticated', scopes: [] });
+
+    expect(() => assertMcpToolAuthorized(actor, 'memory_search', { query: 'notes' })).toThrow(
+      'MCP tool scope denied: memory:insight:read',
+    );
+  });
+
+  it('removes caller-controlled userId from memory schemas and never queries victim memory', async () => {
+    const { service, memory } = makeService();
+    const { server, tools } = makeCapturingServer();
+    const actor = makeMemberActor('authenticated-user');
+
+    service.registerTools(server, actor);
+    const tool = getTool(tools, 'memory_search');
+
+    expect(tool.inputSchema.safeParse({ userId: 'victim-user', query: 'anything' }).success).toBe(
+      false,
+    );
+    await expect(tool.handler({ userId: 'victim-user', query: 'anything' })).rejects.toThrow(
+      'MCP caller-controlled identity field is forbidden: userId',
+    );
+    expect(memory.insights.searchByEmbedding).not.toHaveBeenCalled();
+
+    await tool.handler({ query: 'only my notes' });
+    expect(memory.insights.searchByEmbedding).toHaveBeenCalledWith(
+      'authenticated-user',
+      [0.1, 0.2, 0.3],
+      5,
+    );
+  });
+
+  it('binds conversation listing to the authenticated actor instead of a caller-supplied userId', async () => {
+    const { service, brain } = makeService();
+    const { server, tools } = makeCapturingServer();
+    const actor = makeMemberActor('authenticated-user');
+
+    service.registerTools(server, actor);
+    const tool = getTool(tools, 'brain_list_conversations');
+
+    expect(tool.inputSchema.safeParse({ userId: 'victim-user' }).success).toBe(false);
+    await expect(tool.handler({ userId: 'victim-user' })).rejects.toThrow(
+      'MCP caller-controlled identity field is forbidden: userId',
+    );
+    expect(brain.conversations.findAll).not.toHaveBeenCalled();
+
+    await tool.handler({});
+    expect(brain.conversations.findAll).toHaveBeenCalledWith('authenticated-user');
+  });
+
+  it('scopes brain project, mission, and task reads to the authenticated actor', async () => {
+    const { service } = makeService({
+      projects: [
+        { id: 'project-owned', ownerId: 'authenticated-user', name: 'owned' },
+        { id: 'project-victim', ownerId: 'victim-user', name: 'victim' },
+      ],
+      missions: [
+        { id: 'mission-owned', projectId: 'project-owned' },
+        { id: 'mission-victim', userId: 'victim-user', projectId: 'project-victim' },
+      ],
+      tasks: [
+        { id: 'task-owned-project', projectId: 'project-owned', status: 'not-started' },
+        { id: 'task-owned-mission', missionId: 'mission-owned', status: 'not-started' },
+        { id: 'task-victim-project', projectId: 'project-victim', status: 'not-started' },
+        { id: 'task-unowned', status: 'not-started' },
+      ],
+    });
+    const { server, tools } = makeCapturingServer();
+    const actor = makeMemberActor('authenticated-user');
+
+    service.registerTools(server, actor);
+
+    const projects = JSON.parse(
+      (await getTool(tools, 'brain_list_projects').handler({})).content[0]!.text,
+    );
+    expect(projects.map((project: { id: string }) => project.id)).toEqual(['project-owned']);
+
+    const missions = JSON.parse(
+      (await getTool(tools, 'brain_list_missions').handler({})).content[0]!.text,
+    );
+    expect(missions.map((mission: { id: string }) => mission.id)).toEqual(['mission-owned']);
+
+    const tasks = JSON.parse(
+      (await getTool(tools, 'brain_list_tasks').handler({})).content[0]!.text,
+    );
+    expect(tasks.map((task: { id: string }) => task.id)).toEqual([
+      'task-owned-project',
+      'task-owned-mission',
+    ]);
+  });
+
+  it('enforces tenant boundaries for tenant-admin brain project, mission, and task reads', async () => {
+    const { service } = makeService({
+      projects: [
+        {
+          id: 'project-tenant-a',
+          ownerId: 'other-user-a',
+          teamId: 'tenant-a',
+          name: 'same tenant',
+        },
+        {
+          id: 'project-tenant-b',
+          ownerId: 'other-user-b',
+          teamId: 'tenant-b',
+          name: 'other tenant',
+        },
+      ],
+      missions: [
+        { id: 'mission-tenant-a', tenantId: 'tenant-a', projectId: 'project-tenant-a' },
+        { id: 'mission-tenant-b', tenantId: 'tenant-b', projectId: 'project-tenant-b' },
+      ],
+      tasks: [
+        { id: 'task-tenant-a', projectId: 'project-tenant-a', status: 'not-started' },
+        { id: 'task-tenant-b', projectId: 'project-tenant-b', status: 'not-started' },
+      ],
+    });
+    const { server, tools } = makeCapturingServer();
+    const actor = makeAdminActor('tenant-admin-user', 'tenant-a');
+
+    service.registerTools(server, actor);
+
+    const projects = JSON.parse(
+      (await getTool(tools, 'brain_list_projects').handler({})).content[0]!.text,
+    );
+    expect(projects.map((project: { id: string }) => project.id)).toEqual(['project-tenant-a']);
+
+    const missions = JSON.parse(
+      (await getTool(tools, 'brain_list_missions').handler({})).content[0]!.text,
+    );
+    expect(missions.map((mission: { id: string }) => mission.id)).toEqual(['mission-tenant-a']);
+
+    const tasks = JSON.parse(
+      (await getTool(tools, 'brain_list_tasks').handler({})).content[0]!.text,
+    );
+    expect(tasks.map((task: { id: string }) => task.id)).toEqual(['task-tenant-a']);
+  });
+
+  it('denies tenant-admin task writes outside the authenticated tenant', async () => {
+    const { service, brain } = makeService({
+      projects: [
+        { id: 'project-tenant-a', ownerId: 'other-user-a', teamId: 'tenant-a' },
+        { id: 'project-tenant-b', ownerId: 'other-user-b', teamId: 'tenant-b' },
+      ],
+      missions: [
+        { id: 'mission-tenant-a', tenantId: 'tenant-a', projectId: 'project-tenant-a' },
+        { id: 'mission-tenant-b', tenantId: 'tenant-b', projectId: 'project-tenant-b' },
+      ],
+      tasks: [
+        { id: 'task-tenant-a', projectId: 'project-tenant-a', status: 'not-started' },
+        { id: 'task-tenant-b', projectId: 'project-tenant-b', status: 'not-started' },
+      ],
+    });
+    const { server, tools } = makeCapturingServer();
+    const actor = makeAdminActor('tenant-admin-user', 'tenant-a');
+
+    service.registerTools(server, actor);
+
+    await expect(
+      getTool(tools, 'brain_create_task').handler({
+        title: 'unscoped tenant write',
+      }),
+    ).rejects.toThrow('MCP task scope denied');
+    expect(brain.tasks.create).not.toHaveBeenCalled();
+
+    await expect(
+      getTool(tools, 'brain_create_task').handler({
+        title: 'cross-tenant write',
+        projectId: 'project-tenant-b',
+      }),
+    ).rejects.toThrow('MCP task project scope denied');
+    expect(brain.tasks.create).not.toHaveBeenCalled();
+
+    await expect(
+      getTool(tools, 'brain_update_task').handler({
+        id: 'task-tenant-a',
+        projectId: 'project-tenant-b',
+      }),
+    ).rejects.toThrow('MCP task project scope denied');
+    expect(brain.tasks.update).not.toHaveBeenCalled();
+
+    const updateResult = await getTool(tools, 'brain_update_task').handler({
+      id: 'task-tenant-b',
+      title: 'cross-tenant update',
+    });
+    expect(updateResult.content[0]!.text).toBe('Task not found: task-tenant-b');
+    expect(brain.tasks.update).not.toHaveBeenCalled();
+
+    await getTool(tools, 'brain_create_task').handler({
+      title: 'same-tenant write',
+      projectId: 'project-tenant-a',
+    });
+    expect(brain.tasks.create).toHaveBeenCalledWith(
+      expect.objectContaining({ projectId: 'project-tenant-a', title: 'same-tenant write' }),
+    );
+  });
+
+  it('keeps admin-only coordination tools on server-derived paths', async () => {
+    const { service, coord } = makeService();
+    const { server, tools } = makeCapturingServer();
+    const member = makeMemberActor('authenticated-user');
+    const tenantAdmin = makeAdminActor('admin-user');
+    const platformAdmin = makePlatformAdminActor('platform-admin-user');
+
+    service.registerTools(server, member);
+    const memberTool = getTool(tools, 'coord_list_tasks');
+    expect(memberTool.inputSchema.safeParse({ projectPath: '/tmp/victim' }).success).toBe(false);
+    await expect(memberTool.handler({})).rejects.toThrow('MCP tool scope denied: coord:read');
+
+    tools.clear();
+    service.registerTools(server, tenantAdmin);
+    const tenantAdminTool = getTool(tools, 'coord_list_tasks');
+    await expect(tenantAdminTool.handler({})).rejects.toThrow('MCP tool scope denied: coord:read');
+
+    tools.clear();
+    service.registerTools(server, platformAdmin);
+    const platformAdminTool = getTool(tools, 'coord_list_tasks');
+    await platformAdminTool.handler({ projectPath: '/tmp/victim' });
+    expect(coord.listTasks).toHaveBeenCalledWith(process.cwd());
+  });
+
+  it('does not attach a guessed or stale-scope MCP session to another authenticated context', async () => {
+    const { service } = makeService();
+    const owner = makeMemberActor('owner-user');
+    const attacker = makeMemberActor('attacker-user');
+    const admin = makeAdminActor('admin-user');
+    const downgradedAdmin = makeMemberActor('admin-user');
+
+    const { sessionId, transport } = service.createSession(owner);
+    const staleSession = service.createSession(admin);
+
+    expect(service.getSession(sessionId, owner)).toBe(transport);
+    expect(service.getSession(sessionId, attacker)).toBeNull();
+    expect(service.getSession(sessionId, owner)).toBe(transport);
+    expect(service.getSession(staleSession.sessionId, downgradedAdmin)).toBeNull();
+    expect(service.getSession(staleSession.sessionId, admin)).toBe(staleSession.transport);
+
+    await service.onModuleDestroy();
+  });
+});

apps/gateway/src/mcp/mcp.service.ts

@@ -10,11 +10,216 @@ import { MEMORY } from '../memory/memory.tokens.js';
 import { EmbeddingService } from '../memory/embedding.service.js';
 import { CoordService } from '../coord/coord.service.js';
 
+export const MCP_CALLER_IDENTITY_FIELDS = [
+  'actorId',
+  'actor',
+  'authenticatedUserId',
+  'channel',
+  'organizationId',
+  'ownerId',
+  'sessionUserId',
+  'teamId',
+  'tenant',
+  'tenantId',
+  'user',
+  'userId',
+] as const;
+
+type McpCallerIdentityField = (typeof MCP_CALLER_IDENTITY_FIELDS)[number];
+
+export const MCP_TOOL_SCOPES = {
+  brain_list_projects: 'brain:project:read',
+  brain_get_project: 'brain:project:read',
+  brain_list_tasks: 'brain:task:read',
+  brain_create_task: 'brain:task:write',
+  brain_update_task: 'brain:task:write',
+  brain_list_missions: 'brain:mission:read',
+  brain_list_conversations: 'brain:conversation:read',
+  memory_search: 'memory:insight:read',
+  memory_get_preferences: 'memory:preference:read',
+  memory_save_preference: 'memory:preference:write',
+  memory_save_insight: 'memory:insight:write',
+  coord_mission_status: 'coord:read',
+  coord_list_tasks: 'coord:read',
+  coord_task_detail: 'coord:read',
+} as const;
+
+export type McpToolName = keyof typeof MCP_TOOL_SCOPES;
+export type McpToolScope = (typeof MCP_TOOL_SCOPES)[McpToolName];
+
+export interface McpActorContext {
+  userId: string;
+  tenantId: string;
+  role: string;
+  channel: 'mcp';
+  correlationId: string;
+  scopes: ReadonlySet<McpToolScope>;
+}
+
 interface SessionEntry {
   server: McpServer;
   transport: StreamableHTTPServerTransport;
   createdAt: Date;
+  actor: McpActorContext;
+}
+
+const GLOBAL_ADMIN_MCP_SCOPES = new Set<McpToolScope>(Object.values(MCP_TOOL_SCOPES));
+const TENANT_ADMIN_MCP_SCOPES = new Set<McpToolScope>([
+  MCP_TOOL_SCOPES.brain_list_projects,
+  MCP_TOOL_SCOPES.brain_get_project,
+  MCP_TOOL_SCOPES.brain_list_tasks,
+  MCP_TOOL_SCOPES.brain_create_task,
+  MCP_TOOL_SCOPES.brain_update_task,
+  MCP_TOOL_SCOPES.brain_list_missions,
+  MCP_TOOL_SCOPES.brain_list_conversations,
+  MCP_TOOL_SCOPES.memory_search,
+  MCP_TOOL_SCOPES.memory_get_preferences,
+  MCP_TOOL_SCOPES.memory_save_preference,
+  MCP_TOOL_SCOPES.memory_save_insight,
+]);
+const MEMBER_MCP_SCOPES = new Set<McpToolScope>([
+  MCP_TOOL_SCOPES.brain_list_projects,
+  MCP_TOOL_SCOPES.brain_get_project,
+  MCP_TOOL_SCOPES.brain_list_tasks,
+  MCP_TOOL_SCOPES.brain_list_missions,
+  MCP_TOOL_SCOPES.brain_list_conversations,
+  MCP_TOOL_SCOPES.memory_search,
+  MCP_TOOL_SCOPES.memory_get_preferences,
+  MCP_TOOL_SCOPES.memory_save_preference,
+  MCP_TOOL_SCOPES.memory_save_insight,
+]);
+
+export function deriveMcpToolScopesForUser(input: {
+  role?: string | null;
+}): ReadonlySet<McpToolScope> {
+  if (input.role === 'platform-admin' || input.role === 'super-admin') {
+    return new Set(GLOBAL_ADMIN_MCP_SCOPES);
+  }
+  if (input.role === 'admin') {
+    return new Set(TENANT_ADMIN_MCP_SCOPES);
+  }
+  return new Set(MEMBER_MCP_SCOPES);
+}
+
+export function createMcpActorContext(input: {
   userId: string;
+  tenantId?: string;
+  role?: string | null;
+  scopes?: Iterable<McpToolScope>;
+  correlationId?: string;
+}): McpActorContext {
+  const userId = input.userId.trim();
+  if (userId.length === 0) {
+    throw new Error('MCP authenticated user is required');
+  }
+
+  return {
+    userId,
+    tenantId: input.tenantId?.trim() || `user:${userId}`,
+    role: input.role ?? 'member',
+    channel: 'mcp',
+    correlationId: input.correlationId ?? randomUUID(),
+    scopes: new Set(input.scopes ?? []),
+  };
+}
+
+export function assertNoCallerControlledIdentity(params: unknown): void {
+  if (params === null || typeof params !== 'object') return;
+
+  const keys = new Set(Object.keys(params));
+  const forbidden = MCP_CALLER_IDENTITY_FIELDS.find((field: McpCallerIdentityField) =>
+    keys.has(field),
+  );
+  if (forbidden) {
+    throw new Error(`MCP caller-controlled identity field is forbidden: ${forbidden}`);
+  }
+}
+
+export function assertMcpToolAuthorized(
+  actor: McpActorContext,
+  toolName: McpToolName,
+  params: unknown,
+): void {
+  assertNoCallerControlledIdentity(params);
+  const requiredScope = MCP_TOOL_SCOPES[toolName];
+  if (!actor.scopes.has(requiredScope)) {
+    throw new Error(`MCP tool scope denied: ${requiredScope}`);
+  }
+}
+
+function strictObject<T extends z.ZodRawShape>(shape: T): z.ZodObject<T> {
+  return z.object(shape).strict();
+}
+
+type TenantScopedLike = {
+  tenantId?: string | null;
+  organizationId?: string | null;
+  teamId?: string | null;
+};
+type ProjectLike = TenantScopedLike & { id: string; ownerId?: string | null };
+type MissionLike = TenantScopedLike & {
+  id: string;
+  projectId?: string | null;
+  userId?: string | null;
+};
+type TaskLike = TenantScopedLike & {
+  projectId?: string | null;
+  missionId?: string | null;
+  userId?: string | null;
+};
+
+function isGlobalAdminActor(actor: McpActorContext): boolean {
+  return actor.role === 'platform-admin' || actor.role === 'super-admin';
+}
+
+function isTenantAdminActor(actor: McpActorContext): boolean {
+  return actor.role === 'admin';
+}
+
+function matchesTenant(actor: McpActorContext, record: TenantScopedLike): boolean {
+  return (
+    record.tenantId === actor.tenantId ||
+    record.organizationId === actor.tenantId ||
+    record.teamId === actor.tenantId
+  );
+}
+
+function filterProjectsForActor<T extends ProjectLike>(actor: McpActorContext, projects: T[]): T[] {
+  if (isGlobalAdminActor(actor)) return projects;
+  return projects.filter(
+    (project) =>
+      project.ownerId === actor.userId ||
+      (isTenantAdminActor(actor) && matchesTenant(actor, project)),
+  );
+}
+
+function filterMissionsByDirectActorScope<T extends MissionLike>(
+  actor: McpActorContext,
+  missions: T[],
+): T[] {
+  if (isGlobalAdminActor(actor)) return missions;
+  return missions.filter(
+    (mission) =>
+      mission.userId === actor.userId ||
+      (isTenantAdminActor(actor) && matchesTenant(actor, mission)),
+  );
+}
+
+function scopesEqual(left: ReadonlySet<McpToolScope>, right: ReadonlySet<McpToolScope>): boolean {
+  if (left.size !== right.size) return false;
+  for (const scope of left) {
+    if (!right.has(scope)) return false;
+  }
+  return true;
+}
+
+function sameActorAuthorization(stored: McpActorContext, current: McpActorContext): boolean {
+  return (
+    stored.userId === current.userId &&
+    stored.tenantId === current.tenantId &&
+    stored.role === current.role &&
+    scopesEqual(stored.scopes, current.scopes)
+  );
 }
 
 @Injectable()
@@ -33,13 +238,18 @@ export class McpService implements OnModuleDestroy {
    * Creates a new MCP session with its own server + transport pair.
    * Returns the transport for use by the controller.
    */
-  createSession(userId: string): { sessionId: string; transport: StreamableHTTPServerTransport } {
+  createSession(actor: McpActorContext): {
+    sessionId: string;
+    transport: StreamableHTTPServerTransport;
+  } {
     const sessionId = randomUUID();
 
     const transport = new StreamableHTTPServerTransport({
       sessionIdGenerator: () => sessionId,
       onsessioninitialized: (id) => {
-        this.logger.log(`MCP session initialized: ${id} for user ${userId}`);
+        this.logger.log(
+          `MCP session initialized: ${id} for actor=${actor.userId} tenant=${actor.tenantId} correlation=${actor.correlationId}`,
+        );
       },
     });
 
@@ -48,7 +258,7 @@ export class McpService implements OnModuleDestroy {
       { capabilities: { tools: {} } },
     );
 
-    this.registerTools(server, userId);
+    this.registerTools(server, actor);
 
     transport.onclose = () => {
       this.logger.log(`MCP session closed: ${sessionId}`);
@@ -61,31 +271,126 @@ export class McpService implements OnModuleDestroy {
       );
     });
 
-    this.sessions.set(sessionId, { server, transport, createdAt: new Date(), userId });
+    this.sessions.set(sessionId, { server, transport, createdAt: new Date(), actor });
     return { sessionId, transport };
   }
 
   /**
-   * Returns the transport for an existing session, or null if not found.
+   * Returns the transport for an existing session only when it belongs to the
+   * currently authenticated MCP actor. Guessed or cross-tenant session IDs grant
+   * no authority.
    */
-  getSession(sessionId: string): StreamableHTTPServerTransport | null {
-    return this.sessions.get(sessionId)?.transport ?? null;
+  getSession(sessionId: string, actor: McpActorContext): StreamableHTTPServerTransport | null {
+    const entry = this.sessions.get(sessionId);
+    if (!entry) return null;
+    if (!sameActorAuthorization(entry.actor, actor)) {
+      this.logger.warn(
+        `MCP session actor or scope mismatch: session=${sessionId} actor=${actor.userId} tenant=${actor.tenantId} role=${actor.role}`,
+      );
+      return null;
+    }
+    return entry.transport;
+  }
+
+  private async isProjectAuthorized(actor: McpActorContext, projectId: string): Promise<boolean> {
+    if (isGlobalAdminActor(actor)) return true;
+    const project = (await this.brain.projects.findById(projectId)) as ProjectLike | undefined;
+    return project ? filterProjectsForActor(actor, [project]).length === 1 : false;
+  }
+
+  private async filterMissionsForActor<T extends MissionLike>(
+    actor: McpActorContext,
+    missions: T[],
+  ): Promise<T[]> {
+    if (isGlobalAdminActor(actor)) return missions;
+
+    const projects = (await this.brain.projects.findAll()) as ProjectLike[];
+    const projectIds = new Set(
+      filterProjectsForActor(actor, projects).map((project) => project.id),
+    );
+
+    return missions.filter(
+      (mission) =>
+        filterMissionsByDirectActorScope(actor, [mission]).length === 1 ||
+        (typeof mission.projectId === 'string' && projectIds.has(mission.projectId)),
+    );
+  }
+
+  private async isMissionAuthorized(actor: McpActorContext, missionId: string): Promise<boolean> {
+    if (isGlobalAdminActor(actor)) return true;
+    const mission = (await this.brain.missions.findById(missionId)) as MissionLike | undefined;
+    if (!mission) return false;
+    return (await this.filterMissionsForActor(actor, [mission])).length === 1;
+  }
+
+  private async assertTaskReferencesAuthorized(
+    actor: McpActorContext,
+    refs: { projectId?: string | null; missionId?: string | null },
+  ): Promise<void> {
+    if (refs.projectId && !(await this.isProjectAuthorized(actor, refs.projectId))) {
+      throw new Error('MCP task project scope denied');
+    }
+    if (refs.missionId && !(await this.isMissionAuthorized(actor, refs.missionId))) {
+      throw new Error('MCP task mission scope denied');
+    }
+  }
+
+  private async assertTaskCreateScopeAuthorized(
+    actor: McpActorContext,
+    refs: { projectId?: string | null; missionId?: string | null },
+  ): Promise<void> {
+    if (!isGlobalAdminActor(actor) && !refs.projectId && !refs.missionId) {
+      throw new Error('MCP task scope denied');
+    }
+    await this.assertTaskReferencesAuthorized(actor, refs);
+  }
+
+  private async filterTasksForActor<T extends TaskLike>(
+    actor: McpActorContext,
+    tasks: T[],
+  ): Promise<T[]> {
+    if (isGlobalAdminActor(actor)) return tasks;
+
+    const [projects, missions] = await Promise.all([
+      this.brain.projects.findAll(),
+      this.brain.missions.findAll(),
+    ]);
+    const projectIds = new Set(
+      filterProjectsForActor(actor, projects as ProjectLike[]).map((project) => project.id),
+    );
+    const missionIds = new Set(
+      (await this.filterMissionsForActor(actor, missions as MissionLike[])).map(
+        (mission) => mission.id,
+      ),
+    );
+
+    return tasks.filter(
+      (task) =>
+        task.userId === actor.userId ||
+        (isTenantAdminActor(actor) && matchesTenant(actor, task)) ||
+        (typeof task.projectId === 'string' && projectIds.has(task.projectId)) ||
+        (typeof task.missionId === 'string' && missionIds.has(task.missionId)),
+    );
   }
 
   /**
    * Registers all platform tools on the given McpServer instance.
    */
-  private registerTools(server: McpServer, _userId: string): void {
+  registerTools(server: McpServer, actor: McpActorContext): void {
     // ─── Brain: Project tools ────────────────────────────────────────────
 
     server.registerTool(
       'brain_list_projects',
       {
         description: 'List all projects in the brain.',
-        inputSchema: z.object({}),
+        inputSchema: strictObject({}),
       },
-      async () => {
-        const projects = await this.brain.projects.findAll();
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'brain_list_projects', params);
+        const projects = filterProjectsForActor(
+          actor,
+          (await this.brain.projects.findAll()) as ProjectLike[],
+        );
         return {
           content: [{ type: 'text' as const, text: JSON.stringify(projects, null, 2) }],
         };
@@ -96,17 +401,21 @@ export class McpService implements OnModuleDestroy {
       'brain_get_project',
       {
         description: 'Get a project by ID.',
-        inputSchema: z.object({
+        inputSchema: strictObject({
           id: z.string().describe('Project ID (UUID)'),
         }),
       },
-      async ({ id }) => {
-        const project = await this.brain.projects.findById(id);
+      async ({ id, ...params }) => {
+        assertMcpToolAuthorized(actor, 'brain_get_project', params);
+        const project = (await this.brain.projects.findById(id)) as ProjectLike | undefined;
+        const authorizedProject = project ? filterProjectsForActor(actor, [project])[0] : undefined;
         return {
           content: [
             {
               type: 'text' as const,
-              text: project ? JSON.stringify(project, null, 2) : `Project not found: ${id}`,
+              text: authorizedProject
+                ? JSON.stringify(authorizedProject, null, 2)
+                : `Project not found: ${id}`,
             },
           ],
         };
@@ -119,20 +428,23 @@ export class McpService implements OnModuleDestroy {
       'brain_list_tasks',
       {
         description: 'List tasks, optionally filtered by project, mission, or status.',
-        inputSchema: z.object({
+        inputSchema: strictObject({
           projectId: z.string().optional().describe('Filter by project ID'),
           missionId: z.string().optional().describe('Filter by mission ID'),
           status: z.string().optional().describe('Filter by status'),
         }),
       },
-      async ({ projectId, missionId, status }) => {
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'brain_list_tasks', params);
+        const { projectId, missionId, status } = params;
         type TaskStatus = 'not-started' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
         let tasks;
         if (projectId) tasks = await this.brain.tasks.findByProject(projectId);
         else if (missionId) tasks = await this.brain.tasks.findByMission(missionId);
         else if (status) tasks = await this.brain.tasks.findByStatus(status as TaskStatus);
         else tasks = await this.brain.tasks.findAll();
-        return { content: [{ type: 'text' as const, text: JSON.stringify(tasks, null, 2) }] };
+        const scopedTasks = await this.filterTasksForActor(actor, tasks as TaskLike[]);
+        return { content: [{ type: 'text' as const, text: JSON.stringify(scopedTasks, null, 2) }] };
       },
     );
 
@@ -140,7 +452,7 @@ export class McpService implements OnModuleDestroy {
       'brain_create_task',
       {
         description: 'Create a new task in the brain.',
-        inputSchema: z.object({
+        inputSchema: strictObject({
           title: z.string().describe('Task title'),
           description: z.string().optional().describe('Task description'),
           projectId: z.string().optional().describe('Project ID'),
@@ -149,6 +461,8 @@ export class McpService implements OnModuleDestroy {
         }),
       },
       async (params) => {
+        assertMcpToolAuthorized(actor, 'brain_create_task', params);
+        await this.assertTaskCreateScopeAuthorized(actor, params);
         type Priority = 'low' | 'medium' | 'high' | 'critical';
         const task = await this.brain.tasks.create({
           ...params,
@@ -162,7 +476,7 @@ export class McpService implements OnModuleDestroy {
       'brain_update_task',
       {
         description: 'Update an existing task.',
-        inputSchema: z.object({
+        inputSchema: strictObject({
           id: z.string().describe('Task ID'),
           title: z.string().optional(),
           description: z.string().optional(),
@@ -171,9 +485,17 @@ export class McpService implements OnModuleDestroy {
             .optional()
             .describe('not-started, in-progress, blocked, done, cancelled'),
           priority: z.string().optional(),
+          projectId: z.string().optional().describe('Project ID'),
+          missionId: z.string().optional().describe('Mission ID'),
         }),
       },
       async ({ id, ...updates }) => {
+        assertMcpToolAuthorized(actor, 'brain_update_task', updates);
+        const existing = (await this.brain.tasks.findById(id)) as TaskLike | undefined;
+        if (!existing || (await this.filterTasksForActor(actor, [existing])).length === 0) {
+          return { content: [{ type: 'text' as const, text: `Task not found: ${id}` }] };
+        }
+        await this.assertTaskReferencesAuthorized(actor, updates);
         type TaskStatus = 'not-started' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
         type Priority = 'low' | 'medium' | 'high' | 'critical';
         const task = await this.brain.tasks.update(id, {
@@ -198,14 +520,19 @@ export class McpService implements OnModuleDestroy {
       'brain_list_missions',
       {
         description: 'List all missions, optionally filtered by project.',
-        inputSchema: z.object({
+        inputSchema: strictObject({
           projectId: z.string().optional().describe('Filter by project ID'),
         }),
       },
-      async ({ projectId }) => {
-        const missions = projectId
-          ? await this.brain.missions.findByProject(projectId)
-          : await this.brain.missions.findAll();
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'brain_list_missions', params);
+        const { projectId } = params;
+        const missions = await this.filterMissionsForActor(
+          actor,
+          (projectId
+            ? await this.brain.missions.findByProject(projectId)
+            : await this.brain.missions.findAll()) as MissionLike[],
+        );
         return { content: [{ type: 'text' as const, text: JSON.stringify(missions, null, 2) }] };
       },
     );
@@ -213,13 +540,12 @@ export class McpService implements OnModuleDestroy {
     server.registerTool(
       'brain_list_conversations',
       {
-        description: 'List conversations for a user.',
-        inputSchema: z.object({
-          userId: z.string().describe('User ID'),
-        }),
+        description: 'List conversations for the authenticated MCP actor.',
+        inputSchema: strictObject({}),
       },
-      async ({ userId }) => {
-        const conversations = await this.brain.conversations.findAll(userId);
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'brain_list_conversations', params);
+        const conversations = await this.brain.conversations.findAll(actor.userId);
         return {
           content: [{ type: 'text' as const, text: JSON.stringify(conversations, null, 2) }],
         };
@@ -232,14 +558,15 @@ export class McpService implements OnModuleDestroy {
       'memory_search',
       {
         description:
-          'Search across stored insights and knowledge using natural language. Returns semantically similar results.',
-        inputSchema: z.object({
-          userId: z.string().describe('User ID to search memory for'),
+          'Search stored insights and knowledge for the authenticated MCP actor using natural language.',
+        inputSchema: strictObject({
           query: z.string().describe('Natural language search query'),
           limit: z.number().optional().describe('Max results (default 5)'),
         }),
       },
-      async ({ userId, query, limit }) => {
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'memory_search', params);
+        const { query, limit } = params;
         if (!this.embeddings.available) {
           return {
             content: [
@@ -251,7 +578,11 @@ export class McpService implements OnModuleDestroy {
           };
         }
         const embedding = await this.embeddings.embed(query);
-        const results = await this.memory.insights.searchByEmbedding(userId, embedding, limit ?? 5);
+        const results = await this.memory.insights.searchByEmbedding(
+          actor.userId,
+          embedding,
+          limit ?? 5,
+        );
         return { content: [{ type: 'text' as const, text: JSON.stringify(results, null, 2) }] };
       },
     );
@@ -259,20 +590,21 @@ export class McpService implements OnModuleDestroy {
     server.registerTool(
       'memory_get_preferences',
       {
-        description: 'Retrieve stored preferences for a user.',
-        inputSchema: z.object({
-          userId: z.string().describe('User ID'),
+        description: 'Retrieve stored preferences for the authenticated MCP actor.',
+        inputSchema: strictObject({
           category: z
             .string()
             .optional()
             .describe('Filter by category: communication, coding, workflow, appearance, general'),
         }),
       },
-      async ({ userId, category }) => {
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'memory_get_preferences', params);
+        const { category } = params;
         type Cat = 'communication' | 'coding' | 'workflow' | 'appearance' | 'general';
         const prefs = category
-          ? await this.memory.preferences.findByUserAndCategory(userId, category as Cat)
-          : await this.memory.preferences.findByUser(userId);
+          ? await this.memory.preferences.findByUserAndCategory(actor.userId, category as Cat)
+          : await this.memory.preferences.findByUser(actor.userId);
         return { content: [{ type: 'text' as const, text: JSON.stringify(prefs, null, 2) }] };
       },
     );
@@ -281,9 +613,8 @@ export class McpService implements OnModuleDestroy {
       'memory_save_preference',
       {
         description:
-          'Store a learned user preference (e.g., "prefers tables over paragraphs", "timezone: America/Chicago").',
-        inputSchema: z.object({
-          userId: z.string().describe('User ID'),
+          'Store a learned preference for the authenticated MCP actor (e.g., "prefers tables over paragraphs").',
+        inputSchema: strictObject({
           key: z.string().describe('Preference key'),
           value: z.string().describe('Preference value (JSON string)'),
           category: z
@@ -292,7 +623,9 @@ export class McpService implements OnModuleDestroy {
             .describe('Category: communication, coding, workflow, appearance, general'),
         }),
       },
-      async ({ userId, key, value, category }) => {
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'memory_save_preference', params);
+        const { key, value, category } = params;
         type Cat = 'communication' | 'coding' | 'workflow' | 'appearance' | 'general';
         let parsedValue: unknown;
         try {
@@ -301,7 +634,7 @@ export class McpService implements OnModuleDestroy {
           parsedValue = value;
         }
         const pref = await this.memory.preferences.upsert({
-          userId,
+          userId: actor.userId,
           key,
           value: parsedValue,
           category: (category as Cat) ?? 'general',
@@ -315,9 +648,8 @@ export class McpService implements OnModuleDestroy {
       'memory_save_insight',
       {
         description:
-          'Store a learned insight, decision, or knowledge extracted from the current interaction.',
-        inputSchema: z.object({
-          userId: z.string().describe('User ID'),
+          'Store a learned insight, decision, or knowledge for the authenticated MCP actor.',
+        inputSchema: strictObject({
           content: z.string().describe('The insight or knowledge to store'),
           category: z
             .string()
@@ -325,11 +657,13 @@ export class McpService implements OnModuleDestroy {
             .describe('Category: decision, learning, preference, fact, pattern, general'),
         }),
       },
-      async ({ userId, content, category }) => {
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'memory_save_insight', params);
+        const { content, category } = params;
         type Cat = 'decision' | 'learning' | 'preference' | 'fact' | 'pattern' | 'general';
         const embedding = this.embeddings.available ? await this.embeddings.embed(content) : null;
         const insight = await this.memory.insights.create({
-          userId,
+          userId: actor.userId,
           content,
           embedding,
           source: 'agent',
@@ -346,16 +680,11 @@ export class McpService implements OnModuleDestroy {
       {
         description:
           'Get the current orchestration mission status including milestones, tasks, and active session.',
-        inputSchema: z.object({
-          projectPath: z
-            .string()
-            .optional()
-            .describe('Project path. Defaults to gateway working directory.'),
-        }),
+        inputSchema: strictObject({}),
       },
-      async ({ projectPath }) => {
-        const resolvedPath = projectPath ?? process.cwd();
-        const status = await this.coordService.getMissionStatus(resolvedPath);
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'coord_mission_status', params);
+        const status = await this.coordService.getMissionStatus(process.cwd());
         return {
           content: [
             {
@@ -371,16 +700,11 @@ export class McpService implements OnModuleDestroy {
       'coord_list_tasks',
       {
         description: 'List all tasks from the orchestration TASKS.md file.',
-        inputSchema: z.object({
-          projectPath: z
-            .string()
-            .optional()
-            .describe('Project path. Defaults to gateway working directory.'),
-        }),
+        inputSchema: strictObject({}),
       },
-      async ({ projectPath }) => {
-        const resolvedPath = projectPath ?? process.cwd();
-        const tasks = await this.coordService.listTasks(resolvedPath);
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'coord_list_tasks', params);
+        const tasks = await this.coordService.listTasks(process.cwd());
         return { content: [{ type: 'text' as const, text: JSON.stringify(tasks, null, 2) }] };
       },
     );
@@ -389,17 +713,14 @@ export class McpService implements OnModuleDestroy {
       'coord_task_detail',
       {
         description: 'Get detailed status for a specific orchestration task.',
-        inputSchema: z.object({
+        inputSchema: strictObject({
           taskId: z.string().describe('Task ID (e.g. P2-005)'),
-          projectPath: z
-            .string()
-            .optional()
-            .describe('Project path. Defaults to gateway working directory.'),
         }),
       },
-      async ({ taskId, projectPath }) => {
-        const resolvedPath = projectPath ?? process.cwd();
-        const detail = await this.coordService.getTaskStatus(resolvedPath, taskId);
+      async (params) => {
+        assertMcpToolAuthorized(actor, 'coord_task_detail', params);
+        const { taskId } = params;
+        const detail = await this.coordService.getTaskStatus(process.cwd(), taskId);
         return {
           content: [
             {

apps/gateway/src/plugin/discord-ingress.security.spec.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createDiscordIngressEnvelope,
+  verifyDiscordIngressEnvelope,
+  type DiscordIngressPayload,
+} from '@mosaicstack/discord-plugin';
+import { validateDiscordServiceToken } from '../chat/chat.gateway-auth.js';
+import { DiscordReplayProtector } from './discord-replay-protector.js';
+
+const SERVICE_TOKEN = 'test-service-token';
+
+function createPayload(overrides: Partial<DiscordIngressPayload> = {}): DiscordIngressPayload {
+  return {
+    correlationId: 'correlation-001',
+    messageId: 'discord-message-001',
+    guildId: 'guild-001',
+    channelId: 'channel-001',
+    userId: 'user-001',
+    conversationId: 'discord-channel-001',
+    content: 'hello Tess',
+    ...overrides,
+  };
+}
+
+describe('Discord ingress security', () => {
+  it('accepts only the configured Discord service identity', () => {
+    expect(validateDiscordServiceToken(SERVICE_TOKEN, SERVICE_TOKEN)).toBe(true);
+    expect(validateDiscordServiceToken('wrong-service-token', SERVICE_TOKEN)).toBe(false);
+    expect(validateDiscordServiceToken(undefined, SERVICE_TOKEN)).toBe(false);
+  });
+
+  it('rejects unauthenticated or tampered service envelopes', () => {
+    const envelope = createDiscordIngressEnvelope(createPayload(), SERVICE_TOKEN);
+
+    expect(verifyDiscordIngressEnvelope(envelope, SERVICE_TOKEN)).toEqual(createPayload());
+    expect(verifyDiscordIngressEnvelope(envelope, 'wrong-service-token')).toBeNull();
+    expect(
+      verifyDiscordIngressEnvelope(
+        { ...envelope, payload: { ...envelope.payload, content: 'forged command' } },
+        SERVICE_TOKEN,
+      ),
+    ).toBeNull();
+  });
+
+  it.each([
+    ['guild', { guildId: 'unlisted-guild' }],
+    ['channel', { channelId: 'unlisted-channel' }],
+    ['user', { userId: 'unlisted-user' }],
+  ])(
+    'rejects an unallowlisted Discord %s',
+    (_kind: string, overrides: Partial<DiscordIngressPayload>) => {
+      const envelope = createDiscordIngressEnvelope(createPayload(overrides), SERVICE_TOKEN);
+
+      expect(
+        verifyDiscordIngressEnvelope(envelope, SERVICE_TOKEN, {
+          guildIds: ['guild-001'],
+          channelIds: ['channel-001'],
+          userIds: ['user-001'],
+        }),
+      ).toBeNull();
+    },
+  );
+
+  it('retains Discord message and correlation IDs after authenticated allowlisted validation', () => {
+    const payload = createPayload({
+      correlationId: 'correlation-trace-123',
+      messageId: 'discord-snowflake-987',
+    });
+    const envelope = createDiscordIngressEnvelope(payload, SERVICE_TOKEN);
+
+    expect(
+      verifyDiscordIngressEnvelope(envelope, SERVICE_TOKEN, {
+        guildIds: ['guild-001'],
+        channelIds: ['channel-001'],
+        userIds: ['user-001'],
+      }),
+    ).toEqual(payload);
+  });
+
+  it('rejects a replayed Discord message ID while retaining bounded replay state', () => {
+    const replayProtector = new DiscordReplayProtector(60_000, 2);
+
+    expect(replayProtector.claim('discord-message-001')).toBe(true);
+    expect(replayProtector.claim('discord-message-001')).toBe(false);
+    expect(replayProtector.claim('discord-message-002')).toBe(true);
+    expect(replayProtector.claim('discord-message-003')).toBe(true);
+    expect(replayProtector.size).toBe(2);
+  });
+});

apps/gateway/src/plugin/discord-replay-protector.ts

@@ -0,0 +1,40 @@
+/**
+ * Bounded replay cache for Discord's globally unique native message IDs.
+ * Durable ingress idempotency is added with Tess's canonical inbox/outbox work.
+ */
+export class DiscordReplayProtector {
+  private readonly claimedAt = new Map<string, number>();
+
+  constructor(
+    private readonly ttlMs = 15 * 60 * 1000,
+    private readonly maxEntries = 10_000,
+  ) {}
+
+  get size(): number {
+    return this.claimedAt.size;
+  }
+
+  /** Claims an ID exactly once within its bounded retention window. */
+  claim(messageId: string, now = Date.now()): boolean {
+    this.prune(now);
+    if (this.claimedAt.has(messageId)) return false;
+
+    this.claimedAt.set(messageId, now);
+    this.evictOverflow();
+    return true;
+  }
+
+  private prune(now: number): void {
+    for (const [messageId, claimedAt] of this.claimedAt) {
+      if (now - claimedAt >= this.ttlMs) this.claimedAt.delete(messageId);
+    }
+  }
+
+  private evictOverflow(): void {
+    while (this.claimedAt.size > this.maxEntries) {
+      const oldestMessageId = this.claimedAt.keys().next().value;
+      if (oldestMessageId === undefined) return;
+      this.claimedAt.delete(oldestMessageId);
+    }
+  }
+}

apps/gateway/src/plugin/plugin.module.ts

@@ -50,19 +50,41 @@ class TelegramChannelPluginAdapter implements IChannelPlugin {
 
 const DEFAULT_GATEWAY_URL = 'http://localhost:14242';
 
+function requiredDiscordAllowlist(name: string): string[] {
+  const value = process.env[name]
+    ?.split(',')
+    .map((id: string): string => id.trim())
+    .filter((id: string): boolean => id.length > 0);
+  if (!value || value.length === 0) {
+    throw new Error(`${name} is required when DISCORD_BOT_TOKEN is configured`);
+  }
+  return value;
+}
+
 function createPluginRegistry(): IChannelPlugin[] {
   const plugins: IChannelPlugin[] = [];
   const discordToken = process.env['DISCORD_BOT_TOKEN'];
   const discordGuildId = process.env['DISCORD_GUILD_ID'];
   const discordGatewayUrl = process.env['DISCORD_GATEWAY_URL'] ?? DEFAULT_GATEWAY_URL;
+  const discordServiceToken = process.env['DISCORD_SERVICE_TOKEN'];
+  const discordServiceUserId = process.env['DISCORD_SERVICE_USER_ID'];
 
   if (discordToken) {
+    if (!discordServiceToken || !discordServiceUserId) {
+      throw new Error(
+        'DISCORD_SERVICE_TOKEN and DISCORD_SERVICE_USER_ID are required when DISCORD_BOT_TOKEN is configured',
+      );
+    }
     plugins.push(
       new DiscordChannelPluginAdapter(
         new DiscordPlugin({
           token: discordToken,
           guildId: discordGuildId,
           gatewayUrl: discordGatewayUrl,
+          serviceToken: discordServiceToken,
+          allowedGuildIds: requiredDiscordAllowlist('DISCORD_ALLOWED_GUILD_IDS'),
+          allowedChannelIds: requiredDiscordAllowlist('DISCORD_ALLOWED_CHANNEL_IDS'),
+          allowedUserIds: requiredDiscordAllowlist('DISCORD_ALLOWED_USER_IDS'),
         }),
       ),
     );

apps/gateway/src/preferences/system-override.service.ts

@@ -1,9 +1,13 @@
 import { Injectable, Logger } from '@nestjs/common';
 import { createQueue, type QueueHandle } from '@mosaicstack/queue';
+import type { ActorTenantScope } from '../auth/session-scope.js';
 
-const SESSION_SYSTEM_KEY = (sessionId: string) => `mosaic:session:${sessionId}:system`;
-const SESSION_SYSTEM_FRAGMENTS_KEY = (sessionId: string) =>
-  `mosaic:session:${sessionId}:system:fragments`;
+const scopedSessionId = (sessionId: string, scope: ActorTenantScope) =>
+  `${scope.tenantId}:${scope.userId}:${sessionId}`;
+const SESSION_SYSTEM_KEY = (sessionId: string, scope: ActorTenantScope) =>
+  `mosaic:session:${scopedSessionId(sessionId, scope)}:system`;
+const SESSION_SYSTEM_FRAGMENTS_KEY = (sessionId: string, scope: ActorTenantScope) =>
+  `mosaic:session:${scopedSessionId(sessionId, scope)}:system:fragments`;
 const SYSTEM_OVERRIDE_TTL_SECONDS = 604800; // 7 days
 
 interface OverrideFragment {
@@ -20,9 +24,9 @@ export class SystemOverrideService {
     this.handle = createQueue();
   }
 
-  async set(sessionId: string, override: string): Promise<void> {
+  async set(sessionId: string, override: string, scope: ActorTenantScope): Promise<void> {
     // Load existing fragments
-    const existing = await this.handle.redis.get(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId));
+    const existing = await this.handle.redis.get(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope));
     const fragments: OverrideFragment[] = existing
       ? (JSON.parse(existing) as OverrideFragment[])
       : [];
@@ -37,11 +41,11 @@ export class SystemOverrideService {
     // Store both: fragments array and condensed result
     const pipeline = this.handle.redis.pipeline();
     pipeline.setex(
-      SESSION_SYSTEM_FRAGMENTS_KEY(sessionId),
+      SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope),
       SYSTEM_OVERRIDE_TTL_SECONDS,
       JSON.stringify(fragments),
     );
-    pipeline.setex(SESSION_SYSTEM_KEY(sessionId), SYSTEM_OVERRIDE_TTL_SECONDS, condensed);
+    pipeline.setex(SESSION_SYSTEM_KEY(sessionId, scope), SYSTEM_OVERRIDE_TTL_SECONDS, condensed);
     await pipeline.exec();
 
     this.logger.debug(
@@ -49,21 +53,21 @@ export class SystemOverrideService {
     );
   }
 
-  async get(sessionId: string): Promise<string | null> {
-    return this.handle.redis.get(SESSION_SYSTEM_KEY(sessionId));
+  async get(sessionId: string, scope: ActorTenantScope): Promise<string | null> {
+    return this.handle.redis.get(SESSION_SYSTEM_KEY(sessionId, scope));
   }
 
-  async renew(sessionId: string): Promise<void> {
+  async renew(sessionId: string, scope: ActorTenantScope): Promise<void> {
     const pipeline = this.handle.redis.pipeline();
-    pipeline.expire(SESSION_SYSTEM_KEY(sessionId), SYSTEM_OVERRIDE_TTL_SECONDS);
-    pipeline.expire(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId), SYSTEM_OVERRIDE_TTL_SECONDS);
+    pipeline.expire(SESSION_SYSTEM_KEY(sessionId, scope), SYSTEM_OVERRIDE_TTL_SECONDS);
+    pipeline.expire(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope), SYSTEM_OVERRIDE_TTL_SECONDS);
     await pipeline.exec();
   }
 
-  async clear(sessionId: string): Promise<void> {
+  async clear(sessionId: string, scope: ActorTenantScope): Promise<void> {
     await this.handle.redis.del(
-      SESSION_SYSTEM_KEY(sessionId),
-      SESSION_SYSTEM_FRAGMENTS_KEY(sessionId),
+      SESSION_SYSTEM_KEY(sessionId, scope),
+      SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope),
     );
     this.logger.debug(`Cleared system override for session ${sessionId}`);
   }

apps/gateway/src/queue/queue.service.ts

@@ -162,6 +162,23 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
     );
   }
 
+  /**
+   * Remove every existing repeatable schedule for a job name. This supports
+   * safe retirement of previously registered system-wide jobs.
+   */
+  async removeRepeatableJobs(queueName: string, jobName: string): Promise<number> {
+    const queue = this.getQueue(queueName);
+    const jobs = await queue.getRepeatableJobs();
+    const matchingJobs = jobs.filter((job) => job.name === jobName);
+    await Promise.all(matchingJobs.map((job) => queue.removeRepeatableByKey(job.key)));
+    if (matchingJobs.length > 0) {
+      this.logger.log(
+        `Removed ${matchingJobs.length} repeatable "${jobName}" job(s) from "${queueName}"`,
+      );
+    }
+    return matchingJobs.length;
+  }
+
   /**
    * Register a Worker for the given queue name with error handling and
    * exponential backoff.

deploy/portainer/README.md

@@ -0,0 +1,70 @@
+# deploy/portainer/
+
+Portainer stack templates for Mosaic Stack deployments.
+
+## Files
+
+| File                       | Purpose                                                                                                        |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `federated-test.stack.yml` | Docker Swarm stack for federation end-to-end test instances (`mos-test-1.woltje.com`, `mos-test-2.woltje.com`) |
+
+---
+
+## federated-test.stack.yml
+
+A self-contained Swarm stack that boots a federated-tier Mosaic gateway with co-located Postgres 17 (pgvector) and Valkey 8. This is a **test template** — production deployments will use a separate template with stricter resource limits and Docker secrets.
+
+### Deploy via Portainer UI
+
+1. Log into Portainer.
+2. Navigate to **Stacks → Add stack**.
+3. Set a stack name matching `STACK_NAME` below (e.g. `mos-test-1`).
+4. Choose **Web editor** and paste the contents of `federated-test.stack.yml`.
+5. Scroll to **Environment variables** and add each variable listed below.
+6. Click **Deploy the stack**.
+
+### Required environment variables
+
+| Variable             | Example                                 | Notes                                                    |
+| -------------------- | --------------------------------------- | -------------------------------------------------------- |
+| `STACK_NAME`         | `mos-test-1`                            | Unique per stack — used in Traefik router/service names. |
+| `HOST_FQDN`          | `mos-test-1.woltje.com`                 | Fully-qualified hostname served by this stack.           |
+| `POSTGRES_PASSWORD`  | _(generate randomly)_                   | Database password. Do **not** reuse between stacks.      |
+| `BETTER_AUTH_SECRET` | _(generate: `openssl rand -base64 32`)_ | BetterAuth session signing key.                          |
+| `BETTER_AUTH_URL`    | `https://mos-test-1.woltje.com`         | Public base URL of the gateway.                          |
+
+Optional variables (uncomment in the YAML or set in Portainer):
+
+| Variable                      | Notes                                                      |
+| ----------------------------- | ---------------------------------------------------------- |
+| `ANTHROPIC_API_KEY`           | Enable Claude models.                                      |
+| `OPENAI_API_KEY`              | Enable OpenAI models.                                      |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Forward traces to a collector (e.g. `http://jaeger:4318`). |
+
+### Required external resources
+
+Before deploying, ensure the following exist on the Swarm:
+
+1. **`traefik-public` overlay network** — shared network Traefik uses to route traffic to stacks.
+   ```bash
+   docker network create --driver overlay --attachable traefik-public
+   ```
+2. **`letsencrypt` cert resolver** — configured in the Traefik Swarm stack. The stack template references `tls.certresolver=letsencrypt`; the name must match your Traefik config.
+3. **DNS A record** — `${HOST_FQDN}` must resolve to the Swarm ingress IP (or a Cloudflare-proxied address pointing there).
+
+### Deployed instances
+
+| Stack name   | HOST_FQDN               | Purpose                            |
+| ------------ | ----------------------- | ---------------------------------- |
+| `mos-test-1` | `mos-test-1.woltje.com` | DEPLOY-03 — first federation peer  |
+| `mos-test-2` | `mos-test-2.woltje.com` | DEPLOY-04 — second federation peer |
+
+### Image
+
+The gateway image is pinned by digest to `fed-v0.1.0-m1` (verified in DEPLOY-01). Update the digest in the YAML when promoting a new build — never use `:latest` or a mutable tag in Swarm.
+
+### Notes
+
+- This template boots a **vanilla M1-baseline gateway** in federated tier. Federation grants (Step-CA, mTLS) are M2+ scope and not included here.
+- Each stack gets its own Postgres volume (`postgres-data`) and Valkey volume (`valkey-data`) scoped to the stack name by Swarm.
+- `depends_on` is honoured by Compose but ignored by Swarm — healthchecks on Postgres and Valkey ensure the gateway retries until they are ready.

deploy/portainer/federated-test.stack.yml

@@ -0,0 +1,160 @@
+# deploy/portainer/federated-test.stack.yml
+#
+# Portainer / Docker Swarm stack template — federated-tier test instance
+#
+# PURPOSE
+#   Deploys a single federated-tier Mosaic gateway with co-located Postgres
+#   (pgvector) and Valkey for end-to-end federation testing. Intended for
+#   mos-test-1.woltje.com and mos-test-2.woltje.com (DEPLOY-03/04).
+#
+# REQUIRED ENV VARS (set per-stack in Portainer → Stacks → Environment variables)
+#   STACK_NAME          Unique name for Traefik router/service labels.
+#                       Examples: mos-test-1, mos-test-2
+#   HOST_FQDN           Fully-qualified domain name served by this stack.
+#                       Examples: mos-test-1.woltje.com, mos-test-2.woltje.com
+#   POSTGRES_PASSWORD   Database password — set per stack; do NOT commit a default.
+#   BETTER_AUTH_SECRET  Random 32-char string for BetterAuth session signing.
+#                       Generate: openssl rand -base64 32
+#   BETTER_AUTH_URL     Public gateway base URL, e.g. https://mos-test-1.woltje.com
+#
+# OPTIONAL ENV VARS (uncomment and set in Portainer to enable features)
+#   ANTHROPIC_API_KEY   sk-ant-...
+#   OPENAI_API_KEY      sk-...
+#   OTEL_EXPORTER_OTLP_ENDPOINT  http://<collector>:4318
+#   OTEL_SERVICE_NAME   (default: mosaic-gateway)
+#
+# REQUIRED EXTERNAL RESOURCES
+#   traefik-public      Docker overlay network — must exist before deploying.
+#                       Create: docker network create --driver overlay --attachable traefik-public
+#   letsencrypt         Traefik cert resolver configured on the Swarm manager.
+#   DNS A record        ${HOST_FQDN} → Swarm ingress IP (or Cloudflare proxy).
+#
+# IMAGE
+#   Pinned to sha-9f1a081 (main HEAD post-#488 Dockerfile fix). The previous
+#   pin (fed-v0.1.0-m1, sha256:9b72e2...) had a broken pnpm copy and could
+#   not resolve @mosaicstack/storage at runtime. The new digest was smoke-
+#   tested locally — gateway boots, imports resolve, tier-detector runs.
+#   Update digest here when promoting a new build.
+#
+# HEALTHCHECK NOTE (2026-04-21)
+#   Switched from busybox wget to node http.get on 127.0.0.1 (not localhost) to
+#   avoid IPv6 resolution issues on Alpine. Retries increased to 5 and
+#   start_period to 60s to cover the NestJS/GC cold-start window (~40-50s).
+#   restart_policy set to `any` so SIGTERM/clean-exit also triggers restart.
+#
+# NOTE: This is a TEST template — production deployments use a separate
+#       parameterised template with stricter resource limits and secrets.
+
+version: '3.9'
+
+services:
+  gateway:
+    image: git.mosaicstack.dev/mosaicstack/stack/gateway@sha256:1069117740e00ccfeba357cae38c43f3729fe5ae702740ce474f6512414d7c02
+    # Tag for human reference: sha-9f1a081 (post-#488 Dockerfile fix; smoke-tested locally)
+    environment:
+      # ── Tier ───────────────────────────────────────────────────────────────
+      MOSAIC_TIER: federated
+
+      # ── Database ───────────────────────────────────────────────────────────
+      DATABASE_URL: postgres://gateway:${POSTGRES_PASSWORD}@postgres:5432/mosaic
+
+      # ── Queue ──────────────────────────────────────────────────────────────
+      VALKEY_URL: redis://valkey:6379
+
+      # ── Gateway ────────────────────────────────────────────────────────────
+      GATEWAY_PORT: '3000'
+      GATEWAY_CORS_ORIGIN: https://${HOST_FQDN}
+
+      # ── Auth ───────────────────────────────────────────────────────────────
+      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
+      BETTER_AUTH_URL: https://${HOST_FQDN}
+
+      # ── Observability ──────────────────────────────────────────────────────
+      OTEL_SERVICE_NAME: ${STACK_NAME:-mosaic-gateway}
+      # OTEL_EXPORTER_OTLP_ENDPOINT: http://<collector>:4318
+
+      # ── AI Providers (uncomment to enable) ─────────────────────────────────
+      # ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
+      # OPENAI_API_KEY: ${OPENAI_API_KEY}
+    networks:
+      - federated-test
+      - traefik-public
+    deploy:
+      replicas: 1
+      restart_policy:
+        condition: any
+        delay: 5s
+        max_attempts: 3
+      labels:
+        - 'traefik.enable=true'
+        - 'traefik.docker.network=traefik-public'
+        - 'traefik.http.routers.${STACK_NAME}.rule=Host(`${HOST_FQDN}`)'
+        - 'traefik.http.routers.${STACK_NAME}.entrypoints=websecure'
+        - 'traefik.http.routers.${STACK_NAME}.tls=true'
+        - 'traefik.http.routers.${STACK_NAME}.tls.certresolver=letsencrypt'
+        - 'traefik.http.services.${STACK_NAME}.loadbalancer.server.port=3000'
+    healthcheck:
+      test:
+        - 'CMD'
+        - 'node'
+        - '-e'
+        - "require('http').get('http://127.0.0.1:3000/health',r=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"
+      interval: 30s
+      timeout: 5s
+      retries: 5
+      start_period: 60s
+    depends_on:
+      - postgres
+      - valkey
+
+  postgres:
+    image: pgvector/pgvector:pg17
+    environment:
+      POSTGRES_USER: gateway
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: mosaic
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    networks:
+      - federated-test
+    deploy:
+      replicas: 1
+      restart_policy:
+        condition: on-failure
+        delay: 5s
+        max_attempts: 3
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U gateway']
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
+
+  valkey:
+    image: valkey/valkey:8-alpine
+    volumes:
+      - valkey-data:/data
+    networks:
+      - federated-test
+    deploy:
+      replicas: 1
+      restart_policy:
+        condition: on-failure
+        delay: 5s
+        max_attempts: 3
+    healthcheck:
+      test: ['CMD', 'valkey-cli', 'ping']
+      interval: 10s
+      timeout: 3s
+      retries: 5
+      start_period: 5s
+
+volumes:
+  postgres-data:
+  valkey-data:
+
+networks:
+  federated-test:
+    driver: overlay
+  traefik-public:
+    external: true

docker-compose.federated.yml

@@ -27,6 +27,7 @@ services:
   postgres-federated:
     image: pgvector/pgvector:pg17
     profiles: [federated]
+    restart: unless-stopped
     ports:
       - '${PG_FEDERATED_HOST_PORT:-5433}:5432'
     environment:
@@ -45,6 +46,7 @@ services:
   valkey-federated:
     image: valkey/valkey:8-alpine
     profiles: [federated]
+    restart: unless-stopped
     ports:
       - '${VALKEY_FEDERATED_HOST_PORT:-6380}:6379'
     volumes:
@@ -55,6 +57,64 @@ services:
       timeout: 3s
       retries: 5
 
+  # ---------------------------------------------------------------------------
+  # Step-CA — Mosaic Federation internal certificate authority
+  #
+  # Image: pinned to 0.27.4 (latest stable as of late 2025).
+  # `latest` is forbidden per Mosaic image policy (immutable tag required for
+  # reproducible deployments and digest-first promotion in CI).
+  #
+  # Profile: `federated` — this service must not start in non-federated dev.
+  #
+  # Password:
+  #   Dev:  bind-mount ./infra/step-ca/dev-password (gitignored; copy from
+  #         ./infra/step-ca/dev-password.example and customise locally).
+  #   Prod: replace the bind-mount with a Docker secret:
+  #           secrets:
+  #             ca_password:
+  #               external: true
+  #         and reference it as `/run/secrets/ca_password` (same path the
+  #         init script already uses).
+  #
+  # Provisioner: "mosaic-fed" (consumed by apps/gateway/src/federation/ca.service.ts)
+  # ---------------------------------------------------------------------------
+  step-ca:
+    image: smallstep/step-ca:0.27.4
+    profiles: [federated]
+    restart: unless-stopped
+    ports:
+      - '${STEP_CA_HOST_PORT:-9000}:9000'
+    volumes:
+      - step_ca_data:/home/step
+      # init script — executed as the container entrypoint
+      - ./infra/step-ca/init.sh:/usr/local/bin/mosaic-step-ca-init.sh:ro
+      # X.509 template skeleton (wired in M2-04)
+      - ./infra/step-ca/templates:/etc/step-ca-templates:ro
+      # Dev password file — GITIGNORED; copy from dev-password.example
+      # In production, replace this with a Docker secret (see comment above).
+      - ./infra/step-ca/dev-password:/run/secrets/ca_password:ro
+    entrypoint: ['/bin/sh', '/usr/local/bin/mosaic-step-ca-init.sh']
+    healthcheck:
+      # The healthcheck requires the root cert to exist, which is only true
+      # after init.sh has completed on first boot. start_period gives init
+      # time to finish before Docker starts counting retries.
+      test:
+        [
+          'CMD',
+          'step',
+          'ca',
+          'health',
+          '--ca-url',
+          'https://localhost:9000',
+          '--root',
+          '/home/step/certs/root_ca.crt',
+        ]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+
 volumes:
   pg_federated_data:
   valkey_federated_data:
+  step_ca_data:

docker/appservice.Dockerfile

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

docker/gateway.Dockerfile

@@ -5,18 +5,27 @@ RUN corepack enable
 
 FROM base AS builder
 WORKDIR /app
+# Copy workspace manifests first for layer-cached install
 COPY pnpm-workspace.yaml pnpm-lock.yaml package.json ./
 COPY apps/gateway/package.json ./apps/gateway/
 COPY packages/ ./packages/
+COPY plugins/ ./plugins/
 RUN pnpm install --frozen-lockfile
 COPY . .
-RUN pnpm --filter @mosaic/gateway build
+# Build gateway and all of its workspace dependencies via turbo dependency graph
+RUN pnpm turbo run build --filter @mosaicstack/gateway...
+# Produce a self-contained deploy artifact: flat node_modules, no pnpm symlinks
+# --legacy is required for pnpm v10 when inject-workspace-packages is not set
+RUN pnpm --filter @mosaicstack/gateway --prod deploy --legacy /deploy
 
 FROM base AS runner
 WORKDIR /app
 ENV NODE_ENV=production
+# Use the pnpm deploy output — resolves all deps into a flat, self-contained node_modules
+COPY --from=builder /deploy/node_modules ./node_modules
+COPY --from=builder /deploy/package.json ./package.json
+# dist is declared in package.json "files" so pnpm deploy copies it into /deploy;
+# copy from builder explicitly as belt-and-suspenders
 COPY --from=builder /app/apps/gateway/dist ./dist
-COPY --from=builder /app/apps/gateway/package.json ./package.json
-COPY --from=builder /app/node_modules ./node_modules
 EXPOSE 4000
 CMD ["node", "dist/main.js"]

docs/MISSION-MANIFEST.md

@@ -67,10 +67,11 @@ The MVP is complete when ALL declared workstreams are complete AND every cross-c
 
 ## Workstreams
 
-| #   | ID  | Name                                        | Status            | Manifest                                                                | Notes                                               |
-| --- | --- | ------------------------------------------- | ----------------- | ----------------------------------------------------------------------- | --------------------------------------------------- |
-| W1  | FED | Federation v1                               | planning-complete | [docs/federation/MISSION-MANIFEST.md](./federation/MISSION-MANIFEST.md) | 7 milestones, ~175K tokens, issues #460–#466 filed  |
-| W2+ | TBD | (additional workstreams declared as scoped) | —                 | —                                                                       | Scope creep is expected and explicitly accommodated |
+| #   | ID   | Name                                        | Status            | Manifest                                                                | Notes                                               |
+| --- | ---- | ------------------------------------------- | ----------------- | ----------------------------------------------------------------------- | --------------------------------------------------- |
+| W1  | FED  | Federation v1                               | planning-complete | [docs/federation/MISSION-MANIFEST.md](./federation/MISSION-MANIFEST.md) | 7 milestones, ~175K tokens, issues #460–#466 filed  |
+| W2  | TESS | Tess interaction agent                      | planning-complete | [docs/tess/MISSION-MANIFEST.md](./tess/MISSION-MANIFEST.md)             | 5 milestones; issue #706; M1 issue #707 ready       |
+| W3+ | TBD  | (additional workstreams declared as scoped) | —                 | —                                                                       | Scope creep is expected and explicitly accommodated |
 
 ### Likely Additional Workstreams (Not Yet Declared)
 

docs/PRD.md

@@ -64,6 +64,7 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
 21. `@mosaicstack/cli` — unified `mosaic` CLI
 22. Docker Compose deployment + bare-metal capability
 23. Agent log service — ingest, parse, tier, summarize agent interaction logs
+24. Local durable agent fleet canary — `mosaic fleet` / `mosaic agent` CLI for an isolated tmux-backed canary fleet using a named socket, with roster-driven local customization and rollback-safe verification
 
 ### Out of Scope (v0.1.0)
 
@@ -78,6 +79,102 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
 
 ---
 
+## Tess Interaction Agent Workstream (TESS)
+
+### Problem and Objective
+
+Jason needs one durable, operator-facing Mosaic agent outside Hermes that is reachable through a dedicated Discord channel and CLI, can attach to and operate the Mosaic fleet and transitional Hermes agents, and preserves context across restarts and compaction. Mos remains the coding/general fleet orchestrator; Tess is the complementary human interaction, visibility, control, and migration agent.
+
+The objective is to ship **Tess** (from _tessera_, a piece of a mosaic) as a Pi-native, GPT-5.6 Sol agent with high reasoning. Tess must use Mosaic-owned contracts and plugins so Hermes can be replaced incrementally rather than becoming a permanent architectural dependency.
+
+### Scope
+
+#### In Scope
+
+1. `TESS-ARP-001`: A runtime-neutral `AgentRuntimeProvider` contract supporting `listSessions`, `streamSession`, `sendMessage`, `terminate`, `getSessionTree`, `attach`, health, capability discovery, and normalized events/errors.
+2. `TESS-PI-001`: A long-running Pi-native Tess agent profile/service pinned to GPT-5.6 Sol with high reasoning, explicit tool policy, lifecycle hooks, durable checkpoints, and restart recovery.
+3. `TESS-DSC-001`: Dedicated Discord channel binding to Tess through the Mosaic gateway, with allowlists/RBAC, thread/reply policy, streaming, attachments, approvals, and correlation IDs.
+4. `TESS-CLI-001`: `mosaic tess` CLI commands for chat, status, session listing, attach/detach, send/steer/stop, provider health, and recovery.
+5. `TESS-FLT-001`: Fleet plugin capabilities for roster/status/heartbeat inspection, message delivery, session hierarchy, safe attach, and controlled restart/recovery.
+6. `TESS-MOS-001`: Explicit Mos coordination boundary and tools: hand off orchestration requests, observe mission/task state, receive results, and never silently compete for orchestration authority.
+7. `TESS-HRM-001`: Transitional Hermes adapter for profiles/agents, sessions, streaming/messages, Kanban, skills, memory, tools, cron, and health, using capability negotiation and fail-closed unsupported operations.
+8. `TESS-MEM-001`: Unified memory/retrieval plugin with scoped search/recent/capture/stats, startup context injection, provenance, redaction, namespace isolation, and flat-file/project truth precedence.
+9. `TESS-STA-001`: Durable agent state, inbox, handoff, compaction-recovery, and resume reconstruction.
+10. `TESS-PLG-001`: Plugin/tool catalog covering runtime bootstrap, repository/PR workflow, fleet diagnostics, incident-safe read operations, Discord interaction, and extensible MCP/skill discovery.
+11. `TESS-TRN-001`: Replaceable transport providers: tmux/fleet now, Matrix/native Mosaic transport later, with no Discord/CLI business logic coupled to transport details.
+12. `TESS-SEC-001`: RBAC, per-operation authorization, explicit approval for destructive/privileged/customer-visible actions, audit events, secret/PII redaction, tenant isolation, and bounded command execution.
+13. `TESS-SEC-002`: Command execution SHALL enforce declared scope/role server-side; admin/system and destructive operations SHALL require policy-bound durable approval.
+14. `TESS-SEC-003`: Every session list/read/attach/send/terminate operation SHALL enforce server-derived owner and tenant scope; guessed or client-supplied IDs SHALL grant no authority.
+15. `TESS-SEC-004`: MCP tools SHALL derive actor/tenant from authenticated context and SHALL NOT accept caller-controlled identity fields.
+16. `TESS-SEC-005`: Discord plugin ingress SHALL authenticate service identity, enforce guild/channel/user allowlists, propagate correlation/message IDs, and reject replay.
+17. `TESS-SEC-006`: Secret/PII classification and redaction SHALL occur before persistence and before channel egress, including tool metadata and authentication flows.
+18. `TESS-SEC-007`: Approvals SHALL be one-time, expiring, actor/tenant-bound, and cryptographically bound to the exact structured action digest.
+19. `TESS-SEC-008`: Ingress, provider sends, tool side effects, and responses SHALL use durable inbox/outbox/checkpoints and idempotency records for restart-safe replay.
+20. `TESS-SEC-009`: Garbage collection and retention SHALL be session/tenant scoped unless executed as a separately authorized and audited system-wide job.
+21. `TESS-OBS-001`: Structured logs, traces, health/readiness, provider latency/errors, session lifecycle, tool audit, and actionable recovery diagnostics.
+22. `TESS-MIG-001`: Capability inventory and staged Hermes-to-Mosaic migration matrix with coexistence, cutover, rollback, and deprecation gates.
+
+#### Out of Scope
+
+1. Replacing Mos as coding/general fleet orchestrator.
+2. Making Hermes the Mosaic core or coupling Mosaic domain logic to Hermes schemas.
+3. Migrating every historical chat verbatim; only policy-compliant indexed summaries and user-selected sessions are migrated.
+4. Unrestricted shell execution from Discord.
+5. Full web UI parity in the first Tess operational milestone; gateway contracts must remain web-consumable.
+6. Replacing tmux before Matrix/native transport reaches operational parity.
+
+### Stakeholder and User Requirements
+
+- Jason must be able to converse with the same Tess session from Discord and CLI.
+- Jason must be able to see what is running, stale, blocked, or unhealthy without attaching manually to every session.
+- Jason must be able to attach to Tess and authorized fleet sessions through supported CLI controls.
+- Tess must collaborate with Mos and the fleet while preserving a single clear orchestration authority.
+- The system must migrate useful Hermes/OpenClaw capabilities intentionally, with evidence, instead of copying implementations wholesale.
+
+### Non-Functional Requirements
+
+1. **Security:** default-deny provider/tool capabilities, least privilege, no secrets in logs/prompts/commits, Discord user/channel authorization, and auditable approvals.
+2. **Reliability:** durable inbox/checkpoints; idempotent message handling; reconnect with bounded backoff; no message loss or duplicate execution across gateway restart.
+3. **Performance:** first acknowledgement within 2 seconds when connected; streamed agent output begins within 5 seconds excluding model/provider delay; status reads return within 2 seconds under nominal local conditions.
+4. **Observability:** every ingress message and resulting provider/tool operation carries a correlation ID across Discord, gateway, Tess, provider, and audit events.
+5. **Maintainability:** channel, runtime, transport, memory, and external-agent integrations remain adapter-based with contract tests.
+6. **Privacy:** only scoped context enters external runtimes; persisted messages/memories follow retention and redaction policy.
+7. **Portability:** Tess runs through Pi/Mosaic contracts and does not require Hermes to start or serve native Mosaic operations.
+
+### Acceptance Criteria
+
+1. `AC-TESS-01`: A dedicated Discord channel and `mosaic tess chat` connect to one durable Tess session and stream responses bidirectionally.
+2. `AC-TESS-02`: `mosaic tess status|sessions|tree|attach|send|stop` operate against authorized provider capabilities with stable typed outputs and actionable errors.
+3. `AC-TESS-03`: Tess runs GPT-5.6 Sol at high reasoning and its effective runtime/model/tool policy is visible through status without exposing credentials.
+4. `AC-TESS-04`: Tess can inspect and message the Mosaic fleet, hand orchestration work to Mos, and demonstrate that Tess does not independently claim Mos-owned orchestration work.
+5. `AC-TESS-05`: Hermes adapter demonstrates session listing, streaming/message delivery, hierarchy mapping, and at least one approved capability in each of Kanban, skills, memory, tools, and cron—or reports unsupported capabilities fail-closed.
+6. `AC-TESS-06`: Restart/compaction test preserves session identity, pending inbox, last durable checkpoint, and a resumable handoff without duplicate side effects.
+7. `AC-TESS-07`: Unauthorized Discord users/channels, cross-tenant access, unsafe tool calls, forged approvals, and sensitive-output cases are denied and audited.
+8. `AC-TESS-08`: tmux/fleet and Matrix/native transport implementations pass the same provider contract suite; Matrix may remain non-default until readiness gates pass.
+9. `AC-TESS-09`: Baseline quality gates, unit/integration/contract tests, Discord+CLI E2E, restart/recovery tests, independent code review, and security review are green.
+10. `AC-TESS-10`: Migration matrix documents every audited Hermes/OpenClaw capability as native, adapted, deferred, or rejected, with cutover and rollback evidence.
+11. `AC-TESS-11`: User, admin, developer, API/OpenAPI, operations/recovery, and plugin-authoring documentation is current and linked from the sitemap.
+
+### Constraints, Dependencies, Risks, and Assumptions
+
+- Dependency: Mosaic gateway remains the single API surface; Pi is the native runtime; Valkey/PostgreSQL provide canonical durable state where required.
+- Dependency: Discord bot credentials and dedicated channel ID are deployment secrets provisioned outside source control.
+- Risk: Tess could drift into a second orchestrator. Mitigation: explicit role policy, Mos handoff contract, authority checks, and E2E boundary tests.
+- Risk: broad Hermes compatibility can freeze legacy semantics into Mosaic. Mitigation: Mosaic-owned normalized contracts and capability negotiation.
+- Risk: Discord creates a privileged remote-control surface. Mitigation: pairing/allowlists, RBAC, approvals, rate limits, audit, and safe tool classes.
+- Risk: transcript ingestion can violate privacy or overload memory. Mitigation: scoped opt-in import, redacted summaries, provenance, retention, and deduplication.
+- Risk: current root filesystem has limited headroom. Mitigation: isolated worktrees, no duplicated dependency installation unless required, and cleanup only after active-lane verification.
+- `ASSUMPTION:` The public name is **Tess**, because the user requested a name and the tessera/Mosaic relationship is distinctive; config must permit later display-name changes without renaming APIs or storage keys.
+- `ASSUMPTION:` The dedicated Discord channel ID and final guild policy will be supplied/provisioned during deployment, so implementation uses explicit configuration and fail-fast startup validation.
+- `ASSUMPTION:` tmux/fleet is the production transport for the first operational milestone; Matrix/native transport is implemented behind the same contract and promoted only after parity/reliability verification.
+- `ASSUMPTION:` Project/task truth remains in canonical Mosaic/project stores; semantic memory systems are retrieval/mirror layers, not hidden authorities.
+
+### Testing and Delivery Intent
+
+Delivery uses five gated milestones: runtime contracts/security; Pi service/state; Discord/CLI; fleet/Hermes/plugin suite; migration/Matrix/recovery/qualification. Every source-code task requires tests, independent review, a PR to `main`, terminal-green CI, and issue/task closure. Production activation additionally requires a clean-host Pi launch, dedicated Discord channel smoke test, CLI attach test, restart/recovery drill, and rollback procedure.
+
+---
+
 ## Architecture
 
 ### High-Level System Diagram

docs/TASKS.md

@@ -14,22 +14,24 @@
 
 ## Workstream Rollup
 
-| id  | status            | workstream          | progress         | tasks file                                        | notes                                                           |
-| --- | ----------------- | ------------------- | ---------------- | ------------------------------------------------- | --------------------------------------------------------------- |
-| W1  | planning-complete | Federation v1 (FED) | 0 / 7 milestones | [docs/federation/TASKS.md](./federation/TASKS.md) | M1 task breakdown populated; M2–M7 deferred to mission planning |
+| id  | status            | workstream             | progress         | tasks file                                        | notes                                                           |
+| --- | ----------------- | ---------------------- | ---------------- | ------------------------------------------------- | --------------------------------------------------------------- |
+| W1  | planning-complete | Federation v1 (FED)    | 0 / 7 milestones | [docs/federation/TASKS.md](./federation/TASKS.md) | M1 task breakdown populated; M2–M7 deferred to mission planning |
+| W2  | planning-complete | Tess interaction agent | 0 / 5 milestones | [docs/tess/TASKS.md](./tess/TASKS.md)             | Issue #706; independent planning gate PASS; M1 issue #707 ready |
 
 ## Cross-Cutting Tracking
 
 These are MVP-level checks that don't belong to any single workstream. Updated by the orchestrator at each session.
 
-| id      | status      | description                                                                                              | notes                                                                                   |
-| ------- | ----------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| MVP-T01 | done        | Author MVP-level manifest at `docs/MISSION-MANIFEST.md`                                                  | This session (2026-04-19); PR pending                                                   |
-| MVP-T02 | done        | Archive install-ux-v2 mission state to `docs/archive/missions/install-ux-v2-20260405/`                   | IUV-M03 retroactively closed (shipped via PR #446 + releases 0.0.27→0.0.29)             |
-| MVP-T03 | done        | Land federation v1 planning artifacts on `main`                                                          | PR #468 merged 2026-04-19 (commit `66512550`)                                           |
-| MVP-T04 | not-started | Sync `.mosaic/orchestrator/mission.json` MVP slot with this manifest (milestone enumeration, etc.)       | Coord state file; consider whether to repopulate via `mosaic coord` or accept hand-edit |
-| MVP-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                      |
+| id         | status      | description                                                                                              | notes                                                                                                                         |
+| ---------- | ----------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| MVP-T01    | done        | Author MVP-level manifest at `docs/MISSION-MANIFEST.md`                                                  | This session (2026-04-19); PR pending                                                                                         |
+| MVP-T02    | done        | Archive install-ux-v2 mission state to `docs/archive/missions/install-ux-v2-20260405/`                   | IUV-M03 retroactively closed (shipped via PR #446 + releases 0.0.27→0.0.29)                                                   |
+| MVP-T03    | done        | Land federation v1 planning artifacts on `main`                                                          | PR #468 merged 2026-04-19 (commit `66512550`)                                                                                 |
+| MVP-T04    | not-started | Sync `.mosaic/orchestrator/mission.json` MVP slot with this manifest (milestone enumeration, etc.)       | Coord state file; consider whether to repopulate via `mosaic coord` or accept hand-edit                                       |
+| MVP-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
 
@@ -38,3 +40,54 @@ Active workstream is **W1 — Federation v1**. Workers should:
 1. Read [docs/federation/MISSION-MANIFEST.md](./federation/MISSION-MANIFEST.md) for workstream scope
 2. Read [docs/federation/TASKS.md](./federation/TASKS.md) for the next pending task
 3. Follow per-task agent + tier guidance from the workstream manifest
+
+## Thin-core prompt diet (#528) — feat/contract-thin-core
+
+- Status: PR open, awaiting maintainer merge ratification (fleet-governing change).
+- Cut always-injected contract AGENTS+TOOLS+RUNTIME 8,827→4,122 tok (−53%); all 12 hard gates intact.
+- Validation: deterministic gate-checklist PASS; headless A/B thin 7/9 vs monolith 5/9. Detail: scratchpads/contract-thin-core.md.
+
+## P5 — Overlay composer + cross-harness (#604) — feat/p5-overlay-composer
+
+- Status: MERGED to main (#605). R7 (compose-contract) + R8 (cross-harness) + R9 (composer test).
+- `composeContract({harness, mosaicHome})` pure fn + `.local` overlay deltas-by-value; `mosaic compose-contract <harness>` command; AGENTS bare-launch nudge; composer spec (per-tier anchor + Tier-3 byte-equality). Detail: scratchpads/p5-overlay-composer.md.
+
+## P6 — Docs, compliance matrix, alpha tag (#606) — feat/p6-docs-compliance-alpha
+
+- Status: in-repo deliverables done (CONTRIBUTING.md + harness×gate compliance matrix + check-resident-budget.sh + CI wiring + ALPHA-DOD.md). Remaining: alpha tag v0.0.39-alpha (Lead, post-merge). aiguide reconcile merged (#8). Detail: scratchpads/p6-docs-compliance-alpha.md.
+
+## F3-m3 — mosaic update re-seeds framework + relaunches agents (#609) — feat/f3-m3-update-reseed
+
+- Status: implemented + tested. Closes R13: `mosaic update` now re-seeds the framework (data-safe MOSAIC_SYNC_ONLY) after the CLI install so shipped launcher/runtime changes activate; `--relaunch` restarts rostered agents; `--no-reseed` opts out. Detail: scratchpads/f3-m3-update-reseed.md.
+
+## Fleet-polish bundle — boot-survival symmetry (#611) — feat/fleet-polish-bundle
+
+- Status: MERGED to main. disable-on-remove (boot-resurrection bug, TDD) + add-enable + init-R5 hard guarantee. 4 new + 147 existing fleet tests green. Detail: scratchpads/fleet-polish-bundle.md.
+
+## Fleet enhancer role + two-agent floor (#614) — feat/fleet-enhancer-floor
+
+- Status: MERGED to main. enhancer added to 4 presets; init guarantees 1 orchestrator + >=1 enhancer; remove protects the sole enhancer; enhancer role doc. 155 fleet tests green. Detail: scratchpads/fleet-enhancer-floor.md.
+
+## F4 — Orchestrator chat connector + Matrix (#616) — feat/f4-matrix-connector
+
+- Status: Phase 1 MERGED (#617: connector interface send/subscribe/health + registry + roster schema + design). Phase 2a (#618): Matrix CS-API client + factory. 20 connector tests green; no fleet.ts changes. Remaining Phase 2: init/configure connector-selection UX + roster wiring, systemd launch wiring, Conduit deploy guide. Detail: scratchpads/f4-matrix-connector.md.
+
+## Fleet onboarding-injection — comms cheat-sheet + peer roster (#620) — feat/fleet-comms-onboarding
+
+- Status: implemented + tested. Injects # Fleet Comms (peer roster + cross-host agent-send commands + FLIP-reply + --verify) into each spawned fleet agent via composeContract; optional per-agent host/ssh/socket roster fields (socket: named → -L, unset → default socket no -L). 10 + 2 tests green. Detail: scratchpads/fleet-comms-onboarding.md.
+
+## Fleet stand-up fixes — model_hint→--model + socket-default trap (#626) — feat/fleet-standup-fixes
+
+- Status: implemented + tested. FIX1 model_hint→MOSAIC_AGENT_MODEL→--model. FIX2 absent socket = default tmux socket (no -L) across parse/spawn/systemd-unit/observe (socketArgs helper, bare-empty shellEnvValue, conditional -L). 158 fleet tests green; shipped presets unaffected (explicit socket_name). Detail: scratchpads/fleet-standup-fixes.md.
+
+## north-star doctrine consolidation — doc PR — feat/north-star-doctrine
+
+- Status: applied Mos's consolidated merge-map to docs/fleet/north-star.md (budget governance + control plane/central register + 200k cap + delegation + unified-identity Fleet + role-based naming + tmux security + drift re-captures). Doctrine only; #622/#623/#625/#628 out-of-scope. Conflict checklist green. Detail: scratchpads/north-star-doctrine.md.
+
+## #631 — re-seed preserves user fleet data (CRITICAL) — fix/631-reseed-preserves-fleet-data
+
+- Status: implemented + tested. PRIMARY: install.sh PRESERVE_PATHS += fleet/\*.yaml + fleet/agents + fleet/run (glob-aware cp-fallback); TS parity. SECONDARY: refreshActiveFleetUnits propagates unit fixes to ~/.config/systemd/user on mosaic update. bash F6 + TS + unit tests green. Detail: scratchpads/631-reseed-preserves-fleet.md.
+
+## #633 — comms-block emitter + FLEET-LAUNCH runbook — feat/633-comms-block-runbook
+
+- Status: implemented + tested (TDD). `mosaic fleet comms-block <role> [--host]` wraps resolveCommsBlock → readFleetCommsBlock; fails loud (stderr + exit 1) on unknown role / missing roster instead of silent empty. docs/fleet/FLEET-LAUNCH.md runbook: worker path + orchestrator .env fold (MOSAIC_AGENT_COMMAND; line-41 [-z] short-circuits line-44 yolo hardcode) + 3 launch gotchas + #632 preserve note + North-Star 4-field arc (harness ✅/model ✅ roster-native today; yolo + command/channels = PATH B #636). 177 fleet+comms tests green (6 new resolveCommsBlock cases). PATH A of the A→B→webUI arc. Detail: scratchpads/633-comms-block-runbook.md.

docs/architecture/channel-protocol.md

@@ -232,6 +232,10 @@ The following sections document how each supported channel maps its native messa
 
 **Outbound:** Adapter calls Discord REST `POST /channels/{id}/messages`. Markdown content is sent as-is (Discord renders it). For `contentType = "code"` the adapter wraps in triple-backtick fences with the `metadata.language` tag.
 
+### Discord service ingress security
+
+The Discord adapter is an authenticated gateway service, not an anonymous Socket.IO client. It presents `DISCORD_SERVICE_TOKEN` during its `/chat` connection and signs each inbound envelope using HMAC-SHA-256. The envelope contains the Discord native message ID and a generated correlation ID. Gateway verifies the service credential, signature, and configured guild/channel/user allowlists before agent dispatch, then rejects duplicate native message IDs inside its bounded replay window. All three allowlists are default-deny and required when the Discord plugin is enabled. The service credential is injected at runtime and is never logged or included in protocol payloads.
+
 ---
 
 ### Telegram

docs/audits/AUDIT-2026-02-17-framework-consistency.md

@@ -123,7 +123,7 @@ The following legacy references remain in `mosaic-bootstrap` by design and are n
   - `README.md`
   - `profiles/README.md`
   - `adapters/claude.md`
-  - `runtime/claude/settings-overlays/jarvis-loop.json`
+  - `runtime/claude/settings-overlays/` (sample overlay; now shipped sanitized under `examples/overlays/`)
 
 These are required to support existing Claude runtime integration while keeping Mosaic as canonical source.
 

docs/design/framework-constitution/ALPHA-DOD.md

@@ -0,0 +1,75 @@
+# Constitution Alpha — Definition-of-Done checklist + release notes
+
+Drafted for the `v0.0.39-alpha` tag (Lead cuts after P5 #605 → P6 #607 → aiguide #8 merge).
+Maps every DoD §8 acceptance criterion to its merged evidence. Legend:
+**✅ merged on main** · **⏳ review-ready PR (pending merge)** · **🔲 Lead action**.
+
+## DoD §8 green-checklist
+
+| #   | Acceptance criterion (DESIGN §8)                                                                       | Status | Evidence / PR     |
+| --- | ------------------------------------------------------------------------------------------------------ | ------ | ----------------- |
+| 1   | MIT `LICENSE` (root + framework) + `"license":"MIT"` in package.json                                   | ✅     | P0 #570           |
+| 2   | Three credential-path sites + hook URL fast-failed (no private paths in `*.sh`/hooks)                  | ✅     | P0 #570           |
+| 3   | `verify-sanitized.sh` (two-class, `*.sh`+`*.md`, self-tested) wired **blocking** in CI                 | ✅     | P1 #572           |
+| 4   | Operator data purged from the full set (guides / tools / init-generator)                               | ✅     | P2 #572           |
+| 5   | `rails/`→`tools/` in **both** template families                                                        | ✅     | P2 #572           |
+| 6   | `jarvis-loop.json` deleted; `defaults/SOUL.md` → **neutral sanitized persona** (Q10 decision)          | ✅     | P2 #572           |
+| 7   | `CONSTITUTION.md` extracted (gates one place, capability-verb, §1.4 split, no false "already loaded")  | ✅     | P3 #575 / #577    |
+| 8   | `AGENTS.md`/`STANDARDS.md` out of `PRESERVE_PATHS` + seed-semantics → overwrite in **both** installers | ✅     | P4 #590           |
+| 9   | Snapshot + v2→v3 migration moving user edits to `.local`/`.bak`; `FRAMEWORK_VERSION=3`                 | ✅     | P4 #590 / #593    |
+| 10  | `mosaic-init --non-interactive` fail-closed persona                                                    | ✅     | P4 #590           |
+| 11  | **5-fixture migration matrix** green against **both** installers asserting **injected bytes**          | ✅     | P4 #590 / #593    |
+| 12  | `compose-contract` built + composer unit test (per-tier anchor + Tier-3 byte-equality)                 | ⏳     | P5 #605           |
+| 13  | Resident line-count ceiling enforced (framework-owned resident files)                                  | ⏳     | P6 #607           |
+| 14  | `CONTRIBUTING.md` + harness×gate compliance matrix                                                     | ⏳     | P6 #607           |
+| 15  | `aiguide` reconciled with the Constitution                                                             | ⏳     | aiguide #8        |
+| 16  | Each phase PR CI-green; alpha tag pushed + Gitea release published                                     | 🔲     | Lead (post-merge) |
+
+**Note on #6:** the DoD's literal "delete `defaults/SOUL.md`" was superseded by the resolved
+**Q10** decision — ship a _neutral, operator-agnostic_ example persona instead of deleting it. Main
+carries the sanitized 2.6 KB neutral SOUL.md ("Mosaic agent", no operator identity); the sanitization
+gate confirms it is PII-clean. Criterion met in spirit (no operator persona leaks) via the better option.
+
+**Gate to flip 12–14 → ✅:** merge P5 #605 → P6 #607 (rebase auto-drops the dup format fix
+`adc7df2`/`9f6da92`) → aiguide #8, with `ci.yml` terminal-green on the merged head.
+
+---
+
+## Release notes — `v0.0.39-alpha` (Mosaic Framework Constitution, alpha)
+
+### Mosaic Framework Constitution — Alpha
+
+This release makes the Mosaic framework a **safe-to-open-source, fork-and-customize agent
+operating layer**. It separates the non-negotiable law from operator identity, makes
+customization survive upgrades, and wires the guarantees into CI.
+
+**Highlights**
+
+- **Constitution (L0).** The hard gates now live in one place — `CONSTITUTION.md` — authored in
+  capability verbs, with a thin `AGENTS.md` dispatcher that references the law instead of restating
+  it. Governance model in `constitution/LAYER-MODEL.md`.
+- **Public & sanitized.** MIT-licensed; all operator identity, private paths, and credential sites
+  removed from shipped files. A self-tested `verify-sanitized.sh` gate (two rule classes) runs
+  **blocking** in CI so re-contamination can't merge.
+- **Upgrade-safe customization.** Framework-owned files overwrite cleanly on upgrade while
+  `SOUL.md`/`USER.md`/`*.local.md`/`credentials` are preserved. The v2→v3 migration snapshots first
+  and moves any user-edited `AGENTS.md`/`STANDARDS.md` to `.pre-constitution.bak`/`.local.md` —
+  never silently lost. Verified by a 5-fixture matrix across **both** installers.
+- **Operator overlays.** `mosaic compose-contract <harness>` merges your `*.local.md` deltas into
+  the contract per harness, so customization reaches the model as one pre-merged blob.
+- **Cross-harness.** Single L0 source referenced (never restated) by Claude / Codex / OpenCode / Pi;
+  tiered injection with a byte-equal Tier-3 fallback read.
+- **Guardrails in CI.** Resident line-count ceiling over framework-owned resident files; composer
+  unit test; sanitization gate — all blocking.
+- **Docs.** `CONTRIBUTING.md` with the layer model, dual-installer parity rule, and a harness×gate
+  **compliance matrix** (the Codex/OpenCode/Pi hook-parity gap is tracked for v2).
+
+**Known limitations (accepted, documented in `CONTRIBUTING.md` §9)**
+
+- Bare launches that bypass `mosaic` get base contracts only (no `*.local` overlays) and are not
+  drift-checked by `mosaic doctor` — mitigated by the unconditional Tier-3 self-load + a nudge.
+- Codex/OpenCode/Pi mechanical hook parity, `policy/*.md` composition, and live-launch cross-harness
+  verification are **v2**.
+
+**Phase lineage:** P0 #570 · P1+P2 #572 · P3 #575/#577 · P4 #590/#593 · P5 #605 · P6 #607 ·
+aiguide #8 (umbrella #542).

docs/federation/ADMIN-CLI.md

@@ -0,0 +1,106 @@
+# Mosaic Federation — Admin CLI Reference
+
+Available since: FED-M2
+
+## Grant Management
+
+### Create a grant
+
+```bash
+mosaic federation grant create --user <userId> --peer <peerId> --scope <scope-file.json>
+```
+
+The scope file defines what resources and rows the peer may access:
+
+```json
+{
+  "resources": ["tasks", "notes"],
+  "excluded_resources": ["credentials"],
+  "max_rows_per_query": 100
+}
+```
+
+Valid resource values: `tasks`, `notes`, `credentials`, `teams`, `users`
+
+### List grants
+
+```bash
+mosaic federation grant list [--peer <peerId>] [--status pending|active|revoked|expired]
+```
+
+Shows all federation grants, optionally filtered by peer or status.
+
+### Show a grant
+
+```bash
+mosaic federation grant show <grantId>
+```
+
+Display details of a single grant, including its scope, activation timestamp, and status.
+
+### Revoke a grant
+
+```bash
+mosaic federation grant revoke <grantId> [--reason "Reason text"]
+```
+
+Revoke an active grant immediately. Revoked grants cannot be reactivated. The optional reason is stored in the audit log.
+
+### Generate enrollment token
+
+```bash
+mosaic federation grant token <grantId> [--ttl <seconds>]
+```
+
+Generate a single-use enrollment token for the grant. The default TTL is 900 seconds (15 minutes); maximum 15 minutes.
+
+Output includes the token and the full enrollment URL for the peer to use.
+
+## Peer Management
+
+### Add a peer (remote enrollment)
+
+```bash
+mosaic federation peer add <enrollment-url>
+```
+
+Enroll a remote peer using the enrollment URL obtained from a grant token. The command:
+
+1. Generates a P-256 ECDSA keypair locally
+2. Creates a certificate signing request (CSR)
+3. Submits the CSR to the enrollment URL
+4. Verifies the returned certificate includes the correct custom OIDs (grant ID and subject user ID)
+5. Seals the private key at rest using `BETTER_AUTH_SECRET`
+6. Stores the peer record and sealed key in the local gateway database
+
+Once enrollment completes, the peer can authenticate using the certificate and private key.
+
+### List peers
+
+```bash
+mosaic federation peer list
+```
+
+Shows all enrolled peers, including their certificate fingerprints and activation status.
+
+## REST API Reference
+
+All CLI commands call the local gateway admin API. Equivalent REST endpoints:
+
+| CLI Command  | REST Endpoint                                                                               | Method            |
+| ------------ | ------------------------------------------------------------------------------------------- | ----------------- |
+| grant create | `/api/admin/federation/grants`                                                              | POST              |
+| grant list   | `/api/admin/federation/grants`                                                              | GET               |
+| grant show   | `/api/admin/federation/grants/:id`                                                          | GET               |
+| grant revoke | `/api/admin/federation/grants/:id/revoke`                                                   | PATCH             |
+| grant token  | `/api/admin/federation/grants/:id/tokens`                                                   | POST              |
+| peer list    | `/api/admin/federation/peers`                                                               | GET               |
+| peer add     | `/api/admin/federation/peers/keypair` + enrollment + `/api/admin/federation/peers/:id/cert` | POST, POST, PATCH |
+
+## Security Notes
+
+- **Enrollment tokens** are single-use and expire in 15 minutes (not configurable beyond 15 minutes)
+- **Peer private keys** are encrypted at rest using AES-256-GCM, keyed from `BETTER_AUTH_SECRET`
+- **Custom OIDs** in issued certificates are verified post-issuance: the grant ID and subject user ID must match the certificate extensions
+- **Grant activation** is atomic — concurrent enrollment attempts for the same grant are rejected
+- **Revoked grants** cannot be activated; peers attempting to use a revoked grant's token will be rejected