@foldrun/core 9.5.0 → 10.1.0

package/dist/index.d.ts

@@ -32,6 +32,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/dist/index.js

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

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

@@ -0,0 +1,77 @@
+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 declare const ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+/** The algorithms foldrun signs and accepts. Never `none`, never HMAC. */
+export declare const ASSERTION_ALGS: readonly ["ES256", "ES384", "RS256", "PS256", "EdDSA"];
+export type AssertionAlg = (typeof ASSERTION_ALGS)[number];
+/** The longest an assertion may live (proposal: ≤ 5 minutes). */
+export declare const ASSERTION_MAX_SECONDS = 300;
+/** The alg a key signs with when none is said: from its type. */
+export declare function algForKey(key: crypto.KeyObject): AssertionAlg;
+/** A private key from PEM (PKCS#8 or traditional) or a private JWK (JSON). */
+export declare function readPrivateKey(material: string): crypto.KeyObject;
+/** RFC 7638 thumbprint of a public JWK — the default `kid`. */
+export declare function jwkThumbprint(jwk: Jwk): string;
+/** The public JWK a provider needs to register for a private key. */
+export declare function publicJwkOf(privateKey: string, opts?: {
+    kid?: string;
+    alg?: AssertionAlg;
+}): Jwk & {
+    kid: string;
+    alg: AssertionAlg;
+    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 declare function generateClientKey(alg?: "ES256" | "RS256" | "EdDSA"): {
+    privateKey: string;
+    publicJwk: ReturnType<typeof publicJwkOf>;
+};
+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 declare function signClientAssertion(signer: AssertionSigner, audience: string, nowMs?: number): string;
+/** Why a signer's key material cannot work, or null. */
+export declare function assertionKeyProblem(signer: {
+    client_assertion_key?: string;
+    client_assertion_alg?: unknown;
+    client_assertion_cert?: string;
+}): string | null;
+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 declare function verifyClientAssertion(assertion: string, opts: {
+    clientId: string;
+    audiences: string[];
+    keys: Jwk[];
+    nowMs?: number;
+    skewSeconds?: number;
+}): VerifiedAssertion;

package/dist/src/oauth-assertion.js

@@ -0,0 +1,223 @@
+// 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";
+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"];
+/** The longest an assertion may live (proposal: ≤ 5 minutes). */
+export const ASSERTION_MAX_SECONDS = 300;
+const b64url = (b) => Buffer.from(b).toString("base64url");
+/** The alg a key signs with when none is said: from its type. */
+export function algForKey(key) {
+    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) {
+    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) {
+    const members = 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, opts = {}) {
+    const key = readPrivateKey(privateKey);
+    const pub = crypto.createPublicKey(key).export({ format: "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") {
+    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, key) {
+    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) {
+    const text = material.trim();
+    if (!text.startsWith("{"))
+        return undefined;
+    try {
+        const kid = JSON.parse(text).kid;
+        return typeof kid === "string" && kid ? kid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function signBytes(alg, data, key) {
+    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, data, sig, key) {
+    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);
+    }
+}
+/** Sign a client assertion for `audience` (the endpoint it is sent to). */
+export function signClientAssertion(signer, audience, nowMs = Date.now()) {
+    const key = readPrivateKey(signer.client_assertion_key);
+    const alg = signer.client_assertion_alg ?? algForKey(key);
+    if (!ASSERTION_ALGS.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 = { 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" }));
+    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) {
+    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;
+    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.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, 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;
+}
+/**
+ * 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, opts) {
+    const parts = assertion.split(".");
+    if (parts.length !== 3)
+        throw new Error("the client assertion is not a JWT");
+    let header;
+    let claims;
+    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;
+    if (!ASSERTION_ALGS.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/dist/src/oauth-capabilities.js

@@ -83,11 +83,13 @@ export const OAUTH_CAPABILITIES = [
     },
     {
         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",
@@ -148,11 +150,13 @@ 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",
-        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/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-token.d.ts

@@ -1,4 +1,5 @@
-export declare const TOKEN_AUTH_METHODS: readonly ["client_secret_post", "client_secret_basic", "none"];
+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 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;
@@ -6,11 +7,20 @@ 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 declare function tokenAuthProblem(client: {
     client_secret?: string;
     token_auth?: unknown;
+    client_assertion_key?: string;
+    client_assertion_alg?: unknown;
+    client_assertion_cert?: string;
 }): string | null;
 /**
  * The headers and body of one token request. `params` is the grant's own
@@ -21,8 +31,12 @@ export declare function tokenAuthProblem(client: {
  * 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 declare function oauthTokenRequest(client: TokenClient, params: Record<string, string>, opts?: {
+export declare 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;

package/dist/src/oauth-token.js

@@ -13,9 +13,12 @@
 //                        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"];
+import { ASSERTION_TYPE, assertionKeyProblem, signClientAssertion } from "./oauth-assertion.js";
+export const TOKEN_AUTH_METHODS = ["client_secret_post", "client_secret_basic", "none", "private_key_jwt"];
 /** The short spellings a person types (`--token-auth basic`), to the RFC names. */
 export function parseTokenAuth(value) {
     const v = value.trim().toLowerCase();
@@ -25,6 +28,8 @@ export function parseTokenAuth(value) {
         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;
 }
 /** Why a client's token_auth cannot work, or null. */
@@ -42,6 +47,12 @@ export function tokenAuthProblem(client) {
         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;
 }
 /** The form-urlencoding RFC 6749 Appendix B asks for: space as '+'. */
@@ -55,13 +66,16 @@ const formEncode = (s) => new URLSearchParams({ x: s }).toString().slice(2);
  * 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, params, opts = {}) {
+export function oauthTokenRequest(client, params, 
+/** `audience`: the endpoint the request goes to — the `aud` of a
+ *  private_key_jwt assertion (required for that method). */
+opts = {}) {
     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")
+        if (k === "client_id" || k === "client_secret" || k === "client_assertion" || k === "client_assertion_type")
             continue;
         form.set(k, v);
     }
@@ -79,6 +93,13 @@ export function oauthTokenRequest(client, params, opts = {}) {
         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, opts.audience));
+    }
     else {
         form.set("client_id", client.client_id);
         if (auth === "client_secret_post")

package/dist/src/secrets.d.ts

@@ -1,4 +1,5 @@
 import { type TokenAuth } from "./oauth-token.ts";
+import type { AssertionAlg } from "./oauth-assertion.ts";
 /** Which store a secret came from. */
 export type SecretScope = "account" | "workspace";
 /**
@@ -248,6 +249,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;
 }
 /** 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. */