@1agh/maude 0.29.0 → 0.31.0

package/apps/studio/sync/cold-start.ts

@@ -0,0 +1,198 @@
+// Cold-start body resolution — the pure decision core of the conflict
+// protocol (DDR-102; supersedes the v1.1 "hub-wins always" scoping).
+//
+// Both sync paths (agent.ts reconcile, migrate-seed.ts for the shared-doc
+// cutover) feed their observed state into `decideColdStart` and execute the
+// returned action. Keeping the table pure makes the full matrix unit-testable
+// without Y.Docs or disk (mirrors codec.ts's pure-function style).
+//
+// The journal (journal.ts) is what separates a CLEAN catch-up from divergence:
+// journalHash == hash(local) means every local byte was already reconciled
+// through this machine — the hub being different just means it moved ahead, so
+// overwriting disk is a fast-forward, not data loss. Any other combination of
+// "both sides non-empty and different" is a conflict: the caller snapshots
+// BOTH versions to `_history/<slug>/` and applies the newest-wins winner.
+//
+// Newest-wins compares the doc-side `syncMeta.bodyEditAt` stamp (codec.ts —
+// written by every peer that applies a local body into the doc) against the
+// local file mtime. Either side unknown (older peer never stamped; mtime
+// unavailable) or equal → hub wins, exactly the v1.1 default — but now both
+// sides are snapshotted first, so even a wrong pick costs one /design:rollback.
+
+import { hashBytes } from './echo-guard.ts';
+
+export type ColdStartAction =
+  | 'noop'
+  | 'materialize-hub'
+  | 'seed-local-up'
+  | 'fast-forward-hub'
+  | 'recover-seed-dup'
+  | 'conflict';
+
+export interface ColdStartInput {
+  /** Local body file content, or null when the file doesn't exist. */
+  localBody: string | null;
+  /** Body currently held by the doc (hub state after first sync). */
+  docBody: string;
+  /** Journal entry's bodyHash for this slug, or null when never checkpointed. */
+  journalHash: string | null;
+  /** Local body file mtime (ms epoch), or null when unavailable. */
+  localMtimeMs: number | null;
+  /** Doc-side syncMeta.bodyEditAt stamp (ms epoch), or null when no peer ever
+   *  stamped (older peer interop) — falls back to hub-wins. */
+  docBodyEditAtMs: number | null;
+}
+
+export interface ColdStartDecision {
+  action: ColdStartAction;
+  /** Set only for `conflict`. */
+  winner?: 'local' | 'hub';
+  /** Human-readable, logged + recorded in the conflict entry. */
+  reason: string;
+}
+
+/** Trim-only-whitespace bodies count as empty (mirrors the agent's
+ *  `localHtml.trim() !== ''` guard). */
+function isEmptyBody(body: string | null): boolean {
+  return body === null || body.trim() === '';
+}
+
+/**
+ * True when `docBody` is exactly `localBody` repeated N≥2 times — the signature
+ * of a concurrent cold-seed collision (F1): two peers each `seed-local-up`-ed
+ * the SAME body into an empty hub before either's write propagated, so the CRDT
+ * preserved both insertions and the Y.Text became `BODY` × N. We detect the
+ * exact-repeat shape (not a fuzzy "contains") so a legitimate later edit — which
+ * is never a clean integer-multiple repeat of the prior body — can't be
+ * mis-read as a duplication and clobbered back. Exact equality (N==1) is the
+ * caller's `noop`, handled before this is consulted.
+ */
+export function isExactRepeat(docBody: string, localBody: string): boolean {
+  if (localBody.length === 0) return false;
+  if (docBody.length <= localBody.length) return false;
+  if (docBody.length % localBody.length !== 0) return false;
+  const n = docBody.length / localBody.length;
+  return docBody === localBody.repeat(n);
+}
+
+function commentId(c: unknown): string | null {
+  if (c && typeof c === 'object' && typeof (c as { id?: unknown }).id === 'string') {
+    return (c as { id: string }).id;
+  }
+  return null;
+}
+
+/**
+ * Union-merge two comment snapshots by stable `id` (DDR-102): doc order first,
+ * local-only entries appended. Comments carry stable ids, so union loses
+ * nothing and needs no winner — same-id entries keep the doc's version.
+ * Id-less entries dedupe by JSON identity (conservative). Shared by both
+ * cold-start paths (agent reconcile + migrate-seed).
+ */
+export function unionCommentsById(docList: unknown[], localList: unknown[]): unknown[] {
+  const out = [...docList];
+  const seenIds = new Set<string>();
+  const seenJson = new Set<string>();
+  for (const c of docList) {
+    const id = commentId(c);
+    if (id !== null) seenIds.add(id);
+    else seenJson.add(JSON.stringify(c));
+  }
+  for (const c of localList) {
+    const id = commentId(c);
+    const dup = id !== null ? seenIds.has(id) : seenJson.has(JSON.stringify(c));
+    if (dup) continue;
+    out.push(c);
+    if (id !== null) seenIds.add(id);
+    else seenJson.add(JSON.stringify(c));
+  }
+  return out;
+}
+
+export function decideColdStart(input: ColdStartInput): ColdStartDecision {
+  const localEmpty = isEmptyBody(input.localBody);
+  const docEmpty = isEmptyBody(input.docBody);
+
+  if (localEmpty && docEmpty) {
+    return { action: 'noop', reason: 'both sides empty — nothing to reconcile' };
+  }
+
+  if (localEmpty) {
+    // Clean first sync: nothing local to lose.
+    return { action: 'materialize-hub', reason: 'no local body — materializing hub state' };
+  }
+
+  if (docEmpty) {
+    // DDR-064 empty-hub guard, now a named case: an empty hub doc means the hub
+    // holds no body for this slug yet — NOT an authoritative "blank canvas".
+    return {
+      action: 'seed-local-up',
+      reason: 'hub doc empty — seeding local body up (DDR-064 guard)',
+    };
+  }
+
+  if (input.localBody === input.docBody) {
+    // Caller records the journal so the NEXT boot sees a clean checkpoint.
+    return { action: 'noop', reason: 'local and hub identical' };
+  }
+
+  // Concurrent cold-seed collision (F1): the hub body is our local body repeated
+  // N≥2 times — two peers seeded the same canvas into an empty hub at the same
+  // moment and the CRDT concatenated both insertions (un-buildable: two `export
+  // default`). This is NOT divergence (it carries no new bytes — just a doubled
+  // copy of ours), so it must NOT take the conflict/fast-forward path. Collapse
+  // it back to one copy by re-applying local (the caller's `applyHtmlToDoc` diff
+  // deletes the trailing duplicate). Idempotent across peers — the delete targets
+  // the same CRDT items, so concurrent recoveries converge instead of fighting.
+  if (
+    input.localBody !== null &&
+    !localEmpty &&
+    !docEmpty &&
+    isExactRepeat(input.docBody, input.localBody)
+  ) {
+    return {
+      action: 'recover-seed-dup',
+      reason:
+        'hub body is local repeated — concurrent cold-seed duplication; collapsing to one copy',
+    };
+  }
+
+  // Hash via hashBytes ONLY — the journal recorded its hashes through the same
+  // fn (single source, echo-guard.ts), so this comparison is apples-to-apples.
+  if (
+    input.journalHash !== null &&
+    input.localBody !== null &&
+    input.journalHash === hashBytes(input.localBody)
+  ) {
+    // Everything local was already reconciled through this machine; the hub is
+    // simply ahead. Overwrite WITHOUT snapshot/conflict — a clean fast-forward.
+    return {
+      action: 'fast-forward-hub',
+      reason: 'local matches last-synced journal hash — hub is ahead, fast-forwarding',
+    };
+  }
+
+  // Divergence: both sides non-empty, different, and local carries bytes this
+  // machine never reconciled (journal stale or absent). Newest wins; unknown
+  // or tied timestamps fall back to hub (v1.1 default, now recoverable).
+  const local = input.localMtimeMs;
+  const doc = input.docBodyEditAtMs;
+  if (local !== null && doc !== null && local !== doc) {
+    const winner = local > doc ? 'local' : 'hub';
+    return {
+      action: 'conflict',
+      winner,
+      reason: `diverged — newest wins: local mtime ${new Date(local).toISOString()} ${
+        winner === 'local' ? '>' : '<'
+      } doc bodyEditAt ${new Date(doc).toISOString()}`,
+    };
+  }
+  return {
+    action: 'conflict',
+    winner: 'hub',
+    reason:
+      local === null || doc === null
+        ? 'diverged — timestamp unknown on one side, falling back to hub-wins (recoverable: both sides snapshotted)'
+        : 'diverged — timestamps tied, falling back to hub-wins (recoverable: both sides snapshotted)',
+  };
+}

package/apps/studio/sync/connection-state.ts

@@ -23,11 +23,18 @@
 export type ProviderStatus = 'connected' | 'connecting' | 'disconnected';
 export type SyncState = 'online' | 'connecting' | 'offline' | 'offline-long';
 
+/** DDR-102 — per-document sync state. `pending` until the first handshake
+ *  settles; `connected` once synced/active; `auth-rejected` when the hub
+ *  refused auth for this documentName (scope / invalid token / rate limit). */
+export type DocSyncState = 'pending' | 'connected' | 'auth-rejected';
+
 export interface SyncStatusSnapshot {
   state: SyncState;
   /** Local edits made since the hub went unreachable (replayed on reconnect). */
   queuedOps: number;
-  /** ms epoch of the last successful hub sync, or null if never synced. */
+  /** ms epoch of the last successful hub sync, or null if never synced.
+   *  DDR-102: updated on REAL sync activity (noteSyncActivity), not just on
+   *  offline→online transitions. */
   lastSyncAt: number | null;
   /** ms epoch the current offline streak began, or null when online. */
   offlineSince: number | null;
@@ -35,6 +42,11 @@ export interface SyncStatusSnapshot {
   flash: 'synced' | null;
   /** ms epoch this snapshot was produced. */
   updatedAt: number;
+  /** DDR-102 — per-doc rollup (additive; absent in pre-DDR-102 payloads). */
+  docs?: { synced: number; pending: number; rejected: number };
+  /** DDR-102 — slugs currently auth-rejected, capped at 20 (see docs.rejected
+   *  for the true count). Treat as text, never HTML. */
+  rejectedSlugs?: string[];
 }
 
 type TimerHandle = ReturnType<typeof setTimeout>;
@@ -58,6 +70,11 @@ export interface ConnectionMonitor {
   noteProviderStatus(providerId: string, status: ProviderStatus): void;
   /** A local edit happened — counts toward queuedOps while not online. */
   noteLocalEdit(): void;
+  /** DDR-102 — record a document's sync state (pending/connected/auth-rejected). */
+  noteDocState(slug: string, state: DocSyncState): void;
+  /** DDR-102 — real sync activity for a slug (reconcile done, hub-pushed flush
+   *  applied): bumps `lastSyncAt` to now. */
+  noteSyncActivity(slug: string): void;
   /** Current snapshot (defensive copy). */
   snapshot(): SyncStatusSnapshot;
   /** Tear down timers. */
@@ -67,6 +84,8 @@ export interface ConnectionMonitor {
 const DEFAULT_GRACE_MS = 30_000;
 const DEFAULT_ESCALATE_MS = 24 * 60 * 60 * 1000;
 const DEFAULT_FLASH_MS = 3_000;
+/** Cap on rejectedSlugs in the snapshot (the rollup carries the true count). */
+export const MAX_REJECTED_SLUGS = 20;
 
 export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): ConnectionMonitor {
   const graceMs = opts.graceMs ?? DEFAULT_GRACE_MS;
@@ -78,6 +97,8 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
   const onChange = opts.onChange;
 
   const providerStatuses = new Map<string, ProviderStatus>();
+  // DDR-102 — per-doc states (pending/connected/auth-rejected).
+  const docStates = new Map<string, DocSyncState>();
 
   let state: SyncState = 'online';
   let queuedOps = 0;
@@ -91,7 +112,25 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
   let stopped = false;
 
   function snapshot(): SyncStatusSnapshot {
-    return { state, queuedOps, lastSyncAt, offlineSince, flash, updatedAt: now() };
+    const docs = { synced: 0, pending: 0, rejected: 0 };
+    const rejectedSlugs: string[] = [];
+    for (const [slug, st] of docStates) {
+      if (st === 'connected') docs.synced++;
+      else if (st === 'auth-rejected') {
+        docs.rejected++;
+        if (rejectedSlugs.length < MAX_REJECTED_SLUGS) rejectedSlugs.push(slug);
+      } else docs.pending++;
+    }
+    return {
+      state,
+      queuedOps,
+      lastSyncAt,
+      offlineSince,
+      flash,
+      updatedAt: now(),
+      docs,
+      rejectedSlugs,
+    };
   }
 
   function emit(): void {
@@ -189,6 +228,23 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
       emit();
     },
 
+    noteDocState(slug, docState) {
+      if (stopped) return;
+      if (docStates.get(slug) === docState) return;
+      docStates.set(slug, docState);
+      emit();
+    },
+
+    noteSyncActivity(slug) {
+      if (stopped) return;
+      lastSyncAt = now();
+      // Real sync traffic for a pending doc proves its handshake settled.
+      // An auth-rejected doc stays rejected (activity for it can't happen,
+      // but be defensive against ordering races).
+      if (docStates.get(slug) === 'pending') docStates.set(slug, 'connected');
+      emit();
+    },
+
     snapshot,
 
     stop() {

package/apps/studio/sync/hub-link.ts

@@ -0,0 +1,137 @@
+// sync/hub-link.ts — Phase 29 (E4) Door C: connect to a team hub from the wizard.
+//
+// The CLI (`maude design link`) owns the FULL link flow (interactive trust gate +
+// per-project `.design/config.json` linkedHub write + `--adopt` push). This is the
+// lean in-app counterpart used by the onboarding wizard's advanced door: it saves the
+// hub CREDENTIAL to the global `~/.config/maude/hubs.json` (mode 0600) and records the
+// hub as trusted on THIS machine — the in-UI "Connect" IS the explicit trust grant the
+// CLI's interactive confirmation provides (DDR-054 F2). Hub tokens are GLOBAL /
+// per-machine (keyed by normalized URL), so a project later opened whose
+// `.design/config.json` names this hub syncs using the saved token. We deliberately do
+// NOT write a per-project `linkedHub` here (onboarding has no project yet) — that stays
+// a CLI / post-onboarding operation.
+//
+// SECURITY: the http layer gates this main-origin + loopback only (mirrors
+// /_api/github/*). The health probe is a best-effort, TOKENLESS GET to the user-entered
+// hub URL; only `{ ok, version }` is reflected back — no response-body passthrough, so it
+// can't become an SSRF data-exfil channel. The probe deliberately does NOT carry the hub
+// token: a user who pastes a lookalike URL must not have their credential delivered to the
+// attacker's host (phase-29 /flow:done attacker finding A2). The token is only persisted
+// locally (mode 0600) and presented later on the authenticated sync WS upgrade. The hub
+// address is whatever the user typed (a LAN / Tailscale / fly.dev URL is legitimate —
+// phase-9's hub model expects private hosts), so we do NOT block private IPs; the safety
+// is the loopback caller gate + no reflection + no token on the probe.
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import { hubsConfigPath, normalizeUrl } from './hubs-config.ts';
+
+export interface HubLinkResult {
+  status: number;
+  json: unknown;
+}
+
+const HUB_PROBE_TIMEOUT_MS = 4000;
+
+interface HubsFile {
+  hubs: Record<string, { token: string; linkedAt: number }>;
+  trusted?: string[];
+}
+
+/** Validate + probe + persist a hub credential. Returns an http-shaped result. */
+export async function linkHub(body: unknown): Promise<HubLinkResult> {
+  const b = (body ?? {}) as { url?: unknown; token?: unknown };
+  if (typeof b.url !== 'string' || !b.url.trim()) return bad('Enter the hub address.');
+  if (typeof b.token !== 'string' || !b.token.trim())
+    return bad('Paste the invite link or token your team gave you.');
+
+  let norm: string;
+  try {
+    norm = normalizeUrl(b.url.trim());
+  } catch {
+    return bad("That doesn't look like a valid hub address.");
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(norm);
+  } catch {
+    return bad('Invalid hub address.');
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+    return bad('The hub address must start with http:// or https://.');
+
+  const token = b.token.trim();
+
+  // Best-effort reachability probe — TOKENLESS (never deliver the credential to a
+  // possibly-lookalike host) and does NOT gate the save (a firewalled hub the user
+  // trusts still links; the real auth happens on the sync WS upgrade).
+  const probe = await probeHealth(norm);
+
+  try {
+    saveHubCredential(norm, token);
+  } catch {
+    return { status: 500, json: { ok: false, error: "Couldn't save the hub connection." } };
+  }
+
+  return {
+    status: 200,
+    json: { ok: true, url: norm, healthy: probe.ok, version: probe.version ?? null },
+  };
+}
+
+function bad(error: string): HubLinkResult {
+  return { status: 400, json: { ok: false, error } };
+}
+
+async function probeHealth(url: string): Promise<{ ok: boolean; version?: string }> {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), HUB_PROBE_TIMEOUT_MS);
+  try {
+    // Tokenless on purpose (attacker finding A2): /health is a liveness check; the
+    // credential is never sent to the user-typed host, only to the trusted hub on the
+    // authenticated sync WS upgrade later.
+    const res = await fetch(`${url}/health`, { signal: ctrl.signal });
+    if (!res.ok) return { ok: false };
+    let version: string | undefined;
+    try {
+      const j = (await res.json()) as { version?: unknown };
+      if (j && typeof j.version === 'string') version = j.version;
+    } catch {
+      /* health may not be JSON — reachability alone is enough */
+    }
+    return { ok: true, version };
+  } catch {
+    return { ok: false };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Upsert the token under `normUrl` + record per-machine trust; mode 0600. */
+export function saveHubCredential(normUrl: string, token: string): void {
+  const path = hubsConfigPath();
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+  let cfg: HubsFile = { hubs: {} };
+  if (existsSync(path)) {
+    try {
+      const parsed = JSON.parse(readFileSync(path, 'utf8'));
+      if (parsed && typeof parsed.hubs === 'object' && parsed.hubs !== null)
+        cfg = parsed as HubsFile;
+    } catch {
+      /* malformed → start fresh rather than throw */
+    }
+  }
+  cfg.hubs[normUrl] = { token, linkedAt: Date.now() };
+  if (!Array.isArray(cfg.trusted)) cfg.trusted = [];
+  if (!cfg.trusted.includes(normUrl)) cfg.trusted.push(normUrl);
+  writeFileSync(path, `${JSON.stringify(cfg, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  try {
+    chmodSync(path, 0o600);
+  } catch {
+    /* windows / read-only fs — best effort */
+  }
+}
+
+export const __testing = { probeHealth };