@foldrun/core 9.4.0 → 10.0.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,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.4.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

@@ -0,0 +1,204 @@
+// Every kind of OAuth foldrun meets, in each role, and what foldrun does
+// about it: supported (with the tests that prove it), planned, refused (with
+// the reason a person sees), or not needed. The single source the customer
+// page `foldrun-docs/oauth.md` is generated from (`node scripts/oauth-doc.mjs`)
+// — the same pattern as frontmatter-fields.ts. tests/oauth-capabilities.test.ts
+// fails when a supported row names a test that does not exist, or the page is
+// stale.
+//
+// The roles:
+//   client   an agent reaches Google, Slack, a bank — foldrun holds the token
+//   server   an AI app signs in to /api/mcp — foldrun issues the token
+
+export type OAuthRole = "client" | "server";
+export type OAuthStatus = "supported" | "planned" | "refused" | "not-needed";
+
+/** A test that proves a row: the repo, the file in it, and the test's name
+ *  as written (a substring of the title is enough). */
+export interface OAuthProof {
+  repo: "foldrun-core" | "foldrun-platform" | "foldrun-web" | "foldrun-cli";
+  file: string;
+  test: string;
+}
+
+export interface OAuthCapability {
+  id: string;
+  role: OAuthRole;
+  /** What it is, in a person's words. */
+  title: string;
+  /** The RFC or spec that defines it. */
+  spec: string;
+  status: OAuthStatus;
+  /** How to use it (supported), what is coming (planned), or why not. */
+  note: string;
+  proof?: OAuthProof[];
+}
+
+const core = (file: string, test: string): OAuthProof => ({ repo: "foldrun-core", file, test });
+const platform = (file: string, test: string): OAuthProof => ({ repo: "foldrun-platform", file, test });
+const web = (file: string, test: string): OAuthProof => ({ repo: "foldrun-web", file, test });
+const cli = (file: string, test: string): OAuthProof => ({ repo: "foldrun-cli", file, test });
+const KC = "tests/e2e-oauth-keycloak.test.ts";
+
+export const OAUTH_CAPABILITIES: OAuthCapability[] = [
+  // ------------------------------------------------------------ client
+  {
+    id: "client.authorization-code-pkce", role: "client", title: "Authorization code with PKCE (S256)", spec: "RFC 6749 §4.1, RFC 7636",
+    status: "supported", note: "Settings → Connections or `foldrun connect`. PKCE is on for every connection.",
+    proof: [platform("tests/oauth-connect.test.ts", "PKCE: on by default"), platform(KC, "authorization code + PKCE S256 + PAR"), cli("tests/cli-connect.test.ts", "connect: PKCE by default")],
+  },
+  {
+    id: "client.refresh-rotation", role: "client", title: "Refresh, and refresh-token rotation", spec: "RFC 6749 §6, RFC 9700 §2.2.2",
+    status: "supported", note: "Refreshed before every use; a rotated refresh token replaces the stored one.",
+    proof: [core("tests/secret-types.test.ts", "a rotated refresh token is saved where the old one was"), core("tests/oauth-provider-fixtures.test.ts", "rotating refresh tokens: every refresh returns a new one"), platform(KC, "the refresh works and rotates")],
+  },
+  {
+    id: "client.client-credentials", role: "client", title: "Client credentials (machine to machine)", spec: "RFC 6749 §4.4",
+    status: "supported", note: "The \"OAuth — client credentials\" connection, or `foldrun secrets set NAME --kind m2m`.",
+    proof: [platform(KC, "client credentials (machine to machine)")],
+  },
+  {
+    id: "client.secret-post", role: "client", title: "Client secret in the form body", spec: "RFC 6749 §2.3.1",
+    status: "supported", note: "The default (`token_auth: client_secret_post`).",
+    proof: [core("tests/oauth-token.test.ts", "client_secret_post (and absent with a secret)"), platform(KC, "client_secret_post")],
+  },
+  {
+    id: "client.secret-basic", role: "client", title: "Client secret as HTTP Basic", spec: "RFC 6749 §2.3.1",
+    status: "supported", note: "`token_auth: client_secret_basic`, or `--token-auth basic`. Notion, Spotify, Reddit and Zoom need it.",
+    proof: [core("tests/oauth-token.test.ts", "a Basic-only token endpoint"), platform("tests/oauth-connect.test.ts", "token_auth client_secret_basic"), platform(KC, "client_secret_basic"), cli("tests/cli-connect.test.ts", "connect --token-auth basic")],
+  },
+  {
+    id: "client.public", role: "client", title: "Public app (no secret), PKCE only", spec: "RFC 9700 §2.1.1",
+    status: "supported", note: "Leave the client secret empty.",
+    proof: [platform("tests/oauth-connect.test.ts", "a public app (no secret) connects with PKCE"), platform(KC, "a public app (no secret)")],
+  },
+  {
+    id: "client.discovery", role: "client", title: "Metadata discovery from an issuer", spec: "RFC 8414, OpenID Connect Discovery",
+    status: "supported", note: "The Issuer field's Discover, or `--issuer`.",
+    proof: [core("tests/oauth-discovery-revoke.test.ts", "an RFC 8414 server"), core("tests/oauth-discovery-revoke.test.ts", "refused: a document naming another issuer"), platform(KC, "discovery (RFC 8414 / OIDC)"), cli("tests/cli-connect.test.ts", "connect --issuer: the metadata fills the URLs")],
+  },
+  {
+    id: "client.iss-parameter", role: "client", title: "Issuer in the authorization response (mix-up defence)", spec: "RFC 9207",
+    status: "supported", note: "With an issuer, the `iss` that comes back must be it.",
+    proof: [platform("tests/oauth-connect.test.ts", "iss: a pinned issuer must come back exactly"), platform(KC, "a callback whose iss is not the realm is refused"), cli("tests/cli-connect.test.ts", "a callback whose iss is another server is refused")],
+  },
+  {
+    id: "client.revocation", role: "client", title: "Revocation when a connection ends", spec: "RFC 7009",
+    status: "supported", note: "Deleting a connection, or reconnecting it with another app, revokes the old grant.",
+    proof: [core("tests/oauth-discovery-revoke.test.ts", "revoking: the refresh token, then the cached access token"), web("tests/secrets-revoke.test.ts", "deleting revokes"), platform(KC, "revocation (RFC 7009)")],
+  },
+  {
+    id: "client.par", role: "client", title: "Pushed authorization requests", spec: "RFC 9126",
+    status: "supported", note: "Used whenever the provider has a PAR endpoint.",
+    proof: [platform("tests/oauth-connect.test.ts", "PAR (RFC 9126)"), platform(KC, "authorization code + PKCE S256 + PAR"), cli("tests/cli-connect.test.ts", "with a PAR endpoint")],
+  },
+  {
+    id: "client.token-response", role: "client", title: "Token responses as providers send them", spec: "RFC 6749 §5.1",
+    status: "supported", note: "JSON or form-encoded, `expires_in` as a string, Slack's `authed_user`.",
+    proof: [core("tests/oauth-token.test.ts", "Slack: a user token alone"), core("tests/oauth-token.test.ts", "a form-encoded answer"), core("tests/oauth-provider-fixtures.test.ts", "no expires_in; instance_url the agent needs"), core("tests/oauth-provider-fixtures.test.ts", "form-encoded unless asked for JSON")],
+  },
+  {
+    id: "client.jwt-bearer", role: "client", title: "JWT bearer grant (service accounts)", spec: "RFC 7523 §2.1",
+    status: "supported", note: "The service-account connection (`--kind service-account`).",
+    proof: [core("tests/secret-types.test.ts", "service account with a subject")],
+  },
+  {
+    id: "client.rar", role: "client", title: "Rich authorization requests", spec: "RFC 9396",
+    status: "supported", note: "`authorization_details` as an extra authorize parameter (a JSON value).",
+    proof: [platform("tests/oauth-connect.test.ts", "authorization_details (RFC 9396)")],
+  },
+  {
+    id: "client.private-key-jwt", role: "client", title: "Signed client assertion (private_key_jwt)", spec: "RFC 7523 §2.2",
+    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`.",
+  },
+  {
+    id: "client.token-exchange", role: "client", title: "Token exchange", spec: "RFC 8693",
+    status: "planned", note: "Part I: a `token-exchange` secret kind. Cloud STS is covered today by the keyless identity kind.",
+  },
+  {
+    id: "client.dpop", role: "client", title: "DPoP sender-constrained tokens", spec: "RFC 9449",
+    status: "planned", note: "Part H: Bluesky/atproto, Okta DPoP.",
+  },
+  {
+    id: "client.mtls", role: "client", title: "Mutual-TLS client auth and bound tokens", spec: "RFC 8705",
+    status: "planned", note: "Part H: the client-cert secret at the token endpoint.",
+  },
+  {
+    id: "client.ciba", role: "client", title: "Client-initiated backchannel authentication", spec: "OpenID CIBA",
+    status: "not-needed", note: "No provider an agent needs uses it.",
+  },
+  // ------------------------------------------------------------ server (/api/mcp)
+  {
+    id: "server.authorization-code-pkce", role: "server", title: "Authorization code with PKCE (S256)", spec: "OAuth 2.1, MCP authorization",
+    status: "supported", note: "How claude.ai and other AI apps sign in to /api/mcp.",
+    proof: [web("tests/mcp-oauth.test.ts", "the code: PKCE, once, for its own app and redirect"), web("tests/mcp-sdk-oauth.test.ts", "the MCP SDK: 401 → discovery → registration")],
+  },
+  {
+    id: "server.refresh-rotation", role: "server", title: "Refresh rotation, reuse revokes", spec: "OAuth 2.1 §4.3.1",
+    status: "supported", note: "A refresh token used twice ends the connection.",
+    proof: [web("tests/mcp-oauth.test.ts", "refresh rotates; a refresh token used twice ends the connection")],
+  },
+  {
+    id: "server.client-auth", role: "server", title: "Client secret (Basic or body), or a public app", spec: "RFC 6749 §2.3.1",
+    status: "supported", note: "Registered apps choose `none`, `client_secret_post` or `client_secret_basic`.",
+    proof: [web("tests/mcp-oauth.test.ts", "a confidential app proves itself with its secret")],
+  },
+  {
+    id: "server.metadata", role: "server", title: "Authorization server and resource metadata", spec: "RFC 8414, RFC 9728",
+    status: "supported", note: "`/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource`.",
+    proof: [web("tests/mcp-oauth.test.ts", "discovery: the resource names its server")],
+  },
+  {
+    id: "server.registration", role: "server", title: "Dynamic registration and client metadata documents", spec: "RFC 7591, CIMD",
+    status: "supported", note: "An app registers itself, or names itself by an https URL.",
+    proof: [web("tests/mcp-oauth.test.ts", "registration: https or loopback redirect URIs only")],
+  },
+  {
+    id: "server.resource-indicators", role: "server", title: "Resource indicators", spec: "RFC 8707",
+    status: "supported", note: "Tokens are bound to /api/mcp.",
+    proof: [web("tests/mcp-oauth.test.ts", "the access token opens /api/mcp and its tools")],
+  },
+  {
+    id: "server.iss-parameter", role: "server", title: "Issuer in the authorization response", spec: "RFC 9207",
+    status: "supported", note: "Every answer carries `iss`.",
+    proof: [web("tests/mcp-oauth.test.ts", "the approval page's request")],
+  },
+  {
+    id: "server.revocation", role: "server", title: "Revocation endpoint", spec: "RFC 7009",
+    status: "supported", note: "`POST /api/mcp/oauth/revoke`: an app ends its own connection.",
+    proof: [web("tests/mcp-oauth.test.ts", "revocation (RFC 7009): advertised")],
+  },
+  {
+    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.",
+  },
+  {
+    id: "server.private-key-jwt", role: "server", title: "Signed client assertion (private_key_jwt)", spec: "RFC 7523 §2.2",
+    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
+  {
+    id: "refused.implicit", role: "client", title: "Implicit grant", spec: "RFC 9700 §2.1.2",
+    status: "refused", note: "Tokens in the browser's URL leak; OAuth 2.1 removes it.",
+  },
+  {
+    id: "refused.password", role: "client", title: "Resource owner password grant", spec: "RFC 9700 §2.4",
+    status: "refused", note: "foldrun never holds a person's password for another service.",
+  },
+  {
+    id: "refused.pkce-plain", role: "server", title: "PKCE `plain`", spec: "RFC 9700 §2.1.1",
+    status: "refused", note: "Only S256 is accepted: `plain` protects nothing if the request is seen.",
+    proof: [web("tests/mcp-oauth.test.ts", "the approval page's request")],
+  },
+  {
+    id: "refused.wildcard-redirect", role: "server", title: "Wildcard or prefix redirect matching", spec: "RFC 9700 §4.1",
+    status: "refused", note: "Redirect URIs match exactly (a loopback port may vary).",
+    proof: [web("tests/mcp-oauth.test.ts", "the approval page's request")],
+  },
+];

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!);