doover-js 0.11.0 → 0.13.0

package/dist/esm/auth/auth-store.d.ts

@@ -0,0 +1,14 @@
+import type { AuthProfile } from "./auth-profile.js";
+/**
+ * Structural interface for profile stores accepted by auth classes.
+ * Implementations may be backed by files (ConfigManager in the Node subpath)
+ * or by in-memory stores for testing.
+ */
+export interface AuthProfileStore {
+    currentProfile: string | null;
+    current: AuthProfile | null;
+    get(profileName: string): AuthProfile | undefined;
+    create(entry: AuthProfile): void;
+    delete(profileName: string): void;
+    write(): void;
+}

package/dist/esm/auth/build-auth.d.ts

@@ -0,0 +1,38 @@
+import type { AuthProfile } from "./auth-profile.js";
+import type { AuthProfileStore } from "./auth-store.js";
+import { DooverAuth } from "./doover-auth.js";
+/**
+ * Raw auth inputs that can be provided in client configs.
+ *
+ * If `auth` is provided it is used as-is and raw inputs must not be combined
+ * with it. Otherwise these fields are used to build the appropriate auth
+ * instance automatically.
+ */
+export interface AuthConfig {
+    auth?: DooverAuth;
+    profile?: string | AuthProfile;
+    configManager?: AuthProfileStore;
+    token?: string | null;
+    tokenExpires?: Date | number | null;
+    refreshToken?: string | null;
+    refreshTokenId?: string | null;
+    authServerUrl?: string | null;
+    authServerClientId?: string | null;
+}
+/** Fetch implementation to thread through to DooverTokenAuth. */
+interface BuildAuthOptions extends AuthConfig {
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Build a `DooverAuth` instance from the provided configuration.
+ *
+ * Rules:
+ * 1. If `auth` is provided it is returned as-is.
+ * 2. If any token material is present, build `DooverTokenAuth`.
+ * 3. If `profile` is an `AuthProfile`, use it to seed a `DooverTokenAuth`.
+ * 4. If `profile` is a string, look it up via `configManager`.
+ * 5. Otherwise fall back to `CookieAuth`, refresh-capable when
+ *    `authServerUrl` is known.
+ */
+export declare function buildAuth(options: BuildAuthOptions): DooverAuth;
+export {};

package/dist/esm/auth/build-auth.js

@@ -0,0 +1,92 @@
+import { CookieAuth } from "./cookie-auth.js";
+import { DooverTokenAuth } from "./doover-token-auth.js";
+import { DooverAuthError } from "./errors.js";
+const TOKEN_FIELDS = [
+    "token",
+    "tokenExpires",
+    "refreshToken",
+    "refreshTokenId",
+    "authServerUrl",
+    "authServerClientId",
+];
+/**
+ * The subset of `TOKEN_FIELDS` that actually implies bearer-token auth.
+ *
+ * `authServerUrl` / `authServerClientId` describe *where* to refresh, not what
+ * we hold: on their own they now configure a refresh-capable `CookieAuth`
+ * (a browser session in an app that knows its auth server), which is far more
+ * useful than the tokenless `DooverTokenAuth` they used to produce — that
+ * instance could only ever throw "missing refreshToken" on first use.
+ */
+const TOKEN_MATERIAL_FIELDS = [
+    "token",
+    "tokenExpires",
+    "refreshToken",
+    "refreshTokenId",
+];
+/**
+ * Build a `DooverAuth` instance from the provided configuration.
+ *
+ * Rules:
+ * 1. If `auth` is provided it is returned as-is.
+ * 2. If any token material is present, build `DooverTokenAuth`.
+ * 3. If `profile` is an `AuthProfile`, use it to seed a `DooverTokenAuth`.
+ * 4. If `profile` is a string, look it up via `configManager`.
+ * 5. Otherwise fall back to `CookieAuth`, refresh-capable when
+ *    `authServerUrl` is known.
+ */
+export function buildAuth(options) {
+    if (options.auth) {
+        // Validate mutual exclusivity.
+        const hasRaw = TOKEN_FIELDS.some((k) => options[k] !== undefined);
+        if (hasRaw || options.profile !== undefined || options.configManager !== undefined) {
+            throw new DooverAuthError("Cannot combine 'auth' with raw auth config fields (token, profile, configManager, etc.)");
+        }
+        return options.auth;
+    }
+    // Resolve the profile object.
+    let resolvedProfile = null;
+    if (typeof options.profile === "string") {
+        if (!options.configManager) {
+            throw new DooverAuthError("A 'configManager' (AuthProfileStore) is required when 'profile' is a string. " +
+                "Use the doover-js/node subpath to import ConfigManager, or provide an AuthProfile directly.");
+        }
+        resolvedProfile = options.configManager.get(options.profile) ?? null;
+        if (!resolvedProfile) {
+            throw new DooverAuthError(`Profile '${options.profile}' not found in the config manager`);
+        }
+    }
+    else if (options.profile instanceof Object && "profile" in options.profile) {
+        // AuthProfile instance
+        resolvedProfile = options.profile;
+    }
+    // Determine whether we need token auth.
+    const hasTokenInput = TOKEN_MATERIAL_FIELDS.some((k) => options[k] !== undefined);
+    const profileHasToken = resolvedProfile?.token != null;
+    if (!hasTokenInput && !profileHasToken) {
+        // No token data at all — fall back to cookie auth, which can still renew
+        // the session when the app has told us where its auth server lives.
+        const auth = new CookieAuth({
+            authServerUrl: options.authServerUrl ?? resolvedProfile?.authServerUrl ?? null,
+            fetchImpl: options.fetchImpl,
+        });
+        if (resolvedProfile) {
+            auth.attachProfile(resolvedProfile, options.configManager);
+        }
+        return auth;
+    }
+    // Build DooverTokenAuth with explicit fields overriding profile values.
+    const auth = new DooverTokenAuth({
+        token: options.token ?? undefined,
+        tokenExpires: options.tokenExpires ?? undefined,
+        refreshToken: options.refreshToken ?? undefined,
+        refreshTokenId: options.refreshTokenId ?? undefined,
+        authServerUrl: options.authServerUrl ?? undefined,
+        authServerClientId: options.authServerClientId ?? undefined,
+        fetchImpl: options.fetchImpl,
+    });
+    if (resolvedProfile) {
+        auth.attachProfile(resolvedProfile, options.configManager);
+    }
+    return auth;
+}

package/dist/esm/auth/cookie-auth.d.ts

@@ -0,0 +1,91 @@
+import { DooverAuth } from "./doover-auth.js";
+export interface CookieAuthOptions {
+    /**
+     * Base URL of the auth server that serves the hosted-backend refresh
+     * endpoint. Required for any refresh behaviour; without it `CookieAuth`
+     * behaves exactly as it always has (no refresh, no recovery).
+     */
+    authServerUrl?: string | null;
+    /** Refresh endpoint path. Defaults to `/app/refresh/`. */
+    refreshPath?: string;
+    /** Name of the access-token expiry cookie. Defaults to `app.at_exp`. */
+    accessTokenExpiryCookieName?: string;
+    /** Override `fetch` (tests, native hosts). */
+    fetchImpl?: typeof fetch;
+    /** Override how the cookie string is read. Defaults to `document.cookie`. */
+    cookieReader?: () => string;
+}
+/**
+ * Cookie-based auth — the default browser strategy.
+ *
+ * Relies on ambient cookies (`credentials: "include"`) and does not add any
+ * `Authorization` header. The access token itself is httpOnly and invisible to
+ * JS; the only readable part of the session is a companion expiry cookie
+ * (`app.at_exp`).
+ *
+ * ## Why this refreshes
+ *
+ * The FusionAuth React SDK's auto-refresh is a single `setTimeout` per token.
+ * A browser that suspends the tab (backgrounded, laptop asleep) never fires it,
+ * so the tab wakes with an expired access-token cookie and every request 401s —
+ * even though the refresh token itself is usually still valid. Rather than
+ * leaving every browser app to work around that on its own, `CookieAuth`
+ * handles it whenever `authServerUrl` is configured: `ensureReady` renews an
+ * already-expired token before a request goes out (which also covers gateway
+ * reconnects, since `GatewayClient` awaits it before opening a socket), and
+ * `handleUnauthorized` lets `RestClient` replay a 401 once after a renewal.
+ */
+export declare class CookieAuth extends DooverAuth {
+    private readonly authServerUrl;
+    private readonly refreshPath;
+    private readonly expiryCookieName;
+    private readonly fetchImpl;
+    private readonly cookieReader;
+    private refreshInFlight;
+    private lastAttempt;
+    constructor(options?: CookieAuthOptions);
+    getHttpHeaders(): Promise<Record<string, string>>;
+    getFetchCredentials(): RequestCredentials;
+    prepareWebSocket(url: string, _canUseHeaders: boolean): Promise<{
+        url: string;
+        headers?: Record<string, string>;
+    }>;
+    setToken(_token: string | null, _tokenExpires?: Date | number | null): void;
+    setRefreshToken(_refreshToken: string | null): void;
+    /**
+     * Renew the access token when it has already expired, so the request that
+     * follows isn't a guaranteed 401. A token that is merely close to expiry is
+     * left alone: requests must not block on a refresh they don't need, and
+     * `handleUnauthorized` is there for the race.
+     */
+    ensureReady(): Promise<void>;
+    /**
+     * Called by `RestClient` after a 401. A successful refresh means the request
+     * is worth replaying once.
+     */
+    handleUnauthorized(): Promise<boolean>;
+    /** Expiry of the current access token, or `null` if there is no session. */
+    getAccessTokenExpiry(): Date | null;
+    /** True when a session cookie exists and has not yet expired. */
+    isAccessTokenValid(): boolean;
+    /**
+     * True when the access token expires within `thresholdMs` (or already has).
+     * Apps use this to decide whether a `visibilitychange` is worth a proactive
+     * refresh. False when there is no session at all — nothing to refresh.
+     */
+    isAccessTokenStale(thresholdMs?: number): boolean;
+    /**
+     * Refresh the access token, returning whether a valid one is now in place.
+     * Concurrent callers share one request, and the result is reused briefly so
+     * a burst of 401s costs a single round-trip.
+     *
+     * Safe to call directly — e.g. from a `visibilitychange` handler when
+     * {@link isAccessTokenStale} says the token is nearly up.
+     */
+    refreshAccessToken(): Promise<boolean>;
+    private canRefresh;
+    private performRefresh;
+    /** The expiry cookie in epoch milliseconds, or `null` when absent. */
+    private readExpiryCookie;
+    private readCookieString;
+}

package/dist/esm/auth/cookie-auth.js

@@ -0,0 +1,196 @@
+import { DooverAuth } from "./doover-auth.js";
+/** Default FusionAuth hosted-backend refresh endpoint. */
+const DEFAULT_REFRESH_PATH = "/app/refresh/";
+/** Default name of the cookie holding the access token's expiry (Unix seconds). */
+const DEFAULT_EXPIRY_COOKIE = "app.at_exp";
+/**
+ * How long a refresh result is reused. Collapses the burst of callers that all
+ * discover an expired token at the same moment (every queued request 401-ing
+ * after a tab wakes up), and — more importantly — stops a *failed* refresh from
+ * being retried in a tight loop.
+ */
+const ATTEMPT_TTL_MS = 5000;
+/**
+ * Cookie-based auth — the default browser strategy.
+ *
+ * Relies on ambient cookies (`credentials: "include"`) and does not add any
+ * `Authorization` header. The access token itself is httpOnly and invisible to
+ * JS; the only readable part of the session is a companion expiry cookie
+ * (`app.at_exp`).
+ *
+ * ## Why this refreshes
+ *
+ * The FusionAuth React SDK's auto-refresh is a single `setTimeout` per token.
+ * A browser that suspends the tab (backgrounded, laptop asleep) never fires it,
+ * so the tab wakes with an expired access-token cookie and every request 401s —
+ * even though the refresh token itself is usually still valid. Rather than
+ * leaving every browser app to work around that on its own, `CookieAuth`
+ * handles it whenever `authServerUrl` is configured: `ensureReady` renews an
+ * already-expired token before a request goes out (which also covers gateway
+ * reconnects, since `GatewayClient` awaits it before opening a socket), and
+ * `handleUnauthorized` lets `RestClient` replay a 401 once after a renewal.
+ */
+export class CookieAuth extends DooverAuth {
+    constructor(options = {}) {
+        super();
+        this.refreshInFlight = null;
+        this.lastAttempt = null;
+        this.authServerUrl = options.authServerUrl ?? null;
+        this.refreshPath = options.refreshPath ?? DEFAULT_REFRESH_PATH;
+        this.expiryCookieName =
+            options.accessTokenExpiryCookieName ?? DEFAULT_EXPIRY_COOKIE;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.cookieReader = options.cookieReader ?? null;
+    }
+    // ------------------------------------------------------------------
+    // DooverAuth interface
+    // ------------------------------------------------------------------
+    async getHttpHeaders() {
+        return {};
+    }
+    getFetchCredentials() {
+        return "include";
+    }
+    async prepareWebSocket(url, _canUseHeaders) {
+        // Cookie auth relies on ambient cookies — no URL or header changes.
+        return { url };
+    }
+    setToken(_token, _tokenExpires) {
+        // No-op for cookie auth — the token lives in an httpOnly cookie.
+    }
+    setRefreshToken(_refreshToken) {
+        // No-op for cookie auth — the refresh token lives in an httpOnly cookie.
+    }
+    /**
+     * Renew the access token when it has already expired, so the request that
+     * follows isn't a guaranteed 401. A token that is merely close to expiry is
+     * left alone: requests must not block on a refresh they don't need, and
+     * `handleUnauthorized` is there for the race.
+     */
+    async ensureReady() {
+        if (!this.canRefresh()) {
+            return;
+        }
+        if (this.isAccessTokenValid()) {
+            return;
+        }
+        // A failed refresh is not fatal here — let the request go out and be
+        // handled by `handleUnauthorized` / the caller's error handling.
+        await this.refreshAccessToken();
+    }
+    /**
+     * Called by `RestClient` after a 401. A successful refresh means the request
+     * is worth replaying once.
+     */
+    async handleUnauthorized() {
+        if (!this.canRefresh()) {
+            return false;
+        }
+        return this.refreshAccessToken();
+    }
+    // ------------------------------------------------------------------
+    // Public helpers — apps need these for their own lifecycle hooks
+    // ------------------------------------------------------------------
+    /** Expiry of the current access token, or `null` if there is no session. */
+    getAccessTokenExpiry() {
+        const expiryMs = this.readExpiryCookie();
+        return expiryMs == null ? null : new Date(expiryMs);
+    }
+    /** True when a session cookie exists and has not yet expired. */
+    isAccessTokenValid() {
+        const expiryMs = this.readExpiryCookie();
+        return expiryMs != null && expiryMs > Date.now();
+    }
+    /**
+     * True when the access token expires within `thresholdMs` (or already has).
+     * Apps use this to decide whether a `visibilitychange` is worth a proactive
+     * refresh. False when there is no session at all — nothing to refresh.
+     */
+    isAccessTokenStale(thresholdMs = 60000) {
+        const expiryMs = this.readExpiryCookie();
+        if (expiryMs == null) {
+            return false;
+        }
+        return expiryMs - Date.now() < thresholdMs;
+    }
+    /**
+     * Refresh the access token, returning whether a valid one is now in place.
+     * Concurrent callers share one request, and the result is reused briefly so
+     * a burst of 401s costs a single round-trip.
+     *
+     * Safe to call directly — e.g. from a `visibilitychange` handler when
+     * {@link isAccessTokenStale} says the token is nearly up.
+     */
+    async refreshAccessToken() {
+        if (!this.canRefresh()) {
+            return false;
+        }
+        if (this.refreshInFlight) {
+            return this.refreshInFlight;
+        }
+        // No expiry cookie means we were never logged in, or have since logged
+        // out. The refresh endpoint would just 400.
+        if (this.readExpiryCookie() == null) {
+            return false;
+        }
+        if (this.lastAttempt && Date.now() - this.lastAttempt.at < ATTEMPT_TTL_MS) {
+            return this.lastAttempt.result;
+        }
+        const inFlight = this.performRefresh().then((result) => {
+            this.lastAttempt = { result, at: Date.now() };
+            this.refreshInFlight = null;
+            return result;
+        });
+        this.refreshInFlight = inFlight;
+        return inFlight;
+    }
+    // ------------------------------------------------------------------
+    // Internal
+    // ------------------------------------------------------------------
+    canRefresh() {
+        return this.authServerUrl != null && this.authServerUrl !== "";
+    }
+    async performRefresh() {
+        const url = `${this.authServerUrl}${this.refreshPath}`;
+        try {
+            const response = await this.fetchImpl(url, {
+                method: "POST",
+                credentials: "include",
+                headers: { "Content-Type": "text/plain" },
+            });
+            return response.ok;
+        }
+        catch {
+            // Offline, DNS failure, blocked request — indistinguishable from here,
+            // and all mean "no new token".
+            return false;
+        }
+    }
+    /** The expiry cookie in epoch milliseconds, or `null` when absent. */
+    readExpiryCookie() {
+        const cookieString = this.readCookieString();
+        if (!cookieString) {
+            return null;
+        }
+        const match = cookieString.match(new RegExp(`(?:^|;\\s*)${escapeRegExp(this.expiryCookieName)}=([^;]+)`));
+        if (!match) {
+            return null;
+        }
+        // Stored as Unix *seconds* (matching the FusionAuth SDK's own parser);
+        // callers compare against Date.now(), so normalise to milliseconds.
+        const seconds = parseInt(decodeURIComponent(match[1]), 10);
+        return Number.isFinite(seconds) ? seconds * 1000 : null;
+    }
+    readCookieString() {
+        if (this.cookieReader) {
+            return this.cookieReader();
+        }
+        if (typeof document === "undefined") {
+            return null;
+        }
+        return document.cookie;
+    }
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/esm/auth/doover-auth.d.ts

@@ -0,0 +1,52 @@
+import type { AuthProfile } from "./auth-profile.js";
+import type { AuthProfileStore } from "./auth-store.js";
+/**
+ * Abstract base class shared by cookie and token auth strategies.
+ *
+ * Every client (`RestClient`, `GatewayClient`, `DooverDataProvider`) holds a
+ * reference to one `DooverAuth` instance so that refreshed tokens propagate
+ * everywhere automatically.
+ */
+export declare abstract class DooverAuth {
+    protected profile: AuthProfile | null;
+    protected configManager: AuthProfileStore | null;
+    /** Headers to merge into every outgoing HTTP request. */
+    abstract getHttpHeaders(): Promise<Record<string, string>>;
+    /** The `credentials` value for `fetch()`. */
+    abstract getFetchCredentials(): RequestCredentials;
+    /**
+     * Prepare websocket connection parameters.
+     *
+     * @param url          The base websocket URL.
+     * @param canUseHeaders `true` when a `webSocketFactory` that supports
+     *                       custom headers is available.
+     * @returns An object with the (possibly modified) URL and optional headers.
+     */
+    abstract prepareWebSocket(url: string, canUseHeaders: boolean): Promise<{
+        url: string;
+        headers?: Record<string, string>;
+    }>;
+    /**
+     * Imperatively set or clear the current access token.
+     * Subclasses that do not use tokens may no-op.
+     */
+    abstract setToken(token: string | null, tokenExpires?: Date | number | null): void;
+    /**
+     * Imperatively set or clear the refresh token. Subclasses that do not use
+     * refresh tokens may no-op.
+     */
+    abstract setRefreshToken(refreshToken: string | null): void;
+    /**
+     * Ensure the auth layer is ready (e.g. token refreshed if needed).
+     * Called before every HTTP request and before opening a websocket.
+     */
+    abstract ensureReady(): Promise<void>;
+    /**
+     * Called after an authenticated HTTP request receives a 401. Return true when
+     * the auth layer recovered (for example by forcing a token refresh) and the
+     * request should be retried once.
+     */
+    handleUnauthorized(): Promise<boolean>;
+    /** Attach a profile and optional config manager for refresh persistence. */
+    attachProfile(profile: AuthProfile, configManager?: AuthProfileStore): void;
+}

package/dist/esm/auth/doover-auth.js

@@ -0,0 +1,28 @@
+/**
+ * Abstract base class shared by cookie and token auth strategies.
+ *
+ * Every client (`RestClient`, `GatewayClient`, `DooverDataProvider`) holds a
+ * reference to one `DooverAuth` instance so that refreshed tokens propagate
+ * everywhere automatically.
+ */
+export class DooverAuth {
+    constructor() {
+        this.profile = null;
+        this.configManager = null;
+    }
+    /**
+     * Called after an authenticated HTTP request receives a 401. Return true when
+     * the auth layer recovered (for example by forcing a token refresh) and the
+     * request should be retried once.
+     */
+    async handleUnauthorized() {
+        return false;
+    }
+    /** Attach a profile and optional config manager for refresh persistence. */
+    attachProfile(profile, configManager) {
+        this.profile = profile;
+        if (configManager) {
+            this.configManager = configManager;
+        }
+    }
+}

package/dist/esm/auth/doover-token-auth.d.ts

@@ -0,0 +1,39 @@
+import { DooverAuth } from "./doover-auth.js";
+import type { AuthProfile } from "./auth-profile.js";
+import type { AuthProfileStore } from "./auth-store.js";
+export declare class DooverTokenAuth extends DooverAuth {
+    private token;
+    private tokenExpires;
+    private refreshToken;
+    private refreshTokenId;
+    private authServerUrl;
+    private authServerClientId;
+    private fetchImpl;
+    private refreshInFlight;
+    private authInvalid;
+    constructor(options: {
+        token?: string | null;
+        tokenExpires?: Date | number | null;
+        refreshToken?: string | null;
+        refreshTokenId?: string | null;
+        authServerUrl?: string | null;
+        authServerClientId?: string | null;
+        fetchImpl?: typeof fetch;
+    });
+    getHttpHeaders(): Promise<Record<string, string>>;
+    getFetchCredentials(): RequestCredentials;
+    prepareWebSocket(url: string, canUseHeaders: boolean): Promise<{
+        url: string;
+        headers?: Record<string, string>;
+    }>;
+    setToken(token: string | null, tokenExpires?: Date | number | null): void;
+    setRefreshToken(refreshToken: string | null): void;
+    ensureReady(): Promise<void>;
+    handleUnauthorized(): Promise<boolean>;
+    attachProfile(profile: AuthProfile, configManager?: AuthProfileStore): void;
+    private needsRefresh;
+    private refresh;
+    private persistToProfile;
+    private markAuthInvalid;
+    private resolveExpiry;
+}