@foldrun/core 10.0.0 → 11.0.0

package/dist/index.d.ts

@@ -33,6 +33,8 @@ export * from "./src/oauth-presets.ts";
 export * from "./src/oauth-token.ts";
 export * from "./src/oauth-discovery.ts";
 export * from "./src/oauth-assertion.ts";
+export * from "./src/oauth-device.ts";
+export * from "./src/oauth-dpop.ts";
 export * from "./src/secret-files.ts";
 export * from "./src/notify.ts";
 export * from "./src/webhook.ts";

package/dist/index.js

@@ -44,6 +44,8 @@ export * from "./src/oauth-presets.js";
 export * from "./src/oauth-token.js";
 export * from "./src/oauth-discovery.js";
 export * from "./src/oauth-assertion.js";
+export * from "./src/oauth-device.js";
+export * from "./src/oauth-dpop.js";
 export * from "./src/secret-files.js";
 export * from "./src/notify.js";
 export * from "./src/webhook.js";

package/dist/src/oauth-capabilities.js

@@ -88,19 +88,23 @@ export const OAUTH_CAPABILITIES = [
     },
     {
         id: "client.device", role: "client", title: "Device authorization", spec: "RFC 8628",
-        status: "planned", note: "Part F: `foldrun connect --device`.",
+        status: "supported", note: "Connect with a code on any device: the Connections form, or `foldrun connect --device`. PKCE is sent with the device grant.",
+        proof: [core("tests/oauth-device.test.ts", "pending, then slow_down"), platform("tests/oauth-connect.test.ts", "device authorization (RFC 8628): started for a saved app"), platform(KC, "device authorization (RFC 8628): started for a saved app, approved by the person at Keycloak"), web("tests/oauth-device-route.test.ts", "start → pending → approved → stored"), cli("tests/cli-connect.test.ts", "connect --device (RFC 8628)")],
     },
     {
         id: "client.token-exchange", role: "client", title: "Token exchange", spec: "RFC 8693",
-        status: "planned", note: "Part I: a `token-exchange` secret kind. Cloud STS is covered today by the keyless identity kind.",
+        status: "supported", note: "A `token-exchange` secret: another secret's live token traded for a narrower one, cached. Cloud STS is covered by the keyless identity kind; a workload identity as the subject is not yet.",
+        proof: [core("tests/oauth-token-exchange.test.ts", "the subject's live token is traded for a narrower one"), platform(KC, "token exchange (RFC 8693)"), cli("tests/cli-connect.test.ts", "--kind token-exchange")],
     },
     {
         id: "client.dpop", role: "client", title: "DPoP sender-constrained tokens", spec: "RFC 9449",
-        status: "planned", note: "Part H: Bluesky/atproto, Okta DPoP.",
+        status: "supported", note: "`dpop: true` on the app (`--dpop`): each connection's own key; the egress proxy signs a proof for every call through a site binding; nonces honoured.",
+        proof: [core("tests/oauth-dpop-mtls.test.ts", "refresh with DPoP"), platform("tests/egress-dpop.test.ts", "a used DPoP connection gives its key"), platform(KC, "DPoP (RFC 9449): a connection made with DPoP gets a bound token"), cli("tests/cli-connect.test.ts", "connect --dpop")],
     },
     {
         id: "client.mtls", role: "client", title: "Mutual-TLS client auth and bound tokens", spec: "RFC 8705",
-        status: "planned", note: "Part H: the client-cert secret at the token endpoint.",
+        status: "supported", note: "`token_auth: tls_client_auth` with the certificate and key; presented to the token URL and, through the egress proxy, on the calls the token is bound to.",
+        proof: [core("tests/oauth-dpop-mtls.test.ts", "tls_client_auth (RFC 8705)"), platform("tests/egress-dpop.test.ts", "a certificate-authenticated connection gives its certificate"), platform(KC, "mutual TLS (RFC 8705)"), cli("tests/cli-connect.test.ts", "--token-auth mtls stores the certificate")],
     },
     {
         id: "client.ciba", role: "client", title: "Client-initiated backchannel authentication", spec: "OpenID CIBA",
@@ -149,7 +153,8 @@ export const OAUTH_CAPABILITIES = [
     },
     {
         id: "server.client-credentials", role: "server", title: "Client credentials for machine clients", spec: "RFC 6749 §4.4",
-        status: "planned", note: "Part G: machine MCP clients an admin registers.",
+        status: "supported", note: "An admin registers a machine client (Settings, or `foldrun mcp clients add`) with a role, workspaces and access; no refresh token; disconnecting it makes it `invalid_client`.",
+        proof: [web("tests/mcp-oauth.test.ts", "machine clients (client credentials, part G)"), web("tests/mcp-oauth.test.ts", "a machine client can sign in with private_key_jwt"), cli("tests/cli-mcp.test.ts", "mcp clients add")],
     },
     {
         id: "server.private-key-jwt", role: "server", title: "Signed client assertion (private_key_jwt)", spec: "RFC 7523 §2.2",

package/dist/src/oauth-device.d.ts

@@ -0,0 +1,53 @@
+import { type TokenClient, type TokenResponse } from "./oauth-token.ts";
+export declare const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+export interface DeviceStart {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    /** The page with the code already in it, when the provider gives one. */
+    verification_uri_complete?: string;
+    /** Seconds the codes live. */
+    expires_in: number;
+    /** Seconds to wait between polls (default 5, RFC 8628 §3.2). */
+    interval: number;
+    /** PKCE for the device grant: sent with every poll. Keycloak requires it
+     *  of an S256 client; a server that does not know it ignores both halves
+     *  (found by the conformance suite). Secret: never shown to the person. */
+    code_verifier: string;
+}
+type Fetcher = (url: string, init: RequestInit) => Promise<Response>;
+/** RFC 8628 §3.1–3.2: ask for a device code and a user code. */
+export declare function startDeviceAuthorization(client: TokenClient & {
+    device_url: string;
+    token_url: string;
+    issuer?: string;
+}, scopes: string, fetcher: Fetcher, extra?: Record<string, string>): Promise<DeviceStart>;
+/** What one poll came to (RFC 8628 §3.5). */
+export type DevicePoll = {
+    status: "approved";
+    token: TokenResponse;
+} | {
+    status: "pending";
+}
+/** The provider asked for a longer wait: add 5 seconds to the interval. */
+ | {
+    status: "slow_down";
+} | {
+    status: "denied";
+    reason: string;
+} | {
+    status: "expired";
+    reason: string;
+};
+/** One token request with the device code. */
+export declare function pollDeviceToken(client: TokenClient & {
+    token_url: string;
+}, deviceCode: string, fetcher: Fetcher, codeVerifier?: string): Promise<DevicePoll>;
+/** Poll until approved, denied or expired, honouring interval and slow_down. */
+export declare function waitForDeviceToken(client: TokenClient & {
+    token_url: string;
+}, start: DeviceStart, fetcher: Fetcher, opts?: {
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}): Promise<TokenResponse>;
+export {};

package/dist/src/oauth-device.js

@@ -0,0 +1,112 @@
+// Device authorization (RFC 8628): connect an account from somewhere with no
+// browser of its own — a terminal over ssh, a server. foldrun asks the
+// provider for a device code, a person opens the provider's page on any
+// device and types the short user code, and foldrun polls the token endpoint
+// until they have said yes (or no, or the code ran out). The grant that
+// comes back is stored like any other: an oauth2 secret.
+//
+// One request each, so a caller can poll its own way: the CLI in a loop,
+// the platform once per dashboard poll.
+import crypto from "node:crypto";
+import { oauthTokenRequest, readTokenResponse } from "./oauth-token.js";
+export const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+/** RFC 8628 §3.1–3.2: ask for a device code and a user code. */
+export async function startDeviceAuthorization(client, scopes, fetcher, extra = {}) {
+    // The client authenticates as at the token endpoint (§3.1); a signed
+    // assertion's aud is the issuer when known, else the token URL.
+    const verifier = crypto.randomBytes(32).toString("base64url");
+    const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
+    const request = oauthTokenRequest(client, { ...extra, ...(scopes.trim() ? { scope: scopes.trim() } : {}), code_challenge: challenge, code_challenge_method: "S256" }, { clientIdInBody: true, audience: client.issuer ?? client.token_url });
+    const res = await fetcher(client.device_url, { method: "POST", headers: request.headers, body: request.body, redirect: "error", signal: AbortSignal.timeout(15_000) });
+    const text = await res.text().catch(() => "");
+    let body = {};
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        body = Object.fromEntries(new URLSearchParams(text));
+    }
+    if (!res.ok || typeof body.device_code !== "string" || typeof body.user_code !== "string") {
+        const why = (body.error_description ?? body.error ?? "no device code in the reply");
+        throw new Error(`the provider refused the device authorization (${res.status}): ${why}`);
+    }
+    // Some providers (Google's older endpoint) say verification_url.
+    const uri = (body.verification_uri ?? body.verification_url);
+    if (typeof uri !== "string" || !/^https?:\/\//.test(uri))
+        throw new Error("the provider gave no verification_uri to send the person to");
+    const num = (v, d) => {
+        const n = typeof v === "number" ? v : typeof v === "string" ? Number(v) : NaN;
+        return Number.isFinite(n) && n > 0 ? n : d;
+    };
+    return {
+        device_code: body.device_code,
+        user_code: body.user_code,
+        verification_uri: uri,
+        ...(typeof body.verification_uri_complete === "string" ? { verification_uri_complete: body.verification_uri_complete } : {}),
+        expires_in: num(body.expires_in, 600),
+        interval: num(body.interval, 5),
+        code_verifier: verifier,
+    };
+}
+/** One token request with the device code. */
+export async function pollDeviceToken(client, deviceCode, fetcher, codeVerifier) {
+    const request = oauthTokenRequest(client, { grant_type: DEVICE_GRANT, device_code: deviceCode, ...(codeVerifier ? { code_verifier: codeVerifier } : {}) }, { audience: client.token_url });
+    const res = await fetcher(client.token_url, { method: "POST", headers: request.headers, body: request.body, redirect: "error", signal: AbortSignal.timeout(15_000) });
+    // A body cut off mid-read throws here, so the caller retries it as the
+    // transport failure it is — never read as an empty refusal (Codex review).
+    const token = readTokenResponse(await res.text(), res.headers.get("content-type") ?? "");
+    if (res.ok && token.access_token)
+        return { status: "approved", token };
+    switch (token.error) {
+        case "authorization_pending": return { status: "pending" };
+        case "slow_down": return { status: "slow_down" };
+        case "access_denied": return { status: "denied", reason: token.error_description ?? "the person said no" };
+        case "expired_token": return { status: "expired", reason: token.error_description ?? "the code ran out before anyone approved it" };
+        default:
+            throw new Error(`the provider refused the device token request (${res.status}): ${token.error_description ?? token.error ?? "no token in the reply"}`);
+    }
+}
+/** A failure of the wire, not of the provider: fetch's TypeError, an abort
+ *  or a timeout. */
+function isTransient(err) {
+    if (err instanceof TypeError)
+        return true;
+    const name = err?.name;
+    return name === "AbortError" || name === "TimeoutError";
+}
+/** Poll until approved, denied or expired, honouring interval and slow_down. */
+export async function waitForDeviceToken(client, start, fetcher, opts = {}) {
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = opts.now ?? Date.now;
+    const deadline = now() + start.expires_in * 1000;
+    let interval = start.interval;
+    // A client that cannot make the request (no key, a bad alg) says so now,
+    // not after ten minutes of retries.
+    oauthTokenRequest(client, { grant_type: DEVICE_GRANT, device_code: start.device_code }, { audience: client.token_url });
+    for (;;) {
+        await sleep(interval * 1000);
+        if (now() > deadline)
+            throw new Error("the code ran out before anyone approved it — run it again");
+        let r;
+        try {
+            r = await pollDeviceToken(client, start.device_code, fetcher, start.code_verifier);
+        }
+        catch (err) {
+            // Only a transport failure — a timeout, a dropped connection — is
+            // retried, less often (RFC 8628 §3.5); anything else is final. The
+            // backoff never polls faster than the interval the provider set.
+            if (!isTransient(err))
+                throw err;
+            interval = interval >= 60 ? interval : Math.min(interval * 2, 60);
+            continue;
+        }
+        if (r.status === "approved")
+            return r.token;
+        if (r.status === "slow_down")
+            interval += 5;
+        else if (r.status === "denied")
+            throw new Error(`the provider says no: ${r.reason}`);
+        else if (r.status === "expired")
+            throw new Error(`${r.reason} — run it again`);
+    }
+}

package/dist/src/oauth-dpop.d.ts

@@ -0,0 +1,33 @@
+/** A new DPoP key for a connection (EC P-256, ES256): the private PEM. */
+export declare function generateDpopKey(): string;
+/** The htu of a request: its URL with no query or fragment (RFC 9449 §4.2). */
+export declare function dpopHtu(url: string): string;
+/** The ath of an access token: base64url of its SHA-256 (RFC 9449 §4.2). */
+export declare function dpopAth(accessToken: string): string;
+/** A DPoP proof for one request. */
+export declare function dpopProof(key: string, req: {
+    htm: string;
+    htu: string;
+    ath?: string;
+    nonce?: string;
+}, nowMs?: number): string;
+/** The JWK thumbprint the server binds a DPoP token to (cnf.jkt). */
+export declare function dpopJkt(key: string): string;
+/** Remember a DPoP-Nonce a response to this connection carried. */
+export declare function noteDpopNonce(url: string, res: {
+    headers: {
+        get(name: string): string | null;
+    };
+}, key: string): void;
+/** The nonce for this connection's next proof to this URL's server, if any. */
+export declare function dpopNonceFor(url: string, key: string): string | undefined;
+/** Whether an answer asks for a (new) nonce: a token endpoint's 400
+ *  use_dpop_nonce, or a resource's 401 with it in WWW-Authenticate. */
+export declare function wantsDpopNonce(res: {
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+}, body?: {
+    error?: string;
+}): boolean;

package/dist/src/oauth-dpop.js

@@ -0,0 +1,85 @@
+// DPoP (RFC 9449): sender-constrained tokens. A connection made with DPoP
+// holds a key of its own; every request to the token endpoint, and every call
+// that uses the access token, carries a fresh proof signed with it — so a
+// token copied off the wire is useless without the key. Bluesky/atproto and
+// Okta's DPoP mode require it.
+//
+// The proof: header { typ: "dpop+jwt", alg, jwk: the public key }, claims
+// { jti, htm, htu (no query or fragment), iat, ath? (SHA-256 of the access
+// token, on resource calls), nonce? (when the server asked for one) }.
+//
+// Where the proofs are made: core's refresh and the platform's code exchange
+// (token requests), and the egress proxy (resource calls) — a DPoP-bound
+// connection is used through a site binding, where the proxy can sign each
+// request; the sandbox never holds the key.
+import crypto from "node:crypto";
+import { algForKey, readPrivateKey, ASSERTION_ALGS } from "./oauth-assertion.js";
+/** A new DPoP key for a connection (EC P-256, ES256): the private PEM. */
+export function generateDpopKey() {
+    return crypto.generateKeyPairSync("ec", { namedCurve: "P-256" }).privateKey.export({ format: "pem", type: "pkcs8" }).toString();
+}
+/** The htu of a request: its URL with no query or fragment (RFC 9449 §4.2). */
+export function dpopHtu(url) {
+    const u = new URL(url);
+    return `${u.origin}${u.pathname}`;
+}
+/** The ath of an access token: base64url of its SHA-256 (RFC 9449 §4.2). */
+export function dpopAth(accessToken) {
+    return crypto.createHash("sha256").update(accessToken).digest("base64url");
+}
+const b64url = (s) => Buffer.from(s).toString("base64url");
+/** A DPoP proof for one request. */
+export function dpopProof(key, req, nowMs = Date.now()) {
+    const k = readPrivateKey(key);
+    const alg = algForKey(k);
+    if (!ASSERTION_ALGS.includes(alg) || alg === "PS256")
+        throw new Error("a DPoP key must be EC P-256/P-384, RSA or Ed25519");
+    const pub = crypto.createPublicKey(k).export({ format: "jwk" });
+    const header = { typ: "dpop+jwt", alg, jwk: pub };
+    const claims = {
+        jti: b64url(crypto.randomBytes(18)),
+        htm: req.htm.toUpperCase(),
+        htu: dpopHtu(req.htu),
+        iat: Math.floor(nowMs / 1000),
+        ...(req.ath ? { ath: req.ath } : {}),
+        ...(req.nonce ? { nonce: req.nonce } : {}),
+    };
+    const input = `${b64url(JSON.stringify(header))}.${b64url(JSON.stringify(claims))}`;
+    const data = Buffer.from(input);
+    const sig = alg === "ES256" ? crypto.sign("sha256", data, { key: k, dsaEncoding: "ieee-p1363" })
+        : alg === "ES384" ? crypto.sign("sha384", data, { key: k, dsaEncoding: "ieee-p1363" })
+            : alg === "EdDSA" ? crypto.sign(null, data, k)
+                : crypto.sign("sha256", data, k);
+    return `${input}.${b64url(sig)}`;
+}
+/** The JWK thumbprint the server binds a DPoP token to (cnf.jkt). */
+export function dpopJkt(key) {
+    const pub = crypto.createPublicKey(readPrivateKey(key)).export({ format: "jwk" });
+    const members = pub.kty === "EC" ? { crv: pub.crv, kty: pub.kty, x: pub.x, y: pub.y } : pub.kty === "RSA" ? { e: pub.e, kty: pub.kty, n: pub.n } : { crv: pub.crv, kty: pub.kty, x: pub.x };
+    return crypto.createHash("sha256").update(JSON.stringify(members)).digest("base64url");
+}
+// Server-provided nonces (RFC 9449 §8, §9), kept per origin and per DPoP
+// key: the last one a server sent to this connection is the one its next
+// proof carries — two connections to one server never overwrite each other's
+// (a server may issue nonces per client; Codex review).
+const nonces = new Map();
+const nonceKey = (url, key) => `${new URL(url).origin} ${dpopJkt(key)}`;
+/** Remember a DPoP-Nonce a response to this connection carried. */
+export function noteDpopNonce(url, res, key) {
+    const n = res.headers.get("dpop-nonce");
+    if (n)
+        nonces.set(nonceKey(url, key), n);
+}
+/** The nonce for this connection's next proof to this URL's server, if any. */
+export function dpopNonceFor(url, key) {
+    return nonces.get(nonceKey(url, key));
+}
+/** Whether an answer asks for a (new) nonce: a token endpoint's 400
+ *  use_dpop_nonce, or a resource's 401 with it in WWW-Authenticate. */
+export function wantsDpopNonce(res, body) {
+    if (!res.headers.get("dpop-nonce"))
+        return false;
+    if (res.status === 400 && body?.error === "use_dpop_nonce")
+        return true;
+    return res.status === 401 && /use_dpop_nonce/.test(res.headers.get("www-authenticate") ?? "");
+}

package/dist/src/oauth-token.d.ts

@@ -1,5 +1,5 @@
 import { type AssertionAlg } from "./oauth-assertion.ts";
-export declare const TOKEN_AUTH_METHODS: readonly ["client_secret_post", "client_secret_basic", "none", "private_key_jwt"];
+export declare const TOKEN_AUTH_METHODS: readonly ["client_secret_post", "client_secret_basic", "none", "private_key_jwt", "tls_client_auth", "self_signed_tls_client_auth"];
 export type TokenAuth = (typeof TOKEN_AUTH_METHODS)[number];
 /** The short spellings a person types (`--token-auth basic`), to the RFC names. */
 export declare function parseTokenAuth(value: string): TokenAuth | null;
@@ -13,6 +13,11 @@ export interface TokenClient {
     client_assertion_kid?: string;
     client_assertion_alg?: AssertionAlg;
     client_assertion_cert?: string;
+    /** tls_client_auth / self_signed_tls_client_auth (RFC 8705): the client
+     *  certificate and key presented on the connection to the token URL. */
+    tls_client_cert?: string;
+    tls_client_key?: string;
+    tls_client_passphrase?: string;
 }
 /** Why a client's token_auth cannot work, or null. */
 export declare function tokenAuthProblem(client: {
@@ -21,6 +26,9 @@ export declare function tokenAuthProblem(client: {
     client_assertion_key?: string;
     client_assertion_alg?: unknown;
     client_assertion_cert?: string;
+    tls_client_cert?: string;
+    tls_client_key?: string;
+    tls_client_passphrase?: string;
 }): string | null;
 /**
  * The headers and body of one token request. `params` is the grant's own

package/dist/src/oauth-token.js

@@ -17,8 +17,9 @@
 //                        secret at all (RFC 7523 §2.2, oauth-assertion.ts)
 //
 // Absent means the old behaviour: the body, with the secret if there is one.
+import crypto from "node:crypto";
 import { ASSERTION_TYPE, assertionKeyProblem, signClientAssertion } from "./oauth-assertion.js";
-export const TOKEN_AUTH_METHODS = ["client_secret_post", "client_secret_basic", "none", "private_key_jwt"];
+export const TOKEN_AUTH_METHODS = ["client_secret_post", "client_secret_basic", "none", "private_key_jwt", "tls_client_auth", "self_signed_tls_client_auth"];
 /** The short spellings a person types (`--token-auth basic`), to the RFC names. */
 export function parseTokenAuth(value) {
     const v = value.trim().toLowerCase();
@@ -30,6 +31,10 @@ export function parseTokenAuth(value) {
         return "client_secret_basic";
     if (v === "jwt" || v === "private-key-jwt" || v === "key")
         return "private_key_jwt";
+    if (v === "mtls" || v === "tls" || v === "cert")
+        return "tls_client_auth";
+    if (v === "self-signed-mtls" || v === "self-signed")
+        return "self_signed_tls_client_auth";
     return null;
 }
 /** Why a client's token_auth cannot work, or null. */
@@ -53,6 +58,20 @@ export function tokenAuthProblem(client) {
             return "token_auth private_key_jwt signs with a key and sends no client_secret — leave the secret empty";
         return assertionKeyProblem(client);
     }
+    if (auth === "tls_client_auth" || auth === "self_signed_tls_client_auth") {
+        if (hasSecret)
+            return `token_auth ${auth} proves the client with its certificate and sends no client_secret — leave the secret empty`;
+        if (!client.tls_client_cert?.trim() || !client.tls_client_key?.trim())
+            return `token_auth ${auth} needs tls_client_cert and tls_client_key (PEM)`;
+        try {
+            const key = crypto.createPrivateKey(client.tls_client_passphrase ? { key: client.tls_client_key, passphrase: client.tls_client_passphrase } : client.tls_client_key);
+            if (!new crypto.X509Certificate(client.tls_client_cert).checkPrivateKey(key))
+                return "tls_client_cert is not the certificate of tls_client_key";
+        }
+        catch {
+            return "tls_client_cert and tls_client_key must be a PEM certificate and its private key";
+        }
+    }
     return null;
 }
 /** The form-urlencoding RFC 6749 Appendix B asks for: space as '+'. */
@@ -93,6 +112,11 @@ opts = {}) {
         if (opts.clientIdInBody)
             form.set("client_id", client.client_id);
     }
+    else if (auth === "tls_client_auth" || auth === "self_signed_tls_client_auth") {
+        // The certificate on the connection is the proof (RFC 8705 §2): the
+        // caller presents tls_client_cert; the body names the client only.
+        form.set("client_id", client.client_id);
+    }
     else if (auth === "private_key_jwt") {
         if (!opts.audience)
             throw new Error("a private_key_jwt request needs the endpoint it goes to (its assertion's aud)");

package/dist/src/platform.d.ts

@@ -183,6 +183,13 @@ export interface PlatformHooks {
      */
     fetchUntrusted(url: string, init?: RequestInit, opts?: {
         maxBytes?: number;
+        clientCert?: {
+            pool: string;
+            identity: string;
+            cert: string;
+            key: string;
+            passphrase?: string;
+        };
     }): Promise<Response>;
     /**
      * May the host call this URL a tenant chose — a provider's base_url,

package/dist/src/secrets.d.ts

@@ -17,7 +17,7 @@ export declare function installKeyMaterial(): string;
 /** How the stored value is used at run time — "oauth2"/"service-account"
  *  are refreshed into live tokens, "file"/"ssh"/"api" are materialised into
  *  the run's scratch. Plain values have no kind. */
-export type SecretKind = "oauth2" | "service-account" | "file" | "ssh" | "api" | "client-cert" | "identity";
+export type SecretKind = "oauth2" | "service-account" | "file" | "ssh" | "api" | "client-cert" | "identity" | "token-exchange";
 interface StoredSecret {
     iv: string;
     tag: string;
@@ -256,6 +256,15 @@ export interface OAuth2Config {
     client_assertion_kid?: string;
     client_assertion_alg?: AssertionAlg;
     client_assertion_cert?: string;
+    /** DPoP (RFC 9449): this connection's own key; token requests and the
+     *  calls that use its token carry proofs signed with it (oauth-dpop.ts). */
+    dpop_key?: string;
+    /** tls_client_auth (RFC 8705): the client certificate and key presented
+     *  to the token URL — and, through the egress proxy, on the calls its
+     *  certificate-bound token is used for. */
+    tls_client_cert?: string;
+    tls_client_key?: string;
+    tls_client_passphrase?: string;
 }
 /** Tries at a token endpoint before a refresh is called failed: the first,
  *  and two more after a short wait, for a network error, a 5xx or a 429. */
@@ -273,7 +282,7 @@ export declare function isOAuth2Value(value: string): boolean;
  * second account with the same names be handed the first one's token
  * (Codex debate, 22 Oct 2026).
  */
-export declare function tokenCacheKey(kind: "oauth2" | "sa", storedValue: string, tenant?: string): string;
+export declare function tokenCacheKey(kind: "oauth2" | "sa" | "tx", storedValue: string, tenant?: string): string;
 /**
  * A provider that rotates refresh tokens (RFC 9700 §2.2.2) answered a refresh
  * with a new one: write it back where the old one is stored — the workspace
@@ -417,6 +426,32 @@ export declare function setClientCertSecret(tenant: string, name: string, config
 export interface IdentityConfig {
     audience: string;
 }
+export declare const TOKEN_EXCHANGE_GRANT = "urn:ietf:params:oauth:grant-type:token-exchange";
+export interface TokenExchangeConfig {
+    token_url: string;
+    client_id: string;
+    client_secret?: string;
+    token_auth?: TokenAuth;
+    client_assertion_key?: string;
+    client_assertion_kid?: string;
+    client_assertion_alg?: AssertionAlg;
+    client_assertion_cert?: string;
+    tls_client_cert?: string;
+    tls_client_key?: string;
+    tls_client_passphrase?: string;
+    /** The secret whose live token is the subject: an oauth2 or service-account
+     *  secret, or a static token. Declared beside this one, or found in the
+     *  vault at the same scope. */
+    subject_secret: string;
+    /** Default urn:ietf:params:oauth:token-type:access_token. */
+    subject_token_type?: string;
+    requested_token_type?: string;
+    audience?: string;
+    resource?: string;
+    scope?: string;
+}
+export declare function setTokenExchangeSecret(tenant: string, name: string, config: TokenExchangeConfig, workspace?: string, limit?: SecretLimit): void;
+export declare function isTokenExchangeValue(value: string): boolean;
 export declare function setIdentitySecret(tenant: string, name: string, config: IdentityConfig, workspace?: string, limit?: SecretLimit): void;
 export declare function isIdentityValue(value: string): boolean;
 export declare function identityOf(value: string): IdentityConfig;