---
id: security-headers-rate-limit-sbom
title: Security headers + rate-limit primitive + SBOM in CI — Epic C of ADR-025
type: prd
status: approved
author: danijel
created: 2026-05-19T11:05:39Z
updated: 2026-05-19T11:09:21.438Z
---

## Problem

Three load-bearing security primitives the playbook §5, §6, §13 require are missing from the template:

- **Security headers** — no app in the template ships HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, or CSP by default. The playbook calls these "mandatory"; security scanners (securityheaders.com, Mozilla Observatory) flag the absence on first scan. Every consumer reinvents the middleware, and getting CSP right with nonces + Sentry replay + Tailwind inline styles is non-trivial enough that most consumers ship `'unsafe-inline'` and call it done.
- **Rate-limit primitive** — no template surface for "this endpoint is rate-limited." Auth use cases (signIn, signUp) ship without rate-limit declarations; credential-stuffing and account-enumeration windows stay open until a real consumer notices their auth logs. The playbook §5 says "all authentication endpoints rate-limited per IP and per account" — declaratively impossible today.
- **SBOM** — no Software Bill of Materials generated on release. Consumers pursuing SOC 2 / ISO 27001 / FedRAMP / EU CRA evidence have to invent SBOM tooling and bolt it into their release flow. Audit-prep tax compounds across every consumer.

ADR-025 settled the strategy: framework-agnostic header middleware in `core-shared/security`, rate-limit as fourth conformance channel in `core-shared/rate-limit`, SBOM via `cyclonedx-npm` in `release-please.yml`. This PRD is the implementation seed for Epic C.

## Goal

Ship the three hardening primitives so a downstream consumer gets compliant default headers, manifest-declared rate-limit gates, and per-release SBOM evidence without inventing any of them. Template apps (`web-next`, `web-tanstack`, `cms`) wire the middleware end-to-end; auth feature ships rate-limit as the canonical reference example; release-please attaches a CycloneDX SBOM to every tagged release.

## In scope

### Security headers middleware in `core-shared/security`

- New module `core-shared/security/` exporting framework-agnostic header builder:
  - `buildSecurityHeaders(opts: SecurityHeadersConfig): Record<string, string>` — returns header name → value map
  - `SecurityHeadersConfig` type: `{ mode: "production" | "development", nonce?: string, allowedConnectOrigins?, allowedImgOrigins?, allowedFontOrigins?, csp?: { reportUri?: string, reportOnly?: boolean } }`
  - `generateNonce(): string` — cryptographically random 16-byte base64-encoded
  - Six headers emitted: HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, Content-Security-Policy
- Per-framework adapter subpaths (matches `core-analytics/react` pattern):
  - `core-shared/security/next` — Next.js middleware function + `getNonce()` helper reading from `headers()`
  - `core-shared/security/tanstack` — TanStack Start server middleware analog + request-context nonce extractor
- CSP defaults by mode (auto-switched from `NODE_ENV`):
  - **Production** — strict CSP with per-request nonce: `default-src 'self'; script-src 'self' 'strict-dynamic' 'nonce-{NONCE}'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; connect-src 'self' {ALLOWED_ORIGINS}; frame-ancestors 'none'; form-action 'self'; base-uri 'self'; upgrade-insecure-requests;`
  - **Development** — permissive: `default-src 'self' 'unsafe-inline' 'unsafe-eval' ws: localhost:* 127.0.0.1:*;`
- App wiring across all three template apps:
  - `apps/web-next` — `middleware.ts` at app root invoking `core-shared/security/next`
  - `apps/web-tanstack` — `app.config.ts` server middleware
  - `apps/cms` — Payload `express` config middleware
- Sentry browser SDK nonce-aware init in `apps/web-next/instrumentation-client.ts` + `apps/web-tanstack` equivalent (reads `getNonce()` and threads it into `Sentry.init({ ... })` + replay/feedback integrations)

### Rate-limit primitive in `core-shared/rate-limit`

- Scaffolded inline in `core-shared` (small surface; doesn't justify a new optional core)
- `IRateLimit` interface — `consume(budgetName, key, weight?): Promise<RateLimitDecision>` + `reset(budgetName, key): Promise<void>` + `RateLimitDecision = { allowed, remaining, resetAt }`
- Three impls:
  - `NoopRateLimit` — always-allow default
  - `InMemoryRateLimit` — per-process Map-backed; dev/single-replica enforcement
  - `RecordingRateLimit` (lives in `core-testing`) — captures all calls for assertions
- `withRateLimit(rateLimit, factory)` wrapper attaching `RateLimited` brand at DI bind time
- `RateLimited` brand definition added to `core-shared/conformance/brands.ts`
- New per-use-case manifest field `rateLimit: RateLimitBudget[]` where `RateLimitBudget = { name: string, window: string, budget: number }`
- New ESLint rule `no-undeclared-rate-limit` (warn severity):
  - Warn on `rateLimit.consume("X", _)` literal `budgetName` not declared in manifest
  - Warn on declared budget never consumed
- `assertFeatureConformance` extended: require `RateLimited` brand when `rateLimit.length > 0`
- Brand composition order updated to innermost: `withSpan → withCapture → withAudit → withAnalytics → withConsent → withRateLimit → factory(deps)`
- `BindContext` gains `rateLimit?: IRateLimit` (defaults to `NoopRateLimit` when consumer doesn't wire one)
- `auth.signIn` backfilled as canonical reference example:
  - Manifest: `rateLimit: [{ name: "ip", window: "1m", budget: 5 }, { name: "account", window: "1h", budget: 10 }]`
  - Use case body: dual `consume("ip", ...)` + `consume("account", ...)` calls

### SBOM generation in CI

- Amendment to ADR-023 §10 (SBOM bullet) — adds the concrete workflow step
- Step added to `.github/workflows/release-please.yml`:
  - Runs only when release-please cuts a release (`steps.release.outputs.releases_created == 'true'`)
  - Invokes `pnpm dlx @cyclonedx/cyclonedx-npm` to generate `sbom-<tag>.cdx.json` covering the entire workspace via `pnpm-lock.yaml`
  - Attaches SBOM as a GitHub release asset via `softprops/action-gh-release` (Renovate-pinned SHA per ADR-023)

### Documentation

- `docs/guides/security-headers.md` — full cookbook (per-framework wiring, nonce threading for consumer-added inline scripts, CSP allowlist customization, Sentry nonce integration, securityheaders.com verification)
- `docs/guides/rate-limiting.md` — cookbook (manifest field, naming convention `<feature>:<scope>:<key>`, multi-budget patterns, dev/staging/prod backend wiring guidance)
- `docs/glossary.md` — entries for `RateLimited` brand, `IRateLimit`, `SecurityHeadersConfig`, `buildSecurityHeaders`, `SBOM` (CycloneDX terminology)
- `CLAUDE.md` + `conformance-quickref.md` — rule count bump (12 → 13) + new manifest field documentation
- `docs/decisions/adr-023-ci-security-and-supply-chain.md` — amendment subsection capturing the SBOM workflow step

## Out of scope

- **Compliance fill-in docs (incident runbook, password policy templates, etc.)** — Epic D
- **Vendor-specific rate-limit backend** (Redis/Upstash/Cloudflare adapters) — consumer wires via ADR-022 library evaluation
- **Tracking IPs for rate-limit keys via request context** — caller-provided keys per Q5 of grill; consumer threads request context into use case input or builds key from controller
- **Distributed/multi-replica InMemoryRateLimit semantics** — per-process Map is dev-only; documented as such
- **Per-PR SBOM generation** — SBOM is a release artifact, per-release only (Q8 of grill)
- **SBOM signing / attestation** — bare SBOM only; SLSA-style provenance attestation is a future PRD if a consumer asks
- **CSP report-uri endpoint scaffolding** — CSP supports `report-uri` / `report-to` for violation collection but the template doesn't ship a collector. Config exposes the option; consumer wires their own collector
- **Nonce-aware policy for consumer-added inline scripts** — template documents the contract (`getNonce()` helper available; consumer threads via `<Script nonce={...}>`) but doesn't enforce
- **CSP for the Storybook app** — Storybook's renderer needs `'unsafe-eval'` for some addons; out of scope
- **Frame-ancestors override for embeddable widgets** — default `'none'`; consumer overrides when they ship embeddable surfaces
- **HSTS preload list submission** — `preload` directive emitted but submission to hstspreload.org is consumer/legal action

## Constraints

- **ADR-025** — Epic C strategy settled there.
- **ADR-014** — Sentry browser SDK init must respect new nonce contract; can't break existing instrumentation flow.
- **ADR-017** — observability PII boundary stays untouched; CSP changes don't affect Sentry's PII scrubbing.
- **ADR-021** — release-please's workflow shape is canonical for the SBOM step.
- **ADR-022** — no new third-party runtime dependencies for security headers, rate-limit, or SBOM generation. `@cyclonedx/cyclonedx-npm` invoked via `pnpm dlx` (no install). Rate-limit reference impls (`NoopRateLimit`, `InMemoryRateLimit`) use no external libs.
- **ADR-023** — SBOM step is an amendment to §10; CI workflow changes follow the established SHA-pin pattern.
- **ADR-024** + Epic B `requiresConsent`\*\* — rate-limit wrapper composes innermost (after consent); the order is canonical and tested.
- **Generator-first** — `withRateLimit` wrapper, `RateLimited` brand, ESLint rule additions follow the established conformance scaffold pattern.
- **Manifest-first ordering** — manifest schema + types land first; ESLint rule second; wrapper third; backfill (`auth.signIn`) fourth; app wiring last.
- **`core-shared` boundary** — rate-limit + security live in `core-shared` (must-have, available to every consumer). No new optional cores.
- **Conventional Commits** — every slice = one green commit.

## Success criteria

- `pnpm dev` on any app emits all six security headers with mode=development CSP; browser dev tools show `Content-Security-Policy` and the other 5 headers on every response.
- `pnpm build && pnpm start` (production mode) on any app emits mode=production CSP with a unique nonce per request, and Sentry browser SDK initializes successfully (no CSP violations in browser console).
- `securityheaders.com` scan of a `pnpm start`-served app scores A or A+.
- `core-shared/security/next` exports a working Next.js middleware that integrates with the app's existing middleware chain (auth checks etc.).
- `core-shared/security/tanstack` exports a working TanStack Start adapter.
- `IRateLimit` interface has three working impls (Noop, InMemory, Recording) with passing tests.
- `auth.signIn` manifest declares `rateLimit: [{ name: "ip", ... }, { name: "account", ... }]`; use case body invokes both `consume` calls; binding fails `assertFeatureConformance` if `withRateLimit` is omitted.
- `no-undeclared-rate-limit` ESLint rule fires on `rateLimit.consume("foo", ...)` where `"foo"` is not declared in the manifest; passes on matching calls.
- A merged release-please PR cuts a tag AND the release-please workflow uploads a CycloneDX SBOM as a release asset; the asset opens in any CycloneDX viewer.
- `pnpm typecheck && pnpm lint && pnpm test && pnpm conformance && pnpm fallow:audit && pnpm coverage:diff && pnpm compliance:emit-all --check` all green at every commit boundary.
- `docs/guides/security-headers.md` + `docs/guides/rate-limiting.md` cover consumer wiring end-to-end including the Sentry nonce thread and the canonical key-naming convention.
- CLAUDE.md + `conformance-quickref.md` reflect 13 conformance ESLint rules.

## User stories

1. As a **downstream consumer**, I want six security headers shipped by default in all three template apps so a securityheaders.com scan immediately scores A/A+ without my writing middleware.
2. As a **downstream consumer running Next.js**, I want a per-request CSP nonce so I can use Next.js's `<Script>` component without falling back to `'unsafe-inline'`.
3. As a **downstream consumer running TanStack Start**, I want the same nonce contract as Next.js so my dual-framework deployment behaves consistently.
4. As a **downstream consumer**, I want CSP to auto-switch between strict (production) and permissive (development) so my dev tooling (HMR, inline-style libraries) keeps working without manual config.
5. As a **downstream consumer customizing CSP**, I want `allowedConnectOrigins` + `allowedImgOrigins` config so I can allowlist my Sentry DSN host, analytics backend, CDN, etc. without forking the builder.
6. As a **downstream consumer shipping auth**, I want `rateLimit: [{ name: "ip" }, { name: "account" }]` on signIn so credential stuffing fails fast at lint time if I forget to wire it.
7. As a **downstream consumer**, I want `IRateLimit` to support multiple named budgets per use case so I can express "5/min per IP AND 10/hour per account" without homegrown key concatenation.
8. As an **AI agent** modifying signIn's use case body, I want `no-undeclared-rate-limit` to fire when I call `rateLimit.consume("foo", ...)` without declaring `"foo"` in manifest, so rate-limit drift is caught at lint time.
9. As an **AI agent** scaffolding a new auth/write/export use case, I want manifest to default to `rateLimit: []` so I'm prompted to think about rate-limit during manifest-first ordering.
10. As a **downstream consumer running InMemoryRateLimit in dev**, I want predictable single-process enforcement so I can test 429 responses locally without spinning up Redis.
11. As an **SRE rolling out production**, I want a Redis-backed `IRateLimit` impl I can swap in via `BindContext.rateLimit` so my multi-replica deployment shares state.
12. As a **compliance officer pursuing SOC 2**, I want a CycloneDX SBOM attached to every GitHub release so my auditor can answer "what's in version X" without inventory inspection.
13. As a **downstream consumer running serverless**, I want SBOM generation to happen at release time only (not per-PR) so my CI minutes don't balloon.
14. As an **AI agent** sequencing the dispatch, I want Epic C stories independent of Epic A/B so I can interleave with the dependency-ordered chain.

## Implementation decisions

### Module surface

- **`@repo/core-shared` additions** (must-have package, no new optional core):
  - New module `core-shared/security/` containing:
    - `security-types.ts` — `SecurityHeadersConfig`, `CspMode`, `CspDirective` types
    - `build-security-headers.ts` — pure builder function
    - `nonce.ts` — `generateNonce()` cryptographic helper
    - `next/index.ts` — Next.js middleware adapter + `getNonce()` from `headers()`
    - `tanstack/index.ts` — TanStack Start adapter
  - New module `core-shared/rate-limit/` containing:
    - `rate-limit.interface.ts` — `IRateLimit`, `RateLimitBudget`, `RateLimitDecision` types
    - `noop-rate-limit.ts` + sibling test
    - `in-memory-rate-limit.ts` + sibling test
    - `with-rate-limit.ts` — wrapper attaching `RateLimited` brand
  - Extension to `core-shared/conformance/brands.ts`:
    - `RateLimited<F> = F & { readonly __rateLimited: true }` type
    - Helper `isRateLimited(fn): boolean`
  - Extension to `core-shared/conformance/wire-use-case.ts`:
    - Accept optional `rateLimit: IRateLimit` arg; compose `withRateLimit` innermost when manifest declares `rateLimit.length > 0`
  - Extension to `core-shared/conformance/assert-bindings.ts`:
    - Require `RateLimited` brand when `manifest.useCases[name].rateLimit.length > 0`
  - Extension to `core-shared/conformance/define-feature.ts`:
    - Type `UseCaseManifest.rateLimit?: RateLimitBudget[]`
  - Extension to `core-shared/di/bind-context.ts`:
    - `BindContext.rateLimit?: IRateLimit` (defaults to `NoopRateLimit` at app aggregator level)
- **`@repo/core-testing` additions**:
  - `recording-rate-limit.ts` — captures `consume` + `reset` invocations
- **`@repo/core-eslint` additions**:
  - New rule `no-undeclared-rate-limit.js` (warn severity)
  - `_manifest-ast.js` parser gains `rateLimit` field extraction
  - `plugin.js` + `base.js` register the rule at warn
- **`packages/auth/` modifications**:
  - `feature.manifest.ts` — add `rateLimit: [{ name: "ip", window: "1m", budget: 5 }, { name: "account", window: "1h", budget: 10 }]` to `signIn`
  - `application/use-cases/sign-in.use-case.ts` — body invokes both `rateLimit.consume` calls; deps signature gains `rateLimit: IRateLimit`
  - `di/bind-production.ts` + `bind-dev-seed.ts` — pass `ctx.rateLimit` (or `new NoopRateLimit()` fallback) into `wireUseCase` for signIn
- **`apps/web-next` modifications**:
  - `middleware.ts` — invokes `core-shared/security/next` middleware; chains with existing auth checks
  - `instrumentation-client.ts` — reads nonce via `getNonce()`, passes to `Sentry.init({ ..., transportOptions, integrations })`
  - `app/layout.tsx` — threads nonce into `<Script>` tags (Sentry, analytics, any inline scripts)
- **`apps/web-tanstack` modifications**:
  - `app.config.ts` — register server middleware from `core-shared/security/tanstack`
  - Equivalent client init file (`src/client.tsx` or framework convention) — nonce-aware Sentry init
- **`apps/cms` modifications**:
  - Payload config — wire Express middleware from `core-shared/security` (cms is server-side only; no nonce concern)
- **`.github/workflows/release-please.yml` modifications**:
  - Conditional SBOM generation step after release-creation
  - SBOM upload to GitHub release via `softprops/action-gh-release`
- **`docs/decisions/adr-023-ci-security-and-supply-chain.md`**:
  - Amendment subsection capturing the SBOM workflow step concrete shape
- **`docs/guides/`**:
  - New: `security-headers.md`
  - New: `rate-limiting.md`
- **`docs/glossary.md`**:
  - Entries: `IRateLimit`, `RateLimited` brand, `withRateLimit`, `SecurityHeadersConfig`, `buildSecurityHeaders`, `SBOM`, `nonce` (CSP context)
- **`CLAUDE.md` + `docs/guides/conformance-quickref.md`**:
  - Rule count bump: 12 → 13
  - New manifest field `rateLimit` documented in conformance table

### Type primitive contracts (inlined where decision-encoding tight)

```ts
// core-shared/security/security-types.ts
export type CspMode = "production" | "development";

export type SecurityHeadersConfig = {
  mode: CspMode;
  nonce?: string;
  allowedConnectOrigins?: string[];
  allowedImgOrigins?: string[];
  allowedFontOrigins?: string[];
  csp?: {
    reportUri?: string;
    reportOnly?: boolean;
  };
};

// core-shared/rate-limit/rate-limit.interface.ts
export type RateLimitBudget = {
  name: string;
  window: string; // ISO 8601 duration, e.g. "P1M" or shorthand "1m" / "1h"
  budget: number;
};

export type RateLimitDecision = {
  allowed: boolean;
  remaining: number;
  resetAt: Date;
};

export interface IRateLimit {
  consume(
    budgetName: string,
    key: string,
    weight?: number,
  ): Promise<RateLimitDecision>;
  reset(budgetName: string, key: string): Promise<void>;
}
```

```ts
// auth.signIn — canonical example
// feature.manifest.ts entry:
signIn: {
  mutates: false,
  audits: [],
  publishes: [],
  consumes: [],
  analyticsEvents: [],
  requiresConsent: ["essential"],
  rateLimit: [
    { name: "ip", window: "1m", budget: 5 },
    { name: "account", window: "1h", budget: 10 },
  ],
}

// use case body:
export const signInUseCase = (deps) => async (input) => {
  const ipDecision = await deps.rateLimit.consume("ip", `signIn:ip:${input.clientIp}`);
  if (!ipDecision.allowed) throw new TooManyRequestsError("ip");
  const accountDecision = await deps.rateLimit.consume("account", `signIn:account:${input.email}`);
  if (!accountDecision.allowed) throw new TooManyRequestsError("account");
  // ... rest of business logic
};
```

### CSP defaults

**Production CSP (template emits with nonce):**

```
default-src 'self';
script-src 'self' 'strict-dynamic' 'nonce-{NONCE}';
style-src 'self' 'unsafe-inline';
img-src 'self' data: https:;
font-src 'self';
connect-src 'self' {ALLOWED_CONNECT_ORIGINS};
frame-ancestors 'none';
form-action 'self';
base-uri 'self';
upgrade-insecure-requests;
```

`'strict-dynamic'` + nonce: nonce-tagged scripts can load further scripts dynamically without enumeration. Required for Sentry's lazy-loaded modules. `'unsafe-inline'` in `style-src` is a known compromise (Tailwind, CSS-in-JS, framework runtime inject inline styles); production CSP eliminates `'unsafe-inline'` for `script-src` (the actually-dangerous one).

**Development CSP:**

```
default-src 'self' 'unsafe-inline' 'unsafe-eval' ws: localhost:* 127.0.0.1:*;
```

Allows Next.js HMR (websocket), React Refresh (unsafe-eval), and inline scripts. Auto-emitted when `mode === "development"`.

### Sentry nonce integration

Per-framework integration:

- **Next.js** (`apps/web-next/instrumentation-client.ts`):
  ```ts
  const nonce = (await headers()).get("x-nonce") ?? undefined;
  Sentry.init({
    dsn: ...,
    integrations: [
      Sentry.replayIntegration({ ..., nonce }),
      Sentry.feedbackIntegration({ ..., nonce }),
    ],
  });
  ```
- **TanStack Start** — equivalent via request-context extraction
- **Layout / Document head** — `<Script nonce={nonce}>` for any inline scripts the app ships

The `getNonce()` helper exported from `core-shared/security/next` abstracts the framework-specific extraction (`headers().get("x-nonce")` in Next.js Server Components).

### Rate-limit wrapper composition

Composition order (innermost → outermost):

```
withSpan ⟶ withCapture ⟶ withAudit ⟶ withAnalytics ⟶ withConsent ⟶ withRateLimit ⟶ factory(deps)
```

Rate-limit innermost because:

- Rate-limit fires after every other gate (audit, span, capture). The body running rate-limit `consume` calls is the actual work; outer layers wrap the work, including the rate-limit check.
- Spans should include rate-limit decision latency for observability — if `withSpan` were inside `withRateLimit`, the span would miss the rate-limit decision.

### CI workflow amendment (ADR-023 §10)

`.github/workflows/release-please.yml` gains a step after the release-please action emits `releases_created`:

```yaml
- name: Generate SBOM
  if: ${{ steps.release.outputs.releases_created == 'true' }}
  run: pnpm dlx @cyclonedx/cyclonedx-npm --output-file sbom-${{ steps.release.outputs.tag_name }}.cdx.json --output-format json
- name: Upload SBOM to GitHub release
  if: ${{ steps.release.outputs.releases_created == 'true' }}
  uses: softprops/action-gh-release@<SHA>
  with:
    files: sbom-${{ steps.release.outputs.tag_name }}.cdx.json
    tag_name: ${{ steps.release.outputs.tag_name }}
```

`<SHA>` is Renovate-managed per ADR-023. `pnpm dlx` avoids adding cyclonedx-npm to the lockfile (it's a CI-only tool, not a runtime dep).

Per-package SBOMs aren't generated — release-please cuts multiple per-package tags simultaneously, but the root SBOM covers all workspace packages and is the canonical evidence per industry practice.

### Conformance impact

- ESLint rule count: 12 → 13 (`no-undeclared-rate-limit`)
- Manifest field: `rateLimit?: RateLimitBudget[]` (optional, defaults to `[]`)
- New brand: `RateLimited`
- Boot assertion: extended to require `RateLimited` brand when `rateLimit.length > 0`
- New manifest channel doesn't require a new optional core (`core-shared/rate-limit` is must-have)

## Testing decisions

- **`core-shared/security`**:
  - Unit tests on `buildSecurityHeaders`: returns expected header set per mode, nonce threaded into CSP when provided, optional config fields applied to CSP allowlists, dev vs prod CSP shape
  - Unit test on `generateNonce`: returns base64-encoded 16-byte strings, two calls return different values
  - Adapter tests for `core-shared/security/next`: middleware sets headers + injects nonce into response headers + makes nonce available to `getNonce()` helper
  - Adapter tests for `core-shared/security/tanstack`: equivalent
- **`core-shared/rate-limit`**:
  - `NoopRateLimit` test: `consume` always returns `{ allowed: true }`, `reset` is no-op
  - `InMemoryRateLimit` test: tracks per-bucket counts correctly, decrements on consume, resets at window boundary, resets to budget on explicit `reset` call, concurrent consumes are safe (single-threaded JS — straightforward)
  - `RecordingRateLimit` test: captures invocation arguments verbatim
  - `withRateLimit` wrapper test: `RateLimited` brand attached, factory invocation passthrough preserved, composes with other wrappers
- **`assertFeatureConformance` extension**:
  - Synthetic manifest fixture with `rateLimit: [{ name: "ip", ... }]` but no `withRateLimit` at bind: fails with `ConformanceError` naming the missing brand
- **`no-undeclared-rate-limit` ESLint rule**:
  - RuleTester fixtures parallel to `no-undeclared-audit.test.js`
  - Passes when call's `budgetName` matches declared
  - Fires on undeclared `budgetName`
  - Fires on declared-but-unused (warn)
  - No-op on non-use-case files
- **`auth.signIn` integration**:
  - Existing signIn test extended: with `RecordingRateLimit`, assert dual-consume captured; with `InMemoryRateLimit` set to budget 1, second call fails with `TooManyRequestsError`
- **App integration**:
  - `apps/web-next/middleware.test.ts` (or equivalent): assertion that all six headers present in response, CSP shape correct for `NODE_ENV=production` + `NODE_ENV=development`, nonce header present in response
  - Manual verification: `pnpm build && pnpm start`, hit `localhost:3000`, browser dev tools shows all headers + functioning Sentry replay (no CSP violations)
- **SBOM workflow**:
  - Verify locally: `pnpm dlx @cyclonedx/cyclonedx-npm --output-file sbom-test.cdx.json` succeeds and produces valid CycloneDX JSON
  - End-to-end verification: merge a release-please PR, confirm SBOM asset appears on the resulting GitHub release
- **Coverage**: all new modules join L0 vitest thresholds per their `coverage.bands`. L1 `pnpm coverage:diff` gates every slice.
- **Prior art to mirror**:
  - Wrapper + brand pattern: `core-shared/instrumentation/with-capture.{ts,test.ts}` + `core-shared/conformance/wire-use-case.{ts,test.ts}`
  - ESLint rule shape: `packages/core-eslint/rules/no-undeclared-audit.{js,test.js}`
  - Three-impl interface pattern: `core-shared/jobs/{job-queue.interface.ts, payload-job-queue.ts, in-memory-job-queue.ts}` + `core-testing/instrumentation/recording-job-queue.ts`
  - Per-framework adapter subpath: `core-analytics/react` from ADR-024 (ships React provider as subpath)

## Open questions

- **Q1: Should `InMemoryRateLimit` honor TTL via `setTimeout` or check-at-read for bucket expiry?** — Recommended: **check-at-read**. setTimeout floods the event loop with timers in busy apps. Check-at-read on every `consume` call evaluates `now() > resetAt` and resets if expired. Single test case: assert bucket resets after `window` elapses with synthetic clock injection.
- **Q2: Does `withRateLimit` short-circuit the use case body on `!allowed`, or does the body decide?** — Recommended: **body decides**. The wrapper attaches the brand only; the use case body calls `consume(...)` explicitly and decides whether to throw `TooManyRequestsError` or degrade gracefully. Mirrors the audit pattern (`auditLog.record` doesn't decide flow control).
- **Q3: Should the security headers builder validate that `allowedConnectOrigins` entries are well-formed URLs?** — Recommended: **yes, with `URL` constructor parse**. Throws `InvalidSecurityHeadersConfig` at app boot if an allowlisted origin is malformed. Catches typos early. Documented in `docs/guides/security-headers.md`.
- **Q4: For TanStack Start nonce: where does the app store/retrieve the nonce — request context, async-local-storage, or response header?** — Recommended: **request context via TanStack's existing mechanisms**. Use `useRouterState()` or context provider for client-side access; server middleware reads from `event.node.req.headers["x-nonce"]` after setting it. Document the framework-specific extraction in `docs/guides/security-headers.md`.
- **Q5: How does CSP interact with `apps/storybook`?** — Recommended: **out of Epic C scope** (called out in "Out of scope"). Storybook's renderer needs `'unsafe-eval'`; shipping strict CSP there breaks docs. Document the omission.

## Out of scope (deferred)

- **Compliance fill-in docs (incident runbook, password policy, etc.)** — Epic D
- **Redis-backed `IRateLimit` reference impl** — consumer wires via ADR-022 library evaluation (`@upstash/ratelimit` or similar would need a trace)
- **CSP report-uri collector endpoint** — consumer-side; could be added later
- **SBOM signing / SLSA attestation** — bare CycloneDX SBOM only; signed attestations are a future PRD
- **Per-PR SBOM generation** — release-only per Q8 of grill
- **`apps/storybook` CSP** — Storybook tooling requires `'unsafe-eval'`; explicit deferral
- **`IRateLimit` v2: token-bucket algorithm vs fixed-window** — InMemoryRateLimit uses fixed-window for simplicity; consumer's production backend likely uses token-bucket; documented as such
- **CSP nonce reuse strategy** — every request gets a fresh nonce; no reuse across requests. Don't optimize prematurely.
- **HSTS preload list submission** — `preload` directive emitted but hstspreload.org submission is consumer/legal action

## Further notes

- **Builds on**: ADR-014 (Sentry observability — nonce integration), ADR-017 (PII boundary — CSP shouldn't affect server-side scrubbing), ADR-021 (release-please — SBOM step extends), ADR-022 (library evaluation — no new traces needed), ADR-023 (CI security — SBOM amendment), ADR-024 (analytics — confirms wrapper composition order), ADR-025 (strategy umbrella).
- **Pairs with**: Epic A PRD (`compliance-manifests-pii-retention-subprocessors.prd.md` — no direct dependency but Epic C's `auth.signIn` rate-limit backfill follows Epic A's backfill pattern), Epic B PRD (`dsr-consent-and-cookie-banner.prd.md` — wrapper composition order extended consistently), Epic D PRD (`compliance-docs-scaffolds.prd.md` — references Epic C's middleware + rate-limit + SBOM in security checklist documents).
- **Sequencing within Epic C**: type primitives (`SecurityHeadersConfig`, `RateLimitBudget`, `IRateLimit`) → manifest schema + ESLint rule → wrapper + brand + `wireUseCase` extension → `auth.signIn` backfill → security headers builder + per-framework adapters → app integration (web-next middleware + Sentry nonce, web-tanstack same, cms middleware) → SBOM workflow step + ADR-023 amendment → docs.
- **Dispatch independence**: Epic C has no dependencies on Epic A's deliverables or Epic B's; the dispatch loop can interleave Epic C stories with Epic B's whenever an Epic B story is blocked.
- **Stakeholders**: template authors (most affected — adds manifest field + brand + ESLint rule + ADR-023 amendment), downstream consumers (positively affected — gain compliant headers + rate-limit + SBOM out of box), AI agents operating in feature code (positively affected — declarative rate-limit gates with lint-time enforcement), compliance officers (positively affected — SBOM evidence per release; audit-grade headers), SREs (positively affected — IRateLimit interface for production wiring).