create-astram-app 0.4.0 → 0.6.0

package/template/frontend/src/pages/service-accounts/accessModel.js

@@ -0,0 +1,158 @@
+/**
+ * accessModel — the pure (no React, no I/O) logic behind the service-account access dialog
+ * (Phase 4): turn the server's `assignable` set + an existing account into picker options, work out
+ * which of the agent's items are LOCKED (assigned by someone with more access), validate, and build
+ * a minimal PATCH. Kept separate so it is unit-tested with `node --test` (accessModel.test.mjs).
+ *
+ * The server is the authority (ADR-0029 ceiling): `assignable` is computed from the same ceiling the
+ * write enforces. An agent's existing role/node that is NOT assignable to the editor is shown checked
+ * + disabled and is NEVER sent — a non-root PATCH keeps it server-side (sending it would be a 403).
+ * Options carry `name` for display; `id` is only the value sent back (never rendered, ADR-0012).
+ */
+
+export const LOCKED_HINT = 'assigned by someone with more access';
+export const NO_ROLES_WARNING = 'This agent will be denied everything until it has a role.';
+export const SCOPE_REQUIRED = 'Choose at least one scope node.';
+
+/** Depth of each node by walking `parentId` inside the set (cycle-safe; unknown parent ⇒ top). */
+export function withDepth(nodes) {
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  const depthOf = (n) => {
+    let depth = 0;
+    const seen = new Set([n.id]);
+    let p = n.parentId;
+    while (p && byId.has(p) && !seen.has(p)) {
+      seen.add(p);
+      depth += 1;
+      p = byId.get(p).parentId;
+    }
+    return depth;
+  };
+  return nodes.map((n) => ({ id: n.id, name: n.name, depth: depthOf(n) }));
+}
+
+/** Items the agent holds that the editor cannot grant, labelled from the view (same order as ids). */
+function lockedItems(ids, labels, assignableIds) {
+  const out = [];
+  (ids || []).forEach((id, i) => {
+    if (!assignableIds.has(id))
+      out.push({ id, name: (labels && labels[i]) || 'Unnamed', depth: 0, locked: true });
+  });
+  return out;
+}
+
+/**
+ * Build the picker model. `account` is null for create.
+ *  - create: no roles ticked; every assignable scope node ticked ("defaults to everything you can reach").
+ *  - edit:   the agent's assignable items ticked; its non-assignable items appended as locked.
+ */
+export function buildAccessModel(assignable, account) {
+  const roles = (assignable && assignable.roles) || [];
+  const nodes = (assignable && assignable.scopeNodes) || [];
+  const roleIds = new Set(roles.map((r) => r.id));
+  const nodeIds = new Set(nodes.map((n) => n.id));
+
+  const roleOptions = roles.map((r) => ({ id: r.id, name: r.name, depth: 0 }));
+  const scopeOptions = withDepth(nodes);
+
+  if (!account) {
+    return {
+      roleOptions,
+      scopeOptions,
+      initialRoles: [],
+      initialScope: nodes.map((n) => n.id),
+    };
+  }
+  const lockedRoles = lockedItems(account.roleIds, account.roleLabels, roleIds);
+  const lockedScope = lockedItems(account.scopeSubtreeNodeIds, account.scopeLabels, nodeIds);
+  return {
+    roleOptions: [...roleOptions, ...lockedRoles],
+    scopeOptions: [...scopeOptions, ...lockedScope],
+    initialRoles: (account.roleIds || []).filter((id) => roleIds.has(id)),
+    initialScope: (account.scopeSubtreeNodeIds || []).filter((id) => nodeIds.has(id)),
+  };
+}
+
+/** Number of locked options (always held by the agent, never sent). */
+export function lockedCount(options) {
+  return options.filter((o) => o.locked).length;
+}
+
+/** Order-insensitive equality of two id lists. */
+export function sameIds(a, b) {
+  const sa = new Set(a);
+  const sb = new Set(b);
+  if (sa.size !== sb.size) return false;
+  for (const x of sa) if (!sb.has(x)) return false;
+  return true;
+}
+
+/**
+ * Field errors for the form (empty object ⇒ valid). When the scope will be sent (`requireScope`,
+ * default true) it needs ≥1 node — the server rejects an empty scope on edit with a 400.
+ */
+export function validateAccess({ label, scope, requireScope = true }) {
+  const errors = {};
+  if (!label || !label.trim()) errors.label = 'Give the service account a name.';
+  if (requireScope && (!scope || scope.length === 0)) errors.scope = SCOPE_REQUIRED;
+  return errors;
+}
+
+/** Does the agent end up with no role at all (ticked + locked)? → show the non-blocking warning. */
+export function hasNoRoles(roles, roleOptions) {
+  return roles.length === 0 && lockedCount(roleOptions) === 0;
+}
+
+/** Create body: always sends roles + ≥1 scope node (only assignable ids — never locked ones). */
+export function createBody({ label, roles, scope }) {
+  return { label: label.trim(), roleIds: [...roles], scopeSubtreeNodeIds: [...scope] };
+}
+
+/**
+ * Minimal PATCH for an edit: only the fields that changed. `roles` / `scope` hold assignable ids
+ * only (locked items are preserved by the server). Returns `{}` when nothing changed.
+ */
+export function editPatch({ account, label, roles, scope, initialRoles, initialScope }) {
+  const patch = {};
+  const nextLabel = label.trim();
+  if (nextLabel !== account.label) patch.label = nextLabel;
+  if (!sameIds(roles, initialRoles)) patch.roleIds = [...roles];
+  if (!sameIds(scope, initialScope)) patch.scopeSubtreeNodeIds = [...scope];
+  return patch;
+}
+
+/** Route a 400 server message to the field it is about (else the form-level error). */
+export function fieldOfServerError(message) {
+  const m = (message || '').toLowerCase();
+  if (m.includes('scope')) return 'scope';
+  if (m.includes('label') || m.includes('name')) return 'label';
+  return null;
+}
+
+/** First `max` names + a "+N" overflow count, for the row badges. */
+export function summarizeNames(names, max = 3) {
+  const list = names || [];
+  return { shown: list.slice(0, max), more: Math.max(0, list.length - max) };
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Key expiry choices for issue/rotate. The server REQUIRES a choice (ADR-0033 §4): a future
+ * `expiresAtMs`, or an explicit `neverExpires: true` — a non-expiring key is never the default.
+ */
+export const KEY_EXPIRY_CHOICES = [
+  { value: '30', label: '30 days' },
+  { value: '90', label: '90 days' },
+  { value: '365', label: '1 year' },
+  { value: 'never', label: 'Never expires (not recommended)' },
+];
+export const DEFAULT_KEY_EXPIRY = '90';
+
+/** The issue/rotate request body for a choice; an unknown choice uses the default. */
+export function keyExpiryRequest(choice, nowMs = Date.now()) {
+  if (choice === 'never') return { neverExpires: true };
+  const known = KEY_EXPIRY_CHOICES.some((c) => c.value === choice && c.value !== 'never');
+  const days = Number(known ? choice : DEFAULT_KEY_EXPIRY);
+  return { expiresAtMs: nowMs + days * DAY_MS };
+}

package/template/frontend/src/pages/service-accounts/accessModel.test.mjs

@@ -0,0 +1,189 @@
+// accessModel.test.mjs — Phase 4: the service-account access dialog's pure logic (picker
+// options, locked items, validation, minimal PATCH). No React/DOM; runs under Node's built-in
+// runner with zero dependencies:
+//
+//   node --test src/pages/service-accounts/accessModel.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  withDepth,
+  buildAccessModel,
+  lockedCount,
+  sameIds,
+  validateAccess,
+  hasNoRoles,
+  createBody,
+  editPatch,
+  fieldOfServerError,
+  summarizeNames,
+  SCOPE_REQUIRED,
+  KEY_EXPIRY_CHOICES,
+  DEFAULT_KEY_EXPIRY,
+  keyExpiryRequest,
+} from './accessModel.js';
+
+const ASSIGNABLE = {
+  roles: [
+    { id: 'r-ingest', name: 'Ingest' },
+    { id: 'r-audit', name: 'Auditor' },
+  ],
+  scopeNodes: [
+    { id: 'n-acme', name: 'Acme', parentId: null },
+    { id: 'n-east', name: 'Acme East', parentId: 'n-acme' },
+    { id: 'n-east-1', name: 'East 1', parentId: 'n-east' },
+  ],
+};
+
+const ACCOUNT = {
+  id: 'sa-1',
+  label: 'Ingest Bot',
+  roleIds: ['r-ingest', 'r-finance'],
+  roleLabels: ['Ingest', 'Finance Admin'],
+  scopeSubtreeNodeIds: ['n-east', 'n-beta'],
+  scopeLabels: ['Acme East', 'Beta'],
+};
+
+describe('withDepth', () => {
+  test('indents by parent chain inside the set', () => {
+    assert.deepEqual(
+      withDepth(ASSIGNABLE.scopeNodes).map((n) => n.depth),
+      [0, 1, 2],
+    );
+  });
+  test('a parent outside the set, or a cycle, does not loop or over-indent', () => {
+    const d = withDepth([
+      { id: 'a', name: 'A', parentId: 'b' },
+      { id: 'b', name: 'B', parentId: 'a' },
+      { id: 'c', name: 'C', parentId: 'zzz' },
+    ]);
+    assert.equal(d.find((n) => n.id === 'c').depth, 0);
+    assert.ok(d.every((n) => n.depth <= 1));
+  });
+});
+
+describe('buildAccessModel', () => {
+  test('create: no roles ticked, every reachable node ticked, nothing locked', () => {
+    const m = buildAccessModel(ASSIGNABLE, null);
+    assert.deepEqual(m.initialRoles, []);
+    assert.deepEqual(m.initialScope, ['n-acme', 'n-east', 'n-east-1']);
+    assert.equal(lockedCount(m.roleOptions) + lockedCount(m.scopeOptions), 0);
+  });
+
+  test('edit: assignable items ticked; out-of-ceiling items appended LOCKED with their names', () => {
+    const m = buildAccessModel(ASSIGNABLE, ACCOUNT);
+    assert.deepEqual(m.initialRoles, ['r-ingest']);
+    assert.deepEqual(m.initialScope, ['n-east']);
+    const lockedRole = m.roleOptions.find((o) => o.locked);
+    assert.deepEqual(lockedRole, {
+      id: 'r-finance',
+      name: 'Finance Admin',
+      depth: 0,
+      locked: true,
+    });
+    const lockedNode = m.scopeOptions.find((o) => o.locked);
+    assert.equal(lockedNode.name, 'Beta');
+  });
+
+  test('edit by root (everything assignable): nothing locked', () => {
+    const all = {
+      roles: [...ASSIGNABLE.roles, { id: 'r-finance', name: 'Finance Admin' }],
+      scopeNodes: [...ASSIGNABLE.scopeNodes, { id: 'n-beta', name: 'Beta', parentId: null }],
+    };
+    const m = buildAccessModel(all, ACCOUNT);
+    assert.equal(lockedCount(m.roleOptions) + lockedCount(m.scopeOptions), 0);
+    assert.deepEqual(m.initialRoles.sort(), ['r-finance', 'r-ingest']);
+  });
+});
+
+describe('validation + warnings', () => {
+  test('a name and at least one scope node are required', () => {
+    assert.deepEqual(validateAccess({ label: ' ', scope: [] }), {
+      label: 'Give the service account a name.',
+      scope: SCOPE_REQUIRED,
+    });
+    assert.deepEqual(validateAccess({ label: 'Bot', scope: ['n-acme'] }), {});
+  });
+  test('an unsent (unchanged) scope is not validated — rename of an all-locked agent still works', () => {
+    assert.deepEqual(validateAccess({ label: 'Bot', scope: [], requireScope: false }), {});
+  });
+  test('no-roles warning only when nothing is ticked AND nothing is locked', () => {
+    const create = buildAccessModel(ASSIGNABLE, null);
+    assert.equal(hasNoRoles([], create.roleOptions), true);
+    const edit = buildAccessModel(ASSIGNABLE, ACCOUNT);
+    assert.equal(hasNoRoles([], edit.roleOptions), false); // the locked role still applies
+  });
+});
+
+describe('request bodies never carry locked items', () => {
+  test('createBody sends trimmed name + roles + scope', () => {
+    assert.deepEqual(createBody({ label: ' Bot ', roles: ['r-ingest'], scope: ['n-acme'] }), {
+      label: 'Bot',
+      roleIds: ['r-ingest'],
+      scopeSubtreeNodeIds: ['n-acme'],
+    });
+  });
+
+  test('editPatch: unchanged → {}; only changed fields are sent; locked ids never appear', () => {
+    const m = buildAccessModel(ASSIGNABLE, ACCOUNT);
+    const base = { account: ACCOUNT, initialRoles: m.initialRoles, initialScope: m.initialScope };
+    assert.deepEqual(
+      editPatch({ ...base, label: 'Ingest Bot', roles: ['r-ingest'], scope: ['n-east'] }),
+      {},
+    );
+    assert.deepEqual(
+      editPatch({ ...base, label: 'Renamed', roles: ['r-ingest'], scope: ['n-east'] }),
+      {
+        label: 'Renamed',
+      },
+    );
+    const p = editPatch({ ...base, label: 'Ingest Bot', roles: [], scope: ['n-east', 'n-acme'] });
+    assert.deepEqual(p, { roleIds: [], scopeSubtreeNodeIds: ['n-east', 'n-acme'] });
+    assert.ok(!JSON.stringify(p).includes('r-finance'));
+    assert.ok(!JSON.stringify(p).includes('n-beta'));
+  });
+
+  test('sameIds is order-insensitive', () => {
+    assert.equal(sameIds(['a', 'b'], ['b', 'a']), true);
+    assert.equal(sameIds(['a'], ['a', 'b']), false);
+  });
+});
+
+describe('misc', () => {
+  test('fieldOfServerError routes 400s to the right field', () => {
+    assert.equal(fieldOfServerError('choose at least one scope node'), 'scope');
+    assert.equal(fieldOfServerError('label cannot be empty'), 'label');
+    assert.equal(fieldOfServerError('no fields to update'), null);
+  });
+  test('summarizeNames: first 3 + overflow count', () => {
+    assert.deepEqual(summarizeNames(['a', 'b', 'c', 'd', 'e']), {
+      shown: ['a', 'b', 'c'],
+      more: 2,
+    });
+    assert.deepEqual(summarizeNames(undefined), { shown: [], more: 0 });
+  });
+});
+
+describe('key expiry (the server requires an expiry OR an explicit neverExpires)', () => {
+  const NOW = Date.UTC(2026, 0, 1);
+  const DAY = 24 * 60 * 60 * 1000;
+
+  test('every choice maps to exactly one of expiresAtMs (future) / neverExpires', () => {
+    for (const c of KEY_EXPIRY_CHOICES) {
+      const body = keyExpiryRequest(c.value, NOW);
+      const keys = Object.keys(body);
+      assert.equal(keys.length, 1, c.value);
+      if ('expiresAtMs' in body) assert.ok(body.expiresAtMs > NOW, c.value);
+      else assert.deepEqual(body, { neverExpires: true });
+    }
+  });
+
+  test('day choices land N days ahead; the default is a finite expiry', () => {
+    assert.deepEqual(keyExpiryRequest('30', NOW), { expiresAtMs: NOW + 30 * DAY });
+    assert.deepEqual(keyExpiryRequest('never', NOW), { neverExpires: true });
+    assert.ok('expiresAtMs' in keyExpiryRequest(DEFAULT_KEY_EXPIRY, NOW));
+  });
+
+  test('an unknown choice falls back to the default (never silently non-expiring)', () => {
+    assert.deepEqual(keyExpiryRequest('bogus', NOW), keyExpiryRequest(DEFAULT_KEY_EXPIRY, NOW));
+  });
+});

package/template/frontend/src/pages/users/MembershipCard.jsx

@@ -185,7 +185,9 @@ export default function MembershipCard({
             size="sm"
             onClick={onToggleActive}
             disabled={isActive || activating || saving}
-            title={isActive ? 'This is the active login company' : 'Make this the active login company'}
+            title={
+              isActive ? 'This is the active login company' : 'Make this the active login company'
+            }
           >
             {activating ? (
               <Loader2 className="size-4 animate-spin" />

package/template/frontend/src/pages/users/PostingRow.jsx

@@ -115,20 +115,14 @@ export default function PostingRow({
 
   // Department / Branch: small, per-company catalogs (passed in). The SAME control in
   // client-filter mode — `fetchPage` returns the whole list once; the panel filters locally.
-  const fetchDepartments = useCallback(
-    async () => {
-      const options = (departments || []).map((d) => ({ value: d.uuid, label: d.name }));
-      return { options, total: options.length, page: 1 };
-    },
-    [departments],
-  );
-  const fetchBranches = useCallback(
-    async () => {
-      const options = (branches || []).map((b) => ({ value: b.uuid, label: b.name }));
-      return { options, total: options.length, page: 1 };
-    },
-    [branches],
-  );
+  const fetchDepartments = useCallback(async () => {
+    const options = (departments || []).map((d) => ({ value: d.uuid, label: d.name }));
+    return { options, total: options.length, page: 1 };
+  }, [departments]);
+  const fetchBranches = useCallback(async () => {
+    const options = (branches || []).map((b) => ({ value: b.uuid, label: b.name }));
+    return { options, total: options.length, page: 1 };
+  }, [branches]);
 
   // Shared field controls — reused by both the desktop row and the mobile card.
   const roleSelect = (

package/template/frontend/src/pages/users/UsersPage.jsx

@@ -144,19 +144,13 @@ export default function UsersPage() {
     load();
   }, [load]);
 
-  const onSearchChange = useCallback(
-    (search) => setQuery((q) => ({ ...q, search, page: 1 })),
-    [],
-  );
+  const onSearchChange = useCallback((search) => setQuery((q) => ({ ...q, search, page: 1 })), []);
   const onSortChange = useCallback(
     (sortBy, sortOrder) => setQuery((q) => ({ ...q, sortBy, sortOrder })),
     [],
   );
   const onPageChange = useCallback((page) => setQuery((q) => ({ ...q, page })), []);
-  const onLimitChange = useCallback(
-    (limit) => setQuery((q) => ({ ...q, limit, page: 1 })),
-    [],
-  );
+  const onLimitChange = useCallback((limit) => setQuery((q) => ({ ...q, limit, page: 1 })), []);
 
   const onConfirmDelete = async () => {
     if (!deleteTarget) return;
@@ -219,7 +213,11 @@ export default function UsersPage() {
 
       <ConfirmDialog
         open={!!deleteTarget}
-        title={deleteTarget ? `Delete “${deleteTarget.fields?.username || 'this user'}”?` : 'Delete user?'}
+        title={
+          deleteTarget
+            ? `Delete “${deleteTarget.fields?.username || 'this user'}”?`
+            : 'Delete user?'
+        }
         message="This permanently removes the user and all their company memberships. This cannot be undone."
         confirmLabel="Delete"
         destructive

package/template/frontend/src/platform/httpClient.js

@@ -3,6 +3,11 @@
  * contract. Uses the browser `fetch`, same-origin `/api` (proxied by Vite to the
  * server's /auth/* routes). A mobile app provides its OWN adapter (RN fetch + its
  * base URL) implementing the same shape; the shared logic is identical for both.
+ *
+ * This is the RAW transport: it does not refresh tokens. AuthContext wraps it with
+ * @astram/frontend-core's `createRefreshingHttp` (single-flight refresh on a 401, one retry,
+ * cross-tab lock) and hands only the wrapped client to the services and the shield
+ * transport. Use the raw client directly only for the refresh call itself.
  */
 
 const BASE = '/api';

package/template/frontend/src/platform/sessionStore.js

@@ -2,28 +2,70 @@
  * The WEB session store — the platform half of @astram/frontend-core's SessionStore contract,
  * backed by localStorage. A mobile app provides its own (AsyncStorage). The shared
  * session helpers never touch storage directly; the app injects this.
+ *
+ * localStorage is shared by every tab of the app, so a token rotation or logout in one tab
+ * is visible to the others: `createRefreshingHttp` re-reads it inside its cross-tab lock,
+ * and `subscribe` turns the browser's `storage` event (fired in the OTHER tabs) into a
+ * session-change callback for AuthContext.
+ *
+ * Token storage note (D11): the refresh token sits in localStorage, readable by any script
+ * on the origin, which is why index.html ships a strict Content-Security-Policy. Moving the
+ * refresh token to an HttpOnly cookie is a planned follow-up ADR.
  */
 
-const KEY = 'app-session';
+export const SESSION_STORAGE_KEY = 'app-session';
+
+/**
+ * @param {{ storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>,
+ *           events?: Pick<EventTarget, 'addEventListener' | 'removeEventListener'> }} [deps]
+ *   Injected for tests; default to the browser's `localStorage` and `window`.
+ * @returns {import('@astram/frontend-core').SessionStore & {
+ *   subscribe: (listener: (state: object | null) => void) => () => void }}
+ */
+export function createWebSessionStore(deps = {}) {
+  const storage = () => deps.storage ?? globalThis.localStorage;
+  const events = () => deps.events ?? globalThis.window;
+
+  const load = () => {
+    try {
+      const raw = storage().getItem(SESSION_STORAGE_KEY);
+      return raw ? JSON.parse(raw) : null;
+    } catch {
+      return null;
+    }
+  };
 
-/** @returns {import('@astram/frontend-core').SessionStore} */
-export function createWebSessionStore() {
   return {
-    load() {
-      try {
-        const raw = localStorage.getItem(KEY);
-        return raw ? JSON.parse(raw) : null;
-      } catch {
-        return null;
-      }
-    },
+    load,
     save(state) {
       try {
-        if (state) localStorage.setItem(KEY, JSON.stringify(state));
-        else localStorage.removeItem(KEY);
+        if (state) storage().setItem(SESSION_STORAGE_KEY, JSON.stringify(state));
+        else storage().removeItem(SESSION_STORAGE_KEY);
       } catch {
         /* storage unavailable — session stays in memory only */
       }
     },
+    /**
+     * Call `listener(state | null)` when ANOTHER tab changes the session (rotation, logout,
+     * a different sign-in). Returns an unsubscribe function.
+     */
+    subscribe(listener) {
+      const target = events();
+      if (!target || typeof target.addEventListener !== 'function') return () => {};
+      const onStorage = (event) => {
+        // `key === null` means the other tab called localStorage.clear().
+        if (event.key !== SESSION_STORAGE_KEY && event.key !== null) return;
+        let area;
+        try {
+          area = storage();
+        } catch {
+          return;
+        }
+        if (event.storageArea && event.storageArea !== area) return;
+        listener(load());
+      };
+      target.addEventListener('storage', onStorage);
+      return () => target.removeEventListener('storage', onStorage);
+    },
   };
 }

package/template/frontend/src/platform/sessionStore.test.mjs

@@ -0,0 +1,89 @@
+// sessionStore.test.mjs — the web session store's cross-tab half (#12): a logout or a
+// token rotation in one tab must reach the others through the `storage` event.
+//
+//   node --test src/platform/sessionStore.test.mjs
+//
+// Storage and the event target are injected, so this runs under plain Node.
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { createWebSessionStore, SESSION_STORAGE_KEY } from './sessionStore.js';
+
+function memoryStorage() {
+  const m = new Map();
+  return {
+    getItem: (k) => (m.has(k) ? m.get(k) : null),
+    setItem: (k, v) => m.set(k, String(v)),
+    removeItem: (k) => m.delete(k),
+  };
+}
+
+function eventTarget() {
+  const listeners = new Set();
+  return {
+    addEventListener: (type, fn) => type === 'storage' && listeners.add(fn),
+    removeEventListener: (type, fn) => type === 'storage' && listeners.delete(fn),
+    fire: (event) => [...listeners].forEach((fn) => fn(event)),
+    get size() {
+      return listeners.size;
+    },
+  };
+}
+
+const fake = (label) => `fake-${label}`;
+const STATE = {
+  session: { sessionId: 's1' },
+  tokens: { accessToken: fake('a2'), refreshToken: fake('r2') },
+};
+
+describe('createWebSessionStore.subscribe — cross-tab session changes', () => {
+  test('another tab rotated the tokens → listener gets the new state', () => {
+    const storage = memoryStorage();
+    const events = eventTarget();
+    const store = createWebSessionStore({ storage, events });
+    const seen = [];
+    store.subscribe((s) => seen.push(s));
+
+    storage.setItem(SESSION_STORAGE_KEY, JSON.stringify(STATE)); // the other tab's write
+    events.fire({ key: SESSION_STORAGE_KEY, storageArea: storage });
+
+    assert.deepEqual(seen, [STATE]);
+  });
+
+  test('another tab logged out (key removed, or storage cleared) → listener gets null', () => {
+    const storage = memoryStorage();
+    const events = eventTarget();
+    const store = createWebSessionStore({ storage, events });
+    const seen = [];
+    store.subscribe((s) => seen.push(s));
+
+    events.fire({ key: SESSION_STORAGE_KEY, storageArea: storage });
+    events.fire({ key: null, storageArea: storage }); // localStorage.clear()
+
+    assert.deepEqual(seen, [null, null]);
+  });
+
+  test('unrelated keys and other storage areas are ignored; unsubscribe detaches', () => {
+    const storage = memoryStorage();
+    const events = eventTarget();
+    const store = createWebSessionStore({ storage, events });
+    const seen = [];
+    const off = store.subscribe((s) => seen.push(s));
+
+    events.fire({ key: 'app-return-path', storageArea: storage });
+    events.fire({ key: SESSION_STORAGE_KEY, storageArea: memoryStorage() }); // sessionStorage
+    assert.deepEqual(seen, []);
+
+    off();
+    assert.equal(events.size, 0);
+  });
+
+  test('load/save round-trip through the injected storage', () => {
+    const storage = memoryStorage();
+    const store = createWebSessionStore({ storage, events: eventTarget() });
+    assert.equal(store.load(), null);
+    store.save(STATE);
+    assert.deepEqual(store.load(), STATE);
+    store.save(null);
+    assert.equal(store.load(), null);
+  });
+});

package/template/frontend/src/platform/shieldTransport.js

@@ -22,6 +22,12 @@
  *     deny-everything projection past a token refresh. Treated as TRANSIENT (throw), so
  *     the engine holds its last-good/empty projection and the NEXT session-established
  *     fetch (post-refresh/re-login) supersedes it, rather than baking in a deny.
+ *     AuthContext hands this transport the REFRESHING http client (`createRefreshingHttp`,
+ *     #12), so an expired access token is refreshed and the call retried BEFORE a status
+ *     reaches here: a 401 seen here means the refresh itself failed (the session is being
+ *     cleared → login) or the session was replaced, and a refresh outage arrives as a 503.
+ *     Never build this transport over the raw client: a 401 would then be retried forever
+ *     as "transient" instead of refreshing.
  *   - a real 403 (or any other non-5xx !ok)  → TERMINAL deny → return an EMPTY projection
  *     `{ principalId:'', facts:[], projectedAt: Date.now() }` (deny-all).
  *   - 200 with a body                        → return `r.data` (the projection) AS-IS.