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

package/dist/client/index.d.ts

@@ -1,49 +1,230 @@
-import { FunctionReference, OptionalRestArgs } from "convex/server";
 import { Value } from "convex/values";
-type AuthActionCaller = {
-    authenticatedCall<Action extends FunctionReference<"action", "public">>(action: Action, ...args: OptionalRestArgs<Action>): Promise<Action["_returnType"]>;
-    unauthenticatedCall<Action extends FunctionReference<"action", "public">>(action: Action, ...args: OptionalRestArgs<Action>): Promise<Action["_returnType"]>;
-    verbose?: boolean;
-    logger?: {
-        logVerbose?: (message: string) => void;
-    };
-};
-export interface TokenStorage {
+/**
+ * Structural interface for any Convex client.
+ * Satisfied by both `ConvexClient` (`convex/browser`) and
+ * `ConvexReactClient` (`convex/react`).
+ */
+interface ConvexTransport {
+    action(action: any, args: any): Promise<any>;
+    setAuth(fetchToken: (args: {
+        forceRefreshToken: boolean;
+    }) => Promise<string | null | undefined>, onChange?: (isAuthenticated: boolean) => void): void;
+    clearAuth(): void;
+}
+/** Pluggable key-value storage (defaults to `localStorage`). */
+export interface Storage {
     getItem(key: string): string | null | undefined | Promise<string | null | undefined>;
     setItem(key: string, value: string): void | Promise<void>;
     removeItem(key: string): void | Promise<void>;
 }
-export type AuthSession = {
-    token: string;
-    refreshToken: string;
-};
-export type SignInResult = {
+type SignInResult = {
     signingIn: boolean;
     redirect?: URL;
+    totpRequired?: boolean;
+    verifier?: string;
 };
-export type AuthSnapshot = {
+/** Reactive auth state snapshot returned by `auth.state` and `auth.onChange`. */
+export type AuthState = {
     isLoading: boolean;
     isAuthenticated: boolean;
     token: string | null;
 };
-export type AuthClientOptions = {
-    transport: AuthActionCaller;
-    storage?: TokenStorage | null;
-    storageNamespace: string;
+/** Options for {@link client}. */
+export type ClientOptions = {
+    /** Any Convex client (`ConvexClient` or `ConvexReactClient`). */
+    convex: ConvexTransport;
+    /**
+     * Convex deployment URL. Derived automatically from the client internals
+     * when omitted — pass explicitly only if auto-detection fails.
+     */
+    url?: string;
+    /**
+     * Key-value storage for persisting tokens.
+     *
+     * - Defaults to `localStorage` in SPA mode.
+     * - Defaults to `null` (in-memory only) when `proxy` is set,
+     *   since httpOnly cookies handle persistence.
+     */
+    storage?: Storage | null;
+    /** Override how the URL bar is updated after OAuth code exchange. */
     replaceURL?: (relativeUrl: string) => void | Promise<void>;
-    shouldHandleCode?: (() => boolean) | boolean;
-    onChange?: () => Promise<unknown>;
+    /**
+     * SSR proxy endpoint (e.g. `"/api/auth"`).
+     *
+     * When set, `signIn`/`signOut`/token refresh POST to this URL
+     * (with `credentials: "include"`) instead of calling Convex directly.
+     * The server handles httpOnly cookies for token persistence.
+     *
+     * Pair with {@link ClientOptions.token} for flash-free SSR hydration.
+     */
+    proxy?: string;
+    /**
+     * JWT from server-side hydration.
+     *
+     * In proxy mode the server reads the JWT from an httpOnly cookie
+     * and passes it to the client during SSR. This avoids a loading
+     * flash on first render — the client is immediately authenticated.
+     */
+    token?: string | null;
 };
-export declare function createAuthClient(options: AuthClientOptions): {
+/**
+ * Create a framework-agnostic auth client.
+ *
+ * ### SPA mode (default)
+ *
+ * ```ts
+ * import { ConvexClient } from 'convex/browser'
+ * import { client } from '\@robelest/convex-auth/client'
+ *
+ * const convex = new ConvexClient(CONVEX_URL)
+ * const auth = client({ convex })
+ * ```
+ *
+ * ### SSR / proxy mode
+ *
+ * ```ts
+ * const auth = client({
+ *   convex,
+ *   proxy: '/api/auth',
+ *   initialToken: tokenFromServer, // read from httpOnly cookie during SSR
+ * })
+ * ```
+ *
+ * In proxy mode all auth operations go through the proxy URL.
+ * Tokens are stored in httpOnly cookies server-side — the client
+ * only holds the JWT in memory.
+ */
+export declare function client(options: ClientOptions): {
+    /** Current auth state snapshot. */
+    readonly state: AuthState;
     signIn: (provider?: string, args?: FormData | Record<string, Value>) => Promise<SignInResult>;
     signOut: () => Promise<void>;
-    fetchAccessToken: ({ forceRefreshToken, }: {
-        forceRefreshToken: boolean;
-    }) => Promise<string | null>;
-    handleCodeFlow: () => Promise<void>;
-    hydrateFromStorage: () => Promise<void>;
-    getSnapshot: () => AuthSnapshot;
-    subscribe: (cb: () => void) => () => boolean;
+    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":"AAAA,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAMtC,KAAK,gBAAgB,GAAG;IACtB,iBAAiB,CAAC,MAAM,SAAS,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,EACpE,MAAM,EAAE,MAAM,EACd,GAAG,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC,GAChC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;IAClC,mBAAmB,CAAC,MAAM,SAAS,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,EACtE,MAAM,EAAE,MAAM,EACd,GAAG,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC,GAChC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE;QACP,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;KACxC,CAAC;CACH,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACrF,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;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,eAAe,EAAE,OAAO,CAAC;IACzB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9B,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,gBAAgB,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,GAAG,OAAO,CAAC;IAC7C,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACnC,CAAC;AASF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB;wBAoI5C,MAAM,SACV,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,KACtC,OAAO,CAAC,YAAY,CAAC;;+CAiDrB;QACD,iBAAiB,EAAE,OAAO,CAAC;KAC5B,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;;;uBAoDF,YAAY;oBAEb,MAAM,IAAI;EA8BlC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"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"}