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

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,67 @@ 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;
+  /**
+   * Lifecycle callbacks for customizing sign-in behavior.
+   *
+   * Use `redirect` to control post-OAuth redirect URLs, and
+   * `createOrUpdateUser` or `afterUserCreatedOrUpdated` to
+   * customize account linking and user document creation.
+   */
   callbacks?: {
     /**
      * Control which URLs are allowed as a destination after OAuth sign-in
@@ -233,9 +294,11 @@ export type ConvexAuthConfig = {
 };
 
 /**
- * Same as Auth.js provider configs, but adds phone provider
- * for verification via SMS or another phone-number-connected messaging
- * service.
+ * Union of all supported auth provider config types.
+ *
+ * Includes Auth.js OAuth/OIDC providers, plus library-native providers:
+ * credentials, email, phone, passkey (WebAuthn), and TOTP (2FA).
+ * Each can be passed as a config object or a factory function.
  */
 export type AuthProviderConfig =
   | Exclude<
@@ -258,11 +321,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?: (
@@ -402,11 +484,15 @@ export interface TotpProviderConfig {
   };
 }
 
+/** Credentials identifying a provider account (e.g. email + hashed password). */
 export type AuthAccountCredentials = {
+  /** Provider-specific account identifier (e.g. email address). */
   id: string;
+  /** Optional secret (e.g. hashed password). */
   secret?: string;
 };
 
+/** Arguments for `auth.account.create()`. */
 export type AuthCreateAccountArgs = {
   provider: string;
   account: AuthAccountCredentials;
@@ -420,11 +506,13 @@ export type AuthCreateAccountArgs = {
   shouldLinkViaPhone?: boolean;
 };
 
+/** Arguments for `auth.account.get()`. */
 export type AuthRetrieveAccountArgs = {
   provider: string;
   account: AuthAccountCredentials;
 };
 
+/** Arguments for `auth.account.updateCredentials()`. */
 export type AuthUpdateAccountCredentialsArgs = {
   provider: string;
   account: {
@@ -433,21 +521,25 @@ export type AuthUpdateAccountCredentialsArgs = {
   };
 };
 
+/** Arguments for `auth.session.invalidate()`. */
 export type AuthInvalidateSessionsArgs = {
   userId: GenericId<"user">;
   except?: GenericId<"session">[];
 };
 
+/** Arguments for `auth.provider.signIn()`. */
 export type AuthProviderSignInArgs = {
   accountId?: GenericId<"account">;
   params?: Record<string, Value | undefined>;
 };
 
+/** Return type of `auth.provider.signIn()` — user and session IDs, or `null` on failure. */
 export type AuthProviderSignInResult = {
   userId: GenericId<"user">;
   sessionId: GenericId<"session">;
 } | null;
 
+/** Server-side auth helpers available on enriched action contexts. */
 export type AuthServerHelpers = {
   account: {
     create: (
@@ -524,8 +616,158 @@ 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 {
+  /** Document ID. */
+  _id: string;
+  /** Owner user ID. */
+  userId: string;
+  /** Display prefix (e.g. `"sk_live_abc1"`). Safe to show in UIs. */
+  prefix: string;
+  /** Human-readable name (e.g. "CI Pipeline"). */
+  name: string;
+  /** Resource:action permissions granted to this key. */
+  scopes: KeyScope[];
+  /** Per-key rate limit, if configured. */
+  rateLimit?: { maxRequests: number; windowMs: number };
+  /** Expiration timestamp (ms since epoch), or `undefined` for no expiry. */
+  expiresAt?: number;
+  /** Timestamp of last successful verification, or `undefined` if never used. */
+  lastUsedAt?: number;
+  /** Creation timestamp (ms since epoch). */
+  createdAt: number;
+  /** `true` when the key has been revoked (soft-deleted). */
+  revoked: boolean;
+}
+
 /**
  * Component function references required by core auth runtime.
+ *
+ * @internal Consumers should not depend on this shape — it may change
+ * between minor versions. Pass `components.auth` directly to the `Auth` constructor.
  */
 export type AuthComponentApi = {
   public: {
@@ -582,6 +824,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/utils.ts

@@ -1,7 +1,9 @@
+import { throwAuthError } from "./errors.js";
+
 export function requireEnv(name: string) {
   const value = process.env[name];
   if (value === undefined) {
-    throw new Error(`Missing environment variable \`${name}\``);
+    throwAuthError("MISSING_ENV_VAR", `Missing environment variable \`${name}\``, { variable: name });
   }
   return value;
 }

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.1";

package/dist/server/portal.d.ts

@@ -1,116 +0,0 @@
-import type { HttpRouter } from "convex/server";
-import type { ComponentApi as AuthComponentApi } from "../component/_generated/component.js";
-/**
- * Configure the Convex Auth Portal. Returns all the functions needed to
- * serve the portal admin UI, manage invite links, and query auth data.
- *
- * The portal dogfoods the same `Auth()` instance as your app. Portal admins
- * sign in via email magic link and are identified by accepted invites with
- * `role: "portalAdmin"`.
- *
- * ```ts filename="convex/portal.ts"
- * import { Portal } from "@robelest/convex-auth/component";
- * import { auth } from "./auth";
- * import { components } from "./_generated/api";
- *
- * export const {
- *   hosting, getCurrentDeployment,
- *   portalQuery, portalMutation,
- *   validateInvite, acceptInvite, createPortalInvite,
- *   portal,
- * } = Portal(components.auth, components.selfHosting, auth);
- * ```
- *
- * ## Setup
- *
- * 1. Configure an email provider in your `Auth()` config (e.g. Resend).
- * 2. Generate an admin invite link:
- *    `npx @robelest/convex-auth portal link [--prod]`
- * 3. Visit the link, enter your email, click the magic link, and you're in.
- *
- * The portal URL is auto-derived from `CONVEX_SITE_URL` (always set by Convex).
- * Override with `options.portalUrl` if you need a custom URL.
- */
-export declare function Portal(authComponent: AuthComponentApi, selfHostingComponent: any, auth: any, options?: {
-    portalUrl?: string;
-}): {
-    /**
-     * Combined internal mutation for self-hosting operations.
-     * Used by the CLI (`@robelest/convex-auth portal upload`) to
-     * upload static assets and manage deployments.
-     */
-    hosting: import("convex/server").RegisteredMutation<"internal", any, Promise<any>>;
-    getCurrentDeployment: import("convex/server").RegisteredQuery<"public", {}, Promise<any>>;
-    /**
-     * Validate an invite token. Returns the invite if valid and pending,
-     * or `null` otherwise. Used by the portal UI to check if an invite
-     * link is valid before showing the registration form.
-     */
-    validateInvite: import("convex/server").RegisteredQuery<"public", {
-        tokenHash: string;
-    }, Promise<{
-        _id: any;
-        role: any;
-    } | null>>;
-    /**
-     * Accept a portal invite. Must be called by an authenticated user.
-     * Marks the invite as accepted and records the accepting user's ID.
-     *
-     * The portal UI calls this after the user has signed in via magic link
-     * following an invite link.
-     */
-    acceptInvite: import("convex/server").RegisteredMutation<"public", {
-        tokenHash: string;
-    }, Promise<void>>;
-    /**
-     * Create a portal admin invite. Internal mutation called by the CLI
-     * (`npx @robelest/convex-auth portal link`).
-     */
-    createPortalInvite: import("convex/server").RegisteredMutation<"internal", {
-        tokenHash: string;
-    }, Promise<{
-        portalUrl: string;
-    }>>;
-    /**
-     * Combined portal query for all auth data reads.
-     * Requires the caller to be an authenticated portal admin.
-     *
-     * Actions:
-     * - `listUsers` — List all users
-     * - `listSessions` — List all sessions
-     * - `getUser` — Get a single user by ID (requires `userId`)
-     * - `getUserSessions` — List sessions for a user (requires `userId`)
-     * - `getUserAccounts` — List auth accounts for a user (requires `userId`)
-     * - `isAdmin` — Check if the current user is a portal admin
-     */
-    portalQuery: import("convex/server").RegisteredQuery<"public", {
-        action: string;
-        userId?: string;
-    }, Promise<any>>;
-    /**
-     * Combined portal mutation for all auth data writes.
-     * Requires the caller to be an authenticated portal admin.
-     *
-     * Actions:
-     * - `revokeSession` — Revoke (delete) a session (requires `sessionId`)
-     */
-    portalMutation: import("convex/server").RegisteredMutation<"public", {
-        action: string;
-        sessionId?: string;
-    }, Promise<void>>;
-    portal: {
-        /**
-         * The URL where the portal is served. Used by the Svelte client
-         * as the `redirectTo` for magic link sign-in.
-         */
-        portalUrl: string;
-        /**
-         * Register HTTP routes that serve the portal static UI.
-         */
-        addHttpRoutes: (http: HttpRouter, opts?: {
-            pathPrefix?: string;
-            spaFallback?: boolean;
-        }) => void;
-    };
-};
-//# sourceMappingURL=portal.d.ts.map

package/dist/server/portal.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"portal.d.ts","sourceRoot":"","sources":["../../src/server/portal.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,KAAK,EAAE,YAAY,IAAI,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAiC7F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,MAAM,CACpB,aAAa,EAAE,gBAAgB,EAC/B,oBAAoB,EAAE,GAAG,EACzB,IAAI,EAAE,GAAG,EACT,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE;IAW9B;;;;OAIG;;;IAoFH;;;;OAIG;;mBAGqD,MAAM;;;;;IAe9D;;;;;;OAMG;;mBAGqD,MAAM;;IAwB9D;;;OAGG;;mBAGqD,MAAM;;;;IAY9D;;;;;;;;;;;OAWG;;gBAQ+B,MAAM;iBAAW,MAAM;;IAkDzD;;;;;;OAMG;;gBAQkC,MAAM;oBAAc,MAAM;;;QAqB7D;;;WAGG;;QAGH;;WAEG;8BAEK,UAAU,SACT;YAAE,UAAU,CAAC,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,OAAO,CAAA;SAAE;;EAY5D"}