@gaganref/convex-api-keys 0.1.0

package/src/client/__tests__/errors.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, test } from "vitest";
+import { ApiKeys, ApiKeysClientError, isApiKeysClientError } from "../index.js";
+import { normalizeApiKeysOptions } from "../options.js";
+import { components, initConvexTest } from "./setup.test.js";
+import type { RunQueryCtx } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// error contracts
+// ---------------------------------------------------------------------------
+
+describe("error contracts", () => {
+  test("TOKEN_REQUIRED is an ApiKeysClientError", async () => {
+    const client = new ApiKeys(components.apiKeys, { logLevel: "none" });
+    const ctx: RunQueryCtx = {
+      runQuery: async () => {
+        throw new Error("should not be called");
+      },
+    };
+
+    await expect(client.validate(ctx, { token: "  " })).rejects.toSatisfy(
+      (e: unknown) => isApiKeysClientError(e) && e.code === "TOKEN_REQUIRED",
+    );
+  });
+
+  test("OPERATION_FAILED wraps infrastructure errors with cause", async () => {
+    const client = new ApiKeys(components.apiKeys, { logLevel: "none" });
+    const ctx: RunQueryCtx = {
+      runQuery: async () => {
+        throw new Error("simulated Convex failure");
+      },
+    };
+
+    const error = await client
+      .validate(ctx, { token: "ak_sometoken" })
+      .catch((e) => e);
+    expect(isApiKeysClientError(error)).toBe(true);
+    if (isApiKeysClientError(error)) {
+      expect(error.code).toBe("OPERATION_FAILED");
+      expect(error.cause).toBeInstanceOf(Error);
+    }
+  });
+
+  test("ok:false auth decisions do not throw — they return", async () => {
+    const t = initConvexTest();
+    const client = new ApiKeys(components.apiKeys, { logLevel: "none" });
+    const ctx: RunQueryCtx = { runQuery: (q, a) => t.query(q, a) };
+
+    const result = await client.validate(ctx, { token: "ak_unknown_token" });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.reason).toBe("not_found");
+    }
+  });
+
+  test("infrastructure failure throws ApiKeysClientError", async () => {
+    const client = new ApiKeys(components.apiKeys, { logLevel: "none" });
+    const ctx: RunQueryCtx = {
+      runQuery: async () => {
+        throw new Error("db down");
+      },
+    };
+
+    await expect(
+      client.validate(ctx, { token: "ak_sometoken" }),
+    ).rejects.toBeInstanceOf(ApiKeysClientError);
+  });
+
+  test("INVALID_OPTIONS thrown at init time for bad config", () => {
+    expect(
+      () =>
+        new ApiKeys(components.apiKeys, {
+          keyDefaults: { prefix: "" },
+        }),
+    ).toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// option normalization
+// ---------------------------------------------------------------------------
+
+describe("option normalization", () => {
+  test("normalizes defaults", () => {
+    const normalized = normalizeApiKeysOptions({});
+
+    expect(normalized.keyDefaults.prefix).toBe("ak_");
+    expect(normalized.keyDefaults.keyLengthBytes).toBe(32);
+    expect(normalized.keyDefaults.ttlMs).toBe(null);
+    expect(normalized.logLevel).toBe("warn");
+    expect(normalized.permissionDefaults).toBeUndefined();
+  });
+
+  test("normalizes logLevel option", () => {
+    const normalized = normalizeApiKeysOptions({ logLevel: "debug" });
+    expect(normalized.logLevel).toBe("debug");
+  });
+
+  test("normalizes permissionDefaults", () => {
+    const normalized = normalizeApiKeysOptions({
+      permissionDefaults: { beacon: ["events:read"] },
+    });
+    expect(normalized.permissionDefaults).toEqual({
+      beacon: ["events:read"],
+    });
+  });
+
+  test("throws for empty prefix", () => {
+    expect(() =>
+      normalizeApiKeysOptions({ keyDefaults: { prefix: "" } }),
+    ).toThrow(/must not be empty/);
+  });
+
+  test("throws for prefix exceeding max length", () => {
+    expect(() =>
+      normalizeApiKeysOptions({ keyDefaults: { prefix: "a".repeat(33) } }),
+    ).toThrow(/max allowed length/);
+  });
+
+  test("throws typed INVALID_OPTIONS for bad initialization", () => {
+    try {
+      new ApiKeys(components.apiKeys, {
+        keyDefaults: { prefix: "" },
+      });
+      throw new Error("expected constructor to throw");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ApiKeysClientError);
+      expect(isApiKeysClientError(error)).toBe(true);
+      if (isApiKeysClientError(error)) {
+        expect(error.code).toBe("INVALID_OPTIONS");
+      }
+    }
+  });
+});

package/src/client/__tests__/hooks.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, test, vi } from "vitest";
+import type { FunctionReference } from "convex/server";
+import { ApiKeys } from "../index.js";
+import { components, initConvexTest } from "./setup.test.js";
+import type { OnInvalidateHookPayload } from "../types.js";
+import type { RunMutationCtx, RunQueryCtx } from "../types.js";
+
+describe("hooks", () => {
+  test("runs onInvalidate hook after invalidate and refresh", async () => {
+    const t = initConvexTest();
+    const hookRef = {} as unknown as FunctionReference<
+      "mutation",
+      "internal",
+      { event: OnInvalidateHookPayload },
+      null
+    >;
+    const hookCalls: Array<OnInvalidateHookPayload> = [];
+
+    const client = new ApiKeys<{ namespace: string }>(
+      components.apiKeys,
+      {},
+    ).withHooks({ onInvalidate: hookRef });
+
+    const mutationCtx: RunMutationCtx = {
+      runMutation: (mutation, args) => {
+        if (mutation === hookRef) {
+          hookCalls.push(args.event);
+          return Promise.resolve(null) as never;
+        }
+        return t.mutation(mutation, args);
+      },
+    };
+
+    const created = await client.create(mutationCtx, {
+      namespace: "team_alpha",
+      name: "hook target",
+    });
+
+    await client.invalidate(mutationCtx, {
+      keyId: created.keyId,
+      reason: "manual",
+    });
+
+    const created2 = await client.create(mutationCtx, {
+      namespace: "team_alpha",
+      name: "hook rotate",
+    });
+    await client.refresh(mutationCtx, {
+      keyId: created2.keyId,
+      reason: "rotate",
+    });
+
+    expect(hookCalls.some((call) => call.trigger === "invalidate")).toBe(true);
+    expect(hookCalls.some((call) => call.trigger === "refresh")).toBe(true);
+  });
+
+  test("client without onInvalidate does not fire hooks", async () => {
+    const t = initConvexTest();
+    const hookRef = {} as unknown as FunctionReference<
+      "mutation",
+      "internal",
+      { event: OnInvalidateHookPayload },
+      null
+    >;
+    const hookCalls: Array<OnInvalidateHookPayload> = [];
+
+    const baseClient = new ApiKeys<{ namespace: string }>(
+      components.apiKeys,
+      {},
+    );
+    const hookedClient = new ApiKeys<{ namespace: string }>(
+      components.apiKeys,
+      {},
+    ).withHooks({ onInvalidate: hookRef });
+
+    const mutationCtx: RunMutationCtx = {
+      runMutation: (mutation, args) => {
+        if (mutation === hookRef) {
+          hookCalls.push(args.event);
+          return Promise.resolve(null) as never;
+        }
+        return t.mutation(mutation, args);
+      },
+    };
+
+    const createdByBase = await baseClient.create(mutationCtx, {
+      namespace: "team_alpha",
+      name: "base client key",
+    });
+    await baseClient.invalidate(mutationCtx, {
+      keyId: createdByBase.keyId,
+      reason: "base",
+    });
+    expect(hookCalls).toHaveLength(0);
+
+    const createdByHooked = await hookedClient.create(mutationCtx, {
+      namespace: "team_alpha",
+      name: "hooked client key",
+    });
+    await hookedClient.invalidate(mutationCtx, {
+      keyId: createdByHooked.keyId,
+      reason: "hooked",
+    });
+    expect(hookCalls.some((call) => call.trigger === "invalidate")).toBe(true);
+  });
+
+  test("swallows onInvalidate hook failures", async () => {
+    const t = initConvexTest();
+    const hookRef = {} as unknown as FunctionReference<
+      "mutation",
+      "internal",
+      { event: OnInvalidateHookPayload },
+      null
+    >;
+
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const client = new ApiKeys<{ namespace: string }>(
+      components.apiKeys,
+      {},
+    ).withHooks({ onInvalidate: hookRef });
+
+    const mutationCtx: RunMutationCtx = {
+      runMutation: (mutation, args) => {
+        if (mutation === hookRef) {
+          throw new Error("hook boom");
+        }
+        return t.mutation(mutation, args);
+      },
+    };
+    const queryCtx: RunQueryCtx = {
+      runQuery: (query, args) => t.query(query, args),
+    };
+
+    const created = await client.create(mutationCtx, {
+      namespace: "team_alpha",
+      name: "hook failure",
+    });
+    const result = await client.invalidate(mutationCtx, {
+      keyId: created.keyId,
+      reason: "manual",
+    });
+
+    expect(result.ok).toBe(true);
+    expect(warnSpy).toHaveBeenCalledWith("[api-keys:system]", {
+      message: "onInvalidate hook failed",
+      error: expect.any(String),
+    });
+    warnSpy.mockRestore();
+
+    const validate = await client.validate(queryCtx, { token: created.token });
+    expect(validate).toEqual({ ok: false, reason: "revoked" });
+  });
+});