@slashfi/agents-sdk 0.11.2 → 0.13.0

package/src/agent-definitions/users.ts

@@ -250,10 +250,30 @@ export function createUsersAgent(options: UsersAgentOptions): AgentDefinition {
         name: { type: "string", description: "Display name" },
         avatarUrl: { type: "string", description: "Avatar URL" },
         metadata: { type: "object", description: "Additional metadata" },
+        externalRef: {
+          type: "object",
+          description: "Link to a user on a remote system. Creates identity automatically.",
+          properties: {
+            issuer: { type: "string", description: "Issuer URL of the remote system" },
+            userId: { type: "string", description: "User ID on the remote system" },
+          },
+        },
       },
       required: ["tenantId"],
     },
     execute: async (input: any, __ctx: ToolContext) => {
+      // If externalRef provided, check if identity already exists
+      if (input.externalRef) {
+        const existing = await store.findIdentityByProviderUserId(
+          input.externalRef.issuer,
+          input.externalRef.userId,
+        );
+        if (existing) {
+          const user = await store.getUser(existing.userId);
+          return { success: true, user, identity: existing, alreadyLinked: true };
+        }
+      }
+
       const user = await store.createUser({
         id: input.id ?? generateId("user_"),
         tenantId: input.tenantId,
@@ -262,7 +282,21 @@ export function createUsersAgent(options: UsersAgentOptions): AgentDefinition {
         avatarUrl: input.avatarUrl,
         metadata: input.metadata,
       });
-      return { success: true, user };
+
+      // Auto-create identity link if externalRef provided
+      let identity: UserIdentity | undefined;
+      if (input.externalRef) {
+        identity = await store.createIdentity({
+          id: generateId("uid_"),
+          userId: user.id,
+          provider: input.externalRef.issuer,
+          providerUserId: input.externalRef.userId,
+          email: input.email,
+          name: input.name,
+        });
+      }
+
+      return { success: true, user, identity };
     },
   });
 

package/src/define.ts

@@ -5,10 +5,10 @@
  */
 
 import type {
+  IntegrationHooks,
   AgentConfig,
   AgentDefinition,
   AgentRuntime,
-  IntegrationMethods,
   JsonSchema,
   ToolContext,
   ToolDefinition,
@@ -115,10 +115,18 @@ export interface DefineAgentOptions<
   allowedCallers?: string[];
 
   /**
+   * Integration hooks. When provided, defineAgent auto-generates
+   * setup_integration, connect_integration, etc. as tools.
+   */
+  integration?: IntegrationHooks;
+
+  /** Lazy loader for event listeners (e.g. entrypoint.ts) */
+  loadListeners?: () => Promise<unknown>;
+
+  /**
+   * @deprecated Use `integration` instead.
    * Integration method callbacks.
-   * Implement these when this agent acts as an integration.
    */
-  integrationMethods?: IntegrationMethods;
 }
 
 /**
@@ -148,14 +156,98 @@ export interface DefineAgentOptions<
 export function defineAgent<TContext extends ToolContext = ToolContext>(
   options: DefineAgentOptions<TContext>,
 ): AgentDefinition<TContext> {
+  const tools = [...(options.tools ?? [])];
+  let config = options.config;
+
+  // Auto-generate integration tools from hooks
+  if (options.integration) {
+    const h = options.integration;
+
+    // Set config.integration metadata if not already set
+    if (!config?.integration) {
+      config = {
+        ...config,
+        integration: {
+          provider: h.provider,
+          displayName: h.displayName,
+          icon: h.icon,
+          category: h.category,
+          description: h.description,
+        },
+      };
+    }
+
+    if (h.setup) {
+      const fn = h.setup;
+      tools.push(defineTool({
+        name: "setup_integration",
+        description: `Set up ${h.displayName} integration.`,
+        visibility: "public" as const,
+        inputSchema: { type: "object" as const, properties: { url: { type: "string" }, name: { type: "string" }, config: { type: "object" } } },
+        execute: (input: any, ctx: any) => fn(input, ctx),
+      }) as any);
+    }
+    if (h.connect) {
+      const fn = h.connect;
+      tools.push(defineTool({
+        name: "connect_integration",
+        description: `Connect a user to ${h.displayName}.`,
+        visibility: "public" as const,
+        inputSchema: { type: "object" as const, properties: { registryId: { type: "string" }, oidcUserId: { type: "string" }, redirectUri: { type: "string" } }, required: ["registryId"] as const },
+        execute: (input: any, ctx: any) => fn(input, ctx),
+      }) as any);
+    }
+    if (h.discover) {
+      const fn = h.discover;
+      tools.push(defineTool({
+        name: "discover_integrations",
+        description: `Discover available ${h.displayName} instances.`,
+        visibility: "public" as const,
+        inputSchema: { type: "object" as const, properties: { url: { type: "string" } } },
+        execute: (input: any, ctx: any) => fn(input, ctx),
+      }) as any);
+    }
+    if (h.list) {
+      const fn = h.list;
+      tools.push(defineTool({
+        name: "list_integrations",
+        description: `List connected ${h.displayName} instances.`,
+        visibility: "public" as const,
+        inputSchema: { type: "object" as const, properties: {} },
+        execute: (input: any, ctx: any) => fn(input, ctx),
+      }) as any);
+    }
+    if (h.get) {
+      const fn = h.get;
+      tools.push(defineTool({
+        name: "get_integration",
+        description: `Get details of a ${h.displayName} instance.`,
+        visibility: "public" as const,
+        inputSchema: { type: "object" as const, properties: { registryId: { type: "string" } }, required: ["registryId"] as const },
+        execute: (input: any, ctx: any) => fn(input, ctx),
+      }) as any);
+    }
+    if (h.update) {
+      const fn = h.update;
+      tools.push(defineTool({
+        name: "update_integration",
+        description: `Update a ${h.displayName} instance.`,
+        visibility: "public" as const,
+        inputSchema: { type: "object" as const, properties: { registryId: { type: "string" }, name: { type: "string" }, url: { type: "string" } }, required: ["registryId"] as const },
+        execute: (input: any, ctx: any) => fn(input, ctx),
+      }) as any);
+    }
+  }
+
+
   return {
     path: options.path,
     entrypoint: options.entrypoint,
-    config: options.config,
-    tools: options.tools ?? [],
+    config,
+    tools,
     runtime: options.runtime,
     visibility: options.visibility,
     allowedCallers: options.allowedCallers,
-    integrationMethods: options.integrationMethods,
+    loadListeners: options.loadListeners,
   };
 }

package/src/index.ts

@@ -85,6 +85,7 @@ export type {
   IntegrationMethods,
   IntegrationMethodResult,
   IntegrationMethodContext,
+  IntegrationHooks,
   Visibility,
 } from "./types.js";
 
@@ -98,7 +99,7 @@ export type { AgentRegistry, AgentRegistryOptions } from "./registry.js";
 
 // Server
 export { createAgentServer, detectAuth, resolveAuth, canSeeAgent } from "./server.js";
-export type { AgentServer, AgentServerOptions, AuthConfig, ResolvedAuth, TrustedIssuer } from "./server.js";
+export type { AgentServer, AgentServerOptions, AuthConfig, OAuthIdentityProvider, ResolvedAuth, TrustedIssuer } from "./server.js";
 
 // Secret Collection
 export {
@@ -193,3 +194,4 @@ export type {
 export * from "./integrations-store.js";
 export * from "./integration-interface.js";
 export type { ContextFactory } from "./registry.js";
+export { createKeyManager, type KeyManager, type KeyStore, type KeyManagerOptions, type StoredKey, type KeyStatus } from "./key-manager.js";

package/src/jwt.ts

@@ -80,7 +80,7 @@ export interface ExportedKeyPair {
  * Generate a new ES256 signing key pair.
  */
 export async function generateSigningKey(kid?: string): Promise<SigningKey> {
-  const { privateKey, publicKey } = await generateKeyPair("ES256");
+  const { privateKey, publicKey } = await generateKeyPair("ES256", { extractable: true });
   return {
     kid: kid ?? `key-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
     privateKey,

package/src/key-manager.test.ts

@@ -0,0 +1,273 @@
+import { describe, test, expect, afterEach } from "bun:test";
+import { createKeyManager, type KeyStore, type StoredKey, type KeyManager } from "./key-manager";
+import { jwtVerify, createLocalJWKSet } from "jose";
+
+// In-memory KeyStore for testing (no DB needed)
+function createMemoryKeyStore(): KeyStore & { keys: StoredKey[] } {
+  const keys: StoredKey[] = [];
+  return {
+    keys,
+    async loadKeys() {
+      return keys.filter((k) => k.status !== "revoked");
+    },
+    async insertKey(key: StoredKey) {
+      keys.push(key);
+    },
+    async deprecateAllActive() {
+      for (const k of keys) {
+        if (k.status === "active") k.status = "deprecated";
+      }
+    },
+    async cleanupExpired() {
+      const now = Date.now();
+      const before = keys.length;
+      const remaining = keys.filter((k) => k.expiresAt.getTime() > now);
+      keys.length = 0;
+      keys.push(...remaining);
+      return before - remaining.length;
+    },
+    // Transaction support: snapshot + rollback on error
+    async transaction<T>(fn: () => Promise<T>): Promise<T> {
+      const snapshot = keys.map((k) => ({ ...k }));
+      try {
+        return await fn();
+      } catch (err) {
+        // Rollback
+        keys.length = 0;
+        keys.push(...snapshot);
+        throw err;
+      }
+    },
+  };
+}
+
+describe("KeyManager", () => {
+  let km: KeyManager;
+
+  afterEach(() => {
+    km?.stop();
+  });
+
+  test("creates initial key on startup", async () => {
+    const store = createMemoryKeyStore();
+    km = await createKeyManager({
+      store,
+      issuer: "http://test:3000",
+      checkIntervalMs: 60_000,
+    });
+
+    const jwks = km.getJwks();
+    expect(jwks.keys).toHaveLength(1);
+    expect(jwks.keys[0].alg).toBe("ES256");
+    expect(jwks.keys[0].kid).toMatch(/^key-/);
+    // No private key exposed
+    expect(jwks.keys[0].d).toBeUndefined();
+  });
+
+  test("signs a valid JWT", async () => {
+    const store = createMemoryKeyStore();
+    km = await createKeyManager({
+      store,
+      issuer: "http://test:3000",
+      checkIntervalMs: 60_000,
+    });
+
+    const token = await km.signJwt({ sub: "test-service" });
+    const parts = token.split(".");
+    expect(parts).toHaveLength(3);
+
+    const payload = JSON.parse(
+      Buffer.from(parts[1], "base64url").toString()
+    );
+    expect(payload.sub).toBe("test-service");
+    expect(payload.iss).toBe("http://test:3000");
+    expect(payload.exp - payload.iat).toBe(300); // default 5 min TTL
+  });
+
+  test("token verifies against JWKS", async () => {
+    const store = createMemoryKeyStore();
+    km = await createKeyManager({
+      store,
+      issuer: "http://test:3000",
+      checkIntervalMs: 60_000,
+    });
+
+    const token = await km.signJwt({ sub: "verify-me" });
+    const jwks = km.getJwks();
+    const JWKS = createLocalJWKSet(jwks);
+    const { payload } = await jwtVerify(token, JWKS);
+    expect(payload.sub).toBe("verify-me");
+  });
+
+  test("custom token TTL", async () => {
+    const store = createMemoryKeyStore();
+    km = await createKeyManager({
+      store,
+      issuer: "http://test:3000",
+      tokenTtlSeconds: 60,
+      checkIntervalMs: 60_000,
+    });
+
+    const token = await km.signJwt({ sub: "short-lived" });
+    const payload = JSON.parse(
+      Buffer.from(token.split(".")[1], "base64url").toString()
+    );
+    expect(payload.exp - payload.iat).toBe(60);
+  });
+
+  // ---- Rotation tests ----
+
+  test("rotation: creates new key when threshold exceeded", async () => {
+    const store = createMemoryKeyStore();
+    km = await createKeyManager({
+      store,
+      issuer: "http://test:3000",
+      rotationThresholdMs: 0, // immediate rotation
+      checkIntervalMs: 60_000,
+    });
+
+    const initialKid = km.getJwks().keys.find(
+      (k) => store.keys.find((sk) => sk.kid === k.kid)?.status === "active"
+    )?.kid;
+
+    // Force rotation
+    await km.rotate();
+
+    const activeKeys = store.keys.filter((k) => k.status === "active");
+    expect(activeKeys).toHaveLength(1);
+    expect(activeKeys[0].kid).not.toBe(initialKid);
+
+    const deprecatedKeys = store.keys.filter((k) => k.status === "deprecated");
+    expect(deprecatedKeys.length).toBeGreaterThanOrEqual(1);
+  });
+
+  test("rotation: deprecated keys still in JWKS for verification", async () => {
+    const store = createMemoryKeyStore();
+    km = await createKeyManager({
+      store,
+      issuer: "http://test:3000",
+      rotationThresholdMs: 0,
+      checkIntervalMs: 60_000,
+    });
+
+    await km.rotate();
+
+    const jwksKids = km.getJwks().keys.map((k) => k.kid);
+    const nonRevoked = store.keys.filter((k) => k.status !== "revoked");
+    for (const key of nonRevoked) {
+      expect(jwksKids).toContain(key.kid);
+    }
+  });
+
+  test("rotation: pre-rotation tokens still verify", async () => {
+    const store = createMemoryKeyStore();
+    km = await createKeyManager({
+      store,
+      issuer: "http://test:3000",
+      rotationThresholdMs: 0,
+      checkIntervalMs: 60_000,
+    });
+
+    const preRotationToken = await km.signJwt({ sub: "pre-rotate" });
+    await km.rotate();
+
+    // Pre-rotation token should still verify (deprecated key still in JWKS)
+    const jwks = km.getJwks();
+    const JWKS = createLocalJWKSet(jwks);
+    const { payload } = await jwtVerify(preRotationToken, JWKS);
+    expect(payload.sub).toBe("pre-rotate");
+  });
+
+  test("rotation: exactly 1 active key", async () => {
+    const store = createMemoryKeyStore();
+    km = await createKeyManager({
+      store,
+      issuer: "http://test:3000",
+      rotationThresholdMs: 0,
+      checkIntervalMs: 60_000,
+    });
+
+    await km.rotate();
+    await km.rotate();
+
+    const activeKeys = store.keys.filter((k) => k.status === "active");
+    expect(activeKeys).toHaveLength(1);
+  });
+
+  test("rotation: tokens fail verification after key expires and is cleaned up", async () => {
+    const store = createMemoryKeyStore();
+    km = await createKeyManager({
+      store,
+      issuer: "http://test:3000",
+      rotationThresholdMs: 0,
+      keyLifetimeMs: 1, // 1ms — keys expire almost immediately
+      checkIntervalMs: 60_000,
+    });
+
+    const token = await km.signJwt({ sub: "will-expire" });
+
+    // Token should verify now (key is active)
+    const JWKS = createLocalJWKSet(km.getJwks());
+    const { payload } = await jwtVerify(token, JWKS);
+    expect(payload.sub).toBe("will-expire");
+
+    // Wait for key to expire, then rotate (which cleans up expired keys)
+    await new Promise((r) => setTimeout(r, 5));
+    await km.rotate();
+
+    // Old key should be gone from JWKS — verification should fail
+    const jwksAfter = km.getJwks();
+    const JWKS2 = createLocalJWKSet(jwksAfter);
+    let failed = false;
+    try {
+      await jwtVerify(token, JWKS2);
+    } catch {
+      failed = true;
+    }
+    expect(failed).toBe(true);
+  });
+
+    // ---- Transaction tests ----
+
+  test("transaction: rotate is atomic (rollback on failure)", async () => {
+    const store = createMemoryKeyStore();
+    km = await createKeyManager({
+      store,
+      issuer: "http://test:3000",
+      checkIntervalMs: 60_000,
+    });
+
+    const initialKid = store.keys[0].kid;
+
+    // Monkey-patch insertKey to fail mid-transaction
+    const origInsert = store.insertKey;
+    store.insertKey = async () => { throw new Error("simulated failure"); };
+
+    // Rotation should fail, but state should be rolled back
+    try { await km.rotate(); } catch {}
+
+    // Original key should still be active (not deprecated)
+    const active = store.keys.filter((k) => k.status === "active");
+    expect(active).toHaveLength(1);
+    expect(active[0].kid).toBe(initialKid);
+
+    // Restore
+    store.insertKey = origInsert;
+  });
+
+  // ---- enableRotation option ----
+
+  test("enableRotation: false skips background interval", async () => {
+    const store = createMemoryKeyStore();
+    km = await createKeyManager({
+      store,
+      issuer: "http://test:3000",
+      enableRotation: false,
+    });
+
+    // Should still have an initial key
+    expect(km.getJwks().keys).toHaveLength(1);
+    // But stop() should be a no-op (no interval to clear)
+    km.stop();
+  });
+});