@foldrun/core 9.3.0 → 9.4.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-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

package/dist/src/secrets.js

@@ -24,6 +24,7 @@ import { dataRoot } from "./paths.js";
 import { platform } from "./platform.js";
 import { fetchUntrusted } from "./untrusted-fetch.js";
 import { oauthTokenRequest, readTokenResponse, tokenAuthProblem } from "./oauth-token.js";
+import { isSecureUrl } from "./oauth-discovery.js";
 /**
  * GCM's auth tag, pinned to its full 16 bytes at every cipher call. Without
  * `authTagLength`, Node accepts whatever length `setAuthTag` is handed — 4, 8,
@@ -822,12 +823,15 @@ export function setOAuth2Secret(tenant, name, config, workspace, limit = {}) {
     if (config.grant_type !== "client_credentials" && !config.refresh_token?.trim()) {
         throw new Error("oauth2 secret needs refresh_token (or grant_type: client_credentials)");
     }
+    if (config.revocation_url !== undefined && (typeof config.revocation_url !== "string" || !isSecureUrl(config.revocation_url))) {
+        throw new Error("revocation_url must be https");
+    }
     const authProblem = tokenAuthProblem(config);
     if (authProblem)
         throw new Error(`oauth2 secret: ${authProblem}`);
     // Loopback is exempt: a token endpoint on this same machine (tests, a
     // local mock, a sidecar) crosses no wire for http to leak on.
-    if (!/^https:\/\//.test(config.token_url) && !/^http:\/\/(127\.0\.0\.1|localhost)[:/]/.test(config.token_url)) {
+    if (!isSecureUrl(config.token_url)) {
         throw new Error("token_url must be https — a refresh token over http is a leaked one");
     }
     setSecret(tenant, name, OAUTH2_PREFIX + JSON.stringify(config), workspace, "oauth2", limit);
@@ -961,6 +965,129 @@ async function exchange(config, cacheKey) {
         oauthFlight.delete(cacheKey);
     }
 }
+// ---------------------------------------------------------------- revocation
+/** 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 function oauth2ValueAt(tenant, name, workspace) {
+    const v = openRecord(tenant, workspace, name, read(tenant, workspace)[name]);
+    return v !== null && isOAuth2Value(v) ? v : null;
+}
+/** The workspaces with a vault file of their own (current and legacy layout). */
+function workspacesWithSecrets(tenant) {
+    const out = new Set();
+    for (const dir of ["workspaces", "projects"]) {
+        const base = path.join(dataRoot(), tenant, dir);
+        let names = [];
+        try {
+            names = fs.readdirSync(base);
+        }
+        catch {
+            continue;
+        }
+        for (const n of names)
+            if (fs.existsSync(path.join(base, n, "secrets.json")))
+                out.add(n);
+    }
+    return [...out];
+}
+/**
+ * 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 function oauthGrantSharedElsewhere(tenant, name, workspace, refreshToken, app) {
+    for (const scope of [undefined, ...workspacesWithSecrets(tenant)]) {
+        for (const [other, rec] of Object.entries(read(tenant, scope))) {
+            if (other === name && scope === workspace)
+                continue;
+            // By the value, not the optional kind tag: a recipe copied with a
+            // plain setSecret is still one materializeSecrets refreshes.
+            const v = openRecord(tenant, scope, other, rec);
+            if (!v || !isOAuth2Value(v))
+                continue;
+            try {
+                const other = JSON.parse(v.slice(OAUTH2_PREFIX.length));
+                if (other.refresh_token === refreshToken)
+                    return true;
+                if (app && other.grant_type !== "client_credentials" && other.token_url === app.token_url && other.client_id === app.client_id)
+                    return true;
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * 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 async function revokeOAuth2Value(value, opts = {}) {
+    let config;
+    try {
+        config = JSON.parse(value.slice(OAUTH2_PREFIX.length));
+    }
+    catch {
+        return { skipped: "unreadable", revoked: [] };
+    }
+    if (!config.revocation_url)
+        return { skipped: "no-revocation-url", revoked: [] };
+    if (opts.replacement && opts.replacement.token_url === config.token_url && opts.replacement.client_id === config.client_id) {
+        return { skipped: "same-app", revoked: [] };
+    }
+    if (config.grant_type !== "client_credentials" && opts.tenant && opts.name
+        && oauthGrantSharedElsewhere(opts.tenant, opts.name, opts.workspace, config.refresh_token ?? "", { token_url: config.token_url, client_id: config.client_id })) {
+        return { skipped: "shared-grant", revoked: [] };
+    }
+    // No redirect is followed: a 3xx is not ok, so a revocation endpoint that
+    // sends us to a login page is reported, never counted as revoked.
+    const fetcher = opts.fetcher ?? ((url, init) => fetchUntrusted(url, init, { sameOrigin: true, noRedirects: true }));
+    const key = tokenCacheKey("oauth2", value, opts.tenant);
+    const access = oauthCache.get(key)?.token;
+    const tokens = [];
+    if (config.grant_type !== "client_credentials" && config.refresh_token)
+        tokens.push(["refresh_token", config.refresh_token]);
+    if (access)
+        tokens.push(["access_token", access]);
+    const out = { revoked: [] };
+    for (const [hint, token] of tokens) {
+        try {
+            const request = oauthTokenRequest(config, { token, token_type_hint: hint });
+            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(() => { });
+                out.revoked.push(hint);
+            }
+            else {
+                // Reported, and the next token is still tried: a provider that will
+                // not revoke refresh tokens may still revoke the access token.
+                const why = readTokenResponse(await res.text().catch(() => ""), res.headers.get("content-type") ?? "");
+                out.error ??= `the provider refused to revoke the ${hint.replace("_", " ")} (${res.status}${why.error ? `: ${why.error_description ?? why.error}` : ""})`;
+            }
+        }
+        catch (err) {
+            out.error ??= `revoking the ${hint.replace("_", " ")} failed: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    // Every entry serving that access token goes: after a rotation the same
+    // token is cached under the recipe before and after it (Codex review).
+    oauthCache.delete(key);
+    if (access)
+        for (const [k, v] of oauthCache)
+            if (v.token === access)
+                oauthCache.delete(k);
+    return out;
+}
 /**
  * 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

package/dist/src/untrusted-fetch.d.ts

@@ -24,4 +24,8 @@ export declare function fetchUntrusted(url: string, init?: RequestInit, opts?: {
     sameOrigin?: boolean;
     /** The most the answer may be, read; MAX_BYTES unless said. */
     maxBytes?: number;
+    /** Follow no redirect at all: a 3xx comes back as the answer, for the
+     *  caller to treat as the failure it is (a revocation that redirects to
+     *  a login page did not revoke anything). */
+    noRedirects?: boolean;
 }): Promise<Response>;

package/dist/src/untrusted-fetch.js

@@ -93,7 +93,7 @@ export async function fetchUntrusted(url, init = {}, opts = {}) {
     for (let hop = 0;; hop++) {
         const res = await platform.fetchUntrusted(current, { ...req, redirect: "manual" }, { maxBytes });
         const location = REDIRECT.has(res.status) ? res.headers.get("location") : null;
-        if (!location)
+        if (!location || opts.noRedirects)
             return capBody(res, maxBytes, current);
         // The body of a redirect is never read; free the socket.
         await res.body?.cancel().catch(() => { });

package/index.ts

@@ -43,6 +43,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/package.json

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

package/src/oauth-discovery.ts

@@ -0,0 +1,208 @@
+// 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.
+
+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 function isSecureUrl(url: string): boolean {
+  let u: URL;
+  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: string): string[] {
+  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: string): string | null {
+  let u: URL;
+  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;
+}
+
+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 async function fetchOAuthMetadata(issuer: string, fetcher: Fetcher): Promise<{ url: string; metadata: OAuthServerMetadata }> {
+  const problem = issuerProblem(issuer);
+  if (problem) throw new Error(problem);
+  const tried: string[] = [];
+  for (const url of metadataUrls(issuer)) {
+    let res: Response;
+    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: unknown;
+    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 as OAuthServerMetadata;
+    // 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",
+] as const;
+
+/**
+ * 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: { url: string; metadata: OAuthServerMetadata },
+  opts: { hasSecret: boolean; pkce?: boolean; tokenAuth?: TokenAuth; needsAuthorize?: boolean } = { hasSecret: true },
+): DiscoveredClientConfig {
+  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: unknown, opts: { hasSecret: boolean; tokenAuth?: TokenAuth }): { token_auth?: TokenAuth } {
+  if (opts.tokenAuth) return { token_auth: opts.tokenAuth };
+  const list = Array.isArray(supported) ? supported.filter((s): s is string => 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: string,
+  fetcher: Fetcher,
+  opts: { hasSecret: boolean; pkce?: boolean; tokenAuth?: TokenAuth; needsAuthorize?: boolean },
+): Promise<DiscoveredClientConfig> {
+  return clientConfigFromMetadata(await fetchOAuthMetadata(issuer, fetcher), opts);
+}

package/src/oauth-token.ts

@@ -56,8 +56,11 @@ const formEncode = (s: string) => new URLSearchParams({ x: s }).toString().slice
  * 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: TokenClient, params: Record<string, string>): { headers: Record<string, string>; body: string } {
+export function oauthTokenRequest(client: TokenClient, params: Record<string, string>, opts: { clientIdInBody?: boolean } = {}): { headers: Record<string, string>; body: string } {
   const problem = tokenAuthProblem(client);
   if (problem) throw new Error(problem);
   const form = new URLSearchParams();
@@ -76,6 +79,7 @@ export function oauthTokenRequest(client: TokenClient, params: Record<string, st
     // 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);
     if (auth === "client_secret_post") form.set("client_secret", client.client_secret!);

package/src/secrets.ts

@@ -25,6 +25,7 @@ import { dataRoot } from "./paths.ts";
 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";
 
 /**
  * GCM's auth tag, pinned to its full 16 bytes at every cipher call. Without
@@ -941,6 +942,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;
 }
 
 const OAUTH2_PREFIX = "@oauth2 ";
@@ -972,11 +976,14 @@ export function setOAuth2Secret(
   if (config.grant_type !== "client_credentials" && !config.refresh_token?.trim()) {
     throw new Error("oauth2 secret needs refresh_token (or grant_type: client_credentials)");
   }
+  if (config.revocation_url !== undefined && (typeof config.revocation_url !== "string" || !isSecureUrl(config.revocation_url))) {
+    throw new Error("revocation_url must be https");
+  }
   const authProblem = tokenAuthProblem(config);
   if (authProblem) throw new Error(`oauth2 secret: ${authProblem}`);
   // Loopback is exempt: a token endpoint on this same machine (tests, a
   // local mock, a sidecar) crosses no wire for http to leak on.
-  if (!/^https:\/\//.test(config.token_url) && !/^http:\/\/(127\.0\.0\.1|localhost)[:/]/.test(config.token_url)) {
+  if (!isSecureUrl(config.token_url)) {
     throw new Error("token_url must be https — a refresh token over http is a leaked one");
   }
   setSecret(tenant, name, OAUTH2_PREFIX + JSON.stringify(config), workspace, "oauth2", limit);
@@ -1117,6 +1124,135 @@ async function exchange(config: OAuth2Config, cacheKey: string): Promise<OAuthLi
   }
 }
 
+// ---------------------------------------------------------------- revocation
+
+/** 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 function oauth2ValueAt(tenant: string, name: string, workspace?: string): string | null {
+  const v = openRecord(tenant, workspace, name, read(tenant, workspace)[name]);
+  return v !== null && isOAuth2Value(v) ? v : null;
+}
+
+/** The workspaces with a vault file of their own (current and legacy layout). */
+function workspacesWithSecrets(tenant: string): string[] {
+  const out = new Set<string>();
+  for (const dir of ["workspaces", "projects"]) {
+    const base = path.join(dataRoot(), tenant, dir);
+    let names: string[] = [];
+    try {
+      names = fs.readdirSync(base);
+    } catch {
+      continue;
+    }
+    for (const n of names) if (fs.existsSync(path.join(base, n, "secrets.json"))) out.add(n);
+  }
+  return [...out];
+}
+
+/**
+ * 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 function oauthGrantSharedElsewhere(tenant: string, name: string, workspace: string | undefined, refreshToken: string, app?: { token_url: string; client_id: string }): boolean {
+  for (const scope of [undefined, ...workspacesWithSecrets(tenant)]) {
+    for (const [other, rec] of Object.entries(read(tenant, scope))) {
+      if (other === name && scope === workspace) continue;
+      // By the value, not the optional kind tag: a recipe copied with a
+      // plain setSecret is still one materializeSecrets refreshes.
+      const v = openRecord(tenant, scope, other, rec);
+      if (!v || !isOAuth2Value(v)) continue;
+      try {
+        const other = JSON.parse(v.slice(OAUTH2_PREFIX.length)) as OAuth2Config;
+        if (other.refresh_token === refreshToken) return true;
+        if (app && other.grant_type !== "client_credentials" && other.token_url === app.token_url && other.client_id === app.client_id) return true;
+      } catch {
+        continue;
+      }
+    }
+  }
+  return false;
+}
+
+/** 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 async function revokeOAuth2Value(
+  value: string,
+  opts: { tenant?: string; name?: string; workspace?: string; fetcher?: RevokeFetcher; replacement?: { token_url: string; client_id: string } } = {},
+): Promise<OAuthRevokeResult> {
+  let config: OAuth2Config;
+  try {
+    config = JSON.parse(value.slice(OAUTH2_PREFIX.length)) as OAuth2Config;
+  } catch {
+    return { skipped: "unreadable", revoked: [] };
+  }
+  if (!config.revocation_url) return { skipped: "no-revocation-url", revoked: [] };
+  if (opts.replacement && opts.replacement.token_url === config.token_url && opts.replacement.client_id === config.client_id) {
+    return { skipped: "same-app", revoked: [] };
+  }
+  if (config.grant_type !== "client_credentials" && opts.tenant && opts.name
+    && oauthGrantSharedElsewhere(opts.tenant, opts.name, opts.workspace, config.refresh_token ?? "", { token_url: config.token_url, client_id: config.client_id })) {
+    return { skipped: "shared-grant", revoked: [] };
+  }
+  // No redirect is followed: a 3xx is not ok, so a revocation endpoint that
+  // sends us to a login page is reported, never counted as revoked.
+  const fetcher: RevokeFetcher = opts.fetcher ?? ((url, init) => fetchUntrusted(url, init, { sameOrigin: true, noRedirects: true }));
+  const key = tokenCacheKey("oauth2", value, opts.tenant);
+  const access = oauthCache.get(key)?.token;
+  const tokens: ["refresh_token" | "access_token", string][] = [];
+  if (config.grant_type !== "client_credentials" && config.refresh_token) tokens.push(["refresh_token", config.refresh_token]);
+  if (access) tokens.push(["access_token", access]);
+  const out: OAuthRevokeResult = { revoked: [] };
+  for (const [hint, token] of tokens) {
+    try {
+      const request = oauthTokenRequest(config, { token, token_type_hint: hint });
+      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(() => {});
+        out.revoked.push(hint);
+      } else {
+        // Reported, and the next token is still tried: a provider that will
+        // not revoke refresh tokens may still revoke the access token.
+        const why = readTokenResponse(await res.text().catch(() => ""), res.headers.get("content-type") ?? "");
+        out.error ??= `the provider refused to revoke the ${hint.replace("_", " ")} (${res.status}${why.error ? `: ${why.error_description ?? why.error}` : ""})`;
+      }
+    } catch (err) {
+      out.error ??= `revoking the ${hint.replace("_", " ")} failed: ${err instanceof Error ? err.message : String(err)}`;
+    }
+  }
+  // Every entry serving that access token goes: after a rotation the same
+  // token is cached under the recipe before and after it (Codex review).
+  oauthCache.delete(key);
+  if (access) for (const [k, v] of oauthCache) if (v.token === access) oauthCache.delete(k);
+  return out;
+}
+
 /**
  * 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

package/src/untrusted-fetch.ts

@@ -104,6 +104,10 @@ export async function fetchUntrusted(
     sameOrigin?: boolean;
     /** The most the answer may be, read; MAX_BYTES unless said. */
     maxBytes?: number;
+    /** Follow no redirect at all: a 3xx comes back as the answer, for the
+     *  caller to treat as the failure it is (a revocation that redirects to
+     *  a login page did not revoke anything). */
+    noRedirects?: boolean;
   } = {},
 ): Promise<Response> {
   const maxBytes = opts.maxBytes ?? MAX_BYTES;
@@ -112,7 +116,7 @@ export async function fetchUntrusted(
   for (let hop = 0; ; hop++) {
     const res = await platform.fetchUntrusted(current, { ...req, redirect: "manual" }, { maxBytes });
     const location = REDIRECT.has(res.status) ? res.headers.get("location") : null;
-    if (!location) return capBody(res, maxBytes, current);
+    if (!location || opts.noRedirects) return capBody(res, maxBytes, current);
     // The body of a redirect is never read; free the socket.
     await res.body?.cancel().catch(() => {});
     if (hop >= MAX_REDIRECTS) throw new RedirectRefused(`${url}: more than ${MAX_REDIRECTS} redirects — not followed`);