@foldrun/core 9.3.0 → 9.5.0

package/dist/index.d.ts

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

package/dist/index.js

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

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

@@ -0,0 +1,22 @@
+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[];
+}
+export declare const OAUTH_CAPABILITIES: OAuthCapability[];

package/dist/src/oauth-capabilities.js

@@ -0,0 +1,176 @@
+// 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
+const core = (file, test) => ({ repo: "foldrun-core", file, test });
+const platform = (file, test) => ({ repo: "foldrun-platform", file, test });
+const web = (file, test) => ({ repo: "foldrun-web", file, test });
+const cli = (file, test) => ({ repo: "foldrun-cli", file, test });
+const KC = "tests/e2e-oauth-keycloak.test.ts";
+export const OAUTH_CAPABILITIES = [
+    // ------------------------------------------------------------ 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: "planned", note: "Part E: Entra certificates, Okta, FAPI.",
+    },
+    {
+        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: "planned", note: "Part E: apps that declare `jwks` or `jwks_uri`.",
+    },
+    // ------------------------------------------------------------ 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/dist/src/oauth-discovery.d.ts

@@ -0,0 +1,90 @@
+import type { TokenAuth } from "./oauth-token.ts";
+/** What foldrun reads from a metadata document. */
+export interface OAuthServerMetadata {
+    issuer: string;
+    authorization_endpoint?: string;
+    token_endpoint?: string;
+    revocation_endpoint?: string;
+    device_authorization_endpoint?: string;
+    pushed_authorization_request_endpoint?: string;
+    require_pushed_authorization_requests?: boolean;
+    token_endpoint_auth_methods_supported?: string[];
+    code_challenge_methods_supported?: string[];
+    authorization_response_iss_parameter_supported?: boolean;
+    dpop_signing_alg_values_supported?: string[];
+    scopes_supported?: string[];
+    jwks_uri?: string;
+}
+/** A discovered server, as the fields a saved app and an oauth2 secret take. */
+export interface DiscoveredClientConfig {
+    issuer: string;
+    authorize_url?: string;
+    token_url: string;
+    revocation_url?: string;
+    device_url?: string;
+    par_url?: string;
+    /** The server requires PAR: an authorize URL without a request_uri fails. */
+    par_required?: boolean;
+    /** Whether the server sends `iss` with every authorization response
+     *  (RFC 9207): when true, one that comes back without it is refused. */
+    iss_parameter: boolean;
+    /** How the client should authenticate at the token URL, given whether it
+     *  has a secret and what the server supports; absent is the form body. */
+    token_auth?: TokenAuth;
+    /** Where the metadata was read from. */
+    metadata_url: string;
+    metadata: OAuthServerMetadata;
+}
+/** Loopback is exempt: a server on this machine (tests, a local Keycloak)
+ *  crosses no wire for http to leak on. Judged on the parsed URL, never on
+ *  how it starts: `http://localhost:80@evil.example` is evil.example
+ *  (Codex review, 1 Nov 2026). */
+export declare function isSecureUrl(url: string): boolean;
+/** Every URL the metadata may be at, in the order to try. */
+export declare function metadataUrls(issuer: string): string[];
+/** Why an issuer cannot be discovered from, or null. */
+export declare function issuerProblem(issuer: string): string | null;
+type Fetcher = (url: string, init?: RequestInit) => Promise<Response>;
+/**
+ * Read the authorization server's metadata. `fetcher` is how the caller
+ * reaches the network (the platform's SSRF-guarded fetchPublic, the CLI's
+ * fetch). Throws with every place tried when none answers.
+ */
+export declare function fetchOAuthMetadata(issuer: string, fetcher: Fetcher): Promise<{
+    url: string;
+    metadata: OAuthServerMetadata;
+}>;
+/**
+ * What a client config should say for this server. `hasSecret`: the app
+ * has a client secret; `pkce`: false when the caller turned PKCE off;
+ * `tokenAuth`: one the caller chose, which wins over the server's list.
+ */
+export declare function clientConfigFromMetadata(found: {
+    url: string;
+    metadata: OAuthServerMetadata;
+}, opts?: {
+    hasSecret: boolean;
+    pkce?: boolean;
+    tokenAuth?: TokenAuth;
+    needsAuthorize?: boolean;
+}): DiscoveredClientConfig;
+/**
+ * The token_auth to use. A choice the caller made is kept. Otherwise, with a
+ * secret: the form body when the server lists it (what every secret did
+ * before), else Basic — which is also the RFC 8414 default when the server
+ * lists nothing. Without a secret: none (a public client).
+ */
+export declare function pickTokenAuth(supported: unknown, opts: {
+    hasSecret: boolean;
+    tokenAuth?: TokenAuth;
+}): {
+    token_auth?: TokenAuth;
+};
+/** Discover and turn into a client config in one call. */
+export declare function discoverOAuth(issuer: string, fetcher: Fetcher, opts: {
+    hasSecret: boolean;
+    pkce?: boolean;
+    tokenAuth?: TokenAuth;
+    needsAuthorize?: boolean;
+}): Promise<DiscoveredClientConfig>;
+export {};

package/dist/src/oauth-discovery.js

@@ -0,0 +1,168 @@
+// Discovery from an issuer: give foldrun the provider's issuer URL and it
+// reads the authorization server's own metadata (RFC 8414, OpenID Connect
+// Discovery 1.0) instead of a person typing the authorize, token and
+// revocation URLs by hand — where a typo costs a consent, and an endpoint
+// on the wrong host is a mix-up attack waiting to happen.
+//
+// Where the metadata lives, in the order tried (RFC 8414 §3.1 and §5):
+//   https://host/.well-known/oauth-authorization-server{/path}
+//   https://host/.well-known/openid-configuration{/path}
+//   https://host{/path}/.well-known/openid-configuration   (OIDC's own spelling)
+// The document's `issuer` must equal the issuer asked for, exactly (RFC 8414
+// §3.3) — a document that names another issuer is refused, not trusted.
+/** Loopback is exempt: a server on this machine (tests, a local Keycloak)
+ *  crosses no wire for http to leak on. Judged on the parsed URL, never on
+ *  how it starts: `http://localhost:80@evil.example` is evil.example
+ *  (Codex review, 1 Nov 2026). */
+export function isSecureUrl(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (u.username || u.password)
+        return false;
+    if (u.protocol === "https:")
+        return true;
+    return u.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(u.hostname);
+}
+/** Every URL the metadata may be at, in the order to try. */
+export function metadataUrls(issuer) {
+    const u = new URL(issuer);
+    const pathPart = u.pathname.replace(/\/+$/, "");
+    const origin = u.origin;
+    const urls = [
+        `${origin}/.well-known/oauth-authorization-server${pathPart}`,
+        `${origin}/.well-known/openid-configuration${pathPart}`,
+    ];
+    if (pathPart)
+        urls.push(`${origin}${pathPart}/.well-known/openid-configuration`);
+    return [...new Set(urls)];
+}
+/** Why an issuer cannot be discovered from, or null. */
+export function issuerProblem(issuer) {
+    let u;
+    try {
+        u = new URL(issuer);
+    }
+    catch {
+        return "issuer must be a URL, like https://login.example.com";
+    }
+    if (!isSecureUrl(issuer))
+        return "issuer must be https";
+    if (u.search || u.hash)
+        return "issuer has no query or fragment (RFC 8414 §2)";
+    return null;
+}
+/**
+ * Read the authorization server's metadata. `fetcher` is how the caller
+ * reaches the network (the platform's SSRF-guarded fetchPublic, the CLI's
+ * fetch). Throws with every place tried when none answers.
+ */
+export async function fetchOAuthMetadata(issuer, fetcher) {
+    const problem = issuerProblem(issuer);
+    if (problem)
+        throw new Error(problem);
+    const tried = [];
+    for (const url of metadataUrls(issuer)) {
+        let res;
+        try {
+            res = await fetcher(url, { headers: { accept: "application/json" }, redirect: "error", signal: AbortSignal.timeout(10_000) });
+        }
+        catch (err) {
+            tried.push(`${url} (${err instanceof Error ? err.message : String(err)})`);
+            continue;
+        }
+        if (!res.ok) {
+            await res.body?.cancel().catch(() => { });
+            tried.push(`${url} (${res.status})`);
+            continue;
+        }
+        let doc;
+        try {
+            doc = await res.json();
+        }
+        catch {
+            tried.push(`${url} (not JSON)`);
+            continue;
+        }
+        if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+            tried.push(`${url} (not a metadata document)`);
+            continue;
+        }
+        const metadata = doc;
+        // RFC 8414 §3.3: the issuer in the document is the one asked for, or
+        // the document is not used. Trailing-slash differences are not forgiven.
+        if (metadata.issuer !== issuer) {
+            throw new Error(`the metadata at ${url} names the issuer ${JSON.stringify(metadata.issuer ?? null)}, not ${issuer} — refused (RFC 8414 §3.3)`);
+        }
+        return { url, metadata };
+    }
+    throw new Error(`no OAuth metadata for ${issuer} — tried ${tried.join(", ")}`);
+}
+const ENDPOINTS = [
+    "authorization_endpoint", "token_endpoint", "revocation_endpoint",
+    "device_authorization_endpoint", "pushed_authorization_request_endpoint", "jwks_uri",
+];
+/**
+ * What a client config should say for this server. `hasSecret`: the app
+ * has a client secret; `pkce`: false when the caller turned PKCE off;
+ * `tokenAuth`: one the caller chose, which wins over the server's list.
+ */
+export function clientConfigFromMetadata(found, opts = { hasSecret: true }) {
+    const m = found.metadata;
+    for (const k of ENDPOINTS) {
+        const v = m[k];
+        if (v !== undefined && (typeof v !== "string" || !isSecureUrl(v)))
+            throw new Error(`the server's ${k} is not an https URL: ${String(v)}`);
+    }
+    if (!m.token_endpoint)
+        throw new Error(`${m.issuer} publishes no token_endpoint`);
+    if ((opts.needsAuthorize ?? true) && !m.authorization_endpoint)
+        throw new Error(`${m.issuer} publishes no authorization_endpoint — it does not do browser sign-in`);
+    // PKCE S256 is required of every connection (RFC 9700 §2.1.1). A server
+    // that lists its methods and leaves S256 out would ignore our challenge.
+    if (opts.pkce !== false && Array.isArray(m.code_challenge_methods_supported) && !m.code_challenge_methods_supported.includes("S256")) {
+        throw new Error(`${m.issuer} does not support PKCE S256 (it lists ${m.code_challenge_methods_supported.join(", ") || "none"}) — refused; turn PKCE off only if you are sure (--no-pkce)`);
+    }
+    return {
+        issuer: m.issuer,
+        ...(m.authorization_endpoint ? { authorize_url: m.authorization_endpoint } : {}),
+        token_url: m.token_endpoint,
+        ...(m.revocation_endpoint ? { revocation_url: m.revocation_endpoint } : {}),
+        ...(m.device_authorization_endpoint ? { device_url: m.device_authorization_endpoint } : {}),
+        ...(m.pushed_authorization_request_endpoint ? { par_url: m.pushed_authorization_request_endpoint } : {}),
+        ...(m.require_pushed_authorization_requests === true ? { par_required: true } : {}),
+        iss_parameter: m.authorization_response_iss_parameter_supported === true,
+        ...pickTokenAuth(m.token_endpoint_auth_methods_supported, opts),
+        metadata_url: found.url,
+        metadata: m,
+    };
+}
+/**
+ * The token_auth to use. A choice the caller made is kept. Otherwise, with a
+ * secret: the form body when the server lists it (what every secret did
+ * before), else Basic — which is also the RFC 8414 default when the server
+ * lists nothing. Without a secret: none (a public client).
+ */
+export function pickTokenAuth(supported, opts) {
+    if (opts.tokenAuth)
+        return { token_auth: opts.tokenAuth };
+    const list = Array.isArray(supported) ? supported.filter((s) => typeof s === "string") : null;
+    // A public client sends no secret. Not refused when the list leaves out
+    // `none`: Keycloak takes public clients and lists only secret methods,
+    // so the list is not the last word on it (found by the conformance suite).
+    if (!opts.hasSecret)
+        return {};
+    if (list && list.includes("client_secret_post"))
+        return {};
+    if (!list || list.includes("client_secret_basic"))
+        return { token_auth: "client_secret_basic" };
+    throw new Error(`the server takes none of the ways foldrun signs in at its token URL (it lists ${list.join(", ") || "nothing"}; foldrun sends the secret in the form body or as HTTP Basic)`);
+}
+/** Discover and turn into a client config in one call. */
+export async function discoverOAuth(issuer, fetcher, opts) {
+    return clientConfigFromMetadata(await fetchOAuthMetadata(issuer, fetcher), opts);
+}

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

@@ -17,8 +17,13 @@ export declare function tokenAuthProblem(client: {
  * fields (grant_type, code, refresh_token, …); the client's identity is
  * added here, by its token_auth. Fields in `params` named client_id or
  * client_secret are dropped — the method decides those, never an `extra`.
+ * `clientIdInBody`: client_id goes in the form whatever the method — a
+ * 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>): {
+export declare function oauthTokenRequest(client: TokenClient, params: Record<string, string>, opts?: {
+    clientIdInBody?: boolean;
+}): {
     headers: Record<string, string>;
     body: string;
 };

package/dist/src/oauth-token.js

@@ -51,8 +51,11 @@ const formEncode = (s) => new URLSearchParams({ x: s }).toString().slice(2);
  * fields (grant_type, code, refresh_token, …); the client's identity is
  * added here, by its token_auth. Fields in `params` named client_id or
  * client_secret are dropped — the method decides those, never an `extra`.
+ * `clientIdInBody`: client_id goes in the form whatever the method — a
+ * 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) {
+export function oauthTokenRequest(client, params, opts = {}) {
     const problem = tokenAuthProblem(client);
     if (problem)
         throw new Error(problem);
@@ -73,6 +76,8 @@ export function oauthTokenRequest(client, params) {
         // not the body as well.
         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 {
         form.set("client_id", client.client_id);

package/dist/src/secrets.d.ts

@@ -245,6 +245,9 @@ export interface OAuth2Config {
     /** Plain fields the provider returned beside the first token (Salesforce's
      *  instance_url) — kept with the recipe, never a credential. */
     fields?: Record<string, string>;
+    /** The provider's revocation endpoint (RFC 7009): deleting or replacing
+     *  this secret revokes its tokens there (revokeOAuth2). */
+    revocation_url?: 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. */
@@ -271,6 +274,54 @@ export declare function tokenCacheKey(kind: "oauth2" | "sa", storedValue: string
  * older token over a newer one. Returns whether a copy was replaced.
  */
 export declare function replaceOAuth2RefreshToken(tenant: string, name: string, workspace: string | undefined, usedValue: string, refreshToken: string): boolean;
+/** The oauth2 recipe stored at exactly this scope — never the account copy a
+ *  workspace would fall back to: revoking is about the copy being removed. */
+export declare function oauth2ValueAt(tenant: string, name: string, workspace?: string): string | null;
+/**
+ * Another stored secret of this account holds a grant revoking this one could
+ * end: the same refresh token (a copy made by hand, or one rotation reached),
+ * or any grant from the same app (token URL and client id). Providers such as
+ * Google revoke every token of a user's grant to an app together, so deleting
+ * the Ads connection would take down the Search Console one made with the
+ * same app (Codex review, 1 Nov 2026). Such a grant is left alone.
+ */
+export declare function oauthGrantSharedElsewhere(tenant: string, name: string, workspace: string | undefined, refreshToken: string, app?: {
+    token_url: string;
+    client_id: string;
+}): boolean;
+/** What revoking an oauth2 secret's tokens came to. */
+export interface OAuthRevokeResult {
+    /** Nothing was asked: no revocation endpoint; another secret holds the
+     *  same grant or one from the same app; the replacement is from the same
+     *  app (a reconnect: revoking would end the new grant too at providers
+     *  that revoke per app); or the stored recipe could not be read. */
+    skipped?: "no-revocation-url" | "shared-grant" | "same-app" | "unreadable";
+    /** The token types the provider accepted the revocation of. */
+    revoked: ("refresh_token" | "access_token")[];
+    /** Why one failed — reported, never a reason to keep a secret. */
+    error?: string;
+}
+type RevokeFetcher = (url: string, init: RequestInit) => Promise<Response>;
+/**
+ * Revoke what an oauth2 recipe holds at its provider (RFC 7009): the refresh
+ * token, then the access token this process has cached for it. The client
+ * authenticates as at the token URL (its token_auth). A 200 is success —
+ * the RFC answers 200 for a token already invalid too; anything else is
+ * reported in `error`, and the next token is still tried. `replacement`: the
+ * recipe taking this one's place; one from the same app (token URL and client
+ * id) means nothing is revoked, since a provider that revokes per app would
+ * end the new grant with the old.
+ */
+export declare function revokeOAuth2Value(value: string, opts?: {
+    tenant?: string;
+    name?: string;
+    workspace?: string;
+    fetcher?: RevokeFetcher;
+    replacement?: {
+        token_url: string;
+        client_id: string;
+    };
+}): Promise<OAuthRevokeResult>;
 /**
  * Swap every oauth2 recipe in an env map for a live access token. The one
  * async moment in secret resolution, kept out of the sync paths: callers