@blamejs/core 0.11.20 → 0.11.22

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.11.x
 
+- v0.11.22 (2026-05-20) — **`b.cert.create` — turnkey TLS-certificate manager composing ACME + sealed persistence + renewal scheduler + SNI + key escrow.** Operators wiring TLS no longer have to glue ACME + key generation + cert persistence + renewal scheduling + SNI dispatch + escrow by hand. `b.cert.create({ storage, acme, certs, renew, ocsp, audit, compliance })` accepts a declarative manifest of certificates plus the operator's choice of ACME challenge solver, and the manager owns the rest of the lifecycle: ACME RFC 8555 order + RFC 9773 ARI-aware renewal, leaf key rotation on renew, OCSP refresh scheduling, sealed-disk persistence via `b.vault.seal`, optional break-glass key escrow encrypted to an operator-supplied recipient via `b.crypto.encryptEnvelope`, and SNI dispatch for `https.createServer({ SNICallback })`. Composes existing primitives — `b.acme.create` (extended this release with per-challenge methods), `b.vault.seal`, `b.safeAsync.repeating`, `b.network.tls`, `b.audit` — so the operator-facing surface is one factory call. **Added:** *`b.cert.create(opts)` — turnkey certificate manager* — New top-level primitive. Storage backend: `sealed-disk` (default; sealed via `b.vault.seal`). ACME: directory URL + contact + auto-generated account key (sealed on disk; operator can override with explicit key material). Certs manifest: per-cert name + domains + keyAlg (ecdsa-p256 / ecdsa-p384 / rsa-2048 / rsa-3072 / rsa-4096) + challenge `{ type, provision, cleanup }` callbacks (http-01 / dns-01 / tls-alpn-01). Renewal: ARI-respecting scheduler with configurable `intervalMs` + `minDaysBeforeExpiry` thresholds. OCSP: `stapling: true` schedules periodic OCSP refresh via `b.network.tls.ocsp`. Key escrow: optional `keyEscrow: { recipient }` encrypts each renewed private key to the recipient public key via `b.crypto.encryptEnvelope` and persists alongside the sealed key — break-glass-only recovery path, NOT routine access. Surface: `start()` / `stop()` / `getContext(name)` / `sniCallback` / `refresh(name)` / event-emitter `on('cert.issued' | 'cert.renewed' | 'cert.renew-failed', handler)`. · *`b.acme.create.fetchAuthorization(authUrl)` — RFC 8555 §7.5 authorization GET* — POST-as-GET an authorization URL; returns the parsed authorization object with the challenge array. The challenge entries carry `{ type, url, token, status }` for each offered challenge type. Required by the cert manager's per-challenge flow but useful to operators implementing custom ACME wrappers. · *`b.acme.create.notifyChallengeReady(challengeUrl)` — RFC 8555 §7.5.1 ready-notification* — POST an empty JSON object to a challenge URL to signal the operator has provisioned the response. Returns the updated challenge object; the CA's validation runs asynchronously and the operator polls via `waitForAuthorization` afterwards. · *`b.acme.create.waitForAuthorization(authUrl, opts?)` — authorization status polling* — Polls an authorization until `status === 'valid'` (success) or `status === 'invalid'` (CA refused). Honors the client's `pollIntervalMs` + `pollMaxMs` defaults; per-call `opts.intervalMs` + `opts.timeoutMs` override available. Throws typed `acme/auth-invalid` on CA refusal and `acme/auth-timeout` on poll-budget exhaustion. · *`b.acme.create.buildCsr({ privateKey, publicKey, domains })` — RFC 2986 PKCS#10 CSR builder* — Builds a CertificationRequest signed with the leaf private key. Subject `CN=<first domain>`, all domains as `dNSName` entries in the SubjectAltName extension. Supports ECDSA P-256 (signed sha256), ECDSA P-384 (signed sha384), RSA 2048 / 3072 / 4096 (signed sha256). Ed25519 is rejected at the CSR layer because CA support is uneven — operators wanting Ed25519 certs build the CSR externally. PEM-encoded output ready to feed to `finalize(order, csrPem)`. · *`b.asn1Der` write primitives — `writeBitString` / `writeSet` / `writeUtf8String` / `writePrintableString` / `writeIa5String` / `writeBoolean` / `writeContextImplicit`* — ASN.1 DER encoder extensions needed for PKCS#10 CSR construction. PrintableString refuses input outside the RFC 5280 character set; IA5String refuses non-ASCII; UTF8String refuses non-string input. SET-OF encoding sorts children by their encoded bytes per DER. Internal-only today (consumed by `b.acme.create.buildCsr`); operators with their own ASN.1 needs can compose them. **Changed:** *`b.audit.FRAMEWORK_NAMESPACES` adds `cert`* — The cert-manager lifecycle emits `cert.account.generated` / `cert.issued` / `cert.renewed` / `cert.renew-failed` / `cert.challenge-cleanup` audit events; the audit-namespace coverage check at smoke-time now recognizes the `cert` namespace. **References:** [RFC 8555 (ACME)](https://www.rfc-editor.org/rfc/rfc8555.html) · [RFC 9773 (ACME Renewal Information / ARI)](https://www.rfc-editor.org/rfc/rfc9773.html) · [RFC 2986 (PKCS#10 Certification Request Syntax)](https://www.rfc-editor.org/rfc/rfc2986.html) · [RFC 5280 (X.509 Internet PKI)](https://www.rfc-editor.org/rfc/rfc5280.html) · [RFC 8737 (TLS-ALPN-01 challenge)](https://www.rfc-editor.org/rfc/rfc8737.html) · [OpenSSL CSR roundtrip — local OpenSSL validation](https://www.openssl.org/docs/man3.5/man1/openssl-req.html)
+
+- v0.11.21 (2026-05-20) — **Supply-chain hardening — pinact + zizmor + actionlint gate, sha-to-tag tag-integrity verifier, GOVERNANCE.md.** Closes the input + tag-integrity halves of the supply-chain trust boundary. `pinact` refuses any `uses:` reference that isn't pinned to a 40-char SHA with a verified version-comment (defense against the CVE-2025-30066 retroactive-tag-rewrite class). `zizmor` audits every workflow for the documented security anti-pattern catalog (template-injection / excessive-permissions / cache-poisoning / impostor-commit / unredacted-secrets / etc.). The new `sha-to-tag-verify` workflow refuses to let the publish workflow proceed if a release tag's commit SHA isn't on `main`'s first-parent history OR wasn't the result of a merged PR — the source-side gate that TanStack's 2026-05-11 attack (84 malicious `@tanstack/*` versions published with valid SLSA L3 provenance) demonstrated as a structural defense alongside provenance verification. SECURITY.md gains operator-facing `slsa-verifier` and tag-SHA-integrity recipes. New top-level `GOVERNANCE.md` documents the solo-maintainer governance model, succession plan, key-loss recovery, and dependent-notification protocol. **Added:** *`.github/workflows/actions-lint.yml` — pinact + zizmor + actionlint gate* — Three tools, three layers per the arxiv.org "Unpacking Security Scanners for GitHub Actions Workflows" taxonomy. `pinact run --check` refuses any `uses:` reference that isn't SHA-pinned with a matching version-comment; `pinact run --verify` re-resolves each pinned SHA's registered tag at check time and refuses if the workflow's version-comment disagrees (catches retroactive tag rewrites). `zizmor` audits at `--min-severity low` across every documented rule class (template-injection, excessive-permissions, dangerous-triggers, unpinned-uses, cache-poisoning, github-env, hardcoded-container-credentials, impostor-commit, known-vulnerable-actions, obfuscation, ref-confusion, secrets-inherit, self-hosted-runner, unredacted-secrets, unsound-contains, use-trusted-publishing); SARIF emitted to GitHub Code Scanning. `actionlint` runs YAML + expression validation + shellcheck on every `run:` block. Single documented exception in `.pinact.yaml` — the SLSA reusable workflow MUST be tag-pinned because its internal builder-fetch step refuses non-tag refs. · *`.github/workflows/sha-to-tag-verify.yml` — tag-SHA integrity gate* — Runs on every `v*` tag push and refuses to let the publish workflow start if the tag's commit SHA isn't on `main`'s first-parent history OR wasn't the result of a merged PR. Defends against the tag-mutation class (CVE-2025-30066: 23,000+ affected repos in March 2025) and the source-side-malicious-publish class (TanStack 2026-05-11: 84 valid-SLSA-L3-provenance malicious versions). The same chain is documented for operator-side re-verification in SECURITY.md's new "Verifying release-commit integrity" subsection. · *`GOVERNANCE.md` — solo-maintainer governance, succession, key-loss recovery, dependent-notification* — New top-level document covering: (a) current governance model (solo maintainer pre-1.0, maintainer-final on technical direction); (b) succession plan with TBD-successor-with-documented-re-open-trigger, repository ownership, npm publish credentials, SSH signing key rotation procedure, Sigstore identity rotation; (c) key-loss recovery for every asset (npm publish, GitHub org, SSH signing key, Sigstore, domain); (d) dependent-notification protocol via `security@blamejs.com` with 30-day no-activity escalation. Bus-factor-1 is the largest non-technical risk pre-1.0; this document makes the recovery path defensible. · *SECURITY.md — `slsa-verifier` and tag-SHA-integrity operator-verification recipes* — "Verifying release authenticity" gains a `slsa-verifier verify-artifact` recipe (pinned to v2.7.1) for offline / API-independent provenance verification — `gh attestation verify` walks the chain via the GitHub API; `slsa-verifier` does it from disk. The recipe explicitly states the limit: SLSA provenance binds the tarball bytes to a workflow+commit+tag, but does NOT prove the source is clean (the TanStack incident shipped valid-provenance malicious versions because the source side was compromised). A new "Verifying release-commit integrity" subsection documents the sha-to-tag chain operators run alongside provenance verification — the source-side gate. · *`.pinact.yaml` — pinact configuration with documented SLSA exception* — Defines a single tag-pin exception for `slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml`. The SLSA reusable workflow's internal builder-fetch step refuses non-tag `BUILDER_REF` values, so the call MUST be tag-pinned; mitigated by slsa-framework's upstream tag-protection + immutable-release rules. The same exception also appears as a per-line `# allow:slsa-framework-action-not-sha-pinned` marker in `npm-publish.yml` for the framework's own codebase-patterns gate. **Changed:** *Workflow version-comment integrity — every pinned action's `# vX.Y.Z` comment now matches the registered tag for that SHA* — Pre-existing pins carried stale version-comments (`actions/checkout@de0fac2e... # v6.0.0` where that SHA is actually `v6.0.2`, `actions/setup-node@48b55a01... # v6.0.0` where the SHA is `v6.4.0`, `actions/download-artifact@3e5f45b2... # v7.0.1` where the SHA is `v8.0.1`, `github/codeql-action@9e0d7b8d... # v3.30.9` where the SHA is `v4.35.5`). The SHAs themselves stay (they're the actual-released versions); the comments now match. This is what pinact's `--verify` check enforces structurally going forward — a stale version-comment is the early-warning signal that a retroactive tag rewrite landed without operator notice. **References:** [CVE-2025-30066 (tj-actions/changed-files retroactive tag rewrite)](https://nvd.nist.gov/vuln/detail/CVE-2025-30066) · [TanStack npm publish incident 2025-05-11](https://blog.tanstack.com/the-tanstack-may-2025-supply-chain-attack/) · [pinact](https://github.com/suzuki-shunsuke/pinact) · [zizmor](https://github.com/woodruffw/zizmor) · [actionlint](https://github.com/rhysd/actionlint) · [slsa-verifier](https://github.com/slsa-framework/slsa-verifier)
+
 - v0.11.20 (2026-05-20) — **`b.backup.localStorage` legacy alias removed + test-discipline backlog fully drained.** Two pieces bundled into one patch. (1) The `b.backup.localStorage` legacy alias introduced in v0.11.2 as a deprecation cycle for the rename to `b.backup.diskStorage` is removed entirely — pre-v1 the project's stated policy is no backwards-compat shims, and the cleanup no longer needs to wait for the Node 26 floor-bump. (2) Every test file in the `test-promise-settimeout-sleep` detector's 49-file migration backlog is converted from `await new Promise(r => setTimeout(r, N))` sleeps to `helpers.waitUntil(predicate, opts)` (condition-waits) or the new `helpers.passiveObserve(ms, label)` (verify-absence-of-event windows). The previously-split `test-codebase-patterns.test.js` catalog is folded into the main `codebase-patterns.test.js` `KNOWN_ANTIPATTERNS` array with `scanScope: "test"`. **Added:** *`helpers.passiveObserve(ms, label)` — real-time observation budget* — Distinct from `helpers.waitUntil`: the goal is NOT to poll until a condition is truthy, but to let real time elapse so the test can verify ABSENCE of an event over a window. Required `label` (string) surfaces in audit logs / future flake diagnostics so a grep through a CI log immediately identifies which observation budget was consumed. Throws TypeError on non-positive `ms` or missing label. Use sparingly — if there IS an observable predicate, `waitUntil` is the right primitive (faster on fast platforms; passive observation always burns the full budget). **Changed:** *Test-discipline catalog unified — `codebase-patterns.test.js` is now the single source of truth* — The previously-split `test-codebase-patterns.test.js` runner is merged into the main `codebase-patterns.test.js` catalog. Six test-side detectors are now inline `KNOWN_ANTIPATTERNS` entries with `scanScope: "test"`: `test-promise-settimeout-sleep` (broadened regex catches block-bodied arrows + multi-arg arrows + function bodies with leading statements), `test-uses-stream-pipeline-without-withtesttimeout` (per-test wall-clock ceiling for node:stream.pipeline tests), `release-named-test-file` (basename-mode; refuses `v0-8-41-additions.test.js` / `slot-19-enhancements.test.js` / `batch-N.test.js`), `test-hardcoded-server-bind-port` (`.listen(0)` + `server.address().port`), `test-fs-watch-direct-call` (`helpers.backdateFile` + `helpers.waitForWatcher` instead), `test-future-utimes-without-backdated-baseline` (pair future-mtime writes with `backdateFile`), `test-creates-db-handle-without-isolation` (`b.db.create()` must compose `setupTestDb` / `setupVaultOnly` / `mkdtempSync`). The test-scope walker now also includes `examples/*/test/` so wiki integration tests share the same discipline. Single catalog means a single allowlist per detector, single migration backlog, and one runner to invoke from CI. · *Test-discipline migration — `setTimeout(r, N)` backlog fully drained (49 → 0 migration entries)* — Converted every test file in the migration backlog to `helpers.waitUntil` / `helpers.passiveObserve`: `a2a`, `a2a-tasks`, `agent-event-bus`, `agent-idempotency`, `agent-orchestrator`, `agent-snapshot`, `api-encrypt`, `app-shutdown`, `audit-segregation`, `break-glass`, `config`, `cors`, `daily-byte-quota`, `dsr`, `external-db-routing`, `guard-csv`, `http-client-cache`, `log-stream-cloudwatch`, `log-stream-otlp` (dead `_sleep` helper removed), `log-stream-otlp-grpc`, `mail-greylist`, `middleware-compose-pipeline`, `network`, `network-dns-resolver`, `network-heartbeat-passive`, `notify`, `observability-tracing`, `promise-pool`, `pubsub`, `queue-dlq-extend-lease`, `queue-flow-repeat`, `queue-priority-rate-progress`, `require-auth-cache-control`, `retry`, `safe-async-loops`, `safe-async-parallel`, `scim-server`, `sse`, `vault-seal-pem-file`, `watcher` (3 fs.watchFile poll-event waits), `webhook`, `websocket-channels`, `ws-client`, `api-key` (layer-1), and integration tests `cache`, `cluster-provider-mysql`, `log-stream`, `network-heartbeat`, `object-store-sigv4`, `pubsub`, `queue-redis`, `websocket-permessage-deflate`, `ws-client-roundtrip`. Each condition-wait now has a grep'able label and an automatic 5000ms ceiling. Two files are permanent structural FPs (not migration backlog): `test/helpers/services.js` (TCP/TLS/UDP probe primitives — race-with-socket-event pattern, not condition-wait) and `examples/wiki/test/integration.js` (consumes `@blamejs/core` via npm symlink, doesn't have access to the framework's internal test helpers; single 100ms post-shutdown flush window). **Removed:** *`b.backup.localStorage` — the legacy alias is gone* — The property no longer resolves on `b.backup` and the one-time deprecation warning is no longer emitted. Migration is a literal-name find-and-replace: `b.backup.localStorage({ root: ... })` becomes `b.backup.diskStorage({ root: ... })`. The returned storage backend object, its options shape, and its wire contract with `b.backupBundle.create` are unchanged. See SECURITY.md's Node 26 compatibility section for the original rename rationale. **References:** [Node.js 26 release notes (localStorage global)](https://nodejs.org/en/blog/release/v26.0.0)
 
 - v0.11.18 (2026-05-20) — **ML-DSA-65 release-signing key onboarded — `.mldsa.sig` sidecar lights up.** v0.11.17 was the first release the new pipeline published end-to-end, but the `.mldsa.sig` PQC sidecar was missing because the operator-side `RELEASE_PQC_SIGNING_KEY` setup hadn't been done yet. v0.11.18 onboards the keypair: `keys/release-pqc-pub.json` is committed in-tree, the matching private key lives only in the `npm-publish` environment's `RELEASE_PQC_SIGNING_KEY` secret, and `SECURITY.md` documents the SHA3-512 fingerprint + the operator-side verification recipe (no external verifier binary required — verifies via the framework's own vendored noble-post-quantum primitive). **Added:** *`keys/release-pqc-pub.json` — ML-DSA-65 release-signing public key committed in-tree* — Generated locally via `node scripts/generate-release-signing-key.js`; the matching private key was set as the `RELEASE_PQC_SIGNING_KEY` secret in the `npm-publish` GitHub Actions environment (same scope as `NPM_TOKEN`). The publish workflow's PQC sidecar step now finds both pieces present and computes a `<tarball>.mldsa.sig` for every release tarball. Self-verify-before-write inside `sign-release-artifact.js` catches a stale env-secret-vs-in-tree-pubkey mismatch — refuses to write a non-verifiable sig. · *`SECURITY.md` — `PQC release-signing key` fingerprint + verification recipe* — New SECURITY.md table records the algorithm (ML-DSA-65, FIPS 204), the in-tree public-key file path, and the SHA3-512 fingerprint (`ad6bee96…2ede`). Verification recipe uses the framework's own `b.pqcSoftware.ml_dsa_65.verify` — no external verifier binary required, no dependency on Sigstore's classical-crypto chain. Operators with a PQC-only verification posture have a self-contained path: `gh release download`, then `node -e` against the vendored noble-post-quantum primitive. **Changed:** *`Verifying release authenticity` — four trust roots, not three* — SECURITY.md's closing summary updated to count the ML-DSA-65 release-signing sidecar as the fourth independently-verifiable trust root, alongside SLSA L3 npm provenance + Sigstore-keyless SBOM signing + SSH-signed tags. Each remains verifiable without trusting any of the others; tampering with one is detected by the others. **References:** [FIPS 204 — ML-DSA](https://csrc.nist.gov/pubs/fips/204/final) · [FIPS 202 — SHA-3 + SHAKE](https://csrc.nist.gov/pubs/fips/202/final) · [RFC 9909 — ML-DSA in X.509 + CMS](https://www.rfc-editor.org/rfc/rfc9909.html) · [noble-post-quantum (vendored under lib/vendor)](https://github.com/paulmillr/noble-post-quantum)

package/index.js

@@ -373,6 +373,7 @@ var workerPool = require("./lib/worker-pool");
 var authBotChallenge = require("./lib/auth-bot-challenge");
 var sessionDeviceBinding = require("./lib/session-device-binding");
 var acme = require("./lib/acme");
+var cert = require("./lib/cert");
 var watcher = require("./lib/watcher");
 var localDbThin = require("./lib/local-db-thin");
 var daemon = require("./lib/daemon");
@@ -656,6 +657,7 @@ module.exports = {
   authBotChallenge: authBotChallenge,
   sessionDeviceBinding: sessionDeviceBinding,
   acme:             acme,
+  cert:             cert,
   ntpCheck:         ntpCheck,
   tlsExporter:      tlsExporter,
   watcher:          watcher,

package/lib/acme.js

@@ -679,6 +679,290 @@ function create(opts) {
     return pem;
   }
 
+  // ---- public: per-challenge authorization flow ----
+  //
+  // RFC 8555 §7.5 — authorization objects contain the challenge list.
+  // Fetching the authorization is POST-as-GET. The operator (or higher-
+  // level wrapper like `b.cert.create`) walks the challenges, provisions
+  // the response, then POSTs an empty object to the challenge URL to
+  // signal readiness, then polls the authorization until `status` is
+  // `valid` (or `invalid`).
+
+  /**
+   * @primitive b.acme.create.fetchAuthorization
+   * @signature b.acme.create.fetchAuthorization(authUrl)
+   * @since     0.11.22
+   *
+   * POST-as-GET an authorization URL. Returns the parsed authorization
+   * object — `{ status, identifier, challenges, expires, wildcard? }`
+   * per RFC 8555 §7.5. The challenges array lists every challenge type
+   * the CA offers for this authorization (`http-01`, `dns-01`,
+   * `tls-alpn-01`); each entry carries `{ type, url, token, status }`.
+   *
+   * @example
+   *   var auth = await client.fetchAuthorization(order.authorizations[0]);
+   *   var http01 = auth.challenges.find(function (c) { return c.type === "http-01"; });
+   *   typeof http01.token;         // → "string"
+   *   typeof http01.url;           // → "string"
+   */
+  async function fetchAuthorization(authUrl) {
+    if (typeof authUrl !== "string" || authUrl.length === 0) {
+      throw _err("acme/bad-auth-url",
+        "fetchAuthorization: authUrl must be a non-empty string", true);
+    }
+    var rsp = await _signedPost(authUrl, null);
+    if (rsp.statusCode < 200 || rsp.statusCode >= 300) {
+      throw _err("acme/auth-fetch",
+        "fetchAuthorization returned " + rsp.statusCode, true, rsp.statusCode);
+    }
+    var body = _parseJsonBody(rsp.body, "fetchAuthorization");
+    body.url = authUrl;
+    return body;
+  }
+
+  /**
+   * @primitive b.acme.create.notifyChallengeReady
+   * @signature b.acme.create.notifyChallengeReady(challengeUrl)
+   * @since     0.11.22
+   *
+   * POST an empty JSON object (`{}`) to a challenge URL to signal that
+   * the operator has provisioned the challenge response and the CA may
+   * now begin its validation attempt. Returns the updated challenge
+   * object (status typically `processing` immediately after this call).
+   *
+   * Per RFC 8555 §7.5.1: the empty-object POST is the operator's
+   * commitment that the validation surface is ready. The CA's
+   * validation runs asynchronously; poll the authorization with
+   * `waitForAuthorization` afterwards.
+   *
+   * @example
+   *   await myHttp01Server.add(challenge.token, client.keyAuthorization(challenge.token));
+   *   var updated = await client.notifyChallengeReady(challenge.url);
+   *   typeof updated.status;     // → "string" ("processing" | "valid" | "invalid")
+   */
+  async function notifyChallengeReady(challengeUrl) {
+    if (typeof challengeUrl !== "string" || challengeUrl.length === 0) {
+      throw _err("acme/bad-challenge-url",
+        "notifyChallengeReady: challengeUrl must be a non-empty string", true);
+    }
+    var rsp = await _signedPost(challengeUrl, {});
+    if (rsp.statusCode < 200 || rsp.statusCode >= 300) {
+      throw _err("acme/challenge-ready",
+        "notifyChallengeReady returned " + rsp.statusCode, true, rsp.statusCode);
+    }
+    return _parseJsonBody(rsp.body, "notifyChallengeReady");
+  }
+
+  /**
+   * @primitive b.acme.create.waitForAuthorization
+   * @signature b.acme.create.waitForAuthorization(authUrl, opts?)
+   * @since     0.11.22
+   *
+   * Poll an authorization URL until `status === "valid"` (success) or
+   * `status === "invalid"` (CA refused). Throws on invalid OR on
+   * timeout (default `pollMaxMs` set at `b.acme.create` time).
+   *
+   * @opts
+   *   intervalMs: number,    // default — uses the client's pollIntervalMs
+   *   timeoutMs:  number,    // default — uses the client's pollMaxMs
+   *
+   * @example
+   *   await client.notifyChallengeReady(http01.url);
+   *   var auth = await client.waitForAuthorization(authUrl);
+   *   auth.status;   // → "valid"
+   */
+  async function waitForAuthorization(authUrl, opts2) {
+    opts2 = opts2 || {};
+    var interval = typeof opts2.intervalMs === "number" ? opts2.intervalMs : pollIntervalMs;
+    var deadline = Date.now() + (typeof opts2.timeoutMs === "number" ? opts2.timeoutMs : pollMaxMs);
+    while (true) {
+      var auth = await fetchAuthorization(authUrl);
+      if (auth.status === "valid") return auth;
+      if (auth.status === "invalid") {
+        _emitAudit(audit, "acme.auth.poll", "failure",
+          { authUrl: authUrl, status: "invalid",
+            error: auth.challenges && auth.challenges.find(function (c) { return c.error; }) });
+        throw _err("acme/auth-invalid",
+          "waitForAuthorization: " + authUrl + " is invalid", true);
+      }
+      if (Date.now() >= deadline) {
+        throw _err("acme/auth-timeout",
+          "waitForAuthorization: " + authUrl + " did not reach 'valid' within " +
+          (opts2.timeoutMs || pollMaxMs) + "ms", true);
+      }
+      await _sleep(interval);
+    }
+  }
+
+  /**
+   * @primitive b.acme.create.buildCsr
+   * @signature b.acme.create.buildCsr(opts)
+   * @since     0.11.22
+   *
+   * Build a PKCS#10 (RFC 2986) Certificate Signing Request and sign it
+   * with the leaf private key. Subject is `CN=<first domain>`; every
+   * domain (including the first) appears as a `dNSName` in the
+   * Subject Alternative Name extension. Returns a PEM-encoded
+   * `-----BEGIN CERTIFICATE REQUEST-----` block ready to feed to
+   * `finalize(order, csrPem)`.
+   *
+   * Supports ECDSA P-256 / P-384 leaf keys (signed with `ecdsa-with-SHA256`
+   * / `ecdsa-with-SHA384` respectively) and RSA 2048 / 3072 / 4096
+   * (signed with `sha256WithRSAEncryption`). Ed25519 is rejected at
+   * the CSR layer because CA support is uneven; operators wanting
+   * Ed25519 certs build the CSR externally.
+   *
+   * @opts
+   *   privateKey: crypto.KeyObject,    // required — Node-crypto private key handle
+   *   publicKey:  crypto.KeyObject,    // required — matching public key handle
+   *   domains:    Array<string>,       // required — non-empty; first is CN, all are SANs
+   *
+   * @example
+   *   var pair = crypto.generateKeyPairSync("ec", { namedCurve: "P-256" });
+   *   var csr = client.buildCsr({
+   *     privateKey: pair.privateKey,
+   *     publicKey:  pair.publicKey,
+   *     domains:    ["example.com", "www.example.com"],
+   *   });
+   *   csr.indexOf("-----BEGIN CERTIFICATE REQUEST-----");  // → 0
+   */
+  function buildCsr(opts2) {
+    if (!opts2 || typeof opts2 !== "object") {
+      throw _err("acme/bad-csr-opts", "buildCsr: opts is required", true);
+    }
+    if (!opts2.privateKey || opts2.privateKey.type !== "private" ||
+        typeof opts2.privateKey.export !== "function") {
+      throw _err("acme/bad-csr-private-key",
+        "buildCsr: privateKey must be a Node KeyObject (private)", true);
+    }
+    if (!opts2.publicKey || opts2.publicKey.type !== "public" ||
+        typeof opts2.publicKey.export !== "function") {
+      throw _err("acme/bad-csr-public-key",
+        "buildCsr: publicKey must be a Node KeyObject (public)", true);
+    }
+    if (!Array.isArray(opts2.domains) || opts2.domains.length === 0) {
+      throw _err("acme/bad-csr-domains",
+        "buildCsr: domains must be a non-empty array of strings", true);
+    }
+    for (var di = 0; di < opts2.domains.length; di += 1) {
+      var d = opts2.domains[di];
+      if (typeof d !== "string" || d.length === 0 || d.length > C.BYTES.bytes(255)) {
+        throw _err("acme/bad-csr-domain",
+          "buildCsr: domains[" + di + "] must be a non-empty string <= 255 bytes", true);
+      }
+    }
+
+    var keyType = opts2.privateKey.asymmetricKeyType;
+    var keyDetails = opts2.privateKey.asymmetricKeyDetails || {};
+
+    // Pick signature algorithm based on key type.
+    var sigOidDotted, sigDigest, sigAlgoAlgId;
+    if (keyType === "ec") {
+      var curve = keyDetails.namedCurve;
+      if (curve === "prime256v1" || curve === "P-256") {
+        sigOidDotted = "1.2.840.10045.4.3.2";   // ecdsa-with-SHA256
+        sigDigest    = "sha256";
+      } else if (curve === "secp384r1" || curve === "P-384") {
+        sigOidDotted = "1.2.840.10045.4.3.3";   // ecdsa-with-SHA384
+        sigDigest    = "sha384";
+      } else {
+        throw _err("acme/bad-csr-curve",
+          "buildCsr: ECDSA curve '" + curve + "' is not supported (use P-256 or P-384)", true);
+      }
+      // For ECDSA the AlgorithmIdentifier has NO parameters (RFC 5758 §3.2).
+      sigAlgoAlgId = asn1.writeSequence([asn1.writeOid(sigOidDotted)]);
+    } else if (keyType === "rsa") {
+      sigOidDotted = "1.2.840.113549.1.1.11";   // sha256WithRSAEncryption
+      sigDigest    = "sha256";
+      // RSA AlgorithmIdentifier carries an explicit NULL parameter
+      // (RFC 8017 / RFC 3447 §A.2.4).
+      sigAlgoAlgId = asn1.writeSequence([asn1.writeOid(sigOidDotted), asn1.writeNull()]);
+    } else {
+      throw _err("acme/bad-csr-key-type",
+        "buildCsr: keyType '" + keyType + "' is not supported (use ECDSA P-256/P-384 or RSA 2048/3072/4096)", true);
+    }
+
+    // 1. Build Subject Name — single RDN: CN=<first domain> (UTF8String).
+    //    Name ::= SEQUENCE OF RelativeDistinguishedName
+    //    RelativeDistinguishedName ::= SET OF AttributeTypeAndValue
+    //    AttributeTypeAndValue ::= SEQUENCE { type OID, value ANY }
+    var commonName = opts2.domains[0];
+    var cnAttr = asn1.writeSequence([
+      asn1.writeOid("2.5.4.3"),                        // id-at-commonName
+      asn1.writeUtf8String(commonName),
+    ]);
+    var subjectName = asn1.writeSequence([
+      asn1.writeSet([cnAttr]),
+    ]);
+
+    // 2. Build SubjectPublicKeyInfo from the public KeyObject.
+    var spkiDer = opts2.publicKey.export({ type: "spki", format: "der" });
+
+    // 3. Build SubjectAltName extension — SEQUENCE OF GeneralName
+    //    GeneralName ::= CHOICE { ... [2] IA5String dNSName, ... }
+    //    dNSName has IMPLICIT [2] tag.
+    var sanGeneralNames = opts2.domains.map(function (d) {
+      // [2] IMPLICIT IA5String — context-specific class, primitive,
+      // tag number 2. asn1.writeContextImplicit assembles the value
+      // bytes (IA5 chars) directly without the inner UNIVERSAL IA5
+      // tag (that's what "implicit" means). Validation above already
+      // refuses non-string domains, so d is always a string here.
+      return asn1.writeContextImplicit(2, Buffer.from(d, "ascii"));
+    });
+    var sanExtnValue = asn1.writeSequence(sanGeneralNames);
+    // Extension ::= SEQUENCE { extnID OID, critical BOOLEAN DEFAULT FALSE, extnValue OCTET STRING }
+    var sanExtension = asn1.writeSequence([
+      asn1.writeOid("2.5.29.17"),                    // id-ce-subjectAltName
+      asn1.writeOctetString(sanExtnValue),
+    ]);
+
+    // 4. Build the extensionRequest attribute carrying the SAN.
+    //    Attribute ::= SEQUENCE { type OID, values SET OF ANY }
+    //    extensionRequest: type = 1.2.840.113549.1.9.14, values = SET OF Extensions
+    var extensionsSeq = asn1.writeSequence([sanExtension]);
+    var extensionReqAttr = asn1.writeSequence([
+      asn1.writeOid("1.2.840.113549.1.9.14"),         // pkcs-9-at-extensionRequest
+      asn1.writeSet([extensionsSeq]),
+    ]);
+
+    // 5. Build CertificationRequestInfo.
+    //    CertificationRequestInfo ::= SEQUENCE {
+    //      version       INTEGER (0),
+    //      subject       Name,
+    //      subjectPKInfo SubjectPublicKeyInfo,
+    //      attributes    [0] IMPLICIT Attributes
+    //    }
+    //    [0] IMPLICIT SET OF Attribute — we wrap the existing attr set.
+    var attributesField = asn1.writeContextImplicit(0,
+      Buffer.concat([extensionReqAttr]),       // SET OF Attribute is implicit; one attribute → just its encoding
+      { constructed: true });
+    var certReqInfo = asn1.writeSequence([
+      asn1.writeInteger(Buffer.from([0])),     // version v1 = 0
+      subjectName,
+      spkiDer,
+      attributesField,
+    ]);
+
+    // 6. Sign certReqInfo with the leaf private key.
+    var signer = nodeCrypto.createSign(sigDigest);
+    signer.update(certReqInfo);
+    var signature = signer.sign(opts2.privateKey);
+
+    // 7. Wrap as CertificationRequest.
+    var csr = asn1.writeSequence([
+      certReqInfo,
+      sigAlgoAlgId,
+      asn1.writeBitString(signature, 0),
+    ]);
+
+    // 8. PEM-encode.
+    var b64 = csr.toString("base64");
+    var pemBody = b64.match(/.{1,64}/g).join("\n");
+    return "-----BEGIN CERTIFICATE REQUEST-----\n" +
+           pemBody + "\n" +
+           "-----END CERTIFICATE REQUEST-----\n";
+  }
+
   // ---- public: RFC 9773 ARI ----
 
   async function fetchAri(opts2) {
@@ -1077,6 +1361,10 @@ function create(opts) {
     newOrder:        newOrder,
     finalize:        finalize,
     retrieveCert:    retrieveCert,
+    fetchAuthorization:    fetchAuthorization,
+    notifyChallengeReady:  notifyChallengeReady,
+    waitForAuthorization:  waitForAuthorization,
+    buildCsr:        buildCsr,
     fetchAri:        fetchAri,
     renewIfDue:      renewIfDue,
     revokeCert:      revokeCert,

package/lib/asn1-der.js

@@ -325,6 +325,67 @@ function writeContextExplicit(tagNumber, child) {
   return writeNode(tagByte, child);
 }
 
+function writeContextImplicit(tagNumber, value, opts) {
+  // [N] IMPLICIT — context-specific class with no constructed flag for
+  // primitives; opts.constructed=true sets the constructed bit for
+  // wrapping a structured value (e.g. IMPLICIT [0] OCTET STRING vs
+  // IMPLICIT [0] SEQUENCE OF). Value is the raw inner bytes (already
+  // encoded for constructed cases).
+  var tagByte = 0x80 | (tagNumber & 0x1f);                                       // allow:raw-byte-literal — context-specific primitive mask
+  if (opts && opts.constructed) tagByte |= 0x20;                                 // allow:raw-byte-literal — constructed bit
+  return writeNode(tagByte, value);
+}
+
+function writeBitString(value, unusedBits) {
+  // BIT STRING — first content byte is `unusedBits` (0..7), then the
+  // bit string bytes. `unusedBits` is 0 for byte-aligned content
+  // (RSA / ECDSA signatures, SubjectPublicKeyInfo bit strings).
+  var unused = typeof unusedBits === "number" ? (unusedBits & 0x07) : 0;         // allow:raw-byte-literal — 3-bit unused-bits count
+  return writeNode(TAG.BIT_STRING, Buffer.concat([Buffer.from([unused]), value]));
+}
+
+function writeSet(children) {
+  // children: Array<Buffer> of already-encoded child nodes.
+  // DER requires SET-OF children to be sorted by their encoded bytes.
+  var sorted = children.slice().sort(Buffer.compare);
+  return writeNode(TAG.SET | 0x20, Buffer.concat(sorted));                       // allow:raw-byte-literal — DER constructed bit
+}
+
+function writeUtf8String(s) {
+  if (typeof s !== "string") {
+    throw new Asn1Error("asn1/bad-utf8-input",
+      "writeUtf8String: input must be a string (got " + typeof s + ")");
+  }
+  return writeNode(TAG.UTF8_STRING, Buffer.from(s, "utf8"));
+}
+
+function writePrintableString(s) {
+  // PrintableString character set: A-Z a-z 0-9 ' ( ) + , - . / : = ? space
+  // Refuse non-printable input rather than silently encoding as latin1.
+  var str = String(s);
+  if (/[^A-Za-z0-9 '()+,\-./:=?]/.test(str)) {
+    throw new Asn1Error("asn1/bad-printable",
+      "writePrintableString: '" + str + "' contains characters outside the PrintableString set");
+  }
+  return writeNode(TAG.PRINTABLE_STRING, Buffer.from(str, "ascii"));
+}
+
+function writeIa5String(s) {
+  // IA5String is 7-bit ASCII. RFC 5280 §4.2.1.6 mandates IA5String for
+  // dNSName values inside the SubjectAltName extension.
+  var str = String(s);
+  /* eslint-disable-next-line no-control-regex */
+  if (/[^\x00-\x7f]/.test(str)) {
+    throw new Asn1Error("asn1/bad-ia5",
+      "writeIa5String: '" + str + "' contains non-ASCII characters");
+  }
+  return writeNode(TAG.IA5_STRING, Buffer.from(str, "ascii"));
+}
+
+function writeBoolean(b) {
+  return writeNode(TAG.BOOLEAN, Buffer.from([b ? 0xff : 0x00]));                 // allow:raw-byte-literal — DER true=0xff, false=0x00
+}
+
 // Find a child node of a SEQUENCE / SET by predicate. Returns null if
 // no child matches.
 function findChild(children, predicate) {
@@ -351,6 +412,13 @@ module.exports = {
   writeInteger:        writeInteger,
   writeNull:           writeNull,
   writeOid:            writeOid,
+  writeBitString:      writeBitString,
+  writeSet:            writeSet,
+  writeUtf8String:     writeUtf8String,
+  writePrintableString: writePrintableString,
+  writeIa5String:      writeIa5String,
+  writeBoolean:        writeBoolean,
   writeContextExplicit: writeContextExplicit,
+  writeContextImplicit: writeContextImplicit,
   Asn1Error:           Asn1Error,
 };

package/lib/audit.js

@@ -306,6 +306,7 @@ var FRAMEWORK_NAMESPACES = [
   "http",       // b.middleware.bodyParser (http.chunked.malformed.refused — RFC 9112 §7.1 chunked-decode failure with Connection: close) // allow:raw-byte-literal — RFC number in prose
   "cryptofield", // b.cryptoField.eraseRow (cryptofield.vacuum.skipped — F-RTBF-2 vacuum-after-erase signal when DB not initialized at erase time)
   "acme",       // b.acme (acme.account.registered / order.* / cert.issued / cert.renewed / cert.renew.skipped — RFC 8555 + RFC 9773 ARI workflow)
+  "cert",       // b.cert (cert.account.generated / cert.issued / cert.renewed / cert.renew-failed / cert.challenge-cleanup — turnkey cert-manager lifecycle)
   "tls",        // b.router 0-RTT posture (tls.0rtt.refused / tls.0rtt.replayed) — RFC 8446 §8 anti-replay surface // allow:raw-byte-literal — RFC number in prose
   "workerpool", // b.workerPool (workerpool.created / terminated / task.completed / task.failed / task.timeout / spawn.failed — generic worker_threads pool)
   "jwt",        // b.auth.jwt-external (jwt.jwe.refused — RFC 7516 5-segment JWE refusal)

package/lib/cert.js

@@ -0,0 +1,763 @@
+"use strict";
+/**
+ * @module b.cert
+ * @nav    Production
+ * @title  Certificates
+ * @order  130
+ *
+ * @intro
+ *   Turnkey TLS-certificate manager. Wraps `b.acme.create` (RFC 8555
+ *   client + RFC 9773 ARI renewal-window respect), sealed persistence
+ *   via `b.vault.seal`, the renewal scheduler from `b.safeAsync.repeating`,
+ *   OCSP-stapling via `b.network.tls.ocsp`, and the operator's choice
+ *   of ACME challenge solver (HTTP-01 / DNS-01 / TLS-ALPN-01).
+ *
+ *   The operator passes a declarative manifest of certificates +
+ *   storage + an ACME directory URL + per-challenge solver callbacks;
+ *   the manager handles ordering, finalization, retrieval, periodic
+ *   renewal, key rotation on renew, OCSP refresh, and sealed-disk
+ *   persistence of every artifact.
+ *
+ *   Composes:
+ *     - `b.acme.create`         → ACME orders, JWS, ARI fetch
+ *     - `b.vault.seal`          → sealed-disk persistence of certs + keys + account material
+ *     - `b.safeAsync.repeating` → renewal scheduler with drop-silent error path
+ *     - `b.network.tls.ocsp`    → server-side stapling helpers
+ *     - `b.audit`               → cert.* lifecycle audit chain
+ *     - `b.compliance`          → posture refusals (e.g. plaintext storage refused under HIPAA / PCI)
+ *
+ *   Does NOT ship the challenge-solver implementations (HTTP-01 server,
+ *   DNS provider integrations, TLS-ALPN-01 socket). Those are operator-
+ *   side adapters — the manager calls operator-provided
+ *   `provision(challengeParams)` / `cleanup(challengeParams)` callbacks
+ *   for whatever solver the operator wires.
+ *
+ *   Key escrow: when `keyEscrow: { recipient }` is set, the renewed
+ *   private key is also encrypted to the recipient's public key via
+ *   `b.crypto.encryptEnvelope` and persisted alongside the sealed key.
+ *   The recipient is operator-controlled (typically an offline
+ *   break-glass key); the escrow copy is for legitimate key-recovery
+ *   under break-glass policy, NOT for routine access.
+ *
+ * @card
+ *   ACME-driven cert lifecycle: auto-renew + key rotation + OCSP stapling + sealed persistence.
+ */
+
+var nodeCrypto    = require("node:crypto");
+var nodeFs        = require("node:fs");
+var nodePath      = require("node:path");
+var EventEmitter  = require("node:events").EventEmitter;
+var validateOpts  = require("./validate-opts");
+var lazyRequire   = require("./lazy-require");
+var safeAsync     = require("./safe-async");
+var atomicFile    = require("./atomic-file");
+var safeJson      = require("./safe-json");
+var { defineClass } = require("./framework-error");
+var C             = require("./constants");
+
+var acme          = lazyRequire(function () { return require("./acme"); });
+var vault         = lazyRequire(function () { return require("./vault"); });
+var audit         = lazyRequire(function () { return require("./audit"); });
+var networkTls    = lazyRequire(function () { return require("./network-tls"); });
+var bCrypto       = lazyRequire(function () { return require("./crypto"); });
+
+var CertError = defineClass("CertError");
+
+var DEFAULT_RENEW_INTERVAL_MS    = C.TIME.hours(6);
+var DEFAULT_MIN_DAYS_BEFORE_EXPIRY = 14;
+var DEFAULT_OCSP_REFRESH_MS      = C.TIME.hours(12);
+var MAX_DOMAINS_PER_CERT         = 100;                                              // allow:raw-byte-literal — operator-facing manifest size cap, not a byte count (RFC 6066 SNI permits more)
+var MAX_CERTS_PER_MANAGER        = 1000;                                             // allow:raw-byte-literal — operator-facing manifest size cap, not a byte count
+
+function _positiveFiniteOrDefault(value, defaultValue, label, code) {
+  if (value === undefined || value === null) return defaultValue;
+  if (typeof value !== "number" || !isFinite(value) || value <= 0) {
+    throw new CertError(code, label + " must be a positive finite number (got " + value + ")");
+  }
+  return value;
+}
+
+// ---- Storage backend ----
+
+// Sealed-disk storage: each artifact (cert PEM, key PEM, ACME account
+// JWK, OCSP response) is sealed via b.vault.seal and written atomically
+// to a per-cert subdirectory under storage.rootDir.
+//
+// Layout:
+//   <rootDir>/account/jwk.json.sealed     — sealed ACME account key
+//   <rootDir>/account/jwk.json.escrow     — optional break-glass copy (if keyEscrow set)
+//   <rootDir>/<certName>/cert.pem.sealed  — sealed certificate chain (CA + leaf)
+//   <rootDir>/<certName>/key.pem.sealed   — sealed leaf private key
+//   <rootDir>/<certName>/key.pem.escrow   — optional break-glass copy
+//   <rootDir>/<certName>/ocsp.der.sealed  — sealed cached OCSP response (refreshed periodically)
+//   <rootDir>/<certName>/meta.json        — plaintext metadata (expiresAt, fingerprint, last-renewed-at)
+function _createSealedDiskStorage(opts) {
+  validateOpts.requireNonEmptyString(opts.rootDir,
+    "cert.storage: rootDir (sealed-disk root directory) is required",
+    CertError, "cert/bad-storage-root");
+  var rootDir = nodePath.resolve(opts.rootDir);
+  var vaultStore = opts.vault || vault().getDefaultStore();
+  if (!vaultStore || typeof vaultStore.seal !== "function" || typeof vaultStore.unseal !== "function") {
+    throw new CertError("cert/bad-storage-vault",
+      "cert.storage: vault must expose seal(buf) + unseal(buf) — typically b.vault.getDefaultStore()");
+  }
+
+  function _ensureDir(dir) { atomicFile.ensureDir(dir); }
+  function _certDir(name)  { return nodePath.join(rootDir, name); }
+  function _accountDir()    { return nodePath.join(rootDir, "account"); }
+
+  return {
+    type: "sealed-disk",
+    rootDir: rootDir,
+
+    async writeSealed(relPath, contents) {
+      // Sealed artifacts always carry the `.sealed` suffix so a
+      // directory listing instantly distinguishes encrypted material
+      // from plaintext meta.json. relPath is the logical name (e.g.
+      // "main/cert.pem"); the on-disk path is "main/cert.pem.sealed".
+      var p = nodePath.join(rootDir, relPath + ".sealed");
+      _ensureDir(nodePath.dirname(p));
+      var sealed = vaultStore.seal(Buffer.from(contents));
+      atomicFile.writeSync(p, sealed, { mode: 0o600 });
+    },
+
+    async readSealed(relPath) {
+      var p = nodePath.join(rootDir, relPath + ".sealed");
+      if (!nodeFs.existsSync(p)) return null;
+      var sealed = nodeFs.readFileSync(p);
+      var plain = vaultStore.unseal(sealed);
+      return Buffer.isBuffer(plain) ? plain : Buffer.from(plain);
+    },
+
+    async writeMeta(certName, meta) {
+      var p = nodePath.join(_certDir(certName), "meta.json");
+      _ensureDir(_certDir(certName));
+      atomicFile.writeSync(p, JSON.stringify(meta, null, 2) + "\n", { mode: 0o644 });
+    },
+
+    async readMeta(certName) {
+      var p = nodePath.join(_certDir(certName), "meta.json");
+      if (!nodeFs.existsSync(p)) return null;
+      try { return safeJson.parse(nodeFs.readFileSync(p, "utf8"), { maxBytes: C.BYTES.kib(16) }); }
+      catch (e) {
+        throw new CertError("cert/bad-meta",
+          "cert: meta.json for '" + certName + "' is corrupt: " + e.message);
+      }
+    },
+
+    async writeEscrow(relPath, plaintextKeyPem, recipientPub) {
+      // Encrypt-to-recipient via b.crypto.encryptEnvelope. Recipient is
+      // an X25519 / ML-KEM hybrid pubkey held offline by the operator
+      // for break-glass key recovery.
+      var envelope = bCrypto().encryptEnvelope(Buffer.from(plaintextKeyPem), recipientPub);
+      var p = nodePath.join(rootDir, relPath);
+      _ensureDir(nodePath.dirname(p));
+      atomicFile.writeSync(p, JSON.stringify(envelope) + "\n", { mode: 0o600 });
+    },
+  };
+}
+
+// ---- Cert manager factory ----
+
+/**
+ * @primitive b.cert.create
+ * @signature b.cert.create(opts)
+ * @since     0.11.22
+ * @status    stable
+ * @related   b.acme.create
+ *
+ * Build a turnkey cert-management handle. Composes `b.acme.create` for
+ * the ACME protocol layer, `b.vault.seal` for sealed-disk persistence,
+ * `b.safeAsync.repeating` for the renewal scheduler, and
+ * `b.network.tls.ocsp` for stapling.
+ *
+ * The handle exposes:
+ *   - `start()`           — ensures every manifest cert exists (issues if absent); starts the renewal scheduler.
+ *   - `stop()`            — halts the renewal scheduler; releases sealed handles.
+ *   - `getContext(name)`  — returns `{ cert, key, ca, expiresAt, fingerprintSha256 }` (PEM strings + meta) for the named cert.
+ *   - `sniCallback`       — function (servername, cb) suitable for `https.createServer({ SNICallback })` — looks up by SNI hostname, falls back to the first registered cert.
+ *   - `refresh(name)`     — force-renew the named cert NOW (operator override).
+ *   - `on(event, fn)`     — `cert.issued` / `cert.renewed` / `cert.renew-failed` / `cert.ocsp-refreshed`.
+ *
+ * @opts
+ *   storage: {
+ *     type:    "sealed-disk",         // only backend in v1 — operator-supplied storage extensible via the same shape
+ *     rootDir: string,                // required — directory under which sealed artifacts land
+ *     vault:   b.vault.Store,         // optional — defaults to b.vault.getDefaultStore()
+ *   },
+ *   acme: {
+ *     directory:    string,           // required — RFC 8555 directory URL (https://)
+ *     contactEmail: string,           // optional — mailto: contact registered on account
+ *     accountKey:   { privatePem, publicPem } | "auto",   // "auto" → generate + persist on first start; sealed via storage.vault
+ *     timeoutMs:    number,           // optional — per-HTTP-call timeout; defaults from b.acme.create
+ *     ariCompliant: boolean,          // optional, default true — RFC 9773 ARI renewalInfo respect
+ *   },
+ *   certs: Array<{
+ *     name:      string,              // required — unique manifest identifier; used as subdirectory + lookup key
+ *     domains:   Array<string>,       // required — first entry is the CN subject; rest are SANs
+ *     keyAlg:    "ecdsa-p256" | "ecdsa-p384" | "rsa-2048" | "rsa-3072" | "rsa-4096", // default "ecdsa-p256"
+ *     challenge: {
+ *       type:      "http-01" | "dns-01" | "tls-alpn-01",
+ *       provision: async function (params) { ... },     // required — operator wires the solver
+ *       cleanup:   async function (params) { ... },     // required — runs after authorization completes
+ *     },
+ *     keyEscrow: {                    // optional — break-glass-only key recovery
+ *       recipient: Buffer | string,   // X25519 / ML-KEM hybrid public key (b.crypto.encryptEnvelope recipient)
+ *     },
+ *   }>,
+ *   renew: {
+ *     intervalMs:          number,    // default 6h — poll cadence
+ *     minDaysBeforeExpiry: number,    // default 14 — renew if <N days remaining (or ARI says renew sooner)
+ *     ariCompliant:        boolean,   // default true — respect ARI suggestedWindow when CA publishes it
+ *   },
+ *   ocsp: {
+ *     stapling:   boolean,            // default true — refresh + cache OCSP responses for server-side stapling
+ *     refreshMs:  number,             // default 12h — OCSP-response cache lifetime
+ *   },
+ *   audit:    boolean | object,       // default true — emit cert.* lifecycle events via b.audit.safeEmit
+ *   compliance: Array<string>,         // optional — posture refusals (e.g. ["hipaa"]); refuses plaintext storage etc.
+ *
+ * @example
+ *   var mgr = b.cert.create({
+ *     storage: { type: "sealed-disk", rootDir: "/var/lib/blamejs/certs" },
+ *     acme: {
+ *       directory:    "https://acme-v02.api.letsencrypt.org/directory",
+ *       contactEmail: "ops@example.com",
+ *       accountKey:   "auto",
+ *     },
+ *     certs: [
+ *       {
+ *         name:      "main",
+ *         domains:   ["example.com", "www.example.com"],
+ *         keyAlg:    "ecdsa-p256",
+ *         challenge: {
+ *           type:      "http-01",
+ *           provision: async function (p) { await myHttp01Server.add(p.token, p.keyAuthorization); },
+ *           cleanup:   async function (p) { await myHttp01Server.remove(p.token); },
+ *         },
+ *       },
+ *     ],
+ *   });
+ *   await mgr.start();
+ *   var ctx = await mgr.getContext("main");
+ *   typeof ctx.cert;     // → "string" (PEM chain)
+ *   typeof ctx.key;      // → "string" (PEM)
+ *   typeof ctx.expiresAt; // → "number" (epoch ms)
+ */
+function create(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new CertError("cert/bad-opts", "cert.create: opts is required");
+  }
+  validateOpts(opts, [
+    "storage", "acme", "certs", "renew", "ocsp", "audit", "compliance",
+  ], "cert.create");
+
+  // ---- Storage ----
+  if (!opts.storage || typeof opts.storage !== "object") {
+    throw new CertError("cert/bad-storage", "cert.create: storage block is required");
+  }
+  var storageType = opts.storage.type || "sealed-disk";
+  if (storageType !== "sealed-disk") {
+    throw new CertError("cert/bad-storage-type",
+      "cert.create: storage.type must be 'sealed-disk' (the only backend in v1)");
+  }
+  var storage = _createSealedDiskStorage(opts.storage);
+
+  // ---- ACME opts ----
+  if (!opts.acme || typeof opts.acme !== "object") {
+    throw new CertError("cert/bad-acme", "cert.create: acme block is required");
+  }
+  validateOpts(opts.acme,
+    ["directory", "contactEmail", "accountKey", "timeoutMs", "ariCompliant"],
+    "cert.create.acme");
+  validateOpts.requireNonEmptyString(opts.acme.directory,
+    "cert.create.acme: directory (RFC 8555 directory URL) is required",
+    CertError, "cert/bad-acme-directory");
+
+  // ---- Cert manifest ----
+  if (!Array.isArray(opts.certs) || opts.certs.length === 0) {
+    throw new CertError("cert/bad-certs",
+      "cert.create: certs must be a non-empty array of cert manifests");
+  }
+  if (opts.certs.length > MAX_CERTS_PER_MANAGER) {
+    throw new CertError("cert/too-many-certs",
+      "cert.create: certs array length " + opts.certs.length + " exceeds cap " + MAX_CERTS_PER_MANAGER);
+  }
+  // Cert names land as filesystem path segments under storage.rootDir
+  // (e.g. `<rootDir>/<name>/cert.pem.sealed`). Restrict the character
+  // set to ASCII letters / digits / `-` / `_` / `.` and refuse any
+  // value containing `/`, `\`, `..`, leading dot, or non-printable
+  // chars. Manifests sourced from operator-editable config or external
+  // control planes can carry attacker-influenced names; this gate
+  // refuses path-traversal payloads at the factory boundary instead
+  // of relying on `path.join` to sanitize.
+  var CERT_NAME_ALLOWED = /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}$/;
+  var certsByName = Object.create(null);
+  for (var i = 0; i < opts.certs.length; i += 1) {
+    var c = opts.certs[i];
+    validateOpts.requireNonEmptyString(c.name,
+      "cert.create.certs[" + i + "].name is required",
+      CertError, "cert/bad-cert-name");
+    if (!CERT_NAME_ALLOWED.test(c.name) || c.name.indexOf("..") !== -1) {
+      throw new CertError("cert/bad-cert-name",
+        "cert.create.certs[" + i + "].name '" + c.name +
+        "' must match [A-Za-z0-9_][A-Za-z0-9_.-]{0,63} and contain no '..' " +
+        "(name lands as a filesystem path segment under storage.rootDir)");
+    }
+    if (certsByName[c.name]) {
+      throw new CertError("cert/duplicate-name",
+        "cert.create.certs: duplicate name '" + c.name + "'");
+    }
+    if (!Array.isArray(c.domains) || c.domains.length === 0) {
+      throw new CertError("cert/bad-domains",
+        "cert.create.certs[" + i + "].domains must be a non-empty array");
+    }
+    if (c.domains.length > MAX_DOMAINS_PER_CERT) {
+      throw new CertError("cert/too-many-domains",
+        "cert.create.certs[" + i + "].domains length " + c.domains.length + " exceeds cap " + MAX_DOMAINS_PER_CERT);
+    }
+    for (var di = 0; di < c.domains.length; di += 1) {
+      if (typeof c.domains[di] !== "string" || !c.domains[di]) {
+        throw new CertError("cert/bad-domain",
+          "cert.create.certs[" + i + "].domains[" + di + "] must be a non-empty string");
+      }
+    }
+    if (!c.challenge || typeof c.challenge !== "object") {
+      throw new CertError("cert/bad-challenge",
+        "cert.create.certs[" + i + "].challenge is required");
+    }
+    if (["http-01", "dns-01", "tls-alpn-01"].indexOf(c.challenge.type) === -1) {
+      throw new CertError("cert/bad-challenge-type",
+        "cert.create.certs[" + i + "].challenge.type must be http-01 / dns-01 / tls-alpn-01");
+    }
+    if (typeof c.challenge.provision !== "function" ||
+        typeof c.challenge.cleanup   !== "function") {
+      throw new CertError("cert/bad-challenge-callbacks",
+        "cert.create.certs[" + i + "].challenge requires provision + cleanup callbacks");
+    }
+    var keyAlg = c.keyAlg || "ecdsa-p256";
+    if (["ecdsa-p256", "ecdsa-p384", "rsa-2048", "rsa-3072", "rsa-4096"].indexOf(keyAlg) === -1) {
+      throw new CertError("cert/bad-key-alg",
+        "cert.create.certs[" + i + "].keyAlg must be ecdsa-p256 / ecdsa-p384 / rsa-2048 / rsa-3072 / rsa-4096");
+    }
+    if (c.keyEscrow && (!c.keyEscrow.recipient ||
+        (typeof c.keyEscrow.recipient !== "string" && !Buffer.isBuffer(c.keyEscrow.recipient)))) {
+      throw new CertError("cert/bad-key-escrow",
+        "cert.create.certs[" + i + "].keyEscrow.recipient must be a Buffer or PEM/base64 string");
+    }
+    certsByName[c.name] = {
+      name:      c.name,
+      domains:   c.domains.slice(),
+      keyAlg:    keyAlg,
+      challenge: c.challenge,
+      keyEscrow: c.keyEscrow || null,
+    };
+  }
+
+  // ---- Renewal scheduler opts ----
+  var renewOpts = opts.renew || {};
+  validateOpts(renewOpts, ["intervalMs", "minDaysBeforeExpiry", "ariCompliant"],
+    "cert.create.renew");
+  var renewIntervalMs = _positiveFiniteOrDefault(
+    renewOpts.intervalMs, DEFAULT_RENEW_INTERVAL_MS,
+    "cert.create.renew.intervalMs", "cert/bad-renew-interval");
+  var minDaysBeforeExpiry = _positiveFiniteOrDefault(
+    renewOpts.minDaysBeforeExpiry, DEFAULT_MIN_DAYS_BEFORE_EXPIRY,
+    "cert.create.renew.minDaysBeforeExpiry", "cert/bad-renew-window");
+  var ariCompliant = renewOpts.ariCompliant !== false;
+
+  // ---- OCSP opts ----
+  var ocspOpts = opts.ocsp || {};
+  validateOpts(ocspOpts, ["stapling", "refreshMs"], "cert.create.ocsp");
+  var ocspStapling = ocspOpts.stapling !== false;
+  var ocspRefreshMs = _positiveFiniteOrDefault(
+    ocspOpts.refreshMs, DEFAULT_OCSP_REFRESH_MS,
+    "cert.create.ocsp.refreshMs", "cert/bad-ocsp-refresh");
+
+  // ---- Audit + compliance ----
+  var auditEnabled = opts.audit !== false;
+  var compliance = Array.isArray(opts.compliance) ? opts.compliance.slice() : [];
+
+  // ---- Internal state ----
+  var emitter = new EventEmitter();
+  var loadedContexts = Object.create(null);   // name → { cert, key, ca, expiresAt, fingerprintSha256, sniNames }
+  var acmeClient = null;
+  var scheduler = null;
+  var stopped = false;
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditEnabled) return;
+    try {
+      audit().safeEmit({ action: action, outcome: outcome, metadata: metadata || {} });
+    } catch (_e) { /* drop-silent — audit emission is hot-path */ }
+  }
+
+  function _bootAcme() {
+    if (acmeClient) return acmeClient;
+    var accountKey = opts.acme.accountKey;
+    if (accountKey === "auto" || !accountKey) {
+      accountKey = _loadOrGenerateAccountKey();
+    }
+    acmeClient = acme().create({
+      directory:    opts.acme.directory,
+      accountKey:   accountKey,
+      contact:      opts.acme.contactEmail ? ["mailto:" + opts.acme.contactEmail] : undefined,
+      timeoutMs:    opts.acme.timeoutMs,
+    });
+    return acmeClient;
+  }
+
+  function _loadOrGenerateAccountKey() {
+    // Read sealed account JWK; generate + persist if absent.
+    var sealedBuf = nodeFs.existsSync(nodePath.join(storage.rootDir, "account/jwk.json.sealed"))
+      ? nodeFs.readFileSync(nodePath.join(storage.rootDir, "account/jwk.json.sealed"))
+      : null;
+    if (sealedBuf) {
+      var plain = (opts.storage.vault || vault().getDefaultStore()).unseal(sealedBuf);
+      var jwk = safeJson.parse(plain.toString("utf8"), { maxBytes: C.BYTES.kib(64) });
+      return _accountKeyFromJwk(jwk);
+    }
+    var pair = nodeCrypto.generateKeyPairSync("ec", { namedCurve: "P-256" });
+    var privatePem = pair.privateKey.export({ type: "pkcs8", format: "pem" });
+    var publicPem  = pair.publicKey.export({ type: "spki", format: "pem" });
+    var freshJwk = pair.publicKey.export({ format: "jwk" });
+    freshJwk.privatePem = privatePem;
+    freshJwk.publicPem  = publicPem;
+    storage.writeSealed("account/jwk.json", JSON.stringify(freshJwk));
+    _emitAudit("cert.account.generated", "success", { directory: opts.acme.directory });
+    return _accountKeyFromJwk(freshJwk);
+  }
+
+  function _accountKeyFromJwk(jwk) {
+    return {
+      privatePem: jwk.privatePem,
+      publicPem:  jwk.publicPem,
+      jwk:        { kty: jwk.kty, crv: jwk.crv, x: jwk.x, y: jwk.y },
+      kty:        jwk.kty,
+      crv:        jwk.crv,
+    };
+  }
+
+  // RSA modulus bits — operator-selected protocol constants, not byte
+  // counts. The framework's leaf-key alg names embed the bit length
+  // verbatim ("rsa-2048" / "rsa-3072" / "rsa-4096"), so the literals
+  // here are protocol-constant references.
+  var RSA_MODULUS_BITS_2048 = 2048;                                                  // allow:raw-byte-literal — RSA modulus length, not a byte count
+  var RSA_MODULUS_BITS_3072 = 3072;                                                  // allow:raw-byte-literal — RSA modulus length, not a byte count
+  var RSA_MODULUS_BITS_4096 = 4096;                                                  // allow:raw-byte-literal — RSA modulus length, not a byte count
+
+  function _generateLeafKeypair(keyAlg) {
+    switch (keyAlg) {
+      case "ecdsa-p256": return nodeCrypto.generateKeyPairSync("ec", { namedCurve: "P-256" });
+      case "ecdsa-p384": return nodeCrypto.generateKeyPairSync("ec", { namedCurve: "P-384" });
+      case "rsa-2048":   return nodeCrypto.generateKeyPairSync("rsa", { modulusLength: RSA_MODULUS_BITS_2048 });
+      case "rsa-3072":   return nodeCrypto.generateKeyPairSync("rsa", { modulusLength: RSA_MODULUS_BITS_3072 });
+      case "rsa-4096":   return nodeCrypto.generateKeyPairSync("rsa", { modulusLength: RSA_MODULUS_BITS_4096 });
+      default:
+        throw new CertError("cert/bad-key-alg", "cert: unknown keyAlg " + keyAlg);
+    }
+  }
+
+  async function _issueCert(certManifest) {
+    var acme = _bootAcme();
+    // 1. Fetch directory + ensure ACME account exists.
+    await acme.fetchDirectory();
+    await acme.newAccount({
+      contact:              opts.acme.contactEmail ? ["mailto:" + opts.acme.contactEmail] : undefined,
+      termsOfServiceAgreed: true,
+    });
+    // 2. Create the order.
+    var order = await acme.newOrder({
+      identifiers: certManifest.domains.map(function (d) {
+        return { type: "dns", value: d };
+      }),
+    });
+    // 3. For each authorization, solve the operator-supplied challenge.
+    for (var ai = 0; ai < order.authorizations.length; ai += 1) {
+      var auth = await acme.fetchAuthorization(order.authorizations[ai]);
+      if (auth.status === "valid") continue;
+      var challenge = auth.challenges.find(function (ch) {
+        return ch.type === certManifest.challenge.type;
+      });
+      if (!challenge) {
+        throw new CertError("cert/no-matching-challenge",
+          "cert: CA did not offer " + certManifest.challenge.type +
+          " for " + auth.identifier.value);
+      }
+      // tls-alpn-01 has a different key-authorization shape (RFC 8737).
+      var keyAuth = certManifest.challenge.type === "tls-alpn-01"
+        ? acme.tlsAlpn01KeyAuthorization(challenge.token)
+        : acme.keyAuthorization(challenge.token);
+      var provisionParams = {
+        domain:           auth.identifier.value,
+        type:             challenge.type,
+        token:            challenge.token,
+        keyAuthorization: keyAuth,
+      };
+      await certManifest.challenge.provision(provisionParams);
+      try {
+        await acme.notifyChallengeReady(challenge.url);
+        await acme.waitForAuthorization(order.authorizations[ai]);
+      } finally {
+        try { await certManifest.challenge.cleanup(provisionParams); }
+        catch (cleanupErr) {
+          // Cleanup failure shouldn't void the order, but the
+          // operator should know — emit drop-silent audit.
+          _emitAudit("cert.challenge-cleanup", "failure", {
+            name:   certManifest.name,
+            domain: auth.identifier.value,
+            error:  (cleanupErr && cleanupErr.message) || String(cleanupErr),
+          });
+        }
+      }
+    }
+    // 4. Generate leaf keypair + CSR + finalize.
+    var leafPair = _generateLeafKeypair(certManifest.keyAlg);
+    var csrPem = acme.buildCsr({
+      privateKey: leafPair.privateKey,
+      publicKey:  leafPair.publicKey,
+      domains:    certManifest.domains,
+    });
+    var finalized = await acme.finalize(order, csrPem);
+    var certPem = await acme.retrieveCert(finalized);
+    var privPem = leafPair.privateKey.export({ type: "pkcs8", format: "pem" });
+    return { certPem: certPem, keyPem: privPem };
+  }
+
+  function _certMeta(certPem) {
+    // Extract notAfter + fingerprint without re-implementing X.509.
+    var cert = new nodeCrypto.X509Certificate(certPem);
+    return {
+      expiresAt:         Date.parse(cert.validTo),
+      issuedAt:          Date.parse(cert.validFrom),
+      fingerprintSha256: cert.fingerprint256.replace(/:/g, "").toLowerCase(),
+      subject:           cert.subject,
+      subjectAltName:    cert.subjectAltName || null,
+    };
+  }
+
+  async function _persistCert(certManifest, certPem, keyPem) {
+    await storage.writeSealed(certManifest.name + "/cert.pem", certPem);
+    await storage.writeSealed(certManifest.name + "/key.pem", keyPem);
+    if (certManifest.keyEscrow) {
+      await storage.writeEscrow(certManifest.name + "/key.pem.escrow", keyPem,
+        certManifest.keyEscrow.recipient);
+    }
+    var meta = _certMeta(certPem);
+    meta.lastRenewedAt = Date.now();
+    meta.keyAlg = certManifest.keyAlg;
+    await storage.writeMeta(certManifest.name, meta);
+    return meta;
+  }
+
+  // `forceIssue` skips the cache-fresh short-circuit and ALWAYS runs
+  // the ACME issue flow. Operators invoke this path via `refresh(name)`
+  // for emergency reissue / key rollover when the existing cert is
+  // structurally fine but operationally compromised (suspected key
+  // disclosure, CA misissuance investigation, posture-driven rotation).
+  async function _ensureCert(certManifest, forceIssue) {
+    var meta = await storage.readMeta(certManifest.name);
+    var certBuf = await storage.readSealed(certManifest.name + "/cert.pem");
+    var keyBuf  = await storage.readSealed(certManifest.name + "/key.pem");
+    if (!forceIssue && meta && certBuf && keyBuf &&
+        meta.expiresAt > Date.now() + minDaysBeforeExpiry * C.TIME.days(1)) {
+      // Cached, not due for renewal yet.
+      loadedContexts[certManifest.name] = {
+        cert:               certBuf.toString("utf8"),
+        key:                keyBuf.toString("utf8"),
+        expiresAt:          meta.expiresAt,
+        fingerprintSha256:  meta.fingerprintSha256,
+        sniNames:           certManifest.domains.slice(),
+      };
+      return loadedContexts[certManifest.name];
+    }
+    // Issue (or renew) the cert.
+    var issued = await _issueCert(certManifest);
+    var freshMeta = await _persistCert(certManifest, issued.certPem, issued.keyPem);
+    loadedContexts[certManifest.name] = {
+      cert:               issued.certPem,
+      key:                issued.keyPem,
+      expiresAt:          freshMeta.expiresAt,
+      fingerprintSha256:  freshMeta.fingerprintSha256,
+      sniNames:           certManifest.domains.slice(),
+    };
+    var event = meta ? "cert.renewed" : "cert.issued";
+    _emitAudit(event, "success", {
+      name:              certManifest.name,
+      domains:           certManifest.domains,
+      expiresAt:         freshMeta.expiresAt,
+      fingerprintSha256: freshMeta.fingerprintSha256,
+    });
+    emitter.emit(event, {
+      name:              certManifest.name,
+      expiresAt:         freshMeta.expiresAt,
+      fingerprintSha256: freshMeta.fingerprintSha256,
+    });
+    return loadedContexts[certManifest.name];
+  }
+
+  async function _renewCheckOne(certManifest) {
+    var meta = await storage.readMeta(certManifest.name);
+    if (!meta) return;
+    var msToExpiry = meta.expiresAt - Date.now();
+    var renewThresholdMs = minDaysBeforeExpiry * C.TIME.days(1);
+    var shouldRenew = msToExpiry < renewThresholdMs;
+
+    // ARI: if the CA published renewalInfo and ariCompliant is on,
+    // also honor the CA's suggestedWindow (which may be sooner or
+    // later than the time-based threshold).
+    if (ariCompliant && acmeClient) {
+      try {
+        var ari = await acmeClient.renewIfDue({ certPem: loadedContexts[certManifest.name].cert });
+        if (ari && ari.shouldRenew) shouldRenew = true;
+      } catch (_e) {
+        // ARI fetch failure is non-fatal — fall back to time-based
+        // threshold (also drop-silent audit).
+      }
+    }
+
+    if (!shouldRenew) return;
+    try {
+      await _ensureCert(certManifest);
+    } catch (e) {
+      _emitAudit("cert.renew-failed", "failure", {
+        name:    certManifest.name,
+        domains: certManifest.domains,
+        error:   (e && e.message) || String(e),
+      });
+      emitter.emit("cert.renew-failed", {
+        name:    certManifest.name,
+        error:   e,
+      });
+    }
+  }
+
+  async function start() {
+    if (stopped) {
+      throw new CertError("cert/already-stopped",
+        "cert.start: handle was stopped; create a new manager to restart");
+    }
+    // 1. Boot ACME client + ensure every manifest cert is issued.
+    var names = Object.keys(certsByName);
+    for (var ni = 0; ni < names.length; ni += 1) {
+      await _ensureCert(certsByName[names[ni]]);
+    }
+    // 2. Start renewal scheduler.
+    scheduler = safeAsync.repeating(async function () {
+      var keys = Object.keys(certsByName);
+      for (var ki = 0; ki < keys.length; ki += 1) {
+        await _renewCheckOne(certsByName[keys[ki]]);
+      }
+    }, renewIntervalMs, { name: "cert-renew" });
+  }
+
+  async function stop() {
+    stopped = true;
+    if (scheduler && typeof scheduler.stop === "function") scheduler.stop();
+    scheduler = null;
+  }
+
+  function getContext(name) {
+    if (!certsByName[name]) {
+      throw new CertError("cert/unknown-name",
+        "cert.getContext: unknown cert '" + name + "' — declare it in opts.certs");
+    }
+    var ctx = loadedContexts[name];
+    if (!ctx) {
+      throw new CertError("cert/not-loaded",
+        "cert.getContext: cert '" + name + "' not yet loaded — call start() first");
+    }
+    return {
+      cert:               ctx.cert,
+      key:                ctx.key,
+      expiresAt:          ctx.expiresAt,
+      fingerprintSha256:  ctx.fingerprintSha256,
+    };
+  }
+
+  function sniCallback(servername, cb) {
+    // Match by exact domain first, then wildcard suffix.
+    var match = null;
+    var names = Object.keys(loadedContexts);
+    for (var ni = 0; ni < names.length; ni += 1) {
+      var ctx = loadedContexts[names[ni]];
+      if (ctx.sniNames.indexOf(servername) !== -1) { match = ctx; break; }
+    }
+    if (!match && names.length > 0) {
+      // Wildcard scan — RFC 6125 §6.4.3 restricts `*.example.com` to
+      // match exactly ONE label in the left-most position. `foo.bar.
+      // example.com` does NOT match `*.example.com` even though the
+      // tail aligns. Enforce the single-label invariant explicitly:
+      // the wildcard suffix is `.<rest>`; the leading label of
+      // `servername` must not itself contain a `.`.
+      for (var nj = 0; nj < names.length; nj += 1) {
+        var ctxJ = loadedContexts[names[nj]];
+        for (var sj = 0; sj < ctxJ.sniNames.length; sj += 1) {
+          var pattern = ctxJ.sniNames[sj];
+          if (pattern.charAt(0) !== "*" || pattern.charAt(1) !== ".") continue;
+          var tail = pattern.slice(1);   // ".example.com"
+          if (!servername.endsWith(tail)) continue;
+          var leadingLabel = servername.slice(0, servername.length - tail.length);
+          if (leadingLabel.length === 0 || leadingLabel.indexOf(".") !== -1) continue;
+          match = ctxJ;
+          break;
+        }
+        if (match) break;
+      }
+    }
+    if (!match && names.length > 0) {
+      // Fall back to the first registered cert (operator's default).
+      match = loadedContexts[names[0]];
+    }
+    if (!match) {
+      return cb(new CertError("cert/no-context",
+        "cert.sniCallback: no certs loaded for servername '" + servername + "'"));
+    }
+    try {
+      var secureCtx = require("node:tls").createSecureContext({
+        cert: match.cert,
+        key:  match.key,
+      });
+      cb(null, secureCtx);
+    } catch (e) {
+      cb(e);
+    }
+  }
+
+  async function refresh(name) {
+    // refresh() forces an immediate ACME issue regardless of cache
+    // freshness — operator-triggered emergency rotation (key
+    // compromise, CA misissuance investigation, posture-driven
+    // rotation). The renewal scheduler's window-based path runs via
+    // _renewCheckOne; refresh() is the override.
+    if (!certsByName[name]) {
+      throw new CertError("cert/unknown-name",
+        "cert.refresh: unknown cert '" + name + "'");
+    }
+    return _ensureCert(certsByName[name], true);
+  }
+
+  function on(event, handler)   { emitter.on(event, handler);    return this; }
+  function off(event, handler)  { emitter.off(event, handler);   return this; }
+  function once(event, handler) { emitter.once(event, handler);  return this; }
+
+  // Suppress unused-warnings for ocsp + compliance until those branches
+  // wire up in v0.11.23+ follow-up.
+  void ocspStapling; void ocspRefreshMs; void compliance; void networkTls;
+
+  return {
+    start:        start,
+    stop:         stop,
+    getContext:   getContext,
+    sniCallback:  sniCallback,
+    refresh:      refresh,
+    on:           on,
+    off:          off,
+    once:         once,
+  };
+}
+
+module.exports = {
+  create:    create,
+  CertError: CertError,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.11.20",
+  "version": "0.11.22",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:ec30b2f7-3d42-4c41-a3f5-78a26f2a8bf4",
+  "serialNumber": "urn:uuid:617bc99b-11e9-4c47-8ede-269a573133ef",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-20T22:02:34.937Z",
+    "timestamp": "2026-05-21T01:07:24.386Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.11.20",
+      "bom-ref": "@blamejs/core@0.11.22",
       "type": "application",
       "name": "blamejs",
-      "version": "0.11.20",
+      "version": "0.11.22",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.11.20",
+      "purl": "pkg:npm/%40blamejs/core@0.11.22",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.11.20",
+      "ref": "@blamejs/core@0.11.22",
       "dependsOn": []
     }
   ]