@okrlinkhub/agent-bridge 3.0.1 → 3.0.2

package/src/client/index.ts

@@ -38,6 +38,7 @@ export interface AgentBridgeFunctionMetadata {
   description?: string;
   riskLevel?: "low" | "medium" | "high";
   category?: string;
+  authMode?: "service" | "user";
 }
 
 export interface AgentBridgeConfig {
@@ -156,6 +157,8 @@ type RegisterRoutesOptions = {
   pathPrefix?: string;
   serviceKeys?: Record<string, string>;
   serviceKeysEnvVar?: string;
+  auditHashSaltEnvVar?: string;
+  linkingMode?: "component_api_only";
 };
 
 export function registerRoutes(
@@ -165,10 +168,17 @@ export function registerRoutes(
   options?: RegisterRoutesOptions,
 ) {
   const prefix = options?.pathPrefix ?? "/agent";
+  const linkingMode = options?.linkingMode ?? "component_api_only";
+  if (linkingMode !== "component_api_only") {
+    throw new Error(`Unsupported linkingMode: ${linkingMode}`);
+  }
   const configuredServiceKeys = resolveConfiguredServiceKeys({
     serviceKeys: options?.serviceKeys,
     serviceKeysEnvVar: options?.serviceKeysEnvVar ?? "AGENT_BRIDGE_SERVICE_KEYS_JSON",
   });
+  const auditHashSalt =
+    readRuntimeEnv(options?.auditHashSaltEnvVar ?? "AGENT_BRIDGE_AUDIT_HASH_SALT") ??
+    "";
   const normalizedConfig = normalizeAgentBridgeConfig(bridgeConfig);
   const availableFunctionKeys = Object.keys(normalizedConfig.functions);
 
@@ -234,6 +244,10 @@ export function registerRoutes(
       }
 
       const startTime = Date.now();
+      const linkAuditContext = await extractLinkAuditContextFromRequest({
+        request,
+        auditHashSalt,
+      });
       try {
         const args = body.args ?? {};
         let result: unknown;
@@ -262,6 +276,7 @@ export function registerRoutes(
           result,
           duration: Date.now() - startTime,
           timestamp: Date.now(),
+          ...linkAuditContext,
         });
 
         return jsonResponse({ success: true, result }, 200);
@@ -277,8 +292,10 @@ export function registerRoutes(
           functionKey,
           args: body.args ?? {},
           error: errorMessage,
+          errorCode: "bridge_execution_error",
           duration: Date.now() - startTime,
           timestamp: Date.now(),
+          ...linkAuditContext,
         });
 
         return jsonResponse({ success: false, error: errorMessage }, 500);
@@ -443,6 +460,58 @@ function readRuntimeEnv(name: string): string | undefined {
   return trimmed.length > 0 ? trimmed : undefined;
 }
 
+async function extractLinkAuditContextFromRequest(args: {
+  request: Request;
+  auditHashSalt: string;
+}): Promise<{
+  linkedProvider?: string;
+  providerUserIdHash?: string;
+  appUserSubjectHash?: string;
+  linkStatus?: string;
+}> {
+  const linkedProvider =
+    args.request.headers.get("X-Agent-Link-Provider")?.trim().toLowerCase() || undefined;
+  const providerUserIdRaw =
+    args.request.headers.get("X-Agent-Link-Provider-User-Id")?.trim() || undefined;
+  const appUserSubjectRaw =
+    args.request.headers.get("X-Agent-Link-User-Subject")?.trim() || undefined;
+  const linkStatus = args.request.headers.get("X-Agent-Link-Status")?.trim() || undefined;
+  const providerUserIdHash = providerUserIdRaw
+    ? await hashAuditIdentifier(providerUserIdRaw, args.auditHashSalt)
+    : undefined;
+  const appUserSubjectHash = appUserSubjectRaw
+    ? await hashAuditIdentifier(appUserSubjectRaw, args.auditHashSalt)
+    : undefined;
+  const auditContext: {
+    linkedProvider?: string;
+    providerUserIdHash?: string;
+    appUserSubjectHash?: string;
+    linkStatus?: string;
+  } = {};
+  if (linkedProvider) {
+    auditContext.linkedProvider = linkedProvider;
+  }
+  if (providerUserIdHash) {
+    auditContext.providerUserIdHash = providerUserIdHash;
+  }
+  if (appUserSubjectHash) {
+    auditContext.appUserSubjectHash = appUserSubjectHash;
+  }
+  if (linkStatus) {
+    auditContext.linkStatus = linkStatus;
+  }
+  return auditContext;
+}
+
+async function hashAuditIdentifier(value: string, salt: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const input = encoder.encode(`${salt}:${value}`);
+  const digest = await crypto.subtle.digest("SHA-256", input);
+  return Array.from(new Uint8Array(digest))
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}
+
 function resolveConfiguredServiceKeys(args: {
   serviceKeys?: Record<string, string>;
   serviceKeysEnvVar: string;

package/src/client/linking.test.ts

@@ -0,0 +1,145 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { components, initConvexTest } from "./setup.test.js";
+
+describe("component linking lifecycle", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-01-01T10:00:00.000Z"));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  test("upsert + resolve are idempotent and appKey scoped", async () => {
+    const t = initConvexTest();
+
+    const first = await t.mutation(components.agentBridge.linking.upsertLink, {
+      provider: "discord",
+      providerUserId: "user-123",
+      appKey: "CRM",
+      appUserSubject: "convex-user-a",
+      expiresInDays: 30,
+      metadata: { source: "discord-command" },
+    });
+    expect(first.created).toBe(true);
+
+    const second = await t.mutation(components.agentBridge.linking.upsertLink, {
+      provider: "discord",
+      providerUserId: "user-123",
+      appKey: "crm",
+      appUserSubject: "convex-user-b",
+      expiresInDays: 30,
+    });
+    expect(second.created).toBe(false);
+    expect(second.linkId).toBe(first.linkId);
+
+    const resolved = await t.mutation(components.agentBridge.linking.resolveLink, {
+      provider: "discord",
+      providerUserId: "user-123",
+      appKey: "crm",
+    });
+    expect(resolved.ok).toBe(true);
+    if (!resolved.ok) {
+      throw new Error("Expected resolve to succeed");
+    }
+    expect(resolved.link.appUserSubject).toBe("convex-user-b");
+
+    const wrongApp = await t.mutation(components.agentBridge.linking.resolveLink, {
+      provider: "discord",
+      providerUserId: "user-123",
+      appKey: "billing",
+    });
+    expect(wrongApp.ok).toBe(false);
+    if (wrongApp.ok) {
+      throw new Error("Expected app scoped lookup to fail");
+    }
+    expect(wrongApp.errorCode).toBe("link_not_found");
+  });
+
+  test("revoke marks link as revoked", async () => {
+    const t = initConvexTest();
+    const created = await t.mutation(components.agentBridge.linking.upsertLink, {
+      provider: "telegram",
+      providerUserId: "tg-77",
+      appKey: "crm",
+      appUserSubject: "convex-user-77",
+    });
+
+    const revokeResult = await t.mutation(components.agentBridge.linking.revokeLink, {
+      linkId: created.linkId,
+    });
+    expect(revokeResult.revoked).toBe(true);
+
+    const resolved = await t.mutation(components.agentBridge.linking.resolveLink, {
+      provider: "telegram",
+      providerUserId: "tg-77",
+      appKey: "crm",
+    });
+    expect(resolved.ok).toBe(false);
+    if (resolved.ok) {
+      throw new Error("Expected revoked link to fail");
+    }
+    expect(resolved.errorCode).toBe("link_revoked");
+    expect(resolved.statusCode).toBe(410);
+  });
+
+  test("expired links are detected and converted to expired status", async () => {
+    const t = initConvexTest();
+    await t.mutation(components.agentBridge.linking.upsertLink, {
+      provider: "discord",
+      providerUserId: "exp-1",
+      appKey: "crm",
+      appUserSubject: "convex-user-exp",
+      expiresInDays: 1,
+    });
+
+    vi.setSystemTime(new Date("2026-01-03T10:00:00.000Z"));
+    const resolved = await t.mutation(components.agentBridge.linking.resolveLink, {
+      provider: "discord",
+      providerUserId: "exp-1",
+      appKey: "crm",
+    });
+
+    expect(resolved.ok).toBe(false);
+    if (resolved.ok) {
+      throw new Error("Expected expired link to fail");
+    }
+    expect(resolved.errorCode).toBe("link_expired");
+    expect(resolved.statusCode).toBe(410);
+  });
+
+  test("resolveLink applies per-link rate limiting", async () => {
+    const t = initConvexTest();
+    await t.mutation(components.agentBridge.linking.upsertLink, {
+      provider: "discord",
+      providerUserId: "rl-1",
+      appKey: "crm",
+      appUserSubject: "convex-user-rl",
+    });
+
+    const first = await t.mutation(components.agentBridge.linking.resolveLink, {
+      provider: "discord",
+      providerUserId: "rl-1",
+      appKey: "crm",
+      maxRequestsPerWindow: 1,
+      windowSeconds: 60,
+    });
+    expect(first.ok).toBe(true);
+
+    const second = await t.mutation(components.agentBridge.linking.resolveLink, {
+      provider: "discord",
+      providerUserId: "rl-1",
+      appKey: "crm",
+      maxRequestsPerWindow: 1,
+      windowSeconds: 60,
+    });
+    expect(second.ok).toBe(false);
+    if (second.ok) {
+      throw new Error("Expected second resolve to be rate limited");
+    }
+    expect(second.errorCode).toBe("link_rate_limited");
+    expect(second.statusCode).toBe(429);
+    expect(second.retryAfterSeconds).toBeGreaterThanOrEqual(1);
+  });
+});

package/src/component/_generated/api.ts

@@ -11,6 +11,7 @@
 import type * as agentBridgeUtils from "../agentBridgeUtils.js";
 import type * as agents from "../agents.js";
 import type * as gateway from "../gateway.js";
+import type * as linking from "../linking.js";
 import type * as permissions from "../permissions.js";
 
 import type {
@@ -24,6 +25,7 @@ const fullApi: ApiFromModules<{
   agentBridgeUtils: typeof agentBridgeUtils;
   agents: typeof agents;
   gateway: typeof gateway;
+  linking: typeof linking;
   permissions: typeof permissions;
 }> = anyApi as any;
 

package/src/component/_generated/component.ts

@@ -107,10 +107,16 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         "internal",
         {
           agentId: string;
+          appUserSubjectHash?: string;
           args: any;
           duration: number;
           error?: string;
+          errorCode?: string;
           functionKey: string;
+          linkStatus?: string;
+          linkedProvider?: string;
+          providerUserIdHash?: string;
+          rateLimited?: boolean;
           result?: any;
           serviceId?: string;
           timestamp: number;
@@ -130,10 +136,16 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         Array<{
           _id: string;
           agentId: string;
+          appUserSubjectHash?: string;
           args: any;
           duration: number;
           error?: string;
+          errorCode?: string;
           functionKey: string;
+          linkStatus?: string;
+          linkedProvider?: string;
+          providerUserIdHash?: string;
+          rateLimited?: boolean;
           result?: any;
           serviceId?: string;
           timestamp: number;
@@ -141,6 +153,108 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         Name
       >;
     };
+    linking: {
+      listLinks: FunctionReference<
+        "query",
+        "internal",
+        {
+          appKey?: string;
+          limit?: number;
+          provider?: string;
+          status?: "active" | "revoked" | "expired";
+        },
+        Array<{
+          _id: string;
+          appKey: string;
+          appUserSubject: string;
+          createdAt: number;
+          expiresAt?: number;
+          lastUsedAt?: number;
+          metadata?: any;
+          provider: string;
+          providerUserId: string;
+          refreshTokenCiphertext?: string;
+          refreshTokenExpiresAt?: number;
+          revokedAt?: number;
+          status: "active" | "revoked" | "expired";
+          tokenVersion?: number;
+          updatedAt: number;
+        }>,
+        Name
+      >;
+      resolveLink: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          appKey: string;
+          extendExpiryDaysOnUse?: number;
+          maxRequestsPerWindow?: number;
+          provider: string;
+          providerUserId: string;
+          windowSeconds?: number;
+        },
+        | {
+            link: {
+              _id: string;
+              appKey: string;
+              appUserSubject: string;
+              createdAt: number;
+              expiresAt?: number;
+              lastUsedAt?: number;
+              metadata?: any;
+              provider: string;
+              providerUserId: string;
+              refreshTokenCiphertext?: string;
+              refreshTokenExpiresAt?: number;
+              revokedAt?: number;
+              status: "active" | "revoked" | "expired";
+              tokenVersion?: number;
+              updatedAt: number;
+            };
+            ok: true;
+          }
+        | {
+            errorCode:
+              | "link_not_found"
+              | "link_revoked"
+              | "link_expired"
+              | "link_rate_limited";
+            ok: false;
+            retryAfterSeconds?: number;
+            statusCode: number;
+          },
+        Name
+      >;
+      revokeLink: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          appKey?: string;
+          linkId?: string;
+          provider?: string;
+          providerUserId?: string;
+        },
+        { linkId?: string; revoked: boolean },
+        Name
+      >;
+      upsertLink: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          appKey: string;
+          appUserSubject: string;
+          expiresInDays?: number;
+          metadata?: any;
+          provider: string;
+          providerUserId: string;
+          refreshTokenCiphertext?: string;
+          refreshTokenExpiresAt?: number;
+          tokenVersion?: number;
+        },
+        { created: boolean; expiresAt?: number; linkId: string },
+        Name
+      >;
+    };
     permissions: {
       listAgentPermissions: FunctionReference<
         "query",

package/src/component/gateway.ts

@@ -105,7 +105,13 @@ export const logAccess = mutation({
     args: v.any(),
     result: v.optional(v.any()),
     error: v.optional(v.string()),
+    errorCode: v.optional(v.string()),
     duration: v.number(),
+    linkedProvider: v.optional(v.string()),
+    providerUserIdHash: v.optional(v.string()),
+    appUserSubjectHash: v.optional(v.string()),
+    linkStatus: v.optional(v.string()),
+    rateLimited: v.optional(v.boolean()),
     timestamp: v.number(),
   },
   returns: v.null(),
@@ -118,7 +124,13 @@ export const logAccess = mutation({
       args: args.args,
       result: args.result,
       error: args.error,
+      errorCode: args.errorCode,
       duration: args.duration,
+      linkedProvider: args.linkedProvider,
+      providerUserIdHash: args.providerUserIdHash,
+      appUserSubjectHash: args.appUserSubjectHash,
+      linkStatus: args.linkStatus,
+      rateLimited: args.rateLimited,
     });
     return null;
   },
@@ -144,7 +156,13 @@ export const queryAccessLog = query({
       args: v.any(),
       result: v.optional(v.any()),
       error: v.optional(v.string()),
+      errorCode: v.optional(v.string()),
       duration: v.number(),
+      linkedProvider: v.optional(v.string()),
+      providerUserIdHash: v.optional(v.string()),
+      appUserSubjectHash: v.optional(v.string()),
+      linkStatus: v.optional(v.string()),
+      rateLimited: v.optional(v.boolean()),
     }),
   ),
   handler: async (ctx, args) => {
@@ -173,7 +191,13 @@ export const queryAccessLog = query({
         args: l.args,
         result: l.result,
         error: l.error,
+        errorCode: l.errorCode,
         duration: l.duration,
+        linkedProvider: l.linkedProvider,
+        providerUserIdHash: l.providerUserIdHash,
+        appUserSubjectHash: l.appUserSubjectHash,
+        linkStatus: l.linkStatus,
+        rateLimited: l.rateLimited,
       }));
     }
 
@@ -196,7 +220,13 @@ export const queryAccessLog = query({
         args: l.args,
         result: l.result,
         error: l.error,
+        errorCode: l.errorCode,
         duration: l.duration,
+        linkedProvider: l.linkedProvider,
+        providerUserIdHash: l.providerUserIdHash,
+        appUserSubjectHash: l.appUserSubjectHash,
+        linkStatus: l.linkStatus,
+        rateLimited: l.rateLimited,
       }));
     }
 
@@ -218,7 +248,13 @@ export const queryAccessLog = query({
       args: l.args,
       result: l.result,
       error: l.error,
+      errorCode: l.errorCode,
       duration: l.duration,
+      linkedProvider: l.linkedProvider,
+      providerUserIdHash: l.providerUserIdHash,
+      appUserSubjectHash: l.appUserSubjectHash,
+      linkStatus: l.linkStatus,
+      rateLimited: l.rateLimited,
     }));
   },
 });