@oxyhq/services 16.0.0 → 18.0.0

package/src/ui/components/RequireOxyAuth.tsx

@@ -0,0 +1,266 @@
+/**
+ * RequireOxyAuth — the optional signed-out gate primitive (React Native).
+ *
+ * ONE shared way for any Oxy app to opt into a signed-out gate. It is entirely
+ * OPTIONAL: a public app renders its children untouched (`prompt="off"`); an
+ * auth-required app blocks them behind a signed-out state (`prompt="hard"`); an
+ * app that mostly works signed-out but wants a nudge shows a dismissible banner
+ * (`prompt="soft"`). Every mode reuses the ONE account dialog the provider
+ * already mounts — opening the sign-in surface is always
+ * `useOxy().openAccountDialog('signin')`; there is NO second dialog.
+ *
+ * Readiness gating (CRITICAL): the gate keys on the SDK's own readiness state
+ * (`useOxy().canUsePrivateApi` / `isPrivateApiPending`), NEVER on app-local
+ * hooks. While auth is still resolving (`isPrivateApiPending`) it renders a
+ * neutral loading state so the signed-out wall never flashes before the
+ * device-first cold boot concludes (the documented cold-boot race).
+ *
+ * Styling follows the sibling `OxyAccountDialog`/`OxySignInButton` pattern —
+ * `useTheme()` + `StyleSheet` (NOT NativeWind), so the gate renders correctly in
+ * EVERY consumer, including apps that do not run NativeWind (e.g. the accounts
+ * app).
+ */
+
+import type React from 'react';
+import { useState, type ReactNode } from 'react';
+import { ActivityIndicator, Pressable, StyleSheet, View } from 'react-native';
+import { useTheme } from '@oxyhq/bloom/theme';
+import { Text } from '@oxyhq/bloom/typography';
+import { useOxy } from '../context/OxyContext';
+import { OxySignInButton } from './OxySignInButton';
+import OxyLogo from './OxyLogo';
+
+/**
+ * How `RequireOxyAuth` treats a signed-out (or still-resolving) session.
+ *  - `off`  — always render children (public app; a no-op provided for symmetry).
+ *  - `soft` — render children, plus a dismissible sign-in banner when signed out.
+ *  - `hard` — block children behind a centered signed-out state until signed in.
+ */
+export type RequireOxyAuthPrompt = 'off' | 'soft' | 'hard';
+
+export interface RequireOxyAuthProps {
+  children: ReactNode;
+  /** Gate behavior. @default 'hard' */
+  prompt?: RequireOxyAuthPrompt;
+  /** Replaces the neutral loading UI shown while auth is still resolving. */
+  loadingFallback?: ReactNode;
+  /** Replaces the entire default signed-out wall (`prompt="hard"`). */
+  signedOutFallback?: ReactNode;
+  /** Title for the default `prompt="hard"` wall. */
+  title?: string;
+  /** Subtitle for the default `prompt="hard"` wall. */
+  subtitle?: string;
+  /** Message for the `prompt="soft"` banner. */
+  bannerMessage?: string;
+  /** CTA label for the `prompt="soft"` banner. */
+  bannerActionLabel?: string;
+}
+
+const DEFAULT_TITLE = 'Sign in to continue';
+const DEFAULT_SUBTITLE = 'Sign in with your Oxy account to continue.';
+const DEFAULT_BANNER_MESSAGE = "You're browsing signed out.";
+const DEFAULT_BANNER_ACTION = 'Sign in';
+
+/**
+ * Optional signed-out gate. Wrap any subtree (or the whole app via the
+ * provider's `requireAuth` prop) to opt into a shared, readiness-safe wall.
+ */
+export const RequireOxyAuth: React.FC<RequireOxyAuthProps> = ({
+  children,
+  prompt = 'hard',
+  loadingFallback,
+  signedOutFallback,
+  title,
+  subtitle,
+  bannerMessage,
+  bannerActionLabel,
+}) => {
+  const { canUsePrivateApi, isPrivateApiPending, openAccountDialog } = useOxy();
+
+  // Public app: render straight through. Cheap enough to short-circuit before
+  // touching any gate UI.
+  if (prompt === 'off') {
+    return <>{children}</>;
+  }
+
+  // Signed in (and token ready): render the protected subtree in every mode.
+  if (canUsePrivateApi) {
+    return <>{children}</>;
+  }
+
+  if (prompt === 'soft') {
+    return (
+      <SoftGate
+        pending={isPrivateApiPending}
+        message={bannerMessage ?? DEFAULT_BANNER_MESSAGE}
+        actionLabel={bannerActionLabel ?? DEFAULT_BANNER_ACTION}
+        onSignIn={() => openAccountDialog('signin')}
+      >
+        {children}
+      </SoftGate>
+    );
+  }
+
+  // prompt === 'hard'
+  if (isPrivateApiPending) {
+    return loadingFallback ? <>{loadingFallback}</> : <NeutralLoading />;
+  }
+  if (signedOutFallback) {
+    return <>{signedOutFallback}</>;
+  }
+  return <HardWall title={title ?? DEFAULT_TITLE} subtitle={subtitle ?? DEFAULT_SUBTITLE} />;
+};
+
+// ---------------------------------------------------------------------------
+// Soft gate — children + a dismissible sign-in banner while signed out.
+// ---------------------------------------------------------------------------
+
+interface SoftGateProps {
+  children: ReactNode;
+  pending: boolean;
+  message: string;
+  actionLabel: string;
+  onSignIn: () => void;
+}
+
+const SoftGate: React.FC<SoftGateProps> = ({ children, pending, message, actionLabel, onSignIn }) => {
+  const theme = useTheme();
+  const [dismissed, setDismissed] = useState(false);
+
+  // Never surface the nudge while auth is still resolving — only once the boot
+  // has concluded signed out and the user has not dismissed it.
+  const showBanner = !pending && !dismissed;
+
+  return (
+    <View style={styles.softRoot}>
+      {showBanner ? (
+        <View style={[styles.banner, { backgroundColor: theme.colors.card, borderColor: theme.colors.border }]}>
+          <OxyLogo variant="icon" size={20} fillColor={theme.colors.primary} />
+          <Text style={[styles.bannerText, { color: theme.colors.text }]} numberOfLines={2}>
+            {message}
+          </Text>
+          <Pressable
+            onPress={onSignIn}
+            style={[styles.bannerCta, { backgroundColor: theme.colors.primary }]}
+            accessibilityRole="button"
+            accessibilityLabel={actionLabel}
+          >
+            <Text style={styles.bannerCtaText}>{actionLabel}</Text>
+          </Pressable>
+          <Pressable
+            onPress={() => setDismissed(true)}
+            style={styles.bannerDismiss}
+            accessibilityRole="button"
+            accessibilityLabel="Dismiss"
+            hitSlop={8}
+          >
+            <Text style={[styles.bannerDismissText, { color: theme.colors.textSecondary }]}>✕</Text>
+          </Pressable>
+        </View>
+      ) : null}
+      <View style={styles.softBody}>{children}</View>
+    </View>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Hard wall — centered signed-out state with the "Sign in with Oxy" CTA.
+// ---------------------------------------------------------------------------
+
+const HardWall: React.FC<{ title: string; subtitle: string }> = ({ title, subtitle }) => {
+  const theme = useTheme();
+  return (
+    <View style={[styles.wallRoot, { backgroundColor: theme.colors.background }]}>
+      <View style={[styles.logoBadge, { backgroundColor: theme.colors.primarySubtle }]}>
+        <OxyLogo variant="icon" size={44} fillColor={theme.colors.primary} />
+      </View>
+      <Text style={[styles.wallTitle, { color: theme.colors.text }]}>{title}</Text>
+      <Text style={[styles.wallSubtitle, { color: theme.colors.textSecondary }]}>{subtitle}</Text>
+      <OxySignInButton variant="contained" style={styles.wallCta} />
+    </View>
+  );
+};
+
+const NeutralLoading: React.FC = () => {
+  const theme = useTheme();
+  return (
+    <View style={[styles.wallRoot, { backgroundColor: theme.colors.background }]}>
+      <ActivityIndicator color={theme.colors.primary} />
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  softRoot: {
+    flex: 1,
+  },
+  softBody: {
+    flex: 1,
+  },
+  banner: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: 10,
+    paddingVertical: 8,
+    paddingHorizontal: 12,
+    borderBottomWidth: StyleSheet.hairlineWidth,
+  },
+  bannerText: {
+    flex: 1,
+    fontSize: 13.5,
+  },
+  bannerCta: {
+    paddingVertical: 6,
+    paddingHorizontal: 14,
+    borderRadius: 999,
+  },
+  bannerCtaText: {
+    color: '#FFFFFF',
+    fontSize: 13,
+    fontWeight: '700',
+  },
+  bannerDismiss: {
+    width: 28,
+    height: 28,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  bannerDismissText: {
+    fontSize: 15,
+    fontWeight: '600',
+  },
+  wallRoot: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 24,
+    gap: 16,
+  },
+  logoBadge: {
+    width: 88,
+    height: 88,
+    borderRadius: 44,
+    alignItems: 'center',
+    justifyContent: 'center',
+    marginBottom: 4,
+  },
+  wallTitle: {
+    fontSize: 24,
+    fontWeight: '800',
+    letterSpacing: -0.4,
+    textAlign: 'center',
+  },
+  wallSubtitle: {
+    fontSize: 15,
+    lineHeight: 21,
+    textAlign: 'center',
+    maxWidth: 340,
+  },
+  wallCta: {
+    marginTop: 8,
+    width: '100%',
+    maxWidth: 320,
+  },
+});
+
+export default RequireOxyAuth;

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