@flytedesk/app-kit 6.0.0 → 7.1.0

package/README.md

@@ -27,6 +27,156 @@ own domain work resumes.
 pnpm add @flytedesk/app-kit
 ```
 
+## Building a flytedesk ID app
+
+**This is the one supported way to sign people in to a flytedesk app** (PLN-2 R-14). Every
+flytedesk ID app (sms-app, media-planner, and every app after them) uses it unchanged.
+The whole session lifecycle lives in `@flytedesk/app-kit`:
+
+- automatic sign-in;
+- the return to the exact link;
+- session-loss detection and re-auth;
+- the periodic check;
+- outages;
+- sign-out;
+- cross-tab behaviour.
+
+An app renders its screens and nothing else.
+
+### What the user sees
+
+- **Opening the app signed out.** A "Signing you in…" screen, then a top-level
+  navigation through flytedesk ID.
+  - If flytedesk ID is still signed in, the user is back on **the exact link they
+    opened** (path, query and hash) a moment later.
+  - Otherwise they are on flytedesk ID's own sign-in page, and signing in there brings
+    them back to that link.
+  - **There is no sign-in button page, ever.**
+- **The session ending while the app is open.** The session can end when a refresh is
+  refused, when it is revoked, or when the user signs out in another tab. The app
+  disappears behind a "Session expired — signing you back in" screen and goes through
+  the same automatic sign-in back to the same URL. No panel ever shows its own auth
+  error.
+- **Checks.** A visible tab verifies its session every 10 minutes. A tab also re-checks
+  when it becomes visible or focused, at most once a minute. A hidden tab never
+  redirects; it re-checks when it is looked at.
+- **An outage (flytedesk ID or the app's store down) is never a sign-out.** Signed in, the
+  app keeps rendering with a `status: "unavailable"` session and retries with backoff.
+  Before any user is known, the screen shows "Reconnecting…".
+- **A sign-in that fails, or comes back still signed out, never loops.** The screen says
+  what happened and offers **Try again**. This covers:
+  - cancelled at flytedesk ID;
+  - an attempt that took too long;
+  - cookies being blocked;
+  - Back from flytedesk ID's page.
+- **Sign-out** ends the app's session **and** flytedesk ID's (RP-initiated logout). The
+  next sign-in on that browser must be made at flytedesk ID even if a race left
+  flytedesk ID's session alive: the server sets a signed-out marker that forces
+  `prompt=login`. **A signed-out user is never bounced straight back in.** Signing out of
+  one flytedesk app signs the browser out of flytedesk ID, so every other flytedesk app
+  asks again on its next request.
+- **Other tabs.** Signing in or out in one tab is reflected in the others.
+  - Only one tab navigates to flytedesk ID at a time; the others wait for it.
+  - A tab signed in as a different user reloads, so no page ever shows one user's data
+    as another's.
+
+### What an app writes
+
+**The server** registers the plugin:
+
+```ts
+await api.register(flytedeskAuth, {
+  clientId, clientSecret, issuer, redirectUri, appId,
+  // The app's web URL. Return targets resolve against it, a failed sign-in lands on it
+  // (with signin_error), and it is the post-logout redirect: register it at flytedesk ID
+  // as this client's post_logout_redirect_uri too.
+  postLoginRedirect: "https://my-app.flytedesk.com/",
+  cookieSecret, secureCookies, accessTokenSecret, store,
+});
+```
+
+Its `AuthStore` persists `IdpSessionRow.idToken`, which is sent back to flytedesk ID as the
+logout's `id_token_hint`. That is what lets flytedesk ID end its session without a
+confirmation step for a real sign-out, while still asking on a forged one.
+
+**The web app** configures the client once and wraps its shell:
+
+```tsx
+import { configureApiClient, SessionBoundary, type AuthedUserDto } from "@flytedesk/app-kit/auth/client";
+import { SessionScreen } from "@flytedan/flytebot-design-system";
+
+configureApiClient({ baseUrl: import.meta.env.VITE_API_BASE_URL });
+
+export function App() {
+  return (
+    <SessionBoundary<AuthedUserDto>
+      screen={(state) => <SessionScreen {...state} productName="SMS" />}
+    >
+      {(session) => <Shell session={session} />}
+    </SessionBoundary>
+  );
+}
+```
+
+`SessionBoundary` renders the app only while the session is usable: `authenticated`, or
+`unavailable` with a last-known `user`, which is **display-only** and never a basis for an
+authorization decision. In every other state the app is **unmounted**, so none of its
+polls or timers can keep calling the api for a session that is over.
+
+- **The app's own code** calls the api with `apiRequest` / `apiUpload` / `apiDownload`.
+  It reads the session with `useAuthSession<TUser>()` in React, or with
+  `authSession.getSnapshot()` and `authSession.subscribe()` anywhere else.
+- **Its shell** wires `session.signOut` to the account menu. `signOut()` navigates away
+  on success, and rejects only when the server did not end the session.
+- **After changing the user server-side** (a profile edit), the app calls
+  `authSession.refreshUser()`.
+
+`@flytedesk/app-kit` never imports the design system, and the design system never imports
+`@flytedesk/app-kit`: `SessionScreenState` (`{ kind, error, onRetry }`) is a plain shape
+`SessionScreen` accepts.
+
+### What an app must not build
+
+Everything below is app-kit's:
+
+- a sign-in page or button;
+- a return-target stash or post-login landing route;
+- a silent / iframe resume;
+- its own session-loss, 401 or "reconnecting" handling;
+- a sign-out flow;
+- cross-tab session code;
+- token handling.
+
+`setAccessToken` and the other internals are not exported. An app's unit tests use
+`@flytedesk/app-kit/auth/client/testing` (`setTestAccessToken`,
+`resetAuthSessionForTests`). If an app needs something the lifecycle doesn't do, change
+app-kit.
+
+### The draft-survival contract
+
+When a session ends mid-use, the app is unmounted and the tab navigates through
+flytedesk ID. **In-memory state is gone by design.** So:
+
+- Anything a user would be upset to lose (an unsaved draft, a half-built query) must
+  already be in browser storage, written as they edit, never only on unload. Pending
+  debounced writes are flushed on unmount.
+- Keep it **keyed by `user.id`**, so a different user signing in on the same browser
+  never sees it.
+- After the re-auth the browser is back on the exact URL, and the app rehydrates from
+  storage.
+- app-kit never reads, writes or clears app storage. Sign-out does not delete drafts,
+  because they are user-keyed.
+
+### Configuration at flytedesk ID
+
+Register the app's client with:
+
+- its callback as a `redirect_uri`;
+- its `postLoginRedirect` as a `post_logout_redirect_uri` (FD-136).
+
+Sign-in requests `offline_access` with `prompt=consent` (AK-33), so every session gets
+a refresh token.
+
 ## Auth (`@flytedesk/app-kit/auth`)
 
 `idpRequestTimeoutMs` (`FlytedeskAuthOptions`/`OidcClientOptions`, default 5s) bounds
@@ -58,10 +208,10 @@ secret), a lock timeout, any `AuthStore` error, a *throwing* `onAuthorizeUser`
 - The body is always `{ error, code }` with `code` one of `AUTH_UNAVAILABLE_CODES`:
   `idp_unavailable`, `auth_store_unavailable` or `authorization_hook_failed`.
 - The browser client raises `AuthUnavailableError` (an `ApiRequestError`) for it and
-  never runs the auth recovery; `onAuthUnavailable(listener)` announces it. The
-  automatic refresh treats only the plugin's 401 as "signed out": a network error, its
-  10s deadline, a proxy's 502/504 or any other non-200 is an `AuthUnavailableError` too
-  (code `auth_unreachable`). `useAuthSession` keeps the session in
+  never treats it as a session end. The automatic refresh treats only the plugin's 401 as
+  "signed out": a network error, its 10s deadline, a proxy's 502/504 or any other non-200
+  is an `AuthUnavailableError` too (code `auth_unreachable`). The session lifecycle keeps
+  the session in
   `status: "unavailable"` (with the last verified `user` — display-only, not a verified
   identity — and `retryInMs`) and re-verifies by itself with jittered exponential
   backoff (ceilings 1s, 2s, 4s, … capped at 30s, each delay drawn from the ceiling's
@@ -69,10 +219,14 @@ secret), a lock timeout, any `AuthStore` error, a *throwing* `onAuthorizeUser`
   sign-in screen. A failing `/apps` never blocks the session: `apps` is `[]` and
   `appsError` says why.
 
-**Sign-out always clears the cookie (4.0).** `POST {routePrefix}/logout` clears the
-refresh cookie in a `finally`, attempts each store step (revoke the family, look up and
-delete the IdP session) independently, and answers `502 logout_store_failed` (logged)
-if any step failed.
+**Sign-out always ends the session, and flytedesk ID's too.** `POST {routePrefix}/logout`
+accepts only the app's own `Origin` (`postLoginRedirect`'s; anything else is `403
+forbidden_origin`, touching nothing). It clears the refresh cookie and sets the
+signed-out marker (so the next `/login` asks flytedesk ID for `prompt=login`) in a
+`finally`, attempts each store step (revoke the family, look up and delete the IdP
+session) independently, and answers `{ endSessionUrl }` — flytedesk ID's RP-initiated
+logout, carrying the session's id_token as `id_token_hint` — or `502
+logout_store_failed` (logged) still carrying `endSessionUrl` when a store step failed.
 
 **Replays of ended families are not reuse (4.0).** A presented refresh token that was
 *rotated* is a concurrent-tab race inside `refreshReuseGraceMs` and reuse outside it
@@ -118,17 +272,11 @@ token back), and a store must not do more work in the transaction after `fn` ret
 honours the whole contract) and `FakeIdp`, whose controls cover the negative paths:
 `setForceSubjectMismatch`, `setForceInvalidClient`, an identity's `emailVerified: false`,
 `setMyAppsFailureStatus`, `setForceRefreshFailure`, the `setHang*Ms` family, and
-`refreshGrantCount`.
-
-**The silent-resume page is hardened (4.0).** The `prompt=none` callback's postMessage
-page carries only a fixed `SilentAuthDetailCode` (anything unknown becomes `"other"`),
-serializes its payload so `<`, `>`, `&`, U+2028 and U+2029 can't escape the inline
-script, and is served with
-`Content-Security-Policy: default-src 'none'; script-src 'sha256-…'; frame-ancestors <postLoginRedirect origin>; base-uri 'none'`
-plus `X-Content-Type-Options: nosniff`.
-
-`onSignIn(profile, request, context)` receives `context.mode`: `"silent"` for a
-hidden-iframe resume, `"interactive"` for a visible sign-in.
+`refreshGrantCount`. It models flytedesk ID's sign-in and sign-out too: with no live
+session (`setIdpSessionLive(false)`) or on `prompt=login`, `/auth` shows a sign-in
+interaction page (`interactionCount`) instead of answering straight away, and
+`/session/end` performs the RP-initiated logout against its registered
+`postLogoutRedirectUris` (`endSessionCount`).
 
 **Residual risk in the refresh-token grace window (RFC 9700 §4.14.2).** `POST
 {routePrefix}/refresh` rotates the presented refresh token on every call and treats a
@@ -172,28 +320,15 @@ token (a lost response, a concurrent tab) that lands on an instance with the OTH
 cannot re-derive the successor and answers 401 — the client treats that browser as signed
 out. Keep the change short, or drain traffic to one secret at a time.
 
-**Failed interactive sign-ins land back in the app, not on a raw JSON error page.**
-`signInUrl` (`FlytedeskAuthOptions`, required) is where `GET {routePrefix}/callback`
-redirects an INTERACTIVE (not `prompt=none`) sign-in failure — idp_error (including
-`access_denied` and `login_required`), an invalid/expired login-attempt cookie, a state
-mismatch, or a token exchange/verification failure — with `?signin_error=<code>`
-appended, `<code>` being one of `"expired"`, `"cancelled"`, or `"other"` (never the raw
-internal failure reason, which is logged server-side only). A **silent** (`prompt=none`)
-callback failure is unaffected: it still answers through the existing postMessage
-contract (`SilentAuthMessage`), consumed only inside `./client/silentAuth.js`'s hidden
-iframe. When the login-attempt cookie is missing entirely (its 10-minute
-`loginAttemptTtlSeconds` already elapsed), the `silent` flag can't be recovered — this is
-deliberately always treated as interactive (`signin_error=expired`): a genuinely silent
-attempt runs in a hidden iframe and resolves within seconds, so an expired cookie in
-practice only ever means an interactive one, and a redirect delivered inside a hidden
-iframe is harmless (invisible to the user; the parent page's own listener just times out
-as it would have anyway).
-
-`./client/signInError.js`'s `consumeSignInError()` reads and clears `signin_error` from
-the current page's URL and returns the plain message to render (or `null` when there
-isn't one) — e.g. `error={consumeSignInError()}` straight into
-`@flytedan/flytebot-design-system`'s `SignInPage` (0.21.0+). `@flytedesk/app-kit` itself
-never depends on the design system; this returns a plain string.
+**Sign-in returns to the exact link; a failed one lands back in the app, never on a raw
+error page.** `GET {routePrefix}/login?returnTo=<path?query#hash>` keeps a same-origin
+target (`safeReturnTarget`; an unsafe or oversize one is dropped and logged, never a
+400) in a signed login-attempt cookie named after the attempt's `state` — so two tabs
+signing in at once never break each other, and at most two attempt cookies exist at a
+time. The callback redirects to that target, or to `postLoginRedirect`. A failed
+callback redirects to the same place with `?signin_error=<expired|cancelled|other>`
+(never the raw internal reason, which is logged server-side only); the browser lifecycle
+reads and strips it and shows the sign-in-failed state with a manual retry.
 
 ## BigQuery (`@flytedesk/app-kit/bigquery`)
 
@@ -209,6 +344,14 @@ import { createBigQueryReadClient } from "@flytedesk/app-kit/bigquery";
 const client = createBigQueryReadClient(new BigQuery());
 ```
 
+**Query parameter types** (`types` on `runQuery` / `estimateQueryBytes`) take the SDK's own shape
+(`BigQueryParamTypes`): `"INT64"` for a scalar, `["INT64"]` for an ARRAY<INT64>, `{ id: "INT64" }`
+for a STRUCT. Declare the type of every empty array and every NULL — the SDK infers an array's
+element type only from its first element. A bare string (or any value with no `.value`) declared DATE, DATETIME, TIME,
+TIMESTAMP or GEOGRAPHY is bound as NULL by the SDK (it reads `.value` off `BigQuery.date()` and
+friends), so both functions reject it with a `BadQueryError` before creating a job; carry a date as
+a STRING and convert in the SQL (`DATE(@since)`).
+
 **Supported `@google-cloud/bigquery` version range: `^9.0.0`** (verified against
 `9.1.0`). `AK-21` added a compile-time conformance test
 (`src/bigquery/type-safety.test.ts`, run as part of `npm run check`) that
@@ -222,6 +365,14 @@ app-kit's own gate instead. Bumping the supported range means re-running that
 test against the new version and updating this section — a passing gate is
 the actual proof, not this paragraph.
 
+## Tests
+
+`npm run check` is the full gate: lint, typecheck, build, unit tests, integration tests
+(Docker, via testcontainers), the real-browser session-lifecycle tests (Playwright, which
+load the built `dist/`), and the package-exports check. The browser tests need Chromium
+once per machine: `npx playwright install chromium`. `npm run test:browser` builds and
+runs them alone.
+
 ## Publishing
 
 Published to the public npm registry under the `@flytedesk` org, access `restricted`.

package/dist/auth/client/authSession.d.ts

@@ -0,0 +1,168 @@
+/**
+ * The flytedesk ID session lifecycle — the ONE owner of every sign-in and session
+ * decision a flytedesk ID app makes (AK-35, PLN-2 R-14; design: PLN-2 architecture
+ * "flytedesk ID session lifecycle"). An app never builds any of this itself: it renders
+ * its shell for a usable session and the design system's `SessionScreen` for the rest
+ * (`./useAuthSession.ts`'s `SessionBoundary`), and reads the session through
+ * `authSession` / `useAuthSession`.
+ *
+ *  - Signed out: shows "signing in" and sends the browser through flytedesk ID with a
+ *    top-level navigation, carrying the exact `path?query#hash` as the return target.
+ *    Sign-in is only ever that navigation: it is the one request that can carry
+ *    `prompt=consent`, which flytedesk ID requires before it issues a refresh token
+ *    (see `../plugin.ts`'s `/login`).
+ *  - Session lost mid-use (a refused refresh, `onSessionEnded`): "session expired", then
+ *    the same automatic sign-in, back to the same URL.
+ *  - Checked every 10 minutes while the tab is visible, and when it becomes visible or
+ *    focused (at most once a minute).
+ *  - An outage (`AuthUnavailableError`) is never a sign-out: "unavailable", retried with
+ *    backoff (AK-23).
+ *  - Sign-out ends this app's session and flytedesk ID's (RP-initiated logout), and never
+ *    bounces straight back in (the server's signed-out marker forces `prompt=login`).
+ *  - Cross-tab: only a visible tab navigates, and while one tab is signing in (a short
+ *    claim) the others wait for its `signed-in` message.
+ *  - Loop guard: a tab that arrives back still signed out within two minutes of starting
+ *    a sign-in, or with `signin_error`, shows the sign-in-failed state with a manual
+ *    retry — never another automatic redirect.
+ *
+ * Framework-agnostic and browser-safe (ZERO Node imports, like `./httpClient.ts`). Every
+ * browser API it touches comes through an `AuthSessionEnvironment`, so the state machine
+ * is tested with a scripted environment and the real one is `browserEnvironment()`.
+ */
+import { AuthUnavailableError } from "./httpClient.js";
+import { type AppSwitcherEntry, type SignInErrorCode } from "../shared-types.js";
+/** How often a visible, signed-in tab verifies its session. */
+export declare const SESSION_CHECK_INTERVAL_MS: number;
+/** A tab becoming visible or focused re-checks at most this often. */
+export declare const FOCUS_CHECK_MIN_INTERVAL_MS = 60000;
+/** A tab arriving back still signed out this soon after starting a sign-in is a loop. */
+export declare const SIGN_IN_LOOP_WINDOW_MS: number;
+/** How long one tab's sign-in claim makes the other visible tabs wait for it — a round
+ *  trip while flytedesk ID is still signed in. */
+export declare const SIGN_IN_CLAIM_MS = 20000;
+/** A page still here this long after handing the browser to a top-level navigation was
+ *  not navigated (the user cancelled it): it acts on its own behalf again. Well past a
+ *  slow round trip, during which the old page legitimately stays up. */
+export declare const NAVIGATION_STALL_MS = 60000;
+/** First delay before re-verifying a session the server could not verify (AK-23). */
+export declare const UNAVAILABLE_RETRY_BASE_MS = 1000;
+/** The backoff's ceiling: an outage is retried every this-many ms at most. */
+export declare const UNAVAILABLE_RETRY_MAX_MS = 30000;
+/** Storage keys and the BroadcastChannel name — one namespace, never an app's. */
+export declare const SIGN_IN_ATTEMPT_KEY = "flytedesk-app-kit.auth.signInStartedAt";
+export declare const SIGN_IN_CLAIM_KEY = "flytedesk-app-kit.auth.signInClaim";
+export declare const SESSION_CHANNEL = "flytedesk-app-kit-session";
+/**
+ * Jittered exponential backoff for the `"unavailable"` state's automatic retries: the
+ * ceiling doubles per attempt (1s, 2s, 4s, … capped at UNAVAILABLE_RETRY_MAX_MS) and the
+ * delay is drawn uniformly from its upper half ("equal jitter", AK-23 L-c) — so every
+ * tab that saw the same outage does not retry in the same instant when it ends.
+ */
+export declare function unavailableRetryDelayMs(attempt: number, random?: () => number): number;
+/** The plain message each sign-in failure shows (AK-19's closed code set). */
+export declare const SIGN_IN_ERROR_MESSAGES: Record<SignInErrorCode, string>;
+/** Verifying the session (at boot, after a bfcache restore, or on retry). */
+export interface CheckingState {
+    status: "checking";
+}
+export interface AuthenticatedState<TUser> {
+    status: "authenticated";
+    user: TUser;
+    /** The "All flytedesk apps" switcher feed — decoration, never the session (AK-23 N2). */
+    apps: AppSwitcherEntry[];
+    appsError: Error | null;
+}
+/** Signed out, or the session ended: the browser is on its way to flytedesk ID (a
+ *  hidden tab waits until it is looked at; a visible tab may wait on another tab's
+ *  sign-in claim). */
+export interface SigningInState {
+    status: "signing-in";
+    reason: "signed-out" | "expired";
+}
+/**
+ * The server could not verify the session right now (AK-23) — flytedesk-id or the app's
+ * AuthStore is down. NOT signed out: re-verified with backoff (`retryInMs`). `user`, when
+ * set, is who was signed in when the outage began — DISPLAY-ONLY, never a basis for an
+ * authorization decision.
+ */
+export interface UnavailableState<TUser> {
+    status: "unavailable";
+    user: TUser | null;
+    apps: AppSwitcherEntry[];
+    appsError: Error | null;
+    error: AuthUnavailableError;
+    retryInMs: number;
+}
+export interface SigningOutState {
+    status: "signing-out";
+}
+/** A sign-in that did not complete (`sign-in-failed`: retry navigates to flytedesk ID
+ *  by hand) or a session check that failed for a reason other than being signed out
+ *  or an outage (`load-failed`: retry checks again). */
+export interface ErrorState {
+    status: "error";
+    kind: "sign-in-failed" | "load-failed";
+    error: Error;
+}
+export type AuthSessionState<TUser> = CheckingState | AuthenticatedState<TUser> | SigningInState | UnavailableState<TUser> | SigningOutState | ErrorState;
+/** Storage the lifecycle keeps its own two keys in. Any method may throw (storage
+ *  blocked), which the lifecycle handles per key. */
+export interface LifecycleStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export type SessionMessage = {
+    type: "signed-in";
+    userId: string;
+} | {
+    type: "signed-out";
+};
+/** Every browser API the lifecycle uses. `browserEnvironment()` is the real one. */
+export interface AuthSessionEnvironment {
+    /** The page's current URL. */
+    href(): string;
+    /** A top-level navigation (`location.assign`). */
+    navigate(url: string): void;
+    /** Rewrites the current URL without navigating (`history.replaceState`). */
+    replaceUrl(url: string): void;
+    reload(): void;
+    isVisible(): boolean;
+    /** Subscribes to becoming visible (`visibilitychange` to "visible") and to `focus`. */
+    onAttention(listener: () => void): () => void;
+    /** Subscribes to a restore from the back/forward cache (`pageshow` with `persisted`). */
+    onRestore(listener: () => void): () => void;
+    /** Per tab — survives the sign-in round trip in this tab only. */
+    sessionStorage(): LifecycleStorage;
+    /** Shared by every tab of the app's origin. */
+    localStorage(): LifecycleStorage;
+    /** The cross-tab channel (BroadcastChannel `SESSION_CHANNEL`). */
+    openChannel(onMessage: (message: SessionMessage) => void): {
+        post(message: SessionMessage): void;
+        close(): void;
+    };
+}
+export interface AuthSessionController {
+    /** The current state, as one stable object per change (for `useSyncExternalStore`). */
+    getSnapshot<TUser>(): AuthSessionState<TUser>;
+    /** Starts the lifecycle on the first subscription. Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Explicit sign-out: ends this app's session, then navigates to flytedesk ID's
+     * RP-initiated logout so its session ends too. Rejects — leaving the session as the
+     * server says it is — when the server did not end it (an `Origin` refusal, a proxy
+     * error, no answer).
+     */
+    signOut(): Promise<void>;
+    /** The failure states' action: `sign-in-failed` starts a sign-in by hand;
+     *  `load-failed` checks the session again. */
+    retry(): void;
+    /** Re-reads the signed-in user (`GET {routePrefix}/me`) — for an app that just changed
+     *  it server-side. Resolves once the snapshot carries the user as read AFTER the call.
+     *  Does nothing unless the session is `authenticated` (there is no user to refresh
+     *  while signing in or out, and during an outage the next successful load reads it). */
+    refreshUser(): Promise<void>;
+    /** Stops every timer and listener (tests; a page unloading needs nothing). */
+    stop(): void;
+}
+export declare function createAuthSession(env: AuthSessionEnvironment): AuthSessionController;