@slashfi/agents-sdk 0.90.2 → 0.90.5

package/src/config-store.ts

@@ -33,6 +33,7 @@ import type { RegistryAuthRequirement } from "./define-config.js";
 import type { FetchFn } from "./fetch-types.js";
 import type { Logger } from "./logger.js";
 import {
+  type OAuthClientAuthMethod,
   buildOAuthAuthorizeUrl,
   discoverOAuthMetadata,
   dynamicClientRegistration,
@@ -111,6 +112,11 @@ export interface RegistryCacheAuthField {
    * For example HTTP Basic stores one `token` but asks UI for username/password.
    */
   parts?: RegistryCacheAuthFieldPart[];
+  /**
+   * When `false`, connect/refresh bookkeeping only — not forwarded on
+   * `ref.call`. Omitted or `true` for bearer, header, and call-time creds.
+   */
+  outbound?: boolean;
 }
 
 /**
@@ -391,6 +397,8 @@ export interface CredentialField {
   format?: CompositeCredentialFormat;
   /** Structured inputs that compose this canonical stored credential */
   parts?: AuthChallengeField[];
+  /** Connect/refresh only — not forwarded on ref.call. */
+  outbound?: boolean;
 }
 
 /** Describes what auth a ref needs and what's already provided */
@@ -991,6 +999,205 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
     };
   }
 
+  /**
+   * Call-time credential lookup: stored ref config first, then the host
+   * `resolveCredentials` callback. Does not persist resolved values.
+   */
+  async function resolveCallCredential(
+    ctx: CredentialResolverContext,
+    field: string,
+  ): Promise<string | null> {
+    const stored = await readRefSecret(ctx.name, field);
+    if (stored) return stored;
+    return makeTryResolve(ctx)(field);
+  }
+
+  const CALL_BEARER_FIELDS = ["access_token", "api_key", "token"] as const;
+
+  function isBearerAuthField(field: string): boolean {
+    return (CALL_BEARER_FIELDS as readonly string[]).includes(field);
+  }
+
+  /** Legacy cache entries may omit `outbound`; these are never call-time creds. */
+  const LEGACY_CONNECT_ONLY_FIELDS = new Set([
+    "client_id",
+    "client_secret",
+    "refresh_token",
+  ]);
+
+  function isCallOutboundAuthField(
+    field: string,
+    info: RegistryCacheAuthField,
+  ): boolean {
+    if (info.outbound === false) return false;
+    if (info.outbound === true) return true;
+    return !LEGACY_CONNECT_ONLY_FIELDS.has(field);
+  }
+
+  function readRegistryDeclaredAuthFields(
+    security: SecuritySchemeSummary | null,
+  ): Record<string, RegistryCacheAuthField> | undefined {
+    if (!security || typeof security !== "object") return undefined;
+    const raw = (security as { authFields?: unknown }).authFields;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+    const out: Record<string, RegistryCacheAuthField> = {};
+    for (const [field, meta] of Object.entries(
+      raw as Record<string, unknown>,
+    )) {
+      if (!meta || typeof meta !== "object" || Array.isArray(meta)) continue;
+      const m = meta as Record<string, unknown>;
+      if (typeof m.required !== "boolean" || typeof m.automated !== "boolean") {
+        continue;
+      }
+      out[field] = { required: m.required, automated: m.automated };
+      if (typeof m.outbound === "boolean") {
+        out[field].outbound = m.outbound;
+      }
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+  }
+
+  async function mergeRegistryDeclaredAuthFields(
+    fields: Record<string, CredentialField>,
+    declared: Record<string, RegistryCacheAuthField> | undefined,
+    canResolve: (field: string) => Promise<boolean>,
+    configKeys: string[],
+    refConfig: Record<string, unknown>,
+  ): Promise<Record<string, CredentialField>> {
+    if (!declared) return fields;
+    const next: Record<string, CredentialField> = {};
+    for (const [field, meta] of Object.entries(declared)) {
+      next[field] = {
+        required: meta.required,
+        automated: meta.automated,
+        present:
+          configKeys.includes(field) || hasCredentialField(refConfig, field),
+        resolvable: await canResolve(field),
+        ...(meta.format && { format: meta.format }),
+        ...(meta.parts && { parts: meta.parts }),
+        ...(meta.outbound === false && { outbound: false }),
+      };
+    }
+    return next;
+  }
+
+  function bearerFieldSatisfied(
+    accessToken: string | null,
+    refConfig: Record<string, unknown>,
+    field: string,
+  ): boolean {
+    if (accessToken) return true;
+    return hasCredentialField(refConfig, field);
+  }
+
+  function fallbackCallAuthFields(): Record<string, RegistryCacheAuthField> {
+    return {
+      access_token: { required: true, automated: true },
+      api_key: { required: false, automated: true },
+      token: { required: false, automated: true },
+    };
+  }
+
+  function headerFieldSatisfied(
+    headers: Record<string, string>,
+    field: string,
+  ): boolean {
+    const wanted = normalizeCredentialKey(field);
+    return Object.keys(headers).some(
+      (key) => normalizeCredentialKey(key) === wanted,
+    );
+  }
+
+  function resolveHeaderNameForField(
+    field: string,
+    refConfig: Record<string, unknown>,
+  ): string {
+    const wanted = normalizeCredentialKey(field);
+    const configHeaders = refConfig.headers;
+    if (
+      configHeaders &&
+      typeof configHeaders === "object" &&
+      !Array.isArray(configHeaders)
+    ) {
+      for (const key of Object.keys(configHeaders as Record<string, unknown>)) {
+        if (normalizeCredentialKey(key) === wanted) return key;
+      }
+    }
+    // x_api_key → X-API-KEY (registry codegen declares the canonical name;
+    // env-resolved keys use the normalized storage field name).
+    return field
+      .split("_")
+      .filter(Boolean)
+      .map((part) => part.toUpperCase())
+      .join("-");
+  }
+
+  /**
+   * Supplement call-time credentials from `resolveCredentials` when they
+   * are not already present in consumer-config. Stored values and config
+   * headers win — this only fills gaps. Walks cached `authFields` as the
+   * source of truth (registry-declared when auth-status has run).
+   */
+  async function resolveAllCallCredentials(opts: {
+    ctx: CredentialResolverContext;
+    refConfig: Record<string, unknown>;
+    accessToken: string | null;
+    resolvedHeaders: Record<string, string> | undefined;
+  }): Promise<{
+    accessToken: string | null;
+    resolvedHeaders: Record<string, string> | undefined;
+  }> {
+    if (!options.resolveCredentials) {
+      return {
+        accessToken: opts.accessToken,
+        resolvedHeaders: opts.resolvedHeaders,
+      };
+    }
+
+    let accessToken = opts.accessToken;
+    let resolvedHeaders = opts.resolvedHeaders;
+    const { ctx, refConfig } = opts;
+
+    const cache = await readRegistryCache();
+    const authFields =
+      cache.refs[ctx.name]?.authFields ?? fallbackCallAuthFields();
+
+    for (const [field, info] of Object.entries(authFields)) {
+      if (!isCallOutboundAuthField(field, info)) continue;
+      if (!info.required && !info.automated) continue;
+
+      if (isBearerAuthField(field)) {
+        if (bearerFieldSatisfied(accessToken, refConfig, field)) continue;
+        const value = await resolveCallCredential(ctx, field);
+        if (value) accessToken = accessToken ?? value;
+        continue;
+      }
+
+      if (hasCredentialField(refConfig, field)) continue;
+      if (resolvedHeaders && headerFieldSatisfied(resolvedHeaders, field)) {
+        continue;
+      }
+
+      const value = await resolveCallCredential(ctx, field);
+      if (!value) continue;
+
+      resolvedHeaders = resolvedHeaders ?? {};
+      if (!headerFieldSatisfied(resolvedHeaders, field)) {
+        resolvedHeaders[resolveHeaderNameForField(field, refConfig)] = value;
+      }
+    }
+
+    if (!accessToken) {
+      const username = await resolveCallCredential(ctx, "username");
+      const password = await resolveCallCredential(ctx, "password");
+      if (username && password) {
+        accessToken = btoa(`${username}:${password}`);
+      }
+    }
+
+    return { accessToken, resolvedHeaders };
+  }
+
   /**
    * Resolve OAuth client credentials (client_id + client_secret) for a
    * ref. Walks: `resolveCredentials` callback → per-ref VCS storage.
@@ -1023,6 +1230,7 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
     codeVerifier: string;
     clientId: string;
     clientSecret?: string;
+    clientAuthMethod?: OAuthClientAuthMethod;
     tokenEndpoint: string;
     redirectUri: string;
     createdAt: number;
@@ -1230,6 +1438,109 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
     }
   }
 
+  /**
+   * Resolve OAuth server metadata from a registry security scheme.
+   * Shared by `ref.auth` and `ref.refreshToken` so both paths discover
+   * token endpoints the same way — explicit manifest URLs, RFC 8414
+   * discovery via `discoveryUrl`, authorization-server discovery, and
+   * finally the MCP upstream URL for redirect-mode agents.
+   */
+  async function resolveOAuthMetadataFromSecurity(
+    security: SecuritySchemeSummary | null | undefined,
+    opts?: { serverUrl?: string },
+  ): Promise<import("./mcp-client.js").OAuthServerMetadata | null> {
+    if (!security || security.type !== "oauth2") return null;
+
+    const securityExt = security as {
+      discoveryUrl?: string;
+      flows?: {
+        authorizationCode?: {
+          authorizationUrl?: string;
+          tokenUrl?: string;
+          refreshUrl?: string;
+          scopes?: Record<string, string>;
+        };
+      };
+    };
+    const authCodeFlow = securityExt.flows?.authorizationCode;
+
+    const explicitEndpoint = authCodeFlow?.refreshUrl ?? authCodeFlow?.tokenUrl;
+    if (explicitEndpoint) {
+      const flowScopes = (authCodeFlow as Record<string, unknown> | undefined)
+        ?.scopes as Record<string, string> | undefined;
+      const authUrl = authCodeFlow?.authorizationUrl;
+      return {
+        issuer: authUrl
+          ? new URL(authUrl).origin
+          : new URL(explicitEndpoint).origin,
+        authorization_endpoint: authUrl ?? explicitEndpoint,
+        token_endpoint: explicitEndpoint,
+        scopes_supported: flowScopes ? Object.keys(flowScopes) : undefined,
+      };
+    }
+
+    if (securityExt.discoveryUrl) {
+      const fromDiscovery =
+        (await tryFetchOAuthMetadata(securityExt.discoveryUrl)) ??
+        (await discoverOAuthMetadata(securityExt.discoveryUrl));
+      if (fromDiscovery) return fromDiscovery;
+    }
+
+    const authUrl = authCodeFlow?.authorizationUrl;
+    if (authUrl) {
+      let metadata = await tryFetchOAuthMetadata(authUrl);
+      if (!metadata) {
+        metadata = await discoverOAuthMetadata(new URL(authUrl).origin);
+      }
+      if (metadata) return metadata;
+    }
+
+    const serverUrl = opts?.serverUrl;
+    if (serverUrl) {
+      let metadata = await discoverOAuthMetadata(serverUrl);
+      if (!metadata) {
+        metadata = await discoverOAuthMetadata(
+          serverUrl.replace(/\/(mcp|sse)$/, ""),
+        );
+      }
+      if (metadata) return metadata;
+    }
+
+    return null;
+  }
+
+  function resolveClientAuthMethod(
+    security: SecuritySchemeSummary | null | undefined,
+    metadata: OAuthServerMetadata | null,
+  ): OAuthClientAuthMethod {
+    const flowAuth = (
+      security as {
+        flows?: {
+          authorizationCode?: { clientAuth?: OAuthClientAuthMethod };
+        };
+      }
+    ).flows?.authorizationCode?.clientAuth;
+    if (flowAuth) return flowAuth;
+
+    const supported = metadata?.token_endpoint_auth_methods_supported;
+    if (supported?.length === 1 && supported[0] === "client_secret_basic") {
+      return "client_secret_basic";
+    }
+
+    const tokenEndpoint = metadata?.token_endpoint;
+    if (tokenEndpoint) {
+      try {
+        if (new URL(tokenEndpoint).hostname === "api.x.com") {
+          return "client_secret_basic";
+        }
+      } catch {
+        /* ignore malformed token endpoint */
+      }
+    }
+
+    return "client_secret_post";
+  }
+
   /**
    * Build a registryConsumer from the current config.
    * Decrypts secret: values in registry headers/auth before connecting.
@@ -1364,7 +1675,10 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
     });
     if (!found) return false;
     for (const r of registries) {
-      if (typeof r !== "string" && (registryDisplayName(r) === nameOrUrl || registryUrl(r) === nameOrUrl)) {
+      if (
+        typeof r !== "string" &&
+        (registryDisplayName(r) === nameOrUrl || registryUrl(r) === nameOrUrl)
+      ) {
         await mutate(r);
       }
     }
@@ -2254,7 +2568,7 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
       const entry = findRef(config.refs ?? [], name);
       if (!entry) throw new Error(`Ref "${name}" not found`);
 
-      const accessToken =
+      let accessToken =
         (await readRefSecret(name, "access_token")) ??
         (await readRefSecret(name, "api_key")) ??
         (await readRefSecret(name, "token"));
@@ -2306,6 +2620,17 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
         }
       }
 
+      if (options.resolveCredentials) {
+        const supplemented = await resolveAllCallCredentials({
+          ctx: { name, entry, security: null },
+          refConfig,
+          accessToken,
+          resolvedHeaders,
+        });
+        accessToken = supplemented.accessToken;
+        resolvedHeaders = supplemented.resolvedHeaders;
+      }
+
       const doCall = async (token: string | null) => {
         // Direct MCP only for redirect/proxy agents with an MCP upstream.
         // API-mode agents must go through the registry (it does REST translation).
@@ -2460,7 +2785,7 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
         return (await tryResolveField(field, oauthMetadata)) !== null;
       }
 
-      const fields: Record<string, CredentialField> = {};
+      let fields: Record<string, CredentialField> = {};
 
       if (security.type === "oauth2") {
         const securityExt = security as {
@@ -2506,6 +2831,7 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
           automated: hasRegistration,
           present: configKeys.includes("client_id"),
           resolvable: await canResolve("client_id", oauthMetadata),
+          outbound: false,
         };
         if (needsSecret) {
           fields.client_secret = {
@@ -2513,13 +2839,14 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
             automated: hasRegistration,
             present: configKeys.includes("client_secret"),
             resolvable: await canResolve("client_secret", oauthMetadata),
+            outbound: false,
           };
         }
         fields.access_token = {
           required: true,
           automated: accessTokenAutomated,
           present: configKeys.includes("access_token"),
-          resolvable: false,
+          resolvable: await canResolve("access_token"),
         };
       } else if (security.type === "apiKey") {
         const apiKeySec = security as {
@@ -2586,7 +2913,12 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
             format: "basic" as const,
             parts: [
               { name: "username", label: "Username", secret: false },
-              { name: "password", label: "Password", secret: true, optional: true },
+              {
+                name: "password",
+                label: "Password",
+                secret: true,
+                optional: true,
+              },
             ],
           }),
         };
@@ -2607,8 +2939,16 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
         };
       }
 
+      fields = await mergeRegistryDeclaredAuthFields(
+        fields,
+        readRegistryDeclaredAuthFields(security),
+        canResolve,
+        configKeys,
+        (entry.config ?? {}) as Record<string, unknown>,
+      );
+
       const complete = Object.values(fields).every(
-        (f) => !f.required || f.present || f.resolvable,
+        (f) => !f.required || f.automated || f.present || f.resolvable,
       );
 
       // Persist the slim {required, automated} per-field shape into the
@@ -2624,6 +2964,7 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
           automated: info.automated,
           ...(info.format && { format: info.format }),
           ...(info.parts && { parts: info.parts }),
+          ...(info.outbound === false && { outbound: false }),
         };
       }
       await upsertRegistryCacheAuthFields(name, entry.ref, authFields);
@@ -2761,8 +3102,11 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
           const username =
             opts?.credentials?.["username"] ?? (await tryResolve("username"));
           const password =
-            opts?.credentials?.["password"] ?? (await tryResolve("password")) ?? "";
-          const hasUsername = username !== undefined && username !== null && username !== "";
+            opts?.credentials?.["password"] ??
+            (await tryResolve("password")) ??
+            "";
+          const hasUsername =
+            username !== undefined && username !== null && username !== "";
           if (!hasUsername) {
             return {
               type: "http",
@@ -2823,23 +3167,9 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
         }
 
         const authUrl = authCodeFlow.authorizationUrl;
-        let metadata = await tryFetchOAuthMetadata(authUrl);
-        if (!metadata) {
-          const origin = new URL(authUrl).origin;
-          metadata = await discoverOAuthMetadata(origin);
-        }
-        // Fallback: construct metadata from the security scheme's explicit URLs
-        if (!metadata && authCodeFlow.tokenUrl) {
-          const flowScopes = (authCodeFlow as Record<string, unknown>).scopes as
-            | Record<string, string>
-            | undefined;
-          metadata = {
-            issuer: new URL(authUrl).origin,
-            authorization_endpoint: authUrl,
-            token_endpoint: authCodeFlow.tokenUrl,
-            scopes_supported: flowScopes ? Object.keys(flowScopes) : undefined,
-          } as import("./mcp-client.js").OAuthServerMetadata;
-        }
+        const metadata = await resolveOAuthMetadataFromSecurity(security, {
+          serverUrl: entry.url,
+        });
         if (!metadata) {
           throw new Error(`Could not discover OAuth metadata from ${authUrl}`);
         }
@@ -2950,11 +3280,13 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
           });
 
         // Persist pending state so handleCallback works across processes
+        const clientAuthMethod = resolveClientAuthMethod(security, metadata);
         await storePendingOAuth(state, {
           refName: name,
           codeVerifier,
           clientId,
           clientSecret,
+          clientAuthMethod,
           tokenEndpoint: metadata.token_endpoint,
           redirectUri,
           createdAt: Date.now(),
@@ -3125,54 +3457,50 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
 
       const status = await ref.authStatus(name);
       const security = status.security;
-      const flows =
-        security && "flows" in security
-          ? (
-              security as {
-                flows?: Record<
-                  string,
-                  { tokenUrl?: string; refreshUrl?: string }
-                >;
-              }
-            ).flows
-          : undefined;
-      const authCodeFlow = flows?.authorizationCode;
-      const tokenUrl = authCodeFlow?.refreshUrl ?? authCodeFlow?.tokenUrl;
-      if (!tokenUrl) return null;
-
-      const oauthClient = await resolveOAuthClient({ name, entry, security });
-      if (!oauthClient) return null;
-      const { clientId, clientSecret } = oauthClient;
-
-      // POST to the token endpoint with grant_type=refresh_token
-      const body = new URLSearchParams({
-        grant_type: "refresh_token",
-        refresh_token: refreshToken,
-        client_id: clientId,
+      const metadata = await resolveOAuthMetadataFromSecurity(security, {
+        serverUrl: entry.url,
       });
-      if (clientSecret) {
-        body.set("client_secret", clientSecret);
-      }
-
-      const res = await globalThis.fetch(tokenUrl, {
-        method: "POST",
-        headers: { "Content-Type": "application/x-www-form-urlencoded" },
-        body: body.toString(),
+      const tokenEndpoint = metadata?.token_endpoint;
+      if (!tokenEndpoint) return null;
+
+      const oauthClient = await resolveOAuthClient({
+        name,
+        entry,
+        security,
+        metadata,
       });
+      if (!oauthClient) return null;
 
-      if (!res.ok) return null;
-
-      const data = (await res.json()) as Record<string, unknown>;
-      const newAccessToken = data.access_token as string | undefined;
-      if (!newAccessToken) return null;
+      const clientAuthMethod = resolveClientAuthMethod(security, metadata);
+      const fetchFn = options.fetch ?? globalThis.fetch;
+      let tokens: Awaited<ReturnType<typeof refreshAccessToken>>;
+      try {
+        tokens = await refreshAccessToken(
+          tokenEndpoint,
+          {
+            refreshToken,
+            clientId: oauthClient.clientId,
+            clientSecret: oauthClient.clientSecret,
+            clientAuthMethod,
+          },
+          fetchFn,
+        );
+      } catch {
+        return null;
+      }
 
-      // Store the new tokens
-      await storeRefSecret(name, "access_token", newAccessToken);
-      if (data.refresh_token && typeof data.refresh_token === "string") {
-        await storeRefSecret(name, "refresh_token", data.refresh_token);
+      await storeRefSecret(name, "access_token", tokens.accessToken);
+      if (tokens.refreshToken) {
+        await storeRefSecret(name, "refresh_token", tokens.refreshToken);
+      }
+      if (tokens.expiresIn) {
+        const expiresAt = new Date(
+          Date.now() + tokens.expiresIn * 1000,
+        ).toISOString();
+        await storeRefSecret(name, "expires_at", expiresAt);
       }
 
-      return { accessToken: newAccessToken };
+      return { accessToken: tokens.accessToken };
     },
   };
 
@@ -3193,13 +3521,19 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
       throw new Error(`No pending OAuth flow for state "${params.state}".`);
     }
 
-    const tokens = await exchangeCodeForTokens(pending.tokenEndpoint, {
-      code: params.code,
-      codeVerifier: pending.codeVerifier,
-      clientId: pending.clientId,
-      clientSecret: pending.clientSecret,
-      redirectUri: pending.redirectUri,
-    });
+    const fetchFn = options.fetch ?? globalThis.fetch;
+    const tokens = await exchangeCodeForTokens(
+      pending.tokenEndpoint,
+      {
+        code: params.code,
+        codeVerifier: pending.codeVerifier,
+        clientId: pending.clientId,
+        clientSecret: pending.clientSecret,
+        redirectUri: pending.redirectUri,
+        clientAuthMethod: pending.clientAuthMethod,
+      },
+      fetchFn,
+    );
 
     await storeRefSecret(pending.refName, "access_token", tokens.accessToken);
     if (tokens.refreshToken) {

package/src/index.ts

@@ -352,7 +352,10 @@ export {
   exchangeCodeForTokens,
   refreshAccessToken as refreshMcpAccessToken,
 } from "./mcp-client.js";
-export type { OAuthServerMetadata } from "./mcp-client.js";
+export type {
+  OAuthClientAuthMethod,
+  OAuthServerMetadata,
+} from "./mcp-client.js";
 
 // ============================================
 // Serialized Agent Definitions