@blamejs/core 0.8.42 → 0.8.49

package/lib/time.js

@@ -1,28 +1,34 @@
 "use strict";
 /**
- * time — timezone-aware datetime arithmetic + formatting on top of
- * native `Intl.DateTimeFormat`. No TZ-database vendor; operators get
- * the IANA names Node's ICU build supports (full set on every
- * mainstream platform).
+ * @module b.time
+ * @featured true
+ * @nav    Tools
+ * @title  Time
  *
- *   b.time.toParts(d, { timezone: "America/New_York" })
- *     → { year, month, day, hour, minute, second, millisecond,
- *         weekday: 1..7, weekdayName: "Mon"..."Sun", dayOfYear }
+ * @intro
+ *   Timezone-aware datetime helpers built on top of native
+ *   `Intl.DateTimeFormat`. No TZ-database vendor; operators get the
+ *   IANA names Node's ICU build supports (full set on every mainstream
+ *   platform).
  *
- *   b.time.format(d, { timezone, locale, dateStyle, timeStyle })
- *     → operator-readable string
+ *   The module covers four concerns: parsing ISO 8601 strings into
+ *   `Date`, decomposing an instant into calendar parts in a named
+ *   timezone, formatting an instant for human display, and DST-safe
+ *   calendar arithmetic (addDays / addMonths / startOfDay / endOfDay /
+ *   diffDays).
  *
- *   b.time.startOfDay(d, { timezone })   → midnight in TZ
- *   b.time.endOfDay(d, { timezone })     → 23:59:59.999 in TZ
- *   b.time.addDays(d, n, { timezone })   → calendar-day add (DST-safe)
- *   b.time.addMonths(d, n, { timezone }) → calendar-month add
- *   b.time.diffDays(a, b, { timezone })  → calendar days between
+ *   Every operation accepts a `Date`, a millisecond-epoch number, or
+ *   an ISO 8601 string interchangeably. The `timezone` opt defaults
+ *   to `"UTC"` and the `locale` opt defaults to `"en-US"`.
  *
- *   b.time.parseISO(s)                   → Date | throws TimeError
- *   b.time.tzOffsetMs(d, timezone)       → ms offset (= local - utc)
+ *   Calendar arithmetic anchors on parts in the requested timezone,
+ *   not on UTC milliseconds — so `addDays(d, 1, { timezone:
+ *   "America/New_York" })` always lands on the same wall-clock time
+ *   the next civil day, even across the spring-forward / fall-back
+ *   transitions.
  *
- * All ops accept Date, ms-epoch number, or ISO 8601 string. `timezone`
- * defaults to UTC. `locale` defaults to "en-US".
+ * @card
+ *   Timezone-aware datetime helpers built on top of native `Intl.DateTimeFormat`.
  */
 var C = require("./constants");
 var { defineClass } = require("./framework-error");
@@ -68,6 +74,35 @@ var WEEKDAY_TO_NUM = {
   "Mon": 1, "Tue": 2, "Wed": 3, "Thu": 4, "Fri": 5, "Sat": 6, "Sun": 7,
 };
 
+/**
+ * @primitive b.time.toParts
+ * @signature b.time.toParts(input, opts)
+ * @since     0.1.0
+ * @related   b.time.format, b.time.parseISO
+ *
+ * Decompose an instant into calendar parts as observed in a named
+ * timezone. Returns `{ year, month, day, hour, minute, second,
+ * millisecond, weekday: 1..7, weekdayName: "Mon".."Sun", dayOfYear }`.
+ * Weekday numbering follows ISO 8601 (Monday = 1, Sunday = 7).
+ *
+ * Accepts a `Date`, ms-epoch number, or ISO 8601 string. `timezone`
+ * defaults to `"UTC"`.
+ *
+ * @opts
+ *   timezone: string,   // IANA name; defaults to "UTC"
+ *
+ * @example
+ *   var parts = b.time.toParts("2026-05-09T14:30:00Z", {
+ *     timezone: "America/New_York",
+ *   });
+ *   parts.year;         // → 2026
+ *   parts.month;        // → 5
+ *   parts.day;          // → 9
+ *   parts.hour;         // → 10
+ *   parts.weekdayName;  // → "Sat"
+ *   parts.weekday;      // → 6
+ *   parts.dayOfYear;    // → 129
+ */
 function toParts(input, opts) {
   opts = opts || {};
   var date = _toDate(input);
@@ -111,6 +146,51 @@ function toParts(input, opts) {
   return out;
 }
 
+/**
+ * @primitive b.time.format
+ * @signature b.time.format(input, opts)
+ * @since     0.1.0
+ * @related   b.time.toParts, b.time.parseISO
+ *
+ * Render an instant as an operator-readable string in a named
+ * timezone and locale. Accepts the same `Date | number | string`
+ * input as the rest of the module. When neither `dateStyle` /
+ * `timeStyle` nor any per-field opt is supplied, defaults to
+ * `dateStyle: "medium"` + `timeStyle: "short"`.
+ *
+ * Per-field opts (`year` / `month` / `day` / `hour` / `minute` /
+ * `second` / `weekday` / `era` / `hour12` / `fractionalSecondDigits` /
+ * `timeZoneName`) pass through to `Intl.DateTimeFormat` unchanged.
+ *
+ * @opts
+ *   timezone: string,            // IANA name; defaults to "UTC"
+ *   locale:   string,            // BCP 47; defaults to "en-US"
+ *   dateStyle: string,           // "full" | "long" | "medium" | "short"
+ *   timeStyle: string,           // "full" | "long" | "medium" | "short"
+ *   year:     string,            // "numeric" | "2-digit"
+ *   month:    string,            // "numeric" | "2-digit" | "long" | "short" | "narrow"
+ *   day:      string,
+ *   hour:     string,
+ *   minute:   string,
+ *   second:   string,
+ *   weekday:  string,
+ *   era:      string,
+ *   hour12:   boolean,
+ *   fractionalSecondDigits: number,
+ *   timeZoneName: string,        // "long" | "short" | "shortOffset" | etc.
+ *
+ * @example
+ *   var when = "2026-05-09T14:30:00Z";
+ *   b.time.format(when, { timezone: "America/New_York" });
+ *   // → "May 9, 2026, 10:30 AM"
+ *
+ *   b.time.format(when, {
+ *     timezone: "Asia/Tokyo",
+ *     dateStyle: "full",
+ *     timeStyle: "long",
+ *   });
+ *   // → operator-readable Japanese-locale-style string
+ */
 function format(input, opts) {
   opts = opts || {};
   var date = _toDate(input);
@@ -136,6 +216,27 @@ function format(input, opts) {
   return _dtf(fmtOpts).format(date);
 }
 
+/**
+ * @primitive b.time.tzOffsetMs
+ * @signature b.time.tzOffsetMs(input, timezone)
+ * @since     0.1.0
+ * @related   b.time.toParts, b.time.startOfDay
+ *
+ * Compute the offset in milliseconds between the named timezone's
+ * local wall-clock and UTC at the given instant. Positive east of
+ * UTC, negative west. The value depends on the instant — DST
+ * transitions are honoured automatically.
+ *
+ * Throws `TimeError` when `timezone` is missing, non-string, or not
+ * an IANA name supported by Node's ICU build.
+ *
+ * @example
+ *   var offset = b.time.tzOffsetMs("2026-05-09T12:00:00Z", "America/New_York");
+ *   // → -14400000   (UTC-4 during DST; 4h * 60m * 60s * 1000ms)
+ *
+ *   var winter = b.time.tzOffsetMs("2026-01-15T12:00:00Z", "America/New_York");
+ *   // → -18000000   (UTC-5 in standard time)
+ */
 function tzOffsetMs(input, timezone) {
   var date = _toDate(input);
   if (!timezone || typeof timezone !== "string") {
@@ -179,6 +280,27 @@ function _fromPartsAtTz(p, timezone) {
   return new Date(step1 - (offset2 - offset1));
 }
 
+/**
+ * @primitive b.time.startOfDay
+ * @signature b.time.startOfDay(input, opts)
+ * @since     0.1.0
+ * @related   b.time.endOfDay, b.time.diffDays
+ *
+ * Return a `Date` pointing at midnight (00:00:00.000) of the input's
+ * civil day in the named timezone. DST-safe — the spring-forward day
+ * still resolves to the first valid wall-clock instant. Useful for
+ * day-bucketed audit queries and "is this still today?" comparisons.
+ *
+ * @opts
+ *   timezone: string,   // IANA name; defaults to "UTC"
+ *
+ * @example
+ *   var dayStart = b.time.startOfDay("2026-05-09T14:30:00Z", {
+ *     timezone: "America/New_York",
+ *   });
+ *   dayStart.toISOString();
+ *   // → "2026-05-09T04:00:00.000Z"   (midnight NY = 04:00 UTC during DST)
+ */
 function startOfDay(input, opts) {
   opts = opts || {};
   var tz = opts.timezone || DEFAULT_TIMEZONE;
@@ -189,6 +311,27 @@ function startOfDay(input, opts) {
   }, tz);
 }
 
+/**
+ * @primitive b.time.endOfDay
+ * @signature b.time.endOfDay(input, opts)
+ * @since     0.1.0
+ * @related   b.time.startOfDay, b.time.diffDays
+ *
+ * Return a `Date` pointing at the last representable millisecond
+ * (23:59:59.999) of the input's civil day in the named timezone.
+ * DST-safe. Pair with `startOfDay` to bracket "all events on day X
+ * in timezone Y" range queries.
+ *
+ * @opts
+ *   timezone: string,   // IANA name; defaults to "UTC"
+ *
+ * @example
+ *   var dayEnd = b.time.endOfDay("2026-05-09T14:30:00Z", {
+ *     timezone: "America/New_York",
+ *   });
+ *   dayEnd.toISOString();
+ *   // → "2026-05-10T03:59:59.999Z"   (23:59:59.999 NY = 03:59 next-day UTC)
+ */
 function endOfDay(input, opts) {
   opts = opts || {};
   var tz = opts.timezone || DEFAULT_TIMEZONE;
@@ -199,6 +342,34 @@ function endOfDay(input, opts) {
   }, tz);
 }
 
+/**
+ * @primitive b.time.addDays
+ * @signature b.time.addDays(input, n, opts)
+ * @since     0.1.0
+ * @related   b.time.addMonths, b.time.diffDays
+ *
+ * Add `n` calendar days to the input, anchored on the named
+ * timezone's wall clock. Negative `n` subtracts. Calendar-day
+ * arithmetic — the wall-clock hour / minute / second / millisecond
+ * stay the same across DST transitions, even though the resulting
+ * UTC offset between the two instants will differ by an hour around
+ * the transition.
+ *
+ * Throws `TimeError` when `n` is not a finite number.
+ *
+ * @opts
+ *   timezone: string,   // IANA name; defaults to "UTC"
+ *
+ * @example
+ *   var due = b.time.addDays("2026-05-09T14:30:00Z", 7, {
+ *     timezone: "America/New_York",
+ *   });
+ *   due.toISOString();
+ *   // → "2026-05-16T14:30:00.000Z"
+ *
+ *   // Subtract: "yesterday at this time"
+ *   var yesterday = b.time.addDays(Date.now(), -1, { timezone: "UTC" });
+ */
 function addDays(input, n, opts) {
   opts = opts || {};
   if (typeof n !== "number" || !isFinite(n)) {
@@ -216,6 +387,32 @@ function addDays(input, n, opts) {
   }, tz);
 }
 
+/**
+ * @primitive b.time.addMonths
+ * @signature b.time.addMonths(input, n, opts)
+ * @since     0.1.0
+ * @related   b.time.addDays, b.time.diffDays
+ *
+ * Add `n` calendar months to the input, anchored on the named
+ * timezone's wall clock. Negative `n` subtracts. End-of-month days
+ * clamp to the target month's last day — Jan 31 + 1 month is
+ * Feb 28/29, not "March 3". Wall-clock hour / minute / second /
+ * millisecond are preserved.
+ *
+ * Throws `TimeError` when `n` is not a finite number.
+ *
+ * @opts
+ *   timezone: string,   // IANA name; defaults to "UTC"
+ *
+ * @example
+ *   var renewal = b.time.addMonths("2026-01-31T09:00:00Z", 1, {
+ *     timezone: "UTC",
+ *   });
+ *   renewal.toISOString();
+ *   // → "2026-02-28T09:00:00.000Z"   (clamped: Feb has no day 31)
+ *
+ *   var nextQuarter = b.time.addMonths(Date.now(), 3, { timezone: "UTC" });
+ */
 function addMonths(input, n, opts) {
   opts = opts || {};
   if (typeof n !== "number" || !isFinite(n)) {
@@ -234,6 +431,32 @@ function addMonths(input, n, opts) {
   }, tz);
 }
 
+/**
+ * @primitive b.time.diffDays
+ * @signature b.time.diffDays(a, b, opts)
+ * @since     0.1.0
+ * @related   b.time.addDays, b.time.startOfDay
+ *
+ * Calendar days between two instants in the named timezone, computed
+ * as `startOfDay(b) - startOfDay(a)` rounded to whole days. Positive
+ * when `b` is after `a`; negative otherwise. Foundation for
+ * "X days ago" / "Y days until" relative formatting.
+ *
+ * @opts
+ *   timezone: string,   // IANA name; defaults to "UTC"
+ *
+ * @example
+ *   var posted = "2026-05-02T08:00:00Z";
+ *   var now    = "2026-05-09T14:30:00Z";
+ *   var ago    = b.time.diffDays(posted, now, { timezone: "UTC" });
+ *   // → 7
+ *
+ *   // "X days ago" relative formatting:
+ *   var label = ago === 0 ? "today"
+ *             : ago === 1 ? "yesterday"
+ *             : ago + " days ago";
+ *   // → "7 days ago"
+ */
 function diffDays(a, b, opts) {
   opts = opts || {};
   var tz = opts.timezone || DEFAULT_TIMEZONE;
@@ -244,6 +467,35 @@ function diffDays(a, b, opts) {
 
 var ISO_RE = /^(\d{4})-(\d{2})-(\d{2})(?:[T\s](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d+))?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
 
+/**
+ * @primitive b.time.parseISO
+ * @signature b.time.parseISO(s)
+ * @since     0.1.0
+ * @related   b.time.toIso8601NoMs, b.time.toParts
+ *
+ * Parse an ISO 8601 / RFC 3339 datetime string into a `Date`.
+ * Accepts `YYYY-MM-DD`, `YYYY-MM-DDTHH:MM`, `YYYY-MM-DDTHH:MM:SS`,
+ * optional `.sss` fractional seconds, and an optional trailing
+ * `Z` / `+HH:MM` / `-HH:MM` zone designator. A space separator
+ * between date and time is also accepted. Strings without a zone
+ * designator are interpreted as UTC.
+ *
+ * Throws `TimeError` for non-strings, malformed input, or
+ * out-of-range component values (month > 12, day > 31, hour > 23,
+ * etc.).
+ *
+ * @example
+ *   var d = b.time.parseISO("2026-05-09T14:30:00Z");
+ *   d.toISOString();        // → "2026-05-09T14:30:00.000Z"
+ *
+ *   // Offset zone:
+ *   var withOffset = b.time.parseISO("2026-05-09T10:30:00-04:00");
+ *   withOffset.toISOString();   // → "2026-05-09T14:30:00.000Z"
+ *
+ *   // Date-only (interpreted as UTC midnight):
+ *   var date = b.time.parseISO("2026-05-09");
+ *   date.toISOString();     // → "2026-05-09T00:00:00.000Z"
+ */
 function parseISO(s) {
   if (typeof s !== "string" || s.length === 0) {
     throw new TimeError("time/bad-iso", "parseISO: input must be a non-empty string");
@@ -283,12 +535,28 @@ function parseISO(s) {
   return new Date(utcMs);
 }
 
-// toIso8601NoMs — emit ISO 8601 with the trailing `.\d{3}Z`
-// milliseconds dropped (`2026-05-03T12:34:56Z` instead of
-// `…:56.789Z`). Used by SAS / SigV4 / log filename builders that need
-// a one-second-resolution timestamp string. Single source of truth so
-// the strip pattern lives in one place.
 var ISO_MS_RE = /\.\d{3}Z$/;
+
+/**
+ * @primitive b.time.toIso8601NoMs
+ * @signature b.time.toIso8601NoMs(input)
+ * @since     0.1.0
+ * @related   b.time.parseISO
+ *
+ * Emit an ISO 8601 string with the trailing `.sssZ` milliseconds
+ * dropped — produces `2026-05-09T14:30:00Z` instead of
+ * `2026-05-09T14:30:00.000Z`. Used by SAS / SigV4 / log-filename
+ * builders that need a one-second-resolution timestamp string. The
+ * strip pattern lives in one place so every caller agrees on the
+ * shape.
+ *
+ * @example
+ *   b.time.toIso8601NoMs("2026-05-09T14:30:00.789Z");
+ *   // → "2026-05-09T14:30:00Z"
+ *
+ *   b.time.toIso8601NoMs(new Date(Date.UTC(2026, 4, 9, 14, 30, 0)));
+ *   // → "2026-05-09T14:30:00Z"
+ */
 function toIso8601NoMs(input) {
   var d = _toDate(input);
   return d.toISOString().replace(ISO_MS_RE, "Z");

package/lib/tls-exporter.js

@@ -0,0 +1,239 @@
+"use strict";
+/**
+ * @module b.tlsExporter
+ * @nav    Crypto
+ * @title  TLS Exporter
+ *
+ * @intro
+ *   RFC 5705 / RFC 9266 TLS Exporter for binding application-layer
+ *   keys and tokens to the live TLS session. The exporter is a
+ *   deterministic byte-string derived from the TLS 1.3 master secret
+ *   (RFC 8446 §7.5) — pulling 32 bytes under the
+ *   `EXPORTER-Channel-Binding` label gives the RFC 9266
+ *   "tls-exporter" channel-binding identifier.
+ *
+ *   Operators bind bearer tokens, FAPI 2.0 access-token-bound proofs,
+ *   DPoP `cnf.tbh` claims, mTLS-derived auth headers, and session
+ *   cookies to the exporter so a captured token cannot be replayed
+ *   across a different TLS session — even if a downstream proxy
+ *   re-terminates TLS (RFC 8705). The matching node primitive is
+ *   `tls.TLSSocket#exportKeyingMaterial(length, label[, context])`.
+ *
+ *   Validation throws at the call site for sockets that aren't TLS
+ *   (channel binding has no meaning over plaintext), sockets whose
+ *   protocol is not TLS 1.3 (RFC 9266 §4 conformance), or
+ *   out-of-range `length` values. Mismatched bindings on
+ *   `verifyTokenBinding` return `false` rather than throwing —
+ *   token-binding mismatch is a normal request-time outcome, not a
+ *   config bug.
+ *
+ * @card
+ *   RFC 5705 / RFC 9266 TLS Exporter for binding application-layer keys and tokens to the live TLS session.
+ */
+
+var crypto = require("./crypto");
+var C = require("./constants");
+var lazyRequire = require("./lazy-require");
+var nb = require("./numeric-bounds");
+var { TlsExporterError } = require("./framework-error");
+
+var _err = TlsExporterError.factory;
+
+var observability = lazyRequire(function () { return require("./observability"); });
+
+var EXPORTER_LABEL = "EXPORTER-Channel-Binding";
+var EXPORTER_LENGTH = C.BYTES.bytes(32);
+
+// _resolveTlsSocket — accept either a TLSSocket directly OR an http2/
+// http(s) request whose .socket property is the TLSSocket. Operators
+// almost always pass req.socket; the helper normalizes to the
+// underlying socket so the exportKeyingMaterial call lands on the
+// right object.
+function _resolveTlsSocket(socketOrReq) {
+  if (!socketOrReq) {
+    throw _err("BAD_INPUT", "tlsExporter: socket or request object required");
+  }
+  // Express/Node http req → req.socket is the TLSSocket
+  var sock = socketOrReq;
+  if (typeof socketOrReq.exportKeyingMaterial !== "function" &&
+      socketOrReq.socket &&
+      typeof socketOrReq.socket.exportKeyingMaterial === "function") {
+    sock = socketOrReq.socket;
+  }
+  if (typeof sock.exportKeyingMaterial !== "function") {
+    throw _err("NOT_TLS",
+      "tlsExporter: socket has no exportKeyingMaterial — channel binding requires TLS");
+  }
+  // Per RFC 9266 §4 the exporter is only defined for TLS 1.3. Older
+  // protocol versions on the same API would technically return bytes
+  // but the channel-binding semantics are NOT RFC 9266 conformant —
+  // refuse so an operator-built check doesn't silently fall back to a
+  // weaker binding.
+  if (typeof sock.getProtocol === "function") {
+    var proto = sock.getProtocol();
+    if (proto && proto !== "TLSv1.3") {
+      throw _err("NOT_TLS_1_3",
+        "tlsExporter: TLS protocol is " + proto + ", RFC 9266 requires TLS 1.3");
+    }
+  }
+  return sock;
+}
+
+/**
+ * @primitive b.tlsExporter.fromSocket
+ * @signature b.tlsExporter.fromSocket(socketOrReq, opts)
+ * @since     0.7.45
+ * @status    stable
+ * @related   b.tlsExporter.bindToken, b.tlsExporter.verifyTokenBinding
+ *
+ * Extracts a TLS exporter from `socketOrReq` (either a `TLSSocket`
+ * directly or an HTTP/HTTP/2 request whose `.socket` is the
+ * `TLSSocket`). Defaults match RFC 9266 §4 — 32-byte length, label
+ * `EXPORTER-Channel-Binding`, no context — yielding the canonical
+ * "tls-exporter" channel-binding identifier. Custom labels and
+ * lengths pass through for applications defining their own exporter-
+ * derived identifiers; `length` is bounded 16..255 bytes per the
+ * keying-material range Node enforces. Throws when the socket is not
+ * TLS 1.3 or when the export call fails.
+ *
+ * @opts
+ *   {
+ *     label?:   string,    // default "EXPORTER-Channel-Binding"
+ *     length?:  number,    // default 32; bounded 16..255 bytes
+ *     context?: Buffer     // default null (RFC 8446 §7.5 "no context")
+ *   }
+ *
+ * @example
+ *   var b = require("blamejs").create();
+ *   var server = b.https.createServer({ key: KEY, cert: CERT }, function (req, res) {
+ *     var exporter = b.tlsExporter.fromSocket(req, { length: 32 });
+ *     res.end("exporter bytes: " + exporter.length);
+ *     // → "exporter bytes: 32"
+ *   });
+ *   server.listen(0);
+ */
+function fromSocket(socketOrReq, opts) {
+  opts = opts || {};
+  var label = typeof opts.label === "string" && opts.label.length > 0
+    ? opts.label : EXPORTER_LABEL;
+  // length is operator-tunable; validate-when-present via numeric-bounds
+  // so a non-finite / negative / NaN input surfaces with the same error
+  // shape every other framework primitive uses for numeric opts.
+  nb.requirePositiveFiniteIntIfPresent(opts.length,
+    "tlsExporter.fromSocket: length", TlsExporterError, "BAD_LENGTH");
+  var length = opts.length !== undefined ? opts.length : EXPORTER_LENGTH;
+  if (length < C.BYTES.bytes(16) || length > C.BYTES.bytes(255)) {
+    throw _err("BAD_LENGTH",
+      "tlsExporter.fromSocket: length must be 16..255 bytes (got " + length + ")");
+  }
+  var context = opts.context;
+  if (context !== undefined && context !== null && !Buffer.isBuffer(context)) {
+    throw _err("BAD_CONTEXT",
+      "tlsExporter.fromSocket: context must be Buffer or null");
+  }
+
+  var sock = _resolveTlsSocket(socketOrReq);
+  var bytes;
+  try {
+    // Node's exportKeyingMaterial signature: (length, label, [context]).
+    // Passing context=null (the default) corresponds to the RFC 8446
+    // §7.5 "no context" case which RFC 9266 §4 mandates for channel
+    // binding.
+    bytes = context
+      ? sock.exportKeyingMaterial(length, label, context)
+      : sock.exportKeyingMaterial(length, label);
+  } catch (e) {
+    throw _err("EXPORT_FAILED",
+      "tlsExporter.fromSocket: exportKeyingMaterial threw: " + e.message);
+  }
+  if (!Buffer.isBuffer(bytes) || bytes.length !== length) {
+    throw _err("EXPORT_SHORT",
+      "tlsExporter.fromSocket: short exporter (got " + (bytes && bytes.length) + " bytes, want " + length + ")");
+  }
+
+  try { observability().safeEvent("tlsExporter.fromSocket", 1, { outcome: "success" }); }
+  catch (_e) { /* drop-silent */ }
+  return bytes;
+}
+
+/**
+ * @primitive b.tlsExporter.bindToken
+ * @signature b.tlsExporter.bindToken(socketOrReq, token)
+ * @since     0.7.45
+ * @status    stable
+ * @related   b.tlsExporter.fromSocket, b.tlsExporter.verifyTokenBinding
+ *
+ * Binds an opaque token (string or Buffer) to the current TLS session
+ * by hashing `SHA3-512(label || exporter || token)`, where `label` is
+ * `"blamejs/tls-exporter/bind/v1"`. The framework label keeps the
+ * resulting digest distinct from any other place the same exporter +
+ * token bytes might be hashed (audit-chain rows, derived-hash columns,
+ * etc.) so a binding cannot be reinterpreted across primitives.
+ * Operators store the returned hex digest alongside the token and
+ * compare via `verifyTokenBinding` on the next request.
+ *
+ * @example
+ *   var b = require("blamejs").create();
+ *   b.https.createServer({ key: KEY, cert: CERT }, function (req, res) {
+ *     var binding = b.tlsExporter.bindToken(req, "session-token-abc123");
+ *     binding.length;
+ *     // → 128 (SHA3-512 hex digest, 64 bytes × 2 hex chars)
+ *     res.end("ok");
+ *   }).listen(0);
+ */
+function bindToken(socketOrReq, token) {
+  if (typeof token !== "string" && !Buffer.isBuffer(token)) {
+    throw _err("BAD_TOKEN",
+      "tlsExporter.bindToken: token must be a string or Buffer");
+  }
+  var exporter = fromSocket(socketOrReq);
+  var tokenBuf = Buffer.isBuffer(token) ? token : Buffer.from(token, "utf8");
+  // SHA3-512 of (label || exporter || token). The label binds the
+  // hash to "tls-exporter binding" so the same token + exporter pair
+  // does NOT produce the same hash if used in another framework
+  // primitive (e.g., the audit-chain row hash).
+  var labelBuf = Buffer.from("blamejs/tls-exporter/bind/v1", "utf8");
+  return crypto.sha3Hash(Buffer.concat([labelBuf, exporter, tokenBuf]));
+}
+
+/**
+ * @primitive b.tlsExporter.verifyTokenBinding
+ * @signature b.tlsExporter.verifyTokenBinding(socketOrReq, token, claimedBinding)
+ * @since     0.7.45
+ * @status    stable
+ * @related   b.tlsExporter.fromSocket, b.tlsExporter.bindToken
+ *
+ * Constant-time compare of a previously-issued `bindToken` digest
+ * against a fresh binding computed from the current TLS session.
+ * Returns `true` when the digests match (token belongs to this TLS
+ * session) and `false` on any mismatch — token-binding mismatch is a
+ * normal request-time outcome, so this primitive never throws on
+ * mismatch. Throws only when `socketOrReq` is not TLS 1.3 or when
+ * the input shape is wrong.
+ *
+ * @example
+ *   var b = require("blamejs").create();
+ *   b.https.createServer({ key: KEY, cert: CERT }, function (req, res) {
+ *     var stored = b.tlsExporter.bindToken(req, "session-token-abc123");
+ *     var ok = b.tlsExporter.verifyTokenBinding(req, "session-token-abc123", stored);
+ *     ok;
+ *     // → true
+ *     res.end(ok ? "bound" : "mismatch");
+ *   }).listen(0);
+ */
+function verifyTokenBinding(socketOrReq, token, claimedBinding) {
+  var actual = bindToken(socketOrReq, token);
+  if (typeof claimedBinding !== "string" || claimedBinding.length === 0) {
+    return false;
+  }
+  return crypto.timingSafeEqual(actual, claimedBinding);
+}
+
+module.exports = {
+  fromSocket:           fromSocket,
+  bindToken:            bindToken,
+  verifyTokenBinding:   verifyTokenBinding,
+  EXPORTER_LABEL:       EXPORTER_LABEL,
+  EXPORTER_LENGTH:      EXPORTER_LENGTH,
+  TlsExporterError:     TlsExporterError,
+};