@oxy.so/services 1.0.0

package/src/ui/context/oxyContextTypes.ts

@@ -0,0 +1,239 @@
+import type { ReactNode } from 'react';
+import type { OxyServices, User, SessionLoginResponse, AccountNode, CreateAccountInput, ClientSession, AccountDialogController, AccountDialogView, ApiError, SessionClient, SessionMode } from '@oxy.so/core';
+import type { UseFollowHook } from '../hooks/useFollow.types';
+import type { useLanguageManagement } from '../hooks/useLanguageManagement';
+import type { RouteName } from '../navigation/routes';
+import type { StartWebOAuthSignInOptions } from '../oauth/browserAuthTransport';
+import type {
+  OAuthConsentResult,
+  RequestOAuthConsentOptions,
+} from '../oauth/explicitOAuthConsent';
+import type { WebAuthMode, WebOAuthSignInResult } from '../oauth/types';
+import type { StorageInterface } from '../utils/storageHelpers';
+
+export interface OxyContextState {
+  user: User | null;
+  sessions: ClientSession[];
+  activeSessionId: string | null;
+  isAuthenticated: boolean;
+  isLoading: boolean;
+  isTokenReady: boolean;
+  hasAccessToken: boolean;
+  canUsePrivateApi: boolean;
+  isPrivateApiPending: boolean;
+  /**
+   * Whether the initial auth determination has concluded.
+   *
+   * `false` from mount until the FIRST device-first cold boot resolves —
+   * during that window `isAuthenticated: false` is UNDETERMINED, not a
+   * definitive "logged out". Flips to `true` exactly once the boot concludes
+   * (a session was committed OR none exists) and never reverts. Consumers should
+   * defer their first auth-dependent fetch until this is `true` so a cold-boot
+   * web reload with an existing session does not fetch anonymous data.
+   */
+  isAuthResolved: boolean;
+  isStorageReady: boolean;
+  /**
+   * Who owns this provider's session (see `OxyProviderProps.sessionMode`).
+   *
+   * `'account'` — the device's active account; any app on the device can switch
+   * it and this client follows. `'identity'` — the owner of the local primary
+   * identity key, permanently: a sibling app's account switch never changes this
+   * client's user or bearer, and every account-graph mutation
+   * (`switchToAccount` / `switchSession`) rejects with `IdentityBoundSessionError`
+   * while `accounts` stays empty and the account dialog never opens.
+   */
+  sessionMode: SessionMode;
+  /** How web third-party sign-in reaches the IdP (see `OxyProviderProps.webAuthMode`). */
+  webAuthMode: WebAuthMode;
+  error: string | null;
+  /** Active UI locale (`language-REGION`): the account's primary locale when signed in, else the guest/device locale. */
+  currentLanguage: string;
+  /** Ordered account locales (primary first) when signed in, or the single guest override when signed out. */
+  currentLanguages: string[];
+  currentLanguageMetadata: ReturnType<typeof useLanguageManagement>['metadata'];
+  currentLanguageName: string;
+  currentNativeLanguageName: string;
+
+  hasIdentity: () => Promise<boolean>;
+  getPublicKey: () => Promise<string | null>;
+
+  signIn: (publicKey: string, deviceName?: string) => Promise<User>;
+
+  /**
+   * 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;
+    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>;
+
+  /**
+   * Run a WEB third-party OAuth sign-in (authorization code + PKCE) end to end
+   * using this provider's `webAuthMode`, and commit the resulting session.
+   *
+   * This is the shared operation `OxySignInButton` delegates to; RPs that ship
+   * their own button call it directly and never implement popup listeners, a
+   * token exchange, or `state` validation themselves. Returns a typed result —
+   * closing the popup and running out of time are values, not exceptions.
+   *
+   * In popup mode the window MUST be opened during the user's click: either
+   * call this synchronously from the press handler (it opens one itself), or
+   * call `openOAuthPopup()` there and pass the handle as `popup`.
+   *
+   * No-op outside a browser and in `sessionMode: 'identity'`, both of which
+   * resolve to `{ status: 'unsupported' }`.
+   */
+  startWebOAuthSignIn: (options: StartWebOAuthSignInOptions) => Promise<WebOAuthSignInResult>;
+
+  /**
+   * Ask the already-authenticated user for explicit OAuth consent to exact
+   * application scopes. Must be called from a user gesture. Works on web and
+   * native and commits only a callback bound to the same user, state, PKCE pair
+   * and byte-exact redirect URI.
+   */
+  requestOAuthConsent: (options: RequestOAuthConsentOptions) => Promise<OAuthConsentResult>;
+
+  logout: (targetSessionId?: string) => Promise<void>;
+  logoutAll: () => Promise<void>;
+  switchSession: (sessionId: string) => Promise<User>;
+  removeSession: (sessionId: string) => Promise<void>;
+  refreshSessions: () => Promise<void>;
+  setLanguage: (languageId: string) => Promise<void>;
+  getDeviceSessions: () => Promise<
+    Array<{
+      sessionId: string;
+      deviceId: string;
+      deviceName?: string;
+      lastActive?: string;
+      expiresAt?: string;
+    }>
+  >;
+  logoutAllDeviceSessions: () => Promise<void>;
+  updateDeviceName: (deviceName: string) => Promise<void>;
+  clearSessionState: () => Promise<void>;
+  clearAllAccountData: () => Promise<void>;
+  storageKeyPrefix: string;
+  clientId: string | null;
+  oxyServices: OxyServices;
+  /** Server-authoritative device session client. `null` before an `OxyProvider` is mounted. */
+  sessionClient: SessionClient | null;
+  useFollow?: UseFollowHook;
+  showBottomSheet?: (screenOrConfig: RouteName | { screen: RouteName; props?: Record<string, unknown> }) => void;
+  openAvatarPicker: () => void;
+
+  accountDialogController: AccountDialogController | null;
+  isAccountDialogOpen: boolean;
+  openAccountDialog: (view?: AccountDialogView) => void;
+  closeAccountDialog: () => void;
+
+  accounts: AccountNode[];
+  switchToAccount: (accountId: string) => Promise<void>;
+  refreshAccounts: () => Promise<void>;
+  createAccount: (data: CreateAccountInput) => Promise<AccountNode>;
+}
+
+export interface OxyRuntimeProviderProps {
+  children: ReactNode;
+  oxyServices?: OxyServices;
+  baseURL?: string;
+  authWebUrl?: string;
+  authRedirectUri?: string;
+  /**
+   * Authorize endpoint override for web "Sign in with Oxy". Defaults to the
+   * production Oxy IdP when unset; a local/staging deployment points it at its
+   * own IdP so sign-in never reaches production `auth.oxy.so`.
+   */
+  authorizeBaseUrl?: string;
+  storageKeyPrefix?: string;
+  clientId?: string;
+  /**
+   * Who owns this provider's session. See `OxyProviderProps.sessionMode` for the
+   * full contract.
+   * @default 'account'
+   */
+  sessionMode?: SessionMode;
+  /**
+   * Transport for WEB third-party sign-in. See `OxyProviderProps.webAuthMode`.
+   * @default 'popup'
+   */
+  webAuthMode?: WebAuthMode;
+  /**
+   * Let NATIVE background code (a home-screen widget's WorkManager worker, a sync
+   * job) authenticate while the app process is dead and there is no JS runtime.
+   *
+   * With this on, the SDK provisions a purpose-built background credential
+   * whenever the app runs and stores it where `so.oxy.session.OxyBackgroundSession`
+   * can read it; Kotlin then exchanges it for a short access token on demand. The
+   * app writes no session code — this prop is the whole integration.
+   *
+   * OFF by default, because a credential that nobody needs is exposure that
+   * nobody needs. Turn it on only in an app that actually has background code to
+   * authenticate. Android-only today; inert on web and iOS.
+   *
+   * The credential cannot create a session (only the running app can provision
+   * one), cannot rotate or otherwise disturb the app's own device credential, and
+   * is re-authorized server-side on every use so it can never outlive a sign-out.
+   * It does NOT reduce authority: the token it mints is a full user access token,
+   * exactly like the device credential's.
+   *
+   * @default false
+   */
+  backgroundSession?: boolean;
+  /**
+   * Whether this origin/app persists the durable device credential at all. See
+   * `OxyProviderProps.deviceCredentialStorage` for the full rule and the one
+   * caller of `'ephemeral'`.
+   *
+   * @default 'persistent'
+   */
+  deviceCredentialStorage?: 'persistent' | 'ephemeral';
+  onAuthStateChange?: (user: User | null) => void;
+  onError?: (error: ApiError) => void;
+  /** Storage instance owned by the public provider; internal composition seam. */
+  platformStorage?: StorageInterface | null;
+}
+
+/** Internal commit input — session plus zero-cookie device credential. */
+export interface CommitInput {
+  sessionId: string;
+  accessToken?: string;
+  deviceId?: string;
+  deviceSecret?: string;
+  expiresAt?: string;
+  userId?: string;
+  user?: { id: string; username?: string; avatar?: string };
+  /** State returned with a device-token mint, avoiding an immediate REST reread. */
+  deviceState?: import('@oxy.so/contracts').DeviceSessionState;
+}

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 '@oxy.so/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/context/useOxyAccountGraph.ts

@@ -0,0 +1,123 @@
+import { useCallback, useEffect, useState, type RefObject } from 'react';
+import type { OxyServices, AccountNode, CreateAccountInput, AccountDialogController, SessionClient } from '@oxy.so/core';
+import { logger as loggerUtil } from '@oxy.so/core';
+import { isUnauthorizedStatus } from './oxyContextHelpers';
+import { IdentityBoundSessionError } from '../session';
+import type { CommitInput } from './oxyContextTypes';
+
+interface UseOxyAccountGraphParams {
+  isAuthenticated: boolean;
+  tokenReady: boolean;
+  initialized: boolean;
+  /**
+   * `sessionMode: 'identity'`. The account graph is a switcher surface, and an
+   * identity-bound client authenticates as the owner of the local identity key —
+   * permanently. The graph is therefore never fetched and every switch rejects.
+   */
+  identityBound: boolean;
+  oxyServices: OxyServices;
+  sessionClient: SessionClient;
+  syncFromClient: () => Promise<void>;
+  commitSession: (input: CommitInput, options: { activate: boolean }) => Promise<void>;
+  accountDialogControllerRef: RefObject<AccountDialogController | null>;
+  clearSessionStateRef: RefObject<() => Promise<void>>;
+}
+
+export function useOxyAccountGraph({
+  isAuthenticated,
+  tokenReady,
+  initialized,
+  identityBound,
+  oxyServices,
+  sessionClient,
+  syncFromClient,
+  commitSession,
+  accountDialogControllerRef,
+  clearSessionStateRef,
+}: UseOxyAccountGraphParams) {
+  const [accounts, setAccounts] = useState<AccountNode[]>([]);
+
+  const refreshAccounts = useCallback(async (): Promise<void> => {
+    if (identityBound || !isAuthenticated || !tokenReady || !oxyServices.getAccessToken()) {
+      setAccounts([]);
+      return;
+    }
+    try {
+      const list = await oxyServices.listAccounts();
+      setAccounts(list);
+    } catch (err) {
+      if (isUnauthorizedStatus(err)) {
+        setAccounts([]);
+        await clearSessionStateRef.current();
+        return;
+      }
+      if (__DEV__) {
+        loggerUtil.debug('Failed to load accounts', { component: 'OxyContext' }, err as unknown);
+      }
+    }
+  }, [identityBound, isAuthenticated, oxyServices, tokenReady, clearSessionStateRef]);
+
+  useEffect(() => {
+    if (!identityBound && isAuthenticated && initialized && tokenReady) {
+      refreshAccounts();
+      void accountDialogControllerRef.current?.refresh();
+    }
+  }, [identityBound, isAuthenticated, initialized, tokenReady, refreshAccounts, accountDialogControllerRef]);
+
+  const switchToAccount = useCallback(
+    async (accountId: string): Promise<void> => {
+      if (identityBound) {
+        // Loud rejection, never a silent no-op: a resolved promise here would
+        // read to the caller as a completed switch that simply left the user
+        // unchanged, which is exactly the confusion this mode must avoid.
+        throw new IdentityBoundSessionError('switchToAccount');
+      }
+      const deviceState = sessionClient.getState();
+      if (deviceState?.accounts.some((account) => account.accountId === accountId)) {
+        await sessionClient.switchAccount(accountId);
+        await syncFromClient();
+        return;
+      }
+
+      const result = await oxyServices.switchToAccount(accountId);
+      if (!result?.user || !result?.sessionId) {
+        throw new Error('Account switch did not return a valid session');
+      }
+      await commitSession(
+        {
+          sessionId: result.sessionId,
+          accessToken: result.accessToken,
+          deviceSecret: result.deviceSecret,
+          deviceId: result.deviceId,
+          expiresAt: result.expiresAt,
+          userId: result.user.id,
+          user: result.user,
+        },
+        // A switch is IN-PLACE. Cross-tab/app propagation rides the
+        // `session_state` socket.
+        { activate: true },
+      );
+    },
+    // The account-scoped cache reset that used to trail both branches here now
+    // runs inside the runtime's subject transition, BEFORE any subscriber is
+    // woken — so a socket-pushed switch (which never reached this function at
+    // all) gets it too.
+    [identityBound, oxyServices, sessionClient, syncFromClient, commitSession],
+  );
+
+  const createAccount = useCallback(
+    async (data: CreateAccountInput): Promise<AccountNode> => {
+      const account = await oxyServices.createAccount(data);
+      await refreshAccounts();
+      return account;
+    },
+    [oxyServices, refreshAccounts],
+  );
+
+  return {
+    accounts,
+    refreshAccounts,
+    switchToAccount,
+    createAccount,
+  };
+}

package/src/ui/hooks/accountDialogSnapshot.ts

@@ -0,0 +1,37 @@
+import type { AccountDialogSnapshot } from '@oxy.so/core';
+
+/**
+ * The snapshot `useSyncExternalStore` reads before a controller exists.
+ *
+ * `useSyncExternalStore` calls `getSnapshot` several times per commit and
+ * compares by identity, so the no-controller answer has to be one constant
+ * reference — a fresh object literal loops.
+ *
+ * It is ONE constant because there were three, byte-identical, in the hook and
+ * both dialog surfaces. Adding a field to `AccountDialogSnapshot` broke all
+ * three at once and would have gone on doing so; a shared constant makes the
+ * compiler point at one place.
+ */
+export const EMPTY_ACCOUNT_DIALOG_SNAPSHOT: AccountDialogSnapshot = {
+  view: 'accounts',
+  directory: null,
+  activeContext: null,
+  activatingContextId: null,
+  removingContextId: null,
+  removingPrincipalId: null,
+  loading: false,
+  error: null,
+  signIn: {
+    phase: 'idle',
+    authorizeCode: null,
+    qrPayload: null,
+    expiresAt: null,
+    error: null,
+    route: null,
+    routeFailed: false,
+    pushSentAt: null,
+    openedAt: null,
+    progress: 'idle',
+  },
+  commonsAvailability: 'unknown',
+};