@slashfi/agents-sdk 0.31.0 → 0.32.0

package/src/auth-governance.ts

@@ -0,0 +1,94 @@
+/**
+ * Auth Governance
+ *
+ * Single source of truth for visibility and access control decisions.
+ * Used by the server, middleware, and any custom implementations.
+ */
+
+import type { Visibility, AgentDefinition } from "./types.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ResolvedAuth {
+  issuer?: string;
+  callerId: string;
+  callerType: "agent" | "user" | "system";
+  scopes: string[];
+  /** All JWT claims from the verified token (passthrough) */
+  claims: Record<string, unknown>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Governance Functions
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Check if the auth context has admin scope.
+ */
+export function hasAdminScope(auth: ResolvedAuth | null): boolean {
+  if (!auth) return false;
+  return auth.scopes.includes("*") || auth.scopes.includes("admin");
+}
+
+/**
+ * Check if an agent is visible to the given auth context.
+ */
+export function canSeeAgent(
+  agent: AgentDefinition,
+  auth: ResolvedAuth | null,
+): boolean {
+  const visibility = ((agent as any).visibility ??
+    agent.config?.visibility ??
+    "internal") as Visibility;
+  if (hasAdminScope(auth)) return true;
+  if (visibility === "public") return true;
+  if (visibility === "internal" && auth) return true;
+  return false;
+}
+
+/**
+ * Check if a tool is visible to the given auth context.
+ *
+ * When agentVisibility is provided, tools without explicit visibility
+ * inherit from their parent agent.
+ */
+export function canSeeTool(
+  tool: { visibility?: Visibility },
+  auth: ResolvedAuth | null,
+  agentVisibility?: Visibility,
+): boolean {
+  const tv = tool.visibility;
+  if (hasAdminScope(auth)) return true;
+  // Tool has explicit visibility — respect it
+  if (tv === "public") return true;
+  if (tv === "private") return false;
+  if (
+    tv === "authenticated" &&
+    auth?.callerId &&
+    auth.callerId !== "anonymous"
+  )
+    return true;
+  if (tv === "internal" && auth) return true;
+  // No explicit tool visibility — inherit from agent or default to internal
+  if (!tv) {
+    const inherited = agentVisibility ?? "internal";
+    if (inherited === "public") return true;
+    if (inherited === "internal" && auth) return true;
+  }
+  return false;
+}
+
+/**
+ * Get visible tools for an agent, respecting visibility inheritance.
+ */
+export function getVisibleTools(
+  agent: AgentDefinition,
+  auth: ResolvedAuth | null,
+): typeof agent.tools {
+  const agentVisibility = ((agent as any).visibility ??
+    agent.config?.visibility ??
+    "internal") as Visibility;
+  return agent.tools.filter((t) => canSeeTool(t, auth, agentVisibility));
+}

package/src/call-agent-schema.ts

@@ -168,3 +168,36 @@ export const callAgentInputSchema = zodToJsonSchema(
   callAgentToolInputSchema as any,
   { target: "openAi" }
 );
+
+// ─────────────────────────────────────────────────────────────────────────────
+// list_agents schema
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const listAgentsToolInputSchema = z.object({
+  query: z
+    .string()
+    .optional()
+    .describe(
+      "Search query. When provided, returns agents ranked by BM25 relevance over paths, names, descriptions, and tool names.",
+    ),
+  limit: z
+    .number()
+    .optional()
+    .describe(
+      "Maximum number of results per page (default: 20)",
+    ),
+  cursor: z
+    .string()
+    .optional()
+    .describe(
+      "Pagination cursor from a previous response's nextCursor field.",
+    ),
+});
+
+export type ListAgentsInput = z.infer<typeof listAgentsToolInputSchema>;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const listAgentsInputSchema = zodToJsonSchema(
+  listAgentsToolInputSchema as any,
+  { target: "openAi" }
+);

package/src/codegen.test.ts

@@ -62,6 +62,10 @@ beforeAll(() => {
     port: 0,
     fetch(req) {
       return (async () => {
+        // Handle GET requests (well-known endpoints, etc.)
+        if (req.method === "GET") {
+          return new Response("Not Found", { status: 404 });
+        }
         const body = (await req.json()) as {
           id?: number;
           method: string;
@@ -305,6 +309,9 @@ describe("codegen JSON Schema support", () => {
       port: 0,
       fetch(req) {
         return (async () => {
+          if (req.method === "GET") {
+            return new Response("Not Found", { status: 404 });
+          }
           const body = (await req.json()) as { id?: number; method: string; params?: Record<string, unknown> };
           if (body.id === undefined) return new Response(null, { status: 202 });
 
@@ -401,6 +408,9 @@ describe("codegen pagination", () => {
       port: 0,
       fetch(req) {
         return (async () => {
+          if (req.method === "GET") {
+            return new Response("Not Found", { status: 404 });
+          }
           const body = (await req.json()) as {
             id?: number;
             method: string;

package/src/consumer.test.ts

@@ -534,3 +534,135 @@ describe("Secret URI resolution", () => {
     );
   });
 });
+
+// ─── API Key Auth Tests ──────────────────────────────────────────
+
+describe("Registry Consumer — API Key Auth", () => {
+  let server: AgentServer;
+  const PORT = 19894;
+  const API_KEY = "test-secret-key-12345";
+
+  beforeAll(async () => {
+    const registry = createAgentRegistry();
+    registry.register(mathAgent);
+    registry.register(echoAgent);
+
+    server = createAgentServer(registry, {
+      port: PORT,
+      resolveAuth: async (req) => {
+        const apiKey = req.headers.get("x-api-key");
+        if (apiKey === API_KEY) {
+          return {
+            callerId: "api-key-user",
+            callerType: "system" as const,
+            scopes: ["*"],
+          };
+        }
+        return null;
+      },
+    });
+    await server.start();
+  });
+
+  afterAll(async () => {
+    await server.stop();
+  });
+
+  test("consumer with api-key auth type can list agents", async () => {
+    const consumer = await createRegistryConsumer({
+      registries: [
+        {
+          url: `http://localhost:${PORT}`,
+          auth: { type: "api-key", key: API_KEY, header: "x-api-key" },
+        },
+      ],
+      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");
+  });
+
+  test("consumer with custom headers can list agents", async () => {
+    const consumer = await createRegistryConsumer({
+      registries: [
+        {
+          url: `http://localhost:${PORT}`,
+          headers: { "x-api-key": API_KEY },
+        },
+      ],
+      refs: [{ ref: "@math" }],
+    });
+
+    const agents = await consumer.list();
+    expect(agents.length).toBeGreaterThanOrEqual(2);
+  });
+
+  test("consumer with wrong api-key gets different auth context", async () => {
+    // Without the right key, resolveAuth returns null (no auth context)
+    // The server still processes the request but without auth identity
+    const consumer = await createRegistryConsumer({
+      registries: [
+        {
+          url: `http://localhost:${PORT}`,
+          auth: { type: "api-key", key: "wrong-key", header: "x-api-key" },
+        },
+      ],
+      refs: [{ ref: "@math" }],
+    });
+
+    // Can still list public agents (discovery doesn't require auth)
+    const agents = await consumer.list();
+    expect(agents.length).toBeGreaterThanOrEqual(1);
+  });
+
+  test("consumer with api-key auth can call tools", async () => {
+    const consumer = await createRegistryConsumer({
+      registries: [
+        {
+          url: `http://localhost:${PORT}`,
+          auth: { type: "api-key", key: API_KEY, header: "x-api-key" },
+        },
+      ],
+      refs: [{ ref: "@math" }],
+    });
+
+    const result = await consumer.call("@math", "add", { a: 10, b: 20 });
+    expect(result).toBeDefined();
+  });
+
+  test("inspect returns agent details via describe_tools", async () => {
+    const consumer = await createRegistryConsumer({
+      registries: [
+        {
+          url: `http://localhost:${PORT}`,
+          auth: { type: "api-key", key: API_KEY, header: "x-api-key" },
+        },
+      ],
+      refs: [{ ref: "@math" }],
+    });
+
+    const listing = await consumer.inspect("@math");
+    expect(listing).not.toBeNull();
+    expect(listing!.path).toBe("@math");
+  });
+
+  test("browse lists agents from a specific registry", async () => {
+    const consumer = await createRegistryConsumer({
+      registries: [
+        {
+          url: `http://localhost:${PORT}`,
+          auth: { type: "api-key", key: API_KEY, header: "x-api-key" },
+        },
+      ],
+      refs: [{ ref: "@math" }],
+    });
+
+    const agents = await consumer.browse(`http://localhost:${PORT}`);
+    expect(agents.length).toBeGreaterThan(0);
+    expect(agents.some((a) => a.path === "@math")).toBe(true);
+  });
+});

package/src/define-config.ts

@@ -42,11 +42,17 @@ export interface RegistryEntry {
   /** How to authenticate with this registry */
   auth?: RegistryAuth;
 
+  /** Arbitrary headers to send with every request to this registry (values can be secret URIs) */
+  headers?: Record<string, string>;
+
   /** Human-readable name / alias for this registry */
   name?: string;
 
   /** Publisher name shown in the app store UI */
   publisher?: string;
+
+  /** Connection status — set by validation/test, used to filter active entries */
+  status?: 'active' | 'inactive' | 'error';
 }
 
 // ============================================
@@ -75,6 +81,9 @@ export type RefEntry = {
 
       /** The registry where this ref was discovered */
       sourceRegistry?: { url: string; agentPath: string };
+
+      /** Connection status — set by validation/test, used to filter active entries */
+      status?: 'active' | 'inactive' | 'error';
     };
 
 // ============================================
@@ -109,6 +118,8 @@ export interface ResolvedRegistry {
   name: string;
   publisher: string;
   auth: RegistryAuth;
+  /** Resolved headers (secret URIs replaced with values at resolution time) */
+  headers?: Record<string, string>;
 }
 
 /** A normalized ref entry (after resolution) */
@@ -170,6 +181,7 @@ export function normalizeRegistry(
     name: entry.name ?? url.hostname,
     publisher: entry.publisher ?? url.hostname.split(".")[0],
     auth: entry.auth ?? { type: "none" },
+    ...(entry.headers && { headers: entry.headers }),
   };
 }
 

package/src/index.ts

@@ -136,6 +136,8 @@ export {
   detectAuth,
   resolveAuth,
   canSeeAgent,
+  canSeeTool,
+  getVisibleTools,
   hasAdminScope,
 } from "./server.js";
 export type {

package/src/key-manager.test.ts

@@ -118,6 +118,23 @@ describe("KeyManager", () => {
     expect(payload.exp - payload.iat).toBe(60);
   });
 
+  test("respects exp claim instead of default TTL", async () => {
+    const store = createMemoryKeyStore();
+    km = await createKeyManager({
+      store,
+      issuer: "http://test:3000",
+      tokenTtlSeconds: 300,
+      checkIntervalMs: 60_000,
+    });
+
+    const customExp = Math.floor(Date.now() / 1000) + 86400; // 24h from now
+    const token = await km.signJwt({ sub: "custom-exp", exp: customExp });
+    const payload = JSON.parse(
+      Buffer.from(token.split(".")[1], "base64url").toString(),
+    );
+    expect(payload.exp).toBe(customExp);
+  });
+
   // ---- Rotation tests ----
 
   test("rotation: creates new key when threshold exceeded", async () => {

package/src/key-manager.ts

@@ -236,12 +236,18 @@ export async function createKeyManager(
 
     async signJwt(claims: Record<string, unknown>): Promise<string> {
       const key = getActiveKey();
-      return new SignJWT({ ...claims } as any)
+      let builder = new SignJWT({ ...claims } as any)
         .setProtectedHeader({ alg: ALG, kid: key.kid })
         .setIssuer(issuer)
-        .setIssuedAt()
-        .setExpirationTime(`${tokenTtlSeconds}s`)
-        .sign(key.privateKey);
+        .setIssuedAt();
+
+      if (claims.exp != null) {
+        builder = builder.setExpirationTime(claims.exp as number);
+      } else {
+        builder = builder.setExpirationTime(`${tokenTtlSeconds}s`);
+      }
+
+      return builder.sign(key.privateKey);
     },
 
     async rotate(): Promise<void> {