@robelest/convex-auth 0.0.4-preview.18 → 0.0.4-preview.19

package/src/component/public/security/keys.ts

@@ -0,0 +1,365 @@
+import { ConvexError, v } from "convex/values";
+import { mutation, query } from "../../functions";
+import {
+  vApiKeyDoc,
+  vApiKeyRateLimit,
+  vApiKeyRateLimitState,
+  vApiKeyScope,
+  vPaginated,
+} from "../../model";
+
+// ============================================================================
+// API Keys
+// ============================================================================
+
+/**
+ * Insert a new API key record into the `ApiKey` table.
+ *
+ * Creates an API key entry with the given metadata and scopes. The caller
+ * is responsible for generating and hashing the raw key before passing it
+ * here -- this function only stores the hash, never the plaintext key.
+ * The `createdAt` timestamp and `revoked: false` flag are set automatically.
+ *
+ * @param userId - The `_id` of the `User` who owns this API key.
+ * @param prefix - A short, visible prefix for the key (e.g. `"sk_live_"`)
+ *   that helps users identify which key was used without exposing the secret.
+ * @param hashedKey - SHA-256 hash of the full API key string. Used for
+ *   constant-time lookup during Bearer token verification.
+ * @param name - Human-readable name for the key (e.g. `"Production Backend"`).
+ * @param scopes - Array of permission scopes, each containing a `resource`
+ *   name and an array of allowed `actions` (e.g.
+ *   `[{ resource: "messages", actions: ["read", "write"] }]`).
+ * @param rateLimit - Optional rate limit configuration to apply per-key
+ *   (e.g. max requests per window).
+ * @param expiresAt - Optional Unix timestamp (in milliseconds) after which
+ *   the key is no longer valid. Omit for non-expiring keys.
+ * @param metadata - Optional arbitrary metadata to attach to the key record.
+ * @returns The `_id` of the newly created `ApiKey` document.
+ *
+ * @example
+ * ```ts
+ * const keyId = await ctx.runMutation(
+ *   components.auth.security.keys.keyInsert,
+ *   {
+ *     userId: user._id,
+ *     prefix: "sk_live_",
+ *     hashedKey: await sha256(rawKey),
+ *     name: "Production Backend",
+ *     scopes: [{ resource: "messages", actions: ["read", "write"] }],
+ *     expiresAt: Date.now() + 90 * 24 * 60 * 60 * 1000,
+ *   },
+ * );
+ * ```
+ */
+export const keyInsert = mutation({
+  args: {
+    userId: v.id("User"),
+    prefix: v.string(),
+    hashedKey: v.string(),
+    name: v.string(),
+    scopes: v.array(
+      v.object({
+        resource: v.string(),
+        actions: v.array(v.string()),
+      }),
+    ),
+    rateLimit: v.optional(vApiKeyRateLimit),
+    expiresAt: v.optional(v.number()),
+    metadata: v.optional(v.any()),
+  },
+  returns: v.id("ApiKey"),
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("ApiKey", {
+      ...args,
+      createdAt: Date.now(),
+      revoked: false,
+    });
+  },
+});
+
+/**
+ * Look up an API key by its SHA-256 hash.
+ *
+ * Queries the `ApiKey` table using the `hashed_key` index. This is the
+ * primary lookup path during Bearer token verification: the incoming
+ * token is hashed and matched against stored hashes in constant time.
+ * Returns the full key record including scopes, rate limit state, and
+ * revocation status so the caller can perform authorization checks.
+ *
+ * @param hashedKey - SHA-256 hash of the API key string extracted from
+ *   the `Authorization: Bearer <token>` header.
+ * @returns The matching `ApiKey` document (including rate limit state),
+ *   or `null` if no key matches the given hash.
+ *
+ * @example
+ * ```ts
+ * const apiKey = await ctx.runQuery(
+ *   components.auth.security.keys.keyGetByHashedKey,
+ *   { hashedKey: await sha256(bearerToken) },
+ * );
+ * if (apiKey === null || apiKey.revoked) {
+ *   throw new Error("Invalid or revoked API key");
+ * }
+ * ```
+ */
+export const keyGetByHashedKey = query({
+  args: { hashedKey: v.string() },
+  returns: v.union(vApiKeyDoc, v.null()),
+  handler: async (ctx, { hashedKey }) => {
+    return await ctx.db
+      .query("ApiKey")
+      .withIndex("hashed_key", (q) => q.eq("hashedKey", hashedKey))
+      .first();
+  },
+});
+
+/**
+ * List API keys with optional filtering, sorting, and cursor-based pagination.
+ *
+ * Returns a paginated result `{ items, nextCursor }` from the `ApiKey`
+ * table. Supports filtering by `userId`, `revoked` status, `name`, and
+ * `prefix`. The page size is clamped between 1 and 100 (default 50).
+ * Pass the returned `nextCursor` as `cursor` in a subsequent call to
+ * fetch the next page.
+ *
+ * @param where - Optional filter object. All specified fields are
+ *   combined with AND logic:
+ *   - `userId` -- restrict to keys owned by this user.
+ *   - `revoked` -- `true` for revoked keys, `false` for active keys.
+ *   - `name` -- exact match on the key's human-readable name.
+ *   - `prefix` -- exact match on the key prefix string.
+ * @param limit - Maximum number of items to return per page (1--100,
+ *   default `50`).
+ * @param cursor - Opaque cursor string (an `ApiKey` document `_id`)
+ *   returned from a previous call. Pass `null` or omit for the first page.
+ * @param orderBy - Field to sort by. One of `"_creationTime"`, `"name"`,
+ *   `"lastUsedAt"`, `"expiresAt"`, or `"revoked"`. Defaults to
+ *   `"_creationTime"`.
+ * @param order - Sort direction, `"asc"` or `"desc"` (default `"desc"`).
+ * @returns An object with `items` (array of `ApiKey` documents) and
+ *   `nextCursor` (string ID of the last item, or `null` if no more pages).
+ *
+ * @example
+ * ```ts
+ * // Fetch the first page of active keys for a user
+ * const page = await ctx.runQuery(
+ *   components.auth.security.keys.keyList,
+ *   {
+ *     where: { userId: user._id, revoked: false },
+ *     limit: 20,
+ *     order: "desc",
+ *   },
+ * );
+ * // Fetch the next page
+ * if (page.nextCursor) {
+ *   const page2 = await ctx.runQuery(
+ *     components.auth.security.keys.keyList,
+ *     { where: { userId: user._id, revoked: false }, cursor: page.nextCursor },
+ *   );
+ * }
+ * ```
+ */
+export const keyList = query({
+  args: {
+    where: v.optional(
+      v.object({
+        userId: v.optional(v.id("User")),
+        revoked: v.optional(v.boolean()),
+        name: v.optional(v.string()),
+        prefix: v.optional(v.string()),
+      }),
+    ),
+    limit: v.optional(v.number()),
+    cursor: v.optional(v.union(v.string(), v.null())),
+    orderBy: v.optional(
+      v.union(
+        v.literal("_creationTime"),
+        v.literal("name"),
+        v.literal("lastUsedAt"),
+        v.literal("expiresAt"),
+        v.literal("revoked"),
+      ),
+    ),
+    order: v.optional(v.union(v.literal("asc"), v.literal("desc"))),
+  },
+  returns: vPaginated(vApiKeyDoc),
+  handler: async (ctx, args) => {
+    const where = args.where ?? {};
+    const limit = Math.min(Math.max(args.limit ?? 50, 1), 100);
+    const order = args.order ?? "desc";
+
+    let q;
+    if (where.userId !== undefined) {
+      q = ctx.db
+        .query("ApiKey")
+        .withIndex("user_id", (idx) => idx.eq("userId", where.userId!));
+    } else {
+      q = ctx.db.query("ApiKey");
+    }
+
+    if (where.revoked !== undefined) {
+      q = q.filter((f) => f.eq(f.field("revoked"), where.revoked!));
+    }
+    if (where.name !== undefined) {
+      q = q.filter((f) => f.eq(f.field("name"), where.name!));
+    }
+    if (where.prefix !== undefined) {
+      q = q.filter((f) => f.eq(f.field("prefix"), where.prefix!));
+    }
+
+    q = q.order(order);
+
+    const all = await q.collect();
+    let startIdx = 0;
+    if (args.cursor) {
+      const cursorIdx = all.findIndex((doc) => doc._id === args.cursor);
+      if (cursorIdx !== -1) {
+        startIdx = cursorIdx + 1;
+      }
+    }
+    const page = all.slice(startIdx, startIdx + limit + 1);
+    const hasMore = page.length > limit;
+    const items = hasMore ? page.slice(0, limit) : page;
+    const nextCursor = hasMore ? items[items.length - 1]._id : null;
+    return { items, nextCursor };
+  },
+});
+
+/**
+ * Get a single API key by its document ID.
+ *
+ * Performs a direct document lookup on the `ApiKey` table. Useful when
+ * you already have the key's `_id` (e.g. from a list query or a stored
+ * reference) and need to retrieve its full details.
+ *
+ * @param keyId - The `_id` of the `ApiKey` document to retrieve.
+ * @returns The `ApiKey` document, or `null` if no key exists with the
+ *   given ID.
+ *
+ * @example
+ * ```ts
+ * const apiKey = await ctx.runQuery(
+ *   components.auth.security.keys.keyGetById,
+ *   { keyId: storedKeyId },
+ * );
+ * if (apiKey !== null) {
+ *   console.log(apiKey.name, apiKey.scopes);
+ * }
+ * ```
+ */
+export const keyGetById = query({
+  args: { keyId: v.id("ApiKey") },
+  returns: v.union(vApiKeyDoc, v.null()),
+  handler: async (ctx, { keyId }) => {
+    return await ctx.db.get("ApiKey", keyId);
+  },
+});
+
+/**
+ * Patch an API key record with partial updates.
+ *
+ * Performs a partial update on the `ApiKey` document. Supports modifying
+ * the key's name, scopes, rate limit configuration, rate limit state,
+ * revocation flag, and last-used timestamp. Throws a `ConvexError` with
+ * code `"KEY_NOT_FOUND"` if the key does not exist.
+ *
+ * @param keyId - The `_id` of the `ApiKey` document to update.
+ * @param data - An object containing the fields to patch. All fields are
+ *   optional:
+ *   - `name` -- Updated human-readable name.
+ *   - `scopes` -- Replacement array of permission scopes.
+ *   - `rateLimit` -- Updated rate limit configuration.
+ *   - `rateLimitState` -- Updated rate limit tracking state (token
+ *     count, last refill time).
+ *   - `revoked` -- Set to `true` to revoke the key, `false` to
+ *     reinstate it.
+ *   - `lastUsedAt` -- Unix timestamp (in milliseconds) of the most
+ *     recent API call using this key.
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * // Revoke an API key
+ * await ctx.runMutation(
+ *   components.auth.security.keys.keyPatch,
+ *   {
+ *     keyId: apiKey._id,
+ *     data: { revoked: true },
+ *   },
+ * );
+ *
+ * // Rename and update scopes
+ * await ctx.runMutation(
+ *   components.auth.security.keys.keyPatch,
+ *   {
+ *     keyId: apiKey._id,
+ *     data: {
+ *       name: "Read-Only Key",
+ *       scopes: [{ resource: "messages", actions: ["read"] }],
+ *     },
+ *   },
+ * );
+ * ```
+ */
+export const keyPatch = mutation({
+  args: {
+    keyId: v.id("ApiKey"),
+    data: v.object({
+      name: v.optional(v.string()),
+      scopes: v.optional(v.array(vApiKeyScope)),
+      rateLimit: v.optional(vApiKeyRateLimit),
+      rateLimitState: v.optional(vApiKeyRateLimitState),
+      revoked: v.optional(v.boolean()),
+      lastUsedAt: v.optional(v.number()),
+    }),
+  },
+  returns: v.null(),
+  handler: async (ctx, { keyId, data }) => {
+    const key = await ctx.db.get("ApiKey", keyId);
+    if (key === null) {
+      throw new ConvexError({
+        code: "KEY_NOT_FOUND",
+        message: "API key not found",
+        keyId,
+      });
+    }
+    await ctx.db.patch("ApiKey", keyId, data);
+    return null;
+  },
+});
+
+/**
+ * Hard-delete an API key record from the `ApiKey` table.
+ *
+ * Permanently removes the API key document. Unlike revocation (which
+ * keeps the record for audit purposes), this is an irreversible
+ * deletion. Throws a `ConvexError` with code `"KEY_NOT_FOUND"` if the
+ * key does not exist.
+ *
+ * @param keyId - The `_id` of the `ApiKey` document to delete.
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * await ctx.runMutation(
+ *   components.auth.security.keys.keyDelete,
+ *   { keyId: apiKey._id },
+ * );
+ * ```
+ */
+export const keyDelete = mutation({
+  args: { keyId: v.id("ApiKey") },
+  returns: v.null(),
+  handler: async (ctx, { keyId }) => {
+    const key = await ctx.db.get("ApiKey", keyId);
+    if (key === null) {
+      throw new ConvexError({
+        code: "KEY_NOT_FOUND",
+        message: "API key not found",
+        keyId,
+      });
+    }
+    await ctx.db.delete("ApiKey", keyId);
+    return null;
+  },
+});

package/src/component/public/security/limits.ts

@@ -0,0 +1,173 @@
+import { v } from "convex/values";
+import { mutation, query } from "../../functions";
+import { vRateLimitResult } from "../../model";
+
+/**
+ * Look up a rate limit entry by its string identifier.
+ *
+ * Queries the `RateLimit` table using the `by_identifier` unique index.
+ * Returns the rate limit state with camelCase field names (`attemptsLeft`,
+ * `lastAttemptTime`) mapped from the snake_case storage format. Used to
+ * check whether an action should be allowed or throttled.
+ *
+ * @param identifier - Unique string identifying the rate limit bucket
+ *   (e.g. `"login:user@example.com"` or `"api:sk_live_abc123"`).
+ * @returns The rate limit state object (including `attemptsLeft` and
+ *   `lastAttemptTime`), or `null` if no entry exists for the identifier.
+ *
+ * @example
+ * ```ts
+ * const limit = await ctx.runQuery(
+ *   components.auth.security.limits.rateLimitGet,
+ *   { identifier: `login:${email}` },
+ * );
+ * if (limit !== null && limit.attemptsLeft <= 0) {
+ *   throw new Error("Too many login attempts. Please try again later.");
+ * }
+ * ```
+ */
+export const rateLimitGet = query({
+  args: { identifier: v.string() },
+  returns: v.union(vRateLimitResult, v.null()),
+  handler: async (ctx, { identifier }) => {
+    const row = await ctx.db
+      .query("RateLimit")
+      .withIndex("by_identifier", (q) => q.eq("identifier", identifier))
+      .unique();
+    if (row === null) {
+      return null;
+    }
+    return {
+      ...row,
+      attemptsLeft: row.attempts_left,
+      lastAttemptTime: row.last_attempt_time,
+    };
+  },
+});
+
+/**
+ * Create a new rate limit entry in the `RateLimit` table.
+ *
+ * Initializes a rate limit bucket for a given identifier. The entry
+ * tracks remaining attempts and the timestamp of the last attempt,
+ * storing them in snake_case format internally. Call this when the
+ * first rate-limited action occurs for an identifier that does not
+ * yet have an entry.
+ *
+ * @param identifier - Unique string identifying the rate limit bucket
+ *   (e.g. `"login:user@example.com"` or `"otp:+15551234567"`).
+ * @param attemptsLeft - Number of remaining attempts before the action
+ *   is throttled.
+ * @param lastAttemptTime - Unix timestamp (in milliseconds) of the
+ *   initial attempt.
+ * @returns The `_id` of the newly created `RateLimit` document.
+ *
+ * @example
+ * ```ts
+ * const rateLimitId = await ctx.runMutation(
+ *   components.auth.security.limits.rateLimitCreate,
+ *   {
+ *     identifier: `login:${email}`,
+ *     attemptsLeft: 4, // 5 max minus this attempt
+ *     lastAttemptTime: Date.now(),
+ *   },
+ * );
+ * ```
+ */
+export const rateLimitCreate = mutation({
+  args: {
+    identifier: v.string(),
+    attemptsLeft: v.number(),
+    lastAttemptTime: v.number(),
+  },
+  returns: v.id("RateLimit"),
+  handler: async (ctx, { identifier, attemptsLeft, lastAttemptTime }) => {
+    return await ctx.db.insert("RateLimit", {
+      identifier,
+      attempts_left: attemptsLeft,
+      last_attempt_time: lastAttemptTime,
+    });
+  },
+});
+
+/**
+ * Patch a rate limit entry with partial data.
+ *
+ * Updates an existing `RateLimit` document with the provided fields.
+ * Automatically maps camelCase field names (`attemptsLeft`,
+ * `lastAttemptTime`) to the snake_case storage format before writing.
+ * Typically called to decrement remaining attempts or to reset the
+ * bucket after a cooldown window has elapsed.
+ *
+ * @param rateLimitId - The `_id` of the `RateLimit` document to update.
+ * @param data - An object containing the fields to patch. Supports
+ *   camelCase names which are transparently converted:
+ *   - `attemptsLeft` -- Updated number of remaining attempts.
+ *   - `lastAttemptTime` -- Updated timestamp of the most recent attempt.
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * // Decrement attempts after a failed login
+ * await ctx.runMutation(
+ *   components.auth.security.limits.rateLimitPatch,
+ *   {
+ *     rateLimitId: limit._id,
+ *     data: {
+ *       attemptsLeft: limit.attemptsLeft - 1,
+ *       lastAttemptTime: Date.now(),
+ *     },
+ *   },
+ * );
+ * ```
+ */
+export const rateLimitPatch = mutation({
+  args: { rateLimitId: v.id("RateLimit"), data: v.any() },
+  returns: v.null(),
+  handler: async (ctx, { rateLimitId, data }) => {
+    const nextData: Record<string, unknown> = { ...data };
+    if (nextData.attemptsLeft !== undefined) {
+      nextData.attempts_left = nextData.attemptsLeft;
+      delete nextData.attemptsLeft;
+    }
+    if (nextData.lastAttemptTime !== undefined) {
+      nextData.last_attempt_time = nextData.lastAttemptTime;
+      delete nextData.lastAttemptTime;
+    }
+    await ctx.db.patch("RateLimit", rateLimitId, nextData);
+    return null;
+  },
+});
+
+/**
+ * Delete a rate limit entry from the `RateLimit` table.
+ *
+ * Permanently removes the rate limit bucket. This effectively resets
+ * rate limiting for the associated identifier, allowing the next
+ * action to proceed without throttling. Useful for administrative
+ * resets or cleanup of expired buckets.
+ *
+ * @param rateLimitId - The `_id` of the `RateLimit` document to delete.
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * // Admin resets a user's login rate limit
+ * await ctx.runMutation(
+ *   components.auth.security.limits.rateLimitDelete,
+ *   { rateLimitId: limit._id },
+ * );
+ * ```
+ */
+export const rateLimitDelete = mutation({
+  args: { rateLimitId: v.id("RateLimit") },
+  returns: v.null(),
+  handler: async (ctx, { rateLimitId }) => {
+    await ctx.db.delete("RateLimit", rateLimitId);
+    return null;
+  },
+});
+
+// ============================================================================
+// Device Authorization (RFC 8628)
+// ============================================================================

package/src/component/public.ts

@@ -1,5 +1,27 @@
-export * from "./public/identity";
-export * from "./public/factors";
-export * from "./public/groups";
-export * from "./public/enterprise";
-export * from "./public/keys";
+/**
+ * Flat public component namespace for `components.auth.public.*` references.
+ *
+ * The implementation files under `./public/**` stay grouped by domain for
+ * maintainability, while this module preserves the single flat component API
+ * surface consumed by the auth runtime and app code.
+ */
+export * from "./public/identity/accounts";
+export * from "./public/factors/devices";
+export * from "./public/enterprise/audit";
+export * from "./public/enterprise/core";
+export * from "./public/enterprise/domains";
+export * from "./public/enterprise/scim";
+export * from "./public/enterprise/secrets";
+export * from "./public/enterprise/webhooks";
+export * from "./public/groups/core";
+export * from "./public/groups/invites";
+export * from "./public/groups/members";
+export * from "./public/security/keys";
+export * from "./public/factors/passkeys";
+export * from "./public/security/limits";
+export * from "./public/identity/tokens";
+export * from "./public/identity/sessions";
+export * from "./public/factors/totp";
+export * from "./public/identity/users";
+export * from "./public/identity/codes";
+export * from "./public/identity/verifiers";

package/src/providers/credentials.ts

@@ -25,6 +25,8 @@ import type {
 
 /**
  * Configuration for the Credentials provider.
+ *
+ * @typeParam DataModel - The Convex data model.
  */
 export interface CredentialsConfig<
   DataModel extends GenericDataModel = GenericDataModel,
@@ -63,6 +65,8 @@ export interface CredentialsConfig<
  * This is the escape hatch for fully custom auth logic. For email/password
  * flows, use the `Password` class instead.
  *
+ * @typeParam DataModel - The Convex data model.
+ *
  * @example
  * ```ts
  * import { Credentials } from "@robelest/convex-auth/providers";
@@ -96,8 +100,3 @@ export class Credentials<
     } as ConvexCredentialsConfig;
   }
 }
-
-// Re-export the old type name for backward compat
-export type CredentialsUserConfig<
-  DataModel extends GenericDataModel = GenericDataModel,
-> = CredentialsConfig<DataModel>;

package/src/providers/email.ts

@@ -7,6 +7,12 @@
 import { defaultMagicLinkEmail } from "../server/templates";
 import type { EmailConfig } from "../server/types";
 
+/**
+ * User-facing configuration for the {@link Email} provider.
+ *
+ * Use this to wire your email delivery service into Convex Auth's magic-link
+ * or OTP flow.
+ */
 export interface EmailProviderConfig {
   /** Sender address (e.g. "My App <noreply@example.com>"). */
   from: string;
@@ -23,10 +29,34 @@ export interface EmailProviderConfig {
   maxAge?: number;
 }
 
+/**
+ * Email provider for magic-link or one-time-code sign-in.
+ *
+ * Sends verification emails through your `send()` implementation and converts
+ * the result into Convex Auth's internal email-provider runtime shape.
+ *
+ * @example
+ * ```ts
+ * import { Email } from "@robelest/convex-auth/providers";
+ *
+ * const email = new Email({
+ *   from: "My App <noreply@example.com>",
+ *   send: async (_ctx, { to, subject, html }) => {
+ *     await resend.emails.send({ from: "noreply@example.com", to, subject, html });
+ *   },
+ * });
+ * ```
+ */
 export class Email {
   readonly id: string;
   readonly type = "email" as const;
 
+  /**
+   * Create an email provider instance.
+   *
+   * @param config - Email transport and provider settings.
+   * @throws {Error} When `config.from` is empty or whitespace-only.
+   */
   constructor(public readonly config: EmailProviderConfig) {
     const from = config.from.trim();
     if (from.length === 0) {

package/src/providers/phone.ts

@@ -8,6 +8,12 @@ import { Fx } from "@robelest/fx";
 
 import type { PhoneConfig } from "../server/types";
 
+/**
+ * User-facing configuration for the {@link Phone} provider.
+ *
+ * Use this to send SMS or other phone-based verification messages during
+ * sign-in.
+ */
 export interface PhoneProviderConfig {
   /** Send the verification code to the user's phone. */
   send: PhoneConfig["sendVerificationRequest"];
@@ -17,10 +23,32 @@ export interface PhoneProviderConfig {
   maxAge?: number;
 }
 
+/**
+ * Phone provider for SMS or phone-number verification flows.
+ *
+ * Wraps your `send()` implementation and materializes the runtime behavior
+ * Convex Auth needs for short-code or magic-link-style phone verification.
+ *
+ * @example
+ * ```ts
+ * import { Phone } from "@robelest/convex-auth/providers";
+ *
+ * const phone = new Phone({
+ *   send: async ({ identifier, token }) => {
+ *     await sms.send({ to: identifier, body: `Your sign-in code is ${token}` });
+ *   },
+ * });
+ * ```
+ */
 export class Phone {
   readonly id: string;
   readonly type = "phone" as const;
 
+  /**
+   * Create a phone provider instance.
+   *
+   * @param config - Phone delivery and provider settings.
+   */
   constructor(public readonly config: PhoneProviderConfig) {
     this.id = config.id ?? "phone";
   }