tessl/npm-expo-web-browser

Provides access to the system's web browser and supports handling redirects for React Native and Expo applications

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Authentication Sessions

Name: tessl/npm-expo-web-browser
Author: tessl

Secure authentication session management with proper redirect handling for OAuth flows and other authentication workflows that require secure token exchange and session isolation.

Capabilities

Open Authentication Session

Opens a secure authentication session with proper redirect handling. On iOS, uses ASWebAuthenticationSession which asks the user for permission and handles redirects properly. On Android, uses a polyfill with Custom Tabs and app state monitoring. On web, uses window.open() with crypto state verification.

/**
 * Opens secure authentication session with redirect handling
 * @param url - The login page URL to open
 * @param redirectUrl - Optional URL to deep link back into your app
 * @param options - Optional configuration extending WebBrowserOpenOptions
 * @returns Promise resolving to:
 * - { type: 'success', url: string } if authentication succeeds with redirect URL
 * - { type: 'cancel' } if user cancels or closes browser
 * - { type: 'dismiss' } if dismissed programmatically
 */
function openAuthSessionAsync(
  url: string,
  redirectUrl?: string | null,
  options?: AuthSessionOpenOptions
): Promise<WebBrowserAuthSessionResult>;

Usage Examples:

import * as WebBrowser from 'expo-web-browser';

// Basic OAuth flow
const authResult = await WebBrowser.openAuthSessionAsync(
  'https://accounts.google.com/oauth/authorize?client_id=...',
  'myapp://redirect'
);

if (authResult.type === 'success') {
  const redirectUrl = authResult.url;
  // Parse redirect URL for auth tokens
  const url = new URL(redirectUrl);
  const code = url.searchParams.get('code');
  console.log('Authorization code:', code);
}

// With ephemeral session (iOS only)
const authResult = await WebBrowser.openAuthSessionAsync(
  'https://example.com/login',
  'myapp://auth',
  {
    preferEphemeralSession: true, // Doesn't share cookies with browser
    presentationStyle: WebBrowser.WebBrowserPresentationStyle.PAGE_SHEET
  }
);

// Web-specific authentication
const authResult = await WebBrowser.openAuthSessionAsync(
  'https://oauth.provider.com/auth?redirect_uri=https://mysite.com/callback',
  null, // Auto-generated from Linking.createURL("")
  {
    windowName: 'OAuth',
    windowFeatures: { width: 500, height: 600 }
  }
);

Dismiss Authentication Session

Dismisses the current authentication session. Available on iOS and web platforms.

/**
 * Dismisses the current authentication session
 * @platform ios
 * @platform web
 */
function dismissAuthSession(): void;

Usage Example:

import * as WebBrowser from 'expo-web-browser';

// Start auth session
const authPromise = WebBrowser.openAuthSessionAsync(
  'https://accounts.google.com/oauth/authorize?...',
  'myapp://redirect'
);

// Cancel after timeout
setTimeout(() => {
  try {
    WebBrowser.dismissAuthSession();
    console.log('Auth session dismissed');
  } catch (error) {
    console.log('Dismiss not available on this platform');
  }
}, 30000);

const result = await authPromise;
console.log('Auth result:', result);

Complete Authentication Session

Completes an authentication session on web platform. This method should be invoked on the page that the authentication window redirects to.

/**
 * Completes authentication session on web platform
 * @param options - Optional configuration for completion
 * @returns Result object indicating success or failure with descriptive message
 * @platform web
 */
function maybeCompleteAuthSession(
  options?: WebBrowserCompleteAuthSessionOptions
): WebBrowserCompleteAuthSessionResult;

Usage Example:

import * as WebBrowser from 'expo-web-browser';

// On the redirect page (e.g., https://mysite.com/auth-callback)
const result = WebBrowser.maybeCompleteAuthSession();

if (result.type === 'success') {
  console.log('Auth completed successfully:', result.message);
  // Parent window will close this popup automatically
} else {
  console.log('Auth completion failed:', result.message);
  // Handle various error cases:
  // - "Not supported on this platform"
  // - "Cannot use expo-web-browser in a non-browser environment"  
  // - "No auth session is currently in progress"
  // - "Current URL and original redirect URL do not match"
}

// Skip redirect URL validation in development
const result = WebBrowser.maybeCompleteAuthSession({
  skipRedirectCheck: true
});

Configuration Types

interface AuthSessionOpenOptions extends WebBrowserOpenOptions {
  /**
   * Request private authentication session that doesn't share cookies
   * with the user's normal browser session
   * @default false
   * @platform ios
   */
  preferEphemeralSession?: boolean;
}

interface WebBrowserCompleteAuthSessionOptions {
  /**
   * Skip checking if redirect URL matches cached redirect URL
   * Useful for development environments
   */
  skipRedirectCheck?: boolean;
}

interface WebBrowserCompleteAuthSessionResult {
  /** Type of the result: 'success' or 'failed' */
  type: 'success' | 'failed';
  /** Additional description or reasoning of the result */
  message: string;
}