@1agh/maude 0.48.0 → 0.49.0

package/cli/commands/hub.test.mjs

@@ -32,7 +32,20 @@ function withDataDir(fn) {
 test('hub help prints subcommand summary on stdout', () => {
   const res = runCli(['hub', 'help']);
   assert.equal(res.status, 0, res.stderr);
-  assert.match(res.stdout, /maude hub <serve\|token\|status\|deploy>/);
+  // Every verb must appear in the usage header — a subcommand that exists but
+  // isn't listed is one nobody finds.
+  assert.match(res.stdout, /maude hub <[a-z|-]+> \[options\]/);
+  for (const verb of [
+    'serve',
+    'token',
+    'status',
+    'deploy',
+    'backup',
+    'restore-drill',
+    'asset-check',
+  ]) {
+    assert.ok(res.stdout.includes(verb), `usage must mention "${verb}"`);
+  }
   assert.match(res.stdout, /token generate --label NAME/);
   assert.match(res.stdout, /token rotate --label NAME/);
   assert.match(res.stdout, /deploy <fly\|docker>/);

package/cli/lib/cell-plan.mjs

@@ -0,0 +1,302 @@
+// `maude cell` — the pure planning layer. Cloud Phase 5 Task 2.
+//
+// Naming, addressing, isolation boundaries, and the teardown sweep, as
+// functions of their inputs. No Cloudflare API calls; `cli/commands/cell.mjs`
+// makes those.
+//
+// Why this is worth separating (same argument as workspace-plan.mjs, and it
+// matters more here): the failure modes of a multi-tenant provisioner are
+// almost entirely NAMING and SCOPE mistakes — a tenant id that escapes its R2
+// prefix, a hostname that collides with another tenant's, a destroy that
+// misses one resource and leaves an orphan billing forever. All of those are
+// decisions, and decisions can be tested exhaustively without a paid account.
+
+/**
+ * A tenant id is not cosmetic. It becomes:
+ *   • the R2 key prefix `tenants/<id>/`,
+ *   • the subdomain `<id>.cloud.maude.sh`,
+ *   • the Durable Object name,
+ *   • the container instance name.
+ *
+ * So it has to satisfy the intersection of DNS labels, R2 keys, and Cloudflare
+ * resource names, and it must be impossible to construct one that reads as
+ * another tenant's namespace.
+ */
+const TENANT_ID_RE = /^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])?$/;
+
+/**
+ * Reserved for the platform itself. `api.cloud.maude.sh` belonging to a tenant
+ * who signed up early would be a phishing surface handed out for free.
+ */
+const RESERVED_IDS = new Set([
+  'api',
+  'www',
+  'admin',
+  'app',
+  'dashboard',
+  'status',
+  'docs',
+  'help',
+  'support',
+  'billing',
+  'account',
+  'accounts',
+  'login',
+  'signin',
+  'signup',
+  'auth',
+  'cdn',
+  'assets',
+  'static',
+  'mail',
+  'smtp',
+  'ns',
+  'ns1',
+  'ns2',
+  'internal',
+  'system',
+  'maude',
+  'cloud',
+  'test',
+  'staging',
+  'prod',
+  'production',
+]);
+
+export function validateTenantId(raw) {
+  const id = String(raw ?? '')
+    .trim()
+    .toLowerCase();
+  if (!id) return { ok: false, error: 'a project id is required' };
+  if (id.length > 63) return { ok: false, error: 'project id must be at most 63 characters' };
+  if (!TENANT_ID_RE.test(id)) {
+    return {
+      ok: false,
+      error:
+        'project id must be lowercase letters, digits and inner hyphens ' +
+        '(it becomes a hostname, an R2 key prefix and a Durable Object name)',
+    };
+  }
+  if (RESERVED_IDS.has(id)) {
+    // Handing out `api.cloud.maude.sh` to whoever signs up first is a phishing
+    // surface given away for free.
+    return { ok: false, error: `"${id}" is reserved for the platform` };
+  }
+  if (id.startsWith('xn--')) {
+    return { ok: false, error: 'punycode-style ids are not allowed (homograph risk)' };
+  }
+  return { ok: true, id };
+}
+
+export const DEFAULT_ZONE = 'cloud.maude.sh';
+
+/**
+ * Every name a cell occupies, derived from one id so they cannot drift apart.
+ * Drift is how a destroy misses a resource.
+ */
+export function cellNames(id, { zone = DEFAULT_ZONE } = {}) {
+  const check = validateTenantId(id);
+  if (!check.ok) throw new Error(`invalid project id: ${check.error}`);
+  const tenant = check.id;
+  return {
+    tenant,
+    hostname: `${tenant}.${zone}`,
+    /** Trailing slash included: it is what makes prefix matching exact. */
+    r2Prefix: `tenants/${tenant}/`,
+    durableObject: `cell-${tenant}`,
+    container: `maude-cell-${tenant}`,
+    /** Per-cell scoped token name — never the account master key (DDR-164). */
+    r2TokenName: `maude-cell-${tenant}-r2`,
+  };
+}
+
+/**
+ * True when `key` belongs to `tenant`'s prefix.
+ *
+ * Exists as its own function because "starts with the prefix" is subtly wrong
+ * without the trailing slash: `tenants/acme` would match `tenants/acme-evil/…`.
+ * That single character is the entire isolation boundary between two
+ * customers' data.
+ */
+export function keyBelongsToTenant(key, tenant) {
+  const names = cellNames(tenant);
+  return typeof key === 'string' && key.startsWith(names.r2Prefix);
+}
+
+/**
+ * The resources a cell owns, in the order `destroy` must remove them.
+ *
+ * Order is deliberate: stop routing FIRST, then compute, then credentials,
+ * then data. Deleting data while the hostname still resolves gives a live
+ * endpoint serving a half-deleted project; revoking the token before stopping
+ * the container gives a running cell erroring in a loop.
+ *
+ * `retainable` marks what a SUSPEND keeps. Suspension stops a cell; it does not
+ * delete state (DDR-193 §3) — the 30-day retention and export-before-teardown
+ * guarantee live here.
+ */
+export function cellResources(id, { zone = DEFAULT_ZONE } = {}) {
+  const n = cellNames(id, { zone });
+  return [
+    {
+      kind: 'dns',
+      name: n.hostname,
+      why: 'stop routing first — otherwise a half-deleted project stays reachable',
+      retainable: false,
+    },
+    {
+      kind: 'worker-route',
+      name: `${n.hostname}/*`,
+      why: 'the ingress route that maps the hostname to this cell’s Durable Object',
+      retainable: false,
+    },
+    {
+      kind: 'container',
+      name: n.container,
+      why: 'the running cell',
+      retainable: false,
+    },
+    {
+      kind: 'durable-object',
+      name: n.durableObject,
+      why: 'lifecycle + hibernation state for this project',
+      retainable: false,
+    },
+    {
+      kind: 'r2-token',
+      name: n.r2TokenName,
+      why: 'the per-cell scoped credential; revoked after compute is gone, never before',
+      retainable: false,
+    },
+    {
+      kind: 'r2-prefix',
+      name: n.r2Prefix,
+      why: 'the tenant’s data — retained through suspension, deleted only after export',
+      retainable: true,
+    },
+  ];
+}
+
+/**
+ * What `destroy` must verify is gone. A destroy that leaves an orphan bills
+ * forever and is invisible until the invoice, so the sweep is part of the
+ * operation rather than a separate cleanup task somebody remembers to run.
+ */
+export function destroySweep(id, { zone = DEFAULT_ZONE, purgeData = false } = {}) {
+  return cellResources(id, { zone }).filter((r) => purgeData || !r.retainable);
+}
+
+/**
+ * The tenant lifecycle from DDR-193 §3, as a machine.
+ *
+ * Encoded rather than implied because the ONE transition that must never exist
+ * is `* → purged` without passing through `exported`: there is no path from
+ * "stopped paying" to "your designs are gone" that skips "you were handed your
+ * files".
+ */
+const TRANSITIONS = {
+  pending: ['active', 'purged'],
+  active: ['past_due', 'suspended'],
+  past_due: ['active', 'suspended'],
+  suspended: ['active', 'exported'],
+  exported: ['active', 'purged'],
+  purged: [],
+};
+
+export function canTransition(from, to) {
+  return (TRANSITIONS[from] ?? []).includes(to);
+}
+
+export function assertTransition(from, to) {
+  if (!TRANSITIONS[from]) throw new Error(`unknown state "${from}"`);
+  if (!TRANSITIONS[to]) throw new Error(`unknown state "${to}"`);
+  if (!canTransition(from, to)) {
+    const extra =
+      to === 'purged' && from !== 'exported'
+        ? ' — a tenant must be EXPORTED before purge (DDR-193 §3): there is no path from ' +
+          '"stopped paying" to "your designs are gone" that skips "you were handed your files"'
+        : '';
+    throw new Error(`illegal transition ${from} → ${to}${extra}`);
+  }
+  return to;
+}
+
+export function lifecycleStates() {
+  return Object.keys(TRANSITIONS);
+}
+
+/**
+ * The next state on the shortest LEGAL path from `from` to `to`, or null when
+ * no path exists.
+ *
+ * Needed because a desired state is often not reachable in one hop and that is
+ * perfectly ordinary rather than an error: a `pending` tenant whose payment is
+ * already failing did subscribe, so the truthful route is
+ * `pending → active → past_due`, and a `suspended` tenant who resubscribes with
+ * a failing card goes `suspended → active → past_due`.
+ *
+ * Walking the path beats jumping to the destination, because every hop stays
+ * inside the machine — including the one hop the machine exists to forbid.
+ * `exported` is the only door to `purged` no matter how the search runs.
+ */
+export function stepToward(from, to) {
+  if (from === to) return null;
+  if (!TRANSITIONS[from] || !TRANSITIONS[to]) return null;
+  const queue = [[from, null]];
+  const seen = new Set([from]);
+  while (queue.length > 0) {
+    const [state, firstHop] = queue.shift();
+    for (const next of TRANSITIONS[state]) {
+      if (seen.has(next)) continue;
+      const hop = firstHop ?? next;
+      if (next === to) return hop;
+      seen.add(next);
+      queue.push([next, hop]);
+    }
+  }
+  return null;
+}
+
+/**
+ * Render the container + ingress config for one cell.
+ *
+ * Kept as data (not a template string) so a test can assert a specific field
+ * without matching a whole file, and so the control plane in Phase 7 can build
+ * the same object without re-parsing TOML.
+ */
+export function cellConfig(
+  id,
+  { zone = DEFAULT_ZONE, memoryMib = 2048, imageTag = 'latest' } = {}
+) {
+  const n = cellNames(id, { zone });
+  if (!Number.isInteger(memoryMib) || memoryMib < 512 || memoryMib > 4096) {
+    // Containers GA caps at 4 GiB; below 512 MiB the hub cannot hold a
+    // reasonable working set. Both bounds are refusals, not clamps — silently
+    // giving someone less memory than they asked for is a support ticket
+    // nobody can diagnose.
+    throw new Error('memoryMib must be an integer between 512 and 4096');
+  }
+  return {
+    name: n.container,
+    image: `ghcr.io/1agh/maude-cell:${imageTag}`,
+    instanceType: { memoryMib, vcpu: 0.5 },
+    // Scale to zero: an idle cell should cost approximately nothing under
+    // Active-CPU pricing, which is the whole economic premise (DDR-193 §1).
+    lifecycle: { scaleToZero: true, wakeOn: ['http', 'websocket'], idleTimeoutSeconds: 300 },
+    durableObject: n.durableObject,
+    route: `${n.hostname}/*`,
+    env: {
+      MAUDE_TENANT_ID: n.tenant,
+      HUB_PUBLIC_URL: `https://${n.hostname}`,
+      HUB_WORKSPACE_MODE: '1',
+      MAUDE_WORKSPACE_MODE: '1',
+      // Caddy is gone — TLS terminates at the Cloudflare edge, and the Worker
+      // is the only thing that can reach the container.
+      HUB_TRUSTED_PROXIES: '10.0.0.0/8,172.16.0.0/12,fd00::/8',
+    },
+    // Secrets are NAMED here, never valued: this object is logged, diffed and
+    // stored by the control plane.
+    secrets: ['HUB_SECRET', 'MAUDE_S3_ACCESS_KEY_ID', 'MAUDE_S3_SECRET_ACCESS_KEY'],
+    r2: { prefix: n.r2Prefix, tokenName: n.r2TokenName },
+  };
+}

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

@@ -0,0 +1,225 @@
+// Cloud Phase 5 Task 2 — cell naming, isolation, teardown and lifecycle.
+//
+// A multi-tenant provisioner fails at NAMING and SCOPE: an id that escapes its
+// R2 prefix, a hostname handed to the wrong party, a destroy that leaves an
+// orphan billing forever. Those are decisions, and decisions test exhaustively
+// without a paid Cloudflare account — which is the point of this file existing
+// before the account does.
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import {
+  assertTransition,
+  canTransition,
+  cellConfig,
+  cellNames,
+  cellResources,
+  destroySweep,
+  keyBelongsToTenant,
+  lifecycleStates,
+  validateTenantId,
+} from './cell-plan.mjs';
+
+// ------------------------------------------------------------------ naming
+
+test('a well-formed id is accepted and lowercased', () => {
+  assert.deepEqual(validateTenantId('  Alligators '), { ok: true, id: 'alligators' });
+  assert.deepEqual(validateTenantId('acme-design-2'), { ok: true, id: 'acme-design-2' });
+});
+
+test('ids that would break a hostname, an R2 key or a DO name are refused', () => {
+  for (const bad of [
+    '',
+    ' ',
+    '-leading',
+    'trailing-',
+    'has_underscore',
+    'has.dot',
+    'has space',
+    'UPPER-ONLY-OK-BUT/slash',
+    '../escape',
+    'tenants/other',
+    'a'.repeat(64),
+    'emoji-🙂',
+  ]) {
+    assert.equal(validateTenantId(bad).ok, false, `${JSON.stringify(bad)} must be refused`);
+  }
+});
+
+test('platform names are reserved', () => {
+  // `api.cloud.maude.sh` belonging to whoever signs up first is a phishing
+  // surface given away for free.
+  for (const reserved of ['api', 'www', 'admin', 'billing', 'login', 'assets', 'maude']) {
+    const res = validateTenantId(reserved);
+    assert.equal(res.ok, false);
+    assert.match(res.error, /reserved/);
+  }
+});
+
+test('punycode-style ids are refused (homograph risk)', () => {
+  assert.equal(validateTenantId('xn--80ak6aa92e').ok, false);
+});
+
+test('every name a cell occupies derives from ONE id', () => {
+  // Drift between these is how a destroy misses a resource.
+  const n = cellNames('alligators');
+  assert.deepEqual(n, {
+    tenant: 'alligators',
+    hostname: 'alligators.cloud.maude.sh',
+    r2Prefix: 'tenants/alligators/',
+    durableObject: 'cell-alligators',
+    container: 'maude-cell-alligators',
+    r2TokenName: 'maude-cell-alligators-r2',
+  });
+  assert.throws(() => cellNames('../evil'), /invalid project id/);
+});
+
+// --------------------------------------------------------------- isolation
+
+test('the trailing slash IS the isolation boundary between two customers', () => {
+  // Without it, `tenants/acme` matches `tenants/acme-evil/secret.png`. One
+  // character, and it is the entire boundary.
+  assert.equal(keyBelongsToTenant('tenants/acme/assets/deadbeef.png', 'acme'), true);
+  assert.equal(keyBelongsToTenant('tenants/acme/', 'acme'), true);
+  assert.equal(keyBelongsToTenant('tenants/acme-evil/assets/x.png', 'acme'), false);
+  assert.equal(keyBelongsToTenant('tenants/acmex/x.png', 'acme'), false);
+  assert.equal(keyBelongsToTenant('tenants/other/x.png', 'acme'), false);
+  assert.equal(keyBelongsToTenant('backups/hub.db.gz', 'acme'), false);
+  assert.equal(keyBelongsToTenant('', 'acme'), false);
+  assert.equal(keyBelongsToTenant(null, 'acme'), false);
+});
+
+test('two tenants can never share a prefix, hostname or DO name', () => {
+  const a = cellNames('acme');
+  const b = cellNames('acme-evil');
+  assert.notEqual(a.r2Prefix, b.r2Prefix);
+  assert.notEqual(a.hostname, b.hostname);
+  assert.notEqual(a.durableObject, b.durableObject);
+  assert.ok(!b.r2Prefix.startsWith(a.r2Prefix));
+});
+
+// ---------------------------------------------------------------- teardown
+
+test('destroy removes routing first and data last', () => {
+  // Deleting data while the hostname resolves leaves a live endpoint serving a
+  // half-deleted project; revoking the credential before stopping the container
+  // leaves a cell erroring in a loop.
+  const order = cellResources('acme').map((r) => r.kind);
+  assert.deepEqual(order, [
+    'dns',
+    'worker-route',
+    'container',
+    'durable-object',
+    'r2-token',
+    'r2-prefix',
+  ]);
+  assert.ok(order.indexOf('dns') < order.indexOf('container'));
+  assert.ok(order.indexOf('container') < order.indexOf('r2-token'));
+  assert.ok(order.indexOf('r2-token') < order.indexOf('r2-prefix'));
+});
+
+test('every resource explains why it is in the list', () => {
+  for (const r of cellResources('acme')) {
+    assert.ok(r.why && r.why.length > 15, `${r.kind} needs a reason`);
+    assert.ok(r.name, `${r.kind} needs a name`);
+  }
+});
+
+test('a suspend keeps the DATA and drops everything else', () => {
+  // Suspension stops a cell; it does not delete state (DDR-193 §3).
+  const suspend = destroySweep('acme').map((r) => r.kind);
+  assert.ok(!suspend.includes('r2-prefix'), 'suspension must never delete the tenant’s data');
+  assert.ok(suspend.includes('container'));
+
+  const purge = destroySweep('acme', { purgeData: true }).map((r) => r.kind);
+  assert.ok(purge.includes('r2-prefix'), 'a full purge does remove it');
+  assert.equal(purge.length, cellResources('acme').length);
+});
+
+// --------------------------------------------------------------- lifecycle
+
+test('the state machine matches DDR-193 §3', () => {
+  assert.deepEqual(lifecycleStates(), [
+    'pending',
+    'active',
+    'past_due',
+    'suspended',
+    'exported',
+    'purged',
+  ]);
+  assert.equal(canTransition('pending', 'active'), true);
+  assert.equal(canTransition('active', 'past_due'), true);
+  assert.equal(canTransition('past_due', 'active'), true, 'paying again must resurrect');
+  assert.equal(canTransition('past_due', 'suspended'), true);
+  assert.equal(canTransition('suspended', 'active'), true, 'suspension must be reversible');
+  assert.equal(canTransition('suspended', 'exported'), true);
+  assert.equal(canTransition('exported', 'purged'), true);
+});
+
+test('NOTHING reaches purged without passing through exported', () => {
+  // The one transition that must never exist: there is no path from "stopped
+  // paying" to "your designs are gone" that skips "you were handed your files".
+  for (const from of ['active', 'past_due', 'suspended']) {
+    assert.equal(canTransition(from, 'purged'), false, `${from} → purged must be illegal`);
+    assert.throws(() => assertTransition(from, 'purged'), /must be EXPORTED before purge/);
+  }
+  // `pending → purged` is allowed: a cell that never became active has no
+  // customer data to hand back.
+  assert.equal(canTransition('pending', 'purged'), true);
+});
+
+test('purged is terminal, and unknown states are refused', () => {
+  for (const to of lifecycleStates()) {
+    assert.equal(canTransition('purged', to), false);
+  }
+  assert.throws(() => assertTransition('nonsense', 'active'), /unknown state/);
+  assert.throws(() => assertTransition('active', 'deleted'), /unknown state/);
+});
+
+// ------------------------------------------------------------------ config
+
+test('the rendered cell config carries the containment flags', () => {
+  const cfg = cellConfig('alligators');
+  assert.equal(cfg.env.MAUDE_WORKSPACE_MODE, '1');
+  assert.equal(cfg.env.HUB_WORKSPACE_MODE, '1');
+  assert.equal(cfg.env.MAUDE_TENANT_ID, 'alligators');
+  assert.equal(cfg.env.HUB_PUBLIC_URL, 'https://alligators.cloud.maude.sh');
+  assert.equal(cfg.route, 'alligators.cloud.maude.sh/*');
+  assert.equal(cfg.r2.prefix, 'tenants/alligators/');
+});
+
+test('secrets are NAMED, never valued', () => {
+  // This object is logged, diffed and stored by the control plane.
+  const cfg = cellConfig('acme');
+  assert.deepEqual(cfg.secrets, [
+    'HUB_SECRET',
+    'MAUDE_S3_ACCESS_KEY_ID',
+    'MAUDE_S3_SECRET_ACCESS_KEY',
+  ]);
+  for (const value of Object.values(cfg.env)) {
+    assert.ok(!/secret|password|key/i.test(String(value)), 'no secret may appear in env values');
+  }
+});
+
+test('an idle cell scales to zero and wakes on connect', () => {
+  // The economic premise: an idle cell costs approximately nothing under
+  // Active-CPU pricing (DDR-193 §1).
+  const cfg = cellConfig('acme');
+  assert.equal(cfg.lifecycle.scaleToZero, true);
+  assert.deepEqual(cfg.lifecycle.wakeOn, ['http', 'websocket']);
+  assert.ok(cfg.lifecycle.idleTimeoutSeconds > 0);
+});
+
+test('memory outside the platform bounds is REFUSED, not clamped', () => {
+  // Silently giving someone less memory than they asked for is a support
+  // ticket nobody can diagnose.
+  assert.equal(cellConfig('acme', { memoryMib: 4096 }).instanceType.memoryMib, 4096);
+  for (const bad of [0, 256, 8192, 1024.5, '2048']) {
+    assert.throws(() => cellConfig('acme', { memoryMib: bad }), /between 512 and 4096/);
+  }
+});
+
+test('the image tag is pinnable', () => {
+  assert.match(cellConfig('acme', { imageTag: 'v0.48.0' }).image, /maude-cell:v0\.48\.0$/);
+});

package/cli/lib/gitignore-block.mjs

@@ -20,7 +20,7 @@ export const END_MARKER = '# maude:end';
  * The runtime paths Maude ignores under the design root, relative to repo root.
  * `designRel` defaults to `.design` (the only design root in v1.1 defaults).
  */
-export function buildBlock(designRel = '.design') {
+export function buildBlock(designRel = '.design', { s3Assets = false } = {}) {
   const root = designRel.replace(/\/+$/, '');
   // The canonical IGNORED set is the DDR-115 runtime-state taxonomy — kept in
   // lockstep with `apps/studio/git/service.ts` (isMaudeRuntimeState backstop)
@@ -51,6 +51,17 @@ export function buildBlock(designRel = '.design') {
     `${root}/_chat/`, // ACP transcripts (per-machine)
     `${root}/_untrusted/`, // hub-synced untrusted file mirror (DDR-054)
     `${root}/_comments/`, // hub-sync-only collab comments (DDR-102/DDR-115 — never git)
+    // Cloud Phase 3 Task 2 — when an S3/R2 asset lane is configured, binary
+    // media lives in the bucket and must STOP entering git: a 60 MB clip is
+    // 60 MB in every clone forever, and delta compression does nothing for it.
+    // Off by default, because without a bucket the only copy of an asset is the
+    // one in the repo and ignoring it would delete people's media on the next
+    // clean checkout.
+    ...(s3Assets
+      ? [
+          `${root}/assets/`, // binary media lives in the S3/R2 bucket (DDR-192 §1)
+        ]
+      : []),
     // kgai knowledge-graph projection (repo-root, NOT under the design root) —
     // per-machine append-only store, rebuilds from the remote on `kg sync`
     // (feature-kgai-ecosystem-integration, DDR-115). kgai itself also ignores it.