@foldrun/core 9.5.0 → 10.1.0

package/dist/src/secrets.js

@@ -817,8 +817,8 @@ 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()) {
-        throw new Error("oauth2 secret needs client_secret for client_credentials");
+    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)");
     }
     if (config.grant_type !== "client_credentials" && !config.refresh_token?.trim()) {
         throw new Error("oauth2 secret needs refresh_token (or grant_type: client_credentials)");
@@ -908,11 +908,14 @@ async function exchange(config, cacheKey) {
     const flight = (async () => {
         // One builder for every token request (oauth-token.ts): the client's
         // identity goes where its token_auth says, and an `extra` cannot set it.
-        const request = oauthTokenRequest(config, {
+        // Built per try: a private_key_jwt assertion's jti is good once, so a
+        // retry after a lost answer must carry a new one (Codex review).
+        const build = () => oauthTokenRequest(config, {
             grant_type: config.grant_type ?? "refresh_token",
             ...(config.grant_type === "client_credentials" ? {} : { refresh_token: config.refresh_token }),
             ...(config.extra ?? {}),
-        });
+        }, { audience: config.token_url });
+        build(); // a config that cannot make a request says so before any network
         // A network blip is retried; a provider's answer is not. "fetch failed"
         // (a reset, a DNS hiccup, a timeout) failed whole steps on the first try
         // — gbp-desk's Thursday posts, 7 Oct 2026. A 4xx (revoked, wrong client)
@@ -924,6 +927,7 @@ async function exchange(config, cacheKey) {
             if (attempt)
                 await new Promise((r) => setTimeout(r, oauthRetryDelayMs(attempt)));
             try {
+                const request = build();
                 res = await fetchUntrusted(config.token_url, {
                     method: "POST",
                     headers: request.headers,
@@ -1062,7 +1066,7 @@ export async function revokeOAuth2Value(value, opts = {}) {
     const out = { revoked: [] };
     for (const [hint, token] of tokens) {
         try {
-            const request = oauthTokenRequest(config, { token, token_type_hint: hint });
+            const request = oauthTokenRequest(config, { token, token_type_hint: hint }, { audience: config.token_url });
             const res = await fetcher(config.revocation_url, { method: "POST", headers: request.headers, body: request.body, redirect: "error", signal: AbortSignal.timeout(10_000) });
             if (res.ok) {
                 await res.body?.cancel().catch(() => { });

package/index.ts

@@ -44,6 +44,8 @@ export * from "./src/secrets.ts";
 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/secret-files.ts";
 export * from "./src/notify.ts";
 export * from "./src/webhook.ts";

package/package.json

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

package/src/oauth-assertion.ts

@@ -0,0 +1,234 @@
+// Signed client assertions (private_key_jwt, RFC 7523 §2.2 and §3; OIDC Core
+// §9): a client proves itself at a token endpoint by signing a short JWT with
+// its private key instead of sending a secret. What Microsoft Entra
+// certificate credentials, Okta and FAPI providers ask for — and what the MCP
+// server (foldrun-web server/mcp-oauth.ts) accepts from apps that publish a
+// JWKS. Both halves are here so the client and the server read one rule.
+//
+// The assertion: header { alg, typ: "JWT", kid?, x5t?, x5t#S256? }, claims
+// { iss = sub = client_id, aud = the endpoint, jti = random, iat, exp ≤ 5 min }.
+
+import crypto from "node:crypto";
+
+/** A JSON Web Key, as node's crypto reads and writes it. */
+export interface Jwk { kty?: string; crv?: string; x?: string; y?: string; n?: string; e?: string; d?: string; kid?: string; alg?: string; use?: string; [k: string]: unknown }
+
+export const ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+/** The algorithms foldrun signs and accepts. Never `none`, never HMAC. */
+export const ASSERTION_ALGS = ["ES256", "ES384", "RS256", "PS256", "EdDSA"] as const;
+export type AssertionAlg = (typeof ASSERTION_ALGS)[number];
+/** The longest an assertion may live (proposal: ≤ 5 minutes). */
+export const ASSERTION_MAX_SECONDS = 300;
+
+const b64url = (b: Buffer | string) => Buffer.from(b).toString("base64url");
+
+/** The alg a key signs with when none is said: from its type. */
+export function algForKey(key: crypto.KeyObject): AssertionAlg {
+  const t = key.asymmetricKeyType;
+  if (t === "ec") {
+    const crv = key.asymmetricKeyDetails?.namedCurve;
+    if (crv === "prime256v1" || crv === "P-256") return "ES256";
+    if (crv === "secp384r1" || crv === "P-384") return "ES384";
+    throw new Error(`an EC key on ${crv} cannot sign a client assertion — use P-256 or P-384`);
+  }
+  if (t === "rsa") return "RS256";
+  // An RSA-PSS-only key cannot be exported as a JWK (no kid, no public JWK
+  // for the provider): refused here, not at the first token exchange. A
+  // plain RSA key signs PS256 when client_assertion_alg says so.
+  if (t === "rsa-pss") throw new Error("an RSA-PSS-only key is not supported — use a plain RSA key with client_assertion_alg PS256");
+  if (t === "ed25519") return "EdDSA";
+  throw new Error(`a ${t} key cannot sign a client assertion — use EC P-256, RSA or Ed25519`);
+}
+
+/** A private key from PEM (PKCS#8 or traditional) or a private JWK (JSON). */
+export function readPrivateKey(material: string): crypto.KeyObject {
+  const text = material.trim();
+  try {
+    if (text.startsWith("{")) return crypto.createPrivateKey({ key: JSON.parse(text), format: "jwk" });
+    return crypto.createPrivateKey(text);
+  } catch (err) {
+    throw new Error(`the client assertion key is not a private key (PEM or JWK): ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+/** RFC 7638 thumbprint of a public JWK — the default `kid`. */
+export function jwkThumbprint(jwk: Jwk): string {
+  const members: Record<string, unknown> =
+    jwk.kty === "EC" ? { crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y }
+    : jwk.kty === "RSA" ? { e: jwk.e, kty: jwk.kty, n: jwk.n }
+    : { crv: jwk.crv, kty: jwk.kty, x: jwk.x };
+  return b64url(crypto.createHash("sha256").update(JSON.stringify(members)).digest());
+}
+
+/** The public JWK a provider needs to register for a private key. */
+export function publicJwkOf(privateKey: string, opts: { kid?: string; alg?: AssertionAlg } = {}): Jwk & { kid: string; alg: AssertionAlg; use: "sig" } {
+  const key = readPrivateKey(privateKey);
+  const pub = crypto.createPublicKey(key).export({ format: "jwk" }) as Jwk;
+  const alg = opts.alg ?? algForKey(key);
+  return { ...pub, kid: opts.kid ?? ownKid(privateKey) ?? jwkThumbprint(pub), alg, use: "sig" };
+}
+
+/** A new signing key for an app: the private PEM to keep sealed, and the
+ *  public JWK to register with the provider. EC P-256 (ES256) unless asked. */
+export function generateClientKey(alg: "ES256" | "RS256" | "EdDSA" = "ES256"): { privateKey: string; publicJwk: ReturnType<typeof publicJwkOf> } {
+  const pair =
+    alg === "RS256" ? crypto.generateKeyPairSync("rsa", { modulusLength: 2048 })
+    : alg === "EdDSA" ? crypto.generateKeyPairSync("ed25519")
+    : crypto.generateKeyPairSync("ec", { namedCurve: "P-256" });
+  const privateKey = pair.privateKey.export({ format: "pem", type: "pkcs8" }).toString();
+  return { privateKey, publicJwk: publicJwkOf(privateKey, { alg }) };
+}
+
+/** Whether a key can sign (and its public half verify) an alg. */
+function algFits(alg: AssertionAlg, key: crypto.KeyObject): boolean {
+  return algForKey(key) === alg || (alg === "PS256" && key.asymmetricKeyType === "rsa");
+}
+
+/** The kid a private JWK carries itself (the provider registered it by it). */
+function ownKid(material: string): string | undefined {
+  const text = material.trim();
+  if (!text.startsWith("{")) return undefined;
+  try {
+    const kid = (JSON.parse(text) as { kid?: unknown }).kid;
+    return typeof kid === "string" && kid ? kid : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function signBytes(alg: AssertionAlg, data: Buffer, key: crypto.KeyObject): Buffer {
+  switch (alg) {
+    case "ES256": return crypto.sign("sha256", data, { key, dsaEncoding: "ieee-p1363" });
+    case "ES384": return crypto.sign("sha384", data, { key, dsaEncoding: "ieee-p1363" });
+    case "RS256": return crypto.sign("sha256", data, key);
+    case "PS256": return crypto.sign("sha256", data, { key, padding: crypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: 32 });
+    case "EdDSA": return crypto.sign(null, data, key);
+  }
+}
+
+function verifyBytes(alg: AssertionAlg, data: Buffer, sig: Buffer, key: crypto.KeyObject): boolean {
+  switch (alg) {
+    case "ES256": return crypto.verify("sha256", data, { key, dsaEncoding: "ieee-p1363" }, sig);
+    case "ES384": return crypto.verify("sha384", data, { key, dsaEncoding: "ieee-p1363" }, sig);
+    case "RS256": return crypto.verify("sha256", data, key, sig);
+    case "PS256": return crypto.verify("sha256", data, { key, padding: crypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: 32 }, sig);
+    case "EdDSA": return crypto.verify(null, data, key, sig);
+  }
+}
+
+export interface AssertionSigner {
+  client_id: string;
+  /** The private key, PEM or JWK. */
+  client_assertion_key: string;
+  client_assertion_kid?: string;
+  client_assertion_alg?: AssertionAlg;
+  /** The certificate for the key (PEM), when the provider identifies keys by
+   *  it (Microsoft Entra: x5t / x5t#S256 in the header). */
+  client_assertion_cert?: string;
+}
+
+/** Sign a client assertion for `audience` (the endpoint it is sent to). */
+export function signClientAssertion(signer: AssertionSigner, audience: string, nowMs = Date.now()): string {
+  const key = readPrivateKey(signer.client_assertion_key);
+  const alg = signer.client_assertion_alg ?? algForKey(key);
+  if (!(ASSERTION_ALGS as readonly string[]).includes(alg)) throw new Error(`client_assertion_alg must be one of ${ASSERTION_ALGS.join(", ")}`);
+  if (!algFits(alg, key)) throw new Error(`client_assertion_alg ${alg} does not fit this key`);
+  const header: Record<string, string> = { alg, typ: "JWT" };
+  if (signer.client_assertion_cert) {
+    const der = new crypto.X509Certificate(signer.client_assertion_cert).raw;
+    header["x5t#S256"] = b64url(crypto.createHash("sha256").update(der).digest());
+    header.x5t = b64url(crypto.createHash("sha1").update(der).digest());
+  }
+  header.kid = signer.client_assertion_kid ?? ownKid(signer.client_assertion_key) ?? jwkThumbprint(crypto.createPublicKey(key).export({ format: "jwk" }) as Jwk);
+  const iat = Math.floor(nowMs / 1000);
+  const claims = { iss: signer.client_id, sub: signer.client_id, aud: audience, jti: b64url(crypto.randomBytes(18)), iat, nbf: iat, exp: iat + 120 };
+  const input = `${b64url(JSON.stringify(header))}.${b64url(JSON.stringify(claims))}`;
+  return `${input}.${b64url(signBytes(alg, Buffer.from(input), key))}`;
+}
+
+/** Why a signer's key material cannot work, or null. */
+export function assertionKeyProblem(signer: { client_assertion_key?: string; client_assertion_alg?: unknown; client_assertion_cert?: string }): string | null {
+  if (!signer.client_assertion_key?.trim()) return "token_auth private_key_jwt needs a client_assertion_key (a private key, PEM or JWK)";
+  let key: crypto.KeyObject;
+  try {
+    key = readPrivateKey(signer.client_assertion_key);
+    algForKey(key);
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+  if (signer.client_assertion_alg !== undefined) {
+    const alg = String(signer.client_assertion_alg);
+    if (!(ASSERTION_ALGS as readonly string[]).includes(alg)) return `client_assertion_alg must be one of ${ASSERTION_ALGS.join(", ")}`;
+    // The alg must be one this key signs: an RSA key also signs PS256.
+    if (!algFits(alg as AssertionAlg, key)) return `client_assertion_alg ${alg} does not fit this key (a ${key.asymmetricKeyType} key signs ${algForKey(key)})`;
+  }
+  if (signer.client_assertion_cert) {
+    try {
+      const cert = new crypto.X509Certificate(signer.client_assertion_cert);
+      if (!cert.checkPrivateKey(key)) return "client_assertion_cert is not the certificate of client_assertion_key";
+    } catch {
+      return "client_assertion_cert is not a PEM certificate";
+    }
+  }
+  return null;
+}
+
+// ------------------------------------------------------------ the server's half
+
+export interface VerifiedAssertion {
+  jti: string;
+  exp: number;
+}
+
+/**
+ * Check a client assertion presented to `audiences` (the endpoint URL, and
+ * the issuer — RFC 7523 §3 and its successor accept either). `keys` is the
+ * client's public JWKS. Throws with why; returns the jti and exp for the
+ * caller's replay store, which must refuse a jti it has seen before.
+ */
+export function verifyClientAssertion(
+  assertion: string,
+  opts: { clientId: string; audiences: string[]; keys: Jwk[]; nowMs?: number; skewSeconds?: number },
+): VerifiedAssertion {
+  const parts = assertion.split(".");
+  if (parts.length !== 3) throw new Error("the client assertion is not a JWT");
+  let header: { alg?: string; kid?: string; typ?: string };
+  let claims: { iss?: unknown; sub?: unknown; aud?: unknown; exp?: unknown; iat?: unknown; nbf?: unknown; jti?: unknown };
+  try {
+    header = JSON.parse(Buffer.from(parts[0], "base64url").toString("utf8"));
+    claims = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+  } catch {
+    throw new Error("the client assertion is not a JWT");
+  }
+  const alg = header.alg as AssertionAlg;
+  if (!(ASSERTION_ALGS as readonly string[]).includes(alg)) throw new Error(`the client assertion's alg ${JSON.stringify(header.alg)} is not accepted (${ASSERTION_ALGS.join(", ")})`);
+  // A key registered with an alg signs only that alg (RFC 7517 §4.4).
+  const candidates = opts.keys.filter((k) => (!header.kid || k.kid === header.kid) && k.use !== "enc" && (!k.alg || k.alg === alg));
+  if (!candidates.length) throw new Error(`no key${header.kid ? ` with kid ${header.kid}` : ""} in the client's JWKS`);
+  const input = Buffer.from(`${parts[0]}.${parts[1]}`);
+  const sig = Buffer.from(parts[2], "base64url");
+  const good = candidates.some((jwk) => {
+    try {
+      const key = crypto.createPublicKey({ key: jwk, format: "jwk" });
+      // The key's type must be the alg's: an RSA key cannot be presented as ES256.
+      if (!algFits(alg, key)) return false;
+      return verifyBytes(alg, input, sig, key);
+    } catch {
+      return false;
+    }
+  });
+  if (!good) throw new Error("the client assertion's signature does not verify against the client's keys");
+  if (claims.iss !== opts.clientId || claims.sub !== opts.clientId) throw new Error("the client assertion's iss and sub must be the client_id");
+  // Plain string comparison (RFC 7519 §4.1.3): a trailing slash is another audience.
+  const aud = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+  if (!aud.some((a) => typeof a === "string" && opts.audiences.includes(a))) throw new Error(`the client assertion is for ${JSON.stringify(claims.aud)}, not this server`);
+  const now = Math.floor((opts.nowMs ?? Date.now()) / 1000);
+  const skew = opts.skewSeconds ?? 60;
+  if (typeof claims.exp !== "number") throw new Error("the client assertion has no exp");
+  if (claims.exp + skew < now) throw new Error("the client assertion has expired");
+  if (typeof claims.nbf === "number" && claims.nbf - skew > now) throw new Error("the client assertion is not valid yet");
+  const issued = typeof claims.iat === "number" ? claims.iat : now;
+  if (claims.exp - issued > ASSERTION_MAX_SECONDS || claims.exp - now > ASSERTION_MAX_SECONDS + skew) throw new Error(`the client assertion lives longer than ${ASSERTION_MAX_SECONDS} seconds`);
+  if (typeof claims.jti !== "string" || !claims.jti) throw new Error("the client assertion has no jti");
+  return { jti: claims.jti, exp: claims.exp };
+}

package/src/oauth-capabilities.ts

@@ -109,11 +109,13 @@ export const OAUTH_CAPABILITIES: OAuthCapability[] = [
   },
   {
     id: "client.private-key-jwt", role: "client", title: "Signed client assertion (private_key_jwt)", spec: "RFC 7523 §2.2",
-    status: "planned", note: "Part E: Entra certificates, Okta, FAPI.",
+    status: "supported", note: "`token_auth: private_key_jwt` with a key you paste or foldrun makes; a certificate adds Entra's thumbprint. `--token-auth jwt`.",
+    proof: [core("tests/oauth-assertion.test.ts", "an oauth2 secret with private_key_jwt refreshes"), platform("tests/oauth-connect.test.ts", "private_key_jwt: a saved app can have its key made"), platform(KC, "private_key_jwt (RFC 7523): code + PKCE + PAR signed"), cli("tests/cli-connect.test.ts", "connect --token-auth jwt --key-file")],
   },
   {
     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",
@@ -174,11 +176,13 @@ 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",
-    status: "planned", note: "Part E: apps that declare `jwks` or `jwks_uri`.",
+    status: "supported", note: "Apps that register `jwks` or `jwks_uri` sign in with assertions; each `jti` is used once.",
+    proof: [web("tests/mcp-oauth.test.ts", "private_key_jwt (RFC 7523): an app with a JWKS signs in"), core("tests/oauth-assertion.test.ts", "the verifier refuses")],
   },
   // ------------------------------------------------------------ refused, both roles
   {

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-token.ts

@@ -13,10 +13,14 @@
 //                        base64 of the raw pair, which breaks on a secret
 //                        holding ':' or '%'
 //   none                 a public client: client_id in the body, no secret
+//   private_key_jwt      a JWT signed with the client's private key, no
+//                        secret at all (RFC 7523 §2.2, oauth-assertion.ts)
 //
 // Absent means the old behaviour: the body, with the secret if there is one.
 
-export const TOKEN_AUTH_METHODS = ["client_secret_post", "client_secret_basic", "none"] as const;
+import { ASSERTION_TYPE, assertionKeyProblem, signClientAssertion, type AssertionAlg } from "./oauth-assertion.ts";
+
+export const TOKEN_AUTH_METHODS = ["client_secret_post", "client_secret_basic", "none", "private_key_jwt"] as const;
 export type TokenAuth = (typeof TOKEN_AUTH_METHODS)[number];
 
 /** The short spellings a person types (`--token-auth basic`), to the RFC names. */
@@ -25,6 +29,7 @@ export function parseTokenAuth(value: string): TokenAuth | null {
   if ((TOKEN_AUTH_METHODS as readonly string[]).includes(v)) return v as TokenAuth;
   if (v === "post" || v === "body") return "client_secret_post";
   if (v === "basic") return "client_secret_basic";
+  if (v === "jwt" || v === "private-key-jwt" || v === "key") return "private_key_jwt";
   return null;
 }
 
@@ -32,10 +37,16 @@ export interface TokenClient {
   client_id: string;
   client_secret?: string;
   token_auth?: TokenAuth;
+  /** private_key_jwt: the private key (PEM or JWK), its kid and alg, and
+   *  its certificate when the provider names keys by it (oauth-assertion.ts). */
+  client_assertion_key?: string;
+  client_assertion_kid?: string;
+  client_assertion_alg?: AssertionAlg;
+  client_assertion_cert?: string;
 }
 
 /** Why a client's token_auth cannot work, or null. */
-export function tokenAuthProblem(client: { client_secret?: string; token_auth?: unknown }): string | null {
+export function tokenAuthProblem(client: { client_secret?: string; token_auth?: unknown; client_assertion_key?: string; client_assertion_alg?: unknown; client_assertion_cert?: string }): string | null {
   const auth = client.token_auth;
   if (auth === undefined) return null;
   if (typeof auth !== "string" || !(TOKEN_AUTH_METHODS as readonly string[]).includes(auth)) {
@@ -45,6 +56,11 @@ export function tokenAuthProblem(client: { client_secret?: string; token_auth?:
   if (auth === "client_secret_basic" && !hasSecret) return "token_auth client_secret_basic needs a client_secret";
   if (auth === "client_secret_post" && !hasSecret) return "token_auth client_secret_post needs a client_secret — a public app is token_auth none";
   if (auth === "none" && hasSecret) return "token_auth none is a public client — it sends no client_secret; leave the secret empty or pick client_secret_post or client_secret_basic";
+  if (auth === "private_key_jwt") {
+    // One method per request: a signed assertion, never a secret beside it.
+    if (hasSecret) return "token_auth private_key_jwt signs with a key and sends no client_secret — leave the secret empty";
+    return assertionKeyProblem(client);
+  }
   return null;
 }
 
@@ -60,12 +76,18 @@ const formEncode = (s: string) => new URLSearchParams({ x: s }).toString().slice
  * pushed authorization request carries it as a parameter of the request it
  * describes even when the client authenticates with Basic (RFC 9126 §2.1).
  */
-export function oauthTokenRequest(client: TokenClient, params: Record<string, string>, opts: { clientIdInBody?: boolean } = {}): { headers: Record<string, string>; body: string } {
+export function oauthTokenRequest(
+  client: TokenClient,
+  params: Record<string, string>,
+  /** `audience`: the endpoint the request goes to — the `aud` of a
+   *  private_key_jwt assertion (required for that method). */
+  opts: { clientIdInBody?: boolean; audience?: string } = {},
+): { headers: Record<string, string>; body: string } {
   const problem = tokenAuthProblem(client);
   if (problem) throw new Error(problem);
   const form = new URLSearchParams();
   for (const [k, v] of Object.entries(params)) {
-    if (k === "client_id" || k === "client_secret") continue;
+    if (k === "client_id" || k === "client_secret" || k === "client_assertion" || k === "client_assertion_type") continue;
     form.set(k, v);
   }
   const headers: Record<string, string> = {
@@ -80,6 +102,11 @@ export function oauthTokenRequest(client: TokenClient, params: Record<string, st
     const pair = `${formEncode(client.client_id)}:${formEncode(client.client_secret!)}`;
     headers.authorization = `Basic ${Buffer.from(pair, "utf8").toString("base64")}`;
     if (opts.clientIdInBody) 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)");
+    form.set("client_id", client.client_id);
+    form.set("client_assertion_type", ASSERTION_TYPE);
+    form.set("client_assertion", signClientAssertion(client as TokenClient & { client_assertion_key: string }, opts.audience));
   } else {
     form.set("client_id", client.client_id);
     if (auth === "client_secret_post") form.set("client_secret", client.client_secret!);

package/src/secrets.ts

@@ -26,6 +26,7 @@ import { platform } from "./platform.ts";
 import { fetchUntrusted } from "./untrusted-fetch.ts";
 import { oauthTokenRequest, readTokenResponse, tokenAuthProblem, type TokenAuth } from "./oauth-token.ts";
 import { isSecureUrl } from "./oauth-discovery.ts";
+import type { AssertionAlg } from "./oauth-assertion.ts";
 
 /**
  * GCM's auth tag, pinned to its full 16 bytes at every cipher call. Without
@@ -945,6 +946,13 @@ export interface OAuth2Config {
   /** The provider's revocation endpoint (RFC 7009): deleting or replacing
    *  this secret revokes its tokens there (revokeOAuth2). */
   revocation_url?: string;
+  /** token_auth private_key_jwt: the private key (PEM or JWK) the client
+   *  signs its assertions with, sealed with the rest of the recipe; its kid,
+   *  alg, and certificate when the provider names keys by it (Entra). */
+  client_assertion_key?: string;
+  client_assertion_kid?: string;
+  client_assertion_alg?: AssertionAlg;
+  client_assertion_cert?: string;
 }
 
 const OAUTH2_PREFIX = "@oauth2 ";
@@ -970,8 +978,8 @@ export function setOAuth2Secret(
   }
   // 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()) {
-    throw new Error("oauth2 secret needs client_secret for client_credentials");
+  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)");
   }
   if (config.grant_type !== "client_credentials" && !config.refresh_token?.trim()) {
     throw new Error("oauth2 secret needs refresh_token (or grant_type: client_credentials)");
@@ -1068,11 +1076,14 @@ async function exchange(config: OAuth2Config, cacheKey: string): Promise<OAuthLi
   const flight = (async () => {
     // One builder for every token request (oauth-token.ts): the client's
     // identity goes where its token_auth says, and an `extra` cannot set it.
-    const request = oauthTokenRequest(config, {
+    // Built per try: a private_key_jwt assertion's jti is good once, so a
+    // retry after a lost answer must carry a new one (Codex review).
+    const build = () => oauthTokenRequest(config, {
       grant_type: config.grant_type ?? "refresh_token",
       ...(config.grant_type === "client_credentials" ? {} : { refresh_token: config.refresh_token! }),
       ...(config.extra ?? {}),
-    });
+    }, { audience: config.token_url });
+    build(); // a config that cannot make a request says so before any network
     // A network blip is retried; a provider's answer is not. "fetch failed"
     // (a reset, a DNS hiccup, a timeout) failed whole steps on the first try
     // — gbp-desk's Thursday posts, 7 Oct 2026. A 4xx (revoked, wrong client)
@@ -1083,6 +1094,7 @@ async function exchange(config: OAuth2Config, cacheKey: string): Promise<OAuthLi
     for (let attempt = 0; attempt < OAUTH_REFRESH_TRIES; attempt++) {
       if (attempt) await new Promise((r) => setTimeout(r, oauthRetryDelayMs(attempt)));
       try {
+        const request = build();
         res = await fetchUntrusted(config.token_url, {
           method: "POST",
           headers: request.headers,
@@ -1231,7 +1243,7 @@ export async function revokeOAuth2Value(
   const out: OAuthRevokeResult = { revoked: [] };
   for (const [hint, token] of tokens) {
     try {
-      const request = oauthTokenRequest(config, { token, token_type_hint: hint });
+      const request = oauthTokenRequest(config, { token, token_type_hint: hint }, { audience: config.token_url });
       const res = await fetcher(config.revocation_url, { method: "POST", headers: request.headers, body: request.body, redirect: "error", signal: AbortSignal.timeout(10_000) });
       if (res.ok) {
         await res.body?.cancel().catch(() => {});