@1agh/maude 0.58.2 → 0.58.3

package/apps/studio/figma/url.test.ts

@@ -0,0 +1,167 @@
+// figma/url.ts — the SSRF chokepoint-1 rejection table (DDR-216 D4).
+//
+// The accept cases prove the four public URL shapes + bare keys parse; the
+// REJECT table is the load-bearing half. Round 1 of the DDR's security review
+// attacked this parser specifically (userinfo-in-host, IDN look-alikes, `..`,
+// `%2e%2e`, a key carrying `/`/`@`/`#`, a node id smuggling a path, a full
+// absolute URL passed as the key) and could not break it — these cases pin
+// that result so a later "let's be more forgiving" refactor fails loudly.
+
+import { describe, expect, test } from 'bun:test';
+
+import { FigmaUrlError, normalizeNodeId, parseFigmaTarget } from './url.ts';
+
+const DESIGN_KEY = 'dGNzRC2kmrmGnOxaBa0RI7'; // the real design fixture
+const BOARD_KEY = 'Em6NOwaOFTYV7NlQT4NK8l'; // the real FigJam fixture
+
+describe('parseFigmaTarget — accepts the four public shapes', () => {
+  const cases: Array<[string, string, { fileKey: string; nodeId?: string; surface: string }]> = [
+    [
+      'design URL',
+      `https://www.figma.com/design/${DESIGN_KEY}/Maude-fixtures`,
+      { fileKey: DESIGN_KEY, surface: 'design' },
+    ],
+    [
+      'board URL',
+      `https://www.figma.com/board/${BOARD_KEY}/Analyza`,
+      { fileKey: BOARD_KEY, surface: 'board' },
+    ],
+    [
+      'legacy /file/ URL normalizes to design',
+      `https://www.figma.com/file/${DESIGN_KEY}/Old-link`,
+      { fileKey: DESIGN_KEY, surface: 'design' },
+    ],
+    [
+      'proto URL normalizes to design',
+      `https://www.figma.com/proto/${DESIGN_KEY}/Proto`,
+      { fileKey: DESIGN_KEY, surface: 'design' },
+    ],
+    [
+      'apex host (no www)',
+      `https://figma.com/design/${DESIGN_KEY}/x`,
+      { fileKey: DESIGN_KEY, surface: 'design' },
+    ],
+    [
+      'node-id is normalized from a-b to a:b',
+      `https://www.figma.com/design/${DESIGN_KEY}/x?node-id=2-17`,
+      { fileKey: DESIGN_KEY, nodeId: '2:17', surface: 'design' },
+    ],
+    [
+      'node-id already colon-shaped survives',
+      `https://www.figma.com/board/${BOARD_KEY}/x?node-id=1%3A8`,
+      { fileKey: BOARD_KEY, nodeId: '1:8', surface: 'board' },
+    ],
+    [
+      'other query params are ignored',
+      `https://www.figma.com/design/${DESIGN_KEY}/x?t=abc&node-id=2-17&mode=dev`,
+      { fileKey: DESIGN_KEY, nodeId: '2:17', surface: 'design' },
+    ],
+    ['bare key defaults to design', DESIGN_KEY, { fileKey: DESIGN_KEY, surface: 'design' }],
+  ];
+
+  for (const [label, input, expected] of cases) {
+    test(label, () => {
+      expect(parseFigmaTarget(input)).toEqual(expected as never);
+    });
+  }
+
+  test('a bare key honours the caller-supplied default surface', () => {
+    expect(parseFigmaTarget(BOARD_KEY, 'board')).toEqual({ fileKey: BOARD_KEY, surface: 'board' });
+  });
+
+  test('surrounding whitespace from a paste is tolerated', () => {
+    expect(parseFigmaTarget(`  https://www.figma.com/design/${DESIGN_KEY}/x  `).fileKey).toBe(
+      DESIGN_KEY
+    );
+  });
+});
+
+describe('parseFigmaTarget — the rejection table (SSRF chokepoint 1)', () => {
+  const rejects: Array<[string, string]> = [
+    // ── the host must never come from input ──────────────────────────────
+    ['userinfo-in-host', `https://www.figma.com@evil.tld/design/${DESIGN_KEY}/x`],
+    ['userinfo with password', `https://user:pw@www.figma.com/design/${DESIGN_KEY}/x`],
+    ['plain non-figma host', `https://evil.tld/design/${DESIGN_KEY}/x`],
+    ['suffix look-alike (evil-figma.com)', `https://evil-figma.com/design/${DESIGN_KEY}/x`],
+    ['figma.com as a subdomain of evil', `https://figma.com.evil.tld/design/${DESIGN_KEY}/x`],
+    ['IDN homograph', `https://www.figɱa.com/design/${DESIGN_KEY}/x`],
+    ['cyrillic homograph', `https://www.figmа.com/design/${DESIGN_KEY}/x`],
+    ['loopback', `http://127.0.0.1/design/${DESIGN_KEY}/x`],
+    ['link-local metadata host', `http://169.254.169.254/design/${DESIGN_KEY}/x`],
+
+    // ── scheme ───────────────────────────────────────────────────────────
+    ['file scheme', `file:///design/${DESIGN_KEY}/x`],
+    ['data scheme', 'data:text/plain,figma'],
+    ['javascript scheme', 'javascript:alert(1)'],
+
+    // ── the key position ─────────────────────────────────────────────────
+    ['traversal in the key position', 'https://www.figma.com/design/../../etc/passwd'],
+    ['percent-encoded traversal', 'https://www.figma.com/design/%2e%2e%2f%2e%2e/x'],
+    ['encoded slash in the key', 'https://www.figma.com/design/aaaa%2Fbbbb/x'],
+    ['key too short', 'https://www.figma.com/design/short/x'],
+    ['key too long', `https://www.figma.com/design/${'a'.repeat(65)}/x`],
+    ['key with a hyphen', 'https://www.figma.com/design/abcd-efghij/x'],
+    ['key with a dot', 'https://www.figma.com/design/abcdefghi.j/x'],
+    ['no key segment', 'https://www.figma.com/design/'],
+    ['unknown surface segment', `https://www.figma.com/community/${DESIGN_KEY}/x`],
+
+    // ── bare-key position ────────────────────────────────────────────────
+    ['bare key with a slash', 'aaaaaaaaaa/bbbb'],
+    ['bare key with an @', 'aaaaaaaaaa@evil.tld'],
+    ['bare key with a #', 'aaaaaaaaaa#frag'],
+    ['an absolute URL passed where a key is expected', 'https://evil.tld/aaaaaaaaaa'],
+
+    // ── shape ────────────────────────────────────────────────────────────
+    ['empty', ''],
+    ['whitespace only', '   '],
+    ['over-length input', `https://www.figma.com/design/${DESIGN_KEY}/${'x'.repeat(2100)}`],
+  ];
+
+  for (const [label, input] of rejects) {
+    test(`rejects: ${label}`, () => {
+      expect(() => parseFigmaTarget(input)).toThrow(FigmaUrlError);
+    });
+  }
+
+  test('rejection messages never echo the input back', () => {
+    // An error path that reflects attacker-controlled input is a namable
+    // exfil/reflection channel — DDR-172 Decision 1 closed the same class for
+    // token-file parse errors, and DDR-216 D10 makes it a rule for this verb.
+    const hostile = 'https://evil.tld/design/CANARYCANARY/x?node-id=1-2';
+    try {
+      parseFigmaTarget(hostile);
+      throw new Error('expected a rejection');
+    } catch (err) {
+      expect(err).toBeInstanceOf(FigmaUrlError);
+      expect((err as Error).message).not.toContain('CANARY');
+      expect((err as Error).message).not.toContain('evil.tld');
+    }
+  });
+});
+
+describe('normalizeNodeId — a malformed id means "whole file", never "some other node"', () => {
+  test('normalizes the hyphen form', () => {
+    expect(normalizeNodeId('457-608')).toBe('457:608');
+  });
+
+  test('passes a well-formed colon id through', () => {
+    expect(normalizeNodeId('2:17')).toBe('2:17');
+  });
+
+  for (const bad of [
+    null,
+    undefined,
+    '',
+    'abc',
+    '1',
+    '1:2:3',
+    '../1-2',
+    '1-2;rm -rf',
+    '1-2 OR 1=1',
+    `${'9'.repeat(11)}-1`, // over the digit ceiling
+  ]) {
+    test(`drops malformed id: ${JSON.stringify(bad)}`, () => {
+      expect(normalizeNodeId(bad as string)).toBeUndefined();
+    });
+  }
+});

package/apps/studio/figma/url.ts

@@ -0,0 +1,160 @@
+/**
+ * @file       figma/url.ts — Figma URL/key parsing (DDR-216 D4, chokepoint 1).
+ * @scope      apps/studio/figma/url.ts
+ * @purpose    Turn whatever the user pasted into `{ fileKey, nodeId?, surface }`
+ *             — and reject everything else.
+ *
+ * @invariant  THIS IS A REJECTION SURFACE, NOT A CONVENIENCE PARSER.
+ *             **The host is never taken from the input.** Nothing this module
+ *             returns contributes a scheme, host, port or path prefix to a
+ *             request; `client.ts` composes every URL from its own hardcoded
+ *             base plus the charset-validated values below. That is what closes
+ *             the request-construction SSRF class outright (DDR-216 D4) — the
+ *             one closure Round 1 of the security review attacked directly and
+ *             could not break, so keep the property, not just the code.
+ *
+ * @invariant  DEPENDENCY-FREE. No `node:*`, no network, no filesystem. Pure
+ *             string work, so it is trivially testable and has no way to
+ *             dereference anything it parses (the DDR-172 Decision 2 discipline,
+ *             applied to a URL parser instead of an alias resolver).
+ */
+
+/** The four public Figma URL shapes carry the surface in the path segment. */
+export type FigmaSurface = 'design' | 'board';
+
+export interface FigmaTarget {
+  /** Charset-validated document key — safe to interpolate into a path segment. */
+  fileKey: string;
+  /** Normalized `123:456` node id, when the URL carried one. */
+  nodeId?: string;
+  /**
+   * Which editor authored the document. `design` → frames/tokens translators,
+   * `board` → the FigJam stroke translator. `/file/` and `/proto/` are legacy
+   * design-side shapes and normalize to `design`.
+   */
+  surface: FigmaSurface;
+}
+
+export class FigmaUrlError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'FigmaUrlError';
+  }
+}
+
+/**
+ * Document keys are opaque base62-ish tokens. The bound is deliberately tight:
+ * every character admitted here is one that cannot change the meaning of a URL
+ * path segment, so a key can never introduce `/`, `.`, `@`, `#`, `?`, `:` or a
+ * percent-escape. Length floor rejects a stray fragment; ceiling rejects a
+ * pasted blob.
+ */
+const FILE_KEY_RE = /^[A-Za-z0-9]{10,64}$/;
+
+/** Figma node ids are always `<number>:<number>` once normalized from `a-b`. */
+const NODE_ID_RE = /^[0-9]{1,10}:[0-9]{1,10}$/;
+
+/** Path segment → surface. Anything else is not a document URL we understand. */
+const SURFACE_BY_SEGMENT: Readonly<Record<string, FigmaSurface>> = Object.assign(
+  Object.create(null),
+  {
+    design: 'design',
+    board: 'board',
+    file: 'design', // legacy design URLs
+    proto: 'design', // prototype view of a design file
+  }
+);
+
+/**
+ * Hosts we accept a URL *from*. This is a parse-time sanity check on
+ * user-pasted input — NOT the egress control. The egress control is that
+ * `client.ts` ignores this host entirely and uses its own constant base
+ * (DDR-216 D4). Kept strict anyway so a pasted look-alike fails loudly at the
+ * point the user can still see what they pasted.
+ */
+function isFigmaHost(host: string): boolean {
+  const h = host.toLowerCase();
+  return h === 'figma.com' || h.endsWith('.figma.com');
+}
+
+/**
+ * `node-id` arrives URL-encoded as `123-456` (and historically as `123%3A456`).
+ * The API wants `123:456`. Anything that doesn't normalize to exactly that
+ * shape is dropped rather than guessed — a malformed node id means "import the
+ * whole file", never "import some other node".
+ */
+export function normalizeNodeId(raw: string | null | undefined): string | undefined {
+  if (!raw) return undefined;
+  const candidate = raw.trim().replace(/-/g, ':');
+  return NODE_ID_RE.test(candidate) ? candidate : undefined;
+}
+
+/**
+ * Parse a pasted Figma URL or a bare document key.
+ *
+ * Accepts:
+ *   https://www.figma.com/design/<key>/<slug>?node-id=1-2
+ *   https://figma.com/board/<key>/<slug>
+ *   https://www.figma.com/file/<key>/…   (legacy)
+ *   https://www.figma.com/proto/<key>/…
+ *   <key>                                 (bare, surface defaults to `design`)
+ *
+ * Rejects — with a fixed, input-free message — everything else, including
+ * userinfo-in-host (`https://api.figma.com@evil.tld/…`), non-figma hosts, IDN
+ * look-alikes, `..`/percent-escaped traversal in the key position, non-https
+ * schemes, and over-length input.
+ */
+export function parseFigmaTarget(
+  input: string,
+  defaultSurface: FigmaSurface = 'design'
+): FigmaTarget {
+  const raw = typeof input === 'string' ? input.trim() : '';
+  if (!raw) throw new FigmaUrlError('empty Figma URL or file key');
+  // Bound the input before any parsing — a URL this long is not a real one, and
+  // it keeps every regex below linear on a fixed budget.
+  if (raw.length > 2048) throw new FigmaUrlError('Figma URL is too long');
+
+  // Bare key — the shortest path, and the one that cannot carry a host at all.
+  if (FILE_KEY_RE.test(raw)) return { fileKey: raw, surface: defaultSurface };
+
+  // Anything that isn't a bare key must be a URL. Parse with the platform
+  // parser rather than a regex: `URL` resolves userinfo, percent-escapes, IDN
+  // and backslash quirks the same way a browser would, so the host we then
+  // check is the host a browser would actually connect to. A hand-rolled regex
+  // is exactly how `https://api.figma.com@evil.tld/` gets misread.
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new FigmaUrlError('not a valid Figma URL or file key');
+  }
+
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new FigmaUrlError('Figma URL must be http(s)');
+  }
+  // `URL` puts userinfo in `username`/`password`, never in `hostname` — so this
+  // check is what makes `https://api.figma.com@evil.tld/…` fail rather than
+  // silently resolving to `evil.tld`.
+  if (url.username || url.password) {
+    throw new FigmaUrlError('Figma URL must not carry credentials');
+  }
+  if (!isFigmaHost(url.hostname)) {
+    throw new FigmaUrlError('not a figma.com URL');
+  }
+
+  // `url.pathname` keeps percent-encoding intact (the parser resolves literal
+  // `..` segments but never decodes `%2e%2e`/`%2f`), so validating each segment
+  // against a charset that excludes `%` rejects both forms: a resolved `..`
+  // cannot produce a key-shaped segment, and an encoded one still carries `%`.
+  const segments = url.pathname.split('/').filter((s) => s.length > 0);
+  if (segments.length < 2) throw new FigmaUrlError('Figma URL carries no document key');
+
+  const surface = SURFACE_BY_SEGMENT[segments[0].toLowerCase()];
+  if (!surface) throw new FigmaUrlError('unrecognized Figma URL shape');
+
+  const fileKey = segments[1];
+  if (!FILE_KEY_RE.test(fileKey)) throw new FigmaUrlError('Figma document key is not valid');
+
+  const nodeId = normalizeNodeId(url.searchParams.get('node-id'));
+  return nodeId ? { fileKey, nodeId, surface } : { fileKey, surface };
+}

package/apps/studio/http.ts

@@ -41,6 +41,7 @@ import { probeSetupReadiness } from './design-setup-readiness.ts';
 import { type Format, isFormat, isScope, type Scope } from './exporters/index.ts';
 import { type ExportJobQueue, ExportQueueFullError } from './exporters/jobs.ts';
 import type { ActiveJsonShape } from './exporters/scope.ts';
+import { createFigmaEndpoints } from './figma/endpoints.ts';
 import { generatedClipAnalysis } from './footage/schema.ts';
 import { createFootageStore, FOOTAGE_MAX_BYTES } from './footage-store.ts';
 import {
@@ -405,6 +406,7 @@ export const READ_ONLY_ALLOWED_WRITES = new Set([
   // still a gate that is wrong.
   '/_comments',
   '/_api/hub/link', // link/unlink ≈ session management (cell allows /auth/logout)
+  '/_api/cloud/detach', // unlink — the same session-management class as hub/link
   '/_api/workspace/sign-in', // signing in is how the role is (re)learned
   '/_api/workspace/disclosure',
   '/_api/cloud/signin/start', // account session, not project state
@@ -1110,6 +1112,58 @@ export function createHttp(
   // startCanvasServer) and loopback-Host gated — every route either bears or
   // stores the cloud credential.
   const cloudApi = createCloudEndpoints(ctx);
+  // Figma import (DDR-216). Same dual-allowlist rule as the GitHub + cloud
+  // routes: MAIN-ORIGIN ONLY, plus loopback-Host and same-origin gating on
+  // every one of them — each either stores or spends the user's Figma PAT.
+  const figmaApi = createFigmaEndpoints({
+    // The import itself lives in the CLI helper — ONE implementation, so the
+    // panel and `maude design import-figma` cannot drift apart in what they
+    // sanitize, cap or report. Imported lazily so the studio's boot path never
+    // pulls the import machinery (and its browser-backed SVG lane) into memory
+    // for the 99% of sessions that never import anything.
+    async runImport({ url, mode, dryRun }) {
+      const mod = await import('./bin/_import-figma.mjs');
+      const args = {
+        url,
+        root: ctx.paths.repoRoot,
+        designRootRel: ctx.paths.designRel,
+        dryRun: Boolean(dryRun),
+      };
+      if (mode === 'board') {
+        const r = await mod.importBoard(args);
+        return {
+          summary: {
+            mode,
+            slug: r.slug,
+            strokeCount: r.strokeCount,
+            dispositions: r.report.entries,
+          },
+        };
+      }
+      if (mode === 'frames') {
+        const r = await mod.importFrames(args);
+        return {
+          summary: {
+            mode,
+            frameCount: r.frameCount,
+            written: r.written.map((w: { slug: string }) => w.slug),
+            assets: { resolved: r.resolvedAssets, pending: r.pendingExports },
+            dispositions: r.reports.flatMap((rep: { entries: unknown[] }) => rep.entries),
+          },
+        };
+      }
+      const r = await mod.importTokens(args);
+      return {
+        summary: {
+          mode,
+          source: r.source,
+          count: r.count,
+          path: r.path,
+          dispositions: r.report.entries,
+        },
+      };
+    },
+  });
   const gitJson = (r: { status: number; json: unknown }) =>
     Response.json(r.json, { status: r.status, headers: { 'Cache-Control': 'no-store' } });
 
@@ -2374,6 +2428,18 @@ export function createHttp(
         )
       );
     },
+    '/_api/cloud/detach': async (req: Request) => {
+      // The in-app `maude design unlink` (fix 7, sync RCA 2026-08-10). Same
+      // gates as attach; MAIN ORIGIN ONLY (absent from CANVAS_SAFE_API +
+      // startCanvasServer routes — it rewrites config.json and drops a stored
+      // credential).
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      if (!isTrustedRequestHost(req))
+        return new Response('local request required', { status: 403 });
+      return gitJson(await cloudApi.detach());
+    },
 
     '/_api/github/identity': async (req: Request) => {
       if (req.method !== 'GET') return new Response('Method not allowed', { status: 405 });
@@ -2419,6 +2485,69 @@ export function createHttp(
       return gitJson(await githubApi.clone(body));
     },
 
+    // ── Figma import (DDR-216 D2/D3) ────────────────────────────────────────
+    // MAIN-ORIGIN ONLY: absent from BOTH CANVAS_SAFE_API and startCanvasServer's
+    // `routes` map, so the untrusted canvas origin cannot reach them at all —
+    // a canvas-reachable Figma route would be a token-exfiltration primitive AND
+    // an SSRF primitive at once.
+    //
+    // Allowlist-omission alone proves the WRONG property, though: the main origin
+    // is reachable from any website the user happens to visit while the server is
+    // up. Without the two gates below, a CORS-simple POST from evil.example would
+    // plant an attacker's PAT (`connect`) or spend the user's on an attacker-chosen
+    // file key (`probe`) — opaque response, real side effect. So all three carry
+    // `isTrustedRequestHost` + `sameOriginWrite` + a body cap, and `probe` counts
+    // as a WRITE for gating purposes even though it stores nothing: it spends the
+    // credential and reaches the network. (DDR-216 D3, Round-1 security finding.)
+    '/_api/figma/status': async (req: Request) => {
+      if (req.method !== 'GET') return new Response('Method not allowed', { status: 405 });
+      // `sameOriginRead`, not just `sameOriginWrite`: this is a GET, and browsers
+      // do NOT reliably stamp `Origin` on a simple cross-origin GET — so the
+      // write-side guard cannot see this one coming. Without it, any page the
+      // user visits can probe whether they have Figma connected (a small but
+      // real cross-site state leak, and the same shape as the Task-2.5
+      // audio-search F1 finding this helper was added for).
+      if (!sameOriginRead(req)) return new Response('cross-origin read rejected', { status: 403 });
+      if (!isTrustedRequestHost(req))
+        return new Response('local request required', { status: 403 });
+      return gitJson(figmaApi.status());
+    },
+
+    '/_api/figma/connect': async (req: Request) => {
+      if (req.method !== 'POST' && req.method !== 'DELETE')
+        return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      if (!isTrustedRequestHost(req))
+        return new Response('local request required', { status: 403 });
+      if (req.method === 'DELETE') return gitJson(figmaApi.disconnect());
+      const body = await readJson<unknown>(req, 8 * 1024);
+      return gitJson(figmaApi.connect(body));
+    },
+
+    '/_api/figma/probe': async (req: Request) => {
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      if (!isTrustedRequestHost(req))
+        return new Response('local request required', { status: 403 });
+      return gitJson(await figmaApi.probe());
+    },
+
+    // Runs an import. Same triple gate as the other three, and for the same
+    // reasons — it spends the PAT, it reaches the network, and it writes into
+    // the design root. The body is validated into a fixed {mode, url, dryRun}
+    // shape; a caller never gets to choose an output path.
+    '/_api/figma/import': async (req: Request) => {
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      if (!isTrustedRequestHost(req))
+        return new Response('local request required', { status: 403 });
+      const body = await readJson<unknown>(req, 8 * 1024);
+      return gitJson(await figmaApi.runImport(body));
+    },
+
     '/_api/github/create-project': async (req: Request) => {
       if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
       if (!sameOriginWrite(req))

package/apps/studio/sync/asset-push.ts

@@ -0,0 +1,124 @@
+// Desktop→cell asset push — DDR-217 (fix 6 of the 2026-08-10 sync RCA).
+//
+// The sync lanes are text-only (`html`/`css`/`meta`/`syncMeta`), so a
+// desktop-linked project's `<designRoot>/assets/*` never reached the cell: its
+// `/assets/` proxy and its studio child both served bytes they did not have —
+// the grey boxes. The desktop is the one peer that HAS the bytes and already
+// holds an authenticated channel to the hub, so it pushes them over the asset
+// route: `HEAD /assets/<key>` to skip what the cloud already holds, then a
+// streamed `PUT /assets/<key>` for the rest. The hub writes into its checkout
+// and mirrors to the bucket (the browser-upload precedent) — see
+// `apps/hub/src/assets.mjs`.
+//
+// The key-shape rules here MIRROR the hub's `ASSET_KEY` (assets.mjs) — a file
+// this pushes but the hub refuses is a wasted upload, and one this skips but
+// the proxy would serve is a broken image. The HUB's validation stays the
+// authoritative gate (each trust boundary validates its own input); this list
+// is the courtesy filter that keeps junk off the wire.
+
+import { type Dirent, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+/** One path segment of a pushable key — the hub's `ASSET_KEY` charset. */
+const KEY_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+/** `ASSET_KEY` allows the name plus up to 4 directory segments. */
+const MAX_SEGMENTS = 5;
+
+/** Mirror of the sweeper's implausibility bound — a 2 GB file in `assets/` is
+ *  a mistake, and paying to move it silently is the wrong response. */
+const MAX_PUSH_BYTES = 512 * 1024 * 1024;
+
+export interface AssetPushResult {
+  pushed: string[];
+  skipped: number;
+  failed: { key: string; reason: string }[];
+}
+
+/** Pushable keys under `<designRoot>/assets/`, relative to it. Missing dir → []. */
+export function listPushableAssets(designRoot: string): string[] {
+  const root = path.join(designRoot, 'assets');
+  const out: string[] = [];
+  const walk = (dir: string, prefix: string, depth: number): void => {
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!KEY_SEGMENT.test(entry.name)) continue; // dotfiles fail the leading-alnum rule
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (depth + 1 < MAX_SEGMENTS) walk(path.join(dir, entry.name), rel, depth + 1);
+      } else if (entry.isFile()) {
+        try {
+          if (statSync(path.join(dir, entry.name)).size > MAX_PUSH_BYTES) continue;
+        } catch {
+          continue;
+        }
+        out.push(rel);
+      }
+    }
+  };
+  walk(root, '', 1);
+  return out.sort();
+}
+
+/**
+ * Mirror local assets up to the hub. Idempotent and skip-first (one HEAD per
+ * asset per boot; upload only on a miss), sequential on purpose — assets run
+ * to videos, and saturating the link a fresh sync is also using would starve
+ * the handshakes this rides behind. Never throws; a failed upload is retried
+ * for free on the next boot.
+ */
+export async function pushAssets(opts: {
+  designRoot: string;
+  hubUrl: string;
+  /** Read at call time — silent renewal swaps the credential in place. */
+  token: () => string;
+  fetchImpl?: typeof fetch;
+  log?: Pick<Console, 'log' | 'warn'>;
+}): Promise<AssetPushResult> {
+  const { designRoot, hubUrl } = opts;
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const log = opts.log ?? console;
+  const base = hubUrl.replace(/\/+$/, '');
+  const out: AssetPushResult = { pushed: [], skipped: 0, failed: [] };
+
+  for (const key of listPushableAssets(designRoot)) {
+    const url = `${base}/assets/${key}`;
+    const headers = { authorization: `Bearer ${opts.token()}` };
+    try {
+      const head = await fetchImpl(url, { method: 'HEAD', headers });
+      if (head.ok) {
+        out.skipped += 1;
+        continue;
+      }
+      const put = await fetchImpl(url, {
+        method: 'PUT',
+        headers,
+        body: Bun.file(path.join(designRoot, 'assets', key)),
+      });
+      if (put.ok) out.pushed.push(key);
+      else out.failed.push({ key, reason: `HTTP ${put.status}` });
+    } catch (err) {
+      out.failed.push({ key, reason: (err as Error).message });
+    }
+  }
+
+  if (out.pushed.length > 0) {
+    log.log?.(
+      `[sync/assets] pushed ${out.pushed.length} asset(s) to ${base} (${out.skipped} already there)`
+    );
+  }
+  if (out.failed.length > 0) {
+    log.warn?.(
+      `[sync/assets] ${out.failed.length} asset(s) did not reach ${base} (retried next boot): ${out.failed
+        .slice(0, 3)
+        .map((f) => `${f.key} — ${f.reason}`)
+        .join('; ')}`
+    );
+  }
+  return out;
+}

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

@@ -42,6 +42,14 @@ export interface SyncStatusSnapshot {
   flash: 'synced' | null;
   /** ms epoch this snapshot was produced. */
   updatedAt: number;
+  /**
+   * ms epoch this link's monitor was created — i.e. when this runtime started
+   * trying. The one clock `connecting…` can honestly be measured against:
+   * `updatedAt` moves on every emit (an auth-rejection storm refreshes it
+   * forever), so "how long has nothing synced" needs a stamp that does NOT
+   * reset while nothing is actually working. Absent in pre-existing payloads.
+   */
+  startedAt?: 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
@@ -130,6 +138,8 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
   let lastSyncAt: number | null = null;
   let offlineSince: number | null = null;
   let flash: 'synced' | null = null;
+  /** When this monitor began trying — see `SyncStatusSnapshot.startedAt`. */
+  const startedAt = now();
 
   let graceTimer: TimerHandle | null = null;
   let escalateTimer: TimerHandle | null = null;
@@ -172,6 +182,7 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
       offlineSince,
       flash,
       updatedAt: now(),
+      startedAt,
       docs,
       rejectedSlugs,
       ...(pulled ? { pulled } : {}),