@dloizides/auth-client 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,95 @@
 # Changelog
 
+## 3.0.0 (2026-05-19)
+
+Major release for Phase 2 of the identity-hardening initiative. Adds the
+shared `BffAuthClient` — the same-origin client for a per-app
+**Backend-For-Frontend** (`bff-katalogos`, `bff-erevna`). The BFF terminates
+authentication server-side: the browser holds only an opaque httpOnly session
+cookie, never a token.
+
+This is the **new recommended auth surface**. The major bump signals that
+recommendation — it is **not** a breaking change: every v2.x export
+(`AuthClient`, the direct-KC ROPC adapters, `useDirectKcAuth`, the OIDC
+primitives, storage adapters, hooks) remains and is unchanged. BaseClient
+still consumes the direct-KC path; it is removed in a later phase.
+
+### Added
+
+- `BffAuthClient` — same-origin client for a per-app BFF. Methods:
+  `login({username,password})` → `POST /bff/login`; `logout()` →
+  `POST /bff/logout`; `getCurrentUser()` → `GET /bff/me`; `register(...)`,
+  `forgotPassword(...)`, `resetPassword(...)` → the matching `/bff/*`
+  endpoints. Every call is a same-origin `fetch` with
+  `credentials: 'include'`; state-changing calls carry the `X-BFF-Csrf: 1`
+  header the `Bff.AspNetCore` anti-forgery middleware requires. Does **no
+  token handling** — the BFF owns tokens, the browser owns only the cookie.
+- Types: `BffAuthClientOptions`, `BffLoginRequest`, `BffRegisterRequest`,
+  `BffForgotPasswordRequest`, `BffResetPasswordRequest`, `BffUser`.
+
+## 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.

package/README.md

@@ -119,6 +119,41 @@ const storage = new SecureStoreTokenStorage({
 await biometricGate.hydrate();
 ```
 
+## BFF auth (v3 — recommended)
+
+`BffAuthClient` is the same-origin client for a per-app **Backend-For-Frontend**
+(`bff-katalogos`, `bff-erevna`). The BFF terminates authentication
+server-side: it does ROPC against Keycloak with a confidential client, stores
+the tokens in a Redis vault, and hands the browser only an opaque httpOnly
+session cookie. The SPA never sees a token — an XSS cannot exfiltrate one.
+
+`BffAuthClient` does **no token handling**: every call is a same-origin
+`fetch` with `credentials: 'include'`, and state-changing calls carry the
+`X-BFF-Csrf: 1` header the BFF anti-forgery middleware requires.
+
+```ts
+import { BffAuthClient, createFetchHttpClient } from '@dloizides/auth-client';
+
+const bff = new BffAuthClient({
+  http: createFetchHttpClient(window.fetch.bind(window)),
+  // baseUrl defaults to '' (same-origin) — the production wiring.
+});
+
+// Login — the BFF does ROPC server-side and sets the session cookie.
+const user = await bff.login({ username, password });
+
+// Bootstrap on app load — null when there is no live session.
+const current = await bff.getCurrentUser();
+
+await bff.register({ firstName, lastName, username, email, password, tenantName });
+await bff.forgotPassword({ email, resetUrlTemplate });
+await bff.resetPassword({ token, newPassword });
+await bff.logout();
+```
+
+The direct-KC `AuthClient` / ROPC surface below is retained for consumers not
+yet on a BFF; it is deprecated and removed once every app has migrated.
+
 ## React Query hooks
 
 ```ts
@@ -156,7 +191,8 @@ auth.on('sessionExpired', () => {
 
 ### Core (`@dloizides/auth-client`)
 
-- `AuthClient` — realm-aware orchestrator. `init()`, `refresh()`, `loginWithOtp()`, `loginWithPassword()`, `logout({ everywhere })`, `requestPasswordReset()`, `confirmPasswordReset()`, plus the v1 surface (`getAccessToken`, `getTokens`, `setTokens`, `clearTokens`, `buildAuthorizationUrl`, etc.).
+- `BffAuthClient` — same-origin client for a per-app Backend-For-Frontend. `login()`, `logout()`, `getCurrentUser()`, `register()`, `forgotPassword()`, `resetPassword()`. No token handling — the BFF owns tokens, the browser owns only an httpOnly cookie. **The recommended auth surface (v3).**
+- `AuthClient` — realm-aware orchestrator. `init()`, `refresh()`, `loginWithOtp()`, `loginWithPassword()`, `logout({ everywhere })`, `requestPasswordReset()`, `confirmPasswordReset()`, plus the v1 surface (`getAccessToken`, `getTokens`, `setTokens`, `clearTokens`, `buildAuthorizationUrl`, etc.). Direct-KC ROPC; deprecated in favour of `BffAuthClient`.
 - `AuthApiClient` — typed wrapper for IdentityService auth endpoints.
 - `AuthEventEmitter` — `sessionExpired` event.
 - `RefreshInterceptor` — single-flight refresh queue.

package/dist/{AuthClient-Dim7HPRz.d.ts → AuthClient-BGr8L03W.d.mts}

@@ -1,3 +1,5 @@
+import { H as HttpClient, T as TokenResponse } from './TokenResponse-CY1CaU2l.mjs';
+
 /**
  * Tiny dependency-free event emitter for auth lifecycle events.
  *
@@ -19,39 +21,6 @@ declare class AuthEventEmitter {
     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`.
  *
@@ -328,6 +297,34 @@ interface AuthClientCollaborators {
     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. */
@@ -339,15 +336,45 @@ interface LogoutOptions {
 }
 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, storage: TokenStorage, collaborators?: AuthClientCollaborators);
+    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
@@ -430,4 +457,4 @@ declare class AuthClient {
     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 };
+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 };

package/dist/{AuthClient-Dim7HPRz.d.mts → AuthClient-D95OMajD.d.ts}

@@ -1,3 +1,5 @@
+import { H as HttpClient, T as TokenResponse } from './TokenResponse-CY1CaU2l.js';
+
 /**
  * Tiny dependency-free event emitter for auth lifecycle events.
  *
@@ -19,39 +21,6 @@ declare class AuthEventEmitter {
     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`.
  *
@@ -328,6 +297,34 @@ interface AuthClientCollaborators {
     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. */
@@ -339,15 +336,45 @@ interface LogoutOptions {
 }
 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, storage: TokenStorage, collaborators?: AuthClientCollaborators);
+    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
@@ -430,4 +457,4 @@ declare class AuthClient {
     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 };
+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 };

package/dist/TokenResponse-CY1CaU2l.d.mts

@@ -0,0 +1,59 @@
+/**
+ * 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;
+
+/**
+ * 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;
+}
+
+export { type HttpClient as H, type RawTokenResponse as R, type TokenResponse as T, type HttpRequest as a, type HttpResponse as b, createFetchHttpClient as c };

package/dist/TokenResponse-CY1CaU2l.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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;
+
+/**
+ * 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;
+}
+
+export { type HttpClient as H, type RawTokenResponse as R, type TokenResponse as T, type HttpRequest as a, type HttpResponse as b, createFetchHttpClient as c };