From e5dd6e476738a650f57e6d3653f53277b6e26ba5 Mon Sep 17 00:00:00 2001
From: Roland Rodriguez <roland@govcraft.ai>
Date: Thu, 28 May 2026 14:58:32 -0500
Subject: [PATCH] feat(site): tenant switcher chrome in generated admin shell
 (#79)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Surface the operator's tenancy in the generated admin shell and let
multi-tenant users switch the active tenant, building on the stateless
header-driven model shipped in #67/#70 (no active_tenant token claim;
the active tenant is chosen per-request via the X-Active-Tenant header).

- auth.ts: activeTenantStore (sessionStorage), ACTIVE_TENANT_HEADER,
  fetchMe(), and MeResponse/TenantRef/ActiveTenant types mirroring the
  Rust shapes. The active tenant is cleared alongside the token so a lost
  session never strands a stale selection for the next operator.
- api-client: attach X-Active-Tenant on every request (a caller-supplied
  header still wins). The server already 403s a non-member value, so this
  is convenience + display, never the security boundary.
- App.tsx: TenantControl in the topbar — a picker for >=2 memberships, a
  chip for exactly one, and an "Operating as: platform_admin" badge for
  role holders (the server bypasses tenant scoping for them, so a picker
  would imply a constraint that does not exist). Switching stores the
  choice and hard-reloads to /admin so no prior-tenant data lingers in the
  React Query cache under the new scope.
- vendor.rs: INDEX_CSS styles for the picker, chip, and badge.

Frontend-only; no backend change.
---
 .../src/commands/site/vendor.rs               |  37 ++++++
 .../templates/site/src/App.tsx.jinja          |  96 ++++++++++++++-
 .../site/src/admin/api-client.ts.jinja        |  10 +-
 .../templates/site/src/lib/auth.ts.jinja      | 111 ++++++++++++++++++
 4 files changed, 252 insertions(+), 2 deletions(-)

diff --git a/crates/schema-forge-cli/src/commands/site/vendor.rs b/crates/schema-forge-cli/src/commands/site/vendor.rs
index 6978cc6..8da89c5 100644
--- a/crates/schema-forge-cli/src/commands/site/vendor.rs
+++ b/crates/schema-forge-cli/src/commands/site/vendor.rs
@@ -1222,6 +1222,43 @@ body {
   border-radius: 2px;
 }
 
+/* ---- Tenant switcher (topbar) ---- */
+.topbar-tenant {
+  display: inline-flex; align-items: center; gap: 6px;
+  padding: 0 4px 0 8px;
+  border: 1px solid var(--app-border);
+  border-radius: 2px;
+  background: var(--app-bg-2);
+  color: var(--app-fg-2);
+}
+.topbar-tenant:hover { border-color: var(--app-border-2); }
+.topbar-tenant select {
+  border: 0; background: transparent;
+  color: var(--app-fg-1);
+  font-family: inherit; font-size: 13px;
+  padding: 5px 4px; cursor: pointer;
+  max-width: 220px;
+}
+.topbar-tenant select:focus-visible {
+  outline: 2px solid var(--app-fg-1);
+  outline-offset: 2px; border-radius: 2px;
+}
+.topbar-tenant-chip {
+  display: inline-flex; align-items: center; gap: 6px;
+  padding: 5px 10px;
+  border: 1px solid var(--app-border);
+  border-radius: 2px;
+  background: var(--app-bg-2);
+  color: var(--app-fg-2);
+  font-size: 13px;
+}
+.topbar-tenant-admin {
+  font-family: var(--font-mono); font-size: 11px;
+  letter-spacing: 0.04em;
+  border-color: var(--accent);
+  color: var(--app-fg-1);
+}
+
 /* ---- Page wrapper ---- */
 .page { padding: 24px 32px 64px; max-width: 1480px; }
 .page-narrow { padding: 24px 32px 64px; max-width: 920px; }
diff --git a/crates/schema-forge-cli/templates/site/src/App.tsx.jinja b/crates/schema-forge-cli/templates/site/src/App.tsx.jinja
index 3134424..ac73772 100644
--- a/crates/schema-forge-cli/templates/site/src/App.tsx.jinja
+++ b/crates/schema-forge-cli/templates/site/src/App.tsx.jinja
@@ -39,7 +39,14 @@ import { routeManifest } from "@/generated/route-manifest"
 import { LoginPage } from "@/pages/login"
 import { AdminLayout } from "@/admin/layout"
 import { RequireAuth } from "@/lib/require-auth"
-import { getCurrentUsername, isAuthenticated, logout } from "@/lib/auth"
+import {
+  activeTenantStore,
+  fetchMe,
+  getCurrentRoles,
+  getCurrentUsername,
+  isAuthenticated,
+  logout,
+} from "@/lib/auth"
 import {
   getAdminPermissions,
   isSystemSchema,
@@ -273,6 +280,91 @@ function humanizeCrumb(seg: string): string {
   return decoded
 }
 
+// The role that transcends tenancy. A holder sees cross-tenant data because
+// the server's tenant_scope middleware bypasses scoping for them entirely —
+// so the switcher shows a standing badge rather than a picker. Mirrors
+// `PLATFORM_ADMIN_ROLE` in the Rust backend.
+const PLATFORM_ADMIN_ROLE = "platform_admin"
+
+// Tenant ids are TypeIDs (`organization_01k…`); show a compact tail so a
+// screen reader and the eye both get something legible rather than 30 chars.
+function shortTenantId(id: string): string {
+  const tail = id.includes("_") ? id.slice(id.lastIndexOf("_") + 1) : id
+  return tail.length > 10 ? tail.slice(0, 8) + "…" : tail
+}
+
+// Tenant chrome: a picker when the operator belongs to several tenants, a
+// static chip when they belong to exactly one, and a "platform_admin" badge
+// when no tenant scope is in effect (so cross-tenant visibility is explained).
+// Switching is stateless — it stores the choice and hard-reloads to /admin so
+// no tenant-A data lingers in the React Query cache under tenant B.
+function TenantControl() {
+  const { data: me } = useQuery({
+    queryKey: ["auth", "me", activeTenantStore.get()],
+    queryFn: fetchMe,
+  })
+
+  const isPlatformAdmin = getCurrentRoles().includes(PLATFORM_ADMIN_ROLE)
+  const chain = me?.tenant_chain ?? []
+  const active = me?.active_tenant ?? null
+
+  // Platform admin first: their requests are never tenant-scoped server-side,
+  // so a picker would imply a constraint that does not exist.
+  if (isPlatformAdmin) {
+    return (
+      <span className="topbar-tenant-chip topbar-tenant-admin">
+        Operating as: platform_admin
+      </span>
+    )
+  }
+
+  function switchTo(value: string) {
+    const sep = value.indexOf(":")
+    if (sep <= 0) return
+    activeTenantStore.set(value.slice(0, sep), value.slice(sep + 1))
+    if (typeof window !== "undefined") window.location.assign("/admin")
+  }
+
+  if (chain.length >= 2) {
+    const current = active ? `${active.tenant_type}:${active.tenant_id}` : ""
+    return (
+      <label className="topbar-tenant">
+        <Building2 size={14} aria-hidden="true" />
+        <span className="sr-only">Active tenant</span>
+        <select
+          value={current}
+          onChange={(e) => switchTo(e.target.value)}
+          aria-label="Switch active tenant"
+        >
+          {current === "" ? <option value="">Select tenant…</option> : null}
+          {chain.map((t) => (
+            <option key={`${t.schema}:${t.entity_id}`} value={`${t.schema}:${t.entity_id}`}>
+              {t.schema}: {shortTenantId(t.entity_id)}
+            </option>
+          ))}
+        </select>
+      </label>
+    )
+  }
+
+  if (active) {
+    return (
+      <span
+        className="topbar-tenant-chip"
+        title={`${active.tenant_type}:${active.tenant_id}`}
+      >
+        <Building2 size={14} aria-hidden="true" />
+        <span>
+          {active.tenant_type}: {shortTenantId(active.tenant_id)}
+        </span>
+      </span>
+    )
+  }
+
+  // No tenancy in effect (single-tenant deployment or no memberships).
+  return null
+}
+
 function Topbar({ theme, onToggleTheme }: { theme: Theme; onToggleTheme: () => void }) {
   const location = useLocation()
   const navigate = useNavigate()
@@ -324,6 +416,8 @@ function Topbar({ theme, onToggleTheme }: { theme: Theme; onToggleTheme: () => v
         </span>
       </button>
 
+      <TenantControl />
+
       <button
         type="button"
         className="btn btn-icon btn-ghost"
diff --git a/crates/schema-forge-cli/templates/site/src/admin/api-client.ts.jinja b/crates/schema-forge-cli/templates/site/src/admin/api-client.ts.jinja
index 8268991..2410cdc 100644
--- a/crates/schema-forge-cli/templates/site/src/admin/api-client.ts.jinja
+++ b/crates/schema-forge-cli/templates/site/src/admin/api-client.ts.jinja
@@ -8,7 +8,7 @@
 // and `FieldResponse`. Keep them in sync with that file when the backend
 // changes — TODO(Phase 4) is to have the backend expose a pre-digested
 // "view" shape so we don't parse the raw `FieldType` enum on the client.
-import { refreshToken, tokenStore } from "@/lib/auth"
+import { ACTIVE_TENANT_HEADER, activeTenantStore, refreshToken, tokenStore } from "@/lib/auth"
 
 const API_BASE = (import.meta.env.VITE_API_BASE as string | undefined) ?? ""
 const FORGE_API_PREFIX = "/api/v1/forge"
@@ -374,6 +374,14 @@ async function sendRequest(path: string, init?: RequestInit): Promise<Response>
   if (token) {
     headers["Authorization"] = `Bearer ${token}`
   }
+  // Scope every entity request to the operator's chosen tenant. The server
+  // resolves this against the token's membership set and 403s a non-member
+  // value, so it is safe to send unconditionally. A caller-supplied header
+  // (via `init`) wins, letting one-off requests override the active scope.
+  const activeTenant = activeTenantStore.get()
+  if (activeTenant && !(ACTIVE_TENANT_HEADER in headers)) {
+    headers[ACTIVE_TENANT_HEADER] = activeTenant
+  }
   return fetch(`${API_BASE}${path}`, { ...init, headers })
 }
 
diff --git a/crates/schema-forge-cli/templates/site/src/lib/auth.ts.jinja b/crates/schema-forge-cli/templates/site/src/lib/auth.ts.jinja
index d342b42..29e0ef9 100644
--- a/crates/schema-forge-cli/templates/site/src/lib/auth.ts.jinja
+++ b/crates/schema-forge-cli/templates/site/src/lib/auth.ts.jinja
@@ -19,10 +19,21 @@ const TOKEN_KEY = "schemaforge.token"
 const EXPIRES_KEY = "schemaforge.token_expires_at"
 const ROLES_KEY = "schemaforge.roles"
 const USERNAME_KEY = "schemaforge.username"
+// The tenant the operator is currently acting within. Persisted so the
+// choice survives reloads; sent verbatim as the `X-Active-Tenant` request
+// header. Value shape is `<tenant_type>:<tenant_id>`, the same string the
+// server's tenant_scope middleware parses.
+const ACTIVE_TENANT_KEY = "schemaforge.active_tenant"
 
 const API_BASE = (import.meta.env.VITE_API_BASE as string | undefined) ?? ""
 const LOGIN_PATH = "/api/v1/forge/auth/login"
 const REFRESH_PATH = "/api/v1/forge/auth/refresh"
+const ME_PATH = "/api/v1/forge/auth/me"
+
+/** The header the backend reads to scope a request to one of the caller's
+ *  tenant memberships. Mirrors `ACTIVE_TENANT_HEADER` in the Rust
+ *  `tenant_scope` middleware; surfaced here so callers don't hard-code it. */
+export const ACTIVE_TENANT_HEADER = "X-Active-Tenant"
 
 // Fire the background refresh this many ms before the token's stated
 // `expires_at`. Five minutes gives the network and the refresh handler
@@ -108,6 +119,9 @@ export const tokenStore = {
       window.sessionStorage.removeItem(EXPIRES_KEY)
       window.sessionStorage.removeItem(ROLES_KEY)
       window.sessionStorage.removeItem(USERNAME_KEY)
+      // Clear the active tenant alongside the token. Losing the session must
+      // not strand a stale tenant selection that the next operator inherits.
+      window.sessionStorage.removeItem(ACTIVE_TENANT_KEY)
     } catch {
       // Ignore — clear is best-effort.
     }
@@ -118,6 +132,46 @@ export const tokenStore = {
   },
 }
 
+/**
+ * The tenant the operator is currently acting within.
+ *
+ * Switching tenants is a stateless, client-driven concern: the PASETO carries
+ * the user's *full* membership set (`tenant_chain`); which membership scopes a
+ * given request is chosen per-request by sending the `X-Active-Tenant` header.
+ * This store holds that choice. The server independently rejects a header
+ * naming a tenant the caller is not a member of (403), so this is convenience
+ * + display, never the security boundary.
+ */
+export const activeTenantStore = {
+  /** Current `<tenant_type>:<tenant_id>` header value, or `null` if unset. */
+  get(): string | null {
+    if (typeof window === "undefined") return null
+    try {
+      return window.sessionStorage.getItem(ACTIVE_TENANT_KEY)
+    } catch {
+      return null
+    }
+  },
+  set(tenantType: string, tenantId: string): void {
+    if (typeof window === "undefined") return
+    try {
+      window.sessionStorage.setItem(ACTIVE_TENANT_KEY, `${tenantType}:${tenantId}`)
+    } catch {
+      // sessionStorage quota / private mode: silently drop. Requests will
+      // fall back to no header; a multi-membership user then gets the
+      // server's 400 ACTIVE_TENANT_REQUIRED until the next successful set.
+    }
+  },
+  clear(): void {
+    if (typeof window === "undefined") return
+    try {
+      window.sessionStorage.removeItem(ACTIVE_TENANT_KEY)
+    } catch {
+      // Ignore — clear is best-effort.
+    }
+  },
+}
+
 function storeAndSchedule(body: LoginResponse): LoginResponse {
   tokenStore.set(body.token, body.expires_at, body.roles ?? [])
   scheduleRefresh(body.expires_at)
@@ -238,3 +292,60 @@ export function logout(): void {
 export function isAuthenticated(): boolean {
   return tokenStore.get() !== null
 }
+
+// ---------------------------------------------------------------------------
+// Principal / tenancy (`GET /auth/me`)
+// ---------------------------------------------------------------------------
+
+/** One of the caller's tenant memberships. Mirrors the Rust `TenantRef`
+ *  (`{schema, entity_id}`); every entry is directly usable to build an
+ *  `X-Active-Tenant: <schema>:<entity_id>` value. */
+export type TenantRef = {
+  schema: string
+  entity_id: string
+}
+
+/** The tenant scoping the current session. Mirrors the Rust `ActiveTenant`
+ *  (`{tenant_type, tenant_id}`). `tenant_type` equals the membership's
+ *  `schema`; `tenant_id` equals its `entity_id`. */
+export type ActiveTenant = {
+  tenant_type: string
+  tenant_id: string
+}
+
+/** Response of `GET /auth/me` — the browser cannot decrypt the PASETO, so
+ *  this is the client-side anchor for "signed in as / current tenant" chrome
+ *  and the tenant switcher. Mirrors the Rust `MeResponse`. */
+export type MeResponse = {
+  user_id: string
+  email: string
+  display_name: string | null
+  roles: string[]
+  /** The user's full membership set (every tenant they may operate in). */
+  tenant_chain: TenantRef[]
+  /** The tenant scoping this request: the sent `X-Active-Tenant` if a member,
+   *  else the sole membership, else `null` (the client must choose). */
+  active_tenant: ActiveTenant | null
+  /** The header name to send to set/switch the active tenant. */
+  active_tenant_header: string
+}
+
+/**
+ * Fetch the authenticated principal and tenancy context. Sends the stored
+ * `X-Active-Tenant` so the returned `active_tenant` reflects the operator's
+ * current choice (the endpoint is exempt from tenant scoping, so it always
+ * returns the *full* `tenant_chain` regardless of the header). Throws on a
+ * missing token or non-200 so React Query surfaces the error state.
+ */
+export async function fetchMe(): Promise<MeResponse> {
+  const token = tokenStore.get()
+  if (!token) throw new Error("no stored token")
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${token}`,
+  }
+  const active = activeTenantStore.get()
+  if (active) headers[ACTIVE_TENANT_HEADER] = active
+  const res = await fetch(`${API_BASE}${ME_PATH}`, { headers })
+  if (!res.ok) throw new Error(`auth/me failed: ${res.status}`)
+  return (await res.json()) as MeResponse
+}