@blamejs/core 0.6.13 → 0.6.20

package/CHANGELOG.md

@@ -8,6 +8,13 @@ upgrading across more than a few patches at a time.
 
 ## v0.6.x
 
+- **0.6.20** (2026-05-02) — CI / packaging fix-up. The npm-publish workflow's "Attach SBOM as release asset" step started failing with HTTP 422 ("Cannot upload assets to an immutable release") because the operator's manual `gh release create` had already been published when the workflow ran. Two changes: (1) `sbom.cyclonedx.json` is now bundled into the npm tarball (`files` block in package.json), so `npm install @blamejs/core && cat node_modules/@blamejs/core/sbom.cyclonedx.json` is the canonical SBOM access path. The prepack guard's known-allowed list covers the just-in-time generation. (2) The workflow's GH-release-attach step is now non-fatal: it tries to upload, logs a warning if the release is immutable, and lets the publish proceed regardless. The npm tarball is the load-bearing artifact; the GitHub release attachment was only ever supplementary. `.gitignore` adds `sbom.cyclonedx.json` so a stray local `npm sbom` doesn't pollute the repo.
+- **0.6.19** (2026-05-02) — closes the critical + high gaps surfaced by the v0.6.18 audit. **Critical**: `b.network.ntp.nts.querySingle` now actually verifies the server reply with the s2cKey — extracts the AUTHENTICATOR_AND_ENC extension, AEAD-decrypts with AAD = bytes-before-authenticator, fails closed (`nts/auth-failed` / `nts/no-authenticator`) when verification fails. Server-supplied new cookies in the encrypted plaintext are appended to the cookie pool and the consumed cookie popped (real RFC 8915 cookie rotation). Previously the function returned `authenticated: true` while only checking the unique-identifier echo — any MITM that mirrored the request's 32-byte unique field could spoof timestamps. **High**: `azure-blob.presignedUploadPolicy` now throws `PRESIGN_NOT_SUPPORTED` instead of silently returning a SAS PUT URL when operators asked for POST policy semantics — Azure SAS has no body-size cap and the previous shape was a misleading mismatch (operator error message points at presignedUploadUrl + post-upload HEAD as the alternative). `b.auth.password.policy` now ships the SecLists top-10000 common-password list bundled (CC-BY-3.0, `lib/vendor/common-passwords-top-10000.txt`), loaded lazily on first `policy.check()` call; `password` / `dragon` / `qwerty` / etc. now reject with `policy/forbidden-common`; `useBundledCommon: false` per-policy bypasses if operator ships their own list. `b.network.tls` adds `removeCa(fingerprint256)` / `removeCaByLabel(label)` / `clearAll()` / `purgeExpired()` / `expiringSoon(windowMs)` so operators can rotate corp DPI CAs without process restart; every removal audits with subject + fingerprint + reason. `b.network.dns.setResultOrder("ipv6first")` now flips the order on the DoH / DoT dual-stack fallback paths too (was only sorting OS-resolver results). `b.network.dns.resolve4` / `resolve6` / `resolveAaaa` now use real DNS-protocol queries (`dns.promises.resolve4` / `_dohLookup` / `_dotLookup`) instead of aliasing `lookup()` — operator semantics now match Node's standard library (skips `/etc/hosts`, mDNS). `b.network.socket.setDefaultLinger` removed from the silent no-op path; now throws `socket/linger-not-supported` with operator guidance to use `socket.destroy()` (abort) vs `socket.end()` (graceful) since Node's public `net.Socket` has no `setLinger()`. **Internal**: every `new XxxError(...)` call across `lib/network*.js` was passing args in the wrong order (message-then-code instead of code-then-message), making `e.code` return human messages and `e.message` return slash-codes — operators relying on `e.code` for error handling got the wrong field. All 50+ throws fixed across `lib/network.js` / `network-dns.js` / `network-proxy.js` / `network-tls.js` / `network-heartbeat.js` / `network-nts.js`. **CI**: `.gitleaks.toml` adds `test/smoke.js` to the path allowlist and pins the historical commit + fingerprint that tripped the jwt rule on a `REDACTED` placeholder; `npm-publish.yml` job permissions bumped from `contents: read` to `contents: write` so `gh release upload sbom.cyclonedx.json` no longer 403s.
+- **0.6.18** (2026-05-02) — `b.network` primitive — single namespace for runtime-configurable network behaviour. `b.network.ntp` adds tunable warn / fatal drift thresholds, env-var bindings (`BLAMEJS_NTP_SERVERS` / `BLAMEJS_NTP_TIMEOUT_MS` / `BLAMEJS_NTP_DRIFT_WARN_MS` / `BLAMEJS_NTP_DRIFT_FATAL_MS`), and authenticated-time support: `b.network.ntp.nts.query(opts)` performs an NTS-KE handshake (RFC 8915) over TLS 1.3 with the framework's PQC-hybrid group preference, extracts C2S / S2C keys via the standardized TLS exporter, and authenticates NTPv4 packets with AES-SIV-CMAC-256 (mandatory-to-implement, in-house) or AEAD-CHACHA20-POLY1305 — no extra vendored deps. `b.network.dns` exposes operator-pinned resolvers, IPv4 / IPv6 / dual-stack family selection, ipv4first / verbatim / ipv6first ordering, DNS lookup timeout (Node's native `dns.lookup` has none), in-memory positive + negative cache, and DoH / DoT (cloudflare / google / quad9 / custom URL) — `b.ssrfGuard` and `b.httpClient` route through it when configured. `b.network.proxy` honours `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` / `ALL_PROXY` (lower- and upper-case) with CIDR + suffix + wildcard `NO_PROXY` matching, basic-auth via `BLAMEJS_PROXY_AUTH`, CONNECT tunnels for HTTPS through HTTP proxies; `b.httpClient` picks up the agent automatically. `b.network.tls` is a runtime-overridable trust store: `addCa(pemOrPath)` / `addCaBundle(path)` / `useSystemTrust()` / `getTrustStore()` for deep-packet-inspection deploys behind Zscaler / Netskope / corporate Squid + custom CA — Node's `NODE_EXTRA_CA_CERTS` only works at boot; this primitive accepts adds at any time and `b.pqcAgent` picks them up immediately. Every `addCa` audits with subject + issuer + fingerprint256 + validity + isSelfSigned. `b.security.assertProduction({ allowDpiTrust })` refuses to boot in production with installed CAs unless explicitly allowed. `b.network.heartbeat` adds application-level liveness probes for upstream services (HTTP / TCP / NTP probe types, healthy → degraded → down state machine with consecutive-failure threshold, audit on state change, observability counters per probe). `b.network.socket` gives operator-tunable defaults for `TCP_NODELAY` / `SO_KEEPALIVE` / `SO_LINGER`. `b.network.bootFromEnv()` reads every supported env var at startup and applies in the right order so configuration takes effect before the first outbound socket; the wiki app's docker-compose configs ship every knob with a default-empty value (production overlay tightens DNS lookup timeout + cache TTL + `NTP_STRICT=1` + `SOCKET_NO_DELAY=1`). `.gitleaks.toml` was previously gitignored by the deny-all-dotfiles allowlist; it is now allowlisted so CI's secret-scan job loads the framework's allowlist and stops failing on `.gitleaks.toml: no such file or directory`. New wiki page `/network-config` documents all six sub-primitives.
+- **0.6.17** (2026-05-02) — six new CLI subcommands wrapping the v0.6.14 primitives so operators can drive them from runbooks / cron / one-off ops: `blamejs security assert` (boot the framework + run `b.security.assertProduction()` against the live posture; aggregates failures with their codes, exit 1 on any failure), `blamejs config-drift inspect/verify` (read the signed sidecar without rebooting; `verify` returns exit 1 on tamper or missing), `blamejs file-type detect <file>` (magic-byte content classification with `--allowlist` for upload debugging — pure utility, no boot), `blamejs password check --plaintext "..."` (test `b.auth.password.policy` with `--profile pci-4.0` / `nist-aal2` / `hipaa-aal2`, `--breach-check` for HIBP, `--email` / `--username` context — pure utility), `blamejs erase --table X --row-id Y --confirm` (one-off cryptographic erasure for GDPR Art. 17 — replaces sealed columns + derived hashes with NULL + audits via `system.erase`), `blamejs retention preview/run` (ad-hoc rule from CLI flags: `--table` + `--age-field` + `--ttl-ms` + `--action`, with `preview` for dry-run reporting). Also: per-subcommand `--help` now reaches each handler's USAGE block (the previous main() dispatch short-circuited every `<sub> --help` to top-level help); fix applies to all existing subcommands too (`api-key --help`, `vault --help`, etc.). The `b.dualControl` primitive is intentionally NOT in the CLI surface — its grants live in an operator-supplied `b.cache` instance the CLI can't bind to without operator wiring; admins approve / revoke from the operator's app instead. Hadolint action pinned to `@master` (the published `@v3` floating tag doesn't exist; the maintainer ships only patch tags + master).
+- **0.6.16** (2026-05-02) — CI secret-scan job switched from `gitleaks/gitleaks-action` (which started requiring a paid `GITLEAKS_LICENSE` for organization repositories, breaking the v0.6.14 publish workflow) to a direct install of the OSS gitleaks binary (Apache-2.0); resolves the latest release at job time so new ruleset improvements ship automatically. Same forward-track posture applied to other CI tools where pinning would silently miss security improvements: `aquasecurity/trivy-action` swapped from `@v0.36.0` to `@master`, `hadolint/hadolint-action` from `@v3.3.0` to the floating `@v3` major tag, `ludeeus/action-shellcheck` from `@2.0.0` to `@master`, ESLint runner from `eslint@10` to `eslint@latest` in both `ci.yml` and `npm-publish.yml`. Vendored crypto libraries (@noble/ciphers, @simplewebauthn/server, argon2, peculiar-pki) verified at latest upstream — no bundle refresh needed. No framework code changes; npm publish workflow unblocked for v0.6.14 / v0.6.15 / this release.
+- **0.6.15** (2026-05-02) — wiki sidebar nav: every concern group is now a `<details>` section starting collapsed; the section containing the current page is rendered with `open` server-side so the operator's current location is always visible. Custom CSS-only disclosure glyph (▸ → ▾ via rotation) — works under the wiki's strict CSP without inline JS. Wiki app gains three new env knobs that ship with the docker-compose configs out of the box: `WIKI_TRUST_PROXY` (cookie Secure-flag detection through TLS terminator; pre-existing in v0.6.12 lib code, now in docker-compose with documentation), `WIKI_ADMIN_ALLOWED_CIDRS` / `WIKI_ADMIN_DENIED_CIDRS` (in-process CIDR fence on `/admin` paths via `b.middleware.networkAllowlist`), `WIKI_REQUIRE_PROD_ASSERTS` (boot-time `b.security.assertProduction()` gate that refuses to boot when production posture is incomplete). The production overlay (`docker-compose.prod.yml`) defaults the latter two on (TRUST_PROXY=1 since Caddy terminates TLS, REQUIRE_PROD_ASSERTS=1 so a misconfigured prod deploy fails fast); the dev overlay defaults them off.
+- **0.6.14** (2026-05-02) — new operator-facing primitives, each shipping the v1-defensible compliance surface: `b.security.assertProduction(opts)` boot-time policy engine (vault / dbAtRest / auditSigning posture, NTP strict, Node minimum major, TLS minimum version, required + forbidden env vars, NODE_ENV pinning, dataDir POSIX-mode check, CORS-allow-all detection, operator-supplied extra asserts); `b.permissions.policy(scope, predicate)` ABAC layer that evaluates per-scope predicates after RBAC passes (single + requireAll + requireAny modes); `b.permissions` role-spec `requireMfa` / `mfaWindowMs` AND per-route MFA enforcement; `b.session` IP/UA fingerprint capture + drift detection with operator-supplied scorer for anomaly scoring (strict modes: `requireFingerprintMatch` AND `maxAnomalyScore`); `b.auth.password.policy(opts)` with NIST 800-63B / PCI-DSS 4.0 / HIPAA-AAL2 named profiles, length / common / context / dictionary / complexity (categories + min-run + min-sequence) rules, HIBP k-anonymity breach check (SHA-1 lives in `lib/internal-sha1-hibp.js`, NOT exported on `b.crypto`), rotation (`shouldRotate`) and history-reuse (`reuseProhibited`); `b.dualControl.create(opts)` two-person-rule with m-of-n quorum, cooling-off lock between approval and consume, approver-role gate, requester cancellation, minimum reason length, notification hook; `b.retention.create(opts)` with multi-stage rules (warn → archive → erase), legal-hold per-row exemption, dry-run `preview()`, soft-delete vs hard-delete vs erase, cross-table cascade, per-rule concurrency lock; `b.configDrift.create(opts)` with multi-baseline support, critical-keys severity classification, ignore-keys allowlist, signed sidecar via SLH-DSA + diff vs prev snapshot; `b.fileType.detect/.assertOneOf` magic-byte content classification (image / document / archive / executable / etc.); `b.middleware.networkAllowlist({ paths, allowedCidrs, deniedCidrs })` deny-then-allow CIDR fence; `b.httpClient.request({ allowedHosts })` with exact / suffix / wildcard / per-method entries and audit emit on disallowed; `b.cryptoField.eraseRow(table, row)` cryptographic-erasure helper for sealed columns + derived hashes. CI gains gitleaks secret scan + CycloneDX SBOM via `npm sbom` (no vendoring). README + SECURITY operator-checklist updated end to end for the new surface; wiki gains alerting-rule reference table for the framework's emitted events. Backwards-compatible — every new opt is opt-in.
 - **0.6.13** (2026-05-02) — wiki primitive-section docs catch up to the v0.6.12 surface (`safeUrl.parse` allowUserinfo, `session.touch` extendBy ceiling, `queue.consume` rateLimit validation, `mail.transports.console` redactBcc, `logStream` webhook-sink onDrop, `backup.create` requireFlush, `restore.create` maxPulledBytes / maxPulledFiles); restore default cap stated as `C.BYTES.gib(4)` instead of a raw byte literal; numeric-check predicates (`isPositiveInt`, `isFiniteNonNegative`, `isPositiveFinite`) consolidated into `lib/numeric-checks.js` — were duplicated across api-key, cache, notify, queue, restore, retry, slug, testing, webhook; api-snapshot.json refreshed
 - **0.6.12** (2026-05-02) — `b.safeUrl.parse` now rejects URLs with `user:pass@` userinfo by default (opt in per-call via `allowUserinfo: true`); `b.session.touch({ extendBy })` enforces the same `MAX_TTL_MS` ceiling as `create` / `rotate`; `b.queue.consume({ rateLimit })` rejects negative / zero / `NaN` / `Infinity` / fractional `max`; `b.middleware.requireAuth` no longer treats request `Content-Type: application/json` as a JSON-preference signal (only `Accept` and `X-Requested-With` count); `b.backup.create({ requireFlush: true })` opt-in fails the backup if pre-flush fails instead of producing a stale snapshot; `b.restore.create({ maxPulledBytes, maxPulledFiles })` preflight bounds bundle footprint before and after pull (defaults 4 GiB / 100K files); `b.mail.transports.console({ redactBcc: true })` opt-in prints recipient count instead of addresses; `b.logStream.transports.webhook({ onDrop })` callback fires on overflow + retry-exhausted batch drops. Wiki: admin login wired through `b.auth.lockout` (exponential-backoff after bad-cred attempts) and cookie `Secure` flag now routes through `b.requestHelpers.requestProtocol` with `WIKI_TRUST_PROXY` opt-in instead of trusting raw `x-forwarded-proto`. Wiki README documents the trust model for editable page bodies and the sanitization pattern operators should adopt before expanding the editor surface.
 - **0.6.11** (2026-05-01) — wiki example-execution validator: fixture init no longer reaches across module realms (unblocks the npm-publish workflow's wiki-e2e gate, which `npm install --install-links` copies the framework into the wiki's node_modules — two distinct singletons before this fix)

package/NOTICE

@@ -57,3 +57,19 @@ Used for:    Pure-JS mTLS CA. Self-signed CA generation (ECDSA P-384, SHA-384),
              asn1js, pvtsutils, pvutils, and the @peculiar/asn1-* schema
              chain).
 --------------------------------------------------------------------------------
+Component:   SecLists — 10k-most-common.txt
+Version:     master snapshot (bundled 2026-05-02)
+Source:      https://github.com/danielmiessler/SecLists
+             https://github.com/danielmiessler/SecLists/blob/master/Passwords/Common-Credentials/10k-most-common.txt
+License:     CC-BY-3.0
+Copyright:   Copyright (c) Daniel Miessler and SecLists contributors
+Used for:    Top-10000 most-common (breach-derived) passwords. Loaded by
+             b.auth.password.policy() to satisfy NIST 800-63B §5.1.1.2's
+             "previously breached, dictionary, repetitive/sequential,
+             context-specific" check. Operators with deeper enforcement
+             (HIBP downloads, NCSC 100k) layer on top via opts.forbidCommon
+             — the bundled set is additive. Bundled at lib/vendor/
+             common-passwords-top-10000.txt; thank you to the SecLists
+             project maintainers for keeping a curated, freely-redistributable
+             baseline.
+--------------------------------------------------------------------------------

package/README.md

@@ -42,15 +42,15 @@ var b = require("@blamejs/core");
 The framework bundles the surface a typical Node app reaches for. Every primitive listed is callable today; nothing is a stub.
 
 - **Data layer** — SQLite with sealed-by-default columns (`b.db`), migrations, seeders, atomic-file writes; bring-your-own external Postgres / MySQL / etc. with pool tuning + role-aware connect + read-replica routing (`b.externalDb`); declarative role-narrowed views and Postgres row-level-security migrations (`b.db.declareView`, `b.db.declareRowPolicy`); S3 / R2 / B2 / GCS / Azure object store with multipart upload + SSE + bucket ops (`b.storage`, `b.objectStore`); durable queue with priority + cron + flows (`b.queue`, `b.jobs`); cluster-shared cache (`b.cache`).
-- **Identity & access** — passwords (Argon2id), passkeys (WebAuthn), TOTP, JWT (PQ-default), OAuth, sessions, brute-force lockout (`b.auth.*`, `b.session`); RBAC with optional per-role DB binding (`b.permissions`, role-spec `dbRole` field); API keys with rotation (`b.apiKey`); break-glass column gates with second-factor + audit (`b.breakGlass`).
-- **Crypto** — envelope-versioned PQC at rest (ML-KEM-1024 + P-384 hybrid, XChaCha20-Poly1305, SHAKE256), vault sealing, field-level crypto, signed webhooks (SLH-DSA-SHAKE-256f), ECIES API encryption (`b.crypto`, `b.vault`, `b.webhook`); pure-JS mTLS CA, PQC TLS gates inbound + outbound (`b.mtlsCa`, `b.pqcGate`, `b.pqcAgent`).
-- **HTTP** — router with schema-validated routes + OpenAPI publication; full middleware stack (CSRF, CORS, rate-limit, security headers, CSP nonce, body parser, compression, SSE, request log, request-time DB role binding via `b.middleware.dbRoleFor`) wired by `createApp`; HTTP/1.1 + HTTP/2 outbound client with SSRF gate, redirects, multipart, interceptors, progress, encrypted cookie jar (`b.httpClient`, `b.ssrfGuard`, `b.safeUrl`).
-- **Defensive parsers** — `b.safeJson`, `b.safeBuffer`, `b.safeSql`, `b.safeSchema`, `b.parsers` (XML / TOML / YAML / .env), `b.config` (schema-validated env).
+- **Identity & access** — passwords (Argon2id) + policy primitive (NIST 800-63B / PCI-DSS 4.0 / HIPAA-AAL2 profiles, HaveIBeenPwned k-anonymity breach check, length / context / dictionary / complexity rules, rotation + history) (`b.auth.password`); passkeys (WebAuthn), TOTP, JWT (PQ-default), OAuth, sessions with optional IP / UA fingerprint drift detection + anomaly scoring, brute-force lockout (`b.auth.*`, `b.session`); RBAC + optional per-role DB binding + role-spec `requireMfa` + per-route MFA freshness window + ABAC predicate registry (`b.permissions`); API keys with rotation (`b.apiKey`); break-glass column gates with second-factor + audit (`b.breakGlass`); two-person-rule approval workflow with m-of-n quorum + cooling-off lock + approver-role gate + cancellation (`b.dualControl`).
+- **Crypto** — envelope-versioned PQC at rest (ML-KEM-1024 + P-384 hybrid, XChaCha20-Poly1305, SHAKE256), vault sealing, field-level crypto + cryptographic erasure (`b.cryptoField.eraseRow`), signed webhooks (SLH-DSA-SHAKE-256f), ECIES API encryption (`b.crypto`, `b.vault`, `b.webhook`); pure-JS mTLS CA, PQC TLS gates inbound + outbound (`b.mtlsCa`, `b.pqcGate`, `b.pqcAgent`).
+- **HTTP** — router with schema-validated routes + OpenAPI publication; full middleware stack (CSRF, CORS, rate-limit, security headers, CSP nonce, body parser, compression, SSE, request log, request-time DB role binding via `b.middleware.dbRoleFor`, in-process CIDR fence via `b.middleware.networkAllowlist`) wired by `createApp`; HTTP/1.1 + HTTP/2 outbound client with SSRF gate, scheme + userinfo + per-host (wildcard / per-method) destination allowlist, redirects, multipart, interceptors, progress, encrypted cookie jar (`b.httpClient`, `b.ssrfGuard`, `b.safeUrl`); operator-tunable network configurability — env-driven NTP / NTS (RFC 8915 authenticated time), DNS with IPv6 / DoH / DoT / cache / lookup timeout, outbound HTTP proxy (`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`), runtime DPI trust-store CA additions, application-level heartbeats, TCP socket defaults (`b.network`).
+- **Defensive parsers** — `b.safeJson`, `b.safeBuffer`, `b.safeSql`, `b.safeSchema`, `b.parsers` (XML / TOML / YAML / .env), `b.config` (schema-validated env), `b.fileType` magic-byte content classification with deny-on-upload categories (image / document / archive / executable / etc.).
 - **Communication** — WebSockets with channel/room fan-out across cluster replicas (`b.websocket`, `b.websocketChannels`); mail with multipart + attachments + DKIM + calendar invites + bounce intake (`b.mail`, `b.mailBounce`); generic notification dispatcher with operator-supplied transports (`b.notify`).
-- **Observability** — tamper-evident audit chain with SLH-DSA-signed checkpoints, metrics, tracing (OTel pass-through when wired), PII redaction, log-stream sinks, OTLP/HTTP-JSON exporter for any OTel-compatible backend (`b.audit`, `b.metrics`, `b.tracing`, `b.redact`, `b.logStream`, `b.otelExport`).
+- **Observability** — tamper-evident audit chain with SLH-DSA-signed checkpoints, metrics, tracing (OTel pass-through when wired), PII redaction, log-stream sinks, OTLP/HTTP-JSON exporter for any OTel-compatible backend (`b.audit`, `b.metrics`, `b.tracing`, `b.redact`, `b.logStream`, `b.otelExport`); operator-callable boot-time security policy assertions (`b.security.assertProduction`) and tamper-evident config-baseline drift detection signed with the audit-signing key (`b.configDrift`).
 - **i18n** — CLDR plural rules, Accept-Language negotiation, Intl formatters, RTL (`b.i18n`).
 - **Format helpers** — RFC 4180 CSV with Excel formula-injection prevention (`b.csv`), RFC 9562 UUID v4 + v7 (`b.uuid`), URL-safe slugs (`b.slug`), TZ-aware datetime (`b.time`), ZIP creation (`b.archive`), HMAC-signed cursor pagination (`b.pagination`), HTML form rendering + validation + CSRF (`b.forms`).
-- **Production** — cluster leader election with fenced leases over Postgres/SQLite (`b.cluster`); cron + interval scheduler that runs exactly-once globally (`b.scheduler`); retry with full-jitter backoff + circuit breaker (`b.retry`); graceful shutdown (`b.appShutdown`); NTP boot check (`b.ntpCheck`); end-to-end-encrypted backup bundles (`b.backup`).
+- **Production** — cluster leader election with fenced leases over Postgres/SQLite (`b.cluster`); cron + interval scheduler that runs exactly-once globally (`b.scheduler`); retry with full-jitter backoff + circuit breaker (`b.retry`); graceful shutdown (`b.appShutdown`); NTP boot check (`b.ntpCheck`); end-to-end-encrypted backup bundles with pre-flush fail-closed mode (`b.backup`); restore with pulled-bundle footprint preflight (`b.restore`); GDPR / PCI / HIPAA-shaped retention rules with multi-stage warn → archive → erase, legal-hold exemptions, dry-run preview, cross-table cascade (`b.retention`).
 
 ## Documentation
 
@@ -59,7 +59,7 @@ Full primitive-by-primitive docs live at [blamejs.com](https://blamejs.com), whi
 - **Data** — [Database](https://blamejs.com/database) · [Object Store](https://blamejs.com/object-store) · [Queue & Cache](https://blamejs.com/queue-cache)
 - **Identity** — [Authentication](https://blamejs.com/auth) · [Access Control](https://blamejs.com/access-control)
 - **Crypto** — [Crypto & Vault](https://blamejs.com/crypto-vault) · [Network Crypto](https://blamejs.com/network-crypto)
-- **HTTP** — [Routing](https://blamejs.com/routing) · [Middleware](https://blamejs.com/middleware) · [Outbound HTTP](https://blamejs.com/outbound-http)
+- **HTTP** — [Routing](https://blamejs.com/routing) · [Middleware](https://blamejs.com/middleware) · [Outbound HTTP](https://blamejs.com/outbound-http) · [Network Configurability](https://blamejs.com/network-config)
 - **Validation** — [Safe Parsers](https://blamejs.com/safe-parsers)
 - **Communication** — [WebSockets](https://blamejs.com/websockets) · [Mail](https://blamejs.com/mail) · [Notifications](https://blamejs.com/notifications)
 - **Tools** — [Observability](https://blamejs.com/observability) · [Testing](https://blamejs.com/testing) · [i18n & Locale](https://blamejs.com/i18n-locale) · [Format Helpers](https://blamejs.com/format-helpers)
@@ -106,9 +106,10 @@ All runtime dependencies are committed to the repo — no transitive npm install
 | [`@simplewebauthn/server`](https://github.com/MasterKale/SimpleWebAuthn) | 13.3.0 | [Matthew Miller](https://github.com/MasterKale) | WebAuthn / passkey verification |
 | [`argon2`](https://github.com/ranisalt/node-argon2) | 0.44.0 | [Ranieri Althoff](https://github.com/ranisalt) | Password hashing (native prebuilds, 8 platforms) |
 | [`@peculiar/x509`](https://github.com/PeculiarVentures/x509) + [`pkijs`](https://github.com/PeculiarVentures/PKI.js) | 2.0.0 + 3.4.0 | [Peculiar Ventures](https://github.com/PeculiarVentures) | Pure-JS mTLS CA — ECDSA P-384 cert signing, PKCS#12 packaging (no openssl CLI) |
+| [`SecLists` 10k-most-common.txt](https://github.com/danielmiessler/SecLists/blob/master/Passwords/Common-Credentials/10k-most-common.txt) | master snapshot | [Daniel Miessler / SecLists contributors](https://github.com/danielmiessler/SecLists) (CC-BY-3.0) | Top-10000 common-password dictionary read by `b.auth.password.policy()` for the NIST 800-63B §5.1.1.2 "previously breached" check |
 | [`prismjs`](https://prismjs.com/) | 1.30.0 | [Lea Verou + contributors](https://github.com/PrismJS/prism) | Syntax highlighting in the example wiki's code blocks (browser-side) |
 
-These libraries are exceptional work — blamejs wouldn't exist without them. All are MIT licensed. Per-package version, license, and provenance live in two manifests: [`lib/vendor/MANIFEST.json`](lib/vendor/MANIFEST.json) for the framework's server-side bundles and [`examples/wiki/public/vendor/MANIFEST.json`](examples/wiki/public/vendor/MANIFEST.json) for the wiki app's browser-side bundle. The framework's [`NOTICE`](NOTICE) file carries the upstream attributions.
+These libraries are exceptional work — blamejs wouldn't exist without them. All are MIT licensed (the SecLists password list is CC-BY-3.0). Per-package version, license, and provenance live in two manifests: [`lib/vendor/MANIFEST.json`](lib/vendor/MANIFEST.json) for the framework's server-side bundles and [`examples/wiki/public/vendor/MANIFEST.json`](examples/wiki/public/vendor/MANIFEST.json) for the wiki app's browser-side bundle. The framework's [`NOTICE`](NOTICE) file carries the upstream attributions.
 
 ## Why "blamejs"
 

package/index.js

@@ -159,6 +159,12 @@ var seeders = require("./lib/seeders");
 var i18n = require("./lib/i18n");
 var notify = require("./lib/notify");
 var testing = require("./lib/testing");
+var configDrift = require("./lib/config-drift");
+var security = require("./lib/security-assert");
+var fileType = require("./lib/file-type");
+var dualControl = require("./lib/dual-control");
+var retention = require("./lib/retention");
+var network = require("./lib/network");
 
 module.exports = {
   crypto:           crypto,
@@ -266,6 +272,12 @@ module.exports = {
   i18n:             i18n,
   notify:           notify,
   testing:          testing,
+  configDrift:      configDrift,
+  security:         security,
+  fileType:         fileType,
+  dualControl:      dualControl,
+  retention:        retention,
+  network:          network,
   ntpCheck:         ntpCheck,
   version:          constants.version,
 };

package/lib/audit.js

@@ -203,13 +203,17 @@ var FRAMEWORK_NAMESPACES = [
   "backup",     // b.backup
   "breakglass", // b.breakGlass — column-policy / row-enforcement step-up auth (audit namespace lowercased per the validator's `namespace.verb` rule, same convention as b.apiKey → apikey.*)
   "cache",      // b.cache
+  "config",     // b.configDrift (config.baseline.captured / config.drift.detected / config.baseline.tamper / config.baseline.unreadable)
   "db",         // b.db / b.middleware.dbRoleFor / b.externalDb.runAs
                 //   (role-switching, RLS-shaped events)
   "dkim",       // b.mail.dkim (DKIM-Signature generation events)
+  "dual",       // b.dualControl (dual.grant.requested / approved / denied / consumed / expired / self_approval_denied)
   "mail",       // b.mail (b.mail-bounce uses "system.mail.*")
+  "network",    // b.middleware.networkAllowlist (network.gate.denied)
   "notify",     // b.notify
   "permissions", // b.permissions
   "restore",    // b.restore
+  "retention",  // b.retention (retention.rule.declared / sweep.started / row.processed / sweep.completed / sweep.failed)
   "scheduler",  // b.scheduler (lifecycle: scheduler.start / scheduler.stop;
                 //              tick/task events use "system.scheduler.*")
   "seeders",    // b.seeders

package/lib/auth/password.js

@@ -47,6 +47,10 @@
  * "the call shape was wrong" (empty plain, oversize plain).
  */
 var argon2 = require("../vendor/argon2");
+var httpClient = require("../http-client");
+var internalSha1Hibp = require("../internal-sha1-hibp");
+var safeUrl = require("../safe-url");
+var timingSafeEqual = require("../crypto").timingSafeEqual;
 var { AuthError } = require("../framework-error");
 
 // Tuning targets ~250–500ms on commodity 2026 hardware. memoryCost
@@ -59,6 +63,444 @@ var DEFAULT_PARAMS = Object.freeze({
 
 var MAX_PLAINTEXT_BYTES = 4096;
 
+// ---- Policy primitive ----------------------------------------------
+//
+// Argon2id covers the OFFLINE attack model: even with the DB stolen,
+// each guess costs ~250ms of CPU + 64 MiB of RAM. It does NOT cover:
+//   - Online weak-credential attacks (operator phishes / reuses)
+//   - Periodic rotation requirements (PCI 8.3, NYDFS, some HIPAA)
+//   - History reuse (PCI 8.3 last-4 floor)
+//   - Operator-tunable composition rules (HIPAA / industry-specific
+//     where AAL2-equivalent posture is mandated)
+//
+// b.auth.password.policy(opts) returns:
+//   - check(plaintext, context?)         → presentation-time gate
+//   - shouldRotate(passwordSetAt)        → per-account rotation check
+//   - reuseProhibited(plaintext, history)→ history-reuse check
+//
+// Standards mapped:
+//   - NIST 800-63B §5.1.1.2: 8-char min floor, 64-char min max,
+//     breach check, NO MANDATORY composition. (Default posture.)
+//   - PCI-DSS 8.3.6 / 8.3.7: 12-char min, 90-day rotation, history
+//     of 4. (Operator opts in via { profile: "pci-8.3" }.)
+//   - HIPAA 164.308(a)(5)(ii)(D): "procedures for creating, changing,
+//     and safeguarding passwords" — addressed via composition opts.
+//   - GDPR Art. 32: storage shape (sealed via Argon2id); no
+//     additional policy requirement here.
+//   - NYDFS 23 NYCRR 500.12 / NIST AAL2: rotation + breach + length.
+//
+// The defaults follow NIST 800-63B (no mandatory composition,
+// length-and-breach over rules). Every other regime layers on
+// opt-in opts; the framework refuses to surprise an operator who
+// followed the defaults.
+//
+//   var policy = b.auth.password.policy({
+//     minLength:        12,
+//     breachCheck:      "haveibeenpwned",
+//     mustRotateAfterMs:    C.TIME.days(90),     // PCI 8.3.9
+//     historyMinDistance:   4,                    // PCI 8.3.7
+//     complexity: {
+//       minCategories:      0,                    // NIST: don't enforce. opt in for HIPAA-flavoured.
+//       categories:         ["lower", "upper", "digit", "special"],
+//       minRunRepeat:       3,                    // reject "aaaa…"
+//       minSequenceLength:  3,                    // reject "abcd"/"1234"
+//     },
+//     dictionary: ["companyName", "productName"],
+//   });
+//
+//   await policy.check(plain, { email, username, deny: [...], passwordSetAt });
+//   policy.shouldRotate(passwordSetAt);
+//   await policy.reuseProhibited(plain, [oldHash1, oldHash2, oldHash3]);
+//
+// breachCheck:"haveibeenpwned" uses the HIBP k-anonymity API; the
+// SHA-1 hash is computed in-process via lib/internal-sha1-hibp.js
+// (NOT exported on b.crypto — see comment in lib/crypto.js). Only
+// the first 5 hex chars cross the wire. Rate-limit and failure-mode
+// are operator's call: an HIBP outage returns
+// { ok: true, breachCheckSkipped: true } by default; failClosed:true
+// rejects.
+var DEFAULT_POLICY = Object.freeze({
+  minLength:              8,                  // NIST floor
+  maxLength:              MAX_PLAINTEXT_BYTES,
+  forbidCommon:           [],
+  // The bundled top-10000 list ships in lib/vendor/common-passwords-top-10000.txt
+  // (SecLists, CC-BY-3.0). Set false to skip — operators with a richer
+  // breach-list (HIBP downloads, NCSC 100k) layered via forbidCommon
+  // typically leave this on; it's additive.
+  useBundledCommon:       true,
+  denyContextSubstrings:  true,
+  breachCheck:            null,               // null | "haveibeenpwned"
+  breachThreshold:        1,
+  failClosed:             false,
+  hibpEndpoint:           "https://api.pwnedpasswords.com",
+  hibpTimeoutMs:          1500,
+  // Rotation policy (PCI 8.3.9 / NYDFS / industry-specific). null = no rotation.
+  mustRotateAfterMs:      null,
+  // History reuse (PCI 8.3.7 floor: last-4). 0 = disabled.
+  // Operator passes the actual stored hash list to reuseProhibited().
+  historyMinDistance:     0,
+  // Composition rules (NIST 800-63B explicitly says NOT to enforce
+  // these; HIPAA / older standards still ask for them. Default is OFF
+  // so the NIST-aligned posture is the default; operators opt in.)
+  complexity:             null,
+  // Dictionary terms forbidden as substrings (operator brand names,
+  // product names, etc.). Substring match, case-insensitive. Empty
+  // by default.
+  dictionary:             [],
+});
+
+var COMPLEXITY_DEFAULT = Object.freeze({
+  minCategories:     0,        // NIST default off; HIPAA-flavoured ops set 3 or 4
+  categories:        ["lower", "upper", "digit", "special"],
+  minRunRepeat:      0,        // reject N+ identical chars in a row; 0 = off
+  minSequenceLength: 0,        // reject N+ ascending or descending chars; 0 = off
+});
+
+// Predefined profiles operators can opt into. Each spreads onto the
+// policy opts so the operator can still override individual fields.
+var POLICY_PROFILES = Object.freeze({
+  // NIST 800-63B AAL2 baseline — length + breach, no composition.
+  "nist-aal2": Object.freeze({
+    minLength:    8,
+    breachCheck:  "haveibeenpwned",
+  }),
+  // PCI-DSS 4.0 §8.3 — 12-char min, 90-day rotation, history of 4.
+  // Composition is NOT required by PCI 4.0 (it dropped the older
+  // version's composition rule); breach check + length covers it.
+  "pci-4.0": Object.freeze({
+    minLength:           12,
+    breachCheck:         "haveibeenpwned",
+    mustRotateAfterMs:   90 * 24 * 60 * 60 * 1000,
+    historyMinDistance:  4,
+  }),
+  // HIPAA 164.308 — "procedures for creating, changing, and
+  // safeguarding". The standard is intentionally vague; the
+  // commonly-implemented profile pairs length + composition +
+  // rotation + lockout (lockout is b.auth.lockout, separate
+  // primitive).
+  "hipaa-aal2": Object.freeze({
+    minLength:           12,
+    breachCheck:         "haveibeenpwned",
+    mustRotateAfterMs:   180 * 24 * 60 * 60 * 1000,
+    historyMinDistance:  4,
+    complexity: {
+      minCategories: 3,
+      minRunRepeat:  3,
+      minSequenceLength: 3,
+    },
+  }),
+});
+
+// Top-10000 common-password set vendored from SecLists
+// (CC-BY-3.0 by Daniel Miessler). Loaded lazily on first policy.check
+// call — keeps boot fast for apps that never invoke the dictionary.
+// Operators wanting deeper enforcement supply opts.forbidCommon (set
+// of additional plaintexts) and/or opts.forbidCommonExtra (operator's
+// own breach list); both layer additively on top of the bundled set.
+var path = require("node:path");
+var fs   = require("node:fs");
+var _bundledCommonPasswords = null;
+function _loadBundledCommon() {
+  if (_bundledCommonPasswords) return _bundledCommonPasswords;
+  var p = path.join(__dirname, "..", "vendor", "common-passwords-top-10000.txt");
+  var text = fs.readFileSync(p, "utf8");
+  var set = new Set();
+  var lines = text.split(/\r?\n/);
+  for (var i = 0; i < lines.length; i++) {
+    var line = lines[i].trim();
+    if (line.length > 0) set.add(line.toLowerCase());
+  }
+  _bundledCommonPasswords = set;
+  return _bundledCommonPasswords;
+}
+function _commonPasswordsSize() {
+  return _loadBundledCommon().size;
+}
+
+function _ok(extra) { return Object.assign({ ok: true }, extra || {}); }
+function _fail(code, message) {
+  return { ok: false, code: "policy/" + code, message: message };
+}
+
+// Argon2id verify with a known stored hash — used by reuseProhibited
+// to compare a candidate plaintext against history entries without
+// the operator having to wire verify() per row.
+async function _argon2Verify(stored, plaintext) {
+  if (typeof stored !== "string" || stored.indexOf("$argon2id$") !== 0) return false;
+  try { return await argon2.verify(stored, plaintext); }
+  catch (_e) { return false; }
+}
+
+function _hasCategory(plaintext, category) {
+  if (category === "lower")   return /[a-z]/.test(plaintext);
+  if (category === "upper")   return /[A-Z]/.test(plaintext);
+  if (category === "digit")   return /[0-9]/.test(plaintext);
+  if (category === "special") return /[^A-Za-z0-9]/.test(plaintext);
+  return false;
+}
+
+function _hasRunOfLength(plaintext, n) {
+  if (n < 2) return false;
+  for (var i = 0; i + n <= plaintext.length; i++) {
+    var c = plaintext.charCodeAt(i);
+    var allSame = true;
+    for (var j = 1; j < n; j++) {
+      if (plaintext.charCodeAt(i + j) !== c) { allSame = false; break; }
+    }
+    if (allSame) return true;
+  }
+  return false;
+}
+
+function _hasSequenceOfLength(plaintext, n) {
+  if (n < 3) return false;
+  for (var i = 0; i + n <= plaintext.length; i++) {
+    var ascending = true, descending = true;
+    for (var j = 1; j < n; j++) {
+      var diff = plaintext.charCodeAt(i + j) - plaintext.charCodeAt(i + j - 1);
+      if (diff !== 1)  ascending  = false;
+      if (diff !== -1) descending = false;
+    }
+    if (ascending || descending) return true;
+  }
+  return false;
+}
+
+function policy(opts) {
+  opts = opts || {};
+  // Apply named profile FIRST, then operator opts on top so the
+  // operator can override profile defaults per-field.
+  if (typeof opts.profile === "string" && opts.profile.length > 0) {
+    if (!POLICY_PROFILES[opts.profile]) {
+      throw new AuthError("auth-password/bad-policy",
+        "policy.profile must be one of " + Object.keys(POLICY_PROFILES).join("/") +
+        ", got " + JSON.stringify(opts.profile));
+    }
+    opts = Object.assign({}, POLICY_PROFILES[opts.profile], opts);
+    delete opts.profile;
+  }
+  var p = Object.assign({}, DEFAULT_POLICY, opts);
+  if (typeof p.minLength !== "number" || p.minLength < 1 || p.minLength > MAX_PLAINTEXT_BYTES) {
+    throw new AuthError("auth-password/bad-policy",
+      "policy.minLength must be in [1, " + MAX_PLAINTEXT_BYTES + "]");
+  }
+  if (typeof p.maxLength !== "number" || p.maxLength < p.minLength || p.maxLength > MAX_PLAINTEXT_BYTES) {
+    throw new AuthError("auth-password/bad-policy",
+      "policy.maxLength must be in [minLength, " + MAX_PLAINTEXT_BYTES + "]");
+  }
+  if (p.breachCheck !== null && p.breachCheck !== "haveibeenpwned") {
+    throw new AuthError("auth-password/bad-policy",
+      "policy.breachCheck must be null or 'haveibeenpwned', got " + JSON.stringify(p.breachCheck));
+  }
+  if (p.hibpEndpoint) {
+    safeUrl.parse(p.hibpEndpoint, { allowedProtocols: safeUrl.ALLOW_HTTP_TLS, errorClass: AuthError });
+  }
+  if (p.mustRotateAfterMs !== null &&
+      (typeof p.mustRotateAfterMs !== "number" || !isFinite(p.mustRotateAfterMs) || p.mustRotateAfterMs <= 0)) {
+    throw new AuthError("auth-password/bad-policy",
+      "policy.mustRotateAfterMs must be a positive finite number or null");
+  }
+  if (typeof p.historyMinDistance !== "number" || !isFinite(p.historyMinDistance) ||
+      p.historyMinDistance < 0 || Math.floor(p.historyMinDistance) !== p.historyMinDistance) {
+    throw new AuthError("auth-password/bad-policy",
+      "policy.historyMinDistance must be a non-negative integer");
+  }
+  if (p.complexity !== null && typeof p.complexity !== "object") {
+    throw new AuthError("auth-password/bad-policy",
+      "policy.complexity must be null or an object");
+  }
+  var complexity = p.complexity ? Object.assign({}, COMPLEXITY_DEFAULT, p.complexity) : null;
+  if (complexity) {
+    if (typeof complexity.minCategories !== "number" || complexity.minCategories < 0 ||
+        complexity.minCategories > complexity.categories.length) {
+      throw new AuthError("auth-password/bad-policy",
+        "policy.complexity.minCategories must be in [0, " + complexity.categories.length + "]");
+    }
+    for (var ci = 0; ci < complexity.categories.length; ci++) {
+      if (["lower", "upper", "digit", "special"].indexOf(complexity.categories[ci]) === -1) {
+        throw new AuthError("auth-password/bad-policy",
+          "policy.complexity.categories[" + ci + "] must be lower / upper / digit / special, got " +
+          JSON.stringify(complexity.categories[ci]));
+      }
+    }
+  }
+  var forbidLower = (Array.isArray(p.forbidCommon) ? p.forbidCommon : [])
+    .map(function (s) { return String(s).toLowerCase(); });
+  var bundledSet = p.useBundledCommon === false ? null : _loadBundledCommon();
+  var dictionaryLower = (Array.isArray(p.dictionary) ? p.dictionary : [])
+    .filter(function (s) { return typeof s === "string" && s.length >= 3; })
+    .map(function (s) { return s.toLowerCase(); });
+
+  async function check(plaintext, context) {
+    if (typeof plaintext !== "string") {
+      return _fail("bad-input", "plaintext must be a string");
+    }
+    var byteLen = Buffer.byteLength(plaintext, "utf8");
+    if (byteLen < p.minLength) {
+      return _fail("too-short", "plaintext is shorter than " + p.minLength + " bytes");
+    }
+    if (byteLen > p.maxLength) {
+      return _fail("too-long", "plaintext exceeds " + p.maxLength + " bytes");
+    }
+    var lower = plaintext.toLowerCase();
+    if (bundledSet && bundledSet.has(lower)) {
+      return _fail("forbidden-common", "plaintext matches a known breached / common password (bundled top-10000)");
+    }
+    for (var i = 0; i < forbidLower.length; i++) {
+      if (lower === forbidLower[i]) {
+        return _fail("forbidden-common", "plaintext matches a known weak / common password");
+      }
+    }
+    for (var di2 = 0; di2 < dictionaryLower.length; di2++) {
+      if (lower.indexOf(dictionaryLower[di2]) !== -1) {
+        return _fail("forbidden-dictionary",
+          "plaintext contains a forbidden dictionary term");
+      }
+    }
+    if (p.denyContextSubstrings && context) {
+      var deny = [];
+      if (typeof context.email === "string" && context.email.length > 0) {
+        deny.push(context.email.toLowerCase());
+        var at = context.email.indexOf("@");
+        if (at > 0) deny.push(context.email.slice(0, at).toLowerCase());
+      }
+      if (typeof context.username === "string" && context.username.length > 0) {
+        deny.push(context.username.toLowerCase());
+      }
+      if (Array.isArray(context.deny)) {
+        for (var di = 0; di < context.deny.length; di++) {
+          if (typeof context.deny[di] === "string" && context.deny[di].length >= 3) {
+            deny.push(context.deny[di].toLowerCase());
+          }
+        }
+      }
+      for (var dj = 0; dj < deny.length; dj++) {
+        if (deny[dj].length >= 3 && lower.indexOf(deny[dj]) !== -1) {
+          return _fail("contains-context",
+            "plaintext contains a forbidden context substring (account identifier or operator-supplied deny string)");
+        }
+      }
+    }
+    if (complexity) {
+      if (complexity.minCategories > 0) {
+        var hits = 0;
+        for (var cc = 0; cc < complexity.categories.length; cc++) {
+          if (_hasCategory(plaintext, complexity.categories[cc])) hits++;
+        }
+        if (hits < complexity.minCategories) {
+          return _fail("complexity-categories",
+            "plaintext uses " + hits + " character categories; policy requires at least " +
+            complexity.minCategories + " of [" + complexity.categories.join(", ") + "]");
+        }
+      }
+      if (complexity.minRunRepeat >= 2 && _hasRunOfLength(plaintext, complexity.minRunRepeat)) {
+        return _fail("complexity-run",
+          "plaintext contains " + complexity.minRunRepeat + "+ identical consecutive characters");
+      }
+      if (complexity.minSequenceLength >= 3 && _hasSequenceOfLength(plaintext, complexity.minSequenceLength)) {
+        return _fail("complexity-sequence",
+          "plaintext contains a " + complexity.minSequenceLength + "+-char ascending or descending sequence");
+      }
+    }
+    if (p.breachCheck === "haveibeenpwned") {
+      // HIBP k-anonymity: send the first 5 hex chars of the SHA-1
+      // hash, scan the returned suffix list. The framework's only
+      // SHA-1 usage; HIBP requires it. (See lib/internal-sha1-hibp.js
+      // for the restriction rationale.)
+      var sha1Full = internalSha1Hibp.sha1Hex(plaintext).toUpperCase();
+      var prefix = sha1Full.slice(0, 5);
+      var suffix = sha1Full.slice(5);
+      var url = p.hibpEndpoint.replace(/\/+$/, "") + "/range/" + prefix;
+      var resp;
+      try {
+        resp = await httpClient.request({
+          method:        "GET",
+          url:           url,
+          headers:       { "User-Agent": "blamejs-password-policy/1" },
+          idleTimeoutMs: p.hibpTimeoutMs,
+          errorClass:    AuthError,
+        });
+      } catch (e) {
+        if (p.failClosed) {
+          return _fail("breach-check-failed",
+            "HIBP lookup failed and policy is fail-closed: " + ((e && e.message) || String(e)));
+        }
+        return _ok({ breachCheckSkipped: true,
+          breachCheckSkipReason: (e && e.message) || String(e) });
+      }
+      if (resp.statusCode !== 200 || !resp.body) {
+        if (p.failClosed) {
+          return _fail("breach-check-failed",
+            "HIBP returned status " + resp.statusCode + " with no body");
+        }
+        return _ok({ breachCheckSkipped: true,
+          breachCheckSkipReason: "hibp-status-" + resp.statusCode });
+      }
+      var bodyText = Buffer.isBuffer(resp.body) ? resp.body.toString("utf8") : String(resp.body);
+      var lines = bodyText.split(/\r?\n/);
+      for (var li = 0; li < lines.length; li++) {
+        var line = lines[li].trim();
+        if (line.length === 0) continue;
+        var colon = line.indexOf(":");
+        if (colon < 0) continue;
+        var hashSuffix = line.slice(0, colon).toUpperCase();
+        var count = parseInt(line.slice(colon + 1), 10);
+        if (timingSafeEqual(Buffer.from(hashSuffix, "utf8"), Buffer.from(suffix, "utf8")) &&
+            isFinite(count) && count >= p.breachThreshold) {
+          return _fail("breached",
+            "plaintext appears in HaveIBeenPwned with count " + count +
+            " (threshold " + p.breachThreshold + ")");
+        }
+      }
+      return _ok({ breachCheckCount: 0 });
+    }
+    return _ok();
+  }
+
+  function shouldRotate(passwordSetAt, now) {
+    if (p.mustRotateAfterMs === null) return false;
+    if (typeof passwordSetAt !== "number" || !isFinite(passwordSetAt)) {
+      throw new AuthError("auth-password/bad-input",
+        "shouldRotate: passwordSetAt must be a numeric ms-epoch timestamp");
+    }
+    var nowMs = typeof now === "number" ? now : Date.now();
+    return (nowMs - passwordSetAt) >= p.mustRotateAfterMs;
+  }
+
+  async function reuseProhibited(plaintext, history) {
+    if (typeof plaintext !== "string" || plaintext.length === 0) return false;
+    if (p.historyMinDistance <= 0) return false;
+    if (!Array.isArray(history) || history.length === 0) return false;
+    // Check the most-recent N entries (history-min-distance bound).
+    var checkCount = Math.min(history.length, p.historyMinDistance);
+    for (var i = 0; i < checkCount; i++) {
+      if (await _argon2Verify(history[i], plaintext)) return true;
+    }
+    return false;
+  }
+
+  return {
+    check:            check,
+    shouldRotate:     shouldRotate,
+    reuseProhibited:  reuseProhibited,
+    // Operator introspection — handy when an admin tool wants to
+    // surface "your policy requires X" to end users.
+    describe: function () {
+      return {
+        minLength:           p.minLength,
+        maxLength:           p.maxLength,
+        breachCheck:         p.breachCheck,
+        mustRotateAfterMs:   p.mustRotateAfterMs,
+        historyMinDistance:  p.historyMinDistance,
+        complexity:          complexity ? Object.assign({}, complexity) : null,
+        dictionaryCount:     dictionaryLower.length,
+        forbidCommonCount:   forbidLower.length,
+        bundledCommonCount:  bundledSet ? bundledSet.size : 0,
+      };
+    },
+  };
+}
+
 function _validatePlain(plain) {
   if (typeof plain !== "string" || plain.length === 0) {
     throw new AuthError("auth-password/invalid-plain",
@@ -132,8 +574,11 @@ function needsRehash(stored, opts) {
 }
 
 module.exports = {
-  hash:           hash,
-  verify:         verify,
-  needsRehash:    needsRehash,
-  DEFAULT_PARAMS: DEFAULT_PARAMS,
+  hash:             hash,
+  verify:           verify,
+  needsRehash:      needsRehash,
+  policy:           policy,
+  DEFAULT_PARAMS:   DEFAULT_PARAMS,
+  DEFAULT_POLICY:   DEFAULT_POLICY,
+  POLICY_PROFILES:  POLICY_PROFILES,
 };