@foldrun/core 10.0.0 → 11.0.0

package/dist/src/secrets.js

@@ -25,6 +25,7 @@ import { platform } from "./platform.js";
 import { fetchUntrusted } from "./untrusted-fetch.js";
 import { oauthTokenRequest, readTokenResponse, tokenAuthProblem } from "./oauth-token.js";
 import { isSecureUrl } from "./oauth-discovery.js";
+import { dpopProof, dpopNonceFor, noteDpopNonce } from "./oauth-dpop.js";
 /**
  * GCM's auth tag, pinned to its full 16 bytes at every cipher call. Without
  * `authTagLength`, Node accepts whatever length `setAuthTag` is handed — 4, 8,
@@ -41,7 +42,7 @@ const tenantKey = (tenant) => platform.tenantKey(tenant);
 import crypto from "node:crypto";
 import { assertSafeName } from "./store.js";
 import { trimSlashes } from "./paths.js";
-import { SITE } from "./network.js";
+import { SITE, siteCovers } from "./network.js";
 const keyFile = () => path.join(dataRoot(), ".secret-key");
 /**
  * The install's root secret, as text: FOLDRUN_SECRET_KEY when set, else the
@@ -817,8 +818,9 @@ export function setOAuth2Secret(tenant, name, config, workspace, limit = {}) {
     }
     // A public client (PKCE, no secret) refreshes with its client id alone;
     // client credentials are nothing without the secret.
-    if (config.grant_type === "client_credentials" && !config.client_secret?.trim() && config.token_auth !== "private_key_jwt") {
-        throw new Error("oauth2 secret needs client_secret for client_credentials (or token_auth private_key_jwt with a key)");
+    // Client credentials need a proof of the client: a secret, a signing key or a certificate.
+    if (config.grant_type === "client_credentials" && !config.client_secret?.trim() && !["private_key_jwt", "tls_client_auth", "self_signed_tls_client_auth"].includes(config.token_auth ?? "")) {
+        throw new Error("oauth2 secret needs client_secret for client_credentials (or token_auth private_key_jwt with a key, or tls_client_auth with a certificate)");
     }
     if (config.grant_type !== "client_credentials" && !config.refresh_token?.trim()) {
         throw new Error("oauth2 secret needs refresh_token (or grant_type: client_credentials)");
@@ -923,31 +925,55 @@ async function exchange(config, cacheKey) {
         // and the reconnect mail; a 5xx or 429 is the provider busy, retried.
         let res;
         let lastNetwork;
+        let text = "";
+        // A certificate-authenticated client (RFC 8705) presents it on the connection.
+        const clientCert = config.tls_client_cert && config.tls_client_key
+            ? { cert: config.tls_client_cert, key: config.tls_client_key, ...(config.tls_client_passphrase ? { passphrase: config.tls_client_passphrase } : {}) }
+            : undefined;
+        let nonceRetried = false;
         for (let attempt = 0; attempt < OAUTH_REFRESH_TRIES; attempt++) {
             if (attempt)
                 await new Promise((r) => setTimeout(r, oauthRetryDelayMs(attempt)));
             try {
                 const request = build();
+                // DPoP: a fresh proof per try, with the server's nonce when it gave one.
+                const headers = config.dpop_key
+                    ? { ...request.headers, dpop: dpopProof(config.dpop_key, { htm: "POST", htu: config.token_url, ...(dpopNonceFor(config.token_url, config.dpop_key) ? { nonce: dpopNonceFor(config.token_url, config.dpop_key) } : {}) }) }
+                    : request.headers;
                 res = await fetchUntrusted(config.token_url, {
                     method: "POST",
-                    headers: request.headers,
+                    headers,
                     body: request.body,
                     signal: AbortSignal.timeout(15_000),
-                }, { sameOrigin: true });
+                    // A DPoP proof names this URL and method: a redirect would carry it
+                    // somewhere it is not for, so none is followed (Codex review).
+                }, { sameOrigin: true, ...(clientCert ? { clientCert } : {}), ...(config.dpop_key ? { noRedirects: true } : {}) });
             }
             catch (err) {
                 lastNetwork = err;
                 res = undefined;
                 continue;
             }
+            // Read before deciding to retry: the last answer's own words are the
+            // error a person sees when every try is busy (Codex review).
+            text = await res.text().catch(() => "");
             if (res.status === 429 || res.status >= 500)
                 continue;
+            if (config.dpop_key) {
+                noteDpopNonce(config.token_url, res, config.dpop_key);
+                // The server wants a nonce in the proof (RFC 9449 §8): once more, at once.
+                if (!nonceRetried && res.status === 400 && res.headers.get("dpop-nonce") && readTokenResponse(text, res.headers.get("content-type") ?? "").error === "use_dpop_nonce") {
+                    nonceRetried = true;
+                    attempt--;
+                    continue;
+                }
+            }
             break;
         }
         if (!res)
             throw lastNetwork instanceof Error ? lastNetwork : new Error(String(lastNetwork));
         // JSON or form-encoded, Slack's nested user token, expires_in as a string.
-        const payload = readTokenResponse(await res.text().catch(() => ""), res.headers.get("content-type") ?? "");
+        const payload = readTokenResponse(text, res.headers.get("content-type") ?? "");
         if (!res.ok || !payload.access_token) {
             throw new Error(`token refresh failed (${res.status}): ${payload.error_description ?? payload.error ?? "no access_token in the reply"}`);
         }
@@ -1055,7 +1081,9 @@ export async function revokeOAuth2Value(value, opts = {}) {
     }
     // No redirect is followed: a 3xx is not ok, so a revocation endpoint that
     // sends us to a login page is reported, never counted as revoked.
-    const fetcher = opts.fetcher ?? ((url, init) => fetchUntrusted(url, init, { sameOrigin: true, noRedirects: true }));
+    // A certificate-authenticated client (RFC 8705) presents it here too.
+    const clientCert = config.tls_client_cert && config.tls_client_key ? { cert: config.tls_client_cert, key: config.tls_client_key, ...(config.tls_client_passphrase ? { passphrase: config.tls_client_passphrase } : {}) } : undefined;
+    const fetcher = opts.fetcher ?? ((url, init) => fetchUntrusted(url, init, { sameOrigin: true, noRedirects: true, ...(clientCert ? { clientCert } : {}) }));
     const key = tokenCacheKey("oauth2", value, opts.tenant);
     const access = oauthCache.get(key)?.token;
     const tokens = [];
@@ -1144,6 +1172,9 @@ ctx) {
             if (ctx)
                 await platform.noteOAuthRefresh(ctx, name, null).catch(() => undefined);
         }
+        else if (value.startsWith(TOKEN_EXCHANGE_PREFIX)) {
+            out[name] = await materializeTokenExchange(name, value, env, ctx);
+        }
         else if (value.startsWith(SERVICE_ACCOUNT_PREFIX)) {
             let config;
             try {
@@ -1383,6 +1414,116 @@ export function setClientCertSecret(tenant, name, config, workspace, limit = {})
     });
 }
 const IDENTITY_PREFIX = "@identity ";
+// ---------------------------------------------------------------- token exchange
+// Token exchange (RFC 8693): a secret that is not a credential of its own but
+// a recipe for one — present another secret's token (the subject) at a token
+// endpoint and get back a narrower one: another audience, fewer scopes, a
+// token a downstream service accepts. Cached like an oauth2 token; the
+// subject is made live first, the same way it would be on its own.
+export const TOKEN_EXCHANGE_GRANT = "urn:ietf:params:oauth:grant-type:token-exchange";
+const ACCESS_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:access_token";
+const TOKEN_EXCHANGE_PREFIX = "@token-exchange ";
+export function setTokenExchangeSecret(tenant, name, config, workspace, limit = {}) {
+    for (const field of ["token_url", "client_id", "subject_secret"]) {
+        if (typeof config[field] !== "string" || !config[field].trim())
+            throw new Error(`a token-exchange secret needs ${field}`);
+    }
+    if (!SECRET_NAME.test(config.subject_secret))
+        throw new Error("subject_secret is a secret's name, UPPER_SNAKE_CASE");
+    if (config.subject_secret === name)
+        throw new Error("a token exchange cannot be its own subject");
+    if (!isSecureUrl(config.token_url))
+        throw new Error("token_url must be https");
+    for (const k of ["subject_token_type", "requested_token_type", "audience", "resource", "scope"]) {
+        if (config[k] !== undefined && typeof config[k] !== "string")
+            throw new Error(`${k} is a string`);
+    }
+    const authProblem = tokenAuthProblem(config);
+    if (authProblem)
+        throw new Error(`token-exchange secret: ${authProblem}`);
+    setSecret(tenant, name, TOKEN_EXCHANGE_PREFIX + JSON.stringify(config), workspace, "token-exchange", limit);
+}
+export function isTokenExchangeValue(value) {
+    return value.startsWith(TOKEN_EXCHANGE_PREFIX);
+}
+const txCache = new Map();
+const txFlight = new Map();
+async function materializeTokenExchange(name, value, env, ctx) {
+    let config;
+    try {
+        config = JSON.parse(value.slice(TOKEN_EXCHANGE_PREFIX.length));
+    }
+    catch {
+        throw new Error(`secret ${name}: stored token-exchange config is unreadable`);
+    }
+    // The subject: declared beside this secret, else the vault at this scope.
+    const subjectName = config.subject_secret;
+    let subjectValue = env[subjectName];
+    if (subjectValue === undefined && ctx)
+        subjectValue = getSecret(ctx.tenant, subjectName, ctx.workspace)?.value;
+    if (subjectValue === undefined)
+        throw new Error(`secret ${name}: its subject ${subjectName} is not set — declare it in secrets: beside ${name}`);
+    if (isTokenExchangeValue(subjectValue))
+        throw new Error(`secret ${name}: its subject ${subjectName} is itself a token exchange — the subject must be a token`);
+    // Only a token may be sent as the subject: a file, ssh key, header set,
+    // certificate or identity recipe would hand its contents to the token
+    // endpoint (Codex review).
+    for (const p of [FILE_PREFIX, SSH_PREFIX, API_PREFIX, CLIENT_CERT_PREFIX, IDENTITY_PREFIX]) {
+        if (subjectValue.startsWith(p))
+            throw new Error(`secret ${name}: its subject ${subjectName} is a ${p.slice(1).trim()} secret — the subject must be a token (an oauth2, service-account or plain token secret)`);
+    }
+    // A subject bound to sites goes to those sites alone: an exchange whose
+    // token URL is not one of them would carry it elsewhere (Codex review).
+    if (ctx) {
+        const bound = secretSites(ctx.tenant, [subjectName], ctx.workspace)[subjectName] ?? [];
+        const host = new URL(config.token_url).host;
+        if (bound.length && !bound.some((site) => siteCovers(site, host))) {
+            throw new Error(`secret ${name}: its subject ${subjectName} is bound to ${bound.join(", ")} — the exchange's token URL (${host}) is not one of them; bind the subject to it too`);
+        }
+    }
+    const subjectToken = (await materializeSecrets({ [subjectName]: subjectValue }, ctx))[subjectName];
+    // Cached by the recipe and the subject token: a new subject is a new exchange.
+    const key = tokenCacheKey("tx", `${value}\n${crypto.createHash("sha256").update(subjectToken).digest("hex")}`, ctx?.tenant);
+    const hit = txCache.get(key);
+    if (hit && hit.expiresAt > Date.now())
+        return hit.token;
+    const pending = txFlight.get(key);
+    if (pending)
+        return pending;
+    const flight = (async () => {
+        const clientCert = config.tls_client_cert && config.tls_client_key ? { cert: config.tls_client_cert, key: config.tls_client_key, ...(config.tls_client_passphrase ? { passphrase: config.tls_client_passphrase } : {}) } : undefined;
+        const request = oauthTokenRequest(config, {
+            grant_type: TOKEN_EXCHANGE_GRANT,
+            subject_token: subjectToken,
+            subject_token_type: config.subject_token_type ?? ACCESS_TOKEN_TYPE,
+            ...(config.requested_token_type ? { requested_token_type: config.requested_token_type } : {}),
+            ...(config.audience ? { audience: config.audience } : {}),
+            ...(config.resource ? { resource: config.resource } : {}),
+            ...(config.scope ? { scope: config.scope } : {}),
+        }, { audience: config.token_url });
+        const res = await fetchUntrusted(config.token_url, { method: "POST", headers: request.headers, body: request.body, signal: AbortSignal.timeout(15_000) }, { sameOrigin: true, ...(clientCert ? { clientCert } : {}) });
+        const payload = readTokenResponse(await res.text().catch(() => ""), res.headers.get("content-type") ?? "");
+        if (!res.ok || !payload.access_token) {
+            throw new Error(`secret ${name}: the token exchange was refused (${res.status}): ${payload.error_description ?? payload.error ?? "no access_token in the reply"}`);
+        }
+        // Never cached past its life: a minute short of it, or half a short life.
+        const life = payload.expires_in ?? 3600;
+        const ttl = Math.max(0, life - Math.min(60, life / 2)) * 1000;
+        const now = Date.now();
+        for (const [k, v] of txCache)
+            if (v.expiresAt <= now)
+                txCache.delete(k);
+        txCache.set(key, { token: payload.access_token, expiresAt: now + ttl });
+        return payload.access_token;
+    })();
+    txFlight.set(key, flight);
+    try {
+        return await flight;
+    }
+    finally {
+        txFlight.delete(key);
+    }
+}
 export function setIdentitySecret(tenant, name, config, workspace, limit = {}) {
     const audience = typeof config.audience === "string" ? config.audience.trim() : "";
     if (!audience)

package/dist/src/untrusted-fetch.d.ts

@@ -28,4 +28,10 @@ export declare function fetchUntrusted(url: string, init?: RequestInit, opts?: {
      *  caller to treat as the failure it is (a revocation that redirects to
      *  a login page did not revoke anything). */
     noRedirects?: boolean;
+    /** Present this client certificate (mutual TLS, RFC 8705). */
+    clientCert?: {
+        cert: string;
+        key: string;
+        passphrase?: string;
+    };
 }): Promise<Response>;

package/dist/src/untrusted-fetch.js

@@ -20,7 +20,8 @@
 // tier holding it all in memory is the platform's problem, not the tenant's.
 // Past the limit the body errors — a caller never gets the first megabyte
 // passed off as the whole answer.
-import { platform } from "./platform.js";
+import crypto from "node:crypto";
+import { platform, guardsUntrustedUrls } from "./platform.js";
 /** How many redirects one request may follow. fetch's own limit is 20;
  *  nothing a tenant points the platform at needs more than a couple. */
 export const MAX_REDIRECTS = 5;
@@ -80,6 +81,57 @@ export function capBody(res, maxBytes, url) {
     Object.defineProperty(out, "url", { value: res.url });
     return out;
 }
+/** One request with a client certificate, through node's https — a laptop's
+ *  fetch has no way to present one. Redirects are the caller's. */
+async function fetchWithClientCert(url, init, cert, maxBytes) {
+    const https = await import("node:https");
+    const body = init.body === undefined || init.body === null ? undefined : typeof init.body === "string" ? init.body : Buffer.from(await new Response(init.body).arrayBuffer());
+    const headers = {};
+    new Headers(init.headers).forEach((v, k) => (headers[k] = v));
+    // fetch decompresses; node's https does not. Ask for none, and decode one
+    // that comes anyway (Codex review).
+    headers["accept-encoding"] ??= "identity";
+    const zlib = await import("node:zlib");
+    const { pipeline } = await import("node:stream");
+    return new Promise((resolve, reject) => {
+        const r = https.request(url, { method: init.method ?? "GET", headers, cert: cert.cert, key: cert.key, ...(cert.passphrase ? { passphrase: cert.passphrase } : {}), ...(init.signal ? { signal: init.signal } : {}) }, (raw) => {
+            const enc = String(raw.headers["content-encoding"] ?? "").toLowerCase();
+            const decoder = enc === "gzip" || enc === "x-gzip" ? zlib.createGunzip()
+                : enc === "deflate" ? zlib.createInflate()
+                    : enc === "br" ? zlib.createBrotliDecompress()
+                        : null;
+            // pipeline: a reset mid-answer, or a bad compressed stream, rejects;
+            // and one side ending destroys the other (Codex review).
+            const res = decoder ? pipeline(raw, decoder, (err) => { if (err)
+                reject(err); }) : raw;
+            const chunks = [];
+            let size = 0;
+            res.on("data", (c) => {
+                // The read limit holds while reading, not after (Codex review).
+                size += c.length;
+                if (size > maxBytes) {
+                    res.destroy();
+                    raw.destroy();
+                    reject(new Error(`${url}: the answer is larger than ${maxBytes} bytes — not read`));
+                    return;
+                }
+                chunks.push(c);
+            });
+            res.on("end", () => {
+                const h = new Headers();
+                for (const [k, v] of Object.entries(raw.headers))
+                    if (v !== undefined && k !== "content-encoding" && k !== "content-length")
+                        h.set(k, Array.isArray(v) ? v.join(", ") : String(v));
+                resolve(new Response(chunks.length ? Buffer.concat(chunks) : null, { status: raw.statusCode ?? 502, headers: h }));
+            });
+            res.on("error", reject);
+        });
+        r.on("error", reject);
+        if (body !== undefined)
+            r.write(body);
+        r.end();
+    });
+}
 export class RedirectRefused extends Error {
     constructor(message) {
         super(message);
@@ -91,7 +143,15 @@ export async function fetchUntrusted(url, init = {}, opts = {}) {
     let current = url;
     let req = { ...init };
     for (let hop = 0;; hop++) {
-        const res = await platform.fetchUntrusted(current, { ...req, redirect: "manual" }, { maxBytes });
+        const res = opts.clientCert && !guardsUntrustedUrls()
+            // A laptop's plain fetch cannot present a certificate: node's https does.
+            ? await fetchWithClientCert(current, { ...req, redirect: "manual" }, opts.clientCert, maxBytes)
+            : await platform.fetchUntrusted(current, { ...req, redirect: "manual" }, {
+                maxBytes,
+                // A pool per certificate: a connection that presented one client's
+                // certificate is never reused for another's (Codex review).
+                ...(opts.clientCert ? (() => { const fp = crypto.createHash("sha256").update(`${opts.clientCert.cert}\n${opts.clientCert.key}`).digest("hex"); return { clientCert: { pool: `oauth-mtls:${fp}`, identity: fp, ...opts.clientCert } }; })() : {}),
+            });
         const location = REDIRECT.has(res.status) ? res.headers.get("location") : null;
         if (!location || opts.noRedirects)
             return capBody(res, maxBytes, current);
@@ -111,7 +171,8 @@ export async function fetchUntrusted(url, init = {}, opts = {}) {
         }
         const from = new URL(current);
         const crossOrigin = next.origin !== from.origin;
-        if (crossOrigin && opts.sameOrigin) {
+        // A client certificate is a credential too: never carried to another origin.
+        if (crossOrigin && (opts.sameOrigin || opts.clientCert)) {
             throw new RedirectRefused(`${from.origin} redirected to ${next.origin} — not followed: this request carries a credential, and it goes only where it was sent`);
         }
         // fetch's own rewrite: a 303, and a 301/302 answering a POST, is

package/index.ts

@@ -45,6 +45,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "10.0.0",
+  "version": "11.0.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "FSL-1.1-ALv2",
   "type": "module",

package/src/oauth-capabilities.ts

@@ -114,19 +114,23 @@ export const OAUTH_CAPABILITIES: OAuthCapability[] = [
   },
   {
     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",
@@ -175,7 +179,8 @@ export const OAUTH_CAPABILITIES: OAuthCapability[] = [
   },
   {
     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/src/oauth-device.ts

@@ -0,0 +1,149 @@
+// 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, type TokenClient, type TokenResponse } from "./oauth-token.ts";
+
+export 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 async function startDeviceAuthorization(
+  client: TokenClient & { device_url: string; token_url: string; issuer?: string },
+  scopes: string,
+  fetcher: Fetcher,
+  extra: Record<string, string> = {},
+): Promise<DeviceStart> {
+  // 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: Record<string, unknown> = {};
+  try {
+    body = JSON.parse(text) as Record<string, unknown>;
+  } 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") as string;
+    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) as unknown;
+  if (typeof uri !== "string" || !/^https?:\/\//.test(uri)) throw new Error("the provider gave no verification_uri to send the person to");
+  const num = (v: unknown, d: number) => {
+    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,
+  };
+}
+
+/** 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 async function pollDeviceToken(
+  client: TokenClient & { token_url: string },
+  deviceCode: string,
+  fetcher: Fetcher,
+  codeVerifier?: string,
+): Promise<DevicePoll> {
+  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: unknown): boolean {
+  if (err instanceof TypeError) return true;
+  const name = (err as { name?: unknown })?.name;
+  return name === "AbortError" || name === "TimeoutError";
+}
+
+/** Poll until approved, denied or expired, honouring interval and slow_down. */
+export async function waitForDeviceToken(
+  client: TokenClient & { token_url: string },
+  start: DeviceStart,
+  fetcher: Fetcher,
+  opts: { sleep?: (ms: number) => Promise<void>; now?: () => number } = {},
+): Promise<TokenResponse> {
+  const sleep = opts.sleep ?? ((ms: number) => new Promise<void>((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: DevicePoll;
+    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/src/oauth-dpop.ts

@@ -0,0 +1,93 @@
+// 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, type AssertionAlg, type Jwk } from "./oauth-assertion.ts";
+
+/** A new DPoP key for a connection (EC P-256, ES256): the private PEM. */
+export function generateDpopKey(): string {
+  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: string): string {
+  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: string): string {
+  return crypto.createHash("sha256").update(accessToken).digest("base64url");
+}
+
+const b64url = (s: string | Buffer) => Buffer.from(s).toString("base64url");
+
+/** A DPoP proof for one request. */
+export function dpopProof(key: string, req: { htm: string; htu: string; ath?: string; nonce?: string }, nowMs = Date.now()): string {
+  const k = readPrivateKey(key);
+  const alg: AssertionAlg = algForKey(k);
+  if (!(ASSERTION_ALGS as readonly string[]).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" }) as 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: string): string {
+  const pub = crypto.createPublicKey(readPrivateKey(key)).export({ format: "jwk" }) as 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<string, string>();
+const nonceKey = (url: string, key: string) => `${new URL(url).origin} ${dpopJkt(key)}`;
+
+/** Remember a DPoP-Nonce a response to this connection carried. */
+export function noteDpopNonce(url: string, res: { headers: { get(name: string): string | null } }, key: string): void {
+  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: string, key: string): string | undefined {
+  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: { status: number; headers: { get(name: string): string | null } }, body?: { error?: string }): boolean {
+  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") ?? "");
+}