@dloizides/auth-client 1.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,181 @@
 # Changelog
 
+## 2.1.0 (2026-05-17)
+
+Additive release. Lays the groundwork for the "shrink identity service"
+migration by extracting the OIDC primitives that three apps (BaseClient,
+`apps/erevna-web`, `apps/katalogos-web`) had each duplicated in their own
+`useKeycloakExchange.ts` files. No breaking changes — v2.0 callers continue
+to work unchanged.
+
+### Added
+
+#### New `/oidc` sub-path entry
+
+- `@dloizides/auth-client/oidc` — Pure OIDC primitives (no React, no hooks).
+  Lets non-React consumers tree-shake the `AuthClient` class away entirely.
+
+#### OIDC primitives (also re-exported from the main entry)
+
+- `fetchDiscoveryDocument({ issuerUrl, http })` — Fetches
+  `{issuer}/.well-known/openid-configuration` and caches the result per
+  issuer URL for the lifetime of the process. Throws on non-2xx or invalid
+  metadata. Cache cleared with `clearDiscoveryCache()` (test-only).
+- `generateCodeVerifier(length?)` — RFC 7636-compliant PKCE verifier
+  generator. Defaults to 64 chars; enforces the 43..128 band.
+- `deriveCodeChallenge(verifier)` — `BASE64URL(SHA256(verifier))` via
+  `crypto.subtle` (browser + Node 16+). Matches the RFC 7636 Appendix B
+  test vector.
+- `generatePkcePair(length?)` — Convenience: fresh verifier + matching S256
+  challenge in one call.
+- `exchangeAuthorizationCode({ http, baseUrl, realm, clientId, code,
+  redirectUri, codeVerifier })` — POSTs `grant_type=authorization_code` to
+  the realm's token endpoint. Returns a normalised `TokenResponse`.
+- `refreshAccessToken({ http, baseUrl, realm, clientId, refreshToken })` —
+  POSTs `grant_type=refresh_token`. Same return shape.
+
+#### `AuthClient` v2.1 surface
+
+- `useDirectKcAuth?: boolean` config flag. Default `false`. When `true`,
+  apps can route their PKCE flow through the shared `exchangeAuthorizationCode`
+  primitive instead of the proxied identity-api `/auth/login` flow. The
+  flag is read-only at runtime via `AuthClient.isDirectMode()` so apps can
+  render conditionally on whether they've opted in.
+- `acceptDirectKcTokens(response)` — Persists a `TokenResponse` produced by
+  the direct-KC flow into the configured storage, marks the inactivity
+  tracker active, and fires `onTokenAcquired`. Use this from the app's
+  `useKeycloakExchange.ts` hook after `exchangeAuthorizationCode()` resolves.
+- `acceptDirectKcRefresh(response)` — Same as above but fires
+  `onTokenRefreshed` instead. Use after `refreshAccessToken()` swaps.
+- `onTokenAcquired?: (tokens) => void` collaborator — fires after any login
+  path (OTP, password, direct-KC) successfully persists a fresh token
+  bundle. For app-side analytics/logging only — NOT designed for BFF
+  integration (Phase 2 designs that fresh).
+- `onTokenRefreshed?: (tokens) => void` collaborator — fires after any
+  refresh (interceptor or direct-KC) persists a fresh bundle.
+
+### Notes
+
+- The `useDirectKcAuth` flag is the dormant-path flip mechanism. After v2.1
+  ships, apps still default to the proxied path. Per-app cutover (flipping
+  the flag to `true`) happens in subsequent steps of the
+  shrink-identity-to-tenant-service migration.
+- The proxied `/auth/login`, `/auth/refresh`, `/auth/refresh-cookie` methods
+  on `AuthApiClient` are unchanged — production apps still call them.
+
+## 2.0.0 (2026-05-07)
+
+Major release. Extends the realm-aware OIDC core into a single source of truth for every auth surface in the dloizides.com portfolio: web cookies, mobile secure storage, biometric gating, silent token refresh with single-flight, inactivity enforcement, password reset, and sessions management.
+
+### Added
+
+#### New entry points
+
+- `@dloizides/auth-client/react` — React Query hooks. Imported separately so non-React consumers (or pure-utility usage) don't load `react` / `@tanstack/react-query`.
+
+#### Storage adapters
+
+- `CookieTokenStorage` — web adapter that pairs an in-memory access token with a backend-managed `__Host-refresh` httpOnly cookie. The adapter intentionally does NOT persist refresh material into JS-readable storage; refresh swaps go via `/auth/refresh-cookie` with `credentials: 'include'`.
+- `SecureStoreTokenStorage` — mobile adapter for `expo-secure-store`. Splits tokens across four slots (`auth.access`, `auth.refresh`, `auth.id`, `auth.expiresAt`) so the OS can apply different ACLs per slot. Optional `requireAuthentication` triggers OS biometric prompts on read. Optional `biometricGate` adds an in-process biometric check before reads.
+
+#### Biometric
+
+- `BiometricGate` — wraps `expo-local-authentication`. Provides `isAvailable`, `prompt`, `setEnabled`, `unlock`, `hydrate`. Opt-in by default. After 3 consecutive `unlock()` failures, throws `locked out` so consumers force a re-login.
+
+#### Refresh / inactivity
+
+- `RefreshInterceptor` — single-flight refresh queue with pluggable `RefreshFn`. Concurrent 401s join the same in-flight refresh; on failure the storage clears and `sessionExpired` fires once. Decoupled from transport — works for both `/auth/refresh` (mobile) and `/auth/refresh-cookie` (web).
+- `InactivityTracker` — persists `lastRefreshedAt` via a pluggable `InactivityStore` and decides whether the session has aged past `maxInactivityDays` (default 90).
+
+#### Events
+
+- `AuthEventEmitter` — tiny zero-dependency event emitter with `sessionExpired` event. Subscriptions return an unsubscribe function. Snapshot dispatch so listeners may unsubscribe mid-emit.
+
+#### HTTP transport
+
+- `HttpClient` interface + `createFetchHttpClient(fetch)` factory. Lets the auth API client work with native fetch, axios, ky, or any caller-supplied transport.
+
+#### API client
+
+- `AuthApiClient` — typed wrapper for `IdentityService` auth endpoints: `loginWithOtp`, `loginWithPassword`, `refreshCookie`, `logout`, `forgotPassword`, `resetPassword`, `listSessions`, `revokeSession`. Supports optional Bearer auth and cookie credentials.
+
+#### `AuthClient` collaborators
+
+- `AuthClient` constructor accepts an optional `AuthClientCollaborators` bag: `{ api, interceptor, inactivityTracker, events }`. v1 callers continue to work — collaborators are all optional.
+- New methods on `AuthClient`: `init()`, `refresh()`, `loginWithOtp()`, `loginWithPassword()`, `logout({ everywhere })`, `requestPasswordReset()`, `confirmPasswordReset()`, `on('sessionExpired', listener)`.
+- `buildAuthorizationUrl({ offlineAccess: true })` appends `offline_access` to scope (idempotent if already present).
+
+#### React Query hooks (under `@dloizides/auth-client/react`)
+
+- `useForgotPassword({ api })` — POST `/auth/forgot-password`.
+- `useResetPassword({ api })` — POST `/auth/reset-password`.
+- `useSessions({ api })` — GET `/me/sessions` with exported `SESSIONS_QUERY_KEY` for invalidation.
+- `useRevokeSession({ api })` — POST `/me/sessions/{id}/revoke`. Auto-invalidates the sessions query.
+- `useLogoutEverywhere({ client })` — calls `AuthClient.logout({ everywhere: true })` and invalidates the sessions query.
+
+### Peer dependencies
+
+- `react` (`>=17.0.0`) — optional, only needed when importing from `@dloizides/auth-client/react`.
+- `@tanstack/react-query` (`^5.0.0`) — optional, same as react.
+- `expo-secure-store` — optional, only needed by `SecureStoreTokenStorage` consumers (i.e. mobile). Web bundles never load it.
+- `expo-local-authentication` — optional, only needed by `BiometricGate` consumers.
+
+### Migration from v1.x
+
+The v1 API is fully preserved. To upgrade in a no-op way:
+
+```ts
+// v1 — still works in v2
+const auth = new AuthClient(config, storage);
+```
+
+To opt into v2 features, pass collaborators:
+
+```ts
+import {
+  AuthClient,
+  AuthApiClient,
+  RefreshInterceptor,
+  InactivityTracker,
+  AuthEventEmitter,
+  CookieTokenStorage,        // web
+  createFetchHttpClient,
+} from '@dloizides/auth-client';
+
+const events = new AuthEventEmitter();
+const storage = new CookieTokenStorage();
+const http = createFetchHttpClient(fetch);
+const api = new AuthApiClient({ http, baseUrl: 'https://api.dloizides.com', useCredentials: true });
+const interceptor = new RefreshInterceptor({
+  storage,
+  events,
+  refresh: async () => {
+    const raw = await api.refreshCookie();
+    if (typeof raw.access_token !== 'string') return null;
+    // …convert to AuthTokens
+  },
+});
+const inactivityTracker = new InactivityTracker({
+  store: yourPlatformInactivityStore,
+  maxInactivityDays: 90,
+});
+
+const auth = new AuthClient(config, storage, { api, interceptor, inactivityTracker, events });
+
+events.on('sessionExpired', () => navigate('/login'));
+const { hasSession } = await auth.init();
+```
+
+Hooks live in the React entry point:
+
+```ts
+import { useSessions, useRevokeSession } from '@dloizides/auth-client/react';
+```
+
+### Coverage
+
+100% statements / branches / functions / lines (290 tests).
+
 ## 1.0.0 (2026-05-01)
 
 Initial production release. Extracts realm-aware auth helpers from `BaseClient/src/auth/`.

package/README.md

@@ -1,10 +1,12 @@
 # @dloizides/auth-client
 
-Realm-aware Keycloak / OIDC helpers for the dloizides.com portfolio. Takes `realm` and `clientId` as config — never hardcodes them — so the same package serves every product (Questioner, OnlineMenu, future apps) with its own Keycloak realm.
+Realm-aware Keycloak / OIDC client for the dloizides.com portfolio. v2 extends the v1 PKCE / token-storage core with platform-specific adapters (cookie web, secure-store mobile, biometric gate), silent token refresh with single-flight, inactivity enforcement, password reset, and React Query hooks for sessions management.
 
-## Why
+## Why one package across four products
 
-Phase 2 of the Questioner ⇄ OnlineMenu product split puts each product on its own Keycloak realm. A Questioner-realm token must never be accepted by the OnlineMenu service, and vice versa. This package centralises every realm-aware concern (URL derivation, PKCE flow building blocks, token persistence, JWT decoding, user normalisation) so each app instance is wired to exactly one realm via constructor config.
+Phase 2 of the Questioner ⇄ OnlineMenu split puts each product on its own Keycloak realm. A Questioner-realm token must never be accepted by the OnlineMenu service, and vice versa. The v1 surface centralised every realm-aware concern (URL derivation, PKCE building blocks, token persistence, JWT decoding, user normalisation) so each app instance is wired to exactly one realm via constructor config.
+
+v2 widens that to **all** auth machinery: persistent sessions, refresh, biometric gating, sessions list/revoke, password reset, login orchestration. Same library, configured per-platform via adapters. Adding a fifth product or a new mobile app means picking the right adapter and going.
 
 ## Install
 
@@ -12,81 +14,175 @@ Phase 2 of the Questioner ⇄ OnlineMenu product split puts each product on its
 npm install @dloizides/auth-client
 ```
 
-## Quick start
+Optional peer dependencies:
+
+| Peer | Required when |
+|------|---------------|
+| `react` (`>=17`) | Importing from `@dloizides/auth-client/react` |
+| `@tanstack/react-query` (`^5`) | Importing from `@dloizides/auth-client/react` |
+| `expo-secure-store` | Using `SecureStoreTokenStorage` (mobile only) |
+| `expo-local-authentication` | Using `BiometricGate` (mobile only) |
+
+Web bundles never pull in `expo-*` packages — those modules import via injected adapter interfaces, not direct module references.
+
+## Quick start (web, cookie auth)
 
 ```ts
 import {
   AuthClient,
-  BrowserStorageTokenStorage,
-  normalizeKeycloakUser,
+  AuthApiClient,
+  RefreshInterceptor,
+  InactivityTracker,
+  AuthEventEmitter,
+  CookieTokenStorage,
+  createFetchHttpClient,
+  tokenResponseToAuthTokens,
+  normalizeTokenResponse,
 } from '@dloizides/auth-client';
 
-const storage = new BrowserStorageTokenStorage({ storage: localStorage });
+const events = new AuthEventEmitter();
+const storage = new CookieTokenStorage();
+const http = createFetchHttpClient(window.fetch.bind(window));
+const api = new AuthApiClient({
+  http,
+  baseUrl: 'https://api.dloizides.com',
+  useCredentials: true,                 // sends the __Host-refresh cookie
+  getAccessToken: () => storage.read().then((t) => t?.accessToken ?? null),
+});
+
+const interceptor = new RefreshInterceptor({
+  storage,
+  events,
+  refresh: async () => {
+    const raw = await api.refreshCookie();
+    if (typeof raw.access_token !== 'string' || raw.access_token === '') return null;
+    return tokenResponseToAuthTokens(normalizeTokenResponse({ ...raw, access_token: raw.access_token }));
+  },
+  onRefreshSuccess: () => inactivity.markActive(),
+});
+
+const inactivity = new InactivityTracker({ store: yourInactivityStore });
 
 const auth = new AuthClient(
   {
     baseUrl: 'https://identity.dloizides.com',
-    realm: 'OnlineMenu',         // product-specific
+    realm: 'OnlineMenu',
     clientId: 'online-menu-client',
     redirectUri: 'http://localhost:8082',
     scope: 'openid profile email offline_access',
   },
   storage,
+  { api, interceptor, inactivityTracker: inactivity, events },
 );
 
-// Derived URLs (always realm-aware):
-auth.issuerUrl;              // https://identity.dloizides.com/realms/OnlineMenu
-auth.tokenEndpoint;          // .../realms/OnlineMenu/protocol/openid-connect/token
-auth.userInfoEndpoint;       // .../realms/OnlineMenu/protocol/openid-connect/userinfo
-auth.buildAuthorizationUrl({ state: 'xyz', codeChallenge: 'abc' });
+events.on('sessionExpired', () => navigate('/login'));
+const { hasSession } = await auth.init();
 ```
 
-### Migrating from a legacy issuer URL
-
-If your app currently stores only an issuer URL like `https://identity.dloizides.com/realms/OnlineMenu`, derive the realm and base URL automatically:
+## Quick start (mobile, secure-store)
 
 ```ts
-const auth = AuthClient.fromIssuerUrl(
-  {
-    issuerUrl: process.env.KEYCLOAK_ISSUER!,
-    clientId: 'online-menu-client',
+import * as SecureStore from 'expo-secure-store';
+import * as LocalAuthentication from 'expo-local-authentication';
+import {
+  AuthClient,
+  AuthApiClient,
+  BiometricGate,
+  InactivityTracker,
+  RefreshInterceptor,
+  SecureStoreTokenStorage,
+  AuthEventEmitter,
+  createFetchHttpClient,
+} from '@dloizides/auth-client';
+
+const events = new AuthEventEmitter();
+
+const biometricGate = new BiometricGate({
+  localAuth: {
+    hasHardwareAsync: LocalAuthentication.hasHardwareAsync,
+    isEnrolledAsync: LocalAuthentication.isEnrolledAsync,
+    authenticateAsync: (opts) => LocalAuthentication.authenticateAsync(opts),
   },
-  storage,
-);
+  flagStore: yourBiometricFlagStore, // optional persistence for the user's opt-in
+});
+
+const storage = new SecureStoreTokenStorage({
+  secureStore: {
+    getItemAsync: SecureStore.getItemAsync,
+    setItemAsync: SecureStore.setItemAsync,
+    deleteItemAsync: SecureStore.deleteItemAsync,
+  },
+  requireAuthentication: true,
+  biometricGate,
+});
+
+await biometricGate.hydrate();
 ```
 
-## What's in the box
+## React Query hooks
+
+```ts
+import { useSessions, useRevokeSession, useLogoutEverywhere, useForgotPassword, useResetPassword } from '@dloizides/auth-client/react';
+
+const { data: sessions, isLoading } = useSessions({ api });
+const revoke = useRevokeSession({ api });
+const logoutEverywhere = useLogoutEverywhere({ client: auth });
+const forgot = useForgotPassword({ api });
+const reset = useResetPassword({ api });
+
+// In your component
+revoke.mutate(sessionId);
+logoutEverywhere.mutate();
+forgot.mutate({ email });
+reset.mutate({ token, newPassword });
+```
+
+## Lifecycle events
 
-### Class
+`AuthEventEmitter` exposes a `sessionExpired` event:
 
-- `AuthClient` — realm-aware container for config + storage. Exposes `issuerUrl`, `authorizationEndpoint`, `tokenEndpoint`, `userInfoEndpoint`, `logoutEndpoint`, `buildAuthorizationUrl()`, `getAccessToken()`, `getTokens()` / `setTokens()` / `clearTokens()`.
+```ts
+auth.on('sessionExpired', () => {
+  navigate('/login');
+});
+```
 
-### Token storage adapters
+`sessionExpired` fires when:
+
+- The inactivity tracker reports the session has aged past `maxInactivityDays` (during `auth.init()`).
+- A refresh attempt fails (`RefreshInterceptor` clears storage and emits the event exactly once per attempt, even when joined by N concurrent waiters).
+
+## What's in the box
 
-- `InMemoryTokenStorage` — for tests and SSR.
-- `BrowserStorageTokenStorage` — wraps any `Storage`-shaped backend (`localStorage`, `sessionStorage`, AsyncStorage shim).
+### Core (`@dloizides/auth-client`)
 
-Bring your own implementation by satisfying the `TokenStorage` interface (`read` / `write` / `clear`).
+- `AuthClient` — realm-aware orchestrator. `init()`, `refresh()`, `loginWithOtp()`, `loginWithPassword()`, `logout({ everywhere })`, `requestPasswordReset()`, `confirmPasswordReset()`, plus the v1 surface (`getAccessToken`, `getTokens`, `setTokens`, `clearTokens`, `buildAuthorizationUrl`, etc.).
+- `AuthApiClient` — typed wrapper for IdentityService auth endpoints.
+- `AuthEventEmitter` — `sessionExpired` event.
+- `RefreshInterceptor` — single-flight refresh queue.
+- `InactivityTracker` — 90-day default timeout (configurable).
+- Storage adapters: `InMemoryTokenStorage`, `BrowserStorageTokenStorage`, `CookieTokenStorage`, `SecureStoreTokenStorage`.
+- `BiometricGate` — wraps `expo-local-authentication`. 3-strikes lockout default.
+- `createFetchHttpClient(fetch)` — `HttpClient` factory.
+- All v1 pure helpers (URL builders, token body builders, JWT decoder, user normaliser).
 
-### Pure helpers (zero-dependency, fully tested)
+### React (`@dloizides/auth-client/react`)
 
-- `parseRealmFromIssuer(url)` / `parseBaseUrlFromIssuer(url)` — split a Keycloak issuer URL.
-- `buildIssuerUrl`, `buildAuthorizationEndpoint`, `buildTokenEndpoint`, `buildUserInfoEndpoint`, `buildLogoutEndpoint`, `buildAuthorizationUrl` — realm-aware URL builders.
-- `buildAuthorizationCodeBody`, `buildRefreshTokenBody` — `application/x-www-form-urlencoded` body helpers for the token endpoint.
-- `extractAuthCode(response)` — pull the `code` out of an `expo-auth-session` (or browser) redirect response.
-- `normalizeTokenResponse(raw)` / `tokenResponseToAuthTokens(response)` — snake_case → camelCase + absolute `expiresAt` computation.
-- `isTokenExpired(tokens, leewayMs?, now?)` / `computeExpiresAt(expiresIn, now?)` — clock-aware expiry checks with default 30 s leeway.
-- `decodeJwt<T>(token)` — base64url-decode the payload of a compact JWT (no signature verification — UI only).
-- `normalizeKeycloakUser(userInfo)` — collapse Keycloak `realm_access` + `resource_access` roles into a deduplicated `roles[]` array, pick a sensible `displayName` / `username`.
+- `useForgotPassword`, `useResetPassword` — mutation hooks.
+- `useSessions` — query hook with exported `SESSIONS_QUERY_KEY`.
+- `useRevokeSession`, `useLogoutEverywhere` — mutation hooks that auto-invalidate the sessions query.
 
-### Types
+## Architecture decisions baked in
 
-- `AuthClientConfig`, `AuthTokens`, `TokenStorage`, `RawTokenResponse`, `TokenResponse`
-- `KeycloakUserInfo`, `NormalizedUser`, `KeycloakRoles` (`const enum` + `isKeycloakRole` guard)
+1. **Biometric is opt-in** via `BiometricGate.setEnabled(true)`. Default off so a fresh install doesn't gate the user behind a hardware prompt.
+2. **Inactivity timeout default 90 days** (configurable). Mobile tasks chose this number; web matches.
+3. **Single account per device.** The package has no multi-account surface — one refresh-token slot, period.
+4. **No `react-native` import in package core.** RN-specific code lives in adapters that take injected interfaces (`SecureStoreLike`, `LocalAuthLike`). Web bundles don't pay for what they don't use.
+5. **Cookie refresh material is server-managed.** `CookieTokenStorage.write()` discards `refreshToken` from the JS heap on purpose — refresh swaps go via `/auth/refresh-cookie` with `credentials: 'include'`.
 
 ## Coverage
 
-100% statements / branches / functions / lines. Test runner: Jest with `ts-jest`.
+100% statements / branches / functions / lines (290 tests). Test runner: Jest with `ts-jest`.
 
 ## License