@inkeep/agents-run-api 0.0.0-dev-20250910232631

package/dist/middleware/api-key-auth.js

@@ -0,0 +1,139 @@
+import { getLogger, validateAndGetApiKey } from '@inkeep/agents-core';
+import { createMiddleware } from 'hono/factory';
+import { HTTPException } from 'hono/http-exception';
+import dbClient from '../data/db/dbClient';
+import { env } from '../env';
+import { createExecutionContext } from '../types/execution-context';
+const logger = getLogger('env-key-auth');
+/**
+ * Middleware to authenticate API requests using Bearer token authentication
+ * First checks if token matches INKEEP_AGENTS_RUN_BYPASS_SECRET, then falls back to API key validation
+ * Extracts and validates API keys, then adds execution context to the request
+ */
+export const apiKeyAuth = () => createMiddleware(async (c, next) => {
+    const authHeader = c.req.header('Authorization');
+    const tenantId = c.req.header('x-inkeep-tenant-id');
+    const projectId = c.req.header('x-inkeep-project-id');
+    const graphId = c.req.header('x-inkeep-graph-id');
+    const agentId = c.req.header('x-inkeep-agent-id');
+    const baseUrl = new URL(c.req.url).origin;
+    // Bypass authentication only for integration tests with specific header
+    if (process.env.ENVIRONMENT === 'development' || process.env.ENVIRONMENT === 'test') {
+        const executionContext = createExecutionContext({
+            apiKey: 'development',
+            tenantId: tenantId || 'test-tenant',
+            projectId: projectId || 'test-project',
+            graphId: graphId || 'test-graph',
+            apiKeyId: 'test-key',
+            baseUrl: baseUrl,
+            agentId: agentId,
+        });
+        c.set('executionContext', executionContext);
+        logger.info({}, 'Test environment bypass authenticated successfully');
+        await next();
+        return;
+    }
+    // Check for Bearer token
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+        throw new HTTPException(401, {
+            message: 'Missing or invalid authorization header. Expected: Bearer <api_key>',
+        });
+    }
+    const apiKey = authHeader.substring(7); // Remove 'Bearer ' prefix
+    // If bypass secret is configured, allow bypass authentication or api key validation
+    if (env.INKEEP_AGENTS_RUN_BYPASS_SECRET) {
+        if (apiKey === env.INKEEP_AGENTS_RUN_BYPASS_SECRET) {
+            // Extract base URL from request
+            if (!tenantId || !projectId || !graphId) {
+                throw new HTTPException(401, {
+                    message: 'Missing or invalid tenant, project, or graph ID',
+                });
+            }
+            // Create bypass execution context with default values
+            const executionContext = createExecutionContext({
+                apiKey: apiKey,
+                tenantId: tenantId,
+                projectId: projectId,
+                graphId: graphId,
+                apiKeyId: 'bypass',
+                baseUrl: baseUrl,
+                agentId: agentId,
+            });
+            c.set('executionContext', executionContext);
+            logger.info({}, 'Bypass secret authenticated successfully');
+            await next();
+            return;
+        }
+        else if (apiKey) {
+            const executionContext = await extractContextFromApiKey(apiKey);
+            c.set('executionContext', executionContext);
+            logger.info({}, 'API key authenticated successfully');
+            await next();
+            return;
+        }
+        else {
+            // Bypass secret is set but token doesn't match - reject
+            throw new HTTPException(401, {
+                message: 'Invalid Token',
+            });
+        }
+    }
+    // No bypass secret configured - continue with normal API key validation
+    // Validate API key format (basic validation)
+    if (!apiKey || apiKey.length < 16) {
+        throw new HTTPException(401, {
+            message: 'Invalid API key format',
+        });
+    }
+    try {
+        const executionContext = await extractContextFromApiKey(apiKey);
+        c.set('executionContext', executionContext);
+        // Log successful authentication (without sensitive data)
+        logger.debug({
+            tenantId: executionContext.tenantId,
+            projectId: executionContext.projectId,
+            graphId: executionContext.graphId,
+        }, 'API key authenticated successfully');
+        await next();
+    }
+    catch (error) {
+        // Re-throw HTTPException
+        if (error instanceof HTTPException) {
+            throw error;
+        }
+        // Log unexpected errors and return generic message
+        logger.error({ error }, 'API key authentication error');
+        throw new HTTPException(500, {
+            message: 'Authentication failed',
+        });
+    }
+});
+export const extractContextFromApiKey = async (apiKey) => {
+    const apiKeyRecord = await validateAndGetApiKey(apiKey, dbClient);
+    if (!apiKeyRecord) {
+        throw new HTTPException(401, {
+            message: 'Invalid or expired API key',
+        });
+    }
+    return createExecutionContext({
+        apiKey: apiKey,
+        tenantId: apiKeyRecord.tenantId,
+        projectId: apiKeyRecord.projectId,
+        graphId: apiKeyRecord.graphId,
+        apiKeyId: apiKeyRecord.id,
+    });
+};
+/**
+ * Helper middleware for endpoints that optionally support API key authentication
+ * If no auth header is present, it continues without setting the executionContext
+ */
+export const optionalAuth = () => createMiddleware(async (c, next) => {
+    const authHeader = c.req.header('Authorization');
+    // If no auth header, continue without authentication
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+        await next();
+        return;
+    }
+    // If auth header exists, use the regular auth middleware
+    return apiKeyAuth()(c, next);
+});

package/dist/middleware/index.d.ts

@@ -0,0 +1,2 @@
+export * from './api-key-auth';
+//# sourceMappingURL=index.d.ts.map

package/dist/middleware/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/middleware/index.js

@@ -0,0 +1 @@
+export * from './api-key-auth';

package/dist/openapi.d.ts

@@ -0,0 +1,2 @@
+export declare function setupOpenAPIRoutes(app: any): void;
+//# sourceMappingURL=openapi.d.ts.map

package/dist/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAIA,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,GAAG,QAsC1C"}

package/dist/openapi.js

@@ -0,0 +1,36 @@
+import { swaggerUI } from '@hono/swagger-ui';
+import { env } from './env';
+export function setupOpenAPIRoutes(app) {
+    // OpenAPI specification endpoint - serves the complete API spec
+    app.get('/openapi.json', (c) => {
+        try {
+            const document = app.getOpenAPIDocument({
+                openapi: '3.0.0',
+                info: {
+                    title: 'Inkeep Execution API',
+                    version: '1.0.0',
+                    description: 'Complete REST API for Inkeep Execution application including chat completions, A2A agent communication, and comprehensive CRUD operations for all entities',
+                },
+                servers: [
+                    {
+                        url: env.AGENT_BASE_URL || `http://localhost:3003`,
+                        description: 'Development server',
+                    },
+                ],
+            });
+            return c.json(document);
+        }
+        catch (error) {
+            console.error('OpenAPI document generation failed:', error);
+            const errorDetails = error instanceof Error
+                ? { message: error.message, stack: error.stack }
+                : JSON.stringify(error, null, 2);
+            return c.json({ error: 'Failed to generate OpenAPI document', details: errorDetails }, 500);
+        }
+    });
+    // Swagger UI endpoint for interactive documentation
+    app.get('/docs', swaggerUI({
+        url: '/openapi.json',
+        title: 'Inkeep Execution API Documentation',
+    }));
+}

package/dist/routes/agents.d.ts

@@ -0,0 +1,10 @@
+import { OpenAPIHono } from '@hono/zod-openapi';
+import { type CredentialStoreRegistry } from '@inkeep/agents-core';
+type AppVariables = {
+    credentialStores: CredentialStoreRegistry;
+};
+declare const app: OpenAPIHono<{
+    Variables: AppVariables;
+}, {}, "/">;
+export default app;
+//# sourceMappingURL=agents.d.ts.map

package/dist/routes/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/routes/agents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EACL,KAAK,uBAAuB,EAI7B,MAAM,qBAAqB,CAAC;AAS7B,KAAK,YAAY,GAAG;IAClB,gBAAgB,EAAE,uBAAuB,CAAC;CAC3C,CAAC;AAEF,QAAA,MAAM,GAAG;eAAgC,YAAY;WAAK,CAAC;AAqM3D,eAAe,GAAG,CAAC"}

package/dist/routes/agents.js

@@ -0,0 +1,158 @@
+import { createRoute, OpenAPIHono } from '@hono/zod-openapi';
+import { getAgentGraphWithDefaultAgent, getRequestExecutionContext, HeadersScopeSchema, } from '@inkeep/agents-core';
+import { z } from 'zod';
+import { a2aHandler } from '../a2a/handlers';
+import { getRegisteredGraph } from '../data/agentGraph';
+import { getRegisteredAgent } from '../data/agents';
+import dbClient from '../data/db/dbClient';
+import { getLogger } from '../logger';
+const app = new OpenAPIHono();
+const logger = getLogger('agents');
+// A2A Agent Card Discovery (REST with OpenAPI)
+app.openapi(createRoute({
+    method: 'get',
+    path: '/.well-known/agent.json',
+    request: {
+        headers: HeadersScopeSchema,
+    },
+    tags: ['a2a'],
+    security: [{ bearerAuth: [] }],
+    responses: {
+        200: {
+            description: 'Agent Card for A2A discovery',
+            content: {
+                'application/json': {
+                    schema: z.object({
+                        name: z.string(),
+                        description: z.string().optional(),
+                        url: z.string(),
+                        version: z.string(),
+                        defaultInputModes: z.array(z.string()),
+                        defaultOutputModes: z.array(z.string()),
+                        skills: z.array(z.any()),
+                    }),
+                },
+            },
+        },
+        404: {
+            description: 'Agent not found',
+        },
+    },
+}), async (c) => {
+    const otelHeaders = {
+        traceparent: c.req.header('traceparent'),
+        tracestate: c.req.header('tracestate'),
+        baggage: c.req.header('baggage'),
+    };
+    logger.info({
+        otelHeaders,
+        path: c.req.path,
+        method: c.req.method,
+    }, 'OpenTelemetry headers: well-known agent.json');
+    // Get execution context from API key authentication
+    const executionContext = getRequestExecutionContext(c);
+    const { tenantId, projectId, graphId, agentId } = executionContext;
+    // If agentId is defined in execution context, run agent-level logic
+    if (agentId) {
+        logger.info({
+            message: 'getRegisteredAgent (agent-level)',
+            tenantId,
+            projectId,
+            graphId,
+            agentId,
+        }, 'agent-level well-known agent.json');
+        const credentialStores = c.get('credentialStores');
+        const agent = await getRegisteredAgent(executionContext, credentialStores);
+        logger.info({ agent }, 'agent registered: well-known agent.json');
+        if (!agent) {
+            return c.json({ error: 'Agent not found' }, 404);
+        }
+        return c.json(agent.agentCard);
+    }
+    else {
+        // Run graph-level logic
+        logger.info({
+            message: 'getRegisteredGraph (graph-level)',
+            tenantId,
+            projectId,
+            graphId,
+        }, 'graph-level well-known agent.json');
+        const graph = await getRegisteredGraph(executionContext);
+        if (!graph) {
+            return c.json({ error: 'Graph not found' }, 404);
+        }
+        return c.json(graph.agentCard);
+    }
+});
+// A2A Protocol Handler (supports both agent-level and graph-level)
+app.post('/a2a', async (c) => {
+    const otelHeaders = {
+        traceparent: c.req.header('traceparent'),
+        tracestate: c.req.header('tracestate'),
+        baggage: c.req.header('baggage'),
+    };
+    logger.info({
+        otelHeaders,
+        path: c.req.path,
+        method: c.req.method,
+    }, 'OpenTelemetry headers: a2a');
+    // Get execution context from API key authentication
+    const executionContext = getRequestExecutionContext(c);
+    const { tenantId, projectId, graphId, agentId } = executionContext;
+    // If agentId is defined in execution context, run agent-level logic
+    if (agentId) {
+        logger.info({
+            message: 'a2a (agent-level)',
+            tenantId,
+            projectId,
+            graphId,
+            agentId,
+        }, 'agent-level a2a endpoint');
+        // Ensure agent is registered (lazy loading)
+        const credentialStores = c.get('credentialStores');
+        const agent = await getRegisteredAgent(executionContext, credentialStores);
+        if (!agent) {
+            return c.json({
+                jsonrpc: '2.0',
+                error: { code: -32004, message: 'Agent not found' },
+                id: null,
+            }, 404);
+        }
+        return a2aHandler(c, agent);
+    }
+    else {
+        // Run graph-level logic
+        logger.info({
+            message: 'a2a (graph-level)',
+            tenantId,
+            projectId,
+            graphId,
+        }, 'graph-level a2a endpoint');
+        // fetch the graph and the default agent
+        const graph = await getAgentGraphWithDefaultAgent(dbClient)({
+            scopes: { tenantId, projectId },
+            graphId,
+        });
+        if (!graph) {
+            return c.json({
+                jsonrpc: '2.0',
+                error: { code: -32004, message: 'Agent not found' },
+                id: null,
+            }, 404);
+        }
+        executionContext.agentId = graph.defaultAgentId;
+        // fetch the default agent and use it as entry point for the graph
+        const credentialStores = c.get('credentialStores');
+        const defaultAgent = await getRegisteredAgent(executionContext, credentialStores);
+        if (!defaultAgent) {
+            return c.json({
+                jsonrpc: '2.0',
+                error: { code: -32004, message: 'Agent not found' },
+                id: null,
+            }, 404);
+        }
+        // Use the existing a2aHandler with the default agent as a registered agent
+        return a2aHandler(c, defaultAgent);
+    }
+});
+export default app;

package/dist/routes/chat.d.ts

@@ -0,0 +1,10 @@
+import { OpenAPIHono } from '@hono/zod-openapi';
+import { type CredentialStoreRegistry } from '@inkeep/agents-core';
+type AppVariables = {
+    credentialStores: CredentialStoreRegistry;
+};
+declare const app: OpenAPIHono<{
+    Variables: AppVariables;
+}, {}, "/">;
+export default app;
+//# sourceMappingURL=chat.d.ts.map

package/dist/routes/chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../src/routes/chat.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EACL,KAAK,uBAAuB,EAW7B,MAAM,qBAAqB,CAAC;AAY7B,KAAK,YAAY,GAAG;IAClB,gBAAgB,EAAE,uBAAuB,CAAC;CAC3C,CAAC;AAEF,QAAA,MAAM,GAAG;eAAgC,YAAY;WAAK,CAAC;AA2W3D,eAAe,GAAG,CAAC"}