@antasphere/chassis-server 1.0.0

package/src/identity/hub-jwt.ts

@@ -0,0 +1,78 @@
+import { createRemoteJWKSet, jwtVerify, type JWTPayload, type JWTVerifyOptions } from 'jose';
+
+/** Discovery-document cache lifetime; the JWKS itself is cached by jose. */
+const DISCOVERY_TTL_MS = 10 * 60 * 1000;
+
+/**
+ * Verifies hub-minted RS256 JWTs against the hub's REMOTE JWKS (discovered
+ * via OIDC discovery at the issuer root) — the cloud edition's trust anchor
+ * for "Sign in with Antasphere" (internal/federation.md). Same discipline as
+ * the local OauthJwtVerifier: hard issuer pinning, per-call audience
+ * pinning, RS256 allowlist (implicitly rejects none/HS256), small clock
+ * tolerance. jose's remote key set self-refreshes on an unknown `kid`; a
+ * signature failure on a KNOWN kid (rotation racing the cache) gets exactly
+ * one retry against a freshly created key set.
+ */
+export class HubJwtVerifier {
+  private discoveryCache: { jwksUri: string; fetchedAt: number } | null = null;
+  private keySet: ReturnType<typeof createRemoteJWKSet> | null = null;
+
+  constructor(private readonly issuerUrl: string) {}
+
+  private async jwksUri(): Promise<string> {
+    if (this.discoveryCache && Date.now() - this.discoveryCache.fetchedAt < DISCOVERY_TTL_MS) {
+      return this.discoveryCache.jwksUri;
+    }
+    const url = this.issuerUrl.replace(/\/+$/, '') + '/.well-known/openid-configuration';
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`hub discovery failed: ${res.status} ${url}`);
+    const doc = (await res.json()) as { issuer?: string; jwks_uri?: string };
+    // The discovery document must claim the issuer we were configured to
+    // trust — a mismatch means HUB_ISSUER_URL points at the wrong deployment
+    // (or something impersonating it); fail closed before trusting its keys.
+    if (doc.issuer !== this.issuerUrl) {
+      throw new Error(`hub discovery issuer mismatch: expected ${this.issuerUrl}, got ${doc.issuer}`);
+    }
+    if (typeof doc.jwks_uri !== 'string' || !doc.jwks_uri) {
+      throw new Error('hub discovery document carries no jwks_uri');
+    }
+    this.discoveryCache = { jwksUri: doc.jwks_uri, fetchedAt: Date.now() };
+    return this.discoveryCache.jwksUri;
+  }
+
+  private async keys(forceRefresh = false) {
+    const jwksUri = await this.jwksUri();
+    if (!forceRefresh && this.keySet) return this.keySet;
+    this.keySet = createRemoteJWKSet(new URL(jwksUri));
+    return this.keySet;
+  }
+
+  /** Verify a hub JWT with the given audience pin; throws on any failure. */
+  async verify(token: string, audience: string): Promise<JWTPayload> {
+    const options: JWTVerifyOptions = {
+      issuer: this.issuerUrl,
+      // The hub access token's `aud` is an ARRAY when openid is scoped
+      // ([<our resource>, <hub userinfo>]); jose accepts any element
+      // matching, so pinning our own value stays exact.
+      audience,
+      algorithms: ['RS256'], // hard allowlist — implicitly rejects none/HS256
+      clockTolerance: 5,
+      requiredClaims: ['sub']
+    };
+    try {
+      return (await jwtVerify(token, await this.keys(), options)).payload;
+    } catch (err) {
+      // One retry with fresh keys covers signing-key rotation mid-cache.
+      // Two shapes mean "the cached keys may be stale": an unknown kid
+      // (JWKSNoMatchingKey — jose's own refetch is cooldown-throttled and
+      // may have been skipped) and a signature failure on a known kid.
+      if (
+        err instanceof Error &&
+        (err.name === 'JWKSNoMatchingKey' || err.name === 'JWSSignatureVerificationFailed')
+      ) {
+        return (await jwtVerify(token, await this.keys(true), options)).payload;
+      }
+      throw err;
+    }
+  }
+}

package/src/identity/hub-live-gate.ts

@@ -0,0 +1,167 @@
+import { and, eq } from 'drizzle-orm';
+import { workspaceMembers, workspaces, type Db } from '@antasphere/chassis-db';
+import type { Logger } from '../logger.js';
+import type { GateWorkspace, PrincipalGate, PrincipalGateResult } from '../middleware/auth-context.js';
+import type { HubOrgReconciler } from './hub-reconcile.js';
+import { resolveMembership } from './resolve-membership.js';
+
+/**
+ * The cloud edition's post-resolution principal gate (user-scoped
+ * federation — the replacement for the retired master-key P4 gates): on
+ * EVERY authenticated request into a PROJECTED workspace
+ * (`principal.accountRef` set), hub truth is re-read AS THE USER via the
+ * TTL'd reconciler, and the request is judged on the freshly reconciled
+ * LOCAL rows. No service key, no cross-tenant surface — a user's requests
+ * can only ever be gated by their OWN grant's view of the hub.
+ *
+ * Verdicts, in order:
+ *  - grant dead → 401 `hub_grant_expired` (immediate, no stale window —
+ *    Romain's decision 3; a browser SSO re-login heals the grant);
+ *  - reconcile stale beyond the window AND the hub failing → 403
+ *    `hub_unavailable` (fail closed after ~15 min of outage);
+ *  - hub-origin membership row now inactive (this very pass may have swept
+ *    it) → 401 `membership_revoked`;
+ *  - workspace `hub_status='suspended'` → 403 `account_suspended`, EXCEPT
+ *    `GET /api/v1/me` — suspended is VISIBLE-BUT-BLOCKED, and /me is how
+ *    the dashboard shows the suspended badge instead of stranding the user
+ *    (the reason the PrincipalGate seam carries the request);
+ *  - a role delta from the reconciled row applies to THIS request (D11);
+ *  - a request that SELECTED no workspace, on a credential that pins none,
+ *    runs in the person's default AS THE PASS LEFT IT: the resolver chose
+ *    the workspace before the pass ran, so a default moved at the hub
+ *    (`antasphere org use`) would land the very command that read it in the
+ *    old organization and only the next one in the new (PRDCT-2958, F2).
+ *    The membership is resolved again here and handed back as `workspace`.
+ *
+ * Guest and local-origin rows in a projected workspace skip hub enforcement
+ * entirely EXCEPT the org-level suspension read — and that reads the
+ * LOCALLY MATERIALIZED `workspaces.hub_status` column only, never a hub
+ * round-trip on a borrowed grant. ACCEPTED BOUND (documented): a guest's
+ * own `/orgs` never includes the resource's org, so that column refreshes only
+ * when a MEMBER's reconcile runs — a guest may keep resource access in a
+ * hub-suspended org until a member next touches the tool. Every cheap fix
+ * leaks (a public status probe = suspension oracle) or borrows credentials
+ * (acting on a grant its holder didn't present). Same accepted-bound class
+ * as ungated share-link viewing; suspension still cuts all MEMBERS within
+ * seconds.
+ */
+
+const SUSPENDED_MESSAGE = 'This organization is suspended on Antasphere';
+const UNAVAILABLE_MESSAGE =
+  'The Antasphere hub has been unreachable for too long; requests are refused until it recovers';
+const GRANT_EXPIRED_MESSAGE =
+  'Your Antasphere grant on this instance has expired — sign in with Antasphere again to renew it';
+
+/** The one suspension exemption: the dashboard's whoami read. */
+function isMeRead(request: { path: string; method: string }): boolean {
+  return request.method === 'GET' && request.path === '/api/v1/me';
+}
+
+export interface HubLiveGateDeps {
+  db: Db;
+  reconciler: HubOrgReconciler;
+  logger: Logger;
+}
+
+export class HubLiveGate {
+  constructor(private readonly deps: HubLiveGateDeps) {}
+
+  readonly assert: PrincipalGate = async (principal, request) => {
+    // Unprojected workspace: zero hub surface on this request.
+    if (!principal.accountRef) return { ok: true };
+
+    // Guest/local rows are the tool's own business (never hub truth): no
+    // reconcile, no membership re-assertion, no grant requirement. Org-level
+    // suspension still applies, read from the local column.
+    if (principal.origin !== 'hub') {
+      return this.assertOrgActive(principal.workspaceId, request);
+    }
+
+    const verdict = await this.deps.reconciler.reconcile(principal.userId);
+    if (verdict.kind === 'grant_dead') {
+      return { ok: false, status: 401, code: 'hub_grant_expired', message: GRANT_EXPIRED_MESSAGE };
+    }
+    if (verdict.kind === 'unavailable') {
+      return { ok: false, status: 403, code: 'hub_unavailable', message: UNAVAILABLE_MESSAGE };
+    }
+
+    // Judge the FRESHLY RECONCILED local rows (the pass above may have
+    // swept the membership, synced the role, or flipped hub_status).
+    const row = await this.memberRow(principal.userId, principal.workspaceId);
+    if (!row || !row.isActive) {
+      // Resolution saw an active row moments ago; the reconcile swept it —
+      // the hub no longer asserts this membership. Every later request dies
+      // at resolution itself (plain 401); THIS one carries the reason. A
+      // swept membership is never papered over by a move to another
+      // workspace below: the person learns what happened.
+      return {
+        ok: false,
+        status: 401,
+        code: 'membership_revoked',
+        message: 'Your membership of this organization was removed on Antasphere'
+      };
+    }
+
+    // A selector-less request on an unpinned credential runs in the default
+    // membership as the pass above left it (the resolver read it before, so
+    // a default moved at the hub would land THIS request in the old one).
+    // The moved-to workspace is judged exactly as the resolved one is.
+    if (request.selector === null && !principal.pinned) {
+      const fresh = await resolveMembership(this.deps.db, principal.userId, null);
+      if (fresh && fresh.workspaceId !== principal.workspaceId) {
+        const target = await this.memberRow(principal.userId, fresh.workspaceId);
+        if (target?.isActive) {
+          if (target.hubStatus === 'suspended' && !isMeRead(request)) {
+            return { ok: false, status: 403, code: 'account_suspended', message: SUSPENDED_MESSAGE };
+          }
+          const moved: GateWorkspace = {
+            workspaceId: fresh.workspaceId,
+            role: target.role,
+            origin: fresh.origin,
+            accountRef: fresh.accountRef
+          };
+          return { ok: true, workspace: moved };
+        }
+      }
+    }
+
+    if (row.hubStatus === 'suspended' && !isMeRead(request)) {
+      return { ok: false, status: 403, code: 'account_suspended', message: SUSPENDED_MESSAGE };
+    }
+    // A role delta from the reconciled row applies to THIS request (D11):
+    // a demoted admin loses admin surfaces now, a promotion lands now.
+    if (row.role !== principal.role) {
+      return { ok: true, role: row.role };
+    }
+    return { ok: true };
+  };
+
+  private async memberRow(userId: string, workspaceId: string) {
+    const [row] = await this.deps.db
+      .select({
+        role: workspaceMembers.role,
+        isActive: workspaceMembers.isActive,
+        hubStatus: workspaces.hubStatus
+      })
+      .from(workspaceMembers)
+      .innerJoin(workspaces, eq(workspaceMembers.workspaceId, workspaces.id))
+      .where(and(eq(workspaceMembers.userId, userId), eq(workspaceMembers.workspaceId, workspaceId)))
+      .limit(1);
+    return row;
+  }
+
+  private async assertOrgActive(
+    workspaceId: string,
+    request: { path: string; method: string }
+  ): Promise<PrincipalGateResult> {
+    const [ws] = await this.deps.db
+      .select({ hubStatus: workspaces.hubStatus })
+      .from(workspaces)
+      .where(eq(workspaces.id, workspaceId))
+      .limit(1);
+    if (ws?.hubStatus === 'suspended' && !isMeRead(request)) {
+      return { ok: false, status: 403, code: 'account_suspended', message: SUSPENDED_MESSAGE };
+    }
+    return { ok: true };
+  }
+}

package/src/identity/hub-logout.ts

@@ -0,0 +1,174 @@
+import { and, eq } from 'drizzle-orm';
+import { decodeJwt } from 'jose';
+import { symmetricDecrypt } from 'better-auth/crypto';
+import { account, type Db } from '@antasphere/chassis-db';
+import type { Logger } from '../logger.js';
+import { isLikelyEncrypted } from './hub-grant.js';
+import { HUB_SSO_PROVIDER_ID } from './hub-sso.js';
+
+/**
+ * RP-initiated logout against the hub (SL-2, internal/federation.md): "one
+ * concept of being logged in" needs logout-anywhere to end the HUB session,
+ * not just the local one. The hub's oauth-provider plugin exposes
+ * `GET /oauth2/end-session` (RP-initiated logout); this module builds the
+ * URL the browser must VISIT to end the anchor session — the local revoke
+ * itself happens in api/sso-logout.ts regardless of whether a URL could be
+ * built.
+ *
+ * Everything here FAILS SOFT to `null` ("no hub leg — local signout only"):
+ * a logout must never be blocked by a missing id_token, a hub outage, or a
+ * malformed discovery document. Pinned 1.6.15 plugin facts this leans on
+ * (re-verify on ANY Better Auth / oauth-provider bump):
+ *
+ *  - the id_token is stored PLAINTEXT on the `account` row —
+ *    `encryptOAuthTokens` wraps only access/refresh tokens (setTokenUtil,
+ *    dist/oauth2/utils.mjs; idToken is written raw in
+ *    generic-oauth/routes.mjs + oauth2/link-account.mjs). The read below is
+ *    still encrypted-TOLERANT (the hub-grant isLikelyEncrypted mirror) so a
+ *    future bump that starts encrypting it cannot break logout;
+ *  - the end-session endpoint HARD-FAILS on an id_token_hint without a
+ *    `sid` claim ("id token missing session") — pre-flip id_tokens (minted
+ *    before the hub client's enableEndSession flip) carry none, so a
+ *    sid-less token degrades HERE to null instead of bouncing the user
+ *    through a hub error;
+ *  - verification there is signature-only (jose compactVerify against the
+ *    hub JWKS) — an EXPIRED id_token is still a usable hint, so no expiry
+ *    check happens here either;
+ *  - `post_logout_redirect_uri` must EXACT-match the client's registered
+ *    postLogoutRedirectUris — the cross-repo contract pins
+ *    `<PUBLIC_BASE_URL>/login?signed_out=1`, seeded in the hub registry.
+ */
+
+/** The pinned post-logout landing (cross-repo contract — match EXACTLY). */
+export function postLogoutRedirectUri(publicBaseUrl: string): string {
+  return publicBaseUrl.replace(/\/+$/, '') + '/login?signed_out=1';
+}
+
+export interface HubLogoutOptions {
+  db: Db;
+  /** Hub OIDC issuer (HUB_ISSUER_URL) — discovery derives from it. */
+  issuerUrl: string;
+  /** This instance's public origin — the post-logout landing derives from it. */
+  publicBaseUrl: string;
+  /**
+   * Better Auth's token-encryption key material (`(await
+   * auth.$context).secretConfig`) — only ever consulted when a stored
+   * id_token LOOKS encrypted (future-bump insurance; today's are plaintext).
+   */
+  key: () => Promise<Parameters<typeof symmetricDecrypt>[0]['key']>;
+  logger: Logger;
+  /** Discovery fetch timeout — a slow hub must never hang a logout. */
+  discoveryTimeoutMs?: number;
+  /** Test seam. */
+  fetchImpl?: typeof fetch;
+}
+
+export class HubLogoutService {
+  private readonly fetchImpl: typeof fetch;
+  private readonly timeoutMs: number;
+  /** Discovery-cached end-session endpoint; failures are retried per call. */
+  private endpointCache: string | null = null;
+
+  constructor(private readonly opts: HubLogoutOptions) {
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.timeoutMs = opts.discoveryTimeoutMs ?? 3_000;
+  }
+
+  /**
+   * The hub end-session URL for this user's CURRENT hub session, or null
+   * when no usable hub leg exists (no `antasphere` account row, no stored
+   * id_token, a sid-less pre-flip id_token, or an unreachable/endpoint-less
+   * discovery document). The caller revokes the local session and clears
+   * the hint EITHER WAY — null only means the browser skips the hub bounce.
+   */
+  async endSessionUrl(userId: string): Promise<string | null> {
+    try {
+      const idToken = await this.readIdToken(userId);
+      if (!idToken) return null;
+      // decode (NOT verify) — we only need the sid presence check; the hub
+      // verifies the hint's signature itself on presentation.
+      let sid: unknown;
+      try {
+        sid = decodeJwt(idToken).sid;
+      } catch {
+        return null; // not a JWT — nothing presentable
+      }
+      if (typeof sid !== 'string' || !sid) {
+        // Pre-flip id_token (rollout caveat): the hub would hard-fail the
+        // hint, so degrade to a local-only signout until the next login
+        // stores a sid-carrying token.
+        this.opts.logger.info({ userId }, 'hub logout: stored id_token carries no sid — local signout only');
+        return null;
+      }
+      const endpoint = await this.endSessionEndpoint();
+      if (!endpoint) return null;
+      const url = new URL(endpoint);
+      url.searchParams.set('id_token_hint', idToken);
+      url.searchParams.set('post_logout_redirect_uri', postLogoutRedirectUri(this.opts.publicBaseUrl));
+      return url.toString();
+    } catch (err) {
+      this.opts.logger.warn({ err, userId }, 'hub logout: end-session URL build failed — local signout only');
+      return null;
+    }
+  }
+
+  /** The user's stored hub id_token, plaintext/encrypted-tolerant. */
+  private async readIdToken(userId: string): Promise<string | null> {
+    const [row] = await this.opts.db
+      .select({ idToken: account.idToken })
+      .from(account)
+      .where(and(eq(account.userId, userId), eq(account.providerId, HUB_SSO_PROVIDER_ID)))
+      .limit(1);
+    const stored = row?.idToken;
+    if (!stored) return null;
+    // A JWT (dots, base64url) never matches isLikelyEncrypted, so today's
+    // plaintext tokens pass straight through; a future encrypted value gets
+    // one decrypt attempt and fails soft.
+    if (!isLikelyEncrypted(stored)) return stored;
+    try {
+      return await symmetricDecrypt({ key: await this.opts.key(), data: stored });
+    } catch (err) {
+      this.opts.logger.warn({ err, userId }, 'hub logout: stored id_token failed to decrypt');
+      return null;
+    }
+  }
+
+  /** Discovery read, cached on success; a failed fetch retries next call. */
+  private async endSessionEndpoint(): Promise<string | null> {
+    if (this.endpointCache) return this.endpointCache;
+    const discoveryUrl = this.opts.issuerUrl.replace(/\/+$/, '') + '/.well-known/openid-configuration';
+    try {
+      const res = await this.fetchImpl(discoveryUrl, {
+        headers: { accept: 'application/json' },
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+      if (!res.ok) {
+        this.opts.logger.warn({ status: res.status }, 'hub logout: discovery answered non-2xx');
+        return null;
+      }
+      const doc = (await res.json()) as { end_session_endpoint?: unknown };
+      const endpoint = doc.end_session_endpoint;
+      if (typeof endpoint !== 'string' || !endpoint) {
+        // A hub predating the end-session flip advertises none — degrade.
+        this.opts.logger.info('hub logout: discovery carries no end_session_endpoint — local signout only');
+        return null;
+      }
+      this.endpointCache = endpoint;
+      return endpoint;
+    } catch (err) {
+      this.opts.logger.warn({ err }, 'hub logout: discovery unreachable — local signout only');
+      return null;
+    }
+  }
+}
+
+/**
+ * The Set-Cookie header value that CLEARS the shared SSO hint cookie —
+ * mirroring the hub-set attributes exactly (cross-repo contract: Domain on
+ * the shared parent, Path=/, SameSite=Lax, Secure on https, NOT HttpOnly)
+ * so the browser matches and expires the hub's cookie rather than minting a
+ * host-only shadow. Max-Age=0 is the deletion.
+ */
+export function hintCookieClearHeader(opts: { name: string; domain: string; secure: boolean }): string {
+  return `${opts.name}=; Max-Age=0; Domain=${opts.domain}; Path=/; SameSite=Lax${opts.secure ? '; Secure' : ''}`;
+}

package/src/identity/hub-projection.ts

@@ -0,0 +1,251 @@
+import { and, eq, inArray, isNotNull, lt, notInArray, sql } from 'drizzle-orm';
+import {
+  workspaceMembers,
+  workspaceTeamMembers,
+  workspaceTeams,
+  workspaces,
+  type Db,
+  type DbConn,
+  type WorkspaceRole
+} from '@antasphere/chassis-db';
+
+/**
+ * The ONE hub-org projection primitive (internal/federation.md, ADR 015/018):
+ * extracted verbatim from `HubSsoService.project()` so the SSO login path
+ * and the H4 reconciler (`hub-reconcile.ts`) write byte-identical rows.
+ *
+ * Lazy projection: the hub org becomes a local workspace on first use
+ * (`centralAccountId` = the hub org id), then a membership upsert
+ * re-asserts (role, origin='hub', active) on EVERY call — reactivating a
+ * deactivated row and following hub role changes (D11). Deliberately NOT
+ * WorkspaceService.create: the projection needs ON CONFLICT semantics on
+ * the 0021 unique partial index, the hub's role (not owner), and
+ * origin='hub'.
+ *
+ * Throws raw on any database failure — each caller owns its error posture
+ * (the login path maps to the fail-closed `sso_projection_failed`; the
+ * reconciler logs and continues with the next entry).
+ */
+export interface OrgMembershipProjection {
+  localUserId: string;
+  /** The hub org id (uuid, validated upstream) — never a local workspace id. */
+  hubWorkspaceId: string;
+  /** Display name (H1); null keeps the current name (or mints the placeholder). */
+  hubWorkspaceName: string | null;
+  /** The hub org role, verbatim (D11) — validated upstream, never invented here. */
+  role: WorkspaceRole;
+}
+
+/**
+ * The name a hub org goes by when the hub sends none (an older hub, a blank
+ * name): recognizable, and self-healing wherever the next hub read carries
+ * the real one. The projection's H1 fallback and the refusal page's hint.
+ */
+export function placeholderWorkspaceName(hubOrgId: string): string {
+  return `Antasphere workspace ${hubOrgId.slice(0, 8)}`;
+}
+
+export async function projectOrgMembership(
+  db: Db,
+  projection: OrgMembershipProjection
+): Promise<{ workspaceId: string; memberId: string }> {
+  const { localUserId, hubWorkspaceId, hubWorkspaceName, role } = projection;
+  let [ws] = await db
+    .select({ id: workspaces.id, name: workspaces.name })
+    .from(workspaces)
+    .where(eq(workspaces.centralAccountId, hubWorkspaceId))
+    .limit(1);
+  if (!ws) {
+    // H1 fallback: without workspace_name (older hub), project under a
+    // recognizable placeholder — self-healing, the re-sync below renames
+    // it at the first call whose hub data carries the name.
+    const name = hubWorkspaceName ?? placeholderWorkspaceName(hubWorkspaceId);
+    const inserted = await db
+      .insert(workspaces)
+      .values({ name, centralAccountId: hubWorkspaceId })
+      .onConflictDoNothing({
+        target: workspaces.centralAccountId,
+        where: sql`${workspaces.centralAccountId} IS NOT NULL`
+      })
+      .returning({ id: workspaces.id, name: workspaces.name });
+    // Conflict = a concurrent first projection won the insert; land on its row.
+    ws =
+      inserted[0] ??
+      (
+        await db
+          .select({ id: workspaces.id, name: workspaces.name })
+          .from(workspaces)
+          .where(eq(workspaces.centralAccountId, hubWorkspaceId))
+          .limit(1)
+      )[0];
+    if (!ws) throw new Error('projection insert and re-select both returned nothing');
+  }
+  if (hubWorkspaceName && ws.name !== hubWorkspaceName) {
+    await db.update(workspaces).set({ name: hubWorkspaceName }).where(eq(workspaces.id, ws.id));
+  }
+  const [member] = await db
+    .insert(workspaceMembers)
+    .values({
+      workspaceId: ws.id,
+      userId: localUserId,
+      role,
+      origin: 'hub',
+      isActive: true
+    })
+    .onConflictDoUpdate({
+      target: [workspaceMembers.workspaceId, workspaceMembers.userId],
+      set: { role, origin: 'hub', isActive: true }
+    })
+    .returning({ id: workspaceMembers.id });
+  if (!member) throw new Error('membership upsert returned nothing');
+  return { workspaceId: ws.id, memberId: member.id };
+}
+
+/**
+ * The person's team seats in ONE projected workspace, as the hub asserted
+ * them in this pass (`GET /orgs`' per-org `teams`: the caller's own, never
+ * the team's roster). Upserts each team by its hub id (slug and name follow
+ * the hub; `updated_at` moves only when one of them changed), inserts the
+ * missing seats, and deletes this membership's seats whose team the hub no
+ * longer lists. Both the login pass and the periodic pass come through here,
+ * so they write byte-identical rows.
+ *
+ * Run inside one transaction per org by the caller. Throws raw, like
+ * `projectOrgMembership`. A team id already projected into ANOTHER workspace
+ * (a hub id cannot move between organizations; only a corrupt answer could
+ * say so) is left where it is and not seated here.
+ */
+export interface TeamSeatsProjection {
+  /** The projected workspace (from `projectOrgMembership`). */
+  workspaceId: string;
+  /** The person's membership row in it — the seat rides on it. */
+  memberId: string;
+  teams: ReadonlyArray<{ id: string; slug: string; name: string }>;
+}
+
+export async function projectTeamSeats(db: DbConn, projection: TeamSeatsProjection): Promise<void> {
+  const { workspaceId, memberId, teams } = projection;
+  const seatTeamIds: string[] = [];
+  if (teams.length > 0) {
+    await db
+      .insert(workspaceTeams)
+      .values(teams.map((team) => ({ workspaceId, hubTeamId: team.id, slug: team.slug, name: team.name })))
+      .onConflictDoUpdate({
+        target: workspaceTeams.hubTeamId,
+        set: {
+          slug: sql`excluded.slug`,
+          name: sql`excluded.name`,
+          updatedAt: sql`now()`
+        },
+        // Renamed on drift only, and never across organizations.
+        setWhere: sql`${workspaceTeams.workspaceId} = ${workspaceId}
+          AND (${workspaceTeams.slug} IS DISTINCT FROM excluded.slug
+            OR ${workspaceTeams.name} IS DISTINCT FROM excluded.name)`
+      });
+    const rows = await db
+      .select({ id: workspaceTeams.id })
+      .from(workspaceTeams)
+      .where(
+        and(
+          eq(workspaceTeams.workspaceId, workspaceId),
+          inArray(
+            workspaceTeams.hubTeamId,
+            teams.map((team) => team.id)
+          )
+        )
+      );
+    seatTeamIds.push(...rows.map((row) => row.id));
+    if (seatTeamIds.length > 0) {
+      await db
+        .insert(workspaceTeamMembers)
+        .values(seatTeamIds.map((teamId) => ({ teamId, memberId })))
+        .onConflictDoNothing({ target: [workspaceTeamMembers.teamId, workspaceTeamMembers.memberId] });
+    }
+  }
+  // The seats the hub no longer asserts, in THIS workspace only.
+  const inWorkspace = db
+    .select({ id: workspaceTeams.id })
+    .from(workspaceTeams)
+    .where(eq(workspaceTeams.workspaceId, workspaceId));
+  await db
+    .delete(workspaceTeamMembers)
+    .where(
+      and(
+        eq(workspaceTeamMembers.memberId, memberId),
+        inArray(workspaceTeamMembers.teamId, inWorkspace),
+        ...(seatTeamIds.length > 0 ? [notInArray(workspaceTeamMembers.teamId, seatTeamIds)] : [])
+      )
+    );
+}
+
+/**
+ * The organization's teams in ONE projected workspace, as the hub's `GET
+ * /teams` lists them (PRDCT-2813). This is the organization's DEFINITIVE
+ * list as one member reads it: every team of the org, whether anyone who
+ * signed in here sits in it or not, so a team can be added to a project
+ * before any of its members arrived. The rosters stay the seats of the
+ * people who signed in (`projectTeamSeats`); this touches no seat itself.
+ *
+ * Upserts every listed team by its hub id (slug and name follow the hub,
+ * `updated_at` moves on drift only, never across organizations: the same
+ * rule as `projectTeamSeats`), then, when `complete`, DELETES this
+ * workspace's projected teams (`hub_team_id IS NOT NULL`) the list does not
+ * name: a team deleted at the hub goes, and the foreign keys' cascade takes
+ * its seats and its project entries with it. A local team (`hub_team_id IS
+ * NULL`) is never touched. An incomplete list (the drain's page cap) only
+ * upserts.
+ *
+ * Run inside one transaction by the caller. Throws raw.
+ */
+export interface OrgTeamsProjection {
+  /** The projected workspace (from `projectOrgMembership`). */
+  workspaceId: string;
+  teams: ReadonlyArray<{ id: string; slug: string; name: string }>;
+  /** False when the list is a prefix: nothing is deleted then. Default true. */
+  complete?: boolean | undefined;
+  /**
+   * When the read of the list BEGAN. A projected team created here after that
+   * moment (another replica's pass, another person's seat) is not in this
+   * list because it is newer than the read, not because the hub dropped it:
+   * the delete leaves it alone (verifier round 1, F5). Default: now, which
+   * deletes nothing newer than the call.
+   */
+  readAt?: Date | undefined;
+}
+
+export async function projectOrgTeams(db: DbConn, projection: OrgTeamsProjection): Promise<void> {
+  const { workspaceId, teams } = projection;
+  if (teams.length > 0) {
+    await db
+      .insert(workspaceTeams)
+      .values(teams.map((team) => ({ workspaceId, hubTeamId: team.id, slug: team.slug, name: team.name })))
+      .onConflictDoUpdate({
+        target: workspaceTeams.hubTeamId,
+        set: {
+          slug: sql`excluded.slug`,
+          name: sql`excluded.name`,
+          updatedAt: sql`now()`
+        },
+        setWhere: sql`${workspaceTeams.workspaceId} = ${workspaceId}
+          AND (${workspaceTeams.slug} IS DISTINCT FROM excluded.slug
+            OR ${workspaceTeams.name} IS DISTINCT FROM excluded.name)`
+      });
+  }
+  if (projection.complete === false) return;
+  const readAt = projection.readAt ?? new Date();
+  await db.delete(workspaceTeams).where(
+    and(
+      eq(workspaceTeams.workspaceId, workspaceId),
+      isNotNull(workspaceTeams.hubTeamId),
+      lt(workspaceTeams.createdAt, readAt),
+      ...(teams.length > 0
+        ? [
+            notInArray(
+              workspaceTeams.hubTeamId,
+              teams.map((team) => team.id)
+            )
+          ]
+        : [])
+    )
+  );
+}