@blamejs/core 0.7.107 → 0.8.4

package/lib/auth/acr-vocabulary.js

@@ -0,0 +1,265 @@
+"use strict";
+/**
+ * ACR (Authentication Context Class Reference) vocabulary.
+ *
+ * The `acr` claim is RFC 9470 §3 + OIDC Core 1.0 §2 + ISO/IEC 29115. It
+ * denotes the rigor of the authentication ceremony that backs the
+ * current session — operators reason about it the same way they reason
+ * about NIST 800-63-4 AAL bands, but ACR carries finer granularity: it
+ * also encodes WHICH method achieved the strength.
+ *
+ * The framework ships a built-in dictionary of well-known ACR values
+ * with a strength-rank assigned from the spec authors' intent, but the
+ * dictionary is operator-extendable: every ACR your IdP issues should
+ * be registered with `register({ value, rank })` so policy decisions
+ * can compare what the request carries against what the route requires.
+ *
+ * Built-in vocabulary (rank ascending):
+ *
+ *   "0"                     → no authentication (public access)
+ *   "1"                     → password / single-factor (OIDC Core)
+ *   "loa1" / "low"          → loa1 / iso-29115 LOA-1 (low confidence)
+ *   "phr"                   → phishing-resistant single-factor
+ *                             (RFC 9470 example value)
+ *   "loa2" / "substantial"  → multi-factor, ISO LOA-2
+ *   "2"                     → multi-factor (OIDC Core)
+ *   "phrh"                  → phishing-resistant + hardware (RFC 9470)
+ *   "loa3" / "high"         → multi-factor + phishing-resistant + hw
+ *   "loa4"                  → in-person verified, hardware-bound
+ *   "urn:mace:incommon:iap:bronze"  → InCommon LoA-1
+ *   "urn:mace:incommon:iap:silver"  → InCommon LoA-2
+ *   "urn:mace:incommon:iap:gold"    → InCommon LoA-3
+ *   "aal1" / "aal2" / "aal3"        → NIST 800-63-4 (cross-walked)
+ *   "ial1" / "ial2" / "ial3"        → NIST 800-63A identity (cross-walked)
+ *   "fal1" / "fal2" / "fal3"        → NIST 800-63C federation
+ *
+ * Operators with a private vocabulary register before evaluation:
+ *
+ *   b.auth.acr.register({ value: "myco:strong", rank: 70 });
+ *
+ * Ranks are operator-comparable integers in [0, 100]. The framework's
+ * built-ins occupy the ranges:
+ *
+ *   0–9    public / unauthenticated
+ *   10–29  single factor
+ *   30–49  multi-factor
+ *   50–69  phishing-resistant multi-factor
+ *   70–89  hardware-bound + phishing-resistant
+ *   90–100 in-person identity-proofed + hardware
+ *
+ * ACR is a STRING value carried in the `acr` JWT claim. Some IdPs emit
+ * the value directly; others stuff a JSON-array of ACRs into the
+ * `acr_values` parameter and let the policy engine pick. The framework
+ * accepts both.
+ *
+ * AMR (Authentication Methods References) per RFC 8176 is a separate
+ * but adjacent vocabulary — it lists WHICH methods were used (e.g.
+ * `["pwd", "otp"]` for password+TOTP). The framework's policy engine
+ * also evaluates AMR: a route requiring `requiredAmr: ["hwk"]`
+ * (hardware-key per RFC 8176) rejects sessions whose AMR lacks `hwk`
+ * even when their ACR ranks high enough.
+ */
+
+var validateOpts = require("../validate-opts");
+var { AuthError } = require("../framework-error");
+
+// Core ranks — ascending strength. Operator-extendable via register().
+var BUILTIN_RANKS = {
+  // Public / unauthenticated
+  "0":                                 0,
+
+  // Single factor
+  "1":                                 10,
+  "loa1":                              10,
+  "low":                               10,
+  "ial1":                              10,
+  "fal1":                              10,
+  "aal1":                              10,
+  "urn:mace:incommon:iap:bronze":      12,
+
+  // Phishing-resistant single factor (e.g. mTLS)
+  "phr":                               25,
+
+  // Multi-factor
+  "2":                                 30,
+  "loa2":                              30,
+  "substantial":                       30,
+  "ial2":                              30,
+  "fal2":                              30,
+  "aal2":                              35,
+  "urn:mace:incommon:iap:silver":      32,    // allow:raw-byte-literal — ACR rank, not bytes
+
+  // Phishing-resistant multi-factor (passkey UV)
+  "phrh":                              60,    // allow:raw-time-literal — ACR rank, not seconds
+
+  // Hardware-bound + phishing-resistant + multi-factor
+  "loa3":                              70,
+  "high":                              70,
+  "ial3":                              75,
+  "fal3":                              75,
+  "aal3":                              75,
+  "urn:mace:incommon:iap:gold":        80,    // allow:raw-byte-literal — ACR rank, not bytes
+
+  // In-person identity-proofed + hardware-bound
+  "loa4":                              95,
+};
+
+// AMR catalog per RFC 8176 — used for requiredAmr policy evaluation.
+// Each entry maps the canonical RFC 8176 short-form to a category that
+// allows operators to evaluate broad classes (e.g. "any phishing-
+// resistant method" → `category: "phishing-resistant"`).
+var BUILTIN_AMR = {
+  "face":   { category: "biometric",          phishingResistant: false },
+  "fpt":    { category: "biometric",          phishingResistant: false },
+  "geo":    { category: "context",            phishingResistant: false },
+  "hwk":    { category: "hardware",           phishingResistant: true  },
+  "iris":   { category: "biometric",          phishingResistant: false },
+  "kba":    { category: "knowledge",          phishingResistant: false },
+  "mca":    { category: "multi-channel",      phishingResistant: false },
+  "mfa":    { category: "composite",          phishingResistant: false },
+  "otp":    { category: "out-of-band",        phishingResistant: false },
+  "pin":    { category: "knowledge",          phishingResistant: false },
+  "pop":    { category: "proof-of-possession", phishingResistant: true },
+  "pwd":    { category: "knowledge",          phishingResistant: false },
+  "rba":    { category: "context",            phishingResistant: false },
+  "retina": { category: "biometric",          phishingResistant: false },
+  "sc":     { category: "smart-card",         phishingResistant: true  },
+  "sms":    { category: "out-of-band",        phishingResistant: false },
+  "swk":    { category: "software-key",       phishingResistant: false },
+  "tel":    { category: "out-of-band",        phishingResistant: false },
+  "user":   { category: "user-presence",      phishingResistant: false },
+  "vbm":    { category: "biometric",          phishingResistant: false },
+  "wia":    { category: "windows-integrated", phishingResistant: false },
+};
+
+// In-process registry — operators may extend (and re-extend) at boot.
+var _registry = Object.create(null);
+for (var k in BUILTIN_RANKS) {
+  if (Object.prototype.hasOwnProperty.call(BUILTIN_RANKS, k)) {
+    _registry[k] = BUILTIN_RANKS[k];
+  }
+}
+
+function register(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["value", "rank"], "auth.acr.register");
+  validateOpts.requireNonEmptyString(opts.value, "register: value",
+    AuthError, "auth-stepUp/bad-acr");
+  if (typeof opts.rank !== "number" || !isFinite(opts.rank)) {
+    throw new AuthError("auth-stepUp/bad-rank",
+      "auth.acr.register: rank must be a finite number — got " +
+      JSON.stringify(opts.rank));
+  }
+  if (opts.rank < 0 || opts.rank > 100) {
+    throw new AuthError("auth-stepUp/bad-rank",
+      "auth.acr.register: rank must be in [0, 100] — got " + opts.rank);
+  }
+  _registry[opts.value] = opts.rank;
+  return { value: opts.value, rank: opts.rank };
+}
+
+function rankOf(value) {
+  if (typeof value !== "string" || value.length === 0) return -1;
+  if (Object.prototype.hasOwnProperty.call(_registry, value)) {
+    return _registry[value];
+  }
+  return -1;
+}
+
+function isRegistered(value) {
+  return rankOf(value) !== -1;
+}
+
+function listRegistered() {
+  var out = [];
+  for (var k in _registry) {
+    if (Object.prototype.hasOwnProperty.call(_registry, k)) {
+      out.push({ value: k, rank: _registry[k] });
+    }
+  }
+  out.sort(function (a, b) {
+    if (a.rank !== b.rank) return a.rank - b.rank;
+    if (a.value < b.value) return -1;
+    if (a.value > b.value) return 1;
+    return 0;
+  });
+  return out;
+}
+
+function meets(presented, required) {
+  if (typeof required !== "string") return true;
+  if (typeof presented !== "string") return false;
+  var rp = rankOf(presented);
+  var rr = rankOf(required);
+  if (rr === -1) {
+    throw new AuthError("auth-stepUp/unknown-acr",
+      "auth.acr.meets: required acr is not registered (call b.auth.acr.register first): " +
+      JSON.stringify(required));
+  }
+  if (rp === -1) return false;
+  return rp >= rr;
+}
+
+function meetsAny(presented, requiredList) {
+  if (!Array.isArray(requiredList) || requiredList.length === 0) return true;
+  for (var i = 0; i < requiredList.length; i += 1) {
+    if (meets(presented, requiredList[i])) return true;
+  }
+  return false;
+}
+
+function _classifyAmr(amrValue) {
+  if (typeof amrValue !== "string") return null;
+  if (Object.prototype.hasOwnProperty.call(BUILTIN_AMR, amrValue)) {
+    return BUILTIN_AMR[amrValue];
+  }
+  return null;
+}
+
+function amrIncludesPhishingResistant(amrList) {
+  if (!Array.isArray(amrList)) return false;
+  for (var i = 0; i < amrList.length; i += 1) {
+    var info = _classifyAmr(amrList[i]);
+    if (info && info.phishingResistant) return true;
+  }
+  return false;
+}
+
+function amrSatisfiesRequiredList(presentedAmr, required) {
+  if (!Array.isArray(required) || required.length === 0) return true;
+  if (!Array.isArray(presentedAmr)) return false;
+  var seen = Object.create(null);
+  for (var i = 0; i < presentedAmr.length; i += 1) {
+    if (typeof presentedAmr[i] === "string") seen[presentedAmr[i]] = true;
+  }
+  for (var j = 0; j < required.length; j += 1) {
+    if (!seen[required[j]]) return false;
+  }
+  return true;
+}
+
+// Reset hook — for tests only. Restores built-in registry.
+function _resetForTests() {
+  for (var k in _registry) {
+    if (Object.prototype.hasOwnProperty.call(_registry, k)) delete _registry[k];
+  }
+  for (var bk in BUILTIN_RANKS) {
+    if (Object.prototype.hasOwnProperty.call(BUILTIN_RANKS, bk)) {
+      _registry[bk] = BUILTIN_RANKS[bk];
+    }
+  }
+}
+
+module.exports = {
+  register:                       register,
+  rankOf:                         rankOf,
+  isRegistered:                   isRegistered,
+  listRegistered:                 listRegistered,
+  meets:                          meets,
+  meetsAny:                       meetsAny,
+  amrIncludesPhishingResistant:   amrIncludesPhishingResistant,
+  amrSatisfiesRequiredList:       amrSatisfiesRequiredList,
+  BUILTIN_RANKS:                  BUILTIN_RANKS,
+  BUILTIN_AMR:                    BUILTIN_AMR,
+  _resetForTests:                 _resetForTests,
+};

package/lib/auth/auth-time-tracker.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * auth_time enforcement helpers per RFC 9470 §3 + OIDC Core 1.0 §2.
+ *
+ * The `auth_time` JWT claim records the moment the user completed the
+ * authentication ceremony — NOT the moment the token was minted. A
+ * long-lived session that has been refreshed many times still carries
+ * the original `auth_time` until the user re-authenticates.
+ *
+ * RFC 9470 step-up flows compare the route's `max_age` (seconds since
+ * authentication) against the request's `auth_time`:
+ *
+ *   if (now - auth_time > max_age) → challenge with insufficient_user_authentication
+ *
+ * The framework ships:
+ *
+ *   ageSec(claims, now?)              → seconds since auth_time
+ *   freshEnough(claims, maxAgeSec)    → boolean
+ *   buildClaims({ method, prevAt? })  → { auth_time, amr } scaffold for IdP code
+ *   readClaims(rawClaims)             → normalized { auth_time, acr, amr }
+ *
+ * This module is method-side: it lives in lib/auth/ and consumes the
+ * already-verified JWT claims object (from b.auth.jwt.verify or the
+ * external resolver). It does not parse JWTs itself.
+ */
+
+var validateOpts = require("../validate-opts");
+var C = require("../constants");
+var { AuthError } = require("../framework-error");
+
+function _coerceClaim(claim) {
+  if (claim == null) return null;
+  if (typeof claim === "number" && isFinite(claim)) return claim;
+  if (typeof claim === "string") {
+    var parsed = parseInt(claim, 10);
+    if (isFinite(parsed)) return parsed;
+  }
+  return null;
+}
+
+function readClaims(rawClaims) {
+  if (!rawClaims || typeof rawClaims !== "object") {
+    return { auth_time: null, acr: null, amr: null };
+  }
+  var authTime = _coerceClaim(rawClaims.auth_time);
+  var acr      = (typeof rawClaims.acr === "string") ? rawClaims.acr : null;
+  var amr      = Array.isArray(rawClaims.amr) ? rawClaims.amr.slice() : null;
+  return { auth_time: authTime, acr: acr, amr: amr };
+}
+
+function ageSec(claims, now) {
+  var c = readClaims(claims);
+  if (c.auth_time == null) return null;
+  var nowSec = (typeof now === "number" && isFinite(now)) ? now : Math.floor(Date.now() / C.TIME.seconds(1));
+  if (c.auth_time > nowSec) return 0;     // clock skew — treat as fresh
+  return nowSec - c.auth_time;
+}
+
+function freshEnough(claims, maxAgeSec, now) {
+  if (typeof maxAgeSec !== "number" || !isFinite(maxAgeSec) || maxAgeSec < 0) {
+    throw new AuthError("auth-stepUp/bad-max-age",
+      "auth.authTime.freshEnough: maxAgeSec must be a finite number >= 0 — got " +
+      JSON.stringify(maxAgeSec));
+  }
+  var age = ageSec(claims, now);
+  if (age == null) return false;
+  return age <= maxAgeSec;
+}
+
+function buildClaims(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "method", "prevAt", "now", "amr", "acr",
+  ], "auth.authTime.buildClaims");
+  var nowSec = (typeof opts.now === "number" && isFinite(opts.now))
+    ? opts.now
+    : Math.floor(Date.now() / C.TIME.seconds(1));
+  var prev = _coerceClaim(opts.prevAt);
+  var authTime = nowSec;
+  if (typeof opts.method === "string" && opts.method === "refresh" && prev != null) {
+    authTime = prev;                                  // refresh preserves prior auth_time
+  }
+  var out = { auth_time: authTime };
+  if (Array.isArray(opts.amr)) out.amr = opts.amr.slice();
+  if (typeof opts.acr === "string" && opts.acr.length > 0) out.acr = opts.acr;
+  return out;
+}
+
+// Operator-side helper: given an existing token's claims and an
+// elevation requirement, return the minimum `max_age` we should allow
+// the IdP to use. Avoids handing the IdP a 0-or-skewed value.
+function recommendMaxAge(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "minSec", "maxSec", "default",
+  ], "auth.authTime.recommendMaxAge");
+  var min  = (typeof opts.minSec === "number") ? opts.minSec : (C.TIME.seconds(60) / C.TIME.seconds(1));
+  var max  = (typeof opts.maxSec === "number") ? opts.maxSec : (C.TIME.minutes(15) / C.TIME.seconds(1));
+  var dflt = (typeof opts.default === "number") ? opts.default : (C.TIME.minutes(5) / C.TIME.seconds(1));
+  if (dflt < min) dflt = min;
+  if (dflt > max) dflt = max;
+  return dflt;
+}
+
+module.exports = {
+  readClaims:        readClaims,
+  ageSec:            ageSec,
+  freshEnough:       freshEnough,
+  buildClaims:       buildClaims,
+  recommendMaxAge:   recommendMaxAge,
+};

package/lib/auth/elevation-grant.js

@@ -0,0 +1,306 @@
+"use strict";
+/**
+ * Step-up elevation grant — short-lived signed tokens that record a
+ * successful step-up ceremony. The grant is presented on subsequent
+ * sensitive requests (within a tight TTL) so the user does not face a
+ * step-up challenge on every action of a multi-step sensitive flow.
+ *
+ * Tokens are HMAC-SHA3-512 signed (single-key on the operator's side —
+ * not asymmetric since these never leave the resource server). The
+ * payload binds:
+ *
+ *   subject   — the authenticated user / session
+ *   scope     — operator-defined string (e.g. "billing:write",
+ *               "admin:bulk-update", "phi:read")
+ *   acr       — the achieved ACR value at step-up time
+ *   amr       — the methods that satisfied step-up (RFC 8176)
+ *   evidence  — operator-supplied opaque blob (audit/forensic value
+ *               only — never trust to drive policy)
+ *   iat / exp / jti
+ *
+ * Tokens are revocable: revoke(jti) adds the jti to an in-process
+ * deny-set checked by verify(). Operators with multi-node clusters
+ * pass `revokedSet` opt to back the deny-set with their own KV.
+ *
+ * Token format: base64url(JSON-payload) + "." + base64url(HMAC).
+ *
+ * Per the validation-tier policy: create() throws on bad opts (config-
+ * time entry-point); verify() returns structured errors (hot path).
+ */
+
+var nodeCrypto    = require("crypto");
+var validateOpts  = require("../validate-opts");
+var lazyRequire   = require("../lazy-require");
+var safeJson      = require("../safe-json");
+var C             = require("../constants");
+var { AuthError } = require("../framework-error");
+
+var audit         = lazyRequire(function () { return require("../audit"); });
+var fwCrypto      = lazyRequire(function () { return require("../crypto"); });
+
+var DEFAULT_TTL_SEC      = C.TIME.minutes(15) / C.TIME.seconds(1);
+var MAX_TTL_SEC          = C.TIME.hours(1)    / C.TIME.seconds(1);
+var MIN_TTL_SEC          = C.TIME.seconds(30) / C.TIME.seconds(1);
+var DEFAULT_KEY_BYTES    = C.BYTES.bytes(64);
+var MAC_BYTES            = C.BYTES.bytes(64);
+var MIN_KEY_BYTES        = C.BYTES.bytes(32);
+
+// In-process state.
+var _signingKey   = null;
+var _revokedSet   = Object.create(null);
+var _activeGrants = Object.create(null);   // jti → { exp, subject } for list()
+
+function _ensureSigningKey() {
+  if (_signingKey != null) return _signingKey;
+  _signingKey = nodeCrypto.randomBytes(DEFAULT_KEY_BYTES);
+  return _signingKey;
+}
+
+function setSigningKey(keyBuffer) {
+  if (!Buffer.isBuffer(keyBuffer) || keyBuffer.length < MIN_KEY_BYTES) {
+    throw new AuthError("auth-stepUp/bad-key",
+      "auth.stepUp.grant.setSigningKey: keyBuffer must be a Buffer of >= " +
+      MIN_KEY_BYTES + " bytes");
+  }
+  _signingKey = Buffer.from(keyBuffer);                       // copy — caller may mutate
+}
+
+function _b64url(buf) {
+  return Buffer.from(buf).toString("base64url");
+}
+
+function _b64urlDecode(str) {
+  if (typeof str !== "string") return null;
+  try { return Buffer.from(str, "base64url"); }
+  catch (_e) { return null; }
+}
+
+function _macFor(payloadB64) {
+  var key = _ensureSigningKey();
+  return nodeCrypto.createHmac("sha3-512", key).update(payloadB64).digest();
+}
+
+function _timingSafeEqualBuf(a, b) {
+  if (!Buffer.isBuffer(a) || !Buffer.isBuffer(b)) return false;
+  return fwCrypto().timingSafeEqual(a, b);
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "subject", "scope", "acr", "amr", "evidence",
+    "ttlSec", "audience", "now",
+  ], "auth.stepUp.grant.create");
+  validateOpts.requireNonEmptyString(opts.subject,
+    "grant.create: subject", AuthError, "auth-stepUp/bad-grant");
+  validateOpts.requireNonEmptyString(opts.scope,
+    "grant.create: scope", AuthError, "auth-stepUp/bad-grant");
+  if (opts.acr != null) {
+    validateOpts.requireNonEmptyString(opts.acr,
+      "grant.create: acr", AuthError, "auth-stepUp/bad-grant");
+  }
+  if (opts.amr != null) {
+    if (!Array.isArray(opts.amr)) {
+      throw new AuthError("auth-stepUp/bad-grant",
+        "grant.create: amr must be an array — got " + typeof opts.amr);
+    }
+    for (var i = 0; i < opts.amr.length; i += 1) {
+      if (typeof opts.amr[i] !== "string") {
+        throw new AuthError("auth-stepUp/bad-grant",
+          "grant.create: amr[" + i + "] must be a string");
+      }
+    }
+  }
+  if (opts.audience != null) {
+    validateOpts.requireNonEmptyString(opts.audience,
+      "grant.create: audience", AuthError, "auth-stepUp/bad-grant");
+  }
+  var ttlSec = (typeof opts.ttlSec === "number") ? opts.ttlSec : DEFAULT_TTL_SEC;
+  if (!isFinite(ttlSec) || ttlSec < MIN_TTL_SEC) {
+    throw new AuthError("auth-stepUp/bad-grant",
+      "grant.create: ttlSec must be a finite number >= " +
+      MIN_TTL_SEC + " — got " + JSON.stringify(opts.ttlSec));
+  }
+  if (ttlSec > MAX_TTL_SEC) {
+    throw new AuthError("auth-stepUp/bad-grant",
+      "grant.create: ttlSec must be <= " + MAX_TTL_SEC +
+      " (1h hard ceiling) — got " + ttlSec);
+  }
+  var nowSec = (typeof opts.now === "number" && isFinite(opts.now))
+    ? opts.now : Math.floor(Date.now() / C.TIME.seconds(1));
+  var jti = fwCrypto().generateBytes(C.BYTES.bytes(16)).toString("base64url");
+  var payload = {
+    sub:      opts.subject,
+    scope:    opts.scope,
+    acr:      opts.acr || null,
+    amr:      Array.isArray(opts.amr) ? opts.amr.slice() : null,
+    aud:      opts.audience || null,
+    iat:      nowSec,
+    exp:      nowSec + ttlSec,
+    jti:      jti,
+  };
+  if (opts.evidence != null) {
+    payload.evd = opts.evidence;                       // opaque pass-through
+  }
+  var payloadJson = JSON.stringify(payload);
+  var payloadB64  = _b64url(payloadJson);
+  var mac         = _macFor(payloadB64);
+  var token       = payloadB64 + "." + _b64url(mac);
+
+  _activeGrants[jti] = { exp: payload.exp, subject: opts.subject, scope: opts.scope };
+
+  try {
+    audit().safeEmit({
+      action:  "auth.stepup.grant.issued",
+      outcome: "success",
+      actor:   { userId: opts.subject },
+      metadata: {
+        jti:    jti,
+        scope:  opts.scope,
+        acr:    opts.acr || null,
+        amr:    Array.isArray(opts.amr) ? opts.amr.slice() : null,
+        ttl:    ttlSec,
+      },
+    });
+  } catch (_e) { /* drop-silent */ }
+
+  return { token: token, expiresAt: payload.exp, jti: jti, payload: payload };
+}
+
+function verify(token, opts) {
+  opts = opts || {};
+  if (typeof token !== "string" || token.length === 0) {
+    return { ok: false, error: "no_token", reason: "verify: token must be a non-empty string" };
+  }
+  validateOpts(opts, [
+    "audience", "scope", "subject", "now",
+  ], "auth.stepUp.grant.verify");
+  var dot = token.indexOf(".");
+  if (dot === -1) {
+    return { ok: false, error: "malformed", reason: "verify: token missing '.' separator" };
+  }
+  var payloadB64 = token.slice(0, dot);
+  var macB64     = token.slice(dot + 1);
+  var presentedMac = _b64urlDecode(macB64);
+  if (presentedMac == null || presentedMac.length !== MAC_BYTES) {
+    return { ok: false, error: "malformed", reason: "verify: mac decode failed or wrong length" };
+  }
+  var expectedMac = _macFor(payloadB64);
+  if (!_timingSafeEqualBuf(presentedMac, expectedMac)) {
+    return { ok: false, error: "bad_mac", reason: "verify: mac mismatch" };
+  }
+  var payloadBuf = _b64urlDecode(payloadB64);
+  if (payloadBuf == null) {
+    return { ok: false, error: "malformed", reason: "verify: payload decode failed" };
+  }
+  var payload;
+  try { payload = safeJson.parse(payloadBuf.toString("utf8"), { maxBytes: C.BYTES.kib(8) }); }
+  catch (_e) { return { ok: false, error: "malformed", reason: "verify: payload JSON parse failed" }; }
+  if (!payload || typeof payload !== "object") {
+    return { ok: false, error: "malformed", reason: "verify: payload not an object" };
+  }
+  var nowSec = (typeof opts.now === "number" && isFinite(opts.now))
+    ? opts.now : Math.floor(Date.now() / C.TIME.seconds(1));
+  if (typeof payload.exp !== "number" || payload.exp < nowSec) {
+    return { ok: false, error: "expired", reason: "verify: token expired (exp=" + payload.exp + ", now=" + nowSec + ")" };
+  }
+  if (typeof payload.iat !== "number" ||
+      payload.iat > nowSec + (C.TIME.seconds(60) / C.TIME.seconds(1))) {
+    return { ok: false, error: "future_iat", reason: "verify: iat is in the future" };
+  }
+  if (opts.audience != null && payload.aud !== opts.audience) {
+    return { ok: false, error: "audience_mismatch",
+             reason: "verify: audience " + JSON.stringify(payload.aud) +
+                     " does not match required " + JSON.stringify(opts.audience) };
+  }
+  if (opts.scope != null && payload.scope !== opts.scope) {
+    return { ok: false, error: "scope_mismatch",
+             reason: "verify: scope " + JSON.stringify(payload.scope) +
+                     " does not match required " + JSON.stringify(opts.scope) };
+  }
+  if (opts.subject != null && payload.sub !== opts.subject) {
+    return { ok: false, error: "subject_mismatch",
+             reason: "verify: subject " + JSON.stringify(payload.sub) +
+                     " does not match required " + JSON.stringify(opts.subject) };
+  }
+  if (typeof payload.jti === "string" && _revokedSet[payload.jti] === true) {
+    return { ok: false, error: "revoked", reason: "verify: jti has been revoked" };
+  }
+
+  try {
+    audit().safeEmit({
+      action:  "auth.stepup.grant.consumed",
+      outcome: "success",
+      actor:   { userId: payload.sub },
+      metadata: {
+        jti:   payload.jti || null,
+        scope: payload.scope,
+        aud:   payload.aud || null,
+      },
+    });
+  } catch (_e) { /* drop-silent */ }
+
+  return { ok: true, payload: payload };
+}
+
+function revoke(jti, opts) {
+  opts = opts || {};
+  validateOpts(opts, ["reason"], "auth.stepUp.grant.revoke");
+  if (typeof jti !== "string" || jti.length === 0) {
+    throw new AuthError("auth-stepUp/bad-jti",
+      "grant.revoke: jti must be a non-empty string — got " + JSON.stringify(jti));
+  }
+  _revokedSet[jti] = true;
+  var prior = _activeGrants[jti];
+  delete _activeGrants[jti];
+
+  try {
+    audit().safeEmit({
+      action:  "auth.stepup.grant.revoked",
+      outcome: "success",
+      actor:   { userId: prior && prior.subject || null },
+      metadata: { jti: jti, reason: opts.reason || null },
+    });
+  } catch (_e) { /* drop-silent */ }
+
+  return { ok: true, jti: jti };
+}
+
+function isRevoked(jti) {
+  if (typeof jti !== "string") return false;
+  return _revokedSet[jti] === true;
+}
+
+function list() {
+  var nowSec = Math.floor(Date.now() / C.TIME.seconds(1));
+  var out = [];
+  for (var jti in _activeGrants) {
+    if (Object.prototype.hasOwnProperty.call(_activeGrants, jti)) {
+      var entry = _activeGrants[jti];
+      if (entry.exp > nowSec && !_revokedSet[jti]) {
+        out.push({ jti: jti, subject: entry.subject, scope: entry.scope, exp: entry.exp });
+      }
+    }
+  }
+  out.sort(function (a, b) { return a.exp - b.exp; });
+  return out;
+}
+
+function _resetForTests() {
+  _signingKey = null;
+  _revokedSet = Object.create(null);
+  _activeGrants = Object.create(null);
+}
+
+module.exports = {
+  create:           create,
+  verify:           verify,
+  revoke:           revoke,
+  isRevoked:        isRevoked,
+  list:             list,
+  setSigningKey:    setSigningKey,
+  DEFAULT_TTL_SEC:  DEFAULT_TTL_SEC,
+  MAX_TTL_SEC:      MAX_TTL_SEC,
+  MIN_TTL_SEC:      MIN_TTL_SEC,
+  _resetForTests:   _resetForTests,
+};