@slashfi/agents-sdk 0.8.0 → 0.10.0

package/src/jwt.ts

@@ -1,9 +1,223 @@
 /**
  * JWT utilities for auth tokens.
  *
- * Minimal JWT implementation using Web Crypto API (HMAC-SHA256).
- * No external dependencies.
+ * Supports two modes:
+ * - ES256 (asymmetric) — for production / cross-registry trust
+ * - HS256 (HMAC) — for backward compat / simple single-server setups
+ *
+ * Uses `jose` library for all crypto operations.
+ */
+
+import {
+  SignJWT,
+  jwtVerify,
+  generateKeyPair,
+  exportJWK,
+  importJWK,
+  createRemoteJWKSet,
+  type JWTPayload,
+
+  type JWK,
+} from "jose";
+
+// ============================================
+// Types
+// ============================================
+
+/** JWT payload for auth tokens */
+export interface AgentJwtPayload {
+  /** Subject - the client ID or user ID */
+  sub: string;
+  /** Client/user name */
+  name: string;
+  /** Issuer URL */
+  iss?: string;
+  /** Tenant ID */
+  tenantId?: string;
+  /** User ID (when acting on behalf of a user) */
+  userId?: string;
+  /** Scopes */
+  scopes: string[];
+  /** Identities (for cross-registry provisioning) */
+  identities?: Array<{ provider: string; id: string; [key: string]: unknown }>;
+  /** Issued at (unix seconds) */
+  iat: number;
+  /** Expires at (unix seconds) */
+  exp: number;
+}
+
+/** A signing key with metadata */
+export interface SigningKey {
+  /** Unique key ID */
+  kid: string;
+  /** Private key (for signing) */
+  privateKey: CryptoKey;
+  /** Public key (for verification + JWKS) */
+  publicKey: CryptoKey;
+  /** Algorithm */
+  alg: string;
+  /** Status */
+  status: "active" | "deprecated" | "revoked";
+  /** When this key was created */
+  createdAt: number;
+}
+
+/** Exported key pair for storage */
+export interface ExportedKeyPair {
+  kid: string;
+  alg: string;
+  privateKeyJwk: JWK;
+  publicKeyJwk: JWK;
+  status: "active" | "deprecated" | "revoked";
+  createdAt: number;
+}
+
+// ============================================
+// Key Generation
+// ============================================
+
+/**
+ * Generate a new ES256 signing key pair.
+ */
+export async function generateSigningKey(kid?: string): Promise<SigningKey> {
+  const { privateKey, publicKey } = await generateKeyPair("ES256");
+  return {
+    kid: kid ?? `key-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    privateKey,
+    publicKey,
+    alg: "ES256",
+    status: "active",
+    createdAt: Date.now(),
+  };
+}
+
+/**
+ * Export a signing key to JWK format (for storage).
+ */
+export async function exportSigningKey(key: SigningKey): Promise<ExportedKeyPair> {
+  const privateKeyJwk = await exportJWK(key.privateKey);
+  const publicKeyJwk = await exportJWK(key.publicKey);
+  return {
+    kid: key.kid,
+    alg: key.alg,
+    privateKeyJwk,
+    publicKeyJwk,
+    status: key.status,
+    createdAt: key.createdAt,
+  };
+}
+
+/**
+ * Import a signing key from stored JWK format.
+ */
+export async function importSigningKey(exported: ExportedKeyPair): Promise<SigningKey> {
+  const privateKey = await importJWK(exported.privateKeyJwk, exported.alg) as CryptoKey;
+  const publicKey = await importJWK(exported.publicKeyJwk, exported.alg) as CryptoKey;
+  return {
+    kid: exported.kid,
+    privateKey,
+    publicKey,
+    alg: exported.alg,
+    status: exported.status,
+    createdAt: exported.createdAt,
+  };
+}
+
+/**
+ * Build a JWKS (JSON Web Key Set) from signing keys.
+ * Only includes public keys.
+ */
+export async function buildJwks(keys: SigningKey[]): Promise<{ keys: JWK[] }> {
+  const jwks: JWK[] = [];
+  for (const key of keys) {
+    if (key.status === "revoked") continue;
+    const jwk = await exportJWK(key.publicKey);
+    jwk.kid = key.kid;
+    jwk.alg = key.alg;
+    jwk.use = "sig";
+    jwks.push(jwk);
+  }
+  return { keys: jwks };
+}
+
+// ============================================
+// Signing (ES256)
+// ============================================
+
+/**
+ * Sign a JWT with ES256 using the server's private key.
  */
+export async function signJwtES256(
+  payload: Omit<AgentJwtPayload, "iat" | "exp"> & { iat?: number; exp?: number },
+  privateKey: CryptoKey,
+  kid: string,
+  issuer?: string,
+  expiresIn?: string,
+): Promise<string> {
+  let builder = new SignJWT(payload as unknown as JWTPayload)
+    .setProtectedHeader({ alg: "ES256", kid })
+    .setIssuedAt();
+
+  if (issuer) builder = builder.setIssuer(issuer);
+  if (payload.sub) builder = builder.setSubject(payload.sub);
+  if (expiresIn) {
+    builder = builder.setExpirationTime(expiresIn);
+  } else if (payload.exp) {
+    builder = builder.setExpirationTime(payload.exp);
+  } else {
+    builder = builder.setExpirationTime("1h");
+  }
+
+  return builder.sign(privateKey);
+}
+
+// ============================================
+// Verification
+// ============================================
+
+/**
+ * Verify a JWT against a local public key.
+ */
+export async function verifyJwtLocal(
+  token: string,
+  publicKey: CryptoKey,
+): Promise<AgentJwtPayload | null> {
+  try {
+    const { payload } = await jwtVerify(token, publicKey);
+    return payload as unknown as AgentJwtPayload;
+  } catch {
+    return null;
+  }
+}
+
+/** JWKS cache for remote issuers */
+const jwksCache = new Map<string, ReturnType<typeof createRemoteJWKSet>>();
+
+/**
+ * Verify a JWT against a remote issuer's JWKS.
+ * Fetches and caches the JWKS from the issuer's /.well-known/jwks.json
+ */
+export async function verifyJwtFromIssuer(
+  token: string,
+  issuerUrl: string,
+): Promise<AgentJwtPayload | null> {
+  try {
+    const jwksUrl = issuerUrl.replace(/\/$/, "") + "/.well-known/jwks.json";
+    let jwks = jwksCache.get(jwksUrl);
+    if (!jwks) {
+      jwks = createRemoteJWKSet(new URL(jwksUrl));
+      jwksCache.set(jwksUrl, jwks);
+    }
+    const { payload } = await jwtVerify(token, jwks);
+    return payload as unknown as AgentJwtPayload;
+  } catch {
+    return null;
+  }
+}
+
+// ============================================
+// Legacy HMAC (backward compat)
+// ============================================
 
 const encoder = new TextEncoder();
 
@@ -20,106 +234,60 @@ function base64UrlDecode(str: string): Uint8Array {
 
 async function hmacSign(data: string, secret: string): Promise<Uint8Array> {
   const key = await crypto.subtle.importKey(
-    "raw",
-    encoder.encode(secret),
-    { name: "HMAC", hash: "SHA-256" },
-    false,
-    ["sign"],
+    "raw", encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" }, false, ["sign"],
   );
   const sig = await crypto.subtle.sign("HMAC", key, encoder.encode(data));
   return new Uint8Array(sig);
 }
 
-async function hmacVerify(
-  data: string,
-  signature: Uint8Array,
-  secret: string,
-): Promise<boolean> {
+async function hmacVerify(data: string, signature: Uint8Array, secret: string): Promise<boolean> {
   const key = await crypto.subtle.importKey(
-    "raw",
-    encoder.encode(secret),
-    { name: "HMAC", hash: "SHA-256" },
-    false,
-    ["verify"],
-  );
-  return crypto.subtle.verify(
-    "HMAC",
-    key,
-    signature.buffer as ArrayBuffer,
-    encoder.encode(data),
+    "raw", encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" }, false, ["verify"],
   );
+  return crypto.subtle.verify("HMAC", key, signature.buffer as ArrayBuffer, encoder.encode(data));
 }
 
-/** JWT payload for auth tokens */
-export interface JwtPayload {
-  /** Subject - the client ID */
-  sub: string;
-  /** Client name */
-  name: string;
-  /** Tenant ID */
-  tenantId?: string;
-  /** Scopes */
-  scopes: string[];
-  /** Issued at (unix seconds) */
-  iat: number;
-  /** Expires at (unix seconds) */
-  exp: number;
-}
+/** @deprecated Use AgentJwtPayload instead */
+export type JwtPayload = AgentJwtPayload;
 
 /**
- * Sign a JWT with HMAC-SHA256.
- *
- * @param payload - JWT payload (client_id, scopes, etc.)
- * @param secret - Signing secret (the client's secret hash)
- * @returns Signed JWT string
+ * Sign a JWT with HMAC-SHA256 (legacy).
+ * @deprecated Use signJwtES256 for new code.
  */
 export async function signJwt(
-  payload: JwtPayload,
+  payload: AgentJwtPayload,
   secret: string,
 ): Promise<string> {
   const header = { alg: "HS256", typ: "JWT" };
-
   const headerB64 = base64UrlEncode(encoder.encode(JSON.stringify(header)));
   const payloadB64 = base64UrlEncode(encoder.encode(JSON.stringify(payload)));
   const signingInput = `${headerB64}.${payloadB64}`;
-
   const signature = await hmacSign(signingInput, secret);
-  const signatureB64 = base64UrlEncode(signature);
-
-  return `${signingInput}.${signatureB64}`;
+  return `${signingInput}.${base64UrlEncode(signature)}`;
 }
 
 /**
- * Verify and decode a JWT.
- *
- * @param token - JWT string
- * @param secret - Signing secret to verify against
- * @returns Decoded payload, or null if invalid/expired
+ * Verify and decode a JWT (HMAC-SHA256, legacy).
+ * @deprecated Use verifyJwtLocal or verifyJwtFromIssuer for new code.
  */
 export async function verifyJwt(
   token: string,
   secret: string,
-): Promise<JwtPayload | null> {
+): Promise<AgentJwtPayload | null> {
   const parts = token.split(".");
   if (parts.length !== 3) return null;
-
   const [headerB64, payloadB64, signatureB64] = parts;
   const signingInput = `${headerB64}.${payloadB64}`;
-
   try {
     const signature = base64UrlDecode(signatureB64);
     const valid = await hmacVerify(signingInput, signature, secret);
     if (!valid) return null;
-
     const payload = JSON.parse(
       new TextDecoder().decode(base64UrlDecode(payloadB64)),
-    ) as JwtPayload;
-
-    // Check expiration
-    if (payload.exp && payload.exp < Date.now() / 1000) {
-      return null;
-    }
-
+    ) as AgentJwtPayload;
+    if (payload.exp && payload.exp < Date.now() / 1000) return null;
     return payload;
   } catch {
     return null;

package/src/registry.ts

@@ -37,6 +37,8 @@ const DEFAULT_SUPPORTED_ACTIONS: AgentAction[] = [
 export interface AgentRegistryOptions {
   /** Default visibility for agents without explicit visibility */
   defaultVisibility?: Visibility;
+  /** Factory to enrich ToolContext with application-specific data */
+  contextFactory?: ContextFactory;
 }
 
 /**
@@ -82,6 +84,12 @@ export interface AgentRegistry {
  * });
  * ```
  */
+/**
+ * Factory function that enriches the base ToolContext with application-specific data.
+ * Called before every tool execution.
+ */
+export type ContextFactory = (baseCtx: import("./types.js").ToolContext) => import("./types.js").ToolContext;
+
 export function createAgentRegistry(
   options: AgentRegistryOptions = {},
 ): AgentRegistry {
@@ -165,6 +173,8 @@ export function createAgentRegistry(
         return (
           callerType === "agent" || (callerType != null && callerId != null)
         );
+      case "authenticated":
+        return callerId != null && callerId !== "anonymous";
       case "private":
         return callerId === agent.path;
       default:
@@ -276,12 +286,12 @@ export function createAgentRegistry(
           ) {
             return {
               success: false,
-              error: `Access denied to tool: ${request.tool}`,
+              error: `Access denied to tool: ${request.tool} (visibility=${tool.visibility}, callerId=${request.callerId}, callerType=${request.callerType})`,
               code: "ACCESS_DENIED",
             } as CallAgentErrorResponse;
           }
 
-          const ctx: ToolContext = {
+          let ctx: ToolContext = {
             tenantId: "default",
             agentPath: agent.path,
             callerId: request.callerId ?? "unknown",
@@ -289,6 +299,11 @@ export function createAgentRegistry(
             metadata: request.metadata,
           };
 
+          // Apply contextFactory if provided
+          if (options.contextFactory) {
+            ctx = options.contextFactory(ctx);
+          }
+
           try {
             if (!tool.execute) {
               return {

package/src/secret-collection.ts

@@ -0,0 +1,66 @@
+/**
+ * Secret Collection
+ *
+ * Manages pending secret collection forms (one-time tokens).
+ * Used by @integrations collect_secrets and the server's /secrets/collect endpoint.
+ *
+ * Exported for use in custom server implementations.
+ */
+
+// ============================================
+// Types
+// ============================================
+
+export interface PendingCollectionField {
+  name: string;
+  description?: string;
+  required: boolean;
+  secret: boolean;
+}
+
+export interface PendingCollection {
+  agent: string;
+  tool: string;
+  params: Record<string, unknown>;
+  fields: PendingCollectionField[];
+  auth?: {
+    callerId: string;
+    callerType: string;
+    scopes?: string[];
+    isRoot?: boolean;
+  };
+  createdAt: number;
+}
+
+// ============================================
+// Storage (with TTL cleanup)
+// ============================================
+
+/** Default TTL for pending collections: 15 minutes */
+const COLLECTION_TTL_MS = 15 * 60 * 1000;
+
+/** Pending secret collection forms, keyed by one-time token */
+export const pendingCollections = new Map<string, PendingCollection>();
+
+/** Generate a random one-time token for secret collection */
+export function generateCollectionToken(): string {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+  let token = "";
+  for (let i = 0; i < 48; i++) {
+    token += chars[Math.floor(Math.random() * chars.length)];
+  }
+  return token;
+}
+
+/**
+ * Clean up expired pending collections.
+ * Call this periodically or before lookups.
+ */
+export function cleanupExpiredCollections(): void {
+  const now = Date.now();
+  for (const [token, pending] of pendingCollections) {
+    if (now - pending.createdAt > COLLECTION_TTL_MS) {
+      pendingCollections.delete(token);
+    }
+  }
+}