@robelest/convex-auth 0.0.4-preview.2 → 0.0.4-preview.21

package/dist/client/core/types.d.ts

@@ -0,0 +1,20 @@
+import { FunctionReference } from "convex/server";
+import { ConvexError, Value } from "convex/values";
+
+//#region src/client/core/types.d.ts
+/**
+ * Typed Convex API references for the auth functions.
+ * Pass these from your generated `api` object.
+ *
+ * @typeParam HasPasskey - Whether the passkey provider is configured.
+ * @typeParam HasTotp - Whether the TOTP provider is configured.
+ * @typeParam HasDevice - Whether the device provider is configured.
+ */
+type AuthApiRefs<HasPasskey extends boolean = boolean, HasTotp extends boolean = boolean, HasDevice extends boolean = boolean> = {
+  signIn: FunctionReference<"action", "public", any, any>;
+  signOut: FunctionReference<"action", "public", any, any>;
+  store: FunctionReference<"mutation", "public", any, any>;
+};
+//#endregion
+export { AuthApiRefs };
+//# sourceMappingURL=types.d.ts.map

package/dist/client/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/client/core/types.ts"],"mappings":";;;;;;;;;;;;KA2HY,WAAA;EAKV,MAAA,EAAQ,iBAAA;EACR,OAAA,EAAS,iBAAA;EACT,KAAA,EAAO,iBAAA;AAAA"}

package/dist/client/index.d.ts

@@ -1,299 +1,2 @@
-import { AUTH_ERRORS, AuthErrorCode, isAuthError, parseAuthError } from "../server/errors.js";
-import { Value } from "convex/values";
-
-//#region src/client/index.d.ts
-/**
- * Structural interface for any Convex client.
- * Satisfied by `ConvexClient` (`convex/browser`),
- * `ConvexReactClient` (`convex/react`), and similar transports.
- *
- * `clearAuth` is present on `ConvexReactClient` and `BaseConvexClient`
- * but not on the simplified `ConvexClient`. When available we call it
- * during sign-out for a clean deauthentication.
- */
-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`). */
-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>;
-}
-/**
- * Device code response returned when signing in with the `"device"` provider.
- *
- * The device displays the `userCode` (or `verificationUriComplete`) and
- * polls via `auth.device.poll()` until the user authorizes.
- */
-type DeviceCodeResult = {
-  /** High-entropy device code used for polling (keep secret). */deviceCode: string; /** Short human-readable code the user enters (e.g. "WDJB-MJHT"). */
-  userCode: string; /** Base verification URL (e.g. "https://myapp.com/device"). */
-  verificationUri: string; /** Verification URL with user code pre-filled as `?code=XXXX-XXXX`. */
-  verificationUriComplete: string; /** Lifetime of the codes in seconds. */
-  expiresIn: number; /** Minimum polling interval in seconds. */
-  interval: number;
-};
-/**
- * Result of a `signIn` call.
- *
- * - `signingIn: true` — credentials were accepted and the user is authenticated.
- * - `redirect` — OAuth flow initiated; redirect the user to `redirect.toString()`.
- * - `totpRequired` — credentials valid but 2FA is needed; call `auth.totp.verify()`.
- * - `deviceCode` — device flow initiated; display the code and poll via `auth.device.poll()`.
- * - `verifier` — opaque string for multi-step flows (TOTP, passkey).
- */
-type SignInResult = {
-  /** `true` when sign-in completed and the user is authenticated. */signingIn: boolean; /** OAuth redirect URL. Present when the provider requires a browser redirect. */
-  redirect?: URL; /** `true` when the account has TOTP enabled and a code is required. */
-  totpRequired?: boolean; /** Device code response for the device authorization flow (RFC 8628). */
-  deviceCode?: DeviceCodeResult; /** Opaque verifier for multi-step flows (pass to `totp.verify` or passkey phase 2). */
-  verifier?: string;
-};
-/** Reactive auth state snapshot returned by `auth.state` and `auth.onChange`. */
-type AuthState = {
-  /** `true` during initial hydration before the first token is resolved. */isLoading: boolean; /** `true` when a valid JWT exists (user is signed in). */
-  isAuthenticated: boolean; /** The raw JWT string, or `null` when not authenticated. */
-  token: string | null;
-};
-/** Options for {@link client}. */
-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>;
-  /**
-   * 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;
-};
-/**
- * Create a framework-agnostic auth client.
- *
- * Returns an object with `signIn`, `signOut`, `onChange`, `state`,
- * `passkey`, and `totp` — everything needed for client-side auth.
- *
- * ### 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',
- *   token: tokenFromServer, // JWT 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
- * holds the JWT in memory only.
- *
- * @param options - Client configuration. See {@link ClientOptions}.
- * @returns Auth client with `signIn`, `signOut`, `onChange`, `state`, `passkey`, and `totp`.
- */
-declare function client(options: ClientOptions): {
-  /** Current auth state snapshot. */readonly state: AuthState; /** Sign in with a provider. See {@link SignInResult} for return shape. */
-  signIn: (provider?: string, args?: FormData | Record<string, Value>) => Promise<SignInResult>; /** Sign out and clear all token state. */
-  signOut: () => Promise<void>; /** Subscribe to auth state changes. Returns an unsubscribe function. */
-  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>;
-  }; /** Device authorization (RFC 8628) helpers. */
-  device: {
-    /**
-     * Poll for device authorization status.
-     *
-     * The device calls this repeatedly (respecting `interval`) after
-     * initiating a device flow via `signIn("device")`. Returns when
-     * the user authorizes, or throws on timeout/denial.
-     *
-     * ```ts
-     * const result = await auth.signIn("device");
-     * const { deviceCode } = result;
-     * // Display deviceCode.userCode to the user, then poll:
-     * await auth.device.poll(deviceCode);
-     * // User is now signed in
-     * ```
-     *
-     * @param code - The {@link DeviceCodeResult} from `signIn("device")`.
-     * @returns Resolves when the device is authorized and tokens are stored.
-     * @throws When the code expires, is denied, or polling encounters an error.
-     */
-    poll: (code: DeviceCodeResult) => Promise<void>;
-    /**
-     * Authorize a device from the verification page.
-     *
-     * Called by an authenticated user on the verification page after
-     * they enter the user code displayed on the device.
-     *
-     * ```ts
-     * // On the /device verification page:
-     * await auth.device.verify(userCode);
-     * ```
-     *
-     * @param userCode - The user code entered by the user (e.g. "WDJB-MJHT").
-     */
-    verify: (userCode: string) => Promise<void>;
-  };
-};
-//#endregion
-export { AUTH_ERRORS, type AuthErrorCode, AuthState, ClientOptions, DeviceCodeResult, SignInResult, Storage, client, isAuthError, parseAuthError };
-//# sourceMappingURL=index.d.ts.map
+import { AuthApiRefs } from "./core/types.js";
+import { AUTH_ERRORS, AuthErrorCode, isAuthError, parseAuthError } from "../server/errors.js";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/client/index.ts"],"mappings":";;;;;;AAS0B;;;;;;;UAWhB,eAAA;EACR,MAAA,CAAO,MAAA,OAAa,IAAA,QAAY,OAAA;EAChC,OAAA,CACE,UAAA,GAAa,IAAA;IACX,iBAAA;EAAA,MACI,OAAA,6BACN,QAAA,IAAY,eAAA;EAEd,SAAA;AAAA;;UAIe,OAAA;EACf,OAAA,CACE,GAAA,uCAC6B,OAAA;EAC/B,OAAA,CAAQ,GAAA,UAAa,KAAA,kBAAuB,OAAA;EAC5C,UAAA,CAAW,GAAA,kBAAqB,OAAA;AAAA;;;;;;;KActB,gBAAA;EAjBR,+DAmBF,UAAA,UAjBA;EAmBA,QAAA,UAnBqB;EAqBrB,eAAA,UApBA;EAsBA,uBAAA,UAtBgC;EAwBhC,SAAA,UAxBuC;EA0BvC,QAAA;AAAA;;;;;;;;;;KAYU,YAAA;EAAA,mEAEV,SAAA;EAEA,QAAA,GAAW,GAAA,EAFX;EAIA,YAAA,YAFW;EAIX,UAAA,GAAa,gBAAA,EAAb;EAEA,QAAA;AAAA;;KAIU,SAAA;EAAA,0EAEV,SAAA;EAEA,eAAA,WAFA;EAIA,KAAA;AAAA;;KAIU,aAAA;EAAA,iEAEV,MAAA,EAAQ,eAAA;;;;;EAKR,GAAA;EAUoD;;;;;;;EAFpD,OAAA,GAAU,OAAA,SAEmC;EAA7C,UAAA,IAAc,WAAA,oBAA+B,OAAA;EAkB7C;;;AA2DF;;;;;;EAnEE,KAAA;EAmSoB;;;;;;;EA3RpB,KAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2Dc,MAAA,CAAO,OAAA,EAAS,aAAA;EAkkBxB,mDAqfS,SAAA;8BAx1BI,IAAA,GACV,QAAA,GAAW,MAAA,SAAe,KAAA,MAChC,OAAA,CAAQ,YAAA,GAoWE;gCAkJA;kBAlSU,KAAA,EAAO,SAAA;;IAmSjB;;;;IAoHe;;;;;;;;;+BAlTK,OAAA;IAiV7B;;;;;;;;;;;;;;;;;;;;;;MA3SE,IAAA;MACA,KAAA;MACA,QAAA;MACA,eAAA;IAAA,MAED,OAAA,CAAQ,YAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAkJA,KAAA;MAAgB,QAAA;IAAA,MACxB,OAAA,CAAQ,YAAA;EAAA;;;;;;;;;;;;;;MAoHA,IAAA;MAAe,WAAA;IAAA,MACvB,OAAA;MAAU,GAAA;MAAa,MAAA;MAAgB,QAAA;MAAkB,MAAA;IAAA;;;;;;;;;MA4B1D,IAAA;MACA,QAAA;MACA,MAAA;IAAA,MACE,OAAA;;;;;;;;;;;;;;MA8CmB,IAAA;MAAc,QAAA;IAAA,MAAqB,OAAA;EAAA;;;;;;;;;;;;;;;;;;;;;iBAsDvC,gBAAA,KAAmB,OAAA;;;;;;;;;;;;;;kCAiFJ,OAAA;EAAA;AAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/client/index.ts"],"mappings":";;;;;AAwHA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,MAAA,aACF,WAAA,8BAAyC,WAAA,CAAA,CACrD,OAAA,EAAS,aAAA,CAAc,GAAA,IAAO,UAAA,CAAW,GAAA"}