@inkeep/agents-manage-api 0.39.5 → 0.41.0

package/dist/middleware/auth.js

@@ -0,0 +1,64 @@
+import { env } from "../env.js";
+import dbClient_default from "../data/db/dbClient.js";
+import { getLogger, validateAndGetApiKey } from "@inkeep/agents-core";
+import { createMiddleware } from "hono/factory";
+import { HTTPException } from "hono/http-exception";
+
+//#region src/middleware/auth.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
+*/
+const apiKeyAuth = () => 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 = new Headers();
+		headers.set("Authorization", authHeader);
+		const forwardedCookie = c.req.header("x-forwarded-cookie");
+		const cookie = c.req.header("cookie");
+		if (forwardedCookie) {
+			headers.set("cookie", forwardedCookie);
+			logger.debug({ source: "x-forwarded-cookie" }, "Using x-forwarded-cookie for session validation");
+		} else if (cookie) {
+			headers.set("cookie", cookie);
+			logger.debug({ source: "cookie" }, "Using cookie for session validation");
+		}
+		const session = await auth.api.getSession({ headers });
+		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, dbClient_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;
+	}
+	throw new HTTPException(401, { message: "Invalid Token" });
+});
+
+//#endregion
+export { apiKeyAuth };

package/dist/middleware/error-handler.d.ts

@@ -0,0 +1,12 @@
+import { Context } from "hono";
+
+//#region src/middleware/error-handler.d.ts
+
+/**
+ * Global error handler for the Hono application
+ * Handles Zod validation errors, HTTP exceptions, and unexpected errors
+ * Returns RFC 7807 Problem Details format
+ */
+declare function errorHandler(err: Error, c: Context): Promise<Response>;
+//#endregion
+export { errorHandler };

package/dist/middleware/error-handler.js

@@ -0,0 +1,88 @@
+import { getLogger as getLogger$1 } from "../logger.js";
+import { handleApiError } from "@inkeep/agents-core";
+import { HTTPException } from "hono/http-exception";
+
+//#region src/middleware/error-handler.ts
+const logger = getLogger$1("error-handler");
+/**
+* Extract Zod validation issues from an error object
+*/
+function extractZodIssues(err) {
+	if (err && typeof err === "object") {
+		if ("cause" in err && err.cause && typeof err.cause === "object" && "issues" in err.cause) {
+			const issues = err.cause.issues;
+			if (Array.isArray(issues)) return issues;
+		}
+		if ("issues" in err && Array.isArray(err.issues)) return err.issues;
+	}
+}
+/**
+* Format Zod validation errors into RFC 7807 problem detail format
+*/
+function formatZodValidationError(c, zodIssues) {
+	c.status(400);
+	c.header("Content-Type", "application/problem+json");
+	c.header("X-Content-Type-Options", "nosniff");
+	return c.json({
+		type: "https://docs.inkeep.com/agents-api/errors#bad_request",
+		title: "Validation Failed",
+		status: 400,
+		detail: "Request validation failed",
+		errors: zodIssues.map((issue) => ({
+			detail: issue.message,
+			pointer: issue.path ? `/${issue.path.join("/")}` : void 0,
+			name: issue.path ? issue.path.join(".") : void 0,
+			reason: issue.message
+		}))
+	});
+}
+/**
+* Log server errors with appropriate context
+*/
+function logServerError(err, path, requestId, status, isExpectedError) {
+	if (!isExpectedError) {
+		const errorMessage = err instanceof Error ? err.message : String(err);
+		const errorStack = err instanceof Error ? err.stack : void 0;
+		logger.error({
+			error: err,
+			message: errorMessage,
+			stack: errorStack,
+			path,
+			requestId
+		}, "Unexpected server error occurred");
+	} else logger.error({
+		error: err,
+		path,
+		requestId,
+		status
+	}, "Server error occurred");
+}
+/**
+* Global error handler for the Hono application
+* Handles Zod validation errors, HTTP exceptions, and unexpected errors
+* Returns RFC 7807 Problem Details format
+*/
+async function errorHandler(err, c) {
+	const isExpectedError = err instanceof HTTPException;
+	const status = isExpectedError ? err.status : 500;
+	const requestId = c.get("requestId") || "unknown";
+	const zodIssues = extractZodIssues(err);
+	if (status === 400 && zodIssues) return formatZodValidationError(c, zodIssues);
+	if (status >= 500) logServerError(err, c.req.path, requestId, status, isExpectedError);
+	const errorResponse = await handleApiError(err, requestId);
+	c.status(errorResponse.status);
+	const responseBody = {
+		...errorResponse.code && { code: errorResponse.code },
+		title: errorResponse.title,
+		status: errorResponse.status,
+		detail: errorResponse.detail,
+		...errorResponse.instance && { instance: errorResponse.instance },
+		...errorResponse.error && { error: errorResponse.error }
+	};
+	c.header("Content-Type", "application/problem+json");
+	c.header("X-Content-Type-Options", "nosniff");
+	return c.body(JSON.stringify(responseBody));
+}
+
+//#endregion
+export { errorHandler };

package/dist/middleware/require-permission.d.ts

@@ -0,0 +1,19 @@
+import * as hono1 from "hono";
+import { createAuth } from "@inkeep/agents-core/auth";
+
+//#region src/middleware/require-permission.d.ts
+type Permission = {
+  [resource: string]: string | string[];
+};
+type MinimalAuthVariables = {
+  Variables: {
+    auth: ReturnType<typeof createAuth> | null;
+    userId: string;
+    userEmail: string;
+    tenantId: string;
+    tenantRole: string;
+  };
+};
+declare const requirePermission: <Env$1 extends MinimalAuthVariables = MinimalAuthVariables>(permissions: Permission) => hono1.MiddlewareHandler<Env$1, string, {}, Response>;
+//#endregion
+export { requirePermission };

package/dist/middleware/require-permission.js

@@ -0,0 +1,80 @@
+import { env } from "../env.js";
+import { createApiError } from "@inkeep/agents-core";
+import { createMiddleware } from "hono/factory";
+import { HTTPException } from "hono/http-exception";
+
+//#region src/middleware/require-permission.ts
+function formatPermissionsForDisplay(permissions) {
+	const formatted = [];
+	for (const [resource, actions] of Object.entries(permissions)) {
+		const actionList = Array.isArray(actions) ? actions : [actions];
+		for (const action of actionList) formatted.push(`${resource}:${action}`);
+	}
+	return formatted;
+}
+const requirePermission = (permissions) => createMiddleware(async (c, next) => {
+	const isTestEnvironment = process.env.ENVIRONMENT === "test";
+	const auth = c.get("auth");
+	if (env.DISABLE_AUTH || isTestEnvironment || !auth) {
+		await next();
+		return;
+	}
+	const userId = c.get("userId");
+	const tenantId = c.get("tenantId");
+	const tenantRole = c.get("tenantRole");
+	const requiredPermissions = formatPermissionsForDisplay(permissions);
+	if (userId === "system" || userId?.startsWith("apikey:")) {
+		await next();
+		return;
+	}
+	if (!userId || !tenantId) throw createApiError({
+		code: "unauthorized",
+		message: "User or organization context not found. Ensure you are authenticated and belong to an organization.",
+		instance: c.req.path,
+		extensions: {
+			requiredPermissions,
+			context: {
+				hasUserId: !!userId,
+				hasTenantId: !!tenantId
+			}
+		}
+	});
+	try {
+		const result = await auth.api.hasPermission({
+			body: {
+				permissions,
+				organizationId: tenantId
+			},
+			headers: c.req.raw.headers
+		});
+		if (!result || !result.success) throw createApiError({
+			code: "forbidden",
+			message: `Permission denied. Required: ${requiredPermissions.join(", ")}`,
+			instance: c.req.path,
+			extensions: {
+				requiredPermissions,
+				context: {
+					userId,
+					organizationId: tenantId,
+					currentRole: tenantRole || "unknown"
+				}
+			}
+		});
+		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 permissions",
+			instance: c.req.path,
+			extensions: {
+				requiredPermissions,
+				internalError: errorMessage
+			}
+		});
+	}
+});
+
+//#endregion
+export { requirePermission };

package/dist/middleware/session-auth.d.ts

@@ -0,0 +1,6 @@
+import * as hono3 from "hono";
+
+//#region src/middleware/session-auth.d.ts
+declare const sessionAuth: () => hono3.MiddlewareHandler<any, string, {}, Response>;
+//#endregion
+export { sessionAuth };

package/dist/middleware/session-auth.js

@@ -0,0 +1,26 @@
+import { createApiError } from "@inkeep/agents-core";
+import { createMiddleware } from "hono/factory";
+import { HTTPException } from "hono/http-exception";
+
+//#region src/middleware/session-auth.ts
+const sessionAuth = () => createMiddleware(async (c, next) => {
+	try {
+		const user = c.get("user");
+		if (!user) throw createApiError({
+			code: "unauthorized",
+			message: "Please log in to access this resource"
+		});
+		c.set("userId", user.id);
+		c.set("userEmail", user.email);
+		await next();
+	} catch (error) {
+		if (error instanceof HTTPException) throw error;
+		throw createApiError({
+			code: "unauthorized",
+			message: "Authentication failed"
+		});
+	}
+});
+
+//#endregion
+export { sessionAuth };

package/dist/middleware/tenant-access.d.ts

@@ -0,0 +1,12 @@
+import * as hono4 from "hono";
+
+//#region src/middleware/tenant-access.d.ts
+declare const requireTenantAccess: () => hono4.MiddlewareHandler<{
+  Variables: {
+    userId: string;
+    tenantId: string;
+    tenantRole: string;
+  };
+}, string, {}, Response>;
+//#endregion
+export { requireTenantAccess };

package/dist/middleware/tenant-access.js

@@ -0,0 +1,54 @@
+import dbClient_default from "../data/db/dbClient.js";
+import { createApiError, getUserOrganizations } from "@inkeep/agents-core";
+import { createMiddleware } from "hono/factory";
+import { HTTPException } from "hono/http-exception";
+
+//#region src/middleware/tenant-access.ts
+const requireTenantAccess = () => createMiddleware(async (c, next) => {
+	const userId = c.get("userId");
+	const tenantId = c.req.param("tenantId");
+	if (!userId) throw createApiError({
+		code: "unauthorized",
+		message: "User ID not found"
+	});
+	if (!tenantId) throw createApiError({
+		code: "bad_request",
+		message: "Organization ID is required"
+	});
+	if (userId === "system") {
+		c.set("tenantId", tenantId);
+		c.set("tenantRole", "owner");
+		await next();
+		return;
+	}
+	if (userId.startsWith("apikey:")) {
+		const apiKeyTenantId = c.get("tenantId");
+		if (apiKeyTenantId && apiKeyTenantId !== tenantId) throw createApiError({
+			code: "forbidden",
+			message: "API key does not have access to this organization"
+		});
+		c.set("tenantId", tenantId);
+		c.set("tenantRole", "owner");
+		await next();
+		return;
+	}
+	try {
+		const organizationAccess = (await getUserOrganizations(dbClient_default)(userId)).find((org) => org.organizationId === tenantId);
+		if (!organizationAccess) throw createApiError({
+			code: "forbidden",
+			message: "Access denied to this organization"
+		});
+		c.set("tenantId", tenantId);
+		c.set("tenantRole", organizationAccess.role);
+		await next();
+	} catch (error) {
+		if (error instanceof HTTPException) throw error;
+		throw createApiError({
+			code: "internal_server_error",
+			message: "Failed to verify organization access"
+		});
+	}
+});
+
+//#endregion
+export { requireTenantAccess };

package/dist/openapi.d.ts

@@ -0,0 +1,7 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { Env } from "hono";
+
+//#region src/openapi.d.ts
+declare function setupOpenAPIRoutes<E extends Env = Env>(app: OpenAPIHono<E>): void;
+//#endregion
+export { setupOpenAPIRoutes };

package/dist/openapi.js

@@ -0,0 +1,157 @@
+import { env } from "./env.js";
+import { swaggerUI } from "@hono/swagger-ui";
+
+//#region src/openapi.ts
+function setupOpenAPIRoutes(app) {
+	app.get("/openapi.json", (c) => {
+		try {
+			const serverUrl = process.env.VERCEL_ENV === "production" && process.env.VERCEL_PROJECT_PRODUCTION_URL ? `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}` : process.env.VERCEL_ENV === "preview" && process.env.VERCEL_URL ? `https://${process.env.VERCEL_URL}` : env.INKEEP_AGENTS_MANAGE_API_URL;
+			const document = app.getOpenAPIDocument({
+				openapi: "3.0.0",
+				info: {
+					title: "Inkeep Agents Manage API",
+					version: "1.0.0",
+					description: "REST API for the management of the Inkeep Agent Framework."
+				},
+				servers: [{
+					url: serverUrl,
+					description: "API Server"
+				}],
+				tags: [
+					{
+						name: "Agent",
+						description: "Operations for managing individual agents"
+					},
+					{
+						name: "Agent Artifact Component Relations",
+						description: "Operations for managing agent artifact component relationships"
+					},
+					{
+						name: "Agent Data Component Relations",
+						description: "Operations for managing agent data component relationships"
+					},
+					{
+						name: "Agents",
+						description: "Operations for managing agents"
+					},
+					{
+						name: "API Keys",
+						description: "Operations for managing API keys"
+					},
+					{
+						name: "Artifact Component",
+						description: "Operations for managing artifact components"
+					},
+					{
+						name: "Context Config",
+						description: "Operations for managing context configurations"
+					},
+					{
+						name: "Credential",
+						description: "Operations for managing credentials"
+					},
+					{
+						name: "Credential Store",
+						description: "Operations for managing credential stores"
+					},
+					{
+						name: "Data Component",
+						description: "Operations for managing data components"
+					},
+					{
+						name: "External Agents",
+						description: "Operations for managing external agents"
+					},
+					{
+						name: "Full Agent",
+						description: "Operations for managing complete agent definitions"
+					},
+					{
+						name: "Full Project",
+						description: "Operations for managing complete project definitions"
+					},
+					{
+						name: "Function Tools",
+						description: "Operations for managing function tools"
+					},
+					{
+						name: "Functions",
+						description: "Operations for managing functions"
+					},
+					{
+						name: "OAuth",
+						description: "OAuth authentication endpoints for MCP tools"
+					},
+					{
+						name: "Projects",
+						description: "Operations for managing projects"
+					},
+					{
+						name: "Sub Agent External Agent Relations",
+						description: "Operations for managing sub agent external agent relationships"
+					},
+					{
+						name: "Sub Agent Relations",
+						description: "Operations for managing sub agent relationships"
+					},
+					{
+						name: "Sub Agent Team Agent Relations",
+						description: "Operations for managing sub agent team agent relationships"
+					},
+					{
+						name: "SubAgent",
+						description: "Operations for managing sub agents"
+					},
+					{
+						name: "SubAgent Tool Relations",
+						description: "Operations for managing sub agent tool relationships"
+					},
+					{
+						name: "Tools",
+						description: "Operations for managing MCP tools"
+					}
+				]
+			});
+			document.components = {
+				...document.components,
+				securitySchemes: {
+					...document.components?.securitySchemes || {},
+					cookieAuth: {
+						type: "apiKey",
+						in: "cookie",
+						name: "better-auth.session_token",
+						description: "Session-based authentication using HTTP-only cookies. Cookies are automatically sent by browsers. For server-side requests, include cookies with names starting with \"better-auth.\" in the Cookie header."
+					},
+					bearerAuth: {
+						type: "http",
+						scheme: "bearer",
+						bearerFormat: "Token",
+						description: "Bearer token authentication. Use this for API clients and service-to-service communication. Set the Authorization header to \"Bearer <token>\"."
+					}
+				}
+			};
+			document.security = [{
+				cookieAuth: [],
+				bearerAuth: []
+			}];
+			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);
+		}
+	});
+	app.get("/docs", swaggerUI({
+		url: "/openapi.json",
+		title: "Inkeep Agents Manage API Documentation"
+	}));
+}
+
+//#endregion
+export { setupOpenAPIRoutes };

package/dist/routes/agent.d.ts

@@ -0,0 +1,9 @@
+import { BaseAppVariables } from "../types/app.js";
+import { OpenAPIHono } from "@hono/zod-openapi";
+
+//#region src/routes/agent.d.ts
+declare const app: OpenAPIHono<{
+  Variables: BaseAppVariables;
+}, {}, "/">;
+//#endregion
+export { app as default };