@1agh/maude 0.53.1 → 0.54.0

package/apps/studio/session-scope.ts

@@ -0,0 +1,101 @@
+// Whose runtime state is this? — Cloud Phase 27 D3.
+//
+// `_active.json` (which canvas is open, what is selected) and
+// `_canvas-state/<slug>.view.json` (the camera) are PER-MACHINE singletons by
+// design — DDR-115 made them runtime state precisely so they would never be
+// versioned or shared. On a desktop that is exactly right: one machine, one
+// person, one place in the project.
+//
+// A cell breaks the assumption without changing a line of that code. One studio
+// process serves an owner and a viewer at the same time, so both write the same
+// singleton: your colleague opens a different canvas and YOUR tab switches; they
+// pan and your camera moves. Silently, and it reads as flakiness rather than as
+// two people sharing one file.
+//
+// The proxy already knows who each request is — it injects `x-maude-session`, a
+// stable, non-identifying hash of (project, member) minted at sign-in. What was
+// missing is the studio side: a way for code deep in the path helpers to ask
+// "whose request am I on?" without every function between here and there
+// growing a parameter it does not otherwise care about.
+//
+// That is what `AsyncLocalStorage` is for, and this is the shape it fits: one
+// value, established once at the edge (a request handler, a socket message),
+// read at the leaves. The alternative — threading a `session` argument through
+// `getCanvasMeta` → `readCanvasViewRaw` → `canvasViewPath` and a dozen siblings
+// — spreads a cloud concern across every signature in `api.ts`, where it would
+// be forgotten exactly once and reintroduce the bug.
+//
+// OUTSIDE A CELL THIS IS INERT. No header ⇒ no key ⇒ every path resolves byte
+// for byte the way it did before, which is the property the tests assert first.
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+/** The header the proxy vouches. Never trusted from a client — the proxy strips
+ *  every `x-maude-*` before injecting its own (studio-proxy.mjs property 2). */
+export const SESSION_HEADER = 'x-maude-session';
+
+const storage = new AsyncLocalStorage<string>();
+
+/**
+ * Keep a session key to what it may safely become: a path segment.
+ *
+ * The value is minted by the proxy as a 16-char hash, so this rejects rather
+ * than sanitizes — a key that does not look like one is not a key we should be
+ * guessing the intent of, and falling back to the shared singleton is the same
+ * behaviour a desktop already has.
+ */
+export function normalizeSessionKey(raw: string | null | undefined): string {
+  if (!raw) return '';
+  return /^[a-zA-Z0-9_-]{1,64}$/.test(raw) ? raw : '';
+}
+
+/** Read the session key off a request. */
+export function sessionFromRequest(req: { headers: { get(name: string): string | null } }): string {
+  try {
+    return normalizeSessionKey(req.headers.get(SESSION_HEADER));
+  } catch {
+    return '';
+  }
+}
+
+/** Run `fn` with `key` as the ambient session. An empty key is the shared
+ *  singleton — i.e. exactly today's behaviour, which is why the desktop path
+ *  does not need to know this module exists. */
+export function runInSession<T>(key: string, fn: () => T): T {
+  const normalized = normalizeSessionKey(key);
+  return normalized ? storage.run(normalized, fn) : fn();
+}
+
+/** Whose request are we on? `''` = nobody in particular (desktop, CLI, tests). */
+export function currentSession(): string {
+  return storage.getStore() ?? '';
+}
+
+/**
+ * Insert the session segment into a runtime-state path.
+ *
+ * `_canvas-state/<slug>.view.json` becomes
+ * `_canvas-state/<session>/<slug>.view.json`, and nothing at all happens
+ * without a session. A DIRECTORY rather than a filename suffix so the whole of
+ * one member's runtime state is one subtree — deletable, ignorable, and obvious
+ * to a human looking at the disk.
+ */
+export function sessionDir(base: string, key = currentSession()): string {
+  return key ? `${base}/${key}` : base;
+}
+
+/**
+ * The same idea for a single FILE — `_active.json` → `_active.<session>.json`.
+ *
+ * A suffix rather than a subdirectory here because `_active.json` is a named
+ * runtime file the gitignore, the runtime-state taxonomy (DDR-115) and
+ * `isMaudeRuntimeState` all match by name, and a sibling with the same stem
+ * keeps every one of those matchers correct without a fourth list to update.
+ */
+export function sessionFile(absPath: string, key = currentSession()): string {
+  if (!key) return absPath;
+  const dot = absPath.lastIndexOf('.');
+  const slash = Math.max(absPath.lastIndexOf('/'), absPath.lastIndexOf('\\'));
+  if (dot <= slash) return `${absPath}.${key}`;
+  return `${absPath.slice(0, dot)}.${key}${absPath.slice(dot)}`;
+}

package/apps/studio/sync/autocommit.ts

@@ -27,6 +27,8 @@
 
 import path from 'node:path';
 
+import { withRepoLock } from '../git/repo-lock.ts';
+
 /** How long the tree must be quiet before a commit fires. */
 const DEFAULT_DEBOUNCE_MS = 3000;
 
@@ -173,7 +175,11 @@ export function createAutoCommit(opts: AutoCommitOptions): AutoCommit {
     if (timer) clearTimeout(timer);
     timer = setTimeout(() => {
       timer = null;
-      void flush();
+      // `.catch` and not just `void`: a discarded rejection here is an
+      // unhandled-rejection process exit, and this timer fires unattended.
+      flush().catch((err) => {
+        log.warn?.(`[autocommit] flush failed: ${err instanceof Error ? err.message : err}`);
+      });
     }, debounceMs);
   }
 
@@ -192,51 +198,34 @@ export function createAutoCommit(opts: AutoCommitOptions): AutoCommit {
 
     inFlight = (async (): Promise<CommitOutcome> => {
       try {
-        // Stage ONLY what changed. `git add -A` in a workspace would sweep in
-        // whatever else is in the tree — including files a future feature drops
-        // there — and the cell must never commit something it wasn't told about.
-        const add = await run(['add', '--', ...files], { cwd: repoRoot });
-        if (add.code !== 0) {
-          log.warn?.(`[autocommit] git add failed: ${add.stderr.trim()}`);
-          return { ok: false, reason: 'git-failed', detail: add.stderr.trim(), files };
-        }
-
-        // Nothing staged ⇒ the write was a no-op (an echo, or identical bytes).
-        // Not an error, and committing an empty change would be noise.
-        const staged = await run(['diff', '--cached', '--name-only'], { cwd: repoRoot });
-        if (staged.code === 0 && staged.stdout.trim() === '') {
-          return { ok: false, reason: 'nothing-to-commit', files };
-        }
-
-        const commit = await run(
-          [
-            '-c',
-            `user.name=${bot.name}`,
-            '-c',
-            `user.email=${bot.email}`,
-            'commit',
-            '--author',
-            formatAuthor(who),
-            '--only',
-            '--message',
-            commitMessage(files, who),
-            '--',
-            ...files,
-          ],
-          { cwd: repoRoot }
-        );
-        if (commit.code !== 0) {
-          log.warn?.(`[autocommit] git commit failed: ${commit.stderr.trim()}`);
-          // The bytes are on disk. Re-queue so the next quiescence retries
-          // rather than silently dropping the change from history.
-          for (const f of files) touched.add(f);
-          return { ok: false, reason: 'git-failed', detail: commit.stderr.trim(), files };
-        }
-
-        const head = await run(['rev-parse', 'HEAD'], { cwd: repoRoot });
-        const sha = head.stdout.trim();
-        log.log?.(`[autocommit] ${sha.slice(0, 8)} ${files.length} file(s) by ${who.name}`);
-        return { ok: true, sha, files, author: who };
+        // Cloud Phase 27 D2 — HOLD THE LOCK ACROSS THE WHOLE SEQUENCE, not per
+        // git invocation. `add` and `commit` are two invocations, and the thing
+        // that must not land between them is another process's `checkout` or
+        // `commit`: that is the half-staged commit the phase's preserved
+        // dissent names. `index.lock` cannot express this — it is released the
+        // moment `add` returns.
+        //
+        // The `inFlight` guard above is the in-process half of the same rule
+        // and stays: this lock is CROSS-process, and one AutoCommit racing
+        // itself would still be a bug.
+        return await withRepoLock(repoRoot, 'autocommit', () => commitCycle(files, who));
+      } catch (err) {
+        // A LOCK TIMEOUT MUST NOT LOSE THE QUEUE, AND MUST NOT KILL THE PROCESS.
+        //
+        // `withRepoLock` THROWS when it cannot acquire, and `touched` was
+        // already cleared above — so without this catch a contended autosave
+        // dropped its file list silently (the bytes stay on disk, uncommitted,
+        // with nothing to retry them) and rejected a promise the debounce timer
+        // discards, which on Node ≥15 takes the process down with it. The
+        // trigger is ordinary now, not pathological: post-D2 `pull` and
+        // `checkout` hold this lock across a NETWORK operation.
+        //
+        // Re-queue and report, exactly like a failed `git commit` does. The
+        // next quiescence tries again.
+        for (const f of files) touched.add(f);
+        const detail = err instanceof Error ? err.message : String(err);
+        log.warn?.(`[autocommit] could not take the repo lock: ${detail}`);
+        return { ok: false, reason: 'git-failed', detail, files };
       } finally {
         inFlight = null;
       }
@@ -245,6 +234,55 @@ export function createAutoCommit(opts: AutoCommitOptions): AutoCommit {
     return inFlight;
   }
 
+  /** The critical section: stage exactly these files, commit them, report. */
+  async function commitCycle(files: string[], who: EditAttribution): Promise<CommitOutcome> {
+    // Stage ONLY what changed. `git add -A` in a workspace would sweep in
+    // whatever else is in the tree — including files a future feature drops
+    // there — and the cell must never commit something it wasn't told about.
+    const add = await run(['add', '--', ...files], { cwd: repoRoot });
+    if (add.code !== 0) {
+      log.warn?.(`[autocommit] git add failed: ${add.stderr.trim()}`);
+      return { ok: false, reason: 'git-failed', detail: add.stderr.trim(), files };
+    }
+
+    // Nothing staged ⇒ the write was a no-op (an echo, or identical bytes).
+    // Not an error, and committing an empty change would be noise.
+    const staged = await run(['diff', '--cached', '--name-only'], { cwd: repoRoot });
+    if (staged.code === 0 && staged.stdout.trim() === '') {
+      return { ok: false, reason: 'nothing-to-commit', files };
+    }
+
+    const commit = await run(
+      [
+        '-c',
+        `user.name=${bot.name}`,
+        '-c',
+        `user.email=${bot.email}`,
+        'commit',
+        '--author',
+        formatAuthor(who),
+        '--only',
+        '--message',
+        commitMessage(files, who),
+        '--',
+        ...files,
+      ],
+      { cwd: repoRoot }
+    );
+    if (commit.code !== 0) {
+      log.warn?.(`[autocommit] git commit failed: ${commit.stderr.trim()}`);
+      // The bytes are on disk. Re-queue so the next quiescence retries
+      // rather than silently dropping the change from history.
+      for (const f of files) touched.add(f);
+      return { ok: false, reason: 'git-failed', detail: commit.stderr.trim(), files };
+    }
+
+    const head = await run(['rev-parse', 'HEAD'], { cwd: repoRoot });
+    const sha = head.stdout.trim();
+    log.log?.(`[autocommit] ${sha.slice(0, 8)} ${files.length} file(s) by ${who.name}`);
+    return { ok: true, sha, files, author: who };
+  }
+
   return {
     note,
     flush,

package/apps/studio/sync/index.ts

@@ -222,6 +222,26 @@ export function createSyncRuntime(
   if (!linked) return null;
   const linkedHub = linked;
 
+  // A CELL'S HISTORY BELONGS TO THE CELL — Cloud Phase 27 D2.
+  //
+  // `.design/config.json` is the TENANT's file, versioned in their repo, and
+  // `linkedHub` is whatever hub their desktop was linked to when they committed
+  // it. Honouring that inside a cell would do two things nobody asked for: dial
+  // OUT from the cell to a third-party hub carrying the project's canvases, and
+  // start a SECOND autocommit over the working tree the hub is already
+  // committing — the exact duplication this phase exists to delete.
+  //
+  // Today this is unreachable by accident: the token lookup below reads
+  // `~/.config/maude/hubs.json`, which does not exist in a cell (HOME=/tmp), so
+  // it returns null a few lines further down. An accident is not an invariant,
+  // and the fix for "it happens to be fine" is to say so out loud.
+  if (process.env.MAUDE_WORKSPACE_MODE === '1') {
+    console.warn(
+      `[sync] ignoring linkedHub ${linkedHub.url} — in a workspace cell the hub owns history and sync. (DDR-209 / Phase 27 D2)`
+    );
+    return null;
+  }
+
   // DDR-054 §2a — CI environment gate. Closes the supply-chain side-door
   // where a future CI workflow runs `maude design serve` and a PR-controlled
   // linkedHub.url silently grants a remote actor write access in an

package/apps/studio/test/canvas-build-sandbox.test.ts

@@ -0,0 +1,69 @@
+// Cloud Phase 27 — the sandbox child's environment.
+//
+// Diagnosed against a real cell: the canvas module 422'd with "Cannot find
+// native binding" while running the identical worker command by hand with a
+// clean environment worked. The difference was one inherited variable.
+
+import { describe, expect, test } from 'bun:test';
+
+import { workerEnv } from '../canvas-build-sandbox.ts';
+
+describe('workerEnv', () => {
+  test('a compiled binary’s VIRTUAL binding path is not handed to a child', () => {
+    const env = workerEnv({
+      PATH: '/bin',
+      NAPI_RS_NATIVE_LIBRARY_PATH: '/$bunfs/root/parser.linux-arm64-gnu.node',
+    } as NodeJS.ProcessEnv);
+    expect(env.NAPI_RS_NATIVE_LIBRARY_PATH).toBeUndefined();
+  });
+
+  test('a REAL binding path still is', () => {
+    const env = workerEnv({
+      PATH: '/bin',
+      NAPI_RS_NATIVE_LIBRARY_PATH: '/maude/node_modules/@oxc-parser/binding-linux-arm64-gnu',
+    } as NodeJS.ProcessEnv);
+    expect(env.NAPI_RS_NATIVE_LIBRARY_PATH).toBe(
+      '/maude/node_modules/@oxc-parser/binding-linux-arm64-gnu'
+    );
+  });
+
+  test('the child environment carries no secret — it parses tenant source', () => {
+    const env = workerEnv({
+      PATH: '/bin',
+      HUB_SECRET: 'nope',
+      AWS_SECRET_ACCESS_KEY: 'also-nope',
+      MAUDE_PROJECT_TOKEN_KEY: 'definitely-nope',
+    } as NodeJS.ProcessEnv);
+    expect(env.HUB_SECRET).toBeUndefined();
+    expect(env.AWS_SECRET_ACCESS_KEY).toBeUndefined();
+    expect(env.MAUDE_PROJECT_TOKEN_KEY).toBeUndefined();
+  });
+});
+
+// Cloud Phase 27 B2 — content-addressed media is immutable; everything else
+// revalidates. `no-store` is right on a laptop and is a re-download of every
+// photograph on every pan over the internet.
+import { cacheControlFor } from '../http.ts';
+
+describe('cacheControlFor', () => {
+  test('a content-addressed name is immutable — the name IS the content', () => {
+    for (const p of ['/x/assets/deadbeef.png', '/a/b/0123456789abcdef.mp4']) {
+      expect(cacheControlFor(p).cacheControl).toBe('public, max-age=31536000, immutable');
+      expect(cacheControlFor(p).addEtag).toBe(false);
+    }
+  });
+
+  test('an AUTHORED name revalidates — a designer edits hero.png in place', () => {
+    for (const p of ['/x/assets/hero.png', '/x/system/ds/colors_and_type.css', '/x/logos.svg']) {
+      expect(cacheControlFor(p).cacheControl).toBe('no-cache');
+      expect(cacheControlFor(p).addEtag).toBe(true);
+    }
+  });
+
+  test('a name that merely LOOKS hex-ish is not treated as content-addressed', () => {
+    // `deadbee` is 7 chars; `deadbeefs` has a non-hex char. Getting either
+    // wrong caches a mutable file for a year.
+    expect(cacheControlFor('/x/deadbee.png').cacheControl).toBe('no-cache');
+    expect(cacheControlFor('/x/deadbeefs.png').cacheControl).toBe('no-cache');
+  });
+});

package/apps/studio/test/canvas-origin-gate.test.ts

@@ -36,6 +36,21 @@ describe('canvas-origin gate — A1/A2 traversal + privilege containment', () =>
       join(designRoot, 'ui', 'Gate.tsx'),
       'export default function G(){return <main/>}\n'
     );
+    // DDR-210 — RUNTIME STATE, AT DEPTH.
+    //
+    // The underscore rule narrowed from "any path segment" to "the first path
+    // segment", because a design system's `preview/_components.css` is
+    // versioned, shipped, and was 403ing. The narrowing is sound only while
+    // DDR-115's taxonomy stays first-segment — which it is today, and which
+    // nothing was asserting. `git/service.ts`'s `isMaudeRuntimeState` matches
+    // those names at ANY depth, so the two lists now encode different shapes:
+    // a future nested runtime dir would be correctly gitignored, correctly
+    // hidden from the Changes list, and SERVED TO THE UNTRUSTED CANVAS.
+    // These two files are the tripwire.
+    mkdirSync(join(designRoot, '_history', 'gate'), { recursive: true });
+    writeFileSync(join(designRoot, '_history', 'gate', 'snap.tsx'), 'export default 1\n');
+    mkdirSync(join(designRoot, 'system', 'ds', 'preview'), { recursive: true });
+    writeFileSync(join(designRoot, 'system', 'ds', 'preview', '_components.css'), '.a{}\n');
 
     const port = nextPort();
     const proc = await bootServer(root, port, { MAUDE_CANVAS_ORIGIN_SPLIT: '1' });
@@ -156,6 +171,11 @@ describe('canvas-origin gate — A1/A2 traversal + privilege containment', () =>
         '/_api/debug-bundle',
         '/_api/report',
         '/_api/report-fallback',
+        // …and the shell capture SPAWNS A PROCESS (screenshot.sh → a headless
+        // browser) and renders the whole project. Reachable from the canvas
+        // origin it would be a resource-exhaustion lever driven by untrusted
+        // canvas code, so it carries the same main-origin-only posture.
+        '/_api/shell-shot',
         // Stage F1 — the AssetPicker's asset-listing GET is a shell (main-origin)
         // concern; the untrusted canvas iframe must not enumerate project media.
         '/_api/assets',
@@ -267,6 +287,13 @@ describe('canvas-origin gate — A1/A2 traversal + privilege containment', () =>
       expect(await code('/_canvas-shell.html')).toBe(200);
       // A real .tsx canvas under designRoot transpiles + serves (200).
       expect(await code('/.design/ui/Gate.tsx')).toBe(200);
+      // DDR-210 — the two halves of the narrowed underscore rule, pinned.
+      // First-segment runtime state stays refused AT DEPTH…
+      expect(await code('/.design/_history/gate/snap.tsx')).toBe(403);
+      // …and a NESTED underscore that is versioned design-system content is
+      // served. This one is the reason the rule was narrowed: it 403'd, so
+      // every canvas in every project rendered without its component styles.
+      expect(await code('/.design/system/ds/preview/_components.css')).toBe(200);
       // Phase 23 — the capped image-upload route IS reachable from the canvas
       // origin (it must be — drag-drop/paste/picker run inside the iframe). A GET
       // returns 405 (method-not-allowed) which proves the route is REACHED via
@@ -304,3 +331,42 @@ describe('canvas-origin gate — A1/A2 traversal + privilege containment', () =>
     }
   });
 });
+
+describe('an SVG served from the canvas origin is not a scripting document', () => {
+  test('.svg carries an inert CSP; other static types are untouched', async () => {
+    // The canvas origin serves the TENANT's own SVGs. `image/svg+xml` is inert
+    // as an <img>, a CSS url() or a <use> target — none of those are browsing
+    // contexts — but navigate to one and it is a page, with <script> in it,
+    // running on this origin. Only the shell HTML ever got a CSP, so that was a
+    // stored-XSS primitive on a `*.<zone>` origin: step one of a three-link
+    // cross-tenant chain (an adversarial pass found it; DDR-210 names the other
+    // two links). `default-src 'none'; sandbox` costs the legitimate uses
+    // nothing, because the policy never applies to them.
+    const { root, designRoot } = makeSandbox();
+    mkdirSync(join(designRoot, 'system', 'ds', 'assets'), { recursive: true });
+    writeFileSync(
+      join(designRoot, 'system', 'ds', 'assets', 'mark.svg'),
+      '<svg xmlns="http://www.w3.org/2000/svg"><script>1</script></svg>\n'
+    );
+    writeFileSync(join(designRoot, 'system', 'ds', 'assets', 'tokens.css'), ':root{}\n');
+
+    const port = nextPort();
+    const proc = await bootServer(root, port, { MAUDE_CANVAS_ORIGIN_SPLIT: '1' });
+    try {
+      const canvas = await readCanvasOrigin(designRoot);
+      const head = async (p: string) =>
+        (await fetch(canvas + p, { signal: AbortSignal.timeout(2000) })).headers;
+
+      const svg = await head('/.design/system/ds/assets/mark.svg');
+      expect(svg.get('content-type')).toContain('image/svg+xml');
+      expect(svg.get('content-security-policy')).toBe("default-src 'none'; sandbox");
+
+      // …and only SVG. A stylesheet under a CSP that forbids everything is a
+      // stylesheet that does not apply.
+      const css = await head('/.design/system/ds/assets/tokens.css');
+      expect(css.get('content-security-policy')).toBeNull();
+    } finally {
+      killProc(proc);
+    }
+  });
+});

package/apps/studio/test/canvas-shell-base.test.ts

@@ -0,0 +1,107 @@
+// The canvas shell under a based origin — Cloud Phase 27 (DDR-209).
+//
+// The fleet's canvas origin puts the project in the PATH:
+// `canvas.<zone>/<project>/_canvas-shell.html`. Every URL the shell builds must
+// therefore hang off the path it was SERVED from, not off the origin root —
+// otherwise the browser asks for `canvas.<zone>/.design/…`, the data plane reads
+// `.design` as a project name, and every dynamic import fails with
+// "Failed to fetch dynamically imported module".
+//
+// Two mechanisms, because the shell has two kinds of URL and only one of them
+// can be built at runtime:
+//
+//   built by JS        → `withCap()` prefixes the derived base.
+//   the IMPORTMAP      → cannot be: it must be static and present before any
+//                        module loads, and the server cannot rewrite it either
+//                        (the data plane strips the project segment before the
+//                        request arrives, so only the browser knows the base).
+//                        Importmap addresses resolve against the DOCUMENT's base
+//                        URL, so `./` gets it for free.
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SHELL = readFileSync(
+  join(import.meta.dir, '..', '..', '..', 'plugins', 'design', 'templates', '_shell.html'),
+  'utf8'
+);
+
+/** The shell's own derivation, mirrored so the test breaks when it changes. */
+const baseOf = (pathname: string) => pathname.replace(/\/_canvas-shell(\.html)?$/, '');
+
+describe('the canvas shell hangs off the path it was served from', () => {
+  test('the base is derived from location, and is empty at the origin root', () => {
+    expect(baseOf('/alligators/_canvas-shell.html')).toBe('/alligators');
+    expect(baseOf('/alligators/_canvas-shell')).toBe('/alligators');
+    expect(baseOf('/_canvas-shell.html')).toBe('');
+    expect(baseOf('/_canvas-shell')).toBe('');
+    expect(SHELL).toContain("location.pathname.replace(/\\/_canvas-shell(\\.html)?$/, '')");
+  });
+
+  test('NO importmap entry is origin-absolute', () => {
+    // `"/_canvas-runtime/react.js"` resolves against the origin and drops the
+    // project. This is the one that cannot be fixed at runtime, so it is the one
+    // most worth pinning.
+    expect(SHELL).not.toContain('"/_canvas-runtime/');
+    expect(SHELL).toContain('"./_canvas-runtime/');
+  });
+
+  test('a relative importmap address resolves under the project, and at the root', () => {
+    // The actual browser rule, exercised rather than asserted.
+    expect(
+      new URL(
+        './_canvas-runtime/react.js',
+        'https://canvas.cloud.maude.sh/alligators/_canvas-shell.html?t=x'
+      ).href
+    ).toBe('https://canvas.cloud.maude.sh/alligators/_canvas-runtime/react.js');
+    expect(
+      new URL('./_canvas-runtime/react.js', 'http://localhost:4399/_canvas-shell.html').href
+    ).toBe('http://localhost:4399/_canvas-runtime/react.js');
+  });
+
+  test('withCap prefixes the base AND carries the capability', () => {
+    const base = '/alligators';
+    const cap = 'cap-1';
+    const withCap = (u: string) => {
+      const abs = u.startsWith('/') ? base + u : u;
+      return cap ? abs + (abs.includes('?') ? '&' : '?') + 't=' + encodeURIComponent(cap) : abs;
+    };
+    expect(withCap('/.design/ui/Home.tsx')).toBe('/alligators/.design/ui/Home.tsx?t=cap-1');
+    expect(withCap('/_api/canvas-meta?file=x')).toBe('/alligators/_api/canvas-meta?file=x&t=cap-1');
+    expect(SHELL).toContain("const abs = u.startsWith('/') ? base + u : u;");
+  });
+
+  test('EVERY absolute URL the shell requests goes through the base', () => {
+    // The systematic version of the three separate bugs this file records. Each
+    // was one absolute path that nobody had thought about: the module, then the
+    // importmap, then `comment-mount.js` — and the last one aborted the mount
+    // outright, because it is imported in the same `Promise.all` as the canvas.
+    //
+    // So this asserts the SHAPE rather than a list: nothing in the shell may
+    // form a request from an origin-absolute literal.
+    const offenders: string[] = [];
+    for (const re of [
+      /import\(\s*['"`]\//g, //  import('/…')
+      /fetch\(\s*['"`]\//g, //   fetch('/…')
+      /\.href\s*=\s*['"`]\//g, // el.href = '/…'
+      /\.src\s*=\s*['"`]\//g, //  el.src  = '/…'
+      /location\.host\s*\+\s*['"`]\//g, // ws://host + '/…'
+    ]) {
+      for (const m of SHELL.matchAll(re)) offenders.push(m[0].trim());
+    }
+    expect(offenders).toEqual([]);
+  });
+
+  test('the URLs that DO appear are the ones withCap builds', () => {
+    // Belt to the brace above: the four paths the shell legitimately names must
+    // each be reachable only through `withCap`.
+    for (const path of ['/_client/comment-mount.js', '/_api/canvas-meta']) {
+      const at = SHELL.indexOf(path);
+      expect(at).toBeGreaterThan(0);
+      // `withCap(` appears within the same expression, before the literal.
+      const before = SHELL.slice(Math.max(0, at - 120), at);
+      expect(before).toContain('withCap(');
+    }
+  });
+});

package/apps/studio/test/canvas-url.test.ts

@@ -110,3 +110,29 @@ describe('canvasUrl — per-canvas design-system token resolution', () => {
     ).toBeNull();
   });
 });
+
+// Cloud Phase 27 (DDR-209) — the canvas origin's capability.
+//
+// In the cloud the canvas origin is a cookieless, cross-site hostname: a cookie
+// scoped widely enough to cover it would be readable by the untrusted canvas
+// content itself, which is the one thing the DDR-054 split exists to prevent.
+// So the capability rides in the URL. It reaches `cfg` through the `/_config`
+// projection — which silently dropped it once, and would have 401'd every
+// canvas iframe in production (see `config-projection.test.ts`).
+
+test('a canvas URL carries the capability when the server minted one', () => {
+  const url = canvasUrl('.design/ui/Home.tsx', {
+    designRel: '.design',
+    canvasOrigin: 'https://canvas.cloud.maude.sh/alligators',
+    canvasToken: 'cap-abc123',
+  });
+  expect(url.startsWith('https://canvas.cloud.maude.sh/alligators/_canvas-shell.html?')).toBe(true);
+  expect(new URL(url).searchParams.get('t')).toBe('cap-abc123');
+});
+
+test('a desktop URL is byte-identical to before — no capability, no query', () => {
+  // The loopback canvas origin needs none, so this must not change for the
+  // shell that has always worked.
+  const url = canvasUrl('.design/ui/Home.tsx', { designRel: '.design' });
+  expect(new URL(url, 'http://x').searchParams.has('t')).toBe(false);
+});