@antasphere/chassis-server 1.2.0 → 1.4.0

package/src/identity/hub-grant.ts

@@ -103,6 +103,46 @@ export const DEFAULT_GRANT_DIALS: HubGrantDials = {
   lockWatchdogMs: 12_000
 };
 
+/**
+ * The background renewal of grants about to expire (PRDCT-3584). Hub access
+ * tokens live 15 minutes, so a person who comes back to a tool after a
+ * coffee met the token endpoint INSIDE their first request: the refresh
+ * (the hub's rotation and the row write) stood between the click and the
+ * page. The sweep renews, off any request, the token of every person seen
+ * on this replica within `activeWithinMs` whose cached token expires within
+ * `renewAheadMs`; a person not seen for an hour is forgotten and renews on
+ * demand as before. It goes through `renew()`, the same acquisition as a
+ * request's (the single-flight, the advisory lock, the re-read and the
+ * presentation ledger stay the only writers of the refresh chain), with two
+ * differences the verifier of 18 October 2026 asked for: the cached token is
+ * served until the rotation's result is known, and a sibling replica's
+ * fresh token is adopted instead of rotated again. The timer never holds
+ * the process open and skips while the replica drains.
+ */
+export interface GrantSweepDials {
+  /** How often the sweep runs. */
+  intervalMs: number;
+  /** Renew a cached token this long before it expires. */
+  renewAheadMs: number;
+  /** Only people seen on this replica within this window are renewed. */
+  activeWithinMs: number;
+}
+
+export const DEFAULT_GRANT_SWEEP_DIALS: GrantSweepDials = {
+  intervalMs: 60_000,
+  renewAheadMs: 3 * 60_000,
+  activeWithinMs: 60 * 60_000
+};
+
+/** What `startSweep` hands back: the timer (never holding the process open) and its stop. */
+export interface GrantSweepHandle {
+  timer: NodeJS.Timeout;
+  stop(): void;
+}
+
+/** Bound the seen-map — a user-id flood must never balloon memory. */
+const MAX_SEEN_USERS = 10_000;
+
 /**
  * One answer about a user's hub access.
  *  - 'ok': a hub-callable access token.
@@ -175,12 +215,38 @@ export function isLikelyEncrypted(token: string): boolean {
   return token.length % 2 === 0 && /^[0-9a-f]+$/i.test(token);
 }
 
+/**
+ * What the hub said when it refused: the RFC 6749 `error_description` and
+ * the HTTP status, kept for the log line and nothing else (PRDCT-3584). A
+ * refusal read as `invalid_grant` has four different causes at the pinned
+ * plugin (an unknown token, an expired one, a rotated-out one, a refresh
+ * the pre-flight refused), and only this sentence tells them apart.
+ */
+export interface RefusalReason {
+  status: number;
+  description: string | null;
+}
+
 type RefreshOutcome =
   | { kind: 'ok'; accessToken: string; expiresAt: Date; refreshToken: string | null }
-  | { kind: 'invalid_grant' }
-  | { kind: 'invalid_client' }
+  | ({ kind: 'invalid_grant' } & RefusalReason)
+  | ({ kind: 'invalid_client' } & RefusalReason)
   | { kind: 'transient' };
 
+/** The `error_description` of an RFC 6749 error payload, when it is a non-empty string. */
+export function refusalDescription(payload: unknown): string | null {
+  const d = (payload as { error_description?: unknown } | null)?.error_description;
+  return typeof d === 'string' && d.trim() ? d.trim().slice(0, 300) : null;
+}
+
+/**
+ * How a token is acquired: on `demand` (serve a fresh stored one, else
+ * present); by `force` (the hub refused the current one: present, after the
+ * cache was dropped by the caller); or as a `renew` (the background sweep:
+ * nothing dropped up front, a sibling's fresh stored token adopted).
+ */
+type AcquireMode = 'demand' | 'force' | 'renew';
+
 /** The RFC 7662 probe's answer about a refresh token the hub never confirmed consuming. */
 type ProbeOutcome = 'active' | 'inactive' | 'transient';
 
@@ -188,6 +254,8 @@ export class HubGrantService {
   /** userId → fresh access token (in-memory only; the row is the durable store). */
   private readonly cache = new Map<string, { token: string; expiresAtMs: number }>();
   private readonly inFlight = new Map<string, Promise<GrantAccess>>();
+  /** userId → when this replica last read a token for them (the sweep's population). */
+  private readonly lastSeen = new Map<string, number>();
   private readonly tokenUrl: string;
   private readonly introspectUrl: string;
   private readonly fetchImpl: typeof fetch;
@@ -302,11 +370,12 @@ export class HubGrantService {
 
   /** A hub-callable access token for the user, refresh-on-demand. */
   async accessToken(userId: string): Promise<GrantAccess> {
+    this.markSeen(userId);
     const cached = this.cache.get(userId);
     if (cached && cached.expiresAtMs - this.now() > this.dials.accessSkewMs) {
       return { kind: 'ok', accessToken: cached.token };
     }
-    return this.acquire(userId, false);
+    return this.acquire(userId, 'demand');
   }
 
   /**
@@ -318,13 +387,95 @@ export class HubGrantService {
     this.cache.delete(userId);
     const existing = this.inFlight.get(userId);
     if (existing) await existing.catch(() => {});
-    return this.acquire(userId, true);
+    return this.acquire(userId, 'force');
+  }
+
+  private markSeen(userId: string): void {
+    if (!this.lastSeen.has(userId) && this.lastSeen.size >= MAX_SEEN_USERS) {
+      // Drop the oldest entry (Map keeps insertion order); a re-seen user is
+      // re-inserted at the end below.
+      const oldest = this.lastSeen.keys().next().value;
+      if (oldest !== undefined) this.lastSeen.delete(oldest);
+    }
+    this.lastSeen.delete(userId);
+    this.lastSeen.set(userId, this.now());
+  }
+
+  /**
+   * One pass of the background renewal (GrantSweepDials): renew the cached
+   * token of every recently seen person whose token expires within the
+   * window, one at a time, through `renew()`. Answers how many renewals
+   * were attempted. Never throws: a failed renewal is the next request's
+   * on-demand refresh, exactly as before the sweep existed.
+   */
+  async sweepExpiring(
+    dials: Omit<GrantSweepDials, 'intervalMs'> = DEFAULT_GRANT_SWEEP_DIALS
+  ): Promise<number> {
+    const now = this.now();
+    let attempted = 0;
+    for (const [userId, seenAt] of [...this.lastSeen]) {
+      if (now - seenAt > dials.activeWithinMs) {
+        this.lastSeen.delete(userId);
+        continue;
+      }
+      const cached = this.cache.get(userId);
+      if (!cached || cached.expiresAtMs - now > dials.renewAheadMs) continue;
+      if (this.inFlight.has(userId)) continue;
+      attempted += 1;
+      try {
+        const out = await this.renew(userId, dials.renewAheadMs);
+        if (out.kind !== 'ok') {
+          this.opts.logger.info({ userId, outcome: out.kind }, 'hub grant: background renewal did not renew');
+        }
+      } catch (err) {
+        this.opts.logger.warn(
+          { err, userId },
+          'hub grant: background renewal failed — the next request refreshes on demand'
+        );
+      }
+    }
+    return attempted;
+  }
+
+  /**
+   * Run the sweep on a timer that never holds the process open and skips
+   * while the replica drains. Returns the function that stops it.
+   */
+  startSweep(
+    options: { isDraining?: () => boolean; dials?: Partial<GrantSweepDials> } = {}
+  ): GrantSweepHandle {
+    const dials = { ...DEFAULT_GRANT_SWEEP_DIALS, ...options.dials };
+    let running = false;
+    const timer = setInterval(() => {
+      // One pass at a time: a slow hub must never stack passes.
+      if (running || options.isDraining?.()) return;
+      running = true;
+      void this.sweepExpiring(dials).finally(() => {
+        running = false;
+      });
+    }, dials.intervalMs);
+    timer.unref();
+    return { timer, stop: () => clearInterval(timer) };
+  }
+
+  /**
+   * Renew the grant in the background (the sweep's path, PRDCT-3584): the
+   * cached token keeps being served until the rotation's result is known
+   * (nothing is evicted up front, unlike `refresh()`), and a token a sibling
+   * replica stored with at least `minLeftMs` of life left is adopted instead
+   * of rotating a second time. Joins an acquisition already in flight.
+   */
+  async renew(
+    userId: string,
+    minLeftMs: number = DEFAULT_GRANT_SWEEP_DIALS.renewAheadMs
+  ): Promise<GrantAccess> {
+    return this.acquire(userId, 'renew', minLeftMs);
   }
 
-  private acquire(userId: string, force: boolean): Promise<GrantAccess> {
+  private acquire(userId: string, mode: AcquireMode, minLeftMs?: number): Promise<GrantAccess> {
     let flight = this.inFlight.get(userId);
     if (!flight) {
-      flight = this.doAcquire(userId, force).finally(() => {
+      flight = this.doAcquire(userId, mode, minLeftMs).finally(() => {
         if (this.inFlight.get(userId) === flight) this.inFlight.delete(userId);
       });
       this.inFlight.set(userId, flight);
@@ -332,15 +483,21 @@ export class HubGrantService {
     return flight;
   }
 
-  private async doAcquire(userId: string, force: boolean): Promise<GrantAccess> {
+  private async doAcquire(userId: string, mode: AcquireMode, minLeftMs?: number): Promise<GrantAccess> {
     try {
       const first = await this.readRow(userId);
       if (!first) return { kind: 'no_link' };
       if (!first.refreshToken) return { kind: 'grant_dead' };
 
-      if (!force) {
+      if (mode === 'demand') {
         const stored = await this.storedAccess(userId, first);
         if (stored) return { kind: 'ok', accessToken: stored };
+      } else if (mode === 'renew') {
+        // A sibling replica (or a login) already renewed: adopt its token
+        // without taking the lock (verifier round 6: the common case on
+        // several replicas was paying a dedicated connection for nothing).
+        const stored = await this.storedAccess(userId, first, minLeftMs);
+        if (stored) return { kind: 'ok', accessToken: stored };
       }
 
       // Slow path: rotate under the cross-replica lock.
@@ -354,9 +511,15 @@ export class HubGrantService {
         const row = await this.readRow(userId);
         if (!row) return { kind: 'no_link' };
         if (!row.refreshToken) return { kind: 'grant_dead' };
-        if (!force || row.refreshToken !== first.refreshToken) {
+        if (mode === 'demand' || row.refreshToken !== first.refreshToken) {
           const stored = await this.storedAccess(userId, row);
           if (stored) return { kind: 'ok', accessToken: stored };
+        } else if (mode === 'renew') {
+          // A renewal rotates only what is about to expire: a stored token
+          // with more life than the renewal window is a sibling replica's
+          // fresh one (or a login's), adopted rather than rotated again.
+          const stored = await this.storedAccess(userId, row, minLeftMs);
+          if (stored) return { kind: 'ok', accessToken: stored };
         }
 
         let refreshToken: string;
@@ -416,7 +579,7 @@ export class HubGrantService {
           this.cache.delete(userId);
           this.refreshes.inc({ outcome: 'invalid_grant' });
           this.opts.logger.warn(
-            { userId },
+            { userId, status: outcome.status, reason: outcome.description },
             'hub grant: token endpoint answered invalid_grant — grant marked dead; a browser SSO login heals it'
           );
           return { kind: 'grant_dead' };
@@ -429,6 +592,7 @@ export class HubGrantService {
           await this.clearPresentation(row.id);
           this.refreshes.inc({ outcome: 'invalid_client' });
           this.opts.logger.error(
+            { status: outcome.status, reason: outcome.description },
             'hub grant: token endpoint answered invalid_client — HUB_CLIENT_ID/HUB_CLIENT_SECRET are broken; ' +
               'refreshes are failing transient (grants are NOT being killed); fix the client credentials'
           );
@@ -564,10 +728,14 @@ export class HubGrantService {
   }
 
   /** Decrypt-and-cache the row's access token when it is still fresh. */
-  private async storedAccess(userId: string, row: GrantRow): Promise<string | null> {
+  private async storedAccess(
+    userId: string,
+    row: GrantRow,
+    minLeftMs: number = this.dials.accessSkewMs
+  ): Promise<string | null> {
     if (!row.accessToken || !row.accessTokenExpiresAt) return null;
     const expiresAtMs = row.accessTokenExpiresAt.getTime();
-    if (expiresAtMs - this.now() <= this.dials.accessSkewMs) return null;
+    if (expiresAtMs - this.now() <= minLeftMs) return null;
     try {
       const token = await this.decrypt(row.accessToken);
       this.cache.set(userId, { token, expiresAtMs });
@@ -657,9 +825,13 @@ export class HubGrantService {
     // RFC 6749 errors ride 400/401; anything else (5xx…) is transient.
     if (res.status === 400 || res.status === 401) {
       const error = (payload as { error?: unknown } | null)?.error;
-      if (error === 'invalid_grant') return { kind: 'invalid_grant' };
-      if (error === 'invalid_client') return { kind: 'invalid_client' };
-      this.opts.logger.warn({ status: res.status, error }, 'hub grant: unrecognized token-endpoint error');
+      const description = refusalDescription(payload);
+      if (error === 'invalid_grant') return { kind: 'invalid_grant', status: res.status, description };
+      if (error === 'invalid_client') return { kind: 'invalid_client', status: res.status, description };
+      this.opts.logger.warn(
+        { status: res.status, error, description },
+        'hub grant: unrecognized token-endpoint error'
+      );
       return { kind: 'transient' };
     }
     this.opts.logger.warn({ status: res.status }, 'hub grant: token endpoint answered non-2xx');

package/src/identity/index.ts

@@ -23,9 +23,14 @@ export {
 } from './demo-pass-rules.js';
 export {
   DEFAULT_GRANT_DIALS,
+  DEFAULT_GRANT_SWEEP_DIALS,
   type GrantAccess,
+  type GrantSweepDials,
+  type GrantSweepHandle,
   HubGrantService,
-  LOCK_WATCHDOG_HEADROOM_MS
+  LOCK_WATCHDOG_HEADROOM_MS,
+  type RefusalReason,
+  refusalDescription
 } from './hub-grant.js';
 export { HubJwtVerifier } from './hub-jwt.js';
 export { HubLogoutService, hintCookieClearHeader } from './hub-logout.js';

package/src/middleware/index.ts

@@ -31,3 +31,14 @@ export { MAX_JSON_DEPTH, exceedsJsonDepth, jsonDepthLimit } from './json-depth.j
 export { noStoreAuthenticated } from './no-store.js';
 export { isPublicOauthPath, oauthPublicEndpoints } from './oauth-public.js';
 export { buildCsp, hstsValue, inlineScriptHashes, securityHeaders } from './security-headers.js';
+export {
+  IMMUTABLE_ASSET_PREFIX,
+  IMMUTABLE_CACHE_CONTROL,
+  REVALIDATE_CACHE_CONTROL,
+  type SpaFallback,
+  type StaticAssetsOptions,
+  acceptedEncodings,
+  loadSpaFallback,
+  staticAssets,
+  staticCacheControl
+} from './static-assets.js';

package/src/middleware/static-assets.ts

@@ -0,0 +1,144 @@
+import type { Context, MiddlewareHandler } from 'hono';
+import { serveStatic } from '@hono/node-server/serve-static';
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * The dashboard build, served so the browser keeps it (PRDCT-3584).
+ *
+ * Before this middleware the SPA's files went out with no `Cache-Control`,
+ * no validator and no compression: every visit to a tool re-downloaded the
+ * whole dashboard (about 1.2 MB of JavaScript in a hundred files on the
+ * team stack, measured 2026-10-17), and the splash the person stared at
+ * was that download. Two rules fix it, both on the build's own shape:
+ *
+ *  - `/_app/immutable/*` is CONTENT-HASHED by SvelteKit: a changed file has a
+ *    new name, so the cached copy can never be stale. It is served with
+ *    `public, max-age=31536000, immutable`: a second visit transfers none of
+ *    it. Every other static path (the HTML, the icons, the manifest) is
+ *    `no-cache`: kept, but revalidated on every use, so a release reaches
+ *    the browser on its next load.
+ *  - A `.br`, `.zst` or `.gz` sibling written at build time (the dashboard's
+ *    adapter has `precompress: true`) is served in place of the file when
+ *    the request accepts that encoding, with `Content-Encoding` and `Vary:
+ *    Accept-Encoding`. The server compresses nothing at runtime, and the
+ *    API is untouched: this middleware runs on the static files alone,
+ *    after every credentialed route has answered.
+ *
+ * Nothing here is a security input. `immutable` never reaches a response
+ * that is not a hashed asset, so no user-bearing answer can be cached; the
+ * authenticated JSON keeps its `no-store` (middleware/no-store.ts).
+ */
+
+/** The content-hashed prefix of a SvelteKit build. */
+export const IMMUTABLE_ASSET_PREFIX = '/_app/immutable/';
+export const IMMUTABLE_CACHE_CONTROL = 'public, max-age=31536000, immutable';
+export const REVALIDATE_CACHE_CONTROL = 'no-cache';
+
+/** The `Cache-Control` a static path of the build is served with. */
+export function staticCacheControl(requestPath: string): string {
+  return requestPath.startsWith(IMMUTABLE_ASSET_PREFIX) ? IMMUTABLE_CACHE_CONTROL : REVALIDATE_CACHE_CONTROL;
+}
+
+export interface StaticAssetsOptions {
+  /** The directory holding the built dashboard (`index.html`, `_app/`). */
+  publicDir: string;
+}
+
+/**
+ * Serve `publicDir` with the cache policy above and the precompressed
+ * siblings. Falls through (`next()`) on a path that is not a file there, so
+ * the SPA fallback behind it answers the application routes.
+ */
+export function staticAssets(options: StaticAssetsOptions): MiddlewareHandler {
+  const serve = serveStatic({ root: options.publicDir, precompressed: true });
+  return async (c, next) => {
+    // The application's HTML itself (`/`, `/index.html`) is the SPA
+    // fallback's to answer, with its validator and its sibling; the static
+    // server would hand it out with neither (verifier round 2).
+    if (c.req.path === '/' || c.req.path === '/index.html') return next();
+    const res = await serve(c, next);
+    // serveStatic answers a Response for a file it found and the result of
+    // `next()` otherwise; only the file gets the policy.
+    if (res instanceof Response) {
+      res.headers.set('Cache-Control', staticCacheControl(c.req.path));
+      if (!res.headers.has('Vary')) res.headers.set('Vary', 'Accept-Encoding');
+    }
+    return res;
+  };
+}
+
+// ── The SPA fallback ────────────────────────────────────────────────────────
+
+/** The encodings a precompressed sibling may carry, in the order they are preferred. */
+const FALLBACK_ENCODINGS = [
+  { name: 'br', ext: '.br' },
+  { name: 'gzip', ext: '.gz' }
+] as const;
+type FallbackEncoding = (typeof FALLBACK_ENCODINGS)[number]['name'];
+
+/** The encodings a request accepts, read from `Accept-Encoding` with any `;q=` weight ignored. */
+export function acceptedEncodings(header: string | undefined): Set<string> {
+  return new Set(
+    (header ?? '')
+      .split(',')
+      .map((part) => part.split(';')[0]!.trim().toLowerCase())
+      .filter(Boolean)
+  );
+}
+
+export interface SpaFallback {
+  /** The strong ETag of the plain HTML (the variants derive theirs from it). */
+  readonly etag: string;
+  /** Answer the application's HTML for a route the build has no file for. */
+  respond(c: Context): Response;
+}
+
+/**
+ * The application's HTML under any route the build has no file for, served
+ * with the two things the bare `c.html()` lacked (the tier 1 verifier's two
+ * caveats, PRDCT-3584): a strong `ETag` so `no-cache` means "revalidate"
+ * (a `304` costs no bytes), and the `.br` / `.gz` sibling of `index.html`
+ * when the build wrote one and the request accepts it, so a deep link costs
+ * the same as the root on a front that compresses nothing (Cloud Run, a
+ * self-hosted instance with no proxy). The HTML is read once at boot, like
+ * `indexHtml` itself.
+ */
+export async function loadSpaFallback(publicDir: string, html: string): Promise<SpaFallback> {
+  const plain = Buffer.from(html, 'utf8');
+  const etag = `"${createHash('sha256').update(plain).digest('base64url').slice(0, 27)}"`;
+  const variants = new Map<FallbackEncoding, Buffer>();
+  for (const { name, ext } of FALLBACK_ENCODINGS) {
+    try {
+      variants.set(name, await readFile(join(publicDir, `index.html${ext}`)));
+    } catch {
+      // no sibling of that encoding: the plain HTML answers those requests
+    }
+  }
+  return {
+    etag,
+    respond(c) {
+      const accepted = acceptedEncodings(c.req.header('accept-encoding'));
+      const encoding = FALLBACK_ENCODINGS.find((e) => accepted.has(e.name) && variants.has(e.name))?.name;
+      // One validator per representation: a cached brotli body is never
+      // confirmed against a plain one.
+      const variantEtag = encoding ? etag.replace(/"$/, `-${encoding}"`) : etag;
+      // The type rides the 304 too: the node server would otherwise stamp a
+      // text/plain default on it (verifier round 2), and RFC 9110 allows the
+      // 304 to repeat what the 200 carries.
+      const headers: Record<string, string> = {
+        'Cache-Control': REVALIDATE_CACHE_CONTROL,
+        'Content-Type': 'text/html; charset=utf-8',
+        ETag: variantEtag,
+        Vary: 'Accept-Encoding'
+      };
+      if (c.req.header('if-none-match') === variantEtag) {
+        return c.body(null, 304, headers);
+      }
+      if (encoding) headers['Content-Encoding'] = encoding;
+      const body = encoding ? variants.get(encoding)! : plain;
+      return c.body(new Uint8Array(body), 200, headers);
+    }
+  };
+}

package/test/integration/hub-grant.test.ts

@@ -503,3 +503,100 @@ describe('ambiguous outcomes: the presentation record + the RFC 7662 probe (PRDC
     expect((await makeService(FAST).accessToken(aliceId)).kind).toBe('ok');
   });
 });
+
+/** Bring the stored access token to the renewal window (two minutes left) — the row is what a renewal judges. */
+async function nearExpiryStoredAccess(): Promise<void> {
+  await app.db.pool.query(
+    `UPDATE account SET access_token_expires_at = now() + interval '2 minutes'
+     WHERE provider_id = 'antasphere' AND user_id = $1`,
+    [aliceId]
+  );
+}
+
+describe('the background renewal (PRDCT-3584, verifier round 5)', () => {
+  it('keeps serving the cached token while the hub answers the rotation', async () => {
+    const service = makeService();
+    await sso.ssoLogin(app, hub, alice);
+    const row = await grantRow();
+    const current = await symmetricDecrypt({ key: AUTH_SECRET, data: row.access_token! });
+    // the token is about to expire: inside the renewal window, outside the on-demand skew
+    service.prime(aliceId, current, new Date(Date.now() + 2 * 60_000));
+    await nearExpiryStoredAccess();
+    hub.tokenDelayMs = 1_200;
+    try {
+      const before = hub.refreshCount();
+      const renewal = service.renew(aliceId);
+      const t0 = Date.now();
+      const during = await service.accessToken(aliceId);
+      const waited = Date.now() - t0;
+      expect(during).toEqual({ kind: 'ok', accessToken: current });
+      expect(waited).toBeLessThan(300);
+      const out = await renewal;
+      expect(out.kind).toBe('ok');
+      expect(hub.refreshCount()).toBe(before + 1);
+      // the renewed token is what the next demand serves, without a hub call
+      const after = await service.accessToken(aliceId);
+      expect(after.kind).toBe('ok');
+      expect((after as { accessToken: string }).accessToken).not.toBe(current);
+      expect(hub.refreshCount()).toBe(before + 1);
+    } finally {
+      hub.tokenDelayMs = 0;
+    }
+  });
+
+  it('a transient answer leaves the cached token in place', async () => {
+    const service = makeService();
+    await sso.ssoLogin(app, hub, alice);
+    const row = await grantRow();
+    const current = await symmetricDecrypt({ key: AUTH_SECRET, data: row.access_token! });
+    service.prime(aliceId, current, new Date(Date.now() + 2 * 60_000));
+    await nearExpiryStoredAccess();
+    hub.tokenMode = 'http500';
+    try {
+      expect(await service.renew(aliceId)).toEqual({ kind: 'inconclusive' });
+    } finally {
+      hub.tokenMode = 'ok';
+    }
+    const before = hub.refreshCount();
+    expect(await service.accessToken(aliceId)).toEqual({ kind: 'ok', accessToken: current });
+    expect(hub.refreshCount()).toBe(before);
+  });
+
+  it('a sibling replica adopts the fresh token the first one stored instead of rotating again', async () => {
+    const a = makeService();
+    const b = makeService();
+    await sso.ssoLogin(app, hub, alice);
+    const row = await grantRow();
+    const current = await symmetricDecrypt({ key: AUTH_SECRET, data: row.access_token! });
+    a.prime(aliceId, current, new Date(Date.now() + 2 * 60_000));
+    b.prime(aliceId, current, new Date(Date.now() + 2 * 60_000));
+    await nearExpiryStoredAccess();
+    const before = hub.refreshCount();
+    expect((await a.renew(aliceId)).kind).toBe('ok');
+    expect(hub.refreshCount()).toBe(before + 1);
+    const adopted = await b.renew(aliceId);
+    expect(adopted.kind).toBe('ok');
+    expect(hub.refreshCount()).toBe(before + 1); // no second rotation
+    const fresh = await grantRow();
+    expect((adopted as { accessToken: string }).accessToken).toBe(
+      await symmetricDecrypt({ key: AUTH_SECRET, data: fresh.access_token! })
+    );
+  });
+
+  it('a refused renewal marks the grant dead like a refused refresh', async () => {
+    const service = makeService();
+    await sso.ssoLogin(app, hub, alice);
+    const row = await grantRow();
+    const current = await symmetricDecrypt({ key: AUTH_SECRET, data: row.access_token! });
+    service.prime(aliceId, current, new Date(Date.now() + 2 * 60_000));
+    await nearExpiryStoredAccess();
+    hub.tokenMode = 'invalid_grant';
+    try {
+      expect(await service.renew(aliceId)).toEqual({ kind: 'grant_dead' });
+    } finally {
+      hub.tokenMode = 'ok';
+    }
+    expect(await service.accessToken(aliceId)).toEqual({ kind: 'grant_dead' });
+    await sso.ssoLogin(app, hub, alice); // heal for any later suite
+  });
+});

package/test/unit/hub-grant-refusal.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { refusalDescription } from '../../src/identity/hub-grant.js';
+
+/**
+ * PRDCT-3584. The hub's `invalid_grant` has four causes at the pinned
+ * plugin (unknown token, expired, rotated out, refused by the pre-flight)
+ * and the tool used to drop the sentence that tells them apart. The reader
+ * keeps it for the log line, bounded and trimmed, and nothing else.
+ */
+describe('refusalDescription', () => {
+  it('reads a non-empty error_description', () => {
+    expect(refusalDescription({ error: 'invalid_grant', error_description: 'session not found' })).toBe(
+      'session not found'
+    );
+  });
+  it('trims and bounds it', () => {
+    expect(refusalDescription({ error_description: '  invalid refresh token \n' })).toBe(
+      'invalid refresh token'
+    );
+    expect(refusalDescription({ error_description: 'x'.repeat(1000) })?.length).toBe(300);
+  });
+  it('answers null for anything else', () => {
+    expect(refusalDescription({ error: 'invalid_grant' })).toBeNull();
+    expect(refusalDescription({ error_description: '' })).toBeNull();
+    expect(refusalDescription({ error_description: 42 })).toBeNull();
+    expect(refusalDescription(null)).toBeNull();
+    expect(refusalDescription('invalid_grant')).toBeNull();
+  });
+});