@oxyhq/services 21.0.0 → 22.0.0

package/src/ui/boot/runProviderColdBoot.ts

@@ -8,6 +8,7 @@ import type { SessionClient } from '@oxyhq/core';
 import { loadPersistedDeviceCredential } from '../utils/deviceCredential';
 import {
   consumeSilentOAuthError,
+  isSilentRestoreEligibleOrigin,
   maybeStartSilentOAuthRestore,
 } from '../utils/crossOriginRestore';
 import { tryCompleteOAuthReturn, consumeHubSyncFailure } from '../utils/oauthReturn';
@@ -22,6 +23,12 @@ export interface RunProviderColdBootOptions {
   authStore: AuthStateStore;
   clientId?: string;
   authRedirectUri?: string;
+  /**
+   * Authorize endpoint override for silent cross-origin restore. Defaults to
+   * the production Oxy IdP when unset; a local/staging deployment sets it so the
+   * silent-restore redirect targets its own IdP, never production.
+   */
+  authorizeBaseUrl?: string;
   sessionClient: SessionClient;
   syncDeviceCredentialToHost: () => Promise<void>;
   commitSession: (
@@ -46,6 +53,7 @@ export async function runProviderColdBoot(opts: RunProviderColdBootOptions): Pro
     authStore,
     clientId,
     authRedirectUri,
+    authorizeBaseUrl,
     sessionClient,
     syncDeviceCredentialToHost,
     commitSession,
@@ -129,11 +137,26 @@ export async function runProviderColdBoot(opts: RunProviderColdBootOptions): Pro
       },
     });
 
-    if (isWebBrowser() && clientId && outcome.kind !== 'session') {
+    // Silent cross-origin OAuth restore (web cross-app SSO). Gate it the SAME
+    // way the hub-sync WRITE side (`syncHubAfterSignIn`) gates: official web
+    // origins only, never the IdP hub itself, and — unlike the write side —
+    // never a loopback / local-dev origin (which must not be bounced to a hosted
+    // IdP on cold boot). The authorize endpoint is env-configurable so a
+    // local/staging app targets its own IdP instead of production.
+    const webOrigin = isWebBrowser()
+      ? (globalThis as { location?: Location }).location?.origin
+      : undefined;
+    if (
+      clientId &&
+      outcome.kind !== 'session' &&
+      webOrigin &&
+      isSilentRestoreEligibleOrigin(webOrigin)
+    ) {
       const redirected = await maybeStartSilentOAuthRestore({
         oxyServices,
         clientId,
         redirectUri: authRedirectUri,
+        authorizeBaseUrl,
       });
       if (redirected) {
         return;

package/src/ui/components/OxyAccountDialog.tsx

@@ -62,9 +62,11 @@ import {
   type AppColorName,
 } from '@oxyhq/bloom/theme';
 import type { SwitchableAccount, AccountDialogSnapshot } from '@oxyhq/core';
+import { isOxyRpOrigin } from '@oxyhq/core';
 import { useQueryClient } from '@tanstack/react-query';
 import { useOxy } from '../context/OxyContext';
 import { useI18n } from '../hooks/useI18n';
+import { isWebBrowser } from '../utils/isWebBrowser';
 import { LogoIcon } from './logo/LogoIcon';
 
 /** Diameter of a row avatar. */
@@ -112,11 +114,38 @@ const OxyAccountDialog: React.FC = () => {
     showBottomSheet,
     logoutAll,
     refreshAccounts,
+    signInWithPasskey,
   } = useOxy();
   const theme = useTheme();
   const { t } = useI18n();
   const queryClient = useQueryClient();
 
+  // Passkey sign-in is offered ONLY on a first-party Oxy web origin (a credential
+  // minted for `oxy.so` can only be asserted there or on a loopback dev host).
+  // Off the web / on a non-Oxy origin the button is hidden entirely (a hub popup
+  // for arbitrary web origins is a later phase). This is environment-static.
+  const passkeyAvailable = useMemo(() => isWebBrowser() && isOxyRpOrigin(), []);
+  const [passkeyPending, setPasskeyPending] = useState(false);
+  const [passkeyError, setPasskeyError] = useState<string | null>(null);
+
+  const handleSignInWithPasskey = useCallback(async () => {
+    if (passkeyPending) return;
+    setPasskeyPending(true);
+    setPasskeyError(null);
+    try {
+      await signInWithPasskey();
+      closeAccountDialog();
+    } catch (error) {
+      // A cancelled/failed ceremony keeps the dialog open so the user can retry
+      // or fall back to another method — surface a concise message, never swallow.
+      setPasskeyError(
+        error instanceof Error && error.message ? error.message : 'Passkey sign-in failed.',
+      );
+    } finally {
+      setPasskeyPending(false);
+    }
+  }, [passkeyPending, signInWithPasskey, closeAccountDialog]);
+
   // Bind the headless controller. `getSnapshot` returns a stable reference
   // between changes, so it is `useSyncExternalStore`-safe. Guard the no-provider
   // loading state (`controller` is `null`) with an inert store.
@@ -221,7 +250,9 @@ const OxyAccountDialog: React.FC = () => {
             handlers={handlers}
             onSignInWithOxy={() => void controller.signInWithOxy()}
             onScanQr={() => void controller.showQr()}
-            onUsePassword={() => void controller.openPasswordAtOxyAuth()}
+            onSignInWithPasskey={passkeyAvailable ? () => void handleSignInWithPasskey() : undefined}
+            passkeyPending={passkeyPending}
+            passkeyError={passkeyError}
           />
         )}
       </ScrollView>
@@ -415,7 +446,10 @@ interface SignInViewProps {
   handlers: OxyAccountDialogHandlers;
   onSignInWithOxy: () => void;
   onScanQr: () => void;
-  onUsePassword: () => void;
+  /** When present, offer a "Sign in with a passkey" button (first-party Oxy web only). */
+  onSignInWithPasskey?: () => void;
+  passkeyPending: boolean;
+  passkeyError: string | null;
 }
 
 const SignInView: React.FC<SignInViewProps> = ({
@@ -425,7 +459,9 @@ const SignInView: React.FC<SignInViewProps> = ({
   handlers,
   onSignInWithOxy,
   onScanQr,
-  onUsePassword,
+  onSignInWithPasskey,
+  passkeyPending,
+  passkeyError,
 }) => (
   <View style={styles.signInBlock}>
     {snapshot.accounts.length > 0 ? (
@@ -448,15 +484,27 @@ const SignInView: React.FC<SignInViewProps> = ({
       Sign in with Oxy
     </Button>
 
+    {onSignInWithPasskey ? (
+      <Button
+        variant="secondary"
+        onPress={onSignInWithPasskey}
+        disabled={passkeyPending}
+        style={styles.secondaryButton}
+        testID="passkey-signin-button"
+      >
+        {passkeyPending
+          ? t('accountSwitcher.passkeySigningIn') || 'Signing in…'
+          : t('accountSwitcher.signInWithPasskey') || 'Sign in with a passkey'}
+      </Button>
+    ) : null}
+
+    {passkeyError ? (
+      <Text style={[styles.errorText, { color: theme.colors.error }]}>{passkeyError}</Text>
+    ) : null}
+
     <Button variant="secondary" onPress={onScanQr} style={styles.secondaryButton}>
       {t('accountSwitcher.scanQr') || 'Scan a QR from another device'}
     </Button>
-
-    <Pressable onPress={onUsePassword} accessibilityRole="button" style={styles.passwordLink}>
-      <Text style={[styles.linkText, { color: theme.colors.textSecondary }]}>
-        Use a password instead
-      </Text>
-    </Pressable>
   </View>
 );
 
@@ -681,11 +729,6 @@ const styles = StyleSheet.create({
     borderRadius: 14,
     marginTop: 10,
   },
-  passwordLink: {
-    alignSelf: 'center',
-    paddingVertical: 10,
-    marginTop: 12,
-  },
   dividerRow: {
     flexDirection: 'row',
     alignItems: 'center',

package/src/ui/components/OxyProvider.tsx

@@ -114,6 +114,7 @@ const OxyProvider: FC<OxyProviderProps> = ({
     baseURL,
     authWebUrl,
     authRedirectUri,
+    authorizeBaseUrl,
     queryClient: providedQueryClient,
     requireAuth = 'off',
     hubSync = true,
@@ -309,6 +310,7 @@ const OxyProvider: FC<OxyProviderProps> = ({
                     baseURL={baseURL}
                     authWebUrl={authWebUrl}
                     authRedirectUri={authRedirectUri}
+                    authorizeBaseUrl={authorizeBaseUrl}
                     storageKeyPrefix={storageKeyPrefix}
                     clientId={clientId}
                     hubSync={hubSync}

package/src/ui/context/OxyContext.tsx

@@ -27,7 +27,6 @@ import {
   logger as loggerUtil,
   syncHubAfterSignIn,
 } from '@oxyhq/core';
-import type { SecurityAlert } from '@oxyhq/contracts';
 import {
   registerAccountDialogControls,
   notifyAccountDialogVisibility,
@@ -59,15 +58,21 @@ import {
 } from '../session';
 import type {
   OxyContextState,
-  PasswordSignInResult,
   OxyContextProviderProps,
   CommitInput,
 } from './oxyContextTypes';
 import { DEFAULT_SESSION_VALIDITY_MS, loadUseFollowHook } from './oxyContextHelpers';
 import { commitDeviceSetAndResolve } from './commitSessionFlow';
+import { runPasskeyLogin, runPasskeyRegister, runPasskeyAdd } from './passkeyFlow';
+import {
+  isPasskeySupported,
+  runRegistrationCeremony,
+  runAuthenticationCeremony,
+} from '../../webauthn/passkeyClient';
+import { queryKeys } from '../hooks/queries/queryKeys';
 import { useOxyAccountGraph } from './useOxyAccountGraph';
 
-export type { OxyContextState, PasswordSignInResult, OxyContextProviderProps } from './oxyContextTypes';
+export type { OxyContextState, OxyContextProviderProps } from './oxyContextTypes';
 
 const OxyContext = createContext<OxyContextState | null>(null);
 
@@ -77,6 +82,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   baseURL,
   authWebUrl,
   authRedirectUri,
+  authorizeBaseUrl,
   storageKeyPrefix = 'oxy_session',
   clientId: clientIdProp,
   hubSync = true,
@@ -615,7 +621,6 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       oxyServices,
       sessionClient,
       clientId,
-      authRedirectUri,
       locale: currentLanguage,
       // Same statically-injected `io` as the SessionClient: gives the QR flow an
       // instant `/auth-session` `auth_update` wake instead of a slow poll.
@@ -669,72 +674,81 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     notifyAccountDialogVisibility(accountDialogOpen);
   }, [accountDialogOpen]);
 
-  // Keyless password sign-in: username/email + password.
-  const signInWithPassword = useCallback(
-    async (
-      identifier: string,
-      password: string,
-      opts?: { deviceName?: string; deviceFingerprint?: string },
-    ): Promise<PasswordSignInResult> => {
+  // ── Passkey (WebAuthn) ─────────────────────────────────────────────────────
+  // Web-only sign-in / registration via the browser WebAuthn ceremony. The fixed
+  // `options → ceremony → verify → commit` ordering lives in the pure
+  // `passkeyFlow` helpers (deps-injected, unit-tested); these wrappers supply the
+  // real deps (core `webauthn*` methods, the platform ceremony client, and the
+  // `commitSession` funnel). All three GATE on `isPasskeySupported()` so a native
+  // / unsupported surface throws loudly instead of stalling in a ceremony.
+
+  // Passkey sign-in. No `username` → usernameless (discoverable) flow. With a
+  // `username` → username-first: the server scopes `allowCredentials` to that
+  // user's passkeys so a non-discoverable hardware key (U2F/security key) can
+  // be selected.
+  const signInWithPasskey = useCallback(
+    async (opts?: { username?: string; deviceName?: string; deviceFingerprint?: string }): Promise<void> => {
       const persisted = await authStore.load();
-      const result = await oxyServices.passwordSignIn(identifier, password, {
+      await runPasskeyLogin({
+        isSupported: isPasskeySupported,
+        getLoginOptions: (username) => oxyServices.webauthnLoginOptions(username),
+        runCeremony: runAuthenticationCeremony,
+        loginVerify: (response, envelope) => oxyServices.webauthnLoginVerify(response, envelope),
+        commit: (input) => commitSession(input, { activate: true, hubSync: true }),
+        username: opts?.username,
+        deviceId: persisted?.deviceId,
         deviceName: opts?.deviceName,
         deviceFingerprint: opts?.deviceFingerprint,
-        deviceId: persisted?.deviceId,
       });
-      if ('twoFactorRequired' in result) {
-        return { status: '2fa_required', loginToken: result.loginToken };
-      }
-      // `passwordSignIn` already planted the access token on the session arm.
-      await commitSession(
-        {
-          sessionId: result.sessionId,
-          accessToken: result.accessToken,
-          deviceSecret: result.deviceSecret,
-          deviceId: result.deviceId,
-          expiresAt: result.expiresAt,
-          userId: result.user.id,
-          user: result.user,
-        },
-        { activate: true, hubSync: true },
-      );
-      return { status: 'ok', ...(result.securityAlert ? { securityAlert: result.securityAlert } : {}) };
     },
-    [oxyServices, commitSession],
+    [oxyServices, authStore, commitSession],
   );
 
-  const completeTwoFactorSignIn = useCallback(
-    async (params: {
-      loginToken: string;
-      token?: string;
-      backupCode?: string;
-      deviceName?: string;
-    }): Promise<{ securityAlert?: SecurityAlert }> => {
-      const persisted = await authStore.load();
-      const result = await oxyServices.completeTwoFactorSignIn({
-        loginToken: params.loginToken,
-        token: params.token,
-        backupCode: params.backupCode,
+  // Create a brand-new account whose first auth method is a passkey.
+  const registerWithPasskey = useCallback(
+    async (params: { username: string; deviceName?: string }): Promise<void> => {
+      await runPasskeyRegister({
+        isSupported: isPasskeySupported,
+        getRegisterOptions: (username) => oxyServices.webauthnRegisterOptions(username),
+        runCeremony: runRegistrationCeremony,
+        registerVerify: (response, envelope) => oxyServices.webauthnRegisterVerify(response, envelope),
+        commit: (input) => commitSession(input, { activate: true, hubSync: true }),
+        username: params.username,
         deviceName: params.deviceName,
-        deviceId: persisted?.deviceId,
       });
-      await commitSession(
-        {
-          sessionId: result.sessionId,
-          accessToken: result.accessToken,
-          deviceSecret: result.deviceSecret,
-          deviceId: result.deviceId,
-          expiresAt: result.expiresAt,
-          userId: result.user.id,
-          user: result.user,
-        },
-        { activate: true, hubSync: true },
-      );
-      return { securityAlert: result.securityAlert };
     },
     [oxyServices, commitSession],
   );
 
+  // Add a passkey to the already-signed-in account (bearer present). No new
+  // session is committed — just refresh the linked auth-methods list.
+  const addPasskey = useCallback(
+    async (params?: { deviceName?: string }): Promise<void> => {
+      await runPasskeyAdd({
+        isSupported: isPasskeySupported,
+        getRegisterOptions: () => oxyServices.webauthnRegisterOptions(),
+        runCeremony: runRegistrationCeremony,
+        registerVerify: (response, envelope) => oxyServices.webauthnRegisterVerify(response, envelope),
+        onLinked: () => {
+          void queryClient.invalidateQueries({ queryKey: queryKeys.authMethods.all });
+        },
+        deviceName: params?.deviceName,
+      });
+    },
+    [oxyServices, queryClient],
+  );
+
+  // Remove a passkey from the already-signed-in account by credential id. Not a
+  // ceremony — a plain unlink — so it needs no `isPasskeySupported` gate; it just
+  // refreshes the linked auth-methods list on success.
+  const removePasskey = useCallback(
+    async (credentialId: string): Promise<void> => {
+      await oxyServices.removePasskey(credentialId);
+      void queryClient.invalidateQueries({ queryKey: queryKeys.authMethods.all });
+    },
+    [oxyServices, queryClient],
+  );
+
   // ── Cold boot ────────────────────────────────────────────────────────────
   // Device-first session restore via `runProviderColdBoot` (see boot/runProviderColdBoot.ts).
   const runColdBoot = useCallback(async (): Promise<void> => {
@@ -743,6 +757,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       authStore,
       clientId: clientIdProp,
       authRedirectUri,
+      authorizeBaseUrl,
       sessionClient,
       syncDeviceCredentialToHost,
       commitSession: (input, options) => commitSessionRef.current(input, options),
@@ -754,6 +769,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     authStore,
     clientIdProp,
     authRedirectUri,
+    authorizeBaseUrl,
     syncDeviceCredentialToHost,
     sessionClient,
   ]);
@@ -883,8 +899,10 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       hasIdentity,
       getPublicKey,
       signIn,
-      signInWithPassword,
-      completeTwoFactorSignIn,
+      signInWithPasskey,
+      registerWithPasskey,
+      addPasskey,
+      removePasskey,
       revokeSuspiciousSignIn,
       handleWebSession,
       logout,
@@ -935,8 +953,10 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       hasIdentity,
       getPublicKey,
       signIn,
-      signInWithPassword,
-      completeTwoFactorSignIn,
+      signInWithPasskey,
+      registerWithPasskey,
+      addPasskey,
+      removePasskey,
       revokeSuspiciousSignIn,
       handleWebSession,
       logout,
@@ -1005,8 +1025,10 @@ const LOADING_STATE: OxyContextState = {
   hasIdentity: () => Promise.resolve(false),
   getPublicKey: () => Promise.resolve(null),
   signIn: () => rejectMissingProvider<User>(),
-  signInWithPassword: () => rejectMissingProvider<PasswordSignInResult>(),
-  completeTwoFactorSignIn: () => rejectMissingProvider<{ securityAlert?: SecurityAlert }>(),
+  signInWithPasskey: () => rejectMissingProvider<void>(),
+  registerWithPasskey: () => rejectMissingProvider<void>(),
+  addPasskey: () => rejectMissingProvider<void>(),
+  removePasskey: () => rejectMissingProvider<void>(),
   revokeSuspiciousSignIn: () => rejectMissingProvider<void>(),
   handleWebSession: () => rejectMissingProvider<void>(),
   logout: () => rejectMissingProvider<void>(),

package/src/ui/context/__tests__/passkeyFlow.test.ts

@@ -0,0 +1,244 @@
+/**
+ * `passkeyFlow` — the pure, deps-injected passkey (WebAuthn) orchestration that
+ * backs `useOxy().signInWithPasskey` / `registerWithPasskey` / `addPasskey`.
+ *
+ * These tests assert the fixed `options → ceremony → verify → commit` ordering,
+ * the exact `commitSession` input projected from a session-arm login result, the
+ * `isSupported()` gate, and the branch discipline (sign-in/register commit a
+ * session; add links WITHOUT committing and fires `onLinked`) — the same
+ * deps-injection style `commitSessionFlow.test.ts` uses.
+ */
+
+import type { LoginSessionResult } from '@oxyhq/contracts';
+import {
+  runPasskeyLogin,
+  runPasskeyRegister,
+  runPasskeyAdd,
+  PASSKEY_UNSUPPORTED_MESSAGE,
+  type RunPasskeyLoginDeps,
+  type RunPasskeyRegisterDeps,
+  type RunPasskeyAddDeps,
+  type PasskeyRegisterVerifyResult,
+} from '../passkeyFlow';
+import type { CommitInput } from '../oxyContextTypes';
+
+const SESSION_USER_ID = 'user_pk_1';
+
+/** A full session arm of the login contract (mirrors `webauthn*Verify`'s signup/login output). */
+const sessionResult: LoginSessionResult = {
+  sessionId: 'sess_pk',
+  deviceId: 'dev_pk',
+  accessToken: 'pk.access.token',
+  deviceSecret: 'pk.device.secret',
+  expiresAt: new Date(Date.now() + 3_600_000).toISOString(),
+  user: { id: SESSION_USER_ID, username: 'pkuser' },
+};
+
+/** The `commitSession` input the flow projects from `sessionResult`. */
+const expectedCommitInput: CommitInput = {
+  sessionId: 'sess_pk',
+  accessToken: 'pk.access.token',
+  deviceSecret: 'pk.device.secret',
+  deviceId: 'dev_pk',
+  expiresAt: sessionResult.expiresAt,
+  userId: SESSION_USER_ID,
+  user: { id: SESSION_USER_ID, username: 'pkuser' },
+};
+
+const linkResult: PasskeyRegisterVerifyResult = { success: true, message: 'Passkey added' };
+
+describe('runPasskeyLogin', () => {
+  const buildDeps = (
+    order: string[],
+    overrides: Partial<RunPasskeyLoginDeps> = {},
+  ): RunPasskeyLoginDeps => ({
+    isSupported: jest.fn(() => true),
+    getLoginOptions: jest.fn(async () => {
+      order.push('getLoginOptions');
+      return { challenge: 'login-opts' };
+    }),
+    runCeremony: jest.fn(async (options) => {
+      order.push('runCeremony');
+      expect(options).toEqual({ challenge: 'login-opts' });
+      return { id: 'assertion' };
+    }),
+    loginVerify: jest.fn(async () => {
+      order.push('loginVerify');
+      return sessionResult;
+    }),
+    commit: jest.fn(async () => {
+      order.push('commit');
+    }),
+    deviceId: 'persisted-dev',
+    deviceName: 'My Laptop',
+    deviceFingerprint: 'fp-123',
+    ...overrides,
+  });
+
+  it('drives options → ceremony → verify → commit and threads the device envelope', async () => {
+    const order: string[] = [];
+    const deps = buildDeps(order);
+
+    await runPasskeyLogin(deps);
+
+    expect(order).toEqual(['getLoginOptions', 'runCeremony', 'loginVerify', 'commit']);
+    // The assertion response is forwarded to verify with the device envelope.
+    expect(deps.loginVerify).toHaveBeenCalledWith(
+      { id: 'assertion' },
+      { deviceName: 'My Laptop', deviceFingerprint: 'fp-123', deviceId: 'persisted-dev' },
+    );
+    // The session arm is projected onto the exact commitSession input.
+    expect(deps.commit).toHaveBeenCalledWith(expectedCommitInput);
+  });
+
+  it('forwards the username to getLoginOptions for the username-first (hardware-key) path', async () => {
+    const order: string[] = [];
+    const deps = buildDeps(order, { username: 'alice' });
+
+    await runPasskeyLogin(deps);
+
+    // The username scopes login options to that user's passkeys — the path a
+    // non-discoverable U2F/security key needs.
+    expect(deps.getLoginOptions).toHaveBeenCalledWith('alice');
+  });
+
+  it('passes undefined to getLoginOptions for the usernameless (discoverable) path', async () => {
+    const order: string[] = [];
+    const deps = buildDeps(order);
+
+    await runPasskeyLogin(deps);
+
+    // No username → discoverable-credential ceremony (server returns an empty allow-list).
+    expect(deps.getLoginOptions).toHaveBeenCalledWith(undefined);
+  });
+
+  it('throws and touches nothing when passkeys are unsupported', async () => {
+    const order: string[] = [];
+    const deps = buildDeps(order, { isSupported: jest.fn(() => false) });
+
+    await expect(runPasskeyLogin(deps)).rejects.toThrow(PASSKEY_UNSUPPORTED_MESSAGE);
+    expect(deps.getLoginOptions).not.toHaveBeenCalled();
+    expect(deps.commit).not.toHaveBeenCalled();
+  });
+});
+
+describe('runPasskeyRegister', () => {
+  const buildDeps = (
+    order: string[],
+    overrides: Partial<RunPasskeyRegisterDeps> = {},
+  ): RunPasskeyRegisterDeps => ({
+    isSupported: jest.fn(() => true),
+    getRegisterOptions: jest.fn(async (username) => {
+      order.push('getRegisterOptions');
+      expect(username).toBe('newuser');
+      return { challenge: 'reg-opts' };
+    }),
+    runCeremony: jest.fn(async () => {
+      order.push('runCeremony');
+      return { id: 'attestation' };
+    }),
+    registerVerify: jest.fn(async () => {
+      order.push('registerVerify');
+      return sessionResult;
+    }),
+    commit: jest.fn(async () => {
+      order.push('commit');
+    }),
+    username: 'newuser',
+    deviceName: 'My Laptop',
+    ...overrides,
+  });
+
+  it('creates the account (signup branch) and commits the minted session', async () => {
+    const order: string[] = [];
+    const deps = buildDeps(order);
+
+    await runPasskeyRegister(deps);
+
+    expect(order).toEqual(['getRegisterOptions', 'runCeremony', 'registerVerify', 'commit']);
+    expect(deps.registerVerify).toHaveBeenCalledWith(
+      { id: 'attestation' },
+      { username: 'newuser', deviceName: 'My Laptop' },
+    );
+    expect(deps.commit).toHaveBeenCalledWith(expectedCommitInput);
+  });
+
+  it('throws (no commit) when verify returns a link branch instead of a session', async () => {
+    const order: string[] = [];
+    const deps = buildDeps(order, {
+      registerVerify: jest.fn(async () => linkResult),
+    });
+
+    await expect(runPasskeyRegister(deps)).rejects.toThrow(/did not establish a session/i);
+    expect(deps.commit).not.toHaveBeenCalled();
+  });
+
+  it('throws and touches nothing when passkeys are unsupported', async () => {
+    const order: string[] = [];
+    const deps = buildDeps(order, { isSupported: jest.fn(() => false) });
+
+    await expect(runPasskeyRegister(deps)).rejects.toThrow(PASSKEY_UNSUPPORTED_MESSAGE);
+    expect(deps.getRegisterOptions).not.toHaveBeenCalled();
+    expect(deps.commit).not.toHaveBeenCalled();
+  });
+});
+
+describe('runPasskeyAdd', () => {
+  const buildDeps = (
+    order: string[],
+    overrides: Partial<RunPasskeyAddDeps> = {},
+  ): RunPasskeyAddDeps => ({
+    isSupported: jest.fn(() => true),
+    getRegisterOptions: jest.fn(async () => {
+      order.push('getRegisterOptions');
+      return { challenge: 'add-opts' };
+    }),
+    runCeremony: jest.fn(async () => {
+      order.push('runCeremony');
+      return { id: 'attestation' };
+    }),
+    registerVerify: jest.fn(async () => {
+      order.push('registerVerify');
+      return linkResult;
+    }),
+    onLinked: jest.fn(() => {
+      order.push('onLinked');
+    }),
+    deviceName: 'My Laptop',
+    ...overrides,
+  });
+
+  it('links the passkey WITHOUT committing a session and fires onLinked', async () => {
+    const order: string[] = [];
+    const deps = buildDeps(order);
+
+    await runPasskeyAdd(deps);
+
+    expect(order).toEqual(['getRegisterOptions', 'runCeremony', 'registerVerify', 'onLinked']);
+    // Add requests options with NO username (bearer scopes it to the signed-in user).
+    expect(deps.getRegisterOptions).toHaveBeenCalledWith();
+    expect(deps.registerVerify).toHaveBeenCalledWith({ id: 'attestation' }, { deviceName: 'My Laptop' });
+    expect(deps.onLinked).toHaveBeenCalledTimes(1);
+    // There is no `commit` dependency at all — structurally cannot commit a session.
+    expect('commit' in deps).toBe(false);
+  });
+
+  it('throws (no onLinked) if verify unexpectedly mints a session', async () => {
+    const order: string[] = [];
+    const deps = buildDeps(order, {
+      registerVerify: jest.fn(async () => sessionResult),
+    });
+
+    await expect(runPasskeyAdd(deps)).rejects.toThrow(/instead of linking/i);
+    expect(deps.onLinked).not.toHaveBeenCalled();
+  });
+
+  it('throws and touches nothing when passkeys are unsupported', async () => {
+    const order: string[] = [];
+    const deps = buildDeps(order, { isSupported: jest.fn(() => false) });
+
+    await expect(runPasskeyAdd(deps)).rejects.toThrow(PASSKEY_UNSUPPORTED_MESSAGE);
+    expect(deps.getRegisterOptions).not.toHaveBeenCalled();
+    expect(deps.onLinked).not.toHaveBeenCalled();
+  });
+});