# @oshun/auth-client

Client-side auth/session library for OSHUN mobile and web surfaces.

The canonical customer auth/session contract now lives in
`src/customer-auth-model.ts` and `src/types.ts`.

## Includes

- Canonical customer auth/session model for one OSHUN customer identity across
  Tara, Veritas, Nyx, Arete, Nisaba, and Metis
- Surface-specific policy publication for web, installable PWA, and mobile
  transport/storage boundaries
- Typed `AuthClient` with login/logout/refresh/current-user helpers
- Email/password and social-provider sign-in support
- Proactive/expired token refresh handling with single-flight refresh protection
- Pluggable `AuthTransport` abstraction
- `FetchAuthTransport` implementation for shared HTTP auth calls
- Pluggable `SessionStore` abstraction with in-memory and key-value
  implementations
- Secure-session persistence helpers (`SecureSessionStore`, browser storage
  adapter, Expo secure-storage adapter) with token/profile/session-metadata
  policy checks (expiry windows, payload limits, fail-closed reads)
- `OshunSsoCoordinator` for single sign-on state shared across Tara, Veritas,
  Nyx, Arete, and Nisaba
- Sync adapters for SSO propagation (`createInMemorySsoSyncAdapter`,
  `createBroadcastChannelSsoSyncAdapter`)
- Shared `OshunProfileStore` for profile identity/stats/domain-state across
  mobile and web
- Shared `OshunPreferencesStore` for theme/language/notification preferences
  across mobile and web
- Shared `OshunPrivacyStore` for privacy settings, consent controls, and consent
  ledger snapshots
- Shared `OshunDataRightsStore` for account data export/deletion request UX
  state across mobile and web
- Shared `OshunBillingStore` for billing status, invoice history, and payment
  recovery flows across mobile and web
- Shared entitlement schema and evaluators for tier/domain/feature access
  (`entitlements.ts`)
- Shared profile-to-entitlements mapping + denial copy helpers for shell
  middleware gates (`entitlement-context.ts`)
- Shared subscription catalog + plan upgrade recommendation helpers for purchase
  entry points (`subscription-offers.ts`)
- Transport security policy controls for HTTPS enforcement, host allowlists, and
  certificate pinning strategy hooks (`transport-security.ts`)
- Session management APIs for device revocation (`listSessions`,
  `revokeSession`, `revokeAllSessions`, `signOutAll`)
- Session expiry validation and typed auth errors

## Canonical Surface Rules

- `web`: same-origin BFF session with `HttpOnly` refresh/session cookie; access
  token is treated as memory-only runtime state
- `pwa`: identical auth/session contract to web because the installable PWA is
  the same browser-origin runtime
- `mobile`: bearer access token plus rotating refresh token backed by secure
  device storage; no plain AsyncStorage session persistence

## Nx Targets

- `pnpm nx run @oshun/auth-client:build`
- `pnpm nx run @oshun/auth-client:lint`
- `pnpm nx run @oshun/auth-client:typecheck`
- `pnpm nx run @oshun/auth-client:test`