feat(framework): P0 — MIT license + executable-leak sanitization

First phase of the framework constitution alpha. No behavior change for
configured installs.

- Add MIT LICENSE (root + framework bundle) + "license":"MIT" in manifests
- Drop private jarvis-brain credential fallback at 3 sites; default to
  $HOME/.config/mosaic/credentials.json (aligns with #551)
- prevent-memory-write.sh: soft-degrade OpenBrain nudge via ${OPENBRAIN_URL},
  removing hardcoded brain.woltje.com; still blocks the write

Refs #542, closes #569

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.env.example

@@ -23,8 +23,8 @@ VALKEY_URL=redis://localhost:6380
 
 
 # ─── Gateway ─────────────────────────────────────────────────────────────────
-# TCP port the NestJS/Fastify gateway listens on (default: 4000)
+# TCP port the NestJS/Fastify gateway listens on (default: 14242)
-GATEWAY_PORT=4000
+GATEWAY_PORT=14242
 
 # Comma-separated list of allowed CORS origins.
 # Must include the web app origin in production.
@@ -37,12 +37,12 @@ GATEWAY_CORS_ORIGIN=http://localhost:3000
 BETTER_AUTH_SECRET=change-me-to-a-random-32-char-string
 
 # Public base URL of the gateway (used by BetterAuth for callback URLs)
-BETTER_AUTH_URL=http://localhost:4000
+BETTER_AUTH_URL=http://localhost:14242
 
 
 # ─── Web App (Next.js) ───────────────────────────────────────────────────────
 # Public gateway URL — accessible from the browser, not just the server.
-NEXT_PUBLIC_GATEWAY_URL=http://localhost:4000
+NEXT_PUBLIC_GATEWAY_URL=http://localhost:14242
 
 
 # ─── OpenTelemetry ───────────────────────────────────────────────────────────
@@ -121,12 +121,12 @@ OTEL_SERVICE_NAME=mosaic-gateway
 # ─── Discord Plugin (optional — set DISCORD_BOT_TOKEN to enable) ─────────────
 # DISCORD_BOT_TOKEN=
 # DISCORD_GUILD_ID=
-# DISCORD_GATEWAY_URL=http://localhost:4000
+# DISCORD_GATEWAY_URL=http://localhost:14242
 
 
 # ─── Telegram Plugin (optional — set TELEGRAM_BOT_TOKEN to enable) ───────────
 # TELEGRAM_BOT_TOKEN=
-# TELEGRAM_GATEWAY_URL=http://localhost:4000
+# TELEGRAM_GATEWAY_URL=http://localhost:14242
 
 
 # ─── SSO Providers (add credentials to enable) ───────────────────────────────

.gitignore

@@ -9,3 +9,9 @@ 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/

.npmrc

@@ -1 +1 @@
-@mosaic:registry=https://git.mosaicstack.dev/api/packages/mosaic/npm/
+@mosaicstack:registry=https://git.mosaicstack.dev/api/packages/mosaicstack/npm/

.woodpecker/ci.yml

@@ -15,6 +15,7 @@ steps:
     image: *node_image
     commands:
       - corepack enable
+      - apk add --no-cache python3 make g++
       - pnpm install --frozen-lockfile
 
   typecheck:
@@ -45,27 +46,37 @@ 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
+      # Wait up to 60s for CI postgres to be ready; fail fast if it never comes up.
       - |
-        for i in $(seq 1 30); do
+        ready=0
-          pg_isready -h postgres -p 5432 -U mosaic && break
+        for i in $(seq 1 60); do
-          echo "Waiting for postgres ($i/30)..."
+          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 @mosaic/db run db:migrate
+      - pnpm --filter @mosaicstack/db run db:migrate
       # Run all tests
       - pnpm test
     depends_on:
       - typecheck
 
 services:
-  postgres:
+  ci-postgres:
     image: pgvector/pgvector:pg17
     environment:
       POSTGRES_USER: mosaic

.woodpecker/publish.yml

@@ -33,19 +33,62 @@ steps:
       - *enable_pnpm
       # Configure auth for Gitea npm registry
       - |
-        echo "//git.mosaicstack.dev/api/packages/mosaic/npm/:_authToken=$NPM_TOKEN" > ~/.npmrc
+        echo "//git.mosaicstack.dev/api/packages/mosaicstack/npm/:_authToken=$NPM_TOKEN" > ~/.npmrc
-        echo "@mosaic:registry=https://git.mosaicstack.dev/api/packages/mosaic/npm/" >> ~/.npmrc
+        echo "@mosaicstack:registry=https://git.mosaicstack.dev/api/packages/mosaicstack/npm/" >> ~/.npmrc
-      # Publish all non-private packages (--no-git-checks skips dirty/branch checks in CI)
+      # Publish non-private packages to Gitea.
-      # --filter excludes private apps (gateway, web) and the root
+      #
-      - >
+      # The only publish failure we tolerate is "version already exists" —
-        pnpm --filter "@mosaic/*"
+      # that legitimately happens when only some packages were bumped in
-        --filter "!@mosaic/gateway"
+      # the merge. Any other failure (registry 404, auth error, network
-        --filter "!@mosaic/web"
+      # error) MUST fail the pipeline loudly: the previous
-        publish --no-git-checks --access public
+      # `|| echo "... continuing"` fallback silently hid a 404 from the
-        || echo "[publish] Some packages may already exist at this version — continuing"
+      # Gitea org rename and caused every @mosaicstack/* publish to fall
+      # on the floor while CI still reported green.
+      - |
+        # Portable sh (Alpine ash) — avoid bashisms like PIPESTATUS.
+        set +e
+        pnpm --filter "@mosaicstack/*" --filter "!@mosaicstack/web" publish --no-git-checks --access public >/tmp/publish.log 2>&1
+        EXIT=$?
+        set -e
+        cat /tmp/publish.log
+        if [ "$EXIT" -eq 0 ]; then
+          echo "[publish] all packages published successfully"
+          exit 0
+        fi
+        # Hard registry / auth / network errors → fatal. Match npm's own
+        # error lines specifically to avoid false positives on arbitrary
+        # log text that happens to contain "E404" etc.
+        if grep -qE "npm (error|ERR!) code (E404|E401|ENEEDAUTH|ECONNREFUSED|ETIMEDOUT|ENOTFOUND)" /tmp/publish.log; then
+          echo "[publish] FATAL: registry/auth/network error detected — failing pipeline" >&2
+          exit 1
+        fi
+        # Only tolerate the explicit "version already published" case.
+        # npm returns this as E403 with body "You cannot publish over..."
+        # or EPUBLISHCONFLICT depending on version.
+        if grep -qE "EPUBLISHCONFLICT|You cannot publish over|previously published" /tmp/publish.log; then
+          echo "[publish] some packages already at this version — continuing (non-fatal)"
+          exit 0
+        fi
+        echo "[publish] FATAL: publish failed with unrecognized error — failing pipeline" >&2
+        exit 1
     depends_on:
       - build
 
+  # TODO: Uncomment when ready to publish to npmjs.org
+  # publish-npmjs:
+  #   image: *node_image
+  #   environment:
+  #     NPM_TOKEN:
+  #       from_secret: npmjs_token
+  #   commands:
+  #     - *enable_pnpm
+  #     - apk add --no-cache jq bash
+  #     - bash scripts/publish-npmjs.sh
+  #   depends_on:
+  #     - build
+  #   when:
+  #     - event: [tag]
+
   build-gateway:
     image: gcr.io/kaniko-project/executor:debug
     environment:
@@ -60,17 +103,42 @@ steps:
       - mkdir -p /kaniko/.docker
       - echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$REGISTRY_USER\",\"password\":\"$REGISTRY_PASS\"}}}" > /kaniko/.docker/config.json
       - |
-        DESTINATIONS="--destination git.mosaicstack.dev/mosaic/mosaic-stack/gateway:sha-${CI_COMMIT_SHA:0:7}"
+        DESTINATIONS="--destination git.mosaicstack.dev/mosaicstack/stack/gateway:sha-${CI_COMMIT_SHA:0:7}"
         if [ "$CI_COMMIT_BRANCH" = "main" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaic/mosaic-stack/gateway:latest"
+          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/gateway:latest"
         fi
         if [ -n "$CI_COMMIT_TAG" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaic/mosaic-stack/gateway:$CI_COMMIT_TAG"
+          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/gateway:$CI_COMMIT_TAG"
         fi
         /kaniko/executor --context . --dockerfile docker/gateway.Dockerfile $DESTINATIONS
     depends_on:
       - build
 
+  build-appservice:
+    image: gcr.io/kaniko-project/executor:debug
+    environment:
+      REGISTRY_USER:
+        from_secret: gitea_username
+      REGISTRY_PASS:
+        from_secret: gitea_password
+      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
+      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
+      CI_COMMIT_SHA: ${CI_COMMIT_SHA}
+    commands:
+      - mkdir -p /kaniko/.docker
+      - echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$REGISTRY_USER\",\"password\":\"$REGISTRY_PASS\"}}}" > /kaniko/.docker/config.json
+      - |
+        DESTINATIONS="--destination git.mosaicstack.dev/mosaicstack/stack/appservice:sha-${CI_COMMIT_SHA:0:7}"
+        if [ "$CI_COMMIT_BRANCH" = "main" ]; then
+          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/appservice:latest"
+        fi
+        if [ -n "$CI_COMMIT_TAG" ]; then
+          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/appservice:$CI_COMMIT_TAG"
+        fi
+        /kaniko/executor --context . --dockerfile docker/appservice.Dockerfile $DESTINATIONS
+    depends_on:
+      - build
+
   build-web:
     image: gcr.io/kaniko-project/executor:debug
     environment:
@@ -85,12 +153,12 @@ steps:
       - mkdir -p /kaniko/.docker
       - echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$REGISTRY_USER\",\"password\":\"$REGISTRY_PASS\"}}}" > /kaniko/.docker/config.json
       - |
-        DESTINATIONS="--destination git.mosaicstack.dev/mosaic/mosaic-stack/web:sha-${CI_COMMIT_SHA:0:7}"
+        DESTINATIONS="--destination git.mosaicstack.dev/mosaicstack/stack/web:sha-${CI_COMMIT_SHA:0:7}"
         if [ "$CI_COMMIT_BRANCH" = "main" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaic/mosaic-stack/web:latest"
+          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/web:latest"
         fi
         if [ -n "$CI_COMMIT_TAG" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaic/mosaic-stack/web:$CI_COMMIT_TAG"
+          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/web:$CI_COMMIT_TAG"
         fi
         /kaniko/executor --context . --dockerfile docker/web.Dockerfile $DESTINATIONS
     depends_on:

AGENTS.md

@@ -21,11 +21,11 @@ Mosaic Stack is a self-hosted, multi-user AI agent platform. TypeScript monorepo
 | `apps/web`         | Next.js dashboard               | React 19, Tailwind               |
 | `packages/types`   | Shared TypeScript contracts     | class-validator                  |
 | `packages/db`      | Drizzle ORM schema + migrations | drizzle-orm, postgres            |
-| `packages/auth`    | BetterAuth configuration        | better-auth, @mosaic/db          |
+| `packages/auth`    | BetterAuth configuration        | better-auth, @mosaicstack/db     |
-| `packages/brain`   | Data layer (PG-backed)          | @mosaic/db                       |
+| `packages/brain`   | Data layer (PG-backed)          | @mosaicstack/db                  |
 | `packages/queue`   | Valkey task queue + MCP         | ioredis                          |
-| `packages/coord`   | Mission coordination            | @mosaic/queue                    |
+| `packages/coord`   | Mission coordination            | @mosaicstack/queue               |
-| `packages/cli`     | Unified CLI + Pi TUI            | Ink, Pi SDK                      |
+| `packages/mosaic`  | Unified `mosaic` CLI + TUI      | Ink, Pi SDK, commander           |
 | `plugins/discord`  | Discord channel plugin          | discord.js                       |
 | `plugins/telegram` | Telegram channel plugin         | Telegraf                         |
 
@@ -33,9 +33,9 @@ Mosaic Stack is a self-hosted, multi-user AI agent platform. TypeScript monorepo
 
 1. Gateway is the single API surface — all clients connect through it
 2. Pi SDK is ESM-only — gateway and CLI must use ESM
-3. Socket.IO typed events defined in `@mosaic/types` enforce compile-time contracts
+3. Socket.IO typed events defined in `@mosaicstack/types` enforce compile-time contracts
 4. OTEL auto-instrumentation loads before NestJS bootstrap
-5. BetterAuth manages auth tables; schema defined in `@mosaic/db`
+5. BetterAuth manages auth tables; schema defined in `@mosaicstack/db`
 6. Docker Compose provides PG (5433), Valkey (6380), OTEL Collector (4317/4318), Jaeger (16686)
 7. Explicit `@Inject()` decorators required in NestJS (tsx/esbuild doesn't emit decorator metadata)
 
@@ -58,14 +58,14 @@ pnpm typecheck && pnpm lint && pnpm format:check  # Quality gates
 
 The `agent` column specifies the required model for each task. **This is set at task creation by the orchestrator and must not be changed by workers.**
 
-| Value    | When to use                                                 | Budget                     |
+| Value     | When to use                                                 | Budget                     |
-| -------- | ----------------------------------------------------------- | -------------------------- |
+| --------- | ----------------------------------------------------------- | -------------------------- |
-| `codex`  | All coding tasks (default for implementation)               | OpenAI credits — preferred |
+| `codex`   | All coding tasks (default for implementation)               | OpenAI credits — preferred |
-| `glm-5`  | Cost-sensitive coding where Codex is unavailable            | Z.ai credits               |
+| `glm-5.1` | Cost-sensitive coding where Codex is unavailable            | Z.ai credits               |
-| `haiku`  | Review gates, verify tasks, status checks, docs-only        | Cheapest Claude tier       |
+| `haiku`   | Review gates, verify tasks, status checks, docs-only        | Cheapest Claude tier       |
-| `sonnet` | Complex planning, multi-file reasoning, architecture review | Claude quota               |
+| `sonnet`  | Complex planning, multi-file reasoning, architecture review | Claude quota               |
-| `opus`   | Major cross-cutting architecture decisions ONLY             | Most expensive — minimize  |
+| `opus`    | Major cross-cutting architecture decisions ONLY             | Most expensive — minimize  |
-| `—`      | No preference / auto-select cheapest capable                | Pipeline decides           |
+| `—`       | No preference / auto-select cheapest capable                | Pipeline decides           |
 
 Pipeline crons read this column and spawn accordingly. Workers never modify `docs/TASKS.md` — only the orchestrator writes it.
 

CLAUDE.md

@@ -10,7 +10,7 @@ Self-hosted, multi-user AI agent platform. TypeScript monorepo.
 - **Web**: Next.js 16 + React 19 (`apps/web`)
 - **ORM**: Drizzle ORM + PostgreSQL 17 + pgvector (`packages/db`)
 - **Auth**: BetterAuth (`packages/auth`)
-- **Agent**: Pi SDK (`packages/agent`, `packages/cli`)
+- **Agent**: Pi SDK (`packages/agent`, `packages/mosaic`)
 - **Queue**: Valkey 8 (`packages/queue`)
 - **Build**: pnpm workspaces + Turborepo
 - **CI**: Woodpecker CI
@@ -26,13 +26,13 @@ pnpm test             # Vitest (all packages)
 pnpm build            # Build all packages
 
 # Database
-pnpm --filter @mosaic/db db:push      # Push schema to PG (dev)
+pnpm --filter @mosaicstack/db db:push      # Push schema to PG (dev)
-pnpm --filter @mosaic/db db:generate  # Generate migrations
+pnpm --filter @mosaicstack/db db:generate  # Generate migrations
-pnpm --filter @mosaic/db db:migrate   # Run migrations
+pnpm --filter @mosaicstack/db db:migrate   # Run migrations
 
 # Dev
 docker compose up -d                  # Start PG, Valkey, OTEL, Jaeger
-pnpm --filter @mosaic/gateway exec tsx src/main.ts  # Start gateway
+pnpm --filter @mosaicstack/gateway exec tsx src/main.ts  # Start gateway
 ```
 
 ## Conventions

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

@@ -7,26 +7,39 @@ Mosaic gives you a unified launcher for Claude Code, Codex, OpenCode, and Pi —
 ## Quick Install
 
 ```bash
-bash <(curl -fsSL https://git.mosaicstack.dev/mosaic/mosaic-stack/raw/branch/main/tools/install.sh)
+curl -fsSL https://mosaicstack.dev/install.sh | bash
+```
+
+Or use the direct URL:
+
+```bash
+bash <(curl -fsSL https://git.mosaicstack.dev/mosaicstack/stack/raw/branch/main/tools/install.sh)
+```
+
+The installer auto-launches the setup wizard, which walks you through gateway install and verification. Flags for non-interactive use:
+
+```bash
+bash <(curl -fsSL …) --yes               # Accept all defaults
+bash <(curl -fsSL …) --yes --no-auto-launch  # Install only, skip wizard
 ```
 
 This installs both components:
 
-| Component       | What                                                  | Where                |
+| Component               | What                                                             | Where                |
-| --------------- | ----------------------------------------------------- | -------------------- |
+| ----------------------- | ---------------------------------------------------------------- | -------------------- |
-| **Framework**   | Bash launcher, guides, runtime configs, tools, skills | `~/.config/mosaic/`  |
+| **Framework**           | Bash launcher, guides, runtime configs, tools, skills            | `~/.config/mosaic/`  |
-| **@mosaic/cli** | TUI, gateway client, wizard, auto-updater             | `~/.npm-global/bin/` |
+| **@mosaicstack/mosaic** | Unified `mosaic` CLI — TUI, gateway client, wizard, auto-updater | `~/.npm-global/bin/` |
 
-After install, set up your agent identity:
+After install, the wizard runs automatically or you can invoke it manually:
 
 ```bash
-mosaic init          # Interactive wizard
+mosaic wizard        # Full guided setup (gateway install → verify)
 ```
 
 ### Requirements
 
 - Node.js ≥ 20
-- npm (for global @mosaic/cli install)
+- npm (for global @mosaicstack/mosaic install)
 - One or more runtimes: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [OpenCode](https://opencode.ai), or [Pi](https://github.com/mariozechner/pi-coding-agent)
 
 ## Usage
@@ -45,14 +58,40 @@ 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
 mosaic tui                   # Interactive TUI connected to the gateway
-mosaic login                 # Authenticate with a gateway instance
+mosaic gateway login         # Authenticate with a gateway instance
 mosaic sessions list         # List active agent sessions
 ```
 
+### Gateway Management
+
+```bash
+mosaic gateway install       # Install and configure the gateway service
+mosaic gateway verify        # Post-install health check
+mosaic gateway login         # Authenticate and store a session token
+mosaic gateway config rotate-token    # Rotate your API token
+mosaic gateway config recover-token  # Recover a token via BetterAuth cookie
+```
+
+If you already have a gateway account but no token, use `mosaic gateway config recover-token` to retrieve one without recreating your account.
+
+### Configuration
+
+Mosaic supports three storage tiers: `local` (PGlite, single-host), `standalone` (PostgreSQL, single-host), and `federated` (PostgreSQL + pgvector + Valkey, multi-host). See [Federated Tier Setup](docs/federation/SETUP.md) for multi-user and production deployments, or [Migrating to Federated](docs/guides/migrate-tier.md) to upgrade from existing tiers.
+
+```bash
+mosaic config show           # Print full config as JSON
+mosaic config get <key>      # Read a specific key
+mosaic config set <key> <val># Write a key
+mosaic config edit           # Open config in $EDITOR
+mosaic config path           # Print config file path
+```
+
 ### Management
 
 ```bash
@@ -65,6 +104,80 @@ mosaic coord init            # Initialize a new orchestration mission
 mosaic prdy init             # Create a PRD via guided session
 ```
 
+### Sub-package Commands
+
+Each Mosaic sub-package exposes its API surface through the unified CLI:
+
+```bash
+# User management
+mosaic auth users list
+mosaic auth users create
+mosaic auth sso
+
+# Agent brain (projects, missions, tasks)
+mosaic brain projects
+mosaic brain missions
+mosaic brain tasks
+mosaic brain conversations
+
+# Agent forge pipeline
+mosaic forge run
+mosaic forge status
+mosaic forge resume
+mosaic forge personas
+
+# Structured logging
+mosaic log tail
+mosaic log search
+mosaic log export
+mosaic log level
+
+# MACP protocol
+mosaic macp tasks
+mosaic macp submit
+mosaic macp gate
+mosaic macp events
+
+# Agent memory
+mosaic memory search
+mosaic memory stats
+mosaic memory insights
+mosaic memory preferences
+
+# Task queue (Valkey)
+mosaic queue list
+mosaic queue stats
+mosaic queue pause
+mosaic queue resume
+mosaic queue jobs
+mosaic queue drain
+
+# Object storage
+mosaic storage status
+mosaic storage tier
+mosaic storage export
+mosaic storage import
+mosaic storage migrate
+```
+
+### Telemetry
+
+```bash
+# Local observability (OTEL / Jaeger)
+mosaic telemetry local status
+mosaic telemetry local tail
+mosaic telemetry local jaeger
+
+# Remote telemetry (dry-run by default)
+mosaic telemetry status
+mosaic telemetry opt-in
+mosaic telemetry opt-out
+mosaic telemetry test
+mosaic telemetry upload        # Dry-run unless opted in
+```
+
+Consent state is persisted in config. Remote upload is a no-op until you run `mosaic telemetry opt-in`.
+
 ## Development
 
 ### Prerequisites
@@ -76,8 +189,8 @@ mosaic prdy init             # Create a PRD via guided session
 ### Setup
 
 ```bash
-git clone git@git.mosaicstack.dev:mosaic/mosaic-stack.git
+git clone git@git.mosaicstack.dev:mosaicstack/stack.git
-cd mosaic-stack
+cd stack
 
 # Start infrastructure (Postgres, Valkey, Jaeger)
 docker compose up -d
@@ -86,7 +199,7 @@ docker compose up -d
 pnpm install
 
 # Run migrations
-pnpm --filter @mosaic/db run db:migrate
+pnpm --filter @mosaicstack/db run db:migrate
 
 # Start all services in dev mode
 pnpm dev
@@ -126,13 +239,12 @@ npm packages are published to the Gitea package registry on main merges.
 ## Architecture
 
 ```
-mosaic-stack/
+stack/
 ├── apps/
 │   ├── gateway/             NestJS API + WebSocket hub (Fastify, Socket.IO, OTEL)
 │   └── web/                 Next.js dashboard (React 19, Tailwind)
 ├── packages/
-│   ├── cli/                 Mosaic CLI — TUI, gateway client, wizard
+│   ├── mosaic/              Unified CLI — TUI, gateway client, wizard, sub-package commands
-│   ├── mosaic/              Framework — wizard, runtime detection, update checker
 │   ├── types/               Shared TypeScript contracts (Socket.IO typed events)
 │   ├── db/                  Drizzle ORM schema + migrations (pgvector)
 │   ├── auth/                BetterAuth configuration
@@ -153,7 +265,7 @@ mosaic-stack/
 │   ├── macp/                OpenClaw MACP runtime plugin
 │   └── mosaic-framework/    OpenClaw framework injection plugin
 ├── tools/
-│   └── install.sh           Unified installer (framework + npm CLI)
+│   └── install.sh           Unified installer (framework + npm CLI, --yes / --no-auto-launch)
 ├── scripts/agent/           Agent session lifecycle scripts
 ├── docker-compose.yml       Dev infrastructure
 └── .woodpecker/             CI pipeline configs
@@ -163,7 +275,7 @@ mosaic-stack/
 
 - **Gateway is the single API surface** — all clients (TUI, web, Discord, Telegram) connect through it
 - **ESM everywhere** — `"type": "module"`, `.js` extensions in imports, NodeNext resolution
-- **Socket.IO typed events** — defined in `@mosaic/types`, enforced at compile time
+- **Socket.IO typed events** — defined in `@mosaicstack/types`, enforced at compile time
 - **OTEL auto-instrumentation** — loads before NestJS bootstrap
 - **Explicit `@Inject()` decorators** — required since tsx/esbuild doesn't emit decorator metadata
 
@@ -200,7 +312,13 @@ Each stage has a dispatch mode (`exec` for research/review, `yolo` for coding),
 Run the installer again — it handles upgrades automatically:
 
 ```bash
-bash <(curl -fsSL https://git.mosaicstack.dev/mosaic/mosaic-stack/raw/branch/main/tools/install.sh)
+curl -fsSL https://mosaicstack.dev/install.sh | bash
+```
+
+Or use the direct URL:
+
+```bash
+bash <(curl -fsSL https://git.mosaicstack.dev/mosaicstack/stack/raw/branch/main/tools/install.sh)
 ```
 
 Or use the CLI:
@@ -215,10 +333,12 @@ The CLI also performs a background update check on every invocation (cached for
 ### Installer Flags
 
 ```bash
-bash tools/install.sh --check        # Version check only
+bash tools/install.sh --check           # Version check only
-bash tools/install.sh --framework    # Framework only (skip npm CLI)
+bash tools/install.sh --framework       # Framework only (skip npm CLI)
-bash tools/install.sh --cli          # npm CLI only (skip framework)
+bash tools/install.sh --cli             # npm CLI only (skip framework)
-bash tools/install.sh --ref v1.0     # Install from a specific git ref
+bash tools/install.sh --ref v1.0        # Install from a specific git ref
+bash tools/install.sh --yes             # Non-interactive, accept all defaults
+bash tools/install.sh --no-auto-launch  # Skip auto-launch of wizard
 ```
 
 ## Contributing

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

@@ -2,8 +2,7 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
-    "rootDir": "src",
+    "rootDir": "src"
-    "jsx": "react-jsx"
   },
   "include": ["src/**/*"],
   "exclude": ["node_modules", "dist"]

apps/gateway/package.json

@@ -1,9 +1,23 @@
 {
-  "name": "@mosaic/gateway",
+  "name": "@mosaicstack/gateway",
-  "version": "0.0.2",
+  "version": "0.0.6",
-  "private": true,
+  "repository": {
+    "type": "git",
+    "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
+    "directory": "apps/gateway"
+  },
   "type": "module",
   "main": "dist/main.js",
+  "bin": {
+    "mosaic-gateway": "dist/main.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://git.mosaicstack.dev/api/packages/mosaicstack/npm/",
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsx watch src/main.ts",
@@ -14,32 +28,35 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.80.0",
     "@fastify/helmet": "^13.0.2",
-    "@mariozechner/pi-ai": "~0.57.1",
+    "@mariozechner/pi-ai": "^0.65.0",
-    "@mariozechner/pi-coding-agent": "~0.57.1",
+    "@mariozechner/pi-coding-agent": "^0.65.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "@mosaic/auth": "workspace:^",
+    "@mosaicstack/auth": "workspace:^",
-    "@mosaic/brain": "workspace:^",
+    "@mosaicstack/brain": "workspace:^",
-    "@mosaic/coord": "workspace:^",
+    "@mosaicstack/config": "workspace:^",
-    "@mosaic/db": "workspace:^",
+    "@mosaicstack/coord": "workspace:^",
-    "@mosaic/discord-plugin": "workspace:^",
+    "@mosaicstack/db": "workspace:^",
-    "@mosaic/log": "workspace:^",
+    "@mosaicstack/discord-plugin": "workspace:^",
-    "@mosaic/memory": "workspace:^",
+    "@mosaicstack/log": "workspace:^",
-    "@mosaic/queue": "workspace:^",
+    "@mosaicstack/memory": "workspace:^",
-    "@mosaic/telegram-plugin": "workspace:^",
+    "@mosaicstack/queue": "workspace:^",
-    "@mosaic/types": "workspace:^",
+    "@mosaicstack/storage": "workspace:^",
+    "@mosaicstack/telegram-plugin": "workspace:^",
+    "@mosaicstack/types": "workspace:^",
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
     "@nestjs/platform-fastify": "^11.0.0",
     "@nestjs/platform-socket.io": "^11.0.0",
     "@nestjs/throttler": "^6.5.0",
     "@nestjs/websockets": "^11.0.0",
-    "@opentelemetry/auto-instrumentations-node": "^0.71.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.72.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.213.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.213.0",
     "@opentelemetry/resources": "^2.6.0",
     "@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",
@@ -47,20 +64,30 @@
     "class-validator": "^0.15.1",
     "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",
     "reflect-metadata": "^0.2.0",
     "rxjs": "^7.8.0",
     "socket.io": "^4.8.0",
     "uuid": "^11.0.0",
+    "undici": "^7.24.6",
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@nestjs/testing": "^11.1.18",
+    "@swc/core": "^1.15.24",
+    "@swc/helpers": "^0.5.21",
     "@types/node": "^22.0.0",
     "@types/node-cron": "^3.0.11",
+    "@types/supertest": "^7.2.0",
     "@types/uuid": "^10.0.0",
+    "supertest": "^7.2.2",
     "tsx": "^4.0.0",
     "typescript": "^5.8.0",
+    "unplugin-swc": "^1.5.9",
     "vitest": "^2.0.0"
   }
 }

apps/gateway/src/__tests__/conversation-persistence.test.ts

@@ -12,7 +12,7 @@ import { BadRequestException, NotFoundException } from '@nestjs/common';
 import { describe, expect, it, vi, beforeEach } from 'vitest';
 import type { ConversationHistoryMessage } from '../agent/agent.service.js';
 import { ConversationsController } from '../conversations/conversations.controller.js';
-import type { Message } from '@mosaic/brain';
+import type { Message } from '@mosaicstack/brain';
 
 // ---------------------------------------------------------------------------
 // Shared test data

apps/gateway/src/__tests__/cross-user-isolation.test.ts

@@ -18,13 +18,13 @@
  */
 
 import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest';
-import { createDb } from '@mosaic/db';
+import { createDb } from '@mosaicstack/db';
-import { createConversationsRepo } from '@mosaic/brain';
+import { createConversationsRepo } from '@mosaicstack/brain';
-import { createAgentsRepo } from '@mosaic/brain';
+import { createAgentsRepo } from '@mosaicstack/brain';
-import { createPreferencesRepo, createInsightsRepo } from '@mosaic/memory';
+import { createPreferencesRepo, createInsightsRepo } from '@mosaicstack/memory';
-import { users, conversations, messages, agents, preferences, insights } from '@mosaic/db';
+import { users, conversations, messages, agents, preferences, insights } from '@mosaicstack/db';
-import { eq } from '@mosaic/db';
+import { eq } from '@mosaicstack/db';
-import type { DbHandle } from '@mosaic/db';
+import type { DbHandle } from '@mosaicstack/db';
 
 // ─── Fixed IDs so the afterAll cleanup is deterministic ──────────────────────
 

apps/gateway/src/__tests__/integration/federated-boot.pg-unreachable.integration.test.ts

@@ -0,0 +1,64 @@
+/**
+ * Test B — Gateway boot refuses (fail-fast) when PG is unreachable.
+ *
+ * Prereq: docker compose -f docker-compose.federated.yml --profile federated up -d
+ *         (Valkey must be running; only PG is intentionally misconfigured.)
+ * Run:    FEDERATED_INTEGRATION=1 pnpm --filter @mosaicstack/gateway test src/__tests__/integration/federated-boot.pg-unreachable.integration.test.ts
+ *
+ * Skipped when FEDERATED_INTEGRATION !== '1'.
+ */
+
+import net from 'node:net';
+import { beforeAll, describe, expect, it } from 'vitest';
+import { TierDetectionError, detectAndAssertTier } from '@mosaicstack/storage';
+
+const run = process.env['FEDERATED_INTEGRATION'] === '1';
+
+const VALKEY_URL = 'redis://localhost:6380';
+
+/**
+ * Reserves a guaranteed-closed port at runtime by binding to an ephemeral OS
+ * port (port 0) and immediately releasing it. The OS will not reassign the
+ * port during the TIME_WAIT window, so it remains closed for the duration of
+ * this test.
+ */
+async function reserveClosedPort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.listen(0, '127.0.0.1', () => {
+      const addr = server.address();
+      if (typeof addr !== 'object' || !addr) return reject(new Error('no addr'));
+      const port = addr.port;
+      server.close(() => resolve(port));
+    });
+    server.on('error', reject);
+  });
+}
+
+describe.skipIf(!run)('federated boot — PG unreachable', () => {
+  let badPgUrl: string;
+
+  beforeAll(async () => {
+    const closedPort = await reserveClosedPort();
+    badPgUrl = `postgresql://mosaic:mosaic@localhost:${closedPort}/mosaic`;
+  });
+
+  it('detectAndAssertTier throws TierDetectionError with service: postgres when PG is down', async () => {
+    const brokenConfig = {
+      tier: 'federated' as const,
+      storage: {
+        type: 'postgres' as const,
+        url: badPgUrl,
+        enableVector: true,
+      },
+      queue: {
+        type: 'bullmq',
+        url: VALKEY_URL,
+      },
+    };
+
+    await expect(detectAndAssertTier(brokenConfig)).rejects.toSatisfy(
+      (err: unknown) => err instanceof TierDetectionError && err.service === 'postgres',
+    );
+  }, 10_000);
+});

apps/gateway/src/__tests__/integration/federated-boot.success.integration.test.ts

@@ -0,0 +1,50 @@
+/**
+ * Test A — Gateway boot succeeds when federated services are up.
+ *
+ * Prereq: docker compose -f docker-compose.federated.yml --profile federated up -d
+ * Run:    FEDERATED_INTEGRATION=1 pnpm --filter @mosaicstack/gateway test src/__tests__/integration/federated-boot.success.integration.test.ts
+ *
+ * Skipped when FEDERATED_INTEGRATION !== '1'.
+ */
+
+import postgres from 'postgres';
+import { afterAll, describe, expect, it } from 'vitest';
+import { detectAndAssertTier } from '@mosaicstack/storage';
+
+const run = process.env['FEDERATED_INTEGRATION'] === '1';
+
+const PG_URL = 'postgresql://mosaic:mosaic@localhost:5433/mosaic';
+const VALKEY_URL = 'redis://localhost:6380';
+
+const federatedConfig = {
+  tier: 'federated' as const,
+  storage: {
+    type: 'postgres' as const,
+    url: PG_URL,
+    enableVector: true,
+  },
+  queue: {
+    type: 'bullmq',
+    url: VALKEY_URL,
+  },
+};
+
+describe.skipIf(!run)('federated boot — success path', () => {
+  let sql: ReturnType<typeof postgres> | undefined;
+
+  afterAll(async () => {
+    if (sql) {
+      await sql.end({ timeout: 2 }).catch(() => {});
+    }
+  });
+
+  it('detectAndAssertTier resolves without throwing when federated services are up', async () => {
+    await expect(detectAndAssertTier(federatedConfig)).resolves.toBeUndefined();
+  }, 10_000);
+
+  it('pgvector extension is registered (pg_extension row exists)', async () => {
+    sql = postgres(PG_URL, { max: 1, connect_timeout: 5, idle_timeout: 5 });
+    const rows = await sql`SELECT * FROM pg_extension WHERE extname = 'vector'`;
+    expect(rows).toHaveLength(1);
+  }, 10_000);
+});

apps/gateway/src/__tests__/integration/federated-pgvector.integration.test.ts

@@ -0,0 +1,43 @@
+/**
+ * Test C — pgvector extension is functional end-to-end.
+ *
+ * Creates a temp table with a vector(3) column, inserts a row, and queries it
+ * back — confirming the extension is not just registered but operational.
+ *
+ * Prereq: docker compose -f docker-compose.federated.yml --profile federated up -d
+ * Run:    FEDERATED_INTEGRATION=1 pnpm --filter @mosaicstack/gateway test src/__tests__/integration/federated-pgvector.integration.test.ts
+ *
+ * Skipped when FEDERATED_INTEGRATION !== '1'.
+ */
+
+import postgres from 'postgres';
+import { afterAll, describe, expect, it } from 'vitest';
+
+const run = process.env['FEDERATED_INTEGRATION'] === '1';
+
+const PG_URL = 'postgresql://mosaic:mosaic@localhost:5433/mosaic';
+
+let sql: ReturnType<typeof postgres> | undefined;
+
+afterAll(async () => {
+  if (sql) {
+    await sql.end({ timeout: 2 }).catch(() => {});
+  }
+});
+
+describe.skipIf(!run)('federated pgvector — functional end-to-end', () => {
+  it('vector ops round-trip: INSERT [1,2,3] and SELECT returns [1,2,3]', async () => {
+    sql = postgres(PG_URL, { max: 1, connect_timeout: 5, idle_timeout: 5 });
+
+    await sql`CREATE TEMP TABLE t (id int, embedding vector(3))`;
+    await sql`INSERT INTO t VALUES (1, '[1,2,3]')`;
+    const rows = await sql`SELECT embedding FROM t`;
+
+    expect(rows).toHaveLength(1);
+    // The postgres driver returns vector columns as strings like '[1,2,3]'.
+    // Normalise by parsing the string representation.
+    const raw = rows[0]?.['embedding'] as string;
+    const parsed = JSON.parse(raw) as number[];
+    expect(parsed).toEqual([1, 2, 3]);
+  }, 10_000);
+});

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

@@ -1,6 +1,6 @@
 import { Controller, Get, Inject, UseGuards } from '@nestjs/common';
-import { sql, type Db } from '@mosaic/db';
+import { sql, type Db } from '@mosaicstack/db';
-import { createQueue } from '@mosaic/queue';
+import { createQueue } from '@mosaicstack/queue';
 import { DB } from '../database/database.module.js';
 import { AgentService } from '../agent/agent.service.js';
 import { ProviderService } from '../agent/provider.service.js';

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

@@ -0,0 +1,90 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpCode,
+  HttpStatus,
+  Inject,
+  Param,
+  Post,
+  UseGuards,
+} from '@nestjs/common';
+import { randomBytes, createHash } from 'node:crypto';
+import { eq, type Db, adminTokens } from '@mosaicstack/db';
+import { v4 as uuid } from 'uuid';
+import { DB } from '../database/database.module.js';
+import { AdminGuard } from './admin.guard.js';
+import { CurrentUser } from '../auth/current-user.decorator.js';
+import type {
+  CreateTokenDto,
+  TokenCreatedDto,
+  TokenDto,
+  TokenListDto,
+} from './admin-tokens.dto.js';
+
+function hashToken(plaintext: string): string {
+  return createHash('sha256').update(plaintext).digest('hex');
+}
+
+function toTokenDto(row: typeof adminTokens.$inferSelect): TokenDto {
+  return {
+    id: row.id,
+    label: row.label,
+    scope: row.scope,
+    expiresAt: row.expiresAt?.toISOString() ?? null,
+    lastUsedAt: row.lastUsedAt?.toISOString() ?? null,
+    createdAt: row.createdAt.toISOString(),
+  };
+}
+
+@Controller('api/admin/tokens')
+@UseGuards(AdminGuard)
+export class AdminTokensController {
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  @Post()
+  async create(
+    @Body() dto: CreateTokenDto,
+    @CurrentUser() user: { id: string },
+  ): Promise<TokenCreatedDto> {
+    const plaintext = randomBytes(32).toString('hex');
+    const tokenHash = hashToken(plaintext);
+    const id = uuid();
+
+    const expiresAt = dto.expiresInDays
+      ? new Date(Date.now() + dto.expiresInDays * 24 * 60 * 60 * 1000)
+      : null;
+
+    const [row] = await this.db
+      .insert(adminTokens)
+      .values({
+        id,
+        userId: user.id,
+        tokenHash,
+        label: dto.label ?? 'CLI token',
+        scope: dto.scope ?? 'admin',
+        expiresAt,
+      })
+      .returning();
+
+    return { ...toTokenDto(row!), plaintext };
+  }
+
+  @Get()
+  async list(@CurrentUser() user: { id: string }): Promise<TokenListDto> {
+    const rows = await this.db
+      .select()
+      .from(adminTokens)
+      .where(eq(adminTokens.userId, user.id))
+      .orderBy(adminTokens.createdAt);
+
+    return { tokens: rows.map(toTokenDto), total: rows.length };
+  }
+
+  @Delete(':id')
+  @HttpCode(HttpStatus.NO_CONTENT)
+  async revoke(@Param('id') id: string, @CurrentUser() _user: { id: string }): Promise<void> {
+    await this.db.delete(adminTokens).where(eq(adminTokens.id, id));
+  }
+}

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

@@ -0,0 +1,33 @@
+import { IsString, IsOptional, IsInt, Min } from 'class-validator';
+
+export class CreateTokenDto {
+  @IsString()
+  label!: string;
+
+  @IsOptional()
+  @IsString()
+  scope?: string;
+
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  expiresInDays?: number;
+}
+
+export interface TokenDto {
+  id: string;
+  label: string;
+  scope: string;
+  expiresAt: string | null;
+  lastUsedAt: string | null;
+  createdAt: string;
+}
+
+export interface TokenCreatedDto extends TokenDto {
+  plaintext: string;
+}
+
+export interface TokenListDto {
+  tokens: TokenDto[];
+  total: number;
+}

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

@@ -13,8 +13,8 @@ import {
   Post,
   UseGuards,
 } from '@nestjs/common';
-import { eq, type Db, users as usersTable } from '@mosaic/db';
+import { eq, type Db, users as usersTable } from '@mosaicstack/db';
-import type { Auth } from '@mosaic/auth';
+import type { Auth } from '@mosaicstack/auth';
 import { AUTH } from '../auth/auth.tokens.js';
 import { DB } from '../database/database.module.js';
 import { AdminGuard } from './admin.guard.js';

apps/gateway/src/admin/admin.guard.ts

@@ -6,10 +6,11 @@ import {
   Injectable,
   UnauthorizedException,
 } from '@nestjs/common';
+import { createHash } from 'node:crypto';
 import { fromNodeHeaders } from 'better-auth/node';
-import type { Auth } from '@mosaic/auth';
+import type { Auth } from '@mosaicstack/auth';
-import type { Db } from '@mosaic/db';
+import type { Db } from '@mosaicstack/db';
-import { eq, users as usersTable } from '@mosaic/db';
+import { eq, adminTokens, users as usersTable } from '@mosaicstack/db';
 import type { FastifyRequest } from 'fastify';
 import { AUTH } from '../auth/auth.tokens.js';
 import { DB } from '../database/database.module.js';
@@ -19,6 +20,8 @@ interface UserWithRole {
   role?: string;
 }
 
+type AuthenticatedRequest = FastifyRequest & { user: unknown; session: unknown };
+
 @Injectable()
 export class AdminGuard implements CanActivate {
   constructor(
@@ -28,8 +31,64 @@ export class AdminGuard implements CanActivate {
 
   async canActivate(context: ExecutionContext): Promise<boolean> {
     const request = context.switchToHttp().getRequest<FastifyRequest>();
-    const headers = fromNodeHeaders(request.raw.headers);
 
+    // Try bearer token auth first
+    const authHeader = request.raw.headers['authorization'];
+    if (authHeader?.startsWith('Bearer ')) {
+      return this.validateBearerToken(request, authHeader.slice(7));
+    }
+
+    // Fall back to BetterAuth session
+    return this.validateSession(request);
+  }
+
+  private async validateBearerToken(request: FastifyRequest, plaintext: string): Promise<boolean> {
+    const tokenHash = createHash('sha256').update(plaintext).digest('hex');
+
+    const [row] = await this.db
+      .select({
+        tokenId: adminTokens.id,
+        userId: adminTokens.userId,
+        scope: adminTokens.scope,
+        expiresAt: adminTokens.expiresAt,
+        userName: usersTable.name,
+        userEmail: usersTable.email,
+        userRole: usersTable.role,
+      })
+      .from(adminTokens)
+      .innerJoin(usersTable, eq(adminTokens.userId, usersTable.id))
+      .where(eq(adminTokens.tokenHash, tokenHash))
+      .limit(1);
+
+    if (!row) {
+      throw new UnauthorizedException('Invalid API token');
+    }
+
+    if (row.expiresAt && row.expiresAt < new Date()) {
+      throw new UnauthorizedException('API token expired');
+    }
+
+    if (row.userRole !== 'admin') {
+      throw new ForbiddenException('Admin access required');
+    }
+
+    // Update last-used timestamp (fire-and-forget)
+    this.db
+      .update(adminTokens)
+      .set({ lastUsedAt: new Date() })
+      .where(eq(adminTokens.id, row.tokenId))
+      .then(() => {})
+      .catch(() => {});
+
+    const req = request as AuthenticatedRequest;
+    req.user = { id: row.userId, name: row.userName, email: row.userEmail, role: row.userRole };
+    req.session = { id: `token:${row.tokenId}`, userId: row.userId };
+
+    return true;
+  }
+
+  private async validateSession(request: FastifyRequest): Promise<boolean> {
+    const headers = fromNodeHeaders(request.raw.headers);
     const result = await this.auth.api.getSession({ headers });
 
     if (!result) {
@@ -38,8 +97,6 @@ export class AdminGuard implements CanActivate {
 
     const user = result.user as UserWithRole;
 
-    // Ensure the role field is populated. better-auth should include additionalFields
-    // in the session, but as a fallback, fetch the role from the database if needed.
     let userRole = user.role;
     if (!userRole) {
       const [dbUser] = await this.db
@@ -48,7 +105,6 @@ export class AdminGuard implements CanActivate {
         .where(eq(usersTable.id, user.id))
         .limit(1);
       userRole = dbUser?.role ?? 'member';
-      // Update the session user object with the fetched role
       (user as UserWithRole).role = userRole;
     }
 
@@ -56,8 +112,9 @@ export class AdminGuard implements CanActivate {
       throw new ForbiddenException('Admin access required');
     }
 
-    (request as FastifyRequest & { user: unknown; session: unknown }).user = result.user;
+    const req = request as AuthenticatedRequest;
-    (request as FastifyRequest & { user: unknown; session: unknown }).session = result.session;
+    req.user = result.user;
+    req.session = result.session;
 
     return true;
   }

apps/gateway/src/admin/admin.module.ts

@@ -2,10 +2,18 @@ import { Module } from '@nestjs/common';
 import { AdminController } from './admin.controller.js';
 import { AdminHealthController } from './admin-health.controller.js';
 import { AdminJobsController } from './admin-jobs.controller.js';
+import { AdminTokensController } from './admin-tokens.controller.js';
+import { BootstrapController } from './bootstrap.controller.js';
 import { AdminGuard } from './admin.guard.js';
 
 @Module({
-  controllers: [AdminController, AdminHealthController, AdminJobsController],
+  controllers: [
+    AdminController,
+    AdminHealthController,
+    AdminJobsController,
+    AdminTokensController,
+    BootstrapController,
+  ],
   providers: [AdminGuard],
 })
 export class AdminModule {}

apps/gateway/src/admin/bootstrap.controller.ts

@@ -0,0 +1,102 @@
+import {
+  Body,
+  Controller,
+  ForbiddenException,
+  Get,
+  Inject,
+  InternalServerErrorException,
+  Post,
+} from '@nestjs/common';
+import { randomBytes, createHash } from 'node:crypto';
+import { count, eq, type Db, users as usersTable, adminTokens } from '@mosaicstack/db';
+import type { Auth } from '@mosaicstack/auth';
+import { v4 as uuid } from 'uuid';
+import { AUTH } from '../auth/auth.tokens.js';
+import { DB } from '../database/database.module.js';
+import { BootstrapSetupDto } from './bootstrap.dto.js';
+import type { BootstrapStatusDto, BootstrapResultDto } from './bootstrap.dto.js';
+
+@Controller('api/bootstrap')
+export class BootstrapController {
+  constructor(
+    @Inject(AUTH) private readonly auth: Auth,
+    @Inject(DB) private readonly db: Db,
+  ) {}
+
+  @Get('status')
+  async status(): Promise<BootstrapStatusDto> {
+    const [result] = await this.db.select({ total: count() }).from(usersTable);
+    return { needsSetup: (result?.total ?? 0) === 0 };
+  }
+
+  @Post('setup')
+  async setup(@Body() dto: BootstrapSetupDto): Promise<BootstrapResultDto> {
+    // Only allow setup when zero users exist
+    const [result] = await this.db.select({ total: count() }).from(usersTable);
+    if ((result?.total ?? 0) > 0) {
+      throw new ForbiddenException('Setup already completed — users exist');
+    }
+
+    // Create admin user via BetterAuth API
+    const authApi = this.auth.api as unknown as {
+      createUser: (opts: {
+        body: { name: string; email: string; password: string; role?: string };
+      }) => Promise<{
+        user: { id: string; name: string; email: string };
+      }>;
+    };
+
+    const created = await authApi.createUser({
+      body: {
+        name: dto.name,
+        email: dto.email,
+        password: dto.password,
+        role: 'admin',
+      },
+    });
+
+    // Verify user was created
+    const [user] = await this.db
+      .select()
+      .from(usersTable)
+      .where(eq(usersTable.id, created.user.id))
+      .limit(1);
+
+    if (!user) throw new InternalServerErrorException('User created but not found');
+
+    // Ensure role is admin (createUser may not set it via BetterAuth)
+    if (user.role !== 'admin') {
+      await this.db.update(usersTable).set({ role: 'admin' }).where(eq(usersTable.id, user.id));
+    }
+
+    // Generate admin API token
+    const plaintext = randomBytes(32).toString('hex');
+    const tokenHash = createHash('sha256').update(plaintext).digest('hex');
+    const tokenId = uuid();
+
+    const [token] = await this.db
+      .insert(adminTokens)
+      .values({
+        id: tokenId,
+        userId: user.id,
+        tokenHash,
+        label: 'Initial setup token',
+        scope: 'admin',
+      })
+      .returning();
+
+    return {
+      user: {
+        id: user.id,
+        name: user.name,
+        email: user.email,
+        role: 'admin',
+      },
+      token: {
+        id: token!.id,
+        plaintext,
+        label: token!.label,
+      },
+    };
+  }
+}

apps/gateway/src/admin/bootstrap.dto.ts

@@ -0,0 +1,31 @@
+import { IsString, IsEmail, MinLength } from 'class-validator';
+
+export class BootstrapSetupDto {
+  @IsString()
+  name!: string;
+
+  @IsEmail()
+  email!: string;
+
+  @IsString()
+  @MinLength(8)
+  password!: string;
+}
+
+export interface BootstrapStatusDto {
+  needsSetup: boolean;
+}
+
+export interface BootstrapResultDto {
+  user: {
+    id: string;
+    name: string;
+    email: string;
+    role: string;
+  };
+  token: {
+    id: string;
+    plaintext: string;
+    label: string;
+  };
+}

apps/gateway/src/admin/bootstrap.e2e.spec.ts

@@ -0,0 +1,190 @@
+/**
+ * E2E integration test — POST /api/bootstrap/setup
+ *
+ * Regression guard for the `import type { BootstrapSetupDto }` class-erasure
+ * bug (IUV-M01, issue #436).
+ *
+ * When `BootstrapSetupDto` is imported with `import type`, TypeScript erases
+ * the class at compile time. NestJS then sees `Object` as the `@Body()`
+ * metatype, and ValidationPipe with `whitelist:true + forbidNonWhitelisted:true`
+ * treats every property as non-whitelisted, returning:
+ *
+ *   400 { message: ["property email should not exist", "property password should not exist"] }
+ *
+ * The fix is a plain value import (`import { BootstrapSetupDto }`), which
+ * preserves the class reference so Nest can read the class-validator decorators.
+ *
+ * This test MUST fail if `import type` is re-introduced on `BootstrapSetupDto`.
+ * A controller unit test that constructs ValidationPipe manually won't catch
+ * this — only the real DI binding path exercises the metatype lookup.
+ */
+
+import 'reflect-metadata';
+import { describe, it, expect, afterAll, beforeAll } from 'vitest';
+import { Test } from '@nestjs/testing';
+import { ValidationPipe, type INestApplication } from '@nestjs/common';
+import { FastifyAdapter, type NestFastifyApplication } from '@nestjs/platform-fastify';
+import request from 'supertest';
+import { BootstrapController } from './bootstrap.controller.js';
+import type { BootstrapResultDto } from './bootstrap.dto.js';
+
+// ─── Minimal mock dependencies ───────────────────────────────────────────────
+
+/**
+ * We use explicit `@Inject(AUTH)` / `@Inject(DB)` in the controller so we
+ * can provide mock values by token without spinning up the real DB or Auth.
+ */
+import { AUTH } from '../auth/auth.tokens.js';
+import { DB } from '../database/database.module.js';
+
+const MOCK_USER_ID = 'mock-user-id-001';
+
+const mockAuth = {
+  api: {
+    createUser: () =>
+      Promise.resolve({
+        user: {
+          id: MOCK_USER_ID,
+          name: 'Admin',
+          email: 'admin@example.com',
+        },
+      }),
+  },
+};
+
+// Override db.select() so the second query (verify user exists) returns a user.
+// The bootstrap controller calls select().from() twice:
+//   1. count() to check zero users  → returns [{total: 0}]
+//   2. select().where().limit()     → returns [the created user]
+let selectCallCount = 0;
+const mockDbWithUser = {
+  select: () => {
+    selectCallCount++;
+    return {
+      from: () => {
+        if (selectCallCount === 1) {
+          // First call: count — zero users
+          return Promise.resolve([{ total: 0 }]);
+        }
+        // Subsequent calls: return a mock user row
+        return {
+          where: () => ({
+            limit: () =>
+              Promise.resolve([
+                {
+                  id: MOCK_USER_ID,
+                  name: 'Admin',
+                  email: 'admin@example.com',
+                  role: 'admin',
+                },
+              ]),
+          }),
+        };
+      },
+    };
+  },
+  update: () => ({
+    set: () => ({
+      where: () => Promise.resolve([]),
+    }),
+  }),
+  insert: () => ({
+    values: () => ({
+      returning: () =>
+        Promise.resolve([
+          {
+            id: 'token-id-001',
+            label: 'Initial setup token',
+          },
+        ]),
+    }),
+  }),
+};
+
+// ─── Test suite ───────────────────────────────────────────────────────────────
+
+describe('POST /api/bootstrap/setup — ValidationPipe DTO binding', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    selectCallCount = 0;
+
+    const moduleRef = await Test.createTestingModule({
+      controllers: [BootstrapController],
+      providers: [
+        { provide: AUTH, useValue: mockAuth },
+        { provide: DB, useValue: mockDbWithUser },
+      ],
+    }).compile();
+
+    app = moduleRef.createNestApplication<NestFastifyApplication>(new FastifyAdapter());
+
+    // Mirror main.ts configuration exactly — this is what reproduced the 400.
+    app.useGlobalPipes(
+      new ValidationPipe({
+        whitelist: true,
+        forbidNonWhitelisted: true,
+        transform: true,
+      }),
+    );
+
+    await app.init();
+    // Fastify requires waiting for the adapter to be ready
+    await app.getHttpAdapter().getInstance().ready();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('returns 201 (not 400) when a valid {name, email, password} body is sent', async () => {
+    const res = await request(app.getHttpServer())
+      .post('/api/bootstrap/setup')
+      .send({ name: 'Admin', email: 'admin@example.com', password: 'password123' })
+      .set('Content-Type', 'application/json');
+
+    // Before the fix (import type), Nest ValidationPipe returned 400 with
+    // "property email should not exist" / "property password should not exist"
+    // because the DTO class was erased and every field looked non-whitelisted.
+    expect(res.status).not.toBe(400);
+    expect(res.status).toBe(201);
+    const body = res.body as BootstrapResultDto;
+    expect(body.user).toBeDefined();
+    expect(body.user.email).toBe('admin@example.com');
+    expect(body.token).toBeDefined();
+    expect(body.token.plaintext).toBeDefined();
+  });
+
+  it('returns 400 when extra forbidden properties are sent', async () => {
+    // This proves ValidationPipe IS active and working (forbidNonWhitelisted).
+    const res = await request(app.getHttpServer())
+      .post('/api/bootstrap/setup')
+      .send({
+        name: 'Admin',
+        email: 'admin@example.com',
+        password: 'password123',
+        extraField: 'should-be-rejected',
+      })
+      .set('Content-Type', 'application/json');
+
+    expect(res.status).toBe(400);
+  });
+
+  it('returns 400 when email is invalid', async () => {
+    const res = await request(app.getHttpServer())
+      .post('/api/bootstrap/setup')
+      .send({ name: 'Admin', email: 'not-an-email', password: 'password123' })
+      .set('Content-Type', 'application/json');
+
+    expect(res.status).toBe(400);
+  });
+
+  it('returns 400 when password is too short', async () => {
+    const res = await request(app.getHttpServer())
+      .post('/api/bootstrap/setup')
+      .send({ name: 'Admin', email: 'admin@example.com', password: 'short' })
+      .set('Content-Type', 'application/json');
+
+    expect(res.status).toBe(400);
+  });
+});

apps/gateway/src/agent/__tests__/provider-adapters.test.ts

@@ -62,7 +62,7 @@ function restoreEnv(saved: Map<EnvKey, string | undefined>): void {
 }
 
 function makeRegistry(): ModelRegistry {
-  return new ModelRegistry(AuthStorage.inMemory());
+  return ModelRegistry.inMemory(AuthStorage.inMemory());
 }
 
 // ---------------------------------------------------------------------------

apps/gateway/src/agent/__tests__/routing.service.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { RoutingService } from '../routing.service.js';
-import type { ModelInfo } from '@mosaic/types';
+import type { ModelInfo } from '@mosaicstack/types';
 
 const mockModels: ModelInfo[] = [
   {

apps/gateway/src/agent/adapters/anthropic.adapter.ts

@@ -7,7 +7,7 @@ import type {
   IProviderAdapter,
   ModelInfo,
   ProviderHealth,
-} from '@mosaic/types';
+} from '@mosaicstack/types';
 
 /**
  * Anthropic provider adapter.

apps/gateway/src/agent/adapters/ollama.adapter.ts

@@ -6,7 +6,7 @@ import type {
   IProviderAdapter,
   ModelInfo,
   ProviderHealth,
-} from '@mosaic/types';
+} from '@mosaicstack/types';
 
 /** Embedding models that Ollama ships with out of the box */
 const OLLAMA_EMBEDDING_MODELS: ReadonlyArray<{

apps/gateway/src/agent/adapters/openai.adapter.ts

@@ -7,7 +7,7 @@ import type {
   IProviderAdapter,
   ModelInfo,
   ProviderHealth,
-} from '@mosaic/types';
+} from '@mosaicstack/types';
 
 /**
  * OpenAI provider adapter.

apps/gateway/src/agent/adapters/openrouter.adapter.ts

@@ -6,7 +6,7 @@ import type {
   IProviderAdapter,
   ModelInfo,
   ProviderHealth,
-} from '@mosaic/types';
+} from '@mosaicstack/types';
 
 const OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1';
 

apps/gateway/src/agent/adapters/zai.adapter.ts

@@ -6,7 +6,7 @@ import type {
   IProviderAdapter,
   ModelInfo,
   ProviderHealth,
-} from '@mosaic/types';
+} from '@mosaicstack/types';
 import { getModelCapability } from '../model-capabilities.js';
 
 /**

apps/gateway/src/agent/agent-configs.controller.ts

@@ -13,7 +13,7 @@ import {
   Post,
   UseGuards,
 } from '@nestjs/common';
-import type { Brain } from '@mosaic/brain';
+import type { Brain } from '@mosaicstack/brain';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';

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

@@ -7,8 +7,8 @@ import {
   type AgentSessionEvent,
   type ToolDefinition,
 } from '@mariozechner/pi-coding-agent';
-import type { Brain } from '@mosaic/brain';
+import type { Brain } from '@mosaicstack/brain';
-import type { Memory } from '@mosaic/memory';
+import type { Memory } from '@mosaicstack/memory';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { MEMORY } from '../memory/memory.tokens.js';
 import { EmbeddingService } from '../memory/embedding.service.js';

apps/gateway/src/agent/model-capabilities.ts

@@ -1,4 +1,4 @@
-import type { ModelCapability } from '@mosaic/types';
+import type { ModelCapability } from '@mosaicstack/types';
 
 /**
  * Comprehensive capability matrix for all target models.

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 '@mosaic/db';
+import type { Db } from '@mosaicstack/db';
-import { providerCredentials, eq, and } from '@mosaic/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/provider.service.ts

@@ -14,7 +14,7 @@ import type {
   ModelInfo,
   ProviderHealth,
   ProviderInfo,
-} from '@mosaic/types';
+} from '@mosaicstack/types';
 import {
   AnthropicAdapter,
   OllamaAdapter,
@@ -67,7 +67,7 @@ export class ProviderService implements OnModuleInit, OnModuleDestroy {
 
   async onModuleInit(): Promise<void> {
     const authStorage = AuthStorage.inMemory();
-    this.registry = new ModelRegistry(authStorage);
+    this.registry = ModelRegistry.inMemory(authStorage);
 
     // Build the default set of adapters that rely on the registry
     this.adapters = [

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

@@ -1,5 +1,5 @@
 import { Body, Controller, Delete, Get, Inject, Param, Post, UseGuards } from '@nestjs/common';
-import type { RoutingCriteria } from '@mosaic/types';
+import type { RoutingCriteria } from '@mosaicstack/types';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';
 import { ProviderService } from './provider.service.js';

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

@@ -1,6 +1,6 @@
 import { Inject, Injectable, Logger } from '@nestjs/common';
-import type { ModelInfo } from '@mosaic/types';
+import type { ModelInfo } from '@mosaicstack/types';
-import type { RoutingCriteria, RoutingResult, CostTier } from '@mosaic/types';
+import type { RoutingCriteria, RoutingResult, CostTier } from '@mosaicstack/types';
 import { ProviderService } from './provider.service.js';
 
 /** Per-million-token cost thresholds for tier classification */

apps/gateway/src/agent/routing/default-rules.ts

@@ -1,5 +1,5 @@
 import { Inject, Injectable, Logger, type OnModuleInit } from '@nestjs/common';
-import { routingRules, type Db, sql } from '@mosaic/db';
+import { routingRules, type Db, sql } from '@mosaicstack/db';
 import { DB } from '../../database/database.module.js';
 import type { RoutingCondition, RoutingAction } from './routing.types.js';
 

apps/gateway/src/agent/routing/routing-engine.service.ts

@@ -1,5 +1,5 @@
 import { Inject, Injectable, Logger } from '@nestjs/common';
-import { routingRules, type Db, and, asc, eq, or } from '@mosaic/db';
+import { routingRules, type Db, and, asc, eq, or } from '@mosaicstack/db';
 import { DB } from '../../database/database.module.js';
 import { ProviderService } from '../provider.service.js';
 import { classifyTask } from './task-classifier.js';

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

@@ -13,7 +13,7 @@ import {
   Post,
   UseGuards,
 } from '@nestjs/common';
-import { routingRules, type Db, and, asc, eq, or, inArray } from '@mosaic/db';
+import { routingRules, type Db, and, asc, eq, or, inArray } from '@mosaicstack/db';
 import { DB } from '../../database/database.module.js';
 import { AuthGuard } from '../../auth/auth.guard.js';
 import { CurrentUser } from '../../auth/current-user.decorator.js';

apps/gateway/src/agent/routing/routing.types.ts

@@ -1,7 +1,7 @@
 /**
  * Routing engine types — M4-002 (condition types) and M4-003 (action types).
  *
- * These types are re-exported from `@mosaic/types` for shared use across packages.
+ * These types are re-exported from `@mosaicstack/types` for shared use across packages.
  */
 
 // ─── Classification primitives ───────────────────────────────────────────────
@@ -23,7 +23,7 @@ export type Domain = 'frontend' | 'backend' | 'devops' | 'docs' | 'general';
 
 /**
  * Cost tier for model selection.
- * Extends the existing `CostTier` in `@mosaic/types` with `local` for self-hosted models.
+ * Extends the existing `CostTier` in `@mosaicstack/types` with `local` for self-hosted models.
  */
 export type CostTier = 'cheap' | 'standard' | 'premium' | 'local';
 

apps/gateway/src/agent/tools/brain-tools.ts

@@ -1,6 +1,6 @@
 import { Type } from '@sinclair/typebox';
 import type { ToolDefinition } from '@mariozechner/pi-coding-agent';
-import type { Brain } from '@mosaic/brain';
+import type { Brain } from '@mosaicstack/brain';
 
 export function createBrainTools(brain: Brain): ToolDefinition[] {
   const listProjects: ToolDefinition = {

apps/gateway/src/agent/tools/memory-tools.ts

@@ -1,7 +1,7 @@
 import { Type } from '@sinclair/typebox';
 import type { ToolDefinition } from '@mariozechner/pi-coding-agent';
-import type { Memory } from '@mosaic/memory';
+import type { Memory } from '@mosaicstack/memory';
-import type { EmbeddingProvider } from '@mosaic/memory';
+import type { EmbeddingProvider } from '@mosaicstack/memory';
 
 /**
  * Create memory tools bound to the session's authenticated userId.

apps/gateway/src/app.module.ts

@@ -1,6 +1,7 @@
 import { Module } from '@nestjs/common';
 import { APP_GUARD } from '@nestjs/core';
 import { HealthController } from './health/health.controller.js';
+import { ConfigModule } from './config/config.module.js';
 import { DatabaseModule } from './database/database.module.js';
 import { AuthModule } from './auth/auth.module.js';
 import { BrainModule } from './brain/brain.module.js';
@@ -23,11 +24,13 @@ 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({
   imports: [
     ThrottlerModule.forRoot([{ name: 'default', ttl: 60_000, limit: 60 }]),
+    ConfigModule,
     DatabaseModule,
     AuthModule,
     BrainModule,
@@ -50,6 +53,7 @@ import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler';
     QueueModule,
     ReloadModule,
     WorkspaceModule,
+    FederationModule,
   ],
   controllers: [HealthController],
   providers: [

apps/gateway/src/auth/auth.controller.ts

@@ -1,6 +1,6 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { toNodeHandler } from 'better-auth/node';
-import type { Auth } from '@mosaic/auth';
+import type { Auth } from '@mosaicstack/auth';
 import type { NestFastifyApplication } from '@nestjs/platform-fastify';
 import { AUTH } from './auth.tokens.js';
 

apps/gateway/src/auth/auth.guard.ts

@@ -6,7 +6,7 @@ import {
   UnauthorizedException,
 } from '@nestjs/common';
 import { fromNodeHeaders } from 'better-auth/node';
-import type { Auth } from '@mosaic/auth';
+import type { Auth } from '@mosaicstack/auth';
 import type { FastifyRequest } from 'fastify';
 import { AUTH } from './auth.tokens.js';
 

apps/gateway/src/auth/auth.module.ts

@@ -1,6 +1,6 @@
 import { Global, Module } from '@nestjs/common';
-import { createAuth, type Auth } from '@mosaic/auth';
+import { createAuth, type Auth } from '@mosaicstack/auth';
-import type { Db } from '@mosaic/db';
+import type { Db } from '@mosaicstack/db';
 import { DB } from '../database/database.module.js';
 import { AUTH } from './auth.tokens.js';
 import { SsoController } from './sso.controller.js';
@@ -14,7 +14,7 @@ import { SsoController } from './sso.controller.js';
       useFactory: (db: Db): Auth =>
         createAuth({
           db,
-          baseURL: process.env['BETTER_AUTH_URL'] ?? 'http://localhost:4000',
+          baseURL: process.env['BETTER_AUTH_URL'] ?? 'http://localhost:14242',
           secret: process.env['BETTER_AUTH_SECRET'],
         }),
       inject: [DB],

apps/gateway/src/auth/sso.controller.ts

@@ -1,5 +1,5 @@
 import { Controller, Get } from '@nestjs/common';
-import { buildSsoDiscovery, type SsoProviderDiscovery } from '@mosaic/auth';
+import { buildSsoDiscovery, type SsoProviderDiscovery } from '@mosaicstack/auth';
 
 @Controller('api/sso/providers')
 export class SsoController {

apps/gateway/src/brain/brain.module.ts

@@ -1,6 +1,6 @@
 import { Global, Module } from '@nestjs/common';
-import { createBrain, type Brain } from '@mosaic/brain';
+import { createBrain, type Brain } from '@mosaicstack/brain';
-import type { Db } from '@mosaic/db';
+import type { Db } from '@mosaicstack/db';
 import { DB } from '../database/database.module.js';
 import { BRAIN } from './brain.tokens.js';
 

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

@@ -11,15 +11,15 @@ import {
 } from '@nestjs/websockets';
 import { Server, Socket } from 'socket.io';
 import type { AgentSessionEvent } from '@mariozechner/pi-coding-agent';
-import type { Auth } from '@mosaic/auth';
+import type { Auth } from '@mosaicstack/auth';
-import type { Brain } from '@mosaic/brain';
+import type { Brain } from '@mosaicstack/brain';
 import type {
   SetThinkingPayload,
   SlashCommandPayload,
   SystemReloadPayload,
   RoutingDecisionInfo,
   AbortPayload,
-} from '@mosaic/types';
+} from '@mosaicstack/types';
 import { AgentService, type ConversationHistoryMessage } from '../agent/agent.service.js';
 import { AUTH } from '../auth/auth.tokens.js';
 import { BRAIN } from '../brain/brain.tokens.js';

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

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { CommandExecutorService } from './command-executor.service.js';
-import type { SlashCommandPayload } from '@mosaic/types';
+import type { SlashCommandPayload } from '@mosaicstack/types';
 
 // Minimal mock implementations
 const mockRegistry = {

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

@@ -1,7 +1,7 @@
 import { forwardRef, Inject, Injectable, Logger, Optional } from '@nestjs/common';
-import type { QueueHandle } from '@mosaic/queue';
+import type { QueueHandle } from '@mosaicstack/queue';
-import type { Brain } from '@mosaic/brain';
+import type { Brain } from '@mosaicstack/brain';
-import type { SlashCommandPayload, SlashCommandResultPayload } from '@mosaic/types';
+import type { SlashCommandPayload, SlashCommandResultPayload } from '@mosaicstack/types';
 import { AgentService } from '../agent/agent.service.js';
 import { ChatGateway } from '../chat/chat.gateway.js';
 import { SessionGCService } from '../gc/session-gc.service.js';

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

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { CommandRegistryService } from './command-registry.service.js';
-import type { CommandDef } from '@mosaic/types';
+import type { CommandDef } from '@mosaicstack/types';
 
 const mockCmd: CommandDef = {
   name: 'test',

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

@@ -1,5 +1,5 @@
 import { Injectable, type OnModuleInit } from '@nestjs/common';
-import type { CommandDef, CommandManifest } from '@mosaic/types';
+import type { CommandDef, CommandManifest } from '@mosaicstack/types';
 
 @Injectable()
 export class CommandRegistryService implements OnModuleInit {

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

@@ -13,7 +13,7 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { CommandRegistryService } from './command-registry.service.js';
 import { CommandExecutorService } from './command-executor.service.js';
-import type { SlashCommandPayload } from '@mosaic/types';
+import type { SlashCommandPayload } from '@mosaicstack/types';
 
 // ─── Mocks ───────────────────────────────────────────────────────────────────
 

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

@@ -1,5 +1,5 @@
 import { forwardRef, Inject, Module, type OnApplicationShutdown } from '@nestjs/common';
-import { createQueue, type QueueHandle } from '@mosaic/queue';
+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';

apps/gateway/src/config/config.module.ts

@@ -0,0 +1,16 @@
+import { Global, Module } from '@nestjs/common';
+import { loadConfig, type MosaicConfig } from '@mosaicstack/config';
+
+export const MOSAIC_CONFIG = 'MOSAIC_CONFIG';
+
+@Global()
+@Module({
+  providers: [
+    {
+      provide: MOSAIC_CONFIG,
+      useFactory: (): MosaicConfig => loadConfig(),
+    },
+  ],
+  exports: [MOSAIC_CONFIG],
+})
+export class ConfigModule {}

apps/gateway/src/conversations/conversations.controller.ts

@@ -15,7 +15,7 @@ import {
   Query,
   UseGuards,
 } from '@nestjs/common';
-import type { Brain } from '@mosaic/brain';
+import type { Brain } from '@mosaicstack/brain';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';

apps/gateway/src/coord/coord.service.ts

@@ -8,7 +8,7 @@ import {
   type MissionStatusSummary,
   type MissionTask,
   type TaskDetail,
-} from '@mosaic/coord';
+} from '@mosaicstack/coord';
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 

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

@@ -1,28 +1,89 @@
-import { Global, Inject, Module, type OnApplicationShutdown } from '@nestjs/common';
+import { mkdirSync } from 'node:fs';
-import { createDb, type Db, type DbHandle } from '@mosaic/db';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+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';
 
 export const DB_HANDLE = 'DB_HANDLE';
 export const DB = 'DB';
+export const STORAGE_ADAPTER = 'STORAGE_ADAPTER';
 
 @Global()
 @Module({
   providers: [
     {
       provide: DB_HANDLE,
-      useFactory: (): DbHandle => createDb(),
+      useFactory: (config: MosaicConfig): DbHandle => {
+        if (config.tier === 'local') {
+          const dataDir = join(homedir(), '.config', 'mosaic', 'gateway', 'pglite');
+          mkdirSync(dataDir, { recursive: true });
+          return createPgliteDb(dataDir);
+        }
+        return createDb(config.storage.type === 'postgres' ? config.storage.url : undefined);
+      },
+      inject: [MOSAIC_CONFIG],
     },
     {
       provide: DB,
       useFactory: (handle: DbHandle): Db => handle.db,
       inject: [DB_HANDLE],
     },
+    {
+      provide: STORAGE_ADAPTER,
+      useFactory: (config: MosaicConfig): StorageAdapter => createStorageAdapter(config.storage),
+      inject: [MOSAIC_CONFIG],
+    },
   ],
-  exports: [DB],
+  exports: [DB, STORAGE_ADAPTER],
 })
-export class DatabaseModule implements OnApplicationShutdown {
+export class DatabaseModule implements OnApplicationShutdown, OnModuleInit {
-  constructor(@Inject(DB_HANDLE) private readonly handle: DbHandle) {}
+  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 this.handle.close();
+    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/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,13 @@
+/**
+ * Federation client barrel — re-exports for FederationModule consumers.
+ *
+ * M3-09 (QuerySourceService) and future milestones should import from here,
+ * not directly from the implementation file.
+ */
+
+export {
+  FederationClientService,
+  FederationClientError,
+  type FederationClientErrorCode,
+  type FederationClientErrorOptions,
+} from './federation-client.service.js';

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,29 @@
+import { Module } from '@nestjs/common';
+import { AdminGuard } from '../admin/admin.guard.js';
+import { CaService } from './ca.service.js';
+import { EnrollmentController } from './enrollment.controller.js';
+import { EnrollmentService } from './enrollment.service.js';
+import { FederationController } from './federation.controller.js';
+import { GrantsService } from './grants.service.js';
+import { FederationClientService } from './client/index.js';
+import { FederationAuthGuard } from './server/index.js';
+
+@Module({
+  controllers: [EnrollmentController, FederationController],
+  providers: [
+    AdminGuard,
+    CaService,
+    EnrollmentService,
+    GrantsService,
+    FederationClientService,
+    FederationAuthGuard,
+  ],
+  exports: [
+    CaService,
+    EnrollmentService,
+    GrantsService,
+    FederationClientService,
+    FederationAuthGuard,
+  ],
+})
+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/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,13 @@
+/**
+ * Federation server-side barrel — inbound request handling.
+ *
+ * Exports the mTLS auth guard and the FederationContext interface
+ * for use by verb controllers (M3-05/06/07).
+ *
+ * Usage:
+ *   import { FederationAuthGuard } from './server/index.js';
+ *   @UseGuards(FederationAuthGuard)
+ */
+
+export { FederationAuthGuard } from './federation-auth.guard.js';
+export type { FederationContext } from './federation-context.js';

apps/gateway/src/gc/gc.module.ts

@@ -1,5 +1,5 @@
 import { Module, type OnApplicationShutdown, Inject } from '@nestjs/common';
-import { createQueue, type QueueHandle } from '@mosaic/queue';
+import { createQueue, type QueueHandle } from '@mosaicstack/queue';
 import { SessionGCService } from './session-gc.service.js';
 import { REDIS } from './gc.tokens.js';
 

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

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { Logger } from '@nestjs/common';
-import type { QueueHandle } from '@mosaic/queue';
+import type { QueueHandle } from '@mosaicstack/queue';
-import type { LogService } from '@mosaic/log';
+import type { LogService } from '@mosaicstack/log';
 import { SessionGCService } from './session-gc.service.js';
 
 type MockRedis = {

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

@@ -1,6 +1,6 @@
 import { Inject, Injectable, Logger, type OnModuleInit } from '@nestjs/common';
-import type { QueueHandle } from '@mosaic/queue';
+import type { QueueHandle } from '@mosaicstack/queue';
-import type { LogService } from '@mosaic/log';
+import type { LogService } from '@mosaicstack/log';
 import { LOG_SERVICE } from '../log/log.tokens.js';
 import { REDIS } from './gc.tokens.js';