@oxyhq/services 21.0.0 → 21.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/services",
-  "version": "21.0.0",
+  "version": "21.0.1",
   "description": "OxyHQ Expo/React Native SDK — UI components, screens, and native features",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -126,15 +126,16 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "0.14.1",
+    "@oxyhq/contracts": "0.14.2",
     "@oxyhq/core": "^11.0.0",
+    "@simplewebauthn/browser": "^13.3.0",
     "color": "^4.2.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
     "@commitlint/cli": "^17.6.5",
     "@commitlint/config-conventional": "^17.6.5",
-    "@oxyhq/core": "11.0.0",
+    "@oxyhq/core": "11.0.1",
     "@react-native-async-storage/async-storage": "^2.0.0",
     "@react-native-community/netinfo": "^11.4.1",
     "@react-native/babel-preset": "^0.86.0",

package/src/index.ts

@@ -95,6 +95,7 @@ export {
     useRecentSecurityActivity,
     useInfiniteSecurityActivity,
 } from './ui/hooks/queries/useSecurityQueries';
+export { useAuthMethods } from './ui/hooks/queries/useAuthMethods';
 export {
     useUserSubscription,
     useUserPayments,
@@ -166,6 +167,7 @@ export {
     invalidateStorageQueries,
     invalidatePaymentsQueries,
     invalidateConnectedAppsQueries,
+    invalidateAuthMethodsQueries,
 } from './ui/hooks/queries/queryKeys';
 
 // Mutation status aggregator (for "Syncing..." indicators)

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.
@@ -222,6 +251,9 @@ const OxyAccountDialog: React.FC = () => {
             onSignInWithOxy={() => void controller.signInWithOxy()}
             onScanQr={() => void controller.showQr()}
             onUsePassword={() => void controller.openPasswordAtOxyAuth()}
+            onSignInWithPasskey={passkeyAvailable ? () => void handleSignInWithPasskey() : undefined}
+            passkeyPending={passkeyPending}
+            passkeyError={passkeyError}
           />
         )}
       </ScrollView>
@@ -416,6 +448,10 @@ interface SignInViewProps {
   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> = ({
@@ -426,6 +462,9 @@ const SignInView: React.FC<SignInViewProps> = ({
   onSignInWithOxy,
   onScanQr,
   onUsePassword,
+  onSignInWithPasskey,
+  passkeyPending,
+  passkeyError,
 }) => (
   <View style={styles.signInBlock}>
     {snapshot.accounts.length > 0 ? (
@@ -448,6 +487,24 @@ 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>

package/src/ui/context/OxyContext.tsx

@@ -65,6 +65,13 @@ import type {
 } 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';
@@ -735,6 +742,66 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     [oxyServices, commitSession],
   );
 
+  // ── 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.
+
+  // Usernameless (discoverable) passkey sign-in.
+  const signInWithPasskey = useCallback(
+    async (opts?: { deviceName?: string; deviceFingerprint?: string }): Promise<void> => {
+      const persisted = await authStore.load();
+      await runPasskeyLogin({
+        isSupported: isPasskeySupported,
+        getLoginOptions: () => oxyServices.webauthnLoginOptions(),
+        runCeremony: runAuthenticationCeremony,
+        loginVerify: (response, envelope) => oxyServices.webauthnLoginVerify(response, envelope),
+        commit: (input) => commitSession(input, { activate: true, hubSync: true }),
+        deviceId: persisted?.deviceId,
+        deviceName: opts?.deviceName,
+        deviceFingerprint: opts?.deviceFingerprint,
+      });
+    },
+    [oxyServices, authStore, commitSession],
+  );
+
+  // 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,
+      });
+    },
+    [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],
+  );
+
   // ── Cold boot ────────────────────────────────────────────────────────────
   // Device-first session restore via `runProviderColdBoot` (see boot/runProviderColdBoot.ts).
   const runColdBoot = useCallback(async (): Promise<void> => {
@@ -885,6 +952,9 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       signIn,
       signInWithPassword,
       completeTwoFactorSignIn,
+      signInWithPasskey,
+      registerWithPasskey,
+      addPasskey,
       revokeSuspiciousSignIn,
       handleWebSession,
       logout,
@@ -937,6 +1007,9 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       signIn,
       signInWithPassword,
       completeTwoFactorSignIn,
+      signInWithPasskey,
+      registerWithPasskey,
+      addPasskey,
       revokeSuspiciousSignIn,
       handleWebSession,
       logout,
@@ -1007,6 +1080,9 @@ const LOADING_STATE: OxyContextState = {
   signIn: () => rejectMissingProvider<User>(),
   signInWithPassword: () => rejectMissingProvider<PasswordSignInResult>(),
   completeTwoFactorSignIn: () => rejectMissingProvider<{ securityAlert?: SecurityAlert }>(),
+  signInWithPasskey: () => rejectMissingProvider<void>(),
+  registerWithPasskey: () => rejectMissingProvider<void>(),
+  addPasskey: () => rejectMissingProvider<void>(),
   revokeSuspiciousSignIn: () => rejectMissingProvider<void>(),
   handleWebSession: () => rejectMissingProvider<void>(),
   logout: () => rejectMissingProvider<void>(),

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

@@ -0,0 +1,237 @@
+/**
+ * `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 { LoginResult, 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 twoFactorResult: LoginResult = { twoFactorRequired: true, loginToken: 'lt_should_not_happen' };
+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('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();
+  });
+
+  it('refuses a 2FA arm (a passkey assertion is the strong factor) and never commits', async () => {
+    const order: string[] = [];
+    const deps = buildDeps(order, {
+      loginVerify: jest.fn(async () => {
+        order.push('loginVerify');
+        return twoFactorResult;
+      }),
+    });
+
+    await expect(runPasskeyLogin(deps)).rejects.toThrow(/second factor/i);
+    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();
+  });
+});

package/src/ui/context/oxyContextTypes.ts

@@ -54,6 +54,27 @@ export interface OxyContextState {
     deviceName?: string;
   }) => Promise<{ securityAlert?: SecurityAlert }>;
 
+  /**
+   * Sign in with a passkey (WebAuthn). Usernameless / discoverable-credential
+   * flow: the browser prompts for any resident Oxy passkey. WEB-ONLY — throws on
+   * native or an unsupported browser (native passkeys are Commons' job). On
+   * `useOxy()`, NOT re-exposed on `useAuth()`.
+   */
+  signInWithPasskey: (opts?: { deviceName?: string; deviceFingerprint?: string }) => Promise<void>;
+
+  /**
+   * Create a brand-new account whose first authentication method is a passkey.
+   * WEB-ONLY — throws on native or an unsupported browser.
+   */
+  registerWithPasskey: (params: { username: string; deviceName?: string }) => Promise<void>;
+
+  /**
+   * Add a passkey to the already-signed-in account (bearer present). Does NOT
+   * commit a new session; refreshes the linked auth-methods list on success.
+   * WEB-ONLY — throws on native or an unsupported browser.
+   */
+  addPasskey: (params?: { deviceName?: string }) => Promise<void>;
+
   revokeSuspiciousSignIn: () => Promise<void>;
   handleWebSession: (session: SessionLoginResponse) => Promise<void>;
 

package/src/ui/context/passkeyFlow.ts

@@ -0,0 +1,146 @@
+/**
+ * Pure passkey (WebAuthn) sign-in / registration orchestration.
+ *
+ * Extracted from `OxyContext` so the fixed `options → ceremony → verify → commit`
+ * ordering is unit-testable with injected deps — the exact pattern
+ * `commitSessionFlow.ts` (`commitDeviceSetAndResolve`) uses. The context methods
+ * (`signInWithPasskey` / `registerWithPasskey` / `addPasskey`) are thin wrappers
+ * that supply the real deps: the core `webauthn*` methods, the platform ceremony
+ * client (`webauthn/passkeyClient`), and the internal `commitSession` funnel.
+ *
+ * All three GATE on `isSupported()` first (the platform client returns `false`
+ * off the web) so an unsupported surface fails loudly before touching a ceremony.
+ */
+
+import type { LoginResult, LoginSessionResult } from '@oxyhq/contracts';
+import type { CommitInput } from './oxyContextTypes';
+
+/**
+ * The result of `OxyServices.webauthnRegisterVerify` — either the LINK branch
+ * (`{ success, message }`, bearer present, no session) or the SIGNUP branch (a
+ * full {@link LoginResult}, which carries a `sessionId` on its session arm).
+ */
+export type PasskeyRegisterVerifyResult = { success: true; message: string } | LoginResult;
+
+/** Thrown when a passkey flow is attempted on a surface that cannot run WebAuthn. */
+export const PASSKEY_UNSUPPORTED_MESSAGE =
+  'Passkeys are not available in this environment. Use another sign-in method.';
+
+/** Project a session-arm login result onto the internal `commitSession` input. */
+function toCommitInput(result: LoginSessionResult): CommitInput {
+  return {
+    sessionId: result.sessionId,
+    accessToken: result.accessToken,
+    deviceSecret: result.deviceSecret,
+    deviceId: result.deviceId,
+    expiresAt: result.expiresAt,
+    userId: result.user.id,
+    user: result.user,
+  };
+}
+
+/** Injected dependencies for {@link runPasskeyLogin}. */
+export interface RunPasskeyLoginDeps {
+  isSupported: () => boolean;
+  getLoginOptions: () => Promise<unknown>;
+  runCeremony: (optionsJSON: unknown) => Promise<unknown>;
+  loginVerify: (
+    response: unknown,
+    envelope: { deviceName?: string; deviceFingerprint?: string; deviceId?: string },
+  ) => Promise<LoginResult>;
+  commit: (input: CommitInput) => Promise<void>;
+  deviceId?: string;
+  deviceName?: string;
+  deviceFingerprint?: string;
+}
+
+/**
+ * Usernameless (discoverable-credential) passkey SIGN-IN: request login options,
+ * run the authentication ceremony, verify, then commit the session. A passkey
+ * assertion is itself the strong factor, so a 2FA arm here is a protocol error.
+ */
+export async function runPasskeyLogin(deps: RunPasskeyLoginDeps): Promise<void> {
+  if (!deps.isSupported()) {
+    throw new Error(PASSKEY_UNSUPPORTED_MESSAGE);
+  }
+  const options = await deps.getLoginOptions();
+  const response = await deps.runCeremony(options);
+  const result = await deps.loginVerify(response, {
+    deviceName: deps.deviceName,
+    deviceFingerprint: deps.deviceFingerprint,
+    deviceId: deps.deviceId,
+  });
+  if ('twoFactorRequired' in result) {
+    throw new Error('Passkey sign-in unexpectedly required a second factor.');
+  }
+  await deps.commit(toCommitInput(result));
+}
+
+/** Injected dependencies for {@link runPasskeyRegister}. */
+export interface RunPasskeyRegisterDeps {
+  isSupported: () => boolean;
+  getRegisterOptions: (username: string) => Promise<unknown>;
+  runCeremony: (optionsJSON: unknown) => Promise<unknown>;
+  registerVerify: (
+    response: unknown,
+    envelope: { username: string; deviceName?: string },
+  ) => Promise<PasskeyRegisterVerifyResult>;
+  commit: (input: CommitInput) => Promise<void>;
+  username: string;
+  deviceName?: string;
+}
+
+/**
+ * Passkey SIGNUP: create a brand-new account whose first auth method is a
+ * passkey. The verify signup branch mints a session (a {@link LoginSessionResult}
+ * carrying `sessionId`), which is committed exactly like a password signup.
+ */
+export async function runPasskeyRegister(deps: RunPasskeyRegisterDeps): Promise<void> {
+  if (!deps.isSupported()) {
+    throw new Error(PASSKEY_UNSUPPORTED_MESSAGE);
+  }
+  const options = await deps.getRegisterOptions(deps.username);
+  const response = await deps.runCeremony(options);
+  const result = await deps.registerVerify(response, {
+    username: deps.username,
+    deviceName: deps.deviceName,
+  });
+  // Only the signup session arm carries `sessionId`; the link branch
+  // (`{ success, message }`) and any 2FA arm do not.
+  if (!('sessionId' in result)) {
+    throw new Error('Passkey registration did not establish a session.');
+  }
+  await deps.commit(toCommitInput(result));
+}
+
+/** Injected dependencies for {@link runPasskeyAdd}. */
+export interface RunPasskeyAddDeps {
+  isSupported: () => boolean;
+  getRegisterOptions: () => Promise<unknown>;
+  runCeremony: (optionsJSON: unknown) => Promise<unknown>;
+  registerVerify: (
+    response: unknown,
+    envelope: { deviceName?: string },
+  ) => Promise<PasskeyRegisterVerifyResult>;
+  onLinked: () => void;
+  deviceName?: string;
+}
+
+/**
+ * ADD a passkey to the already-signed-in account (bearer present). The verify
+ * link branch returns `{ success, message }` with NO session — so this never
+ * commits a session; it just fires `onLinked` (which invalidates the
+ * auth-methods query). A session arm here would be a server contract violation.
+ */
+export async function runPasskeyAdd(deps: RunPasskeyAddDeps): Promise<void> {
+  if (!deps.isSupported()) {
+    throw new Error(PASSKEY_UNSUPPORTED_MESSAGE);
+  }
+  const options = await deps.getRegisterOptions();
+  const response = await deps.runCeremony(options);
+  const result = await deps.registerVerify(response, { deviceName: deps.deviceName });
+  if ('sessionId' in result) {
+    throw new Error('addPasskey unexpectedly minted a new session instead of linking.');
+  }
+  deps.onLinked();
+}