@gaganref/convex-api-keys 0.1.0

package/src/client/options.ts

@@ -0,0 +1,146 @@
+import { optionsError } from "./errors.js";
+import type { ApiKeysTypeOptions } from "./types.js";
+
+/**
+ * Initialization options for the API keys client.
+ *
+ * Type-level concerns (namespace shape, metadata shape, permissions shape,
+ * requireName) are passed via the generic parameter of `ApiKeys<TOptions>`.
+ */
+export type ApiKeysOptions<
+  TOptions extends ApiKeysTypeOptions = Record<never, never>,
+> = {
+  /**
+   * Default permissions applied when create args do not include permissions.
+   *
+   * Typed against the `permissions` field of `TOptions` when provided.
+   * This is a convenience default — not a runtime allowlist validator.
+   */
+  permissionDefaults?: TOptions extends {
+    permissions: infer P extends Record<string, string[]>;
+  }
+    ? { [K in keyof P]?: P[K] }
+    : Record<string, string[]>;
+  /**
+   * Default key behavior applied when operation-level values are omitted.
+   */
+  keyDefaults?: {
+    /**
+     * Token prefix used when creating keys.
+     *
+     * @default "ak_"
+     */
+    prefix?: string;
+    /**
+     * Default absolute expiration in milliseconds.
+     *
+     * Set `null` for no expiration.
+     *
+     * @default null
+     */
+    ttlMs?: number | null;
+    /**
+     * Default idle timeout in milliseconds.
+     *
+     * Set `null` to disable idle expiration.
+     *
+     * @default null
+     */
+    idleTimeoutMs?: number | null;
+  };
+  /**
+   * Minimum log level for console output.
+   *
+   * - `"debug"` — logs all operations including successes
+   * - `"warn"` — logs warnings and errors only (default)
+   * - `"error"` — logs infrastructure failures only
+   * - `"none"` — disables all logging
+   *
+   * @default "warn"
+   */
+  logLevel?: "debug" | "warn" | "error" | "none";
+};
+
+/**
+ * Fully validated options shape used by runtime internals.
+ */
+export type NormalizedApiKeysOptions = {
+  permissionDefaults: Record<string, string[]> | undefined;
+  keyDefaults: {
+    prefix: string;
+    keyLengthBytes: number;
+    ttlMs: number | null;
+    idleTimeoutMs: number | null;
+  };
+  logLevel: "debug" | "warn" | "error" | "none";
+};
+
+const KEY_DEFAULTS = {
+  prefix: "ak_",
+  keyLengthBytes: 32,
+  ttlMs: null as number | null,
+  idleTimeoutMs: null as number | null,
+};
+
+const LOG_LEVELS = ["debug", "warn", "error", "none"] as const;
+
+/**
+ * Normalize and validate API keys options.
+ *
+ * @throws {ApiKeysClientError} If any option value is invalid.
+ */
+export function normalizeApiKeysOptions(
+  options: ApiKeysOptions<ApiKeysTypeOptions>,
+): NormalizedApiKeysOptions {
+  const keyDefaults = {
+    prefix: options.keyDefaults?.prefix ?? KEY_DEFAULTS.prefix,
+    keyLengthBytes: KEY_DEFAULTS.keyLengthBytes,
+    ttlMs: options.keyDefaults?.ttlMs ?? KEY_DEFAULTS.ttlMs,
+    idleTimeoutMs:
+      options.keyDefaults?.idleTimeoutMs ?? KEY_DEFAULTS.idleTimeoutMs,
+  };
+
+  if (keyDefaults.prefix.length > 32) {
+    throw optionsError(`keyDefaults.prefix exceeds max allowed length (32)`);
+  }
+  if (keyDefaults.prefix.length === 0) {
+    throw optionsError("keyDefaults.prefix must not be empty");
+  }
+  assertNullableNonNegativeInteger(keyDefaults.ttlMs, "keyDefaults.ttlMs");
+  assertNullableNonNegativeInteger(
+    keyDefaults.idleTimeoutMs,
+    "keyDefaults.idleTimeoutMs",
+  );
+
+  const logLevel = normalizeLogLevel(options.logLevel);
+
+  return {
+    permissionDefaults: options.permissionDefaults as
+      | Record<string, string[]>
+      | undefined,
+    keyDefaults,
+    logLevel,
+  };
+}
+
+function normalizeLogLevel(
+  level: "debug" | "warn" | "error" | "none" | undefined,
+): "debug" | "warn" | "error" | "none" {
+  const resolved = level ?? "warn";
+  if (!LOG_LEVELS.includes(resolved)) {
+    throw optionsError(`logLevel must be one of: ${LOG_LEVELS.join(", ")}`);
+  }
+  return resolved;
+}
+
+export function assertNullableNonNegativeInteger(
+  value: number | null,
+  path: string,
+) {
+  if (value === null) {
+    return;
+  }
+  if (!Number.isInteger(value) || value < 0) {
+    throw optionsError(`${path} must be null or a non-negative integer`);
+  }
+}

package/src/client/types.ts

@@ -0,0 +1,313 @@
+import type {
+  FunctionArgs,
+  FunctionReference,
+  FunctionReturnType,
+  FunctionVisibility,
+} from "convex/server";
+import { v, type Infer } from "convex/values";
+import type { ComponentApi } from "../component/_generated/component.js";
+
+type CreateMutationResult = FunctionReturnType<ComponentApi["lib"]["create"]>;
+type ValidateQueryResult = FunctionReturnType<ComponentApi["lib"]["validate"]>;
+type RefreshMutationResult = FunctionReturnType<ComponentApi["lib"]["refresh"]>;
+type GetKeyQueryResult = FunctionReturnType<ComponentApi["lib"]["getKey"]>;
+type CleanupExpiredMutationResult = FunctionReturnType<
+  ComponentApi["cleanup"]["cleanupExpired"]
+>;
+
+/**
+ * Type-level options passed as the generic parameter to `ApiKeys`.
+ *
+ * All fields are TypeScript-only — they are phantom types cast over `v.any()`
+ * / `v.string()` storage. You are responsible for keeping your type param
+ * consistent with the data already stored in the database.
+ *
+ * - `namespace` — any `string` subtype (literals, template literals).
+ *   Presence implies namespace is required in `create` args.
+ * - `requireName` — set to `true` to require `name` in `create` args.
+ * - `metadata` — shape of the metadata object stored with each key.
+ * - `permissions` — shape of the permissions object; values must be `string[]`
+ *   subtypes (including literal arrays).
+ */
+export type ApiKeysTypeOptions = {
+  namespace?: string;
+  requireName?: true;
+  metadata?: Record<string, unknown>;
+  permissions?: Record<string, string[]>;
+};
+
+/**
+ * Freeform metadata stored with an API key.
+ */
+export type ApiKeyMetadata = Record<string, unknown>;
+
+/**
+ * Metadata attached to lifecycle events (invalidate, refresh, bulk invalidate).
+ */
+export type ApiKeyEventMetadata = Record<string, unknown>;
+
+// --- Internal arg shape helpers ---
+
+type NamespaceArg<TOptions extends ApiKeysTypeOptions> = TOptions extends {
+  namespace: infer N extends string;
+}
+  ? { namespace: N }
+  : { namespace?: string };
+
+type NamespaceFilterArg<TOptions extends ApiKeysTypeOptions> =
+  TOptions extends { namespace: infer N extends string }
+    ? { namespace?: N }
+    : object;
+
+type NameArg<TOptions extends ApiKeysTypeOptions> = TOptions extends {
+  requireName: true;
+}
+  ? { name: string }
+  : { name?: string };
+
+type PermissionsInputArg<TOptions extends ApiKeysTypeOptions> =
+  TOptions extends { permissions: infer P extends Record<string, string[]> }
+    ? { permissions?: { [K in keyof P]?: P[K] } }
+    : { permissions?: Record<string, string[]> };
+
+// --- Internal result shape helpers ---
+
+type NamespaceOutput<TOptions extends ApiKeysTypeOptions> = TOptions extends {
+  namespace: infer N extends string;
+}
+  ? N | undefined
+  : string | undefined;
+
+type MetadataOutput<TOptions extends ApiKeysTypeOptions> = TOptions extends {
+  metadata: infer M extends Record<string, unknown>;
+}
+  ? M | undefined
+  : Record<string, unknown> | undefined;
+
+type PermissionsOutput<TOptions extends ApiKeysTypeOptions> = TOptions extends {
+  permissions: infer P extends Record<string, string[]>;
+}
+  ? P | undefined
+  : Record<string, string[]> | undefined;
+
+// --- Public types ---
+
+export type ApiKeyId = CreateMutationResult["keyId"];
+
+/**
+ * Plaintext API key token.
+ *
+ * Tokens are only available at creation/refresh time.
+ */
+export type ApiKeyToken = string;
+
+export type CreateArgs<
+  TOptions extends ApiKeysTypeOptions = Record<never, never>,
+> = NamespaceArg<TOptions> &
+  NameArg<TOptions> &
+  PermissionsInputArg<TOptions> & {
+    metadata?: TOptions extends {
+      metadata: infer M extends Record<string, unknown>;
+    }
+      ? M
+      : ApiKeyMetadata;
+    prefix?: string;
+    ttlMs?: number | null;
+    idleTimeoutMs?: number | null;
+  };
+
+export type CreateResult = {
+  keyId: ApiKeyId;
+  token: ApiKeyToken;
+  tokenPrefix: string;
+  tokenLast4: string;
+  createdAt: CreateMutationResult["createdAt"];
+  expiresAt?: number;
+};
+
+export type ValidateArgs = {
+  token: ApiKeyToken;
+};
+
+export type TouchArgs = {
+  keyId: ApiKeyId;
+};
+
+export type TouchResult = FunctionReturnType<ComponentApi["lib"]["touch"]>;
+
+export type PaginationOptions = {
+  numItems: number;
+  cursor: string | null;
+};
+
+export type ListKeysArgs<
+  TOptions extends ApiKeysTypeOptions = Record<never, never>,
+> = {
+  paginationOpts: PaginationOptions;
+  status?: "active" | "revoked";
+  order?: "asc" | "desc";
+} & NamespaceFilterArg<TOptions>;
+
+export type ListKeysResult = FunctionReturnType<
+  ComponentApi["lib"]["listKeys"]
+>;
+
+export type ListEventsArgs<
+  TOptions extends ApiKeysTypeOptions = Record<never, never>,
+> = {
+  paginationOpts: PaginationOptions;
+  order?: "asc" | "desc";
+} & NamespaceFilterArg<TOptions>;
+
+export type ListEventsResult = FunctionReturnType<
+  ComponentApi["lib"]["listEvents"]
+>;
+
+export type ListKeyEventsArgs = {
+  keyId: ApiKeyId;
+  paginationOpts: PaginationOptions;
+  order?: "asc" | "desc";
+};
+
+export type ListKeyEventsResult = FunctionReturnType<
+  ComponentApi["lib"]["listKeyEvents"]
+>;
+
+export type GetKeyArgs = {
+  keyId: ApiKeyId;
+};
+
+export type GetKeyResult = GetKeyQueryResult;
+
+export type InvalidateArgs = {
+  keyId: ApiKeyId;
+  reason?: string;
+  metadata?: ApiKeyEventMetadata;
+};
+
+export type InvalidateResult = FunctionReturnType<
+  ComponentApi["lib"]["invalidate"]
+>;
+
+export type InvalidateAllArgs<
+  TOptions extends ApiKeysTypeOptions = Record<never, never>,
+> = {
+  before?: number;
+  after?: number;
+  reason?: string;
+  metadata?: ApiKeyEventMetadata;
+  pageSize?: number;
+} & NamespaceFilterArg<TOptions>;
+
+export type InvalidateAllResult = {
+  processed: number;
+  revoked: number;
+  pages: number;
+};
+
+export type InvalidateAllPageResult = FunctionReturnType<
+  ComponentApi["lib"]["invalidateAll"]
+>;
+
+export const onInvalidateHookPayloadValidator = v.union(
+  v.object({
+    trigger: v.literal("invalidate"),
+    at: v.number(),
+    keyId: v.string(),
+    reason: v.optional(v.string()),
+  }),
+  v.object({
+    trigger: v.literal("refresh"),
+    at: v.number(),
+    keyId: v.string(),
+    replacementKeyId: v.string(),
+    reason: v.optional(v.string()),
+  }),
+  v.object({
+    trigger: v.literal("invalidateAll"),
+    at: v.number(),
+    namespace: v.optional(v.string()),
+    before: v.optional(v.number()),
+    after: v.optional(v.number()),
+    reason: v.optional(v.string()),
+    processed: v.number(),
+    revoked: v.number(),
+    pages: v.number(),
+  }),
+);
+
+export type OnInvalidateHookPayload = Infer<
+  typeof onInvalidateHookPayloadValidator
+>;
+
+export type UpdateArgs = {
+  keyId: ApiKeyId;
+  name?: string;
+  metadata?: ApiKeyMetadata;
+  /** Pass `null` to remove the expiry entirely. */
+  expiresAt?: number | null;
+  /** Pass `null` to remove the idle timeout entirely. */
+  maxIdleMs?: number | null;
+};
+
+export type UpdateResult = FunctionReturnType<ComponentApi["lib"]["update"]>;
+
+export type CleanupExpiredArgs = {
+  /**
+   * How long to retain revoked keys before hard-deleting them and their
+   * audit events. Must be a positive finite number.
+   *
+   * @default 30 days
+   */
+  retentionMs?: number;
+};
+
+export type CleanupExpiredResult = CleanupExpiredMutationResult;
+
+export type RefreshArgs = {
+  keyId: ApiKeyId;
+  /** Override the token prefix for the new key. Falls back to `keyDefaults.prefix`. */
+  prefix?: string;
+  reason?: string;
+  metadata?: ApiKeyEventMetadata;
+};
+
+type RefreshMutationSuccess = Extract<RefreshMutationResult, { ok: true }>;
+type RefreshMutationFailure = Extract<RefreshMutationResult, { ok: false }>;
+
+export type RefreshResult =
+  | (RefreshMutationSuccess & {
+      token: ApiKeyToken;
+      tokenPrefix: string;
+      tokenLast4: string;
+    })
+  | RefreshMutationFailure;
+
+type ValidateSuccessBase = Extract<ValidateQueryResult, { ok: true }>;
+type ValidateFailure = Extract<ValidateQueryResult, { ok: false }>;
+
+export type ValidateResult<
+  TOptions extends ApiKeysTypeOptions = Record<never, never>,
+> =
+  | (Omit<ValidateSuccessBase, "permissions" | "namespace" | "metadata"> & {
+      namespace: NamespaceOutput<TOptions>;
+      permissions: PermissionsOutput<TOptions>;
+      metadata: MetadataOutput<TOptions>;
+    })
+  | ValidateFailure;
+
+export type RunMutationCtx = {
+  runMutation: <
+    Mutation extends FunctionReference<"mutation", FunctionVisibility>,
+  >(
+    mutation: Mutation,
+    args: FunctionArgs<Mutation>,
+  ) => Promise<FunctionReturnType<Mutation>>;
+};
+
+export type RunQueryCtx = {
+  runQuery: <Query extends FunctionReference<"query", "internal">>(
+    query: Query,
+    args: FunctionArgs<Query>,
+  ) => Promise<FunctionReturnType<Query>>;
+};