@gaganref/convex-api-keys 0.1.0

package/src/component/schema.ts

@@ -0,0 +1,49 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+import {
+  apiKeyStatusValidator,
+  metadataValidator,
+  permissionsValidator,
+} from "../shared.js";
+
+export const apiKeysFields = {
+  tokenHash: v.string(),
+  tokenPrefix: v.string(),
+  tokenLast4: v.string(),
+  namespace: v.optional(v.string()),
+  name: v.optional(v.string()),
+  permissions: v.optional(permissionsValidator),
+  metadata: v.optional(metadataValidator),
+  status: apiKeyStatusValidator,
+  expiresAt: v.optional(v.number()),
+  maxIdleMs: v.optional(v.number()),
+  lastUsedAt: v.number(),
+  revokedAt: v.optional(v.number()),
+  revocationReason: v.optional(v.string()),
+  replaces: v.optional(v.id("apiKeys")),
+  updatedAt: v.number(),
+};
+
+export const apiKeyEventsFields = {
+  keyId: v.id("apiKeys"),
+  namespace: v.optional(v.string()),
+  type: v.union(
+    v.literal("created"),
+    v.literal("revoked"),
+    v.literal("rotated"),
+  ),
+  reason: v.optional(v.string()),
+  metadata: v.optional(metadataValidator),
+};
+
+export default defineSchema({
+  apiKeys: defineTable(apiKeysFields)
+    .index("by_token_hash", ["tokenHash"])
+    .index("by_status", ["status"])
+    .index("by_namespace_and_status", ["namespace", "status"])
+    .index("by_revoked_at", ["revokedAt"]),
+
+  apiKeyEvents: defineTable(apiKeyEventsFields)
+    .index("by_key_id", ["keyId"])
+    .index("by_namespace", ["namespace"]),
+});

package/src/component/sweep.ts

@@ -0,0 +1,117 @@
+import { internalMutation } from "./_generated/server.js";
+import type { MutationCtx } from "./_generated/server.js";
+import { internal } from "./_generated/api.js";
+import { v } from "convex/values";
+import type { Id } from "./_generated/dataModel.js";
+
+const BATCH_SIZE = 100;
+
+function isIdleExpired(
+  key: { maxIdleMs?: number; lastUsedAt: number },
+  now: number,
+): boolean {
+  return key.maxIdleMs !== undefined && key.lastUsedAt + key.maxIdleMs < now;
+}
+
+/**
+ * Marks active keys past their absolute TTL as revoked.
+ *
+ * Uses cursor-based pagination to scan all active keys across multiple
+ * runs. Automatically reschedules itself until all pages are processed.
+ * Runs via the component's internal cron.
+ */
+export const sweepExpired = internalMutation({
+  args: {
+    cursor: v.optional(v.string()),
+  },
+  returns: v.object({
+    swept: v.number(),
+    isDone: v.boolean(),
+  }),
+  handler: async (ctx, args) => {
+    const now = Date.now();
+
+    const result = await ctx.db
+      .query("apiKeys")
+      .withIndex("by_status", (q) => q.eq("status", "active"))
+      .paginate({ numItems: BATCH_SIZE, cursor: args.cursor ?? null });
+
+    let swept = 0;
+    for (const key of result.page) {
+      if (key.expiresAt !== undefined && key.expiresAt < now) {
+        await markAsRevoked(ctx, key._id, key.namespace, now, "expired");
+        swept++;
+      }
+    }
+
+    if (!result.isDone) {
+      await ctx.scheduler.runAfter(0, internal.sweep.sweepExpired, {
+        cursor: result.continueCursor,
+      });
+    }
+
+    return { swept, isDone: result.isDone };
+  },
+});
+
+/**
+ * Marks active keys past their idle timeout as revoked.
+ *
+ * Uses cursor-based pagination to scan all active keys across multiple
+ * runs. Automatically reschedules itself until all pages are processed.
+ * Runs via the component's internal cron.
+ */
+export const sweepIdleExpired = internalMutation({
+  args: {
+    cursor: v.optional(v.string()),
+  },
+  returns: v.object({
+    swept: v.number(),
+    isDone: v.boolean(),
+  }),
+  handler: async (ctx, args) => {
+    const now = Date.now();
+
+    const result = await ctx.db
+      .query("apiKeys")
+      .withIndex("by_status", (q) => q.eq("status", "active"))
+      .paginate({ numItems: BATCH_SIZE, cursor: args.cursor ?? null });
+
+    let swept = 0;
+    for (const key of result.page) {
+      if (isIdleExpired(key, now)) {
+        await markAsRevoked(ctx, key._id, key.namespace, now, "idle_timeout");
+        swept++;
+      }
+    }
+
+    if (!result.isDone) {
+      await ctx.scheduler.runAfter(0, internal.sweep.sweepIdleExpired, {
+        cursor: result.continueCursor,
+      });
+    }
+
+    return { swept, isDone: result.isDone };
+  },
+});
+
+async function markAsRevoked(
+  ctx: MutationCtx,
+  keyId: Id<"apiKeys">,
+  namespace: string | undefined,
+  now: number,
+  reason: string,
+): Promise<void> {
+  await ctx.db.patch(keyId, {
+    status: "revoked" as const,
+    revokedAt: now,
+    revocationReason: reason,
+    updatedAt: now,
+  });
+  await ctx.db.insert("apiKeyEvents", {
+    keyId,
+    namespace,
+    type: "revoked",
+    reason,
+  });
+}

package/src/shared.ts

@@ -0,0 +1,18 @@
+import { v } from "convex/values";
+
+/**
+ * Stored status of an API key.
+ *
+ * Note: "expired" and "idle_timeout" are computed at read time from
+ * `expiresAt` / `lastUsedAt + maxIdleMs`, not stored directly.
+ */
+export const apiKeyStatusValidator = v.union(
+  v.literal("active"),
+  v.literal("revoked"),
+);
+
+export const permissionsValidator = v.record(v.string(), v.array(v.string()));
+
+export const metadataValidator = v.record(v.string(), v.any());
+
+export type ApiKeyStatus = "active" | "revoked";

package/src/test.ts

@@ -0,0 +1,18 @@
+/// <reference types="vite/client" />
+import type { TestConvex } from "convex-test";
+import type { GenericSchema, SchemaDefinition } from "convex/server";
+import schema from "./component/schema.js";
+const modules = import.meta.glob("./component/**/*.ts");
+
+/**
+ * Register the component with the test convex instance.
+ * @param t - The test convex instance, e.g. from calling `convexTest`.
+ * @param name - The name of the component, as registered in convex.config.ts.
+ */
+export function register(
+  t: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
+  name: string = "apiKeys",
+) {
+  t.registerComponent(name, schema, modules);
+}
+export default { register, schema, modules };