Skip to content

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.ts
index 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 compiled
diff --git a/site/src/cut/server/http/next.ts b/site/src/cut/server/http/next.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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}`;
+}