@collage-dam/mcp-server 0.1.0

package/docs/deployment-runbook.md

@@ -0,0 +1,446 @@
+# Collage MCP Server — Deployment Runbook
+
+Operational reference for Collage engineering. Covers environment
+configuration, transport options, state store provisioning, observability,
+secret rotation, health checks, and incident-response patterns.
+
+> Companion docs:
+> - [`README.md`](../README.md) — quickstart and surface overview
+> - [`docs/api-field-verification.md`](./api-field-verification.md) — API quirks reference (handoff deliverable)
+> - [`docs/verified-endpoints.md`](./verified-endpoints.md) — Phase-2.5 endpoint stub list (superseded by api-field-verification)
+> - [`docs/typesense-filter-schema.md`](./typesense-filter-schema.md) — search filter shape
+
+---
+
+## Environment configuration
+
+### Required env vars
+
+| Var | Purpose | Failure mode if missing |
+| --- | --- | --- |
+| `COLLAGE_API_KEY` | Bearer token for the Collage REST API. Also forwarded to the Nuxt search proxy as the auth credential. | Server refuses to start with a `Missing required environment variable` error. |
+| `COLLAGE_WORKSPACE_ID` | Numeric workspace ID (the value in app.collage.inc URLs). | Server refuses to start. |
+| `MCP_CONFIRMATION_SECRET` | HMAC secret for dry-run confirmation tokens. Must be high-entropy (32+ bytes). | Server refuses to start. |
+
+### Optional env vars
+
+| Var | Default | Purpose |
+| --- | --- | --- |
+| `COLLAGE_API_URL` | `https://damapi.collage.inc/api/v1/` | Base URL for the Laravel REST API. |
+| `COLLAGE_SEARCH_BASE` | `https://app.collage.inc` | Base URL for the Nuxt `/typesense/search` proxy. |
+| `COLLAGE_SEARCH_TIMEOUT_MS` | `15000` | Search request timeout. Per-request `AbortController`. |
+| `COLLAGE_MAX_RPS` | `10` | Token-bucket rate limit on the REST client. 429s are retried with backoff. |
+| `REDIS_URL` | _unset_ → in-memory state store | Connection string for the dry-run plan store. Required for streamable-HTTP transport in production. |
+| `LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error`. Logs go to stderr. |
+
+### What `COLLAGE_API_KEY` actually is
+
+The Collage REST API doesn't issue dedicated long-lived API keys today.
+The "key" is the JWT issued by `POST /api/v1/login` and stored in the
+Nuxt frontend after a normal user sign-in. In practice you extract it
+from a browser session.
+
+**Implications for production deployments:**
+
+- The token is bound to the signed-in user's session. It expires when
+  the user's session does (typical Nuxt-auth defaults).
+- For long-lived servers, use a **dedicated service-account user**
+  whose session is controlled by ops, not a real engineer.
+- Rotate the token on a schedule that matches the upstream session
+  lifetime — see "Secret rotation" below.
+
+This is a known limitation. Collage's roadmap includes a proper API-key
+system; track that separately. Until then, the JWT-extracted-from-UI
+flow is the only option.
+
+---
+
+## Transport options
+
+The server supports two MCP transports. Pick based on deployment shape.
+
+### stdio (recommended for single-user clients)
+
+The default. Each MCP client (Claude Desktop, Cursor, etc.) spawns a
+dedicated `node dist/index.js` subprocess and talks over stdin/stdout.
+State is per-process and in-memory.
+
+**Pros:**
+- Zero infrastructure beyond Node.
+- Per-user isolation — every client gets a fresh process.
+- Logs go to stderr; the parent client surfaces them.
+
+**Cons:**
+- One process per client. Doesn't scale to a centralized multi-user deploy.
+- Restart on every client launch — cold-start cost is small but real.
+
+**When to use:** developer machines, embedded into desktop AI clients, demo deployments.
+
+### streamable-HTTP (recommended for centralized / multi-user deploys)
+
+Run the server as a long-lived HTTP service. Multiple MCP clients
+connect over HTTP+SSE. Dry-run plans live in Redis so they survive
+across requests and across processes.
+
+**Pros:**
+- One server, many clients.
+- Plans persist across client reconnects.
+- Standard observability (request logging, metrics, health checks).
+
+**Cons:**
+- Requires Redis.
+- Additional ops surface — TLS termination, ingress, auth at the
+  proxy layer.
+
+**Status:** wired but not enabled in the default entrypoint. Tracked
+in `mcp-server-scaffold-auth` T15. When ready to enable: register
+`StreamableHTTPServerTransport` (instead of `StdioServerTransport`)
+in `src/index.ts`, set `REDIS_URL`, and front the server with your
+HTTPS terminator.
+
+---
+
+## State store provisioning
+
+### In-memory (default for stdio)
+
+Used automatically when `REDIS_URL` is unset. Plans are stored in
+process memory and disappear on restart. Adequate for stdio because
+each client has its own process.
+
+### Redis (required for streamable-HTTP, optional for stdio)
+
+For streamable-HTTP deployments, plans must survive across reconnects.
+Set `REDIS_URL` to a connection string Pino's `ioredis` understands:
+
+```
+redis://[username:password@]host:port[/db]
+rediss://...    # TLS
+```
+
+For local development, `docker compose up redis` provides a
+`redis:7-alpine` instance on `redis://localhost:6379` (config in
+[`docker-compose.yml`](../docker-compose.yml)).
+
+For production, run Redis in a managed service (AWS ElastiCache, GCP
+Memorystore, Upstash, Redis Cloud). Sizing: plans are small (~1KB
+typical, max ~10KB for large bulk operations). Memory cost is
+negligible. The store TTLs entries at `confirmation.memo_ttl_seconds`
+(default 60 min); no explicit eviction policy required.
+
+---
+
+## Health checks
+
+The server doesn't expose an HTTP health endpoint by default (stdio
+has no HTTP surface). For streamable-HTTP deployments, the standard
+checks:
+
+- **TCP**: server is listening on the configured port.
+- **HTTP `GET /health`** (when registered): returns 200 with
+  `{ status: "ok", uptime_ms, version }`. Not yet wired — add when
+  enabling streamable-HTTP.
+- **MCP `initialize` round-trip**: the canonical liveness check. A
+  smoke client (see `scripts/smoke-stdio.ts`) connects, sends
+  `initialize`, expects `serverCapabilities`. Run on a 60-second
+  interval against staging.
+
+For stdio deployments embedded in desktop clients, "health" is
+end-to-end: the client surfaces server errors directly. Monitor at
+the client layer.
+
+---
+
+## Logging conventions
+
+The server uses [pino](https://getpino.io) for structured JSON logs
+(stderr only — stdout is reserved for MCP framing). Every log line
+includes:
+
+- `level` (`trace` / `debug` / `info` / `warn` / `error` / `fatal`)
+- `ts` (ISO 8601 timestamp)
+- `pid`, `hostname`
+- `request_id` (ULID, propagated through every CollageClient call)
+- `msg` (human-readable summary)
+
+### What's redacted
+
+The pino logger is configured with a redaction list — secret fields
+never appear in logs. See [`src/conventions/logger.ts`](../src/conventions/logger.ts).
+Currently redacted:
+
+- `Authorization` headers
+- `COLLAGE_API_KEY` value if accidentally logged
+- `confirmation_token` payloads (signed; not strictly secret, but
+  noisy)
+
+### How to find a request
+
+Every tool invocation generates a `request_id`. The MCP response
+includes it in the structured content; the LLM surfaces it on
+errors. Search logs by `request_id` to find the full upstream
+chain — REST calls, search proxy POSTs, dry-run plan/execute, etc.
+
+```bash
+node dist/index.js 2>&1 | jq 'select(.request_id == "01KQT...")'
+```
+
+---
+
+## Secret rotation
+
+### Rotating `COLLAGE_API_KEY`
+
+Until Collage ships a real API-key system, this is a manual flow:
+
+1. Sign into the Collage UI as the service-account user.
+2. Trigger any authenticated request; copy the new `Authorization`
+   header value.
+3. Update the environment variable wherever it's stored
+   (`.env`, secret manager, container env, Claude Desktop config).
+4. Restart the MCP server process.
+
+In-flight tool calls fail with `UNAUTHORIZED`; the LLM re-tries
+naturally. There's no token-refresh flow today; we may add one if
+Collage exposes a refresh-token endpoint.
+
+### Rotating `MCP_CONFIRMATION_SECRET`
+
+By design, rotating this secret invalidates **every in-flight
+confirmation token**. That's the intended way to revoke stale
+plans (e.g. after a security incident):
+
+1. Generate a new high-entropy value: `openssl rand -hex 32`.
+2. Update the environment variable.
+3. Restart the server process.
+
+After restart, every preview-then-confirm flow that started under
+the old secret fails the HMAC check on execute and is re-prompted
+from scratch. The dry-run framework treats this as a hard divergence,
+not a recoverable error — that's the point.
+
+---
+
+## Degraded-mode behaviors
+
+The server is designed to keep working even when individual upstream
+surfaces are unavailable. Here's what degrades and how, so ops can
+recognize each pattern:
+
+### Search proxy unavailable
+
+If `app.collage.inc/typesense/search` returns 502/503 or times out:
+
+- `search_assets` and `search_collections` return a typed `UPSTREAM`
+  error with the request_id.
+- The `library_health_audit` prompt's playbook explicitly handles
+  this: it walks `view_category_contents` per folder as a fallback
+  for small workspaces (~< 500 assets) or surfaces an `UPSTREAM`
+  finding for larger ones (where the fallback is too expensive).
+- Other tools / resources are unaffected — the REST-side surface
+  uses a separate host (`damapi.collage.inc`).
+
+### Search architecture — interim state and migration path
+
+v0.1.0 ships with `COLLAGE_SEARCH_BASE` pointing at the Nuxt
+`/typesense/search` middleware on `app.collage.inc`. Ross Durbin
+confirmed (2026-05-05) that Collage will build a first-party REST
+endpoint at `damapi.collage.inc` that supersedes this hop:
+
+- **Endpoint:** `POST /api/v1/digital-assets/search` (path TBD until
+  shipped). Body shape: `{ collections: ["digital_assets",
+  "dam_collections"], ... }`, max 3 collections per request, with
+  per-collection `query_by` / `facet_by` / `sort_by` overrides.
+- **Build window:** Week 1 (route + multiSearch dispatch + compact
+  projection) → Week 2 (filter translator + verbose projection +
+  facet defaults + error mapping) → buffer for QA + a staging
+  endpoint we can hit. Subject to Collage sprint priority.
+- **Cutover for Collage ops:** when the new endpoint is live and
+  staging-verified, change `COLLAGE_SEARCH_BASE` from
+  `https://app.collage.inc` to the new host. A coordinated MCP-side
+  release will land the path + body-shape changes; the env-var swap
+  is the only ops-side action required at cutover.
+- **Rate-limit posture post-cutover:** the new endpoint will share
+  the default `/api/v1/*` bucket (600 req/min per user) and likely
+  add a dedicated search bucket of 120 req/min per user. Tune
+  `COLLAGE_MAX_RPS` to **2** (= 120 req/min) on the worker handling
+  audit walks so the burst worst case (~400 calls on a 40-folder
+  workspace) doesn't trip the dedicated bucket. The default of 10
+  was sized for the proxy era and will be over-budget post-cutover.
+- **429 handling:** the current client already respects `Retry-After`
+  with exponential backoff; no changes required.
+
+### REST API rate-limited
+
+The token-bucket limiter (`COLLAGE_MAX_RPS`, default 10) caps
+outbound requests. If upstream returns 429, the client backs off
+and retries up to 3 times with exponential delay. Persistent 429s
+return `RATE_LIMITED` to the caller.
+
+Tune `COLLAGE_MAX_RPS` down if you observe sustained 429s in logs.
+The default is conservative for typical workspace traffic.
+
+### Empty facets on `search_assets`
+
+The Nuxt search proxy strips `facet_by` before forwarding to
+Typesense (proxy-side limitation, not a server bug). Effect:
+`facets.tags`, `facets.file_type`, `facets.date_histogram` always
+return `[]`. `next_step_hints` degrades gracefully via per-hit
+`countUntagged()`. This is a steady-state behavior, not a transient
+failure — tracked in the issue dashboard until upstream extends the
+proxy.
+
+### Dry-run confirmation expired
+
+If a plan's soft expiry (15 min) elapses but the memo store still
+has the plan record, the framework auto-refreshes:
+
+1. Re-runs `plan(input)` with the same caller input.
+2. Computes a fingerprint over the new change list (sorted by id;
+   tool-internal metadata excluded).
+3. **Match** → emits a `dry_run.auto_refresh` log entry, executes on
+   the prior plan. No caller action needed.
+4. **Mismatch** → returns `CONFIRMATION_STATE_DIVERGED` with both
+   plan summaries in `error.cause.prior_plan` and
+   `error.cause.new_plan`. The LLM should re-preview and re-confirm.
+
+If the memo expiry (60 min) elapses, the plan is genuinely gone —
+the LLM gets `NOT_FOUND` and must start over.
+
+### Folder tree size at scale
+
+`listAllCategoriesRecursive()` is bounded by `maxNodes` (default 5000)
+and `maxDepth` (default 16). On a workspace with > 5000 folders, the
+walk truncates and consumers see a partial tree. Override the bounds
+via constructor arguments if your deployment needs deeper coverage —
+budget against the 12K-token response cap accordingly.
+
+---
+
+## Observability checklist
+
+For production streamable-HTTP deployments, monitor:
+
+- [ ] Process uptime (alert on restart loops)
+- [ ] Response latency p50/p95/p99 per tool
+- [ ] Error rate per tool (`isError: true` rate)
+- [ ] `dry_run.auto_refresh` log frequency (high frequency suggests
+      callers are pausing too long; consider raising soft TTL)
+- [ ] `dry_run.divergence` log frequency (spikes suggest concurrent
+      mutations; investigate)
+- [ ] Upstream 429 rate (tune `COLLAGE_MAX_RPS`)
+- [ ] Upstream 5xx rate (track separately for `damapi.collage.inc`
+      and `app.collage.inc`)
+- [ ] Redis connection health (if streamable-HTTP)
+- [ ] Memory usage (in-memory state store grows under stdio load)
+
+Pino structured logs feed cleanly into Datadog, CloudWatch, Loki,
+etc. via stderr capture.
+
+---
+
+## Incident playbook
+
+### "All tools return UNAUTHORIZED"
+
+Most likely: `COLLAGE_API_KEY` JWT expired (the upstream session
+ended). Re-extract the token from the service-account user's
+browser session, update env, restart. See "Rotating
+`COLLAGE_API_KEY`" above.
+
+### "search_assets returns UPSTREAM, other tools fine"
+
+Most likely: the Nuxt `/typesense/search` proxy is down, or
+`app.collage.inc` is in a bad deploy state. Confirm:
+
+```bash
+curl -sS -X POST -H "Authorization: Bearer $COLLAGE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"request":{"q":"*","collections":["digital_assets"]},
+       "commonSearchParams":{"query_by":"search_name","per_page":1,"page":1},
+       "workspace_id":'"$COLLAGE_WORKSPACE_ID"'}' \
+  https://app.collage.inc/typesense/search
+```
+
+A 200 confirms the proxy is up. If it's down, the audit prompt's
+fallback path keeps small-workspace flows working; large-workspace
+audits return a structured finding instead.
+
+### "All endpoints return 402 'Workspace not available'"
+
+Confirm `COLLAGE_WORKSPACE_ID` matches the workspace the
+service-account user actually belongs to. The 402 error is a Collage
+middleware message that fires when the user-token / workspace-id pair
+doesn't resolve. Cross-check by hitting `check-workspace-access`
+directly:
+
+```bash
+curl -sS -H "Authorization: Bearer $COLLAGE_API_KEY" \
+  "https://damapi.collage.inc/api/v1/digital-assets/check-workspace-access?url_workspace_id=$COLLAGE_WORKSPACE_ID&workspace_id=$COLLAGE_WORKSPACE_ID"
+```
+
+### "Dry-run executes return CONFIRMATION_STATE_DIVERGED"
+
+Spike in this means a concurrent mutator is touching the same
+targets. Either:
+
+1. Another MCP client is operating on the same workspace.
+2. A human user is editing in the Collage UI in parallel.
+3. A scheduled job is mutating in the background.
+
+The error's `cause.prior_plan` / `cause.new_plan` shows what
+diverged. Resolve by re-prompting the LLM to re-preview, or by
+serializing access at the client layer.
+
+### "Server crashes at startup"
+
+Almost always env-related. The Zod-validated env loader fails loudly
+with a specific missing variable. Check logs for
+`Missing required environment variable: <NAME>`.
+
+If the error mentions `LOG_LEVEL` rejection, you set an invalid
+value (must be one of `debug`/`info`/`warn`/`error`).
+
+If the error mentions `pino.transport`, that's a logger config
+problem — fall back to `LOG_LEVEL=info` and check Node version
+(>= 20).
+
+---
+
+## Update / upgrade procedure
+
+The server follows [Semantic Versioning](https://semver.org). See
+[`CHANGELOG.md`](../CHANGELOG.md) for the per-version delta.
+
+Standard upgrade flow (after Collage takes over the publish credential):
+
+```bash
+# (in the deployment repo)
+npm install @collage-dam/mcp-server@latest
+# or pin: npm install @collage-dam/mcp-server@0.2.0
+```
+
+Then restart the server process. Breaking changes will be flagged in
+the changelog and bump the major version (e.g. `0.x` → `1.0`).
+
+The MCP protocol itself is versioned via the `initialize` capability
+exchange. The server pins to `@modelcontextprotocol/sdk@1.12.1` —
+upgrade SDK separately when the protocol bumps.
+
+---
+
+## Handoff checklist (for Collage ops)
+
+When taking ownership at Week 6:
+
+- [ ] Service-account user provisioned and JWT extracted.
+- [ ] `COLLAGE_API_KEY`, `COLLAGE_WORKSPACE_ID`, `MCP_CONFIRMATION_SECRET` set in your secret manager.
+- [ ] Smoke test: `npm run smoke` against the configured workspace returns `has_access: true` for `list_workspaces`.
+- [ ] Logs are flowing to your aggregator (Datadog / CloudWatch / Loki).
+- [ ] If using streamable-HTTP: Redis provisioned and reachable; TLS terminator configured.
+- [ ] Token-rotation runbook entry added to your ops wiki, referencing this doc.
+- [ ] Internal SLO defined for tool error rate (suggested: < 5% per tool, p95 latency < 3s).
+- [ ] Alert on prolonged `UPSTREAM` rate (suggests Collage REST or search proxy is degraded).
+
+For questions during transition: see the contacts list in
+[`docs/api-field-verification.md`](./api-field-verification.md) header.

package/docs/security-review.md

@@ -0,0 +1,195 @@
+# Security Review — collage-mcp v0.1.0
+
+**Reviewed:** 2026-05-05
+**Scope:** `mvp-release-distribution` T6 — token storage, telemetry-by-default, redaction verification
+**Reviewer:** Southleft (Justin)
+**Outcome:** No P0 blockers. Three small defensive hardenings landed during the review (see _Changes Landed_); residual recommendations tracked below.
+
+---
+
+## Executive summary
+
+The server is a stdio-first MCP server with one upstream destination (Collage REST API at `damapi.collage.inc`) and one search proxy (`app.collage.inc/typesense/search`). It ships no telemetry, no analytics SDKs, no postinstall scripts, and writes logs only to `stderr`. Secret material — the Collage Bearer JWT and the HMAC confirmation secret — is held in process memory, never persisted to disk by this server, and redacted in serialised config. The dry-run framework's confirmation tokens are HMAC-SHA256 signed, single-use (atomic `getAndDelete`), tool-name-bound, and fingerprint-bound, so a leaked token cannot be replayed against substituted args.
+
+Three small defense-in-depth fixes were applied during the review:
+
+1. Pino redaction paths extended to cover `Authorization`, `bearer`, `signed_token`, `confirmation_token`, `apiKey`.
+2. Upstream error bodies (REST + search proxy) are now passed through a sanitiser that replaces `Bearer ...`, JWT-shaped strings, and `api_key=...` patterns before being interpolated into the LLM-visible `McpToolError.message`, then clamped to 512 chars.
+3. `loadConfig()` warns on stderr when `MCP_CONFIRMATION_SECRET` is shorter than 32 characters.
+
+5 new unit tests cover the sanitiser + entropy warning. Full suite: **523 passing** (up from 518), `tsc --noEmit` clean.
+
+---
+
+## Surface inventory
+
+| Surface | Inbound | Outbound | Storage |
+|---|---|---|---|
+| stdio transport | JSON-RPC over stdin | JSON-RPC over stdout (framing only) | none |
+| streamable-HTTP transport (Phase 2 / optional) | HTTPS (Collage-fronted) | (same) | Redis (ephemeral plans, TTL 60m) |
+| REST client | n/a | `https://damapi.collage.inc/api/v1/*` (Bearer JWT) | none |
+| Search proxy | n/a | `https://app.collage.inc/typesense/search` (Bearer JWT) | none |
+| Logger | n/a | `stderr` (fd 2) only | none |
+
+No other network egress, file I/O, or third-party services are touched.
+
+---
+
+## Findings
+
+### F1 — Upstream error bodies could pass through to LLM-visible messages — **resolved 2026-05-05**
+
+`client.ts`'s `request()` and `typesense.ts`'s `postJson()` both wrapped the raw upstream response body into the thrown error's `message`, which then ends up in `McpToolError.message` returned to the calling LLM. Production Collage responses don't echo credentials, but defensive coding warranted a sanitiser at the boundary.
+
+**Resolution:** added `sanitizeUpstreamBody()` (REST) and `sanitizeProxyBody()` (search) that:
+
+- Replace `Bearer <token>` → `Bearer [REDACTED]`
+- Replace JWT-shaped substrings (`eyJ...`) → `[REDACTED_JWT]`
+- Replace `api_key=`, `token=`, `secret=` value pairs → `…=[REDACTED]`
+- Clamp to 512 chars
+
+Tests: `tests/unit/client.test.ts` — three new cases for Bearer, JWT, and length clamp.
+
+**Severity:** medium (defense in depth, no known active leak path)
+**Status:** ✅ fixed in this review
+
+---
+
+### F2 — Pino redact paths missed common secret-bearing keys — **resolved 2026-05-05**
+
+The redaction path list (`*.api_key`, `*.token`, `*.password`, `*.secret`, `*.COLLAGE_API_KEY`, `*.TYPESENSE_API_KEY`, `*.MCP_CONFIRMATION_SECRET`) didn't cover `Authorization`, `bearer`, `apiKey` (camelCase), `signed_token`, or `confirmation_token`. No current call site logs these keys, but the redact rules are defense-in-depth — a future contributor could add a log line that does.
+
+**Resolution:** redact path list extended in `src/conventions/logger.ts`. Existing `secrets-audit.test.ts` continues to pass; the new keys are additive.
+
+**Severity:** low (no active leak; widens redaction net for future code)
+**Status:** ✅ fixed in this review
+
+---
+
+### F3 — `MCP_CONFIRMATION_SECRET` strength only validated as `min(1)` — **resolved 2026-05-05**
+
+`loadConfig()` accepted any non-empty string for `MCP_CONFIRMATION_SECRET`. A short secret (e.g., `"dev"`) would let HMAC-SHA256 confirmation tokens be brute-forced offline given a single observed token.
+
+**Resolution:** `loadConfig()` now writes a warning to stderr when the secret is shorter than 32 chars:
+
+```
+WARN: MCP_CONFIRMATION_SECRET is shorter than 32 characters. Use at least 32
+high-entropy bytes (e.g. `openssl rand -hex 32`) so HMAC tokens are not
+feasibly forgeable.
+```
+
+This is a warning rather than a hard fail because the runbook recommendations already cover this and an existing deployment with a 24-char secret shouldn't refuse to start on upgrade. The hard-fail path stays available if the secret is missing entirely.
+
+Tests: `tests/unit/conventions/env.test.ts` — two new cases (short secret warns, 32+ char secret silent).
+
+**Severity:** medium
+**Status:** ✅ fixed in this review
+
+---
+
+### F4 — Confirmation token TTL increased from 5m → 15m on 2026-05-01 — **information**
+
+This is recorded here for the security review record because it widens the replay window for an exfiltrated token. The increase was deliberate (live QA showed 5m was hostile to human review pauses). The mitigations remain:
+
+- HMAC-SHA256 with timing-safe comparison (`verifyConfirmation` uses `crypto.timingSafeEqual`)
+- Single-use enforcement via atomic `EphemeralStateStore.getAndDelete`
+- Tool-name binding (token bound to one tool; cross-tool reuse rejected)
+- Fingerprint binding (re-plan + fingerprint compare on soft-expired tokens; mismatch returns `CONFIRMATION_STATE_DIVERGED`)
+- 60m hard memo TTL (after which the plan record is gone and the token is dead)
+
+Net replay-window effect: the soft window grew from 5m → 15m, but the token still cannot be reused with substituted args, cannot be reused after one execute, and cannot survive the hard 60m memo TTL.
+
+**Severity:** low (compensating controls intact)
+**Status:** noted; no change needed
+
+---
+
+### F5 — REST client logger logs the upstream error message at WARN level — **information**
+
+`client.ts:1292` logs `{err: {name, message}}` on every failed request. The message originates from the upstream body and is now sanitised (F1), so the log is bounded and credential-stripped. Stays as a recommendation if Collage operations decide to forward stderr to a remote sink — they should treat the JSON `err.message` field as `internal-debug` and not customer-visible.
+
+**Severity:** informational
+**Status:** documented in `docs/deployment-runbook.md`'s "Logging conventions" section
+
+---
+
+## Verified clean (no action)
+
+Things checked and found acceptable as-is:
+
+- **No telemetry SDKs.** Dependency tree: `@modelcontextprotocol/sdk`, `ioredis`, `pino`, `ulid`, `zod`. No analytics, no error reporting, no usage beacons.
+- **No postinstall / preinstall scripts.** Reduces supply-chain risk on `npm install`.
+- **No outbound HTTP except Collage-controlled endpoints.** Verified by grep: only `globalThis.fetch` calls in `client.ts` (REST) and `typesense.ts` (search proxy).
+- **Logger writes to stderr only** (`pino.destination({ fd: 2 })`). Stdout is reserved for MCP framing.
+- **Bearer header constructed inline at request time.** Never logged. The `headers` object is not interpolated into any log line.
+- **HMAC confirmation flow.** Timing-safe comparison via `crypto.timingSafeEqual`, single-use via atomic `getAndDelete`, tool-name binding, fingerprint binding. See `src/conventions/confirmation.ts` and `src/conventions/dry-run/with-dry-run.ts`.
+- **AppConfig redacts via `toJSON()` / `toString()`.** Direct property access still returns the real value (so the client can use the token), but anything that JSON-serialises the config — including accidental log lines or error.cause objects — gets `[REDACTED]`. See `src/conventions/env.ts:withRedaction()`.
+- **npm tarball is tight.** `files` allowlist scopes the package to `dist`, `README.md`, `CHANGELOG.md`, `LICENSE`, `.env.example`, `docs`. `npm pack --dry-run` confirmed no `.env`, no tests, no source maps from outside `dist`. 261 files, 228KB packed.
+- **`.env` excluded from git.** `.gitignore` covers `*.env` with a `!.env.example` un-ignore. No `.env` checked in.
+- **No hardcoded secrets in `src/`.** Existing `tests/unit/conventions/secrets-audit.test.ts` greps source for OpenAI-style keys, hardcoded Bearer tokens, and `api_key="..."` / `token="..."` patterns. Passes.
+- **`.env.example` has empty placeholders.** Tested (`secrets-audit.test.ts`). No real secrets shipped.
+- **README + runbook cover token guidance.** Service-account user, JWT extraction steps, rotation cadence, secret-manager guidance, Confirmation secret rotation as a kill switch.
+- **Search proxy is enforcement seam.** Workspace scope is enforced server-side by the Nuxt `/typesense/search` middleware (it verifies the Bearer via Laravel `/user`, resolves the caller's `workspace_unique_id`, and rewrites the filter). The MCP wrapper cannot construct a cross-workspace query because the proxy refuses any workspace the Bearer's user is not a member of. Documented in `src/typesense.ts` and the deployment runbook.
+- **Rate limiting present.** `TokenBucketRateLimiter` (default 10 RPS, env-tunable) caps egress to upstream. Not a security control directly, but bounds blast radius of a runaway loop.
+
+---
+
+## Telemetry / data-egress posture
+
+This server, by design, has **no telemetry**. There is no opt-in flag because there is nothing to opt into:
+
+- No usage events fired on tool invocation.
+- No error reporting to a remote SaaS (Sentry, etc.) — errors flow only to stderr and back to the calling LLM.
+- No "anonymous metrics" emitted on startup or shutdown.
+
+The deliverable explicitly meets the spec's "no telemetry by default, opt-in error reporting" requirement by virtue of having no telemetry surface at all. If Collage wants to add error reporting post-handoff, it should be a separate, opt-in module wired into `src/conventions/logger.ts`'s pino transport stack — recommended approach: an additional pino transport target gated behind an env var like `COLLAGE_MCP_ERROR_REPORTING_DSN`, default-empty.
+
+---
+
+## Token storage posture
+
+Two secrets are loaded at startup via `loadConfig()`:
+
+1. `COLLAGE_API_KEY` — JWT Bearer token. Held as a `private readonly` field on `CollageClient`. Used as the `Authorization: Bearer …` header on every Collage REST and search-proxy request. Never written to disk. Never logged (verified by grepping all log call sites).
+2. `MCP_CONFIRMATION_SECRET` — HMAC signing secret. Held by reference in each mutating tool's `MutatingToolDeps.secret`. Used only in `crypto.createHmac('sha256', secret)` calls. Never written to disk. Never logged.
+
+Both are redacted from `AppConfig`'s `toJSON()` / `toString()` output. The redacted-config defense covers the failure mode where a future contributor logs the full config struct.
+
+Operations guidance (see `docs/deployment-runbook.md`):
+
+- Use a dedicated service-account user for the JWT, not a personal session.
+- Rotate the JWT when the upstream session expires (currently no refresh-token flow on the Collage side).
+- Generate `MCP_CONFIRMATION_SECRET` with `openssl rand -hex 32` minimum.
+- Rotating the confirmation secret invalidates every in-flight confirmation token by design — that is the intended kill switch for a stale-plan incident.
+
+---
+
+## Changes landed in this review
+
+| File | Change |
+|---|---|
+| `src/conventions/logger.ts` | Extended pino redact paths (Authorization, bearer, signed_token, confirmation_token, apiKey) |
+| `src/conventions/env.ts` | Stderr warning when `MCP_CONFIRMATION_SECRET.length < 32` |
+| `src/client.ts` | Added `sanitizeUpstreamBody()` — Bearer/JWT/`*=...` scrub + 512-char clamp before upstream body reaches `McpToolError.message` |
+| `src/typesense.ts` | Mirror of the same sanitiser at the search-proxy boundary |
+| `tests/unit/conventions/env.test.ts` | 2 new tests (short-secret warn, long-secret silent) |
+| `tests/unit/client.test.ts` | 3 new tests (Bearer scrub, JWT scrub, length clamp) |
+
+Tests: 523 passing (up from 518). Lint: clean.
+
+---
+
+## Recommendations for Collage post-handoff
+
+Not blocking the v0.1.0 ship, but worth tracking:
+
+1. **Service-account JWT refresh.** Today the JWT expires with the upstream session. If Collage adds a refresh-token endpoint server-side, wire it into `CollageClient` so long-lived deployments don't require manual rotation. (Tracked in runbook secret-rotation section.)
+2. **Optional opt-in error reporting.** If/when Collage wants Sentry-like error visibility, add a pino transport target gated on a `COLLAGE_MCP_ERROR_REPORTING_DSN` env var. Default empty → no transport → current behavior unchanged.
+3. **Hard-fail mode for short confirmation secrets.** Current behavior is a warning; some Collage deployments may prefer hard-fail. Consider a `MCP_STRICT_SECRETS=1` env that turns the warning into a thrown error.
+4. **Audit log for executed mutations.** Every mutation runs through the dry-run framework and produces an execute-phase ledger. If Collage wants a tamper-evident audit trail beyond stderr logs, persist the ledger plus the confirmation_id and request_id to the same Redis used for the plan store, with a longer TTL or a separate sink.
+
+---
+
+## Sign-off
+
+The v0.1.0 deliverable meets the SOW Phase 2 security-review requirement. No P0 blockers. The three medium-severity items identified during the review (F1, F2, F3) have been resolved in-band. The two informational items (F4, F5) are documented and have intact compensating controls. Recommended for ship.