@cotal-ai/auth 0.0.0 → 0.11.0

package/dist/ledger.js

@@ -0,0 +1,399 @@
+/**
+ * The local ACTOR LEDGER — the server-side authority over which (owner, actor) pairs may run agents
+ * in this space, and with what capability scope + channel ACL (plan gate 4: "define the local actor
+ * ledger + channel ACL resolver used by both the IdP bridge and callout permission supplier").
+ *
+ * This is THE single authorization source on the user-auth path — both trust boundaries read it:
+ *  - the IdP bridge's `authorizeActor` (Plane 1, bearer MINT time): is this actor granted, and what
+ *    `scope`/`parent` does its bearer carry;
+ *  - the callout's `authorizeActor` + `AclResolver` (Plane 2, CONNECT time): is the actor STILL
+ *    granted (a revoked row kills new connects even while an old bearer lives), has its granted scope
+ *    been narrowed since the bearer was minted, and what channel read/post ACL + role gets minted.
+ *
+ * TWO DISJOINT ROW SPACES, split by construction (the gate-1 review convergence): `actors/` holds
+ * INTERACTIVE rows (written by `cotal actor grant`, exchanged via a human IdP proof) and
+ * `managed-actors/` holds MANAGED-AGENT rows (written only by the spawn path, carrying the hash of
+ * the per-agent secret, exchanged only via that secret). The IdP path reads only the interactive
+ * space and the agent path only the managed space, so no corruption, partial write, or misrepair
+ * can reclassify a managed child as human-exchangeable — the fail-open class is unrepresentable,
+ * not detected. Writers refuse a duplicate (owner, actor) across the two spaces; the CONNECT
+ * boundary (which must serve bearers minted by either path) reads both through ONE helper that
+ * fails closed on a duplicate.
+ *
+ * There is NO allow-by-default anywhere: a missing row is a deny, an empty ledger denies everyone.
+ * Rows are keyed (owner, actor); the owner is the opaque derived `u_…` token — the ledger holds no
+ * IdP subject/email (grant-time derivation maps sub → owner; an optional operator label is for
+ * `list` legibility only). Reads are FRESH per call (the delivery-daemon posture): a grant/revoke is
+ * live at the very next exchange/connect with no daemon restart.
+ *
+ * Storage is ONE FILE PER ROW (`<space>/<owner>.<actor>.json`, atomic tmp+rename writes) — the mesh
+ * registry's lost-update posture: concurrent grant/revoke (an operator command racing the manager's
+ * spawn-time grant) never read-modify-write a shared file, and a crash damages at most one row.
+ * UNLIKE the mesh registry, a corrupt row FAILS CLOSED with a thrown sentence — an auth ledger never
+ * skips what it cannot read (a "skipped" row would silently revoke or, in a list, silently hide a
+ * live grant from the operator).
+ */
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { assertDerivedOwnerToken, assertValidChannel, assertValidOwnerToken, mkSecretDir, patternInAllow, writeSecretFile, } from "@cotal-ai/core";
+const ACTORS_DIR = "actors";
+const MANAGED_DIR = "managed-actors";
+const LEDGER_VER = 1;
+function spaceDir(dir, kind) {
+    return join(dir, kind === "interactive" ? ACTORS_DIR : MANAGED_DIR);
+}
+/** The row's filename IS its principal dot-form + `.json` — both segments are grammar-asserted
+ *  (owner `u_` + base32, actor a plain token), so the name is filesystem-safe by construction. */
+function rowPath(dir, kind, owner, actor) {
+    assertDerivedOwnerToken(owner);
+    assertValidOwnerToken(actor);
+    return join(spaceDir(dir, kind), `${owner}.${actor}.json`);
+}
+/** Read + validate one row file against ITS space's shape. FAIL-CLOSED: unreadable/malformed/
+ *  unknown-version/wrong-shape throws a sentence naming the file — never a skip, never a
+ *  reclassification (an interactive row carrying a token hash was written by the wrong path; a
+ *  managed row without a valid one has a corrupted grant — both deny with the repair). */
+function readRow(path, kind) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (e) {
+        throw new Error(`${path}: unreadable actor grant (${e instanceof Error ? e.message : String(e)}) - fix or remove the row; a broken row denies its actor and fails ledger listings`);
+    }
+    if (parsed === null || typeof parsed !== "object" || parsed.ver !== LEDGER_VER)
+        throw new Error(`${path}: unknown actor-grant version ${String(parsed?.ver)} (expected ${LEDGER_VER}) - refusing to guess at an authorization row`);
+    assertDerivedOwnerToken(parsed.owner);
+    assertValidOwnerToken(parsed.actor);
+    if (!Array.isArray(parsed.scope) || !Array.isArray(parsed.allowSubscribe) || !Array.isArray(parsed.allowPublish))
+        throw new Error(`${path}: actor grant is missing explicit scope/allowSubscribe/allowPublish lists`);
+    if (kind === "interactive" && parsed.tokenHash !== undefined)
+        throw new Error(`${path}: an interactive grant must not carry an agent token hash - it was written by the wrong path; remove the row and re-grant (\`cotal actor grant\`)`);
+    if (kind === "managed-agent" && !(typeof parsed.tokenHash === "string" && /^[0-9a-f]{64}$/.test(parsed.tokenHash)))
+        throw new Error(`${path}: managed-agent grant has a missing/corrupted secret hash - respawn the agent (\`cotal spawn\`) to rewrite it`);
+    const { ver: _ver, ...row } = parsed;
+    return row;
+}
+/** Every granted row in BOTH spaces, read fresh, tagged with its kind. Missing dirs = EMPTY ledger
+ *  (deny-all). A row that cannot be read throws (fail closed) rather than being silently omitted
+ *  from an authorization listing. */
+export function loadActorLedger(dir) {
+    const out = [];
+    for (const kind of ["interactive", "managed-agent"]) {
+        const d = spaceDir(dir, kind);
+        if (!existsSync(d))
+            continue;
+        for (const f of readdirSync(d).filter((f) => f.endsWith(".json")).sort())
+            out.push({ ...readRow(join(d, f), kind), kind });
+    }
+    return out;
+}
+/** Find one row in ONE space, reading only that row's file. Undefined = not granted there. A
+ *  corrupt file for THIS principal throws — deny with the reason, not a miss. */
+function findIn(dir, kind, owner, actor) {
+    const p = rowPath(dir, kind, owner, actor);
+    if (!existsSync(p))
+        return undefined;
+    return readRow(p, kind);
+}
+export function findInteractiveActor(dir, owner, actor) {
+    return findIn(dir, "interactive", owner, actor);
+}
+export function findManagedActor(dir, owner, actor) {
+    return findIn(dir, "managed-agent", owner, actor);
+}
+/** The CONNECT boundary's unified read — a bearer minted by EITHER exchange path authorizes here,
+ *  so both spaces are consulted. A (owner, actor) present in BOTH is a broken ledger (the writers
+ *  refuse it; only manual tampering produces it) and DENIES, fail-closed, naming both files. */
+export function findActorUnified(dir, owner, actor) {
+    const interactive = findIn(dir, "interactive", owner, actor);
+    const managed = findIn(dir, "managed-agent", owner, actor);
+    if (interactive && managed)
+        throw new Error(`actor "${actor}" is granted in BOTH the interactive and managed row spaces - a broken ledger denies; remove one of ${rowPath(dir, "interactive", owner, actor)} / ${rowPath(dir, "managed-agent", owner, actor)}`);
+    if (interactive)
+        return { ...interactive, kind: "interactive" };
+    if (managed)
+        return { ...managed, kind: "managed-agent" };
+    return undefined;
+}
+function writeRow(dir, kind, row) {
+    const path = rowPath(dir, kind, row.owner, row.actor);
+    mkSecretDir(dir);
+    mkSecretDir(spaceDir(dir, kind));
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeSecretFile(tmp, JSON.stringify({ ver: LEDGER_VER, ...row }, null, 2));
+    renameSync(tmp, path);
+}
+function assertRowInputs(row) {
+    if (row.parent !== undefined) {
+        const parts = row.parent.split(".");
+        if (parts.length !== 2)
+            throw new Error(`grantActor: parent "${row.parent}" is not a principal (<owner>.<actor>)`);
+        assertDerivedOwnerToken(parts[0]);
+        assertValidOwnerToken(parts[1]);
+    }
+    if (!Array.isArray(row.scope) || !Array.isArray(row.allowSubscribe) || !Array.isArray(row.allowPublish))
+        throw new Error("grantActor: explicit scope/allowSubscribe/allowPublish lists are required");
+    // Policy-grammar validation at the WRITE boundary (mirroring the mint chokepoint's re-assert in
+    // core `permissionsFor`): a row's ACL lists are the delegation envelope for everything under it,
+    // so a malformed entry (`a.>.b`) must never be stored where containment would later read it.
+    for (const ch of [...row.allowSubscribe, ...row.allowPublish])
+        assertValidChannel(ch);
+    // Scope entries are capability TOKENS (compared by equality, embedded in bearers and repair
+    // commands) — an open vocabulary (`spawn`, `admin`, `role:<r>`, …), but a closed grammar: no
+    // whitespace, no shell/subject metacharacters, nothing `--scope` CSV can't round-trip.
+    for (const s of row.scope)
+        if (!/^[A-Za-z0-9_:-]+$/.test(s))
+            throw new Error(`grantActor: scope entry "${s}" must be a plain capability token ([A-Za-z0-9_:-])`);
+    // The role is embedded in `role:<r>` capability tokens and `svc_<role>` durable names — same
+    // closed grammar, validated where it enters the ledger.
+    if (row.role !== undefined && !/^[A-Za-z0-9_-]+$/.test(row.role))
+        throw new Error(`grantActor: role "${row.role}" must be a plain token ([A-Za-z0-9_-])`);
+}
+/** Grant (or update — an upsert, so re-granting narrows/widens in place) an INTERACTIVE (owner,
+ *  actor) row. Refuses a token hash (that's the managed space's shape, written only by the spawn
+ *  path) and refuses to shadow an existing managed-agent row — the two spaces stay disjoint at the
+ *  write, so the read sides never disambiguate.
+ *
+ *  NOT attenuated by design: interactive rows are OPERATOR-authored (the local `cotal actor grant`
+ *  CLI is the only writer), and the operator is the authority the envelope rule bottoms out in. An
+ *  optional `parent` here is an audit link only — do not build a delegated-USER write path on this
+ *  function; user-authored delegation belongs in the managed space, where the chain walk enforces
+ *  the envelope (an interactive row that carries a parent still gets link-checked when a managed
+ *  chain passes THROUGH it). */
+export function grantActor(dir, row) {
+    assertRowInputs(row);
+    if (row.tokenHash !== undefined)
+        throw new Error("grantActor: an interactive grant cannot carry an agent token hash - managed-agent rows are written by the spawn path only");
+    const managedRefusal = () => new Error(`actor "${row.actor}" is a managed agent - its grant is owned by the spawn lifecycle (respawn rewrites it, despawn revokes it); pick another actor name for an interactive grant`);
+    if (findIn(dir, "managed-agent", row.owner, row.actor))
+        throw managedRefusal();
+    const full = { ...row, grantedAt: new Date().toISOString() };
+    writeRow(dir, "interactive", full);
+    // Post-write compensation for the check-then-write race (an operator grant racing a spawn for
+    // the same name): if the OTHER space's row appeared meanwhile, remove the just-written row and
+    // refuse — at most one row survives, without a cross-process lock protocol. The unified connect
+    // read's duplicate deny stays the backstop for a crash landing exactly between these two lines.
+    if (findIn(dir, "managed-agent", row.owner, row.actor)) {
+        revokeIn(dir, "interactive", row.owner, row.actor);
+        throw managedRefusal();
+    }
+    return full;
+}
+/** Delegation attenuation — the ENVELOPE rule: everything under an owner stays within the
+ *  spawner's own grant. A spawn-scoped actor can delegate only a SUBSET of what it holds — channel
+ *  ACLs by NATS-pattern containment ({@link patternInAllow}), capability scope by set inclusion —
+ *  never more; a spawner whose row carries `admin` is the operator authority and is exempt, and a
+ *  row with NO parent is an operator/roster boot (the operator is the authority). Enforced at BOTH
+ *  managed-row boundaries: authorship ({@link grantManagedActor}) and every agent bearer exchange
+ *  ({@link ledgerAuthorizeAgentExchange}) — so narrowing or revoking a spawner bites its agents at
+ *  their next refresh (≤ {@link AGENT_BEARER_TTL_SEC}s), instead of leaving them orphaned. */
+function assertWithinSpawnerGrant(dir, row, boundary) {
+    // Walk the WHOLE delegation chain, not just the immediate link: per-link containment composes
+    // transitively (child ⊆ parent at every hop ⇒ leaf ⊆ root), and every link must still EXIST — a
+    // single-hop check would let grandchildren outlive a revoked root (their immediate parent row
+    // survives the root's deletion) and let a revoked root's still-live child keep minting. The walk
+    // stops at an authority root: an admin-scoped ancestor or a parentless (operator/roster) row.
+    // `seen` is the cycle guard — legitimate upserts can close a parent loop (re-parent a root under
+    // its own descendant), which must deny, not spin.
+    const leaf = row.actor;
+    let child = row;
+    const seen = new Set([`${row.owner}.${row.actor}`]);
+    while (child.parent) {
+        const parentKey = child.parent;
+        const childKey = `${child.owner}.${child.actor}`;
+        const deep = child !== row;
+        if (seen.has(parentKey))
+            throw new Error(`agent "${leaf}": its delegation chain contains a cycle at "${parentKey}" - a broken ledger denies; repair the parent links (\`cotal actor list\`)`);
+        seen.add(parentKey);
+        const dot = parentKey.indexOf(".");
+        const pOwner = parentKey.slice(0, dot);
+        const pActor = parentKey.slice(dot + 1);
+        const parent = findActorUnified(dir, pOwner, pActor);
+        if (!parent)
+            throw new Error(boundary === "spawn"
+                ? `spawner "${parentKey}"${deep ? ` (an ancestor of "${leaf}")` : ""} has no grant in this space - delegation flows from a granted spawner chain; grant it first (\`cotal actor grant ${pActor} --owner ${pOwner} --scope spawn\`)`
+                : `agent "${leaf}": spawner "${parentKey}"${deep ? ` (an ancestor)` : ""} is no longer granted - revoking a spawner revokes everything under it; re-grant it, then respawn (\`cotal spawn\`)`);
+        if (parent.scope.includes("admin"))
+            return;
+        if (child.owner !== pOwner)
+            throw new Error(`agent "${childKey}" cannot be delegated by spawner "${parentKey}" of a different owner - cross-owner spawns are operator (admin) launches only`);
+        const overScope = child.scope.filter((s) => !parent.scope.includes(s));
+        const overSub = child.allowSubscribe.filter((ch) => !patternInAllow(parent.allowSubscribe, ch));
+        const overPub = child.allowPublish.filter((ch) => !patternInAllow(parent.allowPublish, ch));
+        // A role is RECEIVE reach (bind/consume the shared `svc_<role>` task queue), so it is a
+        // delegated capability like any other: the spawner's scope must carry `role:<r>` to hand it
+        // down. Rides the scope list — no extra row field, and scope's own per-link inclusion makes
+        // role delegation transitive for free.
+        const needRole = child.role && !parent.scope.includes(`role:${child.role}`) ? `role:${child.role}` : undefined;
+        if (overScope.length || overSub.length || overPub.length || needRole) {
+            const wrongs = [
+                overScope.length ? `scope [${overScope.join(", ")}] beyond [${parent.scope.join(", ") || "none"}]` : "",
+                overSub.length ? `read [${overSub.join(", ")}] beyond [${parent.allowSubscribe.join(", ") || "none"}]` : "",
+                overPub.length ? `post [${overPub.join(", ")}] beyond [${parent.allowPublish.join(", ") || "none"}]` : "",
+                needRole ? `role "${child.role}" beyond scope [${parent.scope.join(", ") || "none"}] (a role is delegated with the \`${needRole}\` capability)` : "",
+            ].filter(Boolean);
+            const widen = widenGrantCommand(pOwner, pActor, parent, [...overScope, ...(needRole ? [needRole] : [])], overSub, overPub);
+            const who = deep ? `agent "${leaf}": its ancestor "${childKey}"` : `agent "${leaf}"`;
+            throw new Error((boundary === "spawn"
+                ? `${who} would exceed its spawner's grant - delegation only narrows: `
+                : `${who} exceeds its spawner's CURRENT grant (narrowed since spawn): `) +
+                wrongs.join("; ") +
+                ` - the mesh operator widens the spawner with \`${widen}\`` +
+                (boundary === "spawn" ? ", then respawn" : ", or respawn within it"));
+        }
+        child = parent;
+    }
+}
+/** The exact re-grant that would admit the refused delegation: the spawner's CURRENT row with the
+ *  missing entries unioned in. A grant is an upsert of the WHOLE row, so the repair must carry
+ *  every field — a bare `--allow-subscribe` would silently narrow the rest. */
+function widenGrantCommand(pOwner, pActor, parent, addScope, addSub, addPub) {
+    const union = (base, add) => [...new Set([...base, ...add])];
+    // The command is offered for copy-paste into a shell, so every free-form field is POSIX
+    // single-quote escaped — a row label like `x'; rm -rf ~` must never become a live command.
+    const shq = (s) => `'${s.replaceAll("'", `'\\''`)}'`;
+    const parts = [`cotal actor grant ${pActor} --owner ${pOwner}`];
+    const scope = union(parent.scope, addScope);
+    if (scope.length)
+        parts.push(`--scope ${shq(scope.join(","))}`);
+    parts.push(`--allow-subscribe ${shq(union(parent.allowSubscribe, addSub).join(","))}`);
+    parts.push(`--allow-publish ${shq(union(parent.allowPublish, addPub).join(","))}`);
+    if (parent.role)
+        parts.push(`--role ${shq(parent.role)}`);
+    if (parent.label)
+        parts.push(`--label ${shq(parent.label)}`);
+    return parts.join(" ");
+}
+/** Author a MANAGED-AGENT row (spawn path only): the same upsert semantics, in the managed space,
+ *  with the secret hash REQUIRED — and never shadowing an interactive row. */
+export function grantManagedActor(dir, row) {
+    assertRowInputs(row);
+    if (!/^[0-9a-f]{64}$/.test(row.tokenHash))
+        throw new Error("grantManagedActor: tokenHash must be a sha256 hex digest");
+    assertWithinSpawnerGrant(dir, row, "spawn");
+    const shadowRefusal = () => new Error(`actor "${row.actor}" already has an interactive grant - a managed agent cannot shadow it; revoke it first (\`cotal actor revoke ${row.actor}\`) or spawn under another name`);
+    if (findIn(dir, "interactive", row.owner, row.actor))
+        throw shadowRefusal();
+    const full = { ...row, grantedAt: new Date().toISOString() };
+    writeRow(dir, "managed-agent", full);
+    // Symmetric post-write compensation (see grantActor) — at most one surviving row per principal.
+    if (findIn(dir, "interactive", row.owner, row.actor)) {
+        revokeIn(dir, "managed-agent", row.owner, row.actor);
+        throw shadowRefusal();
+    }
+    return full;
+}
+/** Revoke a row in one space. Returns false when there was nothing to revoke. NOTE: this stops NEW
+ *  bearer mints and NEW connects immediately (both boundaries read fresh); an ALREADY-LIVE
+ *  connection dies at its bearer-bound JWT expiry — live eviction is the D5 lever, not the ledger's. */
+export function revokeActor(dir, owner, actor) {
+    return revokeIn(dir, "interactive", owner, actor);
+}
+export function revokeManagedActor(dir, owner, actor) {
+    return revokeIn(dir, "managed-agent", owner, actor);
+}
+function revokeIn(dir, kind, owner, actor) {
+    const p = rowPath(dir, kind, owner, actor);
+    if (!existsSync(p))
+        return false;
+    rmSync(p);
+    return true;
+}
+/** The IdP bridge's `authorizeActor` hook (bearer-MINT boundary) — INTERACTIVE rows only, by
+ *  construction. A name that exists only as a managed agent gets the exact managed-path answer
+ *  (never "not granted", which would read as a permissions problem, and never a mint). */
+export function ledgerAuthorizeGrant(dir) {
+    return (owner, actor) => {
+        const row = findInteractiveActor(dir, owner, actor);
+        if (!row) {
+            if (findManagedActor(dir, owner, actor))
+                throw new Error(`actor "${actor}" is a managed agent - it authenticates with its own spawn-time secret; interact with it via the mesh, or respawn it with \`cotal spawn\``);
+            throw new Error(`actor "${actor}" is not granted for this user - the mesh operator lets them in with \`cotal actor grant ${actor} --owner ${owner}\` (or --sub <their IdP subject>, printed by their \`cotal login\`)`);
+        }
+        return { scope: row.scope, ...(row.parent ? { parent: row.parent } : {}) };
+    };
+}
+/** The callout's `authorizeActor` hook (CONNECT boundary): the row must still exist — in EITHER
+ *  space (bearers from both exchange paths connect here) — and the bearer's `act.scope` must sit
+ *  within the row's CURRENT scope — a bearer minted before a scope narrowing is refused at
+ *  connect, not honored until expiry. */
+export function ledgerAuthorizeConnect(dir) {
+    return (t) => {
+        const row = findActorUnified(dir, t.owner, t.act.actor);
+        if (!row)
+            throw new Error(`actor "${t.act.actor}" is not (or no longer) granted for this owner`);
+        const granted = new Set(row.scope);
+        for (const s of t.act.scope ?? [])
+            if (!granted.has(s))
+                throw new Error(`bearer scope "${s}" exceeds the actor's current grant - re-login to mint a fresh bearer`);
+    };
+}
+/** The channel-ACL resolver over this ledger — the ONE resolver both the callout permission
+ *  supplier uses today and the IdP bridge shares when it needs channel authority (gate 4's "shared
+ *  by both"). Serves bearers from both spaces (unified read). A missing row throws (the callout
+ *  turns it into a signed deny). */
+export function ledgerAclResolver(dir) {
+    return (t) => {
+        const row = findActorUnified(dir, t.owner, t.act.actor);
+        if (!row)
+            throw new Error(`actor "${t.act.actor}" has no ledger row - no channel ACL to mint`);
+        return { allowSubscribe: row.allowSubscribe, allowPublish: row.allowPublish, ...(row.role ? { role: row.role } : {}) };
+    };
+}
+/** Ensure a filename-hostile owner/actor can never traverse (defense-in-depth behind the grammar
+ *  asserts in {@link rowPath}) — exported for the smoke that pins the property. */
+export function ledgerRowFilename(owner, actor) {
+    assertDerivedOwnerToken(owner);
+    assertValidOwnerToken(actor);
+    return `${owner}.${actor}.json`;
+}
+/** Where the per-row files live under a provider state dir (for tooling/tests). */
+export function actorLedgerDir(dir) {
+    return spaceDir(dir, "interactive");
+}
+/** The managed-agent row space (for tooling/tests). */
+export function managedActorLedgerDir(dir) {
+    return spaceDir(dir, "managed-agent");
+}
+/** Agent bearers are SHORT by design — a spawned agent's endpoint re-exchanges ahead of every
+ *  expiry, so revocation (row deletion) bites a live connection within this window even before
+ *  live eviction lands. There is no upstream IdP proof to cap to; this constant is that cap. */
+export const AGENT_BEARER_TTL_SEC = 300;
+/** Generate a fresh per-agent exchange secret (returned to the spawner ONCE) + its ledger hash. */
+export function newActorToken() {
+    const actorToken = randomBytes(32).toString("base64url");
+    return { actorToken, tokenHash: hashActorToken(actorToken) };
+}
+export function hashActorToken(actorToken) {
+    return createHash("sha256").update(actorToken, "utf8").digest("hex");
+}
+/** Authorize one AGENT exchange (`{ owner, actor, actorToken }`, no IdP proof) — MANAGED rows only,
+ *  by construction. The presented secret must hash to the row's (constant-time over the two fixed
+ *  32-byte digests). Every failure is the SAME sentence — a prober must not learn whether an
+ *  (owner, actor) row exists, lives in the other space, or got the secret wrong (the sentence
+ *  still names the operator's likely fix: respawn). */
+export function ledgerAuthorizeAgentExchange(dir, owner, actor, actorToken) {
+    const deny = () => new Error("agent exchange refused: unknown agent or wrong secret - if this agent should exist, respawn it (`cotal spawn`) to rotate its grant");
+    let row;
+    try {
+        row = findManagedActor(dir, owner, actor);
+    }
+    catch {
+        throw deny(); // a corrupt row denies exactly like a missing one on this unauthenticated surface
+    }
+    if (!row?.tokenHash)
+        throw deny();
+    const presented = Buffer.from(hashActorToken(actorToken), "hex");
+    const stored = Buffer.from(row.tokenHash, "hex");
+    if (presented.length !== stored.length || !timingSafeEqual(presented, stored))
+        throw deny();
+    // Post-authentication (the secret matched), so a SPECIFIC refusal is safe on this surface — and
+    // required: rechecking the envelope here makes it a STANDING invariant (an operator narrowing or
+    // revoking the spawner bites its agents at their next ≤ AGENT_BEARER_TTL_SEC refresh), the same
+    // posture as the connect boundary's "bearer scope vs CURRENT row" check.
+    assertWithinSpawnerGrant(dir, row, "exchange");
+    return { scope: row.scope, ...(row.parent ? { parent: row.parent } : {}) };
+}
+//# sourceMappingURL=ledger.js.map

package/dist/ledger.js.map

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

package/dist/login.d.ts

@@ -0,0 +1,69 @@
+/** A cached IdP login. `token` is the IdP session bearer (Better Auth: `session.token`) — an
+ *  opaque revocable handle, never a JWT. `expiresAt` (unix seconds) is advisory for messages;
+ *  the server is the authority (a revoked session dies earlier). */
+export interface IdpSession {
+    token: string;
+    expiresAt: number;
+    /** The IdP subject this session proved at login (display + local owner derivation). Absent only
+     *  in caches written by older builds — consumers that need it fail loud naming `cotal login`. */
+    sub?: string;
+}
+/** What the human must be shown to approve the sign-in. */
+export interface DeviceLoginPrompt {
+    verificationUri: string;
+    verificationUriComplete: string;
+    userCode: string;
+    expiresInSec: number;
+}
+export interface DeviceLoginOpts {
+    /** The IdP auth base URL (Better Auth: `<origin>/api/auth`). */
+    idpUrl: string;
+    /** The OAuth client id this CLI presents; the IdP may pin it via its validateClient hook. */
+    clientId: string;
+    /** Shows the human the verification URL + code. Called exactly once, before polling starts. */
+    onPrompt: (prompt: DeviceLoginPrompt) => void;
+}
+/** Normalize + guard the IdP base URL: https (or loopback http for dev), no query/hash, no
+ *  trailing slash — the normalized string is also the session-cache key, so `…/api/auth` and
+ *  `…/api/auth/` must land on the same entry. */
+export declare function normalizeIdpUrl(idpUrl: string): string;
+/** Best-effort reachability + shape check of an IdP's JWKS. Used at the FIRST `--user-auth` enable
+ *  so a dead or typo'd `--idp` fails loud BEFORE a space is provisioned around it, instead of only
+ *  surfacing far away at the first user connect (the pin is written but the JWKS is fetched lazily).
+ *  Normalizes the URL exactly as the pin does (`<base>/jwks`). Throws a legible sentence on an
+ *  unreachable host, a non-2xx, or a body that is not a JWKS key set. */
+export declare function probeIdpJwks(idpUrl: string): Promise<void>;
+/** Sign in via the RFC 8628 device flow and return the IdP session. Fail-loud on every non-happy
+ *  path: a deny, an expiry, or an unknown poll error is a thrown human sentence, never a retry
+ *  loop. Blocks (polling at the server's stated interval) until the human approves. */
+export declare function deviceLogin(opts: DeviceLoginOpts): Promise<IdpSession>;
+/** Fetch a fresh short-lived IdP user JWT for the cached session — the input to the bridge
+ *  exchange. A 401 means the session was revoked or expired at the IdP: the error says exactly
+ *  how to recover. The JWT is returned, never stored. */
+export declare function fetchIdpJwt(idpUrl: string, sessionToken: string): Promise<string>;
+/** The whole login operation, in the only safe order: device sign-in, then PROVE the session
+ *  mints a user JWT, and only then persist it. A session that can't produce a JWT must never
+ *  land on disk — it would pass {@link requireIdpSession}'s no-fallback gate as a dud and defer
+ *  the failure to some later connect. Returns the session plus the JWT's `sub`, and a human
+ *  `label` (email/name/preferred_username when the IdP mints one) — BOTH display-only: the
+ *  operator must be able to read WHICH human signed in, but verification is the bridge/callout's
+ *  job, server-side. */
+export declare function establishIdpSession(opts: DeviceLoginOpts & {
+    dir: string;
+}): Promise<{
+    session: IdpSession;
+    sub: string;
+    label?: string;
+}>;
+/** Revoke the session server-side (sign out). A 401 back means the session is already dead —
+ *  the goal state, treated as success; any other failure is thrown because a still-live
+ *  server-side session is a real leak the operator must hear about. */
+export declare function revokeIdpSession(idpUrl: string, sessionToken: string): Promise<void>;
+export declare function loadIdpSession(dir: string, idpUrl: string): IdpSession | undefined;
+export declare function saveIdpSession(dir: string, idpUrl: string, session: IdpSession): void;
+/** Remove the cached session. Returns false when there was nothing to remove. */
+export declare function deleteIdpSession(dir: string, idpUrl: string): boolean;
+/** The no-fallback gate the user-mode connect path consumes: a session or a thrown sentence that
+ *  says exactly how to get one. There is no anonymous degradation when a space requires a user. */
+export declare function requireIdpSession(dir: string, idpUrl: string): IdpSession;
+//# sourceMappingURL=login.d.ts.map

package/dist/login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../src/login.ts"],"names":[],"mappings":"AAkCA;;oEAEoE;AACpE,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB;qGACiG;IACjG,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,2DAA2D;AAC3D,MAAM,WAAW,iBAAiB;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,uBAAuB,EAAE,MAAM,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,6FAA6F;IAC7F,QAAQ,EAAE,MAAM,CAAC;IACjB,+FAA+F;IAC/F,QAAQ,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC/C;AAED;;iDAEiD;AACjD,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAsBtD;AAqDD;;;;yEAIyE;AACzE,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQhE;AAcD;;uFAEuF;AACvF,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAwF5E;AAED;;yDAEyD;AACzD,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAWvF;AAED;;;;;;wBAMwB;AACxB,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,eAAe,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GACtC,OAAO,CAAC;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAoB/D;AAED;;uEAEuE;AACvE,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS1F;AAmCD,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAUlF;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI,CASrF;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAQrE;AAED;mGACmG;AACnG,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAQzE"}