@robelest/convex-auth 0.0.4-preview.18 → 0.0.4-preview.19

package/src/cli/index.ts

@@ -836,7 +836,7 @@ function readConvexJson(): ConvexJSON {
 // Deployment selection
 // ---------------------------------------------------------------------------
 
-function readConvexDeployment(options: {
+export function readConvexDeployment(options: {
   url?: string;
   adminKey?: string;
   prod?: boolean;
@@ -844,11 +844,19 @@ function readConvexDeployment(options: {
   deploymentName?: string;
 }) {
   const { adminKey, url, prod, previewName, deploymentName } = options;
+
+  if (url) {
+    return {
+      name: url,
+      type: null,
+      options,
+    };
+  }
+
   const adminKeyName = adminKey ? deploymentNameFromAdminKey(adminKey) : null;
   const adminKeyType = adminKey ? deploymentTypeFromAdminKey(adminKey) : null;
 
   const explicitSelection = [
-    url ? { name: adminKeyName ?? url, type: adminKeyType } : null,
     prod ? { name: adminKeyName, type: "prod" as const } : null,
     previewName ? { name: previewName, type: "preview" as const } : null,
     deploymentName ? { name: deploymentName, type: adminKeyType } : null,
@@ -869,11 +877,12 @@ function readConvexDeployment(options: {
   loadEnvFile({ path: ".env.local" });
   loadEnvFile();
   if (process.env.CONVEX_DEPLOYMENT) {
+    const type = getDeploymentTypeFromConfiguredDeployment(
+      process.env.CONVEX_DEPLOYMENT,
+    );
     return {
       name: stripDeploymentTypePrefix(process.env.CONVEX_DEPLOYMENT),
-      type: getDeploymentTypeFromConfiguredDeployment(
-        process.env.CONVEX_DEPLOYMENT,
-      ),
+      type,
       options,
     };
   }
@@ -886,20 +895,27 @@ function readConvexDeployment(options: {
 // NOTE: CONVEX CLI DEP
 // Given a deployment string like "dev:tall-forest-1234"
 // returns only the slug "tall-forest-1234".
-// If there's no prefix returns the original string.
 export function stripDeploymentTypePrefix(deployment: string) {
-  return deployment.split(":").at(-1)!;
+  const [type, name] = deployment.split(":");
+  if ((type !== "prod" && type !== "dev" && type !== "preview") || !name) {
+    logErrorAndExit(
+      "Invalid CONVEX_DEPLOYMENT.",
+      'Expected a typed deployment like "dev:my-deployment", "prod:my-deployment", or "preview:my-deployment".',
+    );
+  }
+  return name;
 }
 
 // NOTE: CONVEX CLI DEP
-// Handling legacy CONVEX_DEPLOYMENT without type prefix as well
 function getDeploymentTypeFromConfiguredDeployment(raw: string) {
   const typeRaw = raw.split(":")[0];
-  const type =
-    typeRaw === "prod" || typeRaw === "dev" || typeRaw === "preview"
-      ? typeRaw
-      : null;
-  return type;
+  if (typeRaw === "prod" || typeRaw === "dev" || typeRaw === "preview") {
+    return typeRaw;
+  }
+  logErrorAndExit(
+    "Invalid CONVEX_DEPLOYMENT.",
+    'Expected a typed deployment like "dev:my-deployment", "prod:my-deployment", or "preview:my-deployment".',
+  );
 }
 
 // NOTE: CONVEX CLI DEP
@@ -911,18 +927,20 @@ function deploymentNameFromAdminKey(adminKey: string) {
     : null;
 }
 
-// NOTE: CONVEX CLI DEP - but modified to not default to "prod"
-//
-// For current keys returns prod|dev|preview,
-// for legacy keys returns "prod".
+// NOTE: CONVEX CLI DEP
 // Examples:
 //  "prod:deploymentName|key" -> "prod"
 //  "preview:deploymentName|key" -> "preview"
 //  "dev:deploymentName|key" -> "dev"
-//  "key" -> "prod"
 export function deploymentTypeFromAdminKey(adminKey: string) {
-  const parts = adminKey.split(":");
-  return parts.length > 1 ? parts.at(0)! : null;
+  const type = adminKey.split(":")[0];
+  if (type === "prod" || type === "dev" || type === "preview") {
+    return type;
+  }
+  logErrorAndExit(
+    "Invalid admin key.",
+    'Expected a typed key like "dev:deployment|...", "prod:deployment|...", or "preview:...".',
+  );
 }
 
 // NOTE: CONVEX CLI DEP

package/src/client/core/types.ts

@@ -0,0 +1,437 @@
+import type { FunctionReference } from "convex/server";
+import type { ConvexError, Value } from "convex/values";
+
+/**
+ * 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.
+ */
+export 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 SignInActionResult =
+  | { kind: "signedIn"; tokens: AuthSession | null }
+  | { kind: "redirect"; redirect: string; verifier: string }
+  | { kind: "started" }
+  | { kind: "passkeyOptions"; options: Record<string, any>; verifier: string }
+  | { kind: "totpRequired"; verifier: string }
+  | {
+      kind: "totpSetup";
+      totpSetup: { uri: string; secret: string; totpId: string };
+      verifier: string;
+    }
+  | {
+      kind: "deviceCode";
+      deviceCode: {
+        deviceCode: string;
+        userCode: string;
+        verificationUri: string;
+        verificationUriComplete: string;
+        expiresIn: number;
+        interval: number;
+      };
+    };
+
+/**
+ * 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.
+ */
+export 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.
+ *
+ * - `kind: "signedIn"` — credentials were accepted and the user is authenticated.
+ * - `kind: "redirect"` — OAuth flow initiated; redirect the user to `redirect.toString()`.
+ * - `kind: "totpRequired"` — credentials valid but 2FA is needed; call `auth.totp.verify()`.
+ * - `kind: "deviceCode"` — device flow initiated; display the code and poll via `auth.device.poll()`.
+ * - `kind: "started"` — a non-immediate flow started (for example email/phone verification).
+ *
+ * @see {@link AuthState}
+ */
+export type SignInResult =
+  | { kind: "signedIn" }
+  | { kind: "redirect"; redirect: URL; verifier: string }
+  | { kind: "totpRequired"; verifier: string }
+  | { kind: "deviceCode"; deviceCode: DeviceCodeResult }
+  | { kind: "started" };
+
+/**
+ * Reactive auth state snapshot returned by `auth.state` and `auth.onChange`.
+ *
+ * @see {@link SignInResult}
+ */
+export type AuthState = {
+  /** High-level auth phase for deterministic UI state handling. */
+  phase: "loading" | "handshake" | "authenticated" | "unauthenticated";
+  /** `true` during initial hydration before the first token is resolved. */
+  isLoading: boolean;
+  /** `true` only after Convex confirms authentication with the backend. */
+  isAuthenticated: boolean;
+  /** The raw JWT string, or `null` when not authenticated. */
+  token: string | null;
+};
+
+/**
+ * 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.
+ */
+export 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>;
+  /** @internal Set automatically by `createAuth` — do not set manually. */
+  _capabilities?: {
+    passkey: HasPasskey;
+    totp: HasTotp;
+    device: HasDevice;
+  };
+};
+
+/**
+ * Passkey (WebAuthn) client-side helpers.
+ *
+ * @see {@link TotpClient}
+ * @see {@link DeviceClient}
+ */
+export interface PasskeyClient {
+  /**
+   * Check whether the current runtime exposes WebAuthn passkey APIs.
+   *
+   * @returns `true` when `navigator.credentials` is available.
+   *
+   * @example
+   * ```ts
+   * if (auth.passkey.isSupported()) {
+   *   // Show passkey registration button
+   * }
+   * ```
+   */
+  isSupported(): boolean;
+
+  /**
+   * Check whether conditional mediation (autofill-style passkeys) is available.
+   *
+   * @returns `true` when the browser supports `PublicKeyCredential.isConditionalMediationAvailable`.
+   *
+   * @example
+   * ```ts
+   * if (await auth.passkey.isAutofillSupported()) {
+   *   await auth.passkey.authenticate({ autofill: true });
+   * }
+   * ```
+   */
+  isAutofillSupported(): Promise<boolean>;
+
+  /**
+   * Start a passkey registration flow and complete the WebAuthn ceremony.
+   *
+   * Creates a new credential bound to the current user's account.
+   *
+   * @param opts - Optional registration hints.
+   * @param opts.name - Human-readable name for the passkey (e.g. `"MacBook Pro"`).
+   * @param opts.email - Email hint for discoverable credentials.
+   * @param opts.userName - WebAuthn `user.name` override.
+   * @param opts.userDisplayName - WebAuthn `user.displayName` override.
+   * @returns A {@link SignInResult} — typically `{ kind: "signedIn" }` on success.
+   *
+   * @example
+   * ```ts
+   * const result = await auth.passkey.register({ name: "My laptop" });
+   * ```
+   */
+  register(opts?: Record<string, any>): Promise<SignInResult>;
+
+  /**
+   * Authenticate with an existing passkey and complete the WebAuthn ceremony.
+   *
+   * @param opts - Optional authentication hints.
+   * @param opts.email - Email hint to filter discoverable credentials.
+   * @param opts.autofill - Set to `true` for conditional UI (autofill) mode.
+   * @returns A {@link SignInResult} — typically `{ kind: "signedIn" }` on success.
+   *
+   * @example
+   * ```ts
+   * const result = await auth.passkey.authenticate();
+   * ```
+   */
+  authenticate(opts?: Record<string, any>): Promise<SignInResult>;
+}
+
+/**
+ * TOTP two-factor authentication client-side helpers.
+ *
+ * @see {@link PasskeyClient}
+ * @see {@link DeviceClient}
+ */
+export interface TotpClient {
+  /**
+   * Start TOTP enrollment and return the setup URI, secret, verifier, and factor ID.
+   *
+   * The returned `uri` is an `otpauth://` URL that can be rendered as a QR code
+   * for the user to scan with their authenticator app.
+   *
+   * @param opts - Optional setup hints.
+   * @param opts.name - Issuer name shown in the authenticator app.
+   * @param opts.accountName - Account label in the authenticator app.
+   * @returns An object with `{ uri, secret, verifier, totpId }`.
+   *
+   * @example
+   * ```ts
+   * const { uri, secret, verifier, totpId } = await auth.totp.setup();
+   * // Render `uri` as a QR code, then confirm:
+   * await auth.totp.confirm({ code: userCode, verifier, totpId });
+   * ```
+   */
+  setup(opts?: Record<string, any>): Promise<Record<string, any>>;
+
+  /**
+   * Confirm a newly created TOTP factor with the first authenticator code.
+   *
+   * Call this after the user scans the QR code and enters the first OTP.
+   *
+   * @param opts - Confirmation parameters.
+   * @param opts.code - The 6-digit TOTP code from the authenticator app.
+   * @param opts.verifier - The verifier string returned by {@link TotpClient.setup}.
+   * @param opts.totpId - The factor ID returned by {@link TotpClient.setup}.
+   *
+   * @example
+   * ```ts
+   * await auth.totp.confirm({ code: "123456", verifier, totpId });
+   * ```
+   */
+  confirm(opts: Record<string, any>): Promise<void>;
+
+  /**
+   * Complete a sign-in that is waiting on TOTP verification.
+   *
+   * Called when `signIn()` returns `{ kind: "totpRequired" }`.
+   *
+   * @param opts - Verification parameters.
+   * @param opts.code - The 6-digit TOTP code from the authenticator app.
+   * @param opts.verifier - The verifier string from the `totpRequired` result.
+   *
+   * @example
+   * ```ts
+   * const result = await auth.signIn("password", { email, password });
+   * if (result.kind === "totpRequired") {
+   *   await auth.totp.verify({ code: totpCode, verifier: result.verifier });
+   * }
+   * ```
+   */
+  verify(opts: Record<string, any>): Promise<void>;
+}
+
+/**
+ * Device authorization (RFC 8628) client-side helpers.
+ *
+ * @see {@link PasskeyClient}
+ * @see {@link TotpClient}
+ */
+export interface DeviceClient {
+  /**
+   * Poll until a device flow is approved or expires.
+   *
+   * Polls the server at the interval specified in the {@link DeviceCodeResult}
+   * until the user authorizes the device or the code expires.
+   *
+   * @param opts - Poll options.
+   * @param opts.code - The {@link DeviceCodeResult} returned from `signIn("device")`.
+   * @returns `{ ok: true }` when authorized, or `{ ok: false, expired }` on failure.
+   *
+   * @example
+   * ```ts
+   * const result = await auth.signIn("device");
+   * if (result.kind === "deviceCode") {
+   *   // Display result.deviceCode.userCode to the user
+   *   const poll = await auth.device.poll({ code: result.deviceCode });
+   *   if (poll.ok) console.log("Device authorized!");
+   * }
+   * ```
+   */
+  poll(opts: {
+    code: DeviceCodeResult;
+  }): Promise<{ ok: true } | { ok: false; expired: boolean }>;
+
+  /**
+   * Approve a device flow from the verification page using the displayed user code.
+   *
+   * Call this on the authorization page where the user enters the short code
+   * shown on the device screen.
+   *
+   * @param opts - Verification options.
+   * @param opts.code - The user code string (e.g. `"WDJB-MJHT"`).
+   * @returns `{ ok: true }` on success, or `{ ok: false, message }` on failure.
+   *
+   * @example
+   * ```ts
+   * const result = await auth.device.verify({ code: "WDJB-MJHT" });
+   * if (!result.ok) console.error(result.message);
+   * ```
+   */
+  verify(opts: {
+    code: string;
+  }): Promise<{ ok: true } | { ok: false; message: string }>;
+}
+
+/**
+ * Extract capability flags from an AuthApiRefs type.
+ *
+ * @typeParam Api - An AuthApiRefs type to extract capability flags from.
+ */
+export type InferCaps<Api extends AuthApiRefs<boolean, boolean, boolean>> =
+  Api extends AuthApiRefs<infer P, infer T, infer D>
+    ? { passkey: P; totp: T; device: D }
+    : { passkey: boolean; totp: boolean; device: boolean };
+
+/** Pending invite detected from URL or recovered from storage after redirect. */
+export interface PendingInvite {
+  /**
+   * Raw one-time invite token. Pass to your invite acceptance mutation.
+   * @readonly
+   */
+  readonly token: string;
+  /**
+   * Invite email from the URL or stored redirect state, if available.
+   * @readonly
+   */
+  readonly email: string | null;
+  /** Consume the invite: clears storage/URL params and returns the token. */
+  accept(): Promise<{ ok: boolean; token?: string; message?: string }>;
+}
+
+/** Base auth client — always present. */
+export interface AuthClientBase {
+  /**
+   * Reactive auth state snapshot.
+   * @readonly
+   */
+  readonly state: AuthState;
+  /** SSR-safe query-param reader. */
+  param: (name: string) => string | null;
+  /**
+   * Pending invite recovered from the URL or storage, if present.
+   * @readonly
+   */
+  readonly invite: PendingInvite | null;
+  /** Start a sign-in flow for a provider. */
+  signIn: (
+    provider: string,
+    params?: Record<string, any>,
+  ) => Promise<SignInResult>;
+  /** Sign out and clear local auth state. */
+  signOut: () => Promise<void>;
+  /** Subscribe to auth state changes. Returns an unsubscribe function. */
+  onChange: (callback: (state: AuthState) => void) => () => void;
+  /** Tear down listeners and reject in-flight handshakes. */
+  destroy: () => void;
+}
+
+/**
+ * Auth client return type — conditionally includes `passkey`, `totp`, and
+ * `device` helpers based on the capabilities in the `AuthApiRefs` type.
+ *
+ * @typeParam Api - An AuthApiRefs type that determines which factor helpers are included.
+ */
+export type AuthClient<
+  Api extends AuthApiRefs<boolean, boolean, boolean> = AuthApiRefs,
+> = AuthClientBase &
+  (InferCaps<Api>["passkey"] extends true ? { passkey: PasskeyClient } : {}) &
+  (InferCaps<Api>["totp"] extends true ? { totp: TotpClient } : {}) &
+  (InferCaps<Api>["device"] extends true ? { device: DeviceClient } : {});
+
+/**
+ * Options for {@link client}.
+ *
+ * @typeParam Api - An AuthApiRefs type.
+ */
+export type ClientOptions<
+  Api extends AuthApiRefs<boolean, boolean, boolean> = AuthApiRefs,
+> = {
+  /** Any Convex client implementation used to run auth actions. */
+  convex: ConvexTransport;
+  /** Typed auth function refs from your generated `api` object. */
+  api?: Api;
+  /** Explicit Convex deployment URL when it cannot be inferred from the client. */
+  url?: string;
+  /**
+   * Storage backend for persisted tokens; defaults to `localStorage` in SPA mode.
+   *
+   * @defaultValue localStorage
+   */
+  storage?: Storage | null;
+  /** Override how OAuth code cleanup updates the current URL. */
+  replaceUrl?: (relativeUrl: string) => void | Promise<void>;
+  /** SSR proxy endpoint used instead of direct Convex auth calls. */
+  proxyPath?: string;
+  /** Server-provided JWT seed used for flash-free SSR hydration. */
+  tokenSeed?: string | null;
+  /** SSR-safe URL source for reading query parameters. */
+  location?: URL | (() => URL | null);
+};
+
+export type AuthHandshakeErrorCode =
+  | "AUTH_HANDSHAKE_TIMEOUT"
+  | "AUTH_HANDSHAKE_REJECTED";
+
+export type AuthFlowContext = {
+  provider?: string;
+  flow: string;
+};
+
+export type HandshakeWaiter = {
+  epoch: number;
+  context: AuthFlowContext;
+  resolve: () => void;
+  reject: (error: ConvexError<Value>) => void;
+  timeoutId: ReturnType<typeof setTimeout>;
+};

package/src/client/factors/device.ts

@@ -0,0 +1,160 @@
+import { Fx } from "@robelest/fx";
+import { ConvexError } from "convex/values";
+
+import type {
+  AuthSession,
+  ConvexTransport,
+  DeviceClient,
+  DeviceCodeResult,
+} from "../core/types";
+
+type DeviceDeps = {
+  proxy: string | undefined;
+  convex: ConvexTransport;
+  requireApiRefs: () => { signIn: any };
+  proxyFetch: (body: Record<string, unknown>) => Promise<any>;
+  setTokenAndMaybeWait: (
+    args:
+      | {
+          shouldStore: true;
+          tokens: AuthSession | null;
+          waitForHandshake: boolean;
+          context: { provider?: string; flow: string };
+        }
+      | {
+          shouldStore: false;
+          tokens: { token: string } | null;
+          waitForHandshake: boolean;
+          context: { provider?: string; flow: string };
+        },
+  ) => Promise<boolean>;
+};
+
+/** @internal */
+export function createDeviceClient(deps: DeviceDeps): DeviceClient {
+  const { proxy, convex, requireApiRefs, proxyFetch, setTokenAndMaybeWait } =
+    deps;
+
+  return {
+    poll: async (opts: {
+      code: DeviceCodeResult;
+    }): Promise<{ ok: true } | { ok: false; expired: boolean }> => {
+      const { code } = opts;
+      const intervalMs = code.interval * 1000;
+      const expiresAt = Date.now() + code.expiresIn * 1000;
+
+      while (Date.now() < expiresAt) {
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+
+        const pollResult = await Fx.run(
+          Fx.from({
+            ok: async () => {
+              let result: any;
+              const params: Record<string, any> = {
+                flow: "poll",
+                deviceCode: code.deviceCode,
+              };
+
+              if (proxy) {
+                result = await proxyFetch({
+                  action: "auth:signIn",
+                  args: { provider: "device", params },
+                });
+              } else {
+                result = await convex.action(requireApiRefs().signIn, {
+                  provider: "device",
+                  params,
+                });
+              }
+
+              return result;
+            },
+            err: (e) => e,
+          }).pipe(
+            Fx.recover((e: unknown) => {
+              const dispatch =
+                e instanceof ConvexError
+                  ? {
+                      tag:
+                        (e.data as Record<string, unknown> | undefined)
+                          ?.code === "DEVICE_AUTHORIZATION_PENDING"
+                          ? "continue"
+                          : (e.data as Record<string, unknown> | undefined)
+                                ?.code === "DEVICE_SLOW_DOWN"
+                            ? "slowDown"
+                            : "fatal",
+                    }
+                  : ({ tag: "fatal" } as const);
+
+              return Fx.match(dispatch, dispatch.tag, {
+                continue: () => Fx.succeed({ _poll: "continue" as const }),
+                slowDown: () => Fx.succeed({ _poll: "slow_down" as const }),
+                fatal: () => Fx.fatal(e),
+              });
+            }),
+          ),
+        );
+
+        if ("_poll" in pollResult) {
+          if (pollResult._poll === "slow_down") {
+            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+          }
+          continue;
+        }
+
+        if (pollResult.tokens) {
+          if (proxy) {
+            await setTokenAndMaybeWait({
+              shouldStore: false,
+              tokens:
+                pollResult.tokens === null
+                  ? null
+                  : { token: pollResult.tokens.token },
+              waitForHandshake: true,
+              context: { provider: "device", flow: "poll" },
+            });
+          } else {
+            await setTokenAndMaybeWait({
+              shouldStore: true,
+              tokens: (pollResult.tokens as AuthSession | null) ?? null,
+              waitForHandshake: true,
+              context: { provider: "device", flow: "poll" },
+            });
+          }
+          return { ok: true as const };
+        }
+      }
+
+      return { ok: false as const, expired: true };
+    },
+
+    verify: async (opts: {
+      code: string;
+    }): Promise<{ ok: true } | { ok: false; message: string }> => {
+      const params: Record<string, any> = {
+        flow: "verify",
+        userCode: opts.code,
+      };
+
+      try {
+        if (proxy) {
+          await proxyFetch({
+            action: "auth:signIn",
+            args: { provider: "device", params },
+          });
+        } else {
+          await convex.action(requireApiRefs().signIn, {
+            provider: "device",
+            params,
+          });
+        }
+        return { ok: true as const };
+      } catch (e: unknown) {
+        return {
+          ok: false as const,
+          message: e instanceof Error ? e.message : "Invalid or expired code.",
+        };
+      }
+    },
+  };
+}