@robelest/convex-auth 0.0.2 → 0.0.3-preview

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,
@@ -631,6 +638,191 @@ export function Auth(config_: ConvexAuthConfig) {
         );
       },
     },
+    /**
+     * 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.
      *

package/src/server/implementation/signIn.ts

@@ -170,20 +170,10 @@ async function handleEmailAndPhoneProvider(
     await provider.sendVerificationRequest(
       {
         ...verificationArgs,
-        provider: {
-          ...provider,
-          from:
-            // Simplifies demo configuration of Resend
-            provider.from === "Auth.js <no-reply@authjs.dev>" &&
-            provider.id === "resend"
-              ? "My App <onboarding@resend.dev>"
-              : provider.from,
-        },
-        request: new Request("http://localhost"), // TODO: Document
+        provider,
+        request: new Request("http://localhost"),
         theme: ctx.auth.config.theme,
       },
-      // @ts-expect-error Figure out typing for email providers so they can
-      // access ctx.
       ctx,
     );
   } else if (provider.type === "phone") {

package/src/server/index.ts

@@ -17,6 +17,20 @@ export type AuthCookies = {
   verifier: string | null;
 };
 
+/** A structured cookie ready to be set via any framework's cookie API. */
+export type AuthCookie = {
+  name: string;
+  value: string;
+  options: {
+    path: string;
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: "lax" | "strict" | "none";
+    maxAge?: number;
+    expires?: Date;
+  };
+};
+
 export type ServerOptions = {
   /** Convex deployment URL. */
   url: string;
@@ -27,8 +41,12 @@ export type ServerOptions = {
 };
 
 export type RefreshResult = {
-  response?: Response;
-  cookies?: string[];
+  /** Structured cookies to set on the response. */
+  cookies: AuthCookie[];
+  /** URL to redirect to (set after OAuth code exchange). */
+  redirect?: string;
+  /** JWT for SSR hydration, or `null` if not authenticated. */
+  token: string | null;
 };
 
 export function authCookieNames(host?: string) {
@@ -86,6 +104,57 @@ export function serializeAuthCookies(
   ];
 }
 
+/**
+ * Build structured cookie objects for any SSR framework.
+ *
+ * Use with SvelteKit's `event.cookies.set()`, TanStack Start's `setCookie()`,
+ * Next.js's `cookies().set()`, or any other framework cookie API.
+ */
+export function structuredAuthCookies(
+  cookies: AuthCookies,
+  host?: string,
+  config: AuthCookieConfig = { maxAge: null },
+): AuthCookie[] {
+  const names = authCookieNames(host);
+  const secure = !isLocalHost(host);
+  const base = {
+    path: "/" as const,
+    httpOnly: true as const,
+    secure,
+    sameSite: "lax" as const,
+  };
+  const maxAge = config.maxAge ?? undefined;
+  return [
+    {
+      name: names.token,
+      value: cookies.token ?? "",
+      options: {
+        ...base,
+        maxAge: cookies.token === null ? 0 : maxAge,
+        expires: cookies.token === null ? new Date(0) : undefined,
+      },
+    },
+    {
+      name: names.refreshToken,
+      value: cookies.refreshToken ?? "",
+      options: {
+        ...base,
+        maxAge: cookies.refreshToken === null ? 0 : maxAge,
+        expires: cookies.refreshToken === null ? new Date(0) : undefined,
+      },
+    },
+    {
+      name: names.verifier,
+      value: cookies.verifier ?? "",
+      options: {
+        ...base,
+        maxAge: cookies.verifier === null ? 0 : maxAge,
+        expires: cookies.verifier === null ? new Date(0) : undefined,
+      },
+    },
+  ];
+}
+
 export function shouldProxyAuthAction(pathname: string, apiRoute: string) {
   if (apiRoute.endsWith("/")) {
     return pathname === apiRoute || pathname === apiRoute.slice(0, -1);
@@ -348,21 +417,21 @@ export function server(options: ServerOptions) {
 
     async refresh(request: Request): Promise<RefreshResult> {
       const host = cookieHost(request);
+      const currentToken = parseRequestCookies(request).token;
 
+      // CORS request — clear all auth cookies.
       if (isCorsRequest(request)) {
         return {
-          cookies: serializeAuthCookies(
-            {
-              token: null,
-              refreshToken: null,
-              verifier: null,
-            },
+          cookies: structuredAuthCookies(
+            { token: null, refreshToken: null, verifier: null },
             host,
             cookieConfig,
           ),
+          token: null,
         };
       }
 
+      // OAuth code exchange — exchange code for tokens and redirect.
       const requestUrl = new URL(request.url);
       const code = requestUrl.searchParams.get("code");
       const shouldHandleCode =
@@ -392,47 +461,41 @@ export function server(options: ServerOptions) {
           if (result.tokens === undefined) {
             throw new Error("Invalid `auth:signIn` result for code exchange");
           }
-          const response = Response.redirect(redirectUrl.toString(), 302);
           return {
-            response: attachCookies(
-              response,
-              serializeAuthCookies(
-                {
-                  token: result.tokens?.token ?? null,
-                  refreshToken: result.tokens?.refreshToken ?? null,
-                  verifier: null,
-                },
-                host,
-                cookieConfig,
-              ),
+            cookies: structuredAuthCookies(
+              {
+                token: result.tokens?.token ?? null,
+                refreshToken: result.tokens?.refreshToken ?? null,
+                verifier: null,
+              },
+              host,
+              cookieConfig,
             ),
+            redirect: redirectUrl.toString(),
+            token: result.tokens?.token ?? null,
           };
         } catch (error) {
           console.error(error);
-          const response = Response.redirect(redirectUrl.toString(), 302);
           return {
-            response: attachCookies(
-              response,
-              serializeAuthCookies(
-                {
-                  token: null,
-                  refreshToken: null,
-                  verifier: null,
-                },
-                host,
-                cookieConfig,
-              ),
+            cookies: structuredAuthCookies(
+              { token: null, refreshToken: null, verifier: null },
+              host,
+              cookieConfig,
             ),
+            redirect: redirectUrl.toString(),
+            token: null,
           };
         }
       }
 
+      // Normal page load — refresh tokens if needed.
       const tokens = await refreshTokens(request);
       if (tokens === undefined) {
-        return {};
+        // No refresh needed — return current token for hydration.
+        return { cookies: [], token: currentToken };
       }
       return {
-        cookies: serializeAuthCookies(
+        cookies: structuredAuthCookies(
           {
             token: tokens?.token ?? null,
             refreshToken: tokens?.refreshToken ?? null,
@@ -441,6 +504,7 @@ export function server(options: ServerOptions) {
           host,
           cookieConfig,
         ),
+        token: tokens?.token ?? null,
       };
     },
   };

package/src/server/types.ts

@@ -5,7 +5,7 @@ import {
   OAuth2Config,
   OIDCConfig,
 } from "@auth/core/providers";
-import { Theme } from "@auth/core/types";
+import { Awaitable, Theme } from "@auth/core/types";
 import {
   AnyDataModel,
   FunctionReference,
@@ -82,6 +82,60 @@ export type ConvexAuthConfig = {
      */
     maxFailedAttempsPerHour?: number;
   };
+  /**
+   * API key configuration for programmatic access.
+   *
+   * Enables `auth.key.*` helpers for creating, verifying, and managing
+   * API keys with scoped permissions and optional per-key rate limiting.
+   */
+  apiKeys?: ApiKeyConfig;
+  /**
+   * Email transport configuration.
+   *
+   * Required for magic link authentication and the admin portal.
+   * The library generates email content (subject, styled HTML); you
+   * provide the delivery mechanism — Resend, SendGrid, SES, Postmark,
+   * or any other provider.
+   *
+   * When configured, a magic link email provider (`id: "email"`) is
+   * auto-registered — no need to add a separate Auth.js email provider
+   * to `providers`.
+   *
+   * Works seamlessly with the `@convex-dev/resend` Convex component:
+   *
+   * ```ts
+   * import { Resend } from "@convex-dev/resend";
+   *
+   * const resend = new Resend(components.resend, { testMode: false });
+   *
+   * const auth = new Auth(components.auth, {
+   *   providers: [google],
+   *   email: {
+   *     from: "My App <noreply@example.com>",
+   *     send: (ctx, params) => resend.sendEmail(ctx, params),
+   *   },
+   * });
+   * ```
+   *
+   * Or with any email API directly:
+   *
+   * ```ts
+   * email: {
+   *   from: "My App <noreply@example.com>",
+   *   send: async (_ctx, { from, to, subject, html }) => {
+   *     await fetch("https://api.resend.com/emails", {
+   *       method: "POST",
+   *       headers: {
+   *         Authorization: `Bearer ${process.env.AUTH_RESEND_KEY}`,
+   *         "Content-Type": "application/json",
+   *       },
+   *       body: JSON.stringify({ from, to, subject, html }),
+   *     });
+   *   },
+   * },
+   * ```
+   */
+  email?: EmailTransport;
   callbacks?: {
     /**
      * Control which URLs are allowed as a destination after OAuth sign-in
@@ -258,11 +312,30 @@ export type AuthProviderConfig =
 export interface EmailConfig<
   DataModel extends GenericDataModel = GenericDataModel,
 > extends AuthjsEmailConfig {
+  /**
+   * Send the verification token to the user.
+   *
+   * Overrides the Auth.js 1-arg signature to accept an optional
+   * Convex action context as the second argument. Library-native
+   * email providers use `ctx` to call `email.send(ctx, params)`.
+   */
+  sendVerificationRequest: (
+    params: {
+      identifier: string;
+      url: string;
+      expires: Date;
+      provider: AuthjsEmailConfig;
+      token: string;
+      theme: Theme;
+      request: Request;
+    },
+    ctx?: GenericActionCtx<AnyDataModel>,
+  ) => Awaitable<void>;
   /**
    * Before the token is verified, check other
    * provided parameters.
    *
-   * Used to make sure tha OTPs are accompanied
+   * Used to make sure that OTPs are accompanied
    * with the correct email address.
    */
   authorize?: (
@@ -524,6 +597,143 @@ export type AuthProviderMaterializedConfig =
   | PasskeyProviderConfig
   | TotpProviderConfig;
 
+// ============================================================================
+// Email transport types
+// ============================================================================
+
+/**
+ * Email delivery parameters passed to `EmailTransport.send`.
+ */
+export interface EmailMessage {
+  /** Sender address (from `email.from` in your Auth config). */
+  from: string;
+  /** Recipient email address. */
+  to: string;
+  /** Email subject line. */
+  subject: string;
+  /** HTML body content. */
+  html: string;
+}
+
+/**
+ * Email transport configuration for the Auth library.
+ *
+ * Provides a delivery mechanism for library-generated emails
+ * (magic links, portal admin sign-in). The library owns the
+ * email content; you provide the transport.
+ */
+export interface EmailTransport {
+  /** Sender address shown in the From field (e.g. "My App \<noreply@example.com\>"). */
+  from: string;
+  /**
+   * Deliver an email. Called by the library for magic links and portal emails.
+   *
+   * Receives the Convex action context as the first argument, enabling
+   * use with Convex components like `@convex-dev/resend`:
+   *
+   * ```ts
+   * send: (ctx, params) => resend.sendEmail(ctx, params)
+   * ```
+   *
+   * For plain HTTP email APIs, ignore the `ctx` parameter:
+   *
+   * ```ts
+   * send: async (_ctx, { from, to, subject, html }) => {
+   *   await fetch("https://api.resend.com/emails", { ... });
+   * }
+   * ```
+   */
+  send: (
+    ctx: GenericActionCtx<any>,
+    params: EmailMessage,
+  ) => Promise<void>;
+}
+
+// ============================================================================
+// API Key types
+// ============================================================================
+
+/**
+ * A single scope entry stored per API key.
+ * Uses a resource:action pattern for structured permissions.
+ *
+ * ```ts
+ * { resource: "users", actions: ["read", "list"] }
+ * ```
+ */
+export interface KeyScope {
+  resource: string;
+  actions: string[];
+}
+
+/**
+ * Result of scope verification. Provides a `.can()` helper
+ * for checking if a key has a specific permission.
+ *
+ * ```ts
+ * const result = await auth.key.verify(ctx, rawKey);
+ * if (result.scopes.can("users", "read")) {
+ *   // authorized
+ * }
+ * ```
+ */
+export interface ScopeChecker {
+  /** Check if the key has permission for a given resource:action. */
+  can(resource: string, action: string): boolean;
+  /** The raw scope entries from the key. */
+  scopes: KeyScope[];
+}
+
+/**
+ * Configuration for API key support on the Auth class.
+ *
+ * ```ts
+ * const auth = new Auth(components.auth, {
+ *   providers: [github],
+ *   apiKeys: {
+ *     scopes: {
+ *       users: ["read", "list", "create", "delete"],
+ *       messages: ["read", "write"],
+ *     },
+ *     defaultRateLimit: { maxRequests: 1000, windowMs: 3600000 },
+ *   },
+ * });
+ * ```
+ */
+export interface ApiKeyConfig {
+  /**
+   * Define the available resource:action scopes for your API keys.
+   * Keys can only be created with scopes that are a subset of these.
+   */
+  scopes?: Record<string, string[]>;
+  /**
+   * Default rate limit applied to new keys when not specified per-key.
+   * Uses a token-bucket algorithm.
+   */
+  defaultRateLimit?: { maxRequests: number; windowMs: number };
+  /**
+   * Key prefix. Defaults to `"sk_live_"`.
+   */
+  prefix?: string;
+}
+
+/**
+ * An API key record as returned by `auth.key.list()` and `auth.key.get()`.
+ * Never includes the raw key material — only the display prefix.
+ */
+export interface KeyRecord {
+  _id: string;
+  userId: string;
+  prefix: string;
+  name: string;
+  scopes: KeyScope[];
+  rateLimit?: { maxRequests: number; windowMs: number };
+  expiresAt?: number;
+  lastUsedAt?: number;
+  createdAt: number;
+  revoked: boolean;
+}
+
 /**
  * Component function references required by core auth runtime.
  */
@@ -582,6 +792,13 @@ export type AuthComponentApi = {
     inviteList: FunctionReference<"query", "internal">;
     inviteAccept: FunctionReference<"mutation", "internal">;
     inviteRevoke: FunctionReference<"mutation", "internal">;
+    keyInsert: FunctionReference<"mutation", "internal">;
+    keyGetByHashedKey: FunctionReference<"query", "internal">;
+    keyGetById: FunctionReference<"query", "internal">;
+    keyList: FunctionReference<"query", "internal">;
+    keyListByUserId: FunctionReference<"query", "internal">;
+    keyPatch: FunctionReference<"mutation", "internal">;
+    keyDelete: FunctionReference<"mutation", "internal">;
     passkeyInsert: FunctionReference<"mutation", "internal">;
     passkeyGetByCredentialId: FunctionReference<"query", "internal">;
     passkeyListByUserId: FunctionReference<"query", "internal">;

package/src/server/version.ts

@@ -0,0 +1,2 @@
+// Auto-generated by scripts/generate-version.js — do not edit.
+export const AUTH_VERSION = "0.0.3-preview";