@1agh/maude 0.60.6 → 1.0.2

package/cli/lib/workspace-plan.mjs

@@ -21,6 +21,23 @@ const DOMAIN_RE = /^(?!-)[a-z0-9-]{1,63}(?<!-)(\.(?!-)[a-z0-9-]{1,63}(?<!-))+$/;
 const BUCKET_RE = /^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/;
 const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 
+/**
+ * Normalize a backup namespace into a key-safe segment — Phase 0 F3.
+ *
+ * Deliberately narrow: this becomes an object-key prefix, so anything that
+ * could re-enter the keyspace elsewhere (`/`, `..`, whitespace) has to be gone
+ * rather than escaped. Mirrors the charset the cell validates its tenant id
+ * with, for the same reason.
+ */
+export function sanitizeBackupPrefix(raw) {
+  return String(raw ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^[-.]+|[-.]+$/g, '')
+    .slice(0, 64);
+}
+
 /**
  * @typedef {object} WorkspaceConfig
  * @property {string} domain          public hostname, e.g. design.acme.com
@@ -38,6 +55,36 @@ const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  * problems, not the first one: someone filling this in wants to fix everything
  * in one pass, not to play whack-a-mole with a wizard.
  */
+/**
+ * A seed URL with its credential masked, for anything an eye or a log can see.
+ *
+ * The recommended seed URL carries a live GitHub PAT in userinfo
+ * (`https://x-access-token:<PAT>@github.com/org/repo.git` — `seed-repo.mjs`
+ * accepts nothing else). The AWS spike printed it raw, and the token landed in
+ * SSM command history, CloudTrail and a session transcript before anyone
+ * noticed; it had to be revoked. `.env` is written `0600` — stdout has no such
+ * thing, so nothing may print the configured value directly.
+ *
+ * The host and path survive, because those are what an operator reads the line
+ * to confirm.
+ */
+export function safeSeedUrl(raw) {
+  const value = String(raw ?? '').trim();
+  if (!value) return null;
+  try {
+    const u = new URL(value);
+    if (u.username || u.password) {
+      u.username = '***';
+      u.password = '';
+    }
+    return u.toString();
+  } catch {
+    // `git@host:org/repo.git` is not a URL but carries no secret; anything
+    // else unparseable is not worth guessing at with a token possibly inside.
+    return /^git@[^\s:]+:[^\s]+$/.test(value) ? value : '<unparseable seed url>';
+  }
+}
+
 export function validateWorkspaceConfig(raw = {}) {
   const errors = [];
   const cfg = { ...raw };
@@ -47,6 +94,12 @@ export function validateWorkspaceConfig(raw = {}) {
   // suite ends up needing a purchased domain before it can run even once.
   cfg.local = raw.local === true;
 
+  // feature-cloud-export-render-workers (DDR-230) — the optional maude-render
+  // sidecar. Opt-in: it is the one container in the stack that carries a
+  // browser, and an operator must mean that. Without it the workspace still
+  // works; browser-format exports refuse with a remedy (lane `none`).
+  cfg.render = raw.render === true;
+
   cfg.domain = String(raw.domain ?? '')
     .trim()
     .toLowerCase()
@@ -87,6 +140,43 @@ export function validateWorkspaceConfig(raw = {}) {
     );
   }
 
+  // Spike finding M7 — the SECOND hostname, for the canvas origin. The studio
+  // splits the canvas iframe onto its own origin (DDR-054), and without a
+  // public name for it the iframe falls back to `http://localhost:<container
+  // port>` — an address only the server itself can reach. The stack then comes
+  // up, all eight verification steps pass, and every canvas renders as a blank
+  // frame with ERR_CONNECTION_REFUSED in the console. The hub already routes
+  // by Host (`isCanvasHost`), so all this needs is a name: DNS → Caddy block →
+  // MAUDE_PUBLIC_CANVAS_ORIGIN, all rendered from this one value.
+  cfg.canvasDomain = String(raw.canvasDomain ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/^https?:\/\//, '')
+    .replace(/\/.*$/, '');
+  if (cfg.canvasDomain) {
+    const canvasIsLoopback =
+      cfg.canvasDomain === 'localhost' || cfg.canvasDomain.endsWith('.localhost');
+    if (cfg.local && canvasIsLoopback) {
+      // same carve-out as the main domain — `canvas.localhost` is loopback by RFC 6761
+    } else if (!DOMAIN_RE.test(cfg.canvasDomain)) {
+      errors.push(`canvasDomain "${cfg.canvasDomain}" is not a valid hostname`);
+    } else if (!cfg.canvasDomain.includes('.')) {
+      errors.push('canvasDomain must be fully qualified');
+    }
+    if (cfg.local && !canvasIsLoopback) {
+      errors.push(
+        `--local requires a loopback canvas name (*.localhost); "${cfg.canvasDomain}" is not one`
+      );
+    }
+    // The SAME name would collapse the origin split this domain exists to
+    // create — one origin again, cookies reachable from tenant code (DDR-054).
+    if (cfg.canvasDomain === cfg.domain) {
+      errors.push('canvasDomain must differ from domain — a same-origin canvas defeats the split');
+    }
+  } else {
+    cfg.canvasDomain = null;
+  }
+
   cfg.acmeEmail = String(raw.acmeEmail ?? '').trim();
   if (!cfg.acmeEmail) {
     if (!cfg.local) errors.push('acmeEmail is required (Let’s Encrypt expiry notices)');
@@ -136,6 +226,60 @@ export function validateWorkspaceConfig(raw = {}) {
     };
   }
 
+  // BYO identity — Track C C6. Threaded through validation, .env AND compose;
+  // a var written into one but not the other never reaches the container, which
+  // already shipped once with MAUDE_ADMIN_PASSWORD (see renderCompose).
+  if (raw.oidc) {
+    const o = { ...raw.oidc };
+    o.issuer = String(o.issuer ?? '')
+      .trim()
+      .replace(/\/+$/, '');
+    o.mode = o.mode === 'strict' ? 'strict' : 'hybrid';
+    o.domains = String(o.domains ?? '').trim();
+    if (!o.issuer) errors.push('oidc.issuer is required when oidc is configured');
+    else if (!/^https:\/\//.test(o.issuer)) errors.push('oidc.issuer must be https');
+    if (!o.clientId) errors.push('oidc.clientId is required when oidc is configured');
+    if (!o.clientSecret) errors.push('oidc.clientSecret is required when oidc is configured');
+    // A filter, never a grant — but required, because without it every subject
+    // at a public issuer can queue itself into the operator's pending list.
+    if (!o.domains) errors.push('oidc.domains is required when oidc is configured');
+    cfg.oidc = o;
+  }
+
+  // The backup namespace — Phase 0 F3.
+  //
+  // Until now nothing here mentioned MAUDE_BACKUP_PREFIX at all: the CELL
+  // entrypoint sets it (derived from the tenant id) and a self-hosted
+  // workspace therefore backed up to the bucket ROOT by construction. Two hubs
+  // on one bucket then shared a keyspace, which is how their generations
+  // interleaved and pruned across each other.
+  //
+  // NEW RENDERS ONLY — and that restriction is the point. Adding a prefix to a
+  // deployment that already has generations at the root moves it to a DISJOINT
+  // keyspace (`prefixedTarget` rewrites `list('backups/')` to
+  // `list('<prefix>/backups/')`), so every existing generation goes invisible
+  // in one config change: orphaned, unprunable, and — after the next volume
+  // loss — a cold start that sees zero generations and seeds instead. The fix
+  // would re-open the exact destruction it exists to close.
+  //
+  // Safe to leave off, because the WRITE-side identity refusal already stops
+  // the destruction at the bare root without any prefix. Here the prefix is a
+  // remedy, not the safety mechanism.
+  //
+  // `backupPrefix: null` is the caller saying "existing deployment, leave it
+  // alone"; a string is an explicit choice; undefined derives one.
+  if (raw.backupPrefix === null) {
+    cfg.backupPrefix = null;
+  } else if (raw.backupPrefix !== undefined && String(raw.backupPrefix).trim() !== '') {
+    const explicit = sanitizeBackupPrefix(raw.backupPrefix);
+    if (!explicit) errors.push(`backupPrefix "${raw.backupPrefix}" has no usable characters`);
+    cfg.backupPrefix = explicit || null;
+  } else {
+    // Derived from the address, which is the one identifier the operator has
+    // already had to make unique — DNS enforced it.
+    cfg.backupPrefix = sanitizeBackupPrefix(cfg.domain) || null;
+  }
+
   if (raw.seedRepo !== undefined && raw.seedRepo !== null && String(raw.seedRepo).trim() !== '') {
     const seed = String(raw.seedRepo).trim();
     if (!/^(https?:\/\/|git@|ssh:\/\/)/.test(seed)) {
@@ -172,7 +316,7 @@ export function workspaceBaseUrl(cfg) {
  * without it every client shares one rate-limit bucket and a single attacker's
  * login flood limits everybody (DDR-194 §4).
  */
-export function envEntries(cfg, { hubSecret, adminPassword }) {
+export function envEntries(cfg, { hubSecret, adminPassword, renderSecret }) {
   const entries = [
     {
       key: 'PUBLIC_DOMAIN',
@@ -234,10 +378,67 @@ export function envEntries(cfg, { hubSecret, adminPassword }) {
       { key: 'MAUDE_S3_SECRET_ACCESS_KEY', value: cfg.s3.secretAccessKey },
       { key: 'MAUDE_S3_REGION', value: cfg.s3.region }
     );
+    if (cfg.backupPrefix) {
+      entries.push({
+        key: 'MAUDE_BACKUP_PREFIX',
+        value: cfg.backupPrefix,
+        comment: 'this hub owns this keyspace; never point a second hub at it',
+      });
+    }
+  }
+  if (cfg.oidc) {
+    entries.push(
+      {
+        key: 'HUB_OIDC_MODE',
+        value: cfg.oidc.mode,
+        comment: 'hybrid = password login still works; strict = OIDC only',
+      },
+      { key: 'HUB_OIDC_ISSUER', value: cfg.oidc.issuer },
+      { key: 'HUB_OIDC_CLIENT_ID', value: cfg.oidc.clientId },
+      { key: 'HUB_OIDC_CLIENT_SECRET', value: cfg.oidc.clientSecret },
+      {
+        key: 'HUB_OIDC_ALLOWED_DOMAINS',
+        value: cfg.oidc.domains,
+        comment: 'a filter, never a grant — a permitted domain still needs an account',
+      }
+    );
   }
   if (cfg.seedRepo) {
     entries.push({ key: 'MAUDE_SEED_REPO', value: cfg.seedRepo, comment: 'cloned on first boot' });
   }
+  if (cfg.canvasDomain) {
+    entries.push(
+      {
+        key: 'CANVAS_DOMAIN',
+        value: cfg.canvasDomain,
+        comment: 'second hostname for the canvas origin; Caddy serves it, DNS must point here too',
+      },
+      {
+        key: 'MAUDE_PUBLIC_CANVAS_ORIGIN',
+        value: `${cfg.local ? 'http' : 'https'}://${cfg.canvasDomain}`,
+        comment: 'without this the canvas iframe points at a container-internal port (M7)',
+      }
+    );
+  }
+  if (cfg.render) {
+    entries.push(
+      {
+        key: 'MAUDE_RENDER_SECRET',
+        value: renderSecret,
+        comment: 'hub ↔ render ingress bearer (DDR-230) — its own secret, never HUB_SECRET',
+      },
+      {
+        key: 'MAUDE_RENDER_URL',
+        value: 'http://render:8790',
+        comment: 'compose-internal address the hub dispatches export jobs to',
+      },
+      {
+        key: 'MAUDE_RENDER_CANVAS_BASE',
+        value: 'http://hub:1234',
+        comment: 'where the render service fetches canvases — the hub, over the compose network',
+      }
+    );
+  }
   entries.push({
     key: 'MAUDE_IMAGE_TAG',
     value: cfg.imageTag,
@@ -255,12 +456,36 @@ export function renderEnv(entries) {
   ];
   for (const e of entries) {
     if (e.comment) lines.push(`# ${e.comment}`);
-    lines.push(`${e.key}=${e.value}`);
+    lines.push(`${e.key}=${renderEnvValue(e.value)}`);
     lines.push('');
   }
   return `${lines.join('\n').trimEnd()}\n`;
 }
 
+/**
+ * Render one `.env` value safely (F8).
+ *
+ * Two failure modes a raw `${value}` opens, both with operator-pasted material
+ * (an S3 secret, an OIDC client secret):
+ *   - a NEWLINE injects an arbitrary extra line, which `readExistingEnv`'s
+ *     `^KEY=…$` parser then accepts and PERSISTS across the "re-run is the
+ *     upgrade path" flow — `secret\nHUB_INSECURE_HTTP=1` becomes real config.
+ *   - a `$` is re-interpolated by `docker compose`, so the container silently
+ *     gets a different value than the file shows — an unexplained lockout.
+ * A control character is rejected outright (it cannot be meant); everything
+ * else is single-quoted, and an embedded single quote is escaped the POSIX way.
+ */
+function renderEnvValue(raw) {
+  const v = String(raw ?? '');
+  if (/[\n\r\0]/.test(v)) {
+    throw new Error('refusing to write a .env value containing a newline or control character');
+  }
+  if (v === '') return '';
+  // Single-quote: inside single quotes the shell and compose interpolate
+  // nothing. `'\''` is the POSIX way to embed a single quote.
+  return `'${v.replace(/'/g, `'\\''`)}'`;
+}
+
 /**
  * The compose stack: hub + Caddy, MinIO only under the `dev` profile.
  *
@@ -288,9 +513,27 @@ export function renderCompose(cfg) {
           'MAUDE_S3_ACCESS_KEY_ID',
           'MAUDE_S3_SECRET_ACCESS_KEY',
           'MAUDE_S3_REGION',
+          // Written into .env AND forwarded here. This list is hand-maintained,
+          // and a var present in one but not the other never reaches the
+          // container — which already shipped once, with MAUDE_ADMIN_PASSWORD.
+          ...(cfg.backupPrefix ? ['MAUDE_BACKUP_PREFIX'] : []),
+        ]
+      : []),
+    ...(cfg.oidc
+      ? [
+          'HUB_OIDC_MODE',
+          'HUB_OIDC_ISSUER',
+          'HUB_OIDC_CLIENT_ID',
+          'HUB_OIDC_CLIENT_SECRET',
+          'HUB_OIDC_ALLOWED_DOMAINS',
         ]
       : []),
     ...(cfg.seedRepo ? ['MAUDE_SEED_REPO'] : []),
+    // Written into .env AND forwarded here — same hand-maintained pair as the
+    // S3 block above, same failure mode when they drift (M7: the origin was
+    // supported end to end and no deployment path ever set it).
+    ...(cfg.canvasDomain ? ['MAUDE_PUBLIC_CANVAS_ORIGIN'] : []),
+    ...(cfg.render ? ['MAUDE_RENDER_SECRET', 'MAUDE_RENDER_URL', 'MAUDE_RENDER_CANVAS_BASE'] : []),
   ];
 
   return `# Maude workspace — generated by \`maude hub workspace-up\`.
@@ -324,14 +567,33 @@ ${envLines(hubEnv)}
     expose:
       - "1234"
 
-  caddy:
+${
+  cfg.render
+    ? `  # The maude-render sidecar (DDR-230) — the ONE container here that holds a
+  # browser. It renders export jobs the hub dispatches; it holds no hub
+  # secret, no volume, no tenant store, and it refuses to boot if a known
+  # secret variable reaches it. Not exposed publicly — the hub talks to it
+  # over the compose network only.
+  render:
+    image: ghcr.io/1agh/maude-render:\${MAUDE_IMAGE_TAG:-latest}
+    restart: unless-stopped
+    environment:
+      MAUDE_RENDER_SECRET: \${MAUDE_RENDER_SECRET}
+      # This service only fetches canvases from the hub next door.
+      MAUDE_RENDER_CANVAS_ORIGINS: http://hub:1234
+    expose:
+      - "8790"
+
+`
+    : ''
+}  caddy:
     image: caddy:2-alpine
     restart: unless-stopped
     ports:
       - "80:80"${cfg.local ? '' : '\n      - "443:443"'}
     environment:
       PUBLIC_DOMAIN: \${PUBLIC_DOMAIN}
-      ACME_EMAIL: \${ACME_EMAIL}
+      ACME_EMAIL: \${ACME_EMAIL}${cfg.canvasDomain ? '\n      CANVAS_DOMAIN: ${CANVAS_DOMAIN}' : ''}
     volumes:
       - ./Caddyfile:/etc/caddy/Caddyfile:ro
       - caddy-data:/data
@@ -412,6 +674,24 @@ export function renderCaddyfile(cfg) {
 }
 `;
 
+  const canvasSite = cfg.canvasDomain
+    ? `
+# The CANVAS origin (M7) — a second hostname for the same hub. The hub routes
+# by Host (isCanvasHost) and proxies to the studio's canvas listener itself, so
+# this block needs no port knowledge; it exists so the name resolves and gets a
+# certificate. Deliberately a separate ORIGIN, not a path: the split is what
+# keeps studio cookies unreachable from tenant canvas code (DDR-054).
+${cfg.local ? 'http://{$CANVAS_DOMAIN}' : '{$CANVAS_DOMAIN}'} {
+  encode zstd gzip
+  reverse_proxy hub:1234 {
+    header_up X-Forwarded-For {remote_host}
+    header_up X-Forwarded-Proto {scheme}
+    header_up Host {host}
+  }
+}
+`
+    : '';
+
   return `# Maude workspace — generated by \`maude hub workspace-up\`.
 ${header}
 ${site} {
@@ -427,7 +707,7 @@ ${site} {
     header_up Host {host}
   }
 }
-`;
+${canvasSite}`;
 }
 
 /**
@@ -481,6 +761,13 @@ export function verificationPlan(cfg) {
       }
     );
   }
+  if (cfg.render) {
+    steps.push({
+      id: 'render-health',
+      title: 'the render service answers and is configured',
+      detail: 'GET http://render:8790/_health (via the hub container) reports configured:true',
+    });
+  }
   steps.push({
     id: 'restore-drill',
     title: 'a backup can actually be restored',
@@ -522,6 +809,12 @@ export function operatorDuties(cfg) {
       detail: 'This runs on your infrastructure. Nothing here monitors spend.',
     },
   ];
+  if (cfg.canvasDomain) {
+    duties.push({
+      title: 'DNS for the canvas domain too',
+      detail: `${cfg.canvasDomain} must point at this machine, same as ${cfg.domain} — Caddy fetches its certificate on first request; until DNS lands, canvases are blank frames.`,
+    });
+  }
   if (cfg.s3) {
     duties.push({
       title: 'Never expire the assets/ prefix',

package/cli/lib/workspace-plan.test.mjs

@@ -14,6 +14,7 @@ import {
   renderCaddyfile,
   renderCompose,
   renderEnv,
+  safeSeedUrl,
   validateWorkspaceConfig,
   verificationPlan,
   workspaceBaseUrl,
@@ -125,7 +126,7 @@ test('renderEnv announces that it holds secrets', () => {
   );
   assert.match(text, /Contains SECRETS/);
   assert.match(text, /Mode 0600, never committed/);
-  assert.match(text, /^HUB_SECRET=sekrit$/m);
+  assert.match(text, /^HUB_SECRET='sekrit'$/m);
   // The bootstrap password is flagged as temporary rather than left to linger.
   assert.match(text, /change it after, then remove this line/);
 });
@@ -381,3 +382,216 @@ test('MAUDE_SEED_REPO crosses into the container when one is configured', () =>
   const without = renderCompose(ok(BASE));
   assert.ok(!/MAUDE_SEED_REPO/.test(without), 'no seed configured ⇒ no empty variable to misread');
 });
+
+// ------------------------------------------- the backup namespace (Phase 0 F3)
+
+test('a NEW render derives a backup namespace from the address', () => {
+  // Nothing here mentioned MAUDE_BACKUP_PREFIX before: only the CELL entrypoint
+  // set it, so a self-hosted workspace backed up to the bucket ROOT by
+  // construction, and two hubs on one bucket shared one keyspace.
+  const cfg = ok({ ...BASE, s3: S3 });
+  assert.equal(cfg.backupPrefix, 'design.acme.com');
+  const env = renderEnv(envEntries(cfg, { hubSecret: 'x', adminPassword: 'y'.repeat(12) }));
+  assert.match(env, /MAUDE_BACKUP_PREFIX='design\.acme\.com'/);
+});
+
+test('an EXISTING deployment without a prefix is never given one', () => {
+  // The orphan hazard: a prefixed target lists a DISJOINT keyspace, so adding
+  // one on a re-render makes every existing generation invisible to
+  // listBackups — orphaned, unprunable, and the next lost volume sees zero
+  // generations and seeds over the loss. The fix would re-open the destruction
+  // it exists to close. `backupPrefix: null` is the caller saying "leave it".
+  const cfg = ok({ ...BASE, s3: S3, backupPrefix: null });
+  assert.equal(cfg.backupPrefix, null);
+  const env = renderEnv(envEntries(cfg, { hubSecret: 'x', adminPassword: 'y'.repeat(12) }));
+  assert.ok(!/MAUDE_BACKUP_PREFIX/.test(env), 'no prefix must be written');
+  assert.ok(!/MAUDE_BACKUP_PREFIX/.test(renderCompose(cfg)), 'and none forwarded');
+});
+
+test('the namespace is written into .env AND forwarded to the container', () => {
+  // Hand-maintained lists on both sides; a var in one but not the other never
+  // reaches the container. That already shipped once, with MAUDE_ADMIN_PASSWORD.
+  assert.match(renderCompose(ok({ ...BASE, s3: S3 })), /MAUDE_BACKUP_PREFIX/);
+});
+
+test('no object storage means no namespace to write', () => {
+  const env = renderEnv(envEntries(ok(BASE), { hubSecret: 'x', adminPassword: 'y'.repeat(12) }));
+  assert.ok(!/MAUDE_BACKUP_PREFIX/.test(env));
+});
+
+test('a namespace can never escape its own keyspace', () => {
+  // It becomes an object-key prefix, so `/` and `..` have to be GONE rather
+  // than escaped — otherwise a namespace could address another hub's keys.
+  const cfg = ok({ ...BASE, s3: S3, backupPrefix: '../../Other Hub/' });
+  assert.equal(cfg.backupPrefix, 'other-hub');
+  assert.ok(!cfg.backupPrefix.includes('/'));
+  assert.ok(!cfg.backupPrefix.includes('..'));
+});
+
+// ------------------------------------------------------- BYO identity (C6)
+
+const OIDC = {
+  issuer: 'https://acme.eu.auth0.com',
+  clientId: 'cid',
+  clientSecret: 'shh',
+  domains: 'acme.com',
+};
+
+test('OIDC reaches BOTH .env and the container', () => {
+  // Hand-maintained lists on both sides. A var in one but not the other never
+  // arrives — that already shipped once, with MAUDE_ADMIN_PASSWORD.
+  const cfg = ok({ ...BASE, oidc: OIDC });
+  const env = renderEnv(envEntries(cfg, { hubSecret: 'x', adminPassword: 'y'.repeat(12) }));
+  const compose = renderCompose(cfg);
+  for (const key of [
+    'HUB_OIDC_MODE',
+    'HUB_OIDC_ISSUER',
+    'HUB_OIDC_CLIENT_ID',
+    'HUB_OIDC_CLIENT_SECRET',
+    'HUB_OIDC_ALLOWED_DOMAINS',
+  ]) {
+    assert.ok(env.includes(`${key}=`), `${key} missing from .env`);
+    assert.match(compose, new RegExp(`${key}: \\$\\{${key}\\}`), `${key} not forwarded`);
+  }
+});
+
+test('the allowed-domain list is required — it is a filter, never a grant', () => {
+  const r = validateWorkspaceConfig({ ...BASE, oidc: { ...OIDC, domains: '' } });
+  assert.match(r.errors.join(' '), /oidc.domains is required/);
+});
+
+test('an unrecognised mode falls back to hybrid rather than to strict', () => {
+  // Getting this backwards would lock an operator out of their own box on a
+  // typo. hybrid keeps the password door open.
+  assert.equal(ok({ ...BASE, oidc: { ...OIDC, mode: 'stric' } }).oidc.mode, 'hybrid');
+  assert.equal(ok({ ...BASE, oidc: { ...OIDC, mode: 'strict' } }).oidc.mode, 'strict');
+});
+
+test('no OIDC configured leaves no empty variables to misread', () => {
+  const env = renderEnv(envEntries(ok(BASE), { hubSecret: 'x', adminPassword: 'y'.repeat(12) }));
+  assert.ok(!/HUB_OIDC/.test(env));
+  assert.ok(!/HUB_OIDC/.test(renderCompose(ok(BASE))));
+});
+
+test('.env values are quoted, and a newline in a secret is refused (F8)', () => {
+  // A `$` must not be re-interpolated by compose, and a newline must not inject
+  // an extra line that a re-run would then persist.
+  const env = renderEnv(
+    envEntries(ok({ ...BASE, s3: { ...(OIDC && S3), secretAccessKey: 'a$b' } }), {
+      hubSecret: 'x',
+      adminPassword: 'y'.repeat(12),
+    })
+  );
+  assert.match(env, /MAUDE_S3_SECRET_ACCESS_KEY='a\$b'/, 'a $ is single-quoted, not interpolated');
+  assert.throws(
+    () => renderEnv([{ key: 'X', value: 'a\nMAUDE_ALLOW_EMPTY_START=1' }]),
+    /newline or control character/
+  );
+});
+
+// M3 (AWS spike, 2026-08-20) — the seed URL carries a live GitHub PAT in
+// userinfo, and `workspace-up` printed it verbatim, `--dry-run` included. The
+// token reached SSM command history, CloudTrail and a session transcript, and
+// had to be revoked. `.env` is 0600; stdout is not.
+test('a seed URL never carries its credential into anything printable', () => {
+  assert.equal(
+    safeSeedUrl('https://x-access-token:SECRET123@github.com/o/r.git'),
+    'https://***@github.com/o/r.git'
+  );
+  // Nothing to hide, nothing changed — the operator still reads host and path.
+  assert.equal(safeSeedUrl('https://github.com/o/r.git'), 'https://github.com/o/r.git');
+  assert.equal(safeSeedUrl('git@github.com:o/r.git'), 'git@github.com:o/r.git');
+  assert.equal(safeSeedUrl(null), null);
+  assert.equal(safeSeedUrl(''), null);
+  // Unparseable is refused wholesale rather than echoed on the chance it is clean.
+  assert.equal(safeSeedUrl('https://user:pw@ho st/r.git'), '<unparseable seed url>');
+});
+
+// feature-cloud-export-render-workers (DDR-230) — the optional render sidecar.
+test('--render wires the sidecar end to end; without it nothing render-shaped appears', () => {
+  const cfg = ok({ ...BASE, render: true });
+  const yaml = renderCompose(cfg);
+  assert.match(yaml, /ghcr\.io\/1agh\/maude-render/, 'the sidecar service renders');
+  assert.match(yaml, /MAUDE_RENDER_CANVAS_ORIGINS: http:\/\/hub:1234/, 'origin allowlist pins the hub');
+  assert.match(yaml, /MAUDE_RENDER_URL/, 'the hub is told where to dispatch');
+  const env = renderEnv(
+    envEntries(cfg, { hubSecret: 'x', adminPassword: 'y'.repeat(12), renderSecret: 'rsec' })
+  );
+  assert.match(env, /MAUDE_RENDER_SECRET='?rsec'?/, 'its own secret, in .env');
+  assert.match(env, /MAUDE_RENDER_URL=/, '.env carries the dispatch URL');
+  assert.match(env, /MAUDE_RENDER_CANVAS_BASE=/, '.env carries the canvas base');
+  assert.ok(
+    verificationPlan(cfg).some((s) => s.id === 'render-health'),
+    'the sidecar must prove itself before the run says it worked'
+  );
+
+  const plain = ok(BASE);
+  assert.ok(!renderCompose(plain).includes('maude-render'), 'no sidecar without --render');
+  assert.ok(
+    !verificationPlan(plain).some((s) => s.id === 'render-health'),
+    'no phantom verification step without the sidecar'
+  );
+});
+
+// M7 (AWS spike, 2026-08-20) — the studio splits the canvas iframe onto its
+// own origin (DDR-054), the hub routes it by Host, the child env forwards
+// MAUDE_PUBLIC_CANVAS_ORIGIN — every layer was built, and NO deployment path
+// ever set the variable. The stack came up, all eight verification steps
+// passed, and every canvas was a blank frame pointing at
+// `http://localhost:<container port>`. The spike read that as "workspaces
+// cannot render by design" and planned around it.
+test('a canvas domain renders the full chain: .env, compose passthrough, Caddy site', () => {
+  const cfg = ok({ ...BASE, canvasDomain: 'canvas.acme.com' });
+  assert.equal(cfg.canvasDomain, 'canvas.acme.com');
+
+  const env = renderEnv(envEntries(cfg, { hubSecret: 'x', adminPassword: 'y'.repeat(12) }));
+  assert.match(env, /CANVAS_DOMAIN='canvas\.acme\.com'/);
+  assert.match(env, /MAUDE_PUBLIC_CANVAS_ORIGIN='https:\/\/canvas\.acme\.com'/);
+
+  // Rendered into .env AND forwarded to the hub container — the drift between
+  // those two lists is the exact shape that shipped MAUDE_ADMIN_PASSWORD half-wired.
+  const compose = renderCompose(cfg);
+  assert.match(compose, /MAUDE_PUBLIC_CANVAS_ORIGIN: \$\{MAUDE_PUBLIC_CANVAS_ORIGIN\}/);
+  assert.match(compose, /CANVAS_DOMAIN: \$\{CANVAS_DOMAIN\}/);
+
+  // Caddy serves the second hostname; the hub routes by Host, so the block
+  // needs no port knowledge — but without it there is no name and no cert.
+  const caddy = renderCaddyfile(cfg);
+  assert.match(caddy, /\{\$CANVAS_DOMAIN\} \{/);
+});
+
+test('no canvas domain leaves no empty canvas variables to misread', () => {
+  const cfg = ok(BASE);
+  assert.equal(cfg.canvasDomain, null);
+  const env = renderEnv(envEntries(cfg, { hubSecret: 'x', adminPassword: 'y'.repeat(12) }));
+  assert.ok(!/CANVAS_DOMAIN|MAUDE_PUBLIC_CANVAS_ORIGIN/.test(env));
+  assert.ok(!/CANVAS_DOMAIN/.test(renderCompose(cfg)));
+  assert.ok(!/CANVAS_DOMAIN/.test(renderCaddyfile(cfg)));
+});
+
+test('the canvas domain must be a REAL second name — same-origin defeats the split', () => {
+  const dup = validateWorkspaceConfig({ ...BASE, canvasDomain: BASE.domain });
+  assert.equal(dup.ok, false);
+  assert.ok(dup.errors.some((e) => /must differ from domain/.test(e)));
+
+  const bad = validateWorkspaceConfig({ ...BASE, canvasDomain: 'not a hostname' });
+  assert.equal(bad.ok, false);
+
+  // Scheme + trailing junk normalize away, same as the main domain.
+  const cfg = ok({ ...BASE, canvasDomain: 'https://Canvas.Acme.com/' });
+  assert.equal(cfg.canvasDomain, 'canvas.acme.com');
+});
+
+test('local mode keeps the canvas name loopback-only and plain HTTP', () => {
+  const cfg = ok({ local: true, adminEmail: BASE.adminEmail, canvasDomain: 'canvas.localhost' });
+  const env = renderEnv(envEntries(cfg, { hubSecret: 'x', adminPassword: 'y'.repeat(12) }));
+  assert.match(env, /MAUDE_PUBLIC_CANVAS_ORIGIN='http:\/\/canvas\.localhost'/);
+  assert.match(renderCaddyfile(cfg), /http:\/\/\{\$CANVAS_DOMAIN\} \{/);
+
+  const bad = validateWorkspaceConfig({
+    local: true,
+    adminEmail: BASE.adminEmail,
+    canvasDomain: 'canvas.acme.com',
+  });
+  assert.equal(bad.ok, false);
+});