@inkeep/agents-api 0.0.1

package/dist/middleware/evalsAuth.js

@@ -0,0 +1,52 @@
+import { env } from "../env.js";
+import { getLogger, isInternalServiceToken, verifyInternalServiceAuthHeader } from "@inkeep/agents-core";
+import { createMiddleware } from "hono/factory";
+import { HTTPException } from "hono/http-exception";
+
+//#region src/middleware/evalsAuth.ts
+const logger = getLogger("eval-auth");
+/**
+* Middleware to authenticate API requests using Bearer token authentication
+* First checks if token matches INKEEP_AGENTS_EVAL_API_BYPASS_SECRET,
+*/
+const evalApiKeyAuth = () => createMiddleware(async (c, next) => {
+	const authHeader = c.req.header("Authorization");
+	if (!authHeader || !authHeader.startsWith("Bearer ")) {
+		if (env.ENVIRONMENT === "development") {
+			await next();
+			return;
+		}
+		throw new HTTPException(401, { message: "Missing or invalid authorization header. Expected: Bearer <api_key>" });
+	}
+	const apiKey = authHeader.substring(7);
+	if (env.INKEEP_AGENTS_EVAL_API_BYPASS_SECRET) {
+		if (!authHeader || !authHeader.startsWith("Bearer ")) {
+			console.log("[AUTH DEBUG] Rejecting: No Bearer token provided");
+			throw new HTTPException(401, { message: "Missing or invalid authorization header. Expected: Bearer <api_key>" });
+		}
+		if (authHeader.substring(7) === env.INKEEP_AGENTS_EVAL_API_BYPASS_SECRET) {
+			logger.info({}, "Bypass secret authenticated successfully");
+			await next();
+			return;
+		}
+	}
+	if (isInternalServiceToken(apiKey)) {
+		const result = await verifyInternalServiceAuthHeader(authHeader);
+		if (!result.valid || !result.payload) throw new HTTPException(401, { message: result.error || "Invalid internal service token" });
+		logger.info({
+			serviceId: result.payload.sub,
+			tenantId: result.payload.tenantId,
+			projectId: result.payload.projectId
+		}, "Internal service authenticated");
+		await next();
+		return;
+	}
+	if (env.ENVIRONMENT === "development") {
+		await next();
+		return;
+	}
+	throw new HTTPException(401, { message: "Invalid Token" });
+});
+
+//#endregion
+export { evalApiKeyAuth };

package/dist/middleware/index.d.ts

@@ -0,0 +1,8 @@
+import { authCorsConfig, defaultCorsConfig, getBaseDomain, isOriginAllowed, playgroundCorsConfig, runCorsConfig, signozCorsConfig } from "./cors.js";
+import { errorHandler } from "./errorHandler.js";
+import { manageApiKeyAuth } from "./manageAuth.js";
+import { oauthRefMiddleware } from "./ref.js";
+import { runApiKeyAuth, runApiKeyAuthExcept, runOptionalAuth } from "./runAuth.js";
+import { sessionAuth } from "./sessionAuth.js";
+import { requireTenantAccess } from "./tenantAccess.js";
+export { authCorsConfig, defaultCorsConfig, errorHandler, getBaseDomain, isOriginAllowed, manageApiKeyAuth, oauthRefMiddleware, playgroundCorsConfig, requireTenantAccess, runApiKeyAuth, runApiKeyAuthExcept, runCorsConfig, runOptionalAuth, sessionAuth, signozCorsConfig };

package/dist/middleware/index.js

@@ -0,0 +1,9 @@
+import { sessionAuth } from "./sessionAuth.js";
+import { authCorsConfig, defaultCorsConfig, getBaseDomain, isOriginAllowed, playgroundCorsConfig, runCorsConfig, signozCorsConfig } from "./cors.js";
+import { errorHandler } from "./errorHandler.js";
+import { manageApiKeyAuth } from "./manageAuth.js";
+import { oauthRefMiddleware } from "./ref.js";
+import { runApiKeyAuth, runApiKeyAuthExcept, runOptionalAuth } from "./runAuth.js";
+import { requireTenantAccess } from "./tenantAccess.js";
+
+export { authCorsConfig, defaultCorsConfig, errorHandler, getBaseDomain, isOriginAllowed, manageApiKeyAuth, oauthRefMiddleware, playgroundCorsConfig, requireTenantAccess, runApiKeyAuth, runApiKeyAuthExcept, runCorsConfig, runOptionalAuth, sessionAuth, signozCorsConfig };

package/dist/middleware/manageAuth.d.ts

@@ -0,0 +1,25 @@
+import * as hono0 from "hono";
+import { BaseExecutionContext } from "@inkeep/agents-core";
+import { createAuth } from "@inkeep/agents-core/auth";
+
+//#region src/middleware/manageAuth.d.ts
+
+/**
+ * Middleware to authenticate API requests using Bearer token authentication
+ * Authentication priority:
+ * 1. Bypass secret (INKEEP_AGENTS_MANAGE_API_BYPASS_SECRET)
+ * 2. Better-auth session token (from device authorization flow)
+ * 3. Database API key
+ * 4. Internal service token
+ */
+declare const manageApiKeyAuth: () => hono0.MiddlewareHandler<{
+  Variables: {
+    executionContext: BaseExecutionContext;
+    userId?: string;
+    userEmail?: string;
+    tenantId?: string;
+    auth: ReturnType<typeof createAuth> | null;
+  };
+}, string, {}, Response>;
+//#endregion
+export { manageApiKeyAuth };

package/dist/middleware/manageAuth.js

@@ -0,0 +1,80 @@
+import { env } from "../env.js";
+import runDbClient_default from "../data/db/runDbClient.js";
+import { getLogger, isInternalServiceToken, validateAndGetApiKey, verifyInternalServiceAuthHeader } from "@inkeep/agents-core";
+import { createMiddleware } from "hono/factory";
+import { HTTPException } from "hono/http-exception";
+
+//#region src/middleware/manageAuth.ts
+const logger = getLogger("env-key-auth");
+/**
+* Middleware to authenticate API requests using Bearer token authentication
+* Authentication priority:
+* 1. Bypass secret (INKEEP_AGENTS_MANAGE_API_BYPASS_SECRET)
+* 2. Better-auth session token (from device authorization flow)
+* 3. Database API key
+* 4. Internal service token
+*/
+const manageApiKeyAuth = () => createMiddleware(async (c, next) => {
+	const authHeader = c.req.header("Authorization");
+	if (!authHeader || !authHeader.startsWith("Bearer ")) throw new HTTPException(401, { message: "Missing or invalid authorization header. Expected: Bearer <api_key>" });
+	const token = authHeader.substring(7);
+	if (env.INKEEP_AGENTS_MANAGE_API_BYPASS_SECRET && token === env.INKEEP_AGENTS_MANAGE_API_BYPASS_SECRET) {
+		logger.info({}, "Bypass secret authenticated successfully");
+		c.set("userId", "system");
+		c.set("userEmail", "system@internal");
+		await next();
+		return;
+	}
+	const auth = c.get("auth");
+	if (auth) try {
+		const headers$1 = new Headers();
+		headers$1.set("Authorization", authHeader);
+		const forwardedCookie = c.req.header("x-forwarded-cookie");
+		const cookie = c.req.header("cookie");
+		if (forwardedCookie) {
+			headers$1.set("cookie", forwardedCookie);
+			logger.debug({ source: "x-forwarded-cookie" }, "Using x-forwarded-cookie for session validation");
+		} else if (cookie) {
+			headers$1.set("cookie", cookie);
+			logger.debug({ source: "cookie" }, "Using cookie for session validation");
+		}
+		const session = await auth.api.getSession({ headers: headers$1 });
+		if (session?.user) {
+			logger.info({ userId: session.user.id }, "Better-auth session authenticated successfully");
+			c.set("userId", session.user.id);
+			c.set("userEmail", session.user.email);
+			await next();
+			return;
+		}
+	} catch (error) {
+		logger.debug({ error }, "Better-auth session validation failed, trying API key");
+	}
+	const validatedKey = await validateAndGetApiKey(token, runDbClient_default);
+	if (validatedKey) {
+		logger.info({ keyId: validatedKey.id }, "API key authenticated successfully");
+		c.set("userId", `apikey:${validatedKey.id}`);
+		c.set("userEmail", `apikey-${validatedKey.id}@internal`);
+		c.set("tenantId", validatedKey.tenantId);
+		await next();
+		return;
+	}
+	if (isInternalServiceToken(token)) {
+		const result = await verifyInternalServiceAuthHeader(authHeader);
+		if (!result.valid || !result.payload) throw new HTTPException(401, { message: result.error || "Invalid internal service token" });
+		logger.info({
+			serviceId: result.payload.sub,
+			tenantId: result.payload.tenantId,
+			projectId: result.payload.projectId,
+			userId: result.payload.userId
+		}, "Internal service authenticated");
+		c.set("userId", result.payload.userId || `system`);
+		c.set("userEmail", `${result.payload.sub}@internal.inkeep`);
+		if (result.payload.tenantId) c.set("tenantId", result.payload.tenantId);
+		await next();
+		return;
+	}
+	throw new HTTPException(401, { message: "Invalid Token" });
+});
+
+//#endregion
+export { manageApiKeyAuth };

package/dist/middleware/projectAccess.d.ts

@@ -0,0 +1,31 @@
+import { ManageAppVariables } from "../types/app.js";
+import * as hono8 from "hono";
+
+//#region src/middleware/projectAccess.d.ts
+
+/**
+ * Permission levels for project access
+ *
+ * - view: Can see project and resources (read-only)
+ * - use: Can invoke agents, create API keys, view traces
+ * - edit: Can modify configurations and manage members
+ */
+type ProjectPermission = 'view' | 'use' | 'edit';
+/**
+ * Middleware to check project-level access.
+ *
+ * When ENABLE_AUTHZ is false:
+ * - 'view' permission: all org members can view
+ * - 'edit': only org owner/admin
+ *
+ * When ENABLE_AUTHZ is true:
+ * - Uses SpiceDB to check permissions
+ * - Org owner/admin bypass (handled in canViewProject etc.)
+ */
+declare const requireProjectPermission: <Env$1 extends {
+  Variables: ManageAppVariables;
+} = {
+  Variables: ManageAppVariables;
+}>(permission?: ProjectPermission) => hono8.MiddlewareHandler<Env$1, string, {}, Response>;
+//#endregion
+export { ProjectPermission, requireProjectPermission };

package/dist/middleware/projectAccess.js

@@ -0,0 +1,118 @@
+import { env } from "../env.js";
+import { canEditProject, canUseProject, canViewProject, createApiError, isAuthzEnabled } from "@inkeep/agents-core";
+import { createMiddleware } from "hono/factory";
+import { HTTPException } from "hono/http-exception";
+
+//#region src/middleware/projectAccess.ts
+/**
+* Middleware to check project-level access.
+*
+* When ENABLE_AUTHZ is false:
+* - 'view' permission: all org members can view
+* - 'edit': only org owner/admin
+*
+* When ENABLE_AUTHZ is true:
+* - Uses SpiceDB to check permissions
+* - Org owner/admin bypass (handled in canViewProject etc.)
+*/
+const requireProjectPermission = (permission = "view") => createMiddleware(async (c, next) => {
+	const isTestEnvironment = process.env.ENVIRONMENT === "test";
+	if (env.DISABLE_AUTH || isTestEnvironment) {
+		await next();
+		return;
+	}
+	const userId = c.get("userId");
+	const tenantId = c.get("tenantId");
+	const tenantRole = c.get("tenantRole");
+	const projectId = c.req.param("projectId") || c.req.param("id");
+	if (!userId || !tenantId) throw createApiError({
+		code: "unauthorized",
+		message: "User or organization context not found",
+		instance: c.req.path
+	});
+	if (!projectId) throw createApiError({
+		code: "bad_request",
+		message: "Project ID is required",
+		instance: c.req.path
+	});
+	if (userId === "system" || userId.startsWith("apikey:")) {
+		await next();
+		return;
+	}
+	try {
+		let hasAccess = false;
+		switch (permission) {
+			case "view":
+				hasAccess = await canViewProject({
+					tenantId,
+					userId,
+					projectId,
+					orgRole: tenantRole
+				});
+				break;
+			case "use":
+				hasAccess = await canUseProject({
+					tenantId,
+					userId,
+					projectId,
+					orgRole: tenantRole
+				});
+				break;
+			case "edit":
+				hasAccess = await canEditProject({
+					tenantId,
+					userId,
+					projectId,
+					orgRole: tenantRole
+				});
+				break;
+		}
+		if (!hasAccess) {
+			if (isAuthzEnabled(tenantId) && permission !== "view") {
+				if (await canViewProject({
+					tenantId,
+					userId,
+					projectId,
+					orgRole: tenantRole
+				})) throw createApiError({
+					code: "forbidden",
+					message: `Permission denied. Required: project:${permission}`,
+					instance: c.req.path,
+					extensions: { requiredPermissions: [`project:${permission}`] }
+				});
+			}
+			if (isAuthzEnabled(tenantId)) throw createApiError({
+				code: "not_found",
+				message: "Project not found",
+				instance: c.req.path
+			});
+			throw createApiError({
+				code: "forbidden",
+				message: `Permission denied. Required: project:${permission}`,
+				instance: c.req.path,
+				extensions: {
+					requiredPermissions: [`project:${permission}`],
+					context: {
+						userId,
+						organizationId: tenantId,
+						projectId,
+						currentRole: tenantRole
+					}
+				}
+			});
+		}
+		await next();
+	} catch (error) {
+		if (error instanceof HTTPException) throw error;
+		const errorMessage = error instanceof Error ? error.message : "Unknown error";
+		throw createApiError({
+			code: "internal_server_error",
+			message: "Failed to verify project access",
+			instance: c.req.path,
+			extensions: { internalError: errorMessage }
+		});
+	}
+});
+
+//#endregion
+export { requireProjectPermission };

package/dist/middleware/projectConfig.d.ts

@@ -0,0 +1,25 @@
+import * as hono12 from "hono";
+import { BaseExecutionContext, ResolvedRef } from "@inkeep/agents-core";
+
+//#region src/middleware/projectConfig.d.ts
+/**
+ * Middleware that fetches the full project definition from the Management API
+ */
+declare const projectConfigMiddleware: hono12.MiddlewareHandler<{
+  Variables: {
+    executionContext: BaseExecutionContext;
+    resolvedRef: ResolvedRef;
+  };
+}, string, {}, Response>;
+/**
+ * Creates a middleware that applies project config fetching except for specified route patterns
+ * @param skipRouteCheck - Function that returns true if the route should skip the middleware
+ */
+declare const projectConfigMiddlewareExcept: (skipRouteCheck: (path: string) => boolean) => hono12.MiddlewareHandler<{
+  Variables: {
+    executionContext: BaseExecutionContext;
+    resolvedRef: ResolvedRef;
+  };
+}, string, {}, Response>;
+//#endregion
+export { projectConfigMiddleware, projectConfigMiddlewareExcept };

package/dist/middleware/projectConfig.js

@@ -0,0 +1,89 @@
+import { getLogger as getLogger$1 } from "../logger.js";
+import manageDbPool_default from "../data/db/manageDbPool.js";
+import { ManageApiError, getFullProjectWithRelationIds, withRef } from "@inkeep/agents-core";
+import { createMiddleware } from "hono/factory";
+
+//#region src/middleware/projectConfig.ts
+const logger = getLogger$1("projectConfigMiddleware");
+/**
+* Core handler that fetches the full project definition from the Management API
+* and adds it to the Hono context for use in route handlers.
+*
+* This handler should be applied after authentication middleware since it
+* requires the execution context to be set.
+*/
+async function projectConfigHandler(c, next) {
+	const executionContext = c.get("executionContext");
+	const resolvedRef = c.get("resolvedRef");
+	const { tenantId, projectId } = executionContext;
+	logger.debug({
+		tenantId,
+		projectId,
+		resolvedRef
+	}, "Fetching project config from Management API");
+	try {
+		if (!resolvedRef) throw new Error("Resolved ref not found");
+		if (resolvedRef.type !== "branch") throw new Error(`Runtime operations require a branch ref. Got ${resolvedRef.type} '${resolvedRef.name}'.`);
+		const projectConfig = await withRef(manageDbPool_default, resolvedRef, async (db) => {
+			return await getFullProjectWithRelationIds(db)({ scopes: {
+				tenantId,
+				projectId
+			} });
+		});
+		if (!projectConfig) throw new Error("Project not found");
+		c.set("executionContext", {
+			...executionContext,
+			project: projectConfig,
+			resolvedRef
+		});
+		logger.debug({
+			tenantId,
+			projectId,
+			resolvedRef,
+			agentCount: Object.keys(projectConfig.agents || {}).length,
+			toolCount: Object.keys(projectConfig.tools || {}).length
+		}, "Project config fetched successfully");
+		await next();
+	} catch (error) {
+		if (error instanceof ManageApiError) {
+			logger.error({
+				tenantId,
+				projectId,
+				statusCode: error.statusCode,
+				message: error.message
+			}, "Failed to fetch project config from Management API");
+			if (error.isNotFound) return c.json({
+				error: "Project not found",
+				message: `Project ${projectId} not found for tenant ${tenantId}`
+			}, 404);
+			if (error.isUnauthorized || error.isForbidden) return c.json({
+				error: "Access denied",
+				message: "Unable to access project configuration"
+			}, 403);
+		}
+		logger.error({
+			tenantId,
+			projectId,
+			error: error instanceof Error ? error.message : String(error)
+		}, "Unexpected error fetching project config");
+		return c.json({
+			error: "Internal server error",
+			message: "Failed to load project configuration"
+		}, 500);
+	}
+}
+/**
+* Middleware that fetches the full project definition from the Management API
+*/
+const projectConfigMiddleware = createMiddleware(projectConfigHandler);
+/**
+* Creates a middleware that applies project config fetching except for specified route patterns
+* @param skipRouteCheck - Function that returns true if the route should skip the middleware
+*/
+const projectConfigMiddlewareExcept = (skipRouteCheck) => createMiddleware(async (c, next) => {
+	if (skipRouteCheck(c.req.path)) return next();
+	return projectConfigHandler(c, next);
+});
+
+//#endregion
+export { projectConfigMiddleware, projectConfigMiddlewareExcept };

package/dist/middleware/ref.d.ts

@@ -0,0 +1,61 @@
+import { Context, Next } from "hono";
+import { AgentsManageDatabaseClient, ResolvedRef } from "@inkeep/agents-core";
+
+//#region src/middleware/ref.d.ts
+type RefContext = {
+  resolvedRef?: ResolvedRef;
+};
+interface RefMiddlewareOptions {
+  /**
+   * Extract tenantId from the request context.
+   * Default implementation extracts from path using /tenants/{tenantId} pattern.
+   */
+  extractTenantId?: (c: Context) => string | undefined;
+  /**
+   * Extract projectId from the request context.
+   * Default implementation extracts from path using /tenants/{tenantId}/projects/{projectId} pattern.
+   */
+  extractProjectId?: (c: Context) => string | undefined;
+  /**
+   * Whether to allow extracting projectId from request body for POST/PUT/PATCH.
+   * Default: true
+   */
+  allowProjectIdFromBody?: boolean;
+  /**
+   * Custom path patterns that should skip ref validation.
+   * Default: []
+   */
+  skipRefValidationPaths?: RegExp[];
+}
+/**
+ * Creates a ref resolution middleware factory.
+ *
+ * This middleware:
+ * 1. Extracts tenantId and projectId from the request
+ * 2. Resolves the `ref` query parameter to a ResolvedRef
+ * 3. Creates branches if needed (tenant_main, project_main)
+ * 4. Sets `resolvedRef` in the Hono context for downstream handlers
+ *
+ * @param db - The Doltgres database client to use for ref resolution
+ * @param options - Optional configuration for extraction and validation
+ * @returns Hono middleware function
+ *
+ * @example
+ * ```typescript
+ * import { createRefMiddleware } from '@inkeep/agents-core';
+ * import { manageDbClient } from './db';
+ *
+ * const refMiddleware = createRefMiddleware(manageDbClient);
+ * app.use('/tenants/*', refMiddleware);
+ * ```
+ */
+declare const createRefMiddleware: (db: AgentsManageDatabaseClient, options?: RefMiddlewareOptions) => (c: Context, next: Next) => Promise<void>;
+declare const writeProtectionMiddleware: (c: Context, next: Next) => Promise<void>;
+declare const manageRefMiddleware: (c: Context, next: Next) => Promise<void>;
+declare const runRefMiddleware: (c: Context, next: Next) => Promise<void>;
+/**
+ * Ref middleware for OAuth routes - extracts tenant/project from query params
+ */
+declare const oauthRefMiddleware: (c: Context, next: Next) => Promise<void>;
+//#endregion
+export { RefContext, RefMiddlewareOptions, createRefMiddleware, manageRefMiddleware, oauthRefMiddleware, runRefMiddleware, writeProtectionMiddleware };