@slashfi/agents-sdk 0.90.1 → 0.90.4

package/src/config-store.ts

@@ -86,9 +86,36 @@ export interface RegistryCacheToolSummary {
  *                   client registration). Doesn't need to be `present`
  *                   in the user's config to count as satisfied.
  */
+export type CompositeCredentialFormat = "basic";
+
+export interface RegistryCacheAuthFieldPart {
+  /** Field key callers should collect (for example "username") */
+  name: string;
+  /** Human-readable label for UI rendering */
+  label: string;
+  /** Whether this part is secret and should be masked */
+  secret: boolean;
+  /** Whether this part may be intentionally blank */
+  optional?: boolean;
+  /** Optional description / help text */
+  description?: string;
+}
+
 export interface RegistryCacheAuthField {
   required: boolean;
   automated: boolean;
+  /** How `parts` compose into this canonical stored credential. */
+  format?: CompositeCredentialFormat;
+  /**
+   * Optional structured inputs that compose this canonical stored credential.
+   * 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;
 }
 
 /**
@@ -329,6 +356,7 @@ export interface AdkRegistryApi {
     nameOrUrl: string,
     credential:
       | { token: string; tokenUrl?: string }
+      | { username: string; password?: string }
       | { apiKey: string; header?: string },
   ): Promise<boolean>;
 
@@ -364,6 +392,12 @@ export interface CredentialField {
   present: boolean;
   /** Available via resolveCredentials callback */
   resolvable: boolean;
+  /** How `parts` compose into this canonical stored credential */
+  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 */
@@ -391,6 +425,8 @@ export interface AuthChallengeField {
   label: string;
   /** Whether this is a secret value (should be masked in UI) */
   secret: boolean;
+  /** Whether this field may be intentionally blank */
+  optional?: boolean;
   /** Optional description / help text */
   description?: string;
 }
@@ -667,7 +703,7 @@ function renderCredentialForm(
       <div class="field">
         <label for="${esc(f.name)}">${esc(f.label)}</label>
         ${f.description ? `<p class="desc">${esc(f.description)}</p>` : ""}
-        <input id="${esc(f.name)}" name="${esc(f.name)}" type="${f.secret ? "password" : "text"}" required autocomplete="off" spellcheck="false" />
+        <input id="${esc(f.name)}" name="${esc(f.name)}" type="${f.secret ? "password" : "text"}" ${f.optional ? "" : "required"} autocomplete="off" spellcheck="false" />
       </div>`,
     )
     .join("");
@@ -962,6 +998,203 @@ 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.
@@ -1320,7 +1553,7 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
    */
   async function updateRegistryEntry(
     nameOrUrl: string,
-    mutate: (entry: RegistryEntry) => void,
+    mutate: (entry: RegistryEntry) => void | Promise<void>,
   ): Promise<boolean> {
     const config = await readConfig();
     if (!config.registries?.length) return false;
@@ -1331,10 +1564,14 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
       found = true;
       const existing: RegistryEntry =
         typeof r === "string" ? { url: r } : { ...r };
-      mutate(existing);
       return existing;
     });
     if (!found) return false;
+    for (const r of registries) {
+      if (typeof r !== "string" && (registryDisplayName(r) === nameOrUrl || registryUrl(r) === nameOrUrl)) {
+        await mutate(r);
+      }
+    }
     await writeConfig({ ...config, registries });
     return true;
   }
@@ -1433,6 +1670,7 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
     const hasUsableAuth =
       entry.auth && entry.auth.type !== "none"
         ? (entry.auth.type === "bearer" && !!entry.auth.token) ||
+          (entry.auth.type === "basic" && !!entry.auth.username) ||
           (entry.auth.type === "api-key" && !!entry.auth.key)
         : false;
     if (hasUsableAuth) return;
@@ -1474,6 +1712,7 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
       const hasUsableAuth =
         entry.auth && entry.auth.type !== "none"
           ? (entry.auth.type === "bearer" && !!entry.auth.token) ||
+            (entry.auth.type === "basic" && !!entry.auth.username) ||
             (entry.auth.type === "api-key" && !!entry.auth.key)
           : false;
 
@@ -1584,6 +1823,7 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
             const hasUsableAuth =
               r.auth && r.auth.type !== "none"
                 ? (r.auth.type === "bearer" && !!r.auth.token) ||
+                  (r.auth.type === "basic" && !!r.auth.username) ||
                   (r.auth.type === "api-key" && !!r.auth.key)
                 : false;
             if (!hasUsableAuth) {
@@ -1627,26 +1867,30 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
       nameOrUrl: string,
       credential:
         | { token: string; tokenUrl?: string }
+        | { username: string; password?: string }
         | { apiKey: string; header?: string },
     ): Promise<boolean> {
-      // 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) => {
+      // Encrypt secret values before writing. `buildConsumer` decrypts on the
+      // read side via `decryptConfigSecrets`.
+      const updated = await updateRegistryEntry(nameOrUrl, async (existing) => {
         if ("token" in credential) {
           existing.auth = {
             type: "bearer",
-            token: protectedValue,
+            token: await protectSecret(credential.token),
             ...(credential.tokenUrl && { tokenUrl: credential.tokenUrl }),
           };
+        } else if ("username" in credential) {
+          existing.auth = {
+            type: "basic",
+            username: await protectSecret(credential.username),
+            ...(credential.password && {
+              password: await protectSecret(credential.password),
+            }),
+          };
         } else {
           existing.auth = {
             type: "api-key",
-            key: protectedValue,
+            key: await protectSecret(credential.apiKey),
             ...(credential.header && { header: credential.header }),
           };
         }
@@ -1710,6 +1954,7 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
       const hasUsableAuth =
         target.auth && target.auth.type !== "none"
           ? (target.auth.type === "bearer" && !!target.auth.token) ||
+            (target.auth.type === "basic" && !!target.auth.username) ||
             (target.auth.type === "api-key" && !!target.auth.key)
           : false;
       if (hasUsableAuth && !target.authRequirement) {
@@ -2213,7 +2458,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"));
@@ -2265,6 +2510,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).
@@ -2419,7 +2675,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 {
@@ -2465,6 +2721,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 = {
@@ -2472,13 +2729,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 {
@@ -2531,11 +2789,23 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
           };
         }
       } else if (security.type === "http") {
+        const httpSec = security as { scheme?: string };
+        const isBasic = httpSec.scheme === "basic";
         fields.token = {
           required: true,
           automated: false,
           present: configKeys.includes("token"),
-          resolvable: await canResolve("token"),
+          resolvable: isBasic
+            ? (await canResolve("username")) &&
+              (await tryResolveField("password")) !== null
+            : await canResolve("token"),
+          ...(isBasic && {
+            format: "basic" as const,
+            parts: [
+              { name: "username", label: "Username", secret: false },
+              { name: "password", label: "Password", secret: true, optional: true },
+            ],
+          }),
         };
       } else if (security.type === "form") {
         // Form-based refs collect structured user input at connect time
@@ -2554,8 +2824,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
@@ -2569,6 +2847,9 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
         authFields[field] = {
           required: info.required,
           automated: info.automated,
+          ...(info.format && { format: info.format }),
+          ...(info.parts && { parts: info.parts }),
+          ...(info.outbound === false && { outbound: false }),
         };
       }
       await upsertRegistryCacheAuthFields(name, entry.ref, authFields);
@@ -2706,24 +2987,23 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
           const username =
             opts?.credentials?.["username"] ?? (await tryResolve("username"));
           const password =
-            opts?.credentials?.["password"] ?? (await tryResolve("password"));
-          if (!username || !password) {
-            const missingFields: AuthChallengeField[] = [];
-            if (!username)
-              missingFields.push({
-                name: "username",
-                label: "Username",
-                secret: false,
-              });
-            if (!password)
-              missingFields.push({
-                name: "password",
-                label: "Password",
-                secret: true,
-              });
-            return { type: "http", complete: false, fields: missingFields };
+            opts?.credentials?.["password"] ?? (await tryResolve("password")) ?? "";
+          const hasUsername = username !== undefined && username !== null && username !== "";
+          if (!hasUsername) {
+            return {
+              type: "http",
+              complete: false,
+              fields: [
+                {
+                  name: "username",
+                  label: "Username",
+                  secret: false,
+                },
+              ],
+            };
           }
-          // Store as base64 encoded basic auth token
+          // Store as base64 encoded basic auth token. Password may be blank
+          // for APIs that use the Basic username slot as an API key.
           const token = btoa(`${username}:${password}`);
           await storeRefSecret(name, "token", token);
           return { type: "http", complete: true };
@@ -2951,7 +3231,7 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
               const credentials: Record<string, string> = {};
               for (const field of result.fields!) {
                 const val = params.get(field.name);
-                if (val) credentials[field.name] = val;
+                if (val !== null) credentials[field.name] = val;
               }
 
               try {

package/src/consumer.test.ts

@@ -538,6 +538,60 @@ describe("Secret URI resolution", () => {
   });
 });
 
+// ─── Basic Auth Tests ────────────────────────────────────────────
+
+describe("Registry Consumer — Basic Auth", () => {
+  let server: AgentServer;
+  const PORT = 19895;
+  const USERNAME = "ashby-api-key";
+  const PASSWORD = "";
+
+  beforeAll(async () => {
+    const registry = createAgentRegistry();
+    registry.register(mathAgent);
+    registry.register(echoAgent);
+
+    server = createAgentServer(registry, {
+      port: PORT,
+      resolveAuth: async (req) => {
+        const auth = req.headers.get("authorization");
+        const expected = `Basic ${Buffer.from(`${USERNAME}:${PASSWORD}`, "utf8").toString("base64")}`;
+        if (auth === expected) {
+          return {
+            callerId: "basic-auth-user",
+            callerType: "system" as const,
+            scopes: ["*"],
+          };
+        }
+        return null;
+      },
+    });
+    await server.start();
+  });
+
+  afterAll(async () => {
+    await server.stop();
+  });
+
+  test("consumer with basic auth type can list agents", async () => {
+    const consumer = await createRegistryConsumer({
+      registries: [
+        {
+          url: `http://localhost:${PORT}`,
+          auth: { type: "basic", username: USERNAME, password: PASSWORD },
+        },
+      ],
+      refs: [{ ref: "@math" }],
+    });
+
+    const agents = await consumer.list();
+    expect(agents.length).toBeGreaterThanOrEqual(2);
+    const paths = agents.map((a) => a.path);
+    expect(paths).toContain("@math");
+    expect(paths).toContain("@echo");
+  });
+});
+
 // ─── API Key Auth Tests ──────────────────────────────────────────
 
 describe("Registry Consumer — API Key Auth", () => {

package/src/define-config.ts

@@ -31,6 +31,7 @@
 export type RegistryAuth =
   | { type: "none" }
   | { type: "bearer"; token?: string; tokenUrl?: string }
+  | { type: "basic"; username?: string; password?: string }
   | { type: "api-key"; key?: string; header?: string }
   | { type: "jwt"; issuer?: string };
 

package/src/registry-consumer.ts

@@ -144,7 +144,7 @@ function expandEnvVars(value: string): string {
 
 /**
  * Build auth headers for a registry based on its auth config and custom headers.
- * Merges typed auth (bearer, api-key) with arbitrary custom headers.
+ * Merges typed auth (bearer, basic, api-key) with arbitrary custom headers.
  * Environment variable references ($VAR or ${VAR}) in header values are expanded.
  */
 function buildRegistryAuthHeaders(
@@ -162,6 +162,15 @@ function buildRegistryAuthHeaders(
       }
       break;
     }
+    case "basic": {
+      if ("username" in registry.auth && registry.auth.username) {
+        const password = ("password" in registry.auth ? registry.auth.password : undefined) ?? "";
+        const credentials = `${registry.auth.username}:${password}`;
+        const encoded = Buffer.from(credentials, "utf8").toString("base64");
+        headers.Authorization = `Basic ${encoded}`;
+      }
+      break;
+    }
     case "api-key": {
       if ("key" in registry.auth && registry.auth.key) {
         const headerName = ("header" in registry.auth ? registry.auth.header : undefined) ?? "x-api-key";