@dloizides/auth-client 1.0.0 → 2.1.0

package/dist/index.d.ts

@@ -1,111 +1,8 @@
-/**
- * Configuration for {@link AuthClient}.
- *
- * `realm` and `clientId` are **required** and never have sensible portfolio-wide
- * defaults. Each consumer (Questioner web, OnlineMenu web, future apps) supplies
- * its own values. This is the contract that enables the cross-realm hard wall
- * planned in Phase 2 of the product split.
- */
-interface AuthClientConfig {
-    /** Keycloak base URL, e.g. `https://identity.dloizides.com`. Trailing slash optional. */
-    baseUrl: string;
-    /** Realm name, e.g. `OnlineMenu` or `Questioner`. NEVER hardcoded. */
-    realm: string;
-    /** OAuth client id registered in the realm. */
-    clientId: string;
-    /** Where Keycloak should redirect after authorization (PKCE / authorization-code flow). */
-    redirectUri?: string;
-    /** Space-separated OAuth scopes. Defaults to `openid profile email`. */
-    scope?: string;
-}
-
-/**
- * Persisted token bundle.
- *
- * `expiresAt` is an absolute UNIX millisecond timestamp computed at
- * acquisition time (`Date.now() + expires_in * 1000`) so consumers can
- * trivially compare against `Date.now()` without re-deriving an expiry clock.
- */
-interface AuthTokens {
-    accessToken: string;
-    refreshToken?: string;
-    idToken?: string;
-    /** Absolute UNIX millis. `0` or missing means unknown — treat as expired. */
-    expiresAt: number;
-}
-
-/**
- * Pluggable token persistence.
- *
- * Consumers (web, native, server-side) provide an implementation tailored to
- * their platform: `localStorage`, `sessionStorage`, `expo-secure-store`,
- * `AsyncStorage`, or an in-memory map for tests. Keeping the interface narrow
- * (read / write / clear) keeps the package transport-agnostic.
- */
-interface TokenStorage {
-    read(): Promise<AuthTokens | null>;
-    write(tokens: AuthTokens): Promise<void>;
-    clear(): Promise<void>;
-}
-
-/**
- * Inputs to {@link AuthClient.fromIssuerUrl}.
- *
- * Used by consumers that store only an issuer URL and want to derive `realm`
- * + `baseUrl` rather than configure them separately.
- */
-interface AuthClientFromIssuerInput {
-    issuerUrl: string;
-    clientId: string;
-    redirectUri?: string;
-    scope?: string;
-}
-declare class AuthClient {
-    private readonly config;
-    private readonly tokenStorage;
-    /**
-     * @throws Error when `baseUrl`, `realm`, or `clientId` is missing or empty.
-     */
-    constructor(config: AuthClientConfig, storage: TokenStorage);
-    /**
-     * Build an {@link AuthClient} from a standalone issuer URL by parsing the
-     * realm and base URL. Useful when migrating from the legacy
-     * `KEYCLOAK_ISSUER` env var convention.
-     *
-     * @throws Error when the issuer URL doesn't match `{base}/realms/{realm}`.
-     */
-    static fromIssuerUrl(input: AuthClientFromIssuerInput, storage: TokenStorage): AuthClient;
-    private static validateConfig;
-    get realm(): string;
-    get clientId(): string;
-    get baseUrl(): string;
-    get scope(): string;
-    get redirectUri(): string | undefined;
-    /** Issuer URL: `{baseUrl}/realms/{realm}`. */
-    get issuerUrl(): string;
-    get authorizationEndpoint(): string;
-    get tokenEndpoint(): string;
-    get userInfoEndpoint(): string;
-    get logoutEndpoint(): string;
-    /**
-     * Build a fully-formed authorization URL the user agent can navigate to.
-     *
-     * @throws Error when `redirectUri` is not configured.
-     */
-    buildAuthorizationUrl(input?: {
-        state?: string;
-        codeChallenge?: string;
-        codeChallengeMethod?: 'S256' | 'plain';
-    }): string;
-    getTokens(): Promise<AuthTokens | null>;
-    setTokens(tokens: AuthTokens): Promise<void>;
-    clearTokens(): Promise<void>;
-    /**
-     * Read the current access token if it exists and is not expired.
-     * Returns `null` for "no usable token".
-     */
-    getAccessToken(now?: number): Promise<string | null>;
-}
+import { T as TokenStorage, c as AuthTokens } from './AuthClient-D95OMajD.js';
+export { A as AuthApiClient, d as AuthApiClientOptions, b as AuthClient, e as AuthClientCollaborators, f as AuthClientConfig, g as AuthClientFromIssuerInput, h as AuthEventEmitter, i as AuthEventListener, j as AuthEventName, k as AuthEventUnsubscribe, a as AuthSessionInfo, D as DirectKcOptions, F as ForgotPasswordRequest, I as InactivityStore, l as InactivityTracker, m as InactivityTrackerOptions, L as LoginOptions, n as LogoutOptions, O as OtpLoginRequest, P as PasswordLoginRequest, o as RawAuthLoginResponse, p as RefreshFn, q as RefreshInterceptor, r as RefreshInterceptorOptions, R as ResetPasswordRequest } from './AuthClient-D95OMajD.js';
+export { ExchangeAuthorizationCodeInput, FetchDiscoveryDocumentInput, OidcDiscoveryDocument, PkcePair, RefreshAccessTokenInput, clearDiscoveryCache, deriveCodeChallenge, exchangeAuthorizationCode, fetchDiscoveryDocument, generateCodeVerifier, generatePkcePair, refreshAccessToken } from './oidc/index.js';
+import { R as RawTokenResponse, T as TokenResponse } from './TokenResponse-CY1CaU2l.js';
+export { H as HttpClient, a as HttpRequest, b as HttpResponse, c as createFetchHttpClient } from './TokenResponse-CY1CaU2l.js';
 
 /**
  * Roles emitted by Keycloak realms in the dloizides.com portfolio.
@@ -171,31 +68,6 @@ interface NormalizedUser {
     raw?: KeycloakUserInfo;
 }
 
-/**
- * Raw token endpoint response (snake_case, OIDC standard).
- */
-interface RawTokenResponse {
-    access_token: string;
-    refresh_token?: string;
-    id_token?: string;
-    expires_in?: number;
-    token_type?: string;
-    scope?: string;
-    [key: string]: unknown;
-}
-/**
- * Application-friendly camelCase view of a token endpoint response.
- */
-interface TokenResponse {
-    accessToken: string;
-    refreshToken?: string;
-    idToken?: string;
-    /** Seconds until expiry, as returned by Keycloak. */
-    expiresIn?: number;
-    tokenType?: string;
-    scope?: string;
-}
-
 /**
  * Subset of `Storage` we actually use. Lets callers inject `localStorage`,
  * `sessionStorage`, or any compatible polyfill.
@@ -242,6 +114,207 @@ declare class InMemoryTokenStorage implements TokenStorage {
     clear(): Promise<void>;
 }
 
+/**
+ * Web token storage that pairs an in-memory access token with a backend-managed
+ * httpOnly + Secure + SameSite=Lax refresh-token cookie.
+ *
+ * The browser handles the refresh cookie (`__Host-refresh` by default — set by
+ * the IdentityService on login and rotated on every `/auth/refresh-cookie`
+ * call). JavaScript MUST NOT have access to it, so this adapter intentionally
+ * does NOT persist `refreshToken` into the cookie itself; that's the backend's
+ * job. The adapter just keeps the access token in memory and exposes the same
+ * `TokenStorage` interface as `BrowserStorageTokenStorage` so the rest of the
+ * library doesn't need to know which transport is in use.
+ *
+ * Page reloads drop the access token (memory clears), but the refresh cookie
+ * survives — `RefreshInterceptor` swaps it for a new access token via
+ * `/auth/refresh-cookie` with `credentials: 'include'`.
+ */
+declare class CookieTokenStorage implements TokenStorage {
+    private accessToken;
+    private idToken;
+    private expiresAt;
+    read(): Promise<AuthTokens | null>;
+    write(tokens: AuthTokens): Promise<void>;
+    clear(): Promise<void>;
+}
+
+/**
+ * Subset of `expo-secure-store` we use, abstracted so the package itself never
+ * imports `expo-secure-store` (and so web bundles never pull it in).
+ *
+ * Mobile consumers wire this up at the edge:
+ *
+ * ```ts
+ * import * as SecureStore from 'expo-secure-store';
+ * const adapter: SecureStoreLike = {
+ *   getItemAsync: SecureStore.getItemAsync,
+ *   setItemAsync: SecureStore.setItemAsync,
+ *   deleteItemAsync: SecureStore.deleteItemAsync,
+ * };
+ * ```
+ */
+interface SecureStoreLike {
+    getItemAsync(key: string, options?: {
+        requireAuthentication?: boolean;
+    }): Promise<string | null>;
+    setItemAsync(key: string, value: string, options?: {
+        requireAuthentication?: boolean;
+    }): Promise<void>;
+    deleteItemAsync(key: string, options?: {
+        requireAuthentication?: boolean;
+    }): Promise<void>;
+}
+/**
+ * Optional biometric gate. When provided AND `requireBiometric` is `true`, the
+ * gate's `unlock()` is called before reading the refresh token. Used by mobile
+ * consumers that opt in to biometric-protected sessions.
+ */
+interface BiometricGateLike {
+    unlock(): Promise<void>;
+    isEnabled(): boolean;
+}
+interface SecureStoreTokenStorageOptions {
+    secureStore: SecureStoreLike;
+    /** Defaults applied to every key — usually `'auth'`. */
+    keyPrefix?: string;
+    /**
+     * When true, secure-store reads use `requireAuthentication: true`, prompting
+     * the OS biometric / device-passcode dialog (iOS Keychain access control,
+     * Android Keystore strongbox).
+     */
+    requireAuthentication?: boolean;
+    /**
+     * Optional biometric gate run BEFORE the secure-store read. Belt-and-braces
+     * with `requireAuthentication`: the gate enforces our own retry/lockout
+     * semantics, while `requireAuthentication` enforces the OS keychain ACL.
+     */
+    biometricGate?: BiometricGateLike;
+}
+/**
+ * Persist tokens in iOS Keychain / Android Keystore via `expo-secure-store`.
+ *
+ * Keys are split (access / refresh / id / expiresAt) rather than stored as a
+ * single JSON blob so the OS-level ACL on the refresh token slot can be
+ * tightened independently. With `requireAuthentication: true`, reads of any
+ * key trigger the OS biometric prompt — that's why we keep it OFF for writes
+ * (login flows must not prompt) and ON for reads (boot-time session restore).
+ *
+ * Storage key shape: `{prefix}.{slot}` (e.g. `auth.refresh`).
+ */
+declare class SecureStoreTokenStorage implements TokenStorage {
+    private readonly secureStore;
+    private readonly prefix;
+    private readonly requireAuthentication;
+    private readonly biometricGate;
+    constructor(options: SecureStoreTokenStorageOptions);
+    read(): Promise<AuthTokens | null>;
+    write(tokens: AuthTokens): Promise<void>;
+    clear(): Promise<void>;
+    private shouldRunBiometricGate;
+    private fullKey;
+}
+
+/**
+ * Subset of `expo-local-authentication` we use, abstracted so the package
+ * itself never imports `expo-local-authentication`.
+ *
+ * Mobile consumers wire this up at the edge:
+ *
+ * ```ts
+ * import * as LocalAuthentication from 'expo-local-authentication';
+ * const adapter: LocalAuthLike = {
+ *   hasHardwareAsync: LocalAuthentication.hasHardwareAsync,
+ *   isEnrolledAsync: LocalAuthentication.isEnrolledAsync,
+ *   authenticateAsync: (opts) => LocalAuthentication.authenticateAsync(opts),
+ * };
+ * ```
+ */
+interface LocalAuthLike {
+    hasHardwareAsync(): Promise<boolean>;
+    isEnrolledAsync(): Promise<boolean>;
+    authenticateAsync(options?: {
+        promptMessage?: string;
+        cancelLabel?: string;
+        disableDeviceFallback?: boolean;
+    }): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+}
+/**
+ * Optional persistence so the "enabled" flag survives app restart. Backed by
+ * any `TokenStorage`-shaped key/value store via the calling consumer (or the
+ * app's settings store). We keep it pluggable to avoid coupling
+ * `BiometricGate` to a specific storage adapter.
+ */
+interface BiometricFlagStore {
+    read(): Promise<boolean>;
+    write(enabled: boolean): Promise<void>;
+}
+interface BiometricGateOptions {
+    localAuth: LocalAuthLike;
+    /** Optional persistence for the user's opt-in choice. */
+    flagStore?: BiometricFlagStore;
+    /** Default prompt message; consumers usually override. */
+    promptMessage?: string;
+    /** Max consecutive prompt failures before {@link unlock} throws. Default 3. */
+    maxFailures?: number;
+}
+/**
+ * Biometric gate wrapping `expo-local-authentication`.
+ *
+ * Lifecycle:
+ *
+ * 1. `isAvailable()` — checks hardware + enrolment. Pure read.
+ * 2. `setEnabled(true|false)` — consumer's settings UI flips this. Persisted
+ *    via the optional flag store. Default = disabled (opt-in).
+ * 3. `unlock()` — called by `SecureStoreTokenStorage` (when wired) or by
+ *    consumer code before sensitive operations. Counts consecutive failures;
+ *    after `maxFailures` (default 3), throws `BiometricLockedOutError` and
+ *    consumers MUST navigate to login.
+ * 4. `prompt()` — one-shot biometric prompt that doesn't change the failure
+ *    counter. Useful for re-confirming an action mid-session.
+ *
+ * The failure counter resets on success.
+ */
+declare class BiometricGate {
+    private readonly localAuth;
+    private readonly flagStore;
+    private readonly promptMessage;
+    private readonly maxFailures;
+    private enabled;
+    private failureCount;
+    private hydrated;
+    constructor(options: BiometricGateOptions);
+    /** Hardware present AND a fingerprint/face ID is enrolled. */
+    isAvailable(): Promise<boolean>;
+    /** Synchronous read of the current enabled flag (post-hydration). */
+    isEnabled(): boolean;
+    /** Read the persisted opt-in flag once at app boot. Idempotent. */
+    hydrate(): Promise<void>;
+    /**
+     * Toggle biometric requirement. Persists via {@link BiometricFlagStore} when
+     * configured. Resets the failure counter so a re-enable starts fresh.
+     */
+    setEnabled(enabled: boolean): Promise<void>;
+    /** Reset the failure counter. Tests + consumer recovery flows. */
+    resetFailures(): void;
+    /**
+     * One-shot biometric prompt. Returns `true` on success. Does NOT throw on
+     * failure or update the failure counter — useful for action confirmation.
+     */
+    prompt(): Promise<boolean>;
+    /**
+     * Required pre-condition for sensitive token reads. No-op when disabled.
+     *
+     * @throws Error after {@link maxFailures} consecutive failures.
+     * @throws Error on a single failure (lower in the count, but still throws so
+     *   `SecureStoreTokenStorage.read()` short-circuits).
+     */
+    unlock(): Promise<void>;
+}
+
 /**
  * Convert a Keycloak `/userinfo` payload into a flat, app-friendly user object.
  *
@@ -415,4 +488,4 @@ declare function normalizeTokenResponse(raw: RawTokenResponse): TokenResponse;
  */
 declare function tokenResponseToAuthTokens(response: TokenResponse, now?: number): AuthTokens;
 
-export { AuthClient, type AuthClientConfig, type AuthClientFromIssuerInput, type AuthTokens, type AuthorizationCodeBodyInput, type AuthorizationResponseLike, type AuthorizationUrlInput, BrowserStorageTokenStorage, type BrowserStorageTokenStorageOptions, InMemoryTokenStorage, KeycloakRoles, type KeycloakUserInfo, type NormalizedUser, type RawTokenResponse, type RefreshTokenBodyInput, type StorageLike, type TokenResponse, type TokenStorage, buildAuthorizationCodeBody, buildAuthorizationEndpoint, buildAuthorizationUrl, buildIssuerUrl, buildLogoutEndpoint, buildRefreshTokenBody, buildTokenEndpoint, buildUserInfoEndpoint, computeExpiresAt, decodeJwt, extractAuthCode, isKeycloakRole, isTokenExpired, normalizeKeycloakUser, normalizeTokenResponse, parseBaseUrlFromIssuer, parseRealmFromIssuer, tokenResponseToAuthTokens };
+export { AuthTokens, type AuthorizationCodeBodyInput, type AuthorizationResponseLike, type AuthorizationUrlInput, type BiometricFlagStore, BiometricGate, type BiometricGateLike, type BiometricGateOptions, BrowserStorageTokenStorage, type BrowserStorageTokenStorageOptions, CookieTokenStorage, InMemoryTokenStorage, KeycloakRoles, type KeycloakUserInfo, type LocalAuthLike, type NormalizedUser, RawTokenResponse, type RefreshTokenBodyInput, type SecureStoreLike, SecureStoreTokenStorage, type SecureStoreTokenStorageOptions, type StorageLike, TokenResponse, TokenStorage, buildAuthorizationCodeBody, buildAuthorizationEndpoint, buildAuthorizationUrl, buildIssuerUrl, buildLogoutEndpoint, buildRefreshTokenBody, buildTokenEndpoint, buildUserInfoEndpoint, computeExpiresAt, decodeJwt, extractAuthCode, isKeycloakRole, isTokenExpired, normalizeKeycloakUser, normalizeTokenResponse, parseBaseUrlFromIssuer, parseRealmFromIssuer, tokenResponseToAuthTokens };