@dloizides/auth-client 1.0.0 → 2.0.0

package/dist/AuthClient-Dim7HPRz.d.mts

@@ -0,0 +1,433 @@
+/**
+ * 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;
+}
+
+/**
+ * Minimal HTTP transport the package depends on.
+ *
+ * `AuthClient` orchestrates token-related HTTP calls (login, refresh, logout,
+ * password reset) but doesn't import `fetch` directly — keeping the package
+ * runtime-agnostic. Consumers wire native fetch, axios, ky, or whatever their
+ * platform exposes.
+ */
+interface HttpRequest {
+    url: string;
+    method: 'GET' | 'POST' | 'DELETE';
+    headers?: Record<string, string>;
+    /** When set, body is sent as the request body; serialization is the caller's job. */
+    body?: string;
+    /** Browser fetch only — pass through `credentials: 'include'` for cookie auth. */
+    credentials?: 'include' | 'same-origin' | 'omit';
+}
+interface HttpResponse {
+    status: number;
+    ok: boolean;
+    /** Parsed body (already JSON-decoded). `undefined` for 204 / empty bodies. */
+    data?: unknown;
+}
+type HttpClient = (request: HttpRequest) => Promise<HttpResponse>;
+/**
+ * Wrap the platform's native `fetch` into the package's `HttpClient` shape.
+ * Decoded JSON when `Content-Type` is JSON, otherwise leaves data undefined.
+ *
+ * Errors thrown by `fetch` (network / abort) are NOT swallowed — callers
+ * decide whether to treat them as session-ending.
+ */
+declare function createFetchHttpClient(fetchImpl: typeof fetch): HttpClient;
+
+/**
+ * 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;
+}
+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 tokenStorage;
+    private readonly api;
+    private readonly interceptor;
+    private readonly inactivityTracker;
+    private readonly events;
+    /**
+     * @throws Error when `baseUrl`, `realm`, or `clientId` is missing or empty.
+     */
+    constructor(config: AuthClientConfig, storage: TokenStorage, collaborators?: AuthClientCollaborators);
+    /**
+     * 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 { type AuthTokens as A, type ForgotPasswordRequest as F, type HttpClient as H, type InactivityStore as I, type LoginOptions as L, type OtpLoginRequest as O, type PasswordLoginRequest as P, type RawAuthLoginResponse as R, type TokenStorage as T, AuthApiClient as a, type AuthApiClientOptions as b, AuthClient as c, type AuthClientCollaborators as d, type AuthClientConfig as e, type AuthClientFromIssuerInput as f, AuthEventEmitter as g, type AuthEventListener as h, type AuthEventName as i, type AuthEventUnsubscribe as j, type AuthSessionInfo as k, type HttpRequest as l, type HttpResponse as m, InactivityTracker as n, type InactivityTrackerOptions as o, type LogoutOptions as p, type RefreshFn as q, RefreshInterceptor as r, type RefreshInterceptorOptions as s, type ResetPasswordRequest as t, createFetchHttpClient as u };