hazo_secure 1.0.1 → 1.3.0

package/CHANGE_LOG.md

@@ -0,0 +1,182 @@
+# Change Log
+
+## 1.3.0 — 2026-06-12
+
+### New: `hazo_secure/secrets` — SecretsProvider
+
+- **`SecretsProvider` interface** with `get(name)` / `resolve(names[])` methods.
+- **`EnvSecretsProvider`** — reads from env vars (`${prefix}_${NAME}`; default prefix `HAZO_SECRET`).
+- **`StaticSecretsProvider`** — in-memory map; primary use is tests.
+- **`LookupSecretsProvider`** — caller-supplied `(name) => string|undefined` function.
+- **`SecretsError`** — extends `HazoError`, code `HAZO_SECURE_SECRET_NOT_FOUND` (httpStatus 400, retryable false).
+- New `./secrets` subpath export.
+
+## 1.1.0 — 2026-05-29
+
+### hazo workspace v2 — Wave 2 migration
+
+Additive workspace standardisation. Existing 1.0.x API surface unchanged:
+`SafeFetchError`, `CryptoError`, `CsrfError`, `GdprRegistryError` keep their
+constructors and `err.code` short discriminators; consumer `instanceof`
+checks continue to work.
+
+- **`hazo_core` required peer dep** (`^1.0.0`). All typed errors now extend
+  `HazoError` so they participate in `HazoError.is(err)` cross-package
+  checks and the standard envelope shape (httpStatus + retryable derived
+  per-code). Bare `throw new Error(...)` sites in
+  `src/ratelimit/store-connect.ts` replaced by `HazoConfigError` /
+  `HazoValidationError` with `HAZO_SECURE_RATELIMIT_*` codes.
+- **Logger** — new `src/utils/logger.ts` resolves to
+  `createLogger('hazo_secure')` from `hazo_core`. Root export adds
+  `get_logger`, `set_logger`, `noop_logger`. The legacy `NoopLogger`
+  alias is kept as a deprecated re-export.
+- **Correlation IDs** — `safeFetch` injects the workspace `x-request-id`
+  header on outbound calls when a context correlation ID is available
+  (caller-set headers always win).
+- **INI config** — new `config/hazo_secure_config.ini.sample` covers the
+  `[general]`, `[log.overrides]`, `[fetch]`, `[ratelimit]`, `[csrf]`
+  sections. Loader: `src/lib/config/hazo_secure_config.ts ::
+  getSecureConfig()`. Env-var overrides: `HAZO_SECURE_<SECTION>_<KEY>`.
+- **`db_setup_*.sql` filled out** — `hazo_rl_buckets` schema is now
+  inlined into both root setup files (idempotent, postgres ends with
+  `NOTIFY pgrst, 'reload schema';`). `migrations/001_hazo_rl_buckets.sql`
+  retained as the historical record.
+- **`design/feature_requests/INDEX.md`** added (S16).
+- **Optional-import discipline** — `ConnectRateLimitStore` now uses
+  `optional_import` from `hazo_core` to resolve `hazo_connect/server`
+  with a clear error envelope if the peer is missing.
+- **Dispatcher consistency** — `validateConnectIp` throws
+  `SafeFetchError("private_ip_blocked")` (instead of a bare `Error` with
+  `code: 'SSRF_PRIVATE_IP'`); the legacy `ssrfCode` field is attached
+  for tooling that grepped for it.
+- **package.json** — `engines` block removed (Node-version policy lives
+  in workspace docs). Canonical version pins for `@types/node`,
+  `tsup`. `hazo_core`, `hazo_logs`, `hazo_connect`, `hazo_jobs`,
+  `hazo_files`, `hazo_ui` declared as peer + devDep.
+
+## 1.0.1 — 2026-05-24
+
+### Test-app — expanded interactive scenarios
+
+No library API changes. All improvements are inside `test-app/`.
+
+- **Fetch page** — added 3 interactive scenario buttons: redirect chain (3 hops of 302 → 200), redirect-limit-exceeded (maxRedirects: 1 triggers error), and timeout (1 s against a 5 s endpoint). Fetch API route now absolutifies relative URLs and forwards optional `maxRedirects` / `timeoutMs` per-request.
+- **Crypto page** — added 3 new sections: key-rotation walkthrough (encrypt v1 → rotate to v2 → verify v1 still decrypts → encrypt v2), version-mismatch demo (tampers `keyId` → expects `key_not_found`), and HttpKeyProvider demo (encrypts via mock KMS at `/api/kms`, decrypts from cached key).
+- **GDPR page** — added dry-run export panel (calls `dryRunExport` — filenames only, no data) and live audit-log panel (registry wired with `auditIntent`; every export/anonymise/dry-run appends an entry; clear button resets).
+- **Token-bucket page (new)** — side-by-side `MemoryRateLimitStore` (fixed-window) vs `ConnectRateLimitStore` (token-bucket via in-memory `_svc`). "Fire 1" and "Burst × 8" buttons. Demonstrates partial recovery after wait.
+- **Mock KMS route (new)** — `GET /api/kms/[segment]` returns a stable per-process 32-byte key for `current` or the explicit key ID. Backed by `HttpKeyProvider` in the crypto route.
+- Routes: 13 → 17 (added `/api/fetch/redirect`, `/api/kms/[segment]`, `/api/token-bucket`, `/token-bucket`).
+
+## 1.0.0 — 2026-05-24
+
+First stable release. All four subpaths ship production-grade implementations. All changes are additive — existing 0.x APIs remain unchanged.
+
+### `/ratelimit` — ConnectRateLimitStore (token bucket via hazo_connect)
+
+- New `ConnectRateLimitStore` stores per-key token-bucket state in `hazo_rl_buckets` (PostgreSQL or SQLite). Requires `hazo_connect` optional peer. Token bucket smooths request flow — no 2× burst at window boundary unlike the fixed-window MemoryRateLimitStore.
+- `RateLimitStore.increment()` interface extended with optional `max?` param so stores can enforce capacity limits server-side.
+- Migration file: `migrations/001_hazo_rl_buckets.sql` (supports both PostgreSQL and SQLite).
+- `MemoryRateLimitStore` unchanged — no migration needed for projects already using it.
+
+### `/fetch` — undici dispatcher, connect-time IP validation, DNS rebinding fix
+
+- New `createSsrfDispatcher(policy)` returns an undici `Dispatcher` that validates the resolved IP at socket-creation time, closing the DNS rebinding gap present since 0.2.0 (where `fetch` could re-resolve between pre-flight check and connect).
+- `safeFetch()` now accepts an optional `dispatcher` param — pass the undici dispatcher for Node production use; omit for edge-compatible pre-flight-only mode.
+- New `validateConnectIp(ip)` exported — throws `SafeFetchError` if the IP is in a blocked CIDR range. Useful when rolling your own dispatcher or testing IP validation logic.
+- Undici added as a runtime dependency (`^7.3.0`).
+
+### `/crypto` — HttpKeyProvider (cloud-agnostic HTTPS key endpoint)
+
+- New `HttpKeyProvider({ endpoint, headers?, ttlMs? })` fetches the current encryption key from any HTTPS endpoint that returns `{ keyId, key: "<base64-32-bytes>" }`. Works with AWS Parameter Store, GCP Secret Manager, HashiCorp Vault, or any custom KMS HTTP façade.
+- In-process TTL cache (default 30 s) avoids per-encrypt latency. `provider.clearCache()` forces a re-fetch (useful in tests or on key rotation events).
+- `EnvKeyProvider` and `StaticKeyProvider` unchanged.
+
+### `/gdpr` — registry enhancements (validateRegistry, exportUser, anonymiseUser, dryRunExport, auditIntent)
+
+- `exportUser({ userId })` — async generator that streams `{ filename, content }` records from all registered exporters in sequence. Replaces ad-hoc iteration over `registry.exporters`.
+- `anonymiseUser({ userId })` — calls every registered anonymiser in sequence; rolls back (best-effort) on first failure.
+- `validateRegistry({ requiredDomains? })` — returns an array of `{ domain, issue }` objects for any domain that is missing an exporter, missing an anonymiser, or not present in `requiredDomains`. Returns `[]` if fully valid.
+- `dryRunExport({ userId })` — runs all exporters, collects every yielded file into memory, and returns `GdprFile[]` without writing anything. Useful in test suites.
+- `auditIntent` injection — `createGdprRegistry({ auditIntent })` accepts an async callback `(action, userId) => void`. Called before `exportUser`, `anonymiseUser`, and `dryRunExport` so every invocation is auditable.
+- New `GdprRegistryError` typed error class — throw/catch by `instanceof`. Discriminated by `code` (`missing_exporter`, `missing_anonymiser`, `export_failed`, `anonymise_failed`).
+
+### Test-app (new)
+
+- Six-page Next.js demo app in `test-app/` covering CSRF, rate limiting, SSRF/fetch, crypto, GDPR, and the registry validator. Sidebar layout with collapsible nav. Builds clean (13 routes).
+
+### Tests
+
+134 passing across 9 suites (was 103 in 0.5.0).
+
+## 0.5.0 — 2026-05-17
+
+New subpath implementation: **`hazo_secure/crypto`** — AES-256-GCM field-level encryption.
+
+`encryptField(plaintext, { keys, aad? })` produces an `EncryptedField` envelope: `{ v, keyId, iv, ct, tag, aad? }`. `decryptField(envelope, { keys, aad? })` round-trips it. Uses Node's `node:crypto`, 12-byte CSPRNG IV per encryption, 16-byte GCM auth tag. AAD is optional but recommended — bind it to `<table>:<entityId>:<field>` so envelopes can't be transplanted across rows or fields.
+
+Key providers:
+
+- `EnvKeyProvider(prefix)` — reads `${PREFIX}_CURRENT` for the current key id, then `${PREFIX}_<keyId>` (base64-encoded 32-byte AES-256 key) for each known id. Supports rotation: write under v2, leave v1 in env so historical rows still decrypt; bulk re-encrypt job can migrate later.
+- `StaticKeyProvider(currentKeyId, { keyId: key })` — for tests + ephemeral one-shot encryption. Don't ship to production.
+- Custom: implement the `KeyProvider` interface for KMS adapters (AWS KMS, GCP KMS, HashiCorp Vault).
+
+Helper `aadFor(table, entityId, field)` builds the canonical AAD shape.
+
+Errors: typed `CryptoError` with `code` discriminator (`unsupported_version`, `key_not_found`, `decrypt_failed`, `aad_mismatch`, `invalid_key`, `missing_env_key`, `no_keys_loaded`).
+
+17 new tests: round-trip + unicode + envelope shape + rotation + AAD binding + validation + EnvKeyProvider env-var handling. Total 103/103 across all subpaths.
+
+## 0.4.0 — 2026-05-16
+
+New subpath: **`hazo_secure/csrf`** — double-submit cookie pattern.
+
+- `issueCsrfToken(policy?)` — base64url-encoded random token (default 32 bytes)
+- `csrfCookieHeader(token, policy?)` — Set-Cookie value builder. `SameSite=Lax` default, `Secure` defaults to true in production, customisable name/domain/maxAge
+- `verifyCsrf(req, policy?)` — reads cookie + header, constant-time compare. Safe methods (GET/HEAD/OPTIONS) bypass automatically
+- `withCsrf(handler, opts?)` — Next.js wrapper. 403 with `X-CSRF-Reject-Reason` header by default, customisable via `onReject`. Auto-issues a fresh cookie on safe-method calls when none present (clients always have a token ready to echo)
+- 20 unit tests cover token issue, cookie header, all verify branches, wrapper, and overrides
+
+Design choices: NOT httpOnly (client needs to read it to echo); `SameSite=Lax` default (Strict breaks invite-link UX); constant-time compare via `timingSafeEqual` to defeat timing attacks; pure crypto + cookie work, zero dependencies. Intended for App Router API routes — Server Actions have their own origin check.
+
+## 0.3.1 — 2026-05-16
+
+`withRateLimit` typing: loosened handler constraint from `(req: Request, ...) => Promise<Response>` to `(...args: any[]) => Promise<Response>` so framework subclasses (`NextRequest`, etc.) typecheck cleanly. `args[0]` is asserted as `Request` internally — every framework's request type is structurally a Request, so this is safe in practice.
+
+## 0.3.0 — 2026-05-16
+
+`hazo_secure/ratelimit` — first implementation.
+
+- `createRateLimiter({ store?, windowMs, max, keyResolver?, now? })` returns `{ check(req), checkKey(key) }`
+- One-shot `checkRateLimit(req, opts)` helper for simple cases
+- `withRateLimit(handler, opts)` wraps any `(req, ...rest) => Promise<Response>` — returns 429 with `Retry-After` + `X-RateLimit-*` headers when blocked; adds the headers on success too
+- Default `MemoryRateLimitStore` — fixed-window counter, in-memory `Map`, lazy expiry on read + periodic background sweep (unref'd timer so it doesn't keep the event loop alive)
+- `RateLimitStore` interface for Redis/etc. swap-in
+- Default key resolver checks `x-forwarded-for` → `x-real-ip` → `cf-connecting-ip` → `"unknown"`
+- Custom 429 response via `onLimit` override
+- 19 unit tests cover store, limiter, resolver, and wrapper paths
+
+Known limitation: fixed-window can permit 2× burst at the window boundary. Acceptable for spam-defense and brute-force throttling, which is the current target. Sliding-window or token-bucket strategies can be added as alternative stores without API change.
+
+## 0.2.0 — 2026-05-16
+
+`hazo_secure/fetch` — first real implementation.
+
+- `safeFetch(url, { policy, deps? })` — SSRF-safe wrapper over native `fetch`
+- Policy supports: `allowedHosts`, `allowedHostPatterns`, `blockPrivateIps` (default on), `maxRedirects` (default 3), `timeoutMs` (default 10s), `allowedProtocols` (default `http:`/`https:`)
+- DNS pre-flight blocks: IPv4 RFC1918, loopback, link-local incl. 169.254.169.254 cloud metadata, CGNAT, multicast, reserved; IPv6 loopback, link-local, ULA, IPv4-mapped equivalents
+- Manual redirect following with per-hop revalidation + loop detection
+- Per-request timeout via AbortController, propagates external `signal`
+- 47 unit tests cover CIDR matching and the full SSRF gate matrix
+
+DNS rebinding caveat: the resolved-IP check happens before connect, but native `fetch` re-resolves at connect time. Upgrade path (production-grade): undici Agent with custom `connect` that validates at socket-create time. Acceptable for current consumers (server-to-server with trusted DNS infra); revisit when consumers face hostile networks.
+
+## 0.1.0 — 2026-05-16
+
+Initial scaffold.
+
+- `package.json` with subpath exports for `/fetch`, `/ratelimit`, `/crypto`, `/gdpr`
+- `tsup` build config covering all five entry points
+- Stub modules + public interfaces in place; implementations land in 0.2.x
+- `hazo_logs` as required peer; `hazo_jobs` and `hazo_files` as optional peers (gdpr only)
+
+Why now: §21 of the Kinstripe master plan (Security & Compliance) needed reusable primitives instead of inline code. Pulled CSRF into hazo_auth, kept fetch/ratelimit/crypto/gdpr together under one umbrella because they share a single audience: any project handling PII or untrusted input.

package/README.md

@@ -1,6 +1,6 @@
 # hazo_secure
 
-Security & compliance primitives for Node.js / Next.js apps. Four independent subpath modules — import only the ones you need.
+Security & compliance primitives for Node.js / Next.js apps. Seven independent subpath modules — import only the ones you need.
 
 | Subpath | Purpose |
 |---|---|
@@ -9,6 +9,8 @@ Security & compliance primitives for Node.js / Next.js apps. Four independent su
 | `hazo_secure/crypto` | AES-256-GCM field-level encryption with key versioning and AAD support |
 | `hazo_secure/gdpr` | Exporter / anonymiser registry + lifecycle orchestrator. Uses `hazo_jobs` for async export, `hazo_files` for ZIP delivery |
 | `hazo_secure/csrf` | Double-submit CSRF protection for Next.js routes — token generation, cookie header, constant-time verification |
+| `hazo_secure/mask` | PII masking and anonymization transforms (redact, hash, tokenize, fake_name, jitter_date, …) |
+| `hazo_secure/secrets` | Provider-pattern secret resolution — env vars, static map, or custom lookup |
 
 ## Install
 
@@ -16,7 +18,7 @@ Security & compliance primitives for Node.js / Next.js apps. Four independent su
 npm install hazo_secure
 ```
 
-`hazo_logs` is a required peer dep. `hazo_connect`, `hazo_jobs`, and `hazo_files` are optional peers — `hazo_connect` is needed for `ConnectRateLimitStore`; `hazo_jobs` and `hazo_files` are only needed for `hazo_secure/gdpr`.
+`hazo_core` is a required peer dep. `hazo_logs`, `hazo_connect`, `hazo_jobs`, `hazo_files`, and `hazo_ui` are optional peers — `hazo_connect` is needed for `ConnectRateLimitStore`; `hazo_jobs` and `hazo_files` are only needed for `hazo_secure/gdpr`.
 
 ## Quick start
 
@@ -56,6 +58,24 @@ const stored = await encryptField(plaintext, { keys, aad: `user:${userId}` });
 const recovered = await decryptField(stored, { keys });
 ```
 
+### Resolve application secrets
+
+```ts
+import { EnvSecretsProvider, StaticSecretsProvider, LookupSecretsProvider } from "hazo_secure/secrets";
+
+// Reads from env vars: HAZO_SECRET_DB_PASSWORD, HAZO_SECRET_STRIPE_KEY, …
+const secrets = new EnvSecretsProvider();
+const { db_password, stripe_key } = await secrets.resolve(["db_password", "stripe_key"]);
+
+// Tests — in-memory map
+const mock = new StaticSecretsProvider({ api_key: "test-key" });
+
+// Custom backend (KMS, HashiCorp Vault, etc.)
+const vault = new LookupSecretsProvider(async (name) => fetchFromVault(name));
+```
+
+`SecretsError` (code `HAZO_SECURE_SECRET_NOT_FOUND`) is thrown when a name can't be resolved. Use a custom prefix: `new EnvSecretsProvider("MY_APP")` → reads `MY_APP_<NAME>`.
+
 ### Register GDPR exporters
 
 ```ts
@@ -152,6 +172,8 @@ await gdpr.anonymiseUser({ userId });
 | `hazo_secure/fetch` | ⚠️ pre-flight only | ✅ full protection | Edge: host/IP checks only; Node: + undici connect-time validation |
 | `hazo_secure/crypto` | ❌ | ✅ | Uses `node:crypto` |
 | `hazo_secure/gdpr` | ❌ | ✅ | Async iterables + optional hazo_connect |
+| `hazo_secure/mask` | ✅ | ✅ | Pure transforms — no I/O |
+| `hazo_secure/secrets` | ✅ | ✅ | Pure async — no Node built-ins |
 
 **Node.js ≥ 18 required** for all Node-only subpaths.
 

package/SETUP_CHECKLIST.md

@@ -0,0 +1,85 @@
+# Setup Checklist
+
+For a consuming app (e.g. Kinstripe) pulling in `hazo_secure`.
+
+## Install
+
+```bash
+npm install hazo_secure
+```
+
+Add `hazo_logs` if not already present:
+
+```bash
+npm install hazo_logs
+```
+
+## Per-subpath setup
+
+### `hazo_secure/fetch`
+
+No setup. Construct a `SafeFetchPolicy` at each callsite and pass via the `policy` option.
+
+### `hazo_secure/ratelimit`
+
+Default in-memory store works out of the box. For multi-instance deployments, supply a Redis-backed `RateLimitStore` implementation.
+
+### `hazo_secure/crypto`
+
+1. Provision a 32-byte master key — store base64-encoded in env (`HAZO_SECURE_CRYPTO_KEY` or app-specific name)
+2. Choose a `KeyProvider` implementation:
+   - **`EnvKeyProvider(prefix)`** — reads from env vars; supports rotation by leaving old key ids in env
+   - **`HttpKeyProvider({ endpoint, headers?, ttlMs? })`** — fetches from any HTTPS endpoint returning `{ keyId, key: "<base64>" }` (AWS Parameter Store, GCP Secret Manager, HashiCorp Vault, or a custom facade); caches in-process for `ttlMs` (default 30 s)
+   - **`StaticKeyProvider`** — for tests only; do not ship to production
+   - **Custom** — implement the `KeyProvider` interface directly
+3. Decide AAD scheme — usually `domain:entityId` (e.g. `health:${personId}`)
+
+### `hazo_secure/secrets`
+
+No setup. Choose a provider at startup:
+
+- **`EnvSecretsProvider(prefix?)`** — reads from `${prefix}_${NAME}` env vars (default prefix: `HAZO_SECRET`). Set each secret as an env var on your deployment platform.
+- **`StaticSecretsProvider(map)`** — in-memory; use in tests only.
+- **`LookupSecretsProvider(fn)`** — caller-supplied sync or async lookup; useful for KMS / Vault integrations.
+
+```ts
+import { EnvSecretsProvider } from "hazo_secure/secrets";
+const secrets = new EnvSecretsProvider();
+const value = await secrets.get("db_password"); // reads HAZO_SECRET_DB_PASSWORD
+```
+
+### `hazo_secure/gdpr`
+
+1. Install optional peers if you'll use async export and ZIP delivery:
+
+   ```bash
+   npm install hazo_jobs hazo_files
+   ```
+
+2. Create the registry on app boot:
+
+   ```ts
+   const gdpr = createGdprRegistry();
+   ```
+
+3. Register per-domain exporters and anonymisers in feature modules
+4. Wire `/api/me/export` and `/api/me/delete` route handlers (project-specific)
+
+## Verifying
+
+```bash
+# Fetch — expect: SafeFetchError, safeFetch, createSecureDispatcher, validateConnectIp
+node --input-type=module -e "import * as m from 'hazo_secure/fetch'; console.log(Object.keys(m).join(', '))"
+
+# Ratelimit — expect: MemoryRateLimitStore, ConnectRateLimitStore, withRateLimit, checkRateLimit, createRateLimiter
+node --input-type=module -e "import * as m from 'hazo_secure/ratelimit'; console.log(Object.keys(m).join(', '))"
+
+# Crypto — expect: encryptField, decryptField, CryptoError, EnvKeyProvider, StaticKeyProvider, HttpKeyProvider
+node --input-type=module -e "import * as m from 'hazo_secure/crypto'; console.log(Object.keys(m).join(', '))"
+
+# GDPR — expect: createGdprRegistry, GdprRegistryError
+node --input-type=module -e "import * as m from 'hazo_secure/gdpr'; console.log(Object.keys(m).join(', '))"
+
+# Secrets — expect: SecretsError, SecretsProvider (type), EnvSecretsProvider, StaticSecretsProvider, LookupSecretsProvider
+node --input-type=module -e "import * as m from 'hazo_secure/secrets'; console.log(Object.keys(m).join(', '))"
+```

package/config/hazo_secure_config.ini.sample

@@ -0,0 +1,71 @@
+; hazo_secure configuration
+;
+; Copy to `hazo_secure_config.ini` and customise. Loaded by getSecureConfig()
+; on first access. INI is the workspace standard; only the [general] and
+; [log.overrides] sections are universal — the rest are package-specific
+; defaults the subpath modules can read.
+;
+; Per hazo workspace standard S7, every value can be overridden via env vars:
+;   HAZO_SECURE_<SECTION>_<KEY>=value
+; e.g. HAZO_SECURE_FETCH_TIMEOUT_MS=15000
+;
+; Per D-019, a per-environment overlay file at
+;   config/hazo_secure_config.<HAZO_ENV>.ini
+; is layered on top of this base file when HAZO_ENV is set.
+
+; ============================================================================
+; [general] - Workspace-standard general configuration
+; ============================================================================
+[general]
+
+; Deployment environment label. Falls back to NODE_ENV, then 'development'.
+; env = production
+
+; ============================================================================
+; [log.overrides] - Per-namespace log level overrides (workspace standard)
+; Format: <namespace> = trace|debug|info|warn|error
+; ============================================================================
+[log.overrides]
+
+; hazo_secure = info
+; hazo_secure/fetch = warn
+; hazo_secure/ratelimit = warn
+; hazo_secure/crypto = info
+; hazo_secure/csrf = warn
+
+; ============================================================================
+; [fetch] - SSRF-safe fetch defaults applied when callers omit them
+; ============================================================================
+[fetch]
+
+; Default request timeout in milliseconds (matches DEFAULT_TIMEOUT_MS).
+; timeout_ms = 10000
+
+; Maximum redirect hops to follow (matches DEFAULT_MAX_REDIRECTS).
+; max_redirects = 3
+
+; Whether to block private/reserved IPs by default. Leave true unless your
+; consumer explicitly needs intranet access.
+; block_private_ips = true
+
+; ============================================================================
+; [ratelimit] - Rate-limiting defaults
+; ============================================================================
+[ratelimit]
+
+; Default sweep interval for MemoryRateLimitStore (ms). 0 disables.
+; memory_sweep_interval_ms = 60000
+
+; ============================================================================
+; [csrf] - Double-submit cookie defaults
+; ============================================================================
+[csrf]
+
+; Cookie name written by `csrfCookieHeader()` and read by `verifyCsrf()`.
+; cookie_name = hs_csrf
+
+; Header name the client echoes the token back through.
+; header_name = x-csrf-token
+
+; Token byte length (final base64url string is longer).
+; token_length = 32

package/db_setup_postgres.sql

@@ -0,0 +1,20 @@
+-- hazo_secure PostgreSQL setup (idempotent)
+--
+-- One table is owned by this package:
+--   hazo_rl_buckets — token-bucket state for `ConnectRateLimitStore`
+--                     (subpath `hazo_secure/ratelimit`)
+--
+-- All other subpaths (/fetch, /crypto, /csrf, /gdpr) are stateless; the GDPR
+-- registry hands persistence off to consumer-supplied exporters/anonymisers.
+--
+-- Re-run safe — uses IF NOT EXISTS throughout.
+
+CREATE TABLE IF NOT EXISTS hazo_rl_buckets (
+  id                  TEXT NOT NULL PRIMARY KEY,
+  tokens              DOUBLE PRECISION NOT NULL,
+  last_refill_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  max_tokens          DOUBLE PRECISION NOT NULL,
+  refill_rate_per_ms  DOUBLE PRECISION NOT NULL
+);
+
+NOTIFY pgrst, 'reload schema';

package/db_setup_sqlite.sql

@@ -0,0 +1,18 @@
+-- hazo_secure SQLite setup (idempotent)
+--
+-- One table is owned by this package:
+--   hazo_rl_buckets — token-bucket state for `ConnectRateLimitStore`
+--                     (subpath `hazo_secure/ratelimit`)
+--
+-- All other subpaths (/fetch, /crypto, /csrf, /gdpr) are stateless; the GDPR
+-- registry hands persistence off to consumer-supplied exporters/anonymisers.
+--
+-- Re-run safe — uses IF NOT EXISTS throughout.
+
+CREATE TABLE IF NOT EXISTS hazo_rl_buckets (
+  id                  TEXT NOT NULL PRIMARY KEY,
+  tokens              REAL NOT NULL,
+  last_refill_at      TEXT NOT NULL DEFAULT (datetime('now')),
+  max_tokens          REAL NOT NULL,
+  refill_rate_per_ms  REAL NOT NULL
+);

package/dist/crypto/index.d.ts

@@ -1,3 +1,5 @@
+import { HazoError } from 'hazo_core';
+
 interface HttpKeyProviderOptions {
     /**
      * Base HTTPS endpoint for key material.
@@ -69,9 +71,16 @@ interface EncryptedField {
     tag: string;
     aad?: string;
 }
-declare class CryptoError extends Error {
-    readonly code: "unsupported_version" | "key_not_found" | "decrypt_failed" | "aad_mismatch" | "invalid_key" | "missing_env_key" | "no_keys_loaded";
-    constructor(message: string, code: "unsupported_version" | "key_not_found" | "decrypt_failed" | "aad_mismatch" | "invalid_key" | "missing_env_key" | "no_keys_loaded");
+type CryptoErrorCode = "unsupported_version" | "key_not_found" | "decrypt_failed" | "aad_mismatch" | "invalid_key" | "missing_env_key" | "no_keys_loaded";
+/**
+ * Typed error raised by `/crypto`. Extends `HazoError` so it participates in
+ * the workspace's correlation-ID auto-attach + envelope shape, while
+ * preserving the legacy `(message, code)` constructor + `err.code` short
+ * discriminator that 1.0.x consumers already check.
+ */
+declare class CryptoError extends HazoError {
+    readonly code: CryptoErrorCode;
+    constructor(message: string, code: CryptoErrorCode);
 }
 /**
  * Encrypt a UTF-8 string under the current key.
@@ -131,8 +140,41 @@ declare class StaticKeyProvider implements KeyProvider {
     }>;
     byId(keyId: string): Promise<Uint8Array>;
 }
+/**
+ * Lookup-function-backed `KeyProvider` for config-file (INI) key sources.
+ * Reads keys from a caller-supplied synchronous lookup function, decoding
+ * each value from base64 to a 32-byte AES-256 key.
+ *
+ * Expected key naming convention (mirrors hazo_config INI layout):
+ *   `current`      → the current key id (e.g. `"v1"`)
+ *   `key_<id>`     → base64-encoded 32-byte key (e.g. `key_v1=<base64>`)
+ *
+ * Example backed by hazo_config:
+ *   ```ts
+ *   const cfg = getConfig('crypto.myapp');  // hazo_config, not imported here
+ *   const keys = new LookupKeyProvider(name => cfg.get(name));
+ *   ```
+ *
+ * hazo_secure takes no dependency on hazo_config — the caller supplies the
+ * lookup, keeping this library config-agnostic. `Buffer.from(value, 'base64')`
+ * handles standard base64; keys decoded to anything other than 32 bytes are
+ * rejected with `invalid_key`.
+ *
+ * Decoded keys are memoised per id so the lookup runs once per key per
+ * process lifetime.
+ */
+declare class LookupKeyProvider implements KeyProvider {
+    private readonly lookup;
+    private readonly cache;
+    constructor(lookup: (name: string) => string | undefined);
+    current(): Promise<{
+        keyId: string;
+        key: Uint8Array;
+    }>;
+    byId(keyId: string): Promise<Uint8Array>;
+}
 /** Helper: build a `aad` string with a stable, parser-friendly shape.
  *  Convention: `<table>:<entityId>:<field>` — collision-free across tables. */
 declare function aadFor(table: string, entityId: string, field: string): string;
 
-export { CryptoError, type EncryptedField, EnvKeyProvider, HttpKeyProvider, type HttpKeyProviderOptions, type KeyProvider, StaticKeyProvider, aadFor, decryptField, encryptField };
+export { CryptoError, type CryptoErrorCode, type EncryptedField, EnvKeyProvider, HttpKeyProvider, type HttpKeyProviderOptions, type KeyProvider, LookupKeyProvider, StaticKeyProvider, aadFor, decryptField, encryptField };

package/dist/crypto/index.js

@@ -1,5 +1,6 @@
 // src/crypto/index.ts
 import { createCipheriv, createDecipheriv, randomBytes } from "crypto";
+import { HazoError } from "hazo_core";
 
 // src/crypto/provider-http.ts
 var KEY_LEN = 32;
@@ -79,13 +80,17 @@ var HttpKeyProvider = class {
 };
 
 // src/crypto/index.ts
-var CryptoError = class extends Error {
+var CryptoError = class extends HazoError {
   constructor(message, code) {
-    super(message);
-    this.code = code;
+    super({
+      code,
+      pkg: "hazo_secure",
+      message,
+      httpStatus: 500,
+      retryable: false
+    });
     this.name = "CryptoError";
   }
-  code;
 };
 var ALG = "aes-256-gcm";
 var IV_LEN = 12;
@@ -213,6 +218,44 @@ var StaticKeyProvider = class {
     return key;
   }
 };
+var LookupKeyProvider = class {
+  constructor(lookup) {
+    this.lookup = lookup;
+  }
+  lookup;
+  cache = /* @__PURE__ */ new Map();
+  async current() {
+    const keyId = this.lookup("current");
+    if (!keyId) {
+      throw new CryptoError(
+        "LookupKeyProvider: no 'current' key id from lookup",
+        "missing_env_key"
+      );
+    }
+    const key = await this.byId(keyId);
+    return { keyId, key };
+  }
+  async byId(keyId) {
+    if (this.cache.has(keyId)) return this.cache.get(keyId);
+    const lookupName = `key_${keyId}`;
+    const raw = this.lookup(lookupName);
+    if (!raw) {
+      throw new CryptoError(
+        `LookupKeyProvider: no key material for id ${keyId} (looked up "${lookupName}")`,
+        "key_not_found"
+      );
+    }
+    const buf = Buffer.from(raw, "base64");
+    if (buf.byteLength !== KEY_LEN2) {
+      throw new CryptoError(
+        `${lookupName} decodes to ${buf.byteLength} bytes; AES-256-GCM needs ${KEY_LEN2}`,
+        "invalid_key"
+      );
+    }
+    this.cache.set(keyId, buf);
+    return buf;
+  }
+};
 function aadFor(table, entityId, field) {
   return `${table}:${entityId}:${field}`;
 }
@@ -220,6 +263,7 @@ export {
   CryptoError,
   EnvKeyProvider,
   HttpKeyProvider,
+  LookupKeyProvider,
   StaticKeyProvider,
   aadFor,
   decryptField,

package/dist/csrf/index.d.ts

@@ -1,3 +1,5 @@
+import { HazoError } from 'hazo_core';
+
 interface CsrfPolicy {
     cookieName?: string;
     headerName?: string;
@@ -14,7 +16,14 @@ interface CsrfPolicy {
     };
 }
 type CsrfErrorCode = "csrf_cookie_missing" | "csrf_header_missing" | "csrf_mismatch" | "csrf_malformed";
-declare class CsrfError extends Error {
+/**
+ * Typed error raised by `/csrf`. Extends `HazoError` so it participates in
+ * the workspace's correlation-ID auto-attach + envelope shape, while
+ * preserving the legacy `(code, message)` constructor + `err.code` short
+ * discriminator that 1.0.x consumers already check. All CSRF rejections
+ * map to HTTP 403.
+ */
+declare class CsrfError extends HazoError {
     readonly code: CsrfErrorCode;
     constructor(code: CsrfErrorCode, message: string);
 }

package/dist/csrf/index.js

@@ -1,15 +1,20 @@
 // src/csrf/index.ts
+import { HazoError } from "hazo_core";
 var DEFAULT_COOKIE_NAME = "hs_csrf";
 var DEFAULT_HEADER_NAME = "x-csrf-token";
 var DEFAULT_TOKEN_LENGTH = 32;
 var DEFAULT_PROTECTED = ["POST", "PUT", "PATCH", "DELETE"];
-var CsrfError = class extends Error {
+var CsrfError = class extends HazoError {
   constructor(code, message) {
-    super(message);
-    this.code = code;
+    super({
+      code,
+      pkg: "hazo_secure",
+      message,
+      httpStatus: 403,
+      retryable: false
+    });
     this.name = "CsrfError";
   }
-  code;
 };
 function resolved(policy) {
   return {