@blamejs/core 0.4.1

package/lib/middleware/csrf-protect.js

@@ -0,0 +1,275 @@
+"use strict";
+/**
+ * csrf-protect — middleware that issues CSRF tokens to safe-method
+ * requests AND rejects state-changing requests whose submitted token
+ * doesn't match.
+ *
+ * Mount AFTER attachUser (when using session-stored tokens) and AFTER
+ * bodyParser (when reading the token from a form field). Safe methods
+ * (GET / HEAD / OPTIONS) pass through; the gate fires on POST / PUT /
+ * DELETE / PATCH (configurable via opts.methods).
+ *
+ * Token storage — pick ONE:
+ *
+ *   A. Cookie-stored ("double-submit cookie", default)
+ *      opts.cookie = true | { name, sameSite, secure, path, httpOnly }
+ *
+ *      The middleware reads the token from the configured cookie. On
+ *      safe-method requests with no token cookie, it generates one and
+ *      sets the cookie on the response. The same value is exposed on
+ *      `req.csrfToken` for templates to render into a hidden form field.
+ *      State-changing requests verify the submitted token matches the
+ *      cookie value. SameSite=Lax (default) blocks cross-site form
+ *      POSTs from carrying the cookie.
+ *
+ *      httpOnly defaults to FALSE — JavaScript needs to read it for AJAX
+ *      requests. Operators relying solely on server-rendered forms can
+ *      flip it to true.
+ *
+ *   B. Operator-supplied tokenLookup (session-stored, etc.)
+ *      opts.tokenLookup = (req) => string|null
+ *
+ *      The middleware calls tokenLookup(req) to fetch the expected
+ *      token. Use this when CSRF tokens live in your session store
+ *      (e.g. req.session.data.csrfToken). Issuance + req.csrfToken
+ *      exposure are the operator's responsibility in this mode.
+ *
+ * If neither is supplied, the middleware throws at create() — Tier A
+ * config-time validation, no silent passthrough.
+ *
+ * Submitted-token sources tried in order on state-changing requests:
+ *   1. Header `X-CSRF-Token` (or opts.headerName)
+ *   2. Body field `_csrf` (or opts.fieldName) — requires bodyParser
+ *      mounted before csrfProtect
+ *
+ * On mismatch:
+ *   - Audit emit (auth.csrf.denied) with method + path + IP + reason
+ *   - 403 application/json: { error: "CSRF token mismatch." }
+ *   - next() NOT called
+ *
+ * Full options:
+ *   {
+ *     cookie:      true | {                  EITHER this...
+ *       name:      "csrf",
+ *       sameSite:  "Lax" | "Strict" | "None",
+ *       secure:    auto-detected from request scheme,
+ *       path:      "/",
+ *       httpOnly:  false,
+ *     },
+ *     tokenLookup: (req) => string|null      ...OR this
+ *
+ *     fieldName:   "_csrf"                   form-body field name
+ *     headerName:  "X-CSRF-Token"            header name
+ *     methods:     ["POST", "PUT", "DELETE", "PATCH"]
+ *     audit:        true
+ *   }
+ */
+var lazyRequire = require("../lazy-require");
+var forms = require("../forms");
+var validateOpts = require("../validate-opts");
+var audit = lazyRequire(function () { return require("../audit"); });
+
+var DEFAULT_FIELD_NAME    = "_csrf";
+var DEFAULT_HEADER_NAME   = "X-CSRF-Token";
+var DEFAULT_METHODS       = Object.freeze(["POST", "PUT", "DELETE", "PATCH"]);
+var DEFAULT_COOKIE_NAME   = "csrf";
+
+function _parseCookieHeader(header) {
+  // Minimal cookie-header parser — RFC 6265 §5.2 form. Ignores attributes,
+  // just splits the name=value pairs. Keys that appear multiple times
+  // resolve to the FIRST occurrence (browsers send pairs left-to-right
+  // by registration order; the first is the most-specific path).
+  var out = {};
+  if (typeof header !== "string" || header.length === 0) return out;
+  var parts = header.split(/;\s*/);
+  for (var i = 0; i < parts.length; i++) {
+    var p = parts[i];
+    var eq = p.indexOf("=");
+    if (eq === -1) continue;
+    var k = p.slice(0, eq).trim();
+    if (k.length === 0 || Object.prototype.hasOwnProperty.call(out, k)) continue;
+    var v = p.slice(eq + 1).trim();
+    if (v.length >= 2 && v.charCodeAt(0) === 0x22 && v.charCodeAt(v.length - 1) === 0x22) {
+      v = v.slice(1, -1);
+    }
+    out[k] = v;
+  }
+  return out;
+}
+
+function _isHttps(req) {
+  if (req && req.socket && req.socket.encrypted) return true;
+  var fwd = req && req.headers && req.headers["x-forwarded-proto"];
+  if (typeof fwd === "string" && fwd.length > 0) {
+    return fwd.split(",")[0].trim().toLowerCase() === "https";
+  }
+  return false;
+}
+
+function _formatSetCookie(name, value, opts) {
+  var parts = [name + "=" + value];
+  parts.push("Path=" + (opts.path || "/"));
+  parts.push("SameSite=" + (opts.sameSite || "Lax"));
+  if (opts.httpOnly) parts.push("HttpOnly");
+  if (opts.secure)   parts.push("Secure");
+  if (opts.maxAge != null) parts.push("Max-Age=" + opts.maxAge);
+  return parts.join("; ");
+}
+
+function _appendSetCookie(res, value) {
+  // Don't clobber other Set-Cookie headers the route may have already
+  // queued (login session cookie, etc.). Use res.appendHeader when
+  // available; else array-merge manually.
+  if (typeof res.appendHeader === "function") {
+    res.appendHeader("Set-Cookie", value);
+    return;
+  }
+  var existing = typeof res.getHeader === "function" ? res.getHeader("Set-Cookie") : undefined;
+  if (existing == null) {
+    res.setHeader("Set-Cookie", value);
+  } else if (Array.isArray(existing)) {
+    res.setHeader("Set-Cookie", existing.concat(value));
+  } else {
+    res.setHeader("Set-Cookie", [existing, value]);
+  }
+}
+
+// csrf-protect does NOT buffer or parse the request body itself.
+// Operators who use form-urlencoded POSTs MUST register
+// `b.middleware.bodyParser()` before csrf-protect so that
+// `req.body[fieldName]` is populated. Header-token submissions
+// (X-CSRF-Token) work without bodyParser. The body-parser primitive
+// owns size caps, content-type dispatch, and prototype-pollution
+// defense; csrf-protect just reads the validated value.
+
+function _writeReject(res, message) {
+  if (typeof res.writeHead === "function") {
+    var body = JSON.stringify({ error: message });
+    res.writeHead(403, {
+      "Content-Type":   "application/json; charset=utf-8",
+      "Content-Length": Buffer.byteLength(body),
+    });
+    res.end(body);
+  }
+}
+
+function create(opts) {
+  opts = opts || {};
+
+  validateOpts(opts, [
+    "cookie", "tokenLookup", "fieldName", "headerName", "methods", "audit",
+  ], "middleware.csrfProtect");
+
+  // Tier A — exactly one issuance source.
+  var hasCookie = opts.cookie != null && opts.cookie !== false;
+  var hasLookup = typeof opts.tokenLookup === "function";
+  if (hasCookie && hasLookup) {
+    throw new Error("middleware.csrfProtect: opts.cookie and opts.tokenLookup are " +
+      "mutually exclusive — pick one (cookie = double-submit, tokenLookup = session-stored)");
+  }
+  if (!hasCookie && !hasLookup) {
+    throw new Error("middleware.csrfProtect: opts.cookie or opts.tokenLookup is required");
+  }
+
+  var fieldName  = opts.fieldName  || DEFAULT_FIELD_NAME;
+  var headerName = (opts.headerName || DEFAULT_HEADER_NAME).toLowerCase();
+  var methods    = (opts.methods || DEFAULT_METHODS).map(function (m) { return m.toUpperCase(); });
+  var auditOn    = opts.audit !== false;
+
+  // Cookie issuance config (only when opts.cookie is set).
+  var cookieCfg = null;
+  if (hasCookie) {
+    var raw = opts.cookie === true ? {} : opts.cookie;
+    if (typeof raw !== "object") {
+      throw new Error("middleware.csrfProtect: opts.cookie must be true or an object");
+    }
+    cookieCfg = {
+      name:     raw.name     || DEFAULT_COOKIE_NAME,
+      sameSite: raw.sameSite || "Lax",
+      // secure: undefined means auto-detect from request scheme; explicit
+      // true/false overrides.
+      secure:   raw.secure,
+      path:     raw.path     || "/",
+      httpOnly: !!raw.httpOnly,
+      maxAge:   raw.maxAge != null ? raw.maxAge : null,
+    };
+    if (["Lax", "Strict", "None"].indexOf(cookieCfg.sameSite) === -1) {
+      throw new Error("middleware.csrfProtect: opts.cookie.sameSite must be Lax|Strict|None");
+    }
+  }
+
+  function _emitDenied(req, reason) {
+    if (!auditOn) return;
+    audit().safeEmit({
+      action:   "auth.csrf.denied",
+      outcome:  "denied",
+      actor:    { ip: req.socket && req.socket.remoteAddress, userAgent: req.headers && req.headers["user-agent"] },
+      reason:   reason,
+      metadata: { method: req.method, path: (req.url || "").split("?")[0] },
+    });
+  }
+
+  // Issuance path (cookie mode): on safe-method requests with no cookie,
+  // generate a token and queue it for the response. Always populate
+  // req.csrfToken so templates have something to render.
+  function _issueIfNeeded(req, res) {
+    if (!cookieCfg) return null;
+    var cookies = _parseCookieHeader(req.headers && req.headers.cookie);
+    var existing = cookies[cookieCfg.name];
+    if (existing && /^[a-f0-9]{2,}$/.test(existing)) {
+      req.csrfToken = existing;
+      return existing;
+    }
+    var fresh = forms.generateCsrfToken();
+    var setCookie = _formatSetCookie(cookieCfg.name, fresh, {
+      path:     cookieCfg.path,
+      sameSite: cookieCfg.sameSite,
+      secure:   cookieCfg.secure == null ? _isHttps(req) : !!cookieCfg.secure,
+      httpOnly: cookieCfg.httpOnly,
+      maxAge:   cookieCfg.maxAge,
+    });
+    _appendSetCookie(res, setCookie);
+    req.csrfToken = fresh;
+    return fresh;
+  }
+
+  return function csrfProtect(req, res, next) {
+    // Issue/refresh the token on EVERY request (safe + state-changing)
+    // when running in cookie mode — templates rendered after a POST
+    // (e.g. error response) still need req.csrfToken populated.
+    var expected = _issueIfNeeded(req, res);
+
+    if (methods.indexOf(req.method) === -1) return next();
+
+    if (!cookieCfg) {
+      // Session-stored mode — operator's tokenLookup is the source.
+      expected = opts.tokenLookup(req);
+    }
+    if (!expected) {
+      _emitDenied(req, cookieCfg ? "no token cookie issued yet" : "no expected token in session");
+      return _writeReject(res, "CSRF token mismatch.");
+    }
+
+    // Header path first — covers JSON / AJAX / multipart cases.
+    var submitted = req.headers && req.headers[headerName];
+    if (typeof submitted !== "string" || submitted.length === 0) {
+      // Fall back to body field if bodyParser already populated req.body.
+      // Operators with form-urlencoded POSTs are expected to register
+      // bodyParser before csrf-protect; body buffering / parsing lives
+      // in bodyParser, not here.
+      if (req.body && typeof req.body === "object") {
+        var v = req.body[fieldName];
+        if (typeof v === "string") submitted = v;
+      }
+    }
+
+    if (!forms.verifyCsrfToken(submitted || "", expected)) {
+      _emitDenied(req, "submitted token does not match expected");
+      return _writeReject(res, "CSRF token mismatch.");
+    }
+
+    return next();
+  };
+}
+
+module.exports = { create: create };

package/lib/middleware/error-handler.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Error-handler middleware — thin adapter over lib/errors-page.
+ *
+ * Use this for the standard wiring path (`router.onError(b.middleware.
+ * errorHandler())`). Constructs an errors-page handler and forwards
+ * the (err, req, res, next) router signature into it. All classification,
+ * rendering, content negotiation, dev/prod gating, and audit emission
+ * lives in lib/errors-page — this file only wires the middleware
+ * convention plus the audit-action override that preserves the
+ * 'system.http.error' action name the framework's audit log already
+ * uses for HTTP-layer failures.
+ *
+ * Options forward to errors-page.create with one default override:
+ *   auditAction:        "system.http.error"   (vs errors-page default "request.error")
+ *
+ * Plus a back-compat alias:
+ *   exposeStackInDev:   forwards to opts.showStack (true|false)
+ */
+var errorPage = require("../error-page");
+
+function create(opts) {
+  opts = opts || {};
+  var pageOpts = Object.assign({}, opts);
+
+  // Preserve the existing audit action name for HTTP-layer errors.
+  if (pageOpts.auditAction  === undefined) pageOpts.auditAction  = "system.http.error";
+  // The middleware path historically returned JSON regardless of Accept
+  // (API-style). Page-style HTML rendering is reachable via the direct
+  // errorPage.create() surface, where defaultFormat="auto" negotiates.
+  if (pageOpts.defaultFormat === undefined) pageOpts.defaultFormat = "json";
+
+  // Back-compat: middleware historically used `exposeStackInDev`;
+  // errors-page uses `showStack`. Map when only the legacy name is set.
+  if (pageOpts.showStack === undefined && pageOpts.exposeStackInDev !== undefined) {
+    pageOpts.showStack = !!pageOpts.exposeStackInDev;
+  }
+
+  var pageHandler = errorPage.create(pageOpts);
+
+  return function errorHandler(err, req, res, _next) {
+    pageHandler(err, req, res);
+  };
+}
+
+module.exports = { create: create };

package/lib/middleware/health.js

@@ -0,0 +1,358 @@
+"use strict";
+/**
+ * health — liveness / readiness / startup endpoint primitive.
+ *
+ * Without this, every operator wires 5–20 lines of boilerplate that
+ * gets subtly wrong: /readyz returning 200 before the DB is connected
+ * (LB routes traffic into a half-booted process), /healthz blocking
+ * on a slow check (orchestrator kills the pod), no graceful-shutdown
+ * coordination (LB sends traffic into a draining process), or
+ * leaking internal state on a public endpoint.
+ *
+ * Three probe tiers, each its own URL path, each its own check set:
+ *
+ *   /healthz   liveness   "process is alive" — defaults to always-200
+ *                         unless the operator registers a liveness
+ *                         check (e.g. deadlock detector). Orchestrators
+ *                         use this to decide whether to KILL the pod.
+ *   /readyz    readiness  "process can serve traffic" — every readiness
+ *                         check must pass. Load balancers use this to
+ *                         decide whether to ROUTE TRAFFIC. Default tier
+ *                         for registerCheck.
+ *   /startupz  startup    "slow init has finished" — separate from
+ *                         readiness so a slow-loading model / migration
+ *                         doesn't fail the liveness probe before it
+ *                         finishes. Operators register here for the
+ *                         first-N-seconds-of-process startup work.
+ *
+ * Graceful-shutdown integration: markShuttingDown() flips readiness
+ * (and only readiness) to 503 immediately. /healthz keeps returning
+ * 200 throughout so the orchestrator doesn't kill the pod mid-drain.
+ * Standard Kubernetes pattern. `b.app.shutdown()` calls this on the
+ * health-check instance it manages; standalone callers can invoke
+ * markShuttingDown() directly.
+ *
+ *   var hc = b.middleware.health.create({
+ *     livenessPath:    "/healthz",
+ *     readinessPath:   "/readyz",
+ *     startupPath:     "/startupz",
+ *     defaultTimeoutMs: 5000,
+ *     cacheMs:          0,
+ *     detailLevel:      "minimal",     // "minimal" | "detailed"
+ *     detailPredicate:  function (req) { ... },  // operator decides
+ *   });
+ *
+ *   hc.registerCheck("db", async function () {
+ *     return { ok: b.db.isReady(), latencyMs: ... };
+ *   }, { tier: "readiness", timeoutMs: 1000, critical: true });
+ *
+ *   hc.registerCheck("queue", async function () {
+ *     return b.queue.isReady();
+ *   }, { tier: "readiness", critical: false });
+ *
+ *   router.use(hc.middleware());
+ *
+ *   // On SIGTERM:
+ *   hc.markShuttingDown();
+ *   // → /readyz returns 503 immediately; LB drains the pod;
+ *   //   /healthz still 200 so orchestrator waits for clean exit.
+ *
+ * Check function shape — anything truthy/falsy works, but two patterns
+ * are preferred:
+ *
+ *   () => true | false                    fast path; ok flag only
+ *   () => ({ ok: bool, latencyMs?, ... })  detail visible in detailed mode
+ *
+ *   Promise versions of either also work; per-check timeout (default
+ *   `defaultTimeoutMs`) bounds the wait. A timed-out check fails ok=false
+ *   without blocking other checks.
+ *
+ * Status codes:
+ *   200   "ok"             every check passed (or no checks registered)
+ *   200   "degraded"       a NON-critical check failed; service still
+ *                          serving (informational status; operator can
+ *                          alert on the body content)
+ *   503   "fail"           a CRITICAL check failed; LB should drain
+ *   503   "shutting-down"  readiness only; markShuttingDown was called
+ *
+ * Security:
+ *   - Default `detailLevel: "minimal"` returns only `{ status }` to the
+ *     public endpoint. Internal state (per-check latency, error text,
+ *     downstream service health) is not leaked.
+ *   - `detailLevel: "detailed"` enables the full check breakdown for
+ *     every probe — only suitable for endpoints behind operator auth.
+ *   - `detailPredicate(req)` lets the operator decide per-request:
+ *     return true for internal IPs / authed requests, false otherwise.
+ *     Detail predicate throwing → minimal response (fail closed).
+ *   - `Cache-Control: no-store` on every response so probes never get
+ *     cached by intermediate proxies.
+ *
+ * Caching:
+ *   - cacheMs > 0 caches each tier's result for that duration. With
+ *     k8s-style 1Hz probes against 10 checks, this drops the ambient
+ *     load substantially. Cache is per-tier (liveness cached separately
+ *     from readiness) — markShuttingDown bypasses readiness cache.
+ *
+ * Concurrent execution:
+ *   - All checks for a tier run via Promise.all with per-check withTimeout.
+ *   - One stuck check doesn't block the others; the timed-out check
+ *     fails as { ok: false, error: "timeout" } and the others complete.
+ */
+
+var safeAsync = require("../safe-async");
+var validateOpts = require("../validate-opts");
+var { defineClass } = require("../framework-error");
+
+var HealthError = defineClass("HealthError", { alwaysPermanent: true });
+
+var TIERS = Object.freeze(["liveness", "readiness", "startup"]);
+var TIER_SET = new Set(TIERS);
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "livenessPath", "readinessPath", "startupPath", "detailLevel",
+    "detailPredicate", "defaultTimeoutMs", "cacheMs", "includeMeta", "version",
+  ], "middleware.health");
+  var livenessPath  = opts.livenessPath  || "/healthz";
+  var readinessPath = opts.readinessPath || "/readyz";
+  var startupPath   = opts.startupPath   || "/startupz";
+  var detailLevel   = opts.detailLevel   || "minimal";
+  if (detailLevel !== "minimal" && detailLevel !== "detailed") {
+    throw new HealthError("health/bad-detail-level",
+      "detailLevel must be 'minimal' or 'detailed'");
+  }
+  var detailPredicate  = typeof opts.detailPredicate === "function" ? opts.detailPredicate : null;
+  var defaultTimeoutMs = typeof opts.defaultTimeoutMs === "number" && opts.defaultTimeoutMs > 0
+                          ? opts.defaultTimeoutMs : 5000;
+  var cacheMs = typeof opts.cacheMs === "number" && opts.cacheMs > 0 ? opts.cacheMs : 0;
+  var includeMeta = opts.includeMeta !== false;
+  var version = opts.version || null;
+
+  var checks = [];     // { name, fn, tiers: Set, timeoutMs, critical }
+  var shuttingDown = false;
+  var startedAt = Date.now();
+  var cache = {};      // tier → { result, expiresAt }
+
+  function registerCheck(name, fn, copts) {
+    if (typeof name !== "string" || name.length === 0) {
+      throw new HealthError("health/bad-name",
+        "registerCheck: name must be a non-empty string");
+    }
+    if (typeof fn !== "function") {
+      throw new HealthError("health/bad-fn",
+        "registerCheck: fn must be a function");
+    }
+    copts = copts || {};
+    var tier = copts.tier || "readiness";
+    var tiers = Array.isArray(tier) ? tier : [tier];
+    for (var i = 0; i < tiers.length; i++) {
+      if (!TIER_SET.has(tiers[i])) {
+        throw new HealthError("health/bad-tier",
+          "registerCheck: tier '" + tiers[i] + "' must be one of " + TIERS.join(", "));
+      }
+    }
+    // Refuse duplicate names within a tier — silent overwrite makes
+    // operator config bugs impossible to debug.
+    for (var j = 0; j < checks.length; j++) {
+      if (checks[j].name === name) {
+        for (var k = 0; k < tiers.length; k++) {
+          if (checks[j].tiers.has(tiers[k])) {
+            throw new HealthError("health/duplicate-check",
+              "registerCheck: check '" + name + "' already registered for tier '" + tiers[k] + "'");
+          }
+        }
+      }
+    }
+    var timeoutMs = typeof copts.timeoutMs === "number" && copts.timeoutMs > 0
+                      ? copts.timeoutMs : defaultTimeoutMs;
+    checks.push({
+      name:      name,
+      fn:        fn,
+      tiers:     new Set(tiers),
+      timeoutMs: timeoutMs,
+      critical:  copts.critical !== false,
+    });
+  }
+
+  // Bypass cache when shuttingDown was just flipped; readiness must
+  // surface 503 immediately, not wait for the cache window to expire.
+  function _bypassCacheFor(tier) {
+    return tier === "readiness" && shuttingDown;
+  }
+
+  async function runChecks(tier) {
+    if (!TIER_SET.has(tier)) {
+      throw new HealthError("health/bad-tier", "runChecks: tier must be one of " + TIERS.join(", "));
+    }
+    if (cacheMs > 0 && !_bypassCacheFor(tier)) {
+      var cached = cache[tier];
+      if (cached && cached.expiresAt > Date.now()) return cached.result;
+    }
+    var tierChecks = checks.filter(function (c) { return c.tiers.has(tier); });
+    var promises = tierChecks.map(function (c) {
+      var start = Date.now();
+      // Wrap the check in withTimeout. Promise.resolve() coerces sync
+      // returns into Promises so the timeout can be applied uniformly.
+      return safeAsync.withTimeout(
+          Promise.resolve().then(function () { return c.fn(); }),
+          c.timeoutMs,
+          { name: "health-check:" + c.name }
+        )
+        .then(function (raw) {
+          var ok, detail;
+          if (raw === true) { ok = true; detail = null; }
+          else if (raw === false) { ok = false; detail = null; }
+          else if (raw && typeof raw === "object") {
+            ok = !!raw.ok;
+            detail = raw;
+          } else {
+            // Truthy non-boolean / non-object → treat as ok=true. Falsy → ok=false.
+            ok = !!raw;
+            detail = null;
+          }
+          return {
+            name:     c.name,
+            ok:       ok,
+            detail:   detail,
+            ms:       Date.now() - start,
+            critical: c.critical,
+          };
+        })
+        .catch(function (err) {
+          return {
+            name:     c.name,
+            ok:       false,
+            error:    (err && err.message) || String(err),
+            ms:       Date.now() - start,
+            critical: c.critical,
+          };
+        });
+    });
+
+    var checked = await Promise.all(promises);
+    var results = {};
+    var anyFailed = false;
+    var anyCriticalFailed = false;
+    for (var i = 0; i < checked.length; i++) {
+      var r = checked[i];
+      var entry = { ok: r.ok, ms: r.ms };
+      if (r.detail) {
+        // Merge detail keys other than `ok` into the entry.
+        var keys = Object.keys(r.detail);
+        for (var n = 0; n < keys.length; n++) {
+          if (keys[n] !== "ok") entry[keys[n]] = r.detail[keys[n]];
+        }
+      }
+      if (r.error) entry.error = r.error;
+      if (!r.critical) entry.critical = false;
+      results[r.name] = entry;
+      if (!r.ok) {
+        anyFailed = true;
+        if (r.critical) anyCriticalFailed = true;
+      }
+    }
+
+    var status;
+    if (tier === "readiness" && shuttingDown) status = "shutting-down";
+    else if (anyCriticalFailed) status = "fail";
+    else if (anyFailed) status = "degraded";
+    else status = "ok";
+
+    var result = { status: status, checks: results, tier: tier, shuttingDown: shuttingDown };
+    if (cacheMs > 0 && !_bypassCacheFor(tier)) {
+      cache[tier] = { result: result, expiresAt: Date.now() + cacheMs };
+    }
+    return result;
+  }
+
+  function _writeResponse(res, result, includeDetail) {
+    var status = (result.status === "ok" || result.status === "degraded") ? 200 : 503;
+    var payload;
+    if (includeDetail) {
+      payload = { status: result.status, checks: result.checks };
+      if (includeMeta) {
+        payload.uptime = Date.now() - startedAt;
+        if (version) payload.version = version;
+      }
+    } else {
+      payload = { status: result.status };
+    }
+    var body = JSON.stringify(payload);
+    res.writeHead(status, {
+      "Content-Type":   "application/json; charset=utf-8",
+      "Content-Length": Buffer.byteLength(body),
+      "Cache-Control":  "no-store",
+    });
+    res.end(body);
+  }
+
+  function _wantDetail(req) {
+    if (detailLevel === "detailed") return true;
+    if (!detailPredicate) return false;
+    try { return !!detailPredicate(req); }
+    catch (_e) { return false; /* fail-closed */ }
+  }
+
+  function middleware() {
+    return async function health(req, res, next) {
+      if (req.method !== "GET" && req.method !== "HEAD") return next();
+      var url = req.url || "";
+      var path = url.split("?")[0];
+      var tier;
+      if (path === livenessPath)       tier = "liveness";
+      else if (path === readinessPath) tier = "readiness";
+      else if (path === startupPath)   tier = "startup";
+      else return next();
+
+      try {
+        var result = await runChecks(tier);
+        if (req.method === "HEAD") {
+          // HEAD: status code only, no body.
+          var status = (result.status === "ok" || result.status === "degraded") ? 200 : 503;
+          res.writeHead(status, { "Cache-Control": "no-store" });
+          res.end();
+          return;
+        }
+        _writeResponse(res, result, _wantDetail(req));
+      } catch {
+        // Catastrophic — write 503 with minimal detail and never leak
+        // internal error info on a public endpoint.
+        var body = JSON.stringify({ status: "fail", error: "health-check-internal" });
+        res.writeHead(503, {
+          "Content-Type":   "application/json; charset=utf-8",
+          "Content-Length": Buffer.byteLength(body),
+          "Cache-Control":  "no-store",
+        });
+        res.end(body);
+      }
+    };
+  }
+
+  function markShuttingDown() { shuttingDown = true; }
+  function isShuttingDown()   { return shuttingDown; }
+  function uptime()           { return Date.now() - startedAt; }
+
+  function _resetForTest() {
+    checks = [];
+    shuttingDown = false;
+    startedAt = Date.now();
+    cache = {};
+  }
+
+  return {
+    registerCheck:    registerCheck,
+    middleware:       middleware,
+    runChecks:        runChecks,
+    markShuttingDown: markShuttingDown,
+    isShuttingDown:   isShuttingDown,
+    uptime:           uptime,
+    _resetForTest:    _resetForTest,
+  };
+}
+
+module.exports = {
+  create:      create,
+  HealthError: HealthError,
+  TIERS:       TIERS,
+};