@slashfi/agents-sdk 0.24.1 → 0.24.3

package/dist/cjs/agent-definitions/auth.js

@@ -0,0 +1,678 @@
+"use strict";
+/**
+ * Auth Agent
+ *
+ * Built-in agent that provides OAuth2 client_credentials authentication.
+ * Register it into any agent registry to enable auth.
+ *
+ * Features:
+ * - Client credentials management (create, rotate, revoke)
+ * - OAuth2 client_credentials token exchange
+ * - JWT access tokens with scopes
+ * - Pluggable AuthStore interface (in-memory default)
+ * - Root key for admin operations
+ *
+ * @example
+ * ```typescript
+ * import { createAgentRegistry, createAgentServer, createAuthAgent } from '@slashfi/agents-sdk';
+ *
+ * const registry = createAgentRegistry();
+ * registry.register(createAuthAgent({ rootKey: process.env.ROOT_KEY }));
+ * registry.register(myAgent);
+ *
+ * const server = createAgentServer(registry, { port: 3000 });
+ * await server.start();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMemoryAuthStore = createMemoryAuthStore;
+exports.createAuthAgent = createAuthAgent;
+const define_js_1 = require("../define.js");
+const jwt_js_1 = require("../jwt.js");
+// ============================================
+// In-Memory Auth Store
+// ============================================
+function generateId(prefix) {
+    const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+    let id = prefix;
+    for (let i = 0; i < 24; i++) {
+        id += chars[Math.floor(Math.random() * chars.length)];
+    }
+    return id;
+}
+function generateSecret() {
+    const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+    let secret = "sk_";
+    for (let i = 0; i < 40; i++) {
+        secret += chars[Math.floor(Math.random() * chars.length)];
+    }
+    return secret;
+}
+/** Simple hash for storing secrets (not for production - use bcrypt/argon2) */
+async function hashSecret(secret) {
+    const encoder = new TextEncoder();
+    const data = encoder.encode(secret);
+    const hash = await crypto.subtle.digest("SHA-256", data);
+    return Array.from(new Uint8Array(hash))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * Create an in-memory auth store.
+ * Suitable for development and testing. Use a persistent store for production.
+ */
+function createMemoryAuthStore() {
+    const tenants = new Map();
+    const clients = new Map();
+    const tokens = new Map();
+    const signingKeys = new Map();
+    const trustedIssuers = new Set();
+    const tenantIdentities = new Map(); // "provider:providerTenantId" -> tenantId
+    const userIdentities = new Map(); // "provider:providerUserId" -> userId
+    const refreshTokens = new Map();
+    return {
+        async createTenant(name, _externalRef) {
+            const id = `tenant_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+            tenants.set(id, { id, name, createdAt: Date.now() });
+            return { tenantId: id };
+        },
+        async getTenant(tenantId) {
+            return tenants.get(tenantId) ?? null;
+        },
+        async listTenants() {
+            return Array.from(tenants.values());
+        },
+        async createClient(name, scopes, selfRegistered, tenantId) {
+            const clientId = generateId("ag_");
+            const clientSecret = generateSecret();
+            const secretHash = await hashSecret(clientSecret);
+            clients.set(clientId, {
+                clientId,
+                tenantId,
+                clientSecretHash: secretHash,
+                name,
+                scopes,
+                createdAt: Date.now(),
+                selfRegistered,
+            });
+            return { clientId, clientSecret };
+        },
+        async validateClient(clientId, clientSecret) {
+            const client = clients.get(clientId);
+            if (!client)
+                return null;
+            const hash = await hashSecret(clientSecret);
+            return hash === client.clientSecretHash ? client : null;
+        },
+        async getClient(clientId) {
+            return clients.get(clientId) ?? null;
+        },
+        async listClients() {
+            return Array.from(clients.values());
+        },
+        async revokeClient(clientId) {
+            // Also revoke all tokens for this client
+            for (const [tokenStr, token] of tokens) {
+                if (token.clientId === clientId) {
+                    tokens.delete(tokenStr);
+                }
+            }
+            return clients.delete(clientId);
+        },
+        async rotateSecret(clientId) {
+            const client = clients.get(clientId);
+            if (!client)
+                return null;
+            const clientSecret = generateSecret();
+            client.clientSecretHash = await hashSecret(clientSecret);
+            return {
+                clientSecret: { $agent_type: "secret", value: clientSecret },
+            };
+        },
+        async storeToken(token) {
+            tokens.set(token.token, token);
+        },
+        async validateToken(tokenString) {
+            const token = tokens.get(tokenString);
+            if (!token)
+                return null;
+            if (Date.now() > token.expiresAt) {
+                tokens.delete(tokenString);
+                return null;
+            }
+            return token;
+        },
+        async revokeToken(tokenString) {
+            return tokens.delete(tokenString);
+        },
+        // --- Signing Keys ---
+        async storeSigningKey(key) {
+            signingKeys.set(key.kid, key);
+        },
+        async getSigningKeys() {
+            return Array.from(signingKeys.values()).filter((k) => k.status !== "revoked");
+        },
+        async getActiveSigningKey() {
+            for (const key of signingKeys.values()) {
+                if (key.status === "active")
+                    return key;
+            }
+            return null;
+        },
+        async deprecateSigningKey(kid) {
+            const key = signingKeys.get(kid);
+            if (!key)
+                return false;
+            key.status = "deprecated";
+            return true;
+        },
+        async revokeSigningKey(kid) {
+            return signingKeys.delete(kid);
+        },
+        // --- Trusted Issuers ---
+        async addTrustedIssuer(issuerUrl) {
+            trustedIssuers.add(issuerUrl);
+        },
+        async removeTrustedIssuer(issuerUrl) {
+            return trustedIssuers.delete(issuerUrl);
+        },
+        async listTrustedIssuers() {
+            return Array.from(trustedIssuers);
+        },
+        async storeTenantIdentity(tenantId, provider, providerTenantId) {
+            tenantIdentities.set(`${provider}:${providerTenantId}`, tenantId);
+        },
+        async resolveTenantByIdentity(provider, providerTenantId) {
+            return tenantIdentities.get(`${provider}:${providerTenantId}`) ?? null;
+        },
+        async storeUserIdentity(userId, provider, providerUserId) {
+            userIdentities.set(`${provider}:${providerUserId}`, userId);
+        },
+        async resolveUserByIdentity(provider, providerUserId) {
+            return userIdentities.get(`${provider}:${providerUserId}`) ?? null;
+        },
+        async registerUser(tenantId, userId, clientId) {
+            const refreshToken = `rt_${generateId("rt")}`;
+            refreshTokens.set(refreshToken, { tenantId, userId, clientId });
+            return { refreshToken };
+        },
+        async validateRefreshToken(refreshToken) {
+            return refreshTokens.get(refreshToken) ?? null;
+        },
+        async rotateRefreshToken(oldToken) {
+            const data = refreshTokens.get(oldToken);
+            if (!data)
+                return null;
+            refreshTokens.delete(oldToken);
+            const refreshToken = `rt_${generateId("rt")}`;
+            refreshTokens.set(refreshToken, data);
+            return { refreshToken, ...data };
+        },
+        async transaction(fn) {
+            // In-memory: just run sequentially (single-threaded, no concurrency issues)
+            return fn();
+        },
+    };
+}
+// ============================================
+// Create Auth Agent
+// ============================================
+/**
+ * Create the built-in `@auth` agent.
+ *
+ * Provides OAuth2 client_credentials authentication as agent tools.
+ * The server auto-detects this agent and wires up token validation.
+ */
+function createAuthAgent(options) {
+    const { rootKey, allowRegistration = false, registrationScopes, tokenTtl = 3600, store = createMemoryAuthStore(), } = options;
+    // --- Public Tools ---
+    const createTenantTool = (0, define_js_1.defineTool)({
+        name: "create_tenant",
+        description: "Create a new tenant (organizational unit). All clients and resources are scoped to a tenant.",
+        visibility: "public",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Tenant name" },
+                externalRef: {
+                    type: "object",
+                    description: "Link to a tenant on a remote system (for cross-registry trust)",
+                    properties: {
+                        issuer: {
+                            type: "string",
+                            description: "Issuer URL of the remote system",
+                        },
+                        tenantId: {
+                            type: "string",
+                            description: "Tenant ID on the remote system",
+                        },
+                    },
+                    required: ["issuer", "tenantId"],
+                },
+            },
+            required: ["name"],
+        },
+        execute: async (input) => {
+            const result = await store.createTenant(input.name, input.externalRef);
+            return {
+                tenantId: result.tenantId,
+                name: input.name,
+                externalRef: input.externalRef,
+            };
+        },
+    });
+    const tokenTool = (0, define_js_1.defineTool)({
+        name: "token",
+        description: "Exchange client credentials for an access token (OAuth2 client_credentials grant)",
+        visibility: "public",
+        inputSchema: {
+            type: "object",
+            properties: {
+                grantType: {
+                    type: "string",
+                    enum: ["client_credentials"],
+                    description: "Grant type. Must be 'client_credentials'.",
+                },
+                clientId: { type: "string", description: "Client ID" },
+                clientSecret: { type: "string", description: "Client secret" },
+            },
+            required: ["grantType", "clientId", "clientSecret"],
+        },
+        execute: async (input) => {
+            if (input.grantType === "refresh_token") {
+                if (!input.refreshToken)
+                    throw new Error("refreshToken is required for refresh_token grant");
+                const result = await store.rotateRefreshToken(input.refreshToken);
+                if (!result)
+                    throw new Error("Invalid or expired refresh token");
+                const now = Math.floor(Date.now() / 1000);
+                const jwt = await (0, jwt_js_1.signJwt)({
+                    sub: result.clientId,
+                    name: result.userId,
+                    tenantId: result.tenantId,
+                    scopes: [],
+                    iat: now,
+                    exp: now + tokenTtl,
+                }, (await store.getClient(result.clientId))?.clientSecretHash ?? "");
+                return {
+                    accessToken: { $agent_type: "secret", value: jwt },
+                    refreshToken: { $agent_type: "secret", value: result.refreshToken },
+                    tokenType: "bearer",
+                    expiresIn: tokenTtl,
+                };
+            }
+            if (input.grantType !== "client_credentials") {
+                throw new Error("Unsupported grant type. Use 'client_credentials' or 'refresh_token'.");
+            }
+            const client = await store.validateClient(input.clientId, input.clientSecret);
+            if (!client) {
+                throw new Error("Invalid client credentials");
+            }
+            const now = Math.floor(Date.now() / 1000);
+            const jwt = await (0, jwt_js_1.signJwt)({
+                sub: client.clientId,
+                name: client.name,
+                tenantId: client.tenantId,
+                scopes: client.scopes,
+                iat: now,
+                exp: now + tokenTtl,
+            }, client.clientSecretHash);
+            return {
+                accessToken: { $agent_type: "secret", value: jwt },
+                tokenType: "bearer",
+                expiresIn: tokenTtl,
+                scopes: client.scopes,
+            };
+        },
+    });
+    const whoamiTool = (0, define_js_1.defineTool)({
+        name: "whoami",
+        description: "Introspect the current authentication context",
+        visibility: "public",
+        inputSchema: { type: "object", properties: {} },
+        execute: async (_input, ctx) => {
+            return {
+                callerId: ctx.callerId,
+                callerType: ctx.callerType,
+                scopes: ctx.scopes ?? [],
+                isRoot: ctx.callerId === "root",
+            };
+        },
+    });
+    // --- Optional Public Tool ---
+    const registerTool = (0, define_js_1.defineTool)({
+        name: "register",
+        description: "Register a new agent client (self-service)",
+        visibility: "public",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Name for this client" },
+                scopes: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Requested scopes",
+                },
+            },
+            required: ["name"],
+        },
+        execute: async (input) => {
+            let scopes = input.scopes ?? [];
+            // If registration scopes are restricted, filter
+            if (registrationScopes && registrationScopes.length > 0) {
+                scopes = scopes.filter((s) => registrationScopes.includes(s));
+            }
+            const { clientId, clientSecret } = await store.createClient(input.name, scopes, true, input.tenantId);
+            return {
+                clientId,
+                clientSecret: { $agent_type: "secret", value: clientSecret },
+                scopes,
+            };
+        },
+    });
+    // --- Private Tools (root key only) ---
+    const createClientTool = (0, define_js_1.defineTool)({
+        name: "create_client",
+        description: "Create a new client with specific scopes (admin only)",
+        visibility: "private",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Client name" },
+                scopes: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Scopes to grant",
+                },
+            },
+            required: ["name", "scopes"],
+        },
+        execute: async (input) => {
+            const { clientId, clientSecret } = await store.createClient(input.name, input.scopes);
+            return { clientId, clientSecret, scopes: input.scopes };
+        },
+    });
+    const listClientsTool = (0, define_js_1.defineTool)({
+        name: "list_clients",
+        description: "List all registered clients (admin only)",
+        visibility: "private",
+        inputSchema: { type: "object", properties: {} },
+        execute: async () => {
+            const clients = await store.listClients();
+            return {
+                clients: clients.map((c) => ({
+                    clientId: c.clientId,
+                    name: c.name,
+                    scopes: c.scopes,
+                    createdAt: c.createdAt,
+                    selfRegistered: c.selfRegistered ?? false,
+                })),
+            };
+        },
+    });
+    const revokeClientTool = (0, define_js_1.defineTool)({
+        name: "revoke_client",
+        description: "Revoke a client and all its tokens (admin only)",
+        visibility: "private",
+        inputSchema: {
+            type: "object",
+            properties: {
+                clientId: { type: "string", description: "Client ID to revoke" },
+            },
+            required: ["clientId"],
+        },
+        execute: async (input) => {
+            const revoked = await store.revokeClient(input.clientId);
+            return { revoked };
+        },
+    });
+    const rotateSecretTool = (0, define_js_1.defineTool)({
+        name: "rotate_secret",
+        description: "Rotate a client's secret (admin only)",
+        visibility: "private",
+        inputSchema: {
+            type: "object",
+            properties: {
+                clientId: { type: "string", description: "Client ID to rotate" },
+            },
+            required: ["clientId"],
+        },
+        execute: async (input) => {
+            const result = await store.rotateSecret(input.clientId);
+            if (!result)
+                throw new Error(`Client not found: ${input.clientId}`);
+            return { clientId: input.clientId, clientSecret: result.clientSecret };
+        },
+    });
+    // --- Assemble tools ---
+    // --- Key Management Tools ---
+    const rotateKeysTool = (0, define_js_1.defineTool)({
+        name: "rotate_keys",
+        description: "Generate a new ES256 signing key and deprecate the current active key. The old key remains valid for verification during the overlap period.",
+        visibility: "private",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+        execute: async () => {
+            // Deprecate current active key
+            const current = await store.getActiveSigningKey();
+            if (current) {
+                await store.deprecateSigningKey(current.kid);
+            }
+            // Generate and store new key
+            const newKey = await (0, jwt_js_1.generateSigningKey)();
+            const exported = await (0, jwt_js_1.exportSigningKey)(newKey);
+            await store.storeSigningKey(exported);
+            return {
+                newKid: newKey.kid,
+                deprecatedKid: current?.kid ?? null,
+                message: "New signing key generated. Old key deprecated but still valid for verification.",
+            };
+        },
+    });
+    const apiKeyTool = (0, define_js_1.defineTool)({
+        name: "api_key",
+        description: "Create or list API keys for MCP access.",
+        visibility: "authenticated",
+        inputSchema: {
+            type: "object",
+            properties: {
+                action: {
+                    type: "string",
+                    enum: ["create", "list"],
+                    description: "Action",
+                },
+                name: { type: "string", description: "Key name" },
+                scopes: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Scopes",
+                },
+            },
+            required: ["action"],
+        },
+        execute: async (input) => {
+            if (input.action === "create") {
+                const result = await store.createClient(input.name ?? "api-key", input.scopes ?? ["*"], false);
+                return { key: result.clientSecret, clientId: result.clientId };
+            }
+            if (input.action === "list") {
+                const clients = await store.listClients();
+                return {
+                    keys: clients.map((c) => ({
+                        id: c.clientId,
+                        name: c.name,
+                        scopes: c.scopes,
+                    })),
+                };
+            }
+            return { error: "Unknown action" };
+        },
+    });
+    const trustIssuerTool = (0, define_js_1.defineTool)({
+        name: "trust_issuer",
+        description: "Add or remove a trusted issuer URL. JWTs from trusted issuers are verified against their JWKS endpoint.",
+        visibility: "private",
+        inputSchema: {
+            type: "object",
+            properties: {
+                action: {
+                    type: "string",
+                    enum: ["add", "remove", "list"],
+                    description: "Action to perform",
+                },
+                issuerUrl: {
+                    type: "string",
+                    description: "Issuer URL (required for add/remove)",
+                },
+            },
+            required: ["action"],
+        },
+        execute: async (input) => {
+            switch (input.action) {
+                case "add": {
+                    if (!input.issuerUrl)
+                        throw new Error("issuerUrl is required");
+                    await store.addTrustedIssuer(input.issuerUrl);
+                    return {
+                        success: true,
+                        message: `Added trusted issuer: ${input.issuerUrl}`,
+                    };
+                }
+                case "remove": {
+                    if (!input.issuerUrl)
+                        throw new Error("issuerUrl is required");
+                    const removed = await store.removeTrustedIssuer(input.issuerUrl);
+                    return {
+                        success: removed,
+                        message: removed ? "Removed" : "Not found",
+                    };
+                }
+                case "list": {
+                    const issuers = await store.listTrustedIssuers();
+                    return { issuers };
+                }
+            }
+        },
+    });
+    const exchangeTokenTool = (0, define_js_1.defineTool)({
+        name: "exchange_token",
+        description: "Exchange a foreign JWT for a local identity. Verifies the JWT via JWKS, " +
+            "resolves the tenant and user to local IDs. If the user is not yet linked, " +
+            "returns needsAuth=true with a connect URL for OAuth identity linking.",
+        visibility: "public",
+        inputSchema: {
+            type: "object",
+            properties: {
+                token: {
+                    type: "string",
+                    description: "JWT signed by a trusted issuer",
+                },
+            },
+            required: ["token"],
+        },
+        execute: async (input) => {
+            // 1. Decode JWT to read iss claim (no verification yet)
+            const parts = input.token.split(".");
+            if (parts.length !== 3) {
+                return { success: false, error: "Invalid JWT format" };
+            }
+            let decoded;
+            try {
+                decoded = JSON.parse(Buffer.from(parts[1], "base64url").toString());
+            }
+            catch {
+                return { success: false, error: "Failed to decode JWT payload" };
+            }
+            const issuer = decoded.iss;
+            const sub = decoded.sub;
+            const foreignTenantId = decoded.tenantId;
+            if (!issuer || !sub) {
+                return { success: false, error: "JWT missing iss or sub claims" };
+            }
+            // 2. Match issuer against trusted issuers
+            const trustedIssuers = await store.listTrustedIssuers();
+            if (!trustedIssuers.includes(issuer)) {
+                return { success: false, error: `Issuer ${issuer} is not trusted` };
+            }
+            // 3. Verify JWT against the matched issuer's JWKS
+            let payload;
+            try {
+                payload = await (0, jwt_js_1.verifyJwtFromIssuer)(input.token, issuer);
+            }
+            catch {
+                return { success: false, error: "JWT verification failed" };
+            }
+            if (!payload) {
+                return {
+                    success: false,
+                    error: "JWT verification returned empty payload",
+                };
+            }
+            // 4. Resolve tenant + user inside a transaction for consistency
+            return store.transaction(async () => {
+                const localTenantId = await (async () => {
+                    if (!foreignTenantId)
+                        return null;
+                    const existing = await store.resolveTenantByIdentity(issuer, foreignTenantId);
+                    if (existing)
+                        return existing;
+                    // Auto-create tenant identity link on first encounter
+                    await store.storeTenantIdentity(foreignTenantId, issuer, foreignTenantId);
+                    return foreignTenantId;
+                })();
+                // 5. Resolve user
+                const localUserId = await store.resolveUserByIdentity(issuer, sub);
+                if (localUserId) {
+                    return {
+                        success: true,
+                        tenantId: localTenantId ?? undefined,
+                        userId: localUserId,
+                    };
+                }
+                // 4. User not linked — caller decides how to handle (e.g. OIDC flow)
+                return {
+                    success: false,
+                    needsAuth: true,
+                    tenantId: localTenantId ?? undefined,
+                    issuer,
+                    sub,
+                };
+            });
+        },
+    });
+    const tools = [
+        createTenantTool,
+        tokenTool,
+        whoamiTool,
+        ...(allowRegistration ? [registerTool] : []),
+        createClientTool,
+        listClientsTool,
+        revokeClientTool,
+        rotateSecretTool,
+        rotateKeysTool,
+        trustIssuerTool,
+        apiKeyTool,
+        exchangeTokenTool,
+    ];
+    const agent = (0, define_js_1.defineAgent)({
+        path: "@auth",
+        entrypoint: "Authentication agent. Provides OAuth2 client_credentials authentication for the agent network.",
+        config: {
+            name: "Auth",
+            visibility: "public",
+            description: "Built-in authentication agent",
+            supportedActions: ["execute_tool", "describe_tools", "load"],
+        },
+        tools: tools,
+        visibility: "public",
+    });
+    // Attach store and config for server integration
+    return Object.assign(agent, {
+        __authStore: store,
+        __rootKey: rootKey,
+        __tokenTtl: tokenTtl,
+    });
+}
+//# sourceMappingURL=auth.js.map