@blamejs/blamejs-shop 0.0.44

package/lib/vendor/blamejs/lib/hal.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * @module b.hal
+ * @nav    HTTP
+ * @title  HAL hypermedia
+ * @order  173
+ *
+ * @intro
+ *   HAL (Hypertext Application Language, IETF draft-kelly-json-hal-08).
+ *   Wraps resources with `_links` + `_embedded` so clients discover
+ *   navigation + nested resources without out-of-band routing. The
+ *   spec is small; the framework's helper is correspondingly small.
+ *
+ *   Content-Type: `application/hal+json`
+ *
+ *   Reserved properties:
+ *     - `_links`     — { rel: linkObject | linkObject[] } per RFC 8288
+ *     - `_embedded`  — { rel: resource | resource[] }
+ *     - `_templates` — HAL-FORMS extension (operator-supplied)
+ *
+ * @card
+ *   HAL (draft-kelly-json-hal) + HAL-FORMS hypermedia response builder. Content-Type negotiation + _links/_embedded structure helpers per RFC 8288.
+ */
+
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var HalError = defineClass("HalError", { alwaysPermanent: true });
+
+var CONTENT_TYPE = "application/hal+json";
+
+/**
+ * @primitive b.hal.resource
+ * @signature b.hal.resource(payload, opts?)
+ * @since     0.10.16
+ * @status    stable
+ *
+ * Build a HAL resource. `payload` is the operator's domain object;
+ * `opts.links` is a map of `{ rel: href | linkObject | linkObject[] }`;
+ * `opts.embedded` is a map of `{ rel: resource | resource[] }`.
+ *
+ * @opts
+ *   links:    { [rel]: string | LinkObject | LinkObject[] },
+ *   embedded: { [rel]: object | object[] },
+ *   templates: { [name]: HalFormTemplate },     // HAL-FORMS extension
+ *
+ * @example
+ *   var r = b.hal.resource(
+ *     { title: "Hello", body: "World" },
+ *     { links: { self: "/articles/1",
+ *                next: { href: "/articles/2", title: "Next article" } } }
+ *   );
+ */
+function resource(payload, opts) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new HalError("hal/bad-payload",
+      "resource: payload must be a non-array object");
+  }
+  opts = opts || {};
+  validateOpts(opts, ["links", "embedded", "templates"], "hal.resource");
+  // Build resource by shallow-clone (don't mutate operator input).
+  var out = {};
+  var keys = Object.keys(payload);
+  for (var i = 0; i < keys.length; i += 1) {
+    var k = keys[i];
+    if (k === "_links" || k === "_embedded" || k === "_templates") {
+      // Operator-supplied reserved keys in payload override opts —
+      // refuse to avoid ambiguity.
+      throw new HalError("hal/reserved-key",
+        "resource: payload must not contain reserved key '" + k + "' (use opts." +
+        (k === "_templates" ? "templates" : k.slice(1)) + ")");
+    }
+    out[k] = payload[k];
+  }
+  if (opts.links) {
+    if (typeof opts.links !== "object" || Array.isArray(opts.links)) {
+      throw new HalError("hal/bad-links", "resource: opts.links must be a non-array object");
+    }
+    out._links = _normaliseLinks(opts.links);
+  }
+  if (opts.embedded) {
+    if (typeof opts.embedded !== "object" || Array.isArray(opts.embedded)) {
+      throw new HalError("hal/bad-embedded", "resource: opts.embedded must be a non-array object");
+    }
+    out._embedded = opts.embedded;
+  }
+  if (opts.templates) {
+    if (typeof opts.templates !== "object" || Array.isArray(opts.templates)) {
+      throw new HalError("hal/bad-templates", "resource: opts.templates must be a non-array object");
+    }
+    out._templates = opts.templates;
+  }
+  return out;
+}
+
+function _normaliseLinks(links) {
+  var out = {};
+  var keys = Object.keys(links);
+  for (var i = 0; i < keys.length; i += 1) {
+    var rel = keys[i];
+    var val = links[rel];
+    if (typeof val === "string") {
+      out[rel] = { href: val };
+    } else if (Array.isArray(val)) {
+      out[rel] = val.map(function (v, idx) {
+        if (typeof v === "string") return { href: v };
+        if (v && typeof v === "object" && typeof v.href === "string") return v;
+        throw new HalError("hal/bad-link",
+          "_links." + rel + "[" + idx + "] must be a string or LinkObject");
+      });
+    } else if (val && typeof val === "object" && typeof val.href === "string") {
+      out[rel] = val;
+    } else {
+      throw new HalError("hal/bad-link",
+        "_links." + rel + " must be a string, LinkObject, or LinkObject[]");
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  resource:      resource,
+  CONTENT_TYPE:  CONTENT_TYPE,
+  HalError:      HalError,
+};

package/lib/vendor/blamejs/lib/handlers.js

@@ -0,0 +1,350 @@
+"use strict";
+/**
+ * Async handler primitive — buffered emit + resilient drain.
+ *
+ * The framework has many "fire something off, don't block the request"
+ * surfaces: audit emissions from middleware/log-stream/external-db
+ * hooks, webhook deliveries, log lines being shipped to an external
+ * sink. Without a shared primitive, each surface tends toward a
+ * fire-and-forget Promise pattern, which has well-known failure modes:
+ *
+ *   - Errors disappear silently
+ *   - Promises leak across test/shutdown boundaries
+ *   - In cyclic dispatchers (storage emits about its own writes), the
+ *     pattern is the only thing preventing infinite recursion, but at
+ *     the cost of introducing a race
+ *   - "Did the work complete?" is unanswerable
+ *
+ * AsyncHandler replaces the pattern with a uniform contract that bakes
+ * resilience in by default — operators don't opt in to robustness; it
+ * is the framework's posture and surfaces only what the operator
+ * actively configures (DLQ destination, retry policy adjustments, etc).
+ *
+ * Public API:
+ *
+ *   handler.emit(item)           sync; buffers; never throws (errors go
+ *                                to onError); never returns a Promise
+ *   handler.drain(opts?)         async; flushes buffer to storage with
+ *                                retry + circuit breaker + DLQ;
+ *                                resolves when current backlog is done
+ *                                or breaker is open. opts.signal aborts.
+ *   handler.shutdown(opts?)      async; final drain with timeout (default
+ *                                30s); subsequent emit() drops with
+ *                                onError notification
+ *   handler.getStats()           snapshot of operational metrics
+ *
+ * Resilience layers (all on by default):
+ *
+ *   Retry — batches that fail flush() are retried with exponential
+ *           backoff + jitter (safeAsync.asyncRetry). Default 3 attempts.
+ *           Transient external-db hiccups recover automatically.
+ *
+ *   Circuit breaker — if `failureThreshold` consecutive batches fail
+ *           after retry exhaustion, the breaker OPENS. Subsequent
+ *           emit() calls fast-fail (item goes to DLQ via onError);
+ *           drain() returns immediately with a CIRCUIT_OPEN reason.
+ *           After `cooldownMs` the breaker enters HALF_OPEN and one
+ *           probe batch is allowed; success closes it, failure
+ *           re-opens with another cooldown. Bounded recovery.
+ *
+ *   Dead-letter queue — items that fail every retry land in DLQ via
+ *           the operator-supplied `deadLetter(items, error)` callback.
+ *           If no DLQ is configured, items go to onError with a
+ *           handler/dropped error. The DLQ is fire-and-forget from
+ *           the handler's perspective — the operator can write to a
+ *           file, an external queue, an audit row, anywhere durable.
+ *
+ *   Backpressure — buffer capped at `maxBufferSize` (default 10000);
+ *           emit() over the cap goes to onError + DLQ. Operators
+ *           sizing for high-throughput audit emit larger; default is
+ *           sized for "audit emissions piggyback on request handling."
+ *
+ *   AbortSignal — drain(opts?) accepts opts.signal; aborting cancels
+ *           the in-flight drain (current batch finishes; remaining
+ *           items stay in buffer for next drain).
+ *
+ *   Bounded shutdown — shutdown(opts?) drains with a timeout (default
+ *           30s). Items that don't flush in time go to DLQ or
+ *           onError; the call resolves so process exit isn't blocked.
+ *
+ * Recursion safety: when a handler is flushing, downstream code MAY
+ * emit MORE items into the same handler (e.g. audit.flush writes to
+ * external-db, which would normally audit-emit). Those additional
+ * items land in the buffer for the NEXT cycle (NOT the current batch),
+ * keeping batch sizes bounded. The flush function can mark its own
+ * writes with a sentinel (e.g. `{ skipAudit: true }`) so downstream
+ * emitters know to skip — caller-controlled, not handler concern.
+ *
+ * Metrics (handler.getStats()):
+ *   bufferSize, totalEmitted, totalFlushed, totalRetried,
+ *   totalDeadLettered, lastFlushDurationMs, breakerState.
+ *   Operators wire these to their monitoring; the handler does not
+ *   ship metrics anywhere on its own.
+ */
+
+var safeAsync = require("./safe-async");
+var C = require("./constants");
+var validateOpts = require("./validate-opts");
+var { HandlerError } = require("./framework-error");
+var { boot } = require("./log");
+
+var DEFAULTS = {
+  maxBatch:           100,
+  maxAgeMs:           C.TIME.seconds(1),
+  maxBufferSize:      C.BYTES.bytes(10000),
+  shutdownTimeoutMs:  C.TIME.seconds(30),
+  retry: {
+    maxAttempts:    3,
+    baseDelayMs:    100,
+    maxDelayMs:     C.TIME.seconds(5),
+    jitterFactor:   0.5,
+  },
+  breaker: {
+    failureThreshold: 5,
+    cooldownMs:       C.TIME.seconds(30),
+    successThreshold: 1,
+  },
+};
+
+var _err = HandlerError.factory;
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "name", "flush",
+    "maxBatch", "maxAgeMs", "maxBufferSize", "shutdownTimeoutMs",
+    "retry", "breaker",
+    "deadLetter", "onError",
+  ], "b.handlers");
+  if (typeof opts.flush !== "function") {
+    throw _err("handlers/invalid", "create requires { flush } async function");
+  }
+
+  var name              = opts.name || "anonymous";
+  var flush             = opts.flush;
+  var maxBatch          = (opts.maxBatch          != null) ? opts.maxBatch          : DEFAULTS.maxBatch;
+  var maxAgeMs          = (opts.maxAgeMs          != null) ? opts.maxAgeMs          : DEFAULTS.maxAgeMs;
+  var maxBufferSize     = (opts.maxBufferSize     != null) ? opts.maxBufferSize     : DEFAULTS.maxBufferSize;
+  var shutdownTimeoutMs = (opts.shutdownTimeoutMs != null) ? opts.shutdownTimeoutMs : DEFAULTS.shutdownTimeoutMs;
+  // Handler retry: any thrown error from operator-supplied flush() is
+  // retried until exhaustion. The default isRetryable classifier is
+  // network-shaped and would skip generic Errors; override to retry-
+  // anything since flush failures are caller-defined, not network errors.
+  var retryConfig = Object.assign(
+    { isRetryable: function () { return true; } },
+    DEFAULTS.retry,
+    opts.retry || {}
+  );
+  var breakerConfig     = Object.assign({}, DEFAULTS.breaker, opts.breaker || {});
+  var deadLetter        = (typeof opts.deadLetter === "function") ? opts.deadLetter : null;
+  var handlerLog = boot("handlers/" + name);
+  var onError           = (typeof opts.onError    === "function") ? opts.onError    : function (err) {
+    handlerLog.error(err && err.message ? err.message : String(err));
+  };
+
+  // Buffer + drain coordination.
+  var _buffer = [];
+  var _drainPromise = null;
+  var _ageTimer = null;
+  var _oldestEnqueueAt = null;
+  var _shutdown = false;
+  var _drainMutex = new safeAsync.Mutex();
+  var _breaker = new safeAsync.CircuitBreaker("handler:" + name, breakerConfig);
+
+  // Metrics.
+  var _totalEmitted = 0;
+  var _totalFlushed = 0;
+  var _totalRetried = 0;
+  var _totalDeadLettered = 0;
+  var _lastFlushDurationMs = 0;
+
+  function _scheduleAgeFlush() {
+    if (_ageTimer) return;
+    _ageTimer = setTimeout(function () {
+      _ageTimer = null;
+      drain().catch(function (e) { onError(e, []); });
+    }, maxAgeMs);
+    if (typeof _ageTimer.unref === "function") _ageTimer.unref();
+  }
+
+  function _cancelAgeFlush() {
+    if (_ageTimer) { clearTimeout(_ageTimer); _ageTimer = null; }
+  }
+
+  function _toDeadLetter(items, err) {
+    _totalDeadLettered += items.length;
+    if (deadLetter) {
+      try { deadLetter(items, err); }
+      catch (dlqErr) { onError(_err("handlers/dlq-failed",
+        "DLQ callback for handler '" + name + "' threw", dlqErr), items); }
+    } else {
+      onError(_err("handlers/dropped",
+        items.length + " item(s) dropped from handler '" + name + "' after retry exhaustion: " +
+        (err && err.message ? err.message : String(err)), err), items);
+    }
+  }
+
+  function emit(item) {
+    if (_shutdown) {
+      onError(_err("handlers/shutdown",
+        "emit on shut-down handler '" + name + "' — item dropped"), [item]);
+      _toDeadLetter([item], _err("handlers/shutdown", "handler is shutting down"));
+      return;
+    }
+    if (_buffer.length >= maxBufferSize) {
+      var dropErr = _err("handlers/buffer-full",
+        "buffer for handler '" + name + "' exceeded maxBufferSize=" +
+        maxBufferSize + " — flush is too slow / failing");
+      onError(dropErr, [item]);
+      _toDeadLetter([item], dropErr);
+      return;
+    }
+    _totalEmitted += 1;
+    _buffer.push(item);
+    if (_oldestEnqueueAt === null) _oldestEnqueueAt = Date.now();
+
+    if (_buffer.length >= maxBatch) {
+      _cancelAgeFlush();
+      drain().catch(function (e) { onError(e, []); });
+    } else {
+      _scheduleAgeFlush();
+    }
+  }
+
+  // Drain the buffer with retry + breaker + DLQ. Items emitted DURING
+  // a drain land in the buffer for the NEXT drain cycle (NOT the
+  // current call) — see the recursion-safety note in this module's
+  // header. Without this bound, a handler whose flush() emits MORE
+  // items into the same handler (cluster-mode audit: writing an
+  // audit row goes through externalDb.query, which emits a
+  // system.externaldb.query audit event back into the buffer)
+  // produces an unbounded loop where the buffer refills as fast as
+  // it drains.
+  //
+  // Implementation: snapshot _buffer.length at start; process exactly
+  // that many items (in batches of maxBatch). Items emitted during
+  // the drain accrue at the tail of _buffer and are visible to the
+  // next drain() call. Concurrent drain() calls share the in-flight
+  // Promise.
+  function drain(drainOpts) {
+    if (_drainPromise) return _drainPromise;
+    drainOpts = drainOpts || {};
+    var signal = drainOpts.signal || null;
+
+    _drainPromise = _drainMutex.runExclusive(async function () {
+      _cancelAgeFlush();
+      var remaining = _buffer.length;
+      while (remaining > 0) {
+        if (signal && signal.aborted) break;
+        var take = Math.min(maxBatch, remaining);
+        var batch = _buffer.splice(0, take);
+        remaining -= batch.length;
+        _oldestEnqueueAt = _buffer.length > 0 ? Date.now() : null;
+
+        var t0 = Date.now();
+        try {
+          await _breaker.wrap(async function () {
+            // Retry the entire batch on transient failures. Each retry
+            // re-enters the operator's flush() with the same items; the
+            // operator's flush() should be idempotent within a batch
+            // (or accept the duplicate-write trade-off).
+            //
+            // The operator flush() receives an isShutdown() probe in its
+            // second arg so it can early-exit between items if the
+            // handler was shut down mid-batch (e.g. by a test reset).
+            // Without that check, an in-flight flush keeps processing
+            // batch[i++] items even after shutdown — and audit's
+            // flush in particular writes those into whatever database
+            // is currently bound, leaking rows into the next test's db.
+            var attempts = 0;
+            await safeAsync.asyncRetry(async function () {
+              if (attempts > 0) _totalRetried += 1;
+              attempts += 1;
+              await flush(batch, { isShutdown: function () { return _shutdown; } });
+            }, retryConfig);
+          });
+          _totalFlushed += batch.length;
+        } catch (e) {
+          // Retry exhausted OR breaker open. Items go to DLQ; loop
+          // continues so other batches still attempt — unless the
+          // breaker is open, in which case the next iteration's
+          // _breaker.wrap will fail-fast immediately.
+          _toDeadLetter(batch, e);
+          if (e && e.code === "CIRCUIT_OPEN") {
+            // Stop the drain; remaining buffered items will be tried
+            // again on the next emit() / drain() call.
+            break;
+          }
+        }
+        _lastFlushDurationMs = Date.now() - t0;
+      }
+    }).then(function (v) { _drainPromise = null; return v; },
+            function (e) { _drainPromise = null; throw e; });
+    return _drainPromise;
+  }
+
+  async function shutdown(shutdownOpts) {
+    shutdownOpts = shutdownOpts || {};
+    var timeoutMs = (shutdownOpts.timeoutMs != null) ? shutdownOpts.timeoutMs : shutdownTimeoutMs;
+    _shutdown = true;
+    _cancelAgeFlush();
+    try {
+      await safeAsync.withTimeout(drain(), timeoutMs, { name: "handler:" + name + ".shutdown" });
+    } catch (e) {
+      // Timeout or breaker fail — DLQ whatever's left, then return.
+      var leftover = _buffer.splice(0);
+      if (leftover.length > 0) {
+        _toDeadLetter(leftover, e);
+      }
+    }
+  }
+
+  // Synchronous "stop and drop" — for test resets and other cases
+  // where draining buffered items would write to a stale or changing
+  // backing store. Sets the shutdown flag, cancels the age timer, and
+  // drops every buffered item to the DLQ. After this returns, no
+  // setTimeout from this handler can fire and emit() drops every
+  // future item with handlers/shutdown.
+  function shutdownSync(reason) {
+    _shutdown = true;
+    _cancelAgeFlush();
+    var dropped = _buffer.splice(0);
+    if (dropped.length > 0) {
+      _toDeadLetter(
+        dropped,
+        _err("handlers/shutdown-drop",
+          "handler '" + name + "' shut down with " + dropped.length +
+          " buffered item(s); items dropped: " + (reason || "no-drain shutdown"))
+      );
+    }
+  }
+
+  function getStats() {
+    return {
+      bufferSize:            _buffer.length,
+      totalEmitted:          _totalEmitted,
+      totalFlushed:          _totalFlushed,
+      totalRetried:          _totalRetried,
+      totalDeadLettered:     _totalDeadLettered,
+      lastFlushDurationMs:   _lastFlushDurationMs,
+      breakerState:          _breaker.getState ? _breaker.getState() : null,
+      isShutdown:            _shutdown,
+    };
+  }
+
+  function size() { return _buffer.length; }
+
+  return {
+    name:         name,
+    emit:         emit,
+    drain:        drain,
+    shutdown:     shutdown,
+    shutdownSync: shutdownSync,
+    getStats:     getStats,
+    size:         size,
+  };
+}
+
+module.exports = {
+  create: create,
+};

package/lib/vendor/blamejs/lib/honeytoken.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * @module b.honeytoken
+ * @nav    Identity
+ * @title  Honeytoken
+ *
+ * @intro
+ *   Framework-seeded canary records that trigger an audit alert on
+ *   read; integrates with sealed columns. The framework generates
+ *   decoy values (fake api-key shapes, fake admin URLs, fake DB row
+ *   references) that are NEVER handed to a real client. Their
+ *   presence in a request, log, or DB lookup means an attacker
+ *   reached something they shouldn't have. Every positive lookup
+ *   emits a `honeytoken.tripped` audit row with the observing
+ *   actor's 5 W's so a SOC operator can pivot directly to the
+ *   compromise.
+ *
+ *   Canary value shapes (`kind`):
+ *     - `"apiKey"`  — `bk_canary_<hex>` (mirrors b.apiKey shape)
+ *     - `"session"` — `bks_canary_<hex>` (mirrors b.session shape)
+ *     - `"url"`     — `/admin/canary-<hex>` (planted as a clickable link)
+ *     - `"rowId"`   — `ht_canary_<hex>` (planted as a fake foreign key)
+ *
+ *   Audit shape:
+ *     - `honeytoken.issued`  — outcome=success; metadata { id, kind }
+ *     - `honeytoken.tripped` — outcome=failure; metadata { id, kind,
+ *       metadata, observedAt, observedActor }
+ *
+ * @card
+ *   Framework-seeded canary records that trigger an audit alert on read; integrates with sealed columns.
+ */
+
+var bCrypto = require("./crypto");
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+var HoneytokenError = defineClass("HoneytokenError", { alwaysPermanent: true });
+
+var KINDS = Object.freeze({
+  apiKey:  function () { return "bk_canary_"  + bCrypto.generateToken(16); },     // allow:raw-byte-literal — 16-byte (128-bit) canary entropy
+  session: function () { return "bks_canary_" + bCrypto.generateToken(24); },     // allow:raw-byte-literal — 24-byte (192-bit) canary entropy
+  url:     function () { return "/admin/canary-" + bCrypto.generateToken(16); },  // allow:raw-byte-literal — 16-byte canary entropy
+  rowId:   function () { return "ht_canary_"  + bCrypto.generateToken(16); },     // allow:raw-byte-literal — 16-byte canary entropy
+});
+
+/**
+ * @primitive b.honeytoken.create
+ * @signature b.honeytoken.create(opts)
+ * @since     0.8.40
+ * @status    stable
+ * @compliance soc2, nis2, dora
+ * @related   b.audit, b.apiKey.create, b.session
+ *
+ * Build an in-process honeytoken registry. Returns a handle exposing
+ * `issue(spec)` to mint a canary, `lookup(value, observedActor?)` to
+ * test an incoming value (audit-emits `honeytoken.tripped` on hit),
+ * `revoke(id)` to retire a canary, and `size()` for diagnostics. The
+ * registry is per-process — operators running multiple workers wire
+ * a shared b.audit sink and reconcile alerts at the audit layer
+ * rather than sharing the registry across nodes (a canary's value
+ * is what's planted in the trap, not what's known to the framework).
+ *
+ * @opts
+ *   audit:  b.audit,   // audit sink for issued / tripped events (optional, recommended)
+ *
+ * @example
+ *   var honey = b.honeytoken.create({ audit: b.audit });
+ *
+ *   var canary = honey.issue({
+ *     kind:     "apiKey",
+ *     metadata: { plantedAt: "GET /admin/keys/list", linkedTo: "user-42" },
+ *   });
+ *   // → { id: "ht_<hex>", value: "bk_canary_<hex>" }
+ *
+ *   // Plant the canary value somewhere an attacker who's escalated
+ *   // privileges might find it (a fake row in an admin listing, a
+ *   // dummy env-var leaked into a traceback page, etc.).
+ *
+ *   // On every incoming credential, check for canary use:
+ *   if (honey.lookup(req.headers["x-api-key"], { ip: req.ip })) {
+ *     // tripped — audit already emitted; respond as if invalid.
+ *     return res.writeHead(403).end();
+ *   }
+ */
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["audit"], "honeytoken.create");
+
+  var registry = new Map();   // value → { id, kind, metadata, issuedAt }
+
+  function issue(spec) {
+    spec = spec || {};
+    validateOpts(spec, ["kind", "metadata"], "honeytoken.issue");
+    var kind = spec.kind;
+    if (typeof KINDS[kind] !== "function") {
+      throw new HoneytokenError(
+        "honeytoken/unknown-kind",
+        "honeytoken.issue: unknown kind '" + kind + "' " +
+        "(supported: " + Object.keys(KINDS).join(", ") + ")");
+    }
+    var value = KINDS[kind]();
+    var id = "ht_" + bCrypto.generateToken(8);                                    // allow:raw-byte-literal — 8-byte registry id
+    var record = Object.freeze({
+      id:        id,
+      kind:      kind,
+      metadata:  spec.metadata || null,
+      issuedAt:  Date.now(),
+    });
+    registry.set(value, record);
+    try {
+      audit().safeEmit({
+        action: "honeytoken.issued",
+        outcome: "success",
+        metadata: { id: id, kind: kind },
+      });
+    } catch (_e) { /* audit best-effort */ }
+    return { id: id, value: value };
+  }
+
+  function lookup(value, observedActor) {
+    if (typeof value !== "string" || value.length === 0) return null;
+    var record = registry.get(value);
+    if (!record) return null;
+    try {
+      audit().safeEmit({
+        action: "honeytoken.tripped",
+        outcome: "failure",
+        metadata: {
+          id:             record.id,
+          kind:           record.kind,
+          metadata:       record.metadata,
+          observedAt:     Date.now(),
+          observedActor:  observedActor || null,
+        },
+      });
+    } catch (_e) { /* audit best-effort */ }
+    return record;
+  }
+
+  function revoke(id) {
+    var found = false;
+    registry.forEach(function (record, value) {
+      if (record.id === id) {
+        registry.delete(value);
+        found = true;
+      }
+    });
+    return found;
+  }
+
+  function size() { return registry.size; }
+
+  return {
+    issue:   issue,
+    lookup:  lookup,
+    revoke:  revoke,
+    size:    size,
+  };
+}
+
+module.exports = {
+  create:           create,
+  KINDS:            Object.freeze(Object.keys(KINDS)),
+  HoneytokenError:  HoneytokenError,
+};