@terreno/mcp 57.17.0 → 57.18.0

package/dist/docs/versioned/57.17.0/implementationPlans/framework-audit-log.md

@@ -0,0 +1,247 @@
+# Implementation Plan: Framework-level audit log
+
+**Status:** Complete — shipped in #1301  
+**Branch:** `cursor/framework-audit-log-grow-0d6c`  
+**Owner:** —  
+**Created:** 2026-09-10  
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1186 (implementation PRs use `Fixes #1186`)  
+**Task list:** [framework-audit-log.md](../tasks/framework-audit-log.md)  
+**Program:** [B2B platform](b2b-platform-program.md)  
+**Depends on:** — (soft: `organizationId` now; org-admin list filter waits on [org-management-ui](org-management-ui.md))  
+**RTK deprecation flag:** None — admin viewer uses generated OpenAPI / `useAdminApi`, not syncdb  
+
+## Goal
+
+Opt-in `AuditApp` in `@terreno/api` persists append-only `AuditEvent` rows for successful mutations: who changed which record, with changed-field before/after diffs. The existing admin Platform **Audit Log** lists them. Default retention is forever. This is the B2B compliance log; it generalizes example `AdminAuditLog` without replacing consent `ConsentResponse` rows.
+
+## Non-Goals
+
+- Waiting on `org-management-ui` to start (no `OrgsApp` in tree today).
+- Default-on `modelRouter` product CRUD.
+- Consent signing history (`ConsentResponse` + `GET /consents/audit/:userId` stay).
+- Login, failed auth, permission denials (except existing `RbacAudit` `denied: true` fanned through `auditSink`).
+- Sync mutate / outbox / socket writes (`@terreno/syncdb`). HTTP `modelRouter` only.
+- Admin hard-delete of events; SIEM export; legal hold.
+- Full-document snapshots.
+- Per-org-admin filtered lists (store `organizationId` now; filter when org context ships).
+
+## Decisions
+
+| ID | Question | Choice |
+| --- | --- | --- |
+| Q1 | Org dependency | Ship now. Optional `organizationId` from the mutated document or `req.organization` when present. |
+| Q2 | Default on | Off. `AuditApp` plugin + per-router `audit: true`. **AdminApp writes `AuditEvent` automatically when `AuditApp` is registered.** |
+| Q3 | Events | Successful create/update/delete and array mutations on audited routers; AdminApp → same collection; RBAC via existing `auditSink`; consent stays domain-specific. |
+| Q4 | Mutability / retention | HTTP list+read only. Create only via framework writers. No PATCH/DELETE. **Default retain forever.** Optional `retentionDays > 0` Mongo TTL. |
+| Q5 | Diffs | Changed fields only. Auto-redact `password`, `hash`, `salt`, `token`, `secret`, `refreshToken` (case-insensitive last path segment) plus per-router `redact`. Never log full request bodies. |
+
+**Recorded assumptions (not grilled):** No default-connection singleton (same as `RbacAudit`: `createAuditEventModel(connection)`). Example-backend **replaces** `AdminAuditLog` with `AuditEvent`. `onAdminAudit` remains an extra sink. Writes are best-effort (`logger.error`, mutation still succeeds). Persist is fire-and-forget on the request path. Optional Cloud Tasks enqueue (`GCP_TASKS_AUDIT_QUEUE` + `AUDIT_TASKS_URL`) writes Mongo on a worker via `POST /internal/audit-events`. `AuditEvent` is never audited. `audit: true` without `AuditApp` skips the write and logs an error once per process. Array mutations use `verb: "updated"` and `operation` `arrayPush` / `arrayUpdate` / `arrayRemove`. `organizationId` is stored as string. Admin list uses `Permissions.IsAdmin` until org RBAC lands.
+
+## Architecture
+
+```
+AuditApp({retentionDays?})
+  → createAuditEventModel(connection)
+  → set process recorder
+  → modelRouter("/audit-events", AuditEvent, {create/update/delete: [], list/read: IsAdmin})
+  → adminContribution() for Platform Audit Log
+
+modelRouter(..., {audit: true | {redact?: string[]}})
+  → after successful create/update/delete/array *
+  → recordAuditEvent({actorId, modelName, recordId, recordLabel?, organizationId?, verb, operation, before, after, source: "modelRouter"})
+
+AdminApp
+  → after successful admin CRUD, if recorder present
+  → recordAuditEvent({..., source: "admin"})
+  → then onAdminAudit? (unchanged extra sink)
+
+createAccess({auditSink: persistRbacAuditToAuditEvent})
+  → source: "rbac"; before/after from permissionDelta when present
+```
+
+`AuditApp` implements `TerrenoPlugin` (+ `adminContribution` like FeatureFlags). Importing `@terreno/api` does **not** register `AuditEvent` on `mongoose.connection`.
+
+### Config shape
+
+```typescript
+interface AuditAppOptions {
+  enqueue?: (write: AuditEventWrite) => Promise<void>;
+  processQueuePath?: string;
+  processQueueSecret?: string;
+  /** Mongo TTL in days. Omit or 0 = forever (no TTL index). */
+  retentionDays?: number;
+}
+
+interface ModelRouterAuditOptions {
+  redact?: string[]; // extra field names; merged with defaults
+}
+
+// modelRouter options:
+audit?: boolean | ModelRouterAuditOptions;
+```
+
+`audit: true` equals `{redact: []}`.
+
+### Writer contract
+
+```typescript
+interface AuditEventWrite {
+  actorId?: string;
+  after?: Record<string, unknown>;
+  before?: Record<string, unknown>;
+  modelName: string;
+  operation: "create" | "update" | "delete" | "arrayPush" | "arrayUpdate" | "arrayRemove";
+  organizationId?: string;
+  recordId?: string;
+  recordLabel?: string;
+  source: "admin" | "modelRouter" | "rbac";
+  verb: "created" | "deleted" | "updated";
+}
+```
+
+Diff helper: shallow (plus one-level nested objects) comparison of previous JSON vs next JSON after redaction. Unchanged keys omitted. Create: `before` omitted, `after` is redacted new fields. Delete: `after` omitted, `before` is redacted last state.
+
+`organizationId` resolution order: `req.organization?.id` / `_id`, else string of `doc.organizationId` when present.
+
+## Models
+
+`AuditEvent` (collection `auditevents`):
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `actorId` | ObjectId, ref User, indexed | Optional (system / missing user) |
+| `modelName` | string, required, indexed | |
+| `recordId` | string, indexed | |
+| `recordLabel` | string | Short label (admin list fields / `title` / `name` / `email`) |
+| `organizationId` | string, indexed | Optional |
+| `verb` | `created` \| `updated` \| `deleted`, indexed | Widget-compatible |
+| `operation` | string, required | Fine-grained verb |
+| `source` | `admin` \| `modelRouter` \| `rbac`, indexed | |
+| `before` / `after` | Mixed | Changed fields only, redacted |
+| `created` / `updated` | dates | `createdUpdatedPlugin`; no `isDeletedPlugin` (append-only) |
+
+Indexes: `{created: -1}`, `{modelName: 1, recordId: 1, created: -1}`. Optional TTL on `created` when `retentionDays > 0`. Every field has `description`. Five-type pattern co-located with the schema. `strict: "throw"`.
+
+HTTP: `create`/`update`/`delete` empty permission arrays. No public POST/PATCH/DELETE even for admins. Denied list/create (including non-admin GET list) returns **405**, matching `permissionMiddleware`; instance-level denials after a loaded document remain **403**.
+
+## APIs
+
+| Method | Path | Who | Behavior |
+| --- | --- | --- | --- |
+| GET | `/audit-events` | IsAdmin | Paginated list, default sort `-created`, `queryFields`: `modelName`, `recordId`, `actorId`, `verb`, `source`, `organizationId` |
+| GET | `/audit-events/:id` | IsAdmin | Read one |
+| POST/PATCH/DELETE | `/audit-events` | — | Disabled |
+
+Admin mounts the same model via `adminContribution` (or example registers it once — do **not** double-mount). Route path includes `audit-log` **or** model name `AuditEvent` so `AdminShell.isAuditLogModel` lifts it into Platform.
+
+RBAC helper `persistRbacAuditToAuditEvent(model)` returns an `RbacAuditSink`. Built-in `RbacAudit` collection unchanged.
+
+## Notifications
+
+None.
+
+## UI
+
+Reuse Platform Audit Log + `RecentActivityWidget`. Update `isAuditLogModel` to match `AuditEvent` (keep `AdminAuditLog` and `audit-log` path for leftover apps). List columns: `created`, `verb`, `modelName`, `recordLabel`, `actorId`. Detail form is read-only; show `before`/`after` as JSON (existing object field rendering is enough). No new custom screen.
+
+example-backend: register `AuditApp`, enable `audit: true` on `Todo`, drop `AdminAuditLog` model and `onAdminAudit` persistence (optional `onAdminAudit` may remain no-op or be removed). Point home `recentActivity` at `AuditEvent`. RBAC `auditSink` uses the helper. Scripts that count/wipe `AdminAuditLog` switch to `AuditEvent` (wipe only in test/dev scripts — production HTTP still cannot delete).
+
+## Docs in this slice
+
+| Page | Change |
+| --- | --- |
+| `docs/how-to/audit-log.md` | **New.** Enable `AuditApp`, per-router `audit`, AdminApp auto-write, redaction, TTL, append-only, org field. |
+| `docs/reference/api.md` | `AuditApp`, `audit` option, `persistRbacAuditToAuditEvent`, no default-connection model. |
+| `docs/explanation/admin-interface.md` | Platform Audit Log is `AuditEvent` when `AuditApp` is registered. |
+| `docs/reference/admin-backend.md` | `onAdminAudit` is extra; framework write when `AuditApp` present. |
+| `docs/explanation/roadmap-seed-issues.md` | IP + task URLs; soft org depend. |
+| `docs/implementationPlans/b2b-platform-program.md` | Row for this IP. |
+| `.rulesync/rules/api/00-api.mdc` | AuditApp + `audit` option. |
+| `CHANGELOG.md` | Added opt-in framework audit log. |
+
+## Testing
+
+Tracer: `TerrenoApp` + `AuditApp` + test model with `audit: true` → authenticated PATCH changes `title` → `GET /audit-events` as admin returns one row with `verb: "updated"`, `before.title` / `after.title`, no `password` if present.
+
+Cases:
+
+- Plugin omitted: `audit: true` does not throw on CRUD; no collection on default connection; error logged once.
+- Create/update/delete each write one event; actorId matches `req.user`.
+- Unchanged fields absent from `before`/`after`.
+- Default redact list strips secrets even if not in `redact`.
+- Per-router `redact: ["ssn"]` strips `ssn`.
+- Array push writes `operation: "arrayPush"`, `verb: "updated"`.
+- Admin POST writes `source: "admin"` without `onAdminAudit`.
+- `onAdminAudit` still fires when both configured; mutation 201 if either sink throws.
+- AuditEvent HTTP POST is 404/not registered; PATCH/DELETE disabled.
+- `organizationId` copied from document; from `req.organization` when set.
+- `retentionDays` omitted: no TTL index. `retentionDays: 1`: TTL index present (assert index spec; do not sleep a day).
+- Example RBAC role change fans into `AuditEvent` with `source: "rbac"`.
+- Existing `onAdminAudit` tests stay green (best-effort extra sink).
+- Admin frontend: `isAuditLogModel` true for `AuditEvent`; Recent Activity still skips when no audit model.
+
+Skills: `terreno-backend-api`, `mongoose-schema-safety`, `backend-test-env` (if tests touch env), `building-admin-interfaces`, `verify-ui-changes` (example `/admin` audit log after Todo/admin mutation), `update-docs`, `generate-sdk` if example OpenAPI admin SDK lists the new route.
+
+## Risks
+
+| Risk | Mitigation |
+| --- | --- |
+| Write volume / PII | Opt-in per router; redaction; append-only HTTP. |
+| Missing plugin | No-op + once-per-process error; docs. |
+| Example `AdminAuditLog` break | Replace in the same slice; shell still matches old name. |
+| TTL index change later | How-to: drop old TTL index when changing `retentionDays`. |
+| Sync bypass | Documented non-goal; follow-up IP. |
+| Org filter incomplete | Field stored; list filter is `org-management-ui`. |
+
+## Phases
+
+1. Tracer: model + `AuditApp` + `audit: true` create/update/delete + list/read API + redaction.
+2. Array mutations + `organizationId`.
+3. AdminApp auto-write + example migration + shell matcher + RBAC helper.
+4. Optional TTL.
+5. Docs, changelog, rulesync, seed, B2B table.
+
+## Feature Flags & Migrations
+
+No feature flag. New collection. example-backend drops `AdminAuditLog` (example-only; no published schema). Apps that copied `AdminAuditLog` keep it until they register `AuditApp`.
+
+## Activity Log & User Updates
+
+This IP **is** the activity log. No `UserUpdate` spam.
+
+## Not Included / Future Work
+
+- Org-admin scoped list (`org-management-ui`).
+- Sync-path audit.
+- Auth / login events.
+- SIEM export, legal hold, immutable object storage.
+- Custom diff UI beyond JSON fields.
+
+## Files to Create / Modify
+
+| File | Role |
+| --- | --- |
+| `api/src/audit/*` | Model, recorder, diff/redact, `AuditApp`, tests |
+| `api/src/api.ts` | `audit` option + post hooks |
+| `api/src/index.ts` | Exports |
+| `admin-backend/src/adminApp.ts` | Auto-write when recorder present |
+| `admin-frontend/src/AdminShell.tsx`, `AdminHome.tsx` | `isAuditLogModel` |
+| `example-backend/src/server.ts`, `access.ts`, models, scripts | `AuditApp`; drop `AdminAuditLog` |
+| Docs listed above | Same slice |
+
+## Task List
+
+[docs/tasks/framework-audit-log.md](../tasks/framework-audit-log.md)
+
+## Acceptance Criteria
+
+- [ ] `AuditApp` omitted: no `AuditEvent` on the default connection; product CRUD unchanged.
+- [ ] `audit: true` + `AuditApp`: create/update/delete persist one event with actor, model, record, changed-field diff, redacted secrets.
+- [ ] HTTP `/audit-events` is list+read for admin only; create/update/delete disabled.
+- [ ] Admin mutations write `AuditEvent` when the plugin is registered, without requiring `onAdminAudit`.
+- [ ] `onAdminAudit` still runs as an extra best-effort sink.
+- [ ] example-backend Platform Audit Log and Recent Activity read `AuditEvent`; `AdminAuditLog` removed.
+- [ ] RBAC `auditSink` helper writes `source: "rbac"` without dropping `RbacAudit`.
+- [ ] Default: no TTL. `retentionDays > 0` adds TTL on `created`.
+- [ ] How-to + api reference + admin explanation match the shipped design.
+- [ ] Merging the implementation PR closes https://github.com/TerrenoLabs/terreno/issues/1186 (`Fixes #1186`).

package/dist/docs/versioned/57.17.0/implementationPlans/gpt-chat-mascot.md

@@ -0,0 +1,41 @@
+# GPTChat optional mascot
+
+**Status:** Complete  
+**Roadmap:** Area=`ui`, Target=`Released`, Impact=`Feature`  
+**Branch:** `cursor/gpt-chat-mascot-d39f`  
+**Owner:** cloud agent  
+**Created:** 2026-09-15
+
+## Goal
+
+Let consuming apps brand the GPT screen with their own mascot. Terreno does not ship a default character.
+
+## Non-Goals
+
+- Bundling artwork, Lottie files, or a Terreno fox in `@terreno/ui`
+- Animating the mascot from `isStreaming` inside GPTChat (consumers wrap their own node)
+- Showing the mascot beside assistant bubbles
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Who owns the asset? | Consumer. `mascot?: React.ReactNode` |
+| When is it visible? | Only while `currentMessages.length === 0` |
+| Default? | Omitted — existing empty chat unchanged |
+
+## UI
+
+`GPTChat` empty-state hero: optional mascot slot, then existing suggested prompts.
+
+## Task List
+
+[docs/tasks/gpt-chat-mascot.md](../tasks/gpt-chat-mascot.md)
+
+## Acceptance Criteria
+
+- [ ] Omitting `mascot` leaves the empty chat unchanged
+- [ ] Passing `mascot` shows it on an empty chat, including with suggested prompts
+- [ ] Messages hide the mascot
+- [ ] Demo story and example app show a consumer node
+- [ ] Docs describe the optional slot

package/dist/docs/versioned/57.17.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/`.