@mastergnou/auth-web

Shared browser-side auth helpers for Mount-family web products.

Current surface:

• canonical BrowserStorageLike abstraction for browser persistence
• generic auth request-header builder with optional tenant-header emission
• headless logout flow orchestration
• headless password-login flow orchestration
• session-provider storage helpers
• token and tenant persistence helpers
• SSO login URL construction
• SSO callback request mapping helper for backend transport DTOs
• headless SSO callback completion flow orchestration
• safe auth redirect normalization for relative or same-origin destinations
• SSO callback query parsing and redirect resolution
• logout redirect decision helpers

Import guidance:

• browser apps should prefer focused subpath imports so bundlers can keep chunks small
• use @mastergnou/auth-web/logout for logout helpers such as performLogoutFlow()
• use @mastergnou/auth-web/sso for SSO callback/login helpers
• use @mastergnou/auth-web/storage for session and token storage helpers
• use @mastergnou/auth-web/http for request-header helpers
• the root @mastergnou/auth-web export remains available for compatibility, but it intentionally exposes the whole browser-auth surface

Redirect safety note:

• resolveAuthRedirectUrl() rejects absolute URLs unless the consumer provides appOrigin
• resolveSsoCallbackDestination() only applies same-origin reduction when appOrigin is passed explicitly

Request header note:

• buildAuthRequestHeaders() always adds Authorization when an access token exists
• tenant headers are only emitted when the caller provides tenantHeaderName

Failure handling note:

• performPasswordLoginFlow() and completeSsoCallbackFlow() preserve existing shared auth state by default if the executor fails
• callers can opt into clearing shared auth state on failure with clearExistingAuthOnFailure
• performPasswordLoginFlow() can optionally run a consumer-provided post-login completion callback after shared auth persistence
• completeSsoCallbackFlow() also lets consumers override validation-stage error copy without replacing callback parsing/persistence logic
• performLogoutFlow() accepts an explicit provider; when omitted, it falls back to provider metadata in optional storage, and when neither exists it performs local-only logout
• performLogoutFlow() treats federated logout initiation failures as non-fatal, clears shared local auth state anyway, and can report the raw failure back through onFederatedLogoutFailure
• performLogoutFlow() supports async clearLocalAuthState() so consumers can revoke cookie-backed sessions or finish product-local cleanup before redirecting; cleanup failures propagate to the caller
• clearAdditionalState() remains as a deprecated alias for clearLocalAuthState() for older storage-based consumers

SSO callback transport note:

• completeSsoCallbackFlow() works with code because it starts from browser callback query params
• backend transport DTOs use assertion, so buildSsoCallbackRequest() maps code -> assertion explicitly

Non-goals in this package:

• branded page components
• direct HTTP client wiring
• product route definitions
• profile-fetching or React app wiring