Skip to main content

@twinfinity/authentication

Index

Classes

Enumerations

Functions

Interfaces

Type Aliases

Variables

Type Aliases

Callback

Callback<T>: (value: T) => void

Type parameters

  • T

Type declaration

    • (value: T): void

    • Parameters

      • value: T

      Returns void

Optional

Optional<T, K>: Omit<T, K> & Partial<T>

Type parameters

  • T
  • K: keyof T

PopupWindowOptions

PopupWindowOptions: { height?: number; position?: PopupWindowPosition; signal?: AbortSignal; timeoutMs?: number; width?: number }

Type declaration

  • optionalreadonlyheight?: number
  • optionalreadonlyposition?: PopupWindowPosition

    Defaults to 'center-window'.

  • optionalreadonlysignal?: AbortSignal

    An optional AbortSignal the caller can use to cancel an in-progress login, e.g. when the user dismisses a "signing in…" dialog in the app. Aborting closes the popup and rejects establishUsingPopup with a TwinfinitySessionError carrying cause: 'cancelled', which lets callers tell a deliberate cancellation apart from a real failure. A signal that is already aborted when login starts rejects immediately without opening a popup. Has no effect once the login has settled.

  • optionalreadonlytimeoutMs?: number

    Optional upper bound, in milliseconds, on how long the login may take before it rejects with a TwinfinitySessionError carrying cause: 'timeout'. Defaults to no timeout: the user drives a popup login and a popup the user closes is already detected (see POPUP_CLOSED_POLL_INTERVAL_MS). Set this if you want a hard upper bound regardless.

  • optionalreadonlywidth?: number

PopupWindowPosition

PopupWindowPosition: center-window | default | { left: number; top: number }

Where the login popup should appear.

  • 'center-window' — centered over the current browser window. Multi-monitor aware: the popup follows whichever screen the browser window is on.
  • 'default' — let the browser decide where to place the popup.
  • { left, top } — explicit screen coordinates (relative to the top-left of the primary screen, not the browser window), passed through to window.open.

Positioning is best-effort. The browser may clamp coordinates to keep the popup on-screen, and some environments (notably Safari and mobile browsers) ignore positioning entirely.

ProviderDiscoveryOptions

ProviderDiscoveryOptions: { apiUrl?: never; openIdProviderUrl: string | URL } | { apiUrl: string | URL; openIdProviderUrl?: never }

How a TwinfinitySession discovers its OpenID Connect provider and which origin it is pinned to. Exactly one of the two must be supplied:

  • apiUrl — the Twinfinity backend this app talks to. Discovery is rooted at that origin's /.well-known/openid-configuration (any path is discarded and a leading bim. stripped — see openIdProviderConfigurationUrl), and the session is pinned to that canonical origin. This is the recommended option: pointing BimApi.create at the same backend URL is then guaranteed to match the pinned origin, so the session's token is only ever sent there.
  • openIdProviderUrl — an explicit provider URL, used verbatim (host as given, path preserved, no bim. stripping; see deriveOpenIdProviderConfigurationUrl). Use this for a fixed/known IdP that does not follow the backend's origin convention. The session is pinned to that URL's origin.

TwinfinityClientCredentialsSessionOptions

TwinfinityClientCredentialsSessionOptions: ProviderDiscoveryOptions & { clientId: string; clientSecret: string }

Options for TwinfinitySession.establishWithClientCredentials. Provider discovery and origin pinning work exactly as for the interactive flows (see ProviderDiscoveryOptions); the clientSecret is what replaces the user login. See OpenIdConnectClient.createWithClientCredentials for the constraints on the secret.

TwinfinityEmbeddedSessionLoginOptions

TwinfinityEmbeddedSessionLoginOptions: TwinfinitySessionOptions & { cookieAccessPromptStyle?: Partial<CSSStyleDeclaration>; cookieAccessPromptText?: string; loginFrame?: HTMLIFrameElement; loginHint?: string; signal?: AbortSignal; timeoutMs?: number }

TwinfinitySessionErrorCause

TwinfinitySessionErrorCause: cancelled | popup_closed | unable_to_redirect | timeout

The discriminant values a TwinfinitySessionError can carry on its cause for the in-window login flows (TwinfinitySession.establishUsingPopup / TwinfinitySession.establishEmbedded). Callers switch on error.cause to tell a deliberate cancellation ('cancelled'), a login window the user closed ('popup_closed'), or a login that ran out of time ('timeout') apart from a genuine authentication failure. cause stays unknown on the error type because other failures carry a richer object/Error cause instead, so narrow with this union (e.g. if (error.cause === 'cancelled')) when inspecting an in-window result.

TwinfinitySessionOptions

TwinfinitySessionOptions: Optional<Omit<OpenIdConnectClientOptions, openIdProviderUrl>, redirectUri> & ProviderDiscoveryOptions

TwinfinitySessionOptionsWithApplicationState

TwinfinitySessionOptionsWithApplicationState<ApplicationStateT>: TwinfinitySessionOptions & { applicationState: ApplicationState<ApplicationStateT> }

Type parameters

  • ApplicationStateT

Variables

constCODE_VERIFIER_SESSION_STORAGE_KEY

CODE_VERIFIER_SESSION_STORAGE_KEY: open_id_connect_client_code_verifier = 'open_id_connect_client_code_verifier'

constDEFAULT_SILENT_LOGIN_TIMEOUT_MS

DEFAULT_SILENT_LOGIN_TIMEOUT_MS: 10000 = 10_000

Default upper bound for a silent (hidden iframe) embedded login — see TwinfinitySession.establishEmbedded. A hidden iframe can't be detected as "closed" the way a popup can (see POPUP_CLOSED_POLL_INTERVAL_MS), so without a timeout a provider that never posts a result would leave the login pending forever. Interactive logins (popups and visible iframes, e.g. the cookie-access consent prompt) are not timed out by default since the user drives them; pass an explicit timeoutMs to bound those.

constPOPUP_CLOSED_POLL_INTERVAL_MS

POPUP_CLOSED_POLL_INTERVAL_MS: 500 = 500

How often TwinfinitySession.loginInWindow polls the login popup to detect that the user closed it before authentication completed. There is no DOM event for a user dismissing a popup, so polling window.closed is the only portable way to notice. This only meaningfully covers popups: an attached login iframe's contentWindow.closed never flips to true while the iframe is in the DOM, so a silent iframe login that the provider never answers is bounded by a timeout instead — see DEFAULT_SILENT_LOGIN_TIMEOUT_MS and loginInWindow.

constREDIRECT_URI_SESSION_STORAGE_KEY

REDIRECT_URI_SESSION_STORAGE_KEY: open_id_connect_redirect_uri = 'open_id_connect_redirect_uri'

constSTATE_SESSION_STORAGE_KEY

STATE_SESSION_STORAGE_KEY: open_id_connect_client_state = 'open_id_connect_client_state'

constTWINFINITY_SESSION_APPLICATION_STATE_KEY

TWINFINITY_SESSION_APPLICATION_STATE_KEY: twinfinity_session_application_state = 'twinfinity_session_application_state'

constTWINFINITY_SESSION_REDIRECT_URI_KEY

TWINFINITY_SESSION_REDIRECT_URI_KEY: twinfinity_session_redirect_uri = 'twinfinity_session_redirect_uri'
Page Options