fix(cli): never write project records through symlinks under .hyperframes (#7950)

* fix(cli): never write project records through symlinks under .hyperframes

The committed team descriptor (.hyperframes/project.json) and the HeyGen job
log (.hyperframes/heygen-jobs.jsonl) were written with path-based mkdir/write/
append calls that follow links, so a cloned project could point either file,
or .hyperframes itself, at a file outside the project and have publish or a
paid HeyGen job overwrite or append to it.

- projectRecords: add appendRecord (O_NOFOLLOW open, same plain file checked
  by fstat/lstat, real folders from .hyperframes) and recordKind.
- writeTeamProject goes through writeRecord (exclusive temp + rename), so a
  link at project.json is replaced, never written through, and a linked
  .hyperframes is refused.
- readTeamProject refuses a linked or non-plain descriptor (or a linked
  .hyperframes) instead of reading it as absent, which stops publish before it
  would write one.
- The job log and project voice picks go through appendRecord and fail with
  a Fix when refused.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): route every remaining .hyperframes write through link-refusing helpers

Writers that still made or wrote into a project's .hyperframes with
path-based mkdir/write calls now refuse a linked or non-folder .hyperframes
and never write through a link:

- project lock: folder via recordFolder (the exclusive lock create stays)
- lambda stack state: writeRecord
- received-files record: recordFolder + writeRecord, so a link to another
  project file is replaced instead of overwritten
- check reports: folder via recordFolder (the wx create stays)
- check and snapshot frame folders: new projectFolder, which holds a folder
  inside .hyperframes to recordFolder and makes one elsewhere as asked
- template pull staging: recordFolder
- share render record: writeRecord
- studio server state folder: recordFolder
- share storage: the atomic JSON temp file is opened with wx

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(cli): drop doc comments the comment ratchet counts

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): refuse to append to a project record with more than one hard link

A hard link at .hyperframes/heygen-jobs.jsonl names an outside file as a
plain file, so the O_NOFOLLOW open and the same-file check let the job log
append to it. The append now refuses a file whose link count is above one.
Whole-file record writes go through a temp file renamed into place, which
replaces the name rather than writing to a linked inode.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
WaterrrForever
2026-11-16 15:21:31 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 725d13bb1d
commit 061ff5bbb0
18 changed files with 335 additions and 63 deletions
+10 -2
View File
@@ -2,7 +2,7 @@ import { terminalText } from "@hyperframes/core";
import { captureArtifactRevision } from "../utils/artifactCapture.js";
import { pngDimensions } from "../utils/pngDimensions.js";
import { randomUUID } from "node:crypto";
import { mkdirSync, writeFileSync } from "node:fs";
import { writeFileSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import {
recordArtifacts,
@@ -54,6 +54,7 @@ import {
readCachedPass,
storePass,
} from "../utils/checkCache.js";
import { recordFolder } from "../utils/projectRecords.js";
import { VERSION } from "../version.js";
export const examples: Example[] = [
@@ -113,6 +114,13 @@ export function checkReportFile(projectDir: string, id: string): string {
return join(projectDir, ".hyperframes", "artifacts", "checks", `${id}.json`);
}
function makeReportFolder(path: string, projectDir: string): void {
if (!recordFolder(projectDir, "artifacts/checks"))
throw new Error(
`${dirname(path)} is reached through a link or a file; remove it and run again`,
);
}
async function saveCheckReport(
project: ProjectDir,
options: CheckOptions,
@@ -121,7 +129,7 @@ async function saveCheckReport(
id: string,
): Promise<SavedCheck> {
const path = checkReportFile(project.dir, id);
mkdirSync(dirname(path), { recursive: true });
makeReportFolder(path, project.dir);
writeFileSync(path, JSON.stringify(report, null, 2) + "\n", { flag: "wx" });
const reportScope =
"scope" in report && typeof report.scope === "object" && report.scope !== null
+6 -5
View File
@@ -11,9 +11,9 @@ import { failCommand } from "../../utils/commandResult.js";
* can symlink the directory.
*/
import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
import { dirname, join } from "node:path";
import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
import { join } from "node:path";
import { writeRecord } from "../../utils/projectRecords.js";
export interface StackOutputs {
/** Project-name prefix passed to `deploy`. Used as CloudFormation stack-name suffix. */
@@ -52,8 +52,9 @@ export function stateFilePath(
export function writeStackOutputs(outputs: StackOutputs, cwd: string = process.cwd()): string {
const path = stateFilePath(outputs.stackName, cwd);
mkdirSync(dirname(path), { recursive: true });
replaceFileAtomically(path, JSON.stringify(outputs, null, 2) + "\n");
const name = `${STATE_FILE_PREFIX}${outputs.stackName}.json`;
if (!writeRecord(cwd, name, JSON.stringify(outputs, null, 2) + "\n"))
throw new Error(`Could not write ${path}: it, or .hyperframes, is a link or not a plain file`);
return path;
}
+5 -1
View File
@@ -11,6 +11,7 @@ import {
sdrCanvasColourFilters,
} from "@hyperframes/engine";
import { mediaInputFormatArgs } from "@hyperframes/parsers/ff-binaries";
import { projectFolder } from "../utils/projectRecords.js";
import { screenshotOnceMore } from "../utils/screenshotOnceMore.js";
import { parseTimeoutMs } from "../utils/timeoutArg.js";
import type { Page } from "puppeteer-core";
@@ -1172,7 +1173,10 @@ export async function captureSnapshots(
: null;
const snapshotDir = opts.outputDir ?? artifactDirectory(projectDir, "snapshots");
mkdirSync(snapshotDir, { recursive: true });
if (!projectFolder(projectDir, snapshotDir))
throw new Error(
`${snapshotDir} is reached through a link or a file; remove it and run again`,
);
if (!opts.keep) replaced.push(...clearEarlierStills(snapshotDir));
if (replaced.length > 0) {
log(` ${c.warn("⚠")} ${clearedNote(replaced.length, snapshotDir)}`);
+6 -2
View File
@@ -17,6 +17,7 @@ import {
writeFileSync,
} from "node:fs";
import { makeOutputFolder } from "../utils/outputFolder.js";
import { recordFolder } from "../utils/projectRecords.js";
import { processIsAlive } from "../utils/processTree.js";
import { basename, dirname, join, resolve } from "node:path";
import { resolveCloudAuthHeaders } from "../cloud/auth.js";
@@ -209,7 +210,6 @@ async function unpack(
pack: TemplatePack,
): Promise<string | null> {
makeOutputFolder(dirname(dest));
makeOutputFolder(stage);
removeAbandonedParts(stage, dest);
const work = createStagingDir(stage, `${partPrefix(dest)}${process.pid}-`);
const stopWatching = removeOnStop(work);
@@ -269,7 +269,11 @@ export async function pullTemplate(slug: string, dir: string): Promise<string> {
);
const dest = resolve(dir, "templates", slug);
if (alreadyPulled(dest, pack)) return dest;
const stage = resolve(dir, ".hyperframes", "template-pulls");
const stage = recordFolder(resolve(dir), "template-pulls");
if (!stage)
throw new PullRefused(
`${resolve(dir, ".hyperframes")} is a link or not a folder; remove it and pull again.`,
);
const aside = await unpack(await download(await bundleUrl(pack), pack), dest, stage, pack);
if (aside)
console.log(
+65 -2
View File
@@ -1,4 +1,12 @@
import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
import {
linkSync,
lstatSync,
mkdirSync,
mkdtempSync,
readFileSync,
symlinkSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -14,7 +22,7 @@ vi.mock("../cloud/auth.js", () => ({
resolveCloudBaseUrl: () => "https://api.test",
}));
const { idempotencyKey, ownVoices, runJob } = await import("./v3.js");
const { idempotencyKey, keepVoice, ownVoices, runJob } = await import("./v3.js");
/** A job route through the generated client: the create and the status GET it polls. */
const X: JobRoute = {
@@ -583,3 +591,58 @@ describe("ownVoices", () => {
await expect(ownVoices(5)).rejects.toMatchObject({ fix: "npx hyperframes auth login" });
});
});
describe("a project's job log in place of which a link was planted", () => {
const VICTIM = "victim bytes\n";
const planted = (linkJobLog: boolean) => {
const projectDir = mkdtempSync(join(tmpdir(), "hf-v3-planted-"));
const outside = mkdtempSync(join(tmpdir(), "hf-v3-outside-"));
const victim = join(outside, "heygen-jobs.jsonl");
writeFileSync(victim, VICTIM);
if (linkJobLog) {
mkdirSync(join(projectDir, ".hyperframes"));
symlinkSync(victim, join(projectDir, ".hyperframes/heygen-jobs.jsonl"));
} else {
symlinkSync(outside, join(projectDir, ".hyperframes"));
}
return { projectDir, victim };
};
for (const [what, linkJobLog] of [
["the job log", true],
["the .hyperframes folder", false],
] as const) {
it(`never appends a job or a voice pick through a link in place of ${what}`, async () => {
const { projectDir, victim } = planted(linkJobLog);
vi.stubGlobal("fetch", async () => reply(200, { data: { id: "j1", status: "completed" } }));
await expect(runJob(X, {}, "k1", { log: { projectDir, what: "a line" } })).rejects.toThrow(
/never written through/,
);
expect(() => keepVoice(projectDir, "en", { voice_id: "v1", name: "Ann" })).toThrow(
/never written through/,
);
expect(readFileSync(victim, "utf8")).toBe(VICTIM);
expect(
lstatSync(
join(projectDir, linkJobLog ? ".hyperframes/heygen-jobs.jsonl" : ".hyperframes"),
).isSymbolicLink(),
).toBe(true);
});
}
it("never appends to a job log hard-linked to a file outside the project", async () => {
const projectDir = mkdtempSync(join(tmpdir(), "hf-v3-planted-"));
mkdirSync(join(projectDir, ".hyperframes"));
const victim = join(mkdtempSync(join(tmpdir(), "hf-v3-outside-")), "victim");
writeFileSync(victim, VICTIM);
linkSync(victim, join(projectDir, ".hyperframes/heygen-jobs.jsonl"));
vi.stubGlobal("fetch", async () => reply(200, { data: { id: "j1", status: "completed" } }));
await expect(runJob(X, {}, "k1", { log: { projectDir, what: "a line" } })).rejects.toThrow(
/never written through/,
);
expect(() => keepVoice(projectDir, "en", { voice_id: "v1", name: "Ann" })).toThrow(
/never written through/,
);
expect(readFileSync(victim, "utf8")).toBe(VICTIM);
});
});
+19 -7
View File
@@ -10,6 +10,7 @@ import { resolveCredential } from "../auth/resolver.js";
import { refreshIfNeeded, resolveCloudAuthHeaders, resolveCloudBaseUrl } from "../cloud/auth.js";
import { HyperframesApiError, HyperframesCloudClient } from "../cloud/_gen/client.js";
import { Fix } from "../measure/media.js";
import { appendRecord } from "../utils/projectRecords.js";
import { creditLimit, creditsSpent } from "../media-use/lib/credit-limit.mjs";
import { cliCheckoutLink, pageUrl } from "./plan.js";
@@ -237,14 +238,24 @@ export interface JobLog {
what: string;
}
const JOB_LOG = "heygen-jobs.jsonl";
function appendJobLog(projectDir: string, line: Record<string, unknown>): void {
if (
!appendRecord(
projectDir,
JOB_LOG,
`${JSON.stringify({ at: new Date().toISOString(), ...line })}\n`,
)
)
throw new Fix(
`${join(projectDir, ".hyperframes", JOB_LOG)} could not be added to; a link or anything but a plain file there, or in place of .hyperframes, is never written through`,
"remove that link or file and run the same command again",
);
}
function log(entry: JobLog, record: Record<string, unknown>) {
if (!entry.projectDir) return;
const dir = join(entry.projectDir, ".hyperframes");
mkdirSync(dir, { recursive: true });
appendFileSync(
join(dir, "heygen-jobs.jsonl"),
`${JSON.stringify({ at: new Date().toISOString(), what: entry.what, ...record })}\n`,
);
if (entry.projectDir) appendJobLog(entry.projectDir, { what: entry.what, ...record });
}
export interface RunOptions {
@@ -420,6 +431,7 @@ export function keptVoice(projectDir: string | null, request: string): Voice | u
}
export function keepVoice(projectDir: string | null, request: string, voice: Voice): void {
if (projectDir) return appendJobLog(projectDir, { voice_pick: request, voice });
const file = picksFile(projectDir);
mkdirSync(dirname(file), { recursive: true });
appendFileSync(
+3 -6
View File
@@ -10,7 +10,7 @@ import type { HttpBindings } from "@hono/node-server";
import { Hono, type Context } from "hono";
import { streamSSE } from "hono/streaming";
import { realpath } from "@hyperframes/core";
import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync, unlinkSync } from "node:fs";
import { existsSync, readFileSync, statSync, writeFileSync, unlinkSync } from "node:fs";
import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
import { createHash } from "node:crypto";
import { fileURLToPath } from "node:url";
@@ -45,6 +45,7 @@ import {
} from "@hyperframes/studio-server/request-identity";
import { mountShareRoutes } from "./shareRoutes.js";
import { isDevMode } from "../utils/env.js";
import { recordFolder } from "../utils/projectRecords.js";
import { outsideAssetsAllowed } from "../utils/receivedRender.js";
import { insideHostApp } from "../utils/desktopApp.js";
import { runRenderSetupWorker } from "../utils/cancellableProcess.js";
@@ -467,11 +468,7 @@ function rewriteWrittenToHostViewport(projectDir: string, written: string[]): vo
}
function createStateFolderBeforeWatching(projectDir: string): void {
try {
mkdirSync(join(projectDir, ".hyperframes"), { recursive: true });
} catch {
return;
}
recordFolder(projectDir, "");
}
export function createStudioServer(options: StudioServerOptions): StudioServer {
+6 -9
View File
@@ -1,8 +1,9 @@
import { randomUUID } from "node:crypto";
import { existsSync, readFileSync, realpathSync } from "node:fs";
import { mkdir, writeFile, rename, rm } from "node:fs/promises";
import { mkdir, rm } from "node:fs/promises";
import { join } from "node:path";
import { projectFingerprint, shareSourceFingerprint } from "@hyperframes/share";
import { writeRecord } from "../utils/projectRecords.js";
export const shareContentFingerprint = shareSourceFingerprint;
@@ -76,8 +77,6 @@ export async function prepareShareRender(dir: string): Promise<void> {
import("../commands/render/execute.js"),
import("../commands/render.js"),
]);
const target = join(stateFolder, "share-render.json");
const temporary = `${target}.${id}.tmp`;
try {
const plan = createRenderPlan({ dir, output, format: "mp4", quiet: true, strict: true });
await executeRenderPlan(plan, {
@@ -103,13 +102,11 @@ export async function prepareShareRender(dir: string): Promise<void> {
throw new Error(
"The project changed while rendering. Share again to capture the current project.",
);
await writeFile(
temporary,
JSON.stringify({ id, path: output, fingerprint: before, contentFingerprint: content }),
);
await rename(temporary, target);
const record = { id, path: output, fingerprint: before, contentFingerprint: content };
if (!writeRecord(dir, "share-render.json", JSON.stringify(record)))
throw new Error("Sharing state must stay inside this project, without symlinks.");
} catch (error) {
await Promise.allSettled([rm(output, { force: true }), rm(temporary, { force: true })]);
await rm(output, { force: true });
throw error;
}
}
+1 -2
View File
@@ -5,7 +5,7 @@ import { logCheckProgress } from "./checkProgress.js";
import { BrowserCleanupError, closeManagedBrowser, onStopSignal } from "../browser/launch.js";
import { collectMotionBlurDrafts, dropMotionBlurConsoleEcho } from "./checkMotionBlur.js";
import { checkSnapshotDirectory } from "./checkSnapshotDirectory.js";
import { existsSync, mkdirSync, writeFileSync } from "node:fs";
import { existsSync, writeFileSync } from "node:fs";
import os from "node:os";
import { join, resolve } from "node:path";
import type { Browser, Page } from "puppeteer-core";
@@ -789,7 +789,6 @@ async function withFindingCapturePage<T>(
chromeBrowser = session.browser;
await waitForPreferredSeekTarget(session.page);
const snapshotDir = checkSnapshotDirectory(project.dir);
mkdirSync(snapshotDir, { recursive: true });
return await capture(session.page, snapshotDir, server);
} catch (error) {
failure = { kind: "failed", error };
+1 -2
View File
@@ -24,7 +24,7 @@ import {
findingFrameRequests,
} from "./checkFindingFrames.js";
export { selectFindingFrames } from "./checkFindingFrames.js";
import { mkdirSync, writeFileSync } from "node:fs";
import { writeFileSync } from "node:fs";
import { readFile } from "node:fs/promises";
import type { PrelaunchedBrowser } from "../capture/captureCompositionFrame.js";
import { join, relative } from "node:path";
@@ -2415,7 +2415,6 @@ async function writeSnapshot(
pngBase64: string,
): Promise<string> {
const snapshotDir = checkSnapshotDirectory(projectDir);
mkdirSync(snapshotDir, { recursive: true });
const filename = `frame-${String(index).padStart(2, "0")}-at-${time.toFixed(1)}s.png`;
const path = join(snapshotDir, filename);
writeFileSync(path, Buffer.from(pngBase64, "base64"));
@@ -1,5 +1,6 @@
import { resolve } from "node:path";
import { artifactDirectory, finishSnapshotRun } from "@hyperframes/studio-server/history";
import { projectFolder } from "./projectRecords.js";
const runDirectories = new Map<string, string>();
const activeChecks = new Map<string, number>();
@@ -16,6 +17,8 @@ export function checkSnapshotDirectory(projectDir: string): string {
directory = artifactDirectory(project, "snapshots");
runDirectories.set(project, directory);
}
if (!projectFolder(project, directory))
throw new Error(`${directory} is reached through a link or a file; remove it and run again`);
return directory;
}
@@ -13,10 +13,15 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";
import { writeStackOutputs } from "../commands/lambda/state.js";
import { pullTemplate } from "../commands/templates.js";
import { outDir, writeImage } from "../measure/media.js";
import { writeParakeetTranscript } from "../whisper/parakeet.js";
import { checkSnapshotDirectory } from "./checkSnapshotDirectory.js";
import { writeTurn, type Turn } from "./historyOwner.js";
import { recordReceivedFiles } from "./privateProjectFile.js";
import { recordProjectRegistryItems, seedProjectAuthoringSkill } from "./projectConfig.js";
import { withProjectLock } from "./projectLock.js";
import { projectFolder } from "./projectRecords.js";
const roots: string[] = [];
afterEach(() => {
@@ -146,3 +151,59 @@ describe("fixed-name outputs", () => {
expect(readFileSync(clip).subarray(1, 4).toString()).toBe("PNG");
});
});
describe("every writer under a linked .hyperframes folder", () => {
const writers: [string, (project: string) => unknown][] = [
[
"the project lock",
(project) =>
withProjectLock(project, "test", async () => {}, { projectLock: { waitMs: 50 } }),
],
[
"the lambda stack file",
(project) => writeStackOutputs({ stackName: "demo", region: "us-east-1" } as never, project),
],
["the received-files record", (project) => recordReceivedFiles(project, ["a.png"])],
["a check's snapshot folder", (project) => checkSnapshotDirectory(project)],
[
"a snapshot --output inside .hyperframes",
(project) => {
if (!projectFolder(project, join(records(project), "shots"))) throw new Error("refused");
},
],
[
"a template pull's staging folder",
(project) => {
vi.stubGlobal("fetch", async () => {
throw new Error("offline");
});
return pullTemplate("finance-explainer", project).finally(() => vi.unstubAllGlobals());
},
],
];
for (const [what, write] of writers) {
it(`refuses ${what}`, async () => {
const { project, outside } = setup();
linkRecordsFolderOut(project, outside);
await expect(Promise.resolve().then(() => write(project))).rejects.toThrow(
/link|refused|symlinks/,
);
expect(readdirSync(outside)).toEqual(["victim.txt"]);
});
}
it("replaces a linked received-files record instead of overwriting the project file it points at", () => {
const { project } = setup();
const data = join(project, "data.json");
writeFileSync(data, '{"files":[]}');
mkdirSync(records(project));
const record = join(records(project), "received-files.json");
symlinkSync("../data.json", record);
recordReceivedFiles(project, ["a.png"]);
expect(readFileSync(data, "utf8")).toBe('{"files":[]}');
expect(isLink(record)).toBe(false);
});
});
+16 -6
View File
@@ -8,16 +8,16 @@ import {
rmSync,
statSync,
} from "node:fs";
import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import {
isEnvOrGitPath,
isPrivateOutsideFile,
linksOutside,
} from "@hyperframes/studio-server/outside-file";
import { isPrivateProjectFile, realFilePath } from "@hyperframes/studio-server/safe-path";
import { mkdirWithinProject } from "@hyperframes/core";
import { isCredentialOrToolStatePath } from "@hyperframes/core/safe-path";
import { publishRegistryFile, registryRoot, registryTargetPath } from "../registry/publication.js";
import { registryRoot } from "../registry/publication.js";
import { recordFolder, writeRecord } from "./projectRecords.js";
import { walkBudget } from "./walkBudget.js";
export { isEnvOrGitPath, isPrivateOutsideFile, linksOutside };
@@ -89,15 +89,25 @@ function takeRecordLock(lock: string): void {
function changeReceivedRecord(projectDir: string, change: (files: Set<string>) => boolean): void {
const root = registryRoot(projectDir);
const lock = registryTargetPath(root, RECEIVED_RECORD_LOCK);
mkdirWithinProject(root, dirname(lock));
if (!recordFolder(root, ""))
throw new Error(
`${join(root, ".hyperframes")} is a link or not a folder; remove it and try again.`,
);
const lock = join(root, RECEIVED_RECORD_LOCK);
takeRecordLock(lock);
try {
const record = readRecord(root, true);
if (record && !Array.isArray(record.listed)) return;
const files = new Set(((record?.listed ?? []) as unknown[]).map(String));
if (!change(files)) return;
publishRegistryFile(root, RECEIVED_RECORD, `${JSON.stringify({ files: [...files].sort() })}\n`);
if (
!writeRecord(
root,
basename(RECEIVED_RECORD),
`${JSON.stringify({ files: [...files].sort() })}\n`,
)
)
throw new Error(`Could not write ${join(root, RECEIVED_RECORD)}.`);
} finally {
rmSync(lock, { force: true });
}
+37 -1
View File
@@ -1,4 +1,12 @@
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import {
lstatSync,
mkdirSync,
mkdtempSync,
readFileSync,
rmSync,
symlinkSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join, resolve } from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -113,4 +121,32 @@ describe("projectLink", () => {
writeTeamProject(dir, { projectId: "hfp_team", spaceId: "space-42" });
expect(readTeamProject(dir)).toEqual({ projectId: "hfp_team", spaceId: "space-42" });
});
it("refuses a team descriptor that is a link, and replaces the link rather than writing through it", () => {
const dir = makeProjectDir();
const victim = join(makeProjectDir(), ".bashrc");
writeFileSync(victim, "victim bytes\n");
mkdirSync(join(dir, ".hyperframes"));
const descriptor = join(dir, ".hyperframes", "project.json");
symlinkSync(victim, descriptor);
expect(() => readTeamProject(dir)).toThrow(/is a link or not a plain file/);
writeTeamProject(dir, { projectId: "hfp_new" });
expect(readFileSync(victim, "utf-8")).toBe("victim bytes\n");
expect(lstatSync(descriptor).isFile()).toBe(true);
expect(readTeamProject(dir)).toEqual({ projectId: "hfp_new" });
});
it("refuses to read or write the team descriptor through a linked .hyperframes folder", () => {
const dir = makeProjectDir();
const outside = makeProjectDir();
const victim = join(outside, "project.json");
writeFileSync(victim, "victim bytes\n");
symlinkSync(outside, join(dir, ".hyperframes"));
expect(() => readTeamProject(dir)).toThrow(/is a link or not a plain file/);
expect(() => writeTeamProject(dir, { projectId: "hfp_new" })).toThrow(/Could not write/);
expect(readFileSync(victim, "utf-8")).toBe("victim bytes\n");
});
});
+26 -7
View File
@@ -1,7 +1,9 @@
import { randomUUID } from "node:crypto";
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { join, resolve } from "node:path";
import { CliRuntimeError } from "./commandResult.js";
import { hyperframesConfigDir, seededConfigFile } from "./configDir.js";
import { readRecord, recordKind, writeRecord } from "./projectRecords.js";
interface ProjectLink {
projectId: string;
@@ -13,11 +15,10 @@ type ProjectLinks = Record<string, ProjectLink>;
const configDir = () => hyperframesConfigDir();
const projectsFile = () => seededConfigFile("projects.json");
/** Read + parse a JSON object file, or null if it's missing, unreadable, or not an object. */
function readJsonRecord(path: string): Record<string, unknown> | null {
/** Parse a JSON object, or null if it's not valid JSON or not an object. */
function jsonObject(text: string): Record<string, unknown> | null {
try {
if (!existsSync(path)) return null;
const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
const parsed: unknown = JSON.parse(text);
if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
return parsed as Record<string, unknown>;
} catch {
@@ -25,6 +26,14 @@ function readJsonRecord(path: string): Record<string, unknown> | null {
}
}
function readJsonRecord(path: string): Record<string, unknown> | null {
try {
return existsSync(path) ? jsonObject(readFileSync(path, "utf-8")) : null;
} catch {
return null;
}
}
function isProjectLink(value: unknown): value is ProjectLink {
if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
const link = value as Record<string, unknown>;
@@ -92,8 +101,18 @@ function teamProjectPath(projectDir: string): string {
return join(resolve(projectDir), TEAM_PROJECT_DIR, TEAM_PROJECT_FILE);
}
const MAX_TEAM_PROJECT_BYTES = 64 * 1024;
export function readTeamProject(projectDir: string): TeamProject | null {
const record = readJsonRecord(teamProjectPath(projectDir));
const kind = recordKind(resolve(projectDir), TEAM_PROJECT_FILE);
if (kind === "absent") return null;
if (kind === "other")
throw new CliRuntimeError(
`${teamProjectPath(projectDir)} is a link or not a plain file, or ${TEAM_PROJECT_DIR} is not a real folder. Remove it and publish again.`,
);
const record = jsonObject(
readRecord(resolve(projectDir), TEAM_PROJECT_FILE, MAX_TEAM_PROJECT_BYTES),
);
if (!record || typeof record.projectId !== "string" || record.projectId.length === 0) return null;
const spaceId =
typeof record.spaceId === "string" && record.spaceId.length > 0 ? record.spaceId : undefined;
@@ -107,7 +126,7 @@ export function writeTeamProject(projectDir: string, team: TeamProject): string
projectId: team.projectId,
...(team.spaceId ? { spaceId: team.spaceId } : {}),
};
mkdirSync(join(resolve(projectDir), TEAM_PROJECT_DIR), { recursive: true });
writeFileSync(file, `${JSON.stringify(body, null, 2)}\n`);
if (!writeRecord(resolve(projectDir), TEAM_PROJECT_FILE, `${JSON.stringify(body, null, 2)}\n`))
throw new Error(`Could not write ${file}`);
return file;
}
+7 -3
View File
@@ -1,7 +1,8 @@
import { mkdirSync, readFileSync, unlinkSync } from "node:fs";
import { readFileSync, unlinkSync } from "node:fs";
import { createFileAtomically } from "@hyperframes/core/atomic-file";
import { dirname, join } from "node:path";
import { join } from "node:path";
import { setTimeout as sleep } from "node:timers/promises";
import { recordFolder } from "./projectRecords.js";
import { readToolContext, type ToolContext } from "./toolContext.js";
export class ProjectLockTimeout extends Error {}
@@ -90,7 +91,10 @@ export async function withProjectLock<T>(
): Promise<T> {
if (!context.projectLock) return run();
const path = projectLockPath(projectDir);
mkdirSync(dirname(path), { recursive: true });
if (!recordFolder(projectDir, ""))
throw new Error(
`${join(projectDir, ".hyperframes")} is a link or not a folder; remove it and run again`,
);
const holder: Holder = { pid: process.pid, command, startedAt: Date.now() };
const deadline = holder.startedAt + context.projectLock.waitMs;
let nextNoticeAt = holder.startedAt + FIRST_NOTICE_MS;
+62 -7
View File
@@ -7,8 +7,9 @@ import {
openSync,
readSync,
unlinkSync,
writeSync,
} from "node:fs";
import { join } from "node:path";
import { isAbsolute, join, relative, resolve, sep } from "node:path";
import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
// The records the CLI and the desktop app keep in a project's .hyperframes/. A project can be a clone of someone
@@ -37,9 +38,17 @@ function recordsDir(projectDir: string, name: string, create = false): string |
const recordFile = (name: string) => name.split("/").at(-1) ?? name;
function plainFileAt(fd: number, path: string) {
const stats = fstatSync(fd);
const named = lstatSync(path);
return stats.isFile() && named.isFile() && named.ino === stats.ino && named.dev === stats.dev
? stats
: null;
}
/** The last `maxBytes` of a plain file, and whether that is all of it; null for a link, a device, or a missing file.
* The file is opened first and read only when `lstat` then finds the same plain file at the path, so this holds
* where O_NOFOLLOW doesn't exist (Windows), and nothing path-based follows the check. */
* The file is opened first and read only when `lstat` then finds the same plain file at the path, so nothing
* path-based follows the check. */
function readPlainTail(path: string, maxBytes: number): { text: string; whole: boolean } | null {
let fd: number;
try {
@@ -48,10 +57,8 @@ function readPlainTail(path: string, maxBytes: number): { text: string; whole: b
return null;
}
try {
const stats = fstatSync(fd);
const named = lstatSync(path);
if (!stats.isFile() || !named.isFile() || named.ino !== stats.ino || named.dev !== stats.dev)
return null;
const stats = plainFileAt(fd, path);
if (!stats) return null;
const length = Math.min(stats.size, maxBytes);
const buffer = Buffer.alloc(length);
readSync(fd, buffer, 0, length, stats.size - length);
@@ -108,10 +115,58 @@ export function writeRecord(projectDir: string, name: string, data: string): boo
return dir !== null && replaceFile(join(dir, recordFile(name)), data, 0o600);
}
export function appendRecord(projectDir: string, name: string, data: string): boolean {
const dir = recordsDir(projectDir, name, true);
if (!dir) return false;
const path = join(dir, recordFile(name));
if (recordKind(projectDir, name) === "other") return false;
let fd: number;
try {
const flags = constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT;
fd = openSync(path, flags | NO_FOLLOW | NON_BLOCK, 0o600);
} catch {
return false;
}
try {
if ((plainFileAt(fd, path)?.nlink ?? 2) > 1) return false;
writeSync(fd, data);
return true;
} catch {
return false;
} finally {
closeSync(fd);
}
}
export function recordKind(projectDir: string, name: string): "absent" | "file" | "other" {
const parts = [".hyperframes", ...name.split("/")];
let path = projectDir;
for (const [index, part] of parts.entries()) {
path = join(path, part);
try {
const stats = lstatSync(path, { throwIfNoEntry: false });
if (!stats) return "absent";
if (!(index === parts.length - 1 ? stats.isFile() : stats.isDirectory())) return "other";
} catch {
return "other";
}
}
return "file";
}
export function recordFolder(projectDir: string, folder: string): string | null {
return recordsDir(projectDir, `${folder.replaceAll("\\", "/")}/`, true);
}
export function projectFolder(projectDir: string, folder: string): string | null {
const inside = relative(join(resolve(projectDir), ".hyperframes"), resolve(folder));
if (inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside)) {
mkdirSync(folder, { recursive: true });
return folder;
}
return recordFolder(projectDir, inside);
}
/** Deletes a record that is a plain file; false when there is none to delete. */
export function removeRecord(projectDir: string, name: string): boolean {
const dir = recordsDir(projectDir, name);
+1 -1
View File
@@ -59,7 +59,7 @@ export function writeJsonAtomic(path, data) {
const save = (queued.get(path) ?? Promise.resolve()).then(async () => {
const temp = `${path}.${randomUUID()}.tmp`;
try {
await writeFile(temp, text, { mode: 0o600 });
await writeFile(temp, text, { mode: 0o600, flag: "wx" });
await rename(temp, path);
} finally {
await rm(temp, { force: true });