@inkeep/agents-core 0.41.2 → 0.42.0

package/dist/utils/internal-service-auth.js

@@ -0,0 +1,140 @@
+import { getLogger } from "./logger.js";
+import { extractBearerToken, hasIssuer, signJwt, verifyJwt } from "./jwt-helpers.js";
+
+//#region src/utils/internal-service-auth.ts
+const logger = getLogger("internal-service-auth");
+const ISSUER = "inkeep-agents-internal";
+/**
+* Known internal services that can authenticate
+*/
+const InternalServices = {
+	INKEEP_AGENTS_RUN_API: "inkeep-agents-run-api",
+	INKEEP_AGENTS_MANAGE_API: "inkeep-agents-manage-api",
+	INKEEP_AGENTS_EVAL_API: "inkeep-agents-eval-api"
+};
+/**
+* Generate an internal service token for service-to-service authentication
+*/
+async function generateInternalServiceToken(params) {
+	try {
+		const claims = {};
+		if (params.tenantId) claims.tenantId = params.tenantId;
+		if (params.projectId) claims.projectId = params.projectId;
+		if (params.userId) claims.userId = params.userId;
+		const token = await signJwt({
+			issuer: ISSUER,
+			subject: params.serviceId,
+			expiresIn: params.expiresIn || "5m",
+			claims
+		});
+		logger.debug({
+			serviceId: params.serviceId,
+			tenantId: params.tenantId,
+			projectId: params.projectId
+		}, "Generated internal service token");
+		return token;
+	} catch (error) {
+		logger.error({ error }, "Failed to generate internal service token");
+		throw new Error("Failed to generate internal service token");
+	}
+}
+/**
+* Verify and decode an internal service token
+*/
+async function verifyInternalServiceToken(token) {
+	const result = await verifyJwt(token, { issuer: ISSUER });
+	if (!result.valid || !result.payload) {
+		logger.warn({ error: result.error }, "Internal service token verification failed");
+		return {
+			valid: false,
+			error: result.error
+		};
+	}
+	const payload = result.payload;
+	if (typeof payload.sub !== "string") {
+		logger.warn({ payload }, "Invalid internal service token: missing subject");
+		return {
+			valid: false,
+			error: "Invalid token: missing service identifier"
+		};
+	}
+	if (!Object.values(InternalServices).includes(payload.sub)) {
+		logger.warn({ serviceId: payload.sub }, "Unknown service identifier in token");
+		return {
+			valid: false,
+			error: `Unknown service identifier: ${payload.sub}`
+		};
+	}
+	const validPayload = {
+		iss: payload.iss,
+		sub: payload.sub,
+		tenantId: payload.tenantId,
+		projectId: payload.projectId,
+		userId: payload.userId,
+		iat: payload.iat,
+		exp: payload.exp
+	};
+	logger.debug({
+		serviceId: validPayload.sub,
+		tenantId: validPayload.tenantId,
+		projectId: validPayload.projectId,
+		userId: validPayload.userId
+	}, "Successfully verified internal service token");
+	return {
+		valid: true,
+		payload: validPayload
+	};
+}
+/**
+* Extract and verify an internal service token from Authorization header
+*/
+async function verifyInternalServiceAuthHeader(authHeader) {
+	const extracted = extractBearerToken(authHeader);
+	if (!extracted.token) return {
+		valid: false,
+		error: extracted.error
+	};
+	return verifyInternalServiceToken(extracted.token);
+}
+/**
+* Check if a token is an internal service token (vs user/agent token)
+* by checking the issuer claim without full verification
+*/
+function isInternalServiceToken(token) {
+	return hasIssuer(token, ISSUER);
+}
+/**
+* Validate that the token has access to the specified tenant.
+* If token has no tenantId claim, it has access to all tenants (superuser service).
+*/
+function validateInternalServiceTenantAccess(payload, tenantId) {
+	if (!payload.tenantId) return true;
+	if (payload.tenantId !== tenantId) {
+		logger.warn({
+			tokenTenantId: payload.tenantId,
+			requestedTenantId: tenantId,
+			serviceId: payload.sub
+		}, "Internal service token tenant mismatch");
+		return false;
+	}
+	return true;
+}
+/**
+* Validate that the token has access to the specified project.
+* If token has no projectId claim, it has access to all projects in the allowed tenant(s).
+*/
+function validateInternalServiceProjectAccess(payload, projectId) {
+	if (!payload.projectId) return true;
+	if (payload.projectId !== projectId) {
+		logger.warn({
+			tokenProjectId: payload.projectId,
+			requestedProjectId: projectId,
+			serviceId: payload.sub
+		}, "Internal service token project mismatch");
+		return false;
+	}
+	return true;
+}
+
+//#endregion
+export { InternalServices, generateInternalServiceToken, isInternalServiceToken, validateInternalServiceProjectAccess, validateInternalServiceTenantAccess, verifyInternalServiceAuthHeader, verifyInternalServiceToken };

package/dist/utils/jwt-helpers.d.ts

@@ -0,0 +1,56 @@
+//#region src/utils/jwt-helpers.d.ts
+/**
+ * Get the JWT signing secret from environment variables.
+ * Falls back to an insecure default in non-production environments.
+ */
+declare function getJwtSecret(): Uint8Array;
+/**
+ * Common verification result structure
+ */
+interface JwtVerifyResult<T> {
+  valid: boolean;
+  payload?: T;
+  error?: string;
+}
+/**
+ * Options for signing a JWT
+ */
+interface SignJwtOptions {
+  issuer: string;
+  subject: string;
+  audience?: string;
+  expiresIn?: string;
+  claims?: Record<string, unknown>;
+}
+/**
+ * Sign a JWT with the shared secret
+ */
+declare function signJwt(options: SignJwtOptions): Promise<string>;
+/**
+ * Options for verifying a JWT
+ */
+interface VerifyJwtOptions {
+  issuer: string;
+  audience?: string;
+}
+/**
+ * Verify a JWT and return the raw payload
+ */
+declare function verifyJwt(token: string, options: VerifyJwtOptions): Promise<JwtVerifyResult<Record<string, unknown>>>;
+/**
+ * Extract bearer token from Authorization header
+ */
+declare function extractBearerToken(authHeader: string | undefined): {
+  token?: string;
+  error?: string;
+};
+/**
+ * Decode JWT payload without verification (for checking issuer before full verify)
+ */
+declare function decodeJwtPayload(token: string): Record<string, unknown> | null;
+/**
+ * Check if a token has a specific issuer (without full verification)
+ */
+declare function hasIssuer(token: string, issuer: string): boolean;
+//#endregion
+export { JwtVerifyResult, SignJwtOptions, VerifyJwtOptions, decodeJwtPayload, extractBearerToken, getJwtSecret, hasIssuer, signJwt, verifyJwt };

package/dist/utils/jwt-helpers.js

@@ -0,0 +1,90 @@
+import { env } from "../env.js";
+import { getLogger } from "./logger.js";
+import { SignJWT, jwtVerify } from "jose";
+
+//#region src/utils/jwt-helpers.ts
+const logger = getLogger("jwt-helpers");
+const DEV_SECRET = "insecure-dev-secret-change-in-production-min-32-chars";
+/**
+* Get the JWT signing secret from environment variables.
+* Falls back to an insecure default in non-production environments.
+*/
+function getJwtSecret() {
+	const secret = env.INKEEP_AGENTS_JWT_SIGNING_SECRET;
+	if (!secret) {
+		if (env.ENVIRONMENT === "production") throw new Error("INKEEP_AGENTS_JWT_SIGNING_SECRET environment variable is required in production");
+		logger.warn({}, "INKEEP_AGENTS_JWT_SIGNING_SECRET not set, using insecure default. DO NOT USE IN PRODUCTION!");
+		return new TextEncoder().encode(DEV_SECRET);
+	}
+	return new TextEncoder().encode(secret);
+}
+/**
+* Sign a JWT with the shared secret
+*/
+async function signJwt(options) {
+	const secret = getJwtSecret();
+	const builder = new SignJWT(options.claims || {}).setProtectedHeader({
+		alg: "HS256",
+		typ: "JWT"
+	}).setIssuer(options.issuer).setSubject(options.subject).setIssuedAt().setExpirationTime(options.expiresIn || "5m");
+	if (options.audience) builder.setAudience(options.audience);
+	return builder.sign(secret);
+}
+/**
+* Verify a JWT and return the raw payload
+*/
+async function verifyJwt(token, options) {
+	const secret = getJwtSecret();
+	try {
+		const verifyOptions = {
+			issuer: options.issuer,
+			algorithms: ["HS256"]
+		};
+		if (options.audience) verifyOptions.audience = options.audience;
+		const { payload } = await jwtVerify(token, secret, verifyOptions);
+		return {
+			valid: true,
+			payload
+		};
+	} catch (error) {
+		if (error instanceof Error) return {
+			valid: false,
+			error: error.message
+		};
+		return {
+			valid: false,
+			error: "Token verification failed"
+		};
+	}
+}
+/**
+* Extract bearer token from Authorization header
+*/
+function extractBearerToken(authHeader) {
+	if (!authHeader) return { error: "Missing Authorization header" };
+	if (!authHeader.startsWith("Bearer ")) return { error: "Invalid Authorization header format. Expected: Bearer <token>" };
+	const token = authHeader.substring(7);
+	if (!token) return { error: "Empty token in Authorization header" };
+	return { token };
+}
+/**
+* Decode JWT payload without verification (for checking issuer before full verify)
+*/
+function decodeJwtPayload(token) {
+	try {
+		const parts = token.split(".");
+		if (parts.length !== 3) return null;
+		return JSON.parse(Buffer.from(parts[1], "base64url").toString());
+	} catch {
+		return null;
+	}
+}
+/**
+* Check if a token has a specific issuer (without full verification)
+*/
+function hasIssuer(token, issuer) {
+	return decodeJwtPayload(token)?.iss === issuer;
+}
+
+//#endregion
+export { decodeJwtPayload, extractBearerToken, getJwtSecret, hasIssuer, signJwt, verifyJwt };

package/dist/utils/service-token-auth.d.ts

@@ -1,6 +1,9 @@
+import { JwtVerifyResult } from "./jwt-helpers.js";
+
 //#region src/utils/service-token-auth.d.ts
+
 /**
- * Service Token JWT Claims
+ * Service Token JWT Claims (for agent-to-agent communication)
  */
 interface ServiceTokenPayload {
   /** Issuer - always 'inkeep-agents' */
@@ -30,48 +33,27 @@ interface GenerateServiceTokenParams {
 /**
  * Result of verifying a service token
  */
-interface VerifyServiceTokenResult {
-  valid: boolean;
-  payload?: ServiceTokenPayload;
-  error?: string;
-}
+type VerifyServiceTokenResult = JwtVerifyResult<ServiceTokenPayload>;
 /**
- * Generate a JWT token for team agent authentication
- * Token expires in 5 minutes
- *
- * @param params - Token generation parameters
- * @returns Signed JWT token string
+ * Generate a JWT token for agent-to-agent authentication.
+ * Token expires in 5 minutes.
  */
 declare function generateServiceToken(params: GenerateServiceTokenParams): Promise<string>;
 /**
  * Verify and decode a service JWT token
- *
- * @param token - JWT token string to verify
- * @returns Verification result with payload if valid
  */
 declare function verifyServiceToken(token: string): Promise<VerifyServiceTokenResult>;
 /**
- * Validate that the token's tenant ID matches the expected tenant
- * This prevents cross-tenant delegation attempts
- *
- * @param payload - Decoded token payload
- * @param expectedTenantId - The tenant ID to validate against
- * @returns true if tenant IDs match, false otherwise
+ * Validate that the token's tenant ID matches the expected tenant.
+ * This prevents cross-tenant delegation attempts.
  */
 declare function validateTenantId(payload: ServiceTokenPayload, expectedTenantId: string): boolean;
 /**
  * Validate that the token's target agent ID matches the expected agent
- *
- * @param payload - Decoded token payload
- * @param expectedTargetAgentId - The agent ID to validate against
- * @returns true if agent IDs match, false otherwise
  */
 declare function validateTargetAgent(payload: ServiceTokenPayload, expectedTargetAgentId: string): boolean;
 /**
  * Extract the Authorization header and verify the bearer token
- *
- * @param authHeader - The Authorization header value (e.g., "Bearer <token>")
- * @returns Verification result with payload if valid
  */
 declare function verifyAuthorizationHeader(authHeader: string | undefined): Promise<VerifyServiceTokenResult>;
 //#endregion

package/dist/utils/service-token-auth.js

@@ -1,40 +1,25 @@
-import { env } from "../env.js";
 import { getLogger } from "./logger.js";
-import { SignJWT, jwtVerify } from "jose";
+import { extractBearerToken, signJwt, verifyJwt } from "./jwt-helpers.js";
 
 //#region src/utils/service-token-auth.ts
 const logger = getLogger("service-token-auth");
+const ISSUER = "inkeep-agents";
 /**
-* Get the JWT secret from environment variables
-* Falls back to a default secret in non-production environments (with warning)
-*/
-function getJwtSecret() {
-	const secret = env.INKEEP_AGENTS_JWT_SIGNING_SECRET;
-	const dev_secret = "insecure-dev-secret-change-in-production-min-32-chars";
-	if (!secret) {
-		if (env.ENVIRONMENT === "production") throw new Error("INKEEP_AGENTS_JWT_SIGNING_SECRET environment variable is required in production");
-		logger.warn({}, "INKEEP_AGENTS_JWT_SIGNING_SECRET not set, using insecure default. DO NOT USE IN PRODUCTION!");
-		return new TextEncoder().encode(dev_secret);
-	}
-	return new TextEncoder().encode(secret);
-}
-/**
-* Generate a JWT token for team agent authentication
-* Token expires in 5 minutes
-*
-* @param params - Token generation parameters
-* @returns Signed JWT token string
+* Generate a JWT token for agent-to-agent authentication.
+* Token expires in 5 minutes.
 */
 async function generateServiceToken(params) {
-	const secret = getJwtSecret();
 	try {
-		const token = await new SignJWT({
-			tenantId: params.tenantId,
-			projectId: params.projectId
-		}).setProtectedHeader({
-			alg: "HS256",
-			typ: "JWT"
-		}).setIssuer("inkeep-agents").setSubject(params.originAgentId).setAudience(params.targetAgentId).setIssuedAt().setExpirationTime("5m").sign(secret);
+		const token = await signJwt({
+			issuer: ISSUER,
+			subject: params.originAgentId,
+			audience: params.targetAgentId,
+			expiresIn: "5m",
+			claims: {
+				tenantId: params.tenantId,
+				projectId: params.projectId
+			}
+		});
 		logger.debug({
 			originAgentId: params.originAgentId,
 			targetAgentId: params.targetAgentId,
@@ -48,64 +33,46 @@ async function generateServiceToken(params) {
 }
 /**
 * Verify and decode a service JWT token
-*
-* @param token - JWT token string to verify
-* @returns Verification result with payload if valid
 */
 async function verifyServiceToken(token) {
-	const secret = getJwtSecret();
-	try {
-		const { payload } = await jwtVerify(token, secret, {
-			issuer: "inkeep-agents",
-			algorithms: ["HS256"]
-		});
-		if (typeof payload.sub !== "string" || typeof payload.aud !== "string" || typeof payload.tenantId !== "string" || typeof payload.projectId !== "string") {
-			logger.warn({ payload }, "Invalid service token: missing required claims");
-			return {
-				valid: false,
-				error: "Invalid token: missing required claims"
-			};
-		}
-		const validPayload = {
-			iss: payload.iss,
-			aud: payload.aud,
-			sub: payload.sub,
-			tenantId: payload.tenantId,
-			projectId: payload.projectId,
-			iat: payload.iat,
-			exp: payload.exp
-		};
-		logger.debug({
-			originAgentId: validPayload.sub,
-			targetAgentId: validPayload.aud,
-			tenantId: validPayload.tenantId
-		}, "Successfully verified team agent token");
+	const result = await verifyJwt(token, { issuer: ISSUER });
+	if (!result.valid || !result.payload) {
+		logger.warn({ error: result.error }, "Team agent token verification failed");
 		return {
-			valid: true,
-			payload: validPayload
+			valid: false,
+			error: result.error
 		};
-	} catch (error) {
-		if (error instanceof Error) {
-			logger.warn({ error: error.message }, "Team agent token verification failed");
-			return {
-				valid: false,
-				error: error.message
-			};
-		}
-		logger.warn({ error }, "Team agent token verification failed with unknown error");
+	}
+	const payload = result.payload;
+	if (typeof payload.sub !== "string" || typeof payload.aud !== "string" || typeof payload.tenantId !== "string" || typeof payload.projectId !== "string") {
+		logger.warn({ payload }, "Invalid service token: missing required claims");
 		return {
 			valid: false,
-			error: "Token verification failed"
+			error: "Invalid token: missing required claims"
 		};
 	}
+	const validPayload = {
+		iss: payload.iss,
+		aud: payload.aud,
+		sub: payload.sub,
+		tenantId: payload.tenantId,
+		projectId: payload.projectId,
+		iat: payload.iat,
+		exp: payload.exp
+	};
+	logger.debug({
+		originAgentId: validPayload.sub,
+		targetAgentId: validPayload.aud,
+		tenantId: validPayload.tenantId
+	}, "Successfully verified team agent token");
+	return {
+		valid: true,
+		payload: validPayload
+	};
 }
 /**
-* Validate that the token's tenant ID matches the expected tenant
-* This prevents cross-tenant delegation attempts
-*
-* @param payload - Decoded token payload
-* @param expectedTenantId - The tenant ID to validate against
-* @returns true if tenant IDs match, false otherwise
+* Validate that the token's tenant ID matches the expected tenant.
+* This prevents cross-tenant delegation attempts.
 */
 function validateTenantId(payload, expectedTenantId) {
 	if (payload.tenantId !== expectedTenantId) {
@@ -121,10 +88,6 @@ function validateTenantId(payload, expectedTenantId) {
 }
 /**
 * Validate that the token's target agent ID matches the expected agent
-*
-* @param payload - Decoded token payload
-* @param expectedTargetAgentId - The agent ID to validate against
-* @returns true if agent IDs match, false otherwise
 */
 function validateTargetAgent(payload, expectedTargetAgentId) {
 	if (payload.aud !== expectedTargetAgentId) {
@@ -139,25 +102,14 @@ function validateTargetAgent(payload, expectedTargetAgentId) {
 }
 /**
 * Extract the Authorization header and verify the bearer token
-*
-* @param authHeader - The Authorization header value (e.g., "Bearer <token>")
-* @returns Verification result with payload if valid
 */
 async function verifyAuthorizationHeader(authHeader) {
-	if (!authHeader) return {
-		valid: false,
-		error: "Missing Authorization header"
-	};
-	if (!authHeader.startsWith("Bearer ")) return {
-		valid: false,
-		error: "Invalid Authorization header format. Expected: Bearer <token>"
-	};
-	const token = authHeader.substring(7);
-	if (!token) return {
+	const extracted = extractBearerToken(authHeader);
+	if (!extracted.token) return {
 		valid: false,
-		error: "Empty token in Authorization header"
+		error: extracted.error
 	};
-	return verifyServiceToken(token);
+	return verifyServiceToken(extracted.token);
 }
 
 //#endregion

package/dist/utils/template-interpolation.d.ts

@@ -0,0 +1,22 @@
+//#region src/utils/template-interpolation.d.ts
+/**
+ * Interpolates a message template with placeholders from a payload object.
+ * Supports {{path.to.value}} placeholder syntax with dot notation for nested paths.
+ * Missing values are replaced with empty strings.
+ *
+ * @param template - Message template with {{placeholder}} syntax
+ * @param payload - Object containing values to interpolate
+ * @returns Interpolated message with all placeholders resolved
+ *
+ * @example
+ * const template = "User {{user.name}} from {{user.profile.location}} submitted: {{message}}";
+ * const payload = {
+ *   user: { name: "Alice", profile: { location: "NYC" } },
+ *   message: "Hello World"
+ * };
+ * interpolateTemplate(template, payload);
+ * // => "User Alice from NYC submitted: Hello World"
+ */
+declare function interpolateTemplate(template: string, payload: Record<string, unknown>): string;
+//#endregion
+export { interpolateTemplate };

package/dist/utils/template-interpolation.js

@@ -0,0 +1,62 @@
+//#region src/utils/template-interpolation.ts
+/**
+* Resolves a nested path from an object using dot notation.
+* Example: getValue({ user: { profile: { name: 'John' } } }, 'user.profile.name') => 'John'
+*
+* @param obj - The object to traverse
+* @param path - Dot-separated path (e.g., 'user.profile.name')
+* @returns The value at the path, or undefined if not found
+*/
+function getValue(obj, path) {
+	if (!obj || typeof obj !== "object") return;
+	const keys = path.split(".");
+	let current = obj;
+	for (const key of keys) {
+		if (current === null || current === void 0 || typeof current !== "object") return;
+		current = current[key];
+	}
+	return current;
+}
+/**
+* Converts a value to string for template interpolation.
+* Handles primitives, null, undefined gracefully.
+*
+* @param value - The value to convert
+* @returns String representation or empty string if undefined/null
+*/
+function valueToString(value) {
+	if (value === null || value === void 0) return "";
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return "";
+	}
+}
+/**
+* Interpolates a message template with placeholders from a payload object.
+* Supports {{path.to.value}} placeholder syntax with dot notation for nested paths.
+* Missing values are replaced with empty strings.
+*
+* @param template - Message template with {{placeholder}} syntax
+* @param payload - Object containing values to interpolate
+* @returns Interpolated message with all placeholders resolved
+*
+* @example
+* const template = "User {{user.name}} from {{user.profile.location}} submitted: {{message}}";
+* const payload = {
+*   user: { name: "Alice", profile: { location: "NYC" } },
+*   message: "Hello World"
+* };
+* interpolateTemplate(template, payload);
+* // => "User Alice from NYC submitted: Hello World"
+*/
+function interpolateTemplate(template, payload) {
+	return template.replace(/\{\{([^}]+)\}\}/g, (_match, path) => {
+		return valueToString(getValue(payload, path.trim()));
+	});
+}
+
+//#endregion
+export { interpolateTemplate };