hazo_secure 0.5.0 → 1.1.0

package/CHANGE_LOG.md

@@ -0,0 +1,171 @@
+# Change Log
+
+## 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

@@ -5,9 +5,10 @@ Security & compliance primitives for Node.js / Next.js apps. Four independent su
 | Subpath | Purpose |
 |---|---|
 | `hazo_secure/fetch` | SSRF-safe `safeFetch()` — domain allowlist, private-CIDR blocker, redirect controls |
-| `hazo_secure/ratelimit` | Sliding-window + token-bucket limiter with pluggable store (in-memory default, Redis adapter) |
+| `hazo_secure/ratelimit` | Sliding-window + token-bucket limiter with pluggable store (in-memory default, hazo_connect adapter) |
 | `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 |
 
 ## Install
 
@@ -15,7 +16,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_jobs` and `hazo_files` are optional peers — only needed if you use `hazo_secure/gdpr`.
+`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`.
 
 ## Quick start
 
@@ -72,6 +73,90 @@ gdpr.registerExporter({
 });
 ```
 
+## New in 1.0.0
+
+### `hazo_secure/ratelimit` — ConnectRateLimitStore (token bucket)
+
+```ts
+import { ConnectRateLimitStore } from "hazo_secure/ratelimit";
+
+const store = new ConnectRateLimitStore({ getHazoConnect: () => db });
+const limiter = createRateLimiter({ store, windowMs: 60_000, max: 30 });
+```
+
+Stores token-bucket state in `hazo_rl_buckets` (see `migrations/001_hazo_rl_buckets.sql`). Run the migration before use. Requires `hazo_connect` peer.
+
+### `hazo_secure/fetch` — undici dispatcher + `validateConnectIp`
+
+```ts
+import { safeFetch, createSecureDispatcher, validateConnectIp } from "hazo_secure/fetch";
+
+// Use standalone to close the DNS-rebinding gap at socket creation time
+const dispatcher = createSecureDispatcher();
+const res = await safeFetch(url, { policy, deps: { fetchImpl: (u, i) => fetch(u, { ...i, dispatcher }) } });
+
+// Or validate resolved IPs yourself
+validateConnectIp("169.254.169.254"); // throws — blocked CIDR
+```
+
+Node.js only — undici is a Node dep. Edge runtime gets pre-flight checks only.
+
+### `hazo_secure/crypto` — HttpKeyProvider
+
+```ts
+import { HttpKeyProvider } from "hazo_secure/crypto";
+
+const provider = new HttpKeyProvider({
+  endpoint: "https://kms.internal/keys",
+  headers: { Authorization: `Bearer ${token}` },
+  ttlMs: 30_000,           // in-process cache TTL (default: 30 s)
+});
+provider.clearCache();     // force next fetch to re-fetch from endpoint
+```
+
+Cloud-agnostic — works with any HTTPS key endpoint that returns `{ keyId, key: "<base64>" }`. Caches keys in-process to avoid latency on every encrypt/decrypt call.
+
+### `hazo_secure/gdpr` — registry enhancements
+
+```ts
+import { createGdprRegistry, GdprRegistryError } from "hazo_secure/gdpr";
+
+const gdpr = createGdprRegistry({ auditIntent: logAuditEntry });
+
+// Validate registry completeness
+const issues = await gdpr.validateRegistry({ requiredDomains: ["persons", "payments"] });
+
+// Export user data (streams records from all registered exporters)
+for await (const file of gdpr.exportUser({ userId })) {
+  console.log(file.filename, file.content);
+}
+
+// Dry-run export without side effects
+const files = await gdpr.dryRunExport({ userId });
+
+// Anonymise user across all registered domains
+await gdpr.anonymiseUser({ userId });
+```
+
+`GdprRegistryError` is a typed error class — catch and `instanceof`-check it.
+
+---
+
+## Runtime Compatibility
+
+| Subpath | Edge runtime | Node.js (server) | Notes |
+|---|---|---|---|
+| `hazo_secure` | ✅ | ✅ | Types only, no runtime weight |
+| `hazo_secure/csrf` | ✅ | ✅ | Web Crypto API only |
+| `hazo_secure/ratelimit` | ✅ (MemoryRateLimitStore) | ✅ | ConnectRateLimitStore is Node-only (hazo_connect) |
+| `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 |
+
+**Node.js ≥ 18 required** for all Node-only subpaths.
+
+---
+
 ## Design
 
 Each subpath is independent — no cross-imports between `/fetch`, `/ratelimit`, `/crypto`, `/gdpr`. The `gdpr` module *consumes* the others when a project wires them together, but the package itself doesn't entangle them.

package/SETUP_CHECKLIST.md

@@ -0,0 +1,68 @@
+# 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/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(', '))"
+```

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,36 @@
+import { HazoError } from 'hazo_core';
+
+interface HttpKeyProviderOptions {
+    /**
+     * Base HTTPS endpoint for key material.
+     * - current(): GET {endpoint}/current → { keyId: string; key: string }
+     * - byId(id):  GET {endpoint}/{id}    → { keyId: string; key: string }
+     *
+     * `key` must be base64url-encoded 32-byte AES-256 key material.
+     */
+    endpoint: string;
+    /**
+     * Fetch implementation. Inject safeFetch from hazo_secure/fetch for SSRF
+     * protection on external KMS endpoints. Defaults to globalThis.fetch.
+     */
+    fetch?: typeof globalThis.fetch;
+    /** Bearer token added as Authorization header on every request. */
+    token?: string;
+    /** Additional headers added to every request. */
+    headers?: Record<string, string>;
+}
+declare class HttpKeyProvider implements KeyProvider {
+    #private;
+    constructor(opts: HttpKeyProviderOptions);
+    current(): Promise<{
+        keyId: string;
+        key: Uint8Array;
+    }>;
+    byId(keyId: string): Promise<Uint8Array>;
+    /** Clear in-process key cache. Call after rotating keys. */
+    clearCache(): void;
+}
+
 /**
  * Source of symmetric keys for `encryptField` / `decryptField`. The current
  * key is used for encryption; `byId` resolves any key (current or rotated-out)
@@ -38,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.
@@ -104,4 +144,4 @@ declare class StaticKeyProvider implements KeyProvider {
  *  Convention: `<table>:<entityId>:<field>` — collision-free across tables. */
 declare function aadFor(table: string, entityId: string, field: string): string;
 
-export { CryptoError, type EncryptedField, EnvKeyProvider, type KeyProvider, StaticKeyProvider, aadFor, decryptField, encryptField };
+export { CryptoError, type CryptoErrorCode, type EncryptedField, EnvKeyProvider, HttpKeyProvider, type HttpKeyProviderOptions, type KeyProvider, StaticKeyProvider, aadFor, decryptField, encryptField };

package/dist/crypto/index.js

@@ -1,17 +1,101 @@
 // src/crypto/index.ts
 import { createCipheriv, createDecipheriv, randomBytes } from "crypto";
-var CryptoError = class extends Error {
+import { HazoError } from "hazo_core";
+
+// src/crypto/provider-http.ts
+var KEY_LEN = 32;
+var HttpKeyProvider = class {
+  #endpoint;
+  #fetch;
+  #token;
+  #headers;
+  /** Cache for key material, keyed by keyId. */
+  #cache = /* @__PURE__ */ new Map();
+  /** Cached result of the most recent successful /current fetch. */
+  #currentCache = null;
+  constructor(opts) {
+    this.#endpoint = opts.endpoint.replace(/\/$/, "");
+    this.#fetch = opts.fetch ?? globalThis.fetch;
+    this.#token = opts.token;
+    this.#headers = opts.headers ?? {};
+  }
+  async current() {
+    if (this.#currentCache) return this.#currentCache;
+    const data = await this.#fetchSegment("current");
+    const key = this.#parseAndCacheKey(data);
+    this.#currentCache = { keyId: data.keyId, key };
+    return this.#currentCache;
+  }
+  async byId(keyId) {
+    const cached = this.#cache.get(keyId);
+    if (cached) return cached;
+    const data = await this.#fetchSegment(keyId);
+    return this.#parseAndCacheKey(data);
+  }
+  /** Clear in-process key cache. Call after rotating keys. */
+  clearCache() {
+    this.#cache.clear();
+    this.#currentCache = null;
+  }
+  #parseAndCacheKey(data) {
+    const buf = Buffer.from(data.key, "base64url");
+    if (buf.byteLength !== KEY_LEN) {
+      throw new CryptoError(
+        `HttpKeyProvider: key ${data.keyId} is ${buf.byteLength} bytes; AES-256-GCM needs ${KEY_LEN}`,
+        "invalid_key"
+      );
+    }
+    const key = new Uint8Array(buf);
+    this.#cache.set(data.keyId, key);
+    return key;
+  }
+  async #fetchSegment(segment) {
+    const url = `${this.#endpoint}/${segment}`;
+    const headers = { ...this.#headers };
+    if (this.#token) headers["Authorization"] = `Bearer ${this.#token}`;
+    let res;
+    try {
+      res = await this.#fetch(url, { headers });
+    } catch (err) {
+      throw new CryptoError(
+        `HttpKeyProvider: fetch failed for ${url}: ${err instanceof Error ? err.message : String(err)}`,
+        "key_not_found"
+      );
+    }
+    if (!res.ok) {
+      throw new CryptoError(
+        `HttpKeyProvider: endpoint returned ${res.status} for ${url}`,
+        "key_not_found"
+      );
+    }
+    try {
+      return await res.json();
+    } catch {
+      throw new CryptoError(
+        `HttpKeyProvider: invalid JSON response from ${url}`,
+        "key_not_found"
+      );
+    }
+  }
+};
+
+// src/crypto/index.ts
+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;
 var TAG_LEN = 16;
-var KEY_LEN = 32;
+var KEY_LEN2 = 32;
 function toB64(buf) {
   return Buffer.from(buf).toString("base64");
 }
@@ -20,9 +104,9 @@ function fromB64(s) {
 }
 async function encryptField(plaintext, opts) {
   const { keyId, key } = await opts.keys.current();
-  if (key.byteLength !== KEY_LEN) {
+  if (key.byteLength !== KEY_LEN2) {
     throw new CryptoError(
-      `Key for ${keyId} is ${key.byteLength} bytes; AES-256-GCM needs ${KEY_LEN}.`,
+      `Key for ${keyId} is ${key.byteLength} bytes; AES-256-GCM needs ${KEY_LEN2}.`,
       "invalid_key"
     );
   }
@@ -99,9 +183,9 @@ var EnvKeyProvider = class {
       throw new CryptoError(`Missing ${varName} env var`, "key_not_found");
     }
     const buf = Buffer.from(raw, "base64");
-    if (buf.byteLength !== KEY_LEN) {
+    if (buf.byteLength !== KEY_LEN2) {
       throw new CryptoError(
-        `${varName} decodes to ${buf.byteLength} bytes; AES-256-GCM needs ${KEY_LEN}`,
+        `${varName} decodes to ${buf.byteLength} bytes; AES-256-GCM needs ${KEY_LEN2}`,
         "invalid_key"
       );
     }
@@ -140,6 +224,7 @@ function aadFor(table, entityId, field) {
 export {
   CryptoError,
   EnvKeyProvider,
+  HttpKeyProvider,
   StaticKeyProvider,
   aadFor,
   decryptField,