convex-zen 0.0.1

package/src/component/lib/crypto.ts

@@ -0,0 +1,63 @@
+/**
+ * Cryptographic utilities using Web Crypto API.
+ * All token generation uses crypto.getRandomValues for 256+ bit entropy.
+ * Tokens are stored as SHA-256 hashes only (never raw).
+ */
+
+/** Generate a cryptographically secure 32-byte random hex token (256 bits). */
+export function generateToken(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/** SHA-256 hash a string token, returns hex string. */
+export async function hashToken(token: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(token);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** Base64url encode bytes (no padding). Used for PKCE code challenge. */
+export function base64url(bytes: Uint8Array): string {
+  const base64 = btoa(String.fromCharCode(...bytes));
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+
+/** Generate a PKCE code verifier (32 random bytes, base64url encoded). */
+export function generateCodeVerifier(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return base64url(bytes);
+}
+
+/** Generate a PKCE code challenge (SHA-256 of verifier, base64url encoded). */
+export async function generateCodeChallenge(verifier: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(verifier);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  return base64url(new Uint8Array(hashBuffer));
+}
+
+/**
+ * Generate a cryptographically secure 8-character alphanumeric code.
+ * Uses rejection sampling to avoid modulo bias.
+ * Charset: A-Z, 0-9 (36 chars) — avoids ambiguous chars like 0/O, 1/I/l.
+ */
+export function generateCode(): string {
+  const charset = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"; // 32 chars, power of 2
+  const bytes = new Uint8Array(8);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes)
+    .map((b) => charset[b & 31]) // 32 = 2^5, no bias since 256 / 32 = 8 exactly
+    .join("");
+}
+
+/** Generate a 32-byte random state token for OAuth (returned as hex). */
+export function generateState(): string {
+  return generateToken();
+}

package/src/component/lib/internalApi.ts

@@ -0,0 +1,66 @@
+import { anyApi } from "convex/server";
+import type { FunctionReference } from "convex/server";
+
+type InternalQuery = FunctionReference<"query", "internal">;
+type InternalMutation = FunctionReference<"mutation", "internal">;
+type InternalAction = FunctionReference<"action", "internal">;
+
+export const internal = anyApi as unknown as {
+  core: {
+    sessions: {
+      create: InternalMutation;
+      getByToken: InternalQuery;
+      validate: InternalAction;
+      extend: InternalMutation;
+      invalidateByHash: InternalMutation;
+      invalidateByToken: InternalMutation;
+      invalidateAll: InternalMutation;
+    };
+    users: {
+      create: InternalMutation;
+      getByEmail: InternalQuery;
+      getById: InternalQuery;
+      update: InternalMutation;
+      createAccount: InternalMutation;
+      getAccount: InternalQuery;
+      updateAccount: InternalMutation;
+    };
+    verifications: {
+      create: InternalMutation;
+      verify: InternalMutation;
+      cleanup: InternalMutation;
+    };
+  };
+  lib: {
+    rateLimit: {
+      check: InternalQuery;
+      increment: InternalMutation;
+      reset: InternalMutation;
+    };
+  };
+  providers: {
+    emailPassword: {
+      signUp: InternalAction;
+      signIn: InternalAction;
+      verifyEmail: InternalAction;
+      requestPasswordReset: InternalAction;
+      resetPassword: InternalAction;
+      updatePasswordHash: InternalMutation;
+    };
+    oauth: {
+      getAuthorizationUrl: InternalAction;
+      handleCallback: InternalAction;
+      storeOAuthState: InternalMutation;
+      consumeOAuthState: InternalMutation;
+    };
+  };
+  plugins: {
+    admin: {
+      listUsers: InternalQuery;
+      banUser: InternalMutation;
+      unbanUser: InternalMutation;
+      setRole: InternalMutation;
+      deleteUser: InternalMutation;
+    };
+  };
+};

package/src/component/lib/rateLimit.ts

@@ -0,0 +1,111 @@
+import { v } from "convex/values";
+import { internalMutation, internalQuery } from "../_generated/server";
+
+/** Window duration: 10 minutes in milliseconds. */
+const WINDOW_MS = 10 * 60 * 1000;
+
+/** Max failures before lockout. */
+const MAX_FAILURES = 10;
+
+/** Lockout duration: 10 minutes. */
+const LOCKOUT_MS = 10 * 60 * 1000;
+
+/**
+ * Check if a key is currently rate limited.
+ * Returns { limited: true, retryAfter } if locked, { limited: false } otherwise.
+ */
+export const check = internalQuery({
+  args: {
+    key: v.string(),
+  },
+  handler: async (ctx, { key }) => {
+    const now = Date.now();
+    const record = await ctx.db
+      .query("rateLimits")
+      .withIndex("by_key", (q) => q.eq("key", key))
+      .unique();
+
+    if (!record) {
+      return { limited: false as const };
+    }
+
+    // Check hard lockout
+    if (record.lockedUntil !== undefined && record.lockedUntil > now) {
+      return { limited: true as const, retryAfter: record.lockedUntil - now };
+    }
+
+    // Check sliding window count
+    const windowAge = now - record.windowStart;
+    if (windowAge < WINDOW_MS && record.count >= MAX_FAILURES) {
+      return { limited: true as const, retryAfter: WINDOW_MS - windowAge };
+    }
+
+    return { limited: false as const };
+  },
+});
+
+/**
+ * Increment failure count for a key. Applies lockout if threshold reached.
+ */
+export const increment = internalMutation({
+  args: {
+    key: v.string(),
+  },
+  handler: async (ctx, { key }) => {
+    const now = Date.now();
+    const record = await ctx.db
+      .query("rateLimits")
+      .withIndex("by_key", (q) => q.eq("key", key))
+      .unique();
+
+    if (!record) {
+      await ctx.db.insert("rateLimits", {
+        key,
+        count: 1,
+        windowStart: now,
+      });
+      return;
+    }
+
+    const windowAge = now - record.windowStart;
+    let newCount: number;
+    let windowStart: number;
+
+    if (windowAge >= WINDOW_MS) {
+      // New window
+      newCount = 1;
+      windowStart = now;
+    } else {
+      newCount = record.count + 1;
+      windowStart = record.windowStart;
+    }
+
+    const lockedUntil =
+      newCount >= MAX_FAILURES ? now + LOCKOUT_MS : record.lockedUntil;
+
+    await ctx.db.patch(record._id, {
+      count: newCount,
+      windowStart,
+      lockedUntil,
+    });
+  },
+});
+
+/**
+ * Reset rate limit for a key (called on successful auth).
+ */
+export const reset = internalMutation({
+  args: {
+    key: v.string(),
+  },
+  handler: async (ctx, { key }) => {
+    const record = await ctx.db
+      .query("rateLimits")
+      .withIndex("by_key", (q) => q.eq("key", key))
+      .unique();
+
+    if (record) {
+      await ctx.db.delete(record._id);
+    }
+  },
+});

package/src/component/lib/validators.ts

@@ -0,0 +1,12 @@
+import { v } from "convex/values";
+
+/** Runtime validator for OAuth provider configuration payloads. */
+export const oauthProviderConfigValidator = v.object({
+  id: v.string(),
+  clientId: v.string(),
+  clientSecret: v.string(),
+  authorizationUrl: v.string(),
+  tokenUrl: v.string(),
+  userInfoUrl: v.string(),
+  scopes: v.array(v.string()),
+});

package/src/component/plugins/admin.ts

@@ -0,0 +1,178 @@
+import { v } from "convex/values";
+import { internalMutation, internalQuery } from "../_generated/server";
+import type { Id } from "../_generated/dataModel";
+
+async function assertAdminActor(
+  ctx: { db: { get: (id: Id<"users">) => Promise<{ role?: string } | null> } },
+  actorUserId: Id<"users">
+): Promise<void> {
+  const actor = await ctx.db.get(actorUserId);
+  if (!actor) {
+    throw new Error("Unauthorized");
+  }
+  if (actor.role !== "admin") {
+    throw new Error("Forbidden");
+  }
+}
+
+/** List users with cursor-based pagination.
+ *
+ * paginate() is not available in components, so we use _creationTime as a
+ * cursor with .filter() + .take(). The cursor is a stringified _creationTime.
+ */
+export const listUsers = internalQuery({
+  args: {
+    actorUserId: v.id("users"),
+    limit: v.optional(v.number()),
+    cursor: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    await assertAdminActor(ctx, args.actorUserId);
+
+    const limit = args.limit ?? 20;
+
+    let query = ctx.db.query("users").order("asc");
+
+    if (args.cursor) {
+      const cursorTime = parseFloat(args.cursor);
+      query = query.filter((q) =>
+        q.gt(q.field("_creationTime"), cursorTime)
+      );
+    }
+
+    const rows = await query.take(limit + 1);
+    const hasMore = rows.length > limit;
+    const page = hasMore ? rows.slice(0, limit) : rows;
+    const last = page.at(-1);
+    const nextCursor =
+      hasMore && last
+        ? String(last._creationTime)
+        : null;
+
+    return {
+      users: page,
+      cursor: nextCursor,
+      isDone: !hasMore,
+    };
+  },
+});
+
+/** Get a single user by ID (admin view). */
+export const getUser = internalQuery({
+  args: {
+    actorUserId: v.id("users"),
+    userId: v.id("users"),
+  },
+  handler: async (ctx, { actorUserId, userId }) => {
+    await assertAdminActor(ctx, actorUserId);
+    return await ctx.db.get(userId);
+  },
+});
+
+/**
+ * Ban a user. Sets banned=true, banReason, and optional banExpires.
+ * Also invalidates all active sessions.
+ */
+export const banUser = internalMutation({
+  args: {
+    actorUserId: v.id("users"),
+    userId: v.id("users"),
+    reason: v.optional(v.string()),
+    expiresAt: v.optional(v.number()), // timestamp; undefined = permanent
+  },
+  handler: async (ctx, { actorUserId, userId, reason, expiresAt }) => {
+    await assertAdminActor(ctx, actorUserId);
+
+    const user = await ctx.db.get(userId);
+    if (!user) throw new Error("User not found");
+
+    await ctx.db.patch(userId, {
+      banned: true,
+      banReason: reason,
+      banExpires: expiresAt,
+      updatedAt: Date.now(),
+    });
+
+    // Invalidate all active sessions
+    const sessions = await ctx.db
+      .query("sessions")
+      .withIndex("by_userId", (q) => q.eq("userId", userId))
+      .collect();
+    for (const session of sessions) {
+      await ctx.db.delete(session._id);
+    }
+  },
+});
+
+/** Unban a user. Clears ban fields. */
+export const unbanUser = internalMutation({
+  args: {
+    actorUserId: v.id("users"),
+    userId: v.id("users"),
+  },
+  handler: async (ctx, { actorUserId, userId }) => {
+    await assertAdminActor(ctx, actorUserId);
+
+    const user = await ctx.db.get(userId);
+    if (!user) throw new Error("User not found");
+
+    await ctx.db.patch(userId, {
+      banned: false,
+      banReason: undefined,
+      banExpires: undefined,
+      updatedAt: Date.now(),
+    });
+  },
+});
+
+/** Set a user's role. */
+export const setRole = internalMutation({
+  args: {
+    actorUserId: v.id("users"),
+    userId: v.id("users"),
+    role: v.string(),
+  },
+  handler: async (ctx, { actorUserId, userId, role }) => {
+    await assertAdminActor(ctx, actorUserId);
+
+    const user = await ctx.db.get(userId);
+    if (!user) throw new Error("User not found");
+
+    await ctx.db.patch(userId, {
+      role,
+      updatedAt: Date.now(),
+    });
+  },
+});
+
+/** Delete a user and all associated data. */
+export const deleteUser = internalMutation({
+  args: {
+    actorUserId: v.id("users"),
+    userId: v.id("users"),
+  },
+  handler: async (ctx, { actorUserId, userId }) => {
+    await assertAdminActor(ctx, actorUserId);
+
+    // Delete accounts
+    const accounts = await ctx.db
+      .query("accounts")
+      .withIndex("by_userId", (q) => q.eq("userId", userId))
+      .collect();
+    for (const account of accounts) {
+      await ctx.db.delete(account._id);
+    }
+
+    // Delete sessions
+    const sessions = await ctx.db
+      .query("sessions")
+      .withIndex("by_userId", (q) => q.eq("userId", userId))
+      .collect();
+    for (const session of sessions) {
+      await ctx.db.delete(session._id);
+    }
+
+    // Delete the user
+    await ctx.db.delete(userId);
+  },
+});