@symbiote-native/auth-session 0.0.0-stage → 0.1.1

package/src/core/auth-request.ts

@@ -0,0 +1,199 @@
+import { Platform } from 'react-native';
+import invariant from 'invariant';
+import { openAuthSessionAsync } from '@symbiote-native/web-browser';
+import type { IWebBrowserAuthSessionResult } from '@symbiote-native/web-browser';
+import type {
+  IAuthDiscoveryDocument,
+  IAuthRequestConfig,
+  IAuthRequestPromptOptions,
+  Prompt,
+} from './auth-request.types';
+import { CodeChallengeMethod, ResponseType } from './auth-request.types';
+import type { IAuthSessionResult } from './auth-session.types';
+import { AuthError } from './errors';
+import { createPromptString } from './prompt-string';
+import { getQueryParams } from './query-params';
+import { buildCodeAsync, generateRandom } from './pkce';
+import { TokenResponse } from './token-request';
+
+let authLock = false;
+
+/** Manages an authorization request, https://tools.ietf.org/html/rfc6749#section-4.1.1 */
+export class AuthRequest implements Omit<IAuthRequestConfig, 'state'> {
+  /** Protection against Cross-Site Request Forgery. */
+  public state: string;
+  public url: string | null = null;
+  public codeVerifier?: string;
+  public codeChallenge?: string;
+
+  readonly responseType: ResponseType | string;
+  readonly clientId: string;
+  readonly extraParams: Record<string, string>;
+  readonly usePKCE?: boolean;
+  readonly codeChallengeMethod: CodeChallengeMethod;
+  readonly redirectUri: string;
+  readonly scopes?: string[];
+  readonly clientSecret?: string;
+  readonly prompt?: Prompt | Prompt[];
+
+  constructor(request: IAuthRequestConfig) {
+    this.responseType = request.responseType ?? ResponseType.Code;
+    this.clientId = request.clientId;
+    this.redirectUri = request.redirectUri;
+    this.scopes = request.scopes;
+    this.clientSecret = request.clientSecret;
+    this.prompt = request.prompt;
+    this.state = request.state ?? generateRandom(10);
+    this.extraParams = request.extraParams ?? {};
+    this.codeChallengeMethod =
+      request.codeChallengeMethod ?? CodeChallengeMethod.S256;
+    this.usePKCE = request.usePKCE ?? true;
+
+    invariant(
+      this.codeChallengeMethod !== CodeChallengeMethod.Plain,
+      '`AuthRequest` does not support `CodeChallengeMethod.Plain` as it is not secure.',
+    );
+    invariant(
+      this.redirectUri,
+      `\`AuthRequest\` requires a valid \`redirectUri\`. Ex: ${
+        Platform.OS === 'web'
+          ? 'https://yourwebsite.com/'
+          : 'com.your.app:/oauthredirect'
+      }`,
+    );
+  }
+
+  /** Loads and returns a valid auth request config, generating PKCE fields if needed. */
+  async getAuthRequestConfigAsync(): Promise<IAuthRequestConfig> {
+    if (this.usePKCE) {
+      await this.ensureCodeIsSetupAsync();
+    }
+
+    return {
+      responseType: this.responseType,
+      clientId: this.clientId,
+      redirectUri: this.redirectUri,
+      scopes: this.scopes,
+      clientSecret: this.clientSecret,
+      codeChallenge: this.codeChallenge,
+      codeChallengeMethod: this.codeChallengeMethod,
+      prompt: this.prompt,
+      state: this.state,
+      extraParams: this.extraParams,
+      usePKCE: this.usePKCE,
+    };
+  }
+
+  /** Prompts the user to authorize, opening a browser session for the auth URL. */
+  async promptAsync(
+    discovery: IAuthDiscoveryDocument,
+    { url, ...options }: IAuthRequestPromptOptions = {},
+  ): Promise<IAuthSessionResult> {
+    if (!url) {
+      if (!this.url) {
+        return this.promptAsync(discovery, {
+          ...options,
+          url: await this.makeAuthUrlAsync(discovery),
+        });
+      }
+      url = this.url;
+    }
+    invariant(
+      url,
+      'No authUrl provided - it points to the page where the user signs in.',
+    );
+
+    if (authLock) {
+      return { type: 'locked' };
+    }
+    authLock = true;
+
+    let result: IWebBrowserAuthSessionResult;
+    try {
+      result = await openAuthSessionAsync(url, this.redirectUri, options);
+    } finally {
+      authLock = false;
+    }
+
+    if (result.type === 'opened') {
+      throw new Error('An unexpected error occurred');
+    }
+    if (result.type !== 'success') {
+      return { type: result.type };
+    }
+    return this.parseReturnUrl(result.url);
+  }
+
+  parseReturnUrl(url: string): IAuthSessionResult {
+    const { params, errorCode } = getQueryParams(url);
+    const { state, error = errorCode ?? undefined } = params;
+
+    let parsedError: AuthError | null = null;
+    let authentication: TokenResponse | null = null;
+    if (state !== this.state) {
+      parsedError = new AuthError({
+        error: 'state_mismatch',
+        error_description:
+          'Cross-Site request verification failed. Cached state and returned state do not match.',
+      });
+    } else if (error) {
+      parsedError = new AuthError({ error, ...params });
+    }
+    if (params.access_token) {
+      authentication = TokenResponse.fromQueryParams(params);
+    }
+
+    return {
+      type: parsedError ? 'error' : 'success',
+      error: parsedError,
+      url,
+      params,
+      authentication,
+      errorCode,
+    };
+  }
+
+  /** Builds and caches the authorization URL. */
+  async makeAuthUrlAsync(discovery: IAuthDiscoveryDocument): Promise<string> {
+    const request = await this.getAuthRequestConfigAsync();
+    if (!request.state)
+      throw new Error('Cannot make request URL without a valid `state` loaded');
+
+    const params: Record<string, string> = {};
+    if (request.codeChallenge) {
+      params.code_challenge = request.codeChallenge;
+    }
+    for (const extra in request.extraParams) {
+      const param = request.extraParams[extra];
+      if (param != null) {
+        params[extra] = param;
+      }
+    }
+    if (request.usePKCE && request.codeChallengeMethod) {
+      params.code_challenge_method = request.codeChallengeMethod;
+    }
+    if (request.clientSecret) {
+      params.client_secret = request.clientSecret;
+    }
+    if (request.prompt) {
+      params.prompt = createPromptString(request.prompt) ?? '';
+    }
+    params.redirect_uri = request.redirectUri;
+    params.client_id = request.clientId;
+    params.response_type = request.responseType ?? ResponseType.Code;
+    params.state = request.state;
+    if (request.scopes?.length) {
+      params.scope = request.scopes.join(' ');
+    }
+
+    this.url = `${discovery.authorizationEndpoint}?${new URLSearchParams(params)}`;
+    return this.url;
+  }
+
+  private async ensureCodeIsSetupAsync(): Promise<void> {
+    if (this.codeVerifier) return;
+    const { codeVerifier, codeChallenge } = await buildCodeAsync();
+    this.codeVerifier = codeVerifier;
+    this.codeChallenge = codeChallenge;
+  }
+}

package/src/core/auth-request.types.ts

@@ -0,0 +1,55 @@
+import type { IAuthSessionOpenOptions } from '@symbiote-native/web-browser';
+import type { IDiscoveryDocument } from './discovery';
+
+export enum CodeChallengeMethod {
+  /** The default and recommended method for transforming the code verifier. */
+  S256 = 'S256',
+  /** Not secure - the code verifier would be sent to the server as-is. */
+  Plain = 'plain',
+}
+export type ICodeChallengeMethod = CodeChallengeMethod;
+
+/** https://tools.ietf.org/html/rfc6749#section-3.1.1 */
+export enum ResponseType {
+  Code = 'code',
+  Token = 'token',
+  /** A custom registered type for getting an `id_token` from Google OAuth. */
+  IdToken = 'id_token',
+}
+
+/** https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationRequest */
+export enum Prompt {
+  None = 'none',
+  Login = 'login',
+  Consent = 'consent',
+  SelectAccount = 'select_account',
+}
+
+export type IAuthRequestPromptOptions = IAuthSessionOpenOptions & {
+  /** URL to open when prompting the user; usually left undefined and generated internally. */
+  url?: string;
+};
+
+/** Represents an OAuth authorization request as JSON. */
+export type IAuthRequestConfig = {
+  /** @default ResponseType.Code */
+  responseType?: ResponseType | string;
+  clientId: string;
+  redirectUri: string;
+  scopes?: string[];
+  clientSecret?: string;
+  /** @default CodeChallengeMethod.S256 */
+  codeChallengeMethod?: CodeChallengeMethod;
+  codeChallenge?: string;
+  prompt?: Prompt | Prompt[];
+  /** Protection against Cross-Site Request Forgery. */
+  state?: string;
+  extraParams?: Record<string, string>;
+  /** @default true */
+  usePKCE?: boolean;
+};
+
+export type IAuthDiscoveryDocument = Pick<
+  IDiscoveryDocument,
+  'authorizationEndpoint'
+>;

package/src/core/auth-session.ts

@@ -0,0 +1,63 @@
+import { Platform } from 'react-native';
+import { dismissAuthSession } from '@symbiote-native/web-browser';
+import { AuthRequest } from './auth-request';
+import type { IAuthRequestConfig } from './auth-request.types';
+import type { IAuthSessionRedirectUriOptions } from './auth-session.types';
+import type { IIssuerOrDiscovery } from './discovery';
+import { resolveDiscoveryAsync } from './discovery';
+
+const IPV4_PATTERN =
+  /\b(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b/;
+
+/** Cancels an active `AuthSession`, if there is one. */
+export function dismiss(): void {
+  dismissAuthSession();
+}
+
+/** Unlike upstream, never reads an app manifest - pass `native` or `scheme` explicitly. */
+export function makeRedirectUri({
+  native,
+  scheme,
+  isTripleSlashed = false,
+  queryParams = {},
+  path = '',
+  preferLocalhost = false,
+}: IAuthSessionRedirectUriOptions = {}): string {
+  if (Platform.OS !== 'web' && native) {
+    return native;
+  }
+  if (!scheme) {
+    throw new Error(
+      'makeRedirectUri() requires a `scheme` (or a `native` URI on non-web platforms) - there is no app manifest to infer one from.',
+    );
+  }
+
+  const cleanedPath = path.replace(/^\//, '');
+  const query = new URLSearchParams(
+    Object.entries(queryParams).filter(
+      (entry): entry is [string, string] => entry[1] != null,
+    ),
+  ).toString();
+  const slashes = isTripleSlashed ? '///' : '//';
+  const url = `${scheme}:${slashes}${cleanedPath}${query ? `?${query}` : ''}`;
+
+  if (preferLocalhost) {
+    const ipAddress = url.match(IPV4_PATTERN);
+    if (ipAddress?.length) {
+      const [protocol, rest] = url.split(ipAddress[0]);
+      return `${protocol}localhost${rest}`;
+    }
+  }
+  return url;
+}
+
+/** Builds an `AuthRequest` and loads its authorization URL before returning it. */
+export async function loadAsync(
+  config: IAuthRequestConfig,
+  issuerOrDiscovery: IIssuerOrDiscovery,
+): Promise<AuthRequest> {
+  const request = new AuthRequest(config);
+  const discovery = await resolveDiscoveryAsync(issuerOrDiscovery);
+  await request.makeAuthUrlAsync(discovery);
+  return request;
+}

package/src/core/auth-session.types.ts

@@ -0,0 +1,29 @@
+import type { AuthError } from './errors';
+import type { TokenResponse } from './token-request';
+
+/** cancel/dismiss/opened/locked carry no extra data; error/success carry params + any token. */
+export type IAuthSessionResult =
+  | { type: 'cancel' | 'dismiss' | 'opened' | 'locked' }
+  | {
+      type: 'error' | 'success';
+      /** @deprecated legacy error-code query param, use `error` instead. */
+      errorCode: string | null;
+      error?: AuthError | null;
+      params: Record<string, string>;
+      authentication: TokenResponse | null;
+      url: string;
+    };
+
+export type IAuthSessionRedirectUriOptions = {
+  /** Appended to `scheme`; not applied when `native` is used. */
+  path?: string;
+  /** URI protocol `<scheme>://` built into the native app. Ignored if `native` is set. */
+  scheme?: string;
+  queryParams?: Record<string, string | undefined>;
+  /** `scheme:///path` when `true`, `scheme://path` otherwise. @default false */
+  isTripleSlashed?: boolean;
+  /** Rewrites a matched IPv4 host to `localhost` (iOS simulator convenience). @default false */
+  preferLocalhost?: boolean;
+  /** Manual scheme for a production build; takes precedence over every other option. */
+  native?: string;
+};

package/src/core/base64.ts

@@ -0,0 +1,33 @@
+const KEYSET =
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=';
+
+export function encodeNoWrap(input: string): string {
+  let output = '';
+  let i = 0;
+
+  do {
+    const chr1 = input.charCodeAt(i++);
+    const chr2 = input.charCodeAt(i++);
+    const chr3 = input.charCodeAt(i++);
+
+    const enc1 = chr1 >> 2;
+    const enc2 = ((chr1 & 3) << 4) | (chr2 >> 4);
+    let enc3 = ((chr2 & 15) << 2) | (chr3 >> 6);
+    let enc4 = chr3 & 63;
+    if (isNaN(chr2)) {
+      enc3 = 64;
+      enc4 = 64;
+    } else if (isNaN(chr3)) {
+      enc4 = 64;
+    }
+
+    output =
+      output +
+      KEYSET.charAt(enc1) +
+      KEYSET.charAt(enc2) +
+      KEYSET.charAt(enc3) +
+      KEYSET.charAt(enc4);
+  } while (i < input.length);
+
+  return output;
+}

package/src/core/discovery.ts

@@ -0,0 +1,102 @@
+import invariant from 'invariant';
+import type { ICodeChallengeMethod } from './auth-request.types';
+import { requestAsync } from './fetch';
+
+/** URL using the `https` scheme with no query or fragment, asserted by the OP as its issuer. */
+export type IIssuer = string;
+
+export type IProviderMetadataEndpoints = {
+  issuer?: IIssuer;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  userinfo_endpoint?: string;
+  revocation_endpoint?: string;
+  registration_endpoint?: string;
+  end_session_endpoint?: string;
+  introspection_endpoint?: string;
+  device_authorization_endpoint?: string;
+};
+
+export type IProviderMetadata = Record<string, string | boolean | string[]> &
+  IProviderMetadataEndpoints & {
+    jwks_uri?: string;
+    scopes_supported?: string[];
+    response_types_supported?: string[];
+    response_modes_supported?: string[];
+    grant_types_supported?: string[];
+    id_token_signing_alg_values_supported?: string[];
+    subject_types_supported?: string[];
+    token_endpoint_auth_methods_supported?: string[];
+    display_values_supported?: string[];
+    claim_types_supported?: string[];
+    claims_supported?: string[];
+    service_documentation?: string;
+    claims_locales_supported?: string[];
+    ui_locales_supported?: string[];
+    claims_parameter_supported?: boolean;
+    request_parameter_supported?: boolean;
+    request_uri_parameter_supported?: boolean;
+    require_request_uri_registration?: boolean;
+    op_policy_uri?: string;
+    op_tos_uri?: string;
+    code_challenge_methods_supported?: ICodeChallengeMethod[];
+    check_session_iframe?: string;
+    backchannel_logout_supported?: boolean;
+    backchannel_logout_session_supported?: boolean;
+    frontchannel_logout_supported?: boolean;
+    frontchannel_logout_session_supported?: boolean;
+  };
+
+export type IDiscoveryDocument = {
+  authorizationEndpoint?: string;
+  tokenEndpoint?: string;
+  /** Some providers (e.g. Spotify) don't expose one despite the spec requiring it. */
+  revocationEndpoint?: string;
+  userInfoEndpoint?: string;
+  endSessionEndpoint?: string;
+  registrationEndpoint?: string;
+  discoveryDocument?: IProviderMetadata;
+};
+
+export type IIssuerOrDiscovery = IIssuer | IDiscoveryDocument;
+
+/** https://tools.ietf.org/html/rfc5785 */
+export function issuerWithWellKnownUrl(issuer: IIssuer): string {
+  return `${issuer}/.well-known/openid-configuration`;
+}
+
+export async function fetchDiscoveryAsync(
+  issuer: IIssuer,
+): Promise<IDiscoveryDocument> {
+  const json = await requestAsync<IProviderMetadata>(
+    issuerWithWellKnownUrl(issuer),
+    {
+      dataType: 'json',
+      method: 'GET',
+    },
+  );
+
+  return {
+    discoveryDocument: json,
+    authorizationEndpoint: json.authorization_endpoint,
+    tokenEndpoint: json.token_endpoint,
+    revocationEndpoint: json.revocation_endpoint,
+    userInfoEndpoint: json.userinfo_endpoint,
+    endSessionEndpoint: json.end_session_endpoint,
+    registrationEndpoint: json.registration_endpoint,
+  };
+}
+
+export async function resolveDiscoveryAsync(
+  issuerOrDiscovery: IIssuerOrDiscovery,
+): Promise<IDiscoveryDocument> {
+  invariant(
+    issuerOrDiscovery &&
+      !['number', 'boolean'].includes(typeof issuerOrDiscovery),
+    'Expected a valid discovery object or issuer URL',
+  );
+  if (typeof issuerOrDiscovery === 'string') {
+    return await fetchDiscoveryAsync(issuerOrDiscovery);
+  }
+  return issuerOrDiscovery;
+}

package/src/core/errors.ts

@@ -0,0 +1,102 @@
+// Hand-ported from expo-modules-core's CodedError (src/errors/CodedError.ts) - this package
+// depends on none of the rest of expo-modules-core, so a single small class is copied rather
+// than pulling in the whole native-module runtime as a dependency.
+class CodedError extends Error {
+  code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export type IResponseErrorConfig = Record<string, unknown> & {
+  error: string;
+  error_description?: string;
+  error_uri?: string;
+};
+
+export type IAuthErrorConfig = IResponseErrorConfig & {
+  /** Required only if `state` was used in the initial request. */
+  state?: string;
+};
+
+const AUTH_ERROR_MESSAGES: Record<string, string> = {
+  invalid_request: `The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.`,
+  unauthorized_client: `The client is not authorized to request an authorization code using this method.`,
+  access_denied: `The resource owner or authorization server denied the request.`,
+  unsupported_response_type: `The authorization server does not support obtaining an authorization code using this method.`,
+  invalid_scope: 'The requested scope is invalid, unknown, or malformed.',
+  server_error:
+    'The authorization server encountered an unexpected condition that prevented it from fulfilling the request.',
+  temporarily_unavailable:
+    'The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server.',
+  interaction_required:
+    'Auth server requires user interaction of some form to proceed.',
+  login_required: 'Auth server requires user authentication.',
+  account_selection_required:
+    'User is required to select a session at the auth server.',
+  consent_required: 'Auth server requires user consent.',
+  invalid_request_uri:
+    'The `request_uri` in the auth request returns an error or contains invalid data.',
+  invalid_request_object:
+    'The request parameter contains an invalid request object.',
+  request_not_supported:
+    'The OP does not support use of the `request` parameter.',
+  request_uri_not_supported:
+    'The OP does not support use of the `request_uri` parameter.',
+  registration_not_supported:
+    'The OP does not support use of the `registration` parameter.',
+};
+
+const TOKEN_ERROR_MESSAGES: Record<string, string> = {
+  invalid_request: `The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.`,
+  invalid_client: `Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method).`,
+  invalid_grant: `The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.`,
+  unauthorized_client: `The authenticated client is not authorized to use this authorization grant type.`,
+  unsupported_grant_type: `The authorization grant type is not supported by the authorization server.`,
+};
+
+/** https://tools.ietf.org/html/rfc6749#section-4.1.2.1 */
+export class ResponseError extends CodedError {
+  description?: string;
+  uri?: string;
+  params: Record<string, unknown>;
+
+  constructor(params: IResponseErrorConfig, errorCodeType: 'auth' | 'token') {
+    const { error, error_description, error_uri } = params;
+    const message = (
+      errorCodeType === 'auth' ? AUTH_ERROR_MESSAGES : TOKEN_ERROR_MESSAGES
+    )[error];
+    let errorMessage: string;
+    if (message) {
+      errorMessage =
+        message +
+        (error_description ? `\nMore info: ${error_description}` : '');
+    } else if (error_description) {
+      errorMessage = error_description;
+    } else {
+      errorMessage = 'An unknown error occurred';
+    }
+    super(error, errorMessage);
+    this.description = error_description ?? message;
+    this.uri = error_uri;
+    this.params = params;
+  }
+}
+
+/** https://tools.ietf.org/html/rfc6749#section-5.2 */
+export class AuthError extends ResponseError {
+  state?: string;
+
+  constructor(response: IAuthErrorConfig) {
+    super(response, 'auth');
+    this.state = response.state;
+  }
+}
+
+export class TokenError extends ResponseError {
+  constructor(response: IResponseErrorConfig) {
+    super(response, 'token');
+  }
+}

package/src/core/fetch.ts

@@ -0,0 +1,71 @@
+export type IFetchHeaders = Record<string, string> & {
+  'Content-Type': string;
+  Authorization?: string;
+  Accept?: string;
+};
+
+export type IFetchRequest = {
+  headers?: IFetchHeaders;
+  body?: Record<string, string>;
+  dataType?: string;
+  method?: string;
+};
+
+export function requestAsync<T>(
+  requestUrl: string,
+  fetchRequest: IFetchRequest & { dataType: 'json' },
+): Promise<T>;
+export function requestAsync(
+  requestUrl: string,
+  fetchRequest: IFetchRequest,
+): Promise<string>;
+export async function requestAsync<T>(
+  requestUrl: string,
+  fetchRequest: IFetchRequest,
+): Promise<T | string> {
+  const url = new URL(requestUrl);
+
+  const headers: Record<string, string> = {};
+  const request: RequestInit = {
+    body: undefined,
+    method: fetchRequest.method,
+    mode: 'cors',
+    headers,
+  };
+
+  const isJsonDataType = fetchRequest.dataType?.toLowerCase() === 'json';
+
+  if (fetchRequest.headers) {
+    for (const key in fetchRequest.headers) {
+      const header = fetchRequest.headers[key];
+      if (header != null) {
+        headers[key] = header;
+      }
+    }
+  }
+
+  if (fetchRequest.body) {
+    if (fetchRequest.method?.toUpperCase() === 'POST') {
+      request.body = new URLSearchParams(fetchRequest.body).toString();
+    } else {
+      for (const [key, value] of Object.entries(fetchRequest.body)) {
+        url.searchParams.append(key, value);
+      }
+    }
+  }
+
+  if (isJsonDataType && !headers.Accept && !headers.accept) {
+    headers['Accept'] = 'application/json, text/javascript; q=0.01';
+  }
+
+  // React Native's URL implementation adds a trailing slash that the server doesn't expect.
+  const correctedUrl = url.toString().replace(/\/$/, '');
+
+  const response = await fetch(correctedUrl, request);
+
+  const contentType = response.headers.get('content-type');
+  if (isJsonDataType || contentType?.includes('application/json')) {
+    return response.json();
+  }
+  return response.text();
+}