@robelest/convex-auth 0.0.2-preview.2 → 0.0.3-preview

package/src/server/implementation/apiKey.ts

@@ -0,0 +1,185 @@
+/**
+ * API Key crypto utilities.
+ *
+ * Uses `@oslojs/crypto` primitives for key generation and hashing:
+ * - SHA-256 for hashing keys (API keys have high entropy, no need for bcrypt)
+ * - Cryptographically secure random generation for key material
+ *
+ * @module
+ */
+
+import { sha256, generateRandomString } from "./utils.js";
+import type { KeyScope, ScopeChecker } from "../types.js";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const DEFAULT_KEY_PREFIX = "sk_live_";
+const KEY_RANDOM_LENGTH = 32;
+const KEY_RANDOM_ALPHABET =
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+
+/**
+ * How many characters of the full key to store as the visible prefix.
+ * Includes the prefix string (e.g. "sk_live_") plus a few random chars.
+ */
+const VISIBLE_PREFIX_EXTRA_CHARS = 4;
+
+// ============================================================================
+// Key generation
+// ============================================================================
+
+/**
+ * Generate a new API key.
+ *
+ * Returns the raw key (to be shown once to the user) and metadata for storage.
+ * The raw key is `{prefix}{32 random alphanumeric chars}`.
+ *
+ * @param prefix - Key prefix, defaults to "sk_live_"
+ * @returns `{ raw, hashedKey, displayPrefix }`
+ */
+export async function generateApiKey(prefix: string = DEFAULT_KEY_PREFIX): Promise<{
+  /** The full raw key — show to user once, never store. */
+  raw: string;
+  /** SHA-256 hex hash of the raw key — store this. */
+  hashedKey: string;
+  /** Truncated prefix for display (e.g. "sk_live_aBc1..."). */
+  displayPrefix: string;
+}> {
+  const randomPart = generateRandomString(KEY_RANDOM_LENGTH, KEY_RANDOM_ALPHABET);
+  const raw = `${prefix}${randomPart}`;
+  const hashedKey = await sha256(raw);
+  const displayPrefix = `${raw.substring(0, prefix.length + VISIBLE_PREFIX_EXTRA_CHARS)}...`;
+
+  return { raw, hashedKey, displayPrefix };
+}
+
+/**
+ * Hash a raw API key for lookup.
+ *
+ * Used during Bearer token verification to find the stored key record.
+ */
+export async function hashApiKey(rawKey: string): Promise<string> {
+  return sha256(rawKey);
+}
+
+// ============================================================================
+// Scope checker
+// ============================================================================
+
+/**
+ * Build a `ScopeChecker` from an array of `KeyScope` entries.
+ *
+ * The checker provides a `.can(resource, action)` method that returns `true`
+ * if any scope entry grants the requested permission.
+ *
+ * A wildcard action `"*"` grants all actions on that resource.
+ * A wildcard resource `"*"` grants the action on all resources.
+ */
+export function buildScopeChecker(scopes: KeyScope[]): ScopeChecker {
+  return {
+    scopes,
+    can(resource: string, action: string): boolean {
+      return scopes.some(
+        (scope) =>
+          (scope.resource === resource || scope.resource === "*") &&
+          (scope.actions.includes(action) || scope.actions.includes("*")),
+      );
+    },
+  };
+}
+
+/**
+ * Validate that requested scopes are a subset of the allowed scopes
+ * defined in the API key config.
+ *
+ * @param requested - Scopes the user wants on the new key.
+ * @param allowed - The scope definition from `apiKeys.scopes` config.
+ * @throws Error if any requested scope is not in the allowed set.
+ */
+export function validateScopes(
+  requested: KeyScope[],
+  allowed: Record<string, string[]> | undefined,
+): void {
+  if (!allowed) {
+    // No scope restrictions configured — allow anything.
+    return;
+  }
+
+  for (const scope of requested) {
+    const allowedActions = allowed[scope.resource];
+    if (!allowedActions) {
+      throw new Error(
+        `Unknown resource "${scope.resource}" in API key scopes. ` +
+          `Allowed resources: ${Object.keys(allowed).join(", ")}`,
+      );
+    }
+    for (const action of scope.actions) {
+      if (action !== "*" && !allowedActions.includes(action)) {
+        throw new Error(
+          `Unknown action "${action}" for resource "${scope.resource}". ` +
+            `Allowed actions: ${allowedActions.join(", ")}`,
+        );
+      }
+    }
+  }
+}
+
+// ============================================================================
+// Per-key rate limiting (token-bucket)
+// ============================================================================
+
+/**
+ * Check whether a key is rate-limited based on its stored state.
+ *
+ * Uses the same token-bucket algorithm as sign-in rate limiting:
+ * tokens refill linearly over the configured window.
+ *
+ * @returns `{ limited: boolean; newState: { attemptsLeft, lastAttemptTime } }`
+ */
+export function checkKeyRateLimit(
+  rateLimit: { maxRequests: number; windowMs: number },
+  state: { attemptsLeft: number; lastAttemptTime: number } | undefined,
+): {
+  limited: boolean;
+  newState: { attemptsLeft: number; lastAttemptTime: number };
+} {
+  const now = Date.now();
+
+  if (!state) {
+    // First request — create initial state with one token consumed.
+    return {
+      limited: false,
+      newState: {
+        attemptsLeft: rateLimit.maxRequests - 1,
+        lastAttemptTime: now,
+      },
+    };
+  }
+
+  const elapsed = now - state.lastAttemptTime;
+  const refillRate = rateLimit.maxRequests / rateLimit.windowMs;
+  const refilled = Math.min(
+    rateLimit.maxRequests,
+    state.attemptsLeft + elapsed * refillRate,
+  );
+
+  if (refilled < 1) {
+    return {
+      limited: true,
+      newState: {
+        attemptsLeft: refilled,
+        lastAttemptTime: now,
+      },
+    };
+  }
+
+  return {
+    limited: false,
+    newState: {
+      attemptsLeft: refilled - 1,
+      lastAttemptTime: now,
+    },
+  };
+}

package/src/server/implementation/index.ts

@@ -44,6 +44,13 @@ import {
 } from "./mutations/index.js";
 import { signInImpl } from "./signIn.js";
 import { redirectAbsoluteUrl, setURLSearchParam } from "./redirects.js";
+import {
+  generateApiKey,
+  hashApiKey,
+  buildScopeChecker,
+  validateScopes,
+  checkKeyRateLimit,
+} from "./apiKey.js";
 import { getAuthorizationUrl } from "../oauth/authorizationUrl.js";
 import {
   defaultCookiesOptions,
@@ -446,12 +453,15 @@ export function Auth(config_: ConvexAuthConfig) {
        * Create a new invitation.
        *
        * @param data.groupId - Optional group to invite the user into.
-       * @param data.invitedByUserId - The user sending the invitation.
-       * @param data.email - The email address of the invitee.
+       * @param data.invitedByUserId - Optional user sending the invitation
+       *   (omit for CLI-generated invites).
+       * @param data.email - Optional email of the invitee (omit for
+       *   CLI-generated invite links where the email is unknown upfront).
        * @param data.tokenHash - Hashed token for secure acceptance.
        * @param data.role - Optional role to assign on acceptance.
        * @param data.status - Initial status (typically "pending").
-       * @param data.expiresTime - Timestamp when the invite expires.
+       * @param data.expiresTime - Optional expiration timestamp (omit for
+       *   single-use, non-expiring invites).
        * @param data.extend - Optional arbitrary JSON extension data.
        * @throws ConvexError with code `DUPLICATE_INVITE` if a pending invite
        * already exists for this email and scope.
@@ -461,12 +471,12 @@ export function Auth(config_: ConvexAuthConfig) {
         ctx: ComponentCtx,
         data: {
           groupId?: string;
-          invitedByUserId: string;
-          email: string;
+          invitedByUserId?: string;
+          email?: string;
           tokenHash: string;
           role?: string;
           status: "pending" | "accepted" | "revoked" | "expired";
-          expiresTime: number;
+          expiresTime?: number;
           extend?: Record<string, unknown>;
         },
       ): Promise<string> => {
@@ -478,6 +488,12 @@ export function Auth(config_: ConvexAuthConfig) {
       get: async (ctx: ComponentReadCtx, inviteId: string) => {
         return await ctx.runQuery(config.component.public.inviteGet, { inviteId });
       },
+      /**
+       * Retrieve an invite by its token hash. Returns `null` if not found.
+       */
+      getByTokenHash: async (ctx: ComponentReadCtx, tokenHash: string) => {
+        return await ctx.runQuery(config.component.public.inviteGetByTokenHash, { tokenHash });
+      },
       /**
        * List invites, optionally filtered by group and/or status.
        */
@@ -524,8 +540,11 @@ export function Auth(config_: ConvexAuthConfig) {
        * });
        * ```
        */
-      accept: async (ctx: ComponentCtx, inviteId: string) => {
-        await ctx.runMutation(config.component.public.inviteAccept, { inviteId });
+      accept: async (ctx: ComponentCtx, inviteId: string, acceptedByUserId?: string) => {
+        await ctx.runMutation(config.component.public.inviteAccept, {
+          inviteId,
+          ...(acceptedByUserId ? { acceptedByUserId } : {}),
+        });
       },
        /**
         * Revoke a pending invitation.
@@ -539,6 +558,271 @@ export function Auth(config_: ConvexAuthConfig) {
         await ctx.runMutation(config.component.public.inviteRevoke, { inviteId });
       },
     },
+    /**
+     * Manage passkey credentials for users.
+     *
+     * ```ts
+     * const passkeys = await auth.passkey.list(ctx, { userId });
+     * await auth.passkey.rename(ctx, passkeyId, "MacBook Touch ID");
+     * await auth.passkey.remove(ctx, passkeyId);
+     * ```
+     */
+    passkey: {
+      /**
+       * List all passkeys for a user.
+       *
+       * @param opts.userId - The user whose passkeys to list.
+       * @returns Array of passkey records with credentialId, name, deviceType,
+       * backedUp, createdAt, and lastUsedAt.
+       */
+      list: async (ctx: ComponentReadCtx, opts: { userId: string }) => {
+        return await ctx.runQuery(
+          config.component.public.passkeyListByUserId,
+          opts,
+        );
+      },
+      /**
+       * Rename a passkey (set a user-friendly display name).
+       *
+       * @param passkeyId - The passkey document ID.
+       * @param name - New display name (e.g. "MacBook Touch ID").
+       */
+      rename: async (ctx: ComponentCtx, passkeyId: string, name: string) => {
+        await ctx.runMutation(
+          config.component.public.passkeyUpdateMeta,
+          { passkeyId, data: { name } },
+        );
+      },
+      /**
+       * Delete a passkey credential.
+       *
+       * @param passkeyId - The passkey document ID to remove.
+       */
+      remove: async (ctx: ComponentCtx, passkeyId: string) => {
+        await ctx.runMutation(
+          config.component.public.passkeyDelete,
+          { passkeyId },
+        );
+      },
+    },
+    /**
+     * Manage TOTP two-factor authentication enrollments for users.
+     *
+     * ```ts
+     * const enrollments = await auth.totp.list(ctx, { userId });
+     * await auth.totp.remove(ctx, totpId);
+     * ```
+     */
+    totp: {
+      /**
+       * List all TOTP enrollments for a user.
+       *
+       * @param opts.userId - The user whose enrollments to list.
+       * @returns Array of TOTP enrollment records.
+       */
+      list: async (ctx: ComponentReadCtx, opts: { userId: string }) => {
+        return await ctx.runQuery(
+          config.component.public.totpListByUserId,
+          opts,
+        );
+      },
+      /**
+       * Delete a TOTP enrollment.
+       *
+       * @param totpId - The TOTP document ID to remove.
+       */
+      remove: async (ctx: ComponentCtx, totpId: string) => {
+        await ctx.runMutation(
+          config.component.public.totpDelete,
+          { totpId },
+        );
+      },
+    },
+    /**
+     * Manage API keys for programmatic access.
+     *
+     * Keys use SHA-256 hashing (via `@oslojs/crypto`) and support
+     * scoped resource:action permissions with optional per-key rate limiting.
+     *
+     * ```ts
+     * const { keyId, raw } = await auth.key.create(ctx, {
+     *   userId,
+     *   name: "CI Pipeline",
+     *   scopes: [{ resource: "users", actions: ["read", "list"] }],
+     * });
+     * // raw = "sk_live_abc123..." — show once, never stored
+     *
+     * const result = await auth.key.verify(ctx, rawKey);
+     * result.scopes.can("users", "read"); // true
+     * ```
+     */
+    key: {
+      /**
+       * Create a new API key. Returns the raw key **once** — it cannot
+       * be retrieved again after creation.
+       *
+       * @param opts.userId - The user this key belongs to.
+       * @param opts.name - Human-readable name (e.g. "CI Pipeline").
+       * @param opts.scopes - Resource:action permissions for this key.
+       * @param opts.rateLimit - Optional per-key rate limit override.
+       * @param opts.expiresAt - Optional expiration timestamp.
+       * @returns `{ keyId, raw }` where `raw` is the full key string.
+       */
+      create: async (
+        ctx: ComponentCtx,
+        opts: {
+          userId: string;
+          name: string;
+          scopes: import("../types.js").KeyScope[];
+          rateLimit?: { maxRequests: number; windowMs: number };
+          expiresAt?: number;
+        },
+      ): Promise<{ keyId: string; raw: string }> => {
+        const prefix = config.apiKeys?.prefix ?? "sk_live_";
+
+        // Validate scopes against config if defined
+        validateScopes(opts.scopes, config.apiKeys?.scopes);
+
+        const { raw, hashedKey, displayPrefix } = await generateApiKey(prefix);
+
+        const keyId = await ctx.runMutation(
+          config.component.public.keyInsert,
+          {
+            userId: opts.userId as any,
+            prefix: displayPrefix,
+            hashedKey,
+            name: opts.name,
+            scopes: opts.scopes,
+            rateLimit: opts.rateLimit ?? config.apiKeys?.defaultRateLimit,
+            expiresAt: opts.expiresAt,
+          },
+        );
+
+        return { keyId: keyId as string, raw };
+      },
+
+      /**
+       * Verify a raw API key string. Returns the userId and a scope checker
+       * if the key is valid, not revoked, not expired, and not rate-limited.
+       *
+       * Also updates `lastUsedAt` and rate limit state as a side effect.
+       *
+       * @throws Error if the key is invalid, revoked, expired, or rate-limited.
+       */
+      verify: async (
+        ctx: ComponentCtx,
+        rawKey: string,
+      ): Promise<{
+        userId: string;
+        keyId: string;
+        scopes: import("../types.js").ScopeChecker;
+      }> => {
+        const hashedKey = await hashApiKey(rawKey);
+
+        const key = await ctx.runQuery(
+          config.component.public.keyGetByHashedKey,
+          { hashedKey },
+        );
+        if (!key) {
+          throw new Error("Invalid API key");
+        }
+        if (key.revoked) {
+          throw new Error("API key has been revoked");
+        }
+        if (key.expiresAt && key.expiresAt < Date.now()) {
+          throw new Error("API key has expired");
+        }
+
+        // Check per-key rate limit
+        const patchData: Record<string, any> = { lastUsedAt: Date.now() };
+
+        if (key.rateLimit) {
+          const { limited, newState } = checkKeyRateLimit(
+            key.rateLimit,
+            key.rateLimitState ?? undefined,
+          );
+          if (limited) {
+            throw new Error("API key rate limit exceeded");
+          }
+          patchData.rateLimitState = newState;
+        }
+
+        // Update lastUsedAt (and rate limit state if applicable)
+        await ctx.runMutation(config.component.public.keyPatch, {
+          keyId: key._id,
+          data: patchData,
+        });
+
+        return {
+          userId: key.userId as string,
+          keyId: key._id as string,
+          scopes: buildScopeChecker(key.scopes),
+        };
+      },
+
+      /**
+       * List all API keys for a user.
+       * Never includes the raw key — only the display prefix.
+       */
+      list: async (ctx: ComponentReadCtx, opts: { userId: string }) => {
+        return await ctx.runQuery(
+          config.component.public.keyListByUserId,
+          { userId: opts.userId as any },
+        );
+      },
+
+      /**
+       * Get a single API key by its document ID.
+       * Returns `null` if not found.
+       */
+      get: async (ctx: ComponentReadCtx, keyId: string) => {
+        return await ctx.runQuery(
+          config.component.public.keyGetById,
+          { keyId: keyId as any },
+        );
+      },
+
+      /**
+       * Update an API key's metadata (name, scopes, rate limit).
+       */
+      update: async (
+        ctx: ComponentCtx,
+        keyId: string,
+        data: {
+          name?: string;
+          scopes?: import("../types.js").KeyScope[];
+          rateLimit?: { maxRequests: number; windowMs: number };
+        },
+      ) => {
+        if (data.scopes) {
+          validateScopes(data.scopes, config.apiKeys?.scopes);
+        }
+        await ctx.runMutation(config.component.public.keyPatch, {
+          keyId: keyId as any,
+          data,
+        });
+      },
+
+      /**
+       * Revoke an API key (soft delete). The key record is preserved
+       * for audit purposes but can no longer be used for authentication.
+       */
+      revoke: async (ctx: ComponentCtx, keyId: string) => {
+        await ctx.runMutation(config.component.public.keyPatch, {
+          keyId: keyId as any,
+          data: { revoked: true },
+        });
+      },
+
+      /**
+       * Hard delete an API key record.
+       */
+      remove: async (ctx: ComponentCtx, keyId: string) => {
+        await ctx.runMutation(config.component.public.keyDelete, {
+          keyId: keyId as any,
+        });
+      },
+    },
     /**
      * Add HTTP actions for JWT verification and OAuth sign-in.
      *
@@ -791,6 +1075,9 @@ export function Auth(config_: ConvexAuthConfig) {
         verifier?: string;
         tokens?: Tokens | null;
         started?: boolean;
+        options?: Record<string, any>;
+        totpRequired?: boolean;
+        totpSetup?: { uri: string; secret: string; totpId: string };
       }> => {
         if (args.calledBy !== undefined) {
           logWithLevel("INFO", `\`auth:signIn\` called by ${args.calledBy}`);
@@ -811,6 +1098,12 @@ export function Auth(config_: ConvexAuthConfig) {
             return { tokens: result.signedIn?.tokens ?? null };
           case "started":
             return { started: true };
+          case "passkeyOptions":
+            return { options: result.options, verifier: result.verifier };
+          case "totpRequired":
+            return { totpRequired: true, verifier: result.verifier };
+          case "totpSetup":
+            return { totpSetup: { uri: result.uri, secret: result.secret, totpId: result.totpId }, verifier: result.verifier };
           default: {
             const _typecheck: never = result;
             throw new Error(`Unexpected result from signIn, ${result as any}`);