convex-zen 0.0.1

package/src/component/core/users.ts

@@ -0,0 +1,199 @@
+import { v } from "convex/values";
+import { internalMutation, internalQuery } from "../_generated/server";
+
+/** Create a new user record. Returns the new user's ID. */
+export const create = internalMutation({
+  args: {
+    email: v.string(),
+    emailVerified: v.boolean(),
+    name: v.optional(v.string()),
+    image: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const userDoc: {
+      email: string;
+      emailVerified: boolean;
+      createdAt: number;
+      updatedAt: number;
+      name?: string;
+      image?: string;
+    } = {
+      email: args.email,
+      emailVerified: args.emailVerified,
+      createdAt: now,
+      updatedAt: now,
+    };
+    if (args.name !== undefined) {
+      userDoc.name = args.name;
+    }
+    if (args.image !== undefined) {
+      userDoc.image = args.image;
+    }
+
+    return await ctx.db.insert("users", userDoc);
+  },
+});
+
+/** Get a user by email address. Returns null if not found. */
+export const getByEmail = internalQuery({
+  args: { email: v.string() },
+  handler: async (ctx, { email }) => {
+    return await ctx.db
+      .query("users")
+      .withIndex("by_email", (q) => q.eq("email", email))
+      .unique();
+  },
+});
+
+/** Get a user by ID. Returns null if not found. */
+export const getById = internalQuery({
+  args: { userId: v.id("users") },
+  handler: async (ctx, { userId }) => {
+    return await ctx.db.get(userId);
+  },
+});
+
+/** Update mutable fields on a user. */
+export const update = internalMutation({
+  args: {
+    userId: v.id("users"),
+    email: v.optional(v.string()),
+    emailVerified: v.optional(v.boolean()),
+    name: v.optional(v.string()),
+    image: v.optional(v.string()),
+    role: v.optional(v.string()),
+    banned: v.optional(v.boolean()),
+    banReason: v.optional(v.string()),
+    banExpires: v.optional(v.number()),
+  },
+  handler: async (ctx, { userId, ...fields }) => {
+    const patch: Record<string, unknown> = { updatedAt: Date.now() };
+    for (const [key, value] of Object.entries(fields)) {
+      if (value !== undefined) {
+        patch[key] = value;
+      }
+    }
+    await ctx.db.patch(userId, patch);
+  },
+});
+
+/** Delete a user and all associated accounts and sessions. */
+export const remove = internalMutation({
+  args: { userId: v.id("users") },
+  handler: async (ctx, { userId }) => {
+    // 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 user
+    await ctx.db.delete(userId);
+  },
+});
+
+/** Create an account entry for a user. */
+export const createAccount = internalMutation({
+  args: {
+    userId: v.id("users"),
+    providerId: v.string(),
+    accountId: v.string(),
+    passwordHash: v.optional(v.string()),
+    accessToken: v.optional(v.string()),
+    refreshToken: v.optional(v.string()),
+    accessTokenExpiresAt: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const accountDoc: {
+      userId: typeof args.userId;
+      providerId: string;
+      accountId: string;
+      createdAt: number;
+      updatedAt: number;
+      passwordHash?: string;
+      accessToken?: string;
+      refreshToken?: string;
+      accessTokenExpiresAt?: number;
+    } = {
+      userId: args.userId,
+      providerId: args.providerId,
+      accountId: args.accountId,
+      createdAt: now,
+      updatedAt: now,
+    };
+    if (args.passwordHash !== undefined) {
+      accountDoc.passwordHash = args.passwordHash;
+    }
+    if (args.accessToken !== undefined) {
+      accountDoc.accessToken = args.accessToken;
+    }
+    if (args.refreshToken !== undefined) {
+      accountDoc.refreshToken = args.refreshToken;
+    }
+    if (args.accessTokenExpiresAt !== undefined) {
+      accountDoc.accessTokenExpiresAt = args.accessTokenExpiresAt;
+    }
+
+    return await ctx.db.insert("accounts", accountDoc);
+  },
+});
+
+/** Get an account by provider + accountId. */
+export const getAccount = internalQuery({
+  args: {
+    providerId: v.string(),
+    accountId: v.string(),
+  },
+  handler: async (ctx, { providerId, accountId }) => {
+    return await ctx.db
+      .query("accounts")
+      .withIndex("by_provider_accountId", (q) =>
+        q.eq("providerId", providerId).eq("accountId", accountId)
+      )
+      .unique();
+  },
+});
+
+/** Get all accounts for a user. */
+export const getAccountsByUserId = internalQuery({
+  args: { userId: v.id("users") },
+  handler: async (ctx, { userId }) => {
+    return await ctx.db
+      .query("accounts")
+      .withIndex("by_userId", (q) => q.eq("userId", userId))
+      .collect();
+  },
+});
+
+/** Update an account's tokens. */
+export const updateAccount = internalMutation({
+  args: {
+    accountId: v.id("accounts"),
+    accessToken: v.optional(v.string()),
+    refreshToken: v.optional(v.string()),
+    accessTokenExpiresAt: v.optional(v.number()),
+  },
+  handler: async (ctx, { accountId, ...fields }) => {
+    const patch: Record<string, unknown> = { updatedAt: Date.now() };
+    for (const [key, value] of Object.entries(fields)) {
+      if (value !== undefined) {
+        patch[key] = value;
+      }
+    }
+    await ctx.db.patch(accountId, patch);
+  },
+});

package/src/component/core/verifications.ts

@@ -0,0 +1,173 @@
+import { v } from "convex/values";
+import { internalMutation, internalQuery } from "../_generated/server";
+import { generateCode, hashToken } from "../lib/crypto";
+
+/** Max attempts before a verification code is locked. */
+const MAX_ATTEMPTS = 10;
+
+/** Email verification TTL: 60 minutes. */
+const EMAIL_VERIFICATION_TTL_MS = 60 * 60 * 1000;
+
+/** Password reset TTL: 15 minutes. */
+const PASSWORD_RESET_TTL_MS = 15 * 60 * 1000;
+
+/**
+ * Create a verification code for a given identifier and type.
+ * Any previous verification of the same type is replaced.
+ * Returns the raw code (to be sent to the user) and the expiry.
+ */
+export const create = internalMutation({
+  args: {
+    identifier: v.string(),
+    type: v.union(
+      v.literal("email-verification"),
+      v.literal("password-reset")
+    ),
+  },
+  handler: async (ctx, { identifier, type }) => {
+    const now = Date.now();
+    const code = generateCode();
+    const codeHash = await hashToken(code);
+    const ttl =
+      type === "email-verification"
+        ? EMAIL_VERIFICATION_TTL_MS
+        : PASSWORD_RESET_TTL_MS;
+    const expiresAt = now + ttl;
+
+    // Remove any existing verification of this type for this identifier
+    const existing = await ctx.db
+      .query("verifications")
+      .withIndex("by_identifier_type", (q) =>
+        q.eq("identifier", identifier).eq("type", type)
+      )
+      .unique();
+    if (existing) {
+      await ctx.db.delete(existing._id);
+    }
+
+    await ctx.db.insert("verifications", {
+      identifier,
+      type,
+      codeHash,
+      expiresAt,
+      attempts: 0,
+      createdAt: now,
+    });
+
+    return { code, expiresAt };
+  },
+});
+
+/**
+ * Get verification record without consuming it.
+ */
+export const getByIdentifierType = internalQuery({
+  args: {
+    identifier: v.string(),
+    type: v.union(
+      v.literal("email-verification"),
+      v.literal("password-reset")
+    ),
+  },
+  handler: async (ctx, { identifier, type }) => {
+    return await ctx.db
+      .query("verifications")
+      .withIndex("by_identifier_type", (q) =>
+        q.eq("identifier", identifier).eq("type", type)
+      )
+      .unique();
+  },
+});
+
+/**
+ * Verify a code for an identifier and type.
+ * Increments attempt count; invalidates after MAX_ATTEMPTS.
+ * Returns status: "valid" | "invalid" | "expired" | "too_many_attempts"
+ */
+export const verify = internalMutation({
+  args: {
+    identifier: v.string(),
+    type: v.union(
+      v.literal("email-verification"),
+      v.literal("password-reset")
+    ),
+    code: v.string(),
+  },
+  handler: async (ctx, { identifier, type, code }) => {
+    const record = await ctx.db
+      .query("verifications")
+      .withIndex("by_identifier_type", (q) =>
+        q.eq("identifier", identifier).eq("type", type)
+      )
+      .unique();
+
+    if (!record) {
+      return { status: "invalid" as const };
+    }
+
+    const now = Date.now();
+
+    if (record.expiresAt < now) {
+      await ctx.db.delete(record._id);
+      return { status: "expired" as const };
+    }
+
+    if (record.attempts >= MAX_ATTEMPTS) {
+      return { status: "too_many_attempts" as const };
+    }
+
+    const codeHash = await hashToken(code);
+
+    if (codeHash !== record.codeHash) {
+      // Increment attempts
+      await ctx.db.patch(record._id, { attempts: record.attempts + 1 });
+      if (record.attempts + 1 >= MAX_ATTEMPTS) {
+        return { status: "too_many_attempts" as const };
+      }
+      return { status: "invalid" as const };
+    }
+
+    // Valid — delete the verification (single-use)
+    await ctx.db.delete(record._id);
+    return { status: "valid" as const };
+  },
+});
+
+/** Delete a verification record (e.g., after successful use or on cancel). */
+export const invalidate = internalMutation({
+  args: {
+    identifier: v.string(),
+    type: v.union(
+      v.literal("email-verification"),
+      v.literal("password-reset")
+    ),
+  },
+  handler: async (ctx, { identifier, type }) => {
+    const record = await ctx.db
+      .query("verifications")
+      .withIndex("by_identifier_type", (q) =>
+        q.eq("identifier", identifier).eq("type", type)
+      )
+      .unique();
+    if (record) {
+      await ctx.db.delete(record._id);
+    }
+  },
+});
+
+/**
+ * Cleanup expired verifications (intended to be scheduled).
+ */
+export const cleanup = internalMutation({
+  args: {},
+  handler: async (ctx) => {
+    const now = Date.now();
+    // Collect and delete expired records
+    const allVerifications = await ctx.db.query("verifications").collect();
+    for (const v of allVerifications) {
+      if (v.expiresAt < now) {
+        await ctx.db.delete(v._id);
+      }
+    }
+  },
+});

package/src/component/gateway.ts

@@ -0,0 +1,321 @@
+/**
+ * Public gateway — the only functions callable from the host app.
+ *
+ * All functions are `action` (not `internalAction`) so they appear in the
+ * component's public API and can be reached via ctx.runAction / ctx.runQuery
+ * from the parent Convex backend. They simply delegate to the corresponding
+ * internal functions.
+ *
+ * Internal functions remain `internalAction`/`internalMutation`/`internalQuery`
+ * and are only callable from within this component.
+ */
+import { v } from "convex/values";
+import { action } from "./_generated/server";
+import type { Id } from "./_generated/dataModel";
+import { internal } from "./lib/internalApi";
+import { oauthProviderConfigValidator } from "./lib/validators";
+
+// ─── Email / Password ──────────────────────────────────────────────────────
+
+export const signUp = action({
+  args: {
+    email: v.string(),
+    password: v.string(),
+    name: v.optional(v.string()),
+    ipAddress: v.optional(v.string()),
+  },
+  handler: (ctx, args) =>
+    ctx.runAction(internal.providers.emailPassword.signUp, args),
+});
+
+export const signIn = action({
+  args: {
+    email: v.string(),
+    password: v.string(),
+    ipAddress: v.optional(v.string()),
+    userAgent: v.optional(v.string()),
+    requireEmailVerified: v.optional(v.boolean()),
+  },
+  handler: (ctx, args) =>
+    ctx.runAction(internal.providers.emailPassword.signIn, args),
+});
+
+export const verifyEmail = action({
+  args: {
+    email: v.string(),
+    code: v.string(),
+  },
+  handler: (ctx, args) =>
+    ctx.runAction(internal.providers.emailPassword.verifyEmail, args),
+});
+
+export const requestPasswordReset = action({
+  args: {
+    email: v.string(),
+    ipAddress: v.optional(v.string()),
+  },
+  handler: (ctx, args) =>
+    ctx.runAction(internal.providers.emailPassword.requestPasswordReset, args),
+});
+
+export const resetPassword = action({
+  args: {
+    email: v.string(),
+    code: v.string(),
+    newPassword: v.string(),
+  },
+  handler: (ctx, args) =>
+    ctx.runAction(internal.providers.emailPassword.resetPassword, args),
+});
+
+// ─── Sessions ──────────────────────────────────────────────────────────────
+
+export const validateSession = action({
+  args: {
+    token: v.string(),
+    checkBanned: v.optional(v.boolean()),
+  },
+  handler: (ctx, args) =>
+    ctx.runAction(internal.core.sessions.validate, args),
+});
+
+export const getCurrentUser = action({
+  args: {
+    token: v.string(),
+    checkBanned: v.optional(v.boolean()),
+  },
+  handler: async (ctx, { token, checkBanned }) => {
+    const session = await ctx.runAction(internal.core.sessions.validate, {
+      token,
+      checkBanned,
+    });
+    if (!session) {
+      return null;
+    }
+    return ctx.runQuery(internal.core.users.getById, {
+      userId: session.userId,
+    });
+  },
+});
+
+export const getUserById = action({
+  args: {
+    userId: v.string(),
+    checkBanned: v.optional(v.boolean()),
+  },
+  handler: async (ctx, { userId, checkBanned }) => {
+    const user = await ctx.runQuery(internal.core.users.getById, {
+      userId: userId as Id<"users">,
+    });
+    if (!user) {
+      return null;
+    }
+    if (!checkBanned || !user.banned) {
+      return user;
+    }
+
+    const now = Date.now();
+    const banExpires = user.banExpires;
+    if (banExpires === undefined || banExpires > now) {
+      return null;
+    }
+
+    // Temp ban expired — unban automatically.
+    await ctx.runMutation(internal.core.users.update, {
+      userId: userId as Id<"users">,
+      banned: false,
+    });
+
+    return ctx.runQuery(internal.core.users.getById, {
+      userId: userId as Id<"users">,
+    });
+  },
+});
+
+export const invalidateSession = action({
+  args: { token: v.string() },
+  handler: (ctx, args) =>
+    ctx.runMutation(internal.core.sessions.invalidateByToken, args),
+});
+
+export const invalidateAllSessions = action({
+  args: { userId: v.string() },
+  handler: (ctx, { userId }) =>
+    ctx.runMutation(internal.core.sessions.invalidateAll, {
+      userId: userId as Id<"users">,
+    }),
+});
+
+// ─── OAuth ─────────────────────────────────────────────────────────────────
+
+export const getAuthorizationUrl = action({
+  args: {
+    provider: oauthProviderConfigValidator,
+    redirectUrl: v.optional(v.string()),
+  },
+  handler: (ctx, args) =>
+    ctx.runAction(internal.providers.oauth.getAuthorizationUrl, args),
+});
+
+export const handleCallback = action({
+  args: {
+    provider: oauthProviderConfigValidator,
+    code: v.string(),
+    state: v.string(),
+    redirectUrl: v.optional(v.string()),
+    ipAddress: v.optional(v.string()),
+    userAgent: v.optional(v.string()),
+  },
+  handler: (ctx, args) =>
+    ctx.runAction(internal.providers.oauth.handleCallback, args),
+});
+
+// ─── Admin ─────────────────────────────────────────────────────────────────
+
+export const adminListUsers = action({
+  args: {
+    adminToken: v.string(),
+    limit: v.optional(v.number()),
+    cursor: v.optional(v.string()),
+  },
+  handler: async (ctx, { adminToken, limit, cursor }) => {
+    const session = await ctx.runAction(internal.core.sessions.validate, {
+      token: adminToken,
+      checkBanned: true,
+    });
+    if (!session) {
+      throw new Error("Unauthorized");
+    }
+
+    const adminUser = await ctx.runQuery(internal.core.users.getById, {
+      userId: session.userId,
+    });
+    if (!adminUser || adminUser.role !== "admin") {
+      throw new Error("Forbidden");
+    }
+
+    return ctx.runQuery(internal.plugins.admin.listUsers, {
+      actorUserId: session.userId,
+      limit,
+      cursor,
+    });
+  },
+});
+
+export const adminBanUser = action({
+  args: {
+    adminToken: v.string(),
+    userId: v.string(),
+    reason: v.optional(v.string()),
+    expiresAt: v.optional(v.number()),
+  },
+  handler: async (ctx, { adminToken, userId, reason, expiresAt }) => {
+    const session = await ctx.runAction(internal.core.sessions.validate, {
+      token: adminToken,
+      checkBanned: true,
+    });
+    if (!session) {
+      throw new Error("Unauthorized");
+    }
+
+    const adminUser = await ctx.runQuery(internal.core.users.getById, {
+      userId: session.userId,
+    });
+    if (!adminUser || adminUser.role !== "admin") {
+      throw new Error("Forbidden");
+    }
+
+    return ctx.runMutation(internal.plugins.admin.banUser, {
+      actorUserId: session.userId,
+      userId: userId as Id<"users">,
+      reason,
+      expiresAt,
+    });
+  },
+});
+
+export const adminUnbanUser = action({
+  args: {
+    adminToken: v.string(),
+    userId: v.string(),
+  },
+  handler: async (ctx, { adminToken, userId }) => {
+    const session = await ctx.runAction(internal.core.sessions.validate, {
+      token: adminToken,
+      checkBanned: true,
+    });
+    if (!session) {
+      throw new Error("Unauthorized");
+    }
+
+    const adminUser = await ctx.runQuery(internal.core.users.getById, {
+      userId: session.userId,
+    });
+    if (!adminUser || adminUser.role !== "admin") {
+      throw new Error("Forbidden");
+    }
+
+    return ctx.runMutation(internal.plugins.admin.unbanUser, {
+      actorUserId: session.userId,
+      userId: userId as Id<"users">,
+    });
+  },
+});
+
+export const adminSetRole = action({
+  args: {
+    adminToken: v.string(),
+    userId: v.string(),
+    role: v.string(),
+  },
+  handler: async (ctx, { adminToken, userId, role }) => {
+    const session = await ctx.runAction(internal.core.sessions.validate, {
+      token: adminToken,
+      checkBanned: true,
+    });
+    if (!session) {
+      throw new Error("Unauthorized");
+    }
+
+    const adminUser = await ctx.runQuery(internal.core.users.getById, {
+      userId: session.userId,
+    });
+    if (!adminUser || adminUser.role !== "admin") {
+      throw new Error("Forbidden");
+    }
+
+    return ctx.runMutation(internal.plugins.admin.setRole, {
+      actorUserId: session.userId,
+      userId: userId as Id<"users">,
+      role,
+    });
+  },
+});
+
+export const adminDeleteUser = action({
+  args: {
+    adminToken: v.string(),
+    userId: v.string(),
+  },
+  handler: async (ctx, { adminToken, userId }) => {
+    const session = await ctx.runAction(internal.core.sessions.validate, {
+      token: adminToken,
+      checkBanned: true,
+    });
+    if (!session) {
+      throw new Error("Unauthorized");
+    }
+
+    const adminUser = await ctx.runQuery(internal.core.users.getById, {
+      userId: session.userId,
+    });
+    if (!adminUser || adminUser.role !== "admin") {
+      throw new Error("Forbidden");
+    }
+
+    return ctx.runMutation(internal.plugins.admin.deleteUser, {
+      actorUserId: session.userId,
+      userId: userId as Id<"users">,
+    });
+  },
+});