Open source CapCut alternative.
TypeScript
feat(site): the engine holds clips a paired phone hands over [rebuild]
David Lecd671a04beec
diff --git a/site/src/cut/engine/serve.ts b/site/src/cut/engine/serve.tsindex 8bf81571..02c11125 100644--- a/site/src/cut/engine/serve.ts+++ b/site/src/cut/engine/serve.ts@@ -1,6 +1,7 @@import { allowedOrigin, corsHeaders, preflightHeaders } from "../server/cors";import { matchCutRoute, runCutRoute } from "../server/http/routes";import { flattenCutUsers, migrateCutDataDir } from "../server/migrateDataDir";+import { sweepPhoneInbox } from "../server/phoneLink";import { reconcileProjectDirs } from "../server/projects";import { ensureToolPath, resolveOnPath } from "../server/tool-path";import { enginePort } from "./config";@@ -40,6 +41,10 @@ async function start() {migrateCutDataDir();flattenCutUsers();reconcileProjectDirs();+ // The phone inbox is staging, so what no editor took is cleared here rather+ // than kept: a shoot nobody opened a project for is a second full copy of+ // itself sitting on the disk.+ await sweepPhoneInbox().catch(() => {});await ensureToolPath();// The Agent SDK can't resolve its built-in CLI from inside a compileddiff --git a/site/src/cut/server/http/next.ts b/site/src/cut/server/http/next.tsindex 5df33db6..0889720f 100644--- a/site/src/cut/server/http/next.ts+++ b/site/src/cut/server/http/next.ts@@ -1,5 +1,6 @@import { hostedApiBlock } from "../local-only";import { flattenCutUsers } from "../migrateDataDir";+import { sweepPhoneInbox } from "../phoneLink";import { reconcileProjectDirs } from "../projects";import { ensureToolPath } from "../tool-path";import { matchCutRoute, runCutRoute } from "./routes";@@ -10,6 +11,7 @@ function flattenOnce() {flattened = true;flattenCutUsers();reconcileProjectDirs();+ void sweepPhoneInbox().catch(() => {});}/**diff --git a/site/src/cut/server/http/phoneLink.ts b/site/src/cut/server/http/phoneLink.tsnew file mode 100644index 00000000..ffe0b246--- /dev/null+++ b/site/src/cut/server/http/phoneLink.ts@@ -0,0 +1,212 @@+import {+ addPhoneClip,+ claimPhoneClip,+ claimPhonePairing,+ closePhonePairing,+ listPhoneClips,+ listPhoneDevices,+ movePhoneClipToProject,+ openPhonePairing,+ phoneClipPath,+ phoneDeviceForToken,+ phonePairingClose,+ phonePairingWindow,+ releasePhoneClip,+ removePhoneClip,+ removePhoneDevice,+} from "../phoneLink";+import { serveFileRange } from "../serveFile";++const err = (message: string, status: number) => Response.json({ error: message }, { status });+const caught = (e: unknown, fallback: string) =>+ err(e instanceof Error ? e.message : fallback, 500);++/** The header a paired phone's traffic carries. The app's listener copies it+ * across from the peer connection; nothing else on this Mac sets it. */+const TOKEN_HEADER = "x-donkey-phone-token";++/** The app names the file it already staged on this Mac's disk, and the engine+ * moves it into the inbox instead of taking a second copy through loopback. */+const STAGED_HEADER = "x-donkey-phone-file";++/**+ * The phone link's API: pairing, the paired devices, and the inbox of clips+ * waiting for an editor.+ *+ * Two callers, both on loopback. The settings page mints and revokes, and reads+ * the device list. The app's peer listener checks a phone's token before it+ * writes a byte, claims a pairing code on a phone's behalf, and hands over the+ * clips it has staged.+ */+export const phoneLinkApi = {+ /** The devices paired with this Mac, the pairing code if one is open, and how+ * the last window ended when one is not. */+ async status() {+ try {+ return Response.json({+ devices: await listPhoneDevices(),+ pairing: phonePairingWindow(),+ closed: phonePairingClose(),+ });+ } catch (e) {+ return caught(e, "Could not read the phone link.");+ }+ },++ /** Open a pairing window and answer with the code to show. */+ pair() {+ try {+ return Response.json(openPhonePairing());+ } catch (e) {+ return caught(e, "Could not start pairing.");+ }+ },++ /** Close an open window without pairing anything — the dialog was dismissed. */+ cancelPairing() {+ closePhonePairing();+ return Response.json({ ok: true });+ },++ /** A phone answering the code, relayed by the app's listener. The token in+ * the reply is the only time it exists outside the phone. */+ async claim(req: Request) {+ try {+ const { code, deviceName } = (await req.json()) as {+ code?: string;+ deviceName?: string;+ };+ const paired = await claimPhonePairing(code ?? "", deviceName ?? "");+ if (!paired) return err("That code is not open.", 403);+ return Response.json(paired);+ } catch (e) {+ return caught(e, "Could not pair that phone.");+ }+ },++ /** Is this phone still paired? The listener asks before it writes a clip to+ * disk: the bytes come off an open radio, and an unpaired sender must not be+ * able to spend this Mac's storage on the way to being refused. */+ async verify(req: Request) {+ try {+ const device = await phoneDeviceForToken(req.headers.get(TOKEN_HEADER) ?? "");+ if (!device) return err("This phone is not paired with this Mac.", 401);+ return Response.json({ device });+ } catch (e) {+ return caught(e, "Could not check that phone.");+ }+ },++ async devices() {+ try {+ return Response.json({ devices: await listPhoneDevices() });+ } catch (e) {+ return caught(e, "Could not read the paired phones.");+ }+ },++ /** Unpair: the phone's token stops working on its next upload. */+ async removeDevice(_req: Request, { id }: { id: string }) {+ try {+ await removePhoneDevice(decodeURIComponent(id));+ return Response.json({ ok: true });+ } catch (e) {+ return caught(e, "Could not unpair that phone.");+ }+ },++ /** A clip off a paired phone. The app has already staged the bytes on this+ * Mac, so this call is metadata and a path; the engine moves the file in. */+ async receive(req: Request) {+ try {+ const device = await phoneDeviceForToken(req.headers.get(TOKEN_HEADER) ?? "");+ if (!device) return err("This phone is not paired with this Mac.", 401);+ const staged = req.headers.get(STAGED_HEADER);+ if (!staged) return err("No staged clip named.", 400);+ const q = new URL(req.url).searchParams;+ const takeId = q.get("takeId");+ if (!takeId) return err("A clip carries the take it came from.", 400);+ const num = (key: string) => {+ const n = Number(q.get(key));+ return Number.isFinite(n) && n > 0 ? n : undefined;+ };+ const clip = await addPhoneClip(device, staged, {+ takeId,+ fileName: q.get("fileName") ?? "clip.mov",+ capturedAt: num("capturedAt"),+ durationSeconds: num("durationSeconds"),+ width: num("width"),+ height: num("height"),+ });+ return Response.json(clip);+ } catch (e) {+ return caught(e, "Could not take that clip.");+ }+ },++ /** What is waiting and unclaimed. The editor polls this while a phone is+ * paired. */+ async inbox() {+ try {+ return Response.json({ clips: await listPhoneClips() });+ } catch (e) {+ return caught(e, "Could not read the phone inbox.");+ }+ },++ /** Take a clip. Exactly one editor gets it; a second asking is told it is+ * already spoken for rather than handed a copy of its own. */+ async claimClip(_req: Request, { id }: { id: string }) {+ try {+ const clip = await claimPhoneClip(decodeURIComponent(id));+ if (!clip) return err("That clip is already taken.", 409);+ return Response.json(clip);+ } catch (e) {+ return caught(e, "Could not take that clip.");+ }+ },++ /** Give a claimed clip back, so the next pass finds it waiting. */+ async releaseClip(_req: Request, { id }: { id: string }) {+ try {+ await releasePhoneClip(decodeURIComponent(id));+ return Response.json({ ok: true });+ } catch (e) {+ return caught(e, "Could not put that clip back.");+ }+ },++ /** Move a claimed clip into a project on this Mac. Both ends are local disk,+ * so the bytes never go through the page. */+ async intoProject(req: Request, { id }: { id: string }) {+ try {+ const { projectId } = (await req.json()) as { projectId?: string };+ if (!projectId) return err("No project named.", 400);+ const fileName = await movePhoneClipToProject(decodeURIComponent(id), projectId);+ return Response.json({ fileName });+ } catch (e) {+ return caught(e, "Could not move that clip into the project.");+ }+ },++ /** The bytes, ranged — the editor reads them straight into its own store. */+ async clipFile(req: Request, { id }: { id: string }) {+ try {+ const file = await phoneClipPath(decodeURIComponent(id));+ if (!file) return err("That clip is gone.", 404);+ return serveFileRange(file, req);+ } catch (e) {+ return caught(e, "Could not read that clip.");+ }+ },++ /** Claimed, or thrown away. Either way the inbox lets it go. */+ async removeClip(_req: Request, { id }: { id: string }) {+ try {+ await removePhoneClip(decodeURIComponent(id));+ return Response.json({ ok: true });+ } catch (e) {+ return caught(e, "Could not clear that clip.");+ }+ },+};diff --git a/site/src/cut/server/http/routes.ts b/site/src/cut/server/http/routes.tsindex df51ab46..40f84270 100644--- a/site/src/cut/server/http/routes.ts+++ b/site/src/cut/server/http/routes.ts@@ -6,6 +6,7 @@ import { engineApi } from "./engine";import { exportApi } from "./export";import { libraryApi } from "./library";import { micApi } from "./mic";+import { phoneLinkApi } from "./phoneLink";import { projectsApi } from "./projects";import { sttApi } from "./stt";@@ -54,6 +55,23 @@ export const CUT_ROUTES: CutRoute[] = [{ method: "POST", path: "/api/cut/projects/:id/duplicate", handler: (req, p) => projectsApi.duplicate(req, { id: p.id }) },{ method: "GET", path: "/api/cut/projects/:id/preview", handler: (req, p) => projectsApi.servePreview(req, { id: p.id }) },+ // The phone link: an iPhone shooting in the field hands its clips to this+ // Mac over the app's peer listener, and the open editor claims them.+ { method: "GET", path: "/api/cut/phone", handler: () => phoneLinkApi.status() },+ { method: "POST", path: "/api/cut/phone/pair", handler: () => phoneLinkApi.pair() },+ { method: "DELETE", path: "/api/cut/phone/pair", handler: () => phoneLinkApi.cancelPairing() },+ { method: "POST", path: "/api/cut/phone/pair/claim", handler: (req) => phoneLinkApi.claim(req) },+ { method: "POST", path: "/api/cut/phone/verify", handler: (req) => phoneLinkApi.verify(req) },+ { method: "GET", path: "/api/cut/phone/devices", handler: () => phoneLinkApi.devices() },+ { method: "DELETE", path: "/api/cut/phone/devices/:id", handler: (req, p) => phoneLinkApi.removeDevice(req, { id: p.id }) },+ { method: "POST", path: "/api/cut/phone/clips", handler: (req) => phoneLinkApi.receive(req) },+ { method: "GET", path: "/api/cut/phone/clips", handler: () => phoneLinkApi.inbox() },+ { method: "POST", path: "/api/cut/phone/clips/:id/claim", handler: (req, p) => phoneLinkApi.claimClip(req, { id: p.id }) },+ { method: "POST", path: "/api/cut/phone/clips/:id/release", handler: (req, p) => phoneLinkApi.releaseClip(req, { id: p.id }) },+ { method: "POST", path: "/api/cut/phone/clips/:id/into-project", handler: (req, p) => phoneLinkApi.intoProject(req, { id: p.id }) },+ { method: "GET", path: "/api/cut/phone/clips/:id/file", handler: (req, p) => phoneLinkApi.clipFile(req, { id: p.id }) },+ { method: "DELETE", path: "/api/cut/phone/clips/:id", handler: (req, p) => phoneLinkApi.removeClip(req, { id: p.id }) },+{ method: "GET", path: "/api/cut/library", handler: () => libraryApi.list() },{ method: "POST", path: "/api/cut/library", handler: (req) => libraryApi.upload(req) },{ method: "POST", path: "/api/cut/library/use", handler: (req) => libraryApi.use(req) },diff --git a/site/src/cut/server/phoneLink.test.ts b/site/src/cut/server/phoneLink.test.tsnew file mode 100644index 00000000..75cec357--- /dev/null+++ b/site/src/cut/server/phoneLink.test.ts@@ -0,0 +1,266 @@+import { afterEach, beforeEach, expect, test } from "bun:test";+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";+import { tmpdir } from "node:os";+import path from "node:path";++import {+ addPhoneClip,+ claimPhoneClip,+ claimPhonePairing,+ listPhoneClips,+ listPhoneDevices,+ movePhoneClipToProject,+ openPhonePairing,+ phoneClipPath,+ phoneDeviceForToken,+ phonePairingClose,+ phonePairingWindow,+ releasePhoneClip,+ removePhoneClip,+ removePhoneDevice,+ sweepPhoneInbox,+ type PhoneDeviceInfo,+} from "./phoneLink";++let dataDir: string;+let staging: string;+let previous: string | undefined;++beforeEach(async () => {+ previous = process.env.DONKEY_CUT_DATA_DIR;+ dataDir = await mkdtemp(path.join(tmpdir(), "phone-link-"));+ staging = await mkdtemp(path.join(tmpdir(), "phone-staged-"));+ process.env.DONKEY_CUT_DATA_DIR = dataDir;+});++afterEach(async () => {+ if (previous === undefined) delete process.env.DONKEY_CUT_DATA_DIR;+ else process.env.DONKEY_CUT_DATA_DIR = previous;+ await rm(dataDir, { force: true, recursive: true });+ await rm(staging, { force: true, recursive: true });+});++/** A clip the app has staged in the temp directory, ready to be moved in. */+async function staged(name: string, contents: string): Promise<string> {+ const file = path.join(staging, `${crypto.randomUUID()}-${name}`);+ await writeFile(file, contents);+ return file;+}++async function pairedPhone(): Promise<PhoneDeviceInfo> {+ const open = openPhonePairing();+ return (await claimPhonePairing(open.code, "iPhone"))!.device;+}++const exists = (p: string) => stat(p).then(() => true, () => false);+const inbox = () => path.join(dataDir, "phone", "inbox");++test("a phone pairs on the open code, and only on that code", async () => {+ const open = openPhonePairing();+ expect(await claimPhonePairing("000-000", "Wrong phone")).toBeNull();++ const paired = await claimPhonePairing(open.code, "David's iPhone");+ expect(paired?.device.name).toBe("David's iPhone");+ expect(paired?.token).toHaveLength(64);++ // The code is spent: a second phone cannot ride the same one in.+ expect(await claimPhonePairing(open.code, "Someone else's iPhone")).toBeNull();+ expect(phonePairingClose()).toBe("paired");+});++test("three wrong answers close the window", async () => {+ const open = openPhonePairing();+ for (let i = 0; i < 3; i++) {+ expect(await claimPhonePairing("111-111", "Guesser")).toBeNull();+ }+ expect(phonePairingWindow()).toBeNull();+ expect(phonePairingClose()).toBe("refused");+ // Even the right code is no good once the window is shut.+ expect(await claimPhonePairing(open.code, "iPhone")).toBeNull();+ expect(await listPhoneDevices()).toHaveLength(0);+});++test("the token never lands on disk", async () => {+ const open = openPhonePairing();+ const paired = await claimPhonePairing(open.code, "iPhone");+ const devices = await readFile(path.join(dataDir, "phone", "devices.json"), "utf8");+ expect(devices).not.toContain(paired!.token);+ expect(await listPhoneDevices()).toHaveLength(1);+});++test("a token is only good while its device is paired", async () => {+ const open = openPhonePairing();+ const paired = (await claimPhonePairing(open.code, "iPhone"))!;+ expect((await phoneDeviceForToken(paired.token))?.id).toBe(paired.device.id);++ await removePhoneDevice(paired.device.id);+ expect(await phoneDeviceForToken(paired.token)).toBeNull();+});++test("an upload in flight cannot undo an unpair", async () => {+ const open = openPhonePairing();+ const paired = (await claimPhonePairing(open.code, "iPhone"))!;++ // The upload's last-seen touch and the unpair race: both read the list, both+ // write it back. Serialized, the removal is the one that stands.+ const touching = phoneDeviceForToken(paired.token);+ const unpairing = removePhoneDevice(paired.device.id);+ await Promise.all([touching, unpairing]);++ expect(await listPhoneDevices()).toHaveLength(0);+ expect(await phoneDeviceForToken(paired.token)).toBeNull();+});++test("clips land in the inbox oldest shot first and leave on claim", async () => {+ const device = await pairedPhone();++ const second = await addPhoneClip(device, await staged("b.mov", "second take"), {+ takeId: "take-b",+ fileName: "b.mov",+ capturedAt: 2000,+ });+ await addPhoneClip(device, await staged("a.mov", "first take"), {+ takeId: "take-a",+ fileName: "a.mov",+ capturedAt: 1000,+ });++ const clips = await listPhoneClips();+ expect(clips.map((c) => c.fileName)).toEqual(["a.mov", "b.mov"]);+ expect(clips[1].bytes).toBe("second take".length);++ expect(await readFile((await phoneClipPath(second.id))!, "utf8")).toBe("second take");++ await removePhoneClip(second.id);+ expect(await phoneClipPath(second.id)).toBeNull();+ expect(await listPhoneClips()).toHaveLength(1);+});++test("the same take arriving twice is one clip", async () => {+ const device = await pairedPhone();+ const input = { takeId: "take-1", fileName: "a.mov", capturedAt: 1000 };++ const first = await addPhoneClip(device, await staged("a.mov", "the take"), input);+ // The phone never read the acknowledgement, so it sends the same take again.+ const resend = await staged("a.mov", "the take");+ const second = await addPhoneClip(device, resend, input);++ expect(second.id).toBe(first.id);+ expect(await listPhoneClips()).toHaveLength(1);+ // The re-sent file is not left lying in staging.+ expect(await exists(resend)).toBe(false);+});++test("only one editor can claim a clip", async () => {+ const device = await pairedPhone();+ const clip = await addPhoneClip(device, await staged("a.mov", "the take"), {+ takeId: "take-1",+ fileName: "a.mov",+ });++ const [a, b] = await Promise.all([claimPhoneClip(clip.id), claimPhoneClip(clip.id)]);+ expect([a, b].filter(Boolean)).toHaveLength(1);+ // A claimed clip is not offered again.+ expect(await listPhoneClips()).toHaveLength(0);+ // Its bytes are still readable by whoever holds it.+ expect(await phoneClipPath(clip.id)).not.toBeNull();+});++test("a released clip goes back in the inbox", async () => {+ const device = await pairedPhone();+ const clip = await addPhoneClip(device, await staged("a.mov", "the take"), {+ takeId: "take-1",+ fileName: "a.mov",+ });++ expect(await claimPhoneClip(clip.id)).not.toBeNull();+ await releasePhoneClip(clip.id);+ expect((await listPhoneClips()).map((c) => c.id)).toEqual([clip.id]);+ // And it can be claimed again.+ expect(await claimPhoneClip(clip.id)).not.toBeNull();+});++test("a clip moves into a project without a copy", async () => {+ const device = await pairedPhone();+ const clip = await addPhoneClip(device, await staged("a.mov", "the take"), {+ takeId: "take-1",+ fileName: "a.mov",+ });+ await claimPhoneClip(clip.id);++ const projectId = crypto.randomUUID();+ await mkdir(path.join(dataDir, "projects", projectId), { recursive: true });++ const fileName = await movePhoneClipToProject(clip.id, projectId);+ const landed = path.join(dataDir, "projects", projectId, "media", fileName);+ expect(await readFile(landed, "utf8")).toBe("the take");+ // Nothing of it is left in the inbox.+ expect(await phoneClipPath(clip.id)).toBeNull();+ expect(await listPhoneClips()).toHaveLength(0);+});++test("the sweep clears orphans, records with no bytes, and stale clips", async () => {+ const device = await pairedPhone();+ const keep = await addPhoneClip(device, await staged("keep.mov", "keeping"), {+ takeId: "take-keep",+ fileName: "keep.mov",+ });++ // Bytes from a transfer that broke before its record was written.+ const orphan = path.join(inbox(), `${crypto.randomUUID()}.mov`);+ await writeFile(orphan, "half a take");++ // A record whose bytes are gone.+ const gone = await addPhoneClip(device, await staged("gone.mov", "going"), {+ takeId: "take-gone",+ fileName: "gone.mov",+ });+ await rm((await phoneClipPath(gone.id))!, { force: true });++ // A clip older than the inbox keeps.+ const stale = await addPhoneClip(device, await staged("old.mov", "ancient"), {+ takeId: "take-old",+ fileName: "old.mov",+ });+ const staleMeta = path.join(inbox(), `${stale.id}.json`);+ await writeFile(+ staleMeta,+ JSON.stringify({ ...stale, receivedAt: Date.now() - 30 * 24 * 60 * 60 * 1000 })+ );++ await sweepPhoneInbox();++ expect(await exists(orphan)).toBe(false);+ expect(await phoneClipPath(gone.id)).toBeNull();+ expect(await phoneClipPath(stale.id)).toBeNull();+ expect((await listPhoneClips()).map((c) => c.id)).toEqual([keep.id]);+});++test("a record with no bytes is never offered", async () => {+ const device = await pairedPhone();+ const clip = await addPhoneClip(device, await staged("a.mov", "the take"), {+ takeId: "take-1",+ fileName: "a.mov",+ });+ await rm((await phoneClipPath(clip.id))!, { force: true });+ expect(await listPhoneClips()).toHaveLength(0);+});++test("a phone cannot name a path", async () => {+ const device = await pairedPhone();++ const clip = await addPhoneClip(device, await staged("passwd.mov", "x"), {+ takeId: "take-1",+ fileName: "../../../../etc/passwd.mov",+ });+ expect(clip.fileName).toBe("passwd.mov");+ // The bytes are written under an id of ours, inside the inbox.+ expect(await phoneClipPath(clip.id)).toBe(path.join(inbox(), `${clip.id}.mov`));+});++test("a staged clip comes only from the staging directory", async () => {+ const device = await pairedPhone();+ await expect(+ addPhoneClip(device, "/etc/passwd", { takeId: "take-1", fileName: "take.mov" })+ ).rejects.toThrow("temp directory");+});diff --git a/site/src/cut/server/phoneLink.ts b/site/src/cut/server/phoneLink.tsnew file mode 100644index 00000000..febacf1c--- /dev/null+++ b/site/src/cut/server/phoneLink.ts@@ -0,0 +1,546 @@+import { createHash, randomBytes, randomInt, timingSafeEqual } from "node:crypto";+import { copyFile, mkdir, readdir, readFile, rename, rm, stat } from "node:fs/promises";+import os from "node:os";+import path from "node:path";++import { cutDataRoot } from "./dataDir";+import { assertLocalRuntime } from "./local-only";+import { mediaDir, mediaPath } from "./projects";+import { exists, uniqueName, writeJsonAtomic } from "./util";++/**+ * The phone link: clips shot on an iPhone in the field, handed to this Mac over+ * peer-to-peer Wi-Fi and held here until the editor takes them.+ *+ * The engine owns both halves of it. Pairing is a code the settings page mints+ * and the phone answers with, which buys the phone a token it keeps; every clip+ * after that arrives carrying the token. The app's listener is a pipe — it+ * terminates the peer connection and forwards here, so the only place a device+ * or a pending clip is written down is this Mac's disk.+ *+ * The inbox is a staging area, not storage: a clip sits in it until an open+ * editor claims it into a project, wherever that project lives. That indirection+ * is what lets a browser-resident project receive from a phone at all — the page+ * pulls the bytes off loopback and writes them into its own OPFS.+ *+ * Two editors can be open on one Mac, so taking a clip is a claim rather than a+ * read: the claim renames the record, which the filesystem performs for exactly+ * one caller, and the loser finds nothing to rename. A claim that is never+ * finished — the tab closed mid-import — lapses back into the inbox.+ */++const phoneRoot = () => path.join(cutDataRoot(), "phone");+const devicesPath = () => path.join(phoneRoot(), "devices.json");+const inboxRoot = () => path.join(phoneRoot(), "inbox");+const clipMetaPath = (id: string) => path.join(inboxRoot(), `${id}.json`);+/** A claimed clip's record, under a name a second claim cannot find. */+const claimedMetaPath = (id: string) => path.join(inboxRoot(), `${id}.claimed.json`);++/** A phone that has paired with this Mac. The token never lands on disk — only+ * its hash, so a readable devices.json is not a credential. */+export interface PhoneDevice {+ id: string;+ name: string;+ tokenHash: string;+ pairedAt: number;+ lastSeenAt: number;+}++/** A device as anything outside this module sees it. */+export type PhoneDeviceInfo = Omit<PhoneDevice, "tokenHash">;++/** A clip waiting in the inbox for an editor to claim it. */+export interface PhoneClip {+ id: string;+ /** The take's id on the phone, stable across re-sends. A phone that loses an+ * acknowledgement sends the take again; this is how the second arrival is+ * recognised as the copy already here. */+ takeId: string;+ deviceId: string;+ deviceName: string;+ /** The name the file takes when it lands in a project. */+ fileName: string;+ bytes: number;+ /** When the phone shot it, by the phone's clock. */+ capturedAt: number;+ receivedAt: number;+ durationSeconds?: number;+ width?: number;+ height?: number;+ /** When an editor claimed it. Only on a claimed record. */+ claimedAt?: number;+}++const hashToken = (token: string) => createHash("sha256").update(token).digest("hex");++/** Constant-time compare of two hex digests of equal length. */+function sameHash(a: string, b: string): boolean {+ if (a.length !== b.length) return false;+ return timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));+}++// MARK: Devices++/**+ * Every change to the device list runs through here, one at a time.+ *+ * The list is read, changed and written back with awaits in between, so two of+ * those interleaved would each write a list built before the other's change: an+ * upload touching its device's last-seen stamp would put back a device the user+ * had just unpaired, and the revoked token would keep working.+ */+let deviceWrites: Promise<unknown> = Promise.resolve();++function withDeviceList<T>(work: (devices: PhoneDevice[]) => Promise<T> | T): Promise<T> {+ const next = deviceWrites.then(async () => work(await readDevices()));+ // The chain carries on after a failure; one bad write does not wedge the rest.+ deviceWrites = next.catch(() => {});+ return next;+}++async function readDevices(): Promise<PhoneDevice[]> {+ try {+ const raw = await readFile(devicesPath(), "utf8");+ const parsed = JSON.parse(raw) as { devices?: PhoneDevice[] };+ return Array.isArray(parsed.devices) ? parsed.devices : [];+ } catch {+ return [];+ }+}++async function writeDevices(devices: PhoneDevice[]): Promise<void> {+ await mkdir(phoneRoot(), { recursive: true });+ await writeJsonAtomic(devicesPath(), { devices });+}++/** A device with its token hash left behind — what leaves this module. */+function publicDevice(device: PhoneDevice): PhoneDeviceInfo {+ return {+ id: device.id,+ name: device.name,+ pairedAt: device.pairedAt,+ lastSeenAt: device.lastSeenAt,+ };+}++export function listPhoneDevices(): Promise<PhoneDeviceInfo[]> {+ assertLocalRuntime();+ return withDeviceList((devices) =>+ devices.sort((a, b) => b.lastSeenAt - a.lastSeenAt).map(publicDevice)+ );+}++export function removePhoneDevice(id: string): Promise<void> {+ assertLocalRuntime();+ return withDeviceList(async (devices) => {+ await writeDevices(devices.filter((d) => d.id !== id));+ });+}++/** The device a token belongs to, with its last-seen stamp moved up. Null for a+ * token no paired device holds. */+export function phoneDeviceForToken(token: string): Promise<PhoneDeviceInfo | null> {+ assertLocalRuntime();+ if (!token) return Promise.resolve(null);+ const hash = hashToken(token);+ return withDeviceList(async (devices) => {+ const device = devices.find((d) => sameHash(d.tokenHash, hash));+ if (!device) return null;+ device.lastSeenAt = Date.now();+ await writeDevices(devices);+ return publicDevice(device);+ });+}++// MARK: Pairing++/** How long a pairing code is good for. Long enough to walk to the phone and+ * type it, short enough that a code left on screen is not a standing key. */+const PAIRING_TTL_MS = 5 * 60 * 1000;++/** Wrong answers a window survives. Six digits is 810,000 codes, which is a lot+ * to read off a screen and nothing at all to a machine in radio range working+ * through them, so the window closes long before guessing pays. */+const PAIRING_ATTEMPTS = 3;++/** The open pairing window, in memory only: the engine dies with the app, and a+ * code that outlived a restart would be a code nobody is watching. */+let pending: { code: string; expiresAt: number; attemptsLeft: number } | null = null;+/** Why the last window ended, for the card to explain itself. */+let lastClose: PhonePairingClose = null;++/** How a window ended: a phone took it, or someone guessed at it. */+export type PhonePairingClose = "paired" | "refused" | null;++/** Six digits in two groups — read aloud across a room, typed on a phone. */+const mintCode = () => `${randomInt(100, 1000)}-${randomInt(100, 1000)}`;++export interface PhonePairingWindow {+ code: string;+ expiresAt: number;+}++/** Open a pairing window, replacing any code still standing. */+export function openPhonePairing(): PhonePairingWindow {+ assertLocalRuntime();+ lastClose = null;+ pending = {+ code: mintCode(),+ expiresAt: Date.now() + PAIRING_TTL_MS,+ attemptsLeft: PAIRING_ATTEMPTS,+ };+ return { code: pending.code, expiresAt: pending.expiresAt };+}++/** The window still open, or null once it has lapsed. */+export function phonePairingWindow(): PhonePairingWindow | null {+ if (pending && pending.expiresAt <= Date.now()) pending = null;+ return pending ? { code: pending.code, expiresAt: pending.expiresAt } : null;+}++/** Why the window that is no longer open ended, for the card to say so. */+export function phonePairingClose(): PhonePairingClose {+ return phonePairingWindow() ? null : lastClose;+}++export function closePhonePairing(): void {+ pending = null;+ lastClose = null;+}++/** Answer a pairing code with a device name, and the phone is paired: it gets+ * back the token every later upload carries. A code is spent on first use, and+ * a few wrong answers close the window rather than leaving it standing to be+ * guessed at. Null when no window is open or the code is wrong. */+export function claimPhonePairing(+ code: string,+ deviceName: string+): Promise<{ device: PhoneDeviceInfo; token: string } | null> {+ assertLocalRuntime();+ const open = pending;+ if (!open || open.expiresAt <= Date.now()) {+ pending = null;+ return Promise.resolve(null);+ }+ if (code.trim() !== open.code) {+ open.attemptsLeft -= 1;+ if (open.attemptsLeft <= 0) {+ pending = null;+ lastClose = "refused";+ }+ return Promise.resolve(null);+ }+ pending = null;+ lastClose = "paired";++ const token = randomBytes(32).toString("hex");+ return withDeviceList(async (devices) => {+ const device: PhoneDevice = {+ id: crypto.randomUUID(),+ name: deviceName.trim().slice(0, 60) || "iPhone",+ tokenHash: hashToken(token),+ pairedAt: Date.now(),+ lastSeenAt: Date.now(),+ };+ devices.push(device);+ await writeDevices(devices);+ return { device: publicDevice(device), token };+ });+}++// MARK: Inbox++/** How long a clip nothing has taken stays in the inbox. The inbox is staging,+ * and a shoot nobody opened an editor for would otherwise sit here forever as a+ * second full copy of itself. */+const CLIP_TTL_MS = 7 * 24 * 60 * 60 * 1000;++/** How long a claim holds before the clip goes back in the inbox. An editor that+ * took a clip and died mid-import must not strand it, and an import still+ * running must not have it taken away — a gigabyte take through a browser is+ * minutes, not seconds. */+const CLAIM_TTL_MS = 30 * 60 * 1000;++export interface PhoneClipInput {+ takeId: string;+ fileName: string;+ capturedAt?: number;+ durationSeconds?: number;+ width?: number;+ height?: number;+}++/** Take a clip off a paired phone.+ *+ * The app stages each take in the system temp directory as it comes off the+ * radio, and this moves that file into the inbox under an id of this Mac's+ * choosing — a phone cannot name a path here. A move rather than a copy: a field+ * take is gigabytes, and pushing one through loopback to write it again is the+ * difference between instant and a minute. Across volumes the move falls back to+ * a copy, which is what rename cannot do there.+ *+ * The bytes land before the record, and only the record makes a clip visible, so+ * a transfer that breaks partway leaves nothing for an editor to find. The+ * start-up sweep collects what it left behind.+ */+export async function addPhoneClip(+ device: PhoneDeviceInfo,+ stagedPath: string,+ input: PhoneClipInput+): Promise<PhoneClip> {+ assertLocalRuntime();+ await mkdir(inboxRoot(), { recursive: true });++ // The same take arriving twice is the phone sending one whose acknowledgement+ // it never read. It already has a copy here.+ const already = await findPhoneClipByTake(device.id, input.takeId);+ if (already) {+ await rm(stagedClipPath(stagedPath), { force: true });+ return already;+ }++ const name = clipFileName(input.fileName);+ const id = crypto.randomUUID();+ const file = path.join(inboxRoot(), `${id}${path.extname(name)}`);++ const staged = stagedClipPath(stagedPath);+ try {+ await rename(staged, file);+ } catch {+ await copyFile(staged, file);+ await rm(staged, { force: true });+ }++ const clip: PhoneClip = {+ id,+ takeId: input.takeId,+ deviceId: device.id,+ deviceName: device.name,+ fileName: name,+ bytes: (await stat(file)).size,+ capturedAt: input.capturedAt ?? Date.now(),+ receivedAt: Date.now(),+ ...(input.durationSeconds ? { durationSeconds: input.durationSeconds } : {}),+ ...(input.width ? { width: input.width } : {}),+ ...(input.height ? { height: input.height } : {}),+ };+ await writeJsonAtomic(clipMetaPath(id), clip);+ return clip;+}++/** A take this device already delivered, whichever state its record is in. */+async function findPhoneClipByTake(deviceId: string, takeId: string): Promise<PhoneClip | null> {+ for (const clip of await allPhoneClips()) {+ if (clip.deviceId === deviceId && clip.takeId === takeId) return clip;+ }+ return null;+}++/** Every record in the inbox, claimed or not. */+async function allPhoneClips(): Promise<PhoneClip[]> {+ let names: string[];+ try {+ names = await readdir(inboxRoot());+ } catch {+ return [];+ }+ const clips = await Promise.all(+ names+ .filter((n) => n.endsWith(".json"))+ .map(async (n) => {+ try {+ return JSON.parse(await readFile(path.join(inboxRoot(), n), "utf8")) as PhoneClip;+ } catch {+ return null;+ }+ })+ );+ return clips.filter((c): c is PhoneClip => c !== null);+}++/** Everything waiting and unclaimed, oldest shot first — the order a shoot+ * happened in is the order it should land on a timeline. A record whose bytes+ * are gone is not offered; the sweep collects it. */+export async function listPhoneClips(): Promise<PhoneClip[]> {+ assertLocalRuntime();+ await releaseLapsedClaims();+ const unclaimed = (await allPhoneClips()).filter((c) => c.claimedAt === undefined);+ const present = await Promise.all(unclaimed.map((c) => exists(clipFilePath(c))));+ return unclaimed.filter((_, i) => present[i]).sort((a, b) => a.capturedAt - b.capturedAt);+}++/**+ * Take a clip, if it is still there to take.+ *+ * The rename is the whole mechanism: two editors racing both try to move the+ * same record, the filesystem performs exactly one of them, and the loser's+ * rename finds no source. Nothing is read and written back, so there is no+ * window between deciding and doing.+ */+export async function claimPhoneClip(id: string): Promise<PhoneClip | null> {+ assertLocalRuntime();+ await releaseLapsedClaims();+ const safe = safeId(id);+ let clip: PhoneClip;+ try {+ clip = JSON.parse(await readFile(clipMetaPath(safe), "utf8")) as PhoneClip;+ await rename(clipMetaPath(safe), claimedMetaPath(safe));+ } catch {+ return null;+ }+ const claimed: PhoneClip = { ...clip, claimedAt: Date.now() };+ await writeJsonAtomic(claimedMetaPath(safe), claimed);+ return claimed;+}++/** Give a claimed clip back — the import failed, and the next pass should find+ * it waiting. */+export async function releasePhoneClip(id: string): Promise<void> {+ assertLocalRuntime();+ const safe = safeId(id);+ let clip: PhoneClip;+ try {+ clip = JSON.parse(await readFile(claimedMetaPath(safe), "utf8")) as PhoneClip;+ } catch {+ return;+ }+ delete clip.claimedAt;+ await writeJsonAtomic(clipMetaPath(safe), clip);+ await rm(claimedMetaPath(safe), { force: true });+}++/** Claims whose editor never came back. */+async function releaseLapsedClaims(): Promise<void> {+ const cutoff = Date.now() - CLAIM_TTL_MS;+ for (const clip of await allPhoneClips()) {+ if (clip.claimedAt !== undefined && clip.claimedAt < cutoff) {+ await releasePhoneClip(clip.id);+ }+ }+}++/** A clip's record whether or not it has been claimed. */+export async function readPhoneClip(id: string): Promise<PhoneClip | null> {+ assertLocalRuntime();+ const safe = safeId(id);+ for (const file of [clipMetaPath(safe), claimedMetaPath(safe)]) {+ try {+ return JSON.parse(await readFile(file, "utf8")) as PhoneClip;+ } catch {+ // The other name, or neither.+ }+ }+ return null;+}++/** Where a clip's bytes sit, by its record. */+function clipFilePath(clip: PhoneClip): string {+ return path.join(inboxRoot(), `${clip.id}${path.extname(clip.fileName) || ".mov"}`);+}++/** The clip's file on disk, or null when the record or the bytes are gone. */+export async function phoneClipPath(id: string): Promise<string | null> {+ const clip = await readPhoneClip(id);+ if (!clip) return null;+ const file = clipFilePath(clip);+ return (await exists(file)) ? file : null;+}++/**+ * Move a claimed clip straight into a project's media.+ *+ * For a project that lives on this Mac both ends are local disk, so the bytes+ * never leave it: the editor asks for the move and the file is renamed into the+ * project. The alternative is the page pulling gigabytes off loopback and+ * pushing the same bytes back, which is two copies of a take through a tab that+ * has to hold the whole thing in memory.+ */+export async function movePhoneClipToProject(id: string, projectId: string): Promise<string> {+ assertLocalRuntime();+ const clip = await readPhoneClip(id);+ const file = clip ? clipFilePath(clip) : null;+ if (!clip || !file || !(await exists(file))) throw new Error("That clip is gone.");++ await mkdir(mediaDir(projectId), { recursive: true });+ const base = path.basename(clip.fileName).replace(/[^\w.\-() ]+/g, "_").slice(-80);+ const fileName = await uniqueName(base, (n) => mediaPath(projectId, n));+ const destination = mediaPath(projectId, fileName);+ try {+ await rename(file, destination);+ } catch {+ await copyFile(file, destination);+ await rm(file, { force: true });+ }+ await rm(claimedMetaPath(safeId(id)), { force: true });+ await rm(clipMetaPath(safeId(id)), { force: true });+ return fileName;+}++/** Drop a clip once an editor has it: the record and the bytes together. */+export async function removePhoneClip(id: string): Promise<void> {+ assertLocalRuntime();+ const file = await phoneClipPath(id);+ if (file) await rm(file, { force: true });+ await rm(clipMetaPath(safeId(id)), { force: true });+ await rm(claimedMetaPath(safeId(id)), { force: true });+}++/**+ * Clear what the inbox should not be holding, run once as the engine starts.+ *+ * Three kinds of leftovers: bytes with no record, from a transfer that broke+ * before the record was written; records whose bytes are gone; and clips older+ * than the inbox keeps, which is every take from a shoot nobody opened an editor+ * for.+ */+export async function sweepPhoneInbox(): Promise<void> {+ assertLocalRuntime();+ let names: string[];+ try {+ names = await readdir(inboxRoot());+ } catch {+ return;+ }++ const cutoff = Date.now() - CLIP_TTL_MS;+ const keeping = new Set<string>();+ for (const clip of await allPhoneClips()) {+ if (clip.receivedAt < cutoff || !(await exists(clipFilePath(clip)))) {+ await removePhoneClip(clip.id);+ continue;+ }+ keeping.add(path.basename(clipFilePath(clip)));+ }++ for (const name of names) {+ if (name.endsWith(".json") || keeping.has(name)) continue;+ await rm(path.join(inboxRoot(), name), { force: true });+ }++ await releaseLapsedClaims();+}++/** Clip ids are ours — uuids — so anything else is a path probe. */+function safeId(id: string): string {+ if (!/^[0-9a-f-]{36}$/i.test(id)) throw new Error("Bad clip id.");+ return id;+}++/** A staged clip is one the app just wrote to the system temp directory. The+ * engine answers on loopback with no auth, so it takes a path from that caller+ * only where the app puts them, and nowhere else on the disk. */+function stagedClipPath(raw: string): string {+ const resolved = path.resolve(raw);+ const staging = `${path.resolve(os.tmpdir())}${path.sep}`;+ if (!resolved.startsWith(staging)) throw new Error("A staged clip lives in the temp directory.");+ return resolved;+}++/** The name a clip lands under, reduced to a leaf this Mac is willing to write:+ * the phone names its own takes, and a name is not a path. */+function clipFileName(raw: string): string {+ const leaf = path.basename(raw ?? "").replace(/[/\\]/g, "").trim();+ const ext = path.extname(leaf) || ".mov";+ const stem = leaf.slice(0, leaf.length - path.extname(leaf).length) || "clip";+ return `${stem.slice(0, 80)}${ext}`;+}