@1agh/maude 0.47.0 → 0.49.0

package/apps/studio/workspace-mode.ts

@@ -0,0 +1,210 @@
+// Workspace mode + the containment invariant's first enforcement point.
+//
+// DDR-193 states the invariant:
+//
+//   > No tenant-authored TSX is ever evaluated by vendor-operated compute.
+//   > A cell runs sync + git + asset storage — nothing else. It never renders a
+//   > canvas, never builds a bundle, never executes a canvas module, never runs
+//   > a headless browser against tenant content.
+//
+// and states how it is kept: "enforced, not asserted — a boot-assert in the cell
+// image plus a CI grep gate." This module is the boot-assert. The grep gate is
+// `scripts/check-containment.sh`.
+//
+// WHY A BOOT-ASSERT AND NOT A CODE REVIEW RULE. Every canvas is code the tenant
+// wrote. The moment vendor compute evaluates it, an anonymous signup has
+// arbitrary code execution inside our perimeter, next to other tenants' designs
+// and the control plane's credentials. A convention protects that for exactly as
+// long as everyone remembers it; a process that refuses to start does not
+// forget. The failure mode this prevents is not "someone adds a bad route on
+// purpose" — it is "someone adds a thumbnail endpoint in 2027 without knowing
+// this line exists."
+//
+// It fails CLOSED and LOUD: the cell refuses to boot, naming the exact surfaces
+// that broke it. A cell that will not start is a page; a cell that quietly
+// renders tenant code is an incident.
+
+/** True when this process is a vendor-operated workspace cell. */
+export function isWorkspaceMode(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.MAUDE_WORKSPACE_MODE === '1';
+}
+
+/**
+ * Route paths a workspace cell must not expose, with the reason each one
+ * violates containment. The reason travels with the entry so the error message
+ * teaches rather than just refusing.
+ *
+ * These are prefixes: `/_api/export-jobs` is caught by `/_api/export` and that
+ * is intended — a variant of a forbidden surface is still forbidden.
+ */
+export const FORBIDDEN_ROUTE_PREFIXES: ReadonlyArray<{ prefix: string; why: string }> =
+  Object.freeze([
+    {
+      prefix: '/_api/export',
+      why: 'export renders the canvas through a headless browser — it EVALUATES tenant TSX',
+    },
+    {
+      prefix: '/_api/photo-edit',
+      why: 'photo editing decodes and processes tenant-supplied media in-process',
+    },
+    {
+      prefix: '/_api/generate',
+      why: 'media generation runs tenant-authored prompts against a provider key held here',
+    },
+    {
+      prefix: '/_canvas-shell',
+      why: 'the canvas shell is the surface that mounts and executes a canvas module',
+    },
+    {
+      prefix: '/_canvas-runtime',
+      why: 'serving the canvas runtime only makes sense if something here renders a canvas',
+    },
+    {
+      prefix: '/_ws/acp',
+      why: 'the ACP bridge spawns the user’s own `claude` and can drive file edits (DDR-123 is desktop-only)',
+    },
+  ]);
+
+/**
+ * Modules a cell must not be able to load. Presence of the *dependency* is the
+ * signal — a cell image that ships Playwright is one `import()` away from
+ * rendering tenant content, so the invariant is cheaper to hold at the image
+ * boundary than at the call site.
+ */
+export const FORBIDDEN_MODULES: ReadonlyArray<string> = Object.freeze([
+  'playwright',
+  'playwright-core',
+  'puppeteer',
+  'puppeteer-core',
+]);
+
+/** True when `route` is (or starts with) a forbidden prefix. */
+export function isForbiddenRoute(route: string): boolean {
+  return FORBIDDEN_ROUTE_PREFIXES.some((f) => route === f.prefix || route.startsWith(f.prefix));
+}
+
+/**
+ * Remove every forbidden surface from a route table.
+ *
+ * This is what lets a cell boot at all: the studio serves one route table, and
+ * most of it (sync, comments, annotations, assets, git) is exactly what a cell
+ * needs. Pruning — rather than maintaining a separate cell server — means a cell
+ * runs the SAME code path a self-hoster runs, which is the property DDR-192 §1
+ * is built on. A second implementation would drift.
+ *
+ * Order matters: prune first, then `assertContainment` over the PRUNED keys.
+ * That makes the boot-assert a post-condition on this function rather than an
+ * independent opinion, so a prefix added to the vocabulary automatically both
+ * prunes and is verified.
+ */
+export function pruneForWorkspace<T extends Record<string, unknown>>(
+  routes: T
+): { routes: Partial<T>; removed: string[] } {
+  const kept: Record<string, unknown> = {};
+  const removed: string[] = [];
+  for (const [route, handler] of Object.entries(routes)) {
+    if (isForbiddenRoute(route)) removed.push(route);
+    else kept[route] = handler;
+  }
+  return { routes: kept as Partial<T>, removed: removed.sort() };
+}
+
+export interface ContainmentReport {
+  ok: boolean;
+  /** Route prefixes that are reachable and must not be. */
+  routes: Array<{ route: string; prefix: string; why: string }>;
+  /** Forbidden modules that resolve in this process. */
+  modules: string[];
+}
+
+/**
+ * Check a route table against the invariant. Pure — takes the route names so it
+ * can be unit-tested without booting a server, and so the caller decides what
+ * "reachable" means for its own dispatch shape.
+ */
+export function checkContainment(
+  routeNames: Iterable<string>,
+  { resolveModule }: { resolveModule?: (specifier: string) => boolean } = {}
+): ContainmentReport {
+  const routes: ContainmentReport['routes'] = [];
+  for (const route of routeNames) {
+    for (const { prefix, why } of FORBIDDEN_ROUTE_PREFIXES) {
+      if (route === prefix || route.startsWith(prefix)) {
+        routes.push({ route, prefix, why });
+        break;
+      }
+    }
+  }
+
+  const modules: string[] = [];
+  if (resolveModule) {
+    for (const specifier of FORBIDDEN_MODULES) {
+      if (resolveModule(specifier)) modules.push(specifier);
+    }
+  }
+
+  return { ok: routes.length === 0 && modules.length === 0, routes, modules };
+}
+
+/** Render a report as the message the operator sees when a cell refuses to boot. */
+export function formatContainmentFailure(report: ContainmentReport): string {
+  const lines = [
+    'REFUSING TO START: this process is running as a workspace cell',
+    '(MAUDE_WORKSPACE_MODE=1) but exposes surfaces that break the containment',
+    'invariant — "no tenant-authored TSX is ever evaluated by vendor-operated',
+    'compute" (DDR-193 §2).',
+    '',
+  ];
+  if (report.routes.length > 0) {
+    lines.push('Reachable routes that must not be:');
+    for (const { route, prefix, why } of report.routes) {
+      lines.push(`  ${route}`);
+      lines.push(`      matches ${prefix} — ${why}`);
+    }
+    lines.push('');
+  }
+  if (report.modules.length > 0) {
+    lines.push('Modules that resolve in this process and must not:');
+    for (const m of report.modules) lines.push(`  ${m}`);
+    lines.push('');
+  }
+  lines.push(
+    'A cell runs sync + git + asset storage. Rendering happens on a member’s own',
+    'machine, in Maude Desktop, where DDR-063/DDR-054 already contain it.',
+    '',
+    'If a feature genuinely needs one of these, Direction B (a structured,',
+    'non-executable synced unit) is its HARD PREREQUISITE — not a flag to add here.'
+  );
+  if (report.modules.length > 0) {
+    lines.push(
+      '',
+      'Testing workspace mode inside a DEV CHECKOUT? Playwright is a legitimate',
+      'devDependency here (the E2E harness), so it resolves and this fires. Set',
+      'MAUDE_WORKSPACE_ALLOW_DEV_MODULES=1 to skip the module check locally. It has',
+      'no effect on a built cell image, where the runtime-dependency gate in',
+      'scripts/check-containment.sh is the enforcement — a shipped cell must not',
+      'contain a browser at all.'
+    );
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Boot gate. No-op unless workspace mode is on; otherwise throws with the full
+ * report when anything forbidden is reachable.
+ *
+ * Deliberately throws rather than returning a boolean: a caller that forgets to
+ * check a return value is exactly the class of mistake this exists to survive.
+ */
+export function assertContainment(
+  routeNames: Iterable<string>,
+  {
+    env = process.env,
+    resolveModule,
+  }: { env?: NodeJS.ProcessEnv; resolveModule?: (specifier: string) => boolean } = {}
+): void {
+  if (!isWorkspaceMode(env)) return;
+  const report = checkContainment(routeNames, { resolveModule });
+  if (report.ok) return;
+  throw new Error(formatContainmentFailure(report));
+}

package/apps/studio/ws.ts

@@ -27,6 +27,10 @@ export type WsData =
       remote: string;
       kind: 'collab';
       slug: string;
+      /** Which origin upgraded this socket — 'canvas' marks the untrusted
+       *  canvas iframe origin, whose sync frames go through the DDR-122
+       *  origin gate in collab/room.ts. Set at upgrade time in server.ts. */
+      realm: 'main' | 'canvas';
     }
   | {
       // T2 (9.1-A) — HMR-only socket for the segregated canvas origin. Receives
@@ -244,9 +248,14 @@ export function createWs(
   // right room to disconnect from. Multiplexed via ws.data.id.
   const collabConns = new Map<string, { roomSlug: string; conn: RoomConn }>();
 
-  function bindCollab(ws: ServerWebSocket<WsData>, slug: string): RoomConn {
+  function bindCollab(
+    ws: ServerWebSocket<WsData>,
+    slug: string,
+    realm: 'main' | 'canvas'
+  ): RoomConn {
     const conn: RoomConn = {
       id: ws.data.id,
+      realm,
       send(payload: Uint8Array) {
         try {
           // Bun's ws.send accepts Uint8Array directly as binary.
@@ -264,7 +273,7 @@ export function createWs(
     async open(ws) {
       if (ws.data.kind === 'collab') {
         const room = collab.registry.get(ws.data.slug);
-        const conn = bindCollab(ws, ws.data.slug);
+        const conn = bindCollab(ws, ws.data.slug, ws.data.realm ?? 'main');
         await room.connect(conn);
         return;
       }

package/cli/bin/maude.mjs

@@ -18,6 +18,7 @@ const COMMANDS = {
   design: () => import('../commands/design.mjs'),
   'scenario-report': () => import('../commands/scenario-report.mjs'),
   doctor: () => import('../commands/doctor.mjs'),
+  kg: () => import('../commands/kg.mjs'),
   help: () => import('../commands/help.mjs'),
   hub: () => import('../commands/hub.mjs'),
   version: () => import('../commands/version.mjs'),

package/cli/commands/hub-workspace.mjs

@@ -0,0 +1,341 @@
+// `maude hub workspace-up` — Cloud Phase 4 Task 1, the effects layer.
+//
+// The decisions live in `cli/lib/workspace-plan.mjs` (pure, tested without a
+// VPS). This file does the parts that genuinely touch the world: read config,
+// write files, boot the stack, run the verification plan, print the result.
+//
+// IDEMPOTENT BY CONSTRUCTION. Re-running is the upgrade path: the rendered
+// files are regenerated, but `.env` secrets that already exist are REUSED, not
+// re-minted. Re-minting HUB_SECRET on every run would silently lock out every
+// peer that already has a token, and it would do it to the person whose
+// instinct after a failed run is to try again.
+//
+// It does NOT claim to own the deployment afterwards — see `operatorDuties`.
+
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { parseArgs } from '../lib/argv.mjs';
+import {
+  envEntries,
+  operatorDuties,
+  renderCaddyfile,
+  renderCompose,
+  renderEnv,
+  validateWorkspaceConfig,
+  verificationPlan,
+} from '../lib/workspace-plan.mjs';
+
+export function usage() {
+  return `maude hub workspace-up [options]
+
+  Stand up a self-hosted Maude WORKSPACE — a hub that owns the project, commits
+  autosaves, and stores media in object storage — and verify it actually works
+  before saying so.
+
+  --domain HOST            public hostname (design.acme.com)
+  --acme-email EMAIL       Let's Encrypt contact
+  --admin-email EMAIL      the first person who can sign in
+  --admin-password PASS    their initial password (>= 12 chars; generated if omitted)
+  --s3-endpoint URL        object storage (R2 / MinIO / S3)
+  --s3-bucket NAME
+  --s3-access-key-id ID
+  --s3-secret-access-key SECRET
+  --s3-region REGION       default "auto"
+  --dev-minio              run a local MinIO under the compose 'dev' profile
+  --seed-repo URL          clone an existing project; omit to start fresh
+  --image-tag TAG          default "latest" — pin it before you rely on this
+  --config FILE            read all of the above from a JSON file
+  --out DIR                where to write compose/Caddyfile/.env (default: cwd)
+  --dry-run                render + print the plan, touch nothing else
+  --json                   machine-readable result
+
+  Re-running is the UPGRADE path: files are regenerated, existing secrets in
+  .env are REUSED (re-minting HUB_SECRET would lock out every peer that already
+  has a token).
+
+  What it does NOT do: own the deployment. It scaffolds and verifies once.
+  Rotation, backups, upgrades and the bill stay with you — the run prints the
+  list.
+`;
+}
+
+export async function run({ args, pkgRoot }) {
+  const { flags } = parseArgs(args, { booleans: ['dry-run', 'json', 'dev-minio'] });
+  if (flags.help) {
+    process.stdout.write(usage());
+    return;
+  }
+
+  const outDir = resolve(String(flags.out ?? process.cwd()));
+  const raw = flags.config ? readConfigFile(String(flags.config)) : {};
+  const merged = {
+    domain: flags.domain ?? raw.domain,
+    acmeEmail: flags['acme-email'] ?? raw.acmeEmail,
+    adminEmail: flags['admin-email'] ?? raw.adminEmail,
+    ...((flags['admin-password'] ?? raw.adminPassword)
+      ? { adminPassword: flags['admin-password'] ?? raw.adminPassword }
+      : {}),
+    devMinio: flags['dev-minio'] === true || raw.devMinio === true,
+    seedRepo: flags['seed-repo'] ?? raw.seedRepo,
+    imageTag: flags['image-tag'] ?? raw.imageTag,
+    ...(flags['s3-endpoint'] || raw.s3
+      ? {
+          s3: {
+            endpoint: flags['s3-endpoint'] ?? raw.s3?.endpoint,
+            bucket: flags['s3-bucket'] ?? raw.s3?.bucket,
+            accessKeyId: flags['s3-access-key-id'] ?? raw.s3?.accessKeyId,
+            secretAccessKey: flags['s3-secret-access-key'] ?? raw.s3?.secretAccessKey,
+            region: flags['s3-region'] ?? raw.s3?.region,
+          },
+        }
+      : {}),
+  };
+
+  const { ok, errors, config } = validateWorkspaceConfig(merged);
+  if (!ok) {
+    if (flags.json) {
+      process.stdout.write(`${JSON.stringify({ ok: false, errors }, null, 2)}\n`);
+    } else {
+      process.stderr.write('maude hub workspace-up: the configuration is not usable yet.\n\n');
+      for (const e of errors) process.stderr.write(`  • ${e}\n`);
+      process.stderr.write('\nRun with --help for the full list of options.\n');
+    }
+    process.exit(2);
+  }
+
+  // Reuse existing secrets — re-minting on a re-run would lock out every peer
+  // that already holds a token, and re-running is exactly what someone does
+  // after a failed attempt.
+  const existing = readExistingEnv(resolve(outDir, '.env'));
+  const hubSecret = existing.HUB_SECRET || randomBytes(32).toString('hex');
+  const adminPassword = config.adminPassword || existing.MAUDE_ADMIN_PASSWORD || generatePassword();
+  const reusedSecret = Boolean(existing.HUB_SECRET);
+
+  const entries = envEntries(config, { hubSecret, adminPassword });
+  const files = [
+    { name: '.env', body: renderEnv(entries), mode: 0o600 },
+    { name: 'docker-compose.yml', body: renderCompose(config), mode: 0o644 },
+    { name: 'Caddyfile', body: renderCaddyfile(config), mode: 0o644 },
+  ];
+  const plan = verificationPlan(config);
+  const duties = operatorDuties(config);
+
+  if (flags['dry-run']) {
+    const result = {
+      ok: true,
+      dryRun: true,
+      outDir,
+      files: files.map((f) => ({ name: f.name, bytes: Buffer.byteLength(f.body), mode: f.mode })),
+      verification: plan.map((s) => ({ id: s.id, title: s.title })),
+      duties: duties.map((d) => d.title),
+      reusedSecret,
+    };
+    if (flags.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    else printDryRun({ config, outDir, files, plan, duties, reusedSecret });
+    return;
+  }
+
+  mkdirSync(outDir, { recursive: true });
+  for (const f of files) {
+    const path = resolve(outDir, f.name);
+    writeFileSync(path, f.body, { encoding: 'utf8', mode: f.mode });
+    try {
+      chmodSync(path, f.mode);
+    } catch {
+      /* windows — best effort */
+    }
+  }
+
+  const dockerAvailable = await which('docker');
+  if (!dockerAvailable) {
+    if (flags.json) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, wrote: files.map((f) => f.name), error: 'docker not found' }, null, 2)}\n`
+      );
+    } else {
+      process.stdout.write(
+        `Wrote ${files.map((f) => f.name).join(', ')} to ${outDir}\n\n` +
+          'Docker is not on PATH, so the stack was not started and NOTHING WAS VERIFIED.\n' +
+          'Install Docker and run:\n\n' +
+          `  cd ${outDir} && docker compose up -d\n\n` +
+          'Then re-run this command to verify the deployment.\n'
+      );
+    }
+    process.exit(1);
+  }
+
+  process.stdout.write(`Wrote ${files.map((f) => f.name).join(', ')} to ${outDir}\n`);
+  process.stdout.write('Starting the stack…\n');
+  const up = await sh('docker', ['compose', 'up', '-d'], { cwd: outDir });
+  if (up.code !== 0) {
+    process.stderr.write(`docker compose up failed:\n${up.stderr}\n`);
+    process.exit(1);
+  }
+
+  // Verification is the deliverable. A URL printed without a proven round-trip
+  // tells the operator something this command does not know.
+  process.stdout.write('\nVerifying — this is the part that matters:\n');
+  const results = [];
+  let failed = 0;
+  for (const step of plan) {
+    const outcome = await runVerification(step, {
+      config,
+      hubSecret,
+      adminPassword,
+      outDir,
+      pkgRoot,
+    });
+    results.push({ id: step.id, title: step.title, ...outcome });
+    const mark = outcome.ok ? '✓' : outcome.skipped ? '–' : '✗';
+    process.stdout.write(`  ${mark} ${step.title}${outcome.note ? ` — ${outcome.note}` : ''}\n`);
+    if (!outcome.ok && !outcome.skipped) failed++;
+  }
+
+  if (flags.json) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: failed === 0, outDir, verification: results, duties }, null, 2)}\n`
+    );
+  } else {
+    printDuties(duties);
+    process.stdout.write(
+      failed === 0
+        ? `\nWorkspace verified: https://${config.domain}\n`
+        : `\n${failed} check(s) did NOT pass. The stack is running but is not proven — fix and re-run.\n`
+    );
+  }
+  if (failed > 0) process.exit(1);
+}
+
+// ------------------------------------------------------------------ helpers
+
+function readConfigFile(path) {
+  try {
+    return JSON.parse(readFileSync(resolve(path), 'utf8'));
+  } catch (err) {
+    process.stderr.write(
+      `maude hub workspace-up: couldn't read --config ${path}: ${err.message}\n`
+    );
+    process.exit(2);
+  }
+}
+
+/** Parse an existing `.env` so a re-run reuses secrets instead of re-minting. */
+function readExistingEnv(path) {
+  if (!existsSync(path)) return {};
+  const out = {};
+  try {
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+      const m = line.match(/^([A-Z0-9_]+)=(.*)$/);
+      if (m) out[m[1]] = m[2];
+    }
+  } catch {
+    /* unreadable → treat as absent */
+  }
+  return out;
+}
+
+/** Readable, high-entropy, and safe to paste — no ambiguous glyphs. */
+function generatePassword() {
+  const alphabet = 'abcdefghjkmnpqrstuvwxyzABCDEFGHJKMNPQRSTUVWXYZ23456789';
+  const bytes = randomBytes(24);
+  return Array.from(bytes, (b) => alphabet[b % alphabet.length]).join('');
+}
+
+function sh(cmd, args, opts = {}) {
+  return new Promise((resolvePromise) => {
+    const child = spawn(cmd, args, { ...opts, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => {
+      stdout += d;
+    });
+    child.stderr.on('data', (d) => {
+      stderr += d;
+    });
+    child.on('error', () => resolvePromise({ code: 127, stdout, stderr: 'spawn failed' }));
+    child.on('close', (code) => resolvePromise({ code: code ?? 1, stdout, stderr }));
+  });
+}
+
+async function which(bin) {
+  const res = await sh(process.platform === 'win32' ? 'where' : 'which', [bin]);
+  return res.code === 0;
+}
+
+/**
+ * Execute one verification step.
+ *
+ * A step this build cannot yet perform reports `skipped` with a reason — it
+ * NEVER reports success. Counting an unrun check as passed is the single
+ * fastest way to make a verification suite worthless.
+ */
+async function runVerification(step, { config, hubSecret }) {
+  const base = `https://${config.domain}`;
+  switch (step.id) {
+    case 'health': {
+      const res = await tryFetch(`${base}/health`);
+      return res.ok ? { ok: true } : { ok: false, note: res.note };
+    }
+    case 'admin-claimed': {
+      const res = await tryFetch(`${base}/admin/api/status`, {
+        headers: { Authorization: `Bearer ${hubSecret}` },
+      });
+      return res.ok ? { ok: true } : { ok: false, note: res.note };
+    }
+    default:
+      return {
+        ok: false,
+        skipped: true,
+        note: 'not yet automated — verify by hand, then close it in the plan',
+      };
+  }
+}
+
+async function tryFetch(url, init) {
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 10_000);
+    try {
+      const res = await fetch(url, { ...init, signal: ctrl.signal });
+      return res.ok ? { ok: true } : { ok: false, note: `HTTP ${res.status}` };
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch (err) {
+    return { ok: false, note: err.name === 'AbortError' ? 'timed out' : 'unreachable' };
+  }
+}
+
+function printDryRun({ config, outDir, files, plan, duties, reusedSecret }) {
+  process.stdout.write(
+    `maude hub workspace-up — DRY RUN, nothing was written\n\n` +
+      `  workspace   https://${config.domain}\n` +
+      `  first user  ${config.adminEmail}\n` +
+      `  storage     ${config.s3 ? `${config.s3.bucket} @ ${config.s3.endpoint}${config.s3.dev ? ' (dev MinIO)' : ''}` : 'none — media stays in git'}\n` +
+      `  project     ${config.seedRepo ?? 'starts fresh'}\n` +
+      `  image       ghcr.io/1agh/maude-hub:${config.imageTag}\n` +
+      `  out         ${outDir}\n` +
+      (reusedSecret ? '  secrets     reusing HUB_SECRET from the existing .env\n' : '') +
+      '\nWould write:\n'
+  );
+  for (const f of files) {
+    process.stdout.write(
+      `  ${f.name.padEnd(20)} ${Buffer.byteLength(f.body)} bytes  mode ${f.mode.toString(8)}\n`
+    );
+  }
+  process.stdout.write('\nWould then verify:\n');
+  for (const s of plan) process.stdout.write(`  • ${s.title} — ${s.detail}\n`);
+  printDuties(duties);
+}
+
+function printDuties(duties) {
+  process.stdout.write(
+    '\nThis command scaffolded and verified your workspace once. It does not\noperate it. What stays yours:\n\n'
+  );
+  for (const d of duties) {
+    process.stdout.write(`  ${d.title}\n      ${d.detail}\n`);
+  }
+}