@skrr-ai/cli 0.1.109 → 0.1.111

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/toolApprovalSignature.d.ts

@@ -0,0 +1,232 @@
+import { type KeyObject } from 'node:crypto';
+import { type AttestedToolApprovalRefusalReason } from './daemonToolApproval.js';
+/**
+ * Platform-signed tool approvals (OSK-16614) — attestation v2.
+ *
+ * v1 (`daemonToolApproval.ts`) is a plain JSON object whose authority is the
+ * channel it arrived on. That stops the MODEL approving itself, and nothing
+ * else: anything that can put a `daemon:tool:request` on the daemon's channel
+ * — a websocket or SSE layer bug, a relay, the Redis pub/sub bridge the
+ * request crosses, an injected event, a peer holding a stolen daemon session
+ * — can approve any `manual`-category call by writing the field.
+ *
+ * v2 is `{v: 2, payload, kid, sig}`: an Ed25519 signature by a platform
+ * approval key over the canonical JSON `payload`, which carries the v1 claims
+ * plus the `daemonId` and `sessionId` it was minted for. The daemon verifies
+ * it against a keyset it PINNED outside the approval decision (fetched over
+ * authenticated HTTPS, TOFU, per server origin) and that only changes through
+ * a keyset signed by a key it already trusts.
+ *
+ * What it stops: every writer to the channel that cannot reach the signing
+ * key. What it does NOT stop: a fully compromised API host with access to the
+ * key, or server code that mints without a person having answered — the key
+ * says "the platform says a person approved this call", not that one did.
+ * Only an approval signed by the approving person's own device closes that,
+ * and that is the long-term target this format is shaped for (a second key
+ * class in the same keyset), not something it claims today.
+ *
+ * Pure: node:crypto only, no schema library (auth-core is schema-free), no
+ * I/O. Where the keyset is stored and how it is fetched is the daemon's
+ * (`daemon/src/permissions/approval-keyset.ts`); where the private key lives
+ * is the server's (`api/server/utils/toolApprovalSigning.js`).
+ */
+/**
+ * Announced by a daemon that holds a pinned approval keyset and therefore
+ * verifies v2. The daemon announces it ONLY while pinned — positive
+ * withholding on its side too — and the server mints v2 only for a daemon
+ * that announced it, v1 otherwise.
+ */
+export declare const TOOL_APPROVAL_SIGNED_CAPABILITY = "tool_approval_signed_v1";
+/**
+ * One public approval key. Same encoding as the release keys
+ * (`releaseKeys.ts`): base64 DER-SPKI Ed25519.
+ */
+export interface ApprovalPublicKey {
+    kid: string;
+    publicKeySpkiB64: string;
+}
+export interface ApprovalSigner {
+    kid: string;
+    privateKey: KeyObject;
+}
+/** Derive the wire public key from a private (or public) Ed25519 KeyObject. */
+export declare function approvalPublicKeyFromKeyObject(kid: string, key: KeyObject): ApprovalPublicKey;
+/**
+ * The set of approval keys a daemon trusts for one server origin. `seq` only
+ * ever rises: a daemon refuses a keyset older than the one it pinned, so a
+ * retired (possibly compromised) key cannot be brought back by replaying the
+ * keyset that still listed it.
+ */
+export interface ApprovalKeyset {
+    v: 1;
+    seq: number;
+    keys: ApprovalPublicKey[];
+}
+/**
+ * What the server serves and the daemon pins. `keyset` is the canonical JSON
+ * TEXT of an `ApprovalKeyset`: signatures are over these exact bytes, so the
+ * verifier never has to re-serialize to check one. Each signature names the
+ * key that made it; a keyset is normally signed by every key it lists (that is
+ * what lets a daemon pinning only the old key accept the set that adds the new
+ * one), plus any offline root endorsements.
+ */
+export interface ApprovalKeysetDocument {
+    keyset: string;
+    signatures: Array<{
+        kid: string;
+        sig: string;
+    }>;
+}
+/** Canonical keyset text: keys sorted by kid, canonical JSON. */
+export declare function canonicalApprovalKeysetText(keyset: ApprovalKeyset): string;
+/**
+ * Server side: the document for a keyring. Every signer signs, and every
+ * signer's public key is listed. `endorsements` are signatures made OFFLINE
+ * over the same canonical text by a root key the daemon may have embedded
+ * (see `verifyApprovalKeysetDocument`'s `anchors`); the text is deterministic
+ * — no timestamp — precisely so an endorsement can be made ahead of time.
+ */
+export declare function buildApprovalKeysetDocument(args: {
+    seq: number;
+    signers: ApprovalSigner[];
+    endorsements?: Array<{
+        kid: string;
+        sig: string;
+    }>;
+}): ApprovalKeysetDocument;
+/** Sign keyset text with one key — for an offline root endorsement. */
+export declare function endorseApprovalKeysetText(keysetText: string, signer: ApprovalSigner): {
+    kid: string;
+    sig: string;
+};
+/** Parse and validate keyset text. Null when it is not a well-formed keyset. */
+export declare function parseApprovalKeysetText(text: unknown): ApprovalKeyset | null;
+/**
+ * Why a keyset document was not adopted. Internal-only (daemon log and the
+ * `skrrd status` approvals line's last-refresh note), never a person's action
+ * except through the runbook in daemon/CLAUDE.md:
+ *  - `malformed` — not a keyset document
+ *  - `untrusted` — no valid signature by a key the daemon already trusts (a
+ *                  pinned key or an embedded root), or, for a first pin with no
+ *                  anchor, not even self-signed
+ *  - `rollback`  — `seq` is lower than the pinned keyset's
+ *  - `conflict`  — same `seq` as the pinned keyset with different keys
+ */
+export type ApprovalKeysetRefusalReason = 'malformed' | 'untrusted' | 'rollback' | 'conflict';
+export type ApprovalKeysetVerdict = {
+    ok: true;
+    keyset: ApprovalKeyset;
+    /** The canonical text to pin. */
+    text: string;
+    /** `first_pin` (TOFU or root-anchored), `rotated`, or `unchanged`. */
+    change: 'first_pin' | 'rotated' | 'unchanged';
+} | {
+    ok: false;
+    reason: ApprovalKeysetRefusalReason;
+};
+/**
+ * Daemon side: decide whether to adopt a keyset document.
+ *
+ *  - Pinned: at least one signature must verify under a key in the PINNED set
+ *    (or an anchor). The new set may drop or add keys — that is rotation — but
+ *    its `seq` may not fall, and the same `seq` must be the same set.
+ *  - Not pinned, anchors given (an embedded root for this server origin): at
+ *    least one signature must verify under an anchor. No TOFU.
+ *  - Not pinned, no anchors: trust on first use. The document must still be
+ *    signed by a key it lists (proof that whoever served it holds one), but
+ *    its authority is the authenticated HTTPS fetch it came from.
+ *
+ * A signature is checked against the TRUSTED copy of a key, looked up by kid —
+ * never against the key the new document lists under that kid, or a document
+ * could swap a key's bytes while keeping its name.
+ */
+export declare function verifyApprovalKeysetDocument(doc: unknown, trust: {
+    pinned: ApprovalKeyset | null;
+    anchors?: readonly ApprovalPublicKey[];
+}): ApprovalKeysetVerdict;
+export interface SignedToolApprovalPayload {
+    v: 2;
+    toolUseId: string;
+    toolName: string;
+    /** SHA-256 of the canonical tool input (`canonicalToolInputDigest`). */
+    inputSha256: string;
+    decidedBy: 'user';
+    /** The daemon this approval was minted for — another daemon refuses it. */
+    daemonId: string;
+    /** The agent session the call belongs to. */
+    sessionId: string;
+    issuedAt: number;
+    expiresAt: number;
+}
+export interface SignedToolApproval {
+    v: 2;
+    /** Canonical JSON text of a `SignedToolApprovalPayload` — the signed bytes. */
+    payload: string;
+    kid: string;
+    /** base64 Ed25519 signature over the domain prefix + `payload`. */
+    sig: string;
+}
+/** Server side: mint and sign a v2 attestation after a person approved THIS call. */
+export declare function signToolApproval(args: {
+    toolUseId: string;
+    toolName: string;
+    toolInput: unknown;
+    daemonId: string;
+    sessionId: string;
+    signer: ApprovalSigner;
+    now?: number;
+    ttlMs?: number;
+}): SignedToolApproval;
+export interface SignedToolApprovalCall {
+    toolUseId: string;
+    toolName: string;
+    toolInput: unknown;
+    /** The verifying daemon's own id. */
+    daemonId: string;
+    /** The session the request says it belongs to. */
+    sessionId: string;
+    now?: number;
+}
+export type SignedToolApprovalVerdict = {
+    ok: true;
+    toolUseId: string;
+    expiresAt: number;
+} | {
+    ok: false;
+    reason: AttestedToolApprovalRefusalReason;
+};
+/**
+ * Daemon side: verify a v2 attestation against the pinned keyset and the call.
+ * Order matters: nothing in the payload is READ until the signature verified
+ * under a pinned key, so an unsigned claim can never pick which check runs.
+ */
+export declare function verifySignedToolApproval(approval: unknown, call: SignedToolApprovalCall, keyset: ApprovalKeyset): SignedToolApprovalVerdict;
+/**
+ * Where the verifying daemon stands with the platform's approval keyset.
+ * `unreadable` is its own state, not `unpinned`: a pin file that exists and
+ * cannot be read must not quietly re-open the unsigned path.
+ */
+export type ApprovalKeysetPinState = {
+    state: 'pinned';
+    keyset: ApprovalKeyset;
+} | {
+    state: 'unpinned';
+} | {
+    state: 'unreadable';
+};
+/**
+ * Daemon side: THE decision for any attestation, whatever version arrived.
+ *
+ *  - pinned     → only v2 verified against the pinned keyset approves; v1 is
+ *                 refused as `unsigned` (downgrade protection).
+ *  - unpinned   → legacy: v1 is verified exactly as before; v2 is refused as
+ *                 `unpinned` (nothing here could check it — the server should
+ *                 not have sent it, since this daemon did not announce
+ *                 `tool_approval_signed_v1`).
+ *  - unreadable → nothing approves.
+ *
+ * Returns the claims the spend-once ledger keys on when it approves.
+ */
+export declare function verifyToolApprovalAttestation(approval: unknown, call: SignedToolApprovalCall, pin: ApprovalKeysetPinState): SignedToolApprovalVerdict & {
+    signed?: boolean;
+};

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/toolApprovalSignature.js

@@ -0,0 +1,372 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOL_APPROVAL_SIGNED_CAPABILITY = void 0;
+exports.approvalPublicKeyFromKeyObject = approvalPublicKeyFromKeyObject;
+exports.canonicalApprovalKeysetText = canonicalApprovalKeysetText;
+exports.buildApprovalKeysetDocument = buildApprovalKeysetDocument;
+exports.endorseApprovalKeysetText = endorseApprovalKeysetText;
+exports.parseApprovalKeysetText = parseApprovalKeysetText;
+exports.verifyApprovalKeysetDocument = verifyApprovalKeysetDocument;
+exports.signToolApproval = signToolApproval;
+exports.verifySignedToolApproval = verifySignedToolApproval;
+exports.verifyToolApprovalAttestation = verifyToolApprovalAttestation;
+const node_crypto_1 = require("node:crypto");
+const daemonToolApproval_js_1 = require("./daemonToolApproval.js");
+/**
+ * Platform-signed tool approvals (OSK-16614) — attestation v2.
+ *
+ * v1 (`daemonToolApproval.ts`) is a plain JSON object whose authority is the
+ * channel it arrived on. That stops the MODEL approving itself, and nothing
+ * else: anything that can put a `daemon:tool:request` on the daemon's channel
+ * — a websocket or SSE layer bug, a relay, the Redis pub/sub bridge the
+ * request crosses, an injected event, a peer holding a stolen daemon session
+ * — can approve any `manual`-category call by writing the field.
+ *
+ * v2 is `{v: 2, payload, kid, sig}`: an Ed25519 signature by a platform
+ * approval key over the canonical JSON `payload`, which carries the v1 claims
+ * plus the `daemonId` and `sessionId` it was minted for. The daemon verifies
+ * it against a keyset it PINNED outside the approval decision (fetched over
+ * authenticated HTTPS, TOFU, per server origin) and that only changes through
+ * a keyset signed by a key it already trusts.
+ *
+ * What it stops: every writer to the channel that cannot reach the signing
+ * key. What it does NOT stop: a fully compromised API host with access to the
+ * key, or server code that mints without a person having answered — the key
+ * says "the platform says a person approved this call", not that one did.
+ * Only an approval signed by the approving person's own device closes that,
+ * and that is the long-term target this format is shaped for (a second key
+ * class in the same keyset), not something it claims today.
+ *
+ * Pure: node:crypto only, no schema library (auth-core is schema-free), no
+ * I/O. Where the keyset is stored and how it is fetched is the daemon's
+ * (`daemon/src/permissions/approval-keyset.ts`); where the private key lives
+ * is the server's (`api/server/utils/toolApprovalSigning.js`).
+ */
+/**
+ * Announced by a daemon that holds a pinned approval keyset and therefore
+ * verifies v2. The daemon announces it ONLY while pinned — positive
+ * withholding on its side too — and the server mints v2 only for a daemon
+ * that announced it, v1 otherwise.
+ */
+exports.TOOL_APPROVAL_SIGNED_CAPABILITY = 'tool_approval_signed_v1';
+/**
+ * Domain separation: the signed bytes are prefixed, so a signature made for
+ * an attestation can never verify as a keyset or vice versa, whatever JSON
+ * either happens to contain.
+ */
+const ATTESTATION_SIGNING_DOMAIN = 'skrr-tool-approval-v2\n';
+const KEYSET_SIGNING_DOMAIN = 'skrr-tool-approval-keyset-v1\n';
+/** A key id: short, printable, and safe to put in a log line. */
+const KID_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+/** Bounds on untrusted wire input, so a hostile document cannot cost much. */
+const MAX_PAYLOAD_BYTES = 4096;
+const MAX_KEYSET_BYTES = 16 * 1024;
+const MAX_KEYSET_KEYS = 16;
+const MAX_KEYSET_SIGNATURES = 16;
+/** Derive the wire public key from a private (or public) Ed25519 KeyObject. */
+function approvalPublicKeyFromKeyObject(kid, key) {
+    const publicKey = key.type === 'private' ? (0, node_crypto_1.createPublicKey)(key) : key;
+    const der = publicKey.export({ format: 'der', type: 'spki' });
+    return { kid, publicKeySpkiB64: Buffer.from(der).toString('base64') };
+}
+function ed25519PublicKey(publicKeySpkiB64) {
+    try {
+        const key = (0, node_crypto_1.createPublicKey)({
+            key: Buffer.from(publicKeySpkiB64, 'base64'),
+            format: 'der',
+            type: 'spki',
+        });
+        return key.asymmetricKeyType === 'ed25519' ? key : null;
+    }
+    catch {
+        return null;
+    }
+}
+function verifySignature(domain, message, sigB64, key) {
+    try {
+        const sig = Buffer.from(sigB64, 'base64');
+        // An Ed25519 signature is exactly 64 bytes; anything else is not one, and
+        // base64 decoding is lenient enough that the check is worth making.
+        if (sig.length !== 64)
+            return false;
+        return (0, node_crypto_1.verify)(null, Buffer.from(domain + message, 'utf8'), key, sig);
+    }
+    catch {
+        return false;
+    }
+}
+function signMessage(domain, message, privateKey) {
+    return (0, node_crypto_1.sign)(null, Buffer.from(domain + message, 'utf8'), privateKey).toString('base64');
+}
+/** Code-unit order: the same on every runtime, unlike `localeCompare`. */
+function compareKid(a, b) {
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
+}
+/** Canonical keyset text: keys sorted by kid, canonical JSON. */
+function canonicalApprovalKeysetText(keyset) {
+    const keys = [...keyset.keys]
+        .map((k) => ({ kid: k.kid, publicKeySpkiB64: k.publicKeySpkiB64 }))
+        .sort((a, b) => compareKid(a.kid, b.kid));
+    return (0, daemonToolApproval_js_1.canonicalApprovalJson)({ v: 1, seq: keyset.seq, keys });
+}
+/**
+ * Server side: the document for a keyring. Every signer signs, and every
+ * signer's public key is listed. `endorsements` are signatures made OFFLINE
+ * over the same canonical text by a root key the daemon may have embedded
+ * (see `verifyApprovalKeysetDocument`'s `anchors`); the text is deterministic
+ * — no timestamp — precisely so an endorsement can be made ahead of time.
+ */
+function buildApprovalKeysetDocument(args) {
+    const keyset = canonicalApprovalKeysetText({
+        v: 1,
+        seq: args.seq,
+        keys: args.signers.map((s) => approvalPublicKeyFromKeyObject(s.kid, s.privateKey)),
+    });
+    return {
+        keyset,
+        signatures: [
+            ...args.signers.map((s) => ({
+                kid: s.kid,
+                sig: signMessage(KEYSET_SIGNING_DOMAIN, keyset, s.privateKey),
+            })),
+            ...(args.endorsements ?? []),
+        ],
+    };
+}
+/** Sign keyset text with one key — for an offline root endorsement. */
+function endorseApprovalKeysetText(keysetText, signer) {
+    return {
+        kid: signer.kid,
+        sig: signMessage(KEYSET_SIGNING_DOMAIN, keysetText, signer.privateKey),
+    };
+}
+/** Parse and validate keyset text. Null when it is not a well-formed keyset. */
+function parseApprovalKeysetText(text) {
+    if (typeof text !== 'string' || text.length === 0 || text.length > MAX_KEYSET_BYTES) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const p = parsed;
+    if (p.v !== 1 || !Number.isSafeInteger(p.seq) || p.seq < 1)
+        return null;
+    if (!Array.isArray(p.keys) || p.keys.length === 0 || p.keys.length > MAX_KEYSET_KEYS) {
+        return null;
+    }
+    const keys = [];
+    const seen = new Set();
+    for (const entry of p.keys) {
+        if (!entry || typeof entry !== 'object')
+            return null;
+        const { kid, publicKeySpkiB64 } = entry;
+        if (typeof kid !== 'string' || !KID_PATTERN.test(kid) || seen.has(kid))
+            return null;
+        if (typeof publicKeySpkiB64 !== 'string' || !ed25519PublicKey(publicKeySpkiB64))
+            return null;
+        seen.add(kid);
+        keys.push({ kid, publicKeySpkiB64 });
+    }
+    const keyset = { v: 1, seq: p.seq, keys };
+    // One byte representation per keyset: a pinned keyset is compared by its
+    // text, so a non-canonical spelling of the same keys must not read as a
+    // different set (or the same seq would look like a conflict).
+    return canonicalApprovalKeysetText(keyset) === text ? keyset : null;
+}
+/**
+ * Daemon side: decide whether to adopt a keyset document.
+ *
+ *  - Pinned: at least one signature must verify under a key in the PINNED set
+ *    (or an anchor). The new set may drop or add keys — that is rotation — but
+ *    its `seq` may not fall, and the same `seq` must be the same set.
+ *  - Not pinned, anchors given (an embedded root for this server origin): at
+ *    least one signature must verify under an anchor. No TOFU.
+ *  - Not pinned, no anchors: trust on first use. The document must still be
+ *    signed by a key it lists (proof that whoever served it holds one), but
+ *    its authority is the authenticated HTTPS fetch it came from.
+ *
+ * A signature is checked against the TRUSTED copy of a key, looked up by kid —
+ * never against the key the new document lists under that kid, or a document
+ * could swap a key's bytes while keeping its name.
+ */
+function verifyApprovalKeysetDocument(doc, trust) {
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+        return { ok: false, reason: 'malformed' };
+    }
+    const d = doc;
+    const keyset = parseApprovalKeysetText(d.keyset);
+    if (!keyset)
+        return { ok: false, reason: 'malformed' };
+    const text = d.keyset;
+    if (!Array.isArray(d.signatures) ||
+        d.signatures.length === 0 ||
+        d.signatures.length > MAX_KEYSET_SIGNATURES) {
+        return { ok: false, reason: 'malformed' };
+    }
+    // A list, not a map: an anchor and a pinned key that share a kid are both
+    // tried, so neither can shadow the other.
+    let trusted = [
+        ...(trust.anchors ?? []),
+        ...(trust.pinned?.keys ?? []),
+    ];
+    if (trusted.length === 0)
+        trusted = keyset.keys;
+    const signed = d.signatures.some((entry) => {
+        if (!entry || typeof entry !== 'object')
+            return false;
+        const { kid, sig } = entry;
+        if (typeof kid !== 'string' || typeof sig !== 'string')
+            return false;
+        return trusted.some((k) => {
+            if (k.kid !== kid)
+                return false;
+            const key = ed25519PublicKey(k.publicKeySpkiB64);
+            return key ? verifySignature(KEYSET_SIGNING_DOMAIN, text, sig, key) : false;
+        });
+    });
+    if (!signed)
+        return { ok: false, reason: 'untrusted' };
+    if (!trust.pinned)
+        return { ok: true, keyset, text, change: 'first_pin' };
+    if (keyset.seq < trust.pinned.seq)
+        return { ok: false, reason: 'rollback' };
+    if (keyset.seq === trust.pinned.seq) {
+        return canonicalApprovalKeysetText(trust.pinned) === text
+            ? { ok: true, keyset, text, change: 'unchanged' }
+            : { ok: false, reason: 'conflict' };
+    }
+    return { ok: true, keyset, text, change: 'rotated' };
+}
+/** Server side: mint and sign a v2 attestation after a person approved THIS call. */
+function signToolApproval(args) {
+    const now = args.now ?? Date.now();
+    const payload = {
+        v: 2,
+        toolUseId: args.toolUseId,
+        toolName: args.toolName,
+        inputSha256: (0, daemonToolApproval_js_1.canonicalToolInputDigest)(args.toolInput),
+        decidedBy: 'user',
+        daemonId: args.daemonId,
+        sessionId: args.sessionId,
+        issuedAt: now,
+        expiresAt: now + (args.ttlMs ?? daemonToolApproval_js_1.ATTESTED_TOOL_APPROVAL_TTL_MS),
+    };
+    const text = (0, daemonToolApproval_js_1.canonicalApprovalJson)(payload);
+    return {
+        v: 2,
+        payload: text,
+        kid: args.signer.kid,
+        sig: signMessage(ATTESTATION_SIGNING_DOMAIN, text, args.signer.privateKey),
+    };
+}
+/**
+ * Daemon side: verify a v2 attestation against the pinned keyset and the call.
+ * Order matters: nothing in the payload is READ until the signature verified
+ * under a pinned key, so an unsigned claim can never pick which check runs.
+ */
+function verifySignedToolApproval(approval, call, keyset) {
+    if (approval === undefined || approval === null)
+        return { ok: false, reason: 'absent' };
+    if (typeof approval !== 'object' || Array.isArray(approval)) {
+        return { ok: false, reason: 'malformed' };
+    }
+    const a = approval;
+    if (a.v !== 2 ||
+        typeof a.payload !== 'string' ||
+        a.payload.length > MAX_PAYLOAD_BYTES ||
+        typeof a.kid !== 'string' ||
+        typeof a.sig !== 'string') {
+        return { ok: false, reason: 'malformed' };
+    }
+    const pinnedKey = keyset.keys.find((k) => k.kid === a.kid);
+    const key = pinnedKey ? ed25519PublicKey(pinnedKey.publicKeySpkiB64) : null;
+    if (!key)
+        return { ok: false, reason: 'unknown_key' };
+    if (!verifySignature(ATTESTATION_SIGNING_DOMAIN, a.payload, a.sig, key)) {
+        return { ok: false, reason: 'signature' };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(a.payload);
+    }
+    catch {
+        return { ok: false, reason: 'malformed' };
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { ok: false, reason: 'malformed' };
+    }
+    const p = parsed;
+    if (p.v !== 2 ||
+        typeof p.toolUseId !== 'string' ||
+        typeof p.toolName !== 'string' ||
+        typeof p.inputSha256 !== 'string' ||
+        p.decidedBy !== 'user' ||
+        typeof p.daemonId !== 'string' ||
+        typeof p.sessionId !== 'string' ||
+        typeof p.issuedAt !== 'number' ||
+        typeof p.expiresAt !== 'number') {
+        return { ok: false, reason: 'malformed' };
+    }
+    // A signed approval for another daemon (or another session on this one) is
+    // a valid signature over the wrong question. Checked before freshness so the
+    // log says WHICH wrong question when both are wrong.
+    if (!call.daemonId ||
+        p.daemonId !== call.daemonId ||
+        !call.sessionId ||
+        p.sessionId !== call.sessionId) {
+        return { ok: false, reason: 'daemon_binding' };
+    }
+    const claims = (0, daemonToolApproval_js_1.verifyAttestedToolApprovalClaims)({
+        toolUseId: p.toolUseId,
+        toolName: p.toolName,
+        inputSha256: p.inputSha256,
+        issuedAt: p.issuedAt,
+        expiresAt: p.expiresAt,
+    }, call);
+    if (!claims.ok)
+        return claims;
+    return { ok: true, toolUseId: p.toolUseId, expiresAt: p.expiresAt };
+}
+/**
+ * Daemon side: THE decision for any attestation, whatever version arrived.
+ *
+ *  - pinned     → only v2 verified against the pinned keyset approves; v1 is
+ *                 refused as `unsigned` (downgrade protection).
+ *  - unpinned   → legacy: v1 is verified exactly as before; v2 is refused as
+ *                 `unpinned` (nothing here could check it — the server should
+ *                 not have sent it, since this daemon did not announce
+ *                 `tool_approval_signed_v1`).
+ *  - unreadable → nothing approves.
+ *
+ * Returns the claims the spend-once ledger keys on when it approves.
+ */
+function verifyToolApprovalAttestation(approval, call, pin) {
+    if (approval === undefined || approval === null)
+        return { ok: false, reason: 'absent' };
+    const version = approval && typeof approval === 'object' && !Array.isArray(approval)
+        ? approval.v
+        : undefined;
+    if (pin.state === 'unreadable')
+        return { ok: false, reason: 'pin_unreadable' };
+    if (pin.state === 'pinned') {
+        if (version === 1)
+            return { ok: false, reason: 'unsigned' };
+        const verdict = verifySignedToolApproval(approval, call, pin.keyset);
+        return verdict.ok ? { ...verdict, signed: true } : verdict;
+    }
+    if (version === 2)
+        return { ok: false, reason: 'unpinned' };
+    const legacy = (0, daemonToolApproval_js_1.verifyAttestedToolApproval)(approval, call);
+    if (!legacy.ok)
+        return legacy;
+    const a = approval;
+    return { ok: true, toolUseId: a.toolUseId, expiresAt: a.expiresAt, signed: false };
+}

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/types.d.ts

@@ -82,7 +82,16 @@ export interface TokenPair {
 export type PermanentAuthReason = 'REFRESH_INVALID' | 'REFRESH_REUSED' | 'REFRESH_EXPIRED' | 'SESSION_REVOKED' | 'DEVICE_KEY_MISMATCH' | 'TOKEN_INVALID' | 'TOKEN_EXPIRED' | 'UNKNOWN_401';
 export declare class PermanentAuthFailure extends Error {
     readonly code: PermanentAuthReason;
-    constructor(code: PermanentAuthReason, message: string);
+    /**
+     * OSK-16941 — for `SESSION_REVOKED`, the server's `reason` (a
+     * `SESSION_REVOCATION_REASONS` value, `./sessionRevocation.ts`) exactly as
+     * received, or undefined when the server sent none. Deliberately not
+     * normalized here: a surface rendering it with `describeSessionRevocation`
+     * turns a missing or unknown value into the "we could not tell why" copy,
+     * and keeps an unrecognised code visible rather than losing it.
+     */
+    readonly revocationReason?: string;
+    constructor(code: PermanentAuthReason, message: string, revocationReason?: string);
 }
 export declare class TransientAuthFailure extends Error {
     readonly cause?: unknown;
@@ -91,6 +100,13 @@ export declare class TransientAuthFailure extends Error {
 export interface ReauthState {
     code: string;
     message?: string;
+    /**
+     * OSK-16941 — the server's session-revocation `reason` for a
+     * `SESSION_REVOKED` latch, so the CLI and desktop can say WHY the person was
+     * signed out. Absent on latches written before it existed and on refusals
+     * that were not revocations.
+     */
+    revocationReason?: string;
     /** Epoch ms. */
     at: number;
 }

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/types.js

@@ -8,10 +8,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TransientAuthFailure = exports.PermanentAuthFailure = void 0;
 class PermanentAuthFailure extends Error {
     code;
-    constructor(code, message) {
+    /**
+     * OSK-16941 — for `SESSION_REVOKED`, the server's `reason` (a
+     * `SESSION_REVOCATION_REASONS` value, `./sessionRevocation.ts`) exactly as
+     * received, or undefined when the server sent none. Deliberately not
+     * normalized here: a surface rendering it with `describeSessionRevocation`
+     * turns a missing or unknown value into the "we could not tell why" copy,
+     * and keeps an unrecognised code visible rather than losing it.
+     */
+    revocationReason;
+    constructor(code, message, revocationReason) {
         super(message);
         this.name = 'PermanentAuthFailure';
         this.code = code;
+        if (revocationReason !== undefined)
+            this.revocationReason = revocationReason;
     }
 }
 exports.PermanentAuthFailure = PermanentAuthFailure;