@terreno/mcp 57.20.0 → 57.22.0

package/src/docs/versioned/57.20.0/implementationPlans/inbound-webhooks.md

@@ -0,0 +1,307 @@
+# Implementation Plan: Inbound webhook framework
+
+**Status:** Complete — shipped in #1251  
+**Branch:** `cursor/inbound-webhooks-4945`  
+**Owner:** —  
+**Created:** 2026-09-01  
+**Approved:** 2026-09-01  
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1172 (this feature **closes** that issue; implementation PRs use `Fixes #1172`)  
+**Task list:** [inbound-webhooks.md](../tasks/inbound-webhooks.md)  
+**Depends on:** —  
+**RTK deprecation flag:** None  
+**Program:** [B2B platform](b2b-platform-program.md)  
+
+## Goal
+
+`@terreno/api` can receive signed HTTP callbacks from Stripe, Twilio, SendGrid, and
+similar providers. Apps register webhook routes on a `WebhooksApp` plugin that captures
+the raw body, verifies signatures, claims event ids so retries are no-ops, and dispatches
+to a handler. `@terreno/comms` registers Twilio SMS and SendGrid Event Webhook routes on
+that plugin and maps them through `recordDeliveryEvent` / `recordOptOut`. Stripe checkout
+sync stays in `billing-stripe` Phase 3.
+
+## Non-Goals
+
+- Stripe **billing** handlers, models, or `/billing/webhooks/stripe` (`billing-stripe`
+  Phase 3).
+- Expo push delivery — that adapter **polls receipts**; it does not need inbound HTTP
+  despite the seed blurb.
+- Outbound Slack / Google Chat / Zoom notifiers (already shipped).
+- GitHub / CircleCI CI webhooks, Expo API routes, or a job queue (`job-queues`).
+- Default-on example Stripe endpoint or a framework-global `WEBHOOK_SECRET`.
+- SDK / RTK hooks for webhook POSTs (providers call the API, not the app UI).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Package | **`@terreno/api`**, class `WebhooksApp` implementing `TerrenoPlugin`. Same home as notifiers and rate limiting. No new workspace package. |
+| Registration | Consumer-owned paths. `webhooks.route({path, verify, eventId, handler})` then `app.register(webhooks)`. Billing stays at `POST /billing/webhooks/stripe`. |
+| Comms routes | **In this IP**, in `@terreno/comms`. `CommsApp` takes a `WebhooksApp` and registers Twilio + SendGrid routes when those adapters are the configured `sms` / `mail` providers. Mapping tables stay the adapter IPs' contract. |
+| Raw body | Stash `Buffer` on the request during parse (`express.json` / `urlencoded` `verify`). Never re-serialize `req.body` for HMAC (today's auth-doc snippet is wrong). |
+| Content types | JSON (Stripe, SendGrid) and `application/x-www-form-urlencoded` (Twilio). Other types via an explicit `parser: "raw"` route option. |
+| Verifiers | Built-in: generic HMAC, Stripe `Stripe-Signature`, Twilio request validator, SendGrid Event Webhook ECDSA. Custom `verify(req) => boolean \| Promise<boolean>`. |
+| Secrets | Per-route. Framework does **not** read `WEBHOOK_SECRET`. That env stays optional for the example HMAC demo only. |
+| Auth | No JWT / Better Auth session. Missing or invalid signature → `APIError` 401 `code: "webhook-signature-invalid"`. Missing raw body → 400. |
+| Idempotency | Optional store. Unique claim on `(source, eventId)` **before** `handler`; duplicate → 200 `{received: true, duplicate: true}` without calling `handler`; handler throw deletes the claim so the provider can retry. |
+| Stores | `memory` (tests / single process) \| `mongo` (`webhookReceipts`, TTL default 7 days). No Redis in this slice. |
+| Replay window | Stripe verifier: 300s timestamp skew (Stripe default). Generic HMAC: optional timestamp header + skew. Twilio: no timestamp; rely on MessageSid claim. |
+| Dispatch | Await `handler` then 200 `{received: true}`. No 200-before-work. Slow work stays in a later `job-queues` IP. |
+| Rate limit | Do **not** skip webhook paths. Unsigned floods still consume the `api` IP bucket. |
+| OpenAPI | Do not emit webhook POSTs into `/openapi.json` (no generated SDK hooks). |
+| Compare | `crypto.timingSafeEqual` on equal-length buffers; length mismatch is invalid. |
+| Logging | `createScopedLogger` prefix `[Webhook]` + labels `source`, `eventId`. Never log secrets, raw signatures, or full payloads. |
+
+## Architecture
+
+```
+TerrenoApp
+  json + urlencoded parsers stash req.rawBody
+  …
+  WebhooksApp.register(app)
+    POST {path}  →  parse already done
+                 →  verify(req) using req.rawBody
+                 →  eventId(req)
+                 →  claim (source, eventId)
+                 →  handler({rawBody, body, headers, eventId})
+                 →  200 or 500 (release claim)
+```
+
+```typescript
+const webhooks = new WebhooksApp({idempotency: {store: "mongo"}});
+
+webhooks.route({
+  path: "/billing/webhooks/stripe",
+  source: "stripe",
+  parser: "json",
+  verify: stripeSignature({secret: process.env.STRIPE_WEBHOOK_SECRET!}),
+  eventId: (req) => String((req.body as {id?: string})?.id ?? ""),
+  handler: async ({body}) => { /* billing IP */ },
+});
+
+new TerrenoApp({userModel: User}).register(webhooks).start();
+```
+
+### Comms registration
+
+```typescript
+const webhooks = new WebhooksApp({idempotency: {store: "mongo"}});
+
+new TerrenoApp({userModel: User})
+  .register(webhooks)
+  .register(
+    new CommsApp({
+      mail: new SendGridMailProvider(),
+      sms: new TwilioSmsProvider(),
+      webhooks,
+      webhookPublicUrl: process.env.PUBLIC_API_URL, // Twilio signature URL
+    })
+  )
+  .start();
+```
+
+`CommsApp` calls `webhooks.route` during `register` when `options.webhooks` is set:
+
+| When | Path | Verifier | `eventId` |
+|------|------|----------|-----------|
+| `sms` is `TwilioSmsProvider` | `{basePath}/webhooks/twilio/status` | `twilioSignature` | `MessageSid` |
+| `sms` is `TwilioSmsProvider` | `{basePath}/webhooks/twilio/inbound` | `twilioSignature` | `SmsSid` + inbound `Body` keyword |
+| `mail` is `SendGridMailProvider` | `{basePath}/webhooks/sendgrid` | `sendgridEventSignature` | per-event `sg_event_id` (batch) |
+
+Default `basePath` is `/comms`. Omit `webhooks` → no inbound routes (send path unchanged).
+Missing Twilio auth token or SendGrid verification key → skip that provider's routes and
+`logger.error` (do not crash boot).
+
+SendGrid posts an **array** of events. The HTTP request may skip a single `eventId`; the
+handler calls public `webhooks.claim({source: "sendgrid", eventId})` per `sg_event_id`,
+maps each event per the SendGrid adapter table, then `getCommsService().recordDeliveryEvent`
+/ `recordOptOut`. Correlate mail rows by `sg_message_id` prefix vs stored `x-message-id`.
+
+Twilio status mapping and STOP/START opt-outs follow
+[comms-adapter-twilio-sms](comms-adapter-twilio-sms.md). When webhooks are registered,
+`TwilioSmsProvider` `statusCallbackUrl` defaults to
+`${webhookPublicUrl}{basePath}/webhooks/twilio/status` so sends attach the callback.
+
+Stripe remains a how-to example only in this slice.
+
+`WebhooksApp` must run its capture setup **before** `express.json`. Plugins currently
+mount after JSON, so `WebhooksApp` also implements an early hook: `TerrenoApp.build()`
+calls `plugin.captureRawBody?.(app)` (or equivalent) before JSON, then `register` for
+routes. If no webhook plugin is registered, parser behavior stays as today except a
+harmless `rawBody` Buffer on JSON/urlencoded requests (document the extra field).
+
+Prefer attaching `rawBody` on every JSON parse via the existing `verify` callback so
+consumers that register late still verify correctly. Add `express.urlencoded` next to
+JSON (auth already mounts urlencoded later; consolidating is allowed if tests stay green).
+
+### Verifier helpers (no vendor SDKs required)
+
+| Helper | Input | Algorithm |
+|--------|--------|-----------|
+| `hmacSignature({secret, header, encoding?, algorithm?, timestampHeader?})` | Header vs HMAC of `rawBody`, or `${timestamp}.${rawBody}` when `timestampHeader` is set | Default SHA-256 hex; optional skew (300s) |
+| `stripeSignature({secret, toleranceSec?})` | `Stripe-Signature` `t=` / `v1=` | HMAC-SHA256 of `${t}.${rawBody}` |
+| `twilioSignature({authToken, url?})` | `X-Twilio-Signature`; URL + sorted POST params | HMAC-SHA1 base64 (Twilio validator) |
+| `sendgridEventSignature({publicKey, toleranceSec?})` | `X-Twilio-Email-Event-Webhook-Signature` + timestamp | ECDSA P-256 over `${timestamp}${rawBody}`; default 300s skew |
+
+`url` for Twilio defaults to the public URL the provider was given (`X-Forwarded-Proto` /
+`Host` + original URL only when `trust proxy` is on — same rule as rate limiting). Apps
+behind Cloud Run should pass the configured callback URL explicitly.
+
+### Idempotency store
+
+```
+claim({source, eventId}) → "claimed" | "duplicate"
+release({source, eventId})  // handler failure only
+```
+
+`WebhooksApp.claim` / `release` are public so a batch handler (SendGrid) can claim each
+nested event id. HTTP-level `eventId` remains optional.
+
+Mongo collection `webhookReceipts`: `source` (string), `eventId` (string), `created`
+(date). Unique compound index `(source, eventId)`. TTL on `created`. Field `description`s
+if it is a Mongoose model (`mongoose-schema-safety`). Not a public `modelRouter` model.
+
+Routes with empty `eventId` skip the store and always run `handler` (log a warning).
+Billing may keep `BillingEvent.stripeEventId` as a second, domain-level unique key;
+the framework claim still runs so unsigned retries never double-dispatch if billing is slow.
+
+## Models
+
+Optional internal **WebhookReceipt** only when `idempotency.store === "mongo"`. Five-type
+pattern, `createdUpdatedPlugin` optional; TTL index is the retention mechanism.
+`isDeletedPlugin` is unnecessary (rows expire).
+
+## APIs
+
+No framework-fixed path. Contract per registered route:
+
+| Status | Body / error | When |
+|--------|----------------|------|
+| 200 | `{received: true}` | Handler succeeded |
+| 200 | `{received: true, duplicate: true}` | Event id already claimed |
+| 400 | `webhook-body-missing` | No `rawBody` |
+| 401 | `webhook-signature-invalid` | Verify failed or missing header |
+| 500 | existing `APIError` / `apiErrorMiddleware` | Handler threw (claim released) |
+
+Anonymous. Not listed in OpenAPI.
+
+Comms (when `webhooks` is passed and the adapter is configured):
+
+| Method | Path | Notes |
+|--------|------|--------|
+| POST | `/comms/webhooks/twilio/status` | Form-urlencoded; Twilio signature |
+| POST | `/comms/webhooks/twilio/inbound` | Form-urlencoded; STOP/START → `OptOutEvent` |
+| POST | `/comms/webhooks/sendgrid` | JSON array; ECDSA; per-event claim |
+
+## Notifications
+
+Comms webhook handlers update `CommsMessage` via `recordDeliveryEvent` / `recordOptOut`.
+A throwing `recordDeliveryEvent` (save failure) releases the claim so the provider can retry.
+
+## UI
+
+None. example-backend:
+
+- HMAC demo `POST /webhooks/example` when `WEBHOOK_SECRET` is set.
+- Pass the same `WebhooksApp` into `CommsApp` so Twilio/SendGrid routes exist whenever
+  those adapters are already env-registered. Set `PUBLIC_API_URL` (or
+  `COMMS_WEBHOOK_PUBLIC_URL`) for Twilio signatures on Cloud Run.
+
+## Docs in this slice
+
+| Page | Change |
+|------|--------|
+| `docs/how-to/inbound-webhooks.md` | **New.** Register a route, raw body, verifiers, idempotency, Cloud Run URL, do not stringify `req.body`. |
+| `docs/how-to/README.md` | Link the how-to. |
+| `docs/reference/api.md` | `WebhooksApp` under Webhooks & Notifications; contrast outbound notifiers. |
+| `docs/explanation/authentication.md` | Replace HMAC-on-`JSON.stringify(req.body)` with `WebhooksApp`. |
+| `docs/reference/environment-variables.md` | `WEBHOOK_SECRET` is example-demo only; `SENDGRID_WEBHOOK_VERIFICATION_KEY`, `PUBLIC_API_URL` / `COMMS_WEBHOOK_PUBLIC_URL`. |
+| `docs/reference/comms.md` | Twilio + SendGrid webhook paths, mapping, `CommsApp({webhooks})`. |
+| `docs/explanation/roadmap-seed-issues.md` | IP + task GitHub URLs; `IP=inbound-webhooks`. |
+| `.rulesync/skills/terreno-backend-api/references/custom-routes.md` | Replace hand-rolled Stripe stub with `WebhooksApp.route`. |
+| `.rulesync/rules/api/00-api.mdc` | One paragraph on inbound webhooks. |
+| `changelog/unreleased/inbound-webhooks.md` | Added. |
+| `bun run rules` / `skills:sync` | After rulesync edits. |
+
+## Testing
+
+Bun + supertest against `TerrenoApp.build()`, `@terreno/test` Mongo. Do not mock
+`@terreno/api`. Use `backend-test-env` if tests set secrets.
+
+Must cover:
+
+- Valid HMAC 200 and handler called once.
+- Tampered body / missing header 401, handler not called.
+- `JSON.stringify(req.body)` HMAC does **not** verify (proves raw capture).
+- Same `eventId` twice: first 200, second 200 `duplicate: true`, handler once.
+- Handler throw: 500, retry succeeds (claim released).
+- Stripe fixture header (known secret + payload + timestamp inside/outside window).
+- Twilio form-urlencoded body verifies; JSON body on that route 401.
+- SendGrid ECDSA fixture (generated keypair in test).
+- OpenAPI document does not list the webhook path.
+- Default app with no `WebhooksApp` still parses JSON as today.
+- Twilio signed status fixture updates `CommsMessage.status`; unsigned 401.
+- Twilio STOP inbound fires `onOptOut` with `reason: "sms-stop"`.
+- SendGrid signed `delivered` / `bounce` / `spamreport` fixtures map per the adapter
+  table; unsigned 401; duplicate `sg_event_id` is a no-op.
+
+## Phases
+
+1. **Tracer:** raw body + `WebhooksApp` + HMAC + memory idempotency + example route.
+2. **Provider verifiers + Mongo store:** Stripe, Twilio, SendGrid helpers; mongo receipts.
+3. **Comms routes:** Twilio status + inbound, SendGrid Event Webhook, example-backend wiring.
+4. **Docs + seed + agent skill:** Diátaxis, changelog, rulesync, dependent-IP links.
+
+## Feature Flags & Migrations
+
+New optional collection only. No user data migration. No RTK flag.
+
+## Activity Log & User Updates
+
+`logger` / scoped webhook logger. No activity-log product surface.
+
+## Not Included / Future Work
+
+- Redis receipt store.
+- 200-then-queue dispatch (`job-queues`).
+- GitHub App / CircleCI inbound (CI IP).
+- Expo push HTTP (not required).
+- Stripe billing webhook (`billing-stripe` Phase 3).
+
+## Files to Create / Modify
+
+- `api/src/webhooks/` — `webhooksApp.ts`, `rawBody.ts`, `verifiers/*.ts`, `idempotency/*.ts`, tests
+- `api/src/terrenoApp.ts` — early raw-body capture; plugin hook
+- `api/src/index.ts` — exports
+- `comms/src/commsApp.ts` — `webhooks` / `webhookPublicUrl` options
+- `comms/src/adapters/twilioSms.ts` (+ webhook helper) — status + inbound routes
+- `comms/src/adapters/sendgrid.ts` (+ webhook helper) — Event Webhook route
+- `example-backend/src/server.ts` — HMAC demo + pass `WebhooksApp` into `CommsApp`
+- Docs, rulesync, changelog as in the table
+- Adapter task lists: Phase 2 owned here
+- `docs/implementationPlans/billing-stripe.md` — Depends on this IP (not “pending”)
+
+## Task List
+
+See [docs/tasks/inbound-webhooks.md](../tasks/inbound-webhooks.md).
+
+## Acceptance Criteria
+
+- [ ] An app can register `POST /webhooks/example` with HMAC verification; a signed
+      request returns 200 and runs the handler; an unsigned or tampered request returns
+      401 and does not run it. Verified by bun tests in `api/src/webhooks/`.
+- [ ] Signature verification uses the raw request bytes, not `JSON.stringify(req.body)`.
+      Verified by a test that would pass the old auth-doc snippet and fails here.
+- [ ] Replaying the same `(source, eventId)` is a 200 no-op. Verified by bun tests
+      (memory and mongo stores).
+- [ ] Built-in Stripe, Twilio, and SendGrid verifiers accept a fixture and reject a
+      mutated payload. Verified by bun tests with no live network.
+- [ ] Webhook paths are absent from `/openapi.json`. Verified by bun test against
+      `TerrenoApp.build()`.
+- [ ] How-to + reference + auth explanation match the shipped API. Verified by reading
+      those pages in Roast; `bun run website:build` in the docs task.
+- [ ] `billing-stripe` can call `webhooks.route` without forking parsers. Verified by a
+      compile-checked Stripe example in the how-to (handlers stay in that IP).
+- [ ] With `CommsApp({webhooks, sms: TwilioSmsProvider, mail: SendGridMailProvider})`,
+      signed Twilio and SendGrid fixtures update `CommsMessage` / fire `onOptOut`;
+      unsigned requests are 401. Verified by bun tests in `comms/`.

package/src/docs/versioned/57.20.0/implementationPlans/infra-mcp.md

@@ -0,0 +1,293 @@
+# Implementation Plan: Infrastructure MCP server (`@terreno/infra-mcp`)
+
+**Status:** Approved — unblocked; RBAC module is Complete ([rbac-permissions.md](rbac-permissions.md))
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1090
+**Branch:** TBD
+**Owner:** TBD
+**Created:** 2026-08-09
+**Research:** [infra-mcp-research.md](infra-mcp-research.md)
+
+## Goal
+
+A deployable, self-contained MCP server that puts privileged infrastructure tooling — GCP, Sentry, MongoDB, and later Expo/EAS and Vercel — behind a single MCP endpoint with per-user authentication, RBAC-driven read/write permission tiers, per-call write confirmation, and a full audit trail. Packaged as a reusable `@terreno/infra-mcp` workspace package targeting one-man shops through growing startups, dogfooded by our own Cloud Run deployment. Cloud agents stop receiving raw `GCP_SA_*` service-account env vars and instead call this server with scoped service tokens.
+
+## Non-Goals
+
+- Per-user vendor identity (on-behalf-of OAuth to GCP/Sentry/etc.) — the credential interface accepts a user context so this can be added later, but v1 executes with server-held credentials.
+- Proxying vendor MCP servers that require interactive browser OAuth (Vercel `mcp.vercel.com`, Expo `mcp.expo.dev`) — research showed these are allowlisted/interactive-only; those vendors get native tools instead.
+- A bespoke permission engine — permissioning is the `@terreno/api` RBAC module (`createAccess`), not custom code.
+- Rate limiting, cost tracking, tool versioning (future work).
+- Changes to the existing `@terreno/mcp` docs server (stays on SDK v1, unchanged).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Approach | **Option C (hybrid):** native curated tools first; proxied vendor-MCP adapters behind an explicit per-tool allow-list with mandatory read/write annotation |
+| Protocol | **MCP 2026-07-28 spec** via TS SDK v2 (`@modelcontextprotocol/server`), `createMcpHandler` with `legacy: "stateless"` so 2025-era clients keep working |
+| Permissioning | **`@terreno/api` RBAC module** — this IP is blocked behind that PR. Each integration is an RBAC resource with `read`/`write` actions; meta-permissions live on an `infra` resource |
+| Write safety | **Write tools require per-call confirmation (MCP elicitation).** A config option can disable confirmation per integration or globally, but it only takes effect for users holding `infra:writeUnconfirmed` — everyone else is still prompted |
+| Phase 1 scope | **Read-only:** GCP observability (logs/metrics/errors), Sentry, MongoDB |
+| GCP credentials | **Cloud Run default runtime service account only (ADC).** No injected SA key env vars anywhere; the `GCP_SA_*` pattern for cloud agents is retired. IAM on the runtime SA is the outer bound; the MCP's RBAC is the per-user gate |
+| Other credentials | Static tokens (Sentry auth token, Mongo connection strings, later `EXPO_TOKEN`) from Secret Manager/env |
+| Vercel credentials | **One team-scoped token per Vercel team**, keyed by team slug; each project resolves to its team by asking which token can see it (cached). Project-scoped tokens are not enough: they list deployments and read build logs but get 403 on runtime logs (`POST /v1/observability/events`, measured 2026-10-25; the CLI says "You don't have access to runtime logs for this project"), and Vercel has no scope between project and team |
+| Resource scoping | An integration's reads can be narrowed per caller to named vendor resources (e.g. a machine user may read only its own Vercel projects) with an RBAC `scopes` entry (`vercel.read`). The tool resolves the resource first, then calls `access.can({permissions: {vercel: ["read"]}, context: {projectId}})`. Unknown and forbidden resources get the same refusal, so a caller can't probe names |
+| User store & login | Mongo users via `@terreno/api` (`baseUserPlugin` + `rbacUserPlugin`); MCP clients authenticate via OAuth 2.1 using **`@better-auth/oauth-provider` + `@better-auth/mcp`** (already aligned with the 2026-07-28 authorization spec: CIMD, RFC 9728, `requireMcpAuth`) |
+| Non-human callers | Service tokens (Better Auth `apiKey` plugin if compatible, else a `ServiceToken` model) mapped to machine users with RBAC roles — this is how cloud agents call the server. An orchestrator that starts agent sandboxes mints **one machine user and one token per sandbox** at create (role scoped to that sandbox's repo/resources) and revokes them at teardown. It's per sandbox, not per repo, because `@terreno/api` caps a user at ten live service tokens |
+| Packaging | New workspace package `infra-mcp/` publishing `@terreno/infra-mcp`; config-driven integration registry; deployed via a clone of the existing `mcp_service` terraform module |
+
+## Architecture
+
+```
+MCP client (Cursor, Claude Code, cloud agent)
+  | OAuth 2.1 bearer token (human) or service token (machine)
+  v
+POST /mcp  — SDK v2 createMcpHandler (2026-07-28 + legacy stateless)
+  |
+  1. Auth: Better Auth verifies token -> User (+ roles via rbacUserPlugin)
+  2. Authz: access.can({[integration]: [tier]}) using Mcp-Name header ->
+     integration/tool lookup; tools/list is filtered to the caller's grants;
+     a tool then re-checks with the resource it resolved ({context: {projectId}})
+     against the integration's RBAC scope
+  3. Write tools: elicitation confirmation (unless override + infra:writeUnconfirmed)
+  4. Dispatch: IntegrationAdapter (native handler | proxied MCP client)
+  5. Audit: InfraAuditLog record for every tools/call
+```
+
+### Integration adapter interface
+
+```typescript
+// infra-mcp/src/integrations/types.ts
+export interface InfraToolContext {
+  user: UserDocument;            // resolved caller (human or machine)
+  access: TerrenoAccess<InfraStatements>;
+  confirmWrite: (summary: string) => Promise<boolean>; // elicitation wrapper
+  logger: Logger;
+}
+
+export interface InfraTool {
+  name: string;                  // exposed as `${integration}_${name}`
+  tier: "read" | "write";       // maps to the RBAC action checked
+  description: string;
+  inputSchema: ZodType;          // zod 4 (SDK v2 Standard Schema requirement)
+  handler: (args: unknown, ctx: InfraToolContext) => Promise<ToolResult>;
+}
+
+export type IntegrationAdapter =
+  | {kind: "native"; name: string; tools: InfraTool[]}
+  | {
+      kind: "proxied";
+      name: string;
+      transport: {type: "stdio"; command: string[]} | {type: "http"; url: string; headers?: Record<string, string>};
+      // Deny-by-default: only listed upstream tools are exposed, and each
+      // MUST carry an explicit tier annotation.
+      allowedTools: Record<string, {tier: "read" | "write"; rename?: string}>;
+    };
+```
+
+Proxied adapters use `@modelcontextprotocol/client` (speaks both protocol eras; stateless — no per-upstream session). Stdio upstreams run as child processes inside the container.
+
+### RBAC statements
+
+```typescript
+// infra-mcp/src/access.ts — merged with terrenoStatements via createAccess
+export const infraStatements = {
+  ...terrenoStatements,
+  gcp: ["read", "write"],
+  sentry: ["read", "write"],
+  mongo: ["read", "write"],
+  expo: ["read", "write"],      // phase 3
+  vercel: ["read", "write"],    // phase 3
+  infra: ["viewAudit", "manageIntegrations", "writeUnconfirmed"],
+} as const;
+```
+
+- `read`/`write` are in the RBAC module's `READ_ACTIONS` semantics, so the shipped `auditor` role (read-only everywhere) works unmodified — that is the "log digging" role for free.
+- Default roles seeded on top of the RBAC defaults: `infra-readonly` (every integration `read`), `infra-operator` (`read` + `write`, still confirmed per call), `superadmin` from RBAC covers everything including `infra:writeUnconfirmed`.
+- Per-integration grants ("Sentry read only, no GCP") are just roles with narrower permission sets — no extra machinery.
+- Per-resource grants ("this agent's Vercel projects only") are RBAC `scopes`, passed to `createAccess`:
+
+  ```typescript
+  scopes: {
+    "vercel.read": {
+      check: async ({user, context}) =>
+        context?.projectId === undefined || isOperator(user) ||
+        (await projectsFor(user)).includes(context.projectId as string),
+    },
+  },
+  ```
+
+  `projectsFor` reads the machine user's allow-list (in our deployment, the project ids in the agent repo's environment). With no `projectId` in the context the call is a tier check only.
+
+### Write confirmation flow
+
+1. Tool handler for a `write`-tier tool calls `ctx.confirmWrite(summary)` before mutating.
+2. `confirmWrite` sends an MCP **elicitation** request to the client ("Confirm: roll back Cloud Run service X to revision Y? yes/no") and resolves with the user's answer. Decline → tool returns a cancelled result; audit records `rejected`.
+3. Override: `config.integrations[name].confirmWrites: false` (or global `confirmWrites`) skips the elicitation **only when** `access.can({infra: ["writeUnconfirmed"]})` passes for the caller. Without the permission, the config flag is ignored and the prompt still fires.
+4. Clients that do not support elicitation (some non-interactive agents): write tools **fail closed** with an instructive error unless the caller holds `infra:writeUnconfirmed` and the override is on.
+
+### Configuration
+
+Static config (code/env, validated at boot with zod):
+
+```typescript
+// consuming app / our deployment: infra.config.ts
+export default defineInfraMcp({
+  integrations: {
+    gcp: {enabled: true, projectId: env("GCP_PROJECT")},           // ADC — no key
+    sentry: {enabled: true, authToken: secret("SENTRY_MCP_TOKEN"), org: "flourish"},
+    mongo: {enabled: true, readUri: secret("MONGO_READ_URI"), writeUri: secret("MONGO_WRITE_URI")},
+    // Phase 3. One team token per team, keyed by slug; projects map to teams by lookup.
+    vercel: {enabled: true, teams: {nangio: secret("VERCEL_TEAM_NANGIO"), terrenolabs: secret("VERCEL_TEAM_TERRENOLABS")}},
+  },
+  confirmWrites: true, // global default; per-integration override allowed
+});
+```
+
+## Models
+
+All models live in `infra-mcp/src/types/models/` per convention; every field carries a `description`.
+
+### User
+
+`@terreno/api` user schema with `baseUserPlugin` + `rbacUserPlugin` (adds `roles: string[]`). Machine users (cloud agents) are ordinary users flagged `isServiceAccount: true`.
+
+### InfraAuditLog
+
+| Field | Type | Notes |
+|---|---|---|
+| `userId` | ObjectId ref User | caller (human or machine) |
+| `tool` | string | full exposed tool name |
+| `integration` | string | adapter name |
+| `tier` | "read" \| "write" | |
+| `args` | Mixed | redacted via per-tool redaction list before persist |
+| `status` | enum | `allowed`, `denied`, `confirmed`, `rejected`, `error` |
+| `error` | string? | |
+| `durationMs` | number | |
+| `created` | Date | plugin-managed |
+
+Indexed on `{userId, created}` and `{integration, created}`. Read surface gated by `infra:viewAudit`.
+
+### ServiceToken (only if Better Auth `apiKey` plugin is unsuitable)
+
+`name`, `hashedToken`, `userId`, `expiresAt?`, `lastUsedAt`, `created`. Verified in the same auth middleware path as bearer tokens.
+
+## APIs
+
+| Method | Path | Auth | Purpose |
+|---|---|---|---|
+| POST | `/mcp` | OAuth bearer / service token | MCP endpoint (2026-07-28 + legacy stateless) |
+| GET | `/.well-known/oauth-protected-resource` | — | RFC 9728 metadata (via `@better-auth/mcp`) |
+| * | `/oauth2/*`, `/api/auth/*` | — | Better Auth authorization server + login pages |
+| GET | `/health` | — | health check |
+| * | `/rbac/*` | RBAC perms | role CRUD/assignment (RBAC module's `rbacRouter`) |
+| * | `/admin/*` | `admin:access` | admin panel (`@terreno/admin-backend`): Users, InfraAuditLog (read-only), ServiceTokens |
+
+### Phase 1 tools (read tier)
+
+| Integration | Tools |
+|---|---|
+| gcp | `gcp_query_logs`, `gcp_list_log_names`, `gcp_query_metrics`, `gcp_list_error_groups`, `gcp_list_cloud_run_services`, `gcp_get_cloud_run_service` |
+| sentry | `sentry_search_issues`, `sentry_get_issue`, `sentry_list_issue_events`, `sentry_get_event` |
+| mongo | `mongo_list_collections`, `mongo_collection_schema`, `mongo_find`, `mongo_aggregate` (read-only stages; `$out`/`$merge` rejected; executed on the read-only connection) |
+
+GCP tools call the Cloud Logging/Monitoring/Error Reporting/Cloud Run Admin APIs via ADC. Sentry tools call the Sentry REST API. Mongo tools reuse the read-query/schema logic behind `mcp-server/src/local/tools/databaseQuery.ts`/`databaseSchema.ts` — extracted into a shared module both packages import rather than forked into infra-mcp — run against the configured read URI.
+
+### Phase 2 tools (write tier, all elicitation-confirmed)
+
+Initial minimal set: `sentry_resolve_issue`, `sentry_assign_issue`, `gcp_rollback_cloud_run_revision`, `gcp_update_cloud_run_traffic`, `mongo_update_one`, `mongo_delete_one` (write URI). Expansion is deliberate and per-PR.
+
+## Notifications
+
+None in v1. Future: optional Slack notifier (via `@terreno/api` notifiers) on write-tier tool execution.
+
+## UI
+
+No new frontend package. Admin surfaces reuse `@terreno/admin-backend` + `@terreno/admin-frontend`/`admin-spa`:
+
+- Users + role assignment (RBAC module's admin screens per its IP).
+- InfraAuditLog read-only table (`listFields`: created, user, tool, tier, status).
+- ServiceToken management (create shows the token once).
+
+## Phases
+
+### Phase 1 — Read-only core (the "log digging" MVP)
+
+- Package scaffold `infra-mcp/` (workspace, biome, tsconfig, bun test, catalog deps; zod 4 catalog entry).
+- SDK v2 `/mcp` endpoint (`createMcpHandler`, `legacy: "stateless"`, `toNodeHandler`) mounted on a TerrenoApp/Express server.
+- Better Auth OAuth 2.1 (`@better-auth/oauth-provider` + `@better-auth/mcp`): discovery, login, token verify middleware.
+- RBAC wiring: `infraStatements`, default roles, `access.can()` authz middleware keyed on `Mcp-Name`, filtered `tools/list`. **Gated on the RBAC PR.**
+- Native adapters: gcp (ADC), sentry, mongo — read tools above.
+- `InfraAuditLog` + audit middleware.
+- Terraform: clone `mcp_service` module (new service name, Artifact Registry, runtime SA with viewer/log IAM roles only for now).
+- Tests: authz matrix (role × tool), tool handlers against mocks/emulators, audit records.
+- **Deliverable:** a teammate signs in from Cursor/Claude Code, gets exactly the tools their role allows, digs logs across GCP/Sentry/Mongo.
+
+### Phase 2 — Write tier + machine callers
+
+- Elicitation `confirmWrite` wrapper; config override gated by `infra:writeUnconfirmed`; fail-closed for non-elicitation clients.
+- Initial write tools (list above); runtime SA IAM widened only for the specific write APIs.
+- Service tokens (Better Auth `apiKey` spike → fallback `ServiceToken` model); machine users with `infra-readonly` role.
+- Cloud agent migration: agents get `INFRA_MCP_URL` + service token instead of `GCP_SA_*`; update AGENTS.md/environment docs; retire the env-injected SA keys.
+- **Deliverable:** write actions work with per-call confirmation; cloud agents dig logs through the MCP with no raw GCP credentials.
+
+### Phase 3 — Proxied adapters + remaining vendors
+
+- `ProxiedAdapter` (MCP client, stdio + HTTP transports, allow-list with mandatory tier annotations, name prefixing).
+- First proxied integration: `@sentry/mcp-server` (stdio, static token) or `observability-mcp` — pick one as the reference implementation and keep the native tools as fallback.
+- Native Expo/EAS tools (`EXPO_TOKEN`: builds, updates, submissions status).
+- Native Vercel tools (team tokens, see Decisions): `vercel_list_projects`, `vercel_list_deployments`, `vercel_runtime_logs`.
+  - Runtime logs use `POST /v1/observability/events?teamId=<team>` with `event: "vercel.log"`, `scope: {ownerId, projectIds: [<project>]}`, a `timeRange`, `order: "desc"`, `limit` and an optional `cursor` (from `pagination.nextCursor`). This is the query `vercel logs` makes as of CLI 65.
+  - Optional filters (deployment, level, a free-form Vercel filter on `level`/`source`/`requestPath`/…) are ANDed into `filter`. The project goes in `scope`, never in the filter, so a filter can't widen the query (measured: a filter naming another project returns nothing).
+  - The older `GET /v1/projects/<p>/deployments/<d>/runtime-logs` stream isn't usable: it sent no headers within 60 s even with an account token.
+- Dogfooded first in our agent-session manager (hive) on `@terreno/api`'s MCP server, using the adapter interface above, with per-sandbox machine users and the `vercel.read` scope. It moves into this package when the package exists.
+- **Deliverable:** adding a vendor MCP is config + annotations, not code.
+
+### Phase 4 — OSS packaging
+
+- `defineInfraMcp` config reference docs, quickstart (one-man-shop path: tokens + deploy anywhere a container runs), website docs page.
+- Publish `@terreno/infra-mcp`; bootstrap/MCP-server docs updates; changelog + upgrade notes.
+- **Deliverable:** an external startup can deploy their own instance from docs alone.
+
+## Feature Flags & Migrations
+
+- **No data migrations** — all collections are new.
+- Rollout is additive: new package, new Cloud Run service. Nothing existing changes until Phase 2's cloud-agent credential switch, which is coordinated: keep `GCP_SA_*` injection until the MCP path is verified, then remove.
+- RBAC dependency: the RBAC module is Complete ([rbac-permissions.md](rbac-permissions.md)). Phase 1 wiring consumes `createAccess`, `rbacUserPlugin`, `rbacRouter`, default-role seeding.
+
+## Activity Log & User Updates
+
+`InfraAuditLog` records every `tools/call` (allowed, denied, confirmed, rejected, error) with user attribution — this is the compliance answer for server-held credentials, since vendor-side logs only show the service identity. RBAC role changes are covered by the RBAC module's `RbacAudit`.
+
+## Not Included / Future Work
+
+- Per-user vendor identity for the write tier (credential interface takes user context; add later).
+- Rate limiting / quotas per user or tier.
+- Slack notifications on write actions.
+- Proxying interactive-OAuth-only vendor MCPs (Vercel/Expo hosted) — revisit if they ship headless credentials.
+- Terraform-apply / IaC tools (high blast radius; needs its own design).
+- MCP Tasks extension for long-running operations (EAS builds) — Phase 3+ candidate.
+
+## Files to Create / Modify
+
+- `infra-mcp/` — new package: `src/index.ts` (server entry), `src/server.ts`, `src/access.ts`, `src/config.ts`, `src/auth.ts`, `src/audit.ts` + `src/models/infraAuditLog.ts`, `src/integrations/{types,registry,gcp/*,sentry/*,mongo/*,proxied}.ts`, `src/types/models/*`, tests.
+- `package.json` (root) — workspace entry, catalog: zod 4, `@modelcontextprotocol/server`, `@better-auth/oauth-provider`, `@better-auth/mcp`, Google API clients.
+- `terraform/main.tf`, `variables.tf`, `outputs.tf` — `infra_mcp_service` module instance + runtime SA IAM.
+- `.cursor/rules/infra-mcp/00-infra-mcp.mdc`, `AGENTS.md`/`CLAUDE.md` package lists, docs site page.
+- `ROADMAP.md` + `docs/explanation/roadmap-seed-issues.md` — roadmap entry and ready-to-paste tracking issue (done); `scripts/issueAreaLabels.ts` + bug-report package dropdown when the package lands.
+
+## Task List
+
+See [docs/tasks/infra-mcp.md](../tasks/infra-mcp.md).
+
+## Acceptance Criteria
+
+- [ ] An MCP client completes OAuth against the deployed server and lists only the tools the signed-in user's roles allow.
+- [ ] A user with only `auditor`/`infra-readonly` can query GCP logs, Sentry issues, and Mongo collections, and cannot see or call any write tool.
+- [ ] A write-tier tool call triggers an elicitation prompt; declining aborts with an audited `rejected` status.
+- [ ] With `confirmWrites: false` configured, confirmation is skipped **only** for callers holding `infra:writeUnconfirmed`; all others are still prompted.
+- [ ] Every tool call (including denials) produces an `InfraAuditLog` record with user attribution and redacted args.
+- [ ] The deployed service runs with only the Cloud Run default runtime SA — no SA key files or `GCP_SA_*` env vars anywhere in the stack.
+- [ ] A cloud agent authenticates with a service token and reads logs; the `GCP_SA_*` env vars are removed from agent environments.
+- [ ] A 2025-era MCP client (pre-2026 spec) connects successfully via the legacy stateless fallback.
+- [ ] `bun run lint`, package tests, and CI pass.