cortena-ui 1.4.2 → 1.6.0

package/src/components/session-guard.tsx

@@ -0,0 +1,1071 @@
+"use client";
+
+import * as React from "react";
+import { Button } from "@/components/button";
+import {
+  Dialog,
+  DialogBody,
+  DialogContent,
+  type DialogContentProps,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/dialog";
+import { cn } from "@/lib/cn";
+
+/**
+ * SessionGuard — the shared session-expiry behaviour every Cortena surface
+ * wears (how-to-create-a-cortena-extension §9.4, audit rule P-37, decision
+ * DESIGN-D18).
+ *
+ * A user is warned before their session ends — Continue or Log out — and is
+ * logged out if they do nothing. Identical in every extension, in cortenaweb
+ * and in the agent pop-up, because an idle timeout that differs in length,
+ * warning or cross-tab behaviour between surfaces is one a user cannot learn.
+ *
+ * ## Two clocks, and two authorities
+ *
+ * There are two clocks and they are not the same clock:
+ *
+ *   the access token   plumbing. One hour, refreshed proactively at 75% of its
+ *                      life while the user is active. The user never sees it.
+ *                      Refreshing lazily on a 401 is the failure this component
+ *                      exists to remove: the first click after any pause fails,
+ *                      and if the refresh token has itself gone the screen is
+ *                      left half-dead — panels rendered from cache, every
+ *                      action silently doing nothing, no message anywhere.
+ *   the idle timeout   the user's. Reset by the user's hands, never by a
+ *                      background refresh, and always announced before it fires.
+ *
+ * And two authorities. **This guard is the experience; cortena-auth is the
+ * truth.** The countdown, the modal and the cross-tab handshake are here so the
+ * screen behaves; the decision that a session has actually ended is the refresh
+ * endpoint's, which refuses with `session_idle_expired` or `session_expired`.
+ * A browser clock can be wrong, paused by a sleeping laptop or moved by the
+ * user, so nothing here is a security boundary. A refresh that fails, for any
+ * reason and at any moment, is a signed-out state.
+ *
+ * ## The JWT claim contract it consumes
+ *
+ * The guard reads three claims out of the access token's payload, and it does
+ * so **by decoding, not by verifying**: it splits on `.`, base64url-decodes the
+ * middle segment and parses the JSON. No signature is checked, and none can be
+ * — the browser has no key, and it has no need of one, because nothing in this
+ * component is a decision the server will honour. A forged token buys an
+ * attacker a longer countdown on their own screen and nothing else; every
+ * request it is attached to is still verified by cortena-auth.
+ *
+ *   `iat`          epoch seconds. When the token was minted. The origin for the
+ *                  proactive refresh and for the absolute cap.
+ *   `exp`          epoch seconds. When it expires. Refresh fires at
+ *                  `iat + 0.75 * (exp - iat)`.
+ *   `idle_exp`     epoch seconds. When cortena-auth will call the session idle.
+ *                  Seeds the idle clock at mount, so a page reload after a long
+ *                  pause does not hand the user a fresh eight hours.
+ *   `session_exp`  epoch seconds. The absolute cap, equal to the refresh
+ *                  token's lifetime. It does not move, however active the user.
+ *
+ * Anything malformed, absent or unparseable falls back to the policy defaults
+ * (8 h idle, 12 h absolute, a 2 min warning) rather than throwing: a token this
+ * component cannot read must not be what stops a user working.
+ *
+ * An explicit `policy` value **replaces** the matching claim outright. That is
+ * the one rule; it is what makes the guide's twelve-second session and the
+ * tests' deterministic windows possible without a fabricated token.
+ *
+ * ## What resets what
+ *
+ *   pointer, keyboard, `visibilitychange`   reset the idle clock, while the
+ *       state is `active`. Not network traffic — a polling screen left open on
+ *       a desk is not a user. Not while the warning is up either: a modal that
+ *       a stray mouse movement dismisses has not asked the user anything.
+ *   Continue   records activity and refreshes the token. The only thing that
+ *       clears the warning.
+ *   a refresh  moves the access-token clock and nothing else. If a background
+ *       refresh reset the idle clock, the idle timeout would never fire.
+ *
+ * Everything is shared across tabs over `BroadcastChannel`, so activity in one
+ * tab keeps them all alive and **one Continue answers every open tab**. Without
+ * it a user with three tabs open gets three modals and can dismiss the wrong
+ * one.
+ *
+ * ```tsx
+ * <SessionGuard
+ *   token={{ accessToken }}
+ *   refresh={() => auth.refresh()}        // POST /api/auth/refresh
+ *   logout={() => auth.logout()}          // POST /api/auth/logout
+ *   onSignedOut={(reason) => setSignedOut(reason)}
+ * />
+ * ```
+ *
+ * `onSignedOut` is where the app renders `LoginScreen` with `signedOut` and a
+ * `returnTo` (§7.4). Never a broken screen, never a spinner that never
+ * resolves — which is why the guard hands the reason back rather than
+ * redirecting itself.
+ */
+
+/* ── the contract ────────────────────────────────────────────────────────── */
+
+/** Why the session ended. Handed to `onSignedOut` so the app can word it. */
+export type SessionSignOutReason = "idle" | "absolute" | "refresh_failed" | "user";
+
+/** What the guard shows: counting quietly, counting out loud, or over. */
+export type SessionState = "active" | "warning" | "signedOut";
+
+export interface SessionToken {
+  /** The current access token. Decoded, never verified; see the note above. */
+  accessToken: string;
+  /**
+   * When it expires, for a token whose `exp` cannot be read — an opaque token,
+   * or one this guard failed to parse. Epoch **milliseconds**; a value below
+   * `1e11` is read as epoch seconds instead, since no millisecond timestamp has
+   * been that small since 1973 and every second-based one will be until 5138.
+   */
+  expiresAt?: number;
+}
+
+export interface SessionPolicy {
+  /** How long an unattended screen stays signed in. Default 8 hours. */
+  idleMs: number;
+  /** The cap, however active the user has been. Default 12 hours. */
+  absoluteMs: number;
+  /** How long before the end the modal appears. Default 2 minutes. */
+  warnMs: number;
+}
+
+/** The org policy's defaults, used when neither `policy` nor a claim says otherwise. */
+export const DEFAULT_SESSION_POLICY: SessionPolicy = /* @__PURE__ */ Object.freeze({
+  idleMs: 8 * 60 * 60 * 1000,
+  absoluteMs: 12 * 60 * 60 * 1000,
+  warnMs: 2 * 60 * 1000,
+});
+
+/**
+ * `setTimeout`/`clearTimeout`, injectable so a test can drive a whole session
+ * in a millisecond without the flake a real clock brings.
+ */
+export interface SessionTimers {
+  setTimeout: (handler: () => void, ms: number) => unknown;
+  clearTimeout: (handle: unknown) => void;
+}
+
+const DEFAULT_TIMERS: SessionTimers = /* @__PURE__ */ Object.freeze({
+  setTimeout: (handler: () => void, ms: number) => globalThis.setTimeout(handler, ms),
+  clearTimeout: (handle: unknown) => {
+    globalThis.clearTimeout(handle as ReturnType<typeof globalThis.setTimeout>);
+  },
+});
+
+/** The default `BroadcastChannel` name. One channel per origin is the point. */
+export const SESSION_CHANNEL_NAME = "cortena-session";
+
+/** What tabs say to each other. Deliberately tiny: no token ever crosses it. */
+export type SessionGuardMessage =
+  | { type: "activity"; at: number }
+  | { type: "continue"; at: number }
+  /**
+   * One tab rotated the credential. The token itself never crosses — only
+   * when the new one expires, which is all another tab needs to re-plan its
+   * own proactive refresh instead of racing to rotate again.
+   */
+  | { type: "refreshed"; expiresAt?: number }
+  /**
+   * The fallback claim, for a browser with no `navigator.locks`. `nonce` is
+   * the ballot: the highest one wins the election and rotates, and every other
+   * tab waits for that tab's `refreshed`. A claim without one comes from a tab
+   * running an older build and loses every election it takes part in, which
+   * still leaves exactly one refresher.
+   */
+  | { type: "refresh-claim"; at: number; nonce?: string }
+  | { type: "signed-out"; reason: SessionSignOutReason };
+
+/* ── the claims ──────────────────────────────────────────────────────────── */
+
+/** Epoch milliseconds, whichever unit the claim was written in. */
+const SECONDS_CEILING = 1e11;
+
+function epochMs(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return undefined;
+  }
+  return value < SECONDS_CEILING ? value * 1000 : value;
+}
+
+export interface SessionClaims {
+  /** `iat`, in epoch milliseconds. */
+  issuedAt?: number;
+  /** `exp`, in epoch milliseconds. */
+  expiresAt?: number;
+  /** `idle_exp`, in epoch milliseconds. */
+  idleExpiresAt?: number;
+  /** `session_exp`, in epoch milliseconds. */
+  sessionExpiresAt?: number;
+}
+
+/**
+ * The four session claims out of a JWT payload, **decoded and not verified**.
+ *
+ * Returns `{}` for anything that is not a readable JWT — an opaque token, a
+ * truncated one, a payload that is not JSON. It never throws: a token the guard
+ * cannot read falls back to the policy defaults, because a parse error must not
+ * be what ends a user's session.
+ */
+export function decodeSessionClaims(accessToken: string | undefined): SessionClaims {
+  const payload = readJwtPayload(accessToken);
+  if (!payload) {
+    return {};
+  }
+  return {
+    issuedAt: epochMs(payload.iat),
+    expiresAt: epochMs(payload.exp),
+    idleExpiresAt: epochMs(payload.idle_exp),
+    sessionExpiresAt: epochMs(payload.session_exp),
+  };
+}
+
+function readJwtPayload(accessToken: string | undefined): Record<string, unknown> | undefined {
+  if (typeof accessToken !== "string") {
+    return undefined;
+  }
+  const segment = accessToken.split(".")[1];
+  if (!segment) {
+    return undefined;
+  }
+  try {
+    const base64 = segment.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64 + "=".repeat((4 - (base64.length % 4)) % 4);
+    const binary = globalThis.atob(padded);
+    // The payload is UTF-8; atob gives bytes, so decode them rather than
+    // trusting that every claim happened to be ASCII.
+    const json = decodeURIComponent(
+      Array.from(binary, (char) => `%${char.charCodeAt(0).toString(16).padStart(2, "0")}`).join(""),
+    );
+    const parsed: unknown = JSON.parse(json);
+    return parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/* ── the hook ────────────────────────────────────────────────────────────── */
+
+/** Refresh at three quarters of the access token's life, never on a 401. */
+const REFRESH_AT_FRACTION = 0.75;
+/** At most one activity broadcast per this many ms; the local clock is exact. */
+const ACTIVITY_BROADCAST_MS = 5000;
+/** The countdown redraws once a second, which is the resolution it shows. */
+const COUNTDOWN_TICK_MS = 1000;
+/**
+ * At most one idle-clock reset per second from the pointer.
+ *
+ * `pointermove` fires on every frame a mouse is in motion — hundreds a second
+ * on a 120 Hz display — and each one re-entered the whole tick, recomputed the
+ * deadlines and tore down and rebuilt the timer. The idle clock has a
+ * resolution of hours; a second is finer than it can express.
+ */
+const ACTIVITY_THROTTLE_MS = 1000;
+/**
+ * The largest delay `setTimeout` can express. Anything above it wraps to a
+ * 32-bit signed integer and fires IMMEDIATELY, which turns a long deadline
+ * into a busy loop rather than a long wait.
+ */
+const MAX_TIMEOUT_MS = 2 ** 31 - 1;
+/**
+ * The longest idle window a claim may ask for. Beyond this the claim is not a
+ * policy, it is a mistake — seconds parsed as milliseconds, a fixture with a
+ * year 3000 expiry, a clock that has jumped — and honouring it means a session
+ * that never idles out at all. Absent is safer than absurd: the default
+ * applies, and cortena-auth remains the authority either way.
+ */
+const MAX_PLAUSIBLE_IDLE_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** Whether `idle_exp` describes a window this guard will act on. */
+function plausibleIdleMs(ms: number | undefined): number | undefined {
+  return ms !== undefined && ms > 0 && ms <= MAX_PLAUSIBLE_IDLE_MS ? ms : undefined;
+}
+
+/** The Web Lock the proactive refresh is taken under. One rotation per origin. */
+export const REFRESH_LOCK_NAME = "cortena-session-refresh";
+/**
+ * How long a broadcast claim holds, for a browser with no `navigator.locks`.
+ * Comfortably longer than a refresh round-trip and far shorter than the gap
+ * between two proactive refreshes.
+ */
+const REFRESH_CLAIM_MS = 30_000;
+/**
+ * How long the broadcast election runs before the winner rotates.
+ *
+ * One tick is all it takes: `BroadcastChannel` delivers within the same task
+ * queue turn, so every tab that reached 75% of the same token's life at the
+ * same instant has posted its ballot by the time this elapses. Long enough to
+ * hear them, short enough that nobody notices the token rotated 50ms late.
+ */
+const REFRESH_ELECTION_MS = 50;
+/**
+ * How long a tab that lost the election waits for the winner's `refreshed`.
+ *
+ * A leader can vanish between claiming and rotating — the user closed the tab,
+ * the renderer was killed — and every other tab would then sit waiting for a
+ * message that is never coming, until its token expired. This is the takeover:
+ * comfortably longer than a refresh round-trip, far shorter than the life of
+ * the credential it protects.
+ */
+const REFRESH_TAKEOVER_MS = 10_000;
+
+/**
+ * A ballot for one election. `Math.random` on purpose: this breaks a tie
+ * between tabs of one user in one browser, and nothing is defended by its
+ * unpredictability. Fixed width so the comparison is over the whole ballot.
+ */
+function refreshNonce(): string {
+  return Math.random().toString(36).slice(2, 12).padEnd(10, "0");
+}
+
+export interface UseSessionGuardOptions {
+  token: SessionToken;
+  /** `POST /api/auth/refresh`. Resolves with the rotated access token. */
+  refresh: () => Promise<{ accessToken: string }>;
+  /** `POST /api/auth/logout`. Revokes the refresh token and clears storage. */
+  logout: () => Promise<void>;
+  /**
+   * The session is over. Render `LoginScreen` with `signedOut` and a
+   * `returnTo`; the guard does not navigate.
+   */
+  onSignedOut: (reason: SessionSignOutReason) => void;
+  /** Org policy from `GET /api/orgs/:orgId/session-policy`. Replaces the claims. */
+  policy?: Partial<SessionPolicy>;
+  /** The `BroadcastChannel` name. One per origin unless two apps must not share. */
+  channelName?: string;
+  /** The clock. Injected by tests and by the guide; `Date.now` otherwise. */
+  now?: () => number;
+  /** The timers. Injected by tests and by the guide; `setTimeout` otherwise. */
+  timers?: SessionTimers;
+}
+
+export interface UseSessionGuardResult {
+  /** `active` while it counts quietly, `warning` while the modal is up. */
+  state: SessionState;
+  /** Milliseconds left until the session ends. `0` once it has. */
+  remainingMs: number;
+  /**
+   * Whether Continue can buy the user anything. False once the absolute cap is
+   * the binding deadline, because no amount of activity moves that one.
+   */
+  canContinue: boolean;
+  /** Set once the session has ended. */
+  reason?: SessionSignOutReason;
+  /** The idle deadline, epoch ms. Moves with the user's hands. */
+  idleDeadline: number;
+  /** The absolute cap, epoch ms. Does not move. */
+  absoluteDeadline: number;
+  /** Whichever of the two comes first. */
+  deadline: number;
+  /** Record activity and refresh the token. What Continue calls. */
+  continueSession: () => void;
+  /** End the session now. What Log out calls, with `"user"`. */
+  signOut: (reason?: SessionSignOutReason) => void;
+  /** Record activity by hand, for an app with an activity signal of its own. */
+  recordActivity: () => void;
+}
+
+interface Engine {
+  lastActivity: number;
+  sessionStart: number;
+  absoluteDeadline: number;
+  idleMs: number;
+  refreshAt?: number;
+  refreshing: boolean;
+  ended: boolean;
+  timer: unknown;
+  lastBroadcast: number;
+  /** The last pointer event credited. See `ACTIVITY_THROTTLE_MS`. */
+  lastPointer: number;
+  /** When some tab last claimed, or completed, a rotation. */
+  lastRefreshClaim: number;
+  /** The broadcast election in flight, where there are no Web Locks. */
+  election?: { nonce: string; best: string; timer?: unknown };
+  /** `exp` of the token currently adopted, epoch ms. */
+  expiresAt?: number;
+  channel?: BroadcastChannel;
+  seenToken?: string;
+}
+
+export function useSessionGuard(options: UseSessionGuardOptions): UseSessionGuardResult {
+  const { token, policy, channelName = SESSION_CHANNEL_NAME } = options;
+
+  const warnMs = policy?.warnMs ?? DEFAULT_SESSION_POLICY.warnMs;
+  const policyIdleMs = policy?.idleMs;
+  const policyAbsoluteMs = policy?.absoluteMs;
+
+  // Everything the engine reads from props goes through one ref, so the timer
+  // loop never has to be torn down and rebuilt when a callback identity changes.
+  const latest = React.useRef(options);
+  latest.current = options;
+
+  const now = React.useCallback(() => (latest.current.now ?? Date.now)(), []);
+  const timers = React.useCallback(() => latest.current.timers ?? DEFAULT_TIMERS, []);
+
+  const [state, setState] = React.useState<SessionState>("active");
+  const [remainingMs, setRemainingMs] = React.useState(0);
+  const [reason, setReason] = React.useState<SessionSignOutReason | undefined>(undefined);
+
+  const engineRef = React.useRef<Engine | null>(null);
+  if (engineRef.current === null) {
+    const startedAt = now();
+    const claims = decodeSessionClaims(token.accessToken);
+    // An absurd `idle_exp` is treated as absent rather than honoured: a claim
+    // that asks for a year is a bug somewhere upstream, and acting on it means
+    // a session that never idles out.
+    const claimedIdleMs =
+      claims.idleExpiresAt !== undefined && claims.issuedAt !== undefined
+        ? plausibleIdleMs(claims.idleExpiresAt - claims.issuedAt)
+        : undefined;
+    const idleMs = policyIdleMs ?? claimedIdleMs ?? DEFAULT_SESSION_POLICY.idleMs;
+    const sessionStart = claims.issuedAt ?? startedAt;
+    engineRef.current = {
+      idleMs,
+      sessionStart,
+      // Seed from `idle_exp` so a reload after a long pause does not hand the
+      // user a fresh idle window. A policy override replaces the claim, so a
+      // twelve-second session starts twelve seconds from now.
+      lastActivity:
+        policyIdleMs === undefined && claimedIdleMs !== undefined && claims.idleExpiresAt !== undefined
+          ? claims.idleExpiresAt - idleMs
+          : startedAt,
+      absoluteDeadline:
+        policyAbsoluteMs !== undefined
+          ? sessionStart + policyAbsoluteMs
+          : (claims.sessionExpiresAt ?? sessionStart + DEFAULT_SESSION_POLICY.absoluteMs),
+      refreshing: false,
+      ended: false,
+      timer: undefined,
+      lastBroadcast: 0,
+      lastPointer: 0,
+      lastRefreshClaim: 0,
+    };
+  }
+  const engine = engineRef.current;
+
+  /* — the loop — */
+
+  const tickRef = React.useRef<() => void>(() => {});
+
+  const clearTimer = React.useCallback(() => {
+    if (engine.timer !== undefined) {
+      timers().clearTimeout(engine.timer);
+      engine.timer = undefined;
+    }
+  }, [engine, timers]);
+
+  const schedule = React.useCallback(
+    (ms: number) => {
+      clearTimer();
+      // Clamped: above 2^31-1 `setTimeout` wraps and fires immediately, so a
+      // twelve-hour deadline became a tight loop. Waking early is harmless —
+      // `tick` recomputes and schedules the remainder.
+      engine.timer = timers().setTimeout(() => {
+        engine.timer = undefined;
+        tickRef.current();
+      }, Math.min(Math.max(0, ms), MAX_TIMEOUT_MS));
+    },
+    [clearTimer, engine, timers],
+  );
+
+  const post = React.useCallback(
+    (message: SessionGuardMessage) => {
+      try {
+        engine.channel?.postMessage(message);
+      } catch {
+        // A closed channel is not a reason to break the tab that closed it.
+      }
+    },
+    [engine],
+  );
+
+  const end = React.useCallback(
+    (why: SessionSignOutReason, opts?: { logout?: boolean; broadcast?: boolean }) => {
+      if (engine.ended) {
+        return;
+      }
+      engine.ended = true;
+      clearTimer();
+      setState("signedOut");
+      setReason(why);
+      setRemainingMs(0);
+      if (opts?.broadcast !== false) {
+        post({ type: "signed-out", reason: why });
+      }
+      const done = () => latest.current.onSignedOut(why);
+      // A failed refresh means the credential is already gone; asking
+      // cortena-auth to revoke it again only produces a second failure to
+      // swallow. Every other ending revokes first, then tells the app.
+      if (opts?.logout === false || why === "refresh_failed") {
+        done();
+        return;
+      }
+      void Promise.resolve()
+        .then(() => latest.current.logout())
+        .catch(() => {
+          // The user is signed out either way. A logout that cannot reach the
+          // server must not leave them on a screen that no longer works.
+        })
+        .finally(done);
+    },
+    [clearTimer, engine, post],
+  );
+
+  const adoptToken = React.useCallback(
+    (accessToken: string, expiresAtProp: number | undefined, at: number) => {
+      engine.seenToken = accessToken;
+      const claims = decodeSessionClaims(accessToken);
+      const expiresAt = claims.expiresAt ?? epochMs(expiresAtProp);
+      const issuedAt = claims.issuedAt ?? at;
+      engine.expiresAt = expiresAt;
+      engine.refreshAt =
+        expiresAt !== undefined && expiresAt > issuedAt
+          ? issuedAt + (expiresAt - issuedAt) * REFRESH_AT_FRACTION
+          : undefined;
+      // `session_exp` is the truth about the cap and does not move across a
+      // rotation; an explicit policy replaces it. The idle clock is untouched:
+      // a refresh is not the user.
+      if (policyAbsoluteMs === undefined && claims.sessionExpiresAt !== undefined) {
+        engine.absoluteDeadline = claims.sessionExpiresAt;
+      }
+    },
+    [engine, policyAbsoluteMs],
+  );
+
+  const doRefresh = React.useCallback((): Promise<void> => {
+    if (engine.refreshing || engine.ended) {
+      return Promise.resolve();
+    }
+    engine.refreshing = true;
+    engine.lastRefreshClaim = now();
+    return Promise.resolve()
+      .then(() => latest.current.refresh())
+      .then((next) => {
+        engine.refreshing = false;
+        if (engine.ended) {
+          return;
+        }
+        adoptToken(next.accessToken, undefined, now());
+        // No token crosses the channel — only when the new one expires, which
+        // is all a sibling tab needs to push its own proactive refresh out
+        // instead of rotating a credential that was just rotated.
+        post({
+          type: "refreshed",
+          ...(engine.expiresAt === undefined ? {} : { expiresAt: engine.expiresAt }),
+        });
+        tickRef.current();
+      })
+      .catch(() => {
+        engine.refreshing = false;
+        // §9.4.1: a failed refresh, at any time, is a signed-out state and must
+        // be shown as one. Never a half-dead screen.
+        end("refresh_failed");
+      });
+  }, [adoptToken, end, engine, now, post]);
+
+  /** Abandon any election in flight, and its timer. */
+  const clearElection = React.useCallback(() => {
+    if (engine.election?.timer !== undefined) {
+      timers().clearTimeout(engine.election.timer);
+    }
+    engine.election = undefined;
+  }, [engine, timers]);
+
+  /**
+   * The ballots are in.
+   *
+   * The highest one rotates. Everybody else waits for its `refreshed` — and
+   * takes the rotation over if the winner never sends one, because a leader
+   * that is closed between claiming and refreshing would otherwise leave every
+   * remaining tab waiting for a message nobody is going to send.
+   */
+  const settleElection = React.useCallback(() => {
+    const election = engine.election;
+    if (!election || engine.ended) {
+      return;
+    }
+    if (election.best === election.nonce) {
+      engine.election = undefined;
+      // The same three questions the Web Lock path asks once it holds the
+      // lock: the world may have moved while the ballots were being counted.
+      if (engine.refreshing) {
+        return;
+      }
+      if (engine.refreshAt !== undefined && now() < engine.refreshAt) {
+        return;
+      }
+      void doRefresh();
+      return;
+    }
+    election.timer = timers().setTimeout(() => {
+      engine.election = undefined;
+      if (engine.ended || engine.refreshing) {
+        return;
+      }
+      // The winner's `refreshed` moves `refreshAt` past now, and clears the
+      // election with it. Reaching here means it never arrived.
+      if (engine.refreshAt !== undefined && now() < engine.refreshAt) {
+        return;
+      }
+      void doRefresh();
+    }, REFRESH_TAKEOVER_MS);
+  }, [doRefresh, engine, now, timers]);
+
+  /**
+   * The proactive refresh, once per origin rather than once per tab.
+   *
+   * Every open tab reaches 75% of the same token's life at the same instant,
+   * so without a claim a user with four tabs fires four rotations at once.
+   * The refresh token rotates on use, so three of them present a token that
+   * has just been superseded — and a failed refresh is a signed-out state, by
+   * design. Four tabs, one of them signed in.
+   *
+   * `navigator.locks` is the right instrument and is available everywhere
+   * Cortena runs. `ifAvailable` means a tab that does not get the lock does
+   * NOT queue behind it: the rotation is already happening, and a second one
+   * afterwards is exactly what this prevents.
+   *
+   * Where locks are absent, an election over the channel the guard already
+   * owns. Claiming and refreshing in the same tick was no coordination at all:
+   * every tab reaches the deadline on the same clock, so every tab posted its
+   * claim and rotated before any of them could hear another's — the exact
+   * simultaneous rotation the lock exists to prevent, in the browsers with no
+   * lock to take. So a tab posts a ballot, waits one tick to hear the others,
+   * and only the highest ballot rotates. The losers wait for its `refreshed`,
+   * and take over if it never comes.
+   */
+  const refreshOnce = React.useCallback(() => {
+    if (engine.refreshing || engine.ended) {
+      return;
+    }
+    const locks = globalThis.navigator?.locks;
+    if (locks && typeof locks.request === "function") {
+      void locks
+        .request(REFRESH_LOCK_NAME, { ifAvailable: true }, async (lock) => {
+          // Another tab holds it and is rotating now.
+          if (!lock) {
+            return;
+          }
+          // It may have finished while we waited: `refreshed` moves `refreshAt`
+          // past now, and there is then nothing to do.
+          if (engine.ended || engine.refreshing) {
+            return;
+          }
+          if (engine.refreshAt !== undefined && now() < engine.refreshAt) {
+            return;
+          }
+          await doRefresh();
+        })
+        .catch(() => {
+          // A browser that refuses the lock must not be a browser that never
+          // refreshes. Fall back to rotating unguarded.
+          void doRefresh();
+        });
+      return;
+    }
+    const at = now();
+    if (engine.election || at - engine.lastRefreshClaim < REFRESH_CLAIM_MS) {
+      return;
+    }
+    engine.lastRefreshClaim = at;
+    const nonce = refreshNonce();
+    engine.election = { nonce, best: nonce };
+    post({ type: "refresh-claim", at, nonce });
+    engine.election.timer = timers().setTimeout(settleElection, REFRESH_ELECTION_MS);
+  }, [doRefresh, engine, now, post, settleElection, timers]);
+
+  const tick = React.useCallback(() => {
+    if (engine.ended) {
+      return;
+    }
+    const at = now();
+    const idleDeadline = engine.lastActivity + engine.idleMs;
+    const deadline = Math.min(idleDeadline, engine.absoluteDeadline);
+
+    if (at >= deadline) {
+      end(engine.absoluteDeadline <= idleDeadline ? "absolute" : "idle");
+      return;
+    }
+
+    const warnAt = deadline - warnMs;
+    if (at >= warnAt) {
+      setState("warning");
+      setRemainingMs(deadline - at);
+      schedule(Math.min(COUNTDOWN_TICK_MS, deadline - at));
+      return;
+    }
+
+    setState("active");
+    setRemainingMs(deadline - at);
+
+    const { refreshAt } = engine;
+    if (refreshAt !== undefined && at >= refreshAt && !engine.refreshing) {
+      refreshOnce();
+    }
+    // The next interesting instant: the warning, or the proactive refresh if it
+    // is still ahead of us. Nothing wakes this component in between.
+    const wakeAt =
+      refreshAt !== undefined && refreshAt > at && !engine.refreshing
+        ? Math.min(warnAt, refreshAt)
+        : warnAt;
+    schedule(wakeAt - at);
+  }, [end, engine, now, refreshOnce, schedule, warnMs]);
+
+  tickRef.current = tick;
+
+  /* — activity — */
+
+  // What `recordActivity` consults to decide whether a stray event may reset
+  // the clock. A ref, not the state, because the listeners are bound once.
+  const stateRef = React.useRef(state);
+  stateRef.current = state;
+
+  const recordActivity = React.useCallback(
+    (at: number, opts?: { force?: boolean; broadcast?: boolean }) => {
+      if (engine.ended) {
+        return;
+      }
+      // A stray mouse movement must not answer a question the user was asked.
+      // Only Continue (`force`) clears the warning.
+      if (!opts?.force && stateRef.current !== "active") {
+        return;
+      }
+      if (at > engine.lastActivity) {
+        engine.lastActivity = at;
+      }
+      if (opts?.broadcast !== false && at - engine.lastBroadcast >= ACTIVITY_BROADCAST_MS) {
+        engine.lastBroadcast = at;
+        post({ type: "activity", at });
+      }
+      tickRef.current();
+    },
+    [engine, post],
+  );
+
+  const continueSession = React.useCallback(() => {
+    if (engine.ended) {
+      return;
+    }
+    const at = now();
+    engine.lastBroadcast = at;
+    post({ type: "continue", at });
+    recordActivity(at, { force: true, broadcast: false });
+    doRefresh();
+  }, [doRefresh, engine, now, post, recordActivity]);
+
+  const signOut = React.useCallback(
+    (why: SessionSignOutReason = "user") => {
+      end(why);
+    },
+    [end],
+  );
+
+  /* — mounting the engine — */
+
+  React.useEffect(() => {
+    // Constructed the way `post` posts: a browser that refuses the channel —
+    // storage blocked for the origin, a partitioned third-party frame — must
+    // give a tab that coordinates alone, not a shell that throws on mount and
+    // takes the whole application down with it.
+    let channel: BroadcastChannel | undefined;
+    try {
+      channel =
+        typeof globalThis.BroadcastChannel === "function"
+          ? new globalThis.BroadcastChannel(channelName)
+          : undefined;
+    } catch {
+      channel = undefined;
+    }
+    engine.channel = channel;
+
+    if (channel) {
+      channel.onmessage = (event: MessageEvent<SessionGuardMessage>) => {
+        const message = event.data;
+        if (!message || typeof message !== "object") {
+          return;
+        }
+        if (message.type === "activity") {
+          recordActivity(message.at, { broadcast: false });
+        } else if (message.type === "continue") {
+          // One Continue answers every open tab. Only the tab the user pressed
+          // it in refreshes; a second rotation would race the first.
+          recordActivity(message.at, { force: true, broadcast: false });
+        } else if (message.type === "refreshed") {
+          // Another tab rotated the credential; ours is the same session. Plan
+          // the next proactive refresh off the new token's life rather than
+          // racing to rotate one that has just been superseded.
+          engine.lastRefreshClaim = now();
+          // Whoever won the election has done the job; nobody needs to take
+          // it over, and no loser's timer should rotate on top of it.
+          clearElection();
+          if (message.expiresAt !== undefined) {
+            const at = now();
+            engine.refreshAt = at + (message.expiresAt - at) * REFRESH_AT_FRACTION;
+          }
+          tickRef.current();
+        } else if (message.type === "refresh-claim") {
+          engine.lastRefreshClaim = Math.max(engine.lastRefreshClaim, message.at);
+          // A ballot. Only the highest one refreshes; this tab discovers it
+          // lost when the election settles a tick from now.
+          const ballot = message.nonce ?? "";
+          if (engine.election && ballot > engine.election.best) {
+            engine.election.best = ballot;
+          }
+        } else if (message.type === "signed-out") {
+          end(message.reason, { logout: false, broadcast: false });
+        }
+      };
+    }
+
+    // `pointermove` fires on every frame the mouse is in motion. Crediting
+    // each one re-entered the tick, recomputed both deadlines and rebuilt the
+    // timer hundreds of times a second, to move a clock measured in hours.
+    const onPointer = () => {
+      const at = now();
+      if (at - engine.lastPointer < ACTIVITY_THROTTLE_MS) {
+        return;
+      }
+      engine.lastPointer = at;
+      recordActivity(at);
+    };
+    const onKey = () => recordActivity(now());
+
+    /**
+     * The tab came back. **Judge the clock before crediting the hand.**
+     *
+     * A laptop lid closed at 5pm and opened at 9am delivers exactly one
+     * `visibilitychange`, and the timer that should have signed the user out
+     * at 1am never ran — a background tab's timers are throttled, and a
+     * suspended machine's do not run at all. Crediting the wake as activity
+     * first reset `lastActivity` to now and bought a fully idle session a
+     * fresh eight hours, every morning, for ever. So the deadline that
+     * elapsed while nobody was looking is evaluated against the OLD
+     * `lastActivity`, and only a session that survives it is credited.
+     */
+    const onWake = () => {
+      if (engine.ended) {
+        return;
+      }
+      const at = now();
+      const idleDeadline = engine.lastActivity + engine.idleMs;
+      const deadline = Math.min(idleDeadline, engine.absoluteDeadline);
+      if (at >= deadline) {
+        end(engine.absoluteDeadline <= idleDeadline ? "absolute" : "idle");
+        return;
+      }
+      recordActivity(at);
+    };
+    const onVisibility = () => {
+      if (typeof document !== "undefined" && document.visibilityState === "visible") {
+        onWake();
+      }
+    };
+    // Pointer, keyboard, visibilitychange and focus. Not network traffic: a
+    // polling screen left open on a desk is not a user.
+    window.addEventListener("pointerdown", onPointer, { passive: true });
+    window.addEventListener("pointermove", onPointer, { passive: true });
+    window.addEventListener("keydown", onKey, { passive: true });
+    window.addEventListener("focus", onWake);
+    document.addEventListener("visibilitychange", onVisibility);
+
+    tickRef.current();
+
+    return () => {
+      window.removeEventListener("pointerdown", onPointer);
+      window.removeEventListener("pointermove", onPointer);
+      window.removeEventListener("keydown", onKey);
+      window.removeEventListener("focus", onWake);
+      document.removeEventListener("visibilitychange", onVisibility);
+      if (channel) {
+        channel.onmessage = null;
+        channel.close();
+      }
+      engine.channel = undefined;
+      clearElection();
+      clearTimer();
+    };
+    // The loop reads its inputs through refs; only the channel identity and the
+    // engine can require a rebuild.
+  }, [channelName, clearElection, clearTimer, end, engine, now, recordActivity]);
+
+  // A token the caller replaced — a sign-in, or a refresh the app ran itself.
+  React.useEffect(() => {
+    if (engine.seenToken === token.accessToken) {
+      return;
+    }
+    adoptToken(token.accessToken, token.expiresAt, now());
+    tickRef.current();
+  }, [adoptToken, engine, now, token.accessToken, token.expiresAt]);
+
+  const recordActivityNow = React.useCallback(() => recordActivity(now()), [now, recordActivity]);
+
+  const idleDeadline = engine.lastActivity + engine.idleMs;
+  const deadline = Math.min(idleDeadline, engine.absoluteDeadline);
+
+  return {
+    state,
+    remainingMs: state === "signedOut" ? 0 : remainingMs,
+    canContinue: idleDeadline < engine.absoluteDeadline,
+    reason,
+    idleDeadline,
+    absoluteDeadline: engine.absoluteDeadline,
+    deadline,
+    continueSession,
+    signOut,
+    recordActivity: recordActivityNow,
+  };
+}
+
+/* ── the modal ───────────────────────────────────────────────────────────── */
+
+/** `m:ss`, rounded up, so the countdown reaches 0:00 exactly as it ends. */
+export function formatCountdown(ms: number): string {
+  const seconds = Math.max(0, Math.ceil(ms / 1000));
+  return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`;
+}
+
+export interface SessionExpiryDialogProps {
+  open: boolean;
+  /** Milliseconds left. Rendered as `m:ss`. */
+  remainingMs: number;
+  /** Whether Continue is offered. False under the absolute cap, which no activity moves. */
+  canContinue?: boolean;
+  onContinue?: () => void;
+  onLogout?: () => void;
+  /** Non-modal for the guide, where three theme frames must not fight over focus. */
+  modal?: boolean;
+  /** Where to portal. The guide frames it; the product does not pass this. */
+  container?: DialogContentProps["container"];
+}
+
+/**
+ * The countdown. `role="alertdialog"` rather than `dialog`, because it is not a
+ * surface the user opened — it interrupts them to ask a question with a
+ * deadline, and assistive technology announces it as such.
+ *
+ * It is deliberately undismissable: no Escape, no outside press, no close X.
+ * Both ways out are decisions — Continue or Log out — and a modal you can wave
+ * away without answering is one that ends a session by accident. Focus opens on
+ * Continue, which is the answer nearly every user wants.
+ */
+export function SessionExpiryDialog({
+  open,
+  remainingMs,
+  canContinue = true,
+  onContinue,
+  onLogout,
+  modal = true,
+  container,
+}: SessionExpiryDialogProps) {
+  const continueRef = React.useRef<HTMLButtonElement | null>(null);
+  return (
+    <Dialog
+      open={open}
+      modal={modal}
+      disablePointerDismissal
+      // Controlled and never closed from the inside: Escape and an outside
+      // press both land here and are ignored on purpose.
+      onOpenChange={() => {}}
+    >
+      <DialogContent
+        role="alertdialog"
+        data-slot="session-expiry-dialog"
+        container={container}
+        initialFocus={canContinue ? continueRef : undefined}
+        className="max-w-[420px]"
+      >
+        <DialogHeader>
+          <div className="flex items-center gap-3">
+            <span
+              data-slot="session-expiry-glyph"
+              className={cn(
+                "flex size-9 shrink-0 items-center justify-center",
+                "rounded-[var(--ds-radius-full)] bg-[var(--ds-warning-soft)]",
+                "text-[color:var(--ds-warning)]",
+              )}
+            >
+              <CountdownGlyph />
+            </span>
+            <DialogTitle data-slot="session-expiry-title">
+              Your session ends in{" "}
+              <span data-slot="session-expiry-countdown" className="font-mono tabular-nums">
+                {formatCountdown(remainingMs)}
+              </span>
+            </DialogTitle>
+          </div>
+        </DialogHeader>
+        <DialogBody>
+          {/* A Description, not a plain <p>: it is what `aria-describedby`
+              points at, so the alertdialog announces the question and not only
+              the countdown in its title. */}
+          <DialogDescription data-slot="session-expiry-message">
+            {canContinue
+              ? "You have been inactive for a while. Continue to stay signed in — anything you have not saved is kept."
+              : "This session has reached its maximum length and cannot be extended. Save anything you need before it ends."}
+          </DialogDescription>
+        </DialogBody>
+        <DialogFooter>
+          <Button variant="secondary" onClick={onLogout} data-slot="session-expiry-logout">
+            Log out
+          </Button>
+          {canContinue ? (
+            <Button ref={continueRef} onClick={onContinue} data-slot="session-expiry-continue">
+              Continue
+            </Button>
+          ) : null}
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+/** A clock face. Inline rather than a lucide import: one icon, one shape. */
+function CountdownGlyph() {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      className="size-5"
+      aria-hidden
+      focusable="false"
+    >
+      <circle cx="12" cy="12" r="9" />
+      <path d="M12 7v5l3 2" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  );
+}
+
+/* ── the component ───────────────────────────────────────────────────────── */
+
+export interface SessionGuardProps extends UseSessionGuardOptions {
+  /** Non-modal, for the guide. The product leaves this alone. */
+  modal?: boolean;
+  /** Where to portal the modal — an agent pop-up's own root, say. */
+  container?: DialogContentProps["container"];
+}
+
+/**
+ * Mount one per surface: the shell mounts it, and so does the agent pop-up
+ * (§17). A user whose extension warns them while the chat pop-up beside it does
+ * not has learned nothing about how long a Cortena session lasts.
+ */
+export function SessionGuard({ modal, container, ...options }: SessionGuardProps) {
+  const session = useSessionGuard(options);
+  return (
+    <SessionExpiryDialog
+      open={session.state === "warning"}
+      remainingMs={session.remainingMs}
+      canContinue={session.canContinue}
+      onContinue={session.continueSession}
+      onLogout={() => session.signOut("user")}
+      modal={modal}
+      container={container}
+    />
+  );
+}