@okrlinkhub/agent-bridge 2.0.1 → 3.0.1

package/src/client/index.ts

@@ -6,6 +6,24 @@ import type {
   HttpRouter,
 } from "convex/server";
 import type { ComponentApi } from "../component/_generated/component.js";
+export {
+  buildAgentBridgeStrictHeaders,
+  createAuth0TokenAdapter,
+  createCustomOidcTokenAdapter,
+  createNextAuthConvexTokenAdapter,
+  decodeJwtClaims,
+  resolveUserToken,
+  validateJwtClaims,
+} from "./userAuth.js";
+export type {
+  AgentBridgeStrictHeadersInput,
+  JwtClaimValidationOptions,
+  JwtClaimValidationResult,
+  JwtClaims,
+  NextAuthSessionLike,
+  TokenSource,
+  TokenSourceAdapter,
+} from "./userAuth.js";
 
 export type AgentBridgeFunctionType = "query" | "mutation" | "action";
 
@@ -136,8 +154,8 @@ type ExecuteRequestBody = {
 
 type RegisterRoutesOptions = {
   pathPrefix?: string;
-  serviceKey?: string;
-  serviceKeyEnvVar?: string;
+  serviceKeys?: Record<string, string>;
+  serviceKeysEnvVar?: string;
 };
 
 export function registerRoutes(
@@ -147,9 +165,10 @@ export function registerRoutes(
   options?: RegisterRoutesOptions,
 ) {
   const prefix = options?.pathPrefix ?? "/agent";
-  const expectedServiceKey =
-    options?.serviceKey ??
-    readRuntimeEnv(options?.serviceKeyEnvVar ?? "AGENT_BRIDGE_SERVICE_KEY");
+  const configuredServiceKeys = resolveConfiguredServiceKeys({
+    serviceKeys: options?.serviceKeys,
+    serviceKeysEnvVar: options?.serviceKeysEnvVar ?? "AGENT_BRIDGE_SERVICE_KEYS_JSON",
+  });
   const normalizedConfig = normalizeAgentBridgeConfig(bridgeConfig);
   const availableFunctionKeys = Object.keys(normalizedConfig.functions);
 
@@ -157,8 +176,6 @@ export function registerRoutes(
     path: `${prefix}/execute`,
     method: "POST",
     handler: httpActionGeneric(async (ctx, request) => {
-      const apiKey = request.headers.get("X-Agent-API-Key");
-
       let body: ExecuteRequestBody;
       try {
         body = await request.json();
@@ -185,22 +202,22 @@ export function registerRoutes(
         );
       }
 
-      const authResult = apiKey
-        ? await ctx.runMutation(component.gateway.authorizeRequest, {
-            apiKey,
-            functionKey,
-            estimatedCost: body.estimatedCost,
-          })
-        : await authorizeWithServiceHeaders({
-            request,
-            expectedServiceKey,
-            authorizeByAppKey: (appKey) =>
-              ctx.runMutation(component.gateway.authorizeByAppKey, {
-                appKey,
-                functionKey,
-                estimatedCost: body.estimatedCost,
-              }),
-          });
+      const headerValidation = validateStrictServiceHeaders({
+        request,
+        configuredServiceKeys,
+      });
+      if (!headerValidation.valid) {
+        return jsonResponse(
+          { success: false, error: headerValidation.error },
+          headerValidation.statusCode,
+        );
+      }
+
+      const authResult = await ctx.runMutation(component.gateway.authorizeByAppKey, {
+        appKey: headerValidation.appKey,
+        functionKey,
+        estimatedCost: body.estimatedCost,
+      });
 
       if (!authResult.authorized) {
         const response = jsonResponse(
@@ -239,6 +256,7 @@ export function registerRoutes(
 
         await ctx.runMutation(component.gateway.logAccess, {
           agentId: authResult.agentId as never,
+          serviceId: headerValidation.serviceId,
           functionKey,
           args,
           result,
@@ -255,6 +273,7 @@ export function registerRoutes(
 
         await ctx.runMutation(component.gateway.logAccess, {
           agentId: authResult.agentId as never,
+          serviceId: headerValidation.serviceId,
           functionKey,
           args: body.args ?? {},
           error: errorMessage,
@@ -346,54 +365,71 @@ function jsonResponse(data: unknown, status: number): Response {
   });
 }
 
-async function authorizeWithServiceHeaders(args: {
+function validateStrictServiceHeaders(args: {
   request: Request;
-  expectedServiceKey?: string;
-  authorizeByAppKey: (
-    appKey: string,
-  ) => Promise<
-    | { authorized: true; agentId: string }
-    | {
-        authorized: false;
-        error: string;
-        statusCode: number;
-        agentId?: string;
-        retryAfterSeconds?: number;
-      }
-  >;
-}) {
-  const providedServiceKey = args.request.headers.get("X-Agent-Service-Key");
-  const appKey = args.request.headers.get("X-Agent-App");
+  configuredServiceKeys:
+    | { ok: true; keysByServiceId: Record<string, string> }
+    | { ok: false; error: string };
+}):
+  | { valid: true; serviceId: string; appKey: string }
+  | { valid: false; error: string; statusCode: number } {
+  const serviceId = args.request.headers.get("X-Agent-Service-Id")?.trim();
+  const providedServiceKey = args.request.headers
+    .get("X-Agent-Service-Key")
+    ?.trim();
+  const appKey = args.request.headers.get("X-Agent-App")?.trim();
+
+  if (!serviceId) {
+    return {
+      valid: false,
+      error: "Missing required header: X-Agent-Service-Id",
+      statusCode: 400,
+    };
+  }
   if (!providedServiceKey) {
     return {
-      authorized: false as const,
-      error: "Missing authentication header: X-Agent-Service-Key",
-      statusCode: 401,
+      valid: false,
+      error: "Missing required header: X-Agent-Service-Key",
+      statusCode: 400,
     };
   }
   if (!appKey) {
     return {
-      authorized: false as const,
-      error: "Missing routing header: X-Agent-App",
+      valid: false,
+      error: "Missing required header: X-Agent-App",
       statusCode: 400,
     };
   }
-  if (!args.expectedServiceKey) {
+
+  if (!args.configuredServiceKeys.ok) {
     return {
-      authorized: false as const,
-      error:
-        "Bridge service key is not configured. Set AGENT_BRIDGE_SERVICE_KEY or pass registerRoutes({ serviceKey })",
+      valid: false,
+      error: args.configuredServiceKeys.error,
       statusCode: 500,
     };
   }
-  if (providedServiceKey !== args.expectedServiceKey) {
+
+  const expectedServiceKey = args.configuredServiceKeys.keysByServiceId[serviceId];
+  if (!expectedServiceKey) {
+    return {
+      valid: false,
+      error: `Unknown service id: ${serviceId}`,
+      statusCode: 401,
+    };
+  }
+  if (providedServiceKey !== expectedServiceKey) {
     return {
-      authorized: false as const,
+      valid: false,
       error: "Invalid service key",
       statusCode: 401,
     };
   }
-  return await args.authorizeByAppKey(appKey);
+
+  return {
+    valid: true,
+    serviceId,
+    appKey,
+  };
 }
 
 function readRuntimeEnv(name: string): string | undefined {
@@ -406,3 +442,73 @@ function readRuntimeEnv(name: string): string | undefined {
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : undefined;
 }
+
+function resolveConfiguredServiceKeys(args: {
+  serviceKeys?: Record<string, string>;
+  serviceKeysEnvVar: string;
+}):
+  | { ok: true; keysByServiceId: Record<string, string> }
+  | { ok: false; error: string } {
+  if (args.serviceKeys) {
+    return sanitizeServiceKeysMap(args.serviceKeys);
+  }
+
+  const json = readRuntimeEnv(args.serviceKeysEnvVar);
+  if (!json) {
+    return {
+      ok: false,
+      error: `Bridge service keys are not configured. Provide registerRoutes({ serviceKeys }) or set ${args.serviceKeysEnvVar}`,
+    };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return {
+      ok: false,
+      error: `Invalid JSON in ${args.serviceKeysEnvVar}`,
+    };
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return {
+      ok: false,
+      error: `${args.serviceKeysEnvVar} must be a JSON object mapping serviceId to serviceKey`,
+    };
+  }
+
+  return sanitizeServiceKeysMap(parsed as Record<string, unknown>);
+}
+
+function sanitizeServiceKeysMap(
+  input: Record<string, unknown>,
+): { ok: true; keysByServiceId: Record<string, string> } | { ok: false; error: string } {
+  const keysByServiceId: Record<string, string> = {};
+  for (const [serviceIdRaw, serviceKeyRaw] of Object.entries(input)) {
+    if (typeof serviceKeyRaw !== "string") {
+      return {
+        ok: false,
+        error: `Invalid service key value for "${serviceIdRaw}"`,
+      };
+    }
+    const serviceId = serviceIdRaw.trim();
+    const serviceKey = serviceKeyRaw.trim();
+    if (!serviceId || !serviceKey) {
+      return {
+        ok: false,
+        error: "Service ids and service keys cannot be empty",
+      };
+    }
+    keysByServiceId[serviceId] = serviceKey;
+  }
+
+  if (Object.keys(keysByServiceId).length === 0) {
+    return {
+      ok: false,
+      error: "At least one service key must be configured",
+    };
+  }
+
+  return { ok: true, keysByServiceId };
+}

package/src/client/userAuth.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "vitest";
+import {
+  buildAgentBridgeStrictHeaders,
+  createAuth0TokenAdapter,
+  createCustomOidcTokenAdapter,
+  createNextAuthConvexTokenAdapter,
+  decodeJwtClaims,
+  resolveUserToken,
+  validateJwtClaims,
+} from "./userAuth.js";
+
+const TEST_JWT =
+  "eyJhbGciOiJub25lIn0.eyJzdWIiOiJ1c2VyXzEyMyIsImlzcyI6Imh0dHBzOi8vZGVtby5jb252ZXguc2l0ZSIsImF1ZCI6ImNvbnZleCIsImV4cCI6NDA3MDkwODgwMH0.";
+
+describe("user auth helpers", () => {
+  test("builds strict headers and includes bearer when provided", () => {
+    const headers = buildAgentBridgeStrictHeaders({
+      serviceId: "openclaw-prod",
+      serviceKey: "abs_live_example",
+      appKey: "crm",
+      userToken: "jwt_token",
+    });
+
+    expect(headers["X-Agent-Service-Id"]).toBe("openclaw-prod");
+    expect(headers["X-Agent-Service-Key"]).toBe("abs_live_example");
+    expect(headers["X-Agent-App"]).toBe("crm");
+    expect(headers.Authorization).toBe("Bearer jwt_token");
+  });
+
+  test("decodes jwt claims", () => {
+    const claims = decodeJwtClaims(TEST_JWT);
+    expect(claims?.sub).toBe("user_123");
+    expect(claims?.iss).toBe("https://demo.convex.site");
+    expect(claims?.aud).toBe("convex");
+  });
+
+  test("validates jwt claims with issuer and audience", () => {
+    const validation = validateJwtClaims(TEST_JWT, {
+      expectedIssuer: "https://demo.convex.site",
+      expectedAudience: "convex",
+      nowMs: Date.UTC(2026, 0, 1),
+    });
+    expect(validation.valid).toBe(true);
+  });
+
+  test("fails when jwt is expired", () => {
+    const expired = validateJwtClaims(TEST_JWT, {
+      nowMs: Date.UTC(2100, 0, 1),
+    });
+    expect(expired.valid).toBe(false);
+    expect(expired.reason).toBe("expired");
+  });
+
+  test("resolves nextauth convex token", async () => {
+    const adapter = createNextAuthConvexTokenAdapter({
+      getSession: async () => ({ convexToken: "convex_jwt" }),
+    });
+    const token = await resolveUserToken(adapter);
+    expect(token).toBe("convex_jwt");
+  });
+
+  test("resolves auth0 token", async () => {
+    const adapter = createAuth0TokenAdapter({
+      getAccessToken: async () => "auth0_jwt",
+    });
+    const token = await resolveUserToken(adapter);
+    expect(token).toBe("auth0_jwt");
+  });
+
+  test("resolves custom oidc token", async () => {
+    const adapter = createCustomOidcTokenAdapter({
+      getToken: async () => "oidc_jwt",
+    });
+    const token = await resolveUserToken(adapter);
+    expect(token).toBe("oidc_jwt");
+  });
+});

package/src/client/userAuth.ts

@@ -0,0 +1,192 @@
+export type TokenSource = "nextauth_convex" | "auth0" | "custom_oidc";
+
+export type JwtAudience = string | Array<string>;
+
+export interface JwtClaims {
+  sub?: string;
+  iss?: string;
+  aud?: JwtAudience;
+  exp?: number;
+  [key: string]: unknown;
+}
+
+export interface JwtClaimValidationOptions {
+  expectedIssuer?: string;
+  expectedAudience?: string;
+  nowMs?: number;
+}
+
+export interface JwtClaimValidationResult {
+  valid: boolean;
+  reason?: "malformed_token" | "expired" | "issuer_mismatch" | "audience_mismatch";
+  claims: JwtClaims | null;
+}
+
+export interface AgentBridgeStrictHeadersInput {
+  serviceId: string;
+  serviceKey: string;
+  appKey: string;
+  userToken?: string | null;
+}
+
+export interface NextAuthSessionLike {
+  convexToken?: string | null;
+}
+
+export type UserTokenResolver = () => Promise<string | null>;
+
+export interface TokenSourceAdapter {
+  tokenSource: TokenSource;
+  resolveUserToken: UserTokenResolver;
+}
+
+export function buildAgentBridgeStrictHeaders(
+  input: AgentBridgeStrictHeadersInput,
+): Record<string, string> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "X-Agent-Service-Id": input.serviceId,
+    "X-Agent-Service-Key": input.serviceKey,
+    "X-Agent-App": input.appKey,
+  };
+
+  if (input.userToken) {
+    headers.Authorization = `Bearer ${input.userToken}`;
+  }
+
+  return headers;
+}
+
+export function decodeJwtClaims(token: string): JwtClaims | null {
+  const parts = token.split(".");
+  if (parts.length !== 3 || !parts[1]) {
+    return null;
+  }
+
+  try {
+    const payload = decodeBase64Url(parts[1]);
+    const claims = JSON.parse(payload) as JwtClaims;
+    return claims;
+  } catch {
+    return null;
+  }
+}
+
+export function validateJwtClaims(
+  token: string,
+  options?: JwtClaimValidationOptions,
+): JwtClaimValidationResult {
+  const claims = decodeJwtClaims(token);
+  if (!claims) {
+    return {
+      valid: false,
+      reason: "malformed_token",
+      claims: null,
+    };
+  }
+
+  const nowMs = options?.nowMs ?? Date.now();
+  if (typeof claims.exp === "number") {
+    const expiresAtMs = claims.exp * 1000;
+    if (expiresAtMs <= nowMs) {
+      return {
+        valid: false,
+        reason: "expired",
+        claims,
+      };
+    }
+  }
+
+  if (options?.expectedIssuer && claims.iss !== options.expectedIssuer) {
+    return {
+      valid: false,
+      reason: "issuer_mismatch",
+      claims,
+    };
+  }
+
+  if (options?.expectedAudience) {
+    const audience = claims.aud;
+    const hasAudienceMatch = Array.isArray(audience)
+      ? audience.includes(options.expectedAudience)
+      : audience === options.expectedAudience;
+
+    if (!hasAudienceMatch) {
+      return {
+        valid: false,
+        reason: "audience_mismatch",
+        claims,
+      };
+    }
+  }
+
+  return {
+    valid: true,
+    claims,
+  };
+}
+
+export function createNextAuthConvexTokenAdapter(args: {
+  getSession: () => Promise<NextAuthSessionLike | null | undefined>;
+}): TokenSourceAdapter {
+  return {
+    tokenSource: "nextauth_convex",
+    resolveUserToken: async () => {
+      const session = await args.getSession();
+      const token = session?.convexToken;
+      if (typeof token !== "string" || token.trim().length === 0) {
+        return null;
+      }
+      return token;
+    },
+  };
+}
+
+export function createAuth0TokenAdapter(args: {
+  getAccessToken: () => Promise<string | null | undefined>;
+}): TokenSourceAdapter {
+  return {
+    tokenSource: "auth0",
+    resolveUserToken: async () => {
+      const token = await args.getAccessToken();
+      if (typeof token !== "string" || token.trim().length === 0) {
+        return null;
+      }
+      return token;
+    },
+  };
+}
+
+export function createCustomOidcTokenAdapter(args: {
+  getToken: () => Promise<string | null | undefined>;
+}): TokenSourceAdapter {
+  return {
+    tokenSource: "custom_oidc",
+    resolveUserToken: async () => {
+      const token = await args.getToken();
+      if (typeof token !== "string" || token.trim().length === 0) {
+        return null;
+      }
+      return token;
+    },
+  };
+}
+
+export async function resolveUserToken(
+  adapter: TokenSourceAdapter,
+): Promise<string | null> {
+  return await adapter.resolveUserToken();
+}
+
+function decodeBase64Url(value: string): string {
+  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+  const paddingLength = (4 - (normalized.length % 4)) % 4;
+  const padded = normalized + "=".repeat(paddingLength);
+
+  if (typeof atob === "function") {
+    return atob(padded);
+  }
+
+  const buffer = Buffer.from(padded, "base64");
+  return buffer.toString("utf-8");
+}

package/src/component/_generated/component.ts

@@ -112,6 +112,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           error?: string;
           functionKey: string;
           result?: any;
+          serviceId?: string;
           timestamp: number;
         },
         null,
@@ -120,7 +121,12 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
       queryAccessLog: FunctionReference<
         "query",
         "internal",
-        { agentId?: string; functionKey?: string; limit?: number },
+        {
+          agentId?: string;
+          functionKey?: string;
+          limit?: number;
+          serviceId?: string;
+        },
         Array<{
           _id: string;
           agentId: string;
@@ -129,6 +135,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           error?: string;
           functionKey: string;
           result?: any;
+          serviceId?: string;
           timestamp: number;
         }>,
         Name

package/src/component/gateway.ts

@@ -100,6 +100,7 @@ export const authorizeByAppKey = mutation({
 export const logAccess = mutation({
   args: {
     agentId: v.id("agents"),
+    serviceId: v.optional(v.string()),
     functionKey: v.string(),
     args: v.any(),
     result: v.optional(v.any()),
@@ -112,6 +113,7 @@ export const logAccess = mutation({
     await ctx.db.insert("agentLogs", {
       timestamp: args.timestamp,
       agentId: args.agentId,
+      serviceId: args.serviceId,
       functionKey: args.functionKey,
       args: args.args,
       result: args.result,
@@ -128,6 +130,7 @@ export const logAccess = mutation({
 export const queryAccessLog = query({
   args: {
     agentId: v.optional(v.id("agents")),
+    serviceId: v.optional(v.string()),
     functionKey: v.optional(v.string()),
     limit: v.optional(v.number()),
   },
@@ -136,6 +139,7 @@ export const queryAccessLog = query({
       _id: v.id("agentLogs"),
       timestamp: v.number(),
       agentId: v.id("agents"),
+      serviceId: v.optional(v.string()),
       functionKey: v.string(),
       args: v.any(),
       result: v.optional(v.any()),
@@ -146,6 +150,33 @@ export const queryAccessLog = query({
   handler: async (ctx, args) => {
     const limit = args.limit ?? 50;
 
+    if (args.serviceId !== undefined) {
+      const logs = await ctx.db
+        .query("agentLogs")
+        .withIndex("by_serviceId_and_timestamp", (q) =>
+          q.eq("serviceId", args.serviceId),
+        )
+        .order("desc")
+        .take(limit);
+
+      const filteredLogs =
+        args.functionKey !== undefined
+          ? logs.filter((log) => log.functionKey === args.functionKey)
+          : logs;
+
+      return filteredLogs.map((l) => ({
+        _id: l._id,
+        timestamp: l.timestamp,
+        agentId: l.agentId,
+        serviceId: l.serviceId,
+        functionKey: l.functionKey,
+        args: l.args,
+        result: l.result,
+        error: l.error,
+        duration: l.duration,
+      }));
+    }
+
     const agentId = args.agentId;
     if (agentId !== undefined) {
       const logs = await ctx.db
@@ -160,6 +191,7 @@ export const queryAccessLog = query({
         _id: l._id,
         timestamp: l.timestamp,
         agentId: l.agentId,
+        serviceId: l.serviceId,
         functionKey: l.functionKey,
         args: l.args,
         result: l.result,
@@ -181,6 +213,7 @@ export const queryAccessLog = query({
       _id: l._id,
       timestamp: l.timestamp,
       agentId: l.agentId,
+      serviceId: l.serviceId,
       functionKey: l.functionKey,
       args: l.args,
       result: l.result,

package/src/component/schema.ts

@@ -40,6 +40,7 @@ export default defineSchema({
 
   agentLogs: defineTable({
     agentId: v.id("agents"),
+    serviceId: v.optional(v.string()),
     functionKey: v.string(),
     args: v.any(),
     result: v.optional(v.any()),
@@ -48,6 +49,7 @@ export default defineSchema({
     timestamp: v.number(),
   })
     .index("by_agentId_and_timestamp", ["agentId", "timestamp"])
+    .index("by_serviceId_and_timestamp", ["serviceId", "timestamp"])
     .index("by_functionKey", ["functionKey"])
     .index("by_timestamp", ["timestamp"]),
 });