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

package/src/posture/oracles/scenario-classes.js

@@ -0,0 +1,223 @@
+// Non-taint vulnerability classes and the rules for judging them (X-205).
+//
+// A taint engine answers "does attacker data reach a dangerous call". Several
+// defect classes have no such flow: a missing tenant check, a privileged action
+// open to a lower role, a workflow step that can be skipped, a request whose
+// effect repeats when it is delivered again, an unbounded work parameter. A
+// source-to-sink analysis finding nothing says NOTHING about them, so this module
+// states three things, each with a test:
+//
+//   1. WHICH classes are supported (`SCENARIO_CLASSES`), and for each one the
+//      adapter that executes it, what the requester must supply, the fixtures that
+//      prove it works in both directions, and the limitations a reader must see.
+//      Where an existing adapter already covers a class it is REUSED, and the
+//      entry says so (`adapterReuse`); only replay/idempotency needed a new one.
+//   2. That taint absence NEVER refutes one of these hypotheses
+//      (`judgeNonTaintHypothesis`): without an executed oracle of the class's own
+//      adapter the outcome is `not-run`, never `refuted`.
+//   3. Which results may count as a trusted negative (`trustedNegativeDenominator`):
+//      only a decided result from an executed oracle with proven preconditions.
+//      Unsupported, not-run, inconclusive, error, static-only and model-only results
+//      are listed explicitly and excluded; they cannot be counted as "checked and
+//      clean".
+//
+// This module is pure data and pure functions: it imports no adapter and runs
+// nothing, so `oracle.js` and `registry.js` can both depend on it.
+
+export const NON_TAINT_SCHEMA = 'agentic-security/non-taint-classes';
+
+const FIXTURE_ROOT = 'test/fixtures/non-taint';
+
+export const SCENARIO_CLASSES = Object.freeze([
+  Object.freeze({
+    id: 'tenant-authorization',
+    title: 'Tenant authorization',
+    adapterId: 'authorization-decision', adapterReuse: true,
+    claim: 'an actor from one tenant is allowed to read or change another tenant\'s resource',
+    cwes: ['CWE-639', 'CWE-566', 'CWE-863', 'CWE-862', 'CWE-285', 'CWE-284'],
+    families: ['idor', 'authz', 'missing-authz', 'broken-access-control', 'tenant-isolation'],
+    requires: ['an exported decision function taking the actor and the resource (or ids that resolve to them)', 'one control case the function must allow (the owner) and one attack case it must deny (another tenant)'],
+    limitations: ['asserts the decision function in isolation; a route or middleware that enforces the check elsewhere is not exercised', 'the scenario names which actors should be denied: the oracle does not infer tenancy rules', 'row-level checks inside a database query are not observed'],
+    fixtures: { dir: `${FIXTURE_ROOT}/tenant-authorization`, positive: 'positive', negative: 'negative', scenario: 'scenario.json' },
+  }),
+  Object.freeze({
+    id: 'privileged-action',
+    title: 'Privileged action',
+    adapterId: 'authorization-decision', adapterReuse: true,
+    claim: 'a lower-privileged actor is allowed to perform an action reserved for a higher role',
+    cwes: ['CWE-269', 'CWE-250', 'CWE-266', 'CWE-267'],
+    families: ['privilege-escalation', 'privileged-action', 'missing-role-check'],
+    requires: ['an exported decision function taking the actor and the action', 'one control case with the privileged role (must be allowed) and one attack case with an ordinary role (must be denied)'],
+    limitations: ['asserts the decision function in isolation; role checks enforced only by a gateway or framework guard are not exercised', 'a thrown error is not read as a denial', 'role and permission grants stored outside the function are not observed'],
+    fixtures: { dir: `${FIXTURE_ROOT}/privileged-action`, positive: 'positive', negative: 'negative', scenario: 'scenario.json' },
+  }),
+  Object.freeze({
+    id: 'workflow-order',
+    title: 'Workflow order',
+    adapterId: 'state-transition', adapterReuse: true,
+    claim: 'a step that must follow another can be performed first (for example a refund before approval)',
+    cwes: ['CWE-841', 'CWE-840', 'CWE-696'],
+    families: ['workflow', 'business-logic', 'state-machine', 'workflow-order'],
+    requires: ['an exported factory returning a machine with `send(event)` and a `state`', 'a legal event sequence with its expected final state, an attack sequence and the forbidden state'],
+    limitations: ['covers one factory and finite event lists; it is not a model checker', 'durable effects outside the machine object (a database row, a queued job) are not observed', 'the forbidden state is stated by the scenario: business rules are not inferred'],
+    fixtures: { dir: `${FIXTURE_ROOT}/workflow-order`, positive: 'positive', negative: 'negative', scenario: 'scenario.json' },
+  }),
+  Object.freeze({
+    id: 'replay-idempotency',
+    title: 'Replay and idempotency',
+    adapterId: 'replay-idempotency', adapterReuse: false,
+    claim: 'delivering the same request again repeats its side effect (a double charge, a double credit)',
+    cwes: ['CWE-294', 'CWE-837', 'CWE-841'],
+    families: ['replay', 'idempotency', 'replay-attack', 'duplicate-submission'],
+    requires: ['an exported factory that receives a recording stand-in for the effect and returns a request handler', 'a request, a distinct request and a delivery count'],
+    limitations: ['deliveries are sequential: a race between concurrent deliveries is not exercised', 'deduplication kept in an external store is not observed, only the handler the factory returns', 'code that imports its effect directly instead of receiving it is not covered'],
+    fixtures: { dir: `${FIXTURE_ROOT}/replay-idempotency`, positive: 'positive', negative: 'negative', scenario: 'scenario.json' },
+  }),
+  Object.freeze({
+    id: 'resource-exhaustion',
+    title: 'Bounded resource exhaustion',
+    adapterId: 'parser-resource', adapterReuse: true,
+    claim: 'a bounded hostile parameter makes the code exceed its time or output budget (an uncapped page size, an unbounded loop)',
+    cwes: ['CWE-400', 'CWE-770', 'CWE-789', 'CWE-405', 'CWE-834'],
+    families: ['resource-exhaustion', 'dos', 'denial-of-service', 'unbounded-loop'],
+    requires: ['an exported function taking one string', 'a benign input it must finish and a hostile input described as a unit repeated at most 65536 times'],
+    limitations: ['the hostile input is bounded and the run is cut at the supervisor deadline: this shows a budget was exceeded, not how large the blow-up is', 'memory is not measured', 'distributed or network-level exhaustion, and exhaustion that needs a populated datastore, are not exercised'],
+    fixtures: { dir: `${FIXTURE_ROOT}/resource-exhaustion`, positive: 'positive', negative: 'negative', scenario: 'scenario.json' },
+  }),
+]);
+
+// Non-taint classes this build recognises and does NOT execute. A finding that maps here is `unsupported`,
+// stated by name, and never counted as checked.
+export const UNSUPPORTED_NON_TAINT = Object.freeze([
+  Object.freeze({ id: 'concurrent-race', cwes: ['CWE-362', 'CWE-367'], reason: 'a race needs concurrent scheduling; the adapters deliver sequentially, so no verdict about a race can be formed' }),
+  Object.freeze({ id: 'cross-site-request-forgery', cwes: ['CWE-352'], reason: 'needs a browser and a session; no adapter exercises one' }),
+  Object.freeze({ id: 'authentication-throttling', cwes: ['CWE-307', 'CWE-799'], reason: 'needs a stateful attempt counter over time and a populated store; the adapters bound a single input, not a campaign' }),
+]);
+
+const BY_ID = new Map(SCENARIO_CLASSES.map((c) => [c.id, c]));
+
+export function scenarioClassesForAdapter(adapterId) { return SCENARIO_CLASSES.filter((c) => c.adapterId === adapterId); }
+
+/**
+ * The lines a user reads about one class: what it asserts, what the requester must supply (prerequisites), the platform
+ * statement and every limitation. A report that shows a class shows these with it.
+ * @param {object} cls  a SCENARIO_CLASSES entry
+ * @param {object} [adapter] the executing adapter (prerequisites and platform statements are taken from it)
+ */
+export function scenarioClassReportLines(cls, adapter = null) {
+  const lines = [`${cls.title} (${cls.id}): ${cls.claim}.`];
+  lines.push(`  oracle: ${cls.adapterId}${cls.adapterReuse ? ' (an existing adapter, reused for this class)' : ' (added for this class)'}`);
+  lines.push(`  prerequisites: ${[...cls.requires, ...(adapter ? adapter.prerequisites.map((p) => `host: ${p}`) : [])].join('; ')}`);
+  if (adapter) lines.push(`  platforms: macOS ${adapter.platforms.darwin.status}, Linux ${adapter.platforms.linux.status}, Windows ${adapter.platforms.win32.status}`);
+  for (const l of cls.limitations) lines.push(`  limitation: ${l}`);
+  lines.push('  not established: a clean result covers only the declared scenario; it is not proof the class is absent from the code.');
+  return lines;
+}
+
+// ------------------------------------------------------------------ classification
+
+const cweOf = (f) => String(f?.cwe || '').toUpperCase().replace(/^CWE[-_ ]?/, 'CWE-');
+const familyOf = (f) => String(f?.family || '').toLowerCase();
+
+/**
+ * Which non-taint class, supported or not, does this finding belong to? `null` when it is not a recognised non-taint
+ * hypothesis (then nothing in this module applies). An explicit `finding.scenarioClass` wins over CWE and family.
+ * @returns {null | { classId: string, supported: boolean, title: string, reason?: string }}
+ */
+export function nonTaintClassOf(finding) {
+  if (!finding || typeof finding !== 'object') return null;
+  if (typeof finding.scenarioClass === 'string') {
+    const c = BY_ID.get(finding.scenarioClass);
+    if (c) return { classId: c.id, supported: true, title: c.title };
+  }
+  const cwe = cweOf(finding);
+  const fam = familyOf(finding);
+  for (const u of UNSUPPORTED_NON_TAINT) {
+    if (u.cwes.includes(cwe) || fam === u.id) return { classId: u.id, supported: false, title: u.id.replace(/-/g, ' '), reason: u.reason };
+  }
+  for (const c of SCENARIO_CLASSES) {
+    if (c.cwes.includes(cwe) || c.families.includes(fam)) return { classId: c.id, supported: true, title: c.title };
+  }
+  return null;
+}
+
+// ------------------------------------------------------------------ judging a non-taint hypothesis
+
+/**
+ * Judge a non-taint hypothesis from what is actually known about it.
+ *
+ * The rule: absence of a taint flow is not evidence about these classes, so it is never an input to a refutation. An
+ * outcome of `refuted` needs an EXECUTED oracle result from the class's own adapter with proven preconditions; anything
+ * else is `not-run` (a supported class nobody ran), `unsupported` (a class this build cannot execute) or the oracle's own
+ * `confirmed`/`inconclusive`/`error`.
+ *
+ * @param {object} args
+ * @param {object} args.finding
+ * @param {object} [args.taint]        static taint evidence, for example `{ clean: true }`; recorded, never used to refute
+ * @param {object} [args.oracleResult] `{ outcome, oracleId, preconditionsValid }` from a run of an oracle adapter
+ * @returns {{ nonTaint: boolean, classId?: string, supported?: boolean, outcome?: string, reason?: string, taintAbsenceUsed: false }}
+ */
+export function judgeNonTaintHypothesis({ finding, taint = null, oracleResult = null } = {}) {
+  const cls = nonTaintClassOf(finding);
+  if (!cls) return { nonTaint: false, taintAbsenceUsed: false };
+  const taintNote = taint && taint.clean === true
+    ? ' No source-to-sink flow was found, and that says nothing about this class: it is not a refutation.'
+    : '';
+  if (!cls.supported) {
+    return { nonTaint: true, classId: cls.classId, supported: false, outcome: 'unsupported', taintAbsenceUsed: false,
+      reason: `${cls.title} is a non-taint class this build does not execute: ${cls.reason}.${taintNote}` };
+  }
+  const own = BY_ID.get(cls.classId);
+  const r = oracleResult && typeof oracleResult === 'object' ? oracleResult : null;
+  const decisive = r && r.oracleId === own.adapterId && ['confirmed', 'refuted', 'inconclusive', 'error'].includes(r.outcome);
+  if (!decisive) {
+    return { nonTaint: true, classId: cls.classId, supported: true, outcome: 'not-run', taintAbsenceUsed: false,
+      reason: `no executed ${own.adapterId} oracle result exists for this ${cls.title.toLowerCase()} hypothesis, so it stays unrefuted.${taintNote}` };
+  }
+  if (r.outcome === 'refuted' && r.preconditionsValid !== true) {
+    return { nonTaint: true, classId: cls.classId, supported: true, outcome: 'inconclusive', taintAbsenceUsed: false,
+      reason: `the ${own.adapterId} oracle did not show its preconditions held, so its negative result is not a refutation.${taintNote}` };
+  }
+  return { nonTaint: true, classId: cls.classId, supported: true, outcome: r.outcome, taintAbsenceUsed: false,
+    reason: `decided by the executed ${own.adapterId} oracle.${taintNote}` };
+}
+
+// ------------------------------------------------------------------ the trusted-negative denominator
+
+const ORACLE_IDS = new Set(SCENARIO_CLASSES.map((c) => c.adapterId));
+
+function whyExcluded(rec) {
+  if (!rec || typeof rec !== 'object') return 'malformed';
+  if (rec.outcome === 'unsupported') return 'unsupported';
+  if (rec.outcome === 'not-run') return 'not-run';
+  if (rec.outcome === 'inconclusive') return 'inconclusive';
+  if (rec.outcome === 'error') return 'error';
+  if (rec.outcome !== 'confirmed' && rec.outcome !== 'refuted') return 'not-decided';
+  if (!rec.oracle || rec.oracle.kind !== 'runtime-replay') return 'no-executed-oracle';
+  if (!ORACLE_IDS.has(rec.oracle.id)) return 'oracle-not-in-supported-class-manifest';
+  if (!rec.preconditions || rec.preconditions.valid !== true) return 'preconditions-not-proved';
+  if (!Array.isArray(rec.evidence) || !rec.evidence.some((e) => e && e.kind === 'trusted-runtime-proof')) return 'no-trusted-runtime-proof';
+  return null;
+}
+
+/**
+ * The trusted-negative denominator over verification records: the decided results (`confirmed` or `refuted`) of an
+ * executed oracle of an advertised class with proven preconditions and trusted runtime proof. Everything else is listed
+ * with the reason it is excluded; an unsupported or unrun case can never be counted as a negative.
+ */
+export function trustedNegativeDenominator(records) {
+  const list = Array.isArray(records) ? records : [];
+  let trustedNegatives = 0;
+  let trustedPositives = 0;
+  const excluded = [];
+  for (const rec of list) {
+    const why = whyExcluded(rec);
+    if (why) { excluded.push({ id: rec && rec.id ? String(rec.id) : null, outcome: rec && rec.outcome ? String(rec.outcome) : null, reason: why }); continue; }
+    if (rec.outcome === 'refuted') trustedNegatives++; else trustedPositives++;
+  }
+  return {
+    denominator: trustedNegatives + trustedPositives, trustedNegatives, trustedPositives,
+    excluded, unsupported: excluded.filter((e) => e.reason === 'unsupported'),
+    total: list.length,
+  };
+}

package/src/posture/portfolio/backend.js

@@ -0,0 +1,279 @@
+// Pluggable storage backends and offline operation for portfolios (X-708.AC02, X-708.AC03).
+//
+// Everything in the portfolio works with no hosted service: state is plain files, written atomically, readable with the standard
+// library. This module adds the one thing a single store file cannot give, a defined way to run it from SEVERAL workers or hosts that
+// share a directory, and a defined answer when that directory is not there.
+//
+// THE BACKEND INTERFACE (what a replacement implements)
+//   kind                       'local-fs' | 'shared-dir' (a label that appears in every report)
+//   describe()                 { kind, root, consistency } and what the backend does NOT claim
+//   probe()                    { ok: true } or { ok: false, state: 'blocked', code, reason }; never throws, never creates anything
+//   storeFile(name)            the path of a named document, for the portfolio store and ledger
+//   withExclusive(name, fn)    run `fn` while holding a cross-process lock; throws BACKEND_UNAVAILABLE if the backend went away
+//   acquireLease / renewLease / releaseLease / readLease
+//                              a named, expiring, FENCED lease (below)
+//
+// REFERENCE IMPLEMENTATION. `FileLockBackend` uses exclusive file creation (`open(..., 'wx')`) in a directory. `createLocalBackend`
+// makes the directory if needed (single user, durable restart). `createSharedBackend` will NOT: it requires a marker file written by
+// an explicit `initSharedBackend`, so an unmounted path, a mistyped path or an empty mount point is a typed `blocked`, never a quietly
+// fresh store.
+//
+// LEASE SEMANTICS (each tested, including two real processes contending):
+//   - mutual exclusion: at most one holder has an unexpired lease on a resource at a time;
+//   - fencing: every grant increments a `fence` number that never goes down (a release keeps it). A holder presents its fence on
+//     renew and release, so a holder that was replaced after its lease expired is refused and learns it lost the lease (`lost`);
+//   - expiry takeover: an expired lease can be taken by anyone; the previous holder's renew then fails;
+//   - release by anyone but the holder, or with a stale fence, is refused.
+//
+// WHAT IS NOT CLAIMED. These semantics were verified on one machine's local filesystem, with several processes. Exclusive file
+// creation is atomic on a local POSIX filesystem; whether it is atomic on a particular network filesystem depends on that filesystem
+// and its mount options, and this build has not tested any. A shared directory used from several HOSTS therefore needs the operator to
+// verify exclusive-create atomicity on that mount, and lease expiry compares wall clocks, so hosts' clocks must agree to well within a
+// lease. Stale-lock recovery (a holder that died inside a critical section) has a narrow window in which two recoverers can both
+// believe they broke the lock; critical sections here last milliseconds, and `lockStaleMs` is far above that. `networkFilesystem` is
+// reported `unverified` in `describe()`.
+//
+// UNAVAILABLE BACKEND. Selecting a shared backend that cannot be used returns `{ ok: false, state: 'blocked', code, reason }` from
+// `openBackend`, and there is no fallback argument: nothing here ever "degrades" to a local write. Callers must stop, not substitute.
+
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { digestOf } from '../assurance/identity.js';
+import { findSecret } from './bundle.js';
+import { verifyStore, typedError } from './work-units.js';
+import { ledgerPathFor, readLedger } from './scheduler.js';
+
+export const BACKEND_MARKER = '.agentic-security-backend.json';
+export const BACKEND_MARKER_SCHEMA = 'agentic-security/portfolio-backend-marker';
+export const STATE_EXPORT_SCHEMA = 'agentic-security/portfolio-state-export';
+export const BLOCK_CODES = Object.freeze(['backend-missing', 'backend-not-initialized', 'backend-not-a-directory', 'backend-symlink', 'backend-not-writable', 'backend-marker-invalid']);
+export const BACKEND_LIMITS = Object.freeze({ lockStaleMs: 30_000, lockWaitMs: 5000, maxLeaseMs: 6 * 60 * 60_000, maxExportBytes: 64 * 1024 * 1024 });
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+
+function sleepSync(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+const unavailable = (probe) => typedError('BACKEND_UNAVAILABLE', `the portfolio backend is unavailable (${probe.code}): ${probe.reason}`, { state: 'blocked', probe });
+
+/** The reference backend: exclusive-create file locks in a directory. */
+export class FileLockBackend {
+  constructor({ kind, root, requireMarker, lockStaleMs = BACKEND_LIMITS.lockStaleMs, lockWaitMs = BACKEND_LIMITS.lockWaitMs, nodeId = null }) {
+    this.kind = kind; this.root = path.resolve(root); this.requireMarker = requireMarker;
+    this.lockStaleMs = lockStaleMs; this.lockWaitMs = lockWaitMs;
+    this.nodeId = nodeId ?? `${os.hostname()}:${process.pid}`;
+  }
+
+  describe() {
+    return {
+      kind: this.kind, root: this.root, requiresMarker: this.requireMarker,
+      consistency: {
+        mutualExclusion: 'verified for processes sharing one local filesystem (two-process contention test)',
+        fencing: 'monotonic per resource; a stale holder is refused on renew and release',
+        networkFilesystem: 'unverified',
+        clocks: 'lease expiry compares wall clocks; hosts sharing a directory must agree to well within a lease',
+        staleLockRecovery: `a lock file older than ${this.lockStaleMs} ms is treated as abandoned; the recovery has a narrow race and is not a substitute for short critical sections`,
+      },
+    };
+  }
+
+  probe() {
+    let st;
+    try { st = fs.lstatSync(this.root); } catch { return { ok: false, state: 'blocked', code: 'backend-missing', reason: `${this.kind} backend directory does not exist or cannot be read` }; }
+    if (st.isSymbolicLink()) return { ok: false, state: 'blocked', code: 'backend-symlink', reason: 'the backend directory is a symbolic link; it is not followed' };
+    if (!st.isDirectory()) return { ok: false, state: 'blocked', code: 'backend-not-a-directory', reason: 'the backend path is not a directory' };
+    if (this.requireMarker) {
+      let m;
+      try { m = JSON.parse(fs.readFileSync(path.join(this.root, BACKEND_MARKER), 'utf8')); } catch (e) {
+        return { ok: false, state: 'blocked', code: e.code === 'ENOENT' ? 'backend-not-initialized' : 'backend-marker-invalid', reason: e.code === 'ENOENT' ? 'the shared directory has no backend marker: it is not initialized (an unmounted or empty directory is not a store)' : 'the backend marker is unreadable' };
+      }
+      if (m?.schema !== BACKEND_MARKER_SCHEMA || m.kind !== this.kind) return { ok: false, state: 'blocked', code: 'backend-marker-invalid', reason: 'the backend marker does not describe this kind of backend' };
+    }
+    try {
+      const probeFile = path.join(this.root, `.probe-${process.pid}-${crypto.randomBytes(4).toString('hex')}`);
+      fs.writeFileSync(probeFile, '', { flag: 'wx' }); fs.unlinkSync(probeFile);
+    } catch { return { ok: false, state: 'blocked', code: 'backend-not-writable', reason: 'the backend directory is not writable' }; }
+    return { ok: true };
+  }
+
+  storeFile(name = 'portfolio-store.json') {
+    if (!NAME_RE.test(name)) throw typedError('BAD_NAME', `'${name}' is not an allowed document name`);
+    return path.join(this.root, name);
+  }
+
+  _lockPath(name) {
+    if (!NAME_RE.test(name)) throw typedError('BAD_NAME', `'${name}' is not an allowed lock name`);
+    return path.join(this.root, '.locks', `${name}.lock`);
+  }
+
+  /** Run `fn` under the named cross-process lock. The backend is re-probed first: a backend that went away is an error, not an empty store. */
+  withExclusive(name, fn, { waitMs = this.lockWaitMs } = {}) {
+    const p = this.probe();
+    if (!p.ok) throw unavailable(p);
+    const lock = this._lockPath(name);
+    fs.mkdirSync(path.dirname(lock), { recursive: true });
+    const token = crypto.randomBytes(12).toString('hex');
+    const body = JSON.stringify({ token, node: this.nodeId, pid: process.pid });
+    const start = Date.now();
+    for (;;) {
+      try { fs.writeFileSync(lock, body, { flag: 'wx' }); break; } catch (e) {
+        if (e.code !== 'EEXIST') throw e;
+        this._breakIfStale(lock);
+        if (Date.now() - start > waitMs) throw typedError('LOCK_TIMEOUT', `could not take lock '${name}' within ${waitMs} ms`);
+        sleepSync(3);
+      }
+    }
+    try { return fn(); } finally {
+      // release only OUR lock: if it was recovered as stale and re-taken, the file belongs to someone else now
+      try { if (JSON.parse(fs.readFileSync(lock, 'utf8')).token === token) fs.unlinkSync(lock); } catch { /* already gone */ }
+    }
+  }
+
+  _breakIfStale(lock) {
+    let st; let seen;
+    try { st = fs.statSync(lock); seen = JSON.parse(fs.readFileSync(lock, 'utf8')).token; } catch { return; }
+    if (Date.now() - st.mtimeMs <= this.lockStaleMs) return;
+    const grave = `${lock}.broken-${process.pid}-${crypto.randomBytes(3).toString('hex')}`;
+    try { fs.renameSync(lock, grave); } catch { return; }
+    let got = null;
+    try { got = JSON.parse(fs.readFileSync(grave, 'utf8')).token; } catch { /* unreadable: treated as the stale one */ }
+    if (got !== null && got !== seen) { try { fs.linkSync(grave, lock); } catch { /* the lock was re-taken meanwhile: the documented narrow race */ } }
+    try { fs.unlinkSync(grave); } catch { /* ignore */ }
+  }
+
+  _leaseFile(resource) {
+    if (!NAME_RE.test(resource)) throw typedError('BAD_NAME', `'${resource}' is not an allowed lease name`);
+    return path.join(this.root, 'leases', `${resource}.json`);
+  }
+
+  _readLease(resource) {
+    try { return JSON.parse(fs.readFileSync(this._leaseFile(resource), 'utf8')); } catch (e) { if (e.code === 'ENOENT') return null; throw typedError('LEASE_CORRUPT', `lease '${resource}' is unreadable`); }
+  }
+
+  _writeLease(resource, doc) {
+    const file = this._leaseFile(resource);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(doc), { mode: 0o600 });
+    fs.renameSync(tmp, file);
+  }
+
+  readLease(resource) { return this.withExclusive(`lease-${resource}`, () => this._readLease(resource)); }
+
+  acquireLease(resource, { holder, ttlMs, now }) {
+    if (typeof holder !== 'string' || !holder) throw typedError('BAD_HOLDER', 'a lease needs a holder');
+    if (!(Number.isFinite(ttlMs) && ttlMs >= 1) || !Number.isFinite(now)) throw typedError('BAD_LEASE', 'a lease needs a positive ttlMs and a now');
+    const ttl = Math.min(ttlMs, BACKEND_LIMITS.maxLeaseMs);
+    return this.withExclusive(`lease-${resource}`, () => {
+      const cur = this._readLease(resource);
+      if (cur && cur.holder && cur.expiresAt > now) return { ok: false, code: 'held', heldBy: cur.holder, expiresAt: cur.expiresAt, fence: cur.fence };
+      const fence = (cur?.fence ?? 0) + 1;
+      const doc = { resource, holder, fence, expiresAt: now + ttl, acquiredAt: now, node: this.nodeId };
+      this._writeLease(resource, doc);
+      return { ok: true, fence, expiresAt: doc.expiresAt, takenOver: !!(cur && cur.holder) };
+    });
+  }
+
+  renewLease(resource, { holder, fence, ttlMs, now }) {
+    const ttl = Math.min(ttlMs, BACKEND_LIMITS.maxLeaseMs);
+    return this.withExclusive(`lease-${resource}`, () => {
+      const cur = this._readLease(resource);
+      if (!cur || cur.holder !== holder || cur.fence !== fence) return { ok: false, code: 'lost', reason: 'the lease is held by another holder or generation' };
+      if (cur.expiresAt <= now) return { ok: false, code: 'expired', reason: 'the lease expired; it must be acquired again' };
+      cur.expiresAt = now + ttl;
+      this._writeLease(resource, cur);
+      return { ok: true, fence, expiresAt: cur.expiresAt };
+    });
+  }
+
+  releaseLease(resource, { holder, fence }) {
+    return this.withExclusive(`lease-${resource}`, () => {
+      const cur = this._readLease(resource);
+      if (!cur || cur.holder !== holder || cur.fence !== fence) return { ok: false, code: 'not-holder', reason: 'only the current holder, with its fence, can release' };
+      this._writeLease(resource, { resource, holder: null, fence: cur.fence, expiresAt: 0, node: this.nodeId });
+      return { ok: true };
+    });
+  }
+}
+
+/** Create the marker that makes a directory a shared backend. An explicit operator act; `openBackend` never does it. */
+export function initSharedBackend(dir, { id = crypto.randomBytes(8).toString('hex') } = {}) {
+  const root = path.resolve(dir);
+  fs.mkdirSync(root, { recursive: true });
+  const marker = path.join(root, BACKEND_MARKER);
+  if (fs.existsSync(marker)) return { ok: true, created: false };
+  fs.writeFileSync(marker, JSON.stringify({ schema: BACKEND_MARKER_SCHEMA, kind: 'shared-dir', id }), { flag: 'wx' });
+  return { ok: true, created: true };
+}
+
+export const createLocalBackend = (dir, o = {}) => { fs.mkdirSync(path.resolve(dir), { recursive: true }); return new FileLockBackend({ kind: 'local-fs', root: dir, requireMarker: false, ...o }); };
+export const createSharedBackend = (dir, o = {}) => new FileLockBackend({ kind: 'shared-dir', root: dir, requireMarker: true, ...o });
+
+/**
+ * Select a backend. `mode` is 'local' or 'shared'. A shared backend that is not usable returns `{ ok: false, state: 'blocked', ... }`;
+ * there is no fallback to the local backend, by design.
+ */
+export function openBackend({ mode, dir }) {
+  if (mode !== 'local' && mode !== 'shared') return { ok: false, state: 'blocked', code: 'invalid-mode', reason: "mode must be 'local' or 'shared'" };
+  if (typeof dir !== 'string' || !dir) return { ok: false, state: 'blocked', code: 'backend-missing', reason: 'a backend directory is required' };
+  const backend = mode === 'local' ? createLocalBackend(dir) : createSharedBackend(dir);
+  const p = backend.probe();
+  return p.ok ? { ok: true, backend } : p;
+}
+
+// ---------------------------------------------------------------- offline export and import
+
+/**
+ * A single self-checking file holding the portfolio store and ledger (and optionally the deletion log), for moving state to an
+ * air-gapped machine or archiving it. Reads nothing from the network. Refused if the store fails verification or any text in it has a
+ * secret shape.
+ */
+export function exportState({ storeFile, outFile, retentionLog = null, now }) {
+  const storeText = fs.readFileSync(storeFile, 'utf8');
+  if (storeText.length > BACKEND_LIMITS.maxExportBytes) throw typedError('EXPORT_TOO_LARGE', 'the store is larger than the export limit');
+  const store = JSON.parse(storeText);
+  const v = verifyStore(store);
+  if (!v.ok) throw typedError('STORE_CORRUPT', `refusing to export a store that fails verification: ${v.errors[0].code}`);
+  const ledger = readLedger(storeFile);
+  const log = retentionLog && fs.existsSync(retentionLog) ? fs.readFileSync(retentionLog, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l)) : [];
+  const body = { schema: STATE_EXPORT_SCHEMA, version: 1, ...(store.synthetic ? { synthetic: true } : {}), exportedAtMs: now, store, ledger, retentionLog: log };
+  const secret = findSecret(JSON.stringify(body));
+  if (secret) throw typedError('SECRET_IN_EXPORT', `the state contains a secret-shaped string (${secret}); it was not exported`);
+  const doc = { ...body, digest: digestOf(body) };
+  fs.mkdirSync(path.dirname(path.resolve(outFile)), { recursive: true });
+  const tmp = `${outFile}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(doc), { mode: 0o600 });
+  fs.renameSync(tmp, outFile);
+  return { ok: true, digest: doc.digest, units: Object.keys(store.units).length };
+}
+
+/** Offline verification of an export: re-derives its digest and verifies the store inside. Executes nothing. */
+export function verifyStateExport(file) {
+  let doc;
+  try {
+    const st = fs.lstatSync(file);
+    if (st.isSymbolicLink() || !st.isFile() || st.size > BACKEND_LIMITS.maxExportBytes) return { ok: false, code: 'BAD_FILE', reason: 'not a regular file within the size limit' };
+    doc = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch { return { ok: false, code: 'BAD_FILE', reason: 'unreadable or not JSON' }; }
+  if (doc?.schema !== STATE_EXPORT_SCHEMA || doc.version !== 1) return { ok: false, code: 'BAD_SCHEMA', reason: 'not a portfolio state export of a supported version' };
+  const { digest, ...body } = doc;
+  if (digestOf(body) !== digest) return { ok: false, code: 'DIGEST_MISMATCH', reason: 'the export was modified after it was written' };
+  const v = verifyStore(doc.store);
+  if (!v.ok) return { ok: false, code: 'STORE_INVALID', reason: `the store inside fails verification: ${v.errors[0].code}` };
+  return { ok: true, doc };
+}
+
+/** Import into a backend that holds no portfolio store yet. Verifies first; never overwrites. */
+export function importState({ from, backend, name = 'portfolio-store.json' }) {
+  const p = backend.probe();
+  if (!p.ok) return p;
+  const v = verifyStateExport(from);
+  if (!v.ok) return { ok: false, state: 'rejected', code: v.code, reason: v.reason };
+  const file = backend.storeFile(name);
+  return backend.withExclusive('import', () => {
+    if (fs.existsSync(file)) return { ok: false, state: 'rejected', code: 'WOULD_OVERWRITE', reason: 'the backend already holds a portfolio store; import never overwrites' };
+    fs.writeFileSync(file, JSON.stringify(v.doc.store), { flag: 'wx', mode: 0o600 });
+    fs.writeFileSync(ledgerPathFor(file), JSON.stringify(v.doc.ledger), { flag: 'wx', mode: 0o600 });
+    return { ok: true, file, units: Object.keys(v.doc.store.units).length };
+  });
+}
+