@robelest/convex-auth 0.0.4-preview.25 → 0.0.4-preview.28

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

@@ -1,243 +0,0 @@
-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

@@ -1,259 +0,0 @@
-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
-// ============================================================================