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

package/src/component/public.ts

@@ -5,6 +5,14 @@ import { mutation, query } from "./_generated/server";
 // Users
 // ============================================================================
 
+/** List all users. */
+export const userList = query({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.db.query("user").collect();
+  },
+});
+
 /** Retrieve a user by their document ID. */
 export const userGetById = query({
   args: { userId: v.id("user") },
@@ -79,6 +87,17 @@ export const userPatch = mutation({
 // Accounts
 // ============================================================================
 
+/** List all accounts for a user. */
+export const accountListByUser = query({
+  args: { userId: v.id("user") },
+  handler: async (ctx, { userId }) => {
+    return await ctx.db
+      .query("account")
+      .withIndex("userIdAndProvider", (q) => q.eq("userId", userId as any))
+      .collect();
+  },
+});
+
 /** Look up an account by provider and provider-specific account ID. */
 export const accountGet = query({
   args: { provider: v.string(), providerAccountId: v.string() },
@@ -133,6 +152,14 @@ export const accountDelete = mutation({
 // Sessions
 // ============================================================================
 
+/** List all sessions. */
+export const sessionList = query({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.db.query("session").collect();
+  },
+});
+
 /** Create a new session for a user with an expiration time. */
 export const sessionCreate = mutation({
   args: { userId: v.id("user"), expirationTime: v.number() },
@@ -360,6 +387,150 @@ export const refreshTokenGetActive = query({
   },
 });
 
+// ============================================================================
+// Passkeys
+// ============================================================================
+
+/** Store a new passkey credential for a user. */
+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(),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("passkey", args);
+  },
+});
+
+/** Look up a passkey by its credential ID. */
+export const passkeyGetByCredentialId = query({
+  args: { credentialId: v.string() },
+  handler: async (ctx, { credentialId }) => {
+    return await ctx.db
+      .query("passkey")
+      .withIndex("credentialId", (q) => q.eq("credentialId", credentialId))
+      .unique();
+  },
+});
+
+/** List all passkeys for a user. */
+export const passkeyListByUserId = query({
+  args: { userId: v.id("user") },
+  handler: async (ctx, { userId }) => {
+    return await ctx.db
+      .query("passkey")
+      .withIndex("userId", (q) => q.eq("userId", userId))
+      .collect();
+  },
+});
+
+/** Update a passkey's counter and last used timestamp after authentication. */
+export const passkeyUpdateCounter = mutation({
+  args: { passkeyId: v.id("passkey"), counter: v.number(), lastUsedAt: v.number() },
+  handler: async (ctx, { passkeyId, counter, lastUsedAt }) => {
+    await ctx.db.patch(passkeyId, { counter, lastUsedAt });
+  },
+});
+
+/** Update a passkey's metadata (name). */
+export const passkeyUpdateMeta = mutation({
+  args: { passkeyId: v.id("passkey"), data: v.any() },
+  handler: async (ctx, { passkeyId, data }) => {
+    await ctx.db.patch(passkeyId, data);
+  },
+});
+
+/** Delete a passkey credential. */
+export const passkeyDelete = mutation({
+  args: { passkeyId: v.id("passkey") },
+  handler: async (ctx, { passkeyId }) => {
+    await ctx.db.delete(passkeyId);
+  },
+});
+
+// ============================================================================
+// TOTP Two-Factor Authentication
+// ============================================================================
+
+/** Store a new TOTP enrollment for a user. */
+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(),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("totp", args);
+  },
+});
+
+/** Get a verified TOTP enrollment for a user (returns first match). */
+export const totpGetVerifiedByUserId = query({
+  args: { userId: v.id("user") },
+  handler: async (ctx, { userId }) => {
+    return await ctx.db
+      .query("totp")
+      .withIndex("userId", (q) => q.eq("userId", userId))
+      .filter((q) => q.eq(q.field("verified"), true))
+      .first();
+  },
+});
+
+/** List all TOTP enrollments for a user. */
+export const totpListByUserId = query({
+  args: { userId: v.id("user") },
+  handler: async (ctx, { userId }) => {
+    return await ctx.db
+      .query("totp")
+      .withIndex("userId", (q) => q.eq("userId", userId))
+      .collect();
+  },
+});
+
+/** Get a TOTP enrollment by its ID. */
+export const totpGetById = query({
+  args: { totpId: v.id("totp") },
+  handler: async (ctx, { totpId }) => {
+    return await ctx.db.get(totpId);
+  },
+});
+
+/** Mark a TOTP enrollment as verified (setup complete). */
+export const totpMarkVerified = mutation({
+  args: { totpId: v.id("totp"), lastUsedAt: v.number() },
+  handler: async (ctx, { totpId, lastUsedAt }) => {
+    await ctx.db.patch(totpId, { verified: true, lastUsedAt });
+  },
+});
+
+/** Update a TOTP enrollment's last used timestamp. */
+export const totpUpdateLastUsed = mutation({
+  args: { totpId: v.id("totp"), lastUsedAt: v.number() },
+  handler: async (ctx, { totpId, lastUsedAt }) => {
+    await ctx.db.patch(totpId, { lastUsedAt });
+  },
+});
+
+/** Delete a TOTP enrollment. */
+export const totpDelete = mutation({
+  args: { totpId: v.id("totp") },
+  handler: async (ctx, { totpId }) => {
+    await ctx.db.delete(totpId);
+  },
+});
+
 // ============================================================================
 // Rate Limits
 // ============================================================================
@@ -629,8 +800,8 @@ export const memberUpdate = mutation({
 export const inviteCreate = mutation({
   args: {
     groupId: v.optional(v.id("group")),
-    invitedByUserId: v.id("user"),
-    email: v.string(),
+    invitedByUserId: v.optional(v.id("user")),
+    email: v.optional(v.string()),
     tokenHash: v.string(),
     role: v.optional(v.string()),
     status: v.union(
@@ -639,42 +810,48 @@ export const inviteCreate = mutation({
       v.literal("revoked"),
       v.literal("expired"),
     ),
-    expiresTime: v.number(),
+    expiresTime: v.optional(v.number()),
     extend: v.optional(v.any()),
   },
   handler: async (ctx, args) => {
-    if (args.groupId !== undefined) {
-      const existingGroupInvite = await ctx.db
-        .query("invite")
-        .withIndex("groupIdAndStatus", (q) =>
-          q.eq("groupId", args.groupId).eq("status", "pending"),
-        )
-        .filter((q) => q.eq(q.field("email"), args.email))
-        .first();
-      if (existingGroupInvite !== null) {
-        throw new ConvexError({
-          code: "DUPLICATE_INVITE",
-          message: "A pending invite already exists for this email in this group",
-          email: args.email,
-          groupId: args.groupId,
-          existingInviteId: existingGroupInvite._id,
-        });
-      }
-    } else {
-      const existingPlatformInvite = await ctx.db
-        .query("invite")
-        .withIndex("emailAndStatus", (q) =>
-          q.eq("email", args.email).eq("status", "pending"),
-        )
-        .filter((q) => q.eq(q.field("groupId"), undefined))
-        .first();
-      if (existingPlatformInvite !== null) {
-        throw new ConvexError({
-          code: "DUPLICATE_INVITE",
-          message: "A pending platform invite already exists for this email",
-          email: args.email,
-          existingInviteId: existingPlatformInvite._id,
-        });
+    // Only check for duplicates when an email is provided.
+    // CLI-generated invites (no email) are always allowed.
+    if (args.email !== undefined) {
+      if (args.groupId !== undefined) {
+        const existingGroupInvite = await ctx.db
+          .query("invite")
+          .withIndex("groupIdAndStatus", (q) =>
+            q.eq("groupId", args.groupId).eq("status", "pending"),
+          )
+          .filter((q) => q.eq(q.field("email"), args.email))
+          .first();
+        if (existingGroupInvite !== null) {
+          throw new ConvexError({
+            code: "DUPLICATE_INVITE",
+            message:
+              "A pending invite already exists for this email in this group",
+            email: args.email,
+            groupId: args.groupId,
+            existingInviteId: existingGroupInvite._id,
+          });
+        }
+      } else {
+        const existingPlatformInvite = await ctx.db
+          .query("invite")
+          .withIndex("emailAndStatus", (q) =>
+            q.eq("email", args.email).eq("status", "pending"),
+          )
+          .filter((q) => q.eq(q.field("groupId"), undefined))
+          .first();
+        if (existingPlatformInvite !== null) {
+          throw new ConvexError({
+            code: "DUPLICATE_INVITE",
+            message:
+              "A pending platform invite already exists for this email",
+            email: args.email,
+            existingInviteId: existingPlatformInvite._id,
+          });
+        }
       }
     }
     return await ctx.db.insert("invite", args);
@@ -689,6 +866,17 @@ export const inviteGet = query({
   },
 });
 
+/** Retrieve an invite by its token hash. Returns `null` if not found. */
+export const inviteGetByTokenHash = query({
+  args: { tokenHash: v.string() },
+  handler: async (ctx, { tokenHash }) => {
+    return await ctx.db
+      .query("invite")
+      .withIndex("tokenHash", (q) => q.eq("tokenHash", tokenHash))
+      .unique();
+  },
+});
+
 /**
  * List invites, optionally filtered by group and/or status.
  * Both `groupId` and `status` are optional filters.
@@ -740,8 +928,11 @@ export const inviteList = query({
  * The caller is responsible for creating the corresponding member record.
  */
 export const inviteAccept = mutation({
-  args: { inviteId: v.id("invite") },
-  handler: async (ctx, { inviteId }) => {
+  args: {
+    inviteId: v.id("invite"),
+    acceptedByUserId: v.optional(v.id("user")),
+  },
+  handler: async (ctx, { inviteId, acceptedByUserId }) => {
     const invite = await ctx.db.get(inviteId);
     if (invite === null) {
       throw new ConvexError({
@@ -761,6 +952,7 @@ export const inviteAccept = mutation({
     await ctx.db.patch(inviteId, {
       status: "accepted",
       acceptedTime: Date.now(),
+      ...(acceptedByUserId ? { acceptedByUserId } : {}),
     });
   },
 });
@@ -793,3 +985,147 @@ export const inviteRevoke = mutation({
     await ctx.db.patch(inviteId, { status: "revoked" });
   },
 });
+
+// ============================================================================
+// API Keys
+// ============================================================================
+
+/**
+ * Insert a new API key record.
+ *
+ * The caller is responsible for hashing the raw key before passing it here —
+ * this function only stores the hash and metadata.
+ */
+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(
+      v.object({
+        maxRequests: v.number(),
+        windowMs: v.number(),
+      }),
+    ),
+    expiresAt: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("key", {
+      ...args,
+      createdAt: Date.now(),
+      revoked: false,
+    });
+  },
+});
+
+/**
+ * Look up an API key by its SHA-256 hash.
+ *
+ * Used during Bearer token verification. Returns the full key record
+ * (including rate limit state) or `null` if not found.
+ */
+export const keyGetByHashedKey = query({
+  args: { hashedKey: v.string() },
+  handler: async (ctx, { hashedKey }) => {
+    return await ctx.db
+      .query("key")
+      .withIndex("hashedKey", (q) => q.eq("hashedKey", hashedKey))
+      .first();
+  },
+});
+
+/** List all API keys for a user. */
+export const keyListByUserId = query({
+  args: { userId: v.id("user") },
+  handler: async (ctx, { userId }) => {
+    return await ctx.db
+      .query("key")
+      .withIndex("userId", (q) => q.eq("userId", userId))
+      .collect();
+  },
+});
+
+/** List all API keys across all users (for portal admin). */
+export const keyList = query({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.db.query("key").collect();
+  },
+});
+
+/** Get a single API key by document ID. */
+export const keyGetById = query({
+  args: { keyId: v.id("key") },
+  handler: async (ctx, { keyId }) => {
+    return await ctx.db.get(keyId);
+  },
+});
+
+/**
+ * Patch an API key record. Used for updating name, scopes, rate limit config,
+ * revocation, and lastUsedAt / rate limit state tracking.
+ */
+export const keyPatch = mutation({
+  args: {
+    keyId: v.id("key"),
+    data: v.object({
+      name: v.optional(v.string()),
+      scopes: v.optional(
+        v.array(
+          v.object({
+            resource: v.string(),
+            actions: v.array(v.string()),
+          }),
+        ),
+      ),
+      rateLimit: v.optional(
+        v.object({
+          maxRequests: v.number(),
+          windowMs: v.number(),
+        }),
+      ),
+      rateLimitState: v.optional(
+        v.object({
+          attemptsLeft: v.number(),
+          lastAttemptTime: v.number(),
+        }),
+      ),
+      revoked: v.optional(v.boolean()),
+      lastUsedAt: v.optional(v.number()),
+    }),
+  },
+  handler: async (ctx, { keyId, data }) => {
+    const key = await ctx.db.get(keyId);
+    if (key === null) {
+      throw new ConvexError({
+        code: "KEY_NOT_FOUND",
+        message: "API key not found",
+        keyId,
+      });
+    }
+    await ctx.db.patch(keyId, data);
+  },
+});
+
+/** Hard delete an API key record. */
+export const keyDelete = mutation({
+  args: { keyId: v.id("key") },
+  handler: async (ctx, { keyId }) => {
+    const key = await ctx.db.get(keyId);
+    if (key === null) {
+      throw new ConvexError({
+        code: "KEY_NOT_FOUND",
+        message: "API key not found",
+        keyId,
+      });
+    }
+    await ctx.db.delete(keyId);
+  },
+});

package/src/component/schema.ts

@@ -96,6 +96,61 @@ export default defineSchema({
     signature: v.optional(v.string()),
   }).index("signature", ["signature"]),
 
+  /**
+   * WebAuthn passkey credentials. Each credential links a user to a
+   * registered authenticator (Touch ID, Face ID, security key, etc.).
+   * A user can have multiple passkeys across different devices.
+   */
+  passkey: defineTable({
+    userId: v.id("user"),
+    /** Base64url-encoded credential ID from the authenticator. */
+    credentialId: v.string(),
+    /** Public key bytes (SEC1 uncompressed for EC, SPKI for RSA). */
+    publicKey: v.bytes(),
+    /** COSE algorithm identifier (-7 for ES256, -257 for RS256, -8 for EdDSA). */
+    algorithm: v.number(),
+    /** Signature counter for clone detection. Many authenticators return 0. */
+    counter: v.number(),
+    /** Authenticator transport hints (e.g. "internal", "hybrid", "usb", "ble", "nfc"). */
+    transports: v.optional(v.array(v.string())),
+    /** Whether this is a single-device or multi-device (synced) credential. */
+    deviceType: v.string(),
+    /** Whether the credential is backed up (synced passkey). */
+    backedUp: v.boolean(),
+    /** User-assigned friendly name (e.g. "MacBook Touch ID"). */
+    name: v.optional(v.string()),
+    createdAt: v.number(),
+    lastUsedAt: v.optional(v.number()),
+  })
+    .index("userId", ["userId"])
+    .index("credentialId", ["credentialId"]),
+
+  /**
+   * TOTP two-factor authentication secrets. Each record links a user to
+   * an authenticator app. A user can have multiple TOTP enrollments
+   * (e.g. different authenticator apps) but typically has one.
+   *
+   * The `verified` flag indicates whether the user has completed setup
+   * by successfully entering a code from their authenticator app.
+   * Unverified enrollments are in-progress setup that can be discarded.
+   */
+  totp: defineTable({
+    userId: v.id("user"),
+    /** Raw TOTP secret key bytes. */
+    secret: v.bytes(),
+    /** Number of digits in each code (typically 6). */
+    digits: v.number(),
+    /** Time period in seconds for code rotation (typically 30). */
+    period: v.number(),
+    /** Whether setup has been confirmed with a valid code. */
+    verified: v.boolean(),
+    /** User-assigned friendly name (e.g. "Google Authenticator"). */
+    name: v.optional(v.string()),
+    createdAt: v.number(),
+    lastUsedAt: v.optional(v.number()),
+  })
+    .index("userId", ["userId"]),
+
   /**
    * Rate limit tracking for OTP and password sign-in attempts.
    */
@@ -136,14 +191,17 @@ export default defineSchema({
     .index("userId", ["userId"]),
 
   /**
-   * Group invitations. Tracks pending, accepted, revoked, and expired
-   * invitations to join a group. Uses a hashed token for secure
-   * invitation links.
+   * Invitations. Tracks pending, accepted, revoked, and expired
+   * invitations. Optionally scoped to a group via `groupId`, or
+   * platform-level when `groupId` is omitted.
+   *
+   * `email` and `invitedByUserId` are optional to support CLI-generated
+   * invite links where neither is known upfront (e.g. portal admin invites).
    */
   invite: defineTable({
     groupId: v.optional(v.id("group")),
-    invitedByUserId: v.id("user"),
-    email: v.string(),
+    invitedByUserId: v.optional(v.id("user")),
+    email: v.optional(v.string()),
     tokenHash: v.string(),
     role: v.optional(v.string()),
     status: v.union(
@@ -152,7 +210,7 @@ export default defineSchema({
       v.literal("revoked"),
       v.literal("expired"),
     ),
-    expiresTime: v.number(),
+    expiresTime: v.optional(v.number()),
     acceptedByUserId: v.optional(v.id("user")),
     acceptedTime: v.optional(v.number()),
     extend: v.optional(v.any()),
@@ -162,5 +220,62 @@ export default defineSchema({
     .index("emailAndStatus", ["email", "status"])
     .index("invitedByUserIdAndStatus", ["invitedByUserId", "status"])
     .index("groupId", ["groupId"])
-    .index("groupIdAndStatus", ["groupId", "status"]),
+    .index("groupIdAndStatus", ["groupId", "status"])
+    .index("roleAndStatusAndAcceptedByUserId", [
+      "role",
+      "status",
+      "acceptedByUserId",
+    ]),
+
+  /**
+   * API keys for programmatic access. Each key links a user to a set of
+   * scoped permissions and optional per-key rate limiting.
+   *
+   * The raw key is never stored — only a SHA-256 hash. A short prefix
+   * (e.g. "sk_live_abc1...") is kept for display in the portal.
+   *
+   * Keys support:
+   * - **Scoped permissions**: resource:action pairs (e.g. users:read)
+   * - **Per-key rate limiting**: token-bucket with configurable window
+   * - **Expiration**: optional TTL
+   * - **Soft revocation**: `revoked` flag preserves audit trail
+   */
+  key: defineTable({
+    userId: v.id("user"),
+    /** First chars of the key for display (e.g. "sk_live_abc1..."). */
+    prefix: v.string(),
+    /** SHA-256 hex hash of the full raw key. */
+    hashedKey: v.string(),
+    /** User-assigned name (e.g. "CI Pipeline", "Production API"). */
+    name: v.string(),
+    /** Scoped permissions: [{ resource: "users", actions: ["read", "list"] }]. */
+    scopes: v.array(
+      v.object({
+        resource: v.string(),
+        actions: v.array(v.string()),
+      }),
+    ),
+    /** Optional per-key rate limit configuration. */
+    rateLimit: v.optional(
+      v.object({
+        maxRequests: v.number(),
+        windowMs: v.number(),
+      }),
+    ),
+    /** Rate limit state tracking (token-bucket). */
+    rateLimitState: v.optional(
+      v.object({
+        attemptsLeft: v.number(),
+        lastAttemptTime: v.number(),
+      }),
+    ),
+    /** Expiration timestamp. Null/undefined = never expires. */
+    expiresAt: v.optional(v.number()),
+    lastUsedAt: v.optional(v.number()),
+    createdAt: v.number(),
+    /** Soft-revoke flag. Revoked keys are kept for audit trail. */
+    revoked: v.boolean(),
+  })
+    .index("userId", ["userId"])
+    .index("hashedKey", ["hashedKey"]),
 });

package/src/providers/passkey.ts

@@ -0,0 +1,35 @@
+import { PasskeyProviderConfig } from "../server/types.js";
+
+/**
+ * Passkey (WebAuthn) authentication provider.
+ *
+ * Enables passwordless authentication via biometrics, security keys,
+ * and synced passkeys using the Web Authentication API.
+ *
+ * ```ts
+ * import passkey from "@robelest/convex-auth/providers/passkey";
+ *
+ * export const { auth, signIn, signOut, store } = Auth({
+ *   component: components.auth,
+ *   providers: [passkey()],
+ * });
+ * ```
+ *
+ * @param config Optional configuration for the relying party and credential options.
+ */
+export default function passkey(
+  config?: Partial<PasskeyProviderConfig["options"]>,
+): PasskeyProviderConfig {
+  return {
+    id: "passkey",
+    type: "passkey",
+    options: {
+      attestation: "none",
+      userVerification: "required",
+      residentKey: "preferred",
+      algorithms: [-7, -257], // ES256, RS256
+      challengeExpirationMs: 300_000, // 5 minutes
+      ...config,
+    },
+  };
+}

package/src/providers/totp.ts

@@ -0,0 +1,26 @@
+import { TotpProviderConfig } from "../server/types.js";
+
+/**
+ * Add TOTP (Time-based One-Time Password) authentication.
+ *
+ * ```ts
+ * import TOTP from "@robelest/convex-auth/providers/totp";
+ *
+ * export const { auth, signIn, signOut, store } = Auth({
+ *   providers: [TOTP({ issuer: "My App" })],
+ * });
+ * ```
+ */
+export default function totp(
+  config?: Partial<TotpProviderConfig["options"]>,
+): TotpProviderConfig {
+  return {
+    id: "totp",
+    type: "totp",
+    options: {
+      issuer: config?.issuer ?? "ConvexAuth",
+      digits: config?.digits ?? 6,
+      period: config?.period ?? 30,
+    },
+  };
+}