diff --git a/CLAUDE.md b/CLAUDE.md index aa467c5..2f5863c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,7 +8,7 @@ pnpm dev # Start all dev servers pnpm build # Build all packages pnpm test # Run all tests pnpm typecheck # TypeScript across all packages -pnpm lint # ESLint (incl. 12 conformance/* rules) +pnpm lint # ESLint (incl. 13 conformance/* rules) pnpm conformance # Cross-feature event closure pnpm fallow # Whole-codebase: dead exports, dupes, complexity pnpm fallow:audit # AI-change audit (run before commits) @@ -62,7 +62,7 @@ Turborepo + pnpm monorepo organized by vertical features. Each feature (`auth`, ## Conformance system -Every feature has a `src/feature.manifest.ts` declaring its use cases, audits, publishes, consumes, required cores, and (when applicable) `requiresConsent: ConsentCategory[]` for features that gate behaviour behind user consent. Drift is caught at five latencies: +Every feature has a `src/feature.manifest.ts` declaring its use cases, audits, publishes, consumes, required cores, `rateLimit?: RateLimitBudget[]` (when applicable, for per-use-case rate-limit budgets), and (when applicable) `requiresConsent: ConsentCategory[]` for features that gate behaviour behind user consent. Drift is caught at five latencies: | Layer | Latency | Catches | | -------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- | @@ -72,7 +72,7 @@ Every feature has a `src/feature.manifest.ts` declaring its use cases, audits, p | **CI drift gate** (`pnpm conformance`) | ~120s | orphan event consumers across features | | **Fallow** (`pnpm fallow`) | ~30–60s | dead exports / unused files; duplicate code; circular deps; complexity hotspots; AI-change audit drift | -The twelve conformance ESLint rules: `feature-must-have-manifest` (error), `usecase-must-have-test-file` (error), `required-cores-installed` (error), `usecase-must-be-wired` (error), `no-undeclared-event-publish` (warn), `no-undeclared-audit` (warn), `no-undeclared-analytics-event` (warn), `pii-declaration-must-be-complete` (warn), `component-must-have-story` (warn), `component-must-have-test` (warn), `atomic-tier-import-direction` (warn), `no-undeclared-consent-check` (warn). Fallow runs as a fifth layer, post-ESLint, whole-codebase. +The thirteen conformance ESLint rules: `feature-must-have-manifest` (error), `usecase-must-have-test-file` (error), `required-cores-installed` (error), `usecase-must-be-wired` (error), `no-undeclared-event-publish` (warn), `no-undeclared-audit` (warn), `no-undeclared-analytics-event` (warn), `pii-declaration-must-be-complete` (warn), `component-must-have-story` (warn), `component-must-have-test` (warn), `atomic-tier-import-direction` (warn), `no-undeclared-consent-check` (warn), `no-undeclared-rate-limit` (warn). Fallow runs as a fifth layer, post-ESLint, whole-codebase. See `docs/architecture/agent-first-workflow-and-conformance.md` for the full design and `docs/guides/conformance-quickref.md` for the day-to-day reference. diff --git a/docs/glossary.md b/docs/glossary.md index 3218e9f..24ae32e 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -210,6 +210,10 @@ A commit-body trailer (`Release-As: 0.5.0`) that overrides release-please's auto **CHANGELOG.md**: A per-package, release-please-managed changelog (one at repo root for the template; one at `packages//CHANGELOG.md` for each feature). Do not edit manually — release-please regenerates from commit history. +**SBOM** (Software Bill of Materials): +A machine-readable inventory of all direct and transitive package dependencies attached as a JSON file to each GitHub release. Generated in CycloneDX JSON format via `@cyclonedx/cyclonedx-npm` in the `release-please.yml` CI workflow (runs only when a release is actually cut). Named `sbom-.cdx.json` and uploaded as a GitHub release asset. Enables downstream supply-chain scanning and NTIA minimum-elements compliance. Not committed to the repository. +_Avoid:_ confusing SBOM (a release asset produced by CI) with library traces (developer-authored, per-decision records in `docs/library-decisions/`). + ## Cross-feature mechanisms **Event bus** (`IEventBus`): @@ -283,6 +287,16 @@ _Avoid:_ applying `withConsent` in test files — tests inject mocks directly in **Rate-limit** (`core-shared/rate-limit`): Fourth conformance channel after audit/analytics/consent. `IRateLimit` interface (`consume`/`reset`) + `withRateLimit` wrapper + `RateLimited` brand + `rateLimit: { window, budget }` manifest field. Default budgets in manifest, runtime overrides via `ctx.rateLimit` config. Consumer wires Redis/Upstash impl. See ADR-025. +**`IRateLimit`**: +The vendor-neutral rate-limit interface in `@repo/core-shared/rate-limit/`. Two methods: `consume(budgetName, key, weight?)` → `RateLimitDecision` (fields: `allowed: boolean`, `remaining: number`, `resetAt: Date`) and `reset(budgetName, key)`. Two implementations: `InMemoryRateLimit` (dev/test) and a consumer-wired production backend (Redis/Upstash). Feature packages receive it via `ctx.rateLimit` at DI bind time; declared in the manifest's `rateLimit` field. + +**`RateLimited`**: +The phantom-type brand `RateLimited` attached by `withRateLimit(rateLimit, fn)` at DI bind time. Signals that the wrapped use case's declared `RateLimitBudget[]` entries will be enforced before execution. TypeScript rejects binding an unwrapped factory to a `RateLimited`-typed DI symbol when the manifest declares `rateLimit`. The boot assertion verifies the brand at runtime. +_Avoid:_ applying `withRateLimit` in test files — tests inject mocks directly and do not go through the DI wrappers. + +**`withRateLimit`**: +The wrapper composer that attaches the `RateLimited` brand at DI bind time. Signature: `withRateLimit(rateLimit: IRateLimit, fn)`. Part of the six-wrapper composition chain — see the combined `withSpan / withCapture / …` entry above. Outermost position is `withSpan`; `withRateLimit` sits between `withAnalytics` and the inner factory. + **PII inventory**: Personal-data declaration at the Payload field level via `custom.pii = { category, purpose, retention, exportable, restrictable }`. Generator emits `compliance/data-map.yml`. DSR cascade walks this at runtime. See ADR-025. @@ -307,6 +321,18 @@ The server-side scrubbing of email/passwords/tokens/cookies/auth/IPs at the OTel **Rule 0**: The `bindAll()` decision that selects OTel+Sentry instrumentation when a DSN env var is present, otherwise the Noop chain. Orthogonal to `USE_DEV_SEED` / `NODE_ENV` (those control repo bindings, not instrumentation). +## Security + +**`SecurityHeadersConfig`**: +The TypeScript type accepted by `buildSecurityHeaders()`. Fields: `mode` (`"prod"` | `"dev"`), optional `nonce` (per-request CSP nonce string), and optional allowlist arrays `allowedConnectOrigins`, `allowedImgOrigins`, `allowedFontOrigins` (absolute URLs). Lives at `@repo/core-shared/security`. + +**`buildSecurityHeaders()`**: +The pure function in `@repo/core-shared/security` that accepts a `SecurityHeadersConfig` and returns a `Record` of HTTP security headers: `Strict-Transport-Security`, `X-Frame-Options`, `X-Content-Type-Options`, `Referrer-Policy`, `Permissions-Policy`, and `Content-Security-Policy`. In `"prod"` mode the CSP uses `strict-dynamic` + nonce; in `"dev"` mode it relaxes to `unsafe-inline`/`unsafe-eval` to allow HMR tooling. + +**`nonce`** (CSP context): +A per-request cryptographically random token (typically 16+ bytes, base64-encoded) threaded into the `Content-Security-Policy` header's `script-src` directive as `'nonce-'`. Required when using `strict-dynamic` CSP to permit specific server-rendered inline `