@clear-capabilities/agentic-security-scanner 0.162.0 → 0.163.0

package/src/capabilities/probes.js

@@ -0,0 +1,211 @@
+// Active probes for the controls capability enforcement depends on (X-502, X-503,
+// X-504), and the platform status that follows from them.
+//
+// The sandbox already probes write confinement, read denial of named host paths,
+// environment scrubbing, the no-network default, tree termination and the
+// file-size limit (sandbox/control-probes.js). Capability enforcement needs three
+// more, each established the same way: an attack through the real backend that
+// must fail, paired with a positive control that must succeed, so a probe that
+// cannot succeed cannot pass for a working control.
+//
+//   fs-read-confinement   a canary outside every declared root is unreadable by
+//                         the task, by a descendant, through a symbolic link
+//                         planted inside a readable root and through `..`; the
+//                         same canary IS readable once its directory is declared
+//   fs-multi-root-write   several declared write roots are writable, a read-only
+//                         root and an undeclared directory are not
+//   network-mediation     a declared destination is reachable through the
+//                         mediation proxy, an undeclared one is refused by the
+//                         proxy, and a direct socket to either is refused by the
+//                         operating system
+//
+// Nothing here asserts an outcome on a platform it did not run on. On the
+// namespace backend (Linux) the new controls are `unsupported`, because that
+// backend does not implement them, and the inherited probes run for real where a
+// Linux host exists. No state is ever inherited from another platform.
+import fs from 'node:fs';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { detectBackend } from '../sandbox/capabilities.js';
+import { runConfinedSupervised } from '../sandbox/supervise.js';
+import { probeControls, unmetControls } from '../sandbox/control-probes.js';
+import { digestOf } from '../posture/assurance/identity.js';
+import { FEATURES } from '../posture/assurance/config.js';
+import { bindManifest } from './manifest.js';
+import { startMediationProxy } from './proxy.js';
+
+export const CAPABILITY_CONTROLS = Object.freeze(['fs-read-confinement', 'fs-multi-root-write', 'network-mediation']);
+
+const NODE = process.execPath;
+const ZERO_REV = '0'.repeat(40);
+const proved = (evidence) => ({ state: 'proved', evidence });
+const notProved = (reason) => ({ state: 'not-proved', reason });
+const unsupported = (reason) => ({ state: 'unsupported', reason });
+
+function mk(prefix) { return fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix))); }
+function rm(p) { try { fs.rmSync(p, { recursive: true, force: true }); } catch { /* best effort */ } }
+const token = (p) => `${p}-${crypto.randomBytes(8).toString('hex')}`;
+
+async function probeFsRead(backend) {
+  if (backend !== 'userspace') return unsupported(`read confinement to declared roots is not implemented on the ${backend} backend`);
+  const root = mk('agsec-cap-r-'); const ro = mk('agsec-cap-ro-'); const outside = mk('agsec-cap-out-');
+  try {
+    const okTok = token('READABLE'); const secTok = token('SEALED');
+    fs.writeFileSync(path.join(ro, 'r.txt'), okTok);
+    fs.writeFileSync(path.join(outside, 's.txt'), secTok);
+    fs.symlinkSync(path.join(outside, 's.txt'), path.join(ro, 'link'));
+    const run = (script, readRoots) => runConfinedSupervised(['/bin/sh', '-c', script], { root, readRoots, timeoutMs: 8000, graceMs: 300 });
+    const pos = await run(`cat '${ro}/r.txt'`, [ro]);
+    if (!pos.stdout.includes(okTok)) return notProved(`positive control failed: a file inside a declared root was not readable (${pos.status})`);
+    const open = await run(`cat '${outside}/s.txt'`, [ro, outside]);
+    if (!open.stdout.includes(secTok)) return notProved('positive control failed: the canary was not readable even when its directory was declared');
+    const attempts = {
+      direct: `cat '${outside}/s.txt'`,
+      'symbolic link': `cat '${ro}/link'`,
+      traversal: `cat '${ro}/../${path.basename(outside)}/s.txt'`,
+      descendant: `sh -c "cat '${outside}/s.txt'"; ( cat '${outside}/s.txt' ) 2>&1`,
+    };
+    for (const [name, script] of Object.entries(attempts)) {
+      const r = await run(`${script}; true`, [ro]);
+      if (r.stdout.includes(secTok)) return notProved(`the canary outside every declared root was readable (${name})`);
+    }
+    return proved('declared roots readable; canary unreadable directly, through a link, through .., and from a descendant; readable once declared');
+  } finally { rm(root); rm(ro); rm(outside); }
+}
+
+async function probeMultiWrite(backend) {
+  if (backend !== 'userspace') return unsupported(`several declared write roots are not implemented on the ${backend} backend`);
+  const root = mk('agsec-cap-w-'); const w1 = mk('agsec-cap-w1-'); const w2 = mk('agsec-cap-w2-');
+  const ro = mk('agsec-cap-wro-'); const outside = mk('agsec-cap-wout-');
+  try {
+    const script = [`echo a > '${w1}/f'`, `echo b > '${w2}/f'`, `echo c > '${ro}/f'`, `echo d > '${outside}/f'`, 'true'].join('; ');
+    await runConfinedSupervised(['/bin/sh', '-c', script], { root, readRoots: [ro], writeRoots: [w1, w2], timeoutMs: 8000, graceMs: 300 });
+    if (!fs.existsSync(path.join(w1, 'f')) || !fs.existsSync(path.join(w2, 'f'))) return notProved('positive control failed: a declared write root was not writable');
+    if (fs.existsSync(path.join(ro, 'f'))) return notProved('a root declared read-only was writable');
+    if (fs.existsSync(path.join(outside, 'f'))) return notProved('an undeclared directory was writable');
+    return proved('both declared write roots writable; the read-only root and an undeclared directory were not');
+  } finally { rm(root); rm(w1); rm(w2); rm(ro); rm(outside); }
+}
+
+function listener(label) {
+  const state = { connections: 0 };
+  const server = http.createServer((req, res) => { res.writeHead(200, { 'content-type': 'text/plain' }); res.end(label); });
+  server.on('connection', () => { state.connections += 1; });
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => resolve({ server, state, port: server.address().port }));
+  });
+}
+
+async function probeNetworkMediation(backend) {
+  if (backend !== 'userspace') return unsupported(`mediated network access is not implemented on the ${backend} backend (its network namespace has no path to a proxy)`);
+  const root = mk('agsec-cap-n-');
+  let a; let b; let proxy;
+  try {
+    a = await listener('A'); b = await listener('B');
+    const built = bindManifest({
+      schema: 'agentic-security/capability-manifest', schemaVersion: '1.0.0', taskId: 'probe-network', repository: { revision: ZERO_REV }, policyVersion: 1,
+      network: [{ host: '127.0.0.1', port: a.port, schemes: ['http'] }],
+    });
+    if (!built.ok) return notProved('probe manifest was invalid');
+    proxy = await startMediationProxy({ bound: built.bound });
+    const script = `
+const http=require('http'),net=require('net');
+const via=(p)=>new Promise(r=>{const q=http.request({host:'127.0.0.1',port:${proxy.port},method:'GET',path:'http://127.0.0.1:'+p+'/',headers:{host:'127.0.0.1:'+p},agent:false},res=>{let b='';res.on('data',d=>b+=d);res.on('end',()=>r({s:res.statusCode,b}))});q.on('error',e=>r({e:e.code}));q.setTimeout(4000,()=>q.destroy());q.end()});
+const direct=(p)=>new Promise(r=>{const s=net.connect(p,'127.0.0.1');s.on('connect',()=>{s.destroy();r({connected:true})});s.on('error',e=>r({e:e.code}));setTimeout(()=>r({e:'TIMEOUT'}),2500)});
+(async()=>{console.log(JSON.stringify({pa:await via(${a.port}),pb:await via(${b.port}),da:await direct(${a.port}),db:await direct(${b.port})}))})();`;
+    const r = await runConfinedSupervised([NODE, '-e', script], {
+      root, readRoots: [NODE], networkProxyPort: proxy.port, timeoutMs: 15000, graceMs: 300,
+    });
+    let out;
+    try { out = JSON.parse(String(r.stdout).trim().split('\n').pop()); } catch { return notProved(`positive control failed: the probe client did not report (${r.status})`); }
+    if (!(out.pa && out.pa.s === 200 && out.pa.b === 'A')) return notProved('positive control failed: a declared destination was not reachable through the proxy');
+    if (!(out.pb && out.pb.s === 403)) return notProved('an undeclared destination was not refused by the proxy');
+    if (out.da?.connected || out.db?.connected) return notProved('a direct socket bypassed the proxy');
+    if (b.state.connections !== 0) return notProved('the undeclared listener saw a connection');
+    if (a.state.connections !== 1) return notProved(`the declared listener saw ${a.state.connections} connections; only the proxied request should have arrived`);
+    return proved('declared destination reachable only through the proxy; undeclared refused by the proxy; direct sockets refused by the operating system');
+  } finally {
+    if (proxy) await proxy.close();
+    for (const l of [a, b]) if (l) await new Promise((res) => l.server.close(() => res()));
+    rm(root);
+  }
+}
+
+const _cache = new Map();
+export function resetCapabilityProbeCache() { _cache.clear(); }
+
+async function measure(backend, force) {
+  const base = await probeControls({ force });
+  const controls = { ...base.controls };
+  if (backend === 'disabled') {
+    for (const c of CAPABILITY_CONTROLS) controls[c] = { state: 'unavailable', reason: 'no confinement backend works on this host' };
+  } else {
+    const run = async (name, fn) => {
+      try { controls[name] = await fn(); } catch (e) { controls[name] = notProved(`probe threw: ${String(e.message).split('\n')[0]}`); }
+    };
+    await run('fs-read-confinement', () => probeFsRead(backend));
+    await run('fs-multi-root-write', () => probeMultiWrite(backend));
+    await run('network-mediation', () => probeNetworkMediation(backend));
+  }
+  return controls;
+}
+
+/**
+ * Probe every control capability enforcement uses, on the active backend.
+ * @param {object} [o]
+ * @param {string} [o.force]   backend override (same meaning as runConfined's)
+ * @param {object} [o.probes]  per-control overrides (test seam). An override can only
+ *                             be used to make a control LESS proved in a test; a run
+ *                             still goes through the real backend.
+ */
+export async function probeCapabilityControls({ force, probes = {} } = {}) {
+  const backend = detectBackend({ force });
+  if (!_cache.has(backend)) _cache.set(backend, await measure(backend, force));
+  const controls = { ..._cache.get(backend) };
+  // Overrides replace one control's result after the real measurement; the run
+  // itself still goes through the real backend.
+  for (const [name, fn] of Object.entries(probes)) controls[name] = await fn();
+  const states = Object.fromEntries(Object.entries(controls).sort().map(([k, v]) => [k, v.state]));
+  return {
+    platform: process.platform, backend, controls,
+    probeDigest: digestOf({ platform: process.platform, backend, states }),
+  };
+}
+
+/** Controls this manifest actually depends on; a control it never uses cannot block it. */
+export function requiredControlsFor(manifest) {
+  const req = ['write-confinement', 'read-denial', 'fs-read-confinement', 'fs-multi-root-write', 'env-scrub', 'tree-termination', 'file-size-limit', 'network'];
+  if (manifest.network.length) req.push('network-mediation');
+  return req;
+}
+
+/**
+ * Whether this platform and backend are one the product ADVERTISES for enforced
+ * mode. Taken from the feature table in the assurance config (Linux only), and
+ * the only advertised backend is the kernel-namespace one. The macOS userspace
+ * backend can be proved on a host by the probes above, and is still not
+ * advertised: it is development-host evidence, not an enforced backend.
+ */
+export function isAdvertisedBackend(backend, platform = process.platform) {
+  return FEATURES['capability-enforcement'].platforms.includes(platform) && backend === 'namespace';
+}
+
+/** Standing platform statements. Nothing here is measured; it states what has and has not been evidenced. */
+export function platformStatements() {
+  return Object.freeze({
+    linux: {
+      backend: 'namespace', status: 'unverified',
+      note: 'advertised for enforced mode, but the control probes in this module have not run on a Linux host from this workspace. Several controls are not implemented on the namespace backend (read confinement to declared roots, several write roots, mediated network, supervised tree termination), so enforced mode is blocked there until they are implemented and the sandbox-linux job shows them proved. Process-count caps are never claimed.',
+    },
+    darwin: {
+      backend: 'userspace', status: 'host-proved-not-advertised',
+      note: 'the active probes can prove the controls on a macOS host, and tasks can run there for development only when the caller opts in; macOS is not an advertised enforced backend.',
+    },
+    win32: { backend: null, status: 'unsupported', note: 'no isolation backend exists on Windows.' },
+  });
+}
+
+export { unmetControls };

package/src/capabilities/proxy.js

@@ -0,0 +1,182 @@
+// The mediated network boundary (X-504.AC01, X-504.AC03).
+//
+// The runner starts one of these per task that declares network destinations and
+// opens exactly its loopback port in the sandbox profile. Everything else is
+// closed by the operating system: DNS, every other loopback port, every remote
+// address, every unix socket. A child, a descendant or an interpreter that
+// ignores the proxy settings and opens a socket itself is refused by the kernel,
+// not by this file; this file decides what the ONE open door lets through.
+//
+// Per request:
+//   1. the destination is checked against the bound manifest (`decide`, kind
+//      'network') before any name is resolved
+//   2. the name is resolved ONCE, in this process (the sandbox cannot resolve),
+//      the resolved addresses are checked (a declared name that resolves to a
+//      loopback, private, link-local or metadata address is refused unless the
+//      entry says so; a pinned address set must match), and the connection goes to
+//      the address that was checked, so a name that changes between check and
+//      connect cannot redirect the connection
+//   3. plaintext HTTP is buffered (bounded), filtered with `redactOutbound`, and
+//      forwarded; a binary body that cannot be inspected is refused
+//   4. HTTPS is an opaque CONNECT tunnel, allowed only to a destination declared
+//      for the https scheme. Its payload is NOT inspected and the report says so.
+//   5. a redirect is returned to the client unchanged and never followed here, so
+//      the next hop arrives as a new request and meets step 1 again
+//
+// A denial records the destination class, a digest of the host, the port and the
+// policy code. It never records a path, header, body or the host name itself.
+import dns from 'node:dns';
+import http from 'node:http';
+import net from 'node:net';
+import { decide } from './decide.js';
+import { redactOutbound, denialRecord, recordNetworkDenial } from './outbound.js';
+import { normalizeHost } from './address.js';
+
+const HOP_BY_HOP = new Set([
+  'connection', 'proxy-connection', 'proxy-authorization', 'proxy-authenticate', 'keep-alive', 'te', 'trailer',
+  'transfer-encoding', 'upgrade', 'content-length',
+]);
+const MAX_RECORDS = 1000;
+
+async function defaultResolve(host) {
+  const rows = await dns.promises.lookup(host, { all: true });
+  return rows.map((r) => r.address);
+}
+
+/**
+ * @param {object} o
+ * @param {{manifest: object, binding: object}} o.bound
+ * @param {string[]} [o.canaries]
+ * @param {(host:string)=>Promise<string[]>} [o.resolve]   test seam for name resolution
+ * @param {number} [o.maxRequestBytes]
+ * @param {string} [o.scanRoot]   when set, denials are appended to the egress audit chain
+ * @param {number} [o.connectTimeoutMs]
+ */
+export async function startMediationProxy({
+  bound, canaries = [], resolve = defaultResolve, maxRequestBytes = 1024 * 1024, scanRoot = null, connectTimeoutMs = 8000,
+}) {
+  const records = [];
+  const sockets = new Set();
+  const stats = { allowed: 0, denied: 0, redactions: 0, bytesForwarded: 0 };
+  const ctx = { binding: bound.binding, canaries };
+
+  const note = (outcome, code, host, port, scheme) => {
+    const rec = denialRecord({ taskId: bound.binding.taskId, host, port, scheme, code });
+    const entry = { ...rec, outcome };
+    if (records.length < MAX_RECORDS) records.push(entry);
+    if (outcome === 'deny') { stats.denied += 1; recordNetworkDenial(scanRoot, rec); } else stats.allowed += 1;
+  };
+
+  // Decide on the declared destination, resolve, decide again on the addresses.
+  async function authorize(rawHost, port, scheme) {
+    const first = decide(bound, { kind: 'network', host: rawHost, port, scheme }, ctx);
+    if (first.decision !== 'allow') return { ok: false, code: first.code };
+    const h = normalizeHost(rawHost);
+    let addresses;
+    if (h.kind === 'name') {
+      try { addresses = await resolve(h.host); } catch { addresses = []; }
+      if (!Array.isArray(addresses) || !addresses.every((a) => net.isIP(a))) addresses = [];
+    } else addresses = [h.host];
+    const second = decide(bound, { kind: 'network', host: rawHost, port, scheme, resolvedAddresses: addresses }, ctx);
+    if (second.decision !== 'allow') return { ok: false, code: second.code };
+    return { ok: true, address: addresses[0], host: h.host };
+  }
+
+  function deny(res, code) {
+    if (res.headersSent) { res.destroy(); return; }
+    const body = JSON.stringify({ blocked: true, code });
+    res.writeHead(403, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body), connection: 'close' });
+    res.end(body);
+  }
+
+  const server = http.createServer((req, res) => {
+    handle(req, res).catch(() => deny(res, 'invalid-manifest'));
+  });
+  server.on('connection', (s) => { sockets.add(s); s.on('close', () => sockets.delete(s)); });
+  server.keepAliveTimeout = 1000;
+
+  async function handle(req, res) {
+    let target;
+    try { target = new URL(req.url); } catch { target = null; }
+    if (!target || target.protocol !== 'http:') {
+      // An origin-form request is a client talking to the proxy as if it were a
+      // server; an https:// absolute URI is a client that skipped CONNECT.
+      note('deny', 'destination-not-declared', req.headers.host || '', 0, null);
+      return deny(res, 'destination-not-declared');
+    }
+    const port = target.port ? Number(target.port) : 80;
+    const auth = await authorize(target.hostname, port, 'http');
+    if (!auth.ok) { note('deny', auth.code, target.hostname, port, 'http'); return deny(res, auth.code); }
+
+    const chunks = []; let size = 0; let tooBig = false;
+    await new Promise((done) => {
+      req.on('data', (c) => { size += c.length; if (size > maxRequestBytes) { tooBig = true; req.destroy(); done(); } else chunks.push(c); });
+      req.on('end', done); req.on('error', done); req.on('close', done);
+    });
+    if (tooBig) { note('deny', 'payload-too-large', target.hostname, port, 'http'); return deny(res, 'payload-too-large'); }
+    const body = chunks.length ? Buffer.concat(chunks) : null;
+    const filtered = redactOutbound({ url: req.url, headers: req.headers, body, contentType: req.headers['content-type'] }, { canaries });
+    if (filtered.uninspectable) { note('deny', 'payload-uninspectable', target.hostname, port, 'http'); return deny(res, 'payload-uninspectable'); }
+    stats.redactions += filtered.redactions;
+
+    const out = {};
+    for (const [k, v] of Object.entries(filtered.headers)) if (!HOP_BY_HOP.has(k) && k !== 'host') out[k] = v;
+    out.host = target.port ? `${target.hostname}:${target.port}` : target.hostname;
+    out.connection = 'close';
+    if (filtered.body !== null) out['content-length'] = Buffer.byteLength(filtered.body);
+    const fu = new URL(filtered.url);
+    const upstream = http.request({
+      host: auth.address, port, method: req.method, path: `${fu.pathname}${fu.search}`, headers: out, setHost: false,
+      timeout: connectTimeoutMs, agent: false,
+    });
+    note('allow', 'allowed', target.hostname, port, 'http');
+    upstream.on('timeout', () => upstream.destroy(new Error('timeout')));
+    upstream.on('error', () => deny(res, 'destination-not-declared'));
+    upstream.on('response', (up) => {
+      const headers = {};
+      for (const [k, v] of Object.entries(up.headers)) if (!HOP_BY_HOP.has(k)) headers[k] = v;
+      headers.connection = 'close';
+      res.writeHead(up.statusCode || 502, headers);
+      up.on('data', (c) => { stats.bytesForwarded += c.length; });
+      up.pipe(res);
+    });
+    if (filtered.body !== null) upstream.write(filtered.body);
+    upstream.end();
+  }
+
+  server.on('connect', (req, client, head) => {
+    sockets.add(client); client.on('close', () => sockets.delete(client));
+    client.on('error', () => client.destroy());
+    (async () => {
+      const m = /^(\[[0-9a-fA-F:.]+\]|[^:\s]+):(\d{1,5})$/.exec(req.url || '');
+      if (!m) { note('deny', 'host-invalid', '', 0, 'https'); client.end('HTTP/1.1 403 Forbidden\r\nconnection: close\r\n\r\n'); return; }
+      const port = Number(m[2]);
+      const auth = await authorize(m[1], port, 'https');
+      if (!auth.ok) { note('deny', auth.code, m[1], port, 'https'); client.end('HTTP/1.1 403 Forbidden\r\nconnection: close\r\n\r\n'); return; }
+      const upstream = net.connect({ host: auth.address, port, timeout: connectTimeoutMs });
+      sockets.add(upstream); upstream.on('close', () => sockets.delete(upstream));
+      upstream.on('timeout', () => upstream.destroy());
+      upstream.on('error', () => { client.destroy(); });
+      client.on('close', () => upstream.destroy());
+      upstream.on('connect', () => {
+        note('allow', 'allowed', m[1], port, 'https');
+        client.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+        if (head && head.length) upstream.write(head);
+        upstream.pipe(client); client.pipe(upstream);
+      });
+    })().catch(() => client.destroy());
+  });
+
+  await new Promise((resolveListen, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolveListen); });
+  const port = server.address().port;
+  return {
+    port,
+    url: `http://127.0.0.1:${port}`,
+    records,
+    stats,
+    async close() {
+      for (const s of sockets) { try { s.destroy(); } catch { /* ignore */ } }
+      await new Promise((r) => server.close(() => r()));
+    },
+  };
+}

package/src/capabilities/reasons.js

@@ -0,0 +1,67 @@
+// Policy reason codes (X-501.AC03). A decision carries a code from this closed
+// table and the fixed sentence beside it, never text built from the request. The
+// request (a path, an argument, a host) can carry attacker-chosen content, and a
+// decision is logged, put in receipts and shown to a worker, so nothing from the
+// request may reach the reason. The only request-derived field of a decision is
+// `subject`, which is sanitized and length-capped (`sanitizeSubject`).
+import { scrubSecretText } from './secrets.js';
+
+export const REASONS = Object.freeze({
+  allowed: 'the action is inside the declared capability scope',
+  'no-grant': 'no capability of this kind is declared for the task',
+  'binding-mismatch': 'the request is not bound to this task, repository revision and policy version',
+  'unknown-action': 'the action kind is not recognized',
+  'invalid-manifest': 'the capability manifest is invalid',
+  'scope-expansion': 'the request would widen the capability scope granted by the parent task',
+  'path-invalid': 'the path is not an absolute, well-formed path',
+  'path-traversal': 'the path escapes the declared roots through parent-directory segments',
+  'symlink-escape': 'the path resolves outside the declared roots through a symbolic link',
+  'outside-roots': 'the path is outside every declared root',
+  'protected-path': 'the path is protected from tasks (keys, sealed labels, evidence, credentials)',
+  'executable-not-absolute': 'the executable must be an absolute path; names are not resolved through a search path',
+  'executable-unresolvable': 'the executable does not exist or is not a regular executable file',
+  'executable-in-writable-root': 'the executable lives in a writable root, so the task could replace it',
+  'command-not-listed': 'the executable is not a declared command',
+  'args-invalid': 'the argument list is not an array of plain strings within the size limits',
+  'args-not-permitted': 'the arguments are not permitted for this declared command',
+  'secret-in-argument': 'an argument contains secret material; arguments are visible to every process',
+  'interpreter-blocked': 'the executable is a shell or language interpreter and is not declared as a scoped interpreter',
+  'interpreter-args-unpinned': 'a scoped interpreter must be declared with its exact argument list',
+  'host-invalid': 'the destination host is not a well-formed host name or address',
+  'port-invalid': 'the destination port is not valid',
+  'destination-not-declared': 'the destination is not a declared network destination',
+  'port-not-declared': 'the destination host is declared but not on this port',
+  'scheme-not-declared': 'the destination is declared but not for this scheme',
+  'dns-private-address': 'the host name resolves to a loopback, private, link-local or metadata address that was not declared',
+  'dns-changed': 'the host name resolves to addresses outside the pinned set',
+  'payload-too-large': 'the outbound payload exceeds the mediated size limit',
+  'payload-uninspectable': 'the outbound payload is binary and cannot be filtered for secrets',
+  'tool-not-declared': 'the tool is not a declared tool action',
+  'delegation-not-allowed': 'the task is not allowed to delegate',
+  'delegation-depth': 'the delegation depth limit is reached',
+  'resource-limit-exceeded': 'the request exceeds a declared resource limit',
+  'tool-unclassified': 'the tool has no declared capability classification, so it cannot be checked and is refused',
+  'identity-missing': 'no current task identity is bound to this server, so a mutating or externally communicating tool is refused',
+  'identity-spoofed': 'the request names a task identity other than the one this server is bound to',
+  'retry-limit': 'the same action was denied the permitted number of times in this policy version and stays blocked',
+  'task-halted': 'the task reached its denial budget and is halted until an operator changes the policy',
+});
+
+export const REASON_CODES = Object.freeze(Object.keys(REASONS));
+
+export function reasonText(code) {
+  return Object.prototype.hasOwnProperty.call(REASONS, code) ? REASONS[code] : REASONS['unknown-action'];
+}
+
+/**
+ * The one request-derived field of a decision. Control characters are removed,
+ * secret-shaped material is redacted and the length is capped, so the field is
+ * safe to log and to show to the worker that made the request.
+ */
+export function sanitizeSubject(value, max = 160) {
+  let s = typeof value === 'string' ? value : JSON.stringify(value) ?? '';
+  s = s.replace(/[\u0000-\u001f\u007f]/g, ' ');
+  try { s = scrubSecretText(s).text; } catch { s = '[unprintable]'; }
+  if (s.length > max) s = `${s.slice(0, max)}...`;
+  return s || '(empty)';
+}