@oxyhq/services 21.0.0 → 22.0.0

package/src/ui/context/oxyContextTypes.ts

@@ -1,6 +1,5 @@
 import type { ReactNode } from 'react';
 import type { OxyServices, User, SessionLoginResponse, AccountNode, CreateAccountInput, ClientSession, AccountDialogController, AccountDialogView, ApiError, SessionClient } from '@oxyhq/core';
-import type { SecurityAlert } from '@oxyhq/contracts';
 import type { UseFollowHook } from '../hooks/useFollow.types';
 import type { useLanguageManagement } from '../hooks/useLanguageManagement';
 import type { RouteName } from '../navigation/routes';
@@ -41,18 +40,41 @@ export interface OxyContextState {
 
   signIn: (publicKey: string, deviceName?: string) => Promise<User>;
 
-  signInWithPassword: (
-    identifier: string,
-    password: string,
-    opts?: { deviceName?: string; deviceFingerprint?: string },
-  ) => Promise<PasswordSignInResult>;
-
-  completeTwoFactorSignIn: (params: {
-    loginToken: string;
-    token?: string;
-    backupCode?: string;
+  /**
+   * Sign in with a passkey (WebAuthn). With no `username` this is the
+   * usernameless / discoverable-credential flow: the browser prompts for any
+   * resident Oxy passkey. Pass `username` for the username-first flow — the
+   * server scopes `allowCredentials` to that user's passkeys so a
+   * NON-discoverable hardware key (e.g. a U2F/security key) can be used.
+   * WEB-ONLY — throws on native or an unsupported browser (native passkeys are
+   * Commons' job). On `useOxy()`, NOT re-exposed on `useAuth()`.
+   */
+  signInWithPasskey: (opts?: {
+    username?: string;
     deviceName?: string;
-  }) => Promise<{ securityAlert?: SecurityAlert }>;
+    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>;
+
+  /**
+   * Remove a passkey from the current account by its credential id
+   * (`AuthMethodEntry.credentialId`). Refreshes the linked auth-methods list on
+   * success. Works on any platform (it is a plain unlink, not a WebAuthn
+   * ceremony) but is only reachable from surfaces that list passkeys.
+   */
+  removePasskey: (credentialId: string) => Promise<void>;
 
   revokeSuspiciousSignIn: () => Promise<void>;
   handleWebSession: (session: SessionLoginResponse) => Promise<void>;
@@ -96,19 +118,19 @@ export interface OxyContextState {
   createAccount: (data: CreateAccountInput) => Promise<AccountNode>;
 }
 
-/**
- * Result of {@link OxyContextState.signInWithPassword}.
- */
-export type PasswordSignInResult =
-  | { status: 'ok'; securityAlert?: SecurityAlert }
-  | { status: '2fa_required'; loginToken: string };
-
 export interface OxyContextProviderProps {
   children: ReactNode;
   oxyServices?: OxyServices;
   baseURL?: string;
   authWebUrl?: string;
   authRedirectUri?: string;
+  /**
+   * Authorize endpoint override for silent cross-origin session restore
+   * (web cross-app SSO). Defaults to the production Oxy IdP when unset; a
+   * local/staging deployment points it at its own IdP so cold boot never
+   * bounces the tab to production `auth.oxy.so`.
+   */
+  authorizeBaseUrl?: string;
   storageKeyPrefix?: string;
   clientId?: string;
   /** Sync device credentials to auth.oxy.so after interactive sign-in. @default true */

package/src/ui/context/passkeyFlow.ts

@@ -0,0 +1,154 @@
+/**
+ * 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: (username?: string) => Promise<unknown>;
+  runCeremony: (optionsJSON: unknown) => Promise<unknown>;
+  loginVerify: (
+    response: unknown,
+    envelope: { deviceName?: string; deviceFingerprint?: string; deviceId?: string },
+  ) => Promise<LoginResult>;
+  commit: (input: CommitInput) => Promise<void>;
+  /**
+   * When present, scopes login options to that user's registered passkeys
+   * (username-first) — the path a NON-discoverable hardware key (e.g. a U2F
+   * security key) needs, since it can't be found by a usernameless ceremony.
+   * Omit for the discoverable / resident-credential path.
+   */
+  username?: string;
+  deviceId?: string;
+  deviceName?: string;
+  deviceFingerprint?: string;
+}
+
+/**
+ * Passkey SIGN-IN. With no `username` this is the usernameless
+ * (discoverable-credential) flow; with a `username` it is username-first —
+ * the server scopes `allowCredentials` to that user's passkeys so a
+ * non-discoverable hardware key (U2F/security key) can be selected. Either way:
+ * request login options, run the authentication ceremony, verify, then commit
+ * the session. A passkey assertion is itself the strong factor — sign-in always
+ * resolves to a completed session.
+ */
+export async function runPasskeyLogin(deps: RunPasskeyLoginDeps): Promise<void> {
+  if (!deps.isSupported()) {
+    throw new Error(PASSKEY_UNSUPPORTED_MESSAGE);
+  }
+  const options = await deps.getLoginOptions(deps.username);
+  const response = await deps.runCeremony(options);
+  const result = await deps.loginVerify(response, {
+    deviceName: deps.deviceName,
+    deviceFingerprint: deps.deviceFingerprint,
+    deviceId: deps.deviceId,
+  });
+  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 }`) does 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();
+}

package/src/ui/hooks/queries/queryKeys.ts

@@ -71,6 +71,12 @@ export const queryKeys = {
       [...queryKeys.security.all, 'infinite', limit, eventType] as const,
   },
 
+  // Linked authentication methods (passwords, identity keys, passkeys, social)
+  authMethods: {
+    all: ['authMethods'] as const,
+    list: (userId?: string) => [...queryKeys.authMethods.all, 'list', userId || 'current'] as const,
+  },
+
   // Storage usage queries
   storage: {
     all: ['storage'] as const,
@@ -159,6 +165,14 @@ export const invalidateStorageQueries = (queryClient: QueryClient): void => {
   queryClient.invalidateQueries({ queryKey: queryKeys.storage.all });
 };
 
+/**
+ * Helper to invalidate the user's linked auth-methods list (call after linking
+ * or removing a passkey / password / identity key).
+ */
+export const invalidateAuthMethodsQueries = (queryClient: QueryClient): void => {
+  queryClient.invalidateQueries({ queryKey: queryKeys.authMethods.all });
+};
+
 /**
  * Helper to invalidate all payments / wallet / subscription queries
  */

package/src/ui/hooks/queries/useAuthMethods.ts

@@ -0,0 +1,45 @@
+import { useMemo } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import type { AuthMethodEntry, AuthMethodsResponse } from '@oxyhq/contracts';
+import { queryKeys } from './queryKeys';
+import { useOxy } from '../../context/OxyContext';
+
+/** Stable empty list so the derived selectors keep a stable reference while loading. */
+const EMPTY_METHODS: readonly AuthMethodEntry[] = Object.freeze([]);
+
+/**
+ * The current account's linked authentication methods (`GET /auth/methods`),
+ * plus convenience projections. Backs the security / account surfaces that let a
+ * user see and manage their passwords, identity key, social logins, and passkeys.
+ *
+ * `passkeys` is the `type === 'webauthn'` subset — one entry per registered
+ * credential. Invalidate via `queryKeys.authMethods.all` after linking a passkey
+ * (`useOxy().addPasskey()` does this) or removing one.
+ */
+export const useAuthMethods = (options?: { enabled?: boolean }) => {
+  const { oxyServices, activeSessionId } = useOxy();
+
+  const query = useQuery<AuthMethodsResponse>({
+    queryKey: queryKeys.authMethods.list(),
+    queryFn: () => oxyServices.listAuthMethods(),
+    enabled: options?.enabled !== false && !!activeSessionId,
+    staleTime: 5 * 60 * 1000, // 5 minutes
+    gcTime: 10 * 60 * 1000, // 10 minutes
+  });
+
+  const methods = query.data?.methods ?? EMPTY_METHODS;
+  const passkeys = useMemo(
+    () => methods.filter((method) => method.type === 'webauthn'),
+    [methods],
+  );
+
+  return {
+    ...query,
+    /** Every linked auth method. Empty while loading. */
+    methods,
+    /** The registered passkeys (a `type === 'webauthn'` subset of `methods`). */
+    passkeys,
+    /** The account's DID, or `null` while loading. */
+    did: query.data?.did ?? null,
+  };
+};

package/src/ui/types/navigation.ts

@@ -62,6 +62,14 @@ export interface OxyProviderProps {
     baseURL?: string;
     authWebUrl?: string;
     authRedirectUri?: string;
+    /**
+     * Authorize endpoint override for silent cross-origin session restore
+     * (web cross-app SSO on cold boot). Defaults to the production Oxy IdP
+     * (`https://auth.oxy.so/authorize`) when unset. Set this from an env var
+     * (e.g. Vite `VITE_OXY_AUTHORIZE_URL`, Expo `EXPO_PUBLIC_OXY_AUTHORIZE_URL`)
+     * so a local/staging deployment targets its own IdP instead of production.
+     */
+    authorizeBaseUrl?: string;
     queryClient?: QueryClient;
     /** Sync device credentials to auth.oxy.so after interactive sign-in. @default true */
     hubSync?: boolean;

package/src/ui/utils/__tests__/crossOriginRestore.test.ts

@@ -0,0 +1,143 @@
+import type { OxyServices } from '@oxyhq/core';
+
+// Spy on the platform redirect so no real navigation happens and we can assert
+// the authorize URL the silent-restore flow hands to the browser.
+jest.mock('../../components/oauthNavigation', () => ({
+  redirectToAuthorize: jest.fn(),
+}));
+
+// jsdom's `location` is non-configurable, so the origin the code reads cannot be
+// reassigned per-test. Instead, drive the ORIGIN-CLASSIFICATION predicates
+// (whose real behaviour is covered by core's officialOrigins.test.ts) and keep
+// every other core helper real (PKCE, authorize-URL builder, handshake store).
+jest.mock('@oxyhq/core', () => {
+  const actual = jest.requireActual('@oxyhq/core');
+  return {
+    __esModule: true,
+    ...actual,
+    isLoopbackOrigin: jest.fn(),
+    isOfficialWebOrigin: jest.fn(),
+    isIdpHubOrigin: jest.fn(),
+  };
+});
+
+import {
+  isLoopbackOrigin,
+  isOfficialWebOrigin,
+  isIdpHubOrigin,
+} from '@oxyhq/core';
+import { redirectToAuthorize } from '../../components/oauthNavigation';
+import {
+  isSilentRestoreEligibleOrigin,
+  maybeStartSilentOAuthRestore,
+  clearCrossOriginRestoreGuards,
+} from '../crossOriginRestore';
+
+const mockRedirect = redirectToAuthorize as jest.Mock;
+const mockIsLoopback = isLoopbackOrigin as jest.Mock;
+const mockIsOfficial = isOfficialWebOrigin as jest.Mock;
+const mockIsIdpHub = isIdpHubOrigin as jest.Mock;
+
+const OXY_SERVICES_STUB = {} as OxyServices;
+
+/** Default to an eligible official origin; individual tests narrow this. */
+function makeOriginEligible(): void {
+  mockIsLoopback.mockReturnValue(false);
+  mockIsIdpHub.mockReturnValue(false);
+  mockIsOfficial.mockReturnValue(true);
+}
+
+describe('crossOriginRestore', () => {
+  beforeEach(() => {
+    mockRedirect.mockClear();
+    mockIsLoopback.mockReset();
+    mockIsOfficial.mockReset();
+    mockIsIdpHub.mockReset();
+    globalThis.sessionStorage?.clear();
+    clearCrossOriginRestoreGuards();
+  });
+
+  describe('isSilentRestoreEligibleOrigin', () => {
+    it('rejects loopback / local-dev origins', () => {
+      mockIsLoopback.mockReturnValue(true);
+      mockIsIdpHub.mockReturnValue(false);
+      mockIsOfficial.mockReturnValue(true);
+      expect(isSilentRestoreEligibleOrigin('http://localhost:3000')).toBe(false);
+    });
+
+    it('rejects the central IdP hub origin (no self-hop)', () => {
+      mockIsLoopback.mockReturnValue(false);
+      mockIsIdpHub.mockReturnValue(true);
+      mockIsOfficial.mockReturnValue(true);
+      expect(isSilentRestoreEligibleOrigin('https://auth.oxy.so')).toBe(false);
+    });
+
+    it('rejects non-official origins', () => {
+      mockIsLoopback.mockReturnValue(false);
+      mockIsIdpHub.mockReturnValue(false);
+      mockIsOfficial.mockReturnValue(false);
+      expect(isSilentRestoreEligibleOrigin('https://evil.example')).toBe(false);
+    });
+
+    it('accepts official, non-loopback, non-IdP origins', () => {
+      makeOriginEligible();
+      expect(isSilentRestoreEligibleOrigin('https://accounts.oxy.so')).toBe(true);
+    });
+  });
+
+  describe('maybeStartSilentOAuthRestore', () => {
+    it('is SKIPPED on a loopback origin (no redirect)', async () => {
+      mockIsLoopback.mockReturnValue(true);
+      mockIsIdpHub.mockReturnValue(false);
+      mockIsOfficial.mockReturnValue(true);
+      const redirected = await maybeStartSilentOAuthRestore({
+        oxyServices: OXY_SERVICES_STUB,
+        clientId: 'oxy_dk_test',
+      });
+      expect(redirected).toBe(false);
+      expect(mockRedirect).not.toHaveBeenCalled();
+    });
+
+    it('is SKIPPED on a non-official origin (no redirect)', async () => {
+      mockIsLoopback.mockReturnValue(false);
+      mockIsIdpHub.mockReturnValue(false);
+      mockIsOfficial.mockReturnValue(false);
+      const redirected = await maybeStartSilentOAuthRestore({
+        oxyServices: OXY_SERVICES_STUB,
+        clientId: 'oxy_dk_test',
+      });
+      expect(redirected).toBe(false);
+      expect(mockRedirect).not.toHaveBeenCalled();
+    });
+
+    it('redirects to the PROD IdP by default on an eligible origin', async () => {
+      makeOriginEligible();
+      const redirected = await maybeStartSilentOAuthRestore({
+        oxyServices: OXY_SERVICES_STUB,
+        clientId: 'oxy_dk_test',
+      });
+      expect(redirected).toBe(true);
+      expect(mockRedirect).toHaveBeenCalledTimes(1);
+      const url = mockRedirect.mock.calls[0][0] as string;
+      expect(url.startsWith('https://auth.oxy.so/authorize?')).toBe(true);
+      const params = new URL(url).searchParams;
+      expect(params.get('client_id')).toBe('oxy_dk_test');
+      expect(params.get('prompt')).toBe('none');
+    });
+
+    it('honors an authorizeBaseUrl override (self-hosted / staging IdP)', async () => {
+      makeOriginEligible();
+      const redirected = await maybeStartSilentOAuthRestore({
+        oxyServices: OXY_SERVICES_STUB,
+        clientId: 'oxy_dk_test',
+        authorizeBaseUrl: 'https://auth.staging.oxy.so/authorize',
+      });
+      expect(redirected).toBe(true);
+      const url = mockRedirect.mock.calls[0][0] as string;
+      expect(url.startsWith('https://auth.staging.oxy.so/authorize?')).toBe(true);
+      const params = new URL(url).searchParams;
+      expect(params.get('client_id')).toBe('oxy_dk_test');
+      expect(params.get('prompt')).toBe('none');
+    });
+  });
+});

package/src/ui/utils/crossOriginRestore.ts

@@ -3,6 +3,9 @@ import {
   buildOAuthAuthorizeUrl,
   generateOAuthState,
   generatePkcePair,
+  isIdpHubOrigin,
+  isLoopbackOrigin,
+  isOfficialWebOrigin,
   OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY,
   OXY_SILENT_OAUTH_ATTEMPTED_KEY,
   persistOAuthHandshake,
@@ -43,11 +46,35 @@ export function clearCrossOriginRestoreGuards(): void {
   }
 }
 
+/**
+ * Whether cold boot should attempt silent cross-origin OAuth restore for the
+ * given web origin.
+ *
+ * Mirrors the hub-sync WRITE gate (`syncHubAfterSignIn`): only OFFICIAL Oxy web
+ * origins participate in cross-app SSO — a random third-party / preview origin
+ * must never have its tab bounced to the IdP. Additionally, loopback / local-dev
+ * origins are EXCLUDED here even though {@link isOfficialWebOrigin} treats them
+ * as official: a developer's local app must never be redirected to a hosted IdP
+ * on cold boot (it signs in through the in-app dialog instead). The central IdP
+ * hub's own origin is excluded to avoid a wasteful self-hop.
+ */
+export function isSilentRestoreEligibleOrigin(origin: string): boolean {
+  if (isLoopbackOrigin(origin)) return false;
+  if (isIdpHubOrigin()) return false;
+  return isOfficialWebOrigin(origin);
+}
+
 export interface SilentOAuthRestoreOptions {
   oxyServices: OxyServices;
   clientId: string;
   redirectUri?: string;
   scope?: string;
+  /**
+   * Authorize endpoint override (env-configurable per deployment). Defaults to
+   * the production Oxy IdP when unset, so a local/staging app points silent
+   * restore at its OWN IdP instead of production `auth.oxy.so`.
+   */
+  authorizeBaseUrl?: string;
 }
 
 /**
@@ -62,6 +89,12 @@ export async function maybeStartSilentOAuthRestore(
   const location = (globalThis as { location?: Location }).location;
   if (!location) return false;
 
+  // Defense-in-depth: never bounce a loopback / non-official / IdP-hub origin to
+  // a hosted authorize endpoint (the caller gates on this too).
+  if (!isSilentRestoreEligibleOrigin(location.origin)) {
+    return false;
+  }
+
   if (isCrossOriginRestoreBlocked()) {
     return false;
   }
@@ -83,6 +116,7 @@ export async function maybeStartSilentOAuthRestore(
     );
 
     const authorizeUrl = buildOAuthAuthorizeUrl({
+      authorizeBaseUrl: opts.authorizeBaseUrl,
       clientId: opts.clientId,
       redirectUri,
       state,

package/src/webauthn/passkeyClient.native.ts

@@ -0,0 +1,26 @@
+/**
+ * Passkey / WebAuthn ceremony client — NATIVE implementation.
+ *
+ * React Native has no browser WebAuthn API, and Oxy's native passkey story is
+ * Commons (shared-keychain / QR handoff), NOT `navigator.credentials`. So this
+ * variant imports NOTHING browser-specific and mirrors the clean default:
+ * unsupported, and the ceremony helpers throw if a caller skipped the gate.
+ */
+
+const WEBAUTHN_WEB_ONLY_MESSAGE =
+  'WebAuthn is web-only; native uses Commons. Passkeys are not available on this platform.';
+
+/** Always `false` on native — there is no browser WebAuthn API. */
+export function isPasskeySupported(): boolean {
+  return false;
+}
+
+/** Not available on native — throws. Guard with {@link isPasskeySupported} first. */
+export async function runRegistrationCeremony(_optionsJSON: unknown): Promise<unknown> {
+  throw new Error(WEBAUTHN_WEB_ONLY_MESSAGE);
+}
+
+/** Not available on native — throws. Guard with {@link isPasskeySupported} first. */
+export async function runAuthenticationCeremony(_optionsJSON: unknown): Promise<unknown> {
+  throw new Error(WEBAUTHN_WEB_ONLY_MESSAGE);
+}

package/src/webauthn/passkeyClient.ts

@@ -0,0 +1,31 @@
+/**
+ * Passkey / WebAuthn ceremony client — clean default (non-web) implementation.
+ *
+ * This is the base module TypeScript resolves for TYPES and any bundler that
+ * does not pick a platform variant. It intentionally imports NOTHING browser-
+ * specific (no `@simplewebauthn/browser`) so it stays safe for Metro, native
+ * builds, and SSR. The real ceremony lives in `passkeyClient.web.ts`; native
+ * passkeys are Commons' job, so there is no WebAuthn ceremony here.
+ *
+ * `isPasskeySupported()` returns `false` (no relying-party origin / no browser
+ * WebAuthn API), and the ceremony helpers throw a clear error so a caller that
+ * skipped the support gate fails loudly instead of silently.
+ */
+
+const WEBAUTHN_WEB_ONLY_MESSAGE =
+  'WebAuthn is web-only; native uses Commons. Passkeys are not available on this platform.';
+
+/** Always `false` off the web — there is no relying-party origin or WebAuthn API. */
+export function isPasskeySupported(): boolean {
+  return false;
+}
+
+/** Not available off the web — throws. Guard with {@link isPasskeySupported} first. */
+export async function runRegistrationCeremony(_optionsJSON: unknown): Promise<unknown> {
+  throw new Error(WEBAUTHN_WEB_ONLY_MESSAGE);
+}
+
+/** Not available off the web — throws. Guard with {@link isPasskeySupported} first. */
+export async function runAuthenticationCeremony(_optionsJSON: unknown): Promise<unknown> {
+  throw new Error(WEBAUTHN_WEB_ONLY_MESSAGE);
+}

package/src/webauthn/passkeyClient.web.ts

@@ -0,0 +1,56 @@
+/**
+ * Passkey / WebAuthn ceremony client — WEB implementation.
+ *
+ * The browser half of the passkey flow: it drives `navigator.credentials`
+ * through `@simplewebauthn/browser`, turning the OPAQUE options the server
+ * emitted (`OxyServices.webauthn{Register,Login}Options`) into the opaque
+ * response the matching `verify` endpoint consumes. Oxy never owns those wire
+ * shapes — `@simplewebauthn/browser` does — so options flow in as `unknown` and
+ * the single cast at this boundary hands them to the library's own types.
+ *
+ * This file is selected ONLY on web (react-native-web / Vite RNW): the sibling
+ * `passkeyClient.native.ts` + the clean default `passkeyClient.ts` deliberately
+ * do NOT import `@simplewebauthn/browser` (a browser-only dependency), per the
+ * platform-split rule. Native passkeys are Commons' job — there is no WebAuthn
+ * ceremony off the web.
+ */
+
+import {
+  startRegistration,
+  startAuthentication,
+  type PublicKeyCredentialCreationOptionsJSON,
+  type PublicKeyCredentialRequestOptionsJSON,
+  type RegistrationResponseJSON,
+  type AuthenticationResponseJSON,
+} from '@simplewebauthn/browser';
+
+/**
+ * True iff this browser can run a WebAuthn ceremony (exposes the
+ * `PublicKeyCredential` global). Gate all passkey UI/entrypoints on this so an
+ * unsupported browser fails loudly rather than throwing mid-ceremony.
+ */
+export function isPasskeySupported(): boolean {
+  return typeof window !== 'undefined' && typeof window.PublicKeyCredential !== 'undefined';
+}
+
+/**
+ * Run the WebAuthn REGISTRATION ceremony (`navigator.credentials.create`) from
+ * the server's opaque creation options, returning the opaque attestation
+ * response for `OxyServices.webauthnRegisterVerify`.
+ */
+export async function runRegistrationCeremony(
+  optionsJSON: unknown,
+): Promise<RegistrationResponseJSON> {
+  return startRegistration({ optionsJSON: optionsJSON as PublicKeyCredentialCreationOptionsJSON });
+}
+
+/**
+ * Run the WebAuthn AUTHENTICATION ceremony (`navigator.credentials.get`) from
+ * the server's opaque request options, returning the opaque assertion response
+ * for `OxyServices.webauthnLoginVerify`.
+ */
+export async function runAuthenticationCeremony(
+  optionsJSON: unknown,
+): Promise<AuthenticationResponseJSON> {
+  return startAuthentication({ optionsJSON: optionsJSON as PublicKeyCredentialRequestOptionsJSON });
+}