@robelest/convex-auth 0.0.4-preview.2 → 0.0.4-preview.21

package/src/component/public/factors/passkeys.ts

@@ -0,0 +1,242 @@
+import { v } from "convex/values";
+import { mutation, query } from "../../functions";
+import { vPasskeyDoc } from "../../model";
+
+/**
+ * Store a new WebAuthn passkey credential for a user.
+ *
+ * Persists the public key material and metadata returned by the browser's
+ * `navigator.credentials.create()` call after a successful registration
+ * ceremony. Each passkey is tied to a single user.
+ *
+ * @param userId - The `_id` of the `User` who owns this passkey.
+ * @param credentialId - Base64url-encoded credential identifier assigned
+ *   by the authenticator; used to look up the key during authentication.
+ * @param publicKey - Raw public key bytes (COSE format) for signature
+ *   verification.
+ * @param algorithm - COSE algorithm identifier (e.g. `-7` for ES256,
+ *   `-257` for RS256).
+ * @param counter - Signature counter reported by the authenticator at
+ *   registration time; used to detect cloned credentials.
+ * @param transports - Optional list of transport hints (e.g.
+ *   `["usb", "ble", "nfc", "internal"]`) to help the browser select
+ *   the correct authenticator.
+ * @param deviceType - Authenticator attachment type (e.g.
+ *   `"singleDevice"` or `"multiDevice"`).
+ * @param backedUp - Whether the credential is backed up (synced) by the
+ *   authenticator platform.
+ * @param name - Optional human-readable label for the passkey
+ *   (e.g. `"MacBook Pro Touch ID"`).
+ * @param createdAt - Unix timestamp (in milliseconds) when the passkey
+ *   was registered.
+ * @returns The `_id` of the newly created `Passkey` document.
+ *
+ * @example
+ * ```ts
+ * const passkeyId = await ctx.runMutation(
+ *   components.auth.factors.passkeys.passkeyInsert,
+ *   {
+ *     userId: user._id,
+ *     credentialId: "dGVzdC1jcmVkZW50aWFs",
+ *     publicKey: publicKeyBytes,
+ *     algorithm: -7,
+ *     counter: 0,
+ *     transports: ["internal"],
+ *     deviceType: "multiDevice",
+ *     backedUp: true,
+ *     name: "MacBook Pro Touch ID",
+ *     createdAt: Date.now(),
+ *   },
+ * );
+ * ```
+ */
+export const passkeyInsert = mutation({
+  args: {
+    userId: v.id("User"),
+    credentialId: v.string(),
+    publicKey: v.bytes(),
+    algorithm: v.number(),
+    counter: v.number(),
+    transports: v.optional(v.array(v.string())),
+    deviceType: v.string(),
+    backedUp: v.boolean(),
+    name: v.optional(v.string()),
+    createdAt: v.number(),
+  },
+  returns: v.id("Passkey"),
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("Passkey", args);
+  },
+});
+
+/**
+ * Look up a passkey by its credential ID.
+ *
+ * Queries the `Passkey` table using the `credential_id` unique index.
+ * This is the primary lookup during a WebAuthn authentication ceremony:
+ * the authenticator provides a credential ID, and this function retrieves
+ * the corresponding public key and counter for signature verification.
+ *
+ * @param credentialId - Base64url-encoded credential identifier to search for.
+ * @returns The matching `Passkey` document, or `null` if no passkey exists
+ *   with the given credential ID.
+ *
+ * @example
+ * ```ts
+ * const passkey = await ctx.runQuery(
+ *   components.auth.factors.passkeys.passkeyGetByCredentialId,
+ *   { credentialId: "dGVzdC1jcmVkZW50aWFs" },
+ * );
+ * if (passkey === null) {
+ *   throw new Error("Unknown credential");
+ * }
+ * ```
+ */
+export const passkeyGetByCredentialId = query({
+  args: { credentialId: v.string() },
+  returns: v.union(vPasskeyDoc, v.null()),
+  handler: async (ctx, { credentialId }) => {
+    return await ctx.db
+      .query("Passkey")
+      .withIndex("credential_id", (q) => q.eq("credentialId", credentialId))
+      .unique();
+  },
+});
+
+/**
+ * List all passkeys registered to a user.
+ *
+ * Retrieves every `Passkey` document associated with the given user via
+ * the `user_id` index. Useful for displaying a user's registered
+ * authenticators in a settings page, or for building the
+ * `allowCredentials` list during a WebAuthn authentication ceremony.
+ *
+ * @param userId - The `_id` of the `User` whose passkeys to retrieve.
+ * @returns An array of `Passkey` documents. Returns an empty array if the
+ *   user has no registered passkeys.
+ *
+ * @example
+ * ```ts
+ * const passkeys = await ctx.runQuery(
+ *   components.auth.factors.passkeys.passkeyListByUserId,
+ *   { userId: user._id },
+ * );
+ * // Display each passkey's name and creation date
+ * for (const pk of passkeys) {
+ *   console.log(pk.name, new Date(pk.createdAt));
+ * }
+ * ```
+ */
+export const passkeyListByUserId = query({
+  args: { userId: v.id("User") },
+  returns: v.array(vPasskeyDoc),
+  handler: async (ctx, { userId }) => {
+    return await ctx.db
+      .query("Passkey")
+      .withIndex("user_id", (q) => q.eq("userId", userId))
+      .collect();
+  },
+});
+
+/**
+ * Update a passkey's signature counter and last-used timestamp after
+ * a successful authentication.
+ *
+ * After verifying a WebAuthn assertion, the relying party must persist
+ * the new counter value reported by the authenticator. A counter that
+ * does not increase may indicate a cloned credential.
+ *
+ * @param passkeyId - The `_id` of the `Passkey` document to update.
+ * @param counter - The new signature counter value returned by the
+ *   authenticator in the assertion response.
+ * @param lastUsedAt - Unix timestamp (in milliseconds) recording when
+ *   this passkey was most recently used to authenticate.
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * await ctx.runMutation(
+ *   components.auth.factors.passkeys.passkeyUpdateCounter,
+ *   {
+ *     passkeyId: passkey._id,
+ *     counter: assertionResponse.counter,
+ *     lastUsedAt: Date.now(),
+ *   },
+ * );
+ * ```
+ */
+export const passkeyUpdateCounter = mutation({
+  args: {
+    passkeyId: v.id("Passkey"),
+    counter: v.number(),
+    lastUsedAt: v.number(),
+  },
+  returns: v.null(),
+  handler: async (ctx, { passkeyId, counter, lastUsedAt }) => {
+    await ctx.db.patch("Passkey", passkeyId, { counter, lastUsedAt });
+    return null;
+  },
+});
+
+/**
+ * Update a passkey's metadata fields.
+ *
+ * Performs a partial patch on the `Passkey` document. Typically used to
+ * rename a passkey (e.g. from `"Security Key"` to `"YubiKey 5C"`), but
+ * can update any mutable fields via the `data` argument.
+ *
+ * @param passkeyId - The `_id` of the `Passkey` document to update.
+ * @param data - An object containing the fields to patch. Commonly
+ *   includes `{ name: "New Label" }`, but accepts any valid passkey fields.
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * await ctx.runMutation(
+ *   components.auth.factors.passkeys.passkeyUpdateMeta,
+ *   {
+ *     passkeyId: passkey._id,
+ *     data: { name: "YubiKey 5C NFC" },
+ *   },
+ * );
+ * ```
+ */
+export const passkeyUpdateMeta = mutation({
+  args: { passkeyId: v.id("Passkey"), data: v.any() },
+  returns: v.null(),
+  handler: async (ctx, { passkeyId, data }) => {
+    await ctx.db.patch("Passkey", passkeyId, data);
+    return null;
+  },
+});
+
+/**
+ * Delete a passkey credential from the `Passkey` table.
+ *
+ * Permanently removes the passkey record. After deletion the credential
+ * can no longer be used for authentication. Typically called from a
+ * user's security settings when they want to unregister an authenticator.
+ *
+ * @param passkeyId - The `_id` of the `Passkey` document to delete.
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * await ctx.runMutation(
+ *   components.auth.factors.passkeys.passkeyDelete,
+ *   { passkeyId: passkey._id },
+ * );
+ * ```
+ */
+export const passkeyDelete = mutation({
+  args: { passkeyId: v.id("Passkey") },
+  returns: v.null(),
+  handler: async (ctx, { passkeyId }) => {
+    await ctx.db.delete("Passkey", passkeyId);
+    return null;
+  },
+});
+
+// ============================================================================
+// TOTP Two-Factor Authentication
+// ============================================================================

package/src/component/public/factors/totp.ts

@@ -0,0 +1,258 @@
+import { v } from "convex/values";
+import { mutation, query } from "../../functions";
+import { vTotpFactorDoc } from "../../model";
+
+/**
+ * Store a new TOTP (Time-based One-Time Password) enrollment for a user.
+ *
+ * Creates a `TotpFactor` record containing the shared secret and OTP
+ * parameters. The enrollment starts in an unverified state until the
+ * user confirms it by submitting a valid code generated from the secret.
+ *
+ * @param userId - The `_id` of the `User` enrolling in TOTP-based 2FA.
+ * @param secret - The shared secret key as raw bytes, typically 20 bytes
+ *   of cryptographically random data.
+ * @param digits - Number of digits in the generated OTP code (usually `6`).
+ * @param period - Time step in seconds for code generation (usually `30`).
+ * @param verified - Whether the enrollment has been verified. Set to
+ *   `false` during initial setup; set to `true` after the user submits
+ *   a valid code.
+ * @param name - Optional human-readable label for the TOTP factor
+ *   (e.g. `"Google Authenticator"`).
+ * @param createdAt - Unix timestamp (in milliseconds) when the enrollment
+ *   was created.
+ * @returns The `_id` of the newly created `TotpFactor` document.
+ *
+ * @example
+ * ```ts
+ * const totpId = await ctx.runMutation(
+ *   components.auth.factors.totp.totpInsert,
+ *   {
+ *     userId: user._id,
+ *     secret: crypto.getRandomValues(new Uint8Array(20)),
+ *     digits: 6,
+ *     period: 30,
+ *     verified: false,
+ *     name: "Authenticator App",
+ *     createdAt: Date.now(),
+ *   },
+ * );
+ * ```
+ */
+export const totpInsert = mutation({
+  args: {
+    userId: v.id("User"),
+    secret: v.bytes(),
+    digits: v.number(),
+    period: v.number(),
+    verified: v.boolean(),
+    name: v.optional(v.string()),
+    createdAt: v.number(),
+  },
+  returns: v.id("TotpFactor"),
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("TotpFactor", args);
+  },
+});
+
+/**
+ * Get a verified TOTP enrollment for a user.
+ *
+ * Queries the `TotpFactor` table using the `user_id_verified` compound
+ * index to find the first enrollment that has been successfully verified.
+ * This is the primary lookup during a TOTP authentication challenge --
+ * only verified enrollments should be used to validate codes.
+ *
+ * @param userId - The `_id` of the `User` whose verified TOTP enrollment
+ *   to retrieve.
+ * @returns The first verified `TotpFactor` document for the user, or
+ *   `null` if the user has no verified TOTP enrollment.
+ *
+ * @example
+ * ```ts
+ * const totp = await ctx.runQuery(
+ *   components.auth.factors.totp.totpGetVerifiedByUserId,
+ *   { userId: user._id },
+ * );
+ * if (totp === null) {
+ *   // User does not have TOTP 2FA enabled
+ * }
+ * ```
+ */
+export const totpGetVerifiedByUserId = query({
+  args: { userId: v.id("User") },
+  returns: v.union(vTotpFactorDoc, v.null()),
+  handler: async (ctx, { userId }) => {
+    return await ctx.db
+      .query("TotpFactor")
+      .withIndex("user_id_verified", (q) =>
+        q.eq("userId", userId).eq("verified", true),
+      )
+      .first();
+  },
+});
+
+/**
+ * List all TOTP enrollments for a user, both verified and unverified.
+ *
+ * Retrieves every `TotpFactor` document associated with the given user
+ * via the `user_id` index. Useful for displaying enrolled authenticator
+ * apps in a security settings page, including pending (unverified)
+ * enrollments that the user has not yet confirmed.
+ *
+ * @param userId - The `_id` of the `User` whose TOTP enrollments to
+ *   retrieve.
+ * @returns An array of `TotpFactor` documents. Returns an empty array if
+ *   the user has no TOTP enrollments.
+ *
+ * @example
+ * ```ts
+ * const factors = await ctx.runQuery(
+ *   components.auth.factors.totp.totpListByUserId,
+ *   { userId: user._id },
+ * );
+ * const verified = factors.filter((f) => f.verified);
+ * const pending = factors.filter((f) => !f.verified);
+ * ```
+ */
+export const totpListByUserId = query({
+  args: { userId: v.id("User") },
+  returns: v.array(vTotpFactorDoc),
+  handler: async (ctx, { userId }) => {
+    return await ctx.db
+      .query("TotpFactor")
+      .withIndex("user_id", (q) => q.eq("userId", userId))
+      .collect();
+  },
+});
+
+/**
+ * Get a single TOTP enrollment by its document ID.
+ *
+ * Performs a direct document lookup on the `TotpFactor` table. This is
+ * used when you already have the enrollment's `_id` (e.g. from a
+ * previous list query) and need to fetch its full details, including
+ * the secret and verification status.
+ *
+ * @param totpId - The `_id` of the `TotpFactor` document to retrieve.
+ * @returns The `TotpFactor` document, or `null` if no enrollment exists
+ *   with the given ID.
+ *
+ * @example
+ * ```ts
+ * const totp = await ctx.runQuery(
+ *   components.auth.factors.totp.totpGetById,
+ *   { totpId: enrollmentId },
+ * );
+ * if (totp !== null && !totp.verified) {
+ *   // Enrollment is still pending confirmation
+ * }
+ * ```
+ */
+export const totpGetById = query({
+  args: { totpId: v.id("TotpFactor") },
+  returns: v.union(vTotpFactorDoc, v.null()),
+  handler: async (ctx, { totpId }) => {
+    return await ctx.db.get("TotpFactor", totpId);
+  },
+});
+
+/**
+ * Mark a TOTP enrollment as verified, completing the setup process.
+ *
+ * Called after the user successfully submits a valid TOTP code during
+ * enrollment. This transitions the factor from a pending state to an
+ * active, verified state, enabling it for future authentication
+ * challenges.
+ *
+ * @param totpId - The `_id` of the `TotpFactor` document to mark as
+ *   verified.
+ * @param lastUsedAt - Unix timestamp (in milliseconds) recording when
+ *   the verification code was successfully validated.
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * // After validating the user's TOTP code during setup
+ * await ctx.runMutation(
+ *   components.auth.factors.totp.totpMarkVerified,
+ *   {
+ *     totpId: enrollment._id,
+ *     lastUsedAt: Date.now(),
+ *   },
+ * );
+ * ```
+ */
+export const totpMarkVerified = mutation({
+  args: { totpId: v.id("TotpFactor"), lastUsedAt: v.number() },
+  returns: v.null(),
+  handler: async (ctx, { totpId, lastUsedAt }) => {
+    await ctx.db.patch("TotpFactor", totpId, { verified: true, lastUsedAt });
+    return null;
+  },
+});
+
+/**
+ * Update a TOTP enrollment's last-used timestamp.
+ *
+ * Called after each successful TOTP code validation during sign-in.
+ * Tracking the last-used time helps detect stale enrollments and can
+ * be surfaced in security settings for user awareness.
+ *
+ * @param totpId - The `_id` of the `TotpFactor` document to update.
+ * @param lastUsedAt - Unix timestamp (in milliseconds) recording when
+ *   the TOTP code was most recently validated.
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * await ctx.runMutation(
+ *   components.auth.factors.totp.totpUpdateLastUsed,
+ *   {
+ *     totpId: totp._id,
+ *     lastUsedAt: Date.now(),
+ *   },
+ * );
+ * ```
+ */
+export const totpUpdateLastUsed = mutation({
+  args: { totpId: v.id("TotpFactor"), lastUsedAt: v.number() },
+  returns: v.null(),
+  handler: async (ctx, { totpId, lastUsedAt }) => {
+    await ctx.db.patch("TotpFactor", totpId, { lastUsedAt });
+    return null;
+  },
+});
+
+/**
+ * Delete a TOTP enrollment from the `TotpFactor` table.
+ *
+ * Permanently removes the TOTP factor record, including its shared
+ * secret. After deletion the user can no longer use this factor for
+ * two-factor authentication. Typically called when a user disables
+ * TOTP 2FA or wants to re-enroll with a new secret.
+ *
+ * @param totpId - The `_id` of the `TotpFactor` document to delete.
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * // User disables TOTP 2FA
+ * await ctx.runMutation(
+ *   components.auth.factors.totp.totpDelete,
+ *   { totpId: totp._id },
+ * );
+ * ```
+ */
+export const totpDelete = mutation({
+  args: { totpId: v.id("TotpFactor") },
+  returns: v.null(),
+  handler: async (ctx, { totpId }) => {
+    await ctx.db.delete("TotpFactor", totpId);
+    return null;
+  },
+});
+
+// ============================================================================
+// Rate Limits
+// ============================================================================