@skrr-ai/cli 0.1.79 → 0.1.80

package/dist/lib/daemonRestartWait.js

@@ -0,0 +1,181 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_POLL_MS = exports.SUPERVISED_GRACE_MS = exports.DEFAULT_RESTART_WAIT_MS = exports.STARTING_WINDOW_MS = void 0;
+exports.probeDaemonRestart = probeDaemonRestart;
+exports.awaitRestartedDaemon = awaitRestartedDaemon;
+/**
+ * Bounded wait for a local daemon that is restarting (OSK-13222).
+ *
+ * The CLI's credential on a daemon-brokered machine is redeemed per process
+ * over the daemon's loopback hand-off. A daemon restart opens a window in which
+ * there is nothing to redeem from:
+ *
+ *   - a GRACEFUL restart removes the hand-off descriptor on shutdown and the
+ *     replacement publishes a new one only once it is listening — measured at
+ *     ~14s on a laptop (shutdown 03:11:34 → `listening` 03:11:48), most of it
+ *     harness detection;
+ *   - a CRASH leaves the descriptor naming a pid that has exited until the
+ *     supervisor starts a replacement.
+ *
+ * Every `skrr` process landing in that window used to report "Not signed in.
+ * Run `skrr login` first." and succeed on an immediate retry. This module
+ * decides whether a restart is plausibly in progress and, if so, waits for a
+ * fresh descriptor — bounded, and never when nothing says a daemon is coming
+ * back, so a machine with no daemon pays nothing.
+ *
+ * The signals, cheapest to strongest:
+ *
+ *   - `starting` — the profile's singleton-lock sidecar names a LIVE pid that
+ *     acquired the lock recently. That is a daemon between lock and listen;
+ *     its descriptor is coming. Wait up to the full budget.
+ *   - `supervised` — no live lock holder, but a launchd plist / systemd user
+ *     unit for the profile is installed, so a supervisor is expected to bring
+ *     one up (the ~1.4s between a graceful release and the next acquire, or a
+ *     crash awaiting respawn). Wait a short grace, extended to the full budget
+ *     if a holder appears.
+ *   - `none` — no daemon is coming, or one is running and deliberately not
+ *     serving hand-offs (its lock is old: auth latched, OSK-12807). Do not wait.
+ */
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+/** A lock acquired within this window belongs to a daemon still starting up. */
+exports.STARTING_WINDOW_MS = 60_000;
+/** Total wait once a starting daemon is seen. Startup was measured at ~14s. */
+exports.DEFAULT_RESTART_WAIT_MS = 20_000;
+/** Wait for a supervisor to start a daemon when none holds the lock yet. */
+exports.SUPERVISED_GRACE_MS = 4_000;
+exports.DEFAULT_POLL_MS = 250;
+const PROFILE_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/**
+ * Read the restart signal for `profile` from the daemon's own on-disk state.
+ * Never throws; anything unreadable reads as absent.
+ */
+function probeDaemonRestart(profile, opts = {}) {
+    if (!PROFILE_RE.test(profile))
+        return 'none';
+    const home = opts.homeDir ?? os.homedir();
+    const now = opts.now ?? Date.now();
+    const platform = opts.platform ?? process.platform;
+    try {
+        const infoPath = path.join(home, '.skrr', 'profiles', profile, 'daemon.lock.info.json');
+        const info = JSON.parse(fs.readFileSync(infoPath, 'utf8'));
+        if (typeof info.pid === 'number' && info.pid > 0 && pidAlive(info.pid)) {
+            const startedAt = typeof info.startedAt === 'string' ? Date.parse(info.startedAt) : NaN;
+            // A live holder that started long ago is a running daemon that is not
+            // serving hand-offs on purpose — waiting would only add latency.
+            if (Number.isFinite(startedAt) && now - startedAt <= exports.STARTING_WINDOW_MS)
+                return 'starting';
+            return 'none';
+        }
+    }
+    catch {
+        /* no sidecar, or unreadable: fall through to the supervisor check */
+    }
+    // Supervisor names mirror daemon/src/profile.ts (`launchdLabelFor`,
+    // `systemdUnitFor`); the CLI does not import daemon code.
+    const units = [];
+    if (platform === 'darwin') {
+        units.push(path.join(home, 'Library', 'LaunchAgents', `ai.skrr.daemon.${profile}.plist`));
+    }
+    else if (platform === 'linux') {
+        units.push(path.join(home, '.config', 'systemd', 'user', `skrrd-${profile}.service`));
+    }
+    for (const unit of units) {
+        try {
+            if (fs.existsSync(unit))
+                return 'supervised';
+        }
+        catch {
+            /* unreadable reads as absent */
+        }
+    }
+    return 'none';
+}
+function envBudget() {
+    const raw = process.env.SKRR_DAEMON_RESTART_WAIT_MS;
+    if (raw === undefined || raw.trim() === '')
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+async function awaitRestartedDaemon(opts) {
+    const maxWaitMs = envBudget() ?? opts.maxWaitMs ?? exports.DEFAULT_RESTART_WAIT_MS;
+    if (maxWaitMs <= 0)
+        return { waited: false, waitedMs: 0, ready: false };
+    const probe = opts.probe ?? ((p) => probeDaemonRestart(p));
+    const now = opts.now ?? Date.now;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const pollMs = opts.pollMs ?? exports.DEFAULT_POLL_MS;
+    const grace = Math.min(opts.supervisedGraceMs ?? exports.SUPERVISED_GRACE_MS, maxWaitMs);
+    let signal = probe(opts.profile);
+    if (signal === 'none')
+        return { waited: false, waitedMs: 0, ready: false };
+    const start = now();
+    let deadline = start + (signal === 'starting' ? maxWaitMs : grace);
+    const notify = opts.notify ??
+        ((message) => {
+            process.stderr.write(`[skrr] ${message}\n`);
+        });
+    notify(`The skrr background service on this computer is restarting; waiting up to ${Math.round(maxWaitMs / 1000)}s for it to come back.`);
+    for (;;) {
+        if (opts.ready())
+            return { waited: true, waitedMs: now() - start, ready: true };
+        if (now() >= deadline)
+            break;
+        await sleep(pollMs);
+        signal = probe(opts.profile);
+        if (signal === 'starting')
+            deadline = Math.max(deadline, start + maxWaitMs);
+        else if (signal === 'none') {
+            // Nothing is coming back after all — but a descriptor may have landed
+            // between the last check and this probe.
+            if (opts.ready())
+                return { waited: true, waitedMs: now() - start, ready: true };
+            break;
+        }
+    }
+    return { waited: true, waitedMs: now() - start, ready: false };
+}

package/dist/lib/dedicated-service.js

@@ -26,6 +26,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const socket_io_client_1 = require("socket.io-client");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const agentic_stream_1 = require("./agentic-stream");
+const dpop_auth_1 = require("./dpop-auth");
 const format_1 = require("./format");
 /**
  * Declared services on a Dedicated Runtime — the CLI half of
@@ -411,17 +412,20 @@ function specFromFlags(input) {
     }
     return spec;
 }
-function socketOptions(token) {
+function socketOptions(token, wsOrigin) {
     return {
         path: '/ws/agentic',
-        auth: {
+        // OSK-12020 — a DPoP-bound token proves possession on every handshake.
+        auth: (0, dpop_auth_1.socketAuthWithDpop)({
             token,
             // This proves origin only; the normal CLI token retains full execution authority.
-            ...(process.env.OVERSKY_SESSION_TOKEN ? { executionOriginToken: process.env.OVERSKY_SESSION_TOKEN } : {}),
+            ...(process.env.OVERSKY_SESSION_TOKEN
+                ? { executionOriginToken: process.env.OVERSKY_SESSION_TOKEN }
+                : {}),
             ...(0, data_provider_1.getClientIdentityAuth)(),
             clientPlatform: 'cli',
             clientOs: process.platform === 'darwin' ? 'macos' : process.platform,
-        },
+        }, wsOrigin),
         transports: ['websocket'],
         reconnection: false,
     };
@@ -442,7 +446,8 @@ class DedicatedServiceChannel {
     constructor(options) {
         this.options = options;
         const connect = options.connect ?? socket_io_client_1.io;
-        this.socket = connect((0, agentic_stream_1.toWebSocketOrigin)(options.baseURL), socketOptions(options.token));
+        const wsOrigin = (0, agentic_stream_1.toWebSocketOrigin)(options.baseURL);
+        this.socket = connect(wsOrigin, socketOptions(options.token, wsOrigin));
         // An ack resolves a request only when it arrives on THAT request's own
         // ack event — a requestId echoed back on the wrong family is not an
         // answer, however well-formed it looks.

package/dist/lib/dedicated-ssh.js

@@ -22,6 +22,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const socket_io_client_1 = require("socket.io-client");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const agentic_stream_1 = require("./agentic-stream");
+const dpop_auth_1 = require("./dpop-auth");
 /**
  * Owner SSH to a Dedicated Runtime — SSH protocol over the admitted relay.
  *
@@ -284,14 +285,16 @@ function runSshProxy(options) {
     return new Promise((resolve) => {
         let started = false;
         let finished = false;
-        const socket = connect((0, agentic_stream_1.toWebSocketOrigin)(options.baseURL), {
+        const wsOrigin = (0, agentic_stream_1.toWebSocketOrigin)(options.baseURL);
+        const socket = connect(wsOrigin, {
             path: '/ws/agentic',
-            auth: {
+            // OSK-12020 — a DPoP-bound token proves possession on every handshake.
+            auth: (0, dpop_auth_1.socketAuthWithDpop)({
                 token: options.token,
                 ...(0, data_provider_1.getClientIdentityAuth)(),
                 clientPlatform: 'cli',
                 clientOs: process.platform === 'darwin' ? 'macos' : process.platform,
-            },
+            }, wsOrigin),
             transports: ['websocket'],
             // A reconnect cannot resume a channel whose admission line the daemon
             // revoked on socket death — say it ended and let ssh retry fresh.

package/dist/lib/dedicated-terminal.js

@@ -9,6 +9,7 @@ const node_crypto_1 = require("node:crypto");
 const socket_io_client_1 = require("socket.io-client");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const agentic_stream_1 = require("./agentic-stream");
+const dpop_auth_1 = require("./dpop-auth");
 /**
  * A real pseudo-terminal on a Dedicated Runtime, from a local terminal.
  *
@@ -100,14 +101,16 @@ function runDedicatedTerminal(options) {
         let retryTimer;
         let recoveryTimer;
         let connected = false;
-        const socket = connect((0, agentic_stream_1.toWebSocketOrigin)(options.baseURL), {
+        const wsOrigin = (0, agentic_stream_1.toWebSocketOrigin)(options.baseURL);
+        const socket = connect(wsOrigin, {
             path: '/ws/agentic',
-            auth: {
+            // OSK-12020 — a DPoP-bound token proves possession on every handshake.
+            auth: (0, dpop_auth_1.socketAuthWithDpop)({
                 token: options.token,
                 ...(0, data_provider_1.getClientIdentityAuth)(),
                 clientPlatform: 'cli',
                 clientOs: process.platform === 'darwin' ? 'macos' : process.platform,
-            },
+            }, wsOrigin),
             transports: ['websocket'],
             // A bare PTY cannot be resumed: the relay forgets the session with the
             // socket, and silently opening a NEW shell would drop the user into a

package/dist/lib/dpop-auth.d.ts

@@ -0,0 +1,35 @@
+/**
+ * dpop-auth.ts — attach RFC 9449 proofs for a DPoP-bound hand-off token
+ * (OSK-12020).
+ *
+ * The ONE place a request path asks for a proof, so every transport the CLI
+ * has — `apiFetch`, the data-service node adapter, SSE, and Socket.IO — binds
+ * the same way. For any other credential both helpers are no-ops and the wire
+ * is byte-identical to before.
+ *
+ * The CLI never holds the key. Each proof comes from the local daemon
+ * (`brokeredDpopProof`), which keeps the private half in its own memory; that
+ * is what makes a copied token useless anywhere but on this machine.
+ */
+/** RFC 9449 §4.1. */
+export declare const DPOP_HEADER = "DPoP";
+/** Headers to add to one HTTP request made with `token`; `{}` when unbound. */
+export declare function dpopHeadersFor(token: string | null | undefined, method: string, url: string): Promise<Record<string, string>>;
+/**
+ * The URI a Socket.IO handshake proof commits to: the realtime origin's
+ * http(s) form plus the engine path, no trailing slash — what the server
+ * rebuilds from the handshake request (`reconstructHandshakeHtu`).
+ */
+export declare function socketHandshakeHtu(wsOrigin: string, ioPath?: string): string;
+type SocketAuth = Record<string, unknown>;
+type SocketAuthFn = (cb: (data: SocketAuth) => void) => void;
+/**
+ * Socket.IO `auth` for a handshake made with `auth.token`. Unbound: the object
+ * itself, unchanged. Bound: a FUNCTION, which socket.io-client calls on every
+ * (re)connect — so each handshake presents a fresh, single-use proof instead
+ * of replaying the first one into the server's jti cache.
+ */
+export declare function socketAuthWithDpop(auth: SocketAuth & {
+    token?: string | null;
+}, wsOrigin: string, ioPath?: string): SocketAuth | SocketAuthFn;
+export {};

package/dist/lib/dpop-auth.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * dpop-auth.ts — attach RFC 9449 proofs for a DPoP-bound hand-off token
+ * (OSK-12020).
+ *
+ * The ONE place a request path asks for a proof, so every transport the CLI
+ * has — `apiFetch`, the data-service node adapter, SSE, and Socket.IO — binds
+ * the same way. For any other credential both helpers are no-ops and the wire
+ * is byte-identical to before.
+ *
+ * The CLI never holds the key. Each proof comes from the local daemon
+ * (`brokeredDpopProof`), which keeps the private half in its own memory; that
+ * is what makes a copied token useless anywhere but on this machine.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DPOP_HEADER = void 0;
+exports.dpopHeadersFor = dpopHeadersFor;
+exports.socketHandshakeHtu = socketHandshakeHtu;
+exports.socketAuthWithDpop = socketAuthWithDpop;
+const brokered_dpop_1 = require("./brokered-dpop");
+/** RFC 9449 §4.1. */
+exports.DPOP_HEADER = 'DPoP';
+/** Headers to add to one HTTP request made with `token`; `{}` when unbound. */
+async function dpopHeadersFor(token, method, url) {
+    if (!(0, brokered_dpop_1.isDpopBoundHandoffToken)(token))
+        return {};
+    const proof = await (0, brokered_dpop_1.brokeredDpopProof)(token, method, url);
+    return proof ? { [exports.DPOP_HEADER]: proof } : {};
+}
+/**
+ * The URI a Socket.IO handshake proof commits to: the realtime origin's
+ * http(s) form plus the engine path, no trailing slash — what the server
+ * rebuilds from the handshake request (`reconstructHandshakeHtu`).
+ */
+function socketHandshakeHtu(wsOrigin, ioPath = '/ws/agentic') {
+    const u = new URL(wsOrigin);
+    u.protocol = u.protocol === 'wss:' ? 'https:' : u.protocol === 'ws:' ? 'http:' : u.protocol;
+    u.pathname = ioPath.replace(/\/+$/, '');
+    u.search = '';
+    u.hash = '';
+    return u.toString();
+}
+/**
+ * Socket.IO `auth` for a handshake made with `auth.token`. Unbound: the object
+ * itself, unchanged. Bound: a FUNCTION, which socket.io-client calls on every
+ * (re)connect — so each handshake presents a fresh, single-use proof instead
+ * of replaying the first one into the server's jti cache.
+ */
+function socketAuthWithDpop(auth, wsOrigin, ioPath = '/ws/agentic') {
+    const token = typeof auth.token === 'string' ? auth.token : null;
+    if (!(0, brokered_dpop_1.isDpopBoundHandoffToken)(token))
+        return auth;
+    const htu = socketHandshakeHtu(wsOrigin, ioPath);
+    return (cb) => {
+        void (0, brokered_dpop_1.brokeredDpopProof)(token, 'GET', htu).then((proof) => cb(proof ? { ...auth, dpop: proof } : auth), () => cb(auth));
+    };
+}

package/dist/lib/login.d.ts

@@ -42,6 +42,12 @@ export interface CliLoginWithRefreshTokenOptions {
  * What a shell with no terminal can do instead (OSK-12117). The refusal used to
  * name only CI tokens, which is not a sign-in: an agent session asking for one
  * could only hand the job to a person typing `! skrr login`.
+ *
+ * It also used to send CI to `skrr create-token` + `OVERSKY_TOKEN=osk_ci_...`.
+ * That token only bootstraps a daemon; every `skrr` command rejects it with 401
+ * (create-token.ts, base-command.ts), so the advice was a dead end (OSK-13209).
+ * The route that works today is a minted machine session — see
+ * docs/cli/SKRR_AUTH.md "CI today" for its caveats.
  */
 export declare const HEADLESS_LOGIN_HINT: string;
 /**

package/dist/lib/login.js

@@ -43,10 +43,18 @@ const daemonBrokerRefusal_1 = require("./daemonBrokerRefusal");
  * What a shell with no terminal can do instead (OSK-12117). The refusal used to
  * name only CI tokens, which is not a sign-in: an agent session asking for one
  * could only hand the job to a person typing `! skrr login`.
+ *
+ * It also used to send CI to `skrr create-token` + `OVERSKY_TOKEN=osk_ci_...`.
+ * That token only bootstraps a daemon; every `skrr` command rejects it with 401
+ * (create-token.ts, base-command.ts), so the advice was a dead end (OSK-13209).
+ * The route that works today is a minted machine session — see
+ * docs/cli/SKRR_AUTH.md "CI today" for its caveats.
  */
 exports.HEADLESS_LOGIN_HINT = '`skrr login --device-code` works without a terminal: it prints a URL and a code for a ' +
-    'person to approve in any browser, and finishes when they do. For CI, use ' +
-    '`skrr create-token` and set OVERSKY_TOKEN=osk_ci_...';
+    'person to approve in any browser, and finishes when they do. With no person to approve ' +
+    '(CI, a script), mint a session for this machine elsewhere with `skrr token mint --for <id>` ' +
+    'and run `skrr login` here with OVERSKY_REFRESH_TOKEN and OVERSKY_CLI_ID set. ' +
+    '`skrr create-token` tokens are not accepted by skrr commands.';
 /**
  * The line printed when the daemon descriptor this CLI found is for another
  * server (OSK-12117).
@@ -164,8 +172,9 @@ async function cliLogin(opts = {}) {
         // silently fall through to PKCE / device-code below.
         if (brokerResult.reason === 'ci_token_refused') {
             throw new Error('The skrr background service on this computer is bootstrapped from a CI token, which cannot broker an interactive CLI login. ' +
-                'Use `skrr create-token --name <name>` to mint a long-lived CI credential directly, ' +
-                'or run `skrr login` on a machine where the daemon was authenticated interactively.');
+                'Sign this CLI in on its own with `skrr login --device-code`, or with a session minted elsewhere by ' +
+                '`skrr token mint --for <id>` (OVERSKY_REFRESH_TOKEN + OVERSKY_CLI_ID). ' +
+                'A `skrr create-token` token is not accepted by skrr commands.');
         }
         // `base_url_mismatch` is a configuration drift the user can resolve
         // explicitly; print a one-line hint so they're not surprised when

package/dist/lib/node-adapter.js

@@ -12,6 +12,7 @@ const config_1 = require("./config");
 const auth_storage_1 = require("./auth-storage");
 const credential_resolver_1 = require("./credential-resolver");
 const daemonBroker_1 = require("./daemonBroker");
+const dpop_auth_1 = require("./dpop-auth");
 const refresh_1 = require("./refresh");
 const delegated_cli_1 = require("./delegated-cli");
 const workspace_header_1 = require("./workspace-header");
@@ -159,6 +160,9 @@ function createNodeAdapter(opts = {}) {
             }
         }
         const finalUrl = appendQuery(resolveUrl(url), options?.params);
+        // OSK-12020 — a DPoP-bound hand-off token needs a fresh proof per request
+        // (and per retry: proofs are single-use). No-op for every other token.
+        Object.assign(headers, await (0, dpop_auth_1.dpopHeadersFor)(currentCredential().token, method, finalUrl));
         return fetch(finalUrl, { method, headers, body: finalBody });
     }
     /**

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

@@ -22,7 +22,7 @@
  *  - `access_token`:   broker mode — a short-lived access token from a
  *                      daemon-owned family; nothing durable leaves the daemon.
  */
-export declare const CLI_HANDOFF_MODES: readonly ["refresh_family", "access_token"];
+export declare const CLI_HANDOFF_MODES: readonly ["refresh_family", "access_token", "access_token_dpop"];
 export type CliHandoffMode = (typeof CLI_HANDOFF_MODES)[number];
 /** Broker-mode redeem route on the daemon's loopback server. */
 export declare const CLI_HANDOFF_TOKEN_PATH = "/v1/auth/cli-handoff-token";
@@ -74,10 +74,26 @@ export declare function normalizeHandoffModes(value: unknown): CliHandoffMode[];
  */
 export declare function advertisedHandoffModes(d: CliHandoffDescriptor): CliHandoffMode[];
 export declare function descriptorOffersAccessToken(d: CliHandoffDescriptor): boolean;
+/** True when the token route can serve DPoP-bound tokens (OSK-12020). */
+export declare function descriptorOffersDpop(d: CliHandoffDescriptor): boolean;
 export interface CliHandoffTokenRequest {
     /** Bypass the daemon broker's cached token (the 401-recovery path). */
     forceRefresh?: boolean;
+    /**
+     * The caller can fetch per-request proofs from `CLI_HANDOFF_DPOP_PROOF_PATH`
+     * and wants a DPoP-bound token. Sent only to a descriptor that advertises
+     * `access_token_dpop`; a daemon that does not know the field ignores it and
+     * answers an unbound token, which `tokenType` then says.
+     */
+    dpop?: boolean;
 }
+/**
+ * How the token must be presented. `DPoP` means the token carries `cnf.jkt`
+ * and every request needs a fresh proof; absent or `Bearer` means an ordinary
+ * bearer token. Read from the RESPONSE, never assumed from the request: an
+ * older server ignores the binding request and mints an unbound token.
+ */
+export type CliHandoffTokenType = 'Bearer' | 'DPoP';
 export interface CliHandoffTokenResponse {
     accessToken: string;
     /** Absolute expiry in ms since epoch, when the daemon knows it. */
@@ -85,6 +101,31 @@ export interface CliHandoffTokenResponse {
     /** Server the minted credential belongs to — lets the caller verify it is
      *  about to use a token for the API it thinks it is talking to. */
     serverUrl?: string;
+    tokenType?: CliHandoffTokenType;
 }
 /** Parse the redeem response; null when the token itself is absent. */
 export declare function parseCliHandoffTokenResponse(value: unknown): CliHandoffTokenResponse | null;
+/** The daemon refuses an UNBOUND token because its posture requires binding. */
+export declare const CLI_HANDOFF_ERROR_DPOP_REQUIRED = "HANDOFF_DPOP_REQUIRED";
+/**
+ * The daemon signs RFC 9449 proofs for a bound token with a key that never
+ * leaves it. Same descriptor secret as the token route: using a stolen bound
+ * token therefore needs live loopback access to THIS daemon, which is the
+ * boundary the capability already has.
+ */
+export declare const CLI_HANDOFF_DPOP_PROOF_PATH = "/v1/auth/cli-handoff-dpop-proof";
+/** The oracle refused to sign (bad htm/htu, or `ath` names no token it issued). */
+export declare const CLI_HANDOFF_ERROR_DPOP_PROOF_REFUSED = "HANDOFF_DPOP_PROOF_REFUSED";
+/** The daemon holds no DPoP key (binding is off on this daemon). */
+export declare const CLI_HANDOFF_ERROR_DPOP_UNAVAILABLE = "HANDOFF_DPOP_UNAVAILABLE";
+export interface CliHandoffDpopProofRequest {
+    htm: string;
+    htu: string;
+    /** base64url SHA-256 of the bound access token. The token itself is never
+     *  sent: the oracle commits to a hash, and only to one it issued. */
+    ath: string;
+}
+export interface CliHandoffDpopProofResponse {
+    proof: string;
+}
+export declare function parseCliHandoffDpopProofResponse(value: unknown): CliHandoffDpopProofResponse | null;

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

@@ -18,19 +18,21 @@
  * must produce the full shape.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CLI_HANDOFF_ERROR_BROKER_ONLY = exports.CLI_HANDOFF_TOKEN_ERROR_UNAVAILABLE = exports.CLI_HANDOFF_TOKEN_PATH = exports.CLI_HANDOFF_MODES = void 0;
+exports.CLI_HANDOFF_ERROR_DPOP_UNAVAILABLE = exports.CLI_HANDOFF_ERROR_DPOP_PROOF_REFUSED = exports.CLI_HANDOFF_DPOP_PROOF_PATH = exports.CLI_HANDOFF_ERROR_DPOP_REQUIRED = exports.CLI_HANDOFF_ERROR_BROKER_ONLY = exports.CLI_HANDOFF_TOKEN_ERROR_UNAVAILABLE = exports.CLI_HANDOFF_TOKEN_PATH = exports.CLI_HANDOFF_MODES = void 0;
 exports.parseCliHandoffDescriptor = parseCliHandoffDescriptor;
 exports.normalizeHandoffModes = normalizeHandoffModes;
 exports.advertisedHandoffModes = advertisedHandoffModes;
 exports.descriptorOffersAccessToken = descriptorOffersAccessToken;
+exports.descriptorOffersDpop = descriptorOffersDpop;
 exports.parseCliHandoffTokenResponse = parseCliHandoffTokenResponse;
+exports.parseCliHandoffDpopProofResponse = parseCliHandoffDpopProofResponse;
 /**
  * What a caller may redeem the descriptor secret for.
  *  - `refresh_family`: the legacy durable mint (90-day cli-scope family).
  *  - `access_token`:   broker mode — a short-lived access token from a
  *                      daemon-owned family; nothing durable leaves the daemon.
  */
-exports.CLI_HANDOFF_MODES = ['refresh_family', 'access_token'];
+exports.CLI_HANDOFF_MODES = ['refresh_family', 'access_token', 'access_token_dpop'];
 /** Broker-mode redeem route on the daemon's loopback server. */
 exports.CLI_HANDOFF_TOKEN_PATH = '/v1/auth/cli-handoff-token';
 /** Error codes this contract emits. String literals so both ends compare
@@ -96,7 +98,12 @@ function advertisedHandoffModes(d) {
     return declared.length > 0 ? declared : ['refresh_family'];
 }
 function descriptorOffersAccessToken(d) {
-    return advertisedHandoffModes(d).includes('access_token');
+    const modes = advertisedHandoffModes(d);
+    return modes.includes('access_token') || modes.includes('access_token_dpop');
+}
+/** True when the token route can serve DPoP-bound tokens (OSK-12020). */
+function descriptorOffersDpop(d) {
+    return advertisedHandoffModes(d).includes('access_token_dpop');
 }
 /** Parse the redeem response; null when the token itself is absent. */
 function parseCliHandoffTokenResponse(value) {
@@ -109,5 +116,30 @@ function parseCliHandoffTokenResponse(value) {
         accessToken: v.accessToken,
         ...(typeof v.accessExpiresAt === 'number' ? { accessExpiresAt: v.accessExpiresAt } : {}),
         ...(typeof v.serverUrl === 'string' ? { serverUrl: v.serverUrl } : {}),
+        ...(v.tokenType === 'DPoP' || v.tokenType === 'Bearer' ? { tokenType: v.tokenType } : {}),
     };
 }
+/** The daemon refuses an UNBOUND token because its posture requires binding. */
+exports.CLI_HANDOFF_ERROR_DPOP_REQUIRED = 'HANDOFF_DPOP_REQUIRED';
+// ---------------------------------------------------------------------
+// Proof oracle — POST CLI_HANDOFF_DPOP_PROOF_PATH (OSK-12020)
+// ---------------------------------------------------------------------
+/**
+ * The daemon signs RFC 9449 proofs for a bound token with a key that never
+ * leaves it. Same descriptor secret as the token route: using a stolen bound
+ * token therefore needs live loopback access to THIS daemon, which is the
+ * boundary the capability already has.
+ */
+exports.CLI_HANDOFF_DPOP_PROOF_PATH = '/v1/auth/cli-handoff-dpop-proof';
+/** The oracle refused to sign (bad htm/htu, or `ath` names no token it issued). */
+exports.CLI_HANDOFF_ERROR_DPOP_PROOF_REFUSED = 'HANDOFF_DPOP_PROOF_REFUSED';
+/** The daemon holds no DPoP key (binding is off on this daemon). */
+exports.CLI_HANDOFF_ERROR_DPOP_UNAVAILABLE = 'HANDOFF_DPOP_UNAVAILABLE';
+function parseCliHandoffDpopProofResponse(value) {
+    if (value == null || typeof value !== 'object')
+        return null;
+    const v = value;
+    if (typeof v.proof !== 'string' || v.proof.split('.').length !== 3)
+        return null;
+    return { proof: v.proof };
+}

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

@@ -13,6 +13,20 @@
  * Deliberately thin: no persistence, no retry policy, no logging. Callers
  * own their store and their error surfaces; this owns the cache/single-
  * flight/invalidate invariants so they cannot drift between surfaces.
+ *
+ * Two policies are options because mechanisms genuinely need different ones,
+ * and both default to the original behaviour:
+ *
+ *   - `forcedAcquire: 'join'` — a forced acquire joins whatever is in flight,
+ *     for a mechanism where a second concurrent renewal is itself the hazard
+ *     (a refresh-family rotation or a family mint);
+ *   - `classifyAcquireError` — stale-on-degrade: a TRANSIENT failure serves the
+ *     still-unexpired cached credential instead of failing, a PERMANENT one
+ *     drops it.
+ *
+ * Mechanism-specific limits — how often a new family may be minted, which
+ * failures retire it — stay in the mechanism. The daemon's task token broker
+ * (`daemon/src/task/token-broker.ts`) is the consumer that uses both options.
  */
 /** What an acquire returns. `expiresAtMs` absent means "no known expiry" —
  *  the token is served until `invalidate()` or an acquire replaces it. */
@@ -26,13 +40,45 @@ export interface CredentialSessionOptions {
      * The mechanism. Called with `forceRefresh: true` when the caller asked to
      * bypass the cache (the 401-recovery path) — implementations should renew
      * rather than serve their own cache. A rejected promise propagates to every
-     * waiter and is never cached.
+     * waiter and is never cached (`classifyAcquireError` is the one way a waiter
+     * can be served the previous credential instead).
      */
     acquire: (forceRefresh: boolean) => Promise<AcquiredCredential>;
     /** Serve the cached token until this many ms before expiry. Default 30s. */
     skewMs?: number;
     /** Injectable clock for tests. */
     now?: () => number;
+    /**
+     * What a forced acquire does when an acquire is already in flight.
+     *
+     *   - `'supersede'` (default): a forced acquire never joins a NON-forced
+     *     in-flight one — that could serve the very credential a 401 just
+     *     invalidated — so it starts a second operation, and the superseded one
+     *     cannot write its result back. Right for a mechanism whose plain
+     *     acquire may serve its own cache.
+     *   - `'join'`: every acquire, forced or not, joins the one in flight. Right
+     *     — and required — for a mechanism whose acquire ALWAYS renews (it never
+     *     serves a cache of its own), and for which a second concurrent renewal
+     *     is itself the hazard: a rotation that burns a refresh family, a mint
+     *     that creates a new one. Whatever is in flight was started after the
+     *     credential being replaced was issued, so its result is not that
+     *     credential.
+     */
+    forcedAcquire?: 'supersede' | 'join';
+    /**
+     * Classify an acquire failure. Without it every failure propagates and the
+     * cache is left as it was (the default).
+     *
+     *   - `'transient'` — the renewal failed but the cached credential is still
+     *     good: a waiter is served the cached token while it is inside its HARD
+     *     expiry (the skew window only says when to start renewing), instead of
+     *     the error. Nothing stale is served after `invalidate()`, after a forced
+     *     acquire discarded it, or once it has actually expired.
+     *   - `'permanent'` — the credential is dead upstream: the cache is dropped
+     *     and the error propagates.
+     *   - `undefined` — not classified: the default behaviour.
+     */
+    classifyAcquireError?: (err: unknown) => 'transient' | 'permanent' | undefined;
 }
 export interface CredentialSession {
     /**
@@ -41,6 +87,8 @@ export interface CredentialSession {
      * discards the cache first (use after a resource 401).
      */
     getToken(forceRefresh?: boolean): Promise<string>;
+    /** Same as getToken, but resolves the whole credential (with its expiry). */
+    getCredential(forceRefresh?: boolean): Promise<AcquiredCredential>;
     /** Drop the cached token; the next getToken() acquires. */
     invalidate(): void;
 }