API reference#

Exports of @sigx/lynx-webauth v0.9.1.

The package root exports the openAuthSession primitive, an isWebAuthAvailable guard, and two types. The opt-in PKCE helpers live under the @sigx/lynx-webauth/oauth subpath so the core primitive stays unopinionated and they tree-shake away when unused.

import { openAuthSession, isWebAuthAvailable } from '@sigx/lynx-webauth';
import type { OpenAuthSessionOptions, OpenAuthSessionResult } from '@sigx/lynx-webauth';

openAuthSession#

function openAuthSession(
  authorizeUrl: string,
  callbackScheme: string,
  options?: OpenAuthSessionOptions,
): Promise<OpenAuthSessionResult>

Open a system web-auth session — ASWebAuthenticationSession on iOS, Chrome Custom Tabs on Android — for an OAuth / OpenID-Connect flow. Presents the sheet over the app, waits for the provider to redirect to callbackScheme://…, then dismisses itself and resolves with the callback URL. Always resolves — cancellation and failures are normal resolved values, never a rejected promise.

• authorizeUrl — the provider's authorization URL (with client_id, redirect_uri, scope, state, PKCE params, …).
• callbackScheme — the app's registered custom scheme, the same one Lynx wires for Linking (set via signalx.config.ts's scheme). A bare scheme like "myapp"; a trailing :// or : is tolerated.
• options — optional OpenAuthSessionOptions.
• Returns — Promise<OpenAuthSessionResult>, a three-way union discriminated by which field is present.
• Platform — both.

isWebAuthAvailable#

function isWebAuthAvailable(): boolean

Synchronous (non-Promise) check of whether the native WebAuth module is wired into the current build. Returns true once linked.

• Returns — boolean.
• Platform — both.

Types#

OpenAuthSessionOptions#

interface OpenAuthSessionOptions {
  ephemeral?: boolean;
  toolbarColor?: string;
  preferredBrowserPackage?: string;
  signal?: AbortSignal;
}

OpenAuthSessionResult#

type OpenAuthSessionResult =
  | { url: string }        // provider redirected back to callbackScheme://…
  | { canceled: true }     // user dismissed the sheet, or aborted via options.signal
  | { error: string };     // the session could not start or failed

A three-way union discriminated by which field is present. A truthy result.url is the full callback URL — parse code / state / error yourself, or with parseCallback. result.canceled is true when the user backed out or the session was aborted. result.error carries the failure message when the session could not start.

OAuth helpers#

Opt-in helpers under @sigx/lynx-webauth/oauth, scoped to the frozen parts of the spec — PKCE (RFC 7636), state generation, and callback parsing. All pure JS, no native code. Token exchange, refresh, and OIDC discovery are intentionally out of scope.

import { generatePKCE, generateState, parseCallback } from '@sigx/lynx-webauth/oauth';
import type { RandomOptions, PkceChallenge, CallbackParams } from '@sigx/lynx-webauth/oauth';

generatePKCE#

function generatePKCE(options?: RandomOptions): Promise<PkceChallenge>

Generate a PKCE code_verifier / code_challenge pair (RFC 7636, S256). The verifier is 32 random bytes → a 43-char base64url string; the challenge is base64url(sha256(verifier)).

• options.randomBytes — supply length cryptographically-random bytes. Defaults to globalThis.crypto.getRandomValues. There is no insecure fallback — a missing RNG throws rather than silently weakening the flow.
• Returns — Promise<PkceChallenge>: { verifier, challenge, method: 'S256' }. Keep the verifier and send it as code_verifier on token exchange.

generateState#

function generateState(options?: RandomOptions): string

Generate a random opaque state value (16 bytes → base64url). Pass it on /authorize and compare it against the returned CallbackParams.state to defend against CSRF / mix-up attacks.

• options.randomBytes — as for generatePKCE.
• Returns — string.

parseCallback#

function parseCallback(url: string): CallbackParams

Parse the callback URL returned by openAuthSession into its OAuth params. Handles both ?query (authorization-code) and #fragment (implicit / token) responses.

• url — the full callback URL from result.url.
• Returns — CallbackParams.

PkceChallenge#

interface PkceChallenge {
  verifier: string;       // the high-entropy code_verifier — keep it
  challenge: string;      // the code_challenge — send it on /authorize
  method: 'S256';         // always 'S256'; plain is never emitted
}

CallbackParams#

interface CallbackParams {
  code?: string;             // authorization code (code flow)
  state?: string;            // the state echoed back — compare against what you sent
  error?: string;            // OAuth error code (e.g. access_denied), if returned
  errorDescription?: string; // human-readable error_description, if present
  params: Record<string, string>; // all params, merged from query + fragment
}

params merges the query string and the URL fragment, so token-in-fragment responses are covered; the query string wins on key collision.

RandomOptions#

interface RandomOptions {
  randomBytes?: (length: number) => Uint8Array;
}

Override the RNG used by generatePKCE / generateState (defaults to Web Crypto). Useful in tests or RNG-less environments; there is no insecure fallback.

See also#

• Usage guide — the PKCE recipe, sheet customisation, and the Android abort limitation.
• Linking — the URL-scheme pipeline the callback rides in on.
• Secure Storage — encrypted at-rest storage for exchanged tokens.