@1agh/maude 0.43.0 → 0.45.0

package/apps/studio/http.ts

@@ -8,28 +8,75 @@ import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, watch } from 'node:fs';
 import { dirname, join, posix, relative, resolve, sep } from 'node:path';
 
-import { probeAcpAvailability } from './acp/probe.ts';
+import {
+  cancelSignin,
+  getClaudeAuthStatus,
+  getInstallState,
+  isSigninInFlight,
+  startInstall,
+  startSignin,
+} from './acp/login-state.ts';
+import { probeAcpAvailabilityAuthed } from './acp/probe.ts';
 import { deleteChat, listChats, readChatMessages } from './acp/transcript.ts';
 import { type Api, ASSET_MAX_BYTES, ASSET_MAX_VIDEO_BYTES } from './api.ts';
+import { ImportAssetError, importSvg, SVG_MAX_BYTES } from './bin/_import-asset.mjs';
+import { ImportBrandError, importBrand } from './bin/_import-brand.mjs';
 import { buildCanvasModule } from './canvas-build.ts';
 import { canvasLibPath } from './canvas-lib-resolver.ts';
 import { TranspileError } from './canvas-pipeline.ts';
 import type { AiActivity } from './collab/ai-activity.ts';
 import type { Context } from './context.ts';
+import { reloadConfig } from './context.ts';
+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 { generatedClipAnalysis } from './footage/schema.ts';
 import { createFootageStore, FOOTAGE_MAX_BYTES } from './footage-store.ts';
+import {
+  type AudioMatch,
+  type Candidate,
+  rankMatches,
+  sanitizeReuseText,
+} from './generation/audio-library.ts';
+import { localizeGenAsset } from './generation/download.ts';
+import { type GenerationJobQueue, GenerationQueueFullError } from './generation/jobs.ts';
+import {
+  configuredProviders,
+  deleteProviderKey,
+  getProviderKey,
+  isConfigured,
+  setProviderKey,
+} from './generation/keys.ts';
+import {
+  isTranscriptionProvider,
+  readTranscriptionProvider,
+  writeTranscriptionProvider,
+} from './generation/prefs.ts';
+import {
+  createAdapter,
+  getProviderDescriptor,
+  hasProvider,
+  listProviders,
+} from './generation/registry.ts';
+import { validateGenRequest } from './generation/types.ts';
+import {
+  downloadWhisperModel,
+  getWhisperModel,
+  listWhisperModels,
+  removeWhisperModel,
+} from './generation/whisper-models.ts';
 import { createGitEndpoints } from './git/endpoints.ts';
 import { gitShowFile } from './git/service.ts';
 import { createGitHubEndpoints } from './github/endpoints.ts';
 import type { Inspect } from './inspect.ts';
 import { canvasSlug, writeLocator } from './locator.ts';
-import { DEV_SERVER_ROOT, STICKERS_DIR } from './paths.ts';
+import { DEV_SERVER_ROOT, MEDIA_DIR, STICKERS_DIR } from './paths.ts';
 import { createPhotoStore, PHOTO_EDIT_MAX_BYTES } from './photo-store.ts';
 import { probeReadiness } from './readiness.ts';
 import { getRuntimeBundle, packageForSlug } from './runtime-bundle.ts';
 import { linkHub } from './sync/hub-link.ts';
+import { readUiPrefs, type UiPrefs, writeUiPrefs } from './ui-prefs.ts';
 import { loadWhatsNew } from './whats-new.ts';
 import { isLoopbackHost } from './ws.ts';
 
@@ -106,6 +153,17 @@ function ext(p: string): string {
  * external page can no longer reframe the canvas. When `mainOrigin` is unknown
  * (tests / pre-boot) the directive is OMITTED rather than set to `'self'` —
  * `'self'` alone would forbid the legit cross-origin embed and blank the canvas.
+ *
+ * `connect-src` narrow exception (fix-photo-editor-followup-debt, Task 7):
+ * `@imgly/background-removal`'s model weights (~11-44 MB) fetch from IMG.LY's
+ * own CDN, `https://staticimgly.com`, on first client-side use — there is no
+ * self-hosting mechanism today (a separate, larger follow-up; see DDR-054's
+ * dated addendum for this decision, and `.ai/state/STATE.md` for tracking).
+ * The inference itself stays 100% client-side (pixels never leave the
+ * browser) — only the weight DOWNLOAD needs this one extra origin. This is
+ * the ONLY documented exception to the `connect-src 'self'` invariant above —
+ * do not read it as precedent for adding further hosts without the same
+ * scrutiny (exact hostname, no wildcard subdomain, a DDR record).
  */
 export function cspForCanvasShell(html: string, mainOrigin?: string): string {
   const hashes: string[] = [];
@@ -122,7 +180,7 @@ export function cspForCanvasShell(html: string, mainOrigin?: string): string {
   const directives = [
     "default-src 'none'",
     `script-src ${scriptSrc}`,
-    "connect-src 'self'",
+    "connect-src 'self' https://staticimgly.com",
     "img-src 'self' data: blob:",
     // DDR-148 — a video-comp's <Video>/<Audio> loads media from the canvas
     // origin's own designRoot (assets/). Same inert-bytes trust as img-src
@@ -202,6 +260,24 @@ export function sameOriginWrite(req: Request): boolean {
   }
 }
 
+/**
+ * CSRF guard for a key-bearing / side-effecting GET (Task 2.5 audio-search —
+ * ethical-hacker F1). A cross-site page can issue a `no-cors` GET to
+ * `127.0.0.1:<port>` that passes the `isLoopbackHost` DNS-rebind guard AND may
+ * omit `Origin` (browsers don't reliably stamp Origin on a simple cross-origin
+ * GET), so `sameOriginWrite` alone can't fend it off. Browsers DO always send
+ * the Fetch-Metadata `Sec-Fetch-Site` header, and non-browser clients (the CLI,
+ * curl, bun:test) never do — so reject any request whose `Sec-Fetch-Site` is
+ * present and is not `same-origin`/`none`. A missing header (CLI) is allowed.
+ * Prevents a cross-site page from driving the user's key-bearing provider
+ * fan-out + disk scan as a confused deputy.
+ */
+export function sameOriginRead(req: Request): boolean {
+  const site = req.headers.get('sec-fetch-site');
+  if (!site) return true; // non-browser client (CLI / curl) → allow
+  return site === 'same-origin' || site === 'none';
+}
+
 function safePathUnderRoot(reqUrl: string, repoRoot: string): string | null {
   let pathname: string;
   try {
@@ -602,8 +678,19 @@ export function createHttp(
   api: Api,
   inspect: Inspect,
   ai: AiActivity,
-  exportJobs: ExportJobQueue
+  exportJobs: ExportJobQueue,
+  generateJobs: GenerationJobQueue
 ): Http {
+  // Task 2.7 (approach A) — in-flight whisper-model download state (one at a
+  // time), polled by the Settings "Download model" card via GET
+  // /_api/generate/whisper-model. Closure-scoped: one server, one download.
+  let whisperDownload: {
+    id: string;
+    received: number;
+    total: number;
+    error?: string;
+  } | null = null;
+
   // Cache invalidation — when canvas-lib changes, every cached canvas bundle
   // is stale because canvas-lib is inlined into each one via the resolver
   // plugin. Drop the whole cache so the next request rebuilds with the fresh
@@ -785,8 +872,19 @@ export function createHttp(
     // MAIN-ORIGIN ONLY — absent from CANVAS_SAFE_API + startCanvasServer routes,
     // so the untrusted canvas iframe is 403'd. The native shell reads this to
     // decide between the enabled panel and the not-connected explainer.
-    '/_api/acp/status': () =>
-      Response.json(probeAcpAvailability(), { headers: { 'Cache-Control': 'no-store' } }),
+    // Explicit CSRF + DNS-rebind gate added alongside DDR-166: this route's
+    // `claudePath` field can now reveal a Maude-auto-installed binary's exact
+    // path, and this file's other ACP-adjacent routes all double-gate —
+    // security-review finding that this one had none at all, pre-existing
+    // but newly worth closing given what this diff makes it able to reveal.
+    '/_api/acp/status': async (req: Request) => {
+      if (!sameOriginRead(req)) return new Response('cross-origin rejected', { status: 403 });
+      if (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      return Response.json(await probeAcpAvailabilityAuthed(), {
+        headers: { 'Cache-Control': 'no-store' },
+      });
+    },
 
     // DDR-128 — first-open AI-editing readiness. Read-only probe of the AI-editing
     // dependency chain (claude CLI · maude CLI · maude marketplace + plugins in the
@@ -804,6 +902,100 @@ export function createHttp(
       return Response.json(await probeReadiness(), { headers: { 'Cache-Control': 'no-store' } });
     },
 
+    // DDR-166 plan, Phase 2 (T6) — design-setup readiness (project ✓ / design
+    // system ✓ / first canvas ✓ / brand assets ✓), distinct from the AI-editing
+    // dependency probe above. Read-only, cheap (a few existsSync/readdir calls
+    // scoped to designRoot) — same double gate as every other privileged
+    // read here even though it can't shell out, for consistency with the rest
+    // of this file's onboarding-surface routes. The quick-setup checklist
+    // (SetupChecklist.jsx) polls this.
+    '/_api/setup-readiness': async (req: Request) => {
+      if (!sameOriginWrite(req)) return new Response('cross-origin rejected', { status: 403 });
+      if (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      return Response.json(await probeSetupReadiness(ctx), {
+        headers: { 'Cache-Control': 'no-store' },
+      });
+    },
+
+    // DDR-166 T0c (Addendum 2) — install Claude Code from Maude by running the
+    // exact official one-liner once, ephemerally (no persistent Maude-managed
+    // cache — that design was rejected on security review; see
+    // installClaudeCli()'s own doc comment for the fix). MAIN-ORIGIN ONLY,
+    // same CSRF + DNS-rebind double gate as every other privileged route.
+    '/_api/claude/install': (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 (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      // Fire-and-forget — the install can run past Bun's default 10s idle
+      // timeout on a slow network, so this returns as soon as the spawn is
+      // confirmed started; the panel polls /_api/claude/install-status for
+      // the result, the same shape /_api/claude/signin-status already uses.
+      const result = startInstall();
+      return Response.json(result, {
+        status: result.ok ? 200 : 409,
+        headers: { 'Cache-Control': 'no-store' },
+      });
+    },
+    // GET route with a real subprocess side effect downstream (signin-status
+    // spawns `claude auth status`) — sameOriginWrite alone doesn't gate a GET
+    // (browsers don't reliably stamp Origin on a simple cross-origin GET,
+    // per this file's own sameOriginRead doc comment, written for exactly
+    // this class of route after a prior ethical-hacker finding on
+    // audio-search). Security-review finding against the first cut of these
+    // two routes, which used the wrong guard.
+    '/_api/claude/install-status': (req: Request) => {
+      if (!sameOriginRead(req)) return new Response('cross-origin rejected', { status: 403 });
+      if (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      return Response.json(getInstallState(), { headers: { 'Cache-Control': 'no-store' } });
+    },
+
+    // DDR-166 T0d — sign in to Claude from Maude, driving the user's OWN `claude`
+    // CLI through its own `auth login`/`auth status` subcommands (never Maude's
+    // own OAuth, never a token Maude holds). MAIN-ORIGIN ONLY — absent from
+    // CANVAS_SAFE_API + startCanvasServer routes, same CSRF + DNS-rebind double
+    // gate as every other privileged POST route (DDR-088). Zero new Tauri
+    // commands (Decision 0) — this lives in the same Bun process as bridge.ts/
+    // env.ts, so it reuses the literal scrubAgentEnv/resolveClaudePath the chat
+    // spawn already uses.
+    '/_api/claude/signin': (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 (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      const result = startSignin();
+      return Response.json(result, {
+        status: result.ok ? 200 : 409,
+        headers: { 'Cache-Control': 'no-store' },
+      });
+    },
+    '/_api/claude/signin-cancel': (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 (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      cancelSignin();
+      return Response.json({ ok: true }, { headers: { 'Cache-Control': 'no-store' } });
+    },
+    // Read-only poll target — the panel calls this (or /_api/preflight, which
+    // folds the same status in) on an interval while a sign-in is in flight.
+    // Narrowed fields only (never email/orgId/orgName — see login-state.ts).
+    '/_api/claude/signin-status': async (req: Request) => {
+      if (!sameOriginRead(req)) return new Response('cross-origin rejected', { status: 403 });
+      if (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      const status = await getClaudeAuthStatus();
+      return Response.json(
+        { ...status, inFlight: isSigninInFlight() },
+        { headers: { 'Cache-Control': 'no-store' } }
+      );
+    },
+
     // Phase 31 (DDR-123) — `/design:chat` focus hook. `maude design chat-open`
     // POSTs here; we emit a bus event the shell turns into "open the Assistant
     // panel" (app.jsx, native-only). MAIN-ORIGIN ONLY (off the canvas allowlist).
@@ -2133,6 +2325,71 @@ export function createHttp(
       );
     },
 
+    '/_api/set-artboard-hug': async (req: Request) => {
+      // Artboard "hug height" default — Hug ⇄ Fixed toggle in the CSS panel.
+      // POST { canvas, artboardId, fixed, freezeHeight? } → api.setArtboardHugOp
+      // (writes/removes the bare `fixed` prop on <DCArtboard id="…">; freezeHeight
+      // optionally pins `height` at the board's current measured size so pinning
+      // to Fixed doesn't snap the box). Whole-file undo seq. MAIN-ORIGIN ONLY;
+      // sameOriginWrite + loopback-Host gated, mirrors /_api/resize-artboard.
+      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 (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      const body = await readJson<{
+        canvas?: unknown;
+        artboardId?: unknown;
+        fixed?: unknown;
+        freezeHeight?: unknown;
+      }>(req, 8 * 1024);
+      if (!body) return new Response('body required', { status: 400 });
+      const result = await api.setArtboardHugOp(body);
+      if (!result.ok) {
+        return Response.json(
+          { ok: false, error: result.error },
+          { status: result.status, headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+      return Response.json(
+        { ok: true, seq: result.seq },
+        { status: 200, headers: { 'Cache-Control': 'no-store' } }
+      );
+    },
+
+    '/_api/set-artboard-style': async (req: Request) => {
+      // Artboard "more settings" — background / padding / layout / gap, applied
+      // to .dc-artboard-body. POST { canvas, artboardId, background?, padding?,
+      // layout?, gap? } (each key: value to set, `null` to reset, absent to leave
+      // untouched) → api.setArtboardStyleOp. Whole-file undo seq. MAIN-ORIGIN
+      // ONLY; sameOriginWrite + loopback-Host gated, mirrors /_api/resize-artboard.
+      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 (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      const body = await readJson<{
+        canvas?: unknown;
+        artboardId?: unknown;
+        background?: unknown;
+        padding?: unknown;
+        layout?: unknown;
+        gap?: unknown;
+      }>(req, 8 * 1024);
+      if (!body) return new Response('body required', { status: 400 });
+      const result = await api.setArtboardStyleOp(body);
+      if (!result.ok) {
+        return Response.json(
+          { ok: false, error: result.error },
+          { status: result.status, headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+      return Response.json(
+        { ok: true, seq: result.seq },
+        { status: 200, headers: { 'Cache-Control': 'no-store' } }
+      );
+    },
+
     '/_api/delete-artboard': async (req: Request) => {
       // Delete an artboard by its `id` prop (Backspace / context-menu on a frame).
       // POST { canvas, artboardId } → api.deleteArtboardOp (removes the
@@ -2194,6 +2451,140 @@ export function createHttp(
       );
     },
 
+    // DDR-167 (Phase 3 / T10) — hardened LOCAL-file SVG ingestion for the
+    // in-app Brand-upload panel (T12). Privileged + main-origin-only (Decision
+    // 4): absent from CANVAS_SAFE_API + startCanvasServer's routes map — the
+    // untrusted canvas iframe must never reach it. Raw-bytes body only, never
+    // multipart (this dev server has no multipart parsing anywhere). The
+    // `X-Import-Kind` header is a dispatch HINT ONLY — never trusted for the
+    // security-relevant decision; the sanitize pipeline's own pre-parse
+    // structural sniff decides. PDF import is wired but not yet available —
+    // see the DDR's addendum on why the planned rasterization mechanism
+    // (headless-Chromium navigating a file:// PDF) doesn't render content
+    // under browser automation; a `kind: pdf` request 501s naming that.
+    '/_api/import-asset': 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 (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      const kind = (req.headers.get('x-import-kind') || 'svg').toLowerCase();
+      if (kind !== 'svg') {
+        return Response.json(
+          {
+            ok: false,
+            error: 'PDF import is not yet available (DDR-167 addendum) — only SVG import is wired.',
+          },
+          { status: 501, headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+      const declared = Number(req.headers.get('content-length') || '0');
+      if (Number.isFinite(declared) && declared > SVG_MAX_BYTES) {
+        return Response.json(
+          { ok: false, error: `SVG exceeds the ${SVG_MAX_BYTES / (1024 * 1024)} MB cap` },
+          { status: 413, headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+      if (!req.body) return new Response('empty body', { status: 400 });
+      let svgText: string;
+      try {
+        svgText = await new Response(req.body).text();
+      } catch {
+        return new Response('could not read body', { status: 400 });
+      }
+      try {
+        const result = await importSvg(svgText, {
+          root: ctx.paths.repoRoot,
+          designRootRel: ctx.paths.designRel,
+        });
+        return Response.json(
+          { ok: true, path: result.path },
+          { status: 201, headers: { 'Cache-Control': 'no-store' } }
+        );
+      } catch (err) {
+        const status =
+          err instanceof ImportAssetError
+            ? err.code === 3
+              ? 400
+              : err.code === 5
+                ? 415
+                : err.code === 6
+                  ? 500
+                  : 400
+            : 500;
+        const message = err instanceof Error ? err.message : String(err);
+        return Response.json(
+          { ok: false, error: message },
+          { status, headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+    },
+
+    // DDR-173 (Phase 3 / T12) — brand-file typed-cue extraction for the
+    // in-app Brand-upload panel. Privileged + main-origin-only, same posture
+    // as /_api/import-asset: absent from CANVAS_SAFE_API + startCanvasServer's
+    // routes map. Takes a SERVER-GENERATED asset path from a prior
+    // /_api/import-asset response — never a client-supplied filesystem path
+    // (DDR-173 Decision 2: extraction operates only on DDR-167's already-
+    // gated, already-sanitized output, no parallel ungated read). The path is
+    // still realpath-contained + charset-asserted here, never trusted blindly
+    // just because it LOOKS server-shaped.
+    '/_api/import-brand': 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 (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      let body: { assetPath?: unknown };
+      try {
+        body = (await req.json()) as { assetPath?: unknown };
+      } catch {
+        return new Response('invalid JSON body', { status: 400 });
+      }
+      const assetPath = body.assetPath;
+      if (typeof assetPath !== 'string' || !/^assets\/[a-z0-9]{8}\.svg$/.test(assetPath)) {
+        return Response.json(
+          { ok: false, error: 'assetPath must be a server-generated assets/<sha8>.svg path' },
+          { status: 400, headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+      const designAbs = resolve(ctx.paths.repoRoot, ctx.paths.designRel);
+      const resolvedAsset = resolve(designAbs, assetPath);
+      if (!resolvedAsset.startsWith(resolve(designAbs, 'assets') + sep)) {
+        return Response.json(
+          { ok: false, error: 'assetPath escapes the assets directory' },
+          { status: 400, headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+      try {
+        const result = await importBrand({
+          sanitizedSvgPath: resolvedAsset,
+          root: ctx.paths.repoRoot,
+          designRootRel: ctx.paths.designRel,
+        });
+        return Response.json(
+          { ok: true, ...result },
+          { status: 201, headers: { 'Cache-Control': 'no-store' } }
+        );
+      } catch (err) {
+        const status =
+          err instanceof ImportBrandError
+            ? err.code === 3
+              ? 400
+              : err.code === 4
+                ? 404
+                : err.code === 6
+                  ? 500
+                  : 400
+            : 500;
+        const message = err instanceof Error ? err.message : String(err);
+        return Response.json(
+          { ok: false, error: message },
+          { status, headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+    },
+
     '/_api/export-history': async (req: Request) => {
       // Phase 6.5 T10 — read-only recent-exports feed for the dialog's
       // Recent tab. Writes happen as a side-effect of job completion
@@ -2328,6 +2719,433 @@ export function createHttp(
       });
     },
 
+    // feature-ai-media-generation (DDR-16x) — the background AI-media generation
+    // job queue. The privileged sibling of /_api/export-jobs: MAIN-ORIGIN ONLY
+    // (absent from CANVAS_SAFE_API + startCanvasServer's routes — the untrusted
+    // canvas iframe must never reach a route that resolves a provider KEY and
+    // makes an outbound provider call; it sees only the produced /assets/<sha8>).
+    // loopback-Host gated on every method; the mutating POST is additionally
+    // sameOriginWrite CSRF-gated. See DDR-16x + the canvas-origin-gate test.
+    '/_api/generate-jobs': async (req: Request) => {
+      if (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      if (req.method === 'GET') {
+        return Response.json(
+          { jobs: generateJobs.list() },
+          { headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      const body = await readJson<Record<string, unknown>>(req, 64 * 1024);
+      if (!body) return new Response('body required', { status: 400 });
+      const check = validateGenRequest(body);
+      if (!check.ok) return new Response(check.errors.join('; '), { status: 400 });
+      const genReq = body as unknown as import('./generation/types.ts').GenRequest;
+      if (!hasProvider(genReq.provider))
+        return new Response(`unknown provider: ${genReq.provider}`, { status: 400 });
+      const descriptor = getProviderDescriptor(genReq.provider);
+      if (descriptor && !descriptor.modalities.includes(genReq.modality))
+        return new Response(`provider ${genReq.provider} cannot do ${genReq.modality}`, {
+          status: 400,
+        });
+
+      try {
+        const { id } = generateJobs.enqueue({
+          provider: genReq.provider,
+          modality: genReq.modality,
+          model: genReq.model,
+          // The job's work: resolve the key AT RUN TIME (never cached), build the
+          // per-request adapter context with the saveAsset-backed localizer, and
+          // submit → result → localize each produced asset into assets/<sha8>.
+          run: async (signal) => {
+            const apiKey = await getProviderKey(genReq.provider);
+            const adapter = createAdapter(genReq.provider, {
+              apiKey,
+              signal,
+              localize: (asset) => localizeGenAsset(asset, { saveAsset: api.saveAsset }),
+              // Task 1.2 — source-asset access for the maskless-edit / i2v flows
+              // (Nano Banana reads the source into an inlineData part). Contained
+              // to assets/ host-side; the adapter never touches the filesystem.
+              readSourceAsset: (rel) => api.readAssetBytes(rel),
+            });
+            const job = await adapter.submit(genReq);
+            const result = await job.result();
+            const assets: string[] = [];
+            for (const asset of result.assets) {
+              // Task 2.6 — a CLOUD STT result (ElevenLabs Scribe / Groq) is
+              // caption TEXT, not media: it lands as a `assets/<sha8>.srt|.vtt`
+              // sidecar next to its source (the SAME path the local whisper verb
+              // writes), never through the magic-byte media store. Everything
+              // else (image/video/audio) localizes into the content-addressed
+              // media store as before.
+              if (asset.kind === 'transcription' && typeof asset.text === 'string') {
+                if (!genReq.sourceAsset)
+                  throw new Error('transcription result has no source asset to sidecar');
+                const fmt = asset.mime === 'text/vtt' ? 'vtt' : 'srt';
+                const saved = await api.writeCaptionSidecar(genReq.sourceAsset, fmt, asset.text);
+                if (!saved.ok || !saved.path)
+                  throw new Error(`caption sidecar write failed: ${saved.error ?? 'unknown'}`);
+                assets.push(saved.path);
+              } else {
+                assets.push(await localizeGenAsset(asset, { saveAsset: api.saveAsset }));
+              }
+            }
+            // Task 2.5 — record the AUDIO INTENT next to a generated audio asset
+            // (the durable, semantic reuse index) so a later near-identical
+            // request can offer the existing track instead of paying again.
+            if (genReq.modality === 'audio' && assets.length > 0) {
+              const kind = (genReq.params as Record<string, unknown> | undefined)?.audioKind;
+              await api.writeAudioIntent(assets[0], {
+                kind: typeof kind === 'string' ? kind : undefined,
+                prompt: genReq.prompt,
+                provider: genReq.provider,
+                model: genReq.model,
+              });
+            }
+            // Task 3.2 — a generated VIDEO clip gets a provenance FootageAnalysis
+            // stub next to it (assets/<sha8>.footage.json), so it is immediately
+            // KNOWN to the footage/reel pipeline: the director sees the clip is
+            // synthetic (the `ai-generated` tag) and what it was made for (the
+            // prompt), and the footage-analyst later fills the real shots. A
+            // sidecar hiccup must NOT lose the (expensive) clip — best-effort.
+            if (genReq.modality === 'video' && assets.length > 0) {
+              try {
+                await footageStore.saveAnalysis(
+                  assets[0],
+                  generatedClipAnalysis(assets[0], {
+                    provider: genReq.provider,
+                    model: genReq.model,
+                    prompt: genReq.prompt,
+                  })
+                );
+              } catch {
+                /* provenance-only — the clip already landed in assets/ */
+              }
+            }
+            return { assets, usage: result.usage };
+          },
+        });
+        // Don't await the run — the job's own status (GET + the generate:job WS
+        // push) is the completion signal. A failure is recorded on the job
+        // record, so swallow the rejection here to avoid an unhandled rejection.
+        return Response.json(
+          { jobId: id },
+          { status: 202, headers: { 'Cache-Control': 'no-store' } }
+        );
+      } catch (err) {
+        if (err instanceof GenerationQueueFullError)
+          return new Response(err.message, { status: 429 });
+        throw err;
+      }
+    },
+
+    // feature-ai-media-generation (DDR-16x) — inert provider catalogue for the
+    // Settings panel + generate dialog: descriptors (id/label/modalities/notes/
+    // keyUrl) + presence-only `configured` flags. NO secret ever crosses here.
+    // MAIN-ORIGIN ONLY, loopback-gated.
+    '/_api/generate/providers': async (req: Request) => {
+      if (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      if (req.method !== 'GET') return new Response('Method not allowed', { status: 405 });
+      const configured = new Set(configuredProviders());
+      return Response.json(
+        {
+          providers: listProviders().map((d) => ({ ...d, configured: configured.has(d.id) })),
+        },
+        { headers: { 'Cache-Control': 'no-store' } }
+      );
+    },
+
+    // feature-ai-media-generation (DDR-16x) — key management. WRITE-ONLY from the
+    // main origin: POST sets a key, DELETE removes one, GET reports presence only
+    // ({configured:[...]}) — a key value is NEVER echoed back (mirrors
+    // github_is_signed_in). MAIN-ORIGIN ONLY, loopback + sameOriginWrite gated.
+    '/_api/generate/keys': async (req: Request) => {
+      if (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      if (req.method === 'GET') {
+        return Response.json(
+          { configured: configuredProviders() },
+          { headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      const body = await readJson<{ provider?: unknown; key?: unknown }>(req, 16 * 1024);
+      if (!body || typeof body.provider !== 'string')
+        return new Response('provider required', { status: 400 });
+      if (!hasProvider(body.provider))
+        return new Response(`unknown provider: ${body.provider}`, { status: 400 });
+      try {
+        if (req.method === 'DELETE') {
+          deleteProviderKey(body.provider);
+          return Response.json({ configured: false }, { headers: { 'Cache-Control': 'no-store' } });
+        }
+        if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+        if (typeof body.key !== 'string' || !body.key.trim())
+          return new Response('key required', { status: 400 });
+        setProviderKey(body.provider, body.key);
+        // Presence flag only — never the key. Deliberately does not read the
+        // value back so a proxy/log between here and the client can't capture it.
+        return Response.json(
+          { configured: isConfigured(body.provider) },
+          { headers: { 'Cache-Control': 'no-store' } }
+        );
+      } catch (err) {
+        return new Response(err instanceof Error ? err.message : 'key write failed', {
+          status: 400,
+        });
+      }
+    },
+
+    // feature-ai-media-generation (Task 2.6, DDR-164) — NON-SECRET generation
+    // preferences (the transcription-engine choice). GET returns the current
+    // choice; POST persists it into `.design/config.json` and hot-reloads the
+    // config so the next transcribe picks it up without a restart. MAIN-ORIGIN
+    // ONLY, loopback + sameOriginWrite gated. NEVER touches a key — that's the
+    // separate /_api/generate/keys route.
+    '/_api/generate/prefs': async (req: Request) => {
+      if (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      if (req.method === 'GET') {
+        return Response.json(
+          { transcriptionProvider: readTranscriptionProvider(ctx.paths.repoRoot) },
+          { headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      const body = await readJson<{ transcriptionProvider?: unknown }>(req, 4 * 1024);
+      const provider = body?.transcriptionProvider;
+      if (!isTranscriptionProvider(provider))
+        return new Response('transcriptionProvider must be whisper|elevenlabs|groq', {
+          status: 400,
+        });
+      try {
+        await writeTranscriptionProvider(ctx.paths.repoRoot, provider);
+        reloadConfig(ctx);
+        return Response.json(
+          { transcriptionProvider: provider },
+          { headers: { 'Cache-Control': 'no-store' } }
+        );
+      } catch (err) {
+        return new Response(err instanceof Error ? err.message : 'prefs write failed', {
+          status: 400,
+        });
+      }
+    },
+
+    // feature-unified-settings-modal — NON-SECRET UI / view preferences (theme +
+    // the Canvas & View toggles), persisted to `~/.config/maude/prefs.json` so
+    // they survive a restart and a cleared localStorage. GET returns the merged
+    // prefs; POST merge-patches only the provided keys. MAIN-ORIGIN ONLY, loopback
+    // + sameOriginWrite gated (never reachable from the untrusted canvas origin).
+    '/_api/ui-prefs': async (req: Request) => {
+      if (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      if (req.method === 'GET') {
+        return Response.json(readUiPrefs(), { headers: { 'Cache-Control': 'no-store' } });
+      }
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      const body = await readJson<Record<string, unknown>>(req, 4 * 1024);
+      if (!body || typeof body !== 'object')
+        return new Response('body must be a JSON object', { status: 400 });
+      // Build a clean patch — only well-typed known keys pass through, so a bad
+      // field is rejected rather than silently resetting a stored value.
+      const patch: Partial<UiPrefs> = {};
+      if ('theme' in body) {
+        if (body.theme !== 'light' && body.theme !== 'dark')
+          return new Response('theme must be light|dark', { status: 400 });
+        patch.theme = body.theme;
+      }
+      for (const k of ['minimap', 'zoom', 'annotations', 'autoOpenInspector'] as const) {
+        if (k in body) {
+          if (typeof body[k] !== 'boolean')
+            return new Response(`${k} must be a boolean`, { status: 400 });
+          patch[k] = body[k] as boolean;
+        }
+      }
+      if ('layersMode' in body) {
+        if (body.layersMode !== 'separate' && body.layersMode !== 'in-inspector')
+          return new Response('layersMode must be separate|in-inspector', { status: 400 });
+        patch.layersMode = body.layersMode;
+      }
+      if ('panelSides' in body) {
+        const ps = body.panelSides;
+        if (!ps || typeof ps !== 'object' || Array.isArray(ps))
+          return new Response('panelSides must be an object', { status: 400 });
+        for (const v of Object.values(ps as Record<string, unknown>)) {
+          if (v !== 'left' && v !== 'right')
+            return new Response('panelSides values must be left|right', { status: 400 });
+        }
+        // writeUiPrefs → coerce keeps only known ids, so unknown keys are dropped.
+        patch.panelSides = ps as UiPrefs['panelSides'];
+      }
+      try {
+        return Response.json(writeUiPrefs(patch), { headers: { 'Cache-Control': 'no-store' } });
+      } catch (err) {
+        return new Response(err instanceof Error ? err.message : 'ui-prefs write failed', {
+          status: 500,
+        });
+      }
+    },
+
+    // feature-ai-media-generation (Task 2.5, DDR-164) — reuse-before-you-pay for
+    // AUDIO. GET searches the project's OWN generated audio (intent sidecars) and,
+    // when ElevenLabs is configured, the user's re-downloadable History (free —
+    // already paid), returning ranked reuse candidates. MAIN-ORIGIN ONLY,
+    // loopback-gated (it resolves the provider key server-side).
+    '/_api/generate/audio-search': async (req: Request) => {
+      if (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      if (req.method !== 'GET') return new Response('Method not allowed', { status: 405 });
+      // F1 (ethical-hacker) — this GET resolves the user's key + fans out to the
+      // provider, so it must NOT be cross-site-triggerable (a no-cors GET can slip
+      // past the loopback guard). Fetch-Metadata gate: browser cross-site → 403;
+      // the CLI (no Sec-Fetch-Site) → allowed.
+      if (!sameOriginRead(req)) return new Response('cross-site read rejected', { status: 403 });
+      const q = new URL(req.url).searchParams.get('q') ?? '';
+      if (!q.trim()) return new Response('q query param required', { status: 400 });
+      const local: AudioMatch[] = await api.searchAudioLibrary(q, 10);
+      let history: AudioMatch[] = [];
+      // Only reach the provider when its key is present (no key → local-only).
+      if (isConfigured('elevenlabs')) {
+        try {
+          const apiKey = await getProviderKey('elevenlabs');
+          const adapter = createAdapter('elevenlabs', {
+            apiKey,
+            localize: (asset) => localizeGenAsset(asset, { saveAsset: api.saveAsset }),
+          });
+          if (adapter.listHistory) {
+            const items = await adapter.listHistory();
+            const candidates: Candidate[] = items.map((it) => ({
+              source: 'history' as const,
+              ref: it.id,
+              // History `text` is the user's own generation source, but a TTS of
+              // attacker-supplied text could carry injection — sanitize before it
+              // reaches the agent-facing output (F3).
+              text: sanitizeReuseText(it.text),
+              provider: 'elevenlabs',
+              at: it.at,
+            }));
+            history = rankMatches(q, candidates, { limit: 10 });
+          }
+        } catch {
+          // History is best-effort (rate limits / transient) — degrade to local.
+          history = [];
+        }
+      }
+      return Response.json({ local, history }, { headers: { 'Cache-Control': 'no-store' } });
+    },
+
+    // feature-ai-media-generation (Task 2.5) — reuse a History item: re-download
+    // its bytes (NO credit — already paid) through the host's magic-byte-sniffed
+    // saveAsset, localize into assets/<sha8>, and record the audio intent so the
+    // reused track is itself searchable. MAIN-ORIGIN ONLY, loopback +
+    // sameOriginWrite gated.
+    '/_api/generate/audio-reuse': async (req: Request) => {
+      if (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      const body = await readJson<{ id?: unknown }>(req, 8 * 1024);
+      const id = body?.id;
+      if (typeof id !== 'string' || !id.trim())
+        return new Response('history item id required', { status: 400 });
+      if (!isConfigured('elevenlabs'))
+        return new Response('no ElevenLabs key configured', { status: 400 });
+      try {
+        const apiKey = await getProviderKey('elevenlabs');
+        const adapter = createAdapter('elevenlabs', {
+          apiKey,
+          localize: (asset) => localizeGenAsset(asset, { saveAsset: api.saveAsset }),
+        });
+        if (!adapter.fetchHistoryAudio)
+          return new Response('provider has no history re-download', { status: 400 });
+        const asset = await adapter.fetchHistoryAudio(id);
+        const rel = await localizeGenAsset(asset, { saveAsset: api.saveAsset });
+        await api.writeAudioIntent(rel, {
+          kind: 'tts',
+          prompt: `reused from ElevenLabs history ${id}`,
+          provider: 'elevenlabs',
+        });
+        return Response.json({ asset: rel }, { headers: { 'Cache-Control': 'no-store' } });
+      } catch (err) {
+        return new Response(err instanceof Error ? err.message : 'reuse failed', { status: 400 });
+      }
+    },
+
+    // feature-ai-media-generation (Task 2.7 approach A, DDR-164) — managed local
+    // whisper.cpp GGML models: GET lists the registry + which are downloaded +
+    // any in-flight download; POST {id} downloads one (SSRF-hardened, from the
+    // frozen ggerganov/whisper.cpp allowlist); DELETE {id} reclaims disk. This is
+    // the "one-click local subtitles" model half — after a download,
+    // `maude design transcribe --provider whisper` auto-resolves it. MAIN-ORIGIN
+    // ONLY, loopback + sameOriginWrite gated.
+    '/_api/generate/whisper-model': async (req: Request) => {
+      if (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      if (req.method === 'GET') {
+        return Response.json(
+          { models: listWhisperModels(), downloading: whisperDownload },
+          { headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      const body = await readJson<{ id?: unknown }>(req, 4 * 1024);
+      const id = typeof body?.id === 'string' ? body.id : '';
+      if (!getWhisperModel(id)) return new Response('unknown model id', { status: 400 });
+
+      if (req.method === 'DELETE') {
+        const removed = await removeWhisperModel(id);
+        return Response.json({ removed }, { headers: { 'Cache-Control': 'no-store' } });
+      }
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (whisperDownload && !whisperDownload.error)
+        return new Response(`a download is already in progress (${whisperDownload.id})`, {
+          status: 409,
+        });
+      // Kick off the streamed download; progress is polled via GET. Swallow the
+      // rejection here (recorded on the state) to avoid an unhandled rejection.
+      // A generous wall-clock timeout (ethical-hacker Finding 3) so a stalled
+      // connection aborts → errors → frees the single slot instead of wedging it
+      // forever (large models on a slow link can legitimately take many minutes).
+      whisperDownload = { id, received: 0, total: 0 };
+      void downloadWhisperModel(
+        id,
+        (received, total) => {
+          if (whisperDownload && whisperDownload.id === id) {
+            whisperDownload.received = received;
+            whisperDownload.total = total;
+          }
+        },
+        AbortSignal.timeout(45 * 60_000)
+      )
+        .then(() => {
+          if (whisperDownload?.id === id) whisperDownload = null; // done → drops out of GET
+        })
+        .catch((err) => {
+          if (whisperDownload?.id === id)
+            whisperDownload = {
+              id,
+              received: whisperDownload.received,
+              total: whisperDownload.total,
+              error: err instanceof Error ? err.message : 'download failed',
+            };
+        });
+      return Response.json(
+        { started: id },
+        { status: 202, headers: { 'Cache-Control': 'no-store' } }
+      );
+    },
+
     '/_canvas-state': async (req: Request) => {
       const url = new URL(req.url);
       if (req.method === 'GET') {
@@ -2456,14 +3274,21 @@ export function createHttp(
         } catch {
           return new Response('Bad request', { status: 400 });
         }
-        if (
+        // DDR-173 (Phase 3 / T12) — brand-logo assets live one level down at
+        // `assets/logos/<sha8>.<ext>` (DDR-141's own convention). This is the
+        // ONE legitimate subdirectory allowed here, matched by its own exact,
+        // closed-charset shape — not a general "any subdirectory" opt-in,
+        // which would widen this route's containment beyond what DDR-141
+        // actually calls for.
+        const isFlat =
           name &&
           !name.includes('/') &&
           !name.includes('\\') &&
           !name.includes('..') &&
           !name.startsWith('_') &&
-          CANVAS_ASSET_EXTS.has(ext(name))
-        ) {
+          CANVAS_ASSET_EXTS.has(ext(name));
+        const isLogoSubdir = /^logos\/[a-z0-9]{8}\.(svg|png)$/.test(name);
+        if (isFlat || isLogoSubdir) {
           const abs = join(ctx.paths.designRoot, 'assets', name);
           // Range-aware for video/audio (scrubbing + WKWebView compat).
           if (RANGE_MEDIA_EXTS.has(ext(name))) {
@@ -2525,6 +3350,39 @@ export function createHttp(
         return new Response('Not found', { status: 404 });
       }
 
+      // DDR-166 Phase 1 / T2 — bundled Maude-product media (the intro
+      // showreel), served from MAUDE's OWN MEDIA_DIR (paths.ts, DDR-045),
+      // never the served project's designRoot — every user of the canvas
+      // browser sees the same intro regardless of which project is open.
+      // Same shape as /_stickers/ above: MAIN-ORIGIN ONLY (absent from
+      // CANVAS_SAFE_API + startCanvasServer's routes), Range-capable via
+      // serveMediaFile (the wizard/Help player needs to scrub).
+      if (pathname.startsWith('/_media/')) {
+        const name = pathname.slice('/_media/'.length);
+        let decoded = '';
+        try {
+          decoded = decodeURIComponent(name);
+        } catch {
+          return new Response('Bad request', { status: 400 });
+        }
+        if (
+          decoded &&
+          !decoded.includes('..') &&
+          !decoded.includes('/') &&
+          !decoded.includes('\\') &&
+          RANGE_MEDIA_EXTS.has(ext(decoded))
+        ) {
+          const abs = join(MEDIA_DIR, decoded);
+          if (await Bun.file(abs).exists()) {
+            return serveMediaFile(abs, req, {
+              'Cache-Control': 'public, max-age=31536000, immutable', // bundled with this maude version, never changes at this URL
+              'X-Content-Type-Options': 'nosniff',
+            });
+          }
+        }
+        return new Response('Not found', { status: 404 });
+      }
+
       // Fall-through: serve user repo files (designRoot + everything under repoRoot).
       const fp = safePathUnderRoot(req.url, ctx.paths.repoRoot);
       if (!fp) return new Response('Forbidden', { status: 403 });