@slashfi/agents-sdk 0.75.0 → 0.77.0

package/dist/config-store.js

@@ -20,7 +20,7 @@ import { normalizeRef } from "./define-config.js";
 import { createRegistryConsumer } from "./registry-consumer.js";
 import { decryptSecret, encryptSecret } from "./crypto.js";
 import { AdkError } from "./adk-error.js";
-import { discoverOAuthMetadata, dynamicClientRegistration, buildOAuthAuthorizeUrl, exchangeCodeForTokens, } from "./mcp-client.js";
+import { discoverOAuthMetadata, dynamicClientRegistration, buildOAuthAuthorizeUrl, exchangeCodeForTokens, probeRegistryAuth, refreshAccessToken, } from "./mcp-client.js";
 const CONFIG_PATH = "consumer-config.json";
 const SECRET_PREFIX = "secret:";
 // ============================================
@@ -403,15 +403,309 @@ export function createAdk(fs, options = {}) {
         return fallback;
     }
     // ==========================================
+    // Proxy Routing
+    // ==========================================
+    /**
+     * Find the configured RegistryEntry for a ref, consulting `sourceRegistry`
+     * first and falling back to the first registry in config. Returns `null` when
+     * the ref is sourced from a raw URL (no registry), in which case proxy routing
+     * does not apply.
+     */
+    async function findRegistryEntryForRef(entry) {
+        const sourceUrl = entry.sourceRegistry?.url;
+        if (!sourceUrl)
+            return null;
+        const config = await readConfig();
+        const match = (config.registries ?? []).find((r) => {
+            if (typeof r === "string")
+                return r === sourceUrl;
+            return r.url === sourceUrl;
+        });
+        if (!match || typeof match === "string")
+            return null;
+        return match;
+    }
+    /**
+     * Returns the proxy settings for a ref when its source registry has
+     * `proxy` configured. `null` means "run locally".
+     *
+     * Callers pass `{ preferLocal: true }` to opt out of `mode: 'optional'`
+     * proxying when they already hold credentials locally. `mode: 'required'`
+     * cannot be bypassed — the registry owns auth server-side and there is
+     * nothing useful the local SDK can do.
+     */
+    async function resolveProxyForRef(entry, opts) {
+        const reg = await findRegistryEntryForRef(entry);
+        if (!reg?.proxy)
+            return null;
+        if (reg.proxy.mode === "optional" && opts?.preferLocal)
+            return null;
+        return { reg, agent: reg.proxy.agent ?? "@config" };
+    }
+    /**
+     * Forward an `@config ref` operation to the proxy agent on a remote registry.
+     *
+     * The remote side speaks the standard adk-tools surface, so the call shape is
+     * identical to what the local `ref` API would do — the only difference is
+     * that tokens and secrets live server-side. `callRegistry` returns the
+     * standard CallAgentResponse envelope: `{ success: true, result }` on
+     * success or `{ success: false, error }` on failure. We unwrap once and
+     * throw on error so callers get a result that matches the local signature.
+     */
+    async function forwardRefOpToProxy(reg, agent, operation, params) {
+        const consumer = await buildConsumerForRef({ ref: "", sourceRegistry: { url: reg.url, agentPath: agent } });
+        const resolved = consumer.registries().find((r) => r.url === reg.url);
+        if (!resolved)
+            throw new Error(`Registry ${reg.url} not resolvable for proxy forwarding`);
+        const response = await consumer.callRegistry(resolved, {
+            action: "execute_tool",
+            path: agent,
+            tool: "ref",
+            params: { operation, ...params },
+        });
+        if (!response.success) {
+            const errResponse = response;
+            const msg = errResponse.error ?? `Proxy ${agent}.ref(${operation}) failed`;
+            throw new Error(msg);
+        }
+        return response.result;
+    }
+    // ==========================================
     // Registry API
     // ==========================================
+    /**
+     * Encrypt with `secret:` prefix when an encryption key is configured, so the
+     * value is readable by the existing `decryptConfigSecrets` path on the read
+     * side. Plaintext fallback preserves the "no key = dev mode" contract.
+     */
+    async function protectSecret(value) {
+        if (!options.encryptionKey)
+            return value;
+        return `${SECRET_PREFIX}${await encryptSecret(value, options.encryptionKey)}`;
+    }
+    /**
+     * Re-probe a registry with the current stored credentials to see whether it
+     * advertises `capabilities.registry.proxy` in its MCP `initialize` response,
+     * and persist the proxy config when it does. Safe to call after a successful
+     * `auth()` / `authLocal()` — on the add path we skip the proxy probe when
+     * auth is required, so this is the second chance to back-fill it.
+     *
+     * Respects explicit user config: if `proxy` is already set, we leave it
+     * alone. Any discovery failure is swallowed — proxy is an optimization,
+     * not a correctness requirement.
+     */
+    async function discoverProxyAfterAuth(nameOrUrl) {
+        const config = await readConfig();
+        const target = findRegistry(config.registries ?? [], nameOrUrl);
+        if (!target || typeof target === "string")
+            return;
+        if (target.proxy)
+            return;
+        try {
+            const consumer = await buildConsumer(nameOrUrl);
+            const discovered = await consumer.discover(target.url);
+            if (!discovered.proxy?.mode)
+                return;
+            await updateRegistryEntry(nameOrUrl, (existing) => {
+                if (existing.proxy)
+                    return;
+                existing.proxy = {
+                    mode: discovered.proxy.mode,
+                    ...(discovered.proxy.agent && { agent: discovered.proxy.agent }),
+                };
+            });
+        }
+        catch {
+            // Proxy probe is best-effort — auth itself already succeeded.
+        }
+    }
+    /**
+     * Atomic read-modify-write on a registry entry by name or URL. Used by
+     * `authLocal` to persist both `auth` and `oauth` together, which `auth()`
+     * alone can't express. Returns true when the entry was found and written.
+     */
+    async function updateRegistryEntry(nameOrUrl, mutate) {
+        const config = await readConfig();
+        if (!config.registries?.length)
+            return false;
+        let found = false;
+        const registries = config.registries.map((r) => {
+            const rName = registryDisplayName(r);
+            if (rName !== nameOrUrl && registryUrl(r) !== nameOrUrl)
+                return r;
+            found = true;
+            const existing = typeof r === "string" ? { url: r } : { ...r };
+            mutate(existing);
+            return existing;
+        });
+        if (!found)
+            return false;
+        await writeConfig({ ...config, registries });
+        return true;
+    }
+    /**
+     * Decrypt a `secret:`-prefixed value if we hold the encryption key. Plaintext
+     * values pass through unchanged so dev configs keep working.
+     */
+    async function revealSecret(value) {
+        if (!value)
+            return value;
+        if (!value.startsWith(SECRET_PREFIX))
+            return value;
+        if (!options.encryptionKey)
+            return undefined;
+        return decryptSecret(value.slice(SECRET_PREFIX.length), options.encryptionKey);
+    }
+    /**
+     * Refresh a registry's OAuth access token using the stored refresh token.
+     * Persists the new access token (encrypted) and updates `expiresAt`. If the
+     * provider rotates the refresh token, that's encrypted and stored too.
+     * Returns `true` when the refresh succeeded. Callers should catch and fall
+     * back to full re-auth on failure.
+     */
+    async function refreshRegistryToken(nameOrUrl) {
+        const config = await readConfig();
+        const target = findRegistry(config.registries ?? [], nameOrUrl);
+        if (!target || typeof target === "string")
+            return false;
+        const oauth = target.oauth;
+        if (!oauth?.refreshToken || !oauth.tokenEndpoint || !oauth.clientId)
+            return false;
+        const refreshToken = await revealSecret(oauth.refreshToken);
+        const clientSecret = await revealSecret(oauth.clientSecret);
+        if (!refreshToken)
+            return false;
+        const refreshed = await refreshAccessToken(oauth.tokenEndpoint, {
+            refreshToken,
+            clientId: oauth.clientId,
+            ...(clientSecret && { clientSecret }),
+        });
+        const expiresAt = refreshed.expiresIn
+            ? new Date(Date.now() + refreshed.expiresIn * 1000).toISOString()
+            : undefined;
+        const encAccess = await protectSecret(refreshed.accessToken);
+        const encRefresh = refreshed.refreshToken
+            ? await protectSecret(refreshed.refreshToken)
+            : undefined;
+        await updateRegistryEntry(nameOrUrl, (existing) => {
+            existing.auth = { type: "bearer", token: encAccess };
+            if (!existing.oauth)
+                return;
+            if (encRefresh)
+                existing.oauth.refreshToken = encRefresh;
+            if (expiresAt)
+                existing.oauth.expiresAt = expiresAt;
+            else
+                delete existing.oauth.expiresAt;
+        });
+        return true;
+    }
+    /**
+     * Run a registry op once; on 401 (`registry_auth_required`), try to refresh
+     * via the stored refresh token and retry exactly once. Any other AdkError
+     * propagates as-is.
+     */
+    async function callWithRefresh(nameOrUrl, fn) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            if (!(err instanceof AdkError) || err.code !== "registry_auth_required")
+                throw err;
+            let refreshed = false;
+            try {
+                refreshed = await refreshRegistryToken(nameOrUrl);
+            }
+            catch {
+                // Refresh failed — surface the original 401 below.
+            }
+            if (!refreshed)
+                throw err;
+            return fn();
+        }
+    }
+    /**
+     * Throw a typed error if the registry has a recorded auth challenge and
+     * no usable credentials on the entry. Callers should invoke this before
+     * running any op that talks to the registry.
+     */
+    function assertRegistryAuthorized(entry) {
+        if (!entry.authRequirement)
+            return;
+        const hasUsableAuth = entry.auth && entry.auth.type !== "none"
+            ? (entry.auth.type === "bearer" && !!entry.auth.token) ||
+                (entry.auth.type === "api-key" && !!entry.auth.key)
+            : false;
+        if (hasUsableAuth)
+            return;
+        const name = entry.name ?? entry.url;
+        const scope = entry.authRequirement.scopes?.join(" ");
+        throw new AdkError({
+            code: "registry_auth_required",
+            message: `Registry "${name}" requires authentication.`,
+            hint: `Run: adk registry auth ${name} --token <token>${scope ? ` (scopes: ${scope})` : ""}`,
+            details: {
+                url: entry.url,
+                scheme: entry.authRequirement.scheme,
+                realm: entry.authRequirement.realm,
+                authorizationServers: entry.authRequirement.authorizationServers,
+                scopes: entry.authRequirement.scopes,
+                resourceMetadataUrl: entry.authRequirement.resourceMetadataUrl,
+            },
+        });
+    }
     const registry = {
         async add(entry) {
             const config = await readConfig();
             const alias = entry.name ?? entry.url;
             const registries = (config.registries ?? []).filter((r) => registryDisplayName(r) !== alias);
-            registries.push(entry);
+            // Probe the registry before saving. Two things fall out of the probe:
+            //   1. Auth challenge — 401 + WWW-Authenticate points at RFC 9728
+            //      resource metadata; we persist it on `authRequirement` so
+            //      subsequent ops can refuse early with a friendly message.
+            //   2. Proxy capability — the MCP `initialize` response may advertise
+            //      `capabilities.registry.proxy`, which auto-populates `proxy`.
+            // Users who set `proxy` or `auth` explicitly on the entry always win:
+            // discovery only fills in blanks.
+            let final = entry;
+            let authRequirement;
+            const hasUsableAuth = entry.auth && entry.auth.type !== "none"
+                ? (entry.auth.type === "bearer" && !!entry.auth.token) ||
+                    (entry.auth.type === "api-key" && !!entry.auth.key)
+                : false;
+            if (!hasUsableAuth) {
+                const fetchFn = options.fetch ?? globalThis.fetch;
+                const probe = await probeRegistryAuth(entry.url, fetchFn);
+                if (probe.ok === false) {
+                    authRequirement = probe.requirement;
+                    final = { ...final, authRequirement };
+                }
+            }
+            if (!entry.proxy && !authRequirement) {
+                try {
+                    const probeConsumer = await createRegistryConsumer({ registries: [entry], refs: [] }, { token: options.token, fetch: options.fetch });
+                    const resolved = probeConsumer.registries()[0];
+                    if (resolved) {
+                        const discovered = await probeConsumer.discover(resolved.url);
+                        if (discovered.proxy?.mode) {
+                            final = {
+                                ...final,
+                                proxy: {
+                                    mode: discovered.proxy.mode,
+                                    ...(discovered.proxy.agent && { agent: discovered.proxy.agent }),
+                                },
+                            };
+                        }
+                    }
+                }
+                catch {
+                    // Discovery is best-effort — offline, unreachable, or non-adk
+                    // registries simply skip proxy auto-configuration.
+                }
+            }
+            registries.push(final);
             await writeConfig({ ...config, registries });
+            return authRequirement ? { authRequirement } : {};
         },
         async remove(nameOrUrl) {
             const config = await readConfig();
@@ -454,6 +748,8 @@ export function createAdk(fs, options = {}) {
                     existing.auth = updates.auth;
                 if (updates.headers)
                     existing.headers = { ...existing.headers, ...updates.headers };
+                if (updates.proxy !== undefined)
+                    existing.proxy = updates.proxy;
                 return existing;
             });
             if (!found)
@@ -462,18 +758,26 @@ export function createAdk(fs, options = {}) {
             return true;
         },
         async browse(name, query) {
-            const consumer = await buildConsumer(name);
             const config = await readConfig();
             const target = findRegistry(config.registries ?? [], name);
-            const url = target ? registryUrl(target) : name;
-            return consumer.browse(url, query);
+            if (target && typeof target !== "string")
+                assertRegistryAuthorized(target);
+            return callWithRefresh(name, async () => {
+                const consumer = await buildConsumer(name);
+                const url = target ? registryUrl(target) : name;
+                return consumer.browse(url, query);
+            });
         },
         async inspect(name) {
-            const consumer = await buildConsumer(name);
             const config = await readConfig();
             const target = findRegistry(config.registries ?? [], name);
-            const url = target ? registryUrl(target) : name;
-            return consumer.discover(url);
+            if (target && typeof target !== "string")
+                assertRegistryAuthorized(target);
+            return callWithRefresh(name, async () => {
+                const consumer = await buildConsumer(name);
+                const url = target ? registryUrl(target) : name;
+                return consumer.discover(url);
+            });
         },
         async test(name) {
             const config = await readConfig();
@@ -484,9 +788,28 @@ export function createAdk(fs, options = {}) {
             const results = await Promise.allSettled(targets.map(async (r) => {
                 const url = registryUrl(r);
                 const rName = registryDisplayName(r);
+                if (typeof r !== "string" && r.authRequirement) {
+                    const hasUsableAuth = r.auth && r.auth.type !== "none"
+                        ? (r.auth.type === "bearer" && !!r.auth.token) ||
+                            (r.auth.type === "api-key" && !!r.auth.key)
+                        : false;
+                    if (!hasUsableAuth) {
+                        return {
+                            name: rName,
+                            url,
+                            status: "error",
+                            error: `auth required — run: adk registry auth ${rName} --token <token>`,
+                        };
+                    }
+                }
                 try {
-                    const consumer = await createRegistryConsumer({ registries: [r] }, { token: options.token, fetch: options.fetch });
-                    const disc = await consumer.discover(url);
+                    // Route through buildConsumer so encrypted auth/headers get
+                    // decrypted, then use callWithRefresh so a 401 triggers the
+                    // stored refresh token before giving up.
+                    const disc = await callWithRefresh(rName, async () => {
+                        const consumer = await buildConsumer(rName);
+                        return consumer.discover(url);
+                    });
                     return { name: rName, url, status: "active", issuer: disc.issuer };
                 }
                 catch (err) {
@@ -498,6 +821,259 @@ export function createAdk(fs, options = {}) {
                 ? r.value
                 : { name: "unknown", url: "unknown", status: "error", error: "unknown" });
         },
+        async auth(nameOrUrl, credential) {
+            // Encrypt the secret value up-front so the write path is uniform;
+            // `buildConsumer` decrypts on the read side via `decryptConfigSecrets`.
+            const protectedValue = "token" in credential
+                ? await protectSecret(credential.token)
+                : await protectSecret(credential.apiKey);
+            const updated = await updateRegistryEntry(nameOrUrl, (existing) => {
+                if ("token" in credential) {
+                    existing.auth = {
+                        type: "bearer",
+                        token: protectedValue,
+                        ...(credential.tokenUrl && { tokenUrl: credential.tokenUrl }),
+                    };
+                }
+                else {
+                    existing.auth = {
+                        type: "api-key",
+                        key: protectedValue,
+                        ...(credential.header && { header: credential.header }),
+                    };
+                }
+                delete existing.authRequirement;
+            });
+            if (updated)
+                await discoverProxyAfterAuth(nameOrUrl);
+            return updated;
+        },
+        async authLocal(nameOrUrl, opts) {
+            const config = await readConfig();
+            const target = findRegistry(config.registries ?? [], nameOrUrl);
+            if (!target || typeof target === "string") {
+                throw new AdkError({
+                    code: "registry_not_found",
+                    message: `Registry not found: ${nameOrUrl}`,
+                    hint: "Run `adk registry list` to see configured registries.",
+                    details: { nameOrUrl },
+                });
+            }
+            // When the caller forces re-auth, wipe the existing credentials and
+            // re-probe so we know what scheme the registry wants now. Servers can
+            // rotate auth server metadata between runs.
+            if (opts?.force) {
+                await updateRegistryEntry(nameOrUrl, (existing) => {
+                    delete existing.auth;
+                    delete existing.oauth;
+                });
+                const fetchFn = options.fetch ?? globalThis.fetch;
+                const probe = await probeRegistryAuth(target.url, fetchFn);
+                if (probe.ok === false) {
+                    await updateRegistryEntry(nameOrUrl, (existing) => {
+                        existing.authRequirement = probe.requirement;
+                    });
+                    // Re-read so the flow below sees the fresh requirement.
+                    const refreshed = await readConfig();
+                    const refreshedTarget = findRegistry(refreshed.registries ?? [], nameOrUrl);
+                    if (refreshedTarget && typeof refreshedTarget !== "string") {
+                        Object.assign(target, refreshedTarget);
+                    }
+                }
+                else if (probe.ok === true) {
+                    // Registry no longer requires auth — nothing to do.
+                    await updateRegistryEntry(nameOrUrl, (existing) => {
+                        delete existing.authRequirement;
+                    });
+                    return { complete: true };
+                }
+            }
+            // Already authenticated — nothing to do (unless forced above).
+            const hasUsableAuth = target.auth && target.auth.type !== "none"
+                ? (target.auth.type === "bearer" && !!target.auth.token) ||
+                    (target.auth.type === "api-key" && !!target.auth.key)
+                : false;
+            if (hasUsableAuth && !target.authRequirement) {
+                return { complete: true };
+            }
+            const req = target.authRequirement;
+            const port = options.oauthCallbackPort ?? 8919;
+            const timeout = opts?.timeoutMs ?? 300_000;
+            const displayName = target.name ?? target.url;
+            const { createServer } = await import("node:http");
+            // OAuth path — the registry advertised authorization servers via
+            // RFC 9728 protected-resource metadata. Walk the full flow:
+            // AS metadata → dynamic client registration → PKCE authorize →
+            // local callback → token exchange → persist access token.
+            if (req?.authorizationServers?.length) {
+                const authServer = req.authorizationServers[0];
+                const metadata = (await discoverOAuthMetadata(authServer)) ??
+                    (await tryFetchOAuthMetadata(authServer));
+                if (!metadata) {
+                    throw new AdkError({
+                        code: "registry_oauth_discovery_failed",
+                        message: `Could not discover OAuth metadata at ${authServer}.`,
+                        hint: "The authorization server must expose /.well-known/oauth-authorization-server.",
+                        details: { authServer, registry: displayName },
+                    });
+                }
+                if (!metadata.registration_endpoint) {
+                    throw new AdkError({
+                        code: "registry_oauth_no_registration",
+                        message: `Authorization server ${authServer} does not support dynamic client registration.`,
+                        hint: `Obtain a bearer token manually, then run: adk registry auth ${displayName} --token <token>`,
+                        details: { authServer, registry: displayName },
+                    });
+                }
+                const redirectUri = `http://localhost:${port}/callback`;
+                const registration = await dynamicClientRegistration(metadata.registration_endpoint, {
+                    clientName: options.oauthClientName ?? "adk",
+                    redirectUris: [redirectUri],
+                    grantTypes: ["authorization_code"],
+                });
+                const state = crypto.randomUUID();
+                const { url: authorizeUrl, codeVerifier } = await buildOAuthAuthorizeUrl({
+                    authorizationEndpoint: metadata.authorization_endpoint,
+                    clientId: registration.clientId,
+                    redirectUri,
+                    scopes: req.scopes,
+                    state,
+                });
+                return new Promise((resolve, reject) => {
+                    const server = createServer(async (reqIn, resOut) => {
+                        const reqUrl = new URL(reqIn.url ?? "/", `http://localhost:${port}`);
+                        if (reqUrl.pathname !== "/callback") {
+                            resOut.writeHead(404);
+                            resOut.end();
+                            return;
+                        }
+                        const code = reqUrl.searchParams.get("code");
+                        const returnedState = reqUrl.searchParams.get("state");
+                        if (!code || returnedState !== state) {
+                            const error = reqUrl.searchParams.get("error") ?? "missing code/state";
+                            resOut.writeHead(400, { "Content-Type": "text/html" });
+                            resOut.end(`<h1>Error</h1><p>${esc(error)}</p>`);
+                            server.close();
+                            reject(new AdkError({
+                                code: "registry_oauth_denied",
+                                message: `OAuth callback rejected: ${error}`,
+                                hint: "Retry `adk registry auth` and complete the browser consent.",
+                                details: { registry: displayName, error },
+                            }));
+                            return;
+                        }
+                        try {
+                            const tokens = await exchangeCodeForTokens(metadata.token_endpoint, {
+                                code,
+                                codeVerifier,
+                                clientId: registration.clientId,
+                                clientSecret: registration.clientSecret,
+                                redirectUri,
+                            });
+                            const expiresAt = tokens.expiresIn
+                                ? new Date(Date.now() + tokens.expiresIn * 1000).toISOString()
+                                : undefined;
+                            const encToken = await protectSecret(tokens.accessToken);
+                            const encRefresh = tokens.refreshToken
+                                ? await protectSecret(tokens.refreshToken)
+                                : undefined;
+                            const encClientSecret = registration.clientSecret
+                                ? await protectSecret(registration.clientSecret)
+                                : undefined;
+                            await updateRegistryEntry(displayName, (existing) => {
+                                existing.auth = { type: "bearer", token: encToken };
+                                existing.oauth = {
+                                    tokenEndpoint: metadata.token_endpoint,
+                                    clientId: registration.clientId,
+                                    ...(encClientSecret && { clientSecret: encClientSecret }),
+                                    ...(encRefresh && { refreshToken: encRefresh }),
+                                    ...(expiresAt && { expiresAt }),
+                                    ...(req.scopes?.length && { scopes: req.scopes }),
+                                };
+                                delete existing.authRequirement;
+                            });
+                            await discoverProxyAfterAuth(displayName);
+                            resOut.writeHead(200, { "Content-Type": "text/html" });
+                            resOut.end(renderAuthSuccess(displayName));
+                            server.close();
+                            resolve({ complete: true });
+                        }
+                        catch (err) {
+                            resOut.writeHead(500, { "Content-Type": "text/html" });
+                            resOut.end(`<h1>Error</h1><p>${esc(err instanceof Error ? err.message : String(err))}</p>`);
+                            server.close();
+                            reject(err);
+                        }
+                    });
+                    server.listen(port, () => {
+                        opts?.onAuthorizeUrl?.(authorizeUrl);
+                    });
+                    const timer = setTimeout(() => {
+                        server.close();
+                        reject(new Error("OAuth callback timed out"));
+                    }, timeout);
+                    server.on("close", () => clearTimeout(timer));
+                });
+            }
+            // No OAuth metadata — serve a local HTTPS form asking for a token.
+            // Used when the registry returned 401 without pointing at an AS, or
+            // when the caller simply wants to paste a pre-issued token.
+            const fields = [
+                {
+                    name: "token",
+                    label: "Bearer token",
+                    description: req?.realm
+                        ? `Token for realm "${req.realm}"`
+                        : "Token sent as `Authorization: Bearer <token>`.",
+                    secret: true,
+                },
+            ];
+            return new Promise((resolve, reject) => {
+                const server = createServer(async (reqIn, resOut) => {
+                    const reqUrl = new URL(reqIn.url ?? "/", `http://localhost:${port}`);
+                    if (reqIn.method === "GET" && reqUrl.pathname === "/auth") {
+                        resOut.writeHead(200, { "Content-Type": "text/html" });
+                        resOut.end(renderCredentialForm(displayName, fields));
+                        return;
+                    }
+                    if (reqIn.method === "POST" && reqUrl.pathname === "/auth") {
+                        const chunks = [];
+                        for await (const chunk of reqIn)
+                            chunks.push(chunk);
+                        const body = Buffer.concat(chunks).toString();
+                        const params = new URLSearchParams(body);
+                        const token = params.get("token");
+                        if (!token) {
+                            resOut.writeHead(200, { "Content-Type": "text/html" });
+                            resOut.end(renderCredentialForm(displayName, fields, "Token is required."));
+                            return;
+                        }
+                        try {
+                            await registry.auth(displayName, { token });
+                            resOut.writeHead(200, { "Content-Type": "text/html" });
+                            resOut.end(renderAuthSuccess(displayName));
+                            server.close();
+                            resolve({ complete: true });
+                        }
+                        catch (err) {
+                            resOut.writeHead(500, { "Content-Type": "text/html" });
+                            resOut.end(renderCredentialForm(displayName, fields, err instanceof Error ? err.message : String(err)));
+                        }
+                        return;
+                    }
+                    resOut.writeHead(404);
+                    resOut.end();
+                });
+                server.listen(port, () => {
+                    opts?.onAuthorizeUrl?.(`http://localhost:${port}/auth`);
+                });
+                const timer = setTimeout(() => {
+                    server.close();
+                    reject(new Error("Auth timed out"));
+                }, timeout);
+                server.on("close", () => clearTimeout(timer));
+            });
+        },
     };
     // ==========================================
     // Ref API
@@ -751,6 +1327,12 @@ export function createAdk(fs, options = {}) {
             const entry = findRef(config.refs ?? [], name);
             if (!entry)
                 throw new Error(`Ref "${name}" not found`);
+            // Registry-proxied refs: ask the remote @config for state (secrets live
+            // server-side so local inspection would always return "missing").
+            const proxy = await resolveProxyForRef(entry);
+            if (proxy) {
+                return forwardRefOpToProxy(proxy.reg, proxy.agent, "auth-status", { name });
+            }
             let security = null;
             try {
                 const consumer = await buildConsumerForRef(entry);
@@ -856,6 +1438,23 @@ export function createAdk(fs, options = {}) {
             const entry = findRef(config.refs ?? [], name);
             if (!entry)
                 throw new Error(`Ref "${name}" not found`);
+            // Registry-proxied auth: forward the start-of-flow to the remote @config
+            // agent. The registry owns the client_id/secret and returns an authorize
+            // URL pointing at the registry's OAuth callback domain, so the user
+            // completes the flow against the registry instead of localhost.
+            const proxy = await resolveProxyForRef(entry, { preferLocal: opts?.preferLocal });
+            if (proxy) {
+                const params = { name };
+                if (opts?.apiKey !== undefined)
+                    params.apiKey = opts.apiKey;
+                if (opts?.credentials)
+                    params.credentials = opts.credentials;
+                if (opts?.scopes)
+                    params.scopes = opts.scopes;
+                if (opts?.stateContext)
+                    params.stateContext = opts.stateContext;
+                return forwardRefOpToProxy(proxy.reg, proxy.agent, "auth", params);
+            }
             const status = await ref.authStatus(name);
             const security = status.security;
             const resolve = options.resolveCredentials;
@@ -1076,14 +1675,30 @@ export function createAdk(fs, options = {}) {
             return { type: security.type, complete: false };
         },
         async authLocal(name, opts) {
+            // `ref.auth` is already proxy-aware — for proxied refs it returns
+            // the authorizeUrl that the registry minted against its own
+            // callback domain. Everything below is identical for local and
+            // proxied refs except the last step (polling for the callback),
+            // which only makes sense when we own the redirect URI.
             const result = await ref.auth(name);
             if (result.complete)
                 return { complete: true };
+            const config = await readConfig();
+            const entry = findRef(config.refs ?? [], name);
+            const proxy = entry ? await resolveProxyForRef(entry) : null;
             const port = options.oauthCallbackPort ?? 8919;
             const timeout = opts?.timeoutMs ?? 300_000;
             const { createServer } = await import("node:http");
-            // API key / HTTP auth — serve a local credential form
+            // API key / HTTP auth — local credential form.
+            //
+            // We refuse to serve the form for a proxied ref: the registry
+            // owns the credential store, so the user needs to submit via
+            // whatever UI the registry exposes. Supporting this through the
+            // proxy would need a remote form endpoint — out of scope here.
             if (result.fields && result.fields.length > 0 && result.type !== "oauth2") {
+                if (proxy) {
+                    throw new Error(`Ref "${name}" is sourced from a proxied registry; submit credentials through ${proxy.agent} instead of a local form.`);
+                }
                 return new Promise((resolve, reject) => {
                     const server = createServer(async (req, res) => {
                         const reqUrl = new URL(req.url ?? "/", `http://localhost:${port}`);
@@ -1138,13 +1753,20 @@ export function createAdk(fs, options = {}) {
                     server.on("close", () => clearTimeout(timer));
                 });
             }
-            // OAuth2 — open authorize URL and wait for callback
+            // OAuth2 — hand the authorize URL to the caller.
             if (result.type !== "oauth2" || !result.authorizeUrl) {
                 throw new Error(`authLocal cannot handle auth type: ${result.type}`);
             }
             if (opts?.onAuthorizeUrl) {
                 opts.onAuthorizeUrl(result.authorizeUrl);
             }
+            // Proxied refs: the registry owns the callback endpoint, so there's
+            // nothing to poll here. Callers poll `ref.authStatus` on their own
+            // schedule once the user finishes the remote consent screen.
+            if (proxy)
+                return { complete: false };
+            // Local refs: spin up the callback server on oauthCallbackPort and
+            // block until the OAuth provider redirects back.
             return new Promise((resolve, reject) => {
                 const server = createServer(async (req, res) => {
                     const reqUrl = new URL(req.url ?? "/", `http://localhost:${port}`);
@@ -1183,6 +1805,14 @@ export function createAdk(fs, options = {}) {
             });
         },
         async refreshToken(name) {
+            // Registry-proxied refs: the remote @config holds the refresh_token.
+            const entryForProxy = await ref.get(name);
+            if (entryForProxy) {
+                const proxy = await resolveProxyForRef(entryForProxy);
+                if (proxy) {
+                    return forwardRefOpToProxy(proxy.reg, proxy.agent, "refresh-token", { name });
+                }
+            }
             // Read stored refresh_token
             const refreshToken = await readRefSecret(name, "refresh_token");
             if (!refreshToken)
@@ -1257,32 +1887,6 @@ export function createAdk(fs, options = {}) {
         catch { /* state wasn't base64 JSON — legacy format */ }
         return { refName: pending.refName, complete: true, stateContext };
     }
-    // ==========================================
-    // Proxy API
-    // ==========================================
-    const proxy = {
-        async add(entry) {
-            const config = await readConfig();
-            const proxies = (config.proxies ?? []).filter((p) => p.name !== entry.name);
-            proxies.push(entry);
-            await writeConfig({ ...config, proxies });
-        },
-        async remove(name) {
-            const config = await readConfig();
-            if (!config.proxies?.length)
-                return false;
-            const before = config.proxies.length;
-            const proxies = config.proxies.filter((p) => p.name !== name);
-            if (proxies.length === before)
-                return false;
-            await writeConfig({ ...config, proxies });
-            return true;
-        },
-        async list() {
-            const config = await readConfig();
-            return config.proxies ?? [];
-        },
-    };
-    return { proxy, registry, ref, readConfig, writeConfig, handleCallback };
+    return { registry, ref, readConfig, writeConfig, handleCallback };
 }
 //# sourceMappingURL=config-store.js.map