@foldrun/core 9.5.0 → 10.0.0

package/dist/index.d.ts

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

package/dist/index.js

@@ -43,6 +43,7 @@ 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/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,7 +83,8 @@ 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",
@@ -152,7 +153,8 @@ export const OAUTH_CAPABILITIES = [
     },
     {
         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-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. */

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,7 @@ 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/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.0.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,7 +109,8 @@ 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",
@@ -178,7 +179,8 @@ export const OAUTH_CAPABILITIES: OAuthCapability[] = [
   },
   {
     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-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(() => {});