@blamejs/core 0.8.42 → 0.8.49

package/lib/middleware/security-headers.js

@@ -82,6 +82,50 @@ var DEFAULT_CSP =
   "require-trusted-types-for 'script'; " +
   "trusted-types 'allow-duplicates' default;";
 
+/**
+ * @primitive b.middleware.securityHeaders
+ * @signature b.middleware.securityHeaders(req, res, next)
+ * @since     0.1.0
+ * @related   b.middleware.cspNonce, b.middleware.cspReport, b.middleware.cors
+ *
+ * Sets the OWASP-aligned response headers every modern app should
+ * send. Constructed via `b.middleware.securityHeaders(opts)`; the
+ * resulting middleware has the `(req, res, next)` shape shown above.
+ * Headers include: HSTS (2-year max-age + includeSubDomains + preload), X-CTO
+ * nosniff, X-Frame-Options DENY, Referrer-Policy no-referrer, an
+ * extensive Permissions-Policy denylist (camera / geolocation /
+ * payment / Privacy-Sandbox attribution-reporting / bluetooth /
+ * etc.), COOP same-origin, CORP same-origin, Origin-Agent-Cluster
+ * `?1`, and a strict default CSP with `require-trusted-types-for
+ * 'script'`. Each header can be softened by passing the option
+ * value or disabled by passing `false`. Mount FIRST (after
+ * `requestId`) so headers are set before any response could be
+ * partially sent.
+ *
+ * @opts
+ *   {
+ *     hsts:               string|false,
+ *     contentTypeOptions: "nosniff"|false,
+ *     frameOptions:       "DENY"|"SAMEORIGIN"|false,
+ *     referrerPolicy:     string|false,
+ *     permissionsPolicy:  string|false,
+ *     coop:               string|false,
+ *     coep:               string|false,
+ *     corp:               string|false,
+ *     originAgentCluster: "?1"|"?0"|false,
+ *     dnsPrefetchControl: "off"|"on"|false,
+ *     csp:                string|false,
+ *     reportingEndpoints: object,
+ *     trustProxy:         boolean|number,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.securityHeaders({
+ *     hsts: "max-age=63072000; includeSubDomains; preload",
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/security-txt.js

@@ -56,6 +56,44 @@ function _isoFuture(s) {
   return d.getTime() > Date.now();
 }
 
+/**
+ * @primitive b.middleware.securityTxt
+ * @signature b.middleware.securityTxt(opts)
+ * @since     0.1.0
+ * @related   b.middleware.assetlinks, b.middleware.webAppManifest
+ *
+ * Serves an RFC 9116 `/.well-known/security.txt` body so security
+ * researchers find the disclosure policy. With `alsoAtRoot: true`
+ * also serves at `/security.txt`. Required fields per §2.5 are
+ * `Contact` and `Expires` — the middleware throws at create-time
+ * when either is missing OR `Expires` is in the past, and
+ * sanitizes every value against CR / LF / NUL (RFC 9116 forbids
+ * those in field values). Operators with PGP keys, hall-of-fame
+ * URLs, hiring pages, etc. populate the optional fields.
+ *
+ * @opts
+ *   {
+ *     contact:            string[],   // required, ≥1 entry
+ *     expires:            string,     // required, future ISO timestamp
+ *     encryption:         string[],
+ *     policy:             string,
+ *     ack:                string,
+ *     preferredLanguages: string[],
+ *     hiring:             string,
+ *     canonical:          string|string[],
+ *     alsoAtRoot:         boolean,
+ *     audit:              boolean,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.securityTxt({
+ *     contact: ["mailto:security@example.com"],
+ *     expires: "2099-01-01T00:00:00Z",
+ *     policy:  "https://example.com/security/policy",
+ *   }));
+ */
 function create(opts) {
   validateOpts.requireObject(opts, "middleware.securityTxt", SecurityTxtError);
   validateOpts(opts, [

package/lib/middleware/span-http-server.js

@@ -113,6 +113,43 @@ function _captureResponseHeaderAttrs(res, captureList, prefix) {
   return out;
 }
 
+/**
+ * @primitive b.middleware.spanHttpServer
+ * @signature b.middleware.spanHttpServer(opts)
+ * @since     0.1.0
+ * @related   b.middleware.tracePropagate, b.middleware.traceLogCorrelation
+ *
+ * Auto-creates a root OTel span per HTTP request, populates the
+ * `http.request.method`, `http.route`, `url.scheme`, `url.path`,
+ * `server.address`, `client.address`, `user_agent.original`, and
+ * `http.response.status_code` semconv attributes, attaches the
+ * span to `req.span`, and ends it on response close. Span kind is
+ * `server`. `ignorePaths` (strings or RegExp) keeps `/healthz` and
+ * static-asset routes out of the span volume.
+ * `captureRequestHeaders` / `captureResponseHeaders` add operator-
+ * chosen header attributes (e.g. `x-tenant-id`).
+ *
+ * @opts
+ *   {
+ *     tracer:                 object,                       // required
+ *     onEnd:                  function(span): void,
+ *     ignorePaths:            Array<string|RegExp>,
+ *     captureRequestHeaders:  string[],
+ *     captureResponseHeaders: string[],
+ *     spanNameFn:             function(req): string,
+ *     audit:                  boolean,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   var tracer = b.observability.tracer.create({ service: "checkout" });
+ *   app.use(b.middleware.tracePropagate());
+ *   app.use(b.middleware.spanHttpServer({
+ *     tracer:      tracer,
+ *     ignorePaths: ["/healthz"],
+ *   }));
+ */
 function create(opts) {
   validateOpts.requireObject(opts, "middleware.spanHttpServer", SpanHttpError);
   validateOpts(opts, [

package/lib/middleware/sse.js

@@ -64,6 +64,42 @@ function _formatEvent(msg) {
   });
 }
 
+/**
+ * @primitive b.middleware.sse
+ * @signature b.middleware.sse(handler, opts)
+ * @since     0.1.0
+ * @related   b.sse.serializeEvent, b.middleware.compression
+ *
+ * Server-Sent Events handler — one-way streaming from server to
+ * browser over a single HTTP response with `Content-Type:
+ * text/event-stream`. Browsers reconnect automatically with
+ * `Last-Event-ID` so the operator's handler can resume from the
+ * last delivered event. Refuses CRLF / NUL injection in `event` /
+ * `id` (CVE-2026-33128 / 29085 / 44217 class) — the framework
+ * does NOT silently strip; it returns a structured error.
+ * Heartbeat (default 15s) keeps corporate proxies / Heroku-style
+ * idle-timeouts from killing the stream; pass `heartbeatMs: false`
+ * to disable. SSE streams should NOT be compressed —
+ * `b.middleware.compression` already skips `text/event-stream`.
+ *
+ * The handler receives `(channel, req)`. The channel exposes
+ * `send({ id, event, data, retry })`, `ping(comment)`, `close()`,
+ * `onAbort(fn)`.
+ *
+ * @opts
+ *   {
+ *     heartbeatMs: number|false,   // default 15000
+ *     headers:     object,         // extra response headers
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.get("/events", b.middleware.sse(async function (channel, req) {
+ *     channel.send({ id: 1, event: "tick", data: { count: 1 } });
+ *     channel.close();
+ *   }, { heartbeatMs: 15000 }));
+ */
 function create(handler, opts) {
   if (typeof handler !== "function") {
     throw new Error("middleware.sse: handler must be a function (channel, req) => ...");

package/lib/middleware/trace-log-correlation.js

@@ -102,6 +102,39 @@ function _wrapLogger(baseLogger, req, opts) {
   return wrapped;
 }
 
+/**
+ * @primitive b.middleware.traceLogCorrelation
+ * @signature b.middleware.traceLogCorrelation(opts)
+ * @since     0.1.0
+ * @related   b.middleware.tracePropagate, b.middleware.spanHttpServer
+ *
+ * Wraps the operator's `b.log` instance for the request lifetime
+ * so every `log() / info() / warn() / error() / debug()` call
+ * inside the handler auto-includes the canonical `trace_id` +
+ * `span_id` (and tenant attributes from W3C Baggage when present).
+ * Thin adapter — does not change levels, sinks, or the API
+ * surface; logs pass through with the trace fields injected via
+ * the meta-object second argument. When `req.trace` isn't set
+ * (operator forgot to mount `tracePropagate` first), the wrapper
+ * is a no-op pass-through.
+ *
+ * @opts
+ *   {
+ *     logger:         object,    // required b.log instance
+ *     reqField:       string,    // default "log" → req.log
+ *     includeBaggage: boolean,   // default true
+ *     audit:          boolean,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.tracePropagate());
+ *   app.use(b.middleware.traceLogCorrelation({
+ *     logger:   b.log.boot("api"),
+ *     reqField: "log",
+ *   }));
+ */
 function create(opts) {
   validateOpts.requireObject(opts, "middleware.traceLogCorrelation", TraceLogError);
   validateOpts(opts, [

package/lib/middleware/trace-propagate.js

@@ -45,6 +45,38 @@ var TracePropagateError = defineClass("TracePropagateError", { alwaysPermanent:
 var observability = lazyRequire(function () { return require("../observability"); });
 var audit = lazyRequire(function () { return require("../audit"); });
 
+/**
+ * @primitive b.middleware.tracePropagate
+ * @signature b.middleware.tracePropagate(opts)
+ * @since     0.1.0
+ * @related   b.middleware.traceLogCorrelation, b.middleware.spanHttpServer
+ *
+ * Consumes the inbound `traceparent` header per W3C Trace Context
+ * and stamps `req.trace = { traceId, parentId, sampled,
+ * hadUpstream, tracestate }` for downstream handlers and outbound
+ * HTTP propagation. With `generateIfMissing: true` (default) the
+ * middleware synthesises a fresh trace when the inbound header is
+ * absent or malformed, and stamps `hadUpstream: false` so downstream
+ * code can tell locally-originated traces apart. `setResponseHeader:
+ * true` echoes the resolved `traceparent` on the response so the
+ * client sees what the server actually used.
+ *
+ * @opts
+ *   {
+ *     generateIfMissing: boolean,   // default true
+ *     auditOnMissing:    boolean,   // default false
+ *     setResponseHeader: boolean,   // default false
+ *     audit:             boolean,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.tracePropagate({
+ *     generateIfMissing: true,
+ *     setResponseHeader: true,
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/tus-upload.js

@@ -157,6 +157,35 @@ function _parseChecksumHeader(headerValue, allowedSet) {
   return { algo: algo, nodeAlgo: nodeAlgo, digestB64: digestB64 };
 }
 
+/**
+ * @primitive b.middleware.tusUpload.memoryStore
+ * @signature b.middleware.tusUpload.memoryStore(opts)
+ * @since     0.1.0
+ * @related   b.middleware.tusUpload
+ *
+ * In-memory upload store for the TUS middleware. Suitable for
+ * dev / single-node demos / test fixtures — every upload is kept
+ * in process memory until completion or expiry. Production
+ * operators wire a disk- or object-store-backed implementation
+ * matching the same `{ create, head, append, terminate, sweep }`
+ * shape. `maxSize` caps the per-upload byte budget; uploads above
+ * that fail-fast at PATCH time. `defaultExpirationMs` sets the
+ * retention window after creation.
+ *
+ * @opts
+ *   {
+ *     maxSize:             number,
+ *     defaultExpirationMs: number,    // default 24h
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var store = b.middleware.tusUpload.memoryStore({
+ *     maxSize:             b.constants.BYTES.gib(2),
+ *     defaultExpirationMs: b.constants.TIME.hours(24),
+ *   });
+ *   // store is the { create, head, append, ... } object passed to tusUpload({ store })
+ */
 function memoryStore(opts) {
   opts = opts || {};
   var maxSize = opts.maxSize;
@@ -293,6 +322,49 @@ function _readChunk(req, maxChunkSize) {
   });
 }
 
+/**
+ * @primitive b.middleware.tusUpload
+ * @signature b.middleware.tusUpload(opts)
+ * @since     0.1.0
+ * @related   b.middleware.tusUpload.memoryStore, b.middleware.tusUpload.close
+ *
+ * tus.io v1.0.0 resumable-upload protocol implementation. Wires
+ * POST (creation), HEAD (offset query), PATCH (append),
+ * DELETE (termination), and OPTIONS (discovery) per the spec.
+ * Implements `creation`, `creation-with-upload`, `expiration`,
+ * `checksum`, and `termination` extensions. Concatenation (§4.6)
+ * is intentionally out of scope — operators that need parallel-
+ * chunk assembly compose it in their own store layer. Refuses
+ * checksum-mismatch with HTTP 460 per §3.5; expired uploads are
+ * swept on a periodic timer driven by the store. Hot-path PATCH
+ * lifecycle metrics route through `observability.safeEvent` rather
+ * than the audit chain.
+ *
+ * @opts
+ *   {
+ *     mountPath:          string,                              // required
+ *     store:              object,                              // required
+ *     maxSize:            number,
+ *     maxChunkSize:       number,
+ *     expirationSec:      number,
+ *     extensions:         string[],
+ *     checksumAlgorithms: string[],
+ *     onCreate:           async function(uploadId, meta): void,
+ *     onComplete:         async function(uploadId, meta): void,
+ *     onTerminate:        async function(uploadId): void,
+ *     audit:              boolean,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   var store = b.middleware.tusUpload.memoryStore({ maxSize: b.constants.BYTES.gib(2) });
+ *   app.use(b.middleware.tusUpload({
+ *     mountPath: "/uploads",
+ *     store:     store,
+ *     maxSize:   b.constants.BYTES.gib(2),
+ *   }));
+ */
 function create(opts) {
   validateOpts.requireObject(opts, "middleware.tusUpload", TusError);
   validateOpts(opts, [
@@ -637,6 +709,24 @@ function create(opts) {
   };
 }
 
+/**
+ * @primitive b.middleware.tusUpload.close
+ * @signature b.middleware.tusUpload.close(middleware)
+ * @since     0.1.0
+ * @related   b.middleware.tusUpload
+ *
+ * Releases resources held by a TUS upload middleware instance —
+ * timers, periodic-sweep handles, and any store-close hook the
+ * operator wired. Operators call this on graceful shutdown so the
+ * sweep timer doesn't keep the process alive. Tolerant of
+ * middleware values that don't expose a `close` method (no-op).
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var store = b.middleware.tusUpload.memoryStore({});
+ *   var tus = b.middleware.tusUpload({ mountPath: "/uploads", store: store });
+ *   b.middleware.tusUpload.close(tus);
+ */
 function close(middleware) {
   // Reserved for future store-close hook; the sweep timer is the only
   // resource currently bound, and it lives inside the middleware closure.

package/lib/middleware/web-app-manifest.js

@@ -37,6 +37,59 @@ var observability = lazyRequire(function () { return require("../observability")
 
 function _isPlainArray(x) { return Array.isArray(x); }
 
+/**
+ * @primitive b.middleware.webAppManifest
+ * @signature b.middleware.webAppManifest(opts)
+ * @since     0.1.0
+ * @related   b.middleware.assetlinks, b.middleware.securityTxt
+ *
+ * Serves the W3C Web App Manifest at `/manifest.webmanifest`
+ * (and `/manifest.json` when `alsoAtJsonPath: true`). Manifest is
+ * JSON-serialized once at create-time and emitted with
+ * `Content-Type: application/manifest+json`. Throws at create-time
+ * when `name`, `start_url`, or an icons array is missing — those
+ * are the W3C-required fields for an installable PWA. Operator
+ * fields outside the W3C allowlist throw at boot so typos surface
+ * early.
+ *
+ * @opts
+ *   {
+ *     name:                        string,    // required
+ *     start_url:                   string,    // required
+ *     icons:                       Array<{ src, sizes, type }>,  // required, ≥1
+ *     short_name:                  string,
+ *     description:                 string,
+ *     scope:                       string,
+ *     display:                     string,
+ *     display_override:            string[],
+ *     orientation:                 string,
+ *     theme_color:                 string,
+ *     background_color:            string,
+ *     screenshots:                 array,
+ *     shortcuts:                   array,
+ *     categories:                  string[],
+ *     lang:                        string,
+ *     dir:                         string,
+ *     id:                          string,
+ *     prefer_related_applications: boolean,
+ *     related_applications:        array,
+ *     alsoAtJsonPath:              boolean,
+ *     audit:                       boolean,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.webAppManifest({
+ *     name:      "Example App",
+ *     start_url: "/",
+ *     display:   "standalone",
+ *     icons: [
+ *       { src: "/icons/192.png", sizes: "192x192", type: "image/png" },
+ *       { src: "/icons/512.png", sizes: "512x512", type: "image/png" },
+ *     ],
+ *   }));
+ */
 function create(opts) {
   validateOpts.requireObject(opts, "middleware.webAppManifest", WebAppManifestError);
   // Allowlist subset of W3C-spec attributes operators commonly set.

package/lib/mtls-ca.js

@@ -1,80 +1,55 @@
 "use strict";
 /**
- * mtls-ca — mTLS Certificate Authority management.
+ * @module b.mtlsCa
+ * @nav    Crypto
+ * @title  mTLS CA
  *
- * Storage, sealed-loading dispatch, generation tagging, atomic commit.
- * Cert issuance (CA generation, client cert signing, PKCS#12 packaging)
- * delegates to a pluggable engine. The framework ships a default
- * pure-JS engine (lib/mtls-engine-default.js, backed by the vendored
- * @peculiar/x509 + pkijs bundle); operators with custom requirements
- * pass their own via opts.engine.
+ * @intro
+ *   Mutual TLS Certificate Authority — internal CA cert issuance,
+ *   mTLS gate setup, fingerprint pinning.
  *
- *   var ca = b.mtlsCa.create({
- *     dataDir:          "./data",
- *     paths: {
- *       caKey:          "ca.key",
- *       caKeySealed:    "ca.key.sealed",
- *       caCert:         "ca.crt",
- *     },
- *     vault:            b.vault,         // optional; required when sealed
- *     caKeySealedMode:  "required",      // "required" (default) | "disabled"
- *     generation:       1,               // current CA generation for OU=CAv{N}
- *     engine:           myCertEngine,    // optional — defaults to b.mtlsEngine
- *   });
- *
- * Files (relative to dataDir):
- *   ca.crt           CA certificate (PEM, plaintext on disk)
- *   ca.key           CA private key (PEM, plaintext on disk)
- *   ca.key.sealed    CA private key (vault.seal of PEM bytes)
- *
- * caKeySealedMode (defaults to "required"):
- *   "required"  sealed file required; refuse plaintext (default — vault
- *               must be wired)
- *   "disabled"  plaintext required; refuse sealed (dev-only opt-out;
- *               operator must justify with audited reason)
- *
- * The legacy "auto" mode (load whichever exists, fall back to plaintext
- * when no sealed file is present) was removed; it defaulted to writing
- * plaintext on a fresh install, which is the inverse of the framework's
- * security-defaults-on posture for at-rest key material.
- *
- * Generation tagging: every CA cert issued by the framework embeds a
- * "OU=CAv{N}" RDN in its subject DN. Status reads that back so an
- * upgrade flow can detect legacy CAs (a pre-rotation CA whose key
- * parameters are below the current bar) and prompt regeneration
- * without breaking active mTLS clients.
+ *   The framework owns storage, sealed-loading dispatch, generation
+ *   tagging, and atomic commit. Cert issuance (CA generation, client
+ *   cert signing, PKCS#12 packaging) delegates to a pluggable engine
+ *   so the operator chooses the X.509 toolchain. The default pure-JS
+ *   engine lives in `lib/mtls-engine-default.js` (backed by the
+ *   vendored @peculiar/x509 + pkijs bundle); operators with custom
+ *   requirements pass their own via `opts.engine`.
  *
- * Issuance surface (delegates to opts.engine):
+ *   Files relative to `dataDir`: `ca.crt` (PEM cert, plaintext),
+ *   `ca.key` (PEM key, plaintext — refused under `caKeySealedMode:
+ *   "required"`), `ca.key.sealed` (vault.seal of the PEM bytes — the
+ *   default at-rest shape), `revocations.json` (revocation registry),
+ *   `ca.crl` (signed CRL derived from the registry).
  *
- *   ca.initCA()
- *     returns existing { caCertPem, caKeyPem } or generates a fresh
- *     pair via engine.generateCa() and atomically commits it.
+ *   `caKeySealedMode` defaults to "required" — sealed file required,
+ *   plaintext refused. The legacy "auto" fallback was removed; it
+ *   defaulted to writing plaintext on a fresh install, which is the
+ *   inverse of the framework's security-defaults-on posture for
+ *   at-rest key material. The "disabled" mode is a dev-only opt-out
+ *   (operator must justify with audited reason).
  *
- *   ca.generateClientCert({ cn, validityDays })
- *     calls engine.signClientCert with the CA loaded.
+ *   Generation tagging: every CA cert issued by the framework embeds
+ *   an `OU=CAv{N}` RDN in its subject DN. `parseGeneration` reads that
+ *   back so an upgrade flow can detect legacy CAs and prompt
+ *   regeneration without breaking active mTLS clients.
  *
- *   ca.generateClientP12({ cn, password, validityDays })
- *     calls engine.packageP12 with the CA loaded.
- *
- * Engine contract (default lib/mtls-engine-default.js, override via
- * opts.engine):
- *
- *   {
- *     async generateCa({ generation })
- *       returns { caCertPem, caKeyPem },
+ *   Engine contract:
+ *     async generateCa({ generation }) -> { caCertPem, caKeyPem }
  *     async signClientCert({ cn, validityDays, caCertPem, caKeyPem })
- *       returns { cert, key, ca, issuedAt, expiresAt },
+ *       -> { cert, key, ca, issuedAt, expiresAt }
  *     async packageP12({ cn, password, validityDays, caCertPem, caKeyPem })
- *       returns { p12, certPem, issuedAt, expiresAt },
- *   }
+ *       -> { p12, certPem, issuedAt, expiresAt }
+ *
+ *   The engine returns the cert PEM but does NOT compute a
+ *   fingerprint — the framework hashes the cert via
+ *   `b.crypto.sha3Hash(certPem)` so the SHA3-512 posture stays
+ *   consistent across the stack. Operators who need the X.509-
+ *   conventional SHA-256 fingerprint (browser cert-details panels,
+ *   openssl interop) compute it separately from the cert PEM.
  *
- * Note: the engine returns the cert PEM (`certPem`) but does NOT
- * compute a fingerprint — the framework hashes the cert via
- * `b.crypto.sha3Hash(certPem)` for any audit / display purpose,
- * keeping the SHA3-512 posture consistent across the rest of the
- * stack. Operators who want the X.509-conventional SHA-256
- * fingerprint (for browser cert-details panels, openssl interop)
- * compute it separately from the cert PEM.
+ * @card
+ *   Mutual TLS Certificate Authority — internal CA cert issuance, mTLS gate setup, fingerprint pinning.
  */
 
 var fs = require("fs");
@@ -133,10 +108,27 @@ function _resolvePaths(dataDir, paths) {
   };
 }
 
-// Parse "OU=CAv{N}" from a PEM cert's subject DN. Returns the integer
-// N (defaulting to 1 for untagged legacy CAs) or 0 when the cert is
-// unreadable. Untagged returning 1 means the first regen lifts a legacy
-// CA to generation 2 without misidentifying it as fresh.
+/**
+ * @primitive b.mtlsCa.parseGeneration
+ * @signature b.mtlsCa.parseGeneration(certPem)
+ * @since     0.7.68
+ * @related   b.mtlsCa.create
+ *
+ * Read the `OU=CAv{N}` generation tag from a PEM CA certificate's
+ * subject DN. Returns the integer `N`, defaulting to `1` for untagged
+ * legacy CAs (so the first regen lifts a legacy CA to generation 2
+ * without misidentifying it as fresh) or `0` when the cert is
+ * unreadable. Operators wire this into upgrade flows that detect
+ * pre-rotation CAs whose key parameters are below the current bar.
+ *
+ * @example
+ *   var pem = "-----BEGIN CERTIFICATE-----\n(invalid)\n-----END CERTIFICATE-----\n";
+ *   b.mtlsCa.parseGeneration(pem);
+ *   // → 0
+ *
+ *   b.mtlsCa.parseGeneration(null);
+ *   // → 0
+ */
 function parseGeneration(certPem) {
   if (typeof certPem !== "string" && !Buffer.isBuffer(certPem)) return 0;
   try {
@@ -149,6 +141,44 @@ function parseGeneration(certPem) {
   }
 }
 
+/**
+ * @primitive b.mtlsCa.create
+ * @signature b.mtlsCa.create(opts)
+ * @since     0.7.68
+ * @related   b.mtlsCa.parseGeneration, b.crypto.sha3Hash
+ *
+ * Build an mTLS CA handle bound to `opts.dataDir`. The handle owns
+ * sealed-loading of the CA private key, generation tagging on issued
+ * certs, atomic commit of newly generated material, and a pluggable
+ * engine for the X.509 work itself. Returns an object with
+ * `initCA()`, `generateClientCert({ cn, validityDays })`,
+ * `generateClientP12({ cn, password, validityDays })`, plus
+ * revocation helpers.
+ *
+ * Throws `MtlsCaError` at config-time on bad opts (missing dataDir,
+ * sealed-mode mismatch, missing vault when seal required).
+ *
+ * @opts
+ *   dataDir:          string,                                  // required — base for cert / key / revocation files
+ *   paths:            { caKey, caKeySealed, caCert, revocations, crl },  // override defaults
+ *   vault:            object,                                  // b.vault — required when caKeySealedMode = "required"
+ *   caKeySealedMode:  string,                                  // "required" (default) | "disabled"
+ *   generation:       number,                                  // current CA generation for OU=CAv{N}
+ *   engine:           object,                                  // pluggable X.509 engine; default lib/mtls-engine-default
+ *
+ * @example
+ *   var fs   = require("fs");
+ *   var os   = require("os");
+ *   var path = require("path");
+ *   var dir  = fs.mkdtempSync(path.join(os.tmpdir(), "blamejs-mtls-"));
+ *   var ca   = b.mtlsCa.create({
+ *     dataDir:         dir,
+ *     caKeySealedMode: "disabled",
+ *     generation:      1,
+ *   });
+ *   typeof ca.initCA;
+ *   // → "function"
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [