@oxyhq/services 17.0.0 → 18.0.0

package/src/ui/components/OxyProvider.tsx

@@ -116,6 +116,7 @@ const OxyProvider: FC<OxyProviderProps> = ({
     authRedirectUri,
     queryClient: providedQueryClient,
     requireAuth = 'off',
+    coldBoot = true,
 }) => {
 
     // Dynamic KeyboardProvider for native. Uses variable indirection
@@ -310,6 +311,7 @@ const OxyProvider: FC<OxyProviderProps> = ({
                     authRedirectUri={authRedirectUri}
                     storageKeyPrefix={storageKeyPrefix}
                     clientId={clientId}
+                    coldBoot={coldBoot}
                     onAuthStateChange={onAuthStateChange as OxyContextProviderProps['onAuthStateChange']}
                 >
                     {requireAuth === 'off' ? (

package/src/ui/components/OxySignInButton.tsx

@@ -1,12 +1,73 @@
 import type React from 'react';
-import { useCallback, useState, useEffect, useMemo } from 'react';
+import { useCallback, useState, useEffect, useMemo, useRef } from 'react';
 import { TouchableOpacity, Text, View, StyleSheet, type ViewStyle, type TextStyle, type StyleProp, Platform } from 'react-native';
+import {
+    logger,
+    generatePkcePair,
+    generateOAuthState,
+    buildOAuthAuthorizeUrl,
+    type PublicApplication,
+} from '@oxyhq/core';
 import { useAuthStore } from '../stores/authStore';
 import { useShallow } from 'zustand/react/shallow';
 import { useTheme } from '@oxyhq/bloom/theme';
 import { useOxy } from '../context/OxyContext';
 import OxyLogo from './OxyLogo';
 import { subscribeToSignInModal } from '../navigation/accountDialogManager';
+import { redirectToAuthorize, openAuthorizeUrlNative } from './oauthNavigation';
+
+/**
+ * `sessionStorage` keys under which a third-party "Sign in with Oxy" OAuth flow
+ * persists its CSRF `state` and PKCE `code_verifier` across the authorize
+ * redirect. The Relying Party's redirect-URI callback reads them back to
+ * validate the returned `state` and replay the verifier on the token exchange.
+ *
+ * Web only: a browser RP navigates away to `auth.oxy.so` and back, so the
+ * handshake must survive a full-page redirect. Native completes the flow inside
+ * a single `WebBrowser` auth session and surfaces the handshake via
+ * {@link OxySignInButtonProps.onOAuthResult} instead.
+ */
+export const OXY_OAUTH_STATE_STORAGE_KEY = 'oxy_oauth_state';
+export const OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = 'oxy_oauth_code_verifier';
+
+/**
+ * The OAuth handshake surfaced to a NATIVE third-party RP via
+ * {@link OxySignInButtonProps.onOAuthResult} so it can finish the code exchange
+ * (`POST /auth/oauth/token`). Web RPs read the same `state` / `code_verifier`
+ * back from `sessionStorage` across the redirect and do not need this callback.
+ */
+export interface OxyOAuthResult {
+    /** Deep-link URL the native auth session returned to (`?code=…&state=…`), or `null` if unobserved. */
+    redirectUrl: string | null;
+    /** The CSRF `state` sent on the authorize request; the RP must match it on return. */
+    state: string;
+    /** The PKCE `code_verifier` to replay on the token exchange. */
+    codeVerifier: string;
+}
+
+/**
+ * Persist the OAuth CSRF `state` + PKCE `code_verifier` for the RP callback.
+ * Returns `false` when the handshake could not be stored — no `sessionStorage`
+ * (SSR / non-browser host) or a write that threw (`SecurityError` /
+ * `QuotaExceededError`, e.g. Safari private mode) — so the caller aborts the
+ * flow cleanly rather than redirect to a callback that cannot validate `state`.
+ */
+function persistOAuthHandshake(state: string, codeVerifier: string): boolean {
+    const store = (globalThis as { sessionStorage?: Storage }).sessionStorage;
+    try {
+        if (!store) throw new Error('sessionStorage is unavailable');
+        store.setItem(OXY_OAUTH_STATE_STORAGE_KEY, state);
+        store.setItem(OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, codeVerifier);
+        return true;
+    } catch (error) {
+        logger.warn(
+            'OxySignInButton: could not persist the OAuth handshake to sessionStorage; aborting third-party sign-in',
+            { component: 'OxySignInButton' },
+            error,
+        );
+        return false;
+    }
+}
 
 export interface OxySignInButtonProps {
     /**
@@ -48,6 +109,37 @@ export interface OxySignInButtonProps {
      * @default false
      */
     showWhenAuthenticated?: boolean;
+
+    /**
+     * Exact registered redirect URI the OAuth authorization code is returned to.
+     * REQUIRED only for third-party (`type: 'third_party'`) applications, which
+     * sign in via an OAuth + PKCE redirect to `auth.oxy.so`. First-party /
+     * official apps open the in-app dialog and ignore this prop. If a third-party
+     * app resolves without it, the button logs an error and does nothing (it will
+     * not invent a redirect URI).
+     */
+    oauthRedirectUri?: string;
+
+    /**
+     * Native only: receives the OAuth handshake after a third-party auth session
+     * so the RP can finish the token exchange. On web the handshake is read back
+     * from `sessionStorage` across the full-page redirect, so this is not used
+     * there. A native third-party sign-in with NO `onOAuthResult` handler cannot
+     * complete (the `state` + `code_verifier` are lost) and logs a warning.
+     *
+     * @example
+     * ```tsx
+     * <OxySignInButton
+     *   oauthRedirectUri="myapp://oauth/callback"
+     *   onOAuthResult={({ redirectUrl, state, codeVerifier }) => {
+     *     if (!redirectUrl) return;
+     *     const code = new URL(redirectUrl).searchParams.get('code');
+     *     // → POST /auth/oauth/token { code, code_verifier: codeVerifier, state }
+     *   }}
+     * />
+     * ```
+     */
+    onOAuthResult?: (result: OxyOAuthResult) => void;
 }
 
 /**
@@ -82,9 +174,11 @@ export const OxySignInButton: React.FC<OxySignInButtonProps> = ({
     text = 'Sign in with Oxy',
     disabled = false,
     showWhenAuthenticated = false,
+    oauthRedirectUri,
+    onOAuthResult,
 }) => {
     const theme = useTheme();
-    const { openAccountDialog } = useOxy();
+    const { openAccountDialog, oxyServices, clientId } = useOxy();
     const { isAuthenticated, isLoading } = useAuthStore(
         useShallow((state) => ({ isAuthenticated: state.isAuthenticated, isLoading: state.isLoading }))
     );
@@ -95,15 +189,137 @@ export const OxySignInButton: React.FC<OxySignInButtonProps> = ({
 
     useEffect(() => subscribeToSignInModal(setIsModalOpen), []);
 
-    // Open the unified account dialog on its sign-in view (same surface on web +
-    // native), or defer to a caller-supplied handler.
+    // The application's public identity is resolved lazily on first press and its
+    // promise cached, so rapid taps share one in-flight resolve. The cache is
+    // KEYED on the identity inputs (clientId + the oxyServices instance): if
+    // either changes the cache is invalidated and re-resolved — without a
+    // useEffect. A rejected resolve clears the cache so a later press can retry.
+    const appResolutionRef = useRef<{
+        clientId: string;
+        oxyServices: typeof oxyServices;
+        promise: Promise<PublicApplication>;
+    } | null>(null);
+    // Re-entrancy guard: a routing pass may await network + crypto before it
+    // redirects, so block a second concurrent press from racing the sessionStorage
+    // handshake against a different PKCE pair.
+    const routingRef = useRef(false);
+
+    const resolvePublicApplication = useCallback((): Promise<PublicApplication> | null => {
+        if (!clientId) return null;
+        const cached = appResolutionRef.current;
+        if (cached && cached.clientId === clientId && cached.oxyServices === oxyServices) {
+            return cached.promise;
+        }
+        const promise = oxyServices.getPublicApplication(clientId).catch((error) => {
+            // Only clear if this is still the live entry (a later resolve may have
+            // replaced it after a clientId/oxyServices change).
+            if (appResolutionRef.current?.promise === promise) {
+                appResolutionRef.current = null;
+            }
+            throw error;
+        });
+        appResolutionRef.current = { clientId, oxyServices, promise };
+        return promise;
+    }, [clientId, oxyServices]);
+
+    // Official / first-party surface: the in-app account + sign-in dialog.
+    const startOfficialSignIn = useCallback(() => {
+        openAccountDialog('signin');
+    }, [openAccountDialog]);
+
+    // Third-party surface: an OAuth 2.0 authorization-code + PKCE redirect to
+    // auth.oxy.so. No FedCM, no SSO bounce, no Oxy session cookies.
+    const startThirdPartyOAuth = useCallback(
+        async (app: PublicApplication): Promise<void> => {
+            if (!clientId) {
+                startOfficialSignIn();
+                return;
+            }
+            if (!oauthRedirectUri) {
+                logger.error(
+                    'OxySignInButton: a third_party application requires the `oauthRedirectUri` prop to start the OAuth redirect; sign-in aborted',
+                    undefined,
+                    { component: 'OxySignInButton', clientId, application: app.name },
+                );
+                return;
+            }
+
+            const [pkce, state] = await Promise.all([generatePkcePair(), generateOAuthState()]);
+            const authorizeUrl = buildOAuthAuthorizeUrl({
+                clientId,
+                redirectUri: oauthRedirectUri,
+                state,
+                codeChallenge: pkce.codeChallenge,
+            });
+
+            if (Platform.OS === 'web') {
+                // Persist the handshake for the RP callback, then hand the
+                // top-level document to the IdP. Without storage the callback
+                // cannot validate `state`, so abort cleanly rather than redirect.
+                if (!persistOAuthHandshake(state, pkce.codeVerifier)) {
+                    return;
+                }
+                redirectToAuthorize(authorizeUrl);
+                return;
+            }
+
+            // Native: open the in-app auth session, then hand the handshake to the
+            // RP so it can complete the token exchange from its deep-link callback.
+            const { redirectUrl } = await openAuthorizeUrlNative(authorizeUrl, oauthRedirectUri);
+            if (onOAuthResult) {
+                onOAuthResult({ redirectUrl, state, codeVerifier: pkce.codeVerifier });
+                return;
+            }
+            logger.warn(
+                'OxySignInButton: native third-party sign-in cannot complete without an `onOAuthResult` handler; the code exchange is the RP\'s responsibility (state + code_verifier were not surfaced)',
+                { component: 'OxySignInButton', application: app.name },
+            );
+        },
+        [clientId, oauthRedirectUri, onOAuthResult, startOfficialSignIn],
+    );
+
+    // Resolve the Application once, then route: third-party → OAuth redirect;
+    // first-party / official / unresolved → the in-app dialog. Resolution failure
+    // NEVER breaks an official app's sign-in — it falls back to the dialog.
+    const routeSignIn = useCallback(async (): Promise<void> => {
+        if (routingRef.current) return;
+        routingRef.current = true;
+        try {
+            const resolving = resolvePublicApplication();
+            if (!resolving) {
+                startOfficialSignIn();
+                return;
+            }
+            let app: PublicApplication;
+            try {
+                app = await resolving;
+            } catch (error) {
+                logger.warn(
+                    'OxySignInButton: could not resolve the application; opening the sign-in dialog',
+                    { component: 'OxySignInButton', clientId },
+                    error,
+                );
+                startOfficialSignIn();
+                return;
+            }
+            if (app.type === 'third_party' && !app.isOfficial) {
+                await startThirdPartyOAuth(app);
+                return;
+            }
+            startOfficialSignIn();
+        } finally {
+            routingRef.current = false;
+        }
+    }, [resolvePublicApplication, startOfficialSignIn, startThirdPartyOAuth, clientId]);
+
+    // Defer to a caller-supplied handler, otherwise route by application type.
     const handlePress = useCallback(() => {
         if (onPress) {
             onPress();
             return;
         }
-        openAccountDialog('signin');
-    }, [onPress, openAccountDialog]);
+        void routeSignIn();
+    }, [onPress, routeSignIn]);
 
     const themedStyles = useMemo(() => StyleSheet.create({
         button: {

package/src/ui/components/__tests__/OxyConsentScreen.test.tsx

@@ -0,0 +1,130 @@
+/**
+ * `OxyConsentScreen` — the unified OAuth consent surface. These tests exercise
+ * the pure presentational contract: scopes render, privacy/terms links appear
+ * only when supplied, allow/deny fire their handlers, `busy` disables both
+ * actions, and the account badge follows the display-name rule (`displayName`
+ * else `handle`).
+ */
+import { render, fireEvent } from '@testing-library/react';
+import {
+  OxyConsentScreen,
+  type OxyConsentApplication,
+  type OxyConsentScreenProps,
+} from '../OxyConsentScreen';
+
+// OxyLogo renders through react-native-svg, which is not meaningful (and not
+// resolvable) under the jsdom RN stub — replace it with an inert node.
+jest.mock('../OxyLogo', () => ({ __esModule: true, default: () => null }));
+
+const baseApp: OxyConsentApplication = { name: 'Acme Notes' };
+
+function renderScreen(props: Partial<OxyConsentScreenProps> = {}) {
+  const onAllow = jest.fn();
+  const onDeny = jest.fn();
+  const view = render(
+    <OxyConsentScreen
+      application={props.application ?? baseApp}
+      scopes={props.scopes ?? ['openid', 'profile']}
+      user={props.user}
+      onAllow={props.onAllow ?? onAllow}
+      onDeny={props.onDeny ?? onDeny}
+      busy={props.busy}
+      error={props.error}
+    />,
+  );
+  return { ...view, onAllow: props.onAllow ?? onAllow, onDeny: props.onDeny ?? onDeny };
+}
+
+describe('OxyConsentScreen', () => {
+  it('renders every requested scope with a friendly label and falls back to the raw scope for unknown ones', () => {
+    const { getByTestId } = renderScreen({ scopes: ['openid', 'files:write', 'custom:thing'] });
+
+    expect(getByTestId('consent-scope-openid').textContent).toContain('Confirm your identity');
+    expect(getByTestId('consent-scope-files:write').textContent).toContain('Upload and modify your files');
+    // Unknown scope → the raw scope string is shown, never an empty row.
+    expect(getByTestId('consent-scope-custom:thing').textContent).toContain('custom:thing');
+  });
+
+  it('shows the basic-permissions fallback when no scopes are requested', () => {
+    const { getByTestId, queryByTestId } = renderScreen({ scopes: [] });
+    expect(getByTestId('consent-scope-basic').textContent).toContain('Sign you in and read your basic profile');
+    expect(queryByTestId('consent-scope-openid')).toBeNull();
+  });
+
+  it('renders the provenance line for an official application', () => {
+    const { getByTestId } = renderScreen({ application: { name: 'Oxy Console', isOfficial: true } });
+    expect(getByTestId('consent-provenance').textContent).toContain('Official Oxy application');
+  });
+
+  it('renders "Published by …" provenance for a third-party app with a developer', () => {
+    const { getByTestId } = renderScreen({
+      application: { name: 'Third Party', developerName: 'Widgets Inc' },
+    });
+    expect(getByTestId('consent-provenance').textContent).toContain('Widgets Inc');
+  });
+
+  it('omits privacy/terms links when the application does not supply them', () => {
+    const { queryByTestId } = renderScreen();
+    expect(queryByTestId('consent-link-privacy')).toBeNull();
+    expect(queryByTestId('consent-link-terms')).toBeNull();
+  });
+
+  it('renders privacy and terms links when supplied (field 2b)', () => {
+    const { getByTestId } = renderScreen({
+      application: {
+        name: 'Acme Notes',
+        privacyPolicyUrl: 'https://acme.example/privacy',
+        termsUrl: 'https://acme.example/terms',
+      },
+    });
+    expect(getByTestId('consent-link-privacy')).not.toBeNull();
+    expect(getByTestId('consent-link-terms')).not.toBeNull();
+  });
+
+  it('fires onAllow and onDeny from the decision buttons', () => {
+    const { getByTestId, onAllow, onDeny } = renderScreen();
+
+    fireEvent.click(getByTestId('consent-allow'));
+    expect(onAllow).toHaveBeenCalledTimes(1);
+
+    fireEvent.click(getByTestId('consent-deny'));
+    expect(onDeny).toHaveBeenCalledTimes(1);
+  });
+
+  it('disables both actions while busy', () => {
+    const { getByTestId, onAllow, onDeny } = renderScreen({ busy: true });
+
+    const allow = getByTestId('consent-allow') as HTMLButtonElement;
+    const deny = getByTestId('consent-deny') as HTMLButtonElement;
+    expect(allow.disabled).toBe(true);
+    expect(deny.disabled).toBe(true);
+
+    // A disabled jsdom <button> does not fire click — the handlers stay untouched.
+    fireEvent.click(allow);
+    fireEvent.click(deny);
+    expect(onAllow).not.toHaveBeenCalled();
+    expect(onDeny).not.toHaveBeenCalled();
+  });
+
+  it('renders the authorizing account using the display name when present', () => {
+    const { getByTestId } = renderScreen({
+      user: { displayName: '  Alice A  ', handle: 'alice', avatarUri: 'file-1' },
+    });
+    expect(getByTestId('consent-account-name').textContent).toBe('Alice A');
+  });
+
+  it('falls back to the handle when the account has no display name (D5)', () => {
+    const { getByTestId } = renderScreen({ user: { handle: 'bob' } });
+    expect(getByTestId('consent-account-name').textContent).toBe('bob');
+  });
+
+  it('omits the account badge entirely when no user is supplied', () => {
+    const { queryByTestId } = renderScreen({ user: undefined });
+    expect(queryByTestId('consent-account')).toBeNull();
+  });
+
+  it('renders a blocking error when supplied', () => {
+    const { getByTestId } = renderScreen({ error: 'This request has expired.' });
+    expect(getByTestId('consent-error').textContent).toContain('This request has expired.');
+  });
+});

package/src/ui/components/oauthNavigation.ts

@@ -0,0 +1,89 @@
+/**
+ * Platform navigation for the third-party "Sign in with Oxy" OAuth flow.
+ *
+ * Kept out of `OxySignInButton` so the button's routing logic can be unit-tested
+ * without driving a real browser navigation (jsdom's `location.assign` is
+ * non-configurable and cannot be spied). Both entry points hand a fully-built
+ * `auth.oxy.so/authorize` URL to the platform — never FedCM, an SSO bounce, or
+ * an Oxy session cookie.
+ */
+
+import { Linking } from 'react-native';
+import { logger } from '@oxyhq/core';
+
+/** Minimal shape of the optional `expo-web-browser` auth-session result. */
+interface WebBrowserAuthResult {
+    type?: string;
+    url?: string;
+}
+
+/** Minimal shape of the optional `expo-web-browser` native module we depend on. */
+interface WebBrowserModule {
+    openAuthSessionAsync?: (url: string, redirectUrl: string) => Promise<WebBrowserAuthResult>;
+}
+
+/** Outcome of opening the authorize URL on native. */
+export interface OpenAuthorizeResult {
+    /**
+     * The deep-link URL the auth session returned to (carries `?code=…&state=…`)
+     * when `expo-web-browser` observed it, else `null`. `null` means the RP must
+     * complete the exchange from its own deep-link handler (e.g. after the
+     * `Linking.openURL` fallback, which cannot observe the return URL).
+     */
+    redirectUrl: string | null;
+}
+
+/**
+ * Web: hand the TOP-LEVEL document to the OAuth authorize URL (a full-page
+ * redirect, not a popup) so the RP returns to its registered `redirect_uri`.
+ * No-op where `location` is unavailable (SSR / non-browser hosts).
+ */
+export function redirectToAuthorize(url: string): void {
+    (globalThis as { location?: Location }).location?.assign(url);
+}
+
+/**
+ * Native: open the authorize URL in an in-app auth session via the optional
+ * `expo-web-browser` module (`openAuthSessionAsync` returns to `redirectUri`),
+ * degrading to `Linking.openURL` when the module is not installed — the same
+ * dynamic-import-with-fallback pattern services uses for haptics/netinfo.
+ *
+ * Returns the deep-link URL the session came back to when it can be observed, so
+ * the caller can hand `?code=…&state=…` back to the RP for the token exchange.
+ */
+export async function openAuthorizeUrlNative(
+    url: string,
+    redirectUri: string,
+): Promise<OpenAuthorizeResult> {
+    try {
+        const mod = (await import('expo-web-browser')) as unknown as WebBrowserModule;
+        if (mod && typeof mod.openAuthSessionAsync === 'function') {
+            const result = await mod.openAuthSessionAsync(url, redirectUri);
+            const redirectUrl =
+                result && result.type === 'success' && typeof result.url === 'string'
+                    ? result.url
+                    : null;
+            return { redirectUrl };
+        }
+    } catch (error) {
+        logger.warn(
+            'OxySignInButton: expo-web-browser auth session failed; falling back to Linking.openURL',
+            { component: 'oauthNavigation' },
+            error,
+        );
+    }
+
+    // Fallback: Linking cannot observe the return URL, so the RP completes the
+    // exchange from its own deep-link handler. A rejected openURL (e.g. an
+    // unregistered scheme) must not throw out of the sign-in flow.
+    try {
+        await Linking.openURL(url);
+    } catch (error) {
+        logger.warn(
+            'OxySignInButton: Linking.openURL rejected the authorize URL',
+            { component: 'oauthNavigation' },
+            error,
+        );
+    }
+    return { redirectUrl: null };
+}

package/src/ui/context/OxyContext.tsx

@@ -234,6 +234,20 @@ export interface OxyContextProviderProps {
    * for the cross-app device sign-in flow. See {@link OxyContextState.clientId}.
    */
   clientId?: string;
+  /**
+   * Whether this provider is the device-first **session authority**. `true`
+   * (default) runs `runSessionColdBoot` on mount and opens the signed-out
+   * device-state socket — the correct behavior for every Relying Party app.
+   *
+   * `false` is the IdP host (`auth.oxy.so`) opt-out: the IdP is NOT a session
+   * authority (handoff "IdP vs RP"), so it must NOT restore or reproject an
+   * ambient device session. With `coldBoot={false}` the cold boot never runs
+   * and the signed-out device socket never opens; auth resolves immediately as
+   * signed out. Interactive sign-in still commits a normal session on this
+   * origin — only the automatic restore/reproject is suppressed.
+   * @default true
+   */
+  coldBoot?: boolean;
   onAuthStateChange?: (user: User | null) => void;
   onError?: (error: ApiError) => void;
 }
@@ -336,6 +350,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   authRedirectUri,
   storageKeyPrefix = 'oxy_session',
   clientId: clientIdProp,
+  coldBoot = true,
   onAuthStateChange,
   onError,
 }) => {
@@ -1058,7 +1073,20 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   runColdBootRef.current = runColdBoot;
 
   useEffect(() => {
-    if (!storage || initialized) {
+    if (initialized) {
+      return;
+    }
+    // IdP mode (`coldBoot={false}`): this provider is NOT the ecosystem session
+    // authority, so it never runs the device-first restore and never opens the
+    // signed-out device-state socket (`runColdBoot` → `onSignedOut` is the sole
+    // place that socket starts). Resolve auth immediately as signed out so there
+    // is no boot spinner; a deliberate sign-in still commits a normal session.
+    if (!coldBoot) {
+      setInitialized(true);
+      markAuthResolved();
+      return;
+    }
+    if (!storage) {
       return;
     }
     setInitialized(true);
@@ -1067,7 +1095,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
         logger('Cold boot failed', error);
       }
     });
-  }, [runColdBoot, storage, initialized, logger]);
+  }, [coldBoot, runColdBoot, storage, initialized, logger, markAuthResolved]);
 
   // Exposed `refreshSessions`: re-bootstrap the server-authoritative device
   // state and reproject — the manual counterpart to the realtime socket.