@dloizides/auth-client 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,418 @@
+/**
+ * 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>;
+}
+
+/**
+ * Roles emitted by Keycloak realms in the dloizides.com portfolio.
+ *
+ * Lives in its own file per the project convention: each exported `const enum`
+ * sits alone so it can be imported without dragging the rest of the type tree.
+ */
+declare const enum KeycloakRoles {
+    SuperUser = "superUser",
+    Admin = "admin",
+    User = "user"
+}
+/**
+ * Type guard that narrows a string to a known {@link KeycloakRoles} value.
+ *
+ * Use this when ingesting role claims from the network, where the wire payload
+ * is `string[]` but downstream code wants `KeycloakRoles[]`.
+ */
+declare function isKeycloakRole(value: string): value is KeycloakRoles;
+
+/**
+ * Shape of the Keycloak `/userinfo` response (and any equivalent payload returned
+ * by a backend Identity service that wraps Keycloak).
+ *
+ * Fields are optional because Keycloak realms can include or omit claims based
+ * on scope / mapper configuration. Consumers should narrow before use.
+ */
+interface KeycloakUserInfo {
+    sub?: string;
+    name?: string;
+    preferred_username?: string;
+    given_name?: string;
+    family_name?: string;
+    email?: string;
+    email_verified?: boolean;
+    locale?: string;
+    tenantId?: string;
+    realm_access?: {
+        roles?: KeycloakRoles[];
+    };
+    resource_access?: Record<string, {
+        roles?: KeycloakRoles[];
+    }>;
+    roles: KeycloakRoles[];
+    [key: string]: unknown;
+}
+
+/**
+ * Application-friendly view of a Keycloak user.
+ *
+ * Consumers should prefer this over {@link KeycloakUserInfo} for rendering and
+ * authorization checks: it has predictable fields and a deduplicated roles array.
+ */
+interface NormalizedUser {
+    id?: string;
+    username?: string;
+    email?: string;
+    displayName?: string;
+    firstName?: string;
+    lastName?: string;
+    emailVerified?: boolean;
+    roles: KeycloakRoles[];
+    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.
+ */
+interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+interface BrowserStorageTokenStorageOptions {
+    storage: StorageLike;
+    /** Storage key. Defaults to `auth.tokens`. */
+    key?: string;
+}
+/**
+ * Persist tokens in any `Storage`-shaped backend (`localStorage`, `sessionStorage`,
+ * AsyncStorage shim, etc.). The class is sync-aware but exposes a Promise-based
+ * API to match {@link TokenStorage}.
+ *
+ * Errors during read are swallowed and surfaced as `null` (corrupt JSON, denied
+ * access in some private-mode browsers, etc.). Errors during write/clear are
+ * propagated so callers can decide whether to retry or fall back.
+ */
+declare class BrowserStorageTokenStorage implements TokenStorage {
+    private readonly storage;
+    private readonly key;
+    constructor(options: BrowserStorageTokenStorageOptions);
+    read(): Promise<AuthTokens | null>;
+    write(tokens: AuthTokens): Promise<void>;
+    clear(): Promise<void>;
+    private readSync;
+}
+
+/**
+ * In-memory storage backed by a single instance variable.
+ *
+ * Useful for tests, server-side rendering, and as a default fallback when no
+ * platform-specific storage is available. Tokens are lost on process exit.
+ */
+declare class InMemoryTokenStorage implements TokenStorage {
+    private tokens;
+    read(): Promise<AuthTokens | null>;
+    write(tokens: AuthTokens): Promise<void>;
+    clear(): Promise<void>;
+}
+
+/**
+ * Convert a Keycloak `/userinfo` payload into a flat, app-friendly user object.
+ *
+ * - Aggregates `realm_access.roles` and every `resource_access[*].roles` into a
+ *   deduplicated `roles` array.
+ * - Picks a sensible `displayName` / `username` from whatever claims are
+ *   present (Keycloak realms vary in which fields they emit).
+ * - Returns a safe default (`{ roles: [] }`) when input is undefined.
+ */
+declare function normalizeKeycloakUser(u?: KeycloakUserInfo): NormalizedUser;
+
+/**
+ * Extract the realm name from a Keycloak issuer URL.
+ *
+ * Keycloak issuer URLs follow the shape `{baseUrl}/realms/{realm}` (with optional
+ * `/protocol/openid-connect` suffix on token endpoints). This helper reverses
+ * that convention so existing apps that store only the issuer URL can derive
+ * `realm` for the realm-aware {@link AuthClient} constructor.
+ *
+ * @returns the realm name, or `null` if the URL doesn't match the convention.
+ */
+declare function parseRealmFromIssuer(issuerUrl: string | null | undefined): string | null;
+/**
+ * Extract the base URL (scheme + host + optional path prefix) from a
+ * Keycloak issuer URL by stripping the `/realms/{realm}...` suffix.
+ *
+ * Returns the original input unchanged when no `/realms/` segment is found —
+ * callers that need strict validation should pair this with `parseRealmFromIssuer`.
+ */
+declare function parseBaseUrlFromIssuer(issuerUrl: string | null | undefined): string | null;
+
+/**
+ * Inputs for the OAuth `authorization_code` token request.
+ */
+interface AuthorizationCodeBodyInput {
+    clientId: string;
+    code: string;
+    redirectUri: string;
+    codeVerifier: string;
+}
+/**
+ * Inputs for the OAuth `refresh_token` token request.
+ */
+interface RefreshTokenBodyInput {
+    clientId: string;
+    refreshToken: string;
+}
+/**
+ * Build the `application/x-www-form-urlencoded` body for the
+ * `grant_type=authorization_code` token endpoint call (PKCE flow).
+ */
+declare function buildAuthorizationCodeBody(input: AuthorizationCodeBodyInput): string;
+/**
+ * Build the `application/x-www-form-urlencoded` body for the
+ * `grant_type=refresh_token` token endpoint call.
+ */
+declare function buildRefreshTokenBody(input: RefreshTokenBodyInput): string;
+
+/**
+ * URL builders for the realm-aware Keycloak surface area.
+ *
+ * Every helper takes `baseUrl` and `realm` explicitly — no hardcoded realm
+ * names. This is the contract that Phase 2 of the product split relies on:
+ * the same package serves the future Questioner-realm app and OnlineMenu-realm
+ * app without code change.
+ */
+/**
+ * Compute the issuer URL: `{baseUrl}/realms/{realm}`.
+ */
+declare function buildIssuerUrl(baseUrl: string, realm: string): string;
+/**
+ * Compute the authorization endpoint URL.
+ */
+declare function buildAuthorizationEndpoint(baseUrl: string, realm: string): string;
+/**
+ * Compute the token endpoint URL.
+ */
+declare function buildTokenEndpoint(baseUrl: string, realm: string): string;
+/**
+ * Compute the userinfo endpoint URL.
+ */
+declare function buildUserInfoEndpoint(baseUrl: string, realm: string): string;
+/**
+ * Compute the logout endpoint URL.
+ */
+declare function buildLogoutEndpoint(baseUrl: string, realm: string): string;
+interface AuthorizationUrlInput {
+    baseUrl: string;
+    realm: string;
+    clientId: string;
+    redirectUri: string;
+    scope?: string;
+    state?: string;
+    codeChallenge?: string;
+    codeChallengeMethod?: 'S256' | 'plain';
+}
+/**
+ * Build a complete authorization URL the user agent can navigate to.
+ *
+ * All PKCE-related fields are optional so this helper also serves
+ * non-PKCE flows (e.g. confidential server-side clients) — but PKCE is
+ * the recommended path for SPA / native consumers.
+ */
+declare function buildAuthorizationUrl(input: AuthorizationUrlInput): string;
+
+/**
+ * Loose shape of an `expo-auth-session` (or browser-side) authorization response.
+ *
+ * Kept as a structural type rather than importing from `expo-auth-session` so
+ * the package stays usable in plain web apps and Node tests.
+ */
+interface AuthorizationResponseLike {
+    type?: string;
+    params?: {
+        code?: string;
+        error?: string;
+    };
+}
+/**
+ * Pull the authorization `code` out of a successful redirect response.
+ *
+ * Returns `undefined` when the response is missing, indicates an error type,
+ * or doesn't carry a non-empty `code` query param.
+ */
+declare function extractAuthCode(response: AuthorizationResponseLike | null | undefined): string | undefined;
+
+/**
+ * Determine whether a token bundle is expired.
+ *
+ * `expiresAt` is interpreted as an absolute UNIX millisecond timestamp.
+ *
+ * `leewayMs` (default 30 s) shaves a small window off the expiry to compensate
+ * for clock skew and round-trip latency: a token that expires at exactly
+ * `Date.now()` is essentially useless because by the time the request arrives
+ * at the API it will have expired.
+ */
+declare function isTokenExpired(tokens: Pick<AuthTokens, 'expiresAt'> | null | undefined, leewayMs?: number, now?: number): boolean;
+/**
+ * Compute the absolute expiry timestamp from a token endpoint `expires_in` value.
+ *
+ * Returns `0` when `expiresIn` is missing or non-positive — signalling "unknown
+ * expiry, treat as expired" downstream.
+ */
+declare function computeExpiresAt(expiresInSeconds: number | undefined, now?: number): number;
+
+/**
+ * Decode the payload segment of a compact JWT.
+ *
+ * No signature verification — that responsibility belongs to the backend that
+ * accepts the token. This helper is for UI concerns: reading `exp` to schedule
+ * refresh, reading custom claims for routing decisions, etc.
+ *
+ * Returns `null` when the input is malformed, base64url-decodes incorrectly, or
+ * does not produce a JSON object payload.
+ *
+ * Runtime requirement: a global `atob` function. Available in browsers, in
+ * Node ≥ 16, and in modern bundler test envs (jsdom, node-jest).
+ */
+declare function decodeJwt<T = Record<string, unknown>>(token: string | null | undefined): T | null;
+
+/**
+ * Map a raw OIDC token endpoint response (snake_case) to camelCase.
+ *
+ * Throws when `access_token` is missing or empty — callers should let this
+ * propagate to the auth state machine, which treats it as a login failure.
+ */
+declare function normalizeTokenResponse(raw: RawTokenResponse): TokenResponse;
+/**
+ * Convert a normalized {@link TokenResponse} into a persistable
+ * {@link AuthTokens} bundle by computing `expiresAt` from `expiresIn`.
+ */
+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 };