@flytedesk/app-kit 3.2.2 → 4.0.0

package/dist/auth/types.d.ts

@@ -19,6 +19,22 @@ export interface UserinfoClaims {
  *  shape `GET {api}{routePrefix}/me` returns to the browser, see ./shared-types.js's
  *  AuthedUserDto doc comment for why this is a single definition rather than two. */
 export type AuthedUser = AuthedUserDto;
+/**
+ * Why a refresh-token row stopped being usable (AK-23). `"rotated"`: `rotateRefreshToken`
+ * replaced it with a successor — the ONLY reason a later presentation of it can be a
+ * concurrent-tab race rather than reuse (see `FlytedeskAuthOptions.refreshReuseGraceMs`).
+ * Every other value is the `RevokeFamilyReason["type"]` of the `revokeFamily` call that
+ * ended this row's family while the row was still live.
+ */
+export type RefreshTokenRevocationReason = "rotated" | RevokeFamilyReason["type"];
+/** When and why one refresh-token row was revoked — see `RefreshTokenRow.revocation`. */
+export interface RefreshTokenRevocation {
+    /** EXACTLY the time the plugin passed to the `rotateRefreshToken` or `revokeFamily`
+     *  call that revoked the row — the app's clock, never the database's (see `AuthStore`'s
+     *  ONE-clock rule). */
+    at: Date;
+    reason: RefreshTokenRevocationReason;
+}
 export interface RefreshTokenRow {
     id: string;
     /** Shared by every refresh token descended from the same login, via rotation.
@@ -27,24 +43,39 @@ export interface RefreshTokenRow {
     familyId: string;
     userId: string;
     idpSessionId: string;
-    revokedAt: Date | null;
     expiresAt: Date;
+    /** The client this token was issued to — `CreateRefreshTokenInput.ip`/`userAgent`, as
+     *  persisted. The plugin logs them beside the presenting request's own when a
+     *  just-rotated token comes back inside the grace window (AK-23). */
+    ip: string;
+    userAgent: string | null;
     /**
-     * AK-14 (gap 3; MP-127): whether some OTHER row's `replacesId` points at this one —
-     * i.e. this token's presentation was, at some point, followed by a successful
-     * rotation, as opposed to being revoked directly (a logout, or reuse detection
-     * itself). Only a rotated token's LATE replay (`revokedAt` already set when
-     * `findRefreshTokenByHash` read this row, outside `refreshReuseGraceMs`) can be a
-     * concurrent-tab race; `../plugin.ts`'s `POST {routePrefix}/refresh` reads this
-     * straight off the row it already fetched — never recomputed on any other code path —
-     * specifically so its answer reflects a fully-committed state, not one still
-     * in-flight in a sibling request (see that route's doc comment for why a same-instant
-     * race is instead decided entirely by `claimRefreshTokenForRotation`'s atomicity,
-     * not by this field).
+     * `null` while the token is live. Otherwise the FIRST revocation this row received —
+     * never overwritten by a later one (`revokeFamily` only touches still-live rows), so a
+     * token that was rotated and whose family was later signed out still reads
+     * `"rotated"`.
+     *
+     * A row whose revocation time is set but whose reason is missing (only possible if a
+     * store skipped the migration's CHECK constraint) MUST still read as revoked — never
+     * as live — with a non-`"rotated"` reason.
+     *
+     * AK-23 replaced 3.x's `revokedAt` + derived `rotated` pair with this one field:
+     * `POST {routePrefix}/refresh` needs to know WHY a presented token is dead, not just
+     * that it is. A replay of a token whose family was already ended by a sign-out or an
+     * authorization rejection is a dead session, not a reuse attack, and must not be
+     * reported (or audited) as `reuse_detected` — see that route's doc comment in
+     * `./plugin.ts`.
      */
-    rotated: boolean;
+    revocation: RefreshTokenRevocation | null;
 }
+/** One refresh-token row to insert: the first of a family (`createRefreshToken`, at
+ *  login) or the successor of a rotated one (`rotateRefreshToken`). */
 export interface CreateRefreshTokenInput {
+    /** The plugin's own random UUID for this row. A store MUST persist it exactly as given
+     *  and return it as `RefreshTokenRow.id` — never substitute a generated or sequential
+     *  id. The successor of a rotated token is derived from this server-only id (AK-23), so
+     *  a guessable id would let a leaked `accessTokenSecret` plus an old cookie compute the
+     *  family's live token offline. */
     id: string;
     familyId: string;
     userId: string;
@@ -55,14 +86,6 @@ export interface CreateRefreshTokenInput {
     idpSessionId: string;
     userAgent: string | null;
     ip: string;
-    /**
-     * The id of the refresh token this one was rotated FROM, or `null` for the first
-     * token of a family (issued at login). AK-14: this is what `RefreshTokenRow.rotated`
-     * (above) answers — see that field's doc comment and `../plugin.ts`'s
-     * `refreshReuseGraceMs` for how a late replay of a rotated token is told apart from
-     * reuse.
-     */
-    replacesId: string | null;
 }
 export interface IdpSessionRow {
     id: string;
@@ -86,77 +109,158 @@ export interface UpdateIdpSessionInput {
     idpAccessTokenExpiresAt?: Date;
     idpRefreshToken?: string | null;
 }
+/**
+ * The IdP-session reads and writes the plugin makes while holding
+ * `AuthStore.withIdpSessionLock` — the store `fn` receives (AK-23). A Postgres-backed
+ * implementation MUST run both methods on the SAME transaction (hence the same pooled
+ * connection) that holds the lock. See `withIdpSessionLock`'s doc comment for why.
+ */
+export interface IdpSessionLockedStore {
+    findIdpSession(id: string): Promise<IdpSessionRow | null>;
+    updateIdpSession(id: string, patch: UpdateIdpSessionInput): Promise<void>;
+}
 /**
  * Storage seam this package needs, and nothing more — kept ORM-agnostic (no Prisma
  * import here) so a consumer can back it with whatever their own DB layer already is.
  * The two "families" of rows below mirror media-planner's RefreshToken/IdpSession
  * tables, which this module generalizes from (see DEC-38).
+ *
+ * Every method may throw on a storage failure; the plugin wraps whatever it throws in
+ * `AuthStoreError` and never mistakes it for "not found" or "rejected" (AK-23): a store
+ * outage during `POST {routePrefix}/refresh` answers 503 and revokes nothing.
+ *
+ * **ONE clock (AK-23).** Every time the plugin later compares — `RefreshTokenRow.expiresAt`,
+ * `RefreshTokenRow.revocation.at`, `IdpSessionRow.idpAccessTokenExpiresAt` — is stamped by
+ * the plugin from the app's clock and handed to the store (`expiresAt` on an inserted
+ * row, the `rotatedAt`/`revokedAt` argument of `rotateRefreshToken`/`revokeFamily`), and
+ * the plugin compares it against that same clock. A store MUST persist and return these
+ * values exactly as given and MUST NOT stamp any of them itself — no SQL `now()`, no
+ * column `DEFAULT now()`, no Prisma `@default(now())` / `@updatedAt`, no `new Date()`. A
+ * database clock even seconds off the app's moves the refresh-token grace-window
+ * decision: behind, a concurrent-tab race reads as reuse and signs the user out; ahead,
+ * a replay reads as a race and reuse detection never fires. (A store-side `new Date()` is
+ * the app's clock, so it is not skewed — but it is not what the plugin compares either.)
+ * The plugin compares against the clock read at the start of a request and stamps each
+ * revocation time from the clock at the moment of the write, so a slow authorization
+ * step cannot make it land early. Multiple app instances are assumed to run NTP-synced
+ * clocks.
  */
-export interface AuthStore {
+export interface AuthStore extends IdpSessionLockedStore {
+    /** Inserts the FIRST token of a fresh family, at login. Replaces nothing. */
     createRefreshToken(row: CreateRefreshTokenInput): Promise<void>;
+    /** The row whose `tokenHash` matches, live or revoked, or `null` when none does. */
     findRefreshTokenByHash(hash: string): Promise<RefreshTokenRow | null>;
     /**
-     * MUST be implemented as a single atomic conditional update — e.g.
-     * `UPDATE refresh_tokens SET revoked_at = now() WHERE id = $1 AND revoked_at IS NULL`
-     * — returning whether THIS call was the one that actually revoked the row (true), as
-     * opposed to finding it already revoked (false, by a prior request or a concurrent
-     * one that won the race).
+     * Rotates one refresh token (AK-23): in ONE transaction, revoke `presentedId` with
+     * reason `"rotated"` — conditionally, only if it is still live — and, only if that
+     * revoke claimed the row, insert `successor` recording that it replaces
+     * `presentedId`. Returns whether this call rotated it (`true`), or found it already
+     * revoked (`false`, by an earlier request or a concurrent sibling that won the race —
+     * and then inserts nothing).
+     *
+     * Both halves are one atomic unit, never two calls:
+     *  - The conditional revoke must be a single statement (e.g.
+     *    `UPDATE refresh_tokens SET revoked_at = $2, revoked_reason = 'rotated'
+     *     WHERE id = $1 AND revoked_at IS NULL` with `$2` = `rotatedAt`, claimed iff one
+     *    row changed) — a separate
+     *    read then write lets two same-instant `/refresh` calls both see the token live,
+     *    both rotate, and the replay go undetected.
+     *  - The insert must commit or roll back WITH that revoke. 3.x's separate
+     *    `claimRefreshTokenForRotation` + `createRefreshToken` could fail between the two,
+     *    leaving a revoked token with no successor: the browser's next refresh presented it
+     *    again and raised a false `reuse_detected` alarm.
      *
-     * This is the fix for a real race in the plugin's original find-then-revoke logic:
-     * two /refresh calls presenting the same still-valid token at the same instant could
-     * both read `revokedAt: null` before either write landed, both rotate successfully,
-     * and the replay would go undetected. A plain `find -> check -> revoke` sequence in
-     * the CALLER can't close this gap no matter how carefully it's written — the
-     * atomicity has to live in this one storage operation. Never implement this as a
-     * separate read followed by an unconditional write.
+     * `rotatedAt` is the revocation time to record (`revocation.at`), from the app's clock —
+     * see the ONE-clock rule above.
      *
-     * AK-14 (gap 3; MP-127): `../plugin.ts`'s `POST {routePrefix}/refresh` only ever calls
-     * this for a token whose `findRefreshTokenByHash` read, moments earlier in the SAME
-     * request, showed `revokedAt: null` — i.e. as far as this request could tell, the
-     * token still looked live. A `false` result here therefore means a SIBLING request
-     * claimed it in the tiny window since that read: a genuine, same-instant
-     * concurrent-tab race, decided by this method's atomicity alone — unconditionally
-     * treated as a race (401, nothing revoked), with no timing/rotated check needed,
-     * exactly matching media-planner's own `updateMany({revokedAt: null}); if (count !==
-     * 1) return false` shape. A LATE replay of an already (and by now long-since)
-     * rotated-away token is a different code path entirely: it never reaches this method
-     * at all, because `findRefreshTokenByHash`'s OWN `revokedAt`/`rotated` answer (read
-     * before this is ever called) already resolves it — see that field's doc comment.
+     * `POST {routePrefix}/refresh` only calls this for a token `findRefreshTokenByHash` had
+     * just read as live, so `false` always means a same-instant concurrent-tab race (the
+     * plugin then answers with the sibling's successor; nothing is revoked).
+     *
+     * MUST be serialized against `revokeFamily` for the same family — see that method.
      */
-    claimRefreshTokenForRotation(id: string): Promise<boolean>;
+    rotateRefreshToken(presentedId: string, successor: CreateRefreshTokenInput, rotatedAt: Date): Promise<boolean>;
     /**
-     * Revoke every row sharing this familyId — called for reuse detection, sign-out, and
-     * an authorization rejection on refresh (see `RevokeFamilyReason`, AK-20 gap 2327).
-     * `reason` carries WHY, so a consumer's implementation can write its own audit record
-     * (e.g. media-planner's reuse-detection log) without the plugin knowing anything about
-     * that consumer's audit schema — see `RevokeFamilyReason`'s doc comment for what each
-     * variant carries.
+     * Revokes every still-live row sharing this familyId, recording `reason.type` as each
+     * row's `RefreshTokenRevocation.reason` — rows already revoked keep their original
+     * revocation. Called for reuse detection, sign-out, and an authorization rejection on
+     * refresh (see `RevokeFamilyReason`). `reason` also carries what a consumer needs to
+     * write its own audit record (e.g. media-planner's reuse-detection log) without the
+     * plugin knowing that consumer's audit schema.
+     *
+     * MUST be serialized against `rotateRefreshToken` for the same family (AK-23). Under
+     * Postgres's default READ COMMITTED, this method's UPDATE runs on a snapshot taken
+     * when it starts, so a successor a concurrent rotation has inserted but not yet
+     * committed is invisible to it: the rotation commits after, and its successor is a
+     * LIVE token of a family that was just signed out (or revoked for reuse). Take the
+     * same per-family lock in both methods, inside their transactions — e.g.
+     * `acquireAdvisoryLock(tx, { namespace: "refresh-token-family", id: familyId }, ms)`
+     * from `@flytedesk/app-kit/postgres` — so whichever runs second sees the other's
+     * committed rows.
+     *
+     * `revokedAt` is the revocation time to record on every row this revokes, from the
+     * app's clock — see the ONE-clock rule above.
      */
-    revokeFamily(familyId: string, reason: RevokeFamilyReason): Promise<void>;
+    revokeFamily(familyId: string, reason: RevokeFamilyReason, revokedAt: Date): Promise<void>;
     createIdpSession(row: CreateIdpSessionInput): Promise<{
         id: string;
     }>;
-    findIdpSession(id: string): Promise<IdpSessionRow | null>;
-    updateIdpSession(id: string, patch: UpdateIdpSessionInput): Promise<void>;
+    /** Idempotent: an already-deleted session is success, not an error. */
     deleteIdpSession(id: string): Promise<void>;
     /**
-     * Runs `fn` while holding an exclusive, per-session lock (AK-20, gap 2326) — a
-     * Postgres-backed store implements this with an advisory lock scoped to `sessionId`
-     * (e.g. `pg_advisory_xact_lock(hashtext(sessionId))`, taken and released within the
-     * same transaction `fn` runs in), so the lock is held across concurrent requests on
-     * different server instances, not just within one process; an in-memory store (tests,
-     * the hello-world example) can implement it with a simple per-key mutex/queue.
+     * Runs `fn` while holding an exclusive, per-session lock (AK-20, gap 2326), handing it
+     * an `IdpSessionLockedStore` bound to that lock (AK-23).
+     *
+     * Why the lock: flytedesk-id rotates its own refresh token on every use, so two
+     * concurrent requests on the same near-expiry session could both read "stale", both
+     * refresh with the SAME refresh token, and the loser would present one flytedesk-id
+     * already rotated away — signing a perfectly good session out. `../plugin.ts`'s
+     * `getLiveIdpAccessToken` re-reads the session inside the lock and skips its own
+     * refresh when a sibling already did it.
+     *
+     * Why `fn` gets a store: a Postgres implementation holds the lock inside a
+     * transaction (one pooled connection). In 3.x, `fn` called the store's ordinary
+     * `findIdpSession`/`updateIdpSession`, each needing a SECOND pooled connection while
+     * the first sat holding the lock. With as many concurrent stale-session requests as
+     * the pool has connections, every connection was held by a lock transaction waiting
+     * for a second one: the pool starved, the transactions timed out, and (in 3.x) every
+     * one of those sessions was signed out. The store passed to `fn` MUST issue its
+     * queries on the lock's own transaction, so a lock holder never needs a second
+     * connection.
      *
-     * Fixes a real race in `../plugin.ts`'s `getLiveIdpAccessToken`: flytedesk-id rotates
-     * its own refresh token on every use, so two concurrent requests on the same
-     * near-expiry session could both read "stale" before either write landed, both call
-     * `oidc.refreshIdpTokens` with the SAME (about-to-be-consumed) refresh token, and the
-     * loser's request then presents a refresh token flytedesk-id has already rotated away
-     * — getting that otherwise perfectly legitimate session signed out. Every caller of
-     * `getLiveIdpAccessToken` re-reads the session INSIDE the lock and skips its own
-     * refresh if a sibling request already refreshed it while this one was waiting.
+     * A Postgres implementation, with `@flytedesk/app-kit/postgres`:
+     *
+     *     withIdpSessionLock(sessionId, fn) {
+     *       return prisma.$transaction(async (tx) => {
+     *         await acquireAdvisoryLock(tx, { namespace: "idp-session", id: sessionId }, 5_000);
+     *         return fn(lockedStoreOn(tx)); // findIdpSession/updateIdpSession via `tx`
+     *       }, { maxWait: 5_000, timeout: 15_000 });
+     *     }
+     *
+     * `timeout` must exceed the lock wait plus one `idpRequestTimeoutMs` IdP call plus
+     * the transaction's own queries. A lock timeout, a `maxWait` expiry, or any other
+     * throw simply propagates: the plugin treats it as a store outage (503 at `/refresh`,
+     * no revocation), never as a rejected session. An in-memory store (tests) can
+     * implement this with a per-key promise queue.
+     *
+     * **Residual risk — a lost IdP refresh token (AK-23).** flytedesk-id rotates its
+     * refresh token the moment it answers a refresh, so from then until this transaction
+     * commits, the ONLY copy of the new token is in the plugin's memory. If
+     * `locked.updateIdpSession` or the commit fails in that window (the database drops
+     * the connection, the transaction's `timeout` fires, the process dies), the new
+     * token is lost and the stored one is already consumed: the session's next IdP
+     * refresh gets `invalid_grant`, which is a revocation, and that user must sign in
+     * again. No code on this side can close it — the IdP call cannot join the
+     * transaction. The plugin keeps the window as small as it can: the patch is built
+     * with no step that can throw, `updateIdpSession` is the first call after the IdP
+     * answers, and nothing else runs before the commit. `fn` never throws an IdP outcome
+     * — it RETURNS it, and the plugin throws only after this method has resolved — so a
+     * store that rolls back when `fn` throws (as every transaction does) only ever rolls
+     * back a failed store call, never a persisted rotation. A store keeps its part small by
+     * doing nothing inside `fn`'s transaction after `fn` returns, and by sizing
+     * `timeout` as above so it cannot fire while an IdP response is in flight.
      */
-    withIdpSessionLock<T>(sessionId: string, fn: () => Promise<T>): Promise<T>;
+    withIdpSessionLock<T>(sessionId: string, fn: (locked: IdpSessionLockedStore) => Promise<T>): Promise<T>;
 }
 /**
  * Why `AuthStore.revokeFamily` (above) is revoking a family — AK-20, gap 2327. Lets a
@@ -166,10 +270,11 @@ export interface AuthStore {
  * consumer's audit schema.
  */
 export type RevokeFamilyReason = {
-    /** A refresh token already rotated away was presented again — either a genuine
-     *  replay/leak, or a same-cookie-jar tab's request that arrived too late to be
-     *  treated as a race (see `RefreshTokenRow.rotated`'s doc comment and
-     *  `FlytedeskAuthOptions.refreshReuseGraceMs`). */
+    /** A refresh token already ROTATED away was presented again outside
+     *  `FlytedeskAuthOptions.refreshReuseGraceMs` — a genuine replay/leak, or a
+     *  same-cookie-jar tab's request that arrived too late to be treated as a race.
+     *  Never raised for a token whose revocation reason is anything but `"rotated"`
+     *  (AK-23): those families were already ended on purpose. */
     type: "reuse_detected";
     /** The refresh token row that was replayed, exactly as `findRefreshTokenByHash`
      *  read it. */
@@ -179,16 +284,25 @@ export type RevokeFamilyReason = {
     ip: string;
     userAgent: string | null;
 } | {
-    /** POST {routePrefix}/logout — the family is revoked unconditionally as part of
-     *  ending the session, independent of anything else about the request. */
+    /** POST {routePrefix}/logout — the family is revoked as part of ending the
+     *  session, independent of anything else about the request. */
     type: "signed_out";
 } | {
     /** POST {routePrefix}/refresh ran the SAME authorization pipeline
-     *  `loadAuthedUser` runs (live IdP authorization, `onAuthorizeUser`) and it
-     *  rejected this session — e.g. a locally-suspended user, a role flytedesk-id
-     *  since revoked, or the backing IdP session no longer existing at all. */
+     *  `loadAuthedUser` runs and it definitively rejected this session: flytedesk-id
+     *  answered that access is revoked (`IdpAccessRevokedError`), `onAuthorizeUser`
+     *  returned `null`, or the backing IdP session no longer exists. An IdP outage, a
+     *  lock timeout, a store error or a THROWING `onAuthorizeUser` is not a
+     *  rejection and never lands here (AK-23). */
     type: "authorization_rejected";
 };
+/** Whether a `/callback` completed a hidden-iframe `prompt=none` resume or a visible,
+ *  user-driven sign-in (AK-23). */
+export type SignInMode = "silent" | "interactive";
+/** The third argument `FlytedeskAuthOptions.onSignIn` receives. */
+export interface SignInContext {
+    mode: SignInMode;
+}
 export interface FlytedeskAuthOptions {
     /** This app's OAuth client_id, as registered with flytedesk-id. */
     clientId: string;
@@ -224,8 +338,10 @@ export interface FlytedeskAuthOptions {
     /** Gates the __Host- cookie prefix (requires Secure — see ./plugin.ts). Set false only
      *  for local HTTP dev. */
     secureCookies: boolean;
-    /** HS256 signing secret for this service's own short-lived access token. Never shared
-     *  with flytedesk-id or any other app. */
+    /** HS256 signing secret for this service's own short-lived access token, and the input
+     *  key refresh-token rotation derives its successor key from (AK-23). At least 32 bytes
+     *  (UTF-8) — registration throws otherwise. Never shared with flytedesk-id or any other
+     *  app. See the README on recovering from a leak. */
     accessTokenSecret: string;
     /** Default 900 (15 minutes). */
     accessTokenTtlSeconds?: number;
@@ -242,10 +358,18 @@ export interface FlytedeskAuthOptions {
      */
     authorizationCacheTtlMs?: number;
     store: AuthStore;
-    /** Called once per successful /callback, after profile verification and before the
-     *  session is issued — the hook for a consumer's own app-specific bookkeeping (e.g.
-     *  upserting a local profile row, checking a local suspension flag). */
-    onSignIn?: (profile: UserinfoClaims, request: FastifyRequest) => Promise<void> | void;
+    /**
+     * Called once per successful /callback, after profile verification and before the
+     * session is issued — the hook for a consumer's own app-specific bookkeeping (e.g.
+     * upserting a local profile row, checking a local suspension flag, writing a sign-in
+     * audit record). `context.mode` (AK-23) says whether this was a hidden-iframe
+     * `prompt=none` resume (`"silent"`) or a visible sign-in (`"interactive"`), so an
+     * audit trail can tell a user actively signing in apart from a page reload quietly
+     * resuming their flytedesk-id session. Throwing aborts the sign-in (no session is
+     * issued): an interactive attempt redirects to `signInUrl` with
+     * `signin_error=other`, a silent one answers `detail: "idp_exchange_failed"`.
+     */
+    onSignIn?: (profile: UserinfoClaims, request: FastifyRequest, context: SignInContext) => Promise<void> | void;
     /**
      * OAuth scopes requested at `{routePrefix}/login`. Default
      * `["openid", "email", "profile", "offline_access"]` (AK-14, gap 1) — `offline_access`
@@ -277,14 +401,19 @@ export interface FlytedeskAuthOptions {
      * §4.14.2). Two browser tabs share one cookie jar: the loser of a rotation sends the
      * now-stale cookie only if it did so before the winner's `Set-Cookie` reached the
      * browser, so a race's loser can only ever present a token that WAS rotated
-     * (`AuthStore.claimRefreshTokenForRotation`'s `rotated: true`), and only within
+     * (`RefreshTokenRow.revocation.reason === "rotated"`), and only within
      * roughly two client request round-trips of that rotation. Default
      * `2 * AUTH_REQUEST_DEADLINE_MS` (`../shared-types.js`) — matching media-planner's
      * `REFRESH_REUSE_GRACE_MS`, which observed a real race's loser arriving 60ms after the
-     * winner's rotation (MP-112) — comfortably inside this default. A presentation of a
-     * token that was NOT rotated (no successor row references it — e.g. it was revoked
-     * directly, by a logout or by reuse detection itself) is ALWAYS treated as reuse,
-     * regardless of this window: only a rotation can be a race.
+     * winner's rotation (MP-112) — comfortably inside this default. Inside the window the
+     * IMMEDIATELY previous token is answered with the SAME successor its rotation issued,
+     * when that successor is still the family's live token (AK-23) — which is also what
+     * saves a browser whose refresh response was lost after the server rotated. A token two
+     * or more rotations back is reuse even inside the window. Outside the window a rotated
+     * token's replay is reuse (`reuse_detected`, the family is revoked). A token
+     * revoked for any OTHER reason (its family was signed out, rejected, or already
+     * revoked for reuse) is a dead session, not a race and not a new reuse: 401 and the
+     * cookie cleared, nothing revoked or reported again (AK-23).
      */
     refreshReuseGraceMs?: number;
     /**
@@ -298,11 +427,17 @@ export interface FlytedeskAuthOptions {
      * of which is otherwise reachable from outside the plugin, since `onSignIn` only ever
      * fires once, at `/callback` time.
      *
-     * Returning `null` rejects the request exactly like an IdP-side authorization failure
-     * (`request.authUser` stays unset; `requireAuth` 401s). Returning a user (the same one
-     * passed in, or a modified copy) is what gets attached. Throwing, or a rejected
-     * promise, is treated as a rejection too (fail loudly, AK-16: logged with context,
-     * never a 500) — a hook error must never be indistinguishable from "authenticated".
+     * Returning `null` rejects the session exactly like an IdP-side authorization
+     * revocation: `request.authUser` stays unset (`requireAuth` answers 401), and at
+     * `POST {routePrefix}/refresh` the whole refresh-token family is revoked
+     * (`authorization_rejected`). Returning a user (the same one passed in, or a modified
+     * copy) is what gets attached.
+     *
+     * Throwing, or a rejected promise, is an OUTAGE, not a verdict (AK-23): it is logged
+     * with context (fail loudly, AK-16) and the request is never authenticated, but
+     * `requireAuth` and `/refresh` answer 503 (`authorization_hook_failed`) and nothing is
+     * revoked — a hook's own database blip must not
+     * sign users out. Return `null` to reject; throw only when you could not decide.
      */
     onAuthorizeUser?: (user: AuthedUser, request: FastifyRequest) => Promise<AuthedUser | null> | AuthedUser | null;
 }

package/dist/auth/unavailable.d.ts

@@ -0,0 +1,10 @@
+import type { FastifyReply } from "fastify";
+import type { AuthUnavailableCode } from "./shared-types.js";
+/**
+ * The one answer for "the plugin could not decide whether this session is authorized"
+ * (AK-23): 503, a fixed message, and the cause as `code` (`AUTH_UNAVAILABLE_CODES`).
+ * Shared by `POST {routePrefix}/refresh`, `requireAuth`/`requirePermission` and the
+ * plugin's own authenticated routes, so every outage looks the same to a client — and
+ * never like the 401 that means "signed out".
+ */
+export declare function sendAuthUnavailable(reply: FastifyReply, code: AuthUnavailableCode): FastifyReply;

package/dist/auth/unavailable.js

@@ -0,0 +1,11 @@
+/**
+ * The one answer for "the plugin could not decide whether this session is authorized"
+ * (AK-23): 503, a fixed message, and the cause as `code` (`AUTH_UNAVAILABLE_CODES`).
+ * Shared by `POST {routePrefix}/refresh`, `requireAuth`/`requirePermission` and the
+ * plugin's own authenticated routes, so every outage looks the same to a client — and
+ * never like the 401 that means "signed out".
+ */
+export function sendAuthUnavailable(reply, code) {
+    return reply.code(503).send({ error: "Sign-in could not be verified right now — try again", code });
+}
+//# sourceMappingURL=unavailable.js.map

package/dist/auth/unavailable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unavailable.js","sourceRoot":"","sources":["../../src/auth/unavailable.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAmB,EAAE,IAAyB;IAChF,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,qDAAqD,EAAE,IAAI,EAAE,CAAC,CAAC;AACtG,CAAC"}

package/dist/bigquery/errors.d.ts

@@ -10,6 +10,13 @@ export declare class BadQueryError extends BigQueryReadError {
 export declare class PermissionDeniedError extends BigQueryReadError {
     constructor(message: string, cause?: unknown);
 }
+/** BigQuery's own rate-limit/quota class of error (e.g. "too many table
+ *  update operations for this table" on a load job). Transient — distinct
+ *  from PermissionDeniedError so a caller (or an operator reading logs)
+ *  doesn't chase IAM for what's actually a retryable quota condition. */
+export declare class RateLimitExceededError extends BigQueryReadError {
+    constructor(message: string, cause?: unknown);
+}
 /** A dry-run estimate exceeded the caller-supplied byte budget — thrown
  *  before any billable query actually runs. */
 export declare class DryRunBudgetExceededError extends BigQueryReadError {
@@ -17,6 +24,17 @@ export declare class DryRunBudgetExceededError extends BigQueryReadError {
     readonly maxBytesBilled: number;
     constructor(totalBytesProcessed: number, maxBytesBilled: number);
 }
+/** BigQuery itself refused to run a real job because it would bill more than
+ *  the `maximumBytesBilled` passed to `runQuery` — distinct from
+ *  `DryRunBudgetExceededError`, which is this module's own client-side check
+ *  against a *dry-run* estimate. BigQuery reports this as an `invalidQuery`-
+ *  reasoned error whose message names "bytes billed" (see
+ *  `MAXIMUM_BYTES_BILLED_REASON_TEXT` below); this class exists so a caller
+ *  can branch on the billing cap specifically instead of catching a generic
+ *  BadQueryError. */
+export declare class MaximumBytesBilledExceededError extends BigQueryReadError {
+    constructor(message: string, cause?: unknown);
+}
 /**
  * Normalizes anything a BigQueryLike call can throw/reject with (a Google API
  * client error, a job's `status.errorResult`/`status.errors`, or an already-
@@ -27,8 +45,8 @@ export declare function classifyBigQueryError(err: unknown): BigQueryReadError;
 /**
  * True only for BigQuery's own rate-limit/quota class of error. Deliberately
  * narrow: a bad schema, a permissions/auth failure, or any other error must
- * keep failing immediately, not get masked behind a retry loop. Checks both
- * the structured `errors[].reason` the client library attaches and, as a
- * fallback, the reason text embedded in a raw REST error's `message`.
+ * keep failing immediately, not get masked behind a retry loop. Retryable
+ * exactly when `classifyBigQueryError` would report a RateLimitExceededError
+ * (see `isRateLimited`).
  */
 export declare function isRetryableBigQueryError(err: unknown): boolean;

package/dist/bigquery/errors.js

@@ -20,6 +20,16 @@ export class PermissionDeniedError extends BigQueryReadError {
         this.name = "PermissionDeniedError";
     }
 }
+/** BigQuery's own rate-limit/quota class of error (e.g. "too many table
+ *  update operations for this table" on a load job). Transient — distinct
+ *  from PermissionDeniedError so a caller (or an operator reading logs)
+ *  doesn't chase IAM for what's actually a retryable quota condition. */
+export class RateLimitExceededError extends BigQueryReadError {
+    constructor(message, cause) {
+        super(message, cause);
+        this.name = "RateLimitExceededError";
+    }
+}
 /** A dry-run estimate exceeded the caller-supplied byte budget — thrown
  *  before any billable query actually runs. */
 export class DryRunBudgetExceededError extends BigQueryReadError {
@@ -32,6 +42,20 @@ export class DryRunBudgetExceededError extends BigQueryReadError {
         this.name = "DryRunBudgetExceededError";
     }
 }
+/** BigQuery itself refused to run a real job because it would bill more than
+ *  the `maximumBytesBilled` passed to `runQuery` — distinct from
+ *  `DryRunBudgetExceededError`, which is this module's own client-side check
+ *  against a *dry-run* estimate. BigQuery reports this as an `invalidQuery`-
+ *  reasoned error whose message names "bytes billed" (see
+ *  `MAXIMUM_BYTES_BILLED_REASON_TEXT` below); this class exists so a caller
+ *  can branch on the billing cap specifically instead of catching a generic
+ *  BadQueryError. */
+export class MaximumBytesBilledExceededError extends BigQueryReadError {
+    constructor(message, cause) {
+        super(message, cause);
+        this.name = "MaximumBytesBilledExceededError";
+    }
+}
 /** Reason codes the Google APIs client library attaches to a rejected job
  *  promise's `.errors[]` — see
  *  https://cloud.google.com/bigquery/docs/error-messages for the full list.
@@ -53,6 +77,35 @@ const BAD_QUERY_REASONS = new Set([
  *  almost always succeeds seconds later, so callers (see `loadRowsWithRetry`
  *  in ./load.js) retry on this and only this. */
 const RATE_LIMIT_REASONS = new Set(["rateLimitExceeded", "quotaExceeded"]);
+const RATE_LIMIT_REASON_TEXT = new RegExp([...RATE_LIMIT_REASONS].join("|"));
+/** BigQuery reports a `maximumBytesBilled` refusal as an `invalidQuery`-
+ *  reasoned error whose message reads e.g. "Query exceeded limit for bytes
+ *  billed: 123456789. Limit: 100000000." — text-matched (case-insensitively)
+ *  since it shares its `reason` with every other bad-query case. */
+const MAXIMUM_BYTES_BILLED_REASON_TEXT = /bytes billed/i;
+/** The structured `errors[]` entry that carries a rate-limit reason, wherever it
+ *  sits in the list — so a rate limit reported as a later entry is both detected
+ *  and described by its own message, not an unrelated sibling's. */
+function rateLimitCause(apiErr) {
+    return apiErr?.errors?.find((cause) => cause.reason !== undefined && RATE_LIMIT_REASONS.has(cause.reason));
+}
+/**
+ * The one definition of "BigQuery rate-limited this call", shared by
+ * `classifyBigQueryError` and `isRetryableBigQueryError` so that what gets
+ * retried and how a retry-exhausted failure is reported can never disagree.
+ * True for any structured `errors[].reason` in RATE_LIMIT_REASONS or, for a raw
+ * REST error with no `errors[]`, that reason text in its `message`.
+ */
+function isRateLimited(err) {
+    if (err instanceof RateLimitExceededError)
+        return true;
+    if (!err || typeof err !== "object")
+        return false;
+    const apiErr = err;
+    if (rateLimitCause(apiErr))
+        return true;
+    return typeof apiErr.message === "string" && RATE_LIMIT_REASON_TEXT.test(apiErr.message);
+}
 /**
  * Normalizes anything a BigQueryLike call can throw/reject with (a Google API
  * client error, a job's `status.errorResult`/`status.errors`, or an already-
@@ -63,17 +116,25 @@ export function classifyBigQueryError(err) {
     if (err instanceof BigQueryReadError)
         return err;
     const apiErr = err;
-    const detail = apiErr?.errors?.[0];
+    // The entry that explains the classification: the rate-limit cause when there
+    // is one (it decides the class below), otherwise the first reported error.
+    const detail = rateLimitCause(apiErr) ?? apiErr?.errors?.[0];
     const reason = detail?.reason;
     const message = detail?.message ??
         apiErr?.message ??
         (err instanceof Error ? err.message : String(err));
+    if (isRateLimited(err)) {
+        return new RateLimitExceededError(message, err);
+    }
     if (reason && PERMISSION_DENIED_REASONS.has(reason)) {
         return new PermissionDeniedError(message, err);
     }
     if (apiErr?.code === 403) {
         return new PermissionDeniedError(message, err);
     }
+    if (MAXIMUM_BYTES_BILLED_REASON_TEXT.test(message)) {
+        return new MaximumBytesBilledExceededError(message, err);
+    }
     if (reason && BAD_QUERY_REASONS.has(reason)) {
         return new BadQueryError(message, err);
     }
@@ -85,18 +146,11 @@ export function classifyBigQueryError(err) {
 /**
  * True only for BigQuery's own rate-limit/quota class of error. Deliberately
  * narrow: a bad schema, a permissions/auth failure, or any other error must
- * keep failing immediately, not get masked behind a retry loop. Checks both
- * the structured `errors[].reason` the client library attaches and, as a
- * fallback, the reason text embedded in a raw REST error's `message`.
+ * keep failing immediately, not get masked behind a retry loop. Retryable
+ * exactly when `classifyBigQueryError` would report a RateLimitExceededError
+ * (see `isRateLimited`).
  */
 export function isRetryableBigQueryError(err) {
-    if (!err || typeof err !== "object")
-        return false;
-    const apiErr = err;
-    if (apiErr.errors?.some((cause) => cause.reason !== undefined && RATE_LIMIT_REASONS.has(cause.reason))) {
-        return true;
-    }
-    return (typeof apiErr.message === "string" &&
-        /rateLimitExceeded|quotaExceeded/.test(apiErr.message));
+    return isRateLimited(err);
 }
 //# sourceMappingURL=errors.js.map