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

package/src/component/public.ts

@@ -986,4 +986,146 @@ export const inviteRevoke = mutation({
   },
 });
 
+// ============================================================================
+// 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

@@ -226,4 +226,56 @@ export default defineSchema({
       "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/anonymous.ts

@@ -56,6 +56,9 @@ export interface AnonymousConfig<DataModel extends GenericDataModel> {
  * An anonymous authentication provider.
  *
  * This provider doesn't require any user-provided information.
+ *
+ * @param config - Optional overrides (custom ID, profile, etc.).
+ * @returns A `ConvexCredentialsConfig` to include in your `providers` array.
  */
 export default function anonymous<DataModel extends GenericDataModel>(
   config: AnonymousConfig<DataModel> = {},

package/src/providers/credentials.ts

@@ -94,6 +94,9 @@ export interface CredentialsUserConfig<
 /**
  * The Credentials provider allows you to handle signing in with arbitrary credentials,
  * such as a username and password, domain, or two factor authentication or hardware device (e.g. YubiKey U2F / FIDO).
+ *
+ * @param config - Credential-specific options (authorize callback, profile, etc.).
+ * @returns A `ConvexCredentialsConfig` to include in your `providers` array.
  */
 export default function credentials<DataModel extends GenericDataModel>(
   config: CredentialsUserConfig<DataModel>,

package/src/providers/email.ts

@@ -30,6 +30,9 @@ import { EmailConfig, EmailUserConfig } from "../server/types.js";
  * ```
  *
  * Make sure the token has high enough entropy to be secure.
+ *
+ * @param config - Email provider options including `sendVerificationRequest`.
+ * @returns An `EmailConfig` to include in your `providers` array.
  */
 export default function email<DataModel extends GenericDataModel>(
   config: EmailUserConfig<DataModel> &

package/src/providers/passkey.ts

@@ -1,3 +1,9 @@
+/**
+ * Passkey (WebAuthn) authentication provider.
+ *
+ * @module
+ */
+
 import { PasskeyProviderConfig } from "../server/types.js";
 
 /**
@@ -15,7 +21,8 @@ import { PasskeyProviderConfig } from "../server/types.js";
  * });
  * ```
  *
- * @param config Optional configuration for the relying party and credential options.
+ * @param config - Optional relying party and credential options.
+ * @returns A `PasskeyProviderConfig` to include in your `providers` array.
  */
 export default function passkey(
   config?: Partial<PasskeyProviderConfig["options"]>,

package/src/providers/password.ts

@@ -105,6 +105,9 @@ export interface PasswordConfig<DataModel extends GenericDataModel> {
  *
  * Email verification is not required unless you pass
  * an email provider to the `verify` option.
+ *
+ * @param config - Password options (custom ID, crypto, verify, profile, etc.).
+ * @returns A `ConvexCredentialsConfig` to include in your `providers` array.
  */
 export default function password<DataModel extends GenericDataModel>(
   config: PasswordConfig<DataModel> = {},

package/src/providers/phone.ts

@@ -19,6 +19,9 @@ import { PhoneConfig, PhoneUserConfig } from "../server/types.js";
  * When you use this function to create your config, it
  * checks that there is a `phone` field during token verification
  * that matches the `phone` used during the initial `signIn` call.
+ *
+ * @param config - Phone provider options including `sendVerificationRequest`.
+ * @returns A `PhoneConfig` to include in your `providers` array.
  */
 export default function phone<DataModel extends GenericDataModel>(
   config: PhoneUserConfig & Pick<PhoneConfig, "sendVerificationRequest">,

package/src/providers/totp.ts

@@ -1,3 +1,9 @@
+/**
+ * TOTP (Time-based One-Time Password) two-factor authentication provider.
+ *
+ * @module
+ */
+
 import { TotpProviderConfig } from "../server/types.js";
 
 /**
@@ -10,6 +16,9 @@ import { TotpProviderConfig } from "../server/types.js";
  *   providers: [TOTP({ issuer: "My App" })],
  * });
  * ```
+ *
+ * @param config - TOTP options: issuer name, digit count, and period.
+ * @returns A `TotpProviderConfig` to include in your `providers` array.
  */
 export default function totp(
   config?: Partial<TotpProviderConfig["options"]>,