@robelest/convex-auth 0.0.2-preview.2 → 0.0.2

package/dist/client/index.d.ts

@@ -20,6 +20,8 @@ export interface Storage {
 type SignInResult = {
     signingIn: boolean;
     redirect?: URL;
+    totpRequired?: boolean;
+    verifier?: string;
 };
 /** Reactive auth state snapshot returned by `auth.state` and `auth.onChange`. */
 export type AuthState = {
@@ -98,6 +100,131 @@ export declare function client(options: ClientOptions): {
     signIn: (provider?: string, args?: FormData | Record<string, Value>) => Promise<SignInResult>;
     signOut: () => Promise<void>;
     onChange: (cb: (state: AuthState) => void) => (() => void);
+    /** Passkey (WebAuthn) authentication helpers. */
+    passkey: {
+        /**
+         * Check if WebAuthn passkeys are supported in the current environment.
+         */
+        isSupported: () => boolean;
+        /**
+         * Check if conditional UI (autofill-assisted passkey sign-in) is supported.
+         *
+         * ```ts
+         * if (await auth.passkey.isAutofillSupported()) {
+         *   auth.passkey.authenticate({ autofill: true });
+         * }
+         * ```
+         */
+        isAutofillSupported: () => Promise<boolean>;
+        /**
+         * Register a new passkey for the current or new user.
+         *
+         * Performs the full two-round-trip WebAuthn registration ceremony:
+         * 1. Requests creation options from the server (challenge, RP info)
+         * 2. Calls `navigator.credentials.create()` with the options
+         * 3. Sends the attestation back to the server for verification
+         * 4. Server creates user + account + passkey records and returns tokens
+         *
+         * Works in both SPA and proxy (SSR) modes.
+         *
+         * ```ts
+         * await auth.passkey.register({ name: "MacBook Touch ID" });
+         * ```
+         *
+         * @param opts.name - Friendly name for this passkey
+         * @param opts.email - Email to associate with the new account
+         * @param opts.userName - Username for the credential (defaults to email)
+         * @param opts.userDisplayName - Display name for the credential
+         * @returns `{ signingIn: true }` on success
+         */
+        register: (opts?: {
+            name?: string;
+            email?: string;
+            userName?: string;
+            userDisplayName?: string;
+        }) => Promise<SignInResult>;
+        /**
+         * Authenticate with an existing passkey.
+         *
+         * Performs the full two-round-trip WebAuthn authentication ceremony:
+         * 1. Requests assertion options from the server (challenge, allowed credentials)
+         * 2. Calls `navigator.credentials.get()` with the options
+         * 3. Sends the assertion back to the server for signature verification
+         * 4. Server verifies signature, updates counter, creates session, returns tokens
+         *
+         * Works in both SPA and proxy (SSR) modes.
+         *
+         * ```ts
+         * // Discoverable credential (no email needed)
+         * await auth.passkey.authenticate();
+         *
+         * // Scoped to a specific user's credentials
+         * await auth.passkey.authenticate({ email: "user@example.com" });
+         *
+         * // Autofill-assisted (conditional UI)
+         * await auth.passkey.authenticate({ autofill: true });
+         * ```
+         *
+         * @param opts.email - Scope to credentials for this email's user
+         * @param opts.autofill - Use conditional mediation (autofill UI)
+         * @returns `{ signingIn: true }` on success
+         */
+        authenticate: (opts?: {
+            email?: string;
+            autofill?: boolean;
+        }) => Promise<SignInResult>;
+    };
+    /** TOTP two-factor authentication helpers. */
+    totp: {
+        /**
+         * Start TOTP enrollment. Must be authenticated.
+         *
+         * Returns a URI for QR code display and a base32 secret for manual entry.
+         *
+         * ```ts
+         * const setup = await auth.totp.setup();
+         * // Display QR code from setup.uri
+         * // Or show setup.secret for manual entry
+         * ```
+         */
+        setup: (opts?: {
+            name?: string;
+            accountName?: string;
+        }) => Promise<{
+            uri: string;
+            secret: string;
+            verifier: string;
+            totpId: string;
+        }>;
+        /**
+         * Complete TOTP enrollment by verifying the first code from the authenticator app.
+         *
+         * ```ts
+         * await auth.totp.confirm({ code: "123456", verifier: setup.verifier, totpId: setup.totpId });
+         * ```
+         */
+        confirm: (opts: {
+            code: string;
+            verifier: string;
+            totpId: string;
+        }) => Promise<void>;
+        /**
+         * Complete 2FA verification during sign-in.
+         *
+         * Called after a credentials sign-in returns `totpRequired: true`.
+         *
+         * ```ts
+         * const result = await auth.signIn("password", { email, password });
+         * if (result.totpRequired) {
+         *   await auth.totp.verify({ code: "123456", verifier: result.verifier! });
+         * }
+         * ```
+         */
+        verify: (opts: {
+            code: string;
+            verifier: string;
+        }) => Promise<void>;
+    };
 };
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAEtC;;;;GAIG;AACH,UAAU,eAAe;IACvB,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7C,OAAO,CACL,UAAU,EAAE,CAAC,IAAI,EAAE;QACjB,iBAAiB,EAAE,OAAO,CAAC;KAC5B,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EACxC,QAAQ,CAAC,EAAE,CAAC,eAAe,EAAE,OAAO,KAAK,IAAI,GAC5C,IAAI,CAAC;IACR,SAAS,IAAI,IAAI,CAAC;CACnB;AAED,gEAAgE;AAChE,MAAM,WAAW,OAAO;IACtB,OAAO,CACL,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAClE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAOD,KAAK,YAAY,GAAG;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB,CAAC;AAEF,iFAAiF;AACjF,MAAM,MAAM,SAAS,GAAG;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,eAAe,EAAE,OAAO,CAAC;IACzB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAAC;AAEF,kCAAkC;AAClC,MAAM,MAAM,aAAa,GAAG;IAC1B,iEAAiE;IACjE,MAAM,EAAE,eAAe,CAAC;IACxB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,qEAAqE;IACrE,UAAU,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAyBF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,aAAa;IAoazC,mCAAmC;oBACtB,SAAS;wBAlPX,MAAM,SACV,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,KACtC,OAAO,CAAC,YAAY,CAAC;;mBA4LF,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC;EA2DhE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"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"}

package/dist/client/index.js

@@ -212,6 +212,9 @@ export function client(options) {
                 }
                 return { signingIn: false, redirect: redirectUrl };
             }
+            if (result.totpRequired) {
+                return { signingIn: false, totpRequired: true, verifier: result.verifier };
+            }
             if (result.tokens !== undefined) {
                 // Proxy returns { token, refreshToken: "dummy" }.
                 // Store JWT in memory only — real refresh token is in httpOnly cookie.
@@ -239,6 +242,9 @@ export function client(options) {
             }
             return { signingIn: false, redirect: redirectUrl };
         }
+        if (result.totpRequired) {
+            return { signingIn: false, totpRequired: true, verifier: result.verifier };
+        }
         if (result.tokens !== undefined) {
             await setToken({
                 shouldStore: true,
@@ -411,6 +417,410 @@ export function client(options) {
             void hydrateFromStorage().then(() => handleCodeFlow());
         }
     }
+    // ---------------------------------------------------------------------------
+    // Passkey helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Base64url encode/decode helpers for the WebAuthn credential API.
+     * These run client-side only (browser context).
+     */
+    const base64urlEncode = (buffer) => {
+        const bytes = new Uint8Array(buffer);
+        let binary = "";
+        for (let i = 0; i < bytes.byteLength; i++) {
+            binary += String.fromCharCode(bytes[i]);
+        }
+        return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    };
+    const base64urlDecode = (str) => {
+        const padded = str.replace(/-/g, "+").replace(/_/g, "/");
+        const binary = atob(padded);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++) {
+            bytes[i] = binary.charCodeAt(i);
+        }
+        return bytes;
+    };
+    const passkey = {
+        /**
+         * Check if WebAuthn passkeys are supported in the current environment.
+         */
+        isSupported: () => {
+            return (typeof window !== "undefined" &&
+                typeof window.PublicKeyCredential !== "undefined");
+        },
+        /**
+         * Check if conditional UI (autofill-assisted passkey sign-in) is supported.
+         *
+         * ```ts
+         * if (await auth.passkey.isAutofillSupported()) {
+         *   auth.passkey.authenticate({ autofill: true });
+         * }
+         * ```
+         */
+        isAutofillSupported: async () => {
+            if (typeof window === "undefined")
+                return false;
+            if (typeof window.PublicKeyCredential === "undefined")
+                return false;
+            if (typeof window.PublicKeyCredential.isConditionalMediationAvailable !== "function") {
+                return false;
+            }
+            return window.PublicKeyCredential.isConditionalMediationAvailable();
+        },
+        /**
+         * Register a new passkey for the current or new user.
+         *
+         * Performs the full two-round-trip WebAuthn registration ceremony:
+         * 1. Requests creation options from the server (challenge, RP info)
+         * 2. Calls `navigator.credentials.create()` with the options
+         * 3. Sends the attestation back to the server for verification
+         * 4. Server creates user + account + passkey records and returns tokens
+         *
+         * Works in both SPA and proxy (SSR) modes.
+         *
+         * ```ts
+         * await auth.passkey.register({ name: "MacBook Touch ID" });
+         * ```
+         *
+         * @param opts.name - Friendly name for this passkey
+         * @param opts.email - Email to associate with the new account
+         * @param opts.userName - Username for the credential (defaults to email)
+         * @param opts.userDisplayName - Display name for the credential
+         * @returns `{ signingIn: true }` on success
+         */
+        register: async (opts) => {
+            const phase1Params = {
+                flow: "register-options",
+                email: opts?.email,
+                userName: opts?.userName,
+                userDisplayName: opts?.userDisplayName,
+            };
+            // Phase 1: Get registration options from server
+            let phase1Result;
+            if (proxy) {
+                phase1Result = await proxyFetch({
+                    action: "auth:signIn",
+                    args: { provider: "passkey", params: phase1Params },
+                });
+            }
+            else {
+                phase1Result = await convex.action("auth:signIn", {
+                    provider: "passkey",
+                    params: phase1Params,
+                });
+            }
+            if (!phase1Result.options) {
+                throw new Error("Server did not return passkey registration options");
+            }
+            const options = phase1Result.options;
+            // Convert base64url strings to ArrayBuffers for the credential API
+            const createOptions = {
+                publicKey: {
+                    rp: options.rp,
+                    user: {
+                        id: base64urlDecode(options.user.id).buffer,
+                        name: options.user.name,
+                        displayName: options.user.displayName,
+                    },
+                    challenge: base64urlDecode(options.challenge).buffer,
+                    pubKeyCredParams: options.pubKeyCredParams,
+                    timeout: options.timeout,
+                    attestation: options.attestation,
+                    authenticatorSelection: options.authenticatorSelection,
+                    excludeCredentials: (options.excludeCredentials ?? []).map((cred) => ({
+                        type: cred.type ?? "public-key",
+                        id: base64urlDecode(cred.id).buffer,
+                        transports: cred.transports,
+                    })),
+                },
+            };
+            // Phase 2: Create credential via browser API
+            const credential = (await navigator.credentials.create(createOptions));
+            if (!credential) {
+                throw new Error("Passkey registration was cancelled");
+            }
+            const response = credential.response;
+            // Extract transports if available
+            const transports = typeof response.getTransports === "function"
+                ? response.getTransports()
+                : undefined;
+            const phase2Params = {
+                flow: "register-verify",
+                clientDataJSON: base64urlEncode(response.clientDataJSON),
+                attestationObject: base64urlEncode(response.attestationObject),
+                transports,
+                passkeyName: opts?.name,
+                email: opts?.email,
+            };
+            // Phase 3: Send attestation to server for verification
+            let phase2Result;
+            if (proxy) {
+                // In proxy mode the verifier is stored in an httpOnly cookie by the proxy.
+                // We pass it back explicitly so the proxy can forward it to Convex.
+                phase2Result = await proxyFetch({
+                    action: "auth:signIn",
+                    args: {
+                        provider: "passkey",
+                        params: phase2Params,
+                        verifier: phase1Result.verifier,
+                    },
+                });
+            }
+            else {
+                phase2Result = await convex.action("auth:signIn", {
+                    provider: "passkey",
+                    params: phase2Params,
+                    verifier: phase1Result.verifier,
+                });
+            }
+            if (phase2Result.tokens) {
+                if (proxy) {
+                    await setToken({
+                        shouldStore: false,
+                        tokens: phase2Result.tokens === null
+                            ? null
+                            : { token: phase2Result.tokens.token },
+                    });
+                }
+                else {
+                    await setToken({
+                        shouldStore: true,
+                        tokens: phase2Result.tokens,
+                    });
+                }
+                return { signingIn: true };
+            }
+            return { signingIn: false };
+        },
+        /**
+         * Authenticate with an existing passkey.
+         *
+         * Performs the full two-round-trip WebAuthn authentication ceremony:
+         * 1. Requests assertion options from the server (challenge, allowed credentials)
+         * 2. Calls `navigator.credentials.get()` with the options
+         * 3. Sends the assertion back to the server for signature verification
+         * 4. Server verifies signature, updates counter, creates session, returns tokens
+         *
+         * Works in both SPA and proxy (SSR) modes.
+         *
+         * ```ts
+         * // Discoverable credential (no email needed)
+         * await auth.passkey.authenticate();
+         *
+         * // Scoped to a specific user's credentials
+         * await auth.passkey.authenticate({ email: "user@example.com" });
+         *
+         * // Autofill-assisted (conditional UI)
+         * await auth.passkey.authenticate({ autofill: true });
+         * ```
+         *
+         * @param opts.email - Scope to credentials for this email's user
+         * @param opts.autofill - Use conditional mediation (autofill UI)
+         * @returns `{ signingIn: true }` on success
+         */
+        authenticate: async (opts) => {
+            const phase1Params = {
+                flow: "auth-options",
+                email: opts?.email,
+            };
+            // Phase 1: Get assertion options from server
+            let phase1Result;
+            if (proxy) {
+                phase1Result = await proxyFetch({
+                    action: "auth:signIn",
+                    args: { provider: "passkey", params: phase1Params },
+                });
+            }
+            else {
+                phase1Result = await convex.action("auth:signIn", {
+                    provider: "passkey",
+                    params: phase1Params,
+                });
+            }
+            if (!phase1Result.options) {
+                throw new Error("Server did not return passkey authentication options");
+            }
+            const options = phase1Result.options;
+            // Convert base64url strings to ArrayBuffers for the credential API
+            const getOptions = {
+                publicKey: {
+                    challenge: base64urlDecode(options.challenge).buffer,
+                    timeout: options.timeout,
+                    rpId: options.rpId,
+                    userVerification: options.userVerification,
+                    allowCredentials: (options.allowCredentials ?? []).map((cred) => ({
+                        type: cred.type ?? "public-key",
+                        id: base64urlDecode(cred.id).buffer,
+                        transports: cred.transports,
+                    })),
+                },
+                ...(opts?.autofill ? { mediation: "conditional" } : {}),
+            };
+            // Phase 2: Get credential via browser API
+            const credential = (await navigator.credentials.get(getOptions));
+            if (!credential) {
+                throw new Error("Passkey authentication was cancelled");
+            }
+            const response = credential.response;
+            const phase2Params = {
+                flow: "auth-verify",
+                credentialId: base64urlEncode(credential.rawId),
+                clientDataJSON: base64urlEncode(response.clientDataJSON),
+                authenticatorData: base64urlEncode(response.authenticatorData),
+                signature: base64urlEncode(response.signature),
+            };
+            // Phase 3: Send assertion to server for verification
+            let phase2Result;
+            if (proxy) {
+                phase2Result = await proxyFetch({
+                    action: "auth:signIn",
+                    args: {
+                        provider: "passkey",
+                        params: phase2Params,
+                        verifier: phase1Result.verifier,
+                    },
+                });
+            }
+            else {
+                phase2Result = await convex.action("auth:signIn", {
+                    provider: "passkey",
+                    params: phase2Params,
+                    verifier: phase1Result.verifier,
+                });
+            }
+            if (phase2Result.tokens) {
+                if (proxy) {
+                    await setToken({
+                        shouldStore: false,
+                        tokens: phase2Result.tokens === null
+                            ? null
+                            : { token: phase2Result.tokens.token },
+                    });
+                }
+                else {
+                    await setToken({
+                        shouldStore: true,
+                        tokens: phase2Result.tokens,
+                    });
+                }
+                return { signingIn: true };
+            }
+            return { signingIn: false };
+        },
+    };
+    const totp = {
+        /**
+         * Start TOTP enrollment. Must be authenticated.
+         *
+         * Returns a URI for QR code display and a base32 secret for manual entry.
+         *
+         * ```ts
+         * const setup = await auth.totp.setup();
+         * // Display QR code from setup.uri
+         * // Or show setup.secret for manual entry
+         * ```
+         */
+        setup: async (opts) => {
+            const params = { flow: "setup" };
+            if (opts?.name)
+                params.name = opts.name;
+            if (opts?.accountName)
+                params.accountName = opts.accountName;
+            if (proxy) {
+                const result = await proxyFetch({
+                    action: "auth:signIn",
+                    args: { provider: "totp", params },
+                });
+                return { uri: result.totpSetup.uri, secret: result.totpSetup.secret, verifier: result.verifier, totpId: result.totpSetup.totpId };
+            }
+            const result = await convex.action("auth:signIn", {
+                provider: "totp",
+                params,
+            });
+            return { uri: result.totpSetup.uri, secret: result.totpSetup.secret, verifier: result.verifier, totpId: result.totpSetup.totpId };
+        },
+        /**
+         * Complete TOTP enrollment by verifying the first code from the authenticator app.
+         *
+         * ```ts
+         * await auth.totp.confirm({ code: "123456", verifier: setup.verifier, totpId: setup.totpId });
+         * ```
+         */
+        confirm: async (opts) => {
+            const params = {
+                flow: "confirm",
+                code: opts.code,
+                totpId: opts.totpId,
+            };
+            if (proxy) {
+                const result = await proxyFetch({
+                    action: "auth:signIn",
+                    args: { provider: "totp", params, verifier: opts.verifier },
+                });
+                if (result.tokens) {
+                    await setToken({
+                        shouldStore: false,
+                        tokens: result.tokens === null ? null : { token: result.tokens.token },
+                    });
+                }
+                return;
+            }
+            const result = await convex.action("auth:signIn", {
+                provider: "totp",
+                params,
+                verifier: opts.verifier,
+            });
+            if (result.tokens) {
+                await setToken({
+                    shouldStore: true,
+                    tokens: result.tokens ?? null,
+                });
+            }
+        },
+        /**
+         * Complete 2FA verification during sign-in.
+         *
+         * Called after a credentials sign-in returns `totpRequired: true`.
+         *
+         * ```ts
+         * const result = await auth.signIn("password", { email, password });
+         * if (result.totpRequired) {
+         *   await auth.totp.verify({ code: "123456", verifier: result.verifier! });
+         * }
+         * ```
+         */
+        verify: async (opts) => {
+            const params = {
+                flow: "verify",
+                code: opts.code,
+            };
+            if (proxy) {
+                const result = await proxyFetch({
+                    action: "auth:signIn",
+                    args: { provider: "totp", params, verifier: opts.verifier },
+                });
+                if (result.tokens) {
+                    await setToken({
+                        shouldStore: false,
+                        tokens: result.tokens === null ? null : { token: result.tokens.token },
+                    });
+                }
+                return;
+            }
+            const result = await convex.action("auth:signIn", {
+                provider: "totp",
+                params,
+                verifier: opts.verifier,
+            });
+            if (result.tokens) {
+                await setToken({
+                    shouldStore: true,
+                    tokens: result.tokens ?? null,
+                });
+            }
+        },
+    };
     return {
         /** Current auth state snapshot. */
         get state() {
@@ -419,6 +829,10 @@ export function client(options) {
         signIn,
         signOut,
         onChange,
+        /** Passkey (WebAuthn) authentication helpers. */
+        passkey,
+        /** TOTP two-factor authentication helpers. */
+        totp,
     };
 }
 // ---------------------------------------------------------------------------