@robelest/convex-auth 0.0.2 → 0.0.3-preview

package/src/server/convex-auth.ts

@@ -6,11 +6,24 @@
  * ```ts
  * // convex/auth.ts
  * import { Auth, Portal } from "@robelest/convex-auth/component";
- * import github from "@auth/core/providers/github";
+ * import google from "@auth/core/providers/google";
  * import { components } from "./_generated/api";
  *
  * export const auth = new Auth(components.auth, {
- *   providers: [github],
+ *   providers: [google],
+ *   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 }),
+ *       });
+ *     },
+ *   },
  * });
  * export const { signIn, signOut, store } = auth;
  * export const { portalQuery, portalMutation, portalInternal } = Portal(auth);
@@ -23,27 +36,35 @@ import {
   queryGeneric,
   mutationGeneric,
   internalMutationGeneric,
+  httpActionGeneric,
 } from "convex/server";
 import type { HttpRouter } from "convex/server";
 import { v } from "convex/values";
 import type { ComponentApi as AuthComponentApi } from "../component/_generated/component.js";
 import { Auth as AuthFactory } from "./implementation/index.js";
-import type { ConvexAuthConfig } from "./types.js";
+import type { ConvexAuthConfig, EmailTransport } from "./types.js";
 import { registerStaticRoutes } from "@convex-dev/self-hosting";
 import { portalMagicLinkEmail } from "./portal-email.js";
-import email from "../providers/email.js";
+import { defaultMagicLinkEmail } from "./email-templates.js";
+import emailProvider from "../providers/email.js";
+import { AUTH_VERSION } from "./version.js";
 
 // ============================================================================
 // Types
 // ============================================================================
 
 /**
- * Config for the ConvexAuth class. Extends the standard auth config.
+ * Config for the Auth class. Extends the standard auth config
+ * minus `component` (which is passed as the first constructor argument).
  *
- * Portal functionality (admin dashboard, magic link provider, static hosting)
- * is always available — no configuration flag needed. The portal UI works
- * when you export `portalQuery`, `portalMutation`, `portalInternal` from
- * your `convex/auth.ts` and upload the portal static files via CLI.
+ * When `email` is configured, the library auto-registers:
+ * - A magic link provider (`id: "email"`) for user-facing sign-in
+ * - A portal provider (`id: "portal"`) for admin dashboard sign-in
+ *
+ * Portal functionality is always available — no configuration flag
+ * needed. The portal UI works when you export `portalQuery`,
+ * `portalMutation`, `portalInternal` from your `convex/auth.ts`
+ * and upload the portal static files via CLI.
  */
 export type AuthClassConfig = Omit<ConvexAuthConfig, "component">;
 
@@ -84,7 +105,11 @@ async function requirePortalAdmin(
  *
  * ```ts
  * export const auth = new Auth(components.auth, {
- *   providers: [github, resend({ ... })],
+ *   providers: [google, password],
+ *   email: {
+ *     from: "My App <noreply@example.com>",
+ *     send: (ctx, params) => resend.sendEmail(ctx, params),
+ *   },
  * });
  * export const { signIn, signOut, store } = auth;
  * export const { portalQuery, portalMutation, portalInternal } = Portal(auth);
@@ -122,6 +147,8 @@ export class Auth {
   get passkey() { return this._auth.passkey; }
   /** TOTP helpers */
   get totp() { return this._auth.totp; }
+  /** API key helpers: `.create(ctx, ...)`, `.verify(ctx, ...)`, `.list(ctx, ...)`, `.revoke(ctx, ...)` */
+  get key() { return this._auth.key; }
 
   constructor(component: AuthComponentApi, config: AuthClassConfig) {
     this.component = component;
@@ -131,47 +158,63 @@ export class Auth {
       ? `${process.env.CONVEX_SITE_URL.replace(/\/$/, "")}/auth`
       : "/auth";
 
-    // Auto-register the `portal` email provider for magic link sign-in
+    const emailTransport = config.email;
     const providers = [...config.providers];
+
+    // Auto-register user-facing magic link provider when email is configured.
+    // Skipped if the user already registered their own provider with id "email".
+    const hasUserEmailProvider = providers.some(
+      (p) => typeof p === "object" && "id" in p && p.id === "email",
+    );
+    if (emailTransport && !hasUserEmailProvider) {
+      providers.push(
+        emailProvider({
+          id: "email",
+          maxAge: 60 * 60 * 24, // 24 hours
+          authorize: undefined, // Magic link — no OTP email check needed
+          async sendVerificationRequest({ identifier, url }, ctx) {
+            if (!ctx) {
+              throw new Error("Action context is required for email delivery");
+            }
+            const { host } = new URL(url);
+            await emailTransport.send(ctx, {
+              from: emailTransport.from,
+              to: identifier,
+              subject: `Sign in to ${host}`,
+              html: defaultMagicLinkEmail(url, host),
+            });
+          },
+        }),
+      );
+    }
+
+    // Auto-register portal admin magic link provider.
+    // Uses its own styled dark-theme email template.
     providers.push(
-      email({
+      emailProvider({
         id: "portal",
         maxAge: 60 * 60 * 24, // 24 hours
-        authorize: undefined, // Magic link — no email check needed
-        async sendVerificationRequest({ identifier, url, expires }) {
+        authorize: undefined, // Magic link — no OTP email check needed
+        async sendVerificationRequest({ identifier, url, expires }, ctx) {
+          if (!emailTransport) {
+            throw new Error(
+              "Auth email config is required for the portal. " +
+              "Configure email: { from, send } in your Auth constructor.",
+            );
+          }
+          if (!ctx) {
+            throw new Error("Action context is required for email delivery");
+          }
           const hours = Math.max(
             1,
             Math.floor((+expires - Date.now()) / (60 * 60 * 1000)),
           );
-          const html = portalMagicLinkEmail(url, hours);
-          const siteUrl = process.env.CONVEX_SITE_URL;
-          if (!siteUrl) {
-            throw new Error(
-              "CONVEX_SITE_URL is required to send portal magic link email",
-            );
-          }
-          const response = await fetch(`${siteUrl}/auth-email-dispatch`, {
-            method: "POST",
-            headers: {
-              "Content-Type": "application/json",
-              ...(process.env.AUTH_EMAIL_DISPATCH_SECRET
-                ? {
-                    "x-auth-email-dispatch-secret":
-                      process.env.AUTH_EMAIL_DISPATCH_SECRET,
-                  }
-                : {}),
-            },
-            body: JSON.stringify({
-              to: identifier,
-              subject: "Sign in to Convex Auth Portal",
-              html,
-            }),
+          await emailTransport.send(ctx, {
+            from: emailTransport.from,
+            to: identifier,
+            subject: "Sign in to Auth Portal",
+            html: portalMagicLinkEmail(url, hours),
           });
-          if (!response.ok) {
-            throw new Error(
-              `Could not send portal magic link email: ${response.status}`,
-            );
-          }
         },
       }),
     );
@@ -211,9 +254,36 @@ export class Auth {
     // Core auth routes (OAuth, JWKS, etc.)
     this._auth.addHttpRoutes(http);
 
-    // Portal static file serving
     const prefix = opts?.pathPrefix ?? "/auth";
 
+    // Portal configuration endpoint — serves Convex URLs + version info.
+    // The portal SPA fetches this at startup to discover its Convex backend,
+    // which is critical for custom domain deployments where the hostname
+    // alone doesn't reveal the Convex cloud URL.
+    // Registered as an exact path match before the static file prefix catch-all.
+    http.route({
+      path: `${prefix}/.well-known/portal-config`,
+      method: "GET",
+      handler: httpActionGeneric(async () => {
+        return new Response(
+          JSON.stringify({
+            convexUrl: process.env.CONVEX_CLOUD_URL,
+            siteUrl: process.env.CONVEX_SITE_URL,
+            version: AUTH_VERSION,
+          }),
+          {
+            status: 200,
+            headers: {
+              "Content-Type": "application/json",
+              "Cache-Control":
+                "public, max-age=60, stale-while-revalidate=60",
+              "Access-Control-Allow-Origin": "*",
+            },
+          },
+        );
+      }),
+    });
+
     // Create a shim that maps the self-hosting ComponentApi shape
     // to the auth component's portalBridge functions
     const selfHostingShim = {
@@ -328,6 +398,20 @@ export function Portal(auth: Auth) {
             authComponent.portalBridge.getCurrentDeployment,
           );
 
+        // ---- API Keys (portal admin) ----
+        case "listKeys":
+          return await ctx.runQuery(authComponent.public.keyList);
+
+        case "getUserKeys":
+          return await ctx.runQuery(authComponent.public.keyListByUserId, {
+            userId: userId!,
+          });
+
+        case "getKey":
+          return await ctx.runQuery(authComponent.public.keyGetById, {
+            keyId: userId!, // userId param repurposed as keyId
+          });
+
         default:
           throw new Error(`Unknown portal query action: ${action}`);
       }
@@ -339,23 +423,35 @@ export function Portal(auth: Auth) {
       action: v.string(),
       sessionId: v.optional(v.string()),
       tokenHash: v.optional(v.string()),
+      // API key fields
+      keyId: v.optional(v.string()),
+      keyUserId: v.optional(v.string()),
+      keyName: v.optional(v.string()),
+      keyScopes: v.optional(
+        v.array(
+          v.object({
+            resource: v.string(),
+            actions: v.array(v.string()),
+          }),
+        ),
+      ),
+      keyRateLimit: v.optional(
+        v.object({
+          maxRequests: v.number(),
+          windowMs: v.number(),
+        }),
+      ),
+      keyExpiresAt: v.optional(v.number()),
     },
-    handler: async (
-      ctx: any,
-      {
-        action,
-        sessionId,
-        tokenHash,
-      }: { action: string; sessionId?: string; tokenHash?: string },
-    ) => {
+    handler: async (ctx: any, args: any) => {
       const currentUserId = await authHelper.user.require(ctx);
 
-      switch (action) {
+      switch (args.action) {
         case "acceptInvite": {
-          if (!tokenHash) throw new Error("tokenHash required");
+          if (!args.tokenHash) throw new Error("tokenHash required");
           const invite = await ctx.runQuery(
             authComponent.public.inviteGetByTokenHash,
-            { tokenHash },
+            { tokenHash: args.tokenHash },
           );
           if (!invite) throw new Error("Invalid invite token");
           if (invite.status !== "pending") {
@@ -374,13 +470,49 @@ export function Portal(auth: Auth) {
         case "revokeSession": {
           await requirePortalAdmin(ctx, authComponent, currentUserId);
           await ctx.runMutation(authComponent.public.sessionDelete, {
-            sessionId: sessionId!,
+            sessionId: args.sessionId!,
           });
           return;
         }
 
+        // ---- API Keys (portal admin) ----
+        case "createKey": {
+          await requirePortalAdmin(ctx, authComponent, currentUserId);
+          const result = await authHelper.key.create(ctx, {
+            userId: args.keyUserId!,
+            name: args.keyName!,
+            scopes: args.keyScopes ?? [],
+            rateLimit: args.keyRateLimit,
+            expiresAt: args.keyExpiresAt,
+          });
+          // Return the raw key — portal will show it once
+          return result;
+        }
+
+        case "revokeKey": {
+          await requirePortalAdmin(ctx, authComponent, currentUserId);
+          await authHelper.key.revoke(ctx, args.keyId!);
+          return;
+        }
+
+        case "deleteKey": {
+          await requirePortalAdmin(ctx, authComponent, currentUserId);
+          await authHelper.key.remove(ctx, args.keyId!);
+          return;
+        }
+
+        case "updateKey": {
+          await requirePortalAdmin(ctx, authComponent, currentUserId);
+          const data: Record<string, any> = {};
+          if (args.keyName) data.name = args.keyName;
+          if (args.keyScopes) data.scopes = args.keyScopes;
+          if (args.keyRateLimit) data.rateLimit = args.keyRateLimit;
+          await authHelper.key.update(ctx, args.keyId!, data);
+          return;
+        }
+
         default:
-          throw new Error(`Unknown portal mutation action: ${action}`);
+          throw new Error(`Unknown portal mutation action: ${args.action}`);
       }
     },
   });

package/src/server/email-templates.ts

@@ -0,0 +1,77 @@
+/**
+ * Default email templates generated by the Auth library.
+ *
+ * These are used when the library sends emails on behalf of the developer
+ * (magic links, portal admin sign-in). The developer provides the transport
+ * via `email.send`; the library provides the content.
+ *
+ * @module
+ */
+
+/**
+ * Default magic link email template.
+ *
+ * Clean, minimal design that works across email clients.
+ * Used by the auto-registered `email` provider when `email` is
+ * configured in the Auth constructor.
+ */
+export function defaultMagicLinkEmail(url: string, host: string): string {
+  const escapedHost = host.replace(/[&<>"']/g, (c) =>
+    ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]!,
+  );
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Sign in to ${escapedHost}</title>
+</head>
+<body style="margin:0;padding:0;background-color:#f9fafb;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',Arial,sans-serif;">
+  <table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="background-color:#f9fafb;padding:40px 16px;">
+    <tr>
+      <td align="center">
+        <table role="presentation" width="480" cellpadding="0" cellspacing="0" style="background-color:#ffffff;border:1px solid #e5e7eb;border-radius:8px;overflow:hidden;">
+          <tr>
+            <td style="padding:32px 32px 0 32px;text-align:center;">
+              <h1 style="margin:0 0 8px 0;font-size:20px;font-weight:600;color:#111827;line-height:1.3;">
+                Sign in to ${escapedHost}
+              </h1>
+            </td>
+          </tr>
+          <tr>
+            <td style="padding:24px 32px;">
+              <p style="margin:0 0 24px 0;font-size:15px;line-height:1.6;color:#4b5563;text-align:center;">
+                Click the button below to sign in. This link will expire shortly.
+              </p>
+              <table role="presentation" width="100%" cellpadding="0" cellspacing="0">
+                <tr>
+                  <td align="center" style="padding:0 0 24px 0;">
+                    <a href="${url}" target="_blank" style="display:inline-block;background-color:#111827;color:#ffffff;font-size:15px;font-weight:600;text-decoration:none;padding:12px 32px;border-radius:6px;line-height:1;">
+                      Sign in
+                    </a>
+                  </td>
+                </tr>
+              </table>
+              <p style="margin:0 0 12px 0;font-size:13px;line-height:1.6;color:#9ca3af;">
+                If the button doesn't work, copy and paste this URL into your browser:
+              </p>
+              <p style="margin:0;font-size:13px;line-height:1.5;color:#6b7280;word-break:break-all;">
+                ${url}
+              </p>
+            </td>
+          </tr>
+          <tr>
+            <td style="padding:20px 32px;border-top:1px solid #e5e7eb;">
+              <p style="margin:0;font-size:12px;line-height:1.5;color:#9ca3af;text-align:center;">
+                If you didn't request this email, you can safely ignore it.
+              </p>
+            </td>
+          </tr>
+        </table>
+      </td>
+    </tr>
+  </table>
+</body>
+</html>`;
+}

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,
+    },
+  };
+}