@skrr-ai/cli 0.1.79 → 0.1.80

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/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/esm/cliHandoffWire.js

@@ -22,7 +22,7 @@
  *  - `access_token`:   broker mode — a short-lived access token from a
  *                      daemon-owned family; nothing durable leaves the daemon.
  */
-export const CLI_HANDOFF_MODES = ['refresh_family', 'access_token'];
+export const CLI_HANDOFF_MODES = ['refresh_family', 'access_token', 'access_token_dpop'];
 /** Broker-mode redeem route on the daemon's loopback server. */
 export const CLI_HANDOFF_TOKEN_PATH = '/v1/auth/cli-handoff-token';
 /** Error codes this contract emits. String literals so both ends compare
@@ -88,7 +88,12 @@ export function advertisedHandoffModes(d) {
     return declared.length > 0 ? declared : ['refresh_family'];
 }
 export 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). */
+export function descriptorOffersDpop(d) {
+    return advertisedHandoffModes(d).includes('access_token_dpop');
 }
 /** Parse the redeem response; null when the token itself is absent. */
 export function parseCliHandoffTokenResponse(value) {
@@ -101,5 +106,30 @@ export 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. */
+export const 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.
+ */
+export 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 const CLI_HANDOFF_ERROR_DPOP_PROOF_REFUSED = 'HANDOFF_DPOP_PROOF_REFUSED';
+/** The daemon holds no DPoP key (binding is off on this daemon). */
+export const CLI_HANDOFF_ERROR_DPOP_UNAVAILABLE = 'HANDOFF_DPOP_UNAVAILABLE';
+export 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/esm/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;
 }

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/credentialSession.js

@@ -13,11 +13,27 @@
  * 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.
  */
 const DEFAULT_SKEW_MS = 30_000;
 export function createCredentialSession(opts) {
     const skewMs = opts.skewMs ?? DEFAULT_SKEW_MS;
     const now = opts.now ?? Date.now;
+    const forcedJoins = opts.forcedAcquire === 'join';
+    const classify = opts.classifyAcquireError;
     let cached = null;
     let inFlight = null;
     let inFlightForced = false;
@@ -26,17 +42,26 @@ export function createCredentialSession(opts) {
     // result back over the newer one.
     let generation = 0;
     const fresh = (t) => t.expiresAtMs == null || now() < t.expiresAtMs - skewMs;
+    /** Not yet actually expired — the bar for serving a stale credential. */
+    const unexpired = (t) => t.expiresAtMs == null || now() < t.expiresAtMs;
     const acquireShared = (force) => {
-        // A forced acquire must not join a non-forced in-flight one — that would
-        // serve the very credential a 401 just invalidated. A forced in-flight
-        // DOES satisfy non-forced waiters: it is already renewing.
-        if (inFlight && (inFlightForced || !force))
+        // Under 'supersede', a forced acquire must not join a non-forced in-flight
+        // one — that would serve the very credential a 401 just invalidated. A
+        // forced in-flight DOES satisfy non-forced waiters: it is already renewing.
+        // Under 'join', everything joins (see `forcedAcquire`).
+        if (inFlight && (forcedJoins || inFlightForced || !force))
             return inFlight;
         const gen = ++generation;
         const p = opts.acquire(force).then((t) => {
             if (gen === generation)
                 cached = t;
             return t;
+        }, (err) => {
+            // Settled before any waiter resumes, so a waiter's stale check below
+            // already sees a permanent failure's dropped cache.
+            if (gen === generation && classify?.(err) === 'permanent')
+                cached = null;
+            throw err;
         });
         inFlight = p;
         inFlightForced = force;
@@ -51,13 +76,26 @@ export function createCredentialSession(opts) {
         p.then(cleanup, cleanup);
         return p;
     };
+    const getCredential = async (forceRefresh = false) => {
+        if (forceRefresh)
+            cached = null;
+        if (cached && fresh(cached))
+            return cached;
+        try {
+            return await acquireShared(forceRefresh);
+        }
+        catch (err) {
+            // Stale-on-degrade: read `cached` AFTER the failure, so an invalidate()
+            // or a forced discard that happened meanwhile is honoured.
+            if (classify?.(err) === 'transient' && cached && unexpired(cached))
+                return cached;
+            throw err;
+        }
+    };
     return {
+        getCredential,
         async getToken(forceRefresh = false) {
-            if (forceRefresh)
-                cached = null;
-            if (cached && fresh(cached))
-                return cached.accessToken;
-            return (await acquireShared(forceRefresh)).accessToken;
+            return (await getCredential(forceRefresh)).accessToken;
         },
         invalidate() {
             cached = null;

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/deviceKey.d.ts

@@ -1,3 +1,40 @@
+/**
+ * deviceKey.ts — L11 Phase 1: Ed25519 device identity + DPoP-style proofs.
+ *
+ * The load-bearing recommendation in `docs/daemon-auth-cc-deep-comparison-
+ * 2026-04-24.md` §L11. Two-axis identity:
+ *
+ *   user identity  = OAuth refresh token  (server-rotated, scope-pinned, reuse-detected)
+ *   device identity = Ed25519 keypair      (device-generated, server-revocable)
+ *
+ * Every daemon→server request carries a JWS signature over
+ * `{htm, htu, iat, jti, rth?, ath?}` using the device key. Server validates
+ * against the public key registered for this daemon.
+ *
+ * Stolen credentials require BOTH halves:
+ *   - refresh token alone is useless without the device key
+ *   - device key alone is useless without the refresh token
+ *
+ * Why DPoP-shaped (RFC 9449) rather than rolling our own JWS:
+ *   - The htm/htu/iat/jti/ath claim set is well-studied. Server-side
+ *     replay defenses, clock-skew handling, and audit-trail formats all
+ *     have a body of prior art to copy from.
+ *   - Future interop: if we ever expose OverSky as a third-party OAuth
+ *     resource server, DPoP-bearer is the way clients will already
+ *     understand.
+ *
+ * Why we extend with `rth` (refresh-token-hash):
+ *   - RFC 9449 only mints `ath` (access-token-hash). The whole point of
+ *     L11 is to bind the *refresh* token to the device, so the proof
+ *     accompanying a refresh request must commit to the refresh token.
+ *     `rth` is structurally identical to `ath`; the name disambiguates.
+ *
+ * What this module is NOT responsible for:
+ *   - Persistence (lives in `daemon/src/deviceIdentity.ts`).
+ *   - Server-side public-key registration (separate API in a later PR).
+ *   - Wire-up to the daemon's outgoing HTTP path (Phase 2 of L11).
+ */
+import crypto from 'node:crypto';
 /**
  * Ed25519 JSON Web Key — RFC 8037 §2 ("Key Type 'OKP'").
  *
@@ -123,6 +160,18 @@ export interface BuildProofOptions {
  * not a silent fallback.
  */
 export declare function buildProof(privateJwk: Ed25519PrivateJwk, publicJwk: Ed25519PublicJwk, opts: BuildProofOptions): string;
+/** The header `typ` of an OverSky device-identity proof. */
+export declare const DEVICE_PROOF_TYP = "oversky-dpop+jwt";
+/**
+ * Sign a DPoP-shaped proof with an Ed25519 key under the given header `typ`.
+ *
+ * @internal Shared by the device-identity proof (`oversky-dpop+jwt`, above)
+ * and the RFC 9449 access-token proof (`dpop+jwt`, `dpop.ts`). `typ` is the
+ * only thing on the wire that separates the two protocols, which is why it is
+ * a required argument rather than a default: a proof signed for one must
+ * never verify as the other.
+ */
+export declare function signEd25519Proof(privateKey: crypto.KeyObject, publicJwk: Ed25519PublicJwk, typ: string, opts: BuildProofOptions): string;
 export type VerifyFailureReason = 'malformed' | 'bad_alg' | 'bad_typ' | 'bad_jwk' | 'sig_invalid' | 'iat_old' | 'iat_future' | 'htm_mismatch' | 'htu_mismatch' | 'rth_mismatch' | 'ath_mismatch' | 'pin_mismatch';
 export interface VerifySuccess {
     valid: true;
@@ -165,3 +214,10 @@ export interface VerifyOptions {
  * `sig_invalid` to keep the failure surface narrow.
  */
 export declare function verifyProof(jws: string, opts?: VerifyOptions): VerifySuccess | VerifyFailure;
+/**
+ * Verify a DPoP-shaped Ed25519 proof whose header `typ` must equal `typ`.
+ *
+ * @internal See `signEd25519Proof`. `verifyProof` (device identity) and
+ * `verifyDpopProof` (`dpop.ts`, RFC 9449) are the two public doors.
+ */
+export declare function verifyEd25519Proof(jws: string, opts: VerifyOptions, typ: string): VerifySuccess | VerifyFailure;

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/deviceKey.js

@@ -152,17 +152,40 @@ export function normalizeHtu(url) {
  * not a silent fallback.
  */
 export function buildProof(privateJwk, publicJwk, opts) {
+    if (publicJwk.x !== privateJwk.x) {
+        // Defensive — public and private must come from the same keypair.
+        // A mismatch indicates a corrupted in-memory state.
+        throw new Error('buildProof: public/private JWK x mismatch (corrupted keypair)');
+    }
+    // Cast to crypto's `JsonWebKey` shape — that type requires an index
+    // signature for arbitrary string keys; our narrow OKP shape doesn't
+    // declare one because the strict shape is more useful at our API
+    // boundary. Cast through `unknown` to silence the structural mismatch
+    // without losing the rest of the type safety on this surface.
+    const privateKey = crypto.createPrivateKey({
+        format: 'jwk',
+        key: privateJwk,
+    });
+    return signEd25519Proof(privateKey, publicJwk, DEVICE_PROOF_TYP, opts);
+}
+/** The header `typ` of an OverSky device-identity proof. */
+export const DEVICE_PROOF_TYP = 'oversky-dpop+jwt';
+/**
+ * Sign a DPoP-shaped proof with an Ed25519 key under the given header `typ`.
+ *
+ * @internal Shared by the device-identity proof (`oversky-dpop+jwt`, above)
+ * and the RFC 9449 access-token proof (`dpop+jwt`, `dpop.ts`). `typ` is the
+ * only thing on the wire that separates the two protocols, which is why it is
+ * a required argument rather than a default: a proof signed for one must
+ * never verify as the other.
+ */
+export function signEd25519Proof(privateKey, publicJwk, typ, opts) {
     if (typeof opts.method !== 'string' || opts.method.length === 0) {
         throw new Error('buildProof: method must be a non-empty string');
     }
     if (typeof opts.url !== 'string' || opts.url.length === 0) {
         throw new Error('buildProof: url must be a non-empty string');
     }
-    if (publicJwk.x !== privateJwk.x) {
-        // Defensive — public and private must come from the same keypair.
-        // A mismatch indicates a corrupted in-memory state.
-        throw new Error('buildProof: public/private JWK x mismatch (corrupted keypair)');
-    }
     const claims = {
         htm: opts.method.toUpperCase(),
         htu: normalizeHtu(opts.url),
@@ -173,23 +196,10 @@ export function buildProof(privateJwk, publicJwk, opts) {
         claims.rth = tokenHash(opts.refreshToken);
     if (opts.accessToken !== undefined)
         claims.ath = tokenHash(opts.accessToken);
-    const header = {
-        alg: 'EdDSA',
-        typ: 'oversky-dpop+jwt',
-        jwk: publicJwk,
-    };
+    const header = { alg: 'EdDSA', typ, jwk: publicJwk };
     const headerB64 = b64u(Buffer.from(JSON.stringify(header), 'utf-8'));
     const payloadB64 = b64u(Buffer.from(JSON.stringify(claims), 'utf-8'));
     const signingInput = `${headerB64}.${payloadB64}`;
-    // Cast to crypto's `JsonWebKey` shape — that type requires an index
-    // signature for arbitrary string keys; our narrow OKP shape doesn't
-    // declare one because the strict shape is more useful at our API
-    // boundary. Cast through `unknown` to silence the structural mismatch
-    // without losing the rest of the type safety on this surface.
-    const privateKey = crypto.createPrivateKey({
-        format: 'jwk',
-        key: privateJwk,
-    });
     // EdDSA over Ed25519 — Node's crypto.sign expects `null` as the
     // digest algorithm because Ed25519 hashes the message internally.
     const signature = crypto.sign(null, Buffer.from(signingInput, 'utf-8'), privateKey);
@@ -205,6 +215,15 @@ export function buildProof(privateJwk, publicJwk, opts) {
  * `sig_invalid` to keep the failure surface narrow.
  */
 export function verifyProof(jws, opts = {}) {
+    return verifyEd25519Proof(jws, opts, DEVICE_PROOF_TYP);
+}
+/**
+ * Verify a DPoP-shaped Ed25519 proof whose header `typ` must equal `typ`.
+ *
+ * @internal See `signEd25519Proof`. `verifyProof` (device identity) and
+ * `verifyDpopProof` (`dpop.ts`, RFC 9449) are the two public doors.
+ */
+export function verifyEd25519Proof(jws, opts, typ) {
     if (typeof jws !== 'string' || jws.length === 0) {
         return { valid: false, reason: 'malformed' };
     }
@@ -225,7 +244,7 @@ export function verifyProof(jws, opts = {}) {
     if (!header || typeof header !== 'object' || header.alg !== 'EdDSA') {
         return { valid: false, reason: 'bad_alg' };
     }
-    if (header.typ !== 'oversky-dpop+jwt') {
+    if (header.typ !== typ) {
         return { valid: false, reason: 'bad_typ' };
     }
     const headerJwk = header.jwk;

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/dpop.d.ts

@@ -0,0 +1,101 @@
+/**
+ * dpop.ts — RFC 9449 proof-of-possession for ACCESS tokens.
+ *
+ * Sibling of `deviceKey.ts`, and deliberately a different protocol on the
+ * wire. A device-identity proof (`typ: oversky-dpop+jwt`, header
+ * `OverSky-DPoP`) proves a daemon holds its ENROLLED key and authorizes
+ * minting/rotating that daemon's families. An access-token proof
+ * (`typ: dpop+jwt`, header `DPoP`) proves the presenter of an access token
+ * holds the key the token is bound to (`cnf.jkt`). The `typ` keeps either
+ * proof from ever verifying as the other.
+ *
+ * Why a SEPARATE key, never the device key (OSK-12020): the access-token key
+ * signs whatever `{htm, htu, ath}` a local caller asks of the daemon's proof
+ * oracle (`/v1/auth/cli-handoff-dpop-proof`). Handing that oracle the device
+ * key would turn it into a signer for the credential that mints families —
+ * one confused-deputy step from the workload asking for a device proof over
+ * `POST /api/daemons/cli-handoff`. A dedicated key carries no authority but
+ * the tokens bound to it, lives only in daemon memory (`createDpopKey` never
+ * exposes the private half), and dies with the family it binds.
+ *
+ * Algorithm: EdDSA / Ed25519, the same primitive as the device key. RFC 9449
+ * lets the server advertise `dpop_signing_alg_values_supported`; ours is
+ * exactly `["EdDSA"]`, and the verifier refuses anything else.
+ */
+import { type DeviceProofClaims, type Ed25519PublicJwk, type VerifyFailureReason } from './deviceKey.js';
+/** RFC 9449 §4.2 — the proof's JOSE header `typ`. */
+export declare const DPOP_PROOF_TYP = "dpop+jwt";
+/** RFC 9449 §4.1 — the request header carrying the proof. */
+export declare const DPOP_HEADER = "DPoP";
+/** Default freshness window, matching the device-proof verifier. */
+export declare const DPOP_MAX_AGE_SECONDS = 60;
+/** Server error codes for a bound token presented without a usable proof. */
+export declare const DPOP_PROOF_REQUIRED = "DPOP_PROOF_REQUIRED";
+export declare const DPOP_PROOF_INVALID = "DPOP_PROOF_INVALID";
+export declare const DPOP_PROOF_VERIFY_UNAVAILABLE = "DPOP_PROOF_VERIFY_UNAVAILABLE";
+/** A proof's claims: RFC 9449's `{htm, htu, iat, jti, ath?}`. */
+export type DpopProofClaims = Pick<DeviceProofClaims, 'htm' | 'htu' | 'iat' | 'jti' | 'ath'>;
+export interface DpopProofRequest {
+    /** HTTP method of the request the proof will accompany. */
+    htm: string;
+    /** Target URI; query and fragment are stripped (RFC 9449 §4.2). */
+    htu: string;
+    /** The access token the proof commits to (hashed into `ath`). Omitted only
+     *  at the token endpoint, where the token does not exist yet. */
+    accessToken?: string;
+    /** Pre-computed `ath`, for a signer that never sees the token itself. */
+    ath?: string;
+    /** Test hooks. */
+    iat?: number;
+    jti?: string;
+}
+/**
+ * An in-memory DPoP key. The private half lives in this closure and nowhere
+ * else: there is no accessor, no serializer, and it is never written to disk.
+ */
+export interface DpopKey {
+    readonly publicJwk: Ed25519PublicJwk;
+    /** RFC 7638 thumbprint — the value a bound token carries as `cnf.jkt`. */
+    readonly thumbprint: string;
+    sign(req: DpopProofRequest): string;
+}
+export declare function createDpopKey(): DpopKey;
+/** RFC 9449 §4.2 htu normalization — identical to the device proof's. */
+export declare function normalizeDpopHtu(url: string): string;
+/** `ath` for an access token: base64url(SHA-256(ascii(token))), RFC 9449 §4.2. */
+export declare function accessTokenHash(accessToken: string): string;
+/** True for a value shaped like an `ath` / `jkt` (43-char base64url SHA-256). */
+export declare function isAth(value: unknown): value is string;
+/** Same shape test, named for the `cnf.jkt` call sites. */
+export declare const isJwkThumbprint: typeof isAth;
+export type DpopVerifyFailureReason = Exclude<VerifyFailureReason, 'rth_mismatch' | 'pin_mismatch'> | 'ath_missing' | 'jkt_mismatch';
+export interface DpopVerifyOptions {
+    expectedHtm: string;
+    expectedHtu: string;
+    /** `ath` the proof must carry. Required for a resource request. */
+    expectedAth?: string;
+    /** Thumbprint the proof's key must have — the token's `cnf.jkt`. */
+    expectedJkt?: string;
+    maxAgeSeconds?: number;
+    clockSkewSeconds?: number;
+    now?: number;
+}
+export type DpopVerifyResult = {
+    valid: true;
+    claims: DpopProofClaims;
+    thumbprint: string;
+    publicJwk: Ed25519PublicJwk;
+} | {
+    valid: false;
+    reason: DpopVerifyFailureReason;
+};
+/**
+ * Verify an RFC 9449 proof: `typ` dpop+jwt, `alg` EdDSA, a well-formed inline
+ * JWK, the signature, iat window, htm, htu, `ath` (when expected) and the
+ * key's thumbprint against `expectedJkt` (when given).
+ *
+ * Replay (`jti`) is NOT checked here — it needs shared state, and the caller
+ * owns that (the API's Redis jti cache). A verifier that claimed to do it in
+ * process memory would be wrong on every multi-replica deployment.
+ */
+export declare function verifyDpopProof(jws: string, opts: DpopVerifyOptions): DpopVerifyResult;