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

package/src/server/errors.ts

@@ -0,0 +1,269 @@
+/**
+ * Structured error handling for Convex Auth.
+ *
+ * Every error thrown by the auth system uses `ConvexError` with a
+ * `{ code, message }` payload so clients can distinguish error types
+ * and display user-friendly messages.
+ *
+ * @module
+ */
+
+import { ConvexError } from "convex/values";
+
+// ============================================================================
+// Error code → default message map  (single source of truth)
+// ============================================================================
+
+/**
+ * Map of every auth error code to its default human-readable message.
+ *
+ * Use the keys as the `code` argument to {@link throwAuthError}.
+ * Clients can match on these codes for conditional error handling.
+ *
+ * @example
+ * ```ts
+ * throwAuthError("NOT_SIGNED_IN");
+ * // ConvexError { data: { code: "NOT_SIGNED_IN", message: "You must be signed in..." } }
+ * ```
+ */
+export const AUTH_ERRORS = {
+  // ---- Configuration ----
+  PROVIDER_NOT_CONFIGURED:
+    "This sign-in method is not available.",
+  EMAIL_CONFIG_REQUIRED:
+    "Email transport is not configured. Configure email in your Auth constructor.",
+  MISSING_ENV_VAR:
+    "A required server environment variable is missing.",
+  MISSING_ACTION_CONTEXT:
+    "Action context is required for this operation.",
+
+  // ---- Authentication ----
+  NOT_SIGNED_IN:
+    "You must be signed in to perform this action.",
+  INVALID_VERIFICATION_CODE:
+    "Invalid or expired verification code.",
+  INVALID_REFRESH_TOKEN:
+    "Your session has expired. Please sign in again.",
+  SIGN_IN_MISSING_PARAMS:
+    "Cannot sign in: missing provider, code, or refresh token.",
+  UNSUPPORTED_PROVIDER_TYPE:
+    "This provider type is not supported.",
+  INVALID_REDIRECT:
+    "Invalid redirect URL.",
+
+  // ---- Email / Phone ----
+  EMAIL_SEND_FAILED:
+    "Failed to send verification email. Please try again.",
+
+  // ---- Portal ----
+  PORTAL_NOT_AUTHORIZED:
+    "This email does not have portal admin access. Ask an admin for an invite link.",
+  PORTAL_UNKNOWN_ACTION:
+    "Unknown portal action.",
+  INVITE_TOKEN_REQUIRED:
+    "Invite token is required.",
+  INVALID_INVITE:
+    "Invalid or expired invite token.",
+  INVITE_ALREADY_USED:
+    "This invite has already been used.",
+  INVITE_EXPIRED:
+    "This invite has expired.",
+
+  // ---- API Keys ----
+  INVALID_API_KEY:
+    "Invalid API key.",
+  API_KEY_REVOKED:
+    "This API key has been revoked.",
+  API_KEY_EXPIRED:
+    "This API key has expired.",
+  API_KEY_RATE_LIMITED:
+    "API key rate limit exceeded. Please try again later.",
+  API_KEY_INVALID_SCOPE:
+    "Invalid scope requested for API key.",
+
+  // ---- OAuth ----
+  OAUTH_MISSING_PROVIDER:
+    "Missing OAuth provider ID.",
+  OAUTH_MISSING_VERIFIER:
+    "Missing sign-in verifier.",
+  OAUTH_INVALID_STATE:
+    "Invalid OAuth state. Please try signing in again.",
+  OAUTH_PROVIDER_ERROR:
+    "The sign-in provider returned an error.",
+  OAUTH_MISSING_ID_TOKEN:
+    "ID token claims are missing from the provider response.",
+  OAUTH_INVALID_PROFILE:
+    "The sign-in provider returned an invalid profile.",
+  OAUTH_UNSUPPORTED_AUTH_METHOD:
+    "Unsupported OAuth client authentication method.",
+  OAUTH_NO_USERINFO:
+    "No userinfo endpoint configured for this provider.",
+
+  // ---- Credentials ----
+  ACCOUNT_ALREADY_EXISTS:
+    "An account with these credentials already exists.",
+  ACCOUNT_NOT_FOUND:
+    "Account not found.",
+  INVALID_CREDENTIALS_PROVIDER:
+    "This provider does not support credential operations.",
+  MISSING_CRYPTO_FUNCTION:
+    "This provider is missing a required cryptographic function.",
+  USER_UPDATE_FAILED:
+    "Could not update the user record.",
+
+  // ---- Verifier ----
+  INVALID_VERIFIER:
+    "Invalid or expired verifier.",
+
+  // ---- Passkey ----
+  PASSKEY_MISSING_CONFIG:
+    "Passkey provider requires SITE_URL or explicit rpId configuration.",
+  PASSKEY_AUTH_REQUIRED:
+    "Sign in first, then add a passkey to your account.",
+  PASSKEY_MISSING_VERIFIER:
+    "Missing verifier for passkey operation.",
+  PASSKEY_INVALID_CLIENT_DATA:
+    "Invalid passkey client data.",
+  PASSKEY_INVALID_ORIGIN:
+    "Passkey origin does not match the expected value.",
+  PASSKEY_INVALID_CHALLENGE:
+    "Invalid or expired passkey challenge.",
+  PASSKEY_RP_MISMATCH:
+    "Relying party ID mismatch.",
+  PASSKEY_USER_PRESENCE:
+    "User presence flag not set.",
+  PASSKEY_USER_VERIFICATION:
+    "User verification required but not performed.",
+  PASSKEY_NO_CREDENTIAL:
+    "No credential in attestation.",
+  PASSKEY_UNSUPPORTED_ALGORITHM:
+    "Unsupported passkey algorithm.",
+  PASSKEY_INVALID_SIGNATURE:
+    "Invalid passkey signature.",
+  PASSKEY_UNKNOWN_CREDENTIAL:
+    "Unknown passkey credential.",
+  PASSKEY_COUNTER_ERROR:
+    "Authenticator counter did not increase — possible credential cloning detected.",
+  PASSKEY_MISSING_FLOW:
+    "Missing passkey flow parameter.",
+  PASSKEY_UNKNOWN_FLOW:
+    "Unknown passkey flow.",
+
+  // ---- TOTP ----
+  TOTP_AUTH_REQUIRED:
+    "Sign in first, then set up two-factor authentication.",
+  TOTP_MISSING_VERIFIER:
+    "Missing verifier for TOTP operation.",
+  TOTP_MISSING_CODE:
+    "Missing TOTP code.",
+  TOTP_MISSING_ID:
+    "Missing TOTP enrollment ID.",
+  TOTP_NOT_FOUND:
+    "TOTP enrollment not found.",
+  TOTP_ALREADY_VERIFIED:
+    "TOTP enrollment is already verified.",
+  TOTP_INVALID_CODE:
+    "Invalid TOTP code.",
+  TOTP_INVALID_VERIFIER:
+    "Invalid or expired TOTP verifier.",
+  TOTP_NO_ENROLLMENT:
+    "No verified TOTP enrollment found.",
+  TOTP_MISSING_FLOW:
+    "Missing TOTP flow parameter.",
+  TOTP_UNKNOWN_FLOW:
+    "Unknown TOTP flow.",
+
+  // ---- Internal (should never reach user) ----
+  INTERNAL_ERROR:
+    "An unexpected error occurred.",
+} as const satisfies Record<string, string>;
+
+/** Union of all recognized auth error code strings (keys of {@link AUTH_ERRORS}). */
+export type AuthErrorCode = keyof typeof AUTH_ERRORS;
+
+// ============================================================================
+// Error helpers
+// ============================================================================
+
+/**
+ * Throw a structured `ConvexError` with `{ code, message }`.
+ *
+ * @param code    Machine-readable error code from `AUTH_ERRORS`.
+ * @param message Optional override for the default human-readable message.
+ * @param context Optional extra fields merged into the error payload.
+ */
+export function throwAuthError(
+  code: AuthErrorCode,
+  message?: string,
+  context?: Record<string, unknown>,
+): never {
+  throw new ConvexError({
+    code,
+    message: message ?? AUTH_ERRORS[code],
+    ...context,
+  });
+}
+
+/**
+ * Type guard: check whether a caught value is a structured auth `ConvexError`.
+ *
+ * @param error - The caught value (typically from a `catch` block).
+ * @returns `true` when `error` is a `ConvexError` with `{ code, message }` data.
+ *
+ * @example
+ * ```ts
+ * try { await auth.signIn('email', { email }); }
+ * catch (e) {
+ *   if (isAuthError(e)) console.log(e.data.code); // "EMAIL_SEND_FAILED"
+ * }
+ * ```
+ */
+export function isAuthError(
+  error: unknown,
+): error is ConvexError<{ code: AuthErrorCode; message: string }> {
+  return (
+    error instanceof ConvexError &&
+    typeof error.data === "object" &&
+    error.data !== null &&
+    "code" in error.data &&
+    "message" in error.data
+  );
+}
+
+/**
+ * Extract `{ code, message }` from a caught error.
+ *
+ * Works for `ConvexError` (from Convex actions), plain `Error`
+ * instances, and structured auth errors. Returns `null` when the
+ * value is not an error object.
+ *
+ * @param error - The caught value to parse.
+ * @returns `{ code, message }` when extractable, or `null`.
+ *   When `code` is `null`, the error is not a structured auth error
+ *   but `message` still contains the error text.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await auth.signIn("email", { email });
+ * } catch (e) {
+ *   const err = parseAuthError(e);
+ *   if (err?.code === "EMAIL_SEND_FAILED") { ... }
+ * }
+ * ```
+ */
+export function parseAuthError(
+  error: unknown,
+): { code: AuthErrorCode; message: string } | { code: null; message: string } | null {
+  if (isAuthError(error)) {
+    const { code, message } = error.data as { code: AuthErrorCode; message: string };
+    return { code, message };
+  }
+  if (error instanceof ConvexError && typeof error.data === "string") {
+    return { code: null, message: error.data };
+  }
+  if (error instanceof Error) {
+    return { code: null, message: error.message };
+  }
+  return null;
+}

package/src/server/implementation/apiKey.ts

@@ -0,0 +1,186 @@
+/**
+ * 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";
+import { throwAuthError } from "../errors.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) {
+      throwAuthError(
+        "API_KEY_INVALID_SCOPE",
+        `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)) {
+        throwAuthError(
+          "API_KEY_INVALID_SCOPE",
+          `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,
+    },
+  };
+}