convex-zen 0.0.1

package/dist/client/index.js

@@ -0,0 +1,434 @@
+import { AdminPlugin } from "./plugins/admin";
+/**
+ * ConvexAuth — the main integration class for convex-zen.
+ *
+ * Instantiate once in the host app with the component reference and config.
+ * All auth operations go through this class.
+ *
+ * @example
+ * ```ts
+ * // convex/auth.ts
+ * import { ConvexAuth, googleProvider } from "convex-zen";
+ * import { adminPlugin } from "convex-zen/plugins/admin";
+ * import { components } from "./_generated/api";
+ *
+ * export const auth = new ConvexAuth(components.convexAuth, {
+ *   providers: [googleProvider({ clientId: "...", clientSecret: "..." })],
+ *   emailProvider: {
+ *     sendVerificationEmail: async (to, code) => { ... },
+ *     sendPasswordResetEmail: async (to, code) => { ... },
+ *   },
+ *   plugins: [adminPlugin({ defaultRole: "user" })],
+ * });
+ * ```
+ */
+export class ConvexAuth {
+    component;
+    options;
+    _adminPlugin;
+    providerMap;
+    adminConfig;
+    constructor(component, options = {}) {
+        this.component = component;
+        this.options = options;
+        this.providerMap = new Map((options.providers ?? []).map((p) => [p.id, p]));
+        this.adminConfig =
+            options.plugins?.find((p) => p.id === "admin") ?? null;
+        this._adminPlugin = this.adminConfig
+            ? new AdminPlugin(component, this.adminConfig)
+            : null;
+    }
+    /** Access plugin instances after initialization. */
+    get plugins() {
+        return {
+            admin: this._adminPlugin,
+        };
+    }
+    /** Alias for plugins to support auth.plugin.admin style access. */
+    get plugin() {
+        return this.plugins;
+    }
+    /** Admin facade on the auth object (no separate authSystem object required). */
+    get admin() {
+        if (!this._adminPlugin) {
+            return null;
+        }
+        return {
+            listUsers: async (ctx, args = {}) => {
+                const adminToken = await this.requireResolvedToken(ctx, args.token);
+                const payload = { adminToken };
+                if (args.limit !== undefined) {
+                    payload.limit = args.limit;
+                }
+                if (args.cursor !== undefined) {
+                    payload.cursor = args.cursor;
+                }
+                return this._adminPlugin.listUsers(ctx, payload);
+            },
+            banUser: async (ctx, args) => {
+                const adminToken = await this.requireResolvedToken(ctx, args.token);
+                const payload = {
+                    adminToken,
+                    userId: args.userId,
+                };
+                if (args.reason !== undefined) {
+                    payload.reason = args.reason;
+                }
+                if (args.expiresAt !== undefined) {
+                    payload.expiresAt = args.expiresAt;
+                }
+                return this._adminPlugin.banUser(ctx, payload);
+            },
+            unbanUser: async (ctx, args) => {
+                const adminToken = await this.requireResolvedToken(ctx, args.token);
+                return this._adminPlugin.unbanUser(ctx, {
+                    adminToken,
+                    userId: args.userId,
+                });
+            },
+            setRole: async (ctx, args) => {
+                const adminToken = await this.requireResolvedToken(ctx, args.token);
+                return this._adminPlugin.setRole(ctx, {
+                    adminToken,
+                    userId: args.userId,
+                    role: args.role,
+                });
+            },
+            deleteUser: async (ctx, args) => {
+                const adminToken = await this.requireResolvedToken(ctx, args.token);
+                return this._adminPlugin.deleteUser(ctx, {
+                    adminToken,
+                    userId: args.userId,
+                });
+            },
+        };
+    }
+    /** Session helpers available directly on auth object. */
+    get session() {
+        return {
+            validate: async (ctx, token) => {
+                return this.safeValidateSession(ctx, token);
+            },
+            require: async (ctx, token) => {
+                return this.requireAuthSession(ctx, token);
+            },
+        };
+    }
+    /** Authenticated user helpers available directly on auth object. */
+    get user() {
+        return {
+            safeGet: async (ctx, token) => {
+                return this.safeGetAuthUser(ctx, token);
+            },
+            require: async (ctx, token) => {
+                return this.requireAuthUser(ctx, token);
+            },
+        };
+    }
+    /**
+     * Register OAuth callback HTTP routes on the host's router.
+     * Mounts GET `/auth/callback/:provider` for each configured OAuth provider.
+     *
+     * @example
+     * ```ts
+     * // convex/http.ts
+     * import { httpRouter } from "convex/server";
+     * import { auth } from "./auth";
+     * const http = httpRouter();
+     * auth.registerRoutes(http);
+     * export default http;
+     * ```
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    registerRoutes(http, options) {
+        for (const provider of this.providerMap.values()) {
+            const path = `/auth/callback/${provider.id}`;
+            http.route({
+                path,
+                method: "GET",
+                handler: async (req) => {
+                    const url = new URL(req.url);
+                    const code = url.searchParams.get("code");
+                    const state = url.searchParams.get("state");
+                    const error = url.searchParams.get("error");
+                    if (error) {
+                        return new Response(JSON.stringify({ error }), {
+                            status: 400,
+                            headers: { "Content-Type": "application/json" },
+                        });
+                    }
+                    if (!code || !state) {
+                        return new Response(JSON.stringify({ error: "Missing code or state" }), { status: 400, headers: { "Content-Type": "application/json" } });
+                    }
+                    // Note: HTTP handlers can't use ctx directly.
+                    // Host app should use a Convex HTTP action that calls auth.handleCallback.
+                    // This default handler returns the raw data for the host to process.
+                    return new Response(JSON.stringify({
+                        code,
+                        state,
+                        provider: provider.id,
+                        callbackUrl: options?.callbackBaseUrl
+                            ? `${options.callbackBaseUrl}${path}`
+                            : undefined,
+                    }), {
+                        status: 200,
+                        headers: { "Content-Type": "application/json" },
+                    });
+                },
+            });
+        }
+    }
+    /**
+     * Sign up a new user with email and password.
+     * Generates a verification code and sends it via the configured emailProvider.
+     * Call from a Convex action in the host app.
+     */
+    async signUp(ctx, args) {
+        if (!this.options.emailProvider) {
+            throw new Error("emailProvider is required for email/password auth");
+        }
+        const result = (await ctx.runAction(this.fn("gateway:signUp"), args));
+        // Send email from host app context (functions can't be Convex args)
+        await this.options.emailProvider.sendVerificationEmail(args.email, result.verificationCode);
+        return { status: "verification_required" };
+    }
+    /**
+     * Sign in with email and password.
+     * Call from a Convex action in the host app.
+     */
+    async signIn(ctx, args) {
+        return ctx.runAction(this.fn("gateway:signIn"), {
+            ...args,
+            requireEmailVerified: this.options.requireEmailVerified ?? true,
+        });
+    }
+    /**
+     * Verify email with a verification code.
+     */
+    async verifyEmail(ctx, args) {
+        return ctx.runAction(this.fn("gateway:verifyEmail"), args);
+    }
+    /**
+     * Request a password reset. Sends the reset code via emailProvider.
+     */
+    async requestPasswordReset(ctx, args) {
+        if (!this.options.emailProvider) {
+            throw new Error("emailProvider is required for password reset");
+        }
+        const result = (await ctx.runAction(this.fn("gateway:requestPasswordReset"), args));
+        if (result.resetCode) {
+            await this.options.emailProvider.sendPasswordResetEmail(args.email, result.resetCode);
+        }
+        return { status: "sent" };
+    }
+    /**
+     * Reset password using a verification code.
+     */
+    async resetPassword(ctx, args) {
+        return ctx.runAction(this.fn("gateway:resetPassword"), args);
+    }
+    /**
+     * Get an OAuth authorization URL for the given provider.
+     * Call from a Convex action.
+     */
+    async getOAuthUrl(ctx, providerId, redirectUrl) {
+        const provider = this.providerMap.get(providerId);
+        if (!provider) {
+            throw new Error(`OAuth provider "${providerId}" not configured`);
+        }
+        return ctx.runAction(this.fn("gateway:getAuthorizationUrl"), {
+            provider,
+            redirectUrl,
+        });
+    }
+    /**
+     * Handle an OAuth callback. Call from a Convex HTTP action.
+     * Validates state, exchanges code for tokens, upserts user, creates session.
+     */
+    async handleCallback(ctx, args) {
+        const provider = this.providerMap.get(args.providerId);
+        if (!provider) {
+            throw new Error(`OAuth provider "${args.providerId}" not configured`);
+        }
+        return ctx.runAction(this.fn("gateway:handleCallback"), {
+            provider,
+            code: args.code,
+            state: args.state,
+            redirectUrl: args.redirectUrl,
+            ipAddress: args.ipAddress,
+            userAgent: args.userAgent,
+        });
+    }
+    /**
+     * Validate a session token. Returns user/session IDs or null.
+     * Can be called from queries, mutations, or actions.
+     */
+    async validateSession(ctx, token) {
+        return ctx.runAction(this.fn("gateway:validateSession"), {
+            token,
+            checkBanned: this.adminConfig !== null,
+        });
+    }
+    /**
+     * Validate session, resolving token from context when one is not provided.
+     */
+    async safeValidateSession(ctx, token) {
+        const resolvedToken = await this.resolveToken(ctx, token);
+        if (!resolvedToken) {
+            return null;
+        }
+        return this.validateSession(ctx, resolvedToken);
+    }
+    /**
+     * Validate session and throw when missing/invalid.
+     */
+    async requireAuthSession(ctx, token) {
+        const session = await this.safeValidateSession(ctx, token);
+        if (!session) {
+            throw new Error("Unauthorized");
+        }
+        return session;
+    }
+    /**
+     * Resolve the current signed-in user from a session token.
+     * Returns null when token is invalid/expired/banned.
+     */
+    async getAuthUserFromToken(ctx, token) {
+        return ctx.runAction(this.fn("gateway:getCurrentUser"), {
+            token,
+            checkBanned: this.adminConfig !== null,
+        });
+    }
+    /**
+     * Resolve authenticated user from `ctx` if possible.
+     * Resolution order:
+     * 1. explicit token argument
+     * 2. resolveSessionToken option
+     * 3. identity claims (session token-like fields)
+     * 4. resolveUserId option
+     * 5. `ctx.auth.getUserIdentity()?.subject`
+     */
+    async safeGetAuthUser(ctx, token) {
+        const resolvedToken = await this.resolveToken(ctx, token);
+        if (resolvedToken) {
+            return this.getAuthUserFromToken(ctx, resolvedToken);
+        }
+        const userId = await this.resolveUserId(ctx);
+        if (!userId) {
+            return null;
+        }
+        return ctx.runAction(this.fn("gateway:getUserById"), {
+            userId,
+            checkBanned: this.adminConfig !== null,
+        });
+    }
+    /**
+     * Resolve current user and throw if unauthenticated.
+     */
+    async requireAuthUser(ctx, token) {
+        const user = await this.safeGetAuthUser(ctx, token);
+        if (!user) {
+            throw new Error("Unauthorized");
+        }
+        return user;
+    }
+    /**
+     * Sign out by invalidating a session token.
+     * Can be called from a mutation or action context.
+     */
+    async signOut(ctx, token) {
+        await ctx.runAction(this.fn("gateway:invalidateSession"), { token });
+    }
+    /**
+     * Sign out all sessions for a user.
+     */
+    async signOutAll(ctx, userId) {
+        await ctx.runAction(this.fn("gateway:invalidateAllSessions"), { userId });
+    }
+    async getIdentity(ctx) {
+        const auth = ctx
+            .auth;
+        if (!auth?.getUserIdentity) {
+            return null;
+        }
+        const identity = await auth.getUserIdentity();
+        if (!identity || typeof identity !== "object") {
+            return null;
+        }
+        return identity;
+    }
+    getStringClaim(identity, claim) {
+        if (!identity) {
+            return null;
+        }
+        const value = identity[claim];
+        return typeof value === "string" && value.length > 0 ? value : null;
+    }
+    async resolveToken(ctx, explicitToken) {
+        if (explicitToken) {
+            return explicitToken;
+        }
+        const tokenFromResolver = await this.options.resolveSessionToken?.(ctx);
+        if (tokenFromResolver) {
+            return tokenFromResolver;
+        }
+        const identity = await this.getIdentity(ctx);
+        return (this.getStringClaim(identity, "sessionToken") ??
+            this.getStringClaim(identity, "token") ??
+            this.getStringClaim(identity, "https://convex-zen.dev/sessionToken") ??
+            null);
+    }
+    async requireResolvedToken(ctx, explicitToken) {
+        const token = await this.resolveToken(ctx, explicitToken);
+        if (!token) {
+            throw new Error("Unauthorized");
+        }
+        return token;
+    }
+    async resolveUserId(ctx) {
+        const userIdFromResolver = await this.options.resolveUserId?.(ctx);
+        if (userIdFromResolver) {
+            return userIdFromResolver;
+        }
+        const identity = await this.getIdentity(ctx);
+        if (!identity) {
+            return null;
+        }
+        if (typeof identity.subject === "string" && identity.subject.length > 0) {
+            return identity.subject;
+        }
+        return this.getStringClaim(identity, "userId");
+    }
+    /**
+     * Resolve a component function reference by path string.
+     * Converts "providers/emailPassword:signUp" into
+     * component.providers.emailPassword.signUp via nested property traversal.
+     */
+    fn(path) {
+        const [modulePath, funcName] = path.split(":");
+        if (!modulePath || !funcName) {
+            throw new Error(`Invalid function path: ${path}`);
+        }
+        const parts = modulePath.split("/");
+        let ref = this.component;
+        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;
+        }
+        const resolved = ref[funcName];
+        if (!resolved) {
+            throw new Error(`Function not found: ${path}`);
+        }
+        return resolved;
+    }
+}
+// Named exports for convenience
+export { googleProvider, githubProvider } from "./providers";
+export { adminPlugin } from "./plugins/admin";
+export { SessionPrimitives, createSessionPrimitives, } from "./primitives";
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"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"}

package/dist/client/plugins/admin.d.ts

@@ -0,0 +1,92 @@
+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 declare function adminPlugin(config?: {
+    defaultRole?: string;
+    adminRole?: string;
+}): AdminPluginConfig;
+/**
+ * AdminPlugin client class — exposes admin operations as typed methods.
+ * Obtained via `auth.plugins.admin` after ConvexAuth is initialized with adminPlugin.
+ */
+export declare class AdminPlugin {
+    private readonly componentApi;
+    private readonly config;
+    constructor(componentApi: Record<string, unknown>, config: AdminPluginConfig);
+    /**
+     * Resolve a nested component function reference from a path string.
+     * e.g. "plugins/admin:listUsers" → component.plugins.admin.listUsers
+     */
+    private fn;
+    private getAdminToken;
+    private stringifyError;
+    private isRetryableGatewayShapeError;
+    private runAdminGatewayAction;
+    /**
+     * List users with pagination.
+     */
+    listUsers(ctx: {
+        runAction: (fn: any, args: any) => Promise<any>;
+    }, args: {
+        adminToken?: string;
+        token?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<any>;
+    /**
+     * Ban a user, invalidating all their sessions.
+     */
+    banUser(ctx: {
+        runAction: (fn: any, args: any) => Promise<any>;
+    }, args: {
+        adminToken?: string;
+        token?: string;
+        userId: string;
+        reason?: string;
+        expiresAt?: number;
+    }): Promise<any>;
+    /**
+     * Unban a user.
+     */
+    unbanUser(ctx: {
+        runAction: (fn: any, args: any) => Promise<any>;
+    }, args: {
+        adminToken?: string;
+        token?: string;
+        userId: string;
+    }): Promise<any>;
+    /**
+     * Set a user's role.
+     */
+    setRole(ctx: {
+        runAction: (fn: any, args: any) => Promise<any>;
+    }, args: {
+        adminToken?: string;
+        token?: string;
+        userId: string;
+        role: string;
+    }): Promise<any>;
+    /**
+     * Permanently delete a user and all associated data.
+     */
+    deleteUser(ctx: {
+        runAction: (fn: any, args: any) => Promise<any>;
+    }, args: {
+        adminToken?: string;
+        token?: string;
+        userId: string;
+    }): Promise<any>;
+    get defaultRole(): string | undefined;
+    get adminRole(): string | undefined;
+}
+//# sourceMappingURL=admin.d.ts.map

package/dist/client/plugins/admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../../../src/client/plugins/admin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,iBAAiB,CAWpB;AAED;;;GAGG;AACH,qBAAa,WAAW;IAEpB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,MAAM,EAAE,iBAAiB;IAG5C;;;OAGG;IACH,OAAO,CAAC,EAAE;IAyBV,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,cAAc;IAgBtB,OAAO,CAAC,4BAA4B;YAStB,qBAAqB;IAkCnC;;OAEG;IACG,SAAS,CAEb,GAAG,EAAE;QAAE,SAAS,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;KAAE,EACxD,IAAI,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAKhF;;OAEG;IACG,OAAO,CAEX,GAAG,EAAE;QAAE,SAAS,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;KAAE,EACxD,IAAI,EAAE;QACJ,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;IAKH;;OAEG;IACG,SAAS,CAEb,GAAG,EAAE;QAAE,SAAS,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;KAAE,EACxD,IAAI,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;IAK/D;;OAEG;IACG,OAAO,CAEX,GAAG,EAAE;QAAE,SAAS,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;KAAE,EACxD,IAAI,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;IAK7E;;OAEG;IACG,UAAU,CAEd,GAAG,EAAE;QAAE,SAAS,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;KAAE,EACxD,IAAI,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;IAK/D,IAAI,WAAW,uBAEd;IAED,IAAI,SAAS,uBAEZ;CACF"}