@okrlinkhub/agent-bridge 0.1.0

package/src/component/gateway.ts

@@ -0,0 +1,282 @@
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server.js";
+
+// --- Token hashing utility (same as provisioning.ts) ---
+
+async function hashToken(token: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(token);
+  const hash = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(hash))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+// --- Pattern matching (same logic as permissions.ts) ---
+
+function patternSpecificity(pattern: string): number {
+  const wildcardIndex = pattern.indexOf("*");
+  if (wildcardIndex === -1) return pattern.length;
+  return wildcardIndex;
+}
+
+function matchesPattern(functionName: string, pattern: string): boolean {
+  if (pattern === "*") return true;
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  const regexStr = "^" + escaped.replace(/\*/g, ".*") + "$";
+  return new RegExp(regexStr).test(functionName);
+}
+
+// --- Authorize request result validator ---
+
+const authorizeResultValidator = v.union(
+  v.object({
+    authorized: v.literal(true),
+    agentId: v.string(),
+    appName: v.string(),
+    functionHandle: v.string(),
+    functionType: v.union(
+      v.literal("query"),
+      v.literal("mutation"),
+      v.literal("action"),
+    ),
+  }),
+  v.object({
+    authorized: v.literal(false),
+    error: v.string(),
+    statusCode: v.number(),
+    agentId: v.optional(v.string()),
+    matchedPattern: v.optional(v.string()),
+    matchedPermission: v.optional(
+      v.union(
+        v.literal("allow"),
+        v.literal("deny"),
+        v.literal("rate_limited"),
+      ),
+    ),
+  }),
+);
+
+/**
+ * Authorize an agent request.
+ * This is a mutation (not a query) because it updates counters and last activity.
+ *
+ * Steps:
+ * 1. Validate instance token
+ * 2. Check agent is active
+ * 3. Check function permissions
+ * 4. Look up function handle in registry
+ * 5. Update activity counters
+ *
+ * Returns the function handle info if authorized, or an error.
+ */
+export const authorizeRequest = mutation({
+  args: {
+    instanceToken: v.string(),
+    functionName: v.string(),
+    appName: v.string(),
+  },
+  returns: authorizeResultValidator,
+  handler: async (ctx, args) => {
+    // 1. Validate instance token
+    const tokenHash = await hashToken(args.instanceToken);
+    const instance = await ctx.db
+      .query("agentAppInstances")
+      .withIndex("by_instance_token_hash", (q) =>
+        q.eq("instanceTokenHash", tokenHash),
+      )
+      .unique();
+
+    if (!instance) {
+      return {
+        authorized: false as const,
+        error: "Invalid instance token",
+        statusCode: 401,
+      };
+    }
+
+    if (instance.expiresAt < Date.now()) {
+      return {
+        authorized: false as const,
+        error: "Instance token has expired",
+        statusCode: 401,
+      };
+    }
+
+    if (instance.appName !== args.appName) {
+      return {
+        authorized: false as const,
+        error: "Token does not match this app",
+        statusCode: 403,
+      };
+    }
+
+    const agentId = instance.agentId;
+
+    // 2. Check agent is active
+    const agent = await ctx.db
+      .query("registeredAgents")
+      .withIndex("by_agent_id", (q) => q.eq("agentId", agentId))
+      .unique();
+
+    if (!agent || !agent.isActive) {
+      return {
+        authorized: false as const,
+        error: "Agent has been revoked",
+        statusCode: 403,
+        agentId,
+      };
+    }
+
+    // 3. Check permissions
+    const permissions = await ctx.db
+      .query("functionPermissions")
+      .withIndex("by_agent_and_app", (q) =>
+        q.eq("agentId", agentId).eq("appName", args.appName),
+      )
+      .collect();
+
+    const matches = permissions
+      .filter((p) => matchesPattern(args.functionName, p.functionPattern))
+      .sort(
+        (a, b) =>
+          patternSpecificity(b.functionPattern) -
+          patternSpecificity(a.functionPattern),
+      );
+
+    if (matches.length === 0 || matches[0].permission === "deny") {
+      const bestMatch = matches[0];
+      return {
+        authorized: false as const,
+        error: "Function not authorized for this agent",
+        statusCode: 403,
+        agentId,
+        matchedPattern: bestMatch?.functionPattern,
+        matchedPermission: bestMatch?.permission,
+      };
+    }
+
+    // TODO: For rate_limited permissions, check rate counters here
+    // (circuit breaker - deferred to post-MVP)
+
+    // 4. Look up function handle
+    const fnEntry = await ctx.db
+      .query("functionRegistry")
+      .withIndex("by_app_and_function", (q) =>
+        q.eq("appName", args.appName).eq("functionName", args.functionName),
+      )
+      .unique();
+
+    if (!fnEntry) {
+      return {
+        authorized: false as const,
+        error: `Function "${args.functionName}" is not registered`,
+        statusCode: 404,
+        agentId,
+      };
+    }
+
+    // 5. Update activity counters
+    await ctx.db.patch(instance._id, {
+      lastActivityAt: Date.now(),
+      monthlyRequests: instance.monthlyRequests + 1,
+    });
+
+    return {
+      authorized: true as const,
+      agentId,
+      appName: args.appName,
+      functionHandle: fnEntry.functionHandle,
+      functionType: fnEntry.functionType,
+    };
+  },
+});
+
+/**
+ * Log an access attempt to the audit log.
+ * Called after function execution (success or failure).
+ */
+export const logAccess = mutation({
+  args: {
+    agentId: v.string(),
+    appName: v.string(),
+    functionCalled: v.string(),
+    permission: v.string(),
+    errorMessage: v.optional(v.string()),
+    durationMs: v.optional(v.number()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    await ctx.db.insert("accessLog", {
+      timestamp: Date.now(),
+      agentId: args.agentId,
+      appName: args.appName,
+      functionCalled: args.functionCalled,
+      permission: args.permission,
+      errorMessage: args.errorMessage,
+      durationMs: args.durationMs,
+    });
+    return null;
+  },
+});
+
+/**
+ * Query access logs for audit purposes.
+ */
+export const queryAccessLog = query({
+  args: {
+    agentId: v.optional(v.string()),
+    appName: v.optional(v.string()),
+    limit: v.optional(v.number()),
+  },
+  returns: v.array(
+    v.object({
+      timestamp: v.number(),
+      agentId: v.string(),
+      appName: v.string(),
+      functionCalled: v.string(),
+      permission: v.string(),
+      errorMessage: v.optional(v.string()),
+      durationMs: v.optional(v.number()),
+    }),
+  ),
+  handler: async (ctx, args) => {
+    const limit = args.limit ?? 50;
+
+    if (args.agentId) {
+      const logs = await ctx.db
+        .query("accessLog")
+        .withIndex("by_agent_and_timestamp", (q) =>
+          q.eq("agentId", args.agentId!),
+        )
+        .order("desc")
+        .take(limit);
+
+      return logs.map((l) => ({
+        timestamp: l.timestamp,
+        agentId: l.agentId,
+        appName: l.appName,
+        functionCalled: l.functionCalled,
+        permission: l.permission,
+        errorMessage: l.errorMessage,
+        durationMs: l.durationMs,
+      }));
+    }
+
+    // No filter: get recent logs
+    const logs = await ctx.db
+      .query("accessLog")
+      .order("desc")
+      .take(limit);
+
+    return logs.map((l) => ({
+      timestamp: l.timestamp,
+      agentId: l.agentId,
+      appName: l.appName,
+      functionCalled: l.functionCalled,
+      permission: l.permission,
+      errorMessage: l.errorMessage,
+      durationMs: l.durationMs,
+    }));
+  },
+});

package/src/component/permissions.ts

@@ -0,0 +1,321 @@
+import { v } from "convex/values";
+import { mutation, query, internalQuery } from "./_generated/server.js";
+
+// --- Permission result type ---
+
+const permissionResultValidator = v.object({
+  permission: v.union(
+    v.literal("allow"),
+    v.literal("deny"),
+    v.literal("rate_limited"),
+  ),
+  rateLimitConfig: v.optional(
+    v.object({
+      requestsPerHour: v.number(),
+      tokenBudget: v.number(),
+    }),
+  ),
+  matchedPattern: v.optional(v.string()),
+});
+
+// --- Pattern matching utilities ---
+
+/**
+ * Calculate specificity score for a pattern.
+ * More specific patterns (longer fixed prefix before the first wildcard)
+ * get higher scores.
+ */
+function patternSpecificity(pattern: string): number {
+  const wildcardIndex = pattern.indexOf("*");
+  if (wildcardIndex === -1) return pattern.length;
+  return wildcardIndex;
+}
+
+/**
+ * Check if a function name matches a permission pattern.
+ * Supports "*" as a wildcard that matches any characters.
+ * Examples: "okr:*" matches "okr:getObjectives", "*" matches anything.
+ */
+function matchesPattern(functionName: string, pattern: string): boolean {
+  if (pattern === "*") return true;
+  // Escape regex special chars except *, then replace * with .*
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  const regexStr = "^" + escaped.replace(/\*/g, ".*") + "$";
+  const regex = new RegExp(regexStr);
+  return regex.test(functionName);
+}
+
+// --- Public functions ---
+
+/**
+ * Set a permission for an agent on a specific app.
+ * If a permission with the same agentId + appName + functionPattern exists, it is updated.
+ */
+export const setPermission = mutation({
+  args: {
+    agentId: v.string(),
+    appName: v.string(),
+    functionPattern: v.string(),
+    permission: v.union(
+      v.literal("allow"),
+      v.literal("deny"),
+      v.literal("rate_limited"),
+    ),
+    rateLimitConfig: v.optional(
+      v.object({
+        requestsPerHour: v.number(),
+        tokenBudget: v.number(),
+      }),
+    ),
+    createdBy: v.string(),
+  },
+  returns: v.string(),
+  handler: async (ctx, args) => {
+    // Check for existing permission with same pattern
+    const existing = await ctx.db
+      .query("functionPermissions")
+      .withIndex("by_agent_and_app", (q) =>
+        q.eq("agentId", args.agentId).eq("appName", args.appName),
+      )
+      .collect();
+
+    const match = existing.find(
+      (p) => p.functionPattern === args.functionPattern,
+    );
+
+    if (match) {
+      await ctx.db.patch(match._id, {
+        permission: args.permission,
+        rateLimitConfig: args.rateLimitConfig,
+        createdBy: args.createdBy,
+        createdAt: Date.now(),
+      });
+      return match._id;
+    }
+
+    const id = await ctx.db.insert("functionPermissions", {
+      agentId: args.agentId,
+      appName: args.appName,
+      functionPattern: args.functionPattern,
+      permission: args.permission,
+      rateLimitConfig: args.rateLimitConfig,
+      createdAt: Date.now(),
+      createdBy: args.createdBy,
+    });
+    return id;
+  },
+});
+
+/**
+ * Remove a specific permission.
+ */
+export const removePermission = mutation({
+  args: {
+    agentId: v.string(),
+    appName: v.string(),
+    functionPattern: v.string(),
+  },
+  returns: v.boolean(),
+  handler: async (ctx, args) => {
+    const perms = await ctx.db
+      .query("functionPermissions")
+      .withIndex("by_agent_and_app", (q) =>
+        q.eq("agentId", args.agentId).eq("appName", args.appName),
+      )
+      .collect();
+
+    const match = perms.find(
+      (p) => p.functionPattern === args.functionPattern,
+    );
+
+    if (!match) return false;
+
+    await ctx.db.delete(match._id);
+    return true;
+  },
+});
+
+/**
+ * Check permission for a specific function call.
+ * Applies pattern matching with specificity ordering (most specific pattern wins).
+ * Default: deny if no matching pattern is found.
+ */
+export const checkPermission = query({
+  args: {
+    agentId: v.string(),
+    appName: v.string(),
+    functionName: v.string(),
+  },
+  returns: permissionResultValidator,
+  handler: async (ctx, args) => {
+    const permissions = await ctx.db
+      .query("functionPermissions")
+      .withIndex("by_agent_and_app", (q) =>
+        q.eq("agentId", args.agentId).eq("appName", args.appName),
+      )
+      .collect();
+
+    // Find all matching patterns and sort by specificity (most specific first)
+    const matches = permissions
+      .filter((p) => matchesPattern(args.functionName, p.functionPattern))
+      .sort(
+        (a, b) =>
+          patternSpecificity(b.functionPattern) -
+          patternSpecificity(a.functionPattern),
+      );
+
+    if (matches.length === 0) {
+      // Default: deny
+      return { permission: "deny" as const };
+    }
+
+    // Most specific pattern wins
+    const best = matches[0];
+    return {
+      permission: best.permission,
+      rateLimitConfig: best.rateLimitConfig,
+      matchedPattern: best.functionPattern,
+    };
+  },
+});
+
+/**
+ * List all permissions for an agent on a specific app.
+ */
+export const listPermissions = query({
+  args: {
+    agentId: v.string(),
+    appName: v.string(),
+  },
+  returns: v.array(
+    v.object({
+      functionPattern: v.string(),
+      permission: v.union(
+        v.literal("allow"),
+        v.literal("deny"),
+        v.literal("rate_limited"),
+      ),
+      rateLimitConfig: v.optional(
+        v.object({
+          requestsPerHour: v.number(),
+          tokenBudget: v.number(),
+        }),
+      ),
+      createdAt: v.number(),
+      createdBy: v.string(),
+    }),
+  ),
+  handler: async (ctx, args) => {
+    const perms = await ctx.db
+      .query("functionPermissions")
+      .withIndex("by_agent_and_app", (q) =>
+        q.eq("agentId", args.agentId).eq("appName", args.appName),
+      )
+      .collect();
+
+    return perms.map((p) => ({
+      functionPattern: p.functionPattern,
+      permission: p.permission,
+      rateLimitConfig: p.rateLimitConfig,
+      createdAt: p.createdAt,
+      createdBy: p.createdBy,
+    }));
+  },
+});
+
+/**
+ * Remove all permissions for a specific agent on a specific app.
+ */
+export const clearPermissions = mutation({
+  args: {
+    agentId: v.string(),
+    appName: v.string(),
+  },
+  returns: v.number(),
+  handler: async (ctx, args) => {
+    const perms = await ctx.db
+      .query("functionPermissions")
+      .withIndex("by_agent_and_app", (q) =>
+        q.eq("agentId", args.agentId).eq("appName", args.appName),
+      )
+      .collect();
+
+    for (const perm of perms) {
+      await ctx.db.delete(perm._id);
+    }
+
+    return perms.length;
+  },
+});
+
+/**
+ * Debug helper: show permission matching for a specific function call.
+ */
+export const debugMatchPermission = query({
+  args: {
+    agentId: v.string(),
+    appName: v.string(),
+    functionName: v.string(),
+  },
+  returns: v.object({
+    functionName: v.string(),
+    permissions: v.array(
+      v.object({
+        functionPattern: v.string(),
+        permission: v.union(
+          v.literal("allow"),
+          v.literal("deny"),
+          v.literal("rate_limited"),
+        ),
+        specificity: v.number(),
+      }),
+    ),
+    matches: v.array(
+      v.object({
+        functionPattern: v.string(),
+        permission: v.union(
+          v.literal("allow"),
+          v.literal("deny"),
+          v.literal("rate_limited"),
+        ),
+        specificity: v.number(),
+      }),
+    ),
+    bestMatch: v.optional(
+      v.object({
+        functionPattern: v.string(),
+        permission: v.union(
+          v.literal("allow"),
+          v.literal("deny"),
+          v.literal("rate_limited"),
+        ),
+        specificity: v.number(),
+      }),
+    ),
+  }),
+  handler: async (ctx, args) => {
+    const permissions = await ctx.db
+      .query("functionPermissions")
+      .withIndex("by_agent_and_app", (q) =>
+        q.eq("agentId", args.agentId).eq("appName", args.appName),
+      )
+      .collect();
+
+    const withSpecificity = permissions.map((p) => ({
+      functionPattern: p.functionPattern,
+      permission: p.permission,
+      specificity: patternSpecificity(p.functionPattern),
+    }));
+
+    const matches = withSpecificity
+      .filter((p) => matchesPattern(args.functionName, p.functionPattern))
+      .sort((a, b) => b.specificity - a.specificity);
+
+    return {
+      functionName: args.functionName,
+      permissions: withSpecificity,
+      matches,
+      bestMatch: matches[0],
+    };
+  },
+});