@swfte/nexus-sdk 0.1.0

package/src/policy/index.cjs

@@ -0,0 +1,224 @@
+'use strict';
+/**
+ * The enforcement seam — the one thing in this product that can say *no*.
+ *
+ * Capture of coding agents is now free: OpenLIT is Apache-2.0, `opentelemetry-hooks` is MIT, and
+ * ddtrace, OpenLLMetry and OpenInference all read the same provider call sites we do. **None of
+ * them can stop a call.** Every agent-observability vendor observes; the differentiator is not what
+ * we see, it is that we can refuse. That is what is implemented here.
+ *
+ *     import * as nexus from '@swfte/nexus-sdk';
+ *     import * as policy from '@swfte/nexus-sdk/policy';
+ *
+ *     policy.install(signedEnvelope);          // verified before a single rule is read
+ *
+ *     const d = policy.decide('tool_action', { tool: 'db.write', target: 'prod-orders' });
+ *     if (d.denied) { … }
+ *
+ *     policy.gate('tool_action', { tool: 'db.write', target: 'prod-orders' }, () => {
+ *       writeTheRows();                        // never runs if an enforcing rule denies
+ *     });
+ *
+ * ── Where enforcement actually happens, and where it cannot ──────────────────────────────────
+ *
+ * **`run.action(...)` is gated.** It is the only call site in this SDK that is, and that is not an
+ * oversight — it is the only one where the customer owns the call site and a decision can be taken
+ * before the effect.
+ *
+ * **An application on the Vercel AI SDK seam cannot be gated in-process, now or later.** That
+ * seam's callbacks return `void`: there is no channel to refuse on, and a throw from
+ * `onToolExecutionStart` neither stops the tool nor reaches the application — measured, repeatedly.
+ * There is deliberately no policy hook on `telemetry()` and there will not be one, because a hook
+ * there would be a capability that appears to work and silently does not. Enforcement in Node means
+ * the explicit API, a gateway in front of the provider, or nothing.
+ *
+ * ── 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. With no policy
+ * installed — the default — nothing here can throw, so adding this import changes no behaviour
+ * until a signed envelope arrives.
+ */
+
+const core = require('../core.cjs');
+const { Engine, Denied, ALERTS, ALLOW, DENY } = require('./engine.cjs');
+const rules = require('./rules.cjs');
+const envelope = require('./envelope.cjs');
+
+let _engine = null;
+
+/**
+ * The process-wide engine.
+ *
+ * Alerts are routed into the ledger as `policy_alert` events, which is the point of having them:
+ * an integrity failure that only exists as a counter is a failure nobody is looking at. The alert
+ * path is guarded and never re-enters the engine, because an alert raised while deciding must not
+ * be able to make deciding fail.
+ */
+function engine() {
+  if (_engine === null) {
+    _engine = new Engine({
+      settings: settingsFromEnv(),
+      onAlert: (kind, message, extra) => emitAlert(kind, message, extra),
+    });
+  }
+  return _engine;
+}
+
+function settingsFromEnv() {
+  const flag = (name, dflt) => {
+    const v = process.env[name];
+    if (v === undefined || String(v).trim() === '') return dflt;
+    return !['0', 'false', 'no', 'off'].includes(String(v).trim().toLowerCase());
+  };
+  const num = (name, dflt) => {
+    const v = parseFloat(process.env[name]);
+    return Number.isFinite(v) && v > 0 ? v : dflt;
+  };
+  return {
+    enforcementEnabled: flag('NEXUS_POLICY_ENABLED', true),
+    failClosed: flag('NEXUS_POLICY_FAIL_CLOSED', false),
+    decisionBudgetMs: num('NEXUS_POLICY_BUDGET_MS', undefined),
+    pubkeyHex: (process.env.NEXUS_POLICY_PUBKEY || '').trim() || null,
+  };
+}
+
+/**
+ * In-process alert state, deduplicated by kind.
+ *
+ * A ring rather than a stream, because the alerts that matter are the ones that keep happening: a
+ * fleet whose policy will not verify raises `bad_signature` on every install attempt, and a
+ * thousand identical events answer no question a `count` does not answer better. Bounded, because
+ * the kinds are a closed set but a bug that invented one must not become unbounded memory.
+ */
+const _alerts = new Map();
+const MAX_ALERTS = 64;
+
+/**
+ * Emit one `policy_alert`, deduplicated.
+ *
+ * **Only the fields `contract/events.v1.json` declares for this type**: `kind`, `detail`, `count`,
+ * `first_seen`, `last_seen`. An earlier draft of this function invented `alert`, `reason`,
+ * `rule_id`, `subject_kind` and `detected_by` — all of which the schema would have accepted, since
+ * `additionalProperties` is true, and none of which any reader could validate. That is the same
+ * drift as `data_expectation`, one level down: a producer writing fields the ledger has no model
+ * for. The rule-level detail rides inside `detail`, where a human can read it, rather than in
+ * invented columns nothing will ever query.
+ *
+ * `behavior_trace`, matching Python: the class answers *how we know this record exists*, and the
+ * alert being raised is something this process observed itself doing.
+ *
+ * The event pipeline is the **least** important destination for an alert. If reporting a broken
+ * policy required a working collector, the case where both are broken — the case that matters —
+ * would be the silent one. So this is best-effort and wrapped whole; the counters are the
+ * destination that cannot fail.
+ */
+function emitAlert(kind, message, extra) {
+  core.guard('policy.alert', () => {
+    const nowS = Date.now() / 1000;
+    let entry = _alerts.get(kind);
+    if (entry === undefined) {
+      if (_alerts.size >= MAX_ALERTS) {
+        // A full ring means something is very wrong; drop the oldest by first_seen so the newest
+        // signal is the one that survives.
+        let oldestKey = null;
+        let oldest = Infinity;
+        for (const [k, v] of _alerts) if (v.firstSeen < oldest) { oldest = v.firstSeen; oldestKey = k; }
+        if (oldestKey !== null) _alerts.delete(oldestKey);
+      }
+      entry = { count: 0, firstSeen: nowS, lastSeen: nowS };
+      _alerts.set(kind, entry);
+    }
+    entry.count += 1;
+    entry.lastSeen = nowS;
+
+    const client = core.ensureClient();
+    if (!client) return;
+
+    // The detail is authored by this SDK, never by a customer or a model, so it is a label rather
+    // than content and does not go through the tier ladder. Bounded all the same.
+    let detail = String(message || '');
+    if (extra && extra.rule_id) detail += ' [rule ' + String(extra.rule_id) + ']';
+    if (extra && extra.subject_kind) detail += ' [kind ' + String(extra.subject_kind) + ']';
+
+    client.emit(core.base('policy_alert', client.sessionId, client.cfg, 'behavior_trace', {
+      kind: String(kind).slice(0, 64),
+      detail: detail.slice(0, 256),
+      count: entry.count,
+      first_seen: new Date(entry.firstSeen * 1000).toISOString().replace(/\.\d{3}Z$/, 'Z'),
+      last_seen: new Date(entry.lastSeen * 1000).toISOString().replace(/\.\d{3}Z$/, 'Z'),
+    }));
+  });
+}
+
+/** Every alert this process has raised, with its count and window. */
+function alerts() {
+  return core.guard('policy.alerts', () => Array.from(_alerts.entries())
+    .map(([kind, a]) => ({ kind, count: a.count, firstSeen: a.firstSeen, lastSeen: a.lastSeen })), []);
+}
+
+/**
+ * Verify and install a signed policy envelope.
+ *
+ * Failure 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.
+ */
+function install(raw, pubkeyHex) {
+  return core.guard('policy.install', () => engine().install(raw, pubkeyHex),
+    { installed: false, problem: 'install raised', state: null, rules: 0, quarantined: [] });
+}
+
+/** Adjust settings at runtime. Returns the effective settings. */
+function configure(patch) {
+  return core.guard('policy.configure', () => engine().configure(patch), null);
+}
+
+/** Evaluate a subject. **Never throws.** */
+function decide(kind, subject, opts) {
+  // The fallback is a real allow-shaped decision, not null: every caller reads `.denied`, and a
+  // null here would turn a contained guard failure into a TypeError one frame later — which is the
+  // exact shape `guard` exists to prevent.
+  return core.guard('policy.decide', () => engine().decide(kind, subject, opts),
+    { action: ALLOW, enforced: false, denied: false, ruleId: null, reason: '',
+      source: 'error', stale: false, timedOut: false, latencyMs: 0 });
+}
+
+/** Decide, and throw `Denied` if an enforcing rule refuses. */
+function check(kind, subject, opts) {
+  const d = decide(kind, subject, opts);
+  if (d && d.denied) throw new Denied(d);
+  return d;
+}
+
+/** Guard a function: decides **first**, then calls it. Throws `Denied` instead of running it. */
+function gate(kind, subject, fn, opts) {
+  const d = check(kind, subject, opts);
+  return fn(d);
+}
+
+/** What the engine has done: evaluations, denials, budget overruns, alerts by kind. */
+function counters() {
+  return core.guard('policy.counters', () => Object.assign({}, engine().counters), {});
+}
+
+/** Forget the installed policy and every counter. Chiefly for tests. */
+function reset() {
+  if (_engine !== null) _engine.reset();
+  _engine = null;
+  _alerts.clear();
+}
+
+// ── Arm the one gated call site ──────────────────────────────────────────────────────────────
+//
+// Importing this module is what gates `run.action()`. That is deliberate and it is the whole
+// opt-in: a customer who never imports `@swfte/nexus-sdk/policy` has no policy code on their
+// request path at all, and one who does has said, in an import, that they want their actions
+// subject to a signed policy.
+//
+// `check` rather than `decide`: the gate has to be able to throw, or it is not a gate.
+core.setGateHook((subject) => check(subject.kind, subject));
+
+module.exports = {
+  install, configure, decide, check, gate, counters, alerts, reset, engine,
+  Denied, ALERTS, ALLOW, DENY, rules, envelope,
+};

package/src/policy/rules.cjs

@@ -0,0 +1,442 @@
+'use strict';
+/**
+ * Rules: the shape, the matcher, and the three asymmetries that make the matcher safe.
+ *
+ * A port of `nexus/policy/rules.py`. **Unshipped** — see `test/policy-envelope.test.mjs` and
+ * PARITY.md §6. Nothing in this SDK is gated by these rules yet; they exist so the engine can be
+ * built on top of a matcher that is already correct.
+ *
+ * ── Asymmetry one: `enforce` is a property of the rule, not of the caller ────────────────────
+ *
+ * A rule denies for real only if it carries `"enforce": true`. Everything else evaluates, records,
+ * and lets the call through. One flag rather than two, because a mode that could be inferred from
+ * context is a mode somebody will infer wrongly at 3am. A call site cannot promote an unmarked rule
+ * to enforcing; it can only decline to enforce a marked one.
+ *
+ * ── Asymmetry two: unknown fields ────────────────────────────────────────────────────────────
+ *
+ * **An unknown field never satisfies an `allow` clause, but does not save a subject from a `deny`
+ * clause.** `branch_not: ["main"]` against a subject with no branch must not read as *"well, it
+ * isn't main"*. That step, from "I don't know" to "allow", is the one this package exists to
+ * refuse. The mirror holds too: refusing under uncertainty is never the unsafe direction, so a
+ * `deny` rule whose clause references a missing field still denies. One predicate, two polarities,
+ * decided by the rule's own action.
+ *
+ * ── Asymmetry three: normalisation and glob strictness follow the same polarity ──────────────
+ *
+ * An exactly case-sensitive `fnmatch` matcher gives an attacker two free evasions:
+ * `target_contains: ["prod"]` misses `PROD`, and because `*` crosses every character including
+ * `/` and `?`, the *allow* rule `target_glob: "https://*.safe.com/*"` matches
+ * `https://evil.com/a?z=.safe.com/b`. Both are fixed, and each fix moves only in the direction
+ * that is safe for its rule's own polarity:
+ *
+ * - For `deny` / `require_approval`, both sides are NFKC-normalised and case-folded. That can only
+ *   make a refusing rule match *more*.
+ * - For `allow`, both sides stay case-sensitive *and* `*`/`?` stop crossing the structural
+ *   delimiters `/ ? # @`. Both changes can only make a permitting rule match *less*.
+ *
+ * They are opposite rather than uniform because "casefold everything" would widen allow rules, and
+ * a widened allow is an authorisation bug. `branch_not` inverts again, because it is a negative
+ * clause, and it is handled where it lives.
+ *
+ * ── Quarantine ──────────────────────────────────────────────────────────────────────────────
+ *
+ * Malformed rules are quarantined **individually**, never fatal to the envelope. Rejecting a whole
+ * rule set over one typo means a single bad character in a control-plane deploy disarms every
+ * control at once — or, if we failed closed on it, denies everything at once. The cost is honest
+ * and worth naming: a malformed `enforce` rule is an enforcement gap, so `quarantined` is
+ * *reported* rather than merely counted.
+ *
+ * Glob clauses are `fnmatch`, never regex. There is no alternation: `"git (status|diff)*"` matches
+ * that literal text and nothing else. The list form is how you spell alternation, which is why the
+ * matcher needs no pattern language of its own.
+ */
+
+const ALLOW = 'allow';
+const DENY = 'deny';
+const REQUIRE_APPROVAL = 'require_approval';
+const ACTIONS = [ALLOW, DENY, REQUIRE_APPROVAL];
+
+const RISK = { low: 0, medium: 1, high: 2 };
+
+const CLAUSES = new Set(['kind', 'tool', 'tool_glob', 'target', 'target_glob', 'target_contains',
+  'command_glob', 'repos', 'branch_not', 'max_risk', 'field_equals']);
+
+/** Distinct from `undefined`, because a subject may legitimately carry `undefined`. */
+const MISSING = Symbol('missing');
+const UNCACHED = Symbol('uncached');
+
+/**
+ * Structural delimiters an `allow` rule's `*` may not cross. Chosen as the characters that change
+ * what a URL or path *means*: authority (`@`), path (`/`), query (`?`) and fragment (`#`).
+ *
+ * Space is deliberately not one — `command_glob: "git status*"` must keep matching
+ * `git status -s`, and a space does not reinterpret the rest of the string.
+ */
+const SEPARATORS = '/?#@';
+const SEP_SPLIT = /([/?#@])/;
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// glob
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * `fnmatch.fnmatchcase`, which JavaScript has no equivalent of.
+ *
+ * Translated to a regular expression rather than hand-matched, because the translation is small and
+ * total: `*` is any run, `?` is one character, `[...]` is a class (with `!` as its negation, which
+ * is fnmatch's spelling of `^`), and every other character is a literal. Written out because
+ * reaching for a glob library here would put a third-party pattern engine inside a security
+ * control — the one place a transitive dependency is least welcome.
+ */
+function globToRegExp(pattern) {
+  let out = '';
+  let i = 0;
+  while (i < pattern.length) {
+    const c = pattern[i];
+    if (c === '*') { out += '[\\s\\S]*'; i += 1; continue; }
+    if (c === '?') { out += '[\\s\\S]'; i += 1; continue; }
+    if (c === '[') {
+      const close = pattern.indexOf(']', i + (pattern[i + 1] === '!' || pattern[i + 1] === ']' ? 2 : 1));
+      if (close === -1) { out += '\\['; i += 1; continue; }   // unterminated class is a literal
+      let body = pattern.slice(i + 1, close);
+      if (body[0] === '!') body = '^' + body.slice(1);
+      // Escape a backslash inside the class so it cannot introduce an escape of its own.
+      out += '[' + body.replace(/\\/g, '\\\\') + ']';
+      i = close + 1;
+      continue;
+    }
+    out += c.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    i += 1;
+  }
+  return new RegExp('^' + out + '$', 's');
+}
+
+const globCache = new Map();
+function fnmatchcase(text, pattern) {
+  let re = globCache.get(pattern);
+  if (re === undefined) {
+    re = globToRegExp(pattern);
+    // Bounded, because patterns come from a signed envelope but the cache still must not grow
+    // without limit across many installs in one process.
+    if (globCache.size > 4096) globCache.clear();
+    globCache.set(pattern, re);
+  }
+  return re.test(text);
+}
+
+/**
+ * `fnmatch`, except `*` and `?` do not cross `/`, `?`, `#` or `@`.
+ *
+ * Implemented by splitting both sides on the delimiters and matching pairwise — the same thing as
+ * compiling a stricter wildcard, without hand-writing a glob-to-regex translator with different
+ * semantics inside a security control. A differing number of pieces is an immediate no, which is
+ * what stops `https://*.safe.com/*` matching `https://evil.com/a?z=.safe.com/b`: eleven pieces
+ * against seven.
+ *
+ * `**` anywhere in the pattern opts back into plain `fnmatch`. An author who wants a wildcard that
+ * crosses delimiters writes it in two characters and has said so on purpose, which is a different
+ * thing from getting one by accident.
+ */
+function globStrict(text, pattern) {
+  if (pattern.includes('**')) return fnmatchcase(text, pattern);
+  const pat = pattern.split(SEP_SPLIT);
+  const txt = String(text).split(SEP_SPLIT);
+  if (txt.length !== pat.length) return false;
+  for (let i = 0; i < txt.length; i += 1) {
+    // `split` with a capturing group alternates piece, delimiter, piece, … so odd indices are
+    // delimiters and must be identical rather than matched.
+    if (i % 2 === 1) { if (txt[i] !== pat[i]) return false; } else if (!fnmatchcase(txt[i], pat[i])) return false;
+  }
+  return true;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// normalisation
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * NFKC-normalise and case-fold. Applied only where matching *more* is the safe direction.
+ *
+ * `toLowerCase()` rather than a true Unicode case-fold, which JavaScript does not expose. The
+ * difference is confined to a handful of characters (fi, ß, ς) and lands on the permissive side of
+ * a *refusing* rule — the same direction the whole asymmetry moves in — so it is a narrower
+ * approximation than it looks. Named rather than left as an implicit "close enough".
+ */
+function fold(s) {
+  return String(s).normalize('NFKC').toLowerCase();
+}
+
+const foldCache = new Map();
+function foldPattern(p) {
+  const key = String(p);
+  let hit = foldCache.get(key);
+  if (hit === undefined) {
+    hit = fold(key);
+    if (foldCache.size > 4096) foldCache.clear();
+    foldCache.set(key, hit);
+  }
+  return hit;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// parsing
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+
+const EMPTY = Object.freeze({ rules: [], quarantined: [] });
+
+/** True when this rule can actually stop something. */
+function enforcing(rule) {
+  return Boolean(rule.enforce) && (rule.action === DENY || rule.action === REQUIRE_APPROVAL);
+}
+
+function hasEnforcing(ruleset) {
+  return ruleset.rules.some(enforcing);
+}
+
+function parseOne(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return [null, 'rule is not an object'];
+
+  const id = raw.id;
+  if (typeof id !== 'string' || !id.trim()) return [null, 'rule has no id'];
+
+  const action = raw.action;
+  if (!ACTIONS.includes(action)) {
+    return [null, 'rule ' + JSON.stringify(id) + ' unknown action ' + JSON.stringify(action)];
+  }
+
+  const match = raw.match === undefined ? {} : raw.match;
+  if (!match || typeof match !== 'object' || Array.isArray(match)) {
+    return [null, 'rule ' + JSON.stringify(id) + ' non-object match'];
+  }
+  const unknown = Object.keys(match).filter((k) => !CLAUSES.has(k)).sort();
+  if (unknown.length) {
+    return [null, 'rule ' + JSON.stringify(id) + ' unknown clauses ' + JSON.stringify(unknown)];
+  }
+
+  const mr = match.max_risk;
+  if (mr !== undefined && mr !== null && !(mr in RISK)) {
+    return [null, 'rule ' + JSON.stringify(id) + ' unknown max_risk ' + JSON.stringify(mr)];
+  }
+  const fe = match.field_equals;
+  if (fe !== undefined && fe !== null && (typeof fe !== 'object' || Array.isArray(fe))) {
+    return [null, 'rule ' + JSON.stringify(id) + ' non-object field_equals'];
+  }
+
+  // `=== true` rather than truthy: `"enforce": "no"` is a string, and a string is truthy. An
+  // envelope that meant to disarm a rule and spelled it wrongly must not arm it instead.
+  const enforce = raw.enforce === true;
+
+  const approval = raw.approval === undefined || raw.approval === null ? {} : raw.approval;
+  if (typeof approval !== 'object' || Array.isArray(approval)) {
+    return [null, 'rule ' + JSON.stringify(id) + ' non-object approval block'];
+  }
+  const timeout = approval.timeout_s;
+  if (timeout !== undefined && timeout !== null
+      && (typeof timeout !== 'number' || !Number.isFinite(timeout) || timeout <= 0)) {
+    return [null, 'rule ' + JSON.stringify(id) + ' non-positive approval timeout'];
+  }
+  let onTimeout = approval.on_timeout;
+  if (onTimeout === undefined || onTimeout === null) {
+    // An approval gate that allows when nobody answers is not a gate; an *advisory* one that
+    // denied when nobody answered blocks calls the customer never asked us to block. So the
+    // default follows the marking rather than being a constant.
+    onTimeout = enforce ? DENY : ALLOW;
+  }
+  if (onTimeout !== ALLOW && onTimeout !== DENY) {
+    return [null, 'rule ' + JSON.stringify(id) + ' unknown on_timeout ' + JSON.stringify(onTimeout)];
+  }
+
+  return [Object.freeze({
+    id,
+    action,
+    enforce,
+    reason: typeof raw.reason === 'string' ? raw.reason : '',
+    match,
+    approvalTimeoutS: typeof timeout === 'number' ? timeout : null,
+    onTimeout,
+  }), null];
+}
+
+/** Build a rule set. Never throws; anything unusable becomes a quarantine entry. */
+function parse(rawRules, maxRules) {
+  const cap = maxRules === undefined ? 1000 : maxRules;
+  if (!Array.isArray(rawRules)) return EMPTY;
+  const good = [];
+  const bad = [];
+  const slice = rawRules.slice(0, cap);
+  for (let i = 0; i < slice.length; i += 1) {
+    let rule = null;
+    let why = null;
+    try {
+      [rule, why] = parseOne(slice[i]);
+    } catch (err) {
+      rule = null;
+      why = (err && err.name ? err.name : 'Error') + ': ' + (err && err.message);
+    }
+    if (rule === null) bad.push([i, why || 'unusable']);
+    else good.push(rule);
+  }
+  return Object.freeze({ rules: good, quarantined: bad });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// matching
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+
+function get(subject, name) {
+  const v = subject === null || subject === undefined ? undefined : subject[name];
+  if (v === undefined || v === null || v === '') return MISSING;
+  return v;
+}
+
+function asList(v) {
+  return Array.isArray(v) ? v : [v];
+}
+
+/**
+ * A subject field as a comparison string, normalised unless the rule is an `allow`.
+ *
+ * The cache is keyed by field name and lives for one decision, so a 50-rule set that reads `target`
+ * in every rule normalises it once rather than fifty times. This is on the request path under a
+ * latency budget, so that matters.
+ */
+function field(subject, name, allowing, folded) {
+  if (allowing) {
+    const v = get(subject, name);
+    return v === MISSING ? MISSING : String(v);
+  }
+  let hit = folded[name];
+  if (hit === undefined) hit = UNCACHED;
+  if (hit === UNCACHED) {
+    const v = get(subject, name);
+    hit = v === MISSING ? MISSING : fold(String(v));
+    folded[name] = hit;
+  }
+  return hit;
+}
+
+const pat = (x, allowing) => (allowing ? String(x) : foldPattern(String(x)));
+
+function exact(got, want, allowing) {
+  if (got === MISSING) return !allowing;
+  return asList(want).some((x) => pat(x, allowing) === got);
+}
+
+function glob(got, want, allowing) {
+  if (got === MISSING) return !allowing;
+  if (allowing) return asList(want).some((p) => globStrict(got, String(p)));
+  return asList(want).some((p) => fnmatchcase(got, pat(p, false)));
+}
+
+function contains(got, want, allowing) {
+  if (got === MISSING) return !allowing;
+  return asList(want).some((p) => got.includes(pat(p, allowing)));
+}
+
+function clauseOk(clause, want, subject, allowing, folded) {
+  switch (clause) {
+    case 'kind': return exact(field(subject, 'kind', allowing, folded), want, allowing);
+    case 'tool': return exact(field(subject, 'tool', allowing, folded), want, allowing);
+    case 'target': return exact(field(subject, 'target', allowing, folded), want, allowing);
+    case 'tool_glob': return glob(field(subject, 'tool', allowing, folded), want, allowing);
+    case 'target_glob': return glob(field(subject, 'target', allowing, folded), want, allowing);
+    case 'command_glob': return glob(field(subject, 'command', allowing, folded), want, allowing);
+    case 'repos': return glob(field(subject, 'repo', allowing, folded), want, allowing);
+    case 'target_contains':
+      return contains(field(subject, 'target', allowing, folded), want, allowing);
+
+    case 'branch_not': {
+      // The polarity inverts here, because the clause is negative. `branch_not: ["main"]` in a
+      // *deny* rule exempts main, so folding would *widen the exemption* and weaken the deny; in an
+      // *allow* rule it restricts the allow, so folding narrows it. The safe direction is therefore
+      // the opposite of everywhere else: normalise for `allow`, not for `deny`.
+      const branch = field(subject, 'branch', !allowing, folded);
+      // A subject with no branch does not satisfy `branch_not`. "It isn't main because I couldn't
+      // tell" is the smuggling route.
+      if (branch === MISSING) return !allowing;
+      return !asList(want).some((x) => pat(x, !allowing) === branch);
+    }
+
+    case 'max_risk': {
+      const risk = field(subject, 'risk', allowing, folded);
+      if (risk === MISSING) return !allowing;          // no risk stated == worst case
+      // An unknown risk is 99, i.e. worse than anything named. Folding only means `"HIGH"` is
+      // recognised as high, which makes a `deny` with `max_risk: "high"` fire where it previously
+      // fell through, and leaves an `allow` case-sensitive as above.
+      const got = RISK[risk] === undefined ? 99 : RISK[risk];
+      const limit = RISK[String(want)] === undefined ? -1 : RISK[String(want)];
+      return got <= limit;
+    }
+
+    case 'field_equals': {
+      for (const [name, expected] of Object.entries(want || {})) {
+        const got = field(subject, name, allowing, folded);
+        if (got === MISSING) {
+          if (allowing) return false;
+          continue;
+        }
+        if (!asList(expected).some((x) => pat(x, allowing) === got)) return false;
+      }
+      return true;
+    }
+
+    default: return false;                              // unreachable: parse rejects unknown clauses
+  }
+}
+
+/**
+ * True iff `rule` covers `subject`. Clauses are ANDed; a list matches if any entry does.
+ *
+ * `folded` is a per-decision scratch object so a subject value is NFKC-normalised once rather than
+ * once per rule. Passing nothing is correct and simply means no sharing.
+ */
+function matches(rule, subject, folded) {
+  const allowing = rule.action === ALLOW;
+  const scratch = folded || {};
+  const m = rule.match;
+
+  if (!m || Object.keys(m).length === 0) {
+    // A rule with no clauses is unconditional. For a deny that is a legitimate thing to ship —
+    // `{action: 'deny', enforce: true}` is the kill switch, and the control plane is entitled to
+    // send it. For an *allow* it is almost always a mistake (a match block that failed to
+    // serialise, a template that rendered empty), and the mistake authorises everything. So
+    // unconditional means "everything" in the refusing direction only.
+    return rule.action !== ALLOW;
+  }
+
+  for (const [clause, want] of Object.entries(m)) {
+    if (!clauseOk(clause, want, subject, allowing, scratch)) return false;
+  }
+  return true;
+}
+
+/**
+ * First matching rule wins.
+ *
+ * `deadline` is polled between rules — cooperative rather than pre-emptive, because JavaScript
+ * cannot interrupt a running frame any more than Python can. The honest statement of the guarantee
+ * is that it is bounded per-rule, not per-decision.
+ *
+ * `onError` is called for a matcher that throws, which is a malformed rule that got past parsing.
+ * The rule is skipped and evaluation continues: one bad rule must not stop the rules after it from
+ * applying, which is the same argument as quarantining at parse time.
+ */
+function firstMatch(ruleset, subject, deadline, onError) {
+  const folded = {};
+  for (const rule of ruleset.rules) {
+    if (deadline && deadline()) return null;
+    try {
+      if (matches(rule, subject, folded)) return rule;
+    } catch (err) {
+      if (onError) onError(rule, err);
+    }
+  }
+  return null;
+}
+
+module.exports = {
+  ALLOW, DENY, REQUIRE_APPROVAL, ACTIONS, CLAUSES, RISK, EMPTY, SEPARATORS, MISSING,
+  parse, parseOne, matches, firstMatch, enforcing, hasEnforcing,
+  fold, foldPattern, globStrict, fnmatchcase, globToRegExp,
+};