doover-js 0.8.0 → 0.9.0

package/README.md

@@ -37,6 +37,43 @@ const client = new DooverClient({
 const channels = await client.viewer.getChannels({ agentId: "123" });
 ```
 
+### Cookie usage with session refresh (browser apps behind FusionAuth)
+
+Pass `authServerUrl` — and no token material — to get a `CookieAuth` that can
+renew the session itself. The client then POSTs the hosted-backend refresh
+endpoint (`/app/refresh/` by default) when the access token has expired: before
+a request goes out, and again if one comes back 401, replaying it once.
+
+This exists because the FusionAuth React SDK's auto-refresh is a single
+`setTimeout`. A tab the browser suspends (backgrounded, machine asleep) never
+fires it, so it wakes with a dead access-token cookie and 401s on everything —
+even though the refresh token itself is usually still valid.
+
+```ts
+const client = new DooverClient({
+  dataRestUrl: "https://example.com/api",
+  controlApiUrl: "https://example.com/control",
+  dataWssUrl: "wss://example.com/gateway",
+  authServerUrl: "https://auth.example.com",
+});
+```
+
+`CookieAuth` also exposes the session state apps need for their own lifecycle
+hooks — typically a proactive refresh when a tab regains visibility:
+
+```ts
+const auth = client.auth as CookieAuth;
+
+document.addEventListener("visibilitychange", () => {
+  if (document.visibilityState !== "visible") return;
+  if (!auth.isAccessTokenStale(5 * 60_000)) return;
+  void auth.refreshAccessToken();
+});
+```
+
+Without `authServerUrl`, `CookieAuth` behaves exactly as before: ambient
+cookies, no refresh.
+
 ### Explicit token usage
 
 Pass a token directly to use bearer auth. The client will send `Authorization: Bearer <token>` on every HTTP request and use `credentials: "omit"`.

package/dist/apis/agents-api.d.ts

@@ -19,6 +19,65 @@ export interface MultiAgentMessagesParams {
     agent_message_limit?: number;
     field_name?: string[];
 }
+/**
+ * One token-posture knob across all three layers, so a UI can show
+ * "inherited from organisation" vs "overridden on this device" and offer a reset
+ * without duplicating the precedence rule client-side.
+ */
+export interface TokenPolicyField<T> {
+    /** What is actually enforced: `agent_override` if set, else `org_default`. */
+    effective: T | null;
+    /** This device's override. `null` means it inherits. */
+    agent_override: T | null;
+    /** The organisation-wide default inherited when not overridden. */
+    org_default: T | null;
+}
+export interface AgentTokenState {
+    /**
+     * Unix-ms revocation floor: every long-lived credential issued before this is
+     * rejected. `null` means nothing has ever been revoked for this agent.
+     */
+    tokens_valid_from: number | null;
+    /** Auth kill-switch — while true, every auth attempt is rejected. */
+    auth_locked: boolean;
+    self_rotation: TokenPolicyField<boolean>;
+    max_age_ms: TokenPolicyField<number>;
+    reuse_grace_ms: TokenPolicyField<number>;
+}
+/**
+ * A token-posture override. `null` on any field means "inherit the organisation
+ * default"; there is no way to express "explicitly off, ignoring the default",
+ * because every knob here is off when absent.
+ */
+export interface AgentTokenPolicy {
+    /** Allow the device to trade its own credential for a fresh one. */
+    self_rotation?: boolean | null;
+    /**
+     * Hard maximum credential age. Only valid alongside `self_rotation` — without
+     * it the device cannot rotate before the deadline and will be locked out.
+     */
+    max_age_ms?: number | null;
+    /**
+     * Grace window after a rotation before a stale credential counts as reuse.
+     * Setting this opts the device into *automatic* lockout on reuse detection.
+     */
+    reuse_grace_ms?: number | null;
+}
+export interface ResourcePermission {
+    permission_id: string;
+    permission: string;
+}
+export interface AdhocTokenResponse {
+    /** Shown once. Not retrievable afterwards. */
+    token: string;
+    token_id: string | null;
+}
+export interface DeviceTokenResponse {
+    /** Shown once. Not stored anywhere and not retrievable afterwards. */
+    token: string;
+    /** Unix-ms issuance time, which is what the revocation floor compares against. */
+    issued_at_ms: number | null;
+}
 export interface MultiAgentAggregatesParams {
     agent_id: string[];
     /**
@@ -56,4 +115,82 @@ export declare class AgentsApi {
         results: AgentAggregate[];
         count: number;
     }>;
+    /**
+     * Read an agent's credential state: the revocation floor, the auth
+     * kill-switch, and the token posture resolved across the per-agent override
+     * and the organisation default.
+     *
+     * Requires `AgentTokenRead`, which is read-only — a caller can display
+     * credential state (including an auth-lock banner, often the only explanation
+     * for why a device is offline) without being able to change any of it.
+     */
+    getTokenState(agentId: string): Promise<AgentTokenState>;
+    /**
+     * Replace an agent's token-posture override. Omitted or null fields mean
+     * "inherit the organisation default" — a full replacement rather than a
+     * merge, so clearing an override back to inherited is expressible.
+     *
+     * Rejected server-side if the resolved posture sets `max_age_ms` without
+     * `self_rotation`: a device that can't self-rotate has no way to trade its
+     * token in before the max age elapses, making that combination a scheduled
+     * outage.
+     */
+    setTokenPolicy(agentId: string, policy: AgentTokenPolicy): Promise<{
+        effective: AgentTokenPolicy;
+    }>;
+    /**
+     * Set or clear the auth kill-switch. While locked, every auth attempt for the
+     * agent is rejected regardless of token validity.
+     *
+     * doover-data sets this automatically on suspected token reuse, so clearing it
+     * is a routine incident-response action rather than an exotic one.
+     */
+    setAuthLock(agentId: string, locked: boolean): Promise<void>;
+    /**
+     * Revoke every outstanding long-lived credential for an agent by advancing the
+     * revocation floor. Mints nothing.
+     *
+     * This takes the device offline until it is re-provisioned. Break-glass:
+     * confirm before calling.
+     */
+    revokeAllTokens(agentId: string): Promise<{
+        tokens_valid_from: number;
+    }>;
+    /**
+     * Set the revocation floor to an explicit point, in either direction. `0` or
+     * `null` clears it.
+     *
+     * `revokeAllTokens` is the normal way to revoke. Lowering the floor reverses a
+     * revocation, so it is for undoing one made by mistake — not for recovering
+     * from a leak, where you should issue fresh credentials instead.
+     */
+    setRevocationFloor(agentId: string, tokensValidFrom: number | null): Promise<{
+        tokens_valid_from: number | null;
+    }>;
+    /**
+     * Mint a short-lived scoped JWT for ad-hoc access to an agent — debugging, a
+     * one-off script, an integration.
+     *
+     * This is the way to give a *person* access to a device. The device's own
+     * long-lived credential is deliberately not obtainable through the API: it is
+     * minted into an installer bundle and never shown. Expiry stands in for
+     * revocation here, so keep `timeout` as short as the task allows.
+     */
+    createAdhocToken(agentId: string, options?: {
+        permissions?: ResourcePermission[];
+        timeout?: number;
+    }): Promise<AdhocTokenResponse>;
+    /**
+     * Mint the device's long-lived credential and return it once, for manual
+     * provisioning — pasting into a device's config by hand. The installer download
+     * mints one into the bundle for you; this is the equivalent for a device you're
+     * configuring yourself.
+     *
+     * Always additive: the revocation floor is left alone, so minting can never
+     * knock a running device offline. `revoke_existing` is intentionally not
+     * exposed here — revoking is `revokeAllTokens`, a separate deliberate act.
+     *
+     * Returned once and stored nowhere. If it's lost, mint another.
+     */
+    createDeviceToken(agentId: string): Promise<DeviceTokenResponse>;
 }

package/dist/apis/agents-api.js

@@ -232,6 +232,96 @@ class AgentsApi {
             count: responses.reduce((acc, r) => acc + r.count, 0),
         };
     }
+    /**
+     * Read an agent's credential state: the revocation floor, the auth
+     * kill-switch, and the token posture resolved across the per-agent override
+     * and the organisation default.
+     *
+     * Requires `AgentTokenRead`, which is read-only — a caller can display
+     * credential state (including an auth-lock banner, often the only explanation
+     * for why a device is offline) without being able to change any of it.
+     */
+    getTokenState(agentId) {
+        return this.rest.get(`/agents/${agentId}/token_state`);
+    }
+    /**
+     * Replace an agent's token-posture override. Omitted or null fields mean
+     * "inherit the organisation default" — a full replacement rather than a
+     * merge, so clearing an override back to inherited is expressible.
+     *
+     * Rejected server-side if the resolved posture sets `max_age_ms` without
+     * `self_rotation`: a device that can't self-rotate has no way to trade its
+     * token in before the max age elapses, making that combination a scheduled
+     * outage.
+     */
+    setTokenPolicy(agentId, policy) {
+        return this.rest.put(`/agents/${agentId}/token_policy`, policy);
+    }
+    /**
+     * Set or clear the auth kill-switch. While locked, every auth attempt for the
+     * agent is rejected regardless of token validity.
+     *
+     * doover-data sets this automatically on suspected token reuse, so clearing it
+     * is a routine incident-response action rather than an exotic one.
+     */
+    setAuthLock(agentId, locked) {
+        return this.rest.post(`/agents/${agentId}/auth_lock`, { locked });
+    }
+    /**
+     * Revoke every outstanding long-lived credential for an agent by advancing the
+     * revocation floor. Mints nothing.
+     *
+     * This takes the device offline until it is re-provisioned. Break-glass:
+     * confirm before calling.
+     */
+    revokeAllTokens(agentId) {
+        return this.rest.post(`/agents/${agentId}/token/revoke_all`, {});
+    }
+    /**
+     * Set the revocation floor to an explicit point, in either direction. `0` or
+     * `null` clears it.
+     *
+     * `revokeAllTokens` is the normal way to revoke. Lowering the floor reverses a
+     * revocation, so it is for undoing one made by mistake — not for recovering
+     * from a leak, where you should issue fresh credentials instead.
+     */
+    setRevocationFloor(agentId, tokensValidFrom) {
+        return this.rest.post(`/agents/${agentId}/token/floor`, { tokens_valid_from: tokensValidFrom });
+    }
+    /**
+     * Mint a short-lived scoped JWT for ad-hoc access to an agent — debugging, a
+     * one-off script, an integration.
+     *
+     * This is the way to give a *person* access to a device. The device's own
+     * long-lived credential is deliberately not obtainable through the API: it is
+     * minted into an installer bundle and never shown. Expiry stands in for
+     * revocation here, so keep `timeout` as short as the task allows.
+     */
+    createAdhocToken(agentId, options = {}) {
+        return this.rest.post(`/agents/${agentId}/token`, {
+            format: "jwt",
+            permissions: options.permissions ?? [],
+            timeout: options.timeout,
+        });
+    }
+    /**
+     * Mint the device's long-lived credential and return it once, for manual
+     * provisioning — pasting into a device's config by hand. The installer download
+     * mints one into the bundle for you; this is the equivalent for a device you're
+     * configuring yourself.
+     *
+     * Always additive: the revocation floor is left alone, so minting can never
+     * knock a running device offline. `revoke_existing` is intentionally not
+     * exposed here — revoking is `revokeAllTokens`, a separate deliberate act.
+     *
+     * Returned once and stored nowhere. If it's lost, mint another.
+     */
+    createDeviceToken(agentId) {
+        return this.rest.post(`/agents/${agentId}/token`, {
+            format: "mini_v1",
+            revoke_existing: false,
+        });
+    }
 }
 exports.AgentsApi = AgentsApi;
 // CloudFront fronts the channels-rest API with a hard 8,192-byte URL quota.

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

@@ -28,10 +28,11 @@ interface BuildAuthOptions extends AuthConfig {
  *
  * Rules:
  * 1. If `auth` is provided it is returned as-is.
- * 2. If any token-related field is present, build `DooverTokenAuth`.
+ * 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`.
+ * 5. Otherwise fall back to `CookieAuth`, refresh-capable when
+ *    `authServerUrl` is known.
  */
 export declare function buildAuth(options: BuildAuthOptions): DooverAuth;
 export {};

package/dist/auth/build-auth.js

@@ -12,15 +12,31 @@ const TOKEN_FIELDS = [
     "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-related field is present, build `DooverTokenAuth`.
+ * 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`.
+ * 5. Otherwise fall back to `CookieAuth`, refresh-capable when
+ *    `authServerUrl` is known.
  */
 function buildAuth(options) {
     if (options.auth) {
@@ -48,11 +64,15 @@ function buildAuth(options) {
         resolvedProfile = options.profile;
     }
     // Determine whether we need token auth.
-    const hasTokenInput = TOKEN_FIELDS.some((k) => options[k] !== undefined);
+    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.
-        const auth = new cookie_auth_1.CookieAuth();
+        // 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 cookie_auth_1.CookieAuth({
+            authServerUrl: options.authServerUrl ?? resolvedProfile?.authServerUrl ?? null,
+            fetchImpl: options.fetchImpl,
+        });
         if (resolvedProfile) {
             auth.attachProfile(resolvedProfile, options.configManager);
         }

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

@@ -1,11 +1,49 @@
 import { DooverAuth } from "./doover-auth";
+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. Token refresh is not applicable.
+ * `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<{
@@ -14,5 +52,40 @@ export declare class CookieAuth extends DooverAuth {
     }>;
     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/auth/cookie-auth.js

@@ -2,13 +2,52 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CookieAuth = void 0;
 const doover_auth_1 = require("./doover-auth");
+/** 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. Token refresh is not applicable.
+ * `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.
  */
 class CookieAuth extends doover_auth_1.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 {};
     }
@@ -20,13 +59,142 @@ class CookieAuth extends doover_auth_1.DooverAuth {
         return { url };
     }
     setToken(_token, _tokenExpires) {
-        // No-op for cookie auth.
+        // No-op for cookie auth — the token lives in an httpOnly cookie.
     }
     setRefreshToken(_refreshToken) {
-        // No-op for cookie auth.
+        // 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() {
-        // Nothing to prepare for cookie auth.
+        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;
     }
 }
 exports.CookieAuth = CookieAuth;
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/client/capabilities.d.ts

@@ -6,5 +6,5 @@
  * String-literal union (not a TS enum) so values serialise cleanly and can
  * appear in error messages / debug UIs verbatim.
  */
-export type Capability = "agents.list" | "agents.multiAgentMessages" | "agents.multiAgentAggregates" | "channels.list" | "channels.get" | "channels.create" | "channels.archive" | "channels.dataSeries" | "aggregates.get" | "aggregates.put" | "aggregates.patch" | "aggregates.attachment" | "messages.list" | "messages.listHistorical" | "messages.get" | "messages.post" | "messages.put" | "messages.delete" | "messages.attachment" | "messages.timeseries" | "messages.invocationLogs" | "gateway.subscribe" | "gateway.realtime" | "gateway.oneShot" | "rpc.send" | "alarms.read" | "alarms.write" | "connections.read" | "connections.write" | "notifications.read" | "notifications.write" | "permissions.read" | "permissions.write" | "processors.read" | "processors.write" | "turn.credentials" | "users.me";
+export type Capability = "agents.list" | "agents.multiAgentMessages" | "agents.multiAgentAggregates" | "agents.tokenRead" | "agents.tokenManage" | "channels.list" | "channels.get" | "channels.create" | "channels.archive" | "channels.dataSeries" | "aggregates.get" | "aggregates.put" | "aggregates.patch" | "aggregates.attachment" | "messages.list" | "messages.listHistorical" | "messages.get" | "messages.post" | "messages.put" | "messages.delete" | "messages.attachment" | "messages.timeseries" | "messages.invocationLogs" | "gateway.subscribe" | "gateway.realtime" | "gateway.oneShot" | "rpc.send" | "alarms.read" | "alarms.write" | "connections.read" | "connections.write" | "notifications.read" | "notifications.write" | "permissions.read" | "permissions.write" | "processors.read" | "processors.write" | "turn.credentials" | "users.me";
 export declare const ALL_CAPABILITIES: readonly Capability[];

package/dist/client/capabilities.js

@@ -5,6 +5,8 @@ exports.ALL_CAPABILITIES = [
     "agents.list",
     "agents.multiAgentMessages",
     "agents.multiAgentAggregates",
+    "agents.tokenRead",
+    "agents.tokenManage",
     "channels.list",
     "channels.get",
     "channels.create",

package/dist/client/local-agent-client.js

@@ -183,6 +183,13 @@ const METHOD_TO_CAPABILITY = {
     "agents.listAgents": "agents.list",
     "agents.getMultiAgentMessages": "agents.multiAgentMessages",
     "agents.getMultiAgentAggregates": "agents.multiAgentAggregates",
+    "agents.getTokenState": "agents.tokenRead",
+    "agents.setTokenPolicy": "agents.tokenManage",
+    "agents.setAuthLock": "agents.tokenManage",
+    "agents.revokeAllTokens": "agents.tokenManage",
+    "agents.setRevocationFloor": "agents.tokenManage",
+    "agents.createAdhocToken": "agents.tokenManage",
+    "agents.createDeviceToken": "agents.tokenManage",
     "channels.listChannels": "channels.list",
     "channels.getChannel": "channels.get",
     "channels.createChannel": "channels.create",

package/dist/client/multiplex-client.js

@@ -660,6 +660,13 @@ class MultiplexClient {
                 const merged = (0, multiplex_merge_1.dedupeBy)([].concat(...responses.map((r) => r.results)), (a) => a.agent_id);
                 return { results: merged, count: merged.length };
             },
+            getTokenState: self.makeFanoutFirst("agents.getTokenState", "agents.tokenRead"),
+            setTokenPolicy: self.routedWrite("agents.setTokenPolicy", "agents.tokenManage"),
+            setAuthLock: self.routedWrite("agents.setAuthLock", "agents.tokenManage"),
+            revokeAllTokens: self.routedWrite("agents.revokeAllTokens", "agents.tokenManage"),
+            setRevocationFloor: self.routedWrite("agents.setRevocationFloor", "agents.tokenManage"),
+            createAdhocToken: self.routedWrite("agents.createAdhocToken", "agents.tokenManage"),
+            createDeviceToken: self.routedWrite("agents.createDeviceToken", "agents.tokenManage"),
         };
     }
     // ===== non-core generic facade =====

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { getDooverClient, peekDooverClient, resetDooverClient, } from "./client/
 export { DooverStatsCollector } from "./client/stats";
 export type { DooverStatsSnapshot, RestStatsSnapshot, GatewayStatsSnapshot, } from "./client/stats";
 export { AgentsApi } from "./apis/agents-api";
+export type { AgentTokenState, AgentTokenPolicy, TokenPolicyField, AdhocTokenResponse, DeviceTokenResponse, ResourcePermission, } from "./apis/agents-api";
 export { AggregatesApi } from "./apis/aggregates-api";
 export { AlarmsApi } from "./apis/alarms-api";
 export { ChannelsApi } from "./apis/channels-api";
@@ -37,6 +38,7 @@ export type { DataClient, AgentScope, DataClientStatus, DataClientConnectionStat
 export type { SourceProvenance, SourceProvenanceViaRest, SourceProvenanceViaGateway, } from "./types/provenance";
 export { DooverAuth } from "./auth/doover-auth";
 export { CookieAuth } from "./auth/cookie-auth";
+export type { CookieAuthOptions } from "./auth/cookie-auth";
 export { DooverTokenAuth } from "./auth/doover-token-auth";
 export { AuthProfile } from "./auth/auth-profile";
 export type { AuthProfileData } from "./auth/auth-profile";

package/dist/react/index.d.ts

@@ -33,4 +33,6 @@ export type { UseMultiAgentChannelMessagesOptions, UseMultiAgentChannelMessagesR
 export { useDeviceMap } from "./useDeviceMap";
 export type { DeviceMapEntry, UseDeviceMapOptions, UseDeviceMapResult, } from "./useDeviceMap";
 export { useTurnCredentials } from "./useTurnCredentials";
+export { useAgentTokenState, useSetAgentTokenPolicy, useSetAgentAuthLock, useRevokeAgentTokens, useSetRevocationFloor, useCreateAdhocToken, useCreateDeviceToken, agentTokenStateQueryKey, } from "./useAgentTokenState";
+export type { UseAgentTokenStateOptions } from "./useAgentTokenState";
 export { getSharedQueryClient, resetSharedQueryClient, } from "./sharedQueryClient";

package/dist/react/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resetSharedQueryClient = exports.getSharedQueryClient = exports.useTurnCredentials = exports.useDeviceMap = exports.multiAgentChannelMessagesQueryKey = exports.useMultiAgentChannelMessages = exports.multiAgentAggregatesQueryKey = exports.useMultiAgentAggregates = exports.useSendRpc = exports.invocationLogsQueryKey = exports.useInvocationLogs = exports.channelMessageQueryKey = exports.useChannelMessage = exports.channelMessagesQueryKey = exports.useChannelMessages = exports.useUpdateMessage = exports.useUpdateAggregate = exports.useSendMessage = exports.useAgentChannel = exports.channelAggregateQueryKey = exports.useChannelAggregate = exports.useChannelSubscription = exports.agentConnectionsQueryKey = exports.useAgentConnections = exports.useConnectionState = exports.hasOfflineStatus = exports.useOfflineStatus = exports.useClientStatus = exports.useDooverClient = exports.DooverProvider = void 0;
+exports.resetSharedQueryClient = exports.getSharedQueryClient = exports.agentTokenStateQueryKey = exports.useCreateDeviceToken = exports.useCreateAdhocToken = exports.useSetRevocationFloor = exports.useRevokeAgentTokens = exports.useSetAgentAuthLock = exports.useSetAgentTokenPolicy = exports.useAgentTokenState = exports.useTurnCredentials = exports.useDeviceMap = exports.multiAgentChannelMessagesQueryKey = exports.useMultiAgentChannelMessages = exports.multiAgentAggregatesQueryKey = exports.useMultiAgentAggregates = exports.useSendRpc = exports.invocationLogsQueryKey = exports.useInvocationLogs = exports.channelMessageQueryKey = exports.useChannelMessage = exports.channelMessagesQueryKey = exports.useChannelMessages = exports.useUpdateMessage = exports.useUpdateAggregate = exports.useSendMessage = exports.useAgentChannel = exports.channelAggregateQueryKey = exports.useChannelAggregate = exports.useChannelSubscription = exports.agentConnectionsQueryKey = exports.useAgentConnections = exports.useConnectionState = exports.hasOfflineStatus = exports.useOfflineStatus = exports.useClientStatus = exports.useDooverClient = exports.DooverProvider = void 0;
 var context_1 = require("./context");
 Object.defineProperty(exports, "DooverProvider", { enumerable: true, get: function () { return context_1.DooverProvider; } });
 Object.defineProperty(exports, "useDooverClient", { enumerable: true, get: function () { return context_1.useDooverClient; } });
@@ -48,6 +48,15 @@ var useDeviceMap_1 = require("./useDeviceMap");
 Object.defineProperty(exports, "useDeviceMap", { enumerable: true, get: function () { return useDeviceMap_1.useDeviceMap; } });
 var useTurnCredentials_1 = require("./useTurnCredentials");
 Object.defineProperty(exports, "useTurnCredentials", { enumerable: true, get: function () { return useTurnCredentials_1.useTurnCredentials; } });
+var useAgentTokenState_1 = require("./useAgentTokenState");
+Object.defineProperty(exports, "useAgentTokenState", { enumerable: true, get: function () { return useAgentTokenState_1.useAgentTokenState; } });
+Object.defineProperty(exports, "useSetAgentTokenPolicy", { enumerable: true, get: function () { return useAgentTokenState_1.useSetAgentTokenPolicy; } });
+Object.defineProperty(exports, "useSetAgentAuthLock", { enumerable: true, get: function () { return useAgentTokenState_1.useSetAgentAuthLock; } });
+Object.defineProperty(exports, "useRevokeAgentTokens", { enumerable: true, get: function () { return useAgentTokenState_1.useRevokeAgentTokens; } });
+Object.defineProperty(exports, "useSetRevocationFloor", { enumerable: true, get: function () { return useAgentTokenState_1.useSetRevocationFloor; } });
+Object.defineProperty(exports, "useCreateAdhocToken", { enumerable: true, get: function () { return useAgentTokenState_1.useCreateAdhocToken; } });
+Object.defineProperty(exports, "useCreateDeviceToken", { enumerable: true, get: function () { return useAgentTokenState_1.useCreateDeviceToken; } });
+Object.defineProperty(exports, "agentTokenStateQueryKey", { enumerable: true, get: function () { return useAgentTokenState_1.agentTokenStateQueryKey; } });
 var sharedQueryClient_1 = require("./sharedQueryClient");
 Object.defineProperty(exports, "getSharedQueryClient", { enumerable: true, get: function () { return sharedQueryClient_1.getSharedQueryClient; } });
 Object.defineProperty(exports, "resetSharedQueryClient", { enumerable: true, get: function () { return sharedQueryClient_1.resetSharedQueryClient; } });

package/dist/react/useAgentTokenState.d.ts

@@ -0,0 +1,70 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { AgentTokenPolicy, AgentTokenState, ResourcePermission } from "../apis/agents-api";
+export declare function agentTokenStateQueryKey(agentId: string | undefined): readonly ["doover", "agent", string | null, "tokenState"];
+export interface UseAgentTokenStateOptions {
+    enabled?: boolean;
+    staleTime?: number;
+}
+/**
+ * Read an agent's credential state — revocation floor, auth kill-switch, and the
+ * token posture resolved across the per-agent override and organisation default.
+ *
+ * Deliberately short `staleTime`: `auth_locked` can be flipped by doover-data
+ * itself (automatic lockout on suspected token reuse), so this value changes
+ * without any action from this client. Showing a stale "not locked" on the one
+ * screen someone opens *because* their device went offline would be worse than
+ * an extra fetch.
+ */
+export declare function useAgentTokenState(agentId: string | undefined, options?: UseAgentTokenStateOptions): UseQueryResult<AgentTokenState>;
+/**
+ * Write an agent's token-posture override. Full replacement — a null field means
+ * "inherit the organisation default".
+ *
+ * Invalidates the token-state query on success so the inherited-vs-overridden
+ * display reflects the write without the caller wiring that up.
+ */
+export declare function useSetAgentTokenPolicy(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<{
+    effective: AgentTokenPolicy;
+}, Error, AgentTokenPolicy, unknown>;
+/** Set or clear the auth kill-switch. */
+export declare function useSetAgentAuthLock(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<void, Error, boolean, unknown>;
+/**
+ * Mint a short-lived scoped token for ad-hoc access to an agent.
+ *
+ * Does not invalidate the token-state query: an ad-hoc token is a JWT with its
+ * own expiry and doesn't touch the revocation floor or the agent's posture, so
+ * there is nothing in that query for it to change.
+ *
+ * The resulting token is returned once and is not retrievable afterwards — hand
+ * it straight to the user and don't cache it.
+ */
+export declare function useCreateAdhocToken(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<import("../apis/agents-api").AdhocTokenResponse, Error, {
+    permissions?: ResourcePermission[];
+    timeout?: number;
+}, unknown>;
+/**
+ * Set the revocation floor to an explicit point; pass `0` or `null` to clear it.
+ *
+ * Lowering it reverses a revocation, so this is for undoing one made by mistake
+ * rather than for recovering a device whose credentials leaked.
+ */
+export declare function useSetRevocationFloor(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<{
+    tokens_valid_from: number | null;
+}, Error, number | null, unknown>;
+/**
+ * Mint the device's long-lived credential for manual provisioning, returned once.
+ *
+ * Invalidates the token-state query so the revocation floor display stays honest
+ * — the mint itself is additive and doesn't move the floor, but refetching keeps
+ * this in step with anything else that has changed since the panel loaded.
+ */
+export declare function useCreateDeviceToken(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<import("../apis/agents-api").DeviceTokenResponse, Error, void, unknown>;
+/**
+ * Revoke every outstanding long-lived credential for an agent.
+ *
+ * Break-glass: the device stays offline until it is re-provisioned. Confirm with
+ * the user before calling.
+ */
+export declare function useRevokeAgentTokens(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<{
+    tokens_valid_from: number;
+}, Error, void, unknown>;

package/dist/react/useAgentTokenState.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentTokenStateQueryKey = agentTokenStateQueryKey;
+exports.useAgentTokenState = useAgentTokenState;
+exports.useSetAgentTokenPolicy = useSetAgentTokenPolicy;
+exports.useSetAgentAuthLock = useSetAgentAuthLock;
+exports.useCreateAdhocToken = useCreateAdhocToken;
+exports.useSetRevocationFloor = useSetRevocationFloor;
+exports.useCreateDeviceToken = useCreateDeviceToken;
+exports.useRevokeAgentTokens = useRevokeAgentTokens;
+const react_query_1 = require("@tanstack/react-query");
+const context_1 = require("./context");
+function agentTokenStateQueryKey(agentId) {
+    return ["doover", "agent", agentId ?? null, "tokenState"];
+}
+/**
+ * Read an agent's credential state — revocation floor, auth kill-switch, and the
+ * token posture resolved across the per-agent override and organisation default.
+ *
+ * Deliberately short `staleTime`: `auth_locked` can be flipped by doover-data
+ * itself (automatic lockout on suspected token reuse), so this value changes
+ * without any action from this client. Showing a stale "not locked" on the one
+ * screen someone opens *because* their device went offline would be worse than
+ * an extra fetch.
+ */
+function useAgentTokenState(agentId, options) {
+    const client = (0, context_1.useDooverClient)();
+    return (0, react_query_1.useQuery)({
+        queryKey: agentTokenStateQueryKey(agentId),
+        enabled: (options?.enabled ?? true) && Boolean(agentId),
+        staleTime: options?.staleTime ?? 15 * 1000,
+        queryFn: () => client.agents.getTokenState(agentId),
+    });
+}
+/**
+ * Write an agent's token-posture override. Full replacement — a null field means
+ * "inherit the organisation default".
+ *
+ * Invalidates the token-state query on success so the inherited-vs-overridden
+ * display reflects the write without the caller wiring that up.
+ */
+function useSetAgentTokenPolicy(agentId) {
+    const client = (0, context_1.useDooverClient)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: (policy) => client.agents.setTokenPolicy(agentId, policy),
+        onSuccess: () => {
+            void queryClient.invalidateQueries({
+                queryKey: agentTokenStateQueryKey(agentId),
+            });
+        },
+    });
+}
+/** Set or clear the auth kill-switch. */
+function useSetAgentAuthLock(agentId) {
+    const client = (0, context_1.useDooverClient)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: (locked) => client.agents.setAuthLock(agentId, locked),
+        onSuccess: () => {
+            void queryClient.invalidateQueries({
+                queryKey: agentTokenStateQueryKey(agentId),
+            });
+        },
+    });
+}
+/**
+ * Mint a short-lived scoped token for ad-hoc access to an agent.
+ *
+ * Does not invalidate the token-state query: an ad-hoc token is a JWT with its
+ * own expiry and doesn't touch the revocation floor or the agent's posture, so
+ * there is nothing in that query for it to change.
+ *
+ * The resulting token is returned once and is not retrievable afterwards — hand
+ * it straight to the user and don't cache it.
+ */
+function useCreateAdhocToken(agentId) {
+    const client = (0, context_1.useDooverClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: (options) => client.agents.createAdhocToken(agentId, options),
+    });
+}
+/**
+ * Set the revocation floor to an explicit point; pass `0` or `null` to clear it.
+ *
+ * Lowering it reverses a revocation, so this is for undoing one made by mistake
+ * rather than for recovering a device whose credentials leaked.
+ */
+function useSetRevocationFloor(agentId) {
+    const client = (0, context_1.useDooverClient)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: (tokensValidFrom) => client.agents.setRevocationFloor(agentId, tokensValidFrom),
+        onSuccess: () => {
+            void queryClient.invalidateQueries({
+                queryKey: agentTokenStateQueryKey(agentId),
+            });
+        },
+    });
+}
+/**
+ * Mint the device's long-lived credential for manual provisioning, returned once.
+ *
+ * Invalidates the token-state query so the revocation floor display stays honest
+ * — the mint itself is additive and doesn't move the floor, but refetching keeps
+ * this in step with anything else that has changed since the panel loaded.
+ */
+function useCreateDeviceToken(agentId) {
+    const client = (0, context_1.useDooverClient)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: () => client.agents.createDeviceToken(agentId),
+        onSuccess: () => {
+            void queryClient.invalidateQueries({
+                queryKey: agentTokenStateQueryKey(agentId),
+            });
+        },
+    });
+}
+/**
+ * Revoke every outstanding long-lived credential for an agent.
+ *
+ * Break-glass: the device stays offline until it is re-provisioned. Confirm with
+ * the user before calling.
+ */
+function useRevokeAgentTokens(agentId) {
+    const client = (0, context_1.useDooverClient)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationFn: () => client.agents.revokeAllTokens(agentId),
+        onSuccess: () => {
+            void queryClient.invalidateQueries({
+                queryKey: agentTokenStateQueryKey(agentId),
+            });
+        },
+    });
+}

package/dist/test/auth.test.js

@@ -50,6 +50,21 @@ class MemoryProfileStore {
     }
 }
 // ---------------------------------------------------------------------------
+// Helpers: cookie-auth session state
+// ---------------------------------------------------------------------------
+/** An `app.at_exp` cookie string expiring `secondsFromNow` from now. */
+function expiryCookie(secondsFromNow) {
+    return `app.at_exp=${Math.floor(Date.now() / 1000) + secondsFromNow}`;
+}
+/** A refresh-capable CookieAuth over a fixed cookie string. */
+function cookieAuth(options) {
+    return new cookie_auth_1.CookieAuth({
+        authServerUrl: "https://auth.example.com",
+        fetchImpl: (options.fetchMock ?? (0, helpers_1.createFetchMock)()),
+        cookieReader: () => options.cookie,
+    });
+}
+// ---------------------------------------------------------------------------
 // CookieAuth
 // ---------------------------------------------------------------------------
 (0, mocha_1.describe)("CookieAuth", () => {
@@ -67,6 +82,127 @@ class MemoryProfileStore {
         const auth = new cookie_auth_1.CookieAuth();
         await auth.ensureReady(); // should not throw
     });
+    (0, mocha_1.it)("does not refresh when no authServerUrl is configured", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)();
+        const auth = new cookie_auth_1.CookieAuth({
+            fetchImpl: fetchMock,
+            cookieReader: () => expiryCookie(-60),
+        });
+        (0, chai_1.expect)(await auth.handleUnauthorized()).to.equal(false);
+        await auth.ensureReady();
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(0);
+    });
+    // -- Session inspection ---------------------------------------------------
+    (0, mocha_1.it)("reads the expiry cookie", () => {
+        const auth = cookieAuth({ cookie: expiryCookie(3600) });
+        (0, chai_1.expect)(auth.isAccessTokenValid()).to.equal(true);
+        (0, chai_1.expect)(auth.isAccessTokenStale()).to.equal(false);
+        (0, chai_1.expect)(auth.getAccessTokenExpiry()).to.be.instanceOf(Date);
+    });
+    (0, mocha_1.it)("treats an expired cookie as invalid but refreshable", () => {
+        const auth = cookieAuth({ cookie: expiryCookie(-60) });
+        (0, chai_1.expect)(auth.isAccessTokenValid()).to.equal(false);
+        (0, chai_1.expect)(auth.isAccessTokenStale()).to.equal(true);
+    });
+    (0, mocha_1.it)("reports a near-expiry token as stale while still valid", () => {
+        const auth = cookieAuth({ cookie: expiryCookie(60) });
+        (0, chai_1.expect)(auth.isAccessTokenValid()).to.equal(true);
+        (0, chai_1.expect)(auth.isAccessTokenStale(5 * 60000)).to.equal(true);
+    });
+    (0, mocha_1.it)("reports no session when the cookie is absent", () => {
+        const auth = cookieAuth({ cookie: "other=1" });
+        (0, chai_1.expect)(auth.getAccessTokenExpiry()).to.equal(null);
+        (0, chai_1.expect)(auth.isAccessTokenValid()).to.equal(false);
+        // Nothing to refresh — must not read as "stale".
+        (0, chai_1.expect)(auth.isAccessTokenStale()).to.equal(false);
+    });
+    (0, mocha_1.it)("ignores a non-numeric expiry cookie", () => {
+        const auth = cookieAuth({ cookie: "app.at_exp=garbage" });
+        (0, chai_1.expect)(auth.getAccessTokenExpiry()).to.equal(null);
+        (0, chai_1.expect)(auth.isAccessTokenValid()).to.equal(false);
+    });
+    (0, mocha_1.it)("honours a custom expiry cookie name", () => {
+        const auth = new cookie_auth_1.CookieAuth({
+            authServerUrl: "https://auth.example.com",
+            accessTokenExpiryCookieName: "custom.exp",
+            cookieReader: () => `custom.exp=${Math.floor(Date.now() / 1000) + 3600}`,
+        });
+        (0, chai_1.expect)(auth.isAccessTokenValid()).to.equal(true);
+    });
+    // -- Refresh behaviour ----------------------------------------------------
+    (0, mocha_1.it)("refreshes an expired token via the hosted-backend endpoint", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({}));
+        const auth = cookieAuth({ cookie: expiryCookie(-60), fetchMock });
+        (0, chai_1.expect)(await auth.handleUnauthorized()).to.equal(true);
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(1);
+        (0, chai_1.expect)(fetchMock.firstCall.args[0]).to.equal("https://auth.example.com/app/refresh/");
+        const init = fetchMock.firstCall.args[1];
+        (0, chai_1.expect)(init.method).to.equal("POST");
+        (0, chai_1.expect)(init.credentials).to.equal("include");
+    });
+    (0, mocha_1.it)("honours a custom refresh path", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({}));
+        const auth = new cookie_auth_1.CookieAuth({
+            authServerUrl: "https://auth.example.com",
+            refreshPath: "/proxy/renew",
+            fetchImpl: fetchMock,
+            cookieReader: () => expiryCookie(-60),
+        });
+        await auth.refreshAccessToken();
+        (0, chai_1.expect)(fetchMock.firstCall.args[0]).to.equal("https://auth.example.com/proxy/renew");
+    });
+    (0, mocha_1.it)("reports failure when the refresh endpoint rejects", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({}, { status: 400 }));
+        const auth = cookieAuth({ cookie: expiryCookie(-60), fetchMock });
+        (0, chai_1.expect)(await auth.handleUnauthorized()).to.equal(false);
+    });
+    (0, mocha_1.it)("reports failure when the refresh request throws", async () => {
+        const fetchMock = sinon_1.default.stub().rejects(new Error("offline"));
+        const auth = cookieAuth({ cookie: expiryCookie(-60), fetchMock });
+        (0, chai_1.expect)(await auth.handleUnauthorized()).to.equal(false);
+    });
+    (0, mocha_1.it)("skips the refresh call when there is no session cookie", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({}));
+        const auth = cookieAuth({ cookie: "", fetchMock });
+        (0, chai_1.expect)(await auth.handleUnauthorized()).to.equal(false);
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(0);
+    });
+    (0, mocha_1.it)("collapses concurrent refreshes onto one request", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({}));
+        const auth = cookieAuth({ cookie: expiryCookie(-60), fetchMock });
+        const results = await Promise.all([
+            auth.handleUnauthorized(),
+            auth.handleUnauthorized(),
+            auth.handleUnauthorized(),
+        ]);
+        (0, chai_1.expect)(results).to.deep.equal([true, true, true]);
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(1);
+    });
+    (0, mocha_1.it)("reuses a recent failure instead of retrying in a loop", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({}, { status: 400 }));
+        const auth = cookieAuth({ cookie: expiryCookie(-60), fetchMock });
+        (0, chai_1.expect)(await auth.handleUnauthorized()).to.equal(false);
+        (0, chai_1.expect)(await auth.handleUnauthorized()).to.equal(false);
+        (0, chai_1.expect)(await auth.handleUnauthorized()).to.equal(false);
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(1);
+    });
+    (0, mocha_1.it)("ensureReady refreshes an expired token before the request goes out", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({}));
+        const auth = cookieAuth({ cookie: expiryCookie(-60), fetchMock });
+        await auth.ensureReady();
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(1);
+    });
+    (0, mocha_1.it)("ensureReady leaves a valid token alone", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({}));
+        const auth = cookieAuth({ cookie: expiryCookie(30), fetchMock });
+        await auth.ensureReady();
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(0);
+    });
+    (0, mocha_1.it)("ensureReady does not reject when the refresh fails", async () => {
+        const fetchMock = sinon_1.default.stub().rejects(new Error("offline"));
+        const auth = cookieAuth({ cookie: expiryCookie(-60), fetchMock });
+        await auth.ensureReady(); // should not throw
+    });
 });
 // ---------------------------------------------------------------------------
 // DooverTokenAuth
@@ -310,6 +446,24 @@ class MemoryProfileStore {
     (0, mocha_1.it)("builds CookieAuth when no token-related input is present", () => {
         (0, chai_1.expect)((0, build_auth_1.buildAuth)({})).to.be.instanceOf(cookie_auth_1.CookieAuth);
     });
+    (0, mocha_1.it)("builds a refresh-capable CookieAuth from authServerUrl alone", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({}));
+        const auth = (0, build_auth_1.buildAuth)({
+            authServerUrl: "https://auth.example.com",
+            fetchImpl: fetchMock,
+        });
+        // authServerUrl says where to refresh; it is not token material, so this
+        // stays cookie auth rather than becoming a tokenless DooverTokenAuth.
+        (0, chai_1.expect)(auth).to.be.instanceOf(cookie_auth_1.CookieAuth);
+        (0, chai_1.expect)(await auth.handleUnauthorized()).to.equal(false); // no session cookie
+    });
+    (0, mocha_1.it)("still builds DooverTokenAuth when token material accompanies authServerUrl", () => {
+        const auth = (0, build_auth_1.buildAuth)({
+            authServerUrl: "https://auth.example.com",
+            refreshToken: "rt",
+        });
+        (0, chai_1.expect)(auth).to.be.instanceOf(doover_token_auth_1.DooverTokenAuth);
+    });
     (0, mocha_1.it)("builds DooverTokenAuth when token is provided", () => {
         const auth = (0, build_auth_1.buildAuth)({ token: "tok" });
         (0, chai_1.expect)(auth).to.be.instanceOf(doover_token_auth_1.DooverTokenAuth);
@@ -506,6 +660,39 @@ class MemoryProfileStore {
         (0, chai_1.expect)(headers.get("Authorization")).to.equal(null);
         (0, chai_1.expect)(init?.credentials).to.equal("include");
     });
+    (0, mocha_1.it)("refreshes and replays a 401 with refresh-capable cookie auth", async () => {
+        let itemsCalls = 0;
+        const fetchMock = (0, helpers_1.createFetchMock)((url) => {
+            if (url === "https://auth.example.com/app/refresh/") {
+                return (0, helpers_1.createJsonResponse)({});
+            }
+            itemsCalls += 1;
+            // First attempt uses the dead cookie; the replay succeeds.
+            return itemsCalls === 1
+                ? (0, helpers_1.createJsonResponse)({ detail: "expired" }, { status: 401 })
+                : (0, helpers_1.createJsonResponse)({ items: [] });
+        });
+        const auth = cookieAuth({ cookie: expiryCookie(-60), fetchMock });
+        const client = new rest_client_1.RestClient({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            fetchImpl: fetchMock,
+        }, auth);
+        const result = await client.get("/items");
+        (0, chai_1.expect)(result).to.deep.equal({ items: [] });
+        (0, chai_1.expect)(itemsCalls).to.equal(2);
+    });
+    (0, mocha_1.it)("surfaces the 401 when cookie auth cannot refresh", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({ detail: "expired" }, { status: 401 }));
+        const client = new rest_client_1.RestClient({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            fetchImpl: fetchMock,
+        }, new cookie_auth_1.CookieAuth());
+        await (0, chai_1.expect)(client.get("/items")).to.be.rejected;
+    });
     (0, mocha_1.it)("uses credentials: include when no auth is provided (backward compat)", async () => {
         const fetchMock = (0, helpers_1.createFetchMock)();
         const client = new rest_client_1.RestClient({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doover-js",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "TypeScript client for Doover.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",