@dloizides/auth-client 1.0.0 → 2.1.0

package/dist/AuthClient-BGr8L03W.d.mts

@@ -0,0 +1,460 @@
+import { H as HttpClient, T as TokenResponse } from './TokenResponse-CY1CaU2l.mjs';
+
+/**
+ * Tiny dependency-free event emitter for auth lifecycle events.
+ *
+ * Consumers subscribe to `onSessionExpired` to navigate to the login screen
+ * when refresh fails or the inactivity timeout fires. We don't reach for
+ * `EventTarget`/`EventEmitter` because we want one consistent API across web,
+ * React Native, and node test environments without polyfills.
+ */
+type AuthEventName = 'sessionExpired';
+type AuthEventListener = () => void;
+interface AuthEventUnsubscribe {
+    (): void;
+}
+declare class AuthEventEmitter {
+    private readonly listeners;
+    on(event: AuthEventName, listener: AuthEventListener): AuthEventUnsubscribe;
+    emit(event: AuthEventName): void;
+    /** Remove all listeners. Useful for `AuthClient.dispose()` and tests. */
+    clear(): void;
+}
+
+/**
+ * Backend session record returned by `GET /me/sessions`.
+ *
+ * Shape mirrors the existing IdentityService response — see
+ * `Services/Identity/.../GetSessions.cs`. Defined as a permissive interface
+ * so newer fields (added server-side) flow through without a package bump.
+ */
+interface AuthSessionInfo {
+    id: string;
+    isCurrent?: boolean;
+    ipAddress?: string;
+    userAgent?: string;
+    createdAt?: string;
+    lastSeenAt?: string;
+    [key: string]: unknown;
+}
+interface AuthApiClientOptions {
+    http: HttpClient;
+    /** API base, e.g. `https://api.dloizides.com`. No trailing slash needed. */
+    baseUrl: string;
+    /**
+     * Optional supplier of the current access token, used as a Bearer header on
+     * authenticated calls (sessions list, revoke, logout). When omitted those
+     * calls send no Authorization header — typical for cookie-based web auth.
+     */
+    getAccessToken?: () => Promise<string | null>;
+    /**
+     * When true, every request adds `credentials: 'include'`. Required for
+     * cookie-based web auth (`__Host-refresh` lives in an httpOnly cookie).
+     */
+    useCredentials?: boolean;
+}
+interface OtpLoginRequest {
+    email: string;
+    otp: string;
+    tenantId?: string;
+    offlineAccess?: boolean;
+}
+interface PasswordLoginRequest {
+    email: string;
+    password: string;
+    tenantId?: string;
+    offlineAccess?: boolean;
+}
+interface ForgotPasswordRequest {
+    email: string;
+    tenantId?: string;
+}
+interface ResetPasswordRequest {
+    token: string;
+    newPassword: string;
+}
+interface RawAuthLoginResponse {
+    access_token?: string;
+    refresh_token?: string;
+    id_token?: string;
+    expires_in?: number;
+    token_type?: string;
+    scope?: string;
+    [key: string]: unknown;
+}
+/**
+ * Thin HTTP client for the IdentityService auth surface.
+ *
+ * Endpoint paths match the backend task `auth-password-reset-backend.md`:
+ *
+ * - `POST /auth/verify-otp`
+ * - `POST /auth/login` (password)
+ * - `POST /auth/logout` and `POST /auth/logout?everywhere=true`
+ * - `POST /auth/refresh-cookie` (web cookie flow)
+ * - `POST /auth/forgot-password`
+ * - `POST /auth/reset-password`
+ * - `GET /me/sessions`
+ * - `POST /me/sessions/{id}/revoke`
+ *
+ * Doesn't touch token storage — that's `AuthClient`'s job. Doesn't decide
+ * what to do with errors — callers handle them. Just builds requests and
+ * deserialises responses.
+ */
+declare class AuthApiClient {
+    private readonly http;
+    private readonly baseUrl;
+    private readonly getAccessToken;
+    private readonly useCredentials;
+    constructor(options: AuthApiClientOptions);
+    loginWithOtp(request: OtpLoginRequest): Promise<RawAuthLoginResponse>;
+    loginWithPassword(request: PasswordLoginRequest): Promise<RawAuthLoginResponse>;
+    /** Web cookie-flow refresh. Sends no body; cookie travels via `credentials`. */
+    refreshCookie(): Promise<RawAuthLoginResponse>;
+    logout(everywhere?: boolean): Promise<void>;
+    forgotPassword(request: ForgotPasswordRequest): Promise<void>;
+    resetPassword(request: ResetPasswordRequest): Promise<void>;
+    listSessions(): Promise<AuthSessionInfo[]>;
+    revokeSession(sessionId: string): Promise<void>;
+    private postLogin;
+    private authHeaders;
+}
+
+/**
+ * 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>;
+}
+
+/**
+ * Pluggable persistence for the `lastRefreshedAt` timestamp.
+ *
+ * Decoupled from `TokenStorage` so consumers can pick a different backend
+ * (e.g., write through `AsyncStorage` on RN where the secure store would
+ * gate every read on biometric).
+ */
+interface InactivityStore {
+    read(): Promise<number | null>;
+    write(timestamp: number): Promise<void>;
+    clear(): Promise<void>;
+}
+interface InactivityTrackerOptions {
+    store: InactivityStore;
+    /**
+     * Maximum days the user can be inactive (no successful refresh) before
+     * sessions are forcibly cleared. Default 90 (matches mobile decision).
+     */
+    maxInactivityDays?: number;
+    /** Inject for tests; defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Tracks the last time a refresh succeeded and decides whether the session
+ * has aged past its inactivity threshold.
+ *
+ * - `markActive(now?)` is called by `RefreshInterceptor` after every
+ *   successful token swap.
+ * - `isExpired()` is called from `AuthClient.init()` at boot. If true,
+ *   consumers clear tokens and emit `sessionExpired`.
+ *
+ * Choosing days (not e.g. minutes) makes the policy match what users
+ * understand: a session left untouched for 90 days needs re-auth.
+ */
+declare class InactivityTracker {
+    private readonly store;
+    private readonly maxInactivityMs;
+    private readonly now;
+    constructor(options: InactivityTrackerOptions);
+    markActive(timestamp?: number): Promise<void>;
+    getLastActive(): Promise<number | null>;
+    isExpired(): Promise<boolean>;
+    clear(): Promise<void>;
+}
+
+/**
+ * The pluggable refresh function the interceptor calls when an access token
+ * is missing or expired. Implementations differ per transport:
+ *
+ * - **Mobile (SecureStore)**: posts to `/auth/refresh` with the refresh token
+ *   from `AuthTokens.refreshToken`.
+ * - **Web (Cookie)**: posts to `/auth/refresh-cookie` with `credentials:
+ *   'include'` — the refresh token rides on the httpOnly cookie; `current`
+ *   carries only the access token (refresh token will be undefined).
+ *
+ * Returns the new token bundle, or `null` when refresh failed in a way that
+ * means "session over" (e.g., 401 from the auth server).
+ */
+type RefreshFn = (current: AuthTokens | null) => Promise<AuthTokens | null>;
+interface RefreshInterceptorOptions {
+    storage: TokenStorage;
+    refresh: RefreshFn;
+    events: AuthEventEmitter;
+    /**
+     * Optional callback fired AFTER tokens are persisted on a successful
+     * refresh. Used by `AuthClient` to update the inactivity tracker.
+     */
+    onRefreshSuccess?: (tokens: AuthTokens) => Promise<void> | void;
+}
+/**
+ * Coordinates refresh-token swaps so concurrent 401s don't trigger N parallel
+ * refreshes. The first caller to hit `refreshTokens()` while no refresh is
+ * already in flight wins the role of "refresher"; everyone else awaits the
+ * same promise.
+ *
+ * On failure, storage is cleared and `sessionExpired` is emitted exactly once
+ * per refresh attempt.
+ */
+declare class RefreshInterceptor {
+    private readonly storage;
+    private readonly refresh;
+    private readonly events;
+    private readonly onRefreshSuccess;
+    private inflight;
+    constructor(options: RefreshInterceptorOptions);
+    /**
+     * Trigger (or join) a refresh. Returns the new tokens, or `null` if the
+     * refresh failed — in which case storage has already been cleared and
+     * `sessionExpired` already fired.
+     */
+    refreshTokens(): Promise<AuthTokens | null>;
+    /**
+     * Whether a refresh is currently in flight. Exposed for tests / debug.
+     */
+    get isRefreshing(): boolean;
+    private runRefresh;
+    private failHard;
+}
+
+/**
+ * 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;
+}
+/**
+ * Optional collaborators wired into {@link AuthClient} for the v2 surface.
+ *
+ * - `api` enables `loginWith*`, `logout`, `requestPasswordReset`,
+ *   `confirmPasswordReset`. Without it, those methods throw.
+ * - `interceptor` enables `init()` to silently refresh tokens at boot, and is
+ *   used by `loginWithOtp/Password` to mark inactivity-active.
+ * - `inactivityTracker` enforces the 90-day timeout at `init()`.
+ *
+ * Consumers can omit any/all of these — the v1 PKCE / token-storage surface
+ * keeps working unchanged.
+ */
+interface AuthClientCollaborators {
+    api?: AuthApiClient;
+    interceptor?: RefreshInterceptor;
+    inactivityTracker?: InactivityTracker;
+    events?: AuthEventEmitter;
+    /**
+     * Observability hook fired when a fresh token bundle has been acquired
+     * (any login path: OTP, password, or direct-KC PKCE). For app-side
+     * analytics/logging only — NOT for BFF integration (Phase 2 designs that
+     * fresh).
+     */
+    onTokenAcquired?: (tokens: AuthTokens) => void;
+    /**
+     * Observability hook fired when an existing token bundle has been
+     * refreshed. For app-side analytics/logging only.
+     */
+    onTokenRefreshed?: (tokens: AuthTokens) => void;
+}
+/**
+ * Direct-to-KC (PKCE) routing flag added in v2.1.0.
+ *
+ * When `true`, `AuthClient` consumers can route their PKCE auth code through
+ * the shared OIDC primitives (`exchangeAuthorizationCodeViaOidc`,
+ * `refreshTokensViaOidc`) instead of the proxied identity-api `/auth/login`
+ * + `/auth/refresh` flow.
+ *
+ * Default `false` — v2.0 behavior unchanged.
+ *
+ * The flag is read-only at runtime (`isDirectMode()`) so apps can render
+ * conditionally on whether they've opted in.
+ */
+interface DirectKcOptions {
+    useDirectKcAuth?: boolean;
+}
+interface LoginOptions {
+    /** When true, request `offline_access` scope so the IdP issues a long-lived refresh token. */
+    offlineAccess?: boolean;
+}
+interface LogoutOptions {
+    /** Revoke all sessions on the IdP, not just the current one. */
+    everywhere?: boolean;
+}
+declare class AuthClient {
+    private readonly config;
+    private readonly directKcAuth;
+    private readonly tokenStorage;
+    private readonly api;
+    private readonly interceptor;
+    private readonly inactivityTracker;
+    private readonly events;
+    private readonly onTokenAcquired;
+    private readonly onTokenRefreshed;
+    /**
+     * @throws Error when `baseUrl`, `realm`, or `clientId` is missing or empty.
+     */
+    constructor(config: AuthClientConfig & DirectKcOptions, storage: TokenStorage, collaborators?: AuthClientCollaborators);
+    /**
+     * Whether this client is configured to route auth flows directly to
+     * Keycloak (v2.1.0 direct-KC path) instead of through the proxied
+     * identity-api `/auth/*` endpoints.
+     *
+     * Apps can render conditionally on this — e.g. to swap a login form for
+     * a "Sign in with Keycloak" redirect button.
+     */
+    isDirectMode(): boolean;
+    /**
+     * Persist a token bundle produced by an external flow (e.g. the
+     * app-side `useKeycloakExchange` hook that consumes the shared
+     * `exchangeAuthorizationCode` primitive). Fires `onTokenAcquired` after
+     * persistence and marks the inactivity tracker active.
+     *
+     * Designed for the v2.1.0 direct-KC path where the PKCE code exchange
+     * happens in the app's React-Query hook (which needs `useDispatch`/etc.)
+     * but the token persistence + observability should still flow through
+     * the shared client.
+     */
+    acceptDirectKcTokens(response: TokenResponse): Promise<AuthTokens>;
+    /**
+     * Same as {@link acceptDirectKcTokens} but fires `onTokenRefreshed`.
+     * Use after a `refreshAccessToken()` swap to keep observability counts
+     * separated between "fresh login" and "silent refresh".
+     */
+    acceptDirectKcRefresh(response: TokenResponse): Promise<AuthTokens>;
+    /**
+     * 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, collaborators?: AuthClientCollaborators): 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';
+        offlineAccess?: boolean;
+    }): 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>;
+    /** Subscribe to lifecycle events (currently `sessionExpired` only). */
+    on(event: AuthEventName, listener: AuthEventListener): AuthEventUnsubscribe;
+    /**
+     * Boot-time wiring. Checks the inactivity tracker; if expired, clears
+     * tokens and emits `sessionExpired`. Returns whether a usable session
+     * survived.
+     */
+    init(): Promise<{
+        hasSession: boolean;
+    }>;
+    /**
+     * Trigger a refresh via the configured interceptor. Returns the new tokens
+     * or `null` when the refresh failed (in which case `sessionExpired` has
+     * already fired).
+     *
+     * @throws Error when no interceptor is configured.
+     */
+    refresh(): Promise<AuthTokens | null>;
+    loginWithOtp(input: {
+        email: string;
+        otp: string;
+        tenantId?: string;
+    } & LoginOptions): Promise<AuthTokens>;
+    loginWithPassword(input: {
+        email: string;
+        password: string;
+        tenantId?: string;
+    } & LoginOptions): Promise<AuthTokens>;
+    logout(options?: LogoutOptions): Promise<void>;
+    requestPasswordReset(input: {
+        email: string;
+        tenantId?: string;
+    }): Promise<void>;
+    confirmPasswordReset(input: {
+        token: string;
+        newPassword: string;
+    }): Promise<void>;
+    /** Internal: run a login HTTP call, persist tokens, mark inactivity-active. */
+    private runLogin;
+    private requireApi;
+    private resolveScope;
+}
+
+export { AuthApiClient as A, type DirectKcOptions as D, type ForgotPasswordRequest as F, type InactivityStore as I, type LoginOptions as L, type OtpLoginRequest as O, type PasswordLoginRequest as P, type ResetPasswordRequest as R, type TokenStorage as T, type AuthSessionInfo as a, AuthClient as b, type AuthTokens as c, type AuthApiClientOptions as d, type AuthClientCollaborators as e, type AuthClientConfig as f, type AuthClientFromIssuerInput as g, AuthEventEmitter as h, type AuthEventListener as i, type AuthEventName as j, type AuthEventUnsubscribe as k, InactivityTracker as l, type InactivityTrackerOptions as m, type LogoutOptions as n, type RawAuthLoginResponse as o, type RefreshFn as p, RefreshInterceptor as q, type RefreshInterceptorOptions as r };