@antasphere/chassis-server 1.4.0 → 1.5.1

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/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/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));

package/test/integration/apps-route.test.ts

@@ -0,0 +1,239 @@
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import type { StartedPostgreSqlContainer } from '@testcontainers/postgresql';
+import {
+  createDatabase,
+  createTestApp,
+  extractCookie,
+  host,
+  readJson,
+  startPostgres,
+  SETUP_TOKEN,
+  type TestApp
+} from './helpers.js';
+import { FakeHub, type HubUserFixture } from '@antasphere/chassis-server/testing';
+import { nextIp, ssoLogin } from './sso-helpers.js';
+
+/**
+ * The Apps page's route (`GET /apps`, `src/apps/`, PRDCT-3493) through the
+ * REAL boot of the minimal tool, on both editions. The suite runs in every
+ * tool against its own host, so the other tools it lists carry invented slugs
+ * (ledger-tool, people-tool) that no real tool has: a real slug would be the
+ * host's own in that tool and read as "this tool" (chassis 1.5.0 named finance
+ * and hiring, and the finance and hiring tools' suites went red on it).
+ *
+ *  - self-hosted, with an operator's file: a browser session reads the list
+ *    (this tool marked current, the account from the file's `account` entry,
+ *    a non-http entry left out, the descriptor keys read), and a machine
+ *    credential is refused before the handler, since no rule of the scope
+ *    allowlist opens the path (fail-closed);
+ *  - cloud, against the fake hub: the list is the hub's `GET /me/apps` as
+ *    the signed-in person, asked for the workspace's hub organization, the
+ *    tools the organization does not open to them left out, the descriptor
+ *    carried; closing a tool at the hub takes it out of the list once the
+ *    five-minute hold has passed (a fresh person reads it at once); a person
+ *    whose organization the hub suspended reads an empty list that names the
+ *    organization and its status, never the tools.
+ */
+
+const OWNER = { email: 'owner@apps.test', name: 'Apps Owner', password: 'apps-owner-password-1' };
+const DESCRIPTOR = {
+  description: 'Where the company keeps its figures.',
+  icon: 'landmark',
+  drawing: 'ledger',
+  accent: '#B5542A'
+};
+
+let container: StartedPostgreSqlContainer;
+
+const send = (app: TestApp, method: string, path: string, headers: Record<string, string>, body?: unknown) =>
+  app.app.request(`/api/v1${path}`, {
+    method,
+    headers: {
+      'x-forwarded-for': nextIp(),
+      ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+      ...headers
+    },
+    ...(body !== undefined ? { body: JSON.stringify(body) } : {})
+  });
+
+beforeAll(async () => {
+  container = await startPostgres();
+}, 180_000);
+
+afterAll(async () => {
+  await container?.stop();
+});
+
+describe('GET /apps on a self-hosted instance with an operator file', () => {
+  let app: TestApp;
+  let cookie = '';
+
+  beforeAll(async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'apps-route-'));
+    const appsFile = join(dir, 'apps.json');
+    writeFileSync(
+      appsFile,
+      JSON.stringify([
+        { slug: 'account', name: 'Antasphere account', launchUrl: 'https://account.example.com' },
+        {
+          slug: 'ledger-tool',
+          name: 'Antasphere Ledger Tool',
+          launchUrl: 'https://ledger-tool.example.com',
+          ...DESCRIPTOR
+        },
+        { slug: host.identity.slug, name: 'This Tool', launchUrl: 'https://thistool.example.com' },
+        { slug: 'bad-url-tool', name: 'Antasphere Bad URL Tool', launchUrl: 'javascript:alert(1)' }
+      ])
+    );
+    app = await createTestApp(await createDatabase(container, 'apps_route_oss'), { APPS_FILE: appsFile });
+    const setup = await send(
+      app,
+      'POST',
+      '/setup',
+      {},
+      { setupToken: SETUP_TOKEN, instanceName: 'Apps', owner: OWNER }
+    );
+    expect(setup.status).toBe(201);
+    const signIn = await send(
+      app,
+      'POST',
+      '/auth/sign-in/email',
+      {},
+      { email: OWNER.email, password: OWNER.password }
+    );
+    expect(signIn.status).toBe(200);
+    cookie = extractCookie(signIn);
+  }, 120_000);
+
+  afterAll(async () => {
+    await app?.stop();
+  });
+
+  it('a session reads the file: the account, the tools with their descriptor, this tool current, the bad URL left out', async () => {
+    const res = await send(app, 'GET', '/apps', { cookie });
+    expect(res.status).toBe(200);
+    const body = await readJson(res);
+    expect(body.source).toBe('file');
+    expect(body.hub).toEqual({ url: 'https://account.example.com/', name: 'Antasphere account' });
+    expect(body.apps.map((a: { slug: string; current: boolean }) => [a.slug, a.current])).toEqual([
+      ['ledger-tool', false],
+      [host.identity.slug, true]
+    ]);
+    expect(body.apps[0].descriptor).toEqual(DESCRIPTOR);
+    expect(body.apps[1]).not.toHaveProperty('descriptor');
+  });
+
+  it('a machine credential is refused before the handler, and no credential answers 401', async () => {
+    const minted = await send(
+      app,
+      'POST',
+      '/api-keys',
+      { cookie },
+      { name: 'reader', scopes: [host.scopes.read] }
+    );
+    expect(minted.status).toBe(201);
+    const key = (await readJson(minted)).key as string;
+    const asKey = await send(app, 'GET', '/apps', { authorization: `Bearer ${key}` });
+    expect(asKey.status).toBe(403);
+    expect((await readJson(asKey)).error.code).toBe('endpoint_not_allowed');
+    const anon = await send(app, 'GET', '/apps', {});
+    expect(anon.status).toBe(401);
+  });
+});
+
+describe('GET /apps on the cloud edition, against the hub', () => {
+  let hub: FakeHub;
+  let app: TestApp;
+  const ORG = '11111111-2222-4333-8444-555555555555';
+  const mira: HubUserFixture = {
+    sub: 'hub-user-mira',
+    email: 'mira@apps.test',
+    name: 'Mira Lund',
+    workspaceId: ORG,
+    role: 'member',
+    workspaceName: 'Acme'
+  };
+  const omar: HubUserFixture = {
+    ...mira,
+    sub: 'hub-user-omar',
+    email: 'omar@apps.test',
+    name: 'Omar Diallo'
+  };
+  const lea: HubUserFixture = {
+    ...mira,
+    sub: 'hub-user-lea',
+    email: 'lea@apps.test',
+    name: 'Léa Martin'
+  };
+
+  beforeAll(async () => {
+    hub = await FakeHub.start({ clientId: host.hubClientId });
+    hub.setTools([
+      {
+        slug: 'ledger-tool',
+        name: 'Antasphere Ledger Tool',
+        launchUrl: 'https://ledger-tool.example.com',
+        descriptor: DESCRIPTOR
+      },
+      {
+        slug: 'people-tool',
+        name: 'Antasphere People Tool',
+        launchUrl: 'https://people-tool.example.com',
+        descriptor: { icon: 'users' }
+      },
+      { slug: host.identity.slug, name: 'This Tool', launchUrl: 'https://thistool.example.com' }
+    ]);
+    hub.setToolClosed(omar.sub, 'people-tool', ORG);
+    app = await createTestApp(await createDatabase(container, 'apps_route_cloud'), {
+      EDITION: 'cloud',
+      HUB_ISSUER_URL: hub.issuer,
+      HUB_CLIENT_ID: host.hubClientId,
+      HUB_CLIENT_SECRET: 'integration-test-hub-secret-0001'
+    });
+  }, 180_000);
+
+  afterAll(async () => {
+    await app?.stop();
+    await hub?.stop();
+  });
+
+  it('a person signed in through the hub reads the catalogue for her organization, with the descriptors, this tool current', async () => {
+    const cookie = await ssoLogin(app, hub, mira);
+    const res = await send(app, 'GET', '/apps', { cookie });
+    expect(res.status).toBe(200);
+    const body = await readJson(res);
+    expect(body.source).toBe('hub');
+    expect(body.hub).toEqual({ url: `${hub.issuer}/`, name: 'Antasphere Account' });
+    expect(body.apps.map((a: { slug: string; current: boolean }) => [a.slug, a.current])).toEqual([
+      ['ledger-tool', false],
+      ['people-tool', false],
+      [host.identity.slug, true]
+    ]);
+    expect(body.apps[0].descriptor).toEqual(DESCRIPTOR);
+    expect(body.apps[1].descriptor).toEqual({ icon: 'users' });
+    // asked as the person, for the workspace's hub organization
+    const last = hub.meAppsRequests.at(-1)!;
+    expect(last.orgId).toBe(ORG);
+    expect(last.auth).toMatch(/^Bearer /);
+  });
+
+  it('a tool the organization does not open to the person is left out of her list', async () => {
+    const cookie = await ssoLogin(app, hub, omar);
+    const body = await readJson(await send(app, 'GET', '/apps', { cookie }));
+    expect(body.source).toBe('hub');
+    expect(body.apps.map((a: { slug: string }) => a.slug)).toEqual(['ledger-tool', host.identity.slug]);
+  });
+
+  it('a person whose organization the hub suspended reads an empty list that says so, never the tools', async () => {
+    const cookie = await ssoLogin(app, hub, lea);
+    hub.setUserOrg(lea.sub, ORG, { name: 'Acme', role: 'member', status: 'suspended' });
+    const body = await readJson(await send(app, 'GET', '/apps', { cookie }));
+    expect(body.source).toBe('hub');
+    expect(body.apps).toEqual([]);
+    expect(body.organization).toEqual({ name: 'Acme', status: 'suspended' });
+    expect(body.hub).toEqual({ url: `${hub.issuer}/`, name: 'Antasphere Account' });
+  });
+});