@miller-tech/uap 2.21.3 → 2.36.4

package/dist/policies/sandbox-anchor.js

@@ -0,0 +1,187 @@
+/**
+ * The sandbox-consent trust anchor (ADR 0011's named operator-surface follow-up).
+ *
+ * The grant ledger and audit trail live under the MAIN checkout root —
+ * writable by the operator side of every run. The kernel ro-bind closes the
+ * *sandboxed* side, and the load path re-validates shape, but neither
+ * can prove WHO wrote a row: a process with the checkout's write reach can
+ * plant a well-formed grant and claim the operator consented.
+ *
+ * This module is the honest increment: **tamper-evidence, not tamper-proofing**.
+ * A 0600 anchor file OUTSIDE the checkout's write reach records the hash of
+ * the sanitized ledger as of the last recorded consent operation. On load,
+ * the on-disk ledger is re-hashed and compared: a match proves the ledger is
+ * exactly the state a recorded grant/renew/revoke produced; a mismatch means
+ * something with checkout write access altered it — which fails CLOSED (no
+ * extra holes, loud warning) at the sandbox launch and refuses new grants.
+ *
+ * What this does NOT do (kept explicit, not hidden): the anchor lives in the
+ * user's state dir, so a *same-user* process outside the checkout can still
+ * write it. The boundary it draws is exactly the ADR's frame — the
+ * checkout's write reach vs. outside it. True origin proof (a different uid
+ * or a hardware key) remains open and is not claimed.
+ */
+import { createHash } from 'crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join, sep } from 'path';
+import { randomBytes } from 'crypto';
+import { mainCheckoutRoot } from '../utils/checkout-root.js';
+import { termSafe } from '../utils/terminal-safe.js';
+/** Anchor file version — future shape changes bump this and re-anchor. */
+export const ANCHOR_VERSION = 1;
+/** The anchor dir: OUTSIDE the checkout's write reach by construction. */
+export function anchorDir() {
+    const pinned = process.env.UAP_SANDBOX_ANCHOR_DIR;
+    if (pinned) {
+        warnIfPinnedInsideCheckout(pinned);
+        return pinned;
+    }
+    const xdg = process.env.XDG_STATE_HOME;
+    const base = xdg || join(homedir(), '.local', 'state');
+    return join(base, 'uap', 'sandbox-anchors');
+}
+/** Warn once when the pin points INSIDE the checkout the anchor vouches for:
+ *  the "verified against its trust anchor" verdict would then be false
+ *  assurance — the anchor is exactly as tamperable as the ledger it hashes.
+ *  The pin exists for tests and non-standard layouts; a real checkout root
+ *  (a dir whose git toplevel resolves) using it in-tree is operator error
+ *  worth a loud line, not a silent green. */
+let warnedPinInside = false;
+function warnIfPinnedInsideCheckout(pinned) {
+    if (warnedPinInside)
+        return;
+    try {
+        const root = mainCheckoutRoot(pinned);
+        // Only meaningful for a real git checkout; non-git tmp pins (tests) pass.
+        const isGitCheckout = existsSync(join(root, '.git')) || root !== pinned;
+        const inside = pinned === root || pinned.startsWith(root + sep);
+        if (isGitCheckout && inside && root.length > 1) {
+            warnedPinInside = true;
+            console.warn(`[sandbox-anchor] UAP_SANDBOX_ANCHOR_DIR is INSIDE the checkout (${root}) it vouches for — ` +
+                'the tamper-evidence verdict is meaningless for this session; pin a dir outside the tree');
+        }
+    }
+    catch {
+        /* the pin still works; this is advisory */
+    }
+}
+/** One anchor per MAIN-checkout root (keyed by its hash, never its literal
+ *  path — the path can contain spaces/usernames that must not reach a
+ *  filename). Keying by `mainCheckoutRoot` — NOT the raw argument — is the
+ *  whole point: every surface passes a cwd (often a `.worktrees/NNN-*`
+ *  subdir), and the LEDGER already resolves through the same helper, so
+ *  keying the anchor by the raw cwd would give the shared ledger one anchor
+ *  per cwd string: worktree sessions would silently run UNANCHORED, and a
+ *  grant recorded from one cwd would look tampered from another. All three
+ *  P-debt reviewers caught this independently; the fix is to key exactly
+ *  the way the ledger does. */
+export function anchorPath(projectRoot) {
+    const key = createHash('sha256').update(mainCheckoutRoot(projectRoot)).digest('hex').slice(0, 16);
+    return join(anchorDir(), `${key}.json`);
+}
+/** True when a granted writable path would cover the anchor dir — the one
+ *  grant that must be refused, because a hole over the anchor lets the
+ *  sandboxed side delete or corrupt the tamper evidence itself. */
+export function pathCoversAnchorDir(grantPath) {
+    const dir = anchorDir();
+    return dir === grantPath || dir.startsWith(grantPath + sep);
+}
+/** The tamper-evidence hash of a ledger state: over the SANITIZED rows (the
+ *  same shape the load path enforces), in stored order. */
+export function ledgerHeadOf(grants) {
+    return createHash('sha256').update(JSON.stringify(grants)).digest('hex');
+}
+/** Read the anchor; null when absent or malformed (absent = unanchored).
+ *  The metadata fields are termSafe'd here — they are interpolated into the
+ *  mismatch banners on the dashboard/CLI/launch stderr, and whoever can
+ *  write the anchor can plant control bytes in them. */
+export function readAnchor(projectRoot) {
+    try {
+        const raw = JSON.parse(readFileSync(anchorPath(projectRoot), 'utf-8'));
+        // Unknown future versions read as unanchored rather than being coerced
+        // into v1 shape — the anchor's own honesty rule.
+        if (raw.v !== ANCHOR_VERSION)
+            return null;
+        if (typeof raw.ledgerHead !== 'string' || !/^[0-9a-f]{64}$/.test(raw.ledgerHead))
+            return null;
+        return {
+            v: ANCHOR_VERSION,
+            ledgerHead: raw.ledgerHead,
+            mutations: typeof raw.mutations === 'number' ? raw.mutations : 0,
+            seqHi: typeof raw.seqHi === 'number' && Number.isSafeInteger(raw.seqHi) && raw.seqHi >= 0
+                ? raw.seqHi
+                : undefined,
+            updatedAt: typeof raw.updatedAt === 'string' ? termSafe(raw.updatedAt).slice(0, 64) : '',
+            updatedBy: typeof raw.updatedBy === 'string' ? termSafe(raw.updatedBy).slice(0, 64) : '',
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Write the anchor atomically with tight permissions (0600, 0700 dirs).
+ *  Best-effort: a failure is reported by return value, never a throw — the
+ *  ledger itself stays the operative record; without an anchor there is
+ *  simply nothing to verify against yet. `seqHi` is the audit high-water the
+ *  caller witnessed AFTER the operation's audit line landed (the recorded
+ *  mutations run audit-then-anchor for exactly this reason). */
+export function writeAnchor(projectRoot, ledgerHead, mutations, seqHi) {
+    try {
+        const dir = anchorDir();
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        }
+        try {
+            chmodSync(dir, 0o700); // pin the dir every time — a pre-existing loose-perm dir must not stay loose
+        }
+        catch {
+            /* non-fatal: the write still lands */
+        }
+        const state = {
+            v: ANCHOR_VERSION,
+            ledgerHead,
+            mutations,
+            seqHi,
+            updatedAt: new Date().toISOString(),
+            updatedBy: process.env.USER || process.env.LOGNAME || 'unknown',
+        };
+        const path = anchorPath(projectRoot);
+        const tmp = `${path}.${process.pid}-${randomBytes(3).toString('hex')}.tmp`;
+        writeFileSync(tmp, JSON.stringify(state, null, 2), { encoding: 'utf-8', mode: 0o600 });
+        try {
+            chmodSync(tmp, 0o600); // pin against umask
+        }
+        catch {
+            /* non-fatal */
+        }
+        renameSync(tmp, path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Verify the on-disk ledger against the anchor. 'unanchored' is not a
+ * failure — it is the pre-bootstrap state (existing ledgers predate the
+ * anchor; the first recorded mutation anchors them). 'mismatch' is the
+ * tamper signal: something changed the ledger outside a recorded consent
+ * operation.
+ */
+export function verifyLedger(projectRoot, onDiskHead) {
+    const anchor = readAnchor(projectRoot);
+    if (!anchor) {
+        return {
+            state: 'unanchored',
+            detail: 'ledger not yet anchored — the first grant/renew/revoke records the trust anchor',
+        };
+    }
+    if (anchor.ledgerHead === onDiskHead)
+        return { state: 'ok', detail: '' };
+    return {
+        state: 'mismatch',
+        detail: `ledger does not match its trust anchor (anchored ${anchor.updatedAt} by ${anchor.updatedBy}) — it was changed outside a recorded consent operation`,
+    };
+}
+//# sourceMappingURL=sandbox-anchor.js.map

package/dist/policies/sandbox-anchor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-anchor.js","sourceRoot":"","sources":["../../src/policies/sandbox-anchor.ts"],"names":[],"mappings":"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"}

package/dist/policies/sandbox-grants.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Per-session sandbox grants (the D2 consent ledger).
+ *
+ * `uap sandbox` is all-or-nothing authority: the workdir + scratch are
+ * writable, everything else is EROFS. That default is right, but real work
+ * sometimes needs one more hole (a config dir, a build cache outside the
+ * tree) — and the legacy answer, `UAP_SANDBOX_ALLOW=path:path`, was
+ * UNRECORDED authority: an env var nobody audited, invisible to the
+ * operator, surviving in shell histories and hook templates forever.
+ *
+ * This ledger is the fix: every extra hole is a GRANT — bounded by a
+ * session, a TTL, and a stated reason, recorded with who consented, and
+ * audit-logged on use. "Every new authority must state who consented"
+ * (ADR 0011, the P4 bar).
+ *
+ * Design rules (inherited from the attention-queue store, review-hardened):
+ * - the ledger is shared-write state in `.uap/`, so every string is
+ *   sanitized at INGEST and the load path re-applies the same sanitizer —
+ *   a planted row must not become a kernel-writable hole or reach
+ *   operator terminals;
+ * - atomic writes with unique tmp names (no fixed `.tmp` in shared dirs);
+ * - corrupt/unreadable ledger ⇒ EMPTY ledger: the safe direction for an
+ *   authority store is least authority (the sandbox itself stays the real
+ *   kernel boundary — a lost grant just means EROFS, not a breach);
+ * - every grant expires (default 8h, hard cap 7d): authority is bounded
+ *   by construction, and revocation is a single command;
+ * - fail-OPEN for the sandbox, fail-CLOSED for the holes: load problems
+ *   never crash a sandboxed run, they just yield no holes.
+ */
+import type { Verification } from './sandbox-anchor.js';
+/** Audit-log retention: the trail is append-only history, but an unbounded
+ *  JSONL under the shared-write `.uap/` grows forever — past
+ *  the trigger it is compacted to the newest AUDIT_MAX_LINES event lines
+ *  (plus the triggering event and one `audit-compaction` marker), so the
+ *  file lands at AUDIT_MAX_LINES + 2. The compaction is itself audited, so
+ *  a pruned trail is an EXPECTED state, never a silent one. */
+export declare const AUDIT_MAX_LINES = 10000;
+export declare const AUDIT_PRUNE_TRIGGER = 12000;
+/** One consented extra authority for one session. */
+export interface SandboxGrant {
+    id: string;
+    /** Session this grant is scoped to (UAP_SESSION_ID / --session). */
+    sessionId: string;
+    /** Absolute paths made writable inside the sandbox for this session. */
+    paths: string[];
+    /** WHY — operator-facing, required. Empty reason = refused at ingest. */
+    reason: string;
+    /** Who consented (username at grant time). */
+    grantedBy: string;
+    grantedAt: string;
+    /** ISO timestamp after which the grant is inert (hard-bounded). */
+    expiresAt: string;
+}
+export interface GrantInput {
+    sessionId: string;
+    paths: string[];
+    reason: string;
+    ttlSecs?: number;
+}
+/** A session's resolved, ACTIVE authority. */
+export interface ResolvedGrants {
+    grants: SandboxGrant[];
+    paths: string[];
+}
+/** Default grant TTL: 8h — long enough for a working session, short enough
+ *  that a forgotten hole closes itself before the next one. */
+export declare const DEFAULT_GRANT_TTL_SECS = 28800;
+/** Hard cap on grant TTL: authority must be re-consented weekly at most. */
+export declare const MAX_GRANT_TTL_SECS = 604800;
+/** Paths per grant cap: a grant is a scoped exception, not a hole list. */
+export declare const MAX_PATHS_PER_GRANT = 8;
+/**
+ * Ledger file: `<mainCheckoutRoot>/.uap/sandbox-grants.json` — ONE ledger
+ * per checkout, not per cwd, anchored at the main checkout root like the
+ * attention queue (ADR 0010): the CLI can be invoked from any worktree
+ * subdir, and a per-cwd ledger would give the same session different
+ * authority depending on where the operator happened to stand. Today the
+ * CLI is the only consumer; the anchoring also keeps a future dashboard
+ * grants view (a natural P5 surface) reading the same file.
+ * `UAP_SANDBOX_GRANTS` pins an explicit file (tests, odd layouts).
+ */
+export declare function sandboxGrantsPath(projectRoot: string): string;
+/** Audit trail: append-only JSONL, one line per grant/revoke/sandbox-use. */
+export declare function sandboxAuditPath(projectRoot: string): string;
+/**
+ * A grantable path must be ABSOLUTE, must exist (you grant a real hole, not
+ * a speculative one), and must not be an over-broad root — checked AFTER
+ * symlink resolution: `/tmp/link -> $HOME` passes a string-only refusal and
+ * bwrap's `--bind` follows the link, so the check that matters is against
+ * the REALPATH (`/`, `/home`, $HOME itself — the same refusal the sandbox
+ * applies to a too-broad workdir: an over-broad grant IS a sandbox escape).
+ * Returns the RESOLVED path (what the bind will actually target), or null.
+ */
+export declare function validateGrantPath(p: string): string | null;
+/** Verify the SANITIZED on-disk ledger against the out-of-checkout anchor.
+ *  'unanchored' is the pre-bootstrap state, not a failure. When `grants` is
+ *  passed (an already-loaded sanitized snapshot), the SAME snapshot is
+ *  verified and then acted on — the torn-read fix (a review finding):
+ *  loading the file twice left a window where the hash saw one state and
+ *  the resolver acted on another. */
+export declare function verifyLedgerIntegrity(projectRoot: string, grants?: SandboxGrant[]): Verification;
+/** Create a grant. Returns the grant, or a refusal reason. */
+export declare function grantAuthority(projectRoot: string, input: GrantInput): {
+    ok: true;
+    grant: SandboxGrant;
+} | {
+    ok: false;
+    error: string;
+};
+/** List grants, optionally scoped to one session. Expired rows are inert. */
+export declare function listAuthority(projectRoot: string, sessionId?: string): SandboxGrant[];
+/** Revoke one grant by id. Returns true only when it was found AND removed
+ *  from the ledger — a failed persist leaves the grant active, and reporting
+ *  success over a live grant would be a false consent record. */
+export declare function revokeAuthority(projectRoot: string, grantId: string): boolean;
+/**
+ * Resolve the ACTIVE authority for a session — what `uap sandbox` will
+ * actually open. Expired or malformed rows are invisible here; the sandbox
+ * never has to reason about them.
+ */
+export declare function resolveSessionGrants(projectRoot: string, sessionId: string): ResolvedGrants;
+/** Record that a sandbox run USED its grants (the "who consented, when used" line).
+ *  `netMode` is the network mode the run ACTUALLY engaged ('off' = the kernel
+ *  egress boundary): the audit line is the consent record, so it must state
+ *  the boundary that was really on. The legacy-env record states what the
+ *  run actually OPENED (`legacyBound`, the resolved targets that were bound)
+ *  separately from what plan time REFUSED (`legacyRefused`) — recording a
+ *  refused entry as the run's allow would attribute authority the run never
+ *  had, and the durable record must agree with the launch banner. */
+export declare function auditSandboxUse(projectRoot: string, sessionId: string, used: ResolvedGrants, legacyBound: string[], legacyRefused: string[], netMode: 'shared' | 'off'): void;
+//# sourceMappingURL=sandbox-grants.d.ts.map

package/dist/policies/sandbox-grants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-grants.d.ts","sourceRoot":"","sources":["../../src/policies/sandbox-grants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAQH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD;;;;;+DAK+D;AAC/D,eAAO,MAAM,eAAe,QAAS,CAAC;AACtC,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,qDAAqD;AACrD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,8CAA8C;AAC9C,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;+DAC+D;AAC/D,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAC7C,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,SAAU,CAAC;AAC1C,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAI5D;AAeD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAY1D;AAyMD;;;;;qCAKqC;AACrC,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,YAAY,EAAE,GAAG,YAAY,CAGhG;AAmCD,8DAA8D;AAC9D,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAiHvI;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE,CAIrF;AAED;;iEAEiE;AACjE,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CA+B7E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,cAAc,CA+B3F;AAED;;;;;;;qEAOqE;AACrE,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,cAAc,EACpB,WAAW,EAAE,MAAM,EAAE,EACrB,aAAa,EAAE,MAAM,EAAE,EACvB,OAAO,EAAE,QAAQ,GAAG,KAAK,GACxB,IAAI,CAeN"}