feat(workspace-service): didi.sh sessions verified on the WS gate — augment-it becomes the identity service's first consumer

The workspace WebSocket upgrade now verifies the didi_session cookie
locally — jose + remote JWKS, EdDSA-only, issuer-checked — and attaches
the verified didi_id to the session and the session frame. Spec
increment 2, dev mode.

Three modes via DIDI_AUTH: off, optional (dev default — legacy
continuity tokens keep working, identity rides along when present), and
required (4401 on upgrades without a valid cookie — the posture once
invites exist). The adapter is ~80 copied-in lines per the spec's
no-shared-package discipline.

Local dev mirrors production topology: cookies ignore ports, so the id
service on localhost:4000 sets a host-only cookie that rides every
localhost WS upgrade — the same-host analog of the .didi.sh domain
cookie. The container fetches JWKS via host.docker.internal; deploy is
an env swap (ID_JWKS_URL / ID_ISSUER / DIDI_AUTH in docker-compose).

Proven by scripts/prove-didi-auth.mjs against the live local stack:
magic-link redeem -> cookie -> WS upgrade carries verified didi_id ->
cookieless upgrade still works -> tampered token treated as absent.
All green on first run after container rebuild. workspace typecheck 0
errors.

Files changed:
- services/workspace/src/didi.ts (new — the verify adapter)
- services/workspace/src/ws.ts (upgrade handler + session frame)
- services/workspace/package.json (+jose; ws as devDep for the prover)
- docker-compose.yml (ID_JWKS_URL / ID_ISSUER / DIDI_AUTH env)
- scripts/prove-didi-auth.mjs (the acceptance proof)
- changelog/2026-07-06_01_Workspace-Meets-Its-Identity-Didi-Sessions-Verified-On-The-WS-Gate.md

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: mpstaton

changelog/2026-07-06_01_Workspace-Meets-Its-Identity-Didi-Sessions-Verified-On-The-WS-Gate.md

@@ -0,0 +1,69 @@
+---
+date_created: 2026-07-06
+date_modified: 2026-07-06
+title: "Workspace meets its identity — didi.sh sessions verified on the WS gate"
+lede: "augment-it becomes the didi.sh identity service's first consumer: the workspace WS upgrade now verifies the didi_session cookie locally (jose + JWKS, EdDSA-only), attaches didi_id to the session, and keeps the legacy continuity token working — proven end-to-end against local dev, id service to Docker container."
+publish: true
+authors:
+  - Michael Staton
+augmented_with:
+  - Claude Code on Claude Fable 5
+files_changed:
+  - services/workspace/src/didi.ts
+  - services/workspace/src/ws.ts
+  - services/workspace/package.json
+  - docker-compose.yml
+  - scripts/prove-didi-auth.mjs
+tags:
+  - Progress-Update
+  - Auth
+  - Didi-Platform
+  - Identity-Service
+  - Workspace-Service
+  - JWKS
+---
+
+## Why Care?
+
+Until today the workspace gate was session *continuity*, not authentication —
+any browser that connected got a minted token. Now the gate knows **who** is
+connecting: a `didi_session` cookie from the didi.sh identity service is
+verified on the WebSocket upgrade, and the person's stable `didi_id` rides
+the session. This is spec increment 2 landing in dev mode — the wiring that
+turns "reach-edu and humain-vc want logins" from an auth-service feature
+into something augment-it actually enforces.
+
+## What's New?
+
+- **The verify adapter** (`services/workspace/src/didi.ts`) — ~80 lines, per
+  the spec's copy-in discipline (no shared package with the identity
+  service, by design). Verifies signature + expiry + issuer against the id
+  service's JWKS: **EdDSA only** (a symmetric algorithm would let any
+  verifier mint), fetched once and cached, locally checked per upgrade — no
+  network call to the identity service on the hot path.
+- **Three modes** via `DIDI_AUTH`: `off`, `optional` (dev default — identity
+  attaches when the cookie is present, the legacy continuity token still
+  works), `required` (upgrades without a valid cookie are rejected with
+  4401 — the posture once operators are didi users).
+- **The session frame carries `didi_id`** so the shell can know who it is
+  the moment the socket opens.
+- **Local-dev topology that mirrors production.** Cookies ignore ports, so
+  the dev id service on `localhost:4000` sets a host-only cookie that rides
+  every localhost WS upgrade — the same-host analog of the `.didi.sh`
+  domain cookie. The container reaches the host's id service via
+  `host.docker.internal` for the JWKS fetch. Deploy-time is an env swap.
+
+## Proven, not promised
+
+`scripts/prove-didi-auth.mjs` walks the whole loop against the live local
+stack: magic-link issue + redeem at the id service → cookie → WS upgrade
+with the cookie → session frame carrying the verified `didi_id` → upgrade
+without the cookie still works (optional mode) → tampered token treated as
+absent. All four steps green on first run after the container rebuild.
+
+## What's Next
+
+The shell's access panel (sign-in UI calling the id service's magic-link
+endpoints from inside augment-it, per the headless GTM contract), the
+per-capability org→workspace authorization mapping, and — once invites
+exist (id spec increment 3) — flipping `DIDI_AUTH=required`.

docker-compose.yml

@@ -27,6 +27,15 @@ services:
       # absent → first slug alphabetically (humain-vc today).
       CLIENTS_ROOT: /clients
       ACTIVE_CLIENT_ID: ${ACTIVE_CLIENT_ID:-}
+      # didi.sh identity (spec increment 2) — verify the didi_session
+      # cookie on WS upgrade against the id service's JWKS. Local dev runs
+      # the id service on the HOST at :4000 (mix phx.server in id-didi-sh),
+      # reached from this container via host.docker.internal. 'optional'
+      # keeps the legacy continuity-token flow working; flip to 'required'
+      # once operators are didi users. Prod swaps the URLs to id.didi.sh.
+      ID_JWKS_URL: ${ID_JWKS_URL:-http://host.docker.internal:4000/.well-known/jwks.json}
+      ID_ISSUER: ${ID_ISSUER:-http://localhost:4000}
+      DIDI_AUTH: ${DIDI_AUTH:-optional}
     volumes:
       - workspace-data:/data
       - ./clients:/clients:ro

pnpm-lock.yaml

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// ============================================================================
+// prove-didi-auth.mjs — spec increment 2's acceptance proof (dev mode).
+//
+// Proves the didi.sh identity plane works against LOCAL augment-it dev:
+//   1. magic-link issue + redeem against the local id service (:4000)
+//      → didi_session cookie (EdDSA JWT)
+//   2. WS upgrade to workspace-service (:3001) WITH the cookie
+//      → session frame carries didi_id (verified locally via JWKS)
+//   3. WS upgrade WITHOUT the cookie
+//      → still connects (DIDI_AUTH=optional), didi_id null
+//
+// Prereqs:
+//   - id service:      cd ../id-didi-sh && mix phx.server   (user seeded)
+//   - augment-it:      docker compose up --build -d workspace-service
+//
+// Usage: node scripts/prove-didi-auth.mjs [email]
+// ============================================================================
+
+import { createRequire } from 'node:module';
+const require = createRequire(
+  new URL('../services/workspace/package.json', import.meta.url),
+);
+const WebSocket = require('ws');
+
+const ID_BASE = process.env.ID_BASE ?? 'http://localhost:4000';
+const WS_URL = process.env.WS_URL ?? 'ws://localhost:3001/ws';
+const EMAIL = process.argv[2] ?? 'alice@example.com';
+
+const fail = (msg) => {
+  console.error(`\x1b[31mFAIL: ${msg}\x1b[0m`);
+  process.exit(1);
+};
+const step = (msg) => console.log(`\n\x1b[1m== ${msg}\x1b[0m`);
+
+// ── 1. magic link → didi_session cookie ────────────────────────────────────
+step('1. issue + redeem magic link against local id service');
+const issue = await fetch(`${ID_BASE}/api/magic-links`, {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ email: EMAIL, app: 'augment-it' }),
+}).then((r) => r.json());
+if (!issue.dev_token) fail('no dev_token — is the user seeded and the id service in dev mode?');
+
+const redeem = await fetch(`${ID_BASE}/api/magic-links/redeem`, {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ token: issue.dev_token }),
+});
+const setCookie = redeem.headers.get('set-cookie') ?? '';
+const jwt = /didi_session=([^;]+)/.exec(setCookie)?.[1];
+if (!jwt) fail('redeem did not set didi_session');
+const { didi_id } = await redeem.json();
+console.log(`didi_session minted for didi_id=${didi_id}`);
+
+// ── 2. WS upgrade WITH the cookie → identity attached ─────────────────────
+step('2. workspace WS upgrade WITH didi_session cookie');
+const withCookie = await firstFrame(WS_URL, { Cookie: `didi_session=${jwt}` });
+console.log('session frame:', JSON.stringify(withCookie));
+if (withCookie.kind !== 'session') fail('expected a session frame');
+if (withCookie.didi_id !== didi_id) {
+  fail(
+    `workspace did not verify the identity — expected didi_id=${didi_id}, got ${withCookie.didi_id}. ` +
+      'Is the container rebuilt with ID_JWKS_URL set, and can it reach host.docker.internal:4000?',
+  );
+}
+console.log('identity verified by workspace via JWKS ✓');
+
+// ── 3. WS upgrade WITHOUT the cookie → legacy flow, no identity ───────────
+step('3. workspace WS upgrade WITHOUT cookie (DIDI_AUTH=optional)');
+const bare = await firstFrame(WS_URL, {});
+if (bare.kind !== 'session') fail('expected a session frame');
+if (bare.didi_id !== null && bare.didi_id !== undefined) {
+  fail('expected no identity without a cookie');
+}
+console.log('legacy continuity flow intact, didi_id null ✓');
+
+// ── 4. tampered cookie → treated as absent ─────────────────────────────────
+step('4. WS upgrade with a TAMPERED cookie → no identity');
+const [h, p] = jwt.split('.');
+const forged = `${h}.${p}.AAAA`;
+const tampered = await firstFrame(WS_URL, { Cookie: `didi_session=${forged}` });
+if (tampered.didi_id) fail('tampered token must not verify');
+console.log('tampered token rejected ✓');
+
+console.log('\n\x1b[32mDIDI AUTH PROVEN AGAINST LOCAL DEV\x1b[0m');
+process.exit(0);
+
+function firstFrame(url, headers) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(url, { headers });
+    const timer = setTimeout(() => {
+      ws.terminate();
+      reject(new Error('timeout waiting for session frame'));
+    }, 8000);
+    ws.on('message', (raw) => {
+      clearTimeout(timer);
+      ws.close();
+      resolve(JSON.parse(raw.toString('utf8')));
+    });
+    ws.on('close', (code, reason) => {
+      clearTimeout(timer);
+      reject(new Error(`ws closed: ${code} ${reason}`));
+    });
+    ws.on('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+  }).catch((err) => fail(err.message));
+}

scripts/prove-didi-auth.mjs

@@ -12,11 +12,13 @@
   "dependencies": {
     "@fastify/websocket": "^11.0.0",
     "fastify": "^5.9.0",
-    "@nats-io/transport-node": "^3.4.0"
+    "@nats-io/transport-node": "^3.4.0",
+    "jose": "^6.0.11"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",
     "tsx": "^4.22.4",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "ws": "^8.18.0"
   }
-}
+}

services/workspace/package.json

@@ -0,0 +1,81 @@
+// didi.ts — the didi.sh identity verify adapter (spec increment 2).
+//
+// Verifies the `didi_session` cookie presented on the WS upgrade against
+// the id.didi.sh JWKS: EdDSA signature + exp + issuer, checked LOCALLY —
+// no per-request call to the identity service (the JWKS is fetched once
+// and cached by jose; re-fetched on unknown `kid`, which is the key-
+// rotation contract).
+//
+// Modes (DIDI_AUTH env):
+//   off      — adapter inert; legacy continuity tokens only.
+//   optional — verify when the cookie is present; legacy flow still works.
+//              (dev default while the shell's access panel is built)
+//   required — upgrades without a valid didi_session are rejected.
+//              (the posture once invites exist and operators are didi users)
+//
+// Spec of record: ai-labs/context-v/specs/Id-Didi-Sh-Identity-Service.md.
+// Local dev: run the id service on localhost:4000 (`mix phx.server`) —
+// host-only localhost cookies ignore ports, so a cookie set by :4000 rides
+// every localhost WS upgrade, the same-host analog of `.didi.sh`.
+
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+
+const JWKS_URL = process.env.ID_JWKS_URL;
+const ISSUER = process.env.ID_ISSUER ?? 'https://id.didi.sh';
+const MODE = (process.env.DIDI_AUTH ?? 'off') as 'off' | 'optional' | 'required';
+
+export type DidiIdentity = {
+  didi_id: string;
+  session_id: string;
+};
+
+export function didiMode(): 'off' | 'optional' | 'required' {
+  // No JWKS endpoint configured → the adapter cannot verify anything;
+  // fall back to off regardless of the requested mode.
+  return JWKS_URL ? MODE : 'off';
+}
+
+let jwks: ReturnType<typeof createRemoteJWKSet> | null = null;
+
+/**
+ * Verify the didi_session cookie from a raw Cookie header.
+ * Returns the identity on success, null on absent/invalid — the CALLER
+ * decides whether null is fatal (required mode) or fine (optional).
+ */
+export async function verifyDidiCookie(
+  cookieHeader: string | string[] | undefined,
+): Promise<DidiIdentity | null> {
+  if (didiMode() === 'off') return null;
+  const token = readCookie(cookieHeader, 'didi_session');
+  if (!token) return null;
+
+  try {
+    jwks ??= createRemoteJWKSet(new URL(JWKS_URL as string));
+    const { payload } = await jwtVerify(token, jwks, {
+      issuer: ISSUER,
+      algorithms: ['EdDSA'],
+    });
+    if (typeof payload.sub !== 'string' || typeof payload.sid !== 'string') {
+      return null;
+    }
+    return { didi_id: payload.sub, session_id: payload.sid };
+  } catch {
+    return null;
+  }
+}
+
+function readCookie(
+  header: string | string[] | undefined,
+  name: string,
+): string | null {
+  if (!header) return null;
+  const raw = Array.isArray(header) ? header.join('; ') : header;
+  for (const part of raw.split(';')) {
+    const eq = part.indexOf('=');
+    if (eq === -1) continue;
+    if (part.slice(0, eq).trim() === name) {
+      return part.slice(eq + 1).trim();
+    }
+  }
+  return null;
+}