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

package/src/core/index.ts

@@ -0,0 +1,97 @@
+export { AuthRequest } from './auth-request';
+export {
+  CodeChallengeMethod,
+  Prompt,
+  ResponseType,
+  type IAuthDiscoveryDocument,
+  type IAuthRequestConfig,
+  type IAuthRequestPromptOptions,
+  type ICodeChallengeMethod,
+} from './auth-request.types';
+export { dismiss, loadAsync, makeRedirectUri } from './auth-session';
+export type {
+  IAuthSessionRedirectUriOptions,
+  IAuthSessionResult,
+} from './auth-session.types';
+export type {
+  IDiscoveryDocument,
+  IIssuer,
+  IIssuerOrDiscovery,
+  IProviderMetadata,
+} from './discovery';
+export {
+  fetchDiscoveryAsync,
+  issuerWithWellKnownUrl,
+  resolveDiscoveryAsync,
+} from './discovery';
+export { AuthError, ResponseError, TokenError } from './errors';
+export type { IAuthErrorConfig, IResponseErrorConfig } from './errors';
+export { requestAsync } from './fetch';
+export type { IFetchHeaders, IFetchRequest } from './fetch';
+export {
+  AccessTokenRequest,
+  RefreshTokenRequest,
+  RevokeTokenRequest,
+  TokenRequest,
+  TokenResponse,
+  exchangeCodeAsync,
+  fetchUserInfoAsync,
+  getCurrentTimeInSeconds,
+  refreshAsync,
+  revokeAsync,
+} from './token-request';
+export {
+  GrantType,
+  TokenTypeHint,
+  type IAccessTokenRequestConfig,
+  type IRefreshTokenRequestConfig,
+  type IRevokeTokenRequestConfig,
+  type IServerTokenResponseConfig,
+  type ITokenRequestConfig,
+  type ITokenResponseConfig,
+  type ITokenType,
+} from './token-request.types';
+export {
+  AUTH_CELL_CHANGE,
+  createAutoDiscoveryController,
+  createLoadedRequestController,
+  createRequestResultController,
+} from './auth-request-controllers';
+export type {
+  IAuthCell,
+  IAuthRequestClass,
+  ILoadableRequest,
+  IPromptMethod,
+  IRequestResultHolder,
+} from './auth-request-controllers';
+export { GETTER_ARGS, createAuthRequestHooks } from './auth-request-hooks';
+export type {
+  IApply,
+  IAuthHooksKit,
+  IAuthRequestHooks,
+  IAuthResourceController,
+  IBoxedKind,
+  IGetterKind,
+  IHkt,
+} from './auth-request-hooks';
+export { createGoogleExchangeController } from './providers/google-exchange-controller';
+export {
+  resolveFacebookRequestSetup,
+  resolveGoogleRequestSetup,
+  toGoogleIdTokenConfig,
+} from './providers/provider-hook-setup';
+export type {
+  IGoogleExchangeParams,
+  IGoogleRequestSetup,
+} from './providers/provider-hook-setup';
+export type { IProviderAuthRequestConfig } from './providers/provider.types';
+export {
+  FacebookAuthRequest,
+  discovery as facebookDiscovery,
+} from './providers/facebook';
+export type { IFacebookAuthRequestConfig } from './providers/facebook';
+export {
+  GoogleAuthRequest,
+  discovery as googleDiscovery,
+} from './providers/google';
+export type { IGoogleAuthRequestConfig } from './providers/google';

package/src/core/pkce.ts

@@ -0,0 +1,60 @@
+import invariant from 'invariant';
+import {
+  CryptoDigestAlgorithm,
+  CryptoEncoding,
+  digestStringAsync,
+  getRandomValues,
+} from '@symbiote-native/crypto';
+
+const CHARSET =
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+
+function convertBufferToString(buffer: Uint8Array): string {
+  const chars: string[] = [];
+  for (const byte of buffer) {
+    const char = CHARSET[byte % CHARSET.length];
+    if (char != null) {
+      chars.push(char);
+    }
+  }
+  return chars.join('');
+}
+
+function convertToUrlSafeString(b64: string): string {
+  return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+}
+
+export function generateRandom(size: number): string {
+  const buffer = getRandomValues(new Uint8Array(size));
+  return convertBufferToString(buffer);
+}
+
+/** Proof Key for Code Exchange (RFC 7636), Section 4.1. */
+export async function deriveChallengeAsync(code: string): Promise<string> {
+  invariant(
+    code.length > 42 && code.length < 129,
+    'Invalid code length for PKCE.',
+  );
+
+  const buffer = await digestStringAsync(CryptoDigestAlgorithm.SHA256, code, {
+    encoding: CryptoEncoding.BASE64,
+  });
+  return convertToUrlSafeString(buffer);
+}
+
+export async function buildCodeAsync(
+  size: number = 128,
+): Promise<{ codeChallenge: string; codeVerifier: string }> {
+  const codeVerifier = generateRandom(size);
+  const codeChallenge = await deriveChallengeAsync(codeVerifier);
+  return { codeVerifier, codeChallenge };
+}
+
+/** Digests a random string with hex encoding, useful for creating `nonce`s. */
+export async function generateHexStringAsync(size: number): Promise<string> {
+  const value = generateRandom(size);
+  const buffer = await digestStringAsync(CryptoDigestAlgorithm.SHA256, value, {
+    encoding: CryptoEncoding.HEX,
+  });
+  return convertToUrlSafeString(buffer);
+}

package/src/core/prompt-string.ts

@@ -0,0 +1,8 @@
+import type { Prompt } from './auth-request.types';
+
+export function createPromptString(
+  prompt: Prompt | Prompt[] | undefined,
+): string | undefined {
+  if (!prompt) return undefined;
+  return Array.isArray(prompt) ? prompt.join(' ') : prompt;
+}

package/src/core/providers/facebook.ts

@@ -0,0 +1,66 @@
+import type { IAuthRequestConfig } from '../auth-request.types';
+import { ResponseType } from '../auth-request.types';
+import { AuthRequest } from '../auth-request';
+import type { IDiscoveryDocument } from '../discovery';
+import { generateHexStringAsync } from '../pkce';
+import { applyRequiredScopes } from './provider-utils';
+import type { IProviderAuthRequestConfig } from './provider.types';
+
+/** Required for Firebase to work properly - a reasonable default either way. */
+const MINIMUM_SCOPES = ['public_profile', 'email'];
+
+export const discovery: IDiscoveryDocument = {
+  authorizationEndpoint: 'https://www.facebook.com/v6.0/dialog/oauth',
+  tokenEndpoint: 'https://graph.facebook.com/v6.0/oauth/access_token',
+};
+
+export type IFacebookAuthRequestConfig = IProviderAuthRequestConfig & {
+  webClientId?: string;
+  iosClientId?: string;
+  androidClientId?: string;
+};
+
+/** Extends `AuthRequest`, applying Facebook's minimum scopes and an auth nonce. */
+export class FacebookAuthRequest extends AuthRequest {
+  nonce?: string;
+
+  constructor({
+    language,
+    extraParams = {},
+    clientSecret,
+    ...config
+  }: IFacebookAuthRequestConfig) {
+    const inputParams: Record<string, string> = {
+      display: 'popup',
+      ...extraParams,
+    };
+    if (language) {
+      inputParams.locale = language;
+    }
+
+    const scopes = applyRequiredScopes(config.scopes, MINIMUM_SCOPES);
+    // Facebook rejects a client secret unless the code flow is used.
+    const inputClientSecret =
+      config.responseType && config.responseType !== ResponseType.Code
+        ? clientSecret
+        : undefined;
+
+    super({
+      ...config,
+      responseType: config.responseType ?? ResponseType.Token,
+      clientSecret: inputClientSecret,
+      scopes,
+      extraParams: inputParams,
+    });
+  }
+
+  override async getAuthRequestConfigAsync(): Promise<IAuthRequestConfig> {
+    const { extraParams = {}, ...config } =
+      await super.getAuthRequestConfigAsync();
+    if (!extraParams.nonce) {
+      this.nonce = this.nonce ?? (await generateHexStringAsync(16));
+      extraParams.auth_nonce = this.nonce;
+    }
+    return { ...config, extraParams };
+  }
+}

package/src/core/providers/google-exchange-controller.ts

@@ -0,0 +1,117 @@
+// The automatic code exchange of upstream's Google `useAuthRequest`, as a cell that follows the
+// prompt result and swaps in the exchanged authentication once it arrives
+
+import { createResourceController } from '@symbiote-native/engine';
+import type { IAuthCell, ILoadableRequest } from '../auth-request-controllers';
+import { createAuthCell } from '../auth-request-controllers';
+import type { IAuthSessionResult } from '../auth-session.types';
+import type { IAuthSessionParamsResult } from '../session-result';
+import { isSuccessResult } from '../session-result';
+import { AccessTokenRequest } from '../token-request';
+import { discovery as googleDiscovery } from './google';
+import type { IGoogleExchangeParams } from './provider-hook-setup';
+
+type ICodeSource = Pick<ILoadableRequest, 'codeVerifier'>;
+type IExchangeKey = {
+  result: IAuthSessionResult | null;
+  request: ICodeSource | null;
+  exchange: IGoogleExchangeParams;
+};
+type IResultCell = ReturnType<typeof createAuthCell<IAuthSessionResult | null>>;
+type IExchangeResource = { cell: IResultCell; stop: () => void };
+
+// The result to exchange, or null when there is nothing to do: a code and no authentication yet,
+// unless the caller decided explicitly
+function exchangeableResult(
+  result: IAuthSessionResult | null,
+  override: boolean | undefined,
+): IAuthSessionParamsResult | null {
+  if (!isSuccessResult(result)) return null;
+  const shouldExchange =
+    override ?? (Boolean(result.params.code) && !result.authentication);
+  return shouldExchange ? result : null;
+}
+
+// Trades the code for tokens and folds them into the result, as the hook does upstream
+async function exchangeCode(
+  toExchange: IAuthSessionParamsResult,
+  request: ICodeSource | null,
+  exchange: IGoogleExchangeParams,
+): Promise<IAuthSessionResult> {
+  const exchangeRequest = new AccessTokenRequest({
+    clientId: exchange.clientId,
+    clientSecret: exchange.clientSecret,
+    redirectUri: exchange.redirectUri,
+    scopes: exchange.scopes,
+    code: toExchange.params.code ?? '',
+    extraParams: { code_verifier: request?.codeVerifier || '' },
+  });
+  const authentication = await exchangeRequest.performAsync(googleDiscovery);
+  return {
+    ...toExchange,
+    params: {
+      id_token: authentication?.idToken || '',
+      access_token: authentication.accessToken,
+      ...toExchange.params,
+    },
+    authentication,
+  };
+}
+
+function isSameKey(a: IExchangeKey, b: IExchangeKey): boolean {
+  return (
+    a.result === b.result &&
+    a.request?.codeVerifier === b.request?.codeVerifier &&
+    a.exchange.clientId === b.exchange.clientId &&
+    a.exchange.redirectUri === b.exchange.redirectUri &&
+    a.exchange.clientSecret === b.exchange.clientSecret &&
+    a.exchange.shouldAutoExchangeCode === b.exchange.shouldAutoExchangeCode &&
+    a.exchange.scopes?.join(',') === b.exchange.scopes?.join(',')
+  );
+}
+
+export function createGoogleExchangeController(): {
+  resolve: (
+    result: IAuthSessionResult | null,
+    request: ICodeSource | null,
+    exchange: IGoogleExchangeParams,
+  ) => IAuthCell<IAuthSessionResult | null>;
+  flushDispose: () => void;
+  dispose: () => void;
+} {
+  // The last published value stays visible while the next exchange runs
+  let lastPublished: IAuthSessionResult | null = null;
+
+  const controller = createResourceController<IExchangeKey, IExchangeResource>(
+    ({ result, request, exchange }) => {
+      let isMounted = true;
+      const stop = (): void => {
+        isMounted = false;
+      };
+      const toExchange = exchangeableResult(
+        result,
+        exchange.shouldAutoExchangeCode,
+      );
+      if (!toExchange) {
+        lastPublished = result;
+        return { cell: createAuthCell(result), stop };
+      }
+      const cell = createAuthCell<IAuthSessionResult | null>(lastPublished);
+      void exchangeCode(toExchange, request, exchange).then(merged => {
+        if (!isMounted) return;
+        lastPublished = merged;
+        cell.set(merged);
+      });
+      return { cell, stop };
+    },
+    resource => resource.stop(),
+    isSameKey,
+  );
+
+  return {
+    resolve: (result, request, exchange) =>
+      controller.resolve({ result, request, exchange }).cell,
+    flushDispose: controller.flushDispose,
+    dispose: controller.dispose,
+  };
+}

package/src/core/providers/google.ts

@@ -0,0 +1,81 @@
+import type { IAuthRequestConfig } from '../auth-request.types';
+import { Prompt, ResponseType } from '../auth-request.types';
+import { AuthRequest } from '../auth-request';
+import type { IDiscoveryDocument } from '../discovery';
+import { generateHexStringAsync } from '../pkce';
+import { applyRequiredScopes } from './provider-utils';
+import type { IProviderAuthRequestConfig } from './provider.types';
+
+const MINIMUM_SCOPES = [
+  'openid',
+  'https://www.googleapis.com/auth/userinfo.profile',
+  'https://www.googleapis.com/auth/userinfo.email',
+];
+
+export const discovery: IDiscoveryDocument = {
+  authorizationEndpoint: 'https://accounts.google.com/o/oauth2/v2/auth',
+  tokenEndpoint: 'https://oauth2.googleapis.com/token',
+  revocationEndpoint: 'https://oauth2.googleapis.com/revoke',
+  userInfoEndpoint: 'https://openidconnect.googleapis.com/v1/userinfo',
+};
+
+export type IGoogleAuthRequestConfig = IProviderAuthRequestConfig & {
+  /** If the user's email is known ahead of time, supply it as the default option. */
+  loginHint?: string;
+  /** Lets the user switch accounts, where possible. @default false */
+  selectAccount?: boolean;
+  webClientId?: string;
+  iosClientId?: string;
+  androidClientId?: string;
+  /** Exchange the response code for a token in the hook, on by default for the code flow */
+  shouldAutoExchangeCode?: boolean;
+};
+
+/** Extends `AuthRequest`, applying Google's minimum scopes and an id-token nonce. */
+export class GoogleAuthRequest extends AuthRequest {
+  nonce?: string;
+
+  constructor({
+    language,
+    loginHint,
+    selectAccount,
+    extraParams = {},
+    clientSecret,
+    ...config
+  }: IGoogleAuthRequestConfig) {
+    const inputParams = { ...extraParams };
+    if (language) inputParams.hl = language;
+    if (loginHint) inputParams.login_hint = loginHint;
+    if (selectAccount) inputParams.prompt = Prompt.SelectAccount;
+
+    const scopes = applyRequiredScopes(config.scopes, MINIMUM_SCOPES);
+    const isImplicit =
+      config.responseType === ResponseType.Token ||
+      config.responseType === ResponseType.IdToken;
+    if (isImplicit) {
+      config.usePKCE = false;
+    }
+    // Google rejects a client secret unless the code flow is used.
+    const inputClientSecret =
+      config.responseType && config.responseType !== ResponseType.Code
+        ? clientSecret
+        : undefined;
+
+    super({
+      ...config,
+      clientSecret: inputClientSecret,
+      scopes,
+      extraParams: inputParams,
+    });
+  }
+
+  override async getAuthRequestConfigAsync(): Promise<IAuthRequestConfig> {
+    const { extraParams = {}, ...config } =
+      await super.getAuthRequestConfigAsync();
+    if (config.responseType === ResponseType.IdToken && !extraParams.nonce) {
+      this.nonce = this.nonce ?? (await generateHexStringAsync(16));
+      extraParams.nonce = this.nonce;
+    }
+    return { ...config, extraParams };
+  }
+}

package/src/core/providers/provider-hook-setup.ts

@@ -0,0 +1,117 @@
+// The config each provider hook derives before it loads a request, kept pure so every adapter's
+// hook shares one copy of upstream's `useMemo` blocks
+
+import { Platform } from 'react-native';
+import { applicationId } from '@symbiote-native/application';
+import { Prompt, ResponseType } from '../auth-request.types';
+import { makeRedirectUri } from '../auth-session';
+import type { IAuthSessionRedirectUriOptions } from '../auth-session.types';
+import type { IFacebookAuthRequestConfig } from './facebook';
+import type { IGoogleAuthRequestConfig } from './google';
+import { invariantClientId } from './provider-utils';
+
+type IClientIdProperty = 'iosClientId' | 'androidClientId' | 'webClientId';
+
+function clientIdProperty(): IClientIdProperty {
+  return Platform.select<IClientIdProperty>({
+    ios: 'iosClientId',
+    android: 'androidClientId',
+    default: 'webClientId',
+  });
+}
+
+function pickClientId(
+  config: Partial<IGoogleAuthRequestConfig | IFacebookAuthRequestConfig>,
+  providerName: string,
+): string {
+  const propertyName = clientIdProperty();
+  const clientId = config[propertyName] ?? config.clientId;
+  invariantClientId(propertyName, clientId, providerName);
+  return clientId;
+}
+
+/** What the automatic code exchange needs, upstream reads the same fields off the hook config */
+export type IGoogleExchangeParams = {
+  clientId: string;
+  clientSecret?: string;
+  redirectUri: string;
+  scopes?: string[];
+  shouldAutoExchangeCode?: boolean;
+};
+
+export type IGoogleRequestSetup = {
+  requestConfig: IGoogleAuthRequestConfig;
+  exchange: IGoogleExchangeParams;
+};
+
+function resolveGoogleResponseType(
+  config: Partial<IGoogleAuthRequestConfig>,
+): IGoogleAuthRequestConfig['responseType'] {
+  // Allow overrides
+  if (typeof config.responseType !== 'undefined') return config.responseType;
+  // Installed apps auto exchange the code for the token and the id token, no secret needed
+  return ResponseType.Code;
+}
+
+function resolveGoogleExtraParams(
+  config: Partial<IGoogleAuthRequestConfig>,
+): Record<string, string> {
+  const output: Record<string, string> = { ...config.extraParams };
+  if (config.language) output.hl = config.language;
+  if (config.loginHint) output.login_hint = config.loginHint;
+  if (config.selectAccount) output.prompt = Prompt.SelectAccount;
+  return output;
+}
+
+export function resolveGoogleRequestSetup(
+  config: Partial<IGoogleAuthRequestConfig> = {},
+  redirectUriOptions: Partial<IAuthSessionRedirectUriOptions> = {},
+): IGoogleRequestSetup {
+  const clientId = pickClientId(config, 'Google');
+  const redirectUri =
+    config.redirectUri ??
+    makeRedirectUri({
+      native: `${applicationId}:/oauthredirect`,
+      ...redirectUriOptions,
+    });
+  return {
+    requestConfig: {
+      ...config,
+      responseType: resolveGoogleResponseType(config),
+      extraParams: resolveGoogleExtraParams(config),
+      clientId,
+      redirectUri,
+    },
+    exchange: {
+      clientId,
+      clientSecret: config.clientSecret,
+      redirectUri,
+      scopes: config.scopes,
+      shouldAutoExchangeCode: config.shouldAutoExchangeCode,
+    },
+  };
+}
+
+/** Upstream only asks for `id_token` directly on web, so off web the default flow applies */
+export function toGoogleIdTokenConfig(
+  config: Partial<IGoogleAuthRequestConfig>,
+): Partial<IGoogleAuthRequestConfig> {
+  return { ...config, responseType: undefined };
+}
+
+export function resolveFacebookRequestSetup(
+  config: Partial<IFacebookAuthRequestConfig> = {},
+  redirectUriOptions: Partial<IAuthSessionRedirectUriOptions> = {},
+): IFacebookAuthRequestConfig {
+  const clientId = pickClientId(config, 'Facebook');
+  const redirectUri =
+    config.redirectUri ??
+    makeRedirectUri({
+      // The redirect URI is fb + client ID on native
+      native: `fb${clientId}://authorize`,
+      ...redirectUriOptions,
+    });
+  const extraParams: Record<string, string> = { ...config.extraParams };
+  if (config.language) extraParams.locale = config.language;
+  return { ...config, extraParams, clientId, redirectUri };
+}

package/src/core/providers/provider-utils.ts

@@ -0,0 +1,18 @@
+export function applyRequiredScopes(
+  scopes: string[] = [],
+  requiredScopes: string[],
+): string[] {
+  return [...new Set([...scopes, ...requiredScopes])];
+}
+
+export function invariantClientId(
+  idName: string,
+  value: string | undefined,
+  providerName: string,
+): asserts value is string {
+  if (typeof value === 'undefined') {
+    throw new Error(
+      `Client Id property \`${idName}\` must be defined to use ${providerName} auth on this platform.`,
+    );
+  }
+}

package/src/core/providers/provider.types.ts

@@ -0,0 +1,6 @@
+import type { IAuthRequestConfig } from '../auth-request.types';
+
+export type IProviderAuthRequestConfig = IAuthRequestConfig & {
+  /** ISO 639-1 code, optionally `-<ISO 3166-1 alpha-2>` (e.g. `it`, `pt-PT`). */
+  language?: string;
+};

package/src/core/query-params.ts

@@ -0,0 +1,20 @@
+export type IQueryParamsResult = {
+  errorCode: string | null;
+  params: Record<string, string>;
+};
+
+export function getQueryParams(input: string): IQueryParamsResult {
+  const url = new URL(input, 'https://phony.example');
+
+  const errorCode = url.searchParams.get('errorCode');
+  url.searchParams.delete('errorCode');
+
+  const params = Object.fromEntries(url.searchParams);
+  if (url.hash) {
+    new URLSearchParams(url.hash.replace(/^#/, '')).forEach((value, key) => {
+      params[key] = value;
+    });
+  }
+
+  return { errorCode, params };
+}

package/src/core/session-result.ts

@@ -0,0 +1,15 @@
+import type { IAuthSessionResult } from './auth-session.types';
+
+const SUCCESS_TYPE = 'success' satisfies IAuthSessionResult['type'];
+
+/** The variant that carries params and authentication */
+export type IAuthSessionParamsResult = Extract<
+  IAuthSessionResult,
+  { params: unknown }
+>;
+
+export function isSuccessResult(
+  result: IAuthSessionResult | null,
+): result is IAuthSessionParamsResult {
+  return result?.type === SUCCESS_TYPE;
+}