@blamejs/core 0.8.43 → 0.8.49

package/lib/metrics.js

@@ -1,99 +1,40 @@
 "use strict";
 /**
- * metrics — Prometheus-format counters, gauges, and histograms.
+ * @module b.metrics
+ * @nav    Observability
+ * @title  Metrics
  *
- * Production deployments need numbers. Without a metrics layer ops
- * teams are half-blind on every incident: "Was that p99 spike real?
- * What's the queue depth? How fast are audit emits going?". This
- * module ships the standard Prometheus types with framework
- * auto-instrumentation already wired into audit / vault / queue
- * hot paths so operators get the framework's vital signs for free.
+ * @intro
+ *   Counter / gauge / histogram primitives in Prometheus 0.0.4 text
+ *   format with OTLP-friendly labels, plus framework auto-instrumentation
+ *   wired into audit / vault / queue hot paths.
  *
- * Public API:
+ *   `b.metrics.create()` returns a registry — call `counter(name)` /
+ *   `gauge(name)` / `histogram(name)` to register typed metrics, then
+ *   `requestMiddleware()` for per-request counter+latency, and
+ *   `expositionHandler()` for the `/metrics` scrape route. Every metric
+ *   carries a per-instance `labelCardinalityCap` (default 10,000) — when
+ *   the next label combination would push past the cap the increment
+ *   drops and a single warning logs, so a runaway label (request-id,
+ *   raw URL with query string, per-user dimension) can't OOM the
+ *   process.
  *
- *   var m = b.metrics.create({
- *     namespace:     "myapp",                  // prepended to every metric name
- *     defaultLabels: { service: "api", version: "1.2.3" },
- *     labelCardinalityCap: 10000,              // per-metric ceiling
- *   });
+ *   Framework modules call `metrics.tap("audit.record", value, labels)`
+ *   at hot paths. Until a registry is active the call is a zero-cost
+ *   no-op; once `create()` runs, taps flow into pre-registered
+ *   counters / gauges (`framework_audit_events_total`,
+ *   `framework_vault_seal_total`, `framework_queue_depth`,
+ *   `framework_jobs_inflight`, `framework_errors_total`,
+ *   `framework_http_requests_total`,
+ *   `framework_http_request_duration_seconds`).
  *
- *   var requests = m.counter("http_requests_total", {
- *     help: "Total HTTP requests",
- *     labelNames: ["method", "route", "status"],
- *   });
- *   requests.inc({ method: "GET", route: "/users", status: "200" });
- *   requests.inc({ method: "GET", route: "/users", status: "200" }, 5);
+ *   Best-practice route labels are the route TEMPLATE
+ *   (`/users/:id`), not the actual path — `requestMiddleware` reads
+ *   `req.routePattern` when the matcher set one and falls back to the
+ *   query-stripped URL otherwise.
  *
- *   var latency = m.histogram("http_request_duration_seconds", {
- *     help:       "HTTP request latency",
- *     labelNames: ["method", "route"],
- *     buckets:    [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
- *   });
- *   latency.observe({ method: "GET", route: "/users" }, 0.123);
- *
- *   var queueDepth = m.gauge("queue_depth", { labelNames: ["queueName"] });
- *   queueDepth.set({ queueName: "default" }, 42);
- *   queueDepth.inc({ queueName: "default" });
- *   queueDepth.dec({ queueName: "default" });
- *
- *   router.use(m.requestMiddleware());           // auto-times every request
- *   router.get("/metrics", m.expositionHandler());
- *
- * Framework auto-instrumentation:
- *   When metrics.create() runs, framework hot paths (audit.record,
- *   vault.seal, vault.unseal, queue ops) call metrics.tap() — a
- *   global no-op stub that the active registry replaces with real
- *   counters. Modules don't import the registry directly; the tap
- *   pattern keeps them decoupled and lets operators with no metrics
- *   pay zero cost.
- *
- *   Built-in metrics surfaced:
- *     framework_audit_events_total{action, outcome}   counter
- *     framework_vault_seal_total                      counter
- *     framework_vault_unseal_total                    counter
- *     framework_queue_enqueue_total{queueName}        counter
- *     framework_queue_complete_total{queueName}       counter
- *     framework_queue_fail_total{queueName}           counter
- *     framework_queue_depth{queueName}                gauge
- *     framework_jobs_inflight{queueName}              gauge
- *     framework_errors_total{class}                   counter
- *     framework_http_requests_total{method,route,status}  counter
- *     framework_http_request_duration_seconds{method,route}  histogram
- *
- * Cardinality control:
- *   Every metric has a per-instance ceiling on distinct label
- *   combinations (default 10,000). When a request's label set would
- *   create the 10,001st unique combination, the increment is dropped
- *   and a warning is logged ONCE per metric. The bound is high enough
- *   that legitimate apps don't hit it; low enough that runaway
- *   labels (a label per request id, per user id, per full URL with
- *   query string) can't OOM the process. Operators size up via
- *   labelCardinalityCap when they have a legitimate need.
- *
- *   Best practice: route labels are the route TEMPLATE (`/users/:id`),
- *   not the actual path (`/users/123`). The framework's
- *   requestMiddleware uses req.routePattern when set; otherwise falls
- *   back to req.url stripped of query string.
- *
- * Exposition format:
- *   The text/plain exposition follows the Prometheus 0.0.4 text format:
- *   `# HELP <name> <description>` and `# TYPE <name> <counter|gauge|
- *   histogram>` headers, one sample per line with serialized labels
- *   in `{key="value",key2="value2"}` form. Buckets and _sum / _count
- *   for histograms.
- *
- * Out of scope (with structural reasons):
- *   - Summary type (client-side quantiles): generally inferior to
- *     histogram for aggregation across instances. Prometheus team
- *     recommends histogram. Add later if a real demand emerges.
- *   - Push gateway: pull-only monitoring is the simpler architecture.
- *     Operators with batch jobs that want push wire it themselves.
- *   - Native histogram (Prometheus 2.40+): not yet broadly supported
- *     by tooling; classic histogram is universal.
- *   - Per-process labels at scrape time (instance, hostname): operators
- *     pass via defaultLabels. The framework doesn't auto-inject —
- *     deploy environments differ on what to use (k8s pod name,
- *     hostname, container id) and the operator knows best.
+ * @card
+ *   Counter / gauge / histogram primitives in Prometheus 0.0.4 text format with OTLP-friendly labels, plus framework auto-instrumentation wired into audit / vault / queue hot paths.
  */
 
 var C = require("./constants");
@@ -137,6 +78,28 @@ var LABEL_NAME_RE  = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
 
 var _activeTap = null;
 
+/**
+ * @primitive b.metrics.tap
+ * @signature b.metrics.tap(name, value, labels)
+ * @since     0.4.0
+ * @related   b.metrics.create, b.observability.event
+ *
+ * Framework hot-path tap. Modules call `tap("audit.record", 1,
+ * { action, outcome })` without importing a registry. Until
+ * `b.metrics.create()` runs the call is a zero-cost no-op; afterwards
+ * the active registry routes the tap into pre-registered counters and
+ * gauges. Drop-silent on internal throws so a misconfigured metric
+ * cannot crash the request that triggered the tap.
+ *
+ * @example
+ *   // Module-level — no registry yet, no-op:
+ *   b.metrics.tap("audit.record", 1, { action: "auth.login", outcome: "success" });
+ *
+ *   // After registry creation, the same tap call increments
+ *   // framework_audit_events_total{action="auth.login", outcome="success"}.
+ *   var registry = b.metrics.create({ namespace: "myapp" });
+ *   b.metrics.tap("audit.record", 1, { action: "auth.login", outcome: "success" });
+ */
 function tap(name, value, labels) {
   if (_activeTap === null) return;
   try { _activeTap(name, value, labels); }
@@ -260,6 +223,52 @@ function _resolveLabels(defaultLabels, declaredNames, callLabels) {
 
 // ---- registry factory ----
 
+/**
+ * @primitive b.metrics.create
+ * @signature b.metrics.create(opts)
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.metrics.tap, b.observability.event, b.tracing.create
+ *
+ * Build a Prometheus-format metrics registry. The returned registry
+ * exposes `counter` / `gauge` / `histogram` factories,
+ * `requestMiddleware()` for per-route auto-instrumentation,
+ * `expositionHandler()` for the `/metrics` scrape route, and
+ * `exposition()` for direct rendering. Activates the framework
+ * auto-tap so audit / vault / queue / error events feed
+ * pre-registered framework counters.
+ *
+ * @opts
+ *   namespace:           string,  // prepended to every metric name
+ *   defaultLabels:       object,  // attached to every sample
+ *   labelCardinalityCap: number,  // per-metric distinct-label-set cap; default 10000
+ *
+ * @example
+ *   var m = b.metrics.create({
+ *     namespace:     "myapp",
+ *     defaultLabels: { service: "api", version: "1.2.3" },
+ *   });
+ *
+ *   var requests = m.counter("http_requests_total", {
+ *     help:       "Total HTTP requests",
+ *     labelNames: ["method", "route", "status"],
+ *   });
+ *   requests.inc({ method: "GET", route: "/users", status: "200" });
+ *
+ *   var latency = m.histogram("http_request_duration_seconds", {
+ *     help:       "HTTP request latency",
+ *     labelNames: ["method", "route"],
+ *     buckets:    [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+ *   });
+ *   latency.observe({ method: "GET", route: "/users" }, 0.123);
+ *
+ *   var depth = m.gauge("queue_depth", { labelNames: ["queueName"] });
+ *   depth.set({ queueName: "default" }, 42);
+ *
+ *   // Wire into an HTTP server.
+ *   router.use(m.requestMiddleware());
+ *   router.get("/metrics", m.expositionHandler());
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/age-gate.js

@@ -43,6 +43,42 @@ var audit = lazyRequire(function () { return require("../audit"); });
 
 var AgeGateError = defineClass("AgeGateError", { alwaysPermanent: true });
 
+/**
+ * @primitive b.middleware.ageGate
+ * @signature b.middleware.ageGate(opts)
+ * @since     0.1.0
+ * @compliance gdpr, ferpa, ccpa
+ * @related   b.middleware.gpc
+ *
+ * Classifies the request against an operator-supplied age predicate
+ * and applies COPPA / UK Children's Code / California AADC defaults
+ * (no-store cache, no-referrer, X-Privacy-Posture header) for
+ * below-threshold + unknown-age requests. When `requireAge` is set
+ * and the request is below threshold without a parental-consent
+ * record, refuses with HTTP 451. Every classification decision is
+ * audited.
+ *
+ * @opts
+ *   {
+ *     getAge:             function(req): number|null,  // required
+ *     requireAge:         number|null,                  // 451 below this
+ *     consentRequired:    number|null,                  // require consent below
+ *     hasParentalConsent: function(req): boolean,
+ *     skipPaths:          string[],
+ *     errorMessage:       string,
+ *     audit:              boolean,                      // default true
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.ageGate({
+ *     getAge:           function (req) { return (req.user && req.user.age) || null; },
+ *     requireAge:       null,
+ *     consentRequired:  13,
+ *     hasParentalConsent: function (req) { return req.user && req.user.parentalConsent === true; },
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/ai-act-disclosure.js

@@ -42,6 +42,43 @@ var requestHelpers = require("../request-helpers");
 var aiActMod  = lazyRequire(function () { return require("../compliance-ai-act"); });
 var audit     = lazyRequire(function () { return require("../audit"); });
 
+/**
+ * @primitive b.middleware.aiActDisclosure
+ * @signature b.middleware.aiActDisclosure(opts)
+ * @since     0.1.0
+ * @compliance eu-ai-act
+ * @related   b.middleware.botDisclose
+ *
+ * Injects EU AI Act Article 50 transparency disclosures into outgoing
+ * responses. In `mode: "header"` (default) it sets `AI-Act-Notice` and
+ * `AI-Act-Article` response headers — cheapest, works for both JSON
+ * and HTML. In `mode: "html"` it additionally inserts a status banner
+ * after `<body>` and a `<meta>` inside `<head>` for HTML responses.
+ * Skips error pages, redirects, requests bearing the configured
+ * skip-header, and responses opted out via `res.locals.aiActSkip`.
+ * Emits `compliance.aiact.disclosed` audits on success.
+ *
+ * @opts
+ *   {
+ *     kind:         "ai-interaction"|"deepfake"|"emotion-recognition"|"biometric-categorisation"|"synthetic-content",
+ *     deployerName: string,
+ *     policyUri:    string,
+ *     mode:         "header"|"html",   // default "header"
+ *     lang:         string,            // default "en"
+ *     skipHeader:   string,            // default "x-skip-ai-act"
+ *     audit:        boolean,           // default true
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.aiActDisclosure({
+ *     kind:         "ai-interaction",
+ *     deployerName: "myco",
+ *     policyUri:    "https://myco.example.com/ai-policy",
+ *     mode:         "html",
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/api-encrypt.js

@@ -232,6 +232,51 @@ function _writeRejection(res, code, body) {
 
 // ---- Server-side middleware ----
 
+/**
+ * @primitive b.middleware.apiEncrypt
+ * @signature b.middleware.apiEncrypt(opts)
+ * @since     0.1.0
+ * @related   b.middleware.csrfProtect
+ *
+ * End-to-end PQC payload encryption for operator-controlled clients.
+ * TLS protects browser to load-balancer; this middleware protects the
+ * request and response bodies through every intermediate hop (LB,
+ * sidecars, queues, log aggregators, APM tooling). A tampered byte
+ * anywhere downstream of the encrypted boundary fails the AEAD tag
+ * before the route handler runs. Defends against stripped TLS,
+ * body capture in observability tooling, and replay (timestamp +
+ * nonce window). Mount with a server keypair set; the configured
+ * client SDK encrypts to the keypair's public half.
+ *
+ * @opts
+ *   {
+ *     keypair:             { publicKey, secretKey, ecPublicKey, ecSecretKey },
+ *     keypairs:            [...]            // multi-key rotation set; first = active
+ *     replayWindowMs:      number,
+ *     pruneIntervalMs:     number,
+ *     nonceStore:          { has, add, prune },
+ *     exemptPaths:         string[],
+ *     contentTypes:        string[],         // default ["application/json"]
+ *     audit:               boolean,
+ *     maxDecryptedBytes:   number,
+ *     trustProxy:          boolean|number,
+ *     keying:              "per-request"|"per-session",
+ *     sessionStore:        object,
+ *     sessionTtlMs:        number,
+ *     sessionMaxResponses: number,
+ *     observability:       object,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   var kp = b.crypto.keypair();
+ *   app.use(b.middleware.apiEncrypt({
+ *     keypair:        kp,
+ *     replayWindowMs: 30000,
+ *     contentTypes:   ["application/json"],
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/assetlinks.js

@@ -34,6 +34,46 @@ var AssetlinksError = defineClass("AssetlinksError", { alwaysPermanent: true });
 
 var observability = lazyRequire(function () { return require("../observability"); });
 
+/**
+ * @primitive b.middleware.assetlinks
+ * @signature b.middleware.assetlinks(opts)
+ * @since     0.1.0
+ * @related   b.middleware.webAppManifest
+ *
+ * Serves Digital Asset Links at `/.well-known/assetlinks.json` per
+ * Google's spec (Trusted Web Activity, Android App Links, Smart Lock,
+ * WebAuthn-for-Android). The statements array is JSON-serialized once
+ * at create-time and emitted with `Content-Type: application/json`.
+ * Multi-app deployments include multiple statement entries.
+ *
+ * @opts
+ *   {
+ *     statements: Array<{
+ *       relation: string[],
+ *       target: {
+ *         namespace:                string,
+ *         package_name?:            string,
+ *         sha256_cert_fingerprints?: string[],
+ *         site?:                    string,
+ *       },
+ *     }>,
+ *     audit: boolean,   // default true
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.assetlinks({
+ *     statements: [{
+ *       relation: ["delegate_permission/common.handle_all_urls"],
+ *       target: {
+ *         namespace:                "android_app",
+ *         package_name:             "com.example.app",
+ *         sha256_cert_fingerprints: ["AB:CD:EF:01:23:45:67:89"],
+ *       },
+ *     }],
+ *   }));
+ */
 function create(opts) {
   validateOpts.requireObject(opts, "middleware.assetlinks", AssetlinksError);
   validateOpts(opts, ["statements", "audit"], "middleware.assetlinks");

package/lib/middleware/asyncapi-serve.js

@@ -28,6 +28,41 @@ var AsyncApiError = defineClass("AsyncApiError", { alwaysPermanent: true });
 var openapiYaml   = lazyRequire(function () { return require("../openapi-yaml"); });
 var audit         = lazyRequire(function () { return require("../audit"); });
 
+/**
+ * @primitive b.middleware.asyncapiServe
+ * @signature b.middleware.asyncapiServe(opts)
+ * @since     0.1.0
+ * @related   b.middleware.openapiServe, b.asyncapi.create
+ *
+ * Serves an AsyncAPI 3.0 document built via `b.asyncapi.create` at
+ * configurable JSON + YAML mount points. Matches `openapiServe`
+ * behaviour: GET/HEAD only, SHA3-512 ETag with conditional 304,
+ * operator-controlled CORS gate, falls through on unmatched paths
+ * or methods. Use to publish channel + operation + message + schema
+ * specs for event-driven APIs (Kafka, AMQP, MQTT, WebSocket).
+ *
+ * @opts
+ *   {
+ *     document:      object,    // builder from b.asyncapi.create()
+ *     pathJson:      string,    // default "/asyncapi.json"
+ *     pathYaml:      string,    // default "/asyncapi.yaml"
+ *     pretty:        boolean,   // default false → minified
+ *     cacheControl:  string,    // default "public, max-age=300"
+ *     accessControl: "public"|"same-origin"|{ allowOrigin: string },
+ *     audit:         boolean,   // default true
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   var aapi = b.asyncapi.create({ title: "events", version: "1.0.0" });
+ *   app.use(b.middleware.asyncapiServe({
+ *     document:      aapi,
+ *     pathJson:      "/asyncapi.json",
+ *     pathYaml:      "/asyncapi.yaml",
+ *     accessControl: "public",
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/attach-user.js

@@ -63,6 +63,46 @@ function _readBearer(authHeader) {
   return m ? m[1].trim() : null;
 }
 
+/**
+ * @primitive b.middleware.attachUser
+ * @signature b.middleware.attachUser(req, res, next)
+ * @since     0.1.0
+ * @related   b.middleware.requireAuth, b.middleware.bearerAuth, b.session.verify
+ *
+ * Populates `req.user` and `req.session` from a verified session
+ * token. Constructed via `b.middleware.attachUser(opts)`; the
+ * resulting middleware has the `(req, res, next)` shape shown
+ * above. Tries the configured cookie first, then `Authorization:
+ * Bearer <token>`. Sealed cookies (vault-unwrapped) are supported so
+ * the cookie isn't reachable via curl-with-arbitrary-cookies. The
+ * framework can't know the operator's user schema; `userLoader`
+ * receives the verified session and returns the user record. Always
+ * calls `next()` — gating decisions live in
+ * `b.middleware.requireAuth`. Optional fingerprint-drift / IP-UA pin
+ * / anomaly-score enforcement threads through `session.verify`.
+ *
+ * @opts
+ *   {
+ *     userLoader:              async function(session): user|null,  // required
+ *     cookieName:              string,    // default "blamejs_session"
+ *     tokenFrom:               "both"|"cookie"|"header",  // default "both"
+ *     sealed:                  boolean,
+ *     vault:                   object,    // required when sealed
+ *     requireFingerprintMatch: boolean,
+ *     maxAnomalyScore:         number,
+ *     scorer:                  function,
+ *     audit:                   boolean,   // default true
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.attachUser({
+ *     userLoader: async function (session) {
+ *       return { id: session.userId, name: "alice" };
+ *     },
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/middleware/bearer-auth.js

@@ -78,6 +78,46 @@ function _extractToken(req, scheme) {
   return { state: "ok", token: token };
 }
 
+/**
+ * @primitive b.middleware.bearerAuth
+ * @signature b.middleware.bearerAuth(req, res, next)
+ * @since     0.1.0
+ * @related   b.middleware.attachUser, b.middleware.requireAuth, b.auth.jwt
+ *
+ * Extracts `Authorization: Bearer <token>`, calls an operator-supplied
+ * verifier, attaches the result to `req.user`. Constructed via
+ * `b.middleware.bearerAuth(opts)`; the resulting middleware has
+ * the `(req, res, next)` shape shown above. Distinct from
+ * `attachUser` (cookie sessions) — this is the API-token / JWT /
+ * OAuth-access-token path. When the header is absent the middleware
+ * defers to downstream auth; when it IS present but invalid it
+ * rejects with HTTP 401 + `WWW-Authenticate` immediately. Verifier
+ * returns the user object on success, null/false on rejection, or
+ * throws an Error with `code === "auth-bearer/expired"` to surface
+ * a token-expired challenge. Emits `auth.bearer.success` /
+ * `auth.bearer.failure` audit events with actor context.
+ *
+ * @opts
+ *   {
+ *     verify:         async function(token): user|null,  // required
+ *     scheme:         string,    // default "Bearer"; some ops use "Token"
+ *     realm:          string,
+ *     errorMessage:   string,
+ *     tokenAttachKey: string,
+ *     userAttachKey:  string,
+ *     audit:          boolean,   // default true
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use("/api", b.middleware.bearerAuth({
+ *     verify: async function (token) {
+ *       if (token === "valid-token") return { id: "user-1" };
+ *       return null;
+ *     },
+ *   }));
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [