@oxyhq/services 20.0.2 → 21.0.1

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();
+}

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/stores/authStore.ts

@@ -1,8 +1,8 @@
 import { create } from 'zustand';
-import { createDebugLogger, normalizeUserIdentity } from '@oxyhq/core';
+import { createLogger, normalizeUserIdentity } from '@oxyhq/core';
 import type { User } from '@oxyhq/core';
 
-const debug = createDebugLogger('AuthStore');
+const log = createLogger('AuthStore');
 
 export interface AuthState {
   user: User | null;
@@ -46,7 +46,7 @@ export const useAuthStore = create<AuthState>((set: (state: Partial<AuthState>)
 
     // Use cached data if available and not forcing refresh
     if (!forceRefresh && state.user && cacheValid) {
-      debug.log('Using cached user data (age:', cacheAge, 'ms)');
+      log.info('Using cached user data', { cacheAge });
       return;
     }
 
@@ -56,7 +56,7 @@ export const useAuthStore = create<AuthState>((set: (state: Partial<AuthState>)
       set({ user, isLoading: false, isAuthenticated: true, lastUserFetch: now });
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : 'Failed to fetch user';
-      debug.error('Error fetching user:', error);
+      log.error('Error fetching user', error);
       set({ error: errorMessage, isLoading: false });
     }
   },

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 });
+}