@slashfi/agents-sdk 0.11.1 → 0.12.0

package/src/server.ts

@@ -32,7 +32,7 @@ import {
 } from "./agent-definitions/secrets.js";
 import { verifyJwt } from "./jwt.js";
 import type { SigningKey } from "./jwt.js";
-import { generateSigningKey, importSigningKey, exportSigningKey, buildJwks, verifyJwtLocal, verifyJwtFromIssuer } from "./jwt.js";
+import { generateSigningKey, importSigningKey, exportSigningKey, buildJwks, verifyJwtLocal, verifyJwtFromIssuer, signJwtES256 } from "./jwt.js";
 import type { AgentRegistry } from "./registry.js";
 import type { AgentDefinition, CallAgentRequest, Visibility } from "./types.js";
 
@@ -48,6 +48,37 @@ export interface TrustedIssuer {
   scopes: string[];
 }
 
+
+
+/** OAuth identity provider for /oauth/authorize + /oauth/callback flows */
+export interface OAuthIdentityProvider {
+  /**
+   * Handle /oauth/authorize — redirect the user to an external IdP.
+   * Return a Response (typically a 302 redirect).
+   */
+  authorize(req: Request, params: {
+    /** The verified JWT from the foreign registry */
+    token: string;
+    /** Claims from the verified JWT */
+    claims: Record<string, unknown>;
+    /** Where to redirect after completion */
+    redirectUri: string;
+    /** Base URL of this server */
+    baseUrl: string;
+    /** OAuth scope (e.g. "setup" for tenant creation flow) */
+    scope?: string;
+  }): Promise<Response>;
+
+  /**
+   * Handle /oauth/callback — process the IdP response.
+   * Should link the foreign identity to a local user and redirect back.
+   * Return a Response (typically a 302 redirect to redirectUri).
+   */
+  callback(req: Request, params: {
+    /** Base URL of this server */
+    baseUrl: string;
+  }): Promise<Response>;
+}
 export interface AgentServerOptions {
   /** Port to listen on (default: 3000) */
   port?: number;
@@ -67,9 +98,13 @@ export interface AgentServerOptions {
   trustedIssuers?: (TrustedIssuer | string)[];
   /** Pre-generated signing key (if not provided, one is generated on start) */
   signingKey?: SigningKey;
+  /** OAuth identity provider for cross-registry user linking */
+  oauthIdentityProvider?: OAuthIdentityProvider;
 }
 
 export interface AgentServer {
+  /** Initialize signing keys without starting HTTP server */
+  initKeys(): Promise<void>;
   /** Start the server */
   start(): Promise<void>;
   /** Stop the server */
@@ -80,6 +115,10 @@ export interface AgentServer {
   url: string | null;
   /** The agent registry this server uses */
   registry: AgentRegistry;
+  /** Sign a JWT with the server's signing key (for outbound calls) */
+  signJwt(claims: Record<string, unknown>): Promise<string>;
+  /** Dynamically add a trusted JWT issuer at runtime */
+  addTrustedIssuer(issuerUrl: string, scopes?: string[]): void;
 }
 
 // ============================================
@@ -105,12 +144,13 @@ interface JsonRpcResponse {
 // ============================================
 
 export interface AuthConfig {
-  store: AuthStore;
-  rootKey: string;
-  tokenTtl: number;
+  store?: AuthStore;
+  rootKey?: string;
+  tokenTtl?: number;
 }
 
 export interface ResolvedAuth {
+  issuer?: string;
   callerId: string;
   callerType: "agent" | "user" | "system";
   scopes: string[];
@@ -184,7 +224,7 @@ function mcpResult(value: unknown, isError = false) {
 // Auth Detection & Resolution
 // ============================================
 
-export function detectAuth(registry: AgentRegistry): AuthConfig | null {
+export function detectAuth(registry: AgentRegistry): AuthConfig {
   const authAgent = registry.get("@auth") as
     | (AgentDefinition & {
         __authStore?: AuthStore;
@@ -193,7 +233,7 @@ export function detectAuth(registry: AgentRegistry): AuthConfig | null {
       })
     | undefined;
 
-  if (!authAgent?.__authStore || !authAgent.__rootKey) return null;
+  if (!authAgent?.__authStore || !authAgent.__rootKey) return {};
 
   return {
     store: authAgent.__authStore,
@@ -204,7 +244,7 @@ export function detectAuth(registry: AgentRegistry): AuthConfig | null {
 
 export async function resolveAuth(
   req: Request,
-  authConfig: AuthConfig | null,
+  authConfig: AuthConfig,
   jwksOptions?: { signingKeys?: SigningKey[]; trustedIssuers?: TrustedIssuer[] },
 ): Promise<ResolvedAuth | null> {
   const authHeader = req.headers.get("Authorization");
@@ -214,7 +254,7 @@ export async function resolveAuth(
   if (scheme?.toLowerCase() !== "bearer" || !credential) return null;
 
   // Root key check
-  if (authConfig && credential === authConfig.rootKey) {
+  if (authConfig.rootKey && credential === authConfig.rootKey) {
     return {
       callerId: "root",
       callerType: "system",
@@ -285,7 +325,7 @@ export async function resolveAuth(
         exp?: number;
       };
 
-      if (payload.sub && authConfig) {
+      if (payload.sub && authConfig.store) {
         const client = await authConfig.store.getClient(payload.sub);
         if (client) {
           const verified = await verifyJwt(credential, client.clientSecretHash);
@@ -305,7 +345,7 @@ export async function resolveAuth(
   }
 
   // Legacy: opaque token validation (backwards compat)
-  if (!authConfig) return null;
+  if (!authConfig.store) return null;
   const token = await authConfig.store.validateToken(credential);
   if (!token) return null;
 
@@ -401,6 +441,7 @@ export function createAgentServer(
     serverName = "agents-sdk",
     serverVersion = "1.0.0",
     secretStore,
+    oauthIdentityProvider,
   } = options;
 
   // Signing keys for JWKS-based auth
@@ -487,6 +528,7 @@ export function createAgentServer(
           if (!req.metadata) req.metadata = {};
           req.metadata.scopes = auth.scopes;
           req.metadata.isRoot = auth.isRoot;
+          if (auth.issuer) req.metadata.issuer = auth.issuer;
         }
         if (auth?.isRoot) {
           req.callerType = "system";
@@ -552,73 +594,193 @@ export function createAgentServer(
     }
 
     const contentType = req.headers.get("Content-Type") ?? "";
-    let grantType: string;
-    let clientId: string;
-    let clientSecret: string;
+    let params: Record<string, string>;
 
     if (contentType.includes("application/x-www-form-urlencoded")) {
       const body = await req.text();
-      const params = new URLSearchParams(body);
-      grantType = params.get("grant_type") ?? "";
-      clientId = params.get("client_id") ?? "";
-      clientSecret = params.get("client_secret") ?? "";
+      const urlParams = new URLSearchParams(body);
+      params = Object.fromEntries(urlParams.entries());
     } else {
-      const body = (await req.json()) as Record<string, string>;
-      grantType = body.grant_type ?? "";
-      clientId = body.client_id ?? "";
-      clientSecret = body.client_secret ?? "";
+      params = (await req.json()) as Record<string, string>;
     }
 
-    if (grantType !== "client_credentials") {
-      return jsonResponse(
-        {
-          error: "unsupported_grant_type",
-          error_description: "Only client_credentials is supported",
-        },
-        400,
-      );
-    }
+    const grantType = params.grant_type ?? "";
 
-    if (!clientId || !clientSecret) {
-      return jsonResponse(
-        {
-          error: "invalid_request",
-          error_description: "Missing client_id or client_secret",
-        },
-        400,
-      );
+    // ── jwt_exchange grant: verify foreign JWT, resolve local identity ──
+    if (grantType === "jwt_exchange") {
+      const assertion = params.assertion ?? "";
+      if (!assertion) {
+        return jsonResponse(
+          { error: "invalid_request", error_description: "Missing assertion parameter" },
+          400,
+        );
+      }
+
+      try {
+        const result = await registry.call({
+          action: "execute_tool",
+          path: "@auth",
+          tool: "exchange_token",
+          params: { token: assertion },
+          callerType: "system",
+        });
+
+        const exchangeResult = (result as any)?.result;
+        // If the tool call failed, forward the error
+        if ((result as any)?.success === false) {
+          return jsonResponse(
+            { error: "server_error", error_description: (result as any)?.error ?? "Exchange tool failed", raw: JSON.stringify(result)?.slice(0, 300) },
+            500,
+          );
+        }
+
+        // ── Reverse registration: if caller is an agent-registry, auto-store connection ──
+        try {
+          const assertionParts = assertion.split(".");
+          if (assertionParts.length === 3) {
+            const assertionPayload = JSON.parse(atob(assertionParts[1].replace(/-/g, "+").replace(/_/g, "/"))) as any;
+            if (assertionPayload.type === "agent-registry" && assertionPayload.iss) {
+              // Find or create @remote-registry agent and store the reverse connection
+              const rrAgent = registry.get("@remote-registry") ?? registry.get("/agents/@remote-registry");
+              if (rrAgent) {
+                const setupTool = (rrAgent as any).tools?.find((t: any) => t.name === "setup_integration");
+                if (setupTool?.execute) {
+                  try {
+                    await setupTool.execute(
+                      { url: assertionPayload.iss, name: assertionPayload.name ?? "remote-registry" },
+                      { callerId: "system", callerType: "system", tenantId: "default", agentPath: "@remote-registry" },
+                    );
+                    console.error(`[jwt_exchange] Reverse connection stored for ${assertionPayload.iss}`);
+                  } catch (setupErr) {
+                    console.error(`[jwt_exchange] Reverse registration setup failed:`, setupErr);
+                  }
+                } else {
+                  console.error("[jwt_exchange] @remote-registry has no setup_integration tool — reverse registration skipped");
+                }
+              } else {
+                console.error("[jwt_exchange] @remote-registry agent not found — reverse registration skipped");
+              }
+            }
+          }
+        } catch (reverseErr) {
+          console.error("[jwt_exchange] Reverse registration check failed:", reverseErr);
+        }
+
+        if (!exchangeResult) {
+          return jsonResponse(
+            { error: "server_error", error_description: `Exchange returned null: ${JSON.stringify(result)?.slice(0, 300)}` },
+            500,
+          );
+        }
+
+        // User not linked yet — needs OAuth identity linking
+        if (exchangeResult.needsAuth) {
+          const baseUrl = new URL(req.url).origin;
+          const authorizeUrl = new URL(`${baseUrl}${basePath}/oauth/authorize`);
+          authorizeUrl.searchParams.set("token", assertion);
+          if (params.redirect_uri) {
+            authorizeUrl.searchParams.set("redirect_uri", params.redirect_uri);
+          }
+          if (params.scope) {
+            authorizeUrl.searchParams.set("scope", params.scope);
+          }
+          return jsonResponse(
+            {
+              error: "identity_required",
+              error_description: "User identity not linked. Redirect to authorize_url to complete linking.",
+              authorize_url: authorizeUrl.toString(),
+              tenant_id: exchangeResult.tenantId,
+            },
+            403,
+          );
+        }
+
+        // User found — sign a local access token
+        if (exchangeResult.userId && serverSigningKeys.length > 0) {
+          const sigKey = serverSigningKeys[0];
+          const token = await signJwtES256(
+            {
+              sub: exchangeResult.userId,
+              name: exchangeResult.userId,
+              scopes: ["*"],
+              tenantId: exchangeResult.tenantId,
+            },
+            sigKey.privateKey,
+            sigKey.kid,
+            new URL(req.url).origin,
+            `${authConfig.tokenTtl ?? 3600}s`,
+          );
+
+          return jsonResponse({
+            access_token: token,
+            token_type: "Bearer",
+            expires_in: authConfig.tokenTtl ?? 3600,
+            user_id: exchangeResult.userId,
+            tenant_id: exchangeResult.tenantId,
+          });
+        }
+
+        return jsonResponse(exchangeResult);
+      } catch (err) {
+        console.error("[oauth] JWT exchange error:", err);
+        return jsonResponse(
+          { error: "server_error", error_description: `JWT exchange failed: ${err instanceof Error ? err.message : String(err)}` },
+          500,
+        );
+      }
     }
 
-    try {
-      const result = await registry.call({
-        action: "execute_tool",
-        path: "@auth",
-        tool: "token",
-        params: { clientId, clientSecret },
-        callerType: "system",
-      });
+    // ── client_credentials grant ──
+    if (grantType === "client_credentials") {
+      const clientId = params.client_id ?? "";
+      const clientSecret = params.client_secret ?? "";
 
-      const tokenResult = (result as any)?.result;
-      if (!tokenResult?.accessToken) {
+      if (!clientId || !clientSecret) {
         return jsonResponse(
-          { error: "invalid_client", error_description: "Authentication failed" },
-          401,
+          { error: "invalid_request", error_description: "Missing client_id or client_secret" },
+          400,
         );
       }
 
-      return jsonResponse({
-        access_token: tokenResult.accessToken,
-        token_type: "Bearer",
-        expires_in: tokenResult.expiresIn ?? authConfig.tokenTtl,
-        refresh_token: tokenResult.refreshToken,
-      });
-    } catch (err) {
-      console.error("[oauth] Token error:", err);
-      return jsonResponse(
-        { error: "server_error", error_description: "Token exchange failed" },
-        500,
-      );
+      try {
+        const result = await registry.call({
+          action: "execute_tool",
+          path: "@auth",
+          tool: "token",
+          params: { clientId, clientSecret },
+          callerType: "system",
+        });
+
+        const tokenResult = (result as any)?.result;
+        if (!tokenResult?.accessToken) {
+          return jsonResponse(
+            { error: "invalid_client", error_description: "Authentication failed" },
+            401,
+          );
+        }
+
+        return jsonResponse({
+          access_token: tokenResult.accessToken,
+          token_type: "Bearer",
+          expires_in: tokenResult.expiresIn ?? authConfig.tokenTtl,
+          refresh_token: tokenResult.refreshToken,
+        });
+      } catch (err) {
+        console.error("[oauth] Token error:", err);
+        return jsonResponse(
+          { error: "server_error", error_description: "Token exchange failed" },
+          500,
+        );
+      }
     }
+
+    return jsonResponse(
+      {
+        error: "unsupported_grant_type",
+        error_description: "Supported grant types: client_credentials, jwt_exchange",
+      },
+      400,
+    );
   }
 
   // ──────────────────────────────────────────
@@ -636,13 +798,10 @@ export function createAgentServer(
       }
 
       // Resolve auth for all requests
-      // Run resolveAuth when authConfig OR trustedIssuers are present
-      const auth = (authConfig || configTrustedIssuers.length > 0)
-        ? await resolveAuth(req, authConfig, {
-            signingKeys: serverSigningKeys,
-            trustedIssuers: configTrustedIssuers,
-          })
-        : null;
+      const auth = await resolveAuth(req, authConfig, {
+        signingKeys: serverSigningKeys,
+        trustedIssuers: configTrustedIssuers,
+      });
 
       // Also check header-based identity (for proxied requests)
       const headerAuth: ResolvedAuth | null = !auth
@@ -670,12 +829,81 @@ export function createAgentServer(
         return cors ? addCors(jsonResponse(result)) : jsonResponse(result);
       }
 
-      // ── POST /oauth/token → OAuth2 client_credentials ──
+      // ── POST /oauth/token → OAuth2 token exchange ──
       if (path === "/oauth/token" && req.method === "POST") {
         const res = await handleOAuthToken(req);
         return cors ? addCors(res) : res;
       }
 
+      // ── GET /oauth/authorize → Identity linking redirect (browser flow) ──
+      if (path === "/oauth/authorize" && req.method === "GET") {
+        if (!oauthIdentityProvider) {
+          const res = jsonResponse(
+            { error: "not_configured", error_description: "No OAuth identity provider configured" },
+            404,
+          );
+          return cors ? addCors(res) : res;
+        }
+        const url = new URL(req.url);
+        const token = url.searchParams.get("token") ?? "";
+        const redirectUri = url.searchParams.get("redirect_uri") ?? "";
+
+        if (!token) {
+          const res = jsonResponse(
+            { error: "invalid_request", error_description: "Missing token parameter" },
+            400,
+          );
+          return cors ? addCors(res) : res;
+        }
+
+        // Verify the JWT against trusted issuers
+        let claims: Record<string, unknown> | null = null;
+        const issuerUrls = configTrustedIssuers.map(i => typeof i === "string" ? i : i.issuer);
+        for (const issuerUrl of issuerUrls) {
+          try {
+            const result = await verifyJwtFromIssuer(token, issuerUrl);
+            if (result) {
+              claims = result as unknown as Record<string, unknown>;
+              break;
+            }
+          } catch { /* try next issuer */ }
+        }
+        if (!claims) {
+          const res = jsonResponse(
+            { error: "invalid_token", error_description: "JWT verification failed against all trusted issuers" },
+            401,
+          );
+          return cors ? addCors(res) : res;
+        }
+
+        const baseUrl = new URL(req.url).origin;
+        const scope = url.searchParams.get("scope") ?? undefined;
+        const res = await oauthIdentityProvider.authorize(req, {
+          token,
+          claims,
+          redirectUri,
+          baseUrl: baseUrl + basePath,
+          scope,
+        });
+        return cors ? addCors(res) : res;
+      }
+
+      // ── GET /oauth/callback → Identity linking callback ──
+      if (path === "/oauth/callback" && req.method === "GET") {
+        if (!oauthIdentityProvider) {
+          const res = jsonResponse(
+            { error: "not_configured", error_description: "No OAuth identity provider configured" },
+            404,
+          );
+          return cors ? addCors(res) : res;
+        }
+        const baseUrl = new URL(req.url).origin;
+        const res = await oauthIdentityProvider.callback(req, {
+          baseUrl: baseUrl + basePath,
+        });
+        return cors ? addCors(res) : res;
+      }
+
       // ── GET /health → Health check ──
       if (path === "/health" && req.method === "GET") {
         const res = jsonResponse({ status: "ok", agents: registry.listPaths() });
@@ -700,7 +928,8 @@ export function createAgentServer(
           token_endpoint: `${baseUrl}/oauth/token`,
           agents_endpoint: `${baseUrl}/list`,
           call_endpoint: baseUrl,
-          supported_grant_types: ["client_credentials"],
+          supported_grant_types: ["client_credentials", "jwt_exchange"],
+          authorization_endpoint: `${baseUrl}/oauth/authorize`,
           agents: registry.listPaths(),
         });
         return cors ? addCors(res) : res;
@@ -772,11 +1001,11 @@ export function createAgentServer(
     url: null,
     registry,
 
-    async start() {
-      // Load or generate signing key for JWKS
-      if (options.signingKey) {
+    async initKeys() {
+      // Load or generate signing keys (without starting Bun.serve)
+      if (options.signingKey && serverSigningKeys.length === 0) {
         serverSigningKeys.push(options.signingKey);
-      } else if (authConfig?.store?.getSigningKeys) {
+      } else if (authConfig?.store?.getSigningKeys && serverSigningKeys.length === 0) {
         const stored = await authConfig.store.getSigningKeys() ?? [];
         for (const exported of stored) {
           serverSigningKeys.push(await importSigningKey(exported));
@@ -789,6 +1018,10 @@ export function createAgentServer(
           await authConfig.store.storeSigningKey(await exportSigningKey(key));
         }
       }
+    },
+
+    async start() {
+      await this.initKeys();
 
       serverInstance = Bun.serve({
         port,
@@ -808,5 +1041,28 @@ export function createAgentServer(
     },
 
     fetch,
+
+    async signJwt(claims: Record<string, unknown>): Promise<string> {
+      if (serverSigningKeys.length === 0) {
+        throw new Error('No signing keys available. Call start() or initKeys() first.');
+      }
+      const key = serverSigningKeys[0];
+      return signJwtES256(
+        { sub: 'system', name: 'atlas-os', scopes: ['*'], ...claims } as any,
+        key.privateKey,
+        key.kid,
+        options.serverName ?? 'agents-sdk',
+        '1h',
+      );
+    },
+
+    addTrustedIssuer(issuerUrl: string, scopes?: string[]): void {
+      // Avoid duplicates
+      const existing = configTrustedIssuers.find(i => i.issuer === issuerUrl);
+      if (!existing) {
+        configTrustedIssuers.push({ issuer: issuerUrl, scopes: scopes ?? ['*'] });
+        console.error(`[agent-server] Added trusted issuer: ${issuerUrl}`);
+      }
+    },
   };
 }

package/src/types.ts

@@ -20,6 +20,11 @@ export type JsonSchema = {
   enum?: unknown[];
   default?: unknown;
   additionalProperties?: boolean | JsonSchema;
+  /** Agent refs (paths to other agents this agent can call) */
+  refs?: Record<string, { description?: string }>;
+
+  /** Tools to expose publicly (by name) */
+  public?: { tools?: string[] };
   [key: string]: unknown;
 };
 
@@ -73,6 +78,30 @@ export interface IntegrationMethods {
   update(params: Record<string, unknown>, ctx: IntegrationMethodContext): Promise<IntegrationMethodResult>;
 }
 
+
+
+/** Hooks for agents that implement the integrations interface. */
+export interface IntegrationHooks {
+  /** Provider metadata */
+  provider: string;
+  displayName: string;
+  icon?: string;
+  category?: string;
+  description?: string;
+
+  /** Set up this integration (discover, configure, establish trust) */
+  setup?(params: Record<string, unknown>, ctx: ToolContext): Promise<IntegrationMethodResult>;
+  /** Connect a user to this integration (OAuth, identity linking) */
+  connect?(params: Record<string, unknown>, ctx: ToolContext): Promise<IntegrationMethodResult>;
+  /** Discover available instances of this integration */
+  discover?(params: Record<string, unknown>, ctx: ToolContext): Promise<IntegrationMethodResult>;
+  /** List connected instances */
+  list?(params: Record<string, unknown>, ctx: ToolContext): Promise<IntegrationMethodResult>;
+  /** Get details of a specific instance */
+  get?(params: Record<string, unknown>, ctx: ToolContext): Promise<IntegrationMethodResult>;
+  /** Update an existing instance config */
+  update?(params: Record<string, unknown>, ctx: ToolContext): Promise<IntegrationMethodResult>;
+}
 export interface IntegrationConfig {
   /** Provider identifier (e.g., "databases", "slack", "github") */
   provider: string;
@@ -134,6 +163,11 @@ export interface AgentConfig {
   modelParams?: {
     maxTokens?: number;
     temperature?: number;
+  /** Agent refs (paths to other agents this agent can call) */
+  refs?: Record<string, { description?: string }>;
+
+  /** Tools to expose publicly (by name) */
+  public?: { tools?: string[] };
     [key: string]: unknown;
   };
 
@@ -145,6 +179,11 @@ export interface AgentConfig {
   integration?: IntegrationConfig;
 
   /** Additional configuration */
+  /** Agent refs (paths to other agents this agent can call) */
+  refs?: Record<string, { description?: string }>;
+
+  /** Tools to expose publicly (by name) */
+  public?: { tools?: string[] };
   [key: string]: unknown;
 }
 
@@ -197,6 +236,11 @@ export interface ToolContext extends CoreContext {
   callerType: CallerType;
 
   /** Application-specific extensions (e.g., OS services, stores) */
+  /** Agent refs (paths to other agents this agent can call) */
+  refs?: Record<string, { description?: string }>;
+
+  /** Tools to expose publicly (by name) */
+  public?: { tools?: string[] };
   [key: string]: unknown;
 }
 
@@ -492,7 +536,6 @@ export interface AgentDefinition<TContext extends ToolContext = ToolContext> {
    * When set alongside config.integration, this agent can be called
    * by @integrations via standard methods (setup, list, connect, get, update).
    */
-  integrationMethods?: IntegrationMethods;
 
   /**
    * Lazy loader for lifecycle listeners.