cortena-ui 1.4.2 → 1.6.0

package/dist/components/session-guard.d.ts

@@ -0,0 +1,268 @@
+"use client";
+import { DialogContentProps } from "./dialog.js";
+import * as React from "react";
+//#region src/components/session-guard.d.ts
+/**
+ * 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.
+ */
+/** 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 declare const DEFAULT_SESSION_POLICY: SessionPolicy;
+/**
+ * `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;
+}
+/** The default `BroadcastChannel` name. One channel per origin is the point. */
+export declare 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;
+};
+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 declare function decodeSessionClaims(accessToken: string | undefined): SessionClaims;
+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;
+}
+export declare function useSessionGuard(options: UseSessionGuardOptions): UseSessionGuardResult;
+/** `m:ss`, rounded up, so the countdown reaches 0:00 exactly as it ends. */
+export declare function formatCountdown(ms: number): string;
+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 declare function SessionExpiryDialog({ open, remainingMs, canContinue, onContinue, onLogout, modal, container }: SessionExpiryDialogProps): React.JSX.Element;
+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 declare function SessionGuard({ modal, container, ...options }: SessionGuardProps): React.JSX.Element;
+//#endregion
+//# sourceMappingURL=session-guard.d.ts.map