diff --git a/.agents/skills/puppetcontrol/SKILL.md b/.agents/skills/puppetcontrol/SKILL.md index 2f72b8e..181de8f 100644 --- a/.agents/skills/puppetcontrol/SKILL.md +++ b/.agents/skills/puppetcontrol/SKILL.md @@ -21,6 +21,7 @@ Read repo-root AGENTS.md, docs/TECHNICAL_CONCEPT.md, and docs/CHARACTER_IMPORT.m 12. For speech, prepare WAV, install Rhubarb separately, and use node dist/cli/index.js audio align --out [--binary ]. For exact-byte continuity, optionally run `audio bind --cues --out ` and include `--binding ` in `scene new`; bound scenes fail validation/render if cue or voice bytes change. A `scene new` voice track requires both `--voice` and the actual `--cues` file; no fabricated speech sync. Reference audio.path, audio.startMs and audio.cuesPath from the scene; review the actual mouth/audio timing. 13. Do not commit private character illustrations, full generated models, user voice recordings or secrets without checking redistribution rights. Demo:avatar generates pinned MIT-licensed sample artwork into ignored .cache. 14. For animation QA, compare real ordered PNGs with `node dist/cli/index.js character qa sequence ... [--region x,y,w,h] [--control-values v0,v1,...] [--cut-after i,j]`. Supply sampled control values when investigating invisible or stalled motion; label known cuts. Inspect the PNGs/video and report possible ghosting even if the motion statistics look normal. The QA report is not an approval. -15. State what actually rendered and which controls remain unsupported. Do not claim a flat PNG is automatically converted into production-quality animation without landmark review. +15. Verified imported rigs and explicitly bound voice tracks are now consumed from fresh per-render copies, hashed against recorded inputs; see `docs/RENDER_INTEGRITY.md`. This is not protection against a malicious same-user process modifying temporary files, nor proof of visual quality. +16. State what actually rendered and which controls remain unsupported. Do not claim a flat PNG is automatically converted into production-quality animation without landmark review. Keep edits small and testable. Run npm run verify and inspect visual evidence for any animation/asset changes. \ No newline at end of file diff --git a/README.md b/README.md index 2603633..0f93553 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,7 @@ The long-term goal: **generate artwork when necessary, animate and reuse it inde - An opt-in `character approve --reviewed` gate for visually inspected imported rigs; asset fingerprints and review sheets are checked before approval. - `scene new` creates editable expression/look/dialogue scenes from an already approved rig without changing the character; voice requires genuine Rhubarb cues. - Non-destructive MP4 export: output files are promoted only after successful FFmpeg encoding, with overwrite requiring explicit `--force`. +- [Verified render inputs](docs/RENDER_INTEGRITY.md): imported rig/texture assets and bound voice/cues are copied and rehashed before subprocess use; fresh frame directories and explicit-root path checks reduce accidental file-replacement and symlink risks. - Guarded **local drawn eye/mouth variant** request, status and import commands using Rev2D masks and sprites. Imported drawings revoke approval and require a fresh visual review; no image generation happens automatically. - An optional **experimental** short-fade profile for imported half/closed eye drawings; avoids prolonged duplicate lash outlines at the cost of faster pose changes, revokes approval and regenerates review sheets. - Local PNG pixel and ordered-frame QA (full frame or explicit region) reports RGB activity, unexpected transparency, candidate motion jumps and changed-control stalls; these metrics never auto-approve a rig. diff --git a/docs/FIRST_VIDEO.md b/docs/FIRST_VIDEO.md index 9d4fcff..179bba1 100644 --- a/docs/FIRST_VIDEO.md +++ b/docs/FIRST_VIDEO.md @@ -90,6 +90,8 @@ By default, PuppetControl refuses to replace an existing MP4 at the chosen outpu For ordinary revisions, prefer a new `--out` name so the prior render remains available. Scene IDs by default follow the scene filename, reducing collisions between different scenes. +For the filesystem and SHA-256 guarantees available during rendering (and their limits), see [RENDER_INTEGRITY.md](RENDER_INTEGRITY.md). Imported art and texture snapshots use a fresh render root; only scenes with `--binding` get a verified, private voice/cue copy before FFmpeg. + ## Verify an exported MP4 For a 5-second 15-fps 512x640 silent export: diff --git a/docs/IMPLEMENTATION_PLAN.md b/docs/IMPLEMENTATION_PLAN.md index 67a783b..f1a5bd8 100644 --- a/docs/IMPLEMENTATION_PLAN.md +++ b/docs/IMPLEMENTATION_PLAN.md @@ -95,6 +95,7 @@ This milestone is deliberately **narrower** than M5's universal single-image pro - [x] Validate the actual 75-frame, 15fps, 512×640 H.264 output of both scenes using FFprobe and visually inspect representative frames. - [x] Render an additional 12-second, 180-frame H.264/AAC sample using 36 real Rhubarb cues from a local test WAV; verify both streams and inspect representative frames. Local audio and video are ignored, not published. - [x] Prevent silent overwrite of existing MP4s by encoding to a temporary sibling file; `--force` explicitly replaces only after successful encoding. +- [x] Add verified per-render imported rig/textures and exact-byte-bound voice/cues copies, fresh frame roots, and explicit-root scene input confinement. Local QA produced a 45-frame silent imported-rig test export and a 45-frame H.264/AAC bound-voice export; this is not an OS sandbox against malicious concurrent file mutation. - [x] Make `scene validate` distinguish planning-valid bridge/caption/motion documents from scenes the current renderer can actually export, with actionable errors. - [ ] Achieve visibly polished eye/mouth deformation and user-friendly assisted rig correction on **diverse** artwork; the imported Hana avatar previously showed artifacts and remains unapproved. - [x] Add optional exact-byte SHA-256 Rhubarb cue binding sidecars; verified bound first-video scene and live H.264/AAC render. Sidecars are opt-in, and legacy scenes remain supported. diff --git a/docs/RENDER_INTEGRITY.md b/docs/RENDER_INTEGRITY.md new file mode 100644 index 0000000..f0ee79f --- /dev/null +++ b/docs/RENDER_INTEGRITY.md @@ -0,0 +1,36 @@ +# Verified render inputs and filesystem boundaries + +PuppetControl is a **local-first authoring CLI**. It processes user art and files supplied by agents. These safeguards address accidental source edits, ordinary file replacement between checks, and symlinked output destinations. They are **not a sandbox** against another process running with the same user permissions and deliberately modifying the private render snapshot during rendering. + +## Imported-character rig integrity + +After the normal imported-avatar SHA-256 build-record verification, `scene render` now copies the approved `source.png`, `avatar.json`, rig model and all recorded model textures into a fresh, ignored `verified-actor-assets/` directory under its unique frame-output root. Each copied file is SHA-256 checked against the existing build record. The Rev2D adapter reads the **copied** model and textures, never the original files during that render. If any bytes change before or during copying, the copy fails verification. + +This closes the ordinary gap where a rig could be checked at scene-load time and replaced at its original path before Rev2D opened it. The imported test fixture must still be *genuinely* visually reviewed before user approval; an integrity record is not an aesthetic certification or an approval signature. + +## Bound voice/cue integrity + +`audio bind` now parses **the exact cue bytes** that it hashes. When a scene has `audio.bindingPath`, `scene render` verifies the sidecar, copies WAV and cue JSON into a fresh ignored `verified-speech/` directory, hashes both copied inputs against the binding and parses the **copied** cue JSON. Rhubarb tracks use those cues and FFmpeg receives the **copied audio path**. + +This prevents ordinary source edits during an export from mixing new audio with an old cue file. Earlier scenes without an explicit binding remain supported and **do not** gain this protection. + +## Render output and explicit roots + +- Frame output must be **new**, rather than an existing directory that might contain old frames. A symlink/junction escape through its existing ancestors is rejected before rendering. +- The subprocess's list of frame names must match flat `frame_0000.png`-style names; a path-like name or traversal is rejected. +- `loadAndValidateScene(scene, { root })` now checks the scene, actors, and **all** audio, cue, and binding paths against the same realpath-aware root, returning diagnostics rather than throwing on escaped paths. +- The existing MP4 exporter still writes a unique temporary sibling MP4 and refuses overwrite without explicit `--force`. + +## Reproduction and evidence (2026-11-07) + +Run `npm run verify` to execute regression tests for copied asset integrity, path traversal, root-scoped loading, voice swaps, and guarded frame directories. For a locally installed pinned Rev2D backend and available FFmpeg, the actual video exports were separately exercised with two **ignored QA fixtures**: + +- `.cache/render-snapshot-qa-20261107-1800/qa-snapshot.mp4`: 3 seconds, 15 FPS, 512×640, 45 H.264 frames, silent. **The test copy alone** has an explicit forced approval marker to exercise the renderer. The underlying imported artwork was not user-approved and its original manifest remains unapproved. Do not distribute or use the test marker in normal workflows. +- `.cache/first-video-demo/qa-12s-voiced/verified-snapshot-3s.mp4`: 3 seconds, 15 FPS, 512×640, 45 H.264 frames plus one AAC stream. The output refers to an actual ignored `verified-speech/voice.wav` rather than the source file. +- Representative real PNG frames visually inspected at 0, 1 and 2 seconds, contact sheet under `outputs/qa/verified-render-inputs/qa-frames.jpg`. Video codec/duration/stream checks passed, but this does **not** establish the quality of eyelid transitions or lip sync on other speakers. + +## Limits and future review + +Neither SHA-256 nor checked paths are a cryptographic trust boundary against **malicious concurrent same-user modification of the newly copied frame directory**. Node and FFmpeg do not hold immutable read-only file descriptors from validation through every subprocess read; a same-user attacker can intentionally mutate these writable render artifacts. For hostile multiuser execution, a separate OS sandbox with private immutable mounts, privileges and per-process filesystem isolation is needed. That is outside PuppetControl's present local developer scope. + +Rig changes, repeated native speech samples, arbitrary-image eye deformation and cross-rig bridge animation still require independent perceptual QA. Keep stacked PRs in draft until reviewed. diff --git a/src/audio/cue-provenance.ts b/src/audio/cue-provenance.ts index d2ef56d..0f0cb0c 100644 --- a/src/audio/cue-provenance.ts +++ b/src/audio/cue-provenance.ts @@ -131,15 +131,18 @@ export async function createCueBinding( throw new CueBindingError("CUE_BINDING_PATH_INVALID", "Cue binding sidecar must be a separate file"); } - const cueText = await readFile(cues.fullPath, "utf8"); - const parsedCues = parseRhubarbMouthCuesJson(cueText); + // Parse the *same* bytes we hash. A separate filename reopen for the cue + // digest could otherwise hash a replacement file after parsing an older one. + const cueBytes = await readFile(cues.fullPath); + if (cueBytes.length < 1 || cueBytes.length > MAX_CUES_BYTES) { + throw new CueBindingError("CUE_BINDING_INPUT_INVALID", "Rhubarb cues are empty or oversized"); + } + const parsedCues = parseRhubarbMouthCuesJson(cueBytes.toString("utf8")); if (parsedCues.length === 0) { throw new CueBindingError("CUE_BINDING_INPUT_INVALID", "Rhubarb cue file must contain at least one mouth cue"); } - const [audioSha256, cuesSha256] = await Promise.all([ - fingerprint(audio.fullPath), - fingerprint(cues.fullPath), - ]); + const cuesSha256 = createHash("sha256").update(cueBytes).digest("hex"); + const audioSha256 = await fingerprint(audio.fullPath); const binding = cueBindingSchema.parse({ format: CUE_BINDING_FORMAT, version: CUE_BINDING_VERSION, diff --git a/src/render/rev2d.ts b/src/render/rev2d.ts index 40b4b37..b8079ce 100644 --- a/src/render/rev2d.ts +++ b/src/render/rev2d.ts @@ -2,17 +2,18 @@ import { randomUUID } from "node:crypto"; import { execFile } from "node:child_process"; import { promisify } from "node:util"; import { copyFile, link, lstat, mkdir, readFile, rename, stat, writeFile, unlink } from "node:fs/promises"; -import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path"; +import { basename, dirname, join, resolve } from "node:path"; import type { Character, Scene } from "../scene/schemas.js"; import { compilePerformance, PreviewUnsupportedError } from "./scene-plan.js"; import { parseRhubarbMouthCuesJson } from "../audio/rhubarb.js"; -import { verifyCueBinding } from "../audio/cue-provenance.js"; +import { snapshotBoundSpeech } from "./speech-snapshot.js"; import { buildFfmpegArgs, type FfmpegAudioInput } from "../audio/ffmpeg.js"; import type { VideoOutput } from "../video/output.js"; import type { SceneEvent } from "../scene/schemas.js"; import { planPoseTimeline, PoseTimelineError } from "../animation/pose-timeline.js"; import { verifyAvatarBuildRecord, checkAvatarPoseCoverage } from "../character/provenance.js"; import { checkedPath, pinnedRev2D } from "../character/avatar.js"; +import { snapshotImportedRig } from "./rig-snapshot.js"; const execFileAsync = promisify(execFile); @@ -40,6 +41,11 @@ interface Rev2DModel { animations: unknown[]; } +/** Accept only Rev2D's flat PNG frame names, never paths from the subprocess. */ +export function isSafeRev2DFrameName(value: unknown): value is string { + return typeof value === "string" && /^frame_[0-9]{4,8}\.png$/.test(value); +} + export interface FrameResult { framesDir: string; count: number; @@ -54,13 +60,28 @@ export interface FrameResult { camera?: { events: SceneEvent[]; sourceWidth: number; sourceHeight: number }; } -function insideRoot(path: string, root = process.cwd()): string { - const absolute = resolve(path); - const diff = relative(resolve(root), absolute); - if (diff === ".." || diff.startsWith(".." + sep) || isAbsolute(diff)) { - throw new PreviewUnsupportedError("PATH_OUTSIDE_WORKSPACE", "Path must be inside the project directory: " + absolute); +/** + * Frame directories are created once by this render, never reused. + * Resolve existing ancestors before mkdir so symlink/junction escapes are + * rejected even when the final target does not exist yet. + */ +export async function prepareFreshFrameDirectory( + outputDirectory: string, root = process.cwd(), +): Promise { + const destination = await checkedPath(root, resolve(outputDirectory)); + await mkdir(dirname(destination), { recursive: true }); + await checkedPath(root, destination); + try { + await mkdir(destination); + } catch (error) { + if (error instanceof Error && "code" in error && error.code === "EEXIST") { + throw new PreviewUnsupportedError("FRAME_DIRECTORY_EXISTS", + "This render directory already exists; choose a fresh path to avoid overwriting frames"); + } + throw error; } - return absolute; + await checkedPath(root, destination); + return destination; } async function execute(binary: string, args: string[], cwd: string, timeout: number): Promise { @@ -105,6 +126,7 @@ async function readRig(modelPath: string, scene: Scene): Promise { async function loadSpeech( scene: Scene, sceneFilePath: string, + framesDir: string, ): Promise<{ speech?: { cues: ReturnType; startMs: number }; audio?: FfmpegAudioInput; @@ -119,13 +141,18 @@ async function loadSpeech( const cuesFile = await checkedPath(process.cwd(), resolve(directory, entry.cuesPath)); if (entry.bindingPath) { - const bindingFile = await checkedPath(process.cwd(), resolve(directory, entry.bindingPath)); - const verified = await verifyCueBinding(source, cuesFile, bindingFile); - if (!verified.valid) { - throw new PreviewUnsupportedError(verified.code, verified.message); - } + const binding = await checkedPath(process.cwd(), resolve(directory, entry.bindingPath)); + const verifiedSnapshot = await snapshotBoundSpeech( + source, cuesFile, binding, join(framesDir, "verified-speech"), process.cwd(), + ); + return { + speech: { cues: verifiedSnapshot.cues, startMs: entry.startMs }, + audio: { path: verifiedSnapshot.audioPath, startMs: entry.startMs }, + }; } + // Legacy unbound scenes remain supported for compatibility. They do not + // claim protection against post-read changes to their source audio bytes. try { const file = await stat(source); if (!file.isFile() || file.size < 1) throw new Error("Speech file must be a nonempty file"); @@ -218,7 +245,8 @@ async function renderRigSegment(input: { args.push("--times", frameTimes.join(","), ...rev2dFrameRenderingFlags(scene)); const stdout = await execute(process.execPath, args, rev2dRoot, 240_000); const response = JSON.parse(stdout) as { files?: string[]; width?: number; height?: number }; - if (!Array.isArray(response.files) || response.files.length !== frameTimes.length) { + if (!Array.isArray(response.files) || response.files.length !== frameTimes.length || + response.files.some((entry) => !isSafeRev2DFrameName(entry))) { throw new PreviewUnsupportedError("RENDER_FRAME_COUNT_MISMATCH", "Rig segment rendered wrong number of frames."); } if (response.width !== scene.resolution.width || response.height !== scene.resolution.height) { @@ -294,11 +322,13 @@ export async function renderRev2DFrames( } const rev2dRoot = await checkedPath(process.cwd(), resolve(process.env.PUPPETCONTROL_REV2D_ROOT ?? ".cache/rev2d")); - const framesDir = insideRoot(outputDirectory); - const { speech, audio } = await loadSpeech(scene, sceneFilePath); const familyNames: string[] = []; - - await mkdir(framesDir, { recursive: true }); + const framesDir = await prepareFreshFrameDirectory(outputDirectory); + const { speech, audio } = await loadSpeech(scene, sceneFilePath, framesDir); + const isolatedRig = character.provenance ? await snapshotImportedRig( + characterPath, character.render.modelPath, + join(framesDir, "verified-actor-assets"), process.cwd(), + ) : undefined; let totalCopied = 0; for (const [segmentIndex, segment] of plan.segments.entries()) { // An interpolated transition occupies real output frames and uses the same @@ -311,7 +341,8 @@ export async function renderRev2DFrames( // Different artwork must use separately declared rig assets; sharing rigId // alone does not create a visual pose change. const rigFile = family.modelPath ?? character.render.modelPath; - const modelPath = await checkedPath(process.cwd(), resolve(dirname(characterPath), rigFile)); + const modelPath = isolatedRig?.modelPath ?? + await checkedPath(process.cwd(), resolve(dirname(characterPath), rigFile)); const model = await readRig(modelPath, scene); const segmentDir = join(framesDir, "segment_" + String(segmentIndex).padStart(3, "0")); const files = await renderRigSegment({ diff --git a/src/render/rig-snapshot.ts b/src/render/rig-snapshot.ts new file mode 100644 index 0000000..28ba70d --- /dev/null +++ b/src/render/rig-snapshot.ts @@ -0,0 +1,124 @@ +/** + * Materialize a provenance-checked, private *per-render* copy of an imported + * Rev2D rig and its texture files. + * + * No renderer is allowed to reopen the original model/texture paths after this + * step. Copies are verified against the approved source/spec/rig/texture record + * before Rev2D is invoked. The snapshot stays in the ignored frame directory. + * + * This excludes accidental/ordinary concurrent source replacement, but does + * NOT promise resistance to a malicious process with write access to the + * snapshot directory itself. + */ +import { createHash } from "node:crypto"; +import { createReadStream, constants } from "node:fs"; +import { copyFile, mkdir, readFile, realpath, stat } from "node:fs/promises"; +import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"; +import { checkedPath, PINNED_REV2D_SHA, AvatarWorkflowError } from "../character/avatar.js"; +import { AVATAR_BUILD_RECORD, avatarBuildRecordSchema } from "../character/provenance.js"; + +const MAX_SINGLE_ASSET_BYTES = 35 * 1024 * 1024; +const MAX_ASSETS = 1028; + +function canonicalAssetPath(path: string): boolean { + return !!path && !isAbsolute(path) && !path.includes("\\") && + !path.includes(":") && !path.startsWith("/") && + path.split("/").every((part) => part !== "" && part !== "." && part !== ".."); +} + +async function digestFile(filename: string, maxBytes = MAX_SINGLE_ASSET_BYTES): Promise { + const file = await stat(filename); + if (!file.isFile() || file.size < 1 || file.size > maxBytes) { + throw new AvatarWorkflowError("AVATAR_ASSETS_STALE", + "A source or snapshot asset is missing, empty or exceeds its size limit"); + } + const h = createHash("sha256"); + for await (const chunk of createReadStream(filename)) h.update(chunk as Buffer); + return h.digest("hex"); +} + +export interface VerifiedRigSnapshot { + modelPath: string; + snapshotDirectory: string; + fileCount: number; +} + +export async function snapshotImportedRig( + characterFile: string, + expectedModel: string, + snapshotDirectory: string, + root = process.cwd(), +): Promise { + const project = await realpath(dirname(await checkedPath(root, resolve(characterFile)))); + const recordFile = await checkedPath(project, join(project, AVATAR_BUILD_RECORD)); + const record = avatarBuildRecordSchema.parse( + JSON.parse(await readFile(recordFile, "utf8")) as unknown, + ); + if (record.backendCommit !== PINNED_REV2D_SHA || + record.model.path !== expectedModel.replaceAll("\\", "/") || + record.source.path !== "source.png" || record.spec.path !== "avatar.json" || + !record.textures.every((item) => item.path.startsWith("textures/"))) { + throw new AvatarWorkflowError("AVATAR_BUILD_RECORD_INVALID", + "Build record does not describe the expected Rev2D model and canonical source assets"); + } + + const entries = [record.source, record.spec, record.model, ...record.textures]; + if (entries.length > MAX_ASSETS || entries.some((item) => !canonicalAssetPath(item.path)) || + new Set(entries.map((item) => item.path)).size !== entries.length) { + throw new AvatarWorkflowError("AVATAR_BUILD_RECORD_INVALID", + "Build record contains invalid, duplicate or excessive asset references"); + } + + // Verify the model's texture list agrees with the record *before* copying it. + // The snapshot copy itself is hashed again below, so a source swap in between + // cannot silently produce a different renderer asset set. + const sourceModel = await checkedPath(project, join(project, record.model.path)); + const modelInfo = await stat(sourceModel); + if (!modelInfo.isFile() || modelInfo.size < 1 || modelInfo.size > 20_000_000) { + throw new AvatarWorkflowError("AVATAR_ASSETS_STALE", "Model missing or exceeds the 20 MB rig limit"); + } + const model = JSON.parse(await readFile(sourceModel, "utf8")) as { + textures?: Array<{ path?: unknown }>; + }; + if (!Array.isArray(model.textures)) { + throw new AvatarWorkflowError("AVATAR_TEXTURE_LIST_INVALID", "Imported rig has no valid textures"); + } + const texturePaths = model.textures.map((item) => { + const raw = item?.path; + const name = typeof raw === "string" && raw.startsWith("./") ? raw.slice(2) : raw; + if (typeof name !== "string" || !canonicalAssetPath(name) || !name.startsWith("textures/")) { + throw new AvatarWorkflowError("AVATAR_TEXTURE_LIST_INVALID", "Rig has a noncanonical texture path"); + } + return name; + }); + const unique = [...new Set(texturePaths)].sort(); + if (JSON.stringify(unique) !== JSON.stringify(record.textures.map((x) => x.path).sort())) { + throw new AvatarWorkflowError("AVATAR_TEXTURE_LIST_INVALID", + "Rig texture references do not match the provenance record"); + } + + const rootReal = await realpath(root); + const dst = await checkedPath(rootReal, resolve(snapshotDirectory)); + // Every render gets a new UUID-containing output directory; do not accept + // or overwrite an existing directory or any preexisting snapshot files. + await mkdir(dst); + const snapshotReal = await realpath(dst); + await checkedPath(rootReal, snapshotReal); + for (const item of entries) { + const from = await checkedPath(project, join(project, item.path)); + const out = await checkedPath(snapshotReal, join(snapshotReal, item.path)); + await mkdir(dirname(out), { recursive: true }); + await copyFile(from, out, constants.COPYFILE_EXCL); + const copiedHash = await digestFile(out); + if (copiedHash !== item.sha256) { + throw new AvatarWorkflowError("AVATAR_ASSETS_STALE", + "Source art, rig or texture bytes changed while preparing verified render inputs"); + } + } + const modelPath = await checkedPath(snapshotReal, join(snapshotReal, expectedModel)); + const diff = relative(snapshotReal, modelPath); + if (diff === ".." || diff.startsWith(".." + sep)) { + throw new AvatarWorkflowError("AVATAR_ASSETS_STALE", "Snapshot model escaped its private directory"); + } + return { modelPath, snapshotDirectory: snapshotReal, fileCount: entries.length }; +} diff --git a/src/render/speech-snapshot.ts b/src/render/speech-snapshot.ts new file mode 100644 index 0000000..6f81d9d --- /dev/null +++ b/src/render/speech-snapshot.ts @@ -0,0 +1,82 @@ +/** + * Consume exact verified WAV/cue bytes from private per-render copies. + * + * Checking a sidecar and later passing the *original* filename to FFmpeg + * leaves a replacement window. This helper copies both inputs into a fresh + * render-only folder and checks each copied byte stream against the binding. + * Rev2D receives cues parsed from that copied JSON; FFmpeg receives the copied + * audio path. Source-file replacement afterward cannot affect this export. + * + * As with rig snapshots, no Node filesystem API can defend an ignored render + * directory against a malicious same-user process modifying the copies. + */ +import { createHash } from "node:crypto"; +import { createReadStream, constants } from "node:fs"; +import { copyFile, mkdir, readFile, stat } from "node:fs/promises"; +import { dirname, extname, join, resolve } from "node:path"; +import { checkedPath } from "../character/avatar.js"; +import { parseRhubarbMouthCuesJson } from "../audio/rhubarb.js"; +import { verifyCueBinding, CueBindingError } from "../audio/cue-provenance.js"; + +const MAX_AUDIO = 200 * 1024 * 1024; +const MAX_CUES = 5 * 1024 * 1024; + +async function hashStream(path: string, max: number): Promise { + const info = await stat(path); + if (!info.isFile() || info.size < 1 || info.size > max) { + throw new CueBindingError("CUE_BINDING_STALE", "Snapshot input missing, empty or oversized"); + } + const h = createHash("sha256"); + for await (const chunk of createReadStream(path)) h.update(chunk as Buffer); + return h.digest("hex"); +} + +export async function snapshotBoundSpeech( + originalAudio: string, + originalCues: string, + sidecarFile: string, + destination: string, + root = process.cwd(), +): Promise<{ audioPath: string; cues: ReturnType }> { + const audio = await checkedPath(root, resolve(originalAudio)); + const cues = await checkedPath(root, resolve(originalCues)); + const bindingFile = await checkedPath(root, resolve(sidecarFile)); + const verified = await verifyCueBinding(audio, cues, bindingFile); + if (!verified.valid) { + throw new CueBindingError(verified.code, verified.message); + } + + const dst = await checkedPath(root, resolve(destination)); + await checkedPath(root, dirname(dst)); + await mkdir(dst); // Caller supplies a unique, never-reused render directory. + const suffix = extname(audio).toLowerCase(); + if (![".wav", ".mp3", ".m4a", ".flac", ".ogg"].includes(suffix)) { + throw new CueBindingError("CUE_BINDING_INPUT_INVALID", + "Bound speech audio must use a supported, explicit audio extension"); + } + const audioPath = await checkedPath(dst, join(dst, "voice" + suffix)); + const cuesPath = await checkedPath(dst, join(dst, "mouth-cues.json")); + await copyFile(audio, audioPath, constants.COPYFILE_EXCL); + await copyFile(cues, cuesPath, constants.COPYFILE_EXCL); + + // Compare the copied files with immutable expected hashes from the verified + // binding, not with a fresh read of potentially replaced original paths. + const [audioHash, cueBytes] = await Promise.all([ + hashStream(audioPath, MAX_AUDIO), + readFile(cuesPath), + ]); + if (cueBytes.length < 1 || cueBytes.length > MAX_CUES) { + throw new CueBindingError("CUE_BINDING_STALE", "Snapshot Rhubarb cues are missing or oversized"); + } + const cuesHash = createHash("sha256").update(cueBytes).digest("hex"); + if (audioHash !== verified.binding.audio.sha256 || + cuesHash !== verified.binding.cues.sha256) { + throw new CueBindingError("CUE_BINDING_STALE", + "Audio/cues changed between verification and copying into the renderer"); + } + const parsed = parseRhubarbMouthCuesJson(cueBytes.toString("utf8")); + if (!parsed.length) { + throw new CueBindingError("CUE_BINDING_INPUT_INVALID", "Bound Rhubarb cue list is empty"); + } + return { audioPath, cues: parsed }; +} diff --git a/src/scene/load.ts b/src/scene/load.ts index 04a9468..28d3fcc 100644 --- a/src/scene/load.ts +++ b/src/scene/load.ts @@ -15,15 +15,33 @@ export type LoadResult = | { valid: true; scene: Scene; characters: Map; check: SceneValidation } | { valid: false; diagnostics: Diagnostic[] }; -export async function loadAndValidateScene(filePath: string, options: { root?: string } = {}): Promise { - const absolutePath = options.root ? await checkedPath(options.root, resolve(filePath)) : resolve(filePath); +function invalid(code: string, path: string, message: string): Diagnostic { + return { severity: "error", code, path, message }; +} + +export async function loadAndValidateScene( + filePath: string, + options: { root?: string } = {}, +): Promise { + // A custom root must constrain *all* scene inputs, not merely the scene + // manifest and actors. Path checks also resolve existing symlink ancestors. + let absolutePath: string; + try { + absolutePath = options.root ? await checkedPath(options.root, resolve(filePath)) : resolve(filePath); + } catch (error) { + return { + valid: false, + diagnostics: [invalid("SCENE_PATH_OUTSIDE_WORKSPACE", filePath, String(error))], + }; + } + let raw: unknown; try { raw = await readJson(absolutePath); } catch (error) { return { valid: false, - diagnostics: [{ severity: "error", code: "SCENE_READ_FAILED", path: absolutePath, message: String(error) }], + diagnostics: [invalid("SCENE_READ_FAILED", absolutePath, String(error))], }; } @@ -31,77 +49,73 @@ export async function loadAndValidateScene(filePath: string, options: { root?: s if (!parsed.success) { return { valid: false, - diagnostics: parsed.error.issues.map((issue) => ({ - severity: "error" as const, - code: "SCENE_SCHEMA_INVALID", - path: issue.path.join("."), - message: issue.message, - })), + diagnostics: parsed.error.issues.map((issue) => + invalid("SCENE_SCHEMA_INVALID", issue.path.join("."), issue.message)), }; } const characters = new Map(); const diagnostics: Diagnostic[] = []; + const sceneDir = dirname(absolutePath); + for (const [index, audio] of parsed.data.audio.entries()) { - if (!audio.bindingPath) continue; // Legacy scenes remain supported. - if (!audio.cuesPath) { - diagnostics.push({ severity: "error", code: "CUE_BINDING_MISSING_OR_INVALID", - path: "audio." + index, message: "Bound audio requires Rhubarb cuesPath." }); + const audioPath = "audio." + index; + let source = resolve(sceneDir, audio.path); + let cuesFile = audio.cuesPath ? resolve(sceneDir, audio.cuesPath) : undefined; + let bindingFile = audio.bindingPath ? resolve(sceneDir, audio.bindingPath) : undefined; + if (options.root) { + try { + source = await checkedPath(options.root, source); + if (cuesFile) cuesFile = await checkedPath(options.root, cuesFile); + if (bindingFile) bindingFile = await checkedPath(options.root, bindingFile); + } catch (error) { + diagnostics.push(invalid("AUDIO_PATH_OUTSIDE_WORKSPACE", audioPath, String(error))); + continue; + } + } + if (!bindingFile) continue; // Older scenes without exact-byte binding still work. + if (!cuesFile) { + diagnostics.push(invalid("CUE_BINDING_MISSING_OR_INVALID", audioPath, + "Bound audio requires Rhubarb cuesPath")); continue; } - const directory = dirname(absolutePath); - const verified = await verifyCueBinding( - resolve(directory, audio.path), resolve(directory, audio.cuesPath), - resolve(directory, audio.bindingPath), - ); - if (!verified.valid) diagnostics.push({ - severity: "error", code: verified.code, - path: "audio." + index + ".bindingPath", message: verified.message, - }); + const verified = await verifyCueBinding(source, cuesFile, bindingFile); + if (!verified.valid) diagnostics.push(invalid( + verified.code, audioPath + ".bindingPath", verified.message)); } + for (const actor of parsed.data.actors) { - const characterFile = options.root - ? await checkedPath(options.root, resolve(dirname(absolutePath), actor.characterPath)) - : resolve(dirname(absolutePath), actor.characterPath); + let characterFile = resolve(sceneDir, actor.characterPath); try { + if (options.root) characterFile = await checkedPath(options.root, characterFile); const character = characterSchema.safeParse(await readJson(characterFile)); if (!character.success) { for (const issue of character.error.issues) { - diagnostics.push({ - severity: "error", code: "CHARACTER_SCHEMA_INVALID", - path: "actors." + actor.id + "." + issue.path.join("."), - message: issue.message, - }); + diagnostics.push(invalid("CHARACTER_SCHEMA_INVALID", + "actors." + actor.id + "." + issue.path.join("."), issue.message)); + } + continue; + } + if (character.data.provenance) { + const coverage = checkAvatarPoseCoverage(character.data); + if (!coverage.valid) { + diagnostics.push(invalid(coverage.code, "actors." + actor.id + ".provenance", coverage.message)); + continue; } - } else { - if (character.data.provenance) { - const coverage = checkAvatarPoseCoverage(character.data); - if (!coverage.valid) { - diagnostics.push({ - severity: "error", code: coverage.code, - path: "actors." + actor.id + ".provenance", message: coverage.message, - }); - continue; - } - const expectedModel = character.data.render?.modelPath; - const verified = expectedModel - ? await verifyAvatarBuildRecord(characterFile, expectedModel) - : { valid: false as const, code: "AVATAR_BUILD_RECORD_INVALID", message: "Imported character requires a configured model" }; - if (!verified.valid) { - diagnostics.push({ - severity: "error", code: verified.code, - path: "actors." + actor.id + ".provenance", message: verified.message, - }); - continue; - } + const expectedModel = character.data.render?.modelPath; + const verified = expectedModel + ? await verifyAvatarBuildRecord(characterFile, expectedModel) + : { valid: false as const, code: "AVATAR_BUILD_RECORD_INVALID", + message: "Imported character requires a configured model" }; + if (!verified.valid) { + diagnostics.push(invalid(verified.code, "actors." + actor.id + ".provenance", verified.message)); + continue; } - characters.set(actor.id, character.data); } + characters.set(actor.id, character.data); } catch (error) { - diagnostics.push({ - severity: "error", code: "CHARACTER_LOAD_FAILED", path: characterFile, - message: String(error), - }); + diagnostics.push(invalid("CHARACTER_LOAD_FAILED", "actors." + actor.id, + "Could not load character from its scoped path: " + String(error))); } } diff --git a/tests/frame-directory-safety.test.ts b/tests/frame-directory-safety.test.ts new file mode 100644 index 0000000..00ed831 --- /dev/null +++ b/tests/frame-directory-safety.test.ts @@ -0,0 +1,58 @@ +import { beforeEach, afterEach, describe, expect, it } from "vitest"; +import { mkdir, mkdtemp, readdir, rm, symlink } from "node:fs/promises"; +import { join, resolve } from "node:path"; +import { prepareFreshFrameDirectory, isSafeRev2DFrameName } from "../src/render/rev2d.js"; + +let home = ""; +let inside = ""; +let sibling = ""; +beforeEach(async () => { + await mkdir(resolve(".cache"), { recursive: true }); + home = await mkdtemp(resolve(".cache", "frame-path-safety-")); + inside = join(home, "inside"); + sibling = join(home, "sibling"); + await mkdir(inside); + await mkdir(sibling); +}); +afterEach(async () => { + if (home) await rm(home, { recursive: true, force: true }); +}); + +describe("subprocess-provided frame names", () => { + it("accepts only flat Rev2D frame filenames", () => { + expect(isSafeRev2DFrameName("frame_0000.png")).toBe(true); + expect(isSafeRev2DFrameName("frame_0023.png")).toBe(true); + for (const filename of [ + "../other.png", "./frame_0000.png", "segment/frame_0000.png", + "frame_0000.png/../../stolen", "frame_0000.jpg", "", null, 5, + ]) expect(isSafeRev2DFrameName(filename)).toBe(false); + }); +}); + +describe("new render frame directory confinement", () => { + it("creates a fresh directory inside its root", async () => { + const path = join(inside, "frames"); + expect(await prepareFreshFrameDirectory(path, inside)).toBe(path); + expect(await readdir(inside)).toEqual(["frames"]); + }); + + it("does not overwrite previous output, even an empty directory", async () => { + const path = join(inside, "existing"); + await mkdir(path); + await expect(prepareFreshFrameDirectory(path, inside)) + .rejects.toMatchObject({ code: "FRAME_DIRECTORY_EXISTS" }); + }); + + it("refuses an ancestor symlink/junction escaping the supplied workspace root", async () => { + const link = join(inside, "redirect"); + await symlink(sibling, link, process.platform === "win32" ? "junction" : "dir"); + await expect(prepareFreshFrameDirectory(join(link, "frames"), inside)) + .rejects.toMatchObject({ code: "PATH_OUTSIDE_WORKSPACE" }); + expect(await readdir(sibling)).toEqual([]); + }); + + it("refuses the workspace root itself as the frame output", async () => { + await expect(prepareFreshFrameDirectory(inside, inside)) + .rejects.toMatchObject({ code: "FRAME_DIRECTORY_EXISTS" }); + }); +}); diff --git a/tests/rig-snapshot.test.ts b/tests/rig-snapshot.test.ts new file mode 100644 index 0000000..e959057 --- /dev/null +++ b/tests/rig-snapshot.test.ts @@ -0,0 +1,74 @@ +import { beforeEach, afterEach, describe, expect, it } from "vitest"; +import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; +import { join, resolve } from "node:path"; +import { createAvatarBuildRecord, writeAvatarBuildRecord } from "../src/character/provenance.js"; +import { snapshotImportedRig } from "../src/render/rig-snapshot.js"; + +let root = ""; +let dir = ""; +let characterPath = ""; +beforeEach(async () => { + root = resolve(process.cwd()); + await mkdir(join(root, ".cache"), { recursive: true }); + dir = await mkdtemp(join(root, ".cache", "snapshot-rig-")); + await mkdir(join(dir, "textures")); + characterPath = join(dir, "character.json"); + await writeFile(characterPath, JSON.stringify({ id: "test" })); + await writeFile(join(dir, "source.png"), "source bytes"); + await writeFile(join(dir, "avatar.json"), '{"name":"source"}'); + await writeFile(join(dir, "textures", "face.png"), "face pixels"); + await writeFile(join(dir, "rig.r2d.json"), JSON.stringify({ + meta: { width: 512, height: 640 }, + textures: [{ id: "face", path: "./textures/face.png" }], + parameters: [], animations: [], + })); + await writeAvatarBuildRecord(dir, await createAvatarBuildRecord(dir, "rig.r2d.json")); +}); +afterEach(async () => { + if (dir) await rm(dir, { recursive: true, force: true }); +}); + +describe("approved avatar per-render asset snapshot", () => { + it("makes a private, independently hashed model+texture copy before render", async () => { + const result = await snapshotImportedRig( + characterPath, "rig.r2d.json", join(dir, "snapshot"), root, + ); + expect(result.fileCount).toBe(4); + const rig = JSON.parse(await readFile(result.modelPath, "utf8")); + expect(rig.textures[0].path).toBe("./textures/face.png"); + expect(await readFile(join(result.snapshotDirectory, "textures", "face.png"), "utf8")) + .toBe("face pixels"); + + // The renderer is handed the copied path. Original source swaps cannot + // affect the bytes in the copy that Rev2D consumes. + await writeFile(join(dir, "rig.r2d.json"), '{"swapped":true}'); + await writeFile(join(dir, "textures", "face.png"), "replacement"); + expect(JSON.parse(await readFile(result.modelPath, "utf8"))).toEqual(rig); + expect(await readFile(join(result.snapshotDirectory, "textures", "face.png"), "utf8")) + .toBe("face pixels"); + }); + + it("fails closed when a source asset changed before its snapshot was verified", async () => { + await writeFile(join(dir, "textures", "face.png"), "unapproved pixels"); + await expect(snapshotImportedRig( + characterPath, "rig.r2d.json", join(dir, "changed"), root, + )).rejects.toMatchObject({ code: "AVATAR_ASSETS_STALE" }); + }); + + it("refuses to reuse an existing snapshot or switch to an unexpected rig", async () => { + await mkdir(join(dir, "exists")); + await expect(snapshotImportedRig(characterPath, "rig.r2d.json", join(dir, "exists"), root)) + .rejects.toThrow(); + await expect(snapshotImportedRig(characterPath, "different.r2d.json", join(dir, "other"), root)) + .rejects.toMatchObject({ code: "AVATAR_BUILD_RECORD_INVALID" }); + }); + + it("refuses an edited build record that points to a texture escape", async () => { + const recordPath = join(dir, "avatar-build.json"); + const record = JSON.parse(await readFile(recordPath, "utf8")); + record.textures[0].path = "../elsewhere.png"; + await writeFile(recordPath, JSON.stringify(record)); + await expect(snapshotImportedRig(characterPath, "rig.r2d.json", join(dir, "malicious"), root)) + .rejects.toMatchObject({ code: "AVATAR_BUILD_RECORD_INVALID" }); + }); +}); diff --git a/tests/scene-root-confinement.test.ts b/tests/scene-root-confinement.test.ts new file mode 100644 index 0000000..e6769b6 --- /dev/null +++ b/tests/scene-root-confinement.test.ts @@ -0,0 +1,96 @@ +import { afterEach, beforeEach, describe, expect, it } from "vitest"; +import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises"; +import { join, resolve } from "node:path"; +import { loadAndValidateScene } from "../src/scene/load.js"; +import { createCueBinding } from "../src/audio/cue-provenance.js"; + +let home = ""; +let scope = ""; +let sibling = ""; +let sceneFile = ""; +const scene = (audio: unknown[] = [], characterPath = "character.json") => ({ + schemaVersion: 1, id: "scoped", durationMs: 3000, fps: 15, + resolution: { width: 512, height: 640 }, + actors: [{ id: "hana", characterPath }], + events: [], audio, +}); + +beforeEach(async () => { + await mkdir(resolve(".cache"), { recursive: true }); + home = await mkdtemp(resolve(".cache", "load-root-")); + scope = join(home, "scoped"); + sibling = join(home, "outside-scope"); + await mkdir(scope); + await mkdir(sibling); + sceneFile = join(scope, "scene.json"); + const original = await readFile(resolve("examples/characters/hana/character.json")); + await writeFile(join(scope, "character.json"), original); + await writeFile(join(sibling, "character.json"), original); +}); +afterEach(async () => { + if (home) await rm(home, { recursive: true, force: true }); +}); + +describe("scene and voice confinement to an explicit root", () => { + it("allows a local scene and actor", async () => { + await writeFile(sceneFile, JSON.stringify(scene())); + const result = await loadAndValidateScene(sceneFile, { root: scope }); + expect(result.valid).toBe(true); + }); + + it("does not throw on an out-of-root scene", async () => { + const result = await loadAndValidateScene(join(sibling, "scene.json"), { root: scope }); + expect(result.valid).toBe(false); + if (!result.valid) expect(result.diagnostics[0]?.code).toBe("SCENE_PATH_OUTSIDE_WORKSPACE"); + }); + + it("rejects escaped WAV/cue/sidecar paths before verifying a bound file", async () => { + await writeFile(sceneFile, JSON.stringify(scene([{ + actor: "hana", path: "../outside-scope/voice.wav", + cuesPath: "../outside-scope/cues.json", + bindingPath: "../outside-scope/voice.binding.json", startMs: 0, + }]))); + const result = await loadAndValidateScene(sceneFile, { root: scope }); + expect(result.valid).toBe(false); + if (!result.valid) expect(result.diagnostics.map((d) => d.code)) + .toContain("AUDIO_PATH_OUTSIDE_WORKSPACE"); + }); + + it("also refuses escaped unbound audio", async () => { + await writeFile(sceneFile, JSON.stringify(scene([{ + actor: "hana", path: "../outside-scope/voice.wav", startMs: 0, + }]))); + const result = await loadAndValidateScene(sceneFile, { root: scope }); + expect(result.valid).toBe(false); + if (!result.valid) expect(result.diagnostics.map((d) => d.code)) + .toContain("AUDIO_PATH_OUTSIDE_WORKSPACE"); + }); + + it("rejects a character reached through a symlink/junction to a sibling directory", async () => { + const alias = join(scope, "linked"); + await symlink(sibling, alias, process.platform === "win32" ? "junction" : "dir"); + await writeFile(sceneFile, JSON.stringify(scene([], "linked/character.json"))); + const result = await loadAndValidateScene(sceneFile, { root: scope }); + expect(result.valid).toBe(false); + if (!result.valid) expect(result.diagnostics.some((d) => + d.code === "CHARACTER_LOAD_FAILED")).toBe(true); + }); + + it("accepts a correctly bound voice/cue file entirely inside the specified root", async () => { + const wav = join(scope, "voice.wav"); + const cues = join(scope, "cues.json"); + const sidecar = join(scope, "voice.binding.json"); + await writeFile(wav, Buffer.from("RIFF-voice-fixture")); + await writeFile(cues, JSON.stringify({ + metadata: { duration: 0.3, soundFile: "voice.wav" }, + mouthCues: [{ start: 0, end: 0.3, value: "A" }], + })); + await createCueBinding(wav, cues, sidecar); + await writeFile(sceneFile, JSON.stringify(scene([{ + actor: "hana", path: "./voice.wav", cuesPath: "./cues.json", + bindingPath: "./voice.binding.json", startMs: 0, + }]))); + const result = await loadAndValidateScene(sceneFile, { root: scope }); + expect(result.valid).toBe(true); + }); +}); diff --git a/tests/speech-snapshot.test.ts b/tests/speech-snapshot.test.ts new file mode 100644 index 0000000..c63b78a --- /dev/null +++ b/tests/speech-snapshot.test.ts @@ -0,0 +1,65 @@ +import { afterEach, beforeEach, describe, expect, it } from "vitest"; +import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; +import { join, resolve } from "node:path"; +import { createCueBinding } from "../src/audio/cue-provenance.js"; +import { snapshotBoundSpeech } from "../src/render/speech-snapshot.js"; + +let dir = ""; +let wav = ""; +let cues = ""; +let sidecar = ""; +const initialAudio = Buffer.from("RIFF-demo-voice-contents"); +const initialCues = JSON.stringify({ + metadata: { soundFile: "voice.wav", duration: 0.25 }, + mouthCues: [{ start: 0, end: 0.25, value: "A" }], +}); + +beforeEach(async () => { + await mkdir(resolve(".cache"), { recursive: true }); + dir = await mkdtemp(resolve(".cache", "bound-speech-snapshot-")); + wav = join(dir, "voice.wav"); + cues = join(dir, "cues.json"); + sidecar = join(dir, "cues.binding.json"); + await writeFile(wav, initialAudio); + await writeFile(cues, initialCues); + await createCueBinding(wav, cues, sidecar); +}); +afterEach(async () => { + if (dir) await rm(dir, { recursive: true, force: true }); +}); + +describe("verified speech uses per-render immutable-by-origin copies", () => { + it("parses the copied cue bytes and supplies FFmpeg only the copied audio", async () => { + const snapshot = await snapshotBoundSpeech(wav, cues, sidecar, join(dir, "private-a")); + expect(snapshot.audioPath).toContain("private-a"); + expect(snapshot.cues).toHaveLength(1); + expect(await readFile(snapshot.audioPath)).toEqual(initialAudio); + + await writeFile(wav, Buffer.from("RIFF-swapped-unapproved-voice")); + await writeFile(cues, '{"not":"rhubarb cues"}'); + + expect(await readFile(snapshot.audioPath)).toEqual(initialAudio); + expect(snapshot.cues[0]?.value).toBe("A"); + }); + + it("refuses changed voice bytes before materializing the snapshot", async () => { + await writeFile(wav, Buffer.from("RIFF-unauthorized")); + await expect(snapshotBoundSpeech(wav, cues, sidecar, join(dir, "private-b"))) + .rejects.toMatchObject({ code: "CUE_BINDING_STALE" }); + }); + + it("refuses changed cues before materializing the snapshot", async () => { + await writeFile(cues, JSON.stringify({ + metadata: { soundFile: "voice.wav", duration: 0.25 }, + mouthCues: [{ start: 0, end: 0.25, value: "B" }], + })); + await expect(snapshotBoundSpeech(wav, cues, sidecar, join(dir, "private-c"))) + .rejects.toMatchObject({ code: "CUE_BINDING_STALE" }); + }); + + it("rejects reusing a previously created private output directory", async () => { + const name = join(dir, "private-d"); + await snapshotBoundSpeech(wav, cues, sidecar, name); + await expect(snapshotBoundSpeech(wav, cues, sidecar, name)).rejects.toThrow(); + }); +});