convex-zen 0.0.1

package/src/client/plugins/admin.ts

@@ -0,0 +1,205 @@
+import type { AdminPluginConfig } from "../../types";
+
+/**
+ * Create an admin plugin configuration.
+ *
+ * @example
+ * ```ts
+ * import { adminPlugin } from "convex-zen/plugins/admin";
+ *
+ * export const auth = new ConvexAuth(components.convexAuth, {
+ *   plugins: [adminPlugin({ defaultRole: "user", adminRole: "admin" })],
+ * });
+ * ```
+ */
+export function adminPlugin(config?: {
+  defaultRole?: string;
+  adminRole?: string;
+}): AdminPluginConfig {
+  const plugin: AdminPluginConfig = {
+    id: "admin",
+  };
+  if (config?.defaultRole !== undefined) {
+    plugin.defaultRole = config.defaultRole;
+  }
+  if (config?.adminRole !== undefined) {
+    plugin.adminRole = config.adminRole;
+  }
+  return plugin;
+}
+
+/**
+ * AdminPlugin client class — exposes admin operations as typed methods.
+ * Obtained via `auth.plugins.admin` after ConvexAuth is initialized with adminPlugin.
+ */
+export class AdminPlugin {
+  constructor(
+    private readonly componentApi: Record<string, unknown>,
+    private readonly config: AdminPluginConfig
+  ) {}
+
+  /**
+   * Resolve a nested component function reference from a path string.
+   * e.g. "plugins/admin:listUsers" → component.plugins.admin.listUsers
+   */
+  private fn(path: string): unknown {
+    const [modulePath, funcName] = path.split(":");
+    if (!modulePath || !funcName) {
+      throw new Error(`Invalid function path: ${path}`);
+    }
+    const parts = modulePath.split("/");
+    let ref: Record<string, unknown> = this.componentApi;
+    for (const part of parts) {
+      const next = ref[part];
+      if (
+        !next ||
+        typeof next !== "object" ||
+        Array.isArray(next)
+      ) {
+        throw new Error(`Invalid function path segment: ${part}`);
+      }
+      ref = next as Record<string, unknown>;
+    }
+    const resolved = ref[funcName];
+    if (!resolved) {
+      throw new Error(`Function not found: ${path}`);
+    }
+    return resolved;
+  }
+
+  private getAdminToken(args: { adminToken?: string; token?: string }): string {
+    const token = args.adminToken ?? args.token;
+    if (!token) {
+      throw new Error("adminToken is required");
+    }
+    return token;
+  }
+
+  private stringifyError(error: unknown): string {
+    const errorObj = error as { message?: unknown; data?: unknown } | null;
+    return [
+      error instanceof Error ? error.message : "",
+      typeof errorObj?.message === "string" ? errorObj.message : "",
+      typeof errorObj?.data === "string"
+        ? errorObj.data
+        : errorObj?.data
+          ? JSON.stringify(errorObj.data)
+          : "",
+      String(error),
+    ]
+      .filter(Boolean)
+      .join(" | ");
+  }
+
+  private isRetryableGatewayShapeError(error: unknown): boolean {
+    const details = this.stringifyError(error);
+    return (
+      details.includes("Object contains extra field") ||
+      details.includes("ArgumentValidationError") ||
+      details.includes("Server Error")
+    );
+  }
+
+  private async runAdminGatewayAction(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ctx: { runAction: (fn: any, args: any) => Promise<any> },
+    path: string,
+    args: Record<string, unknown> & { adminToken?: string; token?: string }
+  ) {
+    const adminToken = this.getAdminToken(args);
+    const payload = { ...args };
+    delete payload.adminToken;
+    delete payload.token;
+
+    const attempts = [
+      { ...payload, adminToken },
+      payload,
+      { ...payload, token: adminToken },
+    ];
+
+    let lastError: unknown = null;
+    for (let i = 0; i < attempts.length; i += 1) {
+      const attempt = attempts[i];
+      try {
+        return await ctx.runAction(this.fn(path), attempt);
+      } catch (error) {
+        const isLastAttempt = i === attempts.length - 1;
+        if (isLastAttempt || !this.isRetryableGatewayShapeError(error)) {
+          throw error;
+        }
+        lastError = error;
+      }
+    }
+
+    throw lastError ?? new Error(`Failed to call admin action: ${path}`);
+  }
+
+  /**
+   * List users with pagination.
+   */
+  async listUsers(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ctx: { runAction: (fn: any, args: any) => Promise<any> },
+    args: { adminToken?: string; token?: string; limit?: number; cursor?: string }
+  ) {
+    return this.runAdminGatewayAction(ctx, "gateway:adminListUsers", args);
+  }
+
+  /**
+   * Ban a user, invalidating all their sessions.
+   */
+  async banUser(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ctx: { runAction: (fn: any, args: any) => Promise<any> },
+    args: {
+      adminToken?: string;
+      token?: string;
+      userId: string;
+      reason?: string;
+      expiresAt?: number;
+    }
+  ) {
+    return this.runAdminGatewayAction(ctx, "gateway:adminBanUser", args);
+  }
+
+  /**
+   * Unban a user.
+   */
+  async unbanUser(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ctx: { runAction: (fn: any, args: any) => Promise<any> },
+    args: { adminToken?: string; token?: string; userId: string }
+  ) {
+    return this.runAdminGatewayAction(ctx, "gateway:adminUnbanUser", args);
+  }
+
+  /**
+   * Set a user's role.
+   */
+  async setRole(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ctx: { runAction: (fn: any, args: any) => Promise<any> },
+    args: { adminToken?: string; token?: string; userId: string; role: string }
+  ) {
+    return this.runAdminGatewayAction(ctx, "gateway:adminSetRole", args);
+  }
+
+  /**
+   * Permanently delete a user and all associated data.
+   */
+  async deleteUser(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ctx: { runAction: (fn: any, args: any) => Promise<any> },
+    args: { adminToken?: string; token?: string; userId: string }
+  ) {
+    return this.runAdminGatewayAction(ctx, "gateway:adminDeleteUser", args);
+  }
+
+  get defaultRole() {
+    return this.config.defaultRole;
+  }
+
+  get adminRole() {
+    return this.config.adminRole;
+  }
+}

package/src/client/primitives.ts

@@ -0,0 +1,100 @@
+/**
+ * Framework-agnostic auth/session primitives.
+ *
+ * These helpers keep auth flow logic in one place so framework adapters
+ * (TanStack Start, Next.js, etc.) can stay thin.
+ */
+
+export interface SessionInfo {
+  userId: string;
+  sessionId: string;
+}
+
+export interface SignInInput {
+  email: string;
+  password: string;
+  ipAddress?: string;
+  userAgent?: string;
+}
+
+export interface SignInOutput {
+  sessionToken: string;
+  userId: string;
+}
+
+export interface SessionTransport {
+  signIn: (input: SignInInput) => Promise<SignInOutput>;
+  validateSession: (token: string) => Promise<SessionInfo | null>;
+  signOut: (token: string) => Promise<void>;
+}
+
+export interface EstablishedSession {
+  sessionToken: string;
+  session: SessionInfo;
+}
+
+/**
+ * Shared auth/session operations that can be reused by all framework adapters.
+ */
+export class SessionPrimitives {
+  constructor(private readonly transport: SessionTransport) {}
+
+  /**
+   * Resolve session details from a raw token.
+   */
+  async getSessionFromToken(
+    token: string | null | undefined
+  ): Promise<SessionInfo | null> {
+    if (!token) {
+      return null;
+    }
+    return this.transport.validateSession(token);
+  }
+
+  /**
+   * Resolve and require a valid session from a raw token.
+   * Throws "Unauthorized" if missing/invalid.
+   */
+  async requireSessionFromToken(token: string | null | undefined) {
+    const session = await this.getSessionFromToken(token);
+    if (!session) {
+      throw new Error("Unauthorized");
+    }
+    return session;
+  }
+
+  /**
+   * Sign in and immediately verify the returned token.
+   * This mirrors common auth library behavior where sign-in returns a token,
+   * and the framework layer then stores the token in a cookie.
+   */
+  async signInAndResolveSession(
+    input: SignInInput
+  ): Promise<EstablishedSession> {
+    const result = await this.transport.signIn(input);
+    const session = await this.transport.validateSession(result.sessionToken);
+
+    if (!session) {
+      throw new Error("Could not validate newly created session");
+    }
+
+    return {
+      sessionToken: result.sessionToken,
+      session,
+    };
+  }
+
+  /**
+   * Best-effort sign out by token.
+   */
+  async signOutByToken(token: string | null | undefined): Promise<void> {
+    if (!token) {
+      return;
+    }
+    await this.transport.signOut(token);
+  }
+}
+
+export function createSessionPrimitives(transport: SessionTransport) {
+  return new SessionPrimitives(transport);
+}

package/src/client/providers.ts

@@ -0,0 +1,35 @@
+import type { OAuthProviderConfig } from "../types";
+
+/** Create a Google OAuth provider configuration. */
+export function googleProvider(config: {
+  clientId: string;
+  clientSecret: string;
+  scopes?: string[];
+}): OAuthProviderConfig {
+  return {
+    id: "google",
+    clientId: config.clientId,
+    clientSecret: config.clientSecret,
+    authorizationUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+    tokenUrl: "https://oauth2.googleapis.com/token",
+    userInfoUrl: "https://www.googleapis.com/oauth2/v3/userinfo",
+    scopes: config.scopes ?? ["openid", "email", "profile"],
+  };
+}
+
+/** Create a GitHub OAuth provider configuration. */
+export function githubProvider(config: {
+  clientId: string;
+  clientSecret: string;
+  scopes?: string[];
+}): OAuthProviderConfig {
+  return {
+    id: "github",
+    clientId: config.clientId,
+    clientSecret: config.clientSecret,
+    authorizationUrl: "https://github.com/login/oauth/authorize",
+    tokenUrl: "https://github.com/login/oauth/access_token",
+    userInfoUrl: "https://api.github.com/user",
+    scopes: config.scopes ?? ["read:user", "user:email"],
+  };
+}

package/src/client/react.ts

@@ -0,0 +1,97 @@
+import {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from "react";
+import type { SessionInfo } from "./primitives";
+
+export type AuthStatus = "loading" | "authenticated" | "unauthenticated";
+
+export type AuthSession = SessionInfo;
+
+export interface ReactAuthClient {
+  getSession: () => Promise<AuthSession | null>;
+}
+
+export interface ConvexZenAuthContextValue {
+  status: AuthStatus;
+  session: AuthSession | null;
+  isAuthenticated: boolean;
+  refresh: () => Promise<AuthSession | null>;
+}
+
+export interface ConvexZenAuthProviderProps {
+  client: ReactAuthClient;
+  initialSession?: AuthSession | null;
+  children: ReactNode;
+}
+
+const AuthContext = createContext<ConvexZenAuthContextValue | null>(null);
+
+export function ConvexZenAuthProvider({
+  client,
+  initialSession,
+  children,
+}: ConvexZenAuthProviderProps) {
+  const [session, setSession] = useState<AuthSession | null>(
+    initialSession ?? null
+  );
+  const [status, setStatus] = useState<AuthStatus>(() => {
+    if (initialSession === undefined) {
+      return "loading";
+    }
+    return initialSession ? "authenticated" : "unauthenticated";
+  });
+
+  const refresh = useCallback(async () => {
+    setStatus("loading");
+    const next = await client.getSession();
+    setSession(next);
+    setStatus(next ? "authenticated" : "unauthenticated");
+    return next;
+  }, [client]);
+
+  useEffect(() => {
+    if (initialSession !== undefined) {
+      setSession(initialSession);
+      setStatus(initialSession ? "authenticated" : "unauthenticated");
+    }
+  }, [initialSession]);
+
+  useEffect(() => {
+    if (initialSession === undefined) {
+      void refresh();
+    }
+  }, [initialSession, refresh]);
+
+  const value = useMemo<ConvexZenAuthContextValue>(
+    () => ({
+      status,
+      session,
+      isAuthenticated: session !== null,
+      refresh,
+    }),
+    [status, session, refresh]
+  );
+
+  return createElement(AuthContext.Provider, { value }, children);
+}
+
+export function useConvexZenAuth(): ConvexZenAuthContextValue {
+  const context = useContext(AuthContext);
+  if (!context) {
+    throw new Error("useConvexZenAuth must be used within ConvexZenAuthProvider");
+  }
+  return context;
+}
+
+export const useAuth = useConvexZenAuth;
+
+export function useSession(): AuthSession | null {
+  return useConvexZenAuth().session;
+}

package/src/client/tanstack-start-client-plugins.ts

@@ -0,0 +1,113 @@
+import type { TanStackStartAuthApiClientPlugin } from "./tanstack-start-client";
+
+function normalizeRoutePrefix(prefix: string): string {
+  const trimmed = prefix.trim().replace(/^\/+|\/+$/g, "");
+  return trimmed.length > 0 ? trimmed : "admin";
+}
+
+export interface TanStackStartAdminListUsersInput {
+  limit?: number;
+  cursor?: string;
+}
+
+export interface TanStackStartAdminBanUserInput {
+  userId: string;
+  reason?: string;
+  expiresAt?: number;
+}
+
+export interface TanStackStartAdminSetRoleInput {
+  userId: string;
+  role: string;
+}
+
+export interface TanStackStartAdminUserIdInput {
+  userId: string;
+}
+
+export interface TanStackStartAdminClientPluginShape<
+  TListUsersOutput = unknown,
+  TBanUserOutput = unknown,
+  TSetRoleOutput = unknown,
+  TUnbanUserOutput = unknown,
+  TDeleteUserOutput = unknown,
+> {
+  admin: {
+    listUsers: (
+      input?: TanStackStartAdminListUsersInput
+    ) => Promise<TListUsersOutput>;
+    banUser: (input: TanStackStartAdminBanUserInput) => Promise<TBanUserOutput>;
+    setRole: (input: TanStackStartAdminSetRoleInput) => Promise<TSetRoleOutput>;
+    unbanUser: (input: TanStackStartAdminUserIdInput) => Promise<TUnbanUserOutput>;
+    deleteUser: (
+      input: TanStackStartAdminUserIdInput
+    ) => Promise<TDeleteUserOutput>;
+  };
+}
+
+export interface TanStackStartAdminClientPluginOptions {
+  routePrefix?: string;
+}
+
+/**
+ * Adds `authClient.admin.*` methods to the TanStack auth API client.
+ */
+export function adminClient<
+  TListUsersOutput = unknown,
+  TBanUserOutput = unknown,
+  TSetRoleOutput = unknown,
+  TUnbanUserOutput = unknown,
+  TDeleteUserOutput = unknown,
+>(
+  options: TanStackStartAdminClientPluginOptions = {}
+): TanStackStartAuthApiClientPlugin<
+  TanStackStartAdminClientPluginShape<
+    TListUsersOutput,
+    TBanUserOutput,
+    TSetRoleOutput,
+    TUnbanUserOutput,
+    TDeleteUserOutput
+  >
+> {
+  const routePrefix = normalizeRoutePrefix(options.routePrefix ?? "admin");
+
+  return {
+    id: "admin",
+    create: (context) => {
+      const post = async <T>(path: string, input: unknown, fallback: string) => {
+        return context.requestJson<T>(
+          `${routePrefix}/${path}`,
+          {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(input),
+          },
+          { fallback }
+        );
+      };
+
+      return {
+        admin: {
+          listUsers: async (input) =>
+            post<TListUsersOutput>(
+              "list-users",
+              input ?? {},
+              "Could not list users"
+            ),
+          banUser: async (input) =>
+            post<TBanUserOutput>("ban-user", input, "Could not ban user"),
+          setRole: async (input) =>
+            post<TSetRoleOutput>("set-role", input, "Could not set role"),
+          unbanUser: async (input) =>
+            post<TUnbanUserOutput>("unban-user", input, "Could not unban user"),
+          deleteUser: async (input) =>
+            post<TDeleteUserOutput>(
+              "delete-user",
+              input,
+              "Could not delete user"
+            ),
+        },
+      };
+    },
+  };
+}