@1agh/maude 0.48.0 → 0.49.1

package/apps/studio/api.ts

@@ -5,7 +5,7 @@ import crypto from 'node:crypto';
 import type { Dirent } from 'node:fs';
 import { lstat, mkdir, readdir, readFile, rename, rm, stat as statp } from 'node:fs/promises';
 import path from 'node:path';
-
+import { createAssetMirror, s3ConfigFromEnv } from './assets-s3.ts';
 import { renderBriefBoard, validateCanvasName } from './canvas-create.ts';
 import {
   type AssembleClip,
@@ -1646,6 +1646,12 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
   //     user input, but a poisoned designRoot must still not escape).
   // Running total of bytes this server instance has actually written (post-dedupe).
   let assetBytesWritten = 0;
+  // S3/R2 asset lane (Cloud Phase 3 Task 2). Unconfigured by default — a local
+  // project and a single-box self-hoster both work with no bucket at all.
+  const assetMirror = createAssetMirror(s3ConfigFromEnv());
+  if (assetMirror.configured) {
+    console.log(`[assets] mirroring new assets to ${assetMirror.describe}`);
+  }
 
   /**
    * DDR-148 — the streaming write path behind `POST /_api/asset`. Reads the
@@ -1777,7 +1783,17 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       }
       await rename(tmpAbs, fileAbs);
       assetBytesWritten += total;
-      return { ok: true, path: `assets/${name}` };
+      const rel = `assets/${name}`;
+      // S3/R2 lane (Cloud Phase 3) — mirror the bytes so a second machine can
+      // resolve them without the file riding git. Deliberately awaited but
+      // never able to fail the save: the asset is already on disk, the mirror
+      // is the redundant copy, and `maude hub asset-check` reconciles a miss.
+      // Only a genuinely NEW file reaches here, so this is not re-uploading on
+      // every dedupe hit.
+      if (assetMirror.configured) {
+        void assetMirror.push(rel, new Uint8Array(await Bun.file(fileAbs).arrayBuffer()));
+      }
+      return { ok: true, path: rel };
     } catch (err) {
       await cleanup();
       return { ok: false, status: 500, error: err instanceof Error ? err.message : 'write failed' };

package/apps/studio/assets-s3.ts

@@ -0,0 +1,291 @@
+// S3/R2 asset lane — Cloud Phase 3 Task 2.
+//
+// THE PROBLEM. Binary media currently rides git. A 60 MB video in a design repo
+// is 60 MB in every clone, forever, and git's delta compression does nothing for
+// it. DDR-148's line that "video rides git and hub sync" describes an intent the
+// code never made true cross-machine; this lane is what makes heavy media
+// actually reach a second machine without bloating history.
+//
+// THE SHAPE. Assets stay CONTENT-ADDRESSED exactly as they are today —
+// `assets/<sha8>.<ext>`. That single property is what makes every operation
+// here safe:
+//
+//   • push is idempotent — the same bytes produce the same key, so a re-upload
+//     is a no-op rather than a duplicate;
+//   • there is no invalidation problem — a key's content never changes, so a
+//     cached copy is never stale;
+//   • pull is verifiable — the bytes must hash back to the key they came from,
+//     which is what lets us accept them from a semi-trusted hub (DDR-054).
+//
+// NEVER GARBAGE-COLLECTED. A canvas in git history can reference an asset that
+// no current canvas does, so "unreferenced" never means "unreachable". Bucket
+// lifecycle/expiry rules MUST be off for the `assets/` prefix — an expired
+// object is a permanently broken canvas with no recovery path.
+//
+// NO PRESIGNED URLS IN A CANVAS. The canvas origin's CSP is `img-src 'self'`
+// (DDR-063/DDR-054) and stays that way: media is fetched through the hub's
+// authenticated proxy and served same-origin. A presigned URL would also be a
+// bearer credential embedded in tenant-authored content — exactly the thing the
+// canvas must never hold.
+
+import { createHash, createHmac } from 'node:crypto';
+
+// ---------------------------------------------------------------- SigV4
+
+const sha256Hex = (data: string | Uint8Array): string =>
+  createHash('sha256').update(data).digest('hex');
+const hmac = (key: string | Buffer, data: string): Buffer =>
+  createHmac('sha256', key).update(data).digest();
+
+export interface S3Config {
+  endpoint: string;
+  bucket: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  region: string;
+  sessionToken?: string;
+}
+
+/**
+ * Resolve an S3 target from environment. Returns null when not configured —
+ * an unconfigured asset lane is the DEFAULT, not an error: a local project and
+ * a self-hoster on a single box both work without a bucket.
+ */
+export function s3ConfigFromEnv(env: NodeJS.ProcessEnv = process.env): S3Config | null {
+  const endpoint = env.MAUDE_S3_ENDPOINT;
+  const bucket = env.MAUDE_S3_BUCKET;
+  const accessKeyId = env.MAUDE_S3_ACCESS_KEY_ID;
+  const secretAccessKey = env.MAUDE_S3_SECRET_ACCESS_KEY;
+  if (!endpoint || !bucket || !accessKeyId || !secretAccessKey) return null;
+  return {
+    endpoint: endpoint.replace(/\/+$/, ''),
+    bucket,
+    accessKeyId,
+    secretAccessKey,
+    region: env.MAUDE_S3_REGION || 'auto',
+    ...(env.MAUDE_S3_SESSION_TOKEN ? { sessionToken: env.MAUDE_S3_SESSION_TOKEN } : {}),
+  };
+}
+
+function encodeSegment(segment: string): string {
+  return encodeURIComponent(segment).replace(
+    /[!'()*]/g,
+    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`
+  );
+}
+
+function encodeKey(key: string): string {
+  return key.split('/').map(encodeSegment).join('/');
+}
+
+export interface SignedRequest {
+  url: string;
+  headers: Record<string, string>;
+}
+
+/**
+ * AWS Signature Version 4 for one request.
+ *
+ * Hand-rolled for the same reason the hub's is (DDR-194 §7): `@aws-sdk/client-s3`
+ * is ~20 MB and several hundred packages to perform three HTTP verbs, and this
+ * code ships inside a compiled binary users install. Deliberately mirrors
+ * `apps/hub/src/s3.mjs` rather than sharing it — the two packages build
+ * independently — and `test/assets-s3.test.ts` pins them to the same signature
+ * for the same input so they cannot drift.
+ */
+export function signRequest(
+  cfg: S3Config,
+  {
+    method,
+    key,
+    body = null,
+    now = new Date(),
+  }: { method: string; key: string; body?: Uint8Array | null; now?: Date }
+): SignedRequest {
+  const url = new URL(`${cfg.endpoint}/${cfg.bucket}${key ? `/${encodeKey(key)}` : ''}`);
+  const iso = now
+    .toISOString()
+    .replace(/[-:]/g, '')
+    .replace(/\.\d{3}/, '');
+  const dateStamp = iso.slice(0, 8);
+  const payloadHash = body === null ? sha256Hex('') : sha256Hex(body);
+
+  const headers: Record<string, string> = {
+    host: url.host,
+    'x-amz-content-sha256': payloadHash,
+    'x-amz-date': iso,
+    ...(cfg.sessionToken ? { 'x-amz-security-token': cfg.sessionToken } : {}),
+  };
+  const names = Object.keys(headers).sort();
+  const canonicalHeaders = names.map((h) => `${h}:${headers[h]}\n`).join('');
+  const signedHeaders = names.join(';');
+  const canonicalRequest = [
+    method,
+    url.pathname,
+    '',
+    canonicalHeaders,
+    signedHeaders,
+    payloadHash,
+  ].join('\n');
+
+  const scope = `${dateStamp}/${cfg.region}/s3/aws4_request`;
+  const stringToSign = ['AWS4-HMAC-SHA256', iso, scope, sha256Hex(canonicalRequest)].join('\n');
+
+  let signingKey = hmac(`AWS4${cfg.secretAccessKey}`, dateStamp);
+  signingKey = hmac(signingKey, cfg.region);
+  signingKey = hmac(signingKey, 's3');
+  signingKey = hmac(signingKey, 'aws4_request');
+  const signature = createHmac('sha256', signingKey).update(stringToSign).digest('hex');
+
+  headers.authorization =
+    `AWS4-HMAC-SHA256 Credential=${cfg.accessKeyId}/${scope}, ` +
+    `SignedHeaders=${signedHeaders}, Signature=${signature}`;
+
+  return { url: url.toString(), headers };
+}
+
+// ------------------------------------------------------------ content address
+
+/** The `sha8` in `assets/<sha8>.<ext>` — first 8 hex chars of sha256. */
+export function sha8(bytes: Uint8Array): string {
+  return createHash('sha256').update(bytes).digest('hex').slice(0, 8);
+}
+
+/**
+ * Extract the sha8 from a designRoot-relative asset path, or null when the path
+ * is not a content-addressed asset (a legacy or hand-placed file).
+ *
+ * The suffix after the hash is deliberately permissive, because the real corpus
+ * is more varied than `<sha8>.<ext>`:
+ *
+ *   assets/deadbeef.png            saveAsset's own output
+ *   assets/deadbeef.photo.json     a sidecar (dotted, multi-part)
+ *   assets/deadbeef-cloud.mp4      ingested footage, hash + human label
+ *
+ * A stricter pattern silently classified the last two as "not content
+ * addressed", which made `verifyAssetBytes` refuse them — so the mirror would
+ * have rejected legitimate assets as unverifiable. Found by running
+ * `maude hub asset-check` against this repo's own design root, not by a test:
+ * the fixtures all had the tidy shape.
+ *
+ * What must NOT match is anything where the 8 hex chars are not a complete
+ * token — `deadbeef1.png` is a different name, not this asset.
+ */
+export function sha8FromAssetPath(rel: string): string | null {
+  const m = rel.match(/^assets\/([0-9a-f]{8})(?:[-.][^/]*)?$/);
+  return m?.[1] ?? null;
+}
+
+/**
+ * Verify bytes against the sha8 embedded in the path they were fetched under.
+ *
+ * This is what makes accepting an asset from a SEMI-TRUSTED hub (DDR-054) safe:
+ * the hub can refuse to serve, but it cannot substitute different bytes without
+ * the mismatch being detectable. A path with no sha8 (legacy) can't be verified
+ * and is treated as unverifiable rather than valid.
+ */
+export function verifyAssetBytes(rel: string, bytes: Uint8Array): boolean {
+  const expected = sha8FromAssetPath(rel);
+  if (!expected) return false;
+  return sha8(bytes) === expected;
+}
+
+// ------------------------------------------------------------------ the lane
+
+export interface AssetMirror {
+  readonly configured: boolean;
+  readonly describe: string;
+  /**
+   * Upload one asset. Content-addressed ⇒ idempotent, so a re-push of identical
+   * bytes is harmless. Returns false on failure rather than throwing: a failed
+   * mirror must NEVER fail the local save (the file is on disk and in git; the
+   * bucket is the redundant copy, not the authority).
+   */
+  push(rel: string, bytes: Uint8Array): Promise<boolean>;
+  /** Download one asset, or null when absent. Verifies the content address. */
+  pull(rel: string): Promise<Uint8Array | null>;
+  /** True when the object exists. Used by the dangling-pointer check. */
+  has(rel: string): Promise<boolean>;
+}
+
+const NOOP_MIRROR: AssetMirror = {
+  configured: false,
+  describe: 'none',
+  async push() {
+    return false;
+  },
+  async pull() {
+    return null;
+  },
+  async has() {
+    return false;
+  },
+};
+
+export function createAssetMirror(
+  cfg: S3Config | null,
+  { log = console }: { log?: Pick<Console, 'warn'> } = {}
+): AssetMirror {
+  if (!cfg) return NOOP_MIRROR;
+
+  const send = (method: string, key: string, body: Uint8Array | null = null) => {
+    const { url, headers } = signRequest(cfg, { method, key, body });
+    return fetch(url, { method, headers, ...(body === null ? {} : { body }) });
+  };
+
+  return {
+    configured: true,
+    describe: `s3://${cfg.bucket} @ ${cfg.endpoint}`,
+
+    async push(rel, bytes) {
+      try {
+        const res = await send('PUT', rel, bytes);
+        if (!res.ok) {
+          log.warn(`[assets] mirror PUT ${rel} failed: ${res.status}`);
+          return false;
+        }
+        return true;
+      } catch (err) {
+        // Offline, DNS, a bad key — all the same answer. The asset is safely on
+        // local disk; a later push (or `maude hub asset-check`) reconciles.
+        log.warn(`[assets] mirror PUT ${rel} failed: ${(err as Error).message}`);
+        return false;
+      }
+    },
+
+    async pull(rel) {
+      try {
+        const res = await send('GET', rel);
+        if (res.status === 404) return null;
+        if (!res.ok) {
+          log.warn(`[assets] mirror GET ${rel} failed: ${res.status}`);
+          return null;
+        }
+        const bytes = new Uint8Array(await res.arrayBuffer());
+        if (!verifyAssetBytes(rel, bytes)) {
+          // Content address mismatch: either corruption or substitution. Refuse
+          // either way — writing these bytes to disk under this name would
+          // poison every peer that later mirrors from us.
+          log.warn(
+            `[assets] REFUSING ${rel}: content does not hash to its own name ` +
+              '(corruption or substitution — see DDR-054)'
+          );
+          return null;
+        }
+        return bytes;
+      } catch (err) {
+        log.warn(`[assets] mirror GET ${rel} failed: ${(err as Error).message}`);
+        return null;
+      }
+    },
+
+    async has(rel) {
+      try {
+        const res = await send('HEAD', rel);
+        return res.ok;
+      } catch {
+        return false;
+      }
+    },
+  };
+}

package/apps/studio/collab/origins.ts

@@ -0,0 +1,150 @@
+// Origin gate for canvas-realm Y.Doc ops — the named-but-undone DDR-122
+// follow-up ("Origin-gate canvas-injected doc ops"), landed by Cloud Phase 1
+// Task 3.
+//
+// THE THREAT (DDR-054 F1/F3, restated by DDR-122's security residual): the
+// canvas iframe is untrusted, and same-realm canvas script can reach the live
+// collab Y.Doc via `useCollab().doc`. Nothing stopped it from writing the BODY
+// lanes — `html` / `css` / `meta` / `syncMeta`, i.e. the canvas's own `.tsx`,
+// its sibling `.css`, and the shared `.meta.json` — which the sync agent then
+// materializes to **every peer's disk**. That is "untrusted canvas writes
+// source code to all peers" (stored-XSS + Claude-Code-context-poisoning).
+//
+// THE GATE, dual-lock (DDR-063's canvas-origin split is the seam that makes
+// lock 2 expressible at all):
+//
+//   Lock 1 — CLIENT (`use-collab.tsx`): a local doc update that touches a body
+//            lane is not broadcast to the server unless its transaction origin
+//            is a *trusted sentinel* registered here. Closes the honest path
+//            (`useCollab().doc.getText('html').insert(...)`).
+//   Lock 2 — SERVER (`collab/room.ts`): an update arriving on a collab socket
+//            that was upgraded on the CANVAS origin is validated against a
+//            mirror doc before it is allowed to touch the real room doc; a
+//            body-lane write is refused outright and never broadcast. Closes
+//            the bypass where canvas script skips `use-collab` and opens its
+//            own WebSocket to `/_ws/collab/:slug`.
+//
+// Lock 1 alone is defense-in-depth; lock 2 is the actual boundary. Both exist
+// because lock 1 is where the intent is legible and lock 2 is where it is
+// enforceable.
+//
+// WHY A MIRROR DOC AND NOT UPDATE INSPECTION (load-bearing, don't "simplify"):
+// `Y.decodeUpdate` only reveals a struct's parent when the struct has neither a
+// left nor a right origin (yjs writes the parent key *only* in that case). An
+// insert into existing text carries an origin ID instead, so the lane it targets
+// is simply not in the bytes — it is only resolvable against a doc that already
+// holds the referenced items. Hence: apply to a mirror of the room doc, read
+// `transaction.changed`, decide, and only then touch the real doc.
+
+import * as Y from 'yjs';
+
+/**
+ * Lanes that carry the canvas SOURCE (and its sync bookkeeping). Written only
+ * by server-side code — `sync/agent.ts`, `sync/codec.ts`, `sync/projection.ts`.
+ * No browser-realm code writes these today; the gate keeps it that way.
+ */
+const BODY_LANES = new Set<string>(['html', 'css', 'meta', 'syncMeta']);
+
+/**
+ * Lanes the canvas realm legitimately co-authors — annotations (draw layer),
+ * comments, and the presentation channel. Deliberately NOT used as an allowlist
+ * for the gate (a new lane must be reasoned about, not silently permitted); it
+ * documents intent and backs `isCanvasAuthorableLane` for callers that want the
+ * positive form.
+ */
+const CANVAS_AUTHORABLE_LANES = new Set<string>(['comments', 'annotations', 'presentation']);
+
+/** True when `name` is a source-carrying lane the canvas realm may never write. */
+export function isBodyLane(name: string): boolean {
+  return BODY_LANES.has(name);
+}
+
+/** True when `name` is a lane the canvas realm co-authors by design. */
+export function isCanvasAuthorableLane(name: string): boolean {
+  return CANVAS_AUTHORABLE_LANES.has(name);
+}
+
+/** Test/introspection — the frozen lane vocabulary as plain arrays. */
+export function laneVocabulary(): { body: string[]; canvasAuthorable: string[] } {
+  return { body: [...BODY_LANES].sort(), canvasAuthorable: [...CANVAS_AUTHORABLE_LANES].sort() };
+}
+
+// ---------------------------------------------------------------------------
+// Trusted origin sentinels
+// ---------------------------------------------------------------------------
+
+// A WeakSet, not a marker property: a marker property is forgeable by any
+// same-realm script (`{ maudeTrusted: true }`), a WeakSet membership is not —
+// an attacker would need the sentinel *object itself*, which is only reachable
+// from module scope of the modules that legitimately hold it.
+const TRUSTED_ORIGINS = new WeakSet<object>();
+
+/**
+ * Register `origin` as a trusted doc-update origin. Returns it, so a sentinel
+ * can be declared and marked in one expression. Frozen objects are fine —
+ * freezing does not affect WeakSet membership.
+ */
+export function markTrustedOrigin<T extends object>(origin: T): T {
+  TRUSTED_ORIGINS.add(origin);
+  return origin;
+}
+
+/** True when a Y transaction origin was registered via `markTrustedOrigin`. */
+export function isTrustedOrigin(origin: unknown): boolean {
+  return typeof origin === 'object' && origin !== null && TRUSTED_ORIGINS.has(origin as object);
+}
+
+/**
+ * The shell's sanctioned edit path — the inspector / shell UI mutating a body
+ * lane on behalf of an explicit user gesture. Nothing in the canvas realm can
+ * obtain this object; it is exported for the shell modules that need it.
+ */
+export const SHELL_EDIT_ORIGIN: object = markTrustedOrigin(
+  Object.freeze({ maudeOrigin: 'shell-edit' })
+);
+
+/**
+ * The local sync agent applying a disk-authoritative body into the doc. Used by
+ * server-side code that runs outside the canvas realm entirely; marked here so
+ * the client-side lock stays correct if a future build ever colocates them.
+ */
+export const SYNC_AGENT_ORIGIN: object = markTrustedOrigin(
+  Object.freeze({ maudeOrigin: 'sync-agent' })
+);
+
+// ---------------------------------------------------------------------------
+// Transaction inspection
+// ---------------------------------------------------------------------------
+
+/**
+ * Root shared-type names a transaction touched.
+ *
+ * `transaction.changed` is keyed by the *concrete* type that changed, which for
+ * a nested structure is not the root — so walk `_item.parent` up to the root and
+ * resolve its registered name via `Y.findRootTypeKey`. A type that cannot be
+ * resolved (detached / mid-destroy) yields the sentinel `'<unresolved>'`, which
+ * is deliberately NOT a body lane but also not an authorable one — callers that
+ * fail closed should treat an unresolved root as untrusted.
+ */
+export function rootTypesTouched(transaction: Y.Transaction): Set<string> {
+  const roots = new Set<string>();
+  for (const type of transaction.changed.keys()) {
+    let t: Y.AbstractType<unknown> = type;
+    // biome-ignore lint/suspicious/noExplicitAny: `_item` is yjs-internal but stable API surface for parent walks.
+    while ((t as any)._item != null) t = (t as any)._item.parent;
+    try {
+      roots.add(Y.findRootTypeKey(t));
+    } catch {
+      roots.add('<unresolved>');
+    }
+  }
+  return roots;
+}
+
+/** True when a transaction wrote any source-carrying lane. */
+export function touchesBodyLane(transaction: Y.Transaction): boolean {
+  for (const name of rootTypesTouched(transaction)) {
+    if (isBodyLane(name)) return true;
+  }
+  return false;
+}

package/apps/studio/collab/protocol.ts

@@ -71,6 +71,40 @@ export function encodeAwarenessFrame(
   return encoding.toUint8Array(encoder);
 }
 
+/**
+ * Peek the message type of a frame without consuming it. Lets a caller route
+ * sync vs awareness before deciding *which doc* to apply the frame to — the
+ * origin gate (`collab/origins.ts`) validates sync frames against a mirror doc
+ * first, and needs to know a frame is a sync frame to do so.
+ */
+export function readMessageType(payload: Uint8Array): number {
+  return decoding.readVarUint(decoding.createDecoder(payload));
+}
+
+/**
+ * Apply one MESSAGE_SYNC frame to `doc` with `origin` as the Y transaction
+ * origin, returning the reply frame (sync step 2 / ack) if there is one.
+ *
+ * Split out of `handleMessage` so the same bytes can be applied to a throwaway
+ * mirror doc under a probe origin (the origin gate) before they are allowed
+ * anywhere near the real room doc. Non-sync payloads return `null` untouched.
+ */
+export function applySyncMessage(
+  payload: Uint8Array,
+  doc: Y.Doc,
+  origin: unknown
+): Uint8Array | null {
+  const decoder = decoding.createDecoder(payload);
+  if (decoding.readVarUint(decoder) !== MESSAGE_SYNC) return null;
+  const encoder = encoding.createEncoder();
+  encoding.writeVarUint(encoder, MESSAGE_SYNC);
+  // readSyncMessage applies the peer's update to the doc and writes the
+  // response (sync step 2 / sync step 2 ack) into encoder.
+  syncProtocol.readSyncMessage(decoder, encoder, doc, origin);
+  if (encoding.length(encoder) > 1) return encoding.toUint8Array(encoder);
+  return null;
+}
+
 /**
  * Decode and dispatch one incoming binary frame. Returns an optional reply
  * frame the caller MUST send back to the originating peer (sync step 2 from
@@ -89,15 +123,8 @@ export function handleMessage(
   const messageType = decoding.readVarUint(decoder);
 
   switch (messageType) {
-    case MESSAGE_SYNC: {
-      const encoder = encoding.createEncoder();
-      encoding.writeVarUint(encoder, MESSAGE_SYNC);
-      // readSyncMessage applies the peer's update to the doc and writes the
-      // response (sync step 2 / sync step 2 ack) into encoder.
-      syncProtocol.readSyncMessage(decoder, encoder, doc, conn);
-      if (encoding.length(encoder) > 1) return encoding.toUint8Array(encoder);
-      return null;
-    }
+    case MESSAGE_SYNC:
+      return applySyncMessage(payload, doc, conn);
     case MESSAGE_AWARENESS: {
       awarenessProtocol.applyAwarenessUpdate(awareness, decoding.readVarUint8Array(decoder), conn);
       return null;