@antasphere/chassis-server 1.3.0 → 1.5.0

package/src/apps/service.ts

@@ -0,0 +1,198 @@
+import { readFile } from 'node:fs/promises';
+import { eq } from 'drizzle-orm';
+import { workspaces, type Db } from '@antasphere/chassis-db';
+import type { AppsList, Principal } from '@antasphere/chassis-contract';
+import type { GrantAccess } from '../identity/hub-grant.js';
+import type { Logger } from '../logger.js';
+import { HUB_APP_NAME, appsFromFile, readOrganization, safeHttpUrl, selectHubApps } from './select.js';
+
+/**
+ * The Apps page's list (`GET /apps`, PRDCT-3493): the other tools of the
+ * person's organization, and the account that signs them in.
+ *
+ * On the cloud edition the hub is asked AS THE PERSON, with their own grant
+ * (the chassis's `HubGrantService`, the same stored grant and the same
+ * cross-replica refresh lock the reconciler uses): ONE call, `GET
+ * <hub>/api/v1/me/apps` with `X-Workspace-Id` naming the workspace's hub
+ * organization (`workspaces.central_account_id`), answers the catalogue as
+ * the person sees it there (the restricted tools they may not see already
+ * left out by the hub) with the access verdict per tool; the tools not open
+ * are left out here. A SUSPENDED organization (the hub's `organization.status`)
+ * is served as an empty list carrying the organization and its status, never
+ * as the tools: the hub's contract says a tool's Apps service never serves
+ * such a list, and the dashboard says why. The answer is held five minutes
+ * per person and workspace. A grant that is missing or dead, a hub that does
+ * not answer, a malformed body, or a workspace that is no hub organization
+ * falls back to the operator's file, never to an error: the page is a
+ * convenience, not an access decision (each tool still asks the hub when it
+ * is opened).
+ *
+ * On a self-hosted instance the list is the operator's file (`APPS_FILE`),
+ * read on every call; without one the page lists nothing.
+ */
+
+/** How long a person's hub answer is held. */
+export const APPS_CACHE_TTL_MS = 5 * 60_000;
+/** At most this many answers are held; the oldest goes first. */
+const APPS_CACHE_MAX = 5_000;
+/** The hub read's budget: the page waits on it. */
+const HUB_TIMEOUT_MS = 3_000;
+
+/** The as-the-person token source: what the page needs of the chassis's `HubGrantService`. */
+export interface HubTokens {
+  accessToken(userId: string): Promise<GrantAccess>;
+  refresh(userId: string): Promise<GrantAccess>;
+  invalidateAccess(userId: string): void;
+}
+
+export interface AppsServiceOptions {
+  db: Db;
+  logger: Logger;
+  edition: 'oss' | 'cloud';
+  /** HUB_ISSUER_URL (cloud). */
+  hubIssuerUrl?: string | undefined;
+  /** APPS_FILE. */
+  appsFile?: string | undefined;
+  /** This tool's own slug (the identity's): its card says "You are here". */
+  selfSlug: string;
+  /** The person's hub grant (cloud); null on a self-hosted instance. */
+  tokens: HubTokens | null;
+  /** Test seams. */
+  fetchImpl?: typeof fetch;
+  now?: () => number;
+}
+
+type HubRead = { kind: 'ok'; status: number; body: unknown } | { kind: 'fail' };
+
+export class AppsService {
+  private readonly cache = new Map<string, { at: number; value: AppsList }>();
+  private readonly fetchImpl: typeof fetch;
+  private readonly now: () => number;
+  private readonly hubBase: string | null;
+
+  constructor(private readonly opts: AppsServiceOptions) {
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.now = opts.now ?? Date.now;
+    this.hubBase =
+      opts.edition === 'cloud' && opts.hubIssuerUrl ? opts.hubIssuerUrl.replace(/\/+$/, '') : null;
+  }
+
+  /** The list for one person in one workspace. */
+  async list(principal: Pick<Principal, 'userId' | 'workspaceId'>): Promise<AppsList> {
+    const key = `${principal.userId}:${principal.workspaceId}`;
+    const held = this.cache.get(key);
+    if (held && this.now() - held.at < APPS_CACHE_TTL_MS) return held.value;
+
+    const fromHub = await this.fromHub(principal);
+    if (!fromHub) return this.fromFile();
+    this.cache.delete(key);
+    this.cache.set(key, { at: this.now(), value: fromHub });
+    if (this.cache.size > APPS_CACHE_MAX) {
+      const oldest = this.cache.keys().next().value;
+      if (oldest !== undefined) this.cache.delete(oldest);
+    }
+    return fromHub;
+  }
+
+  /** The hub's card: the issuer on the cloud edition. */
+  private cloudHub(): AppsList['hub'] {
+    const url = this.hubBase ? safeHttpUrl(this.hubBase) : null;
+    return url ? { url, name: HUB_APP_NAME } : null;
+  }
+
+  /** The operator's file; `none` without one, or when it cannot be read. */
+  async fromFile(): Promise<AppsList> {
+    const path = this.opts.appsFile;
+    if (!path) return { apps: [], hub: this.cloudHub(), source: 'none' };
+    let raw: unknown;
+    try {
+      raw = JSON.parse(await readFile(path, 'utf8'));
+    } catch (err) {
+      this.opts.logger.warn(
+        { err, path },
+        'APPS_FILE could not be read as JSON — the Apps page lists nothing'
+      );
+      return { apps: [], hub: this.cloudHub(), source: 'none' };
+    }
+    const file = appsFromFile(raw, this.opts.selfSlug);
+    if (file.rejected.length > 0) {
+      this.opts.logger.warn({ path, rejected: file.rejected }, 'APPS_FILE entries left out of the Apps page');
+    }
+    return { apps: file.apps, hub: file.hub ?? this.cloudHub(), source: 'file' };
+  }
+
+  /**
+   * The hub's answer, or null when the hub cannot be asked for this person
+   * (no grant, a dead one, a workspace that is no hub organization, a hub
+   * that does not answer or answers another shape): the file is read instead.
+   */
+  private async fromHub(principal: Pick<Principal, 'userId' | 'workspaceId'>): Promise<AppsList | null> {
+    const tokens = this.opts.tokens;
+    if (!this.hubBase || !tokens) return null;
+    const [row] = await this.opts.db
+      .select({ hubOrgId: workspaces.centralAccountId })
+      .from(workspaces)
+      .where(eq(workspaces.id, principal.workspaceId))
+      .limit(1);
+    const hubOrgId = row?.hubOrgId ?? null;
+    if (!hubOrgId) return null;
+
+    const access = await tokens.accessToken(principal.userId);
+    if (access.kind !== 'ok') return null;
+
+    // One forced refresh and one retry on a 401/403 (the stored token may be
+    // stale): the chassis's own posture (hub-user-client.ts).
+    let res = await this.get(access.accessToken, hubOrgId);
+    if (res.kind === 'ok' && (res.status === 401 || res.status === 403)) {
+      tokens.invalidateAccess(principal.userId);
+      const refreshed = await tokens.refresh(principal.userId);
+      if (refreshed.kind !== 'ok') return null;
+      res = await this.get(refreshed.accessToken, hubOrgId);
+    }
+    if (res.kind !== 'ok' || res.status !== 200) {
+      if (res.kind === 'ok') {
+        this.opts.logger.warn(
+          { status: res.status },
+          'hub /me/apps answered non-200 — the Apps page reads the file'
+        );
+      }
+      return null;
+    }
+    // The organization's status first: a suspended one empties the list
+    // whatever the body's tools say (or fail to say).
+    const organization = readOrganization(res.body);
+    if (organization?.status === 'suspended') {
+      this.opts.logger.info({ hubOrgId }, 'hub organization suspended — the Apps page lists nothing');
+      return { apps: [], hub: this.cloudHub(), source: 'hub', organization };
+    }
+    const apps = selectHubApps(res.body, this.opts.selfSlug);
+    if (!apps) {
+      this.opts.logger.warn('hub /me/apps carried no tools list — the Apps page reads the file');
+      return null;
+    }
+    return { apps, hub: this.cloudHub(), source: 'hub', ...(organization ? { organization } : {}) };
+  }
+
+  private async get(token: string, hubOrgId: string): Promise<HubRead> {
+    try {
+      const response = await this.fetchImpl(`${this.hubBase}/api/v1/me/apps`, {
+        headers: {
+          authorization: `Bearer ${token}`,
+          accept: 'application/json',
+          'x-workspace-id': hubOrgId
+        },
+        signal: AbortSignal.timeout(HUB_TIMEOUT_MS)
+      });
+      let body: unknown = null;
+      try {
+        body = await response.json();
+      } catch {
+        body = null;
+      }
+      return { kind: 'ok', status: response.status, body };
+    } catch (err) {
+      this.opts.logger.warn({ err }, 'hub read for the Apps page failed');
+      return { kind: 'fail' };
+    }
+  }
+}

package/src/boot.ts

@@ -592,6 +592,11 @@ export async function bootPlatform<
         }
       })
     : undefined;
+  // The grants of the people this replica saw in the last hour are renewed
+  // in the background before they expire (PRDCT-3584), so a request never
+  // waits on the hub's token endpoint when the sweep got there first. The
+  // timer never holds the process open and pauses while draining.
+  hubGrant?.startSweep({ isDraining: () => state.draining });
   // RP-initiated logout against the hub (SL-2, cloud only): builds the
   // end-session URL /sso/logout returns. Same key seam as the grant store
   // (it only decrypts if a future Better Auth starts encrypting id_tokens);

package/src/env.ts

@@ -222,6 +222,8 @@ const chassisEnvShape = (version: string) => ({
   HSTS_MAX_AGE: numeric(z.coerce.number().int().min(0).default(15552000)),
   /** Instance-level cap read by the default AllowAllEntitlements. */
   MAX_FILE_SIZE_MB: numeric(z.coerce.number().int().min(1).default(100)),
+  /** A JSON file listing the other tools of the organization for the Apps page (PRDCT-3493): `[{ "slug": "finance", "name": "Antasphere Finance", "launchUrl": "https://finance.example.com", "description": "optional sentence", "icon": "landmark", "drawing": "ledger", "accent": "#B5542A" }]`, the last four the hub's descriptor keys (icon and drawing from the contract's closed lists; an invalid descriptor is dropped, the entry kept). Read on a self-hosted instance (`EDITION=oss`), and on the cloud edition when the hub cannot be asked (the cloud edition otherwise asks the hub as the person, `GET /me/apps`). Every `launchUrl` must be http(s); an entry that is not is left out, with a warning in the log. Absent: the Apps page lists no other tool. */
+  APPS_FILE: optionalString(z.string().min(1).max(1000)),
   /** How many workspaces ONE person may own on this instance — the cap on creating another workspace from the dashboard (the first one comes from setup). Any signed-in member who is not a guest may create one until they own this many. 0 closes workspace creation for everyone. On the cloud edition the count is Antasphere's own organization limit; only the 0 switch applies here. */
   MAX_WORKSPACES_PER_USER: numeric(z.coerce.number().int().min(0).max(1000).default(10)),
   /** General per-principal API quota: sustained requests/minute allowed to every authenticated /api/v1 principal (API key, OAuth token, session). 0 disables the general limiter. */

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/testing/fake-hub.ts

@@ -5,7 +5,8 @@ import {
   usageCheckSchema,
   usageEventSchema,
   usageEventsBatchSchema,
-  usageIngestResultSchema
+  usageIngestResultSchema,
+  meAppsSchema
 } from '@antasphere/chassis-contract';
 import { randomUUID } from 'node:crypto';
 import { exportJWK, generateKeyPair, SignJWT, type JWK } from 'jose';
@@ -111,6 +112,14 @@ export interface HubUserFixture {
   overrides?: HubTokenOverrides | undefined;
 }
 
+/** One tool of the fake's catalogue (what GET /me/apps serves, PRDCT-3493). */
+export interface FakeHubTool {
+  slug: string;
+  name: string;
+  launchUrl: string;
+  descriptor?: Record<string, unknown> | undefined;
+}
+
 /** One entry of a user's org registry (what GET /orgs serves). */
 export interface HubOrgEntry {
   name: string | null;
@@ -180,6 +189,11 @@ export class FakeHub {
   private readonly orgTeamRegistry = new Map<string, Array<{ id: string; slug: string; name: string }>>();
   /** sub → the orgs that do NOT open the tool to them (GET /orgs' top-level `denied`). */
   private readonly userDenied = new Map<string, Array<{ id: string; name: string }>>();
+  /** The catalogue GET /me/apps serves (PRDCT-3493): the registry's tools, in order, with their descriptor. */
+  private tools: FakeHubTool[] = [];
+  /** Per user and tool, the organizations that do NOT open the tool to them (absent = open everywhere). */
+  private readonly userToolClosed = new Map<string, Set<string>>();
+  readonly meAppsRequests: Array<{ auth: string | null; orgId: string | null }> = [];
   /** Every JWT access token this fake minted (bearer lookup for /api/v1). */
   private readonly accessTokens = new Map<string, AccessTokenRecord>();
   /** Live + rotated-out refresh tokens (rotation families). */
@@ -550,6 +564,9 @@ export class FakeHub {
     if (req.method === 'GET' && url.pathname === '/api/v1/teams') {
       return this.handleTeams(req, res, url);
     }
+    if (req.method === 'GET' && url.pathname === '/api/v1/me/apps') {
+      return this.handleMeApps(req, res);
+    }
     if (req.method === 'POST' && url.pathname === '/api/v1/orgs') {
       return this.handleOrgCreate(req, res);
     }
@@ -880,6 +897,71 @@ export class FakeHub {
   }
 
   // ── GET /api/v1/orgs: the caller-scoped org list ──────────────────────
+  /** The tools GET /me/apps lists, in this order. */
+  setTools(tools: FakeHubTool[]): void {
+    this.tools = tools;
+  }
+
+  /** Close one tool to one user in one organization (the real hub's teams rule, reduced to its verdict). */
+  setToolClosed(sub: string, slug: string, orgId: string, closed = true): void {
+    const key = `${sub}:${slug}`;
+    const set = this.userToolClosed.get(key) ?? new Set<string>();
+    if (closed) set.add(orgId);
+    else set.delete(orgId);
+    this.userToolClosed.set(key, set);
+  }
+
+  // ── GET /api/v1/me/apps: the catalogue as one person sees it (PRDCT-3493) ─
+  // Mirrors the hub's api/me-apps.ts: the same bearer rule as /orgs, the
+  // organization the `X-Workspace-Id` header names (else the user's first org,
+  // the real hub's default), every registered tool with `open` from the
+  // per-user closures, `connected` false (the fake keeps no connection facts).
+  private handleMeApps(req: IncomingMessage, res: ServerResponse): void {
+    const header = req.headers['x-workspace-id'];
+    const orgId = (Array.isArray(header) ? header[0] : header) ?? null;
+    this.meAppsRequests.push({ auth: req.headers.authorization ?? null, orgId });
+    const bearer = /^Bearer\s+(.+)$/i.exec(req.headers.authorization ?? '')?.[1] ?? null;
+    const record = bearer ? this.accessTokens.get(bearer) : undefined;
+    if (!record || record.expMs <= Date.now() || !record.aud.includes(this.apiResource)) {
+      return sendJson(res, 401, { error: { code: 'invalid_token', message: 'Unauthorized' } });
+    }
+    const orgs = this.userOrgs.get(record.sub) ?? new Map<string, HubOrgEntry>();
+    const resolved = orgId ?? orgs.keys().next().value ?? null;
+    if (!resolved || !orgs.has(resolved)) {
+      return sendJson(res, 401, { error: { code: 'unauthenticated', message: 'Authentication required' } });
+    }
+    const tools = this.tools.map((tool) => ({
+      slug: tool.slug,
+      clientId: `tool-${tool.slug}`,
+      name: tool.name,
+      launchUrl: tool.launchUrl,
+      returnOrigins: [new URL(tool.launchUrl).origin],
+      connected: false,
+      connectedAt: null,
+      lastUsedAt: null,
+      ...(tool.descriptor ? { descriptor: tool.descriptor } : {}),
+      open: !(this.userToolClosed.get(`${record.sub}:${tool.slug}`)?.has(resolved) ?? false)
+    }));
+    const entry = orgs.get(resolved);
+    const body = {
+      organization: { id: resolved, name: entry?.name ?? '', status: entry?.status ?? 'active' },
+      tools
+    };
+    // The fake answers the hub's published shape and nothing else: a body the
+    // real hub would never send is a test proving nothing, so it is refused
+    // here, as a 500 naming the drift (a thrown error would only hang the socket).
+    const checked = meAppsSchema.safeParse(body);
+    if (!checked.success) {
+      return sendJson(res, 500, {
+        error: {
+          code: 'fake_hub_drift',
+          message: `/me/apps body is off the hub contract: ${checked.error.message}`
+        }
+      });
+    }
+    return sendJson(res, 200, body);
+  }
+
   private async handleOrgs(req: IncomingMessage, res: ServerResponse): Promise<void> {
     this.orgsRequests.push({ auth: req.headers.authorization ?? null });
     if (this.orgsDelayMs > 0) await new Promise((r) => setTimeout(r, this.orgsDelayMs));