@dbx-tools/ui-auth 0.6.91

package/README.md

@@ -0,0 +1,32 @@
+# `@dbx-tools/ui-auth`
+
+React passwordless authentication surfaces for `@dbx-tools/auth`.
+
+Key features:
+
+- email OTP sign-in with passkey actions presented underneath;
+- automatic conditional passkey mediation on supported browsers;
+- first-login passkey enrollment prompt;
+- authenticated passkey list, rename, add, and remove controls;
+- HttpOnly Better Auth sessions with no browser token storage;
+- AppKit and dbx-tools branding primitives.
+
+## Relationship To Native AppKit
+
+The native AppKit UI is sufficient when the Databricks Apps front door owns
+identity. Use this package with `@dbx-tools/auth` when a public tunnel bypasses
+that front door and needs passkey-first login plus email OTP recovery.
+
+```tsx
+import { AuthGate } from "@dbx-tools/ui-auth/react";
+
+root.render(
+  <AuthGate>
+    <App />
+  </AuthGate>,
+);
+```
+
+## Public subpaths
+
+- `@dbx-tools/ui-auth/react` - `AuthGate` and `PasskeyManager`.

package/index.ts

@@ -0,0 +1,12 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export const PACKAGE_IDENTIFIER = "@dbx-tools/ui-auth";
+export * as reactAuthClient from "./src/react/auth-client.ts";
+export * as reactAuthGate from "./src/react/auth-gate.tsx";
+export * as reactPasskeyManager from "./src/react/passkey-manager.tsx";
+export { AUTH_BASE } from "./src/react/auth-client.ts";
+export type { PasskeySummary } from "./src/react/auth-client.ts";
+export type { AuthGateProps } from "./src/react/auth-gate.tsx";
+export type { PasskeyManagerProps } from "./src/react/passkey-manager.tsx";

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@dbx-tools/ui-auth",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools.git",
+    "directory": "packages/js/ui/auth"
+  },
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/node": "^24.6.0",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@better-auth/passkey": "^1.6.25",
+    "@dbx-tools/shared-auth": "0.6.91",
+    "@dbx-tools/shared-core": "0.6.91",
+    "@dbx-tools/ui-appkit": "0.6.91",
+    "@dbx-tools/ui-branding": "0.6.91",
+    "better-auth": "^1.6.25",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.6.91",
+  "type": "module",
+  "exports": {
+    "./react": "./src/react/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.ts",
+    "src"
+  ],
+  "dbxToolsConfig": {
+    "tags": [
+      "ui"
+    ]
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"bunx projen\"."
+}

package/src/react/auth-client.ts

@@ -0,0 +1,55 @@
+import { passkeyClient } from "@better-auth/passkey/client";
+import { createAuthClient } from "better-auth/client";
+import { emailOTPClient } from "better-auth/client/plugins";
+
+export const AUTH_BASE = "/api/email/auth";
+
+const client = createAuthClient({
+  baseURL:
+    typeof window === "undefined"
+      ? `http://localhost${AUTH_BASE}`
+      : `${window.location.origin}${AUTH_BASE}`,
+  plugins: [emailOTPClient(), passkeyClient()],
+});
+
+export interface PasskeySummary {
+  id: string;
+  name?: string | null;
+  createdAt?: Date | string | null;
+  deviceType?: string | null;
+}
+
+export async function requestEmailOtp(email: string): Promise<boolean> {
+  const result = await client.emailOtp.sendVerificationOtp({ email, type: "sign-in" });
+  return result.error === null;
+}
+
+export async function verifyEmailOtp(email: string, otp: string, name: string): Promise<boolean> {
+  const result = await client.signIn.emailOtp({ email, otp, name });
+  return result.error === null;
+}
+
+export async function signInPasskey(autoFill = false): Promise<boolean> {
+  const result = await client.signIn.passkey({ autoFill });
+  return result.error === null;
+}
+
+export async function addPasskey(name?: string): Promise<boolean> {
+  const result = await client.passkey.addPasskey(name ? { name } : undefined);
+  return result.error === null;
+}
+
+export async function listPasskeys(): Promise<PasskeySummary[]> {
+  const result = await client.passkey.listUserPasskeys();
+  return result.data ?? [];
+}
+
+export async function renamePasskey(id: string, name: string): Promise<boolean> {
+  const result = await client.passkey.updatePasskey({ id, name });
+  return result.error === null;
+}
+
+export async function removePasskey(id: string): Promise<boolean> {
+  const result = await client.passkey.deletePasskey({ id });
+  return result.error === null;
+}

package/src/react/auth-gate.tsx

@@ -0,0 +1,234 @@
+import type { AuthStatus } from "@dbx-tools/shared-auth";
+import { net } from "@dbx-tools/shared-core";
+import { Button, Input } from "@dbx-tools/ui-appkit/react";
+import { BrandIcon, useBrand } from "@dbx-tools/ui-branding/react";
+import { type FormEvent, type ReactNode, useCallback, useEffect, useState } from "react";
+
+import {
+  addPasskey,
+  AUTH_BASE,
+  requestEmailOtp,
+  signInPasskey,
+  verifyEmailOtp,
+} from "./auth-client.ts";
+
+type Phase = "loading" | "email" | "code" | "enroll" | "authed" | "open";
+
+export interface AuthGateProps {
+  children: ReactNode;
+  title?: string;
+  description?: string;
+}
+
+/** Email OTP gate with conditional passkey sign-in and first-login enrollment. */
+export function AuthGate({ children, title, description }: AuthGateProps): ReactNode {
+  const { context: brand } = useBrand();
+  const [phase, setPhase] = useState<Phase>("loading");
+  const [email, setEmail] = useState("");
+  const [code, setCode] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [notice, setNotice] = useState<string | null>(null);
+  const [passkeysEnabled, setPasskeysEnabled] = useState(false);
+
+  useEffect(() => {
+    let cancelled = false;
+    void fetch(`${AUTH_BASE}/status`, { credentials: "same-origin" })
+      .then(async (response) => {
+        if (!response.ok) throw new Error(`Authentication status failed (${response.status})`);
+        return (await response.json()) as AuthStatus;
+      })
+      .then((status) => {
+        if (cancelled) return;
+        setPasskeysEnabled(status.passkeysEnabled === true);
+        setPhase(status.enabled ? (status.authenticated ? "authed" : "email") : "open");
+      })
+      .catch(() => {
+        if (!cancelled) setPhase("email");
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  useEffect(() => {
+    if (
+      !passkeysEnabled ||
+      phase !== "email" ||
+      typeof PublicKeyCredential === "undefined" ||
+      typeof PublicKeyCredential.isConditionalMediationAvailable !== "function"
+    ) {
+      return;
+    }
+    let cancelled = false;
+    // Conditional mediation cannot reveal whether a credential exists. It lets
+    // the browser offer one immediately on the focused `webauthn` input without
+    // showing an empty modal to users who have no passkey.
+    void PublicKeyCredential.isConditionalMediationAvailable().then(async (available) => {
+      if (!available || cancelled) return;
+      if ((await signInPasskey(true)) && !cancelled) setPhase("authed");
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [passkeysEnabled, phase]);
+
+  const requestCode = useCallback(
+    async (event: FormEvent) => {
+      event.preventDefault();
+      if (busy) return;
+      const addresses = net.parseEmails(email);
+      const address = addresses[0];
+      if (addresses.length !== 1 || !address || !net.isEmail(address)) {
+        setNotice("Enter a valid email address.");
+        return;
+      }
+      setBusy(true);
+      setNotice(null);
+      setEmail(address);
+      try {
+        if (!(await requestEmailOtp(address))) throw new Error("OTP request failed");
+        setNotice("If the address is authorized, a verification code is on its way.");
+        setPhase("code");
+      } catch {
+        setNotice("Unable to request a verification code. Try again.");
+      } finally {
+        setBusy(false);
+      }
+    },
+    [busy, email],
+  );
+
+  const verifyCode = useCallback(
+    async (event: FormEvent) => {
+      event.preventDefault();
+      if (!code.trim() || busy) return;
+      setBusy(true);
+      setNotice(null);
+      try {
+        if (!(await verifyEmailOtp(email, code.trim(), email.split("@")[0] || "User"))) {
+          throw new Error("OTP verification failed");
+        }
+        setPhase(passkeysEnabled ? "enroll" : "authed");
+      } catch {
+        setNotice("That verification code is incorrect or has expired.");
+      } finally {
+        setBusy(false);
+      }
+    },
+    [busy, code, email, passkeysEnabled],
+  );
+
+  const usePasskey = useCallback(async () => {
+    setBusy(true);
+    setNotice(null);
+    try {
+      if (!(await signInPasskey())) throw new Error("Passkey authentication failed");
+      setPhase("authed");
+    } catch {
+      setNotice("Unable to sign in with a passkey. Use email recovery instead.");
+    } finally {
+      setBusy(false);
+    }
+  }, []);
+
+  const enroll = useCallback(async () => {
+    setBusy(true);
+    setNotice(null);
+    try {
+      if (!(await addPasskey("Primary passkey"))) throw new Error("Passkey enrollment failed");
+      setPhase("authed");
+    } catch {
+      setNotice("Unable to create a passkey. You can continue with email recovery.");
+    } finally {
+      setBusy(false);
+    }
+  }, []);
+
+  if (phase === "authed" || phase === "open") return <>{children}</>;
+  if (phase === "loading") return null;
+
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-background p-6">
+      <div className="w-full max-w-sm rounded-lg border border-border bg-card p-6 shadow-sm">
+        <div className="mb-4 flex items-center gap-2 text-foreground">
+          <BrandIcon className="size-5" alt="" aria-hidden />
+          <h1 className="text-lg font-semibold">{title ?? `Sign in to ${brand.name}`}</h1>
+        </div>
+        <p className="mb-4 text-sm text-muted-foreground">
+          {description ??
+            (phase === "code"
+              ? "Enter the 6-digit verification code sent to your email address."
+              : phase === "enroll"
+                ? "Create a passkey for faster, phishing-resistant sign-in next time."
+                : "Enter your email for a one-time code, or use a passkey.")}
+        </p>
+
+        {phase === "email" ? (
+          <form noValidate onSubmit={requestCode} className="space-y-3">
+            <Input
+              type="email"
+              autoComplete="email webauthn"
+              autoFocus
+              aria-label="Email address"
+              placeholder="you@example.com"
+              value={email}
+              onChange={(event) => setEmail(event.target.value)}
+              required
+            />
+            <Button type="submit" disabled={busy} className="w-full">
+              Sign in with email OTP
+            </Button>
+            {passkeysEnabled ? (
+              <Button
+                type="button"
+                variant="outline"
+                disabled={busy}
+                className="w-full"
+                onClick={usePasskey}
+              >
+                Sign in with a passkey
+              </Button>
+            ) : null}
+          </form>
+        ) : phase === "code" ? (
+          <form onSubmit={verifyCode} className="space-y-3">
+            <Input
+              type="text"
+              inputMode="numeric"
+              autoComplete="one-time-code"
+              aria-label="Verification code"
+              placeholder="6-digit verification code"
+              maxLength={6}
+              value={code}
+              onChange={(event) => setCode(event.target.value)}
+              required
+            />
+            <Button type="submit" disabled={busy} className="w-full">
+              Continue
+            </Button>
+          </form>
+        ) : (
+          <div className="space-y-3">
+            <Button type="button" disabled={busy} className="w-full" onClick={enroll}>
+              Create a passkey
+            </Button>
+            <Button
+              type="button"
+              variant="ghost"
+              className="w-full"
+              onClick={() => setPhase("authed")}
+            >
+              Not now
+            </Button>
+          </div>
+        )}
+
+        {notice ? (
+          <p role="status" aria-live="polite" className="mt-3 text-xs text-muted-foreground">
+            {notice}
+          </p>
+        ) : null}
+      </div>
+    </div>
+  );
+}

package/src/react/index.ts

@@ -0,0 +1,2 @@
+export { AuthGate, type AuthGateProps } from "./auth-gate.tsx";
+export { PasskeyManager, type PasskeyManagerProps } from "./passkey-manager.tsx";

package/src/react/passkey-manager.tsx

@@ -0,0 +1,130 @@
+import { Button, Input } from "@dbx-tools/ui-appkit/react";
+import { type ReactNode, useCallback, useEffect, useState } from "react";
+
+import {
+  addPasskey,
+  listPasskeys,
+  type PasskeySummary,
+  removePasskey,
+  renamePasskey,
+} from "./auth-client.ts";
+
+export interface PasskeyManagerProps {
+  className?: string;
+}
+
+/** Authenticated management surface for a user's Better Auth passkeys. */
+export function PasskeyManager({ className }: PasskeyManagerProps): ReactNode {
+  const [passkeys, setPasskeys] = useState<PasskeySummary[]>([]);
+  const [names, setNames] = useState<Record<string, string>>({});
+  const [busy, setBusy] = useState(false);
+  const [notice, setNotice] = useState<string | null>(null);
+
+  const refresh = useCallback(async () => {
+    const values = await listPasskeys();
+    setPasskeys(values);
+    setNames(Object.fromEntries(values.map((passkey) => [passkey.id, passkey.name ?? "Passkey"])));
+  }, []);
+
+  useEffect(() => {
+    void refresh().catch(() => setNotice("Unable to load passkeys."));
+  }, [refresh]);
+
+  const add = useCallback(async () => {
+    setBusy(true);
+    setNotice(null);
+    try {
+      if (!(await addPasskey())) throw new Error("Passkey enrollment failed");
+      await refresh();
+    } catch {
+      setNotice("Unable to add a passkey.");
+    } finally {
+      setBusy(false);
+    }
+  }, [refresh]);
+
+  const rename = useCallback(
+    async (id: string) => {
+      const name = names[id]?.trim();
+      if (!name) return;
+      setBusy(true);
+      try {
+        if (!(await renamePasskey(id, name))) throw new Error("Passkey rename failed");
+        await refresh();
+      } catch {
+        setNotice("Unable to rename the passkey.");
+      } finally {
+        setBusy(false);
+      }
+    },
+    [names, refresh],
+  );
+
+  const remove = useCallback(
+    async (id: string) => {
+      setBusy(true);
+      try {
+        if (!(await removePasskey(id))) throw new Error("Passkey removal failed");
+        await refresh();
+      } catch {
+        setNotice("Unable to remove the passkey.");
+      } finally {
+        setBusy(false);
+      }
+    },
+    [refresh],
+  );
+
+  return (
+    <section className={className} aria-label="Passkeys">
+      <div className="mb-3 flex items-center justify-between gap-3">
+        <div>
+          <h2 className="font-medium text-foreground">Passkeys</h2>
+          <p className="text-sm text-muted-foreground">
+            Add more than one device so email remains recovery, not your daily sign-in.
+          </p>
+        </div>
+        <Button type="button" onClick={add} disabled={busy}>
+          Add passkey
+        </Button>
+      </div>
+      <div className="space-y-2">
+        {passkeys.map((passkey) => (
+          <div key={passkey.id} className="flex items-center gap-2 rounded-md border p-2">
+            <Input
+              aria-label="Passkey name"
+              value={names[passkey.id] ?? ""}
+              onChange={(event) =>
+                setNames((current) => ({ ...current, [passkey.id]: event.target.value }))
+              }
+            />
+            <Button
+              type="button"
+              variant="outline"
+              disabled={busy}
+              onClick={() => rename(passkey.id)}
+            >
+              Save
+            </Button>
+            <Button
+              type="button"
+              variant="ghost"
+              disabled={busy}
+              onClick={() => remove(passkey.id)}
+            >
+              Remove
+            </Button>
+          </div>
+        ))}
+        {passkeys.length === 0 ? (
+          <p className="text-sm text-muted-foreground">No passkeys enrolled.</p>
+        ) : null}
+      </div>
+      {notice ? (
+        <p role="status" className="mt-2 text-sm text-muted-foreground">
+          {notice}
+        </p>
+      ) : null}
+    </section>
+  );
+}