@swfte/nexus-sdk 0.1.0

package/src/policy/engine.cjs

@@ -0,0 +1,368 @@
+'use strict';
+/**
+ * The decision engine. A port of `nexus/policy/engine.py`'s `decide`.
+ *
+ * **Unshipped, and nothing in this SDK calls it.** `src/policy/` stays out of `files` and out of
+ * the guard allowlist; `gate()` is not yet wired into `run.action()`. The order is deliberate — the
+ * engine becomes real first, in its own right, and only then does anything become gated. A `gate()`
+ * that matches rules but cannot refuse is the same failure as the AI seam swallowing a throw.
+ *
+ * ── Failure semantics, in one paragraph, because this is the part that must be exactly right ──
+ *
+ * Policy that is **missing, unverifiable or unparseable is *no policy***: allow, and raise an
+ * integrity alert so the gap is visible rather than merely survived. Policy that is **verified but
+ * stale keeps enforcing its `enforce`-marked rules** — a cached deny never decays, or disconnecting
+ * from the control plane would be the documented bypass — while its unmarked rules degrade to
+ * advice. Evaluation is **capped by a latency budget; exceeding it allows** and records the
+ * timeout. A rule that requires a human is bounded by a mandatory per-rule timeout, and times out
+ * **to deny when the rule is enforce-marked and to allow when it is not**.
+ *
+ * **Denying because we could not reach something is never a default anywhere in this module.** The
+ * one exception is opt-in and says so in its own reason string: `failClosed` is a deployment that
+ * has asked, in so many words, for governance over availability.
+ *
+ * ── What raises ──────────────────────────────────────────────────────────────────────────────
+ *
+ * `Denied` is the single exception this SDK will ever put in a host stack trace, and the host opted
+ * into it twice: the rule carried `enforce: true` and the call site did not decline. Everything
+ * else is caught — a bug in policy evaluation degrades to allow plus an integrity alert, never to a
+ * 500 in a customer's service. `decide()` never throws at all; only `check()` and `gate()` do, and
+ * only on a real denial.
+ *
+ * ── The human-approval channel is NOT ported, and the gap is load-bearing ────────────────────
+ *
+ * Python parks the calling *thread* on `approval.request` while a human answers. Node has one event
+ * loop and cannot park it — a synchronous wait here would freeze the whole process, which is a
+ * worse outcome than any policy decision.
+ *
+ * So `require_approval` resolves immediately to the rule's own `onTimeout`, stamped
+ * `source: 'approval-unavailable'` so the record says which branch it took and why. That is the
+ * *same* value Python reaches when nobody answers in time, arrived at sooner: **deny** for an
+ * enforce-marked rule, **allow** for an advisory one. Fail-safe by construction rather than by
+ * luck. An asynchronous approval channel is a real piece of work and is named in PARITY.md rather
+ * than approximated here.
+ */
+
+const rulesMod = require('./rules.cjs');
+const envelopeMod = require('./envelope.cjs');
+
+const ALLOW = 'allow';
+const DENY = 'deny';
+
+/** Floors and ceilings that no caller and no rule may cross. */
+const MIN_DECISION_BUDGET_MS = 1.0;
+const DEFAULT_DECISION_BUDGET_MS = 25.0;
+const SOFT_STALE_S = 900;        // 15 minutes
+const HARD_STALE_S = 86400;      // 24 hours
+const EXPIRE_S = 604800;         // 7 days
+
+/** Alert kinds, spelled exactly as the Python module spells them. */
+const ALERTS = Object.freeze({
+  NO_POLICY: 'policy.no_policy',
+  DISARMED: 'policy.disarmed',
+  BUDGET_EXCEEDED: 'policy.budget_exceeded',
+  MALFORMED_RULE: 'policy.malformed_rule',
+  INTERNAL_ERROR: 'policy.internal_error',
+  STALE: 'policy.stale',
+  NO_PUBKEY: 'policy.no_pubkey',
+  BAD_SIGNATURE: 'policy.bad_signature',
+});
+
+/** The exception a real denial produces. The only one this SDK puts in a host stack trace. */
+class Denied extends Error {
+  constructor(decision) {
+    super(decision.reason || 'denied by policy');
+    this.name = 'Denied';
+    this.decision = decision;
+  }
+}
+
+function defaultSettings() {
+  return {
+    enforcementEnabled: true,
+    failClosed: false,
+    decisionBudgetMs: DEFAULT_DECISION_BUDGET_MS,
+    softStaleS: SOFT_STALE_S,
+    hardStaleS: HARD_STALE_S,
+    expireS: EXPIRE_S,
+    pubkeyHex: null,
+  };
+}
+
+/** A decision, with everything a reader needs to tell what happened and why. */
+function decision(o) {
+  return {
+    action: o.action || ALLOW,
+    /** True only when this decision actually stopped something. */
+    enforced: Boolean(o.enforced),
+    get denied() { return this.action === DENY && this.enforced; },
+    ruleId: o.ruleId || null,
+    reason: o.reason || '',
+    /** Where the verdict came from: `policy`, `no-match`, `no-policy`, `stale-advisory`,
+     *  `budget-exceeded`, `approval-unavailable`, `error`. */
+    source: o.source || 'no-policy',
+    stale: Boolean(o.stale),
+    timedOut: Boolean(o.timedOut),
+    latencyMs: o.latencyMs === undefined ? 0 : o.latencyMs,
+  };
+}
+
+const ALLOW_NO_POLICY = { action: ALLOW, source: 'no-policy' };
+
+class Engine {
+  /**
+   * @param {{onAlert?: (kind: string, message: string, extra?: object) => void,
+   *          settings?: object, now?: () => number}} [opts]
+   */
+  constructor(opts) {
+    const o = opts || {};
+    this.settings = Object.assign(defaultSettings(), o.settings || {});
+    this.onAlert = o.onAlert || null;
+    this.now = o.now || (() => Date.now());
+    this.clock = o.clock || (() => Number(process.hrtime.bigint() / 1000n) / 1000);
+    this.counters = Object.create(null);
+    this.snapshot = { present: false, ruleset: rulesMod.EMPTY, env: envelopeMod.ABSENT };
+    this._noPolicyAlerted = false;
+  }
+
+  incr(name, n) {
+    this.counters[name] = (this.counters[name] || 0) + (n === undefined ? 1 : n);
+  }
+
+  alert(kind, message, extra) {
+    this.incr('alert.' + kind);
+    if (this.onAlert) {
+      try { this.onAlert(kind, message, extra || {}); } catch (_err) { this.incr('alert_failed'); }
+    }
+  }
+
+  configure(patch) {
+    Object.assign(this.settings, patch || {});
+    return this.settings;
+  }
+
+  /**
+   * Verify and install an envelope. Returns `{ installed, problem, state, rules, quarantined }`.
+   *
+   * A failure to install is *no policy*, which allows — never a denial. A control plane that
+   * pushed a bad envelope must not take a customer's service down as the punishment.
+   */
+  install(raw, pubkeyHex) {
+    const key = pubkeyHex === undefined ? this.settings.pubkeyHex : pubkeyHex;
+    const { payload, problem } = envelopeMod.verify(raw, key);
+    if (payload === null) {
+      this.incr('install_rejected');
+      this.alert(problem === envelopeMod.NO_KEY ? ALERTS.NO_PUBKEY : ALERTS.BAD_SIGNATURE, problem);
+      // The previous snapshot is deliberately left in place. An envelope that fails to verify is
+      // not evidence that the last good one has stopped being true, and discarding it would make a
+      // malformed control-plane push a way to disarm every control at once.
+      return { installed: false, problem, state: null, rules: 0, quarantined: [] };
+    }
+
+    const ruleset = rulesMod.parse(payload.rules);
+    if (ruleset.quarantined.length) {
+      // Reported, not merely counted: a quarantined `enforce` rule is an enforcement gap, and a
+      // count alone cannot tell an operator which control is missing.
+      this.alert(ALERTS.MALFORMED_RULE,
+        ruleset.quarantined.length + ' rule(s) quarantined',
+        { quarantined: ruleset.quarantined });
+    }
+
+    const issued = envelopeMod.issuedAt(payload);
+    const state = envelopeMod.freshness(issued, this.now(),
+      this.settings.softStaleS, this.settings.hardStaleS, this.settings.expireS);
+
+    this.snapshot = {
+      present: true,
+      ruleset,
+      env: { payload, verified: true, state, problem: null, issuedAt: issued },
+    };
+    this._noPolicyAlerted = false;
+    this.incr('installed');
+    return {
+      installed: true, problem: null, state,
+      rules: ruleset.rules.length, quarantined: ruleset.quarantined,
+    };
+  }
+
+  /** Forget the installed policy. After this, every decision is `no-policy`. */
+  reset() {
+    this.snapshot = { present: false, ruleset: rulesMod.EMPTY, env: envelopeMod.ABSENT };
+    this._noPolicyAlerted = false;
+    this.counters = Object.create(null);
+  }
+
+  /**
+   * Evaluate a subject against the installed policy. **Never throws.**
+   *
+   * @param {string} kind the subject kind, e.g. `tool_action`
+   * @param {object} subject the fields rules match on
+   * @param {{enforce?: boolean, budgetMs?: number}} [opts]
+   *   `enforce: false` forces advise for this call site regardless of rule markings — the dry-run
+   *   switch. `true` or omitted defers to the rule, which is the only thing that can make a denial
+   *   real: a call site can decline to enforce, never promote.
+   */
+  decide(kind, subject, opts) {
+    const t0 = this.clock();
+    try {
+      return this._decide(kind, subject, opts || {}, t0);
+    } catch (err) {
+      // A bug in policy degrades to allow plus an alert. The alternative — a policy bug becoming a
+      // 500 in a customer's service — is the failure that gets an SDK removed rather than patched.
+      this.incr('errors');
+      this.alert(ALERTS.INTERNAL_ERROR, (err && err.name) + ': ' + (err && err.message));
+      return decision({ ...ALLOW_NO_POLICY, source: 'error', latencyMs: this.clock() - t0 });
+    }
+  }
+
+  _decide(kind, subject, opts, t0) {
+    const s = this.settings;
+    this.incr('evaluated');
+
+    const subj = Object.assign({}, subject || {});
+    if (subj.kind === undefined) subj.kind = kind;
+
+    // A caller may lower the budget for its own latency reasons — a checkout handler and a batch
+    // job do not owe each other the same patience — but not below the floor the operator's own
+    // budget is held to. Unfloored, `budgetMs: 0` expires on the first check and every deny becomes
+    // `budget-exceeded` with no rule named: not a bypass, but an erasure shaped like infrastructure.
+    const requested = opts.budgetMs === undefined ? s.decisionBudgetMs : opts.budgetMs;
+    const budgetMs = Math.max(MIN_DECISION_BUDGET_MS, requested);
+    let expired = false;
+    const pastDeadline = () => {
+      if ((this.clock() - t0) > budgetMs) { expired = true; return true; }
+      return false;
+    };
+
+    const finish = (d) => decision({ ...d, latencyMs: this.clock() - t0 });
+
+    if (!this.snapshot.present) {
+      // The fail-open half. No envelope, or one that would not verify. Alerted once per process: a
+      // fleet with no policy configured must not emit one alert per request.
+      if (!this._noPolicyAlerted) {
+        this._noPolicyAlerted = true;
+        this.alert(ALERTS.NO_POLICY, this.snapshot.env.problem || 'no policy installed');
+      }
+      this.incr('no_policy');
+      if (s.failClosed && s.enforcementEnabled && opts.enforce !== false) {
+        // The other half of that argument, and it is opt-in. The customer asked for governance over
+        // availability in so many words, and the deny says so in its reason rather than leaving
+        // them to work out why their service started refusing. This covers only "we have no
+        // policy" — not the budget overrun below, and not the error path above.
+        this.incr('denied');
+        return finish({
+          action: DENY, source: 'no-policy', enforced: true,
+          reason: 'no verified policy is installed and this deployment is configured to fail closed',
+        });
+      }
+      return finish(ALLOW_NO_POLICY);
+    }
+
+    // Re-classify freshness on every decision rather than at install: an envelope goes stale by the
+    // passage of time, not by an event, so a snapshot classified once would report `fresh` forever.
+    const state = envelopeMod.freshness(this.snapshot.env.issuedAt, this.now(),
+      s.softStaleS, s.hardStaleS, s.expireS);
+    const stale = state === envelopeMod.HARD_STALE || state === envelopeMod.EXPIRED;
+
+    const rule = rulesMod.firstMatch(this.snapshot.ruleset, subj, pastDeadline,
+      (r, err) => this.alert(ALERTS.MALFORMED_RULE, 'matcher raised for ' + r.id,
+        { error: err && err.name }));
+
+    if (expired) {
+      // Abandon and allow. Recording the timeout is what keeps this from being a silent hole: a
+      // rule set that consistently blows the budget is a control-plane bug that shows up as a
+      // counter rather than as an unexplained gap in the enforcement record.
+      this.incr('budget_exceeded');
+      this.alert(ALERTS.BUDGET_EXCEEDED, 'decision abandoned after ' + Math.round(budgetMs) + 'ms',
+        { subject_kind: String(kind) });
+      return finish({ ...ALLOW_NO_POLICY, source: 'budget-exceeded', timedOut: true });
+    }
+
+    if (rule === null) return finish({ source: 'no-match', stale });
+
+    // Both flags must agree. The rule marking is necessary; the call site can only decline.
+    const mayEnforce = rulesMod.enforcing(rule) && s.enforcementEnabled && opts.enforce !== false;
+
+    if (stale && !rulesMod.enforcing(rule)) {
+      // A verified-but-stale envelope keeps advising, but an unmarked rule stops mattering. The
+      // marked ones do not decay — that is the branch below, and its absence here is the point.
+      this.alert(ALERTS.STALE, 'policy is ' + state + '; unmarked rules are advisory');
+      return finish({
+        action: rule.action === rulesMod.ALLOW ? ALLOW : DENY,
+        ruleId: rule.id, reason: rule.reason, source: 'stale-advisory', enforced: false, stale: true,
+      });
+    }
+
+    if (rule.action === rulesMod.ALLOW) {
+      return finish({ action: ALLOW, ruleId: rule.id, reason: rule.reason, source: 'policy', stale });
+    }
+
+    if (rule.action === rulesMod.DENY) {
+      if (mayEnforce) this.incr('denied');
+      else {
+        this.incr('advised_deny');
+        if (rulesMod.enforcing(rule) && !s.enforcementEnabled) {
+          // The moment disarming actually costs something. Raised here rather than at startup,
+          // because "enforcement is off" is only a finding once a rule that would have blocked
+          // something does not.
+          this.alert(ALERTS.DISARMED,
+            'enforcement disabled: an enforce-marked deny became advice');
+        }
+      }
+      return finish({
+        action: DENY, ruleId: rule.id, reason: rule.reason || 'denied by policy',
+        source: 'policy', enforced: mayEnforce, stale,
+      });
+    }
+
+    // require_approval, with no human channel to reach. See the module header: this resolves to the
+    // rule's own `onTimeout`, which is the same value Python reaches when nobody answers — deny for
+    // an enforce-marked rule, allow for an advisory one — arrived at sooner and stamped so the
+    // record says which branch it took.
+    if (rulesMod.enforcing(rule) && !s.enforcementEnabled) {
+      this.alert(ALERTS.DISARMED, 'enforcement disabled: an enforce-marked approval gate became advice');
+    }
+    this.incr('approval_unavailable');
+    const timedOutTo = rule.onTimeout === DENY ? DENY : ALLOW;
+    if (timedOutTo === DENY && mayEnforce) this.incr('denied');
+    return finish({
+      action: timedOutTo,
+      ruleId: rule.id,
+      reason: rule.reason || 'approval required and no approver channel is configured',
+      source: 'approval-unavailable',
+      enforced: timedOutTo === DENY && mayEnforce,
+      stale,
+      timedOut: true,
+    });
+  }
+
+  /**
+   * Decide, and throw `Denied` if an enforcing rule refuses. Returns the decision otherwise.
+   *
+   * The raising counterpart to `decide`. Use it where the effect is the next statement and there is
+   * no block to wrap.
+   */
+  check(kind, subject, opts) {
+    const d = this.decide(kind, subject, opts);
+    if (d.denied) throw new Denied(d);
+    return d;
+  }
+
+  /**
+   * Guard a function. **Decides first, then calls it.**
+   *
+   * That order is the acceptance criterion for the whole subsystem: a denial raised after the write
+   * already went out is not enforcement, it is journalism. On a denial the body never executes and
+   * `Denied` propagates. On an allow the decision is passed to the body, so a caller in advise mode
+   * can see that policy *would* have refused — which is the whole value of a shadow deployment.
+   */
+  gate(kind, subject, fn, opts) {
+    const d = this.check(kind, subject, opts);
+    return fn(d);
+  }
+}
+
+module.exports = {
+  ALLOW, DENY, ALERTS, Denied, Engine, decision, defaultSettings,
+  MIN_DECISION_BUDGET_MS, DEFAULT_DECISION_BUDGET_MS, SOFT_STALE_S, HARD_STALE_S, EXPIRE_S,
+};

package/src/policy/envelope.cjs

@@ -0,0 +1,256 @@
+'use strict';
+/**
+ * Signed policy envelopes. A port of `nexus/policy/envelope.py`.
+ *
+ * A policy that anything on the machine can edit is not a control, so an envelope is Ed25519-signed
+ * by the control plane and verified here before a single rule is read. Node's `crypto` does Ed25519
+ * natively, so unlike the Python SDK — which vendors a pure-Python curve implementation to keep its
+ * core ring dependency-free — this needs nothing beyond a builtin.
+ *
+ * ── Freshness is four states, not two ────────────────────────────────────────────────────────
+ *
+ * A verified envelope that has stopped being refreshed is not the same as no envelope, and
+ * collapsing the two is how disconnecting from the control plane becomes the documented bypass.
+ * `FRESH` enforces everything; `SOFT_STALE` and `HARD_STALE` keep enforcing rules marked
+ * `enforce` while unmarked rules degrade to advice; `EXPIRED` is treated as no policy at all.
+ * **A cached deny never decays.**
+ *
+ * ── The canonical form, and the trap in porting it ───────────────────────────────────────────
+ *
+ * Both sides must agree byte-for-byte or every signature fails, so the canonicalisation is
+ * deliberately the most boring available: sorted keys, no insignificant whitespace. Python spells
+ * that `json.dumps(payload, sort_keys=True, separators=(",", ":"))`.
+ *
+ * `JSON.stringify` is **not** that function, in two ways that both matter:
+ *
+ * 1. It does not sort keys. Insertion order is whatever the parser produced.
+ * 2. Python's `json.dumps` defaults to `ensure_ascii=True`, so `é` is signed as the six bytes
+ *    `é` while `JSON.stringify` emits the two UTF-8 bytes of the character itself. Any policy
+ *    containing a non-ASCII character — a reason string in French, a repo name with an umlaut —
+ *    would verify in Python and fail here, with a "signature does not verify" that points at the
+ *    key rather than at the encoder.
+ *
+ * Both are handled below, and `scripts/policy-parity.mjs` diffs the produced bytes against Python's
+ * over a corpus including non-ASCII, nesting and key-ordering cases.
+ */
+
+const crypto = require('node:crypto');
+
+const FRESH = 'fresh';
+const SOFT_STALE = 'soft-stale';
+const HARD_STALE = 'hard-stale';
+const EXPIRED = 'expired';
+
+const NO_KEY = 'no policy public key is configured';
+const NO_ISSUED_AT = 'envelope carries no signed issued_at';
+const ROLLED_BACK = 'envelope is older than one already accepted';
+const UNCANONICALISABLE = 'envelope contains a number this SDK cannot canonicalise byte-identically';
+
+/** What an absent policy looks like. Not a null: a caller must be able to ask it questions. */
+const ABSENT = Object.freeze({
+  payload: {}, verified: false, state: EXPIRED, problem: 'absent', issuedAt: null,
+});
+
+/**
+ * Escape non-ASCII exactly as Python's `ensure_ascii=True` does, including surrogate pairs.
+ *
+ * Python emits `\uXXXX` per UTF-16 code unit — so an astral character becomes a surrogate pair of
+ * two escapes, which is what `JSON.stringify` would have produced had it escaped at all. Iterating
+ * code *units* rather than code points is therefore correct rather than sloppy.
+ */
+function escapeNonAscii(s) {
+  let out = '';
+  for (let i = 0; i < s.length; i += 1) {
+    const c = s.charCodeAt(i);
+    out += c > 0x7f ? '\\u' + c.toString(16).padStart(4, '0') : s[i];
+  }
+  return out;
+}
+
+/**
+ * Numbers Python and JavaScript are guaranteed to render identically.
+ *
+ * **This is a real limit, and it is enforced rather than hoped for.** Python's float repr and
+ * `JSON.stringify` disagree in several ranges at once, measured rather than assumed:
+ *
+ *     value    Python      JavaScript
+ *     30.0     30.0        30            (Python keeps a float's decimal point)
+ *     1e-7     1e-07       1e-7          (exponent padding)
+ *     1e-6     1e-06       0.000001      (different threshold for exponential form)
+ *     1e16     1e+16       10000000000000000
+ *     -0.0     -0.0        0
+ *
+ * Worse, the first row is not fixable from this side: after `JSON.parse`, JavaScript has lost
+ * whether the signed text said `30` or `30.0`, and Python renders those differently. So a
+ * general-purpose emulator cannot be written here even in principle — it would need bytes that no
+ * longer exist by the time `verify` is called.
+ *
+ * Since this is the byte-for-byte input to a signature check, guessing is the one thing that must
+ * not happen: an encoder that is subtly wrong turns valid policies into "signature does not verify",
+ * which reads as a key-distribution problem and gets diagnosed as one for a long time.
+ *
+ * So a payload containing a number outside the safe-integer range — or any non-integer — is
+ * **refused with a specific problem string**, which the engine treats as *no policy*: allow, plus an
+ * integrity alert. Loud and diagnosable, rather than a mysterious signature failure. Integers are
+ * the realistic case for a policy payload anyway (`version`, `issued_at`, `approval_timeout_s`), and
+ * a control plane needing fractional seconds should sign milliseconds.
+ */
+function uncanonicalisableNumber(v) {
+  // Returns `{ value }` or `null`, never the bare number. An earlier draft returned the value and
+  // the recursion tested it for truthiness — which meant `-0`, the one number whose rendering
+  // differs between the two languages *and* is falsy, walked straight through the check written to
+  // catch it. Caught by the parity script asserting the refusal rather than by reading the code.
+  if (Array.isArray(v)) {
+    for (const i of v) { const bad = uncanonicalisableNumber(i); if (bad !== null) return bad; }
+    return null;
+  }
+  if (v && typeof v === 'object') {
+    for (const k of Object.keys(v)) {
+      const bad = uncanonicalisableNumber(v[k]);
+      if (bad !== null) return bad;
+    }
+    return null;
+  }
+  if (typeof v === 'number') {
+    if (!Number.isInteger(v) || !Number.isSafeInteger(v) || Object.is(v, -0)) return { value: v };
+  }
+  return null;
+}
+
+/** Recursively order object keys by code point, as Python's `sort_keys=True` does. */
+function sortKeys(v) {
+  if (Array.isArray(v)) return v.map(sortKeys);
+  if (v && typeof v === 'object') {
+    const out = {};
+    for (const k of Object.keys(v).sort()) out[k] = sortKeys(v[k]);
+    return out;
+  }
+  return v;
+}
+
+/**
+ * The exact bytes the control plane signed.
+ *
+ * Anything clever here is a future interoperability bug with a cryptographic failure mode, so this
+ * is as dull as it can be made.
+ */
+function canonical(payload) {
+  return Buffer.from(escapeNonAscii(JSON.stringify(sortKeys(payload))), 'latin1');
+}
+
+/**
+ * True iff `keyHex` is a key at all.
+ *
+ * Absent, blank, wrong length, not hex, or all-zero are all *no key*. The all-zero case is the one
+ * that mattered upstream: it was once a shipped default on the theory that a nonsense key verifies
+ * nothing, and it verified 23.5% of forgeries because 32 zero bytes decompress to an order-4 point.
+ * This is also the *honest* check — a deployment that set a policy file and forgot the key should
+ * be told it has no key rather than be told its control plane's signature is bad.
+ */
+function keyIsConfigured(keyHex) {
+  const k = String(keyHex || '').trim();
+  if (!k || !/^[0-9a-fA-F]+$/.test(k)) return false;
+  const raw = Buffer.from(k, 'hex');
+  return raw.length === 32 && raw.some((b) => b !== 0);
+}
+
+/**
+ * The 12-byte SPKI prefix for an Ed25519 public key.
+ *
+ * Node's `crypto.createPublicKey` takes DER, not a raw 32-byte curve point, so a raw key has to be
+ * wrapped. The header is a constant: SEQUENCE, SEQUENCE, OID 1.3.101.112 (Ed25519), BIT STRING.
+ * Written as a literal rather than assembled, because a DER encoder for one fixed structure is more
+ * code and more risk than the twelve bytes it would produce.
+ */
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+
+function publicKeyFromHex(keyHex) {
+  return crypto.createPublicKey({
+    key: Buffer.concat([ED25519_SPKI_PREFIX, Buffer.from(keyHex, 'hex')]),
+    format: 'der',
+    type: 'spki',
+  });
+}
+
+/**
+ * Return `{ payload, problem }`. `payload` is non-null only for a valid signature.
+ *
+ * Every malformed input resolves to a problem string rather than an exception. Callers are all
+ * going to treat an exception as "do not trust this policy" anyway, and a verifier that can throw
+ * invites exactly one bare catch too many.
+ */
+function verify(raw, pubkeyHex) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { payload: null, problem: 'envelope is not an object' };
+  }
+  const payload = raw.policy;
+  const sigHex = raw.signature;
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return { payload: null, problem: 'envelope has no policy object' };
+  }
+  if (typeof sigHex !== 'string' || !sigHex) {
+    return { payload: null, problem: 'envelope is unsigned' };
+  }
+  if (!keyIsConfigured(pubkeyHex)) return { payload: null, problem: NO_KEY };
+  // Before any curve arithmetic: if the payload cannot be canonicalised byte-identically with the
+  // signer, no verdict from this function would mean anything. Refusing here produces a specific,
+  // diagnosable problem instead of a 'signature does not verify' that points at the key.
+  const badNumber = uncanonicalisableNumber(payload);
+  if (badNumber !== null) {
+    return { payload: null, problem: UNCANONICALISABLE + ': ' + String(badNumber.value) };
+  }
+  if (!/^[0-9a-fA-F]+$/.test(sigHex)) {
+    return { payload: null, problem: 'signature or public key is not hex' };
+  }
+  try {
+    const ok = crypto.verify(null, canonical(payload),
+      publicKeyFromHex(String(pubkeyHex).trim()), Buffer.from(sigHex, 'hex'));
+    if (!ok) return { payload: null, problem: 'signature does not verify' };
+  } catch (_err) {
+    // A verifier that throws must still mean "do not trust".
+    return { payload: null, problem: 'verification raised' };
+  }
+  return { payload, problem: null };
+}
+
+/**
+ * The signed issue time, or `null` if the envelope does not state one.
+ *
+ * `issued_at` is the name; `iat` is accepted because JWT-shaped tooling spells it that way and one
+ * signer serves both attach points. Booleans are excluded explicitly — `issued_at: true` becoming
+ * `1` would be a 1970 timestamp that reads as maximally stale rather than as the malformed envelope
+ * it is. NaN, infinities and non-positive values are refused for the same reason: a freshness input
+ * we cannot compare is not a freshness input.
+ */
+function issuedAt(payload) {
+  for (const name of ['issued_at', 'iat']) {
+    const v = payload[name];
+    if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0) continue;
+    return v;
+  }
+  return null;
+}
+
+/**
+ * Classify freshness against the configured windows.
+ *
+ * The gap between soft and hard is not decoration. A soft-stale envelope is one the control plane
+ * has merely not refreshed recently; a hard-stale one has been out of contact long enough that an
+ * operator should be told. Neither stops an `enforce` rule working, because a cached deny that
+ * decayed would make disconnecting the bypass.
+ */
+function freshness(issued, now, softStaleS, hardStaleS, expireS) {
+  if (issued === null) return HARD_STALE;   // signed but undated: trusted, never called fresh
+  const ageS = (now - issued * 1000) / 1000;
+  if (ageS <= softStaleS) return FRESH;
+  if (ageS <= hardStaleS) return SOFT_STALE;
+  if (expireS && ageS > expireS) return EXPIRED;
+  return HARD_STALE;
+}
+
+module.exports = {
+  FRESH, SOFT_STALE, HARD_STALE, EXPIRED, ABSENT,
+  NO_KEY, NO_ISSUED_AT, ROLLED_BACK, UNCANONICALISABLE,
+  canonical, keyIsConfigured, verify, issuedAt, freshness, uncanonicalisableNumber,
+  escapeNonAscii, sortKeys, publicKeyFromHex,
+};