Merge pull request #74 from lossless-group/feature/workspace-auth

feat(workspace-auth): multi-tenant workspace auth — org-mapped admission, per-session tenancy, and the zombie-session fix

Author: mpstaton

DEPLOYMENT.md

@@ -1,6 +1,6 @@
 # Deployment
 
-augment-it's single-tenant humain-vc instance runs on **Railway**, not the
+augment-it's instance runs on **Railway**, not the
 DigitalOcean droplet originally prepped for it (see [Why Railway, not
 DO](#why-railway-not-do)). This doc is the standing reference for how it's
 deployed; the narrative of *how it got this way* — including every bug hit
@@ -136,6 +136,82 @@ needing a CNAME + a one-time TXT ownership-verification record:
 `id.didi.sh` had been silently failing since it first deployed. Add each
 new `*.didi.sh` consumer (decks, memos, …) to that list as it goes live.
 
+## Multi-tenancy — the session carries the workspace
+
+As of the `feature/workspace-auth` run (2026-07-28, plan:
+[`context-v/plans/Open-Augment-Didi-Sh-To-Reach-Edu.md`](context-v/plans/Open-Augment-Didi-Sh-To-Reach-Edu.md)),
+ONE instance serves multiple client orgs. The identity spec's designed
+org ↔ workspace mapping is live: a session's `/api/me` memberships resolve
+to the workspaces it may touch, `workspace.activate` is per-user-session,
+and every capability frame is validated server-side against the session's
+allowed set (`services/workspace/src/tenancy.ts` + `enforceTenant` in
+`capabilities.ts`). Proof: `node scripts/prove-session-tenancy.mjs`
+(self-contained; needs only a NATS on localhost).
+
+**Workspace → org binding.** Each workspace declares its org in
+`clients/<id>/workspace.json` (`{ "org_id": "reach.edu" }`) — committed in
+each client repo. Because the deployed `workspace-service` keeps
+`/data/clients` on a volume (self-seeded stubs, not git), production uses
+the env fallback instead:
+
+```
+WORKSPACE_ORG_MAP=humain-vc=humain.vc,reach-edu=reach.edu
+```
+
+The file wins when both exist. A workspace with no org binding is
+invisible to client sessions (fails safe); superusers see everything.
+
+**Env changes vs the single-tenant era** (on `workspace-service`):
+
+| Var | Single-tenant (before) | Multi-tenant (now) |
+|---|---|---|
+| `DIDI_AUTH` | `required` | `required` (unchanged) |
+| `REQUIRED_ORG_ID` | `humain.vc` | **removed** — admission = memberships map onto ≥1 workspace, or superuser |
+| `ACTIVE_CLIENT_ID` | `humain-vc` | **removed** — active is per-session; the global default derives from the persisted pick / first slug |
+| `WORKSPACE_ORG_MAP` | — | `humain-vc=humain.vc,reach-edu=reach.edu` |
+
+The startCommand also seeds the second workspace stub beside humain-vc's:
+
+```sh
+sh -c 'mkdir -p /data/clients/humain-vc /data/clients/reach-edu && echo DEFAULT_DOMAIN_TYPE=thesis > /data/clients/humain-vc/.env && echo DEFAULT_DOMAIN_TYPE=strategy > /data/clients/reach-edu/.env && npm start'
+```
+
+**The row-store caveat.** row-store (and the prompt/response stores behind
+the records surfaces) loads ONE `clients/<active>/rows.json` — the
+instance's *operator-active* workspace, moved only by superuser or
+anonymous switches. Client sessions get those capabilities only while the
+operator-active workspace is in their allowed set; otherwise dispatch
+refuses (`…operator-active workspace…`). SurrealDB-backed surfaces (the
+workbench family) are fully per-session. True per-session row-store
+scoping is a logged follow-up.
+
+**Onboarding the next client org** (the recipe reach-edu followed):
+
+1. id-didi-sh (Fly app `id-didi-sh` — `-C` splits on spaces / strips
+   double quotes, hence `~s(...)` + `\x20`):
+
+   ```bash
+   fly ssh console -a id-didi-sh -C '/app/bin/id_didi_sh rpc IO.inspect(IdDidiSh.Accounts.upsert_org(~s(<org.domain>),~s(Display\x20Name)))'
+   fly ssh console -a id-didi-sh -C '/app/bin/id_didi_sh rpc IO.inspect(IdDidiSh.Accounts.create_user(%{primary_email:~s(<email>),name:~s(First\x20Last)}))'
+   fly ssh console -a id-didi-sh -C '/app/bin/id_didi_sh rpc (u=IdDidiSh.Accounts.get_user_by_email(~s(<email>));IO.inspect(IdDidiSh.Accounts.upsert_membership(u.didi_id,~s(<org.domain>),~s(editor))))'
+   ```
+
+   Roles: `superuser | org_owner | org_admin | editor | viewer`. The user
+   then self-serves a magic link at `id.didi.sh` (or you send one).
+2. `clients/<slug>/workspace.json` in the client repo + append to
+   `WORKSPACE_ORG_MAP` + extend the startCommand's seeded stubs.
+3. Redeploy `workspace-service`.
+
+**The Augment-from-DB remotes** (`org-workbench`, `search-and-add`,
+`search-results`) deploy as three more static-asset services — same shape
+as `chat`/`strategy-curator`: repo-root build context, dockerfilePath
+`apps/<name>/Dockerfile`, no rootDirectory, build-time vars
+`PUBLIC_WS_URL` + `PUBLIC_<NAME>_ASSET_PREFIX=https://<own-domain>`, and
+three matching `PUBLIC_<NAME>_REMOTE=https://<domain>/remoteEntry.js`
+vars on `shell` (then rebuild shell — `PUBLIC_*` is baked at build).
+Person-* resolvers are deliberately NOT deployed: they ride the
+row-store-gated CSV flows.
+
 ## Deploying / redeploying
 
 ```bash

apps/affiliation-rating-resolver/src/App.svelte

@@ -27,7 +27,7 @@
   const ACTIVE_RECORD_SET_KEY = 'augment-it:active-record-set';
   const MAPPING_KEY_PREFIX = 'augment-it:affiliation-rating-resolver:mapping:';
 
-  let status = $state<'connecting' | 'open' | 'closed' | 'error'>('connecting');
+  let status = $state<'connecting' | 'open' | 'closed' | 'error' | 'auth_required'>('connecting');
   let client = $state<string>('reach-edu');
 
   let recordSets = $state<RecordSet[]>([]);

apps/chat/Dockerfile

@@ -18,8 +18,10 @@ COPY shell ./shell
 RUN pnpm install --frozen-lockfile
 
 ARG PUBLIC_WS_URL
+ARG PUBLIC_ID_BASE
 ARG PUBLIC_CHAT_ASSET_PREFIX
 ENV PUBLIC_WS_URL=$PUBLIC_WS_URL
+ENV PUBLIC_ID_BASE=$PUBLIC_ID_BASE
 ENV PUBLIC_CHAT_ASSET_PREFIX=$PUBLIC_CHAT_ASSET_PREFIX
 RUN pnpm --filter @augment-it/chat build
 

apps/chat/src/App.svelte

@@ -19,7 +19,7 @@
     ((import.meta as { env?: Record<string, string> }).env?.PUBLIC_WS_URL as string | undefined) ||
     'ws://localhost:3001/ws';
 
-  let connectionStatus = $state<'connecting' | 'open' | 'closed' | 'error'>('connecting');
+  let connectionStatus = $state<'connecting' | 'open' | 'closed' | 'error' | 'auth_required'>('connecting');
 
   onMount(() => {
     const TOKEN_KEY = 'augment_it_session_token';

apps/enhanced-records-list/src/App.svelte

@@ -21,7 +21,7 @@
     type EnhancedRecord,
   } from './state.svelte';
 
-  let connectionStatus = $state<'connecting' | 'open' | 'closed' | 'error'>('connecting');
+  let connectionStatus = $state<'connecting' | 'open' | 'closed' | 'error' | 'auth_required'>('connecting');
   let loadedOnce = $state<boolean>(false);
 
   // ---- Connect + bootstrap data load ----

apps/org-workbench/Dockerfile

@@ -0,0 +1,32 @@
+# Production build for the org-workbench federated remote — the first
+# surface of the "Augment from DB" flow (Stephenie's workbench). Same
+# rationale as apps/chat/Dockerfile: direct pnpm --filter build, no
+# Railpack auto-detection.
+#
+# Build context is the repo root (Railway: no rootDirectory set for this
+# service, dockerfilePath: apps/org-workbench/Dockerfile).
+
+FROM node:22-alpine AS build
+WORKDIR /monorepo
+RUN corepack enable
+
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY packages ./packages
+COPY apps ./apps
+COPY shell ./shell
+RUN pnpm install --frozen-lockfile
+
+ARG PUBLIC_WS_URL
+ARG PUBLIC_ID_BASE
+ARG PUBLIC_ORG_WORKBENCH_ASSET_PREFIX
+ENV PUBLIC_WS_URL=$PUBLIC_WS_URL
+ENV PUBLIC_ID_BASE=$PUBLIC_ID_BASE
+ENV PUBLIC_ORG_WORKBENCH_ASSET_PREFIX=$PUBLIC_ORG_WORKBENCH_ASSET_PREFIX
+RUN pnpm --filter @augment-it/org-workbench build
+
+FROM node:22-alpine
+WORKDIR /app
+RUN npm install -g serve
+COPY --from=build /monorepo/apps/org-workbench/dist ./dist
+EXPOSE 3014
+CMD ["serve", "-s", "dist", "-l", "3014"]

apps/org-workbench/rsbuild.config.ts

@@ -9,6 +9,13 @@ import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';
 // by design: every read/write rides workspace.invoke → NATS →
 // record-surrealdb-resolver (spec decision D1).
 // See context-v/specs/Augment-From-DB-Flow.md.
+// Own-origin asset prefix for production (chat/strategy-curator pattern):
+// a remote's sub-chunks resolve against the assetPrefix BAKED AT BUILD, not
+// the host page's origin — without output.assetPrefix they 404 into the
+// shell's SPA-fallback HTML in production. dev.assetPrefix alone only
+// covers the local dev server.
+const ASSET_PREFIX = process.env.PUBLIC_ORG_WORKBENCH_ASSET_PREFIX || 'http://localhost:3014';
+
 export default defineConfig({
   plugins: [
     pluginSvelte(),
@@ -27,6 +34,7 @@ export default defineConfig({
   output: {
     target: 'web',
     overrideBrowserslist: ['last 2 Chrome versions', 'last 2 Firefox versions', 'last 2 Safari versions'],
+    assetPrefix: ASSET_PREFIX,
   },
   tools: {
     swc: {

apps/org-workbench/src/App.svelte

@@ -35,7 +35,7 @@
     window.dispatchEvent(new CustomEvent('augment-it:active-entity', { detail }));
   }
 
-  let status = $state<'connecting' | 'open' | 'closed' | 'error'>('connecting');
+  let status = $state<'connecting' | 'open' | 'closed' | 'error' | 'auth_required'>('connecting');
   let client = $state<string>('reach-edu');
 
   let org = $state<OrgDetail | null>(null);

apps/pack-runner/src/App.svelte

@@ -84,7 +84,7 @@
   const initialBundleId = readStored(BUNDLE_ID_KEY) ?? BUNDLES[0].bundle_id;
   const initialBundle = getBundle(initialBundleId) ?? BUNDLES[0];
 
-  let status = $state<'connecting' | 'open' | 'closed' | 'error'>('connecting');
+  let status = $state<'connecting' | 'open' | 'closed' | 'error' | 'auth_required'>('connecting');
   let recordSets = $state<RecordSet[]>([]);
   let selectedRecordSetId = $state<string | null>(
     readStored(ACTIVE_RECORD_SET_KEY) ?? readStored(LEGACY_RECORD_SET_KEY),

apps/person-db-resolver/src/App.svelte

@@ -44,7 +44,7 @@
   // on explicit jumps.
   const IDX_KEY_PREFIX = 'augment-it:person-db-resolver:idx:';
 
-  let status = $state<'connecting' | 'open' | 'closed' | 'error'>('connecting');
+  let status = $state<'connecting' | 'open' | 'closed' | 'error' | 'auth_required'>('connecting');
   let client = $state<string>('reach-edu');
 
   let recordSets = $state<RecordSet[]>([]);