fix(lambda): uploads go only to a bucket the state machine's account owns (#7983)

The lambda commands read the bucket and state machine from
.hyperframes/lambda-stack-<name>.json, which arrives with any project
someone sends. A file naming another account's bucket made render,
render-batch and sites create upload the project there.

- renderToLambda pins ExpectedBucketOwner to the state machine ARN's
  account on every S3 request; deploySite takes expectedBucketOwner,
  which sites create and render-batch pass.
- The state file is read only as a plain file in a real .hyperframes
  folder, and its bucket, ARN, region and other fields are checked.
This commit is contained in:
Michael Wang
2026-11-16 23:17:54 +00:00
committed by GitHub
parent c68c78445d
commit 1463158a4b
18 changed files with 401 additions and 53 deletions
+1 -1
View File
@@ -74,7 +74,7 @@ CLI versions reserved 8 by default, so they stay at 8 until you pass
`--concurrency=N`. Pass `--concurrency=none` to remove the reservation so each
render sizes itself to the account.
`deploy` records the stack's bucket and state machine in `.hyperframes/lambda-stack-<stack-name>.json` under the current directory. Every other `lambda` command reads that file, so run them from the same directory with the same `--stack-name`, or they stop with "no stack state". Redeploying to upgrade rewrites the same file.
`deploy` records the stack's bucket and state machine in `.hyperframes/lambda-stack-<stack-name>.json` under the current directory. Every other `lambda` command reads that file, so run them from the same directory with the same `--stack-name`, or they stop with "no stack state". Redeploying to upgrade rewrites the same file. The commands check the file's fields, and they refuse a file that is a symlink. Uploads go only to a bucket owned by the AWS account of the file's state machine, so a state file in a project someone sent you cannot send the project to their bucket.
After `deploy`, render anything with:
@@ -98,7 +98,7 @@ rendering with the actual composition before choosing a path.
### State files are local by default
`hyperframes lambda deploy` writes `<cwd>/.hyperframes/lambda-stack-<name>.json` so subsequent verbs don't re-derive the bucket / state-machine ARN. Two worktrees produce two distinct state files. If you need a shared default location across CI workers, symlink the directory or pass `--stack-name` explicitly on every call.
`hyperframes lambda deploy` writes `<cwd>/.hyperframes/lambda-stack-<name>.json` so subsequent verbs don't re-derive the bucket / state-machine ARN. Two worktrees produce two distinct state files. CI workers that share a stack run `deploy` once and copy the file into each checkout, or pass `--stack-name` explicitly on every call. The CLI refuses a state file, or a `.hyperframes` folder, that is a symlink.
### IAM policy is print-then-narrow
@@ -16,25 +16,52 @@ export interface FakeS3Op {
kind: "head" | "put";
bucket: string;
key: string;
/** The `ExpectedBucketOwner` the request carried. */
owner?: string;
}
interface Request {
input: { Bucket: string; Key: string; ExpectedBucketOwner?: string };
}
type Handler = (args: Request) => Promise<{ output: unknown }>;
type Middleware = (next: Handler) => Handler;
export class FakeS3 {
ops: FakeS3Op[] = [];
existing = new Set<string>();
bodies = new Map<string, Buffer>();
metadata = new Map<string, Record<string, string> | undefined>();
/** The initialize-step middleware a real client would run, such as `pinBucketOwner`'s. */
private middleware = new Map<string, Middleware>();
readonly middlewareStack = {
add: (middleware: Middleware, options: { name: string }) =>
void this.middleware.set(options.name, middleware),
remove: (name: string) => this.middleware.delete(name),
};
async send(command: unknown): Promise<unknown> {
const cmdName = (command as { constructor: { name: string } }).constructor.name;
const input = (
let input = (
command as {
input: { Bucket: string; Key: string; Metadata?: Record<string, string>; Body?: unknown };
input: {
Bucket: string;
Key: string;
ExpectedBucketOwner?: string;
Metadata?: Record<string, string>;
Body?: unknown;
};
}
).input;
const sent: Handler = async (args) => {
input = { ...input, ...args.input };
return { output: undefined };
};
await [...this.middleware.values()].reduceRight((next, wrap) => wrap(next), sent)({ input });
const owner = input.ExpectedBucketOwner;
const id = `${input.Bucket}/${input.Key}`;
const handlers: Record<string, () => Promise<unknown>> = {
HeadObjectCommand: async () => {
this.ops.push({ kind: "head", bucket: input.Bucket, key: input.Key });
this.ops.push({ kind: "head", bucket: input.Bucket, key: input.Key, owner });
return this.head(id);
},
GetObjectCommand: async () => {
@@ -42,7 +69,7 @@ export class FakeS3 {
return { Body: Readable.from([this.bodies.get(id) ?? Buffer.alloc(0)]) };
},
PutObjectCommand: async () => {
this.ops.push({ kind: "put", bucket: input.Bucket, key: input.Key });
this.ops.push({ kind: "put", bucket: input.Bucket, key: input.Key, owner });
this.existing.add(id);
this.metadata.set(id, input.Metadata);
this.bodies.set(id, await drainBody(input.Body as NodeJS.ReadableStream | Buffer));
@@ -0,0 +1,64 @@
import { describe, expect, it } from "bun:test";
import { CopyObjectCommand, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
import { parseStateMachineArn, pinBucketOwner } from "./bucketOwner.js";
const STOP = new Error("captured");
/** The input `command` reaches S3's serializer with, read before any request is sent. */
async function sentInput(s3: S3Client, command: PutObjectCommand | CopyObjectCommand) {
let input: Record<string, unknown> = {};
s3.middlewareStack.add(
() => async (args) => {
input = { ...args.input };
throw STOP;
},
{ step: "serialize", name: "capture", override: true },
);
await expect(s3.send(command)).rejects.toBe(STOP);
return input;
}
const client = () =>
new S3Client({ region: "us-east-1", credentials: { accessKeyId: "a", secretAccessKey: "b" } });
describe("parseStateMachineArn", () => {
it("reads the region and account of a state machine ARN", () => {
expect(
parseStateMachineArn("arn:aws:states:us-east-2:123456789012:stateMachine:hyperframes-render"),
).toEqual({ region: "us-east-2", account: "123456789012" });
expect(
parseStateMachineArn("arn:aws-cn:states:cn-north-1:123456789012:stateMachine:hf").account,
).toBe("123456789012");
});
it.each([
"arn:aws:states:us-east-1:1234:stateMachine:hf",
"arn:aws:states:us-east-1:123456789012:execution:hf:run",
"arn:aws:s3:::bucket",
"arn:aws:states:us-east-1:123456789012:stateMachine:hf\nx",
])("refuses %p", (arn) => {
expect(() => parseStateMachineArn(arn)).toThrow("INVALID_STATE_MACHINE_ARN");
});
});
describe("pinBucketOwner", () => {
it("names the owner on every request, over any owner the caller set", async () => {
const s3 = pinBucketOwner(client(), "123456789012");
const put = new PutObjectCommand({
Bucket: "b",
Key: "k",
Body: "x",
ExpectedBucketOwner: "999999999999",
});
expect(await sentInput(s3, put)).toMatchObject({ ExpectedBucketOwner: "123456789012" });
});
it("names the owner of a copy's source too, and a second pin replaces the first", async () => {
const s3 = pinBucketOwner(pinBucketOwner(client(), "111111111111"), "123456789012");
const copy = new CopyObjectCommand({ Bucket: "b", Key: "k", CopySource: "b/old" });
expect(await sentInput(s3, copy)).toMatchObject({
ExpectedBucketOwner: "123456789012",
ExpectedSourceBucketOwner: "123456789012",
});
});
});
@@ -0,0 +1,40 @@
import type { S3Client } from "@aws-sdk/client-s3";
const STATE_MACHINE_ARN =
/^arn:aws(?:-cn|-us-gov)?:states:([a-z]{2}(?:-[a-z]+)+-\d):(\d{12}):stateMachine:[\w-]{1,80}$/;
/** The region and account of a state machine ARN; throws for anything that is not one. */
export function parseStateMachineArn(arn: string): { region: string; account: string } {
const match = STATE_MACHINE_ARN.exec(arn);
if (!match) {
const error = new Error(`[renderToLambda] INVALID_STATE_MACHINE_ARN: ${JSON.stringify(arn)}`);
error.name = "INVALID_STATE_MACHINE_ARN";
throw error;
}
return { region: match[1]!, account: match[2]! };
}
const PIN = "hyperframesExpectedBucketOwner";
/**
* Makes every request `s3` sends name `owner` as the bucket's owner (and the copy source's), so S3 answers
* 403 for a bucket another account owns instead of storing the project there. Applied again, it replaces the pin.
*/
export function pinBucketOwner(s3: S3Client, owner: string): S3Client {
s3.middlewareStack.remove(PIN);
s3.middlewareStack.add(
(next) => (args) => {
const copies = "CopySource" in args.input;
return next({
...args,
input: {
...args.input,
ExpectedBucketOwner: owner,
...(copies && { ExpectedSourceBucketOwner: owner }),
},
});
},
{ step: "initialize", name: PIN },
);
return s3;
}
@@ -45,6 +45,18 @@ const HTML = "<html><body>hi</body></html>";
const CSS = "body { color: red; }";
describe("deploySite", () => {
it("names expectedBucketOwner as the bucket's owner on every request", async () => {
const s3 = new FakeS3();
await deploySite({
projectDir,
bucketName: "test-bucket",
expectedBucketOwner: "123456789012",
s3: asS3Client(s3),
});
expect(s3.ops.length).toBeGreaterThan(0);
expect(s3.ops.filter((op) => op.owner !== "123456789012")).toEqual([]);
});
it("uploads each file once under its content hash, then the site manifest", async () => {
const s3 = new FakeS3();
const result = await deploySite({
+4 -1
View File
@@ -15,6 +15,7 @@ import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync
import { tmpdir } from "node:os";
import { join } from "node:path";
import { S3Client } from "@aws-sdk/client-s3";
import { pinBucketOwner } from "./bucketOwner.js";
import { CONTENT_STORE_RETENTION_DAYS, audioSidecarUri, probeFactsUri } from "../contentStore.js";
import {
buildAudioSidecar,
@@ -63,6 +64,7 @@ export interface DeploySiteOptions {
siteId?: string;
/** Called with a line a user should see, such as audio sidecars skipped for want of ffmpeg. */
onNotice?: (message: string) => void;
expectedBucketOwner?: string;
/** Injection seam for tests. Production callers leave unset. */
s3?: S3Client;
}
@@ -155,7 +157,8 @@ async function tarballSite(site: SiteHandle, s3: S3Client, bucket: string): Prom
/** Upload `projectDir`'s files to the content store and write the site manifest. */
export async function deploySite(opts: DeploySiteOptions): Promise<SiteHandle> {
const s3 = opts.s3 ?? new S3Client({ region: opts.region });
const client = opts.s3 ?? new S3Client({ region: opts.region });
const s3 = opts.expectedBucketOwner ? pinBucketOwner(client, opts.expectedBucketOwner) : client;
if (!statSync(opts.projectDir).isDirectory()) {
throw new Error(`[deploySite] projectDir is not a directory: ${opts.projectDir}`);
}
+1
View File
@@ -8,6 +8,7 @@
* AWS-SDK only — safe to load in any Node environment.
*/
export { parseStateMachineArn, pinBucketOwner } from "./bucketOwner.js";
export {
deploySite,
type DeploySiteOptions,
@@ -44,7 +44,7 @@ class FakeSFN {
input: JSON.parse(input.input),
});
return {
executionArn: `arn:aws:states:us-east-1:1234:execution:hf:${input.name}`,
executionArn: `arn:aws:states:us-east-1:123456789012:execution:hf:${input.name}`,
startDate: new Date(),
};
}
@@ -81,7 +81,7 @@ describe("renderToLambda", () => {
const staleOptions = {
projectDir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
stateMachineArn: "arn:aws:states:us-east-1:123456789012:stateMachine:hf",
config: baseConfig,
planProtocol: "v1",
sfn: asSFNClient(sfn),
@@ -102,7 +102,7 @@ describe("renderToLambda", () => {
const handle = await renderToLambda({
projectDir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
stateMachineArn: "arn:aws:states:us-east-1:123456789012:stateMachine:hf",
config: baseConfig,
executionName: "smoke-1",
sfn: asSFNClient(sfn),
@@ -127,7 +127,7 @@ describe("renderToLambda", () => {
expect(sfn.starts).toHaveLength(1);
const start = sfn.starts[0]!;
expect(start.name).toBe("smoke-1");
expect(start.stateMachineArn).toBe("arn:aws:states:us-east-1:1234:stateMachine:hf");
expect(start.stateMachineArn).toBe("arn:aws:states:us-east-1:123456789012:stateMachine:hf");
expect(start.input).toEqual({
ProjectS3Uri: handle.projectS3Uri,
PlanOutputS3Prefix: "s3://test-bucket/renders/smoke-1/",
@@ -137,13 +137,50 @@ describe("renderToLambda", () => {
});
});
it("names the state machine's account as the owner of every bucket it touches", async () => {
const s3 = new FakeS3();
const site = await deploySite({ projectDir, bucketName: "test-bucket", s3: asS3Client(s3) });
s3.ops = [];
for (const siteHandle of [undefined, site]) {
await renderToLambda({
projectDir,
siteHandle,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:123456789012:stateMachine:hf",
config: baseConfig,
sfn: asSFNClient(new FakeSFN()),
s3: asS3Client(s3),
});
}
expect(s3.ops.length).toBeGreaterThan(0);
expect(s3.ops.filter((op) => op.owner !== "123456789012")).toEqual([]);
});
it("refuses a state machine ARN that is not one before any AWS work", async () => {
const sfn = new FakeSFN();
const s3 = new FakeS3();
await expect(
renderToLambda({
projectDir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
config: baseConfig,
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
}),
).rejects.toMatchObject({ name: "INVALID_STATE_MACHINE_ARN" });
expect(sfn.describes).toBe(0);
expect(s3.ops).toHaveLength(0);
});
it("derives the file extension from config.format", async () => {
const sfn = new FakeSFN();
const s3 = new FakeS3();
const handle = await renderToLambda({
projectDir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
stateMachineArn: "arn:aws:states:us-east-1:123456789012:stateMachine:hf",
config: { ...baseConfig, format: "mov" },
executionName: "smoke-mov",
sfn: asSFNClient(sfn),
@@ -166,7 +203,7 @@ describe("renderToLambda", () => {
const handle = await renderToLambda({
siteHandle: prebuilt,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
stateMachineArn: "arn:aws:states:us-east-1:123456789012:stateMachine:hf",
config: baseConfig,
executionName: "smoke-reuse",
sfn: asSFNClient(sfn),
@@ -185,7 +222,7 @@ describe("renderToLambda", () => {
renderToLambda({
projectDir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
stateMachineArn: "arn:aws:states:us-east-1:123456789012:stateMachine:hf",
config: baseConfig,
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
@@ -203,7 +240,7 @@ describe("renderToLambda", () => {
renderToLambda({
siteHandle: siteHandleFromId("test-bucket", siteId),
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
stateMachineArn: "arn:aws:states:us-east-1:123456789012:stateMachine:hf",
config: baseConfig,
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
@@ -244,7 +281,7 @@ describe("renderToLambda", () => {
siteHandle: site,
projectDir: dir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
stateMachineArn: "arn:aws:states:us-east-1:123456789012:stateMachine:hf",
config: baseConfig,
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
@@ -316,7 +353,7 @@ describe("renderToLambda", () => {
await renderToLambda({
projectDir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
stateMachineArn: "arn:aws:states:us-east-1:123456789012:stateMachine:hf",
config: { ...baseConfig, fps: 50 as never },
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
@@ -334,7 +371,7 @@ describe("renderToLambda", () => {
await expect(
renderToLambda({
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
stateMachineArn: "arn:aws:states:us-east-1:123456789012:stateMachine:hf",
config: baseConfig,
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
@@ -348,7 +385,7 @@ describe("renderToLambda", () => {
const handle = await renderToLambda({
projectDir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
stateMachineArn: "arn:aws:states:us-east-1:123456789012:stateMachine:hf",
config: baseConfig,
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
@@ -363,7 +400,7 @@ describe("renderToLambda", () => {
await renderToLambda({
projectDir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
stateMachineArn: "arn:aws:states:us-east-1:123456789012:stateMachine:hf",
config: { ...baseConfig, variables },
executionName: "smoke-variables",
sfn: asSFNClient(sfn),
@@ -387,7 +424,7 @@ describe("renderToLambda", () => {
renderToLambda({
projectDir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
stateMachineArn: "arn:aws:states:us-east-1:123456789012:stateMachine:hf",
config: { ...baseConfig, variables: { blob: huge } },
executionName: "smoke-too-big",
sfn: asSFNClient(sfn),
@@ -406,7 +443,7 @@ describe("renderToLambda", () => {
renderToLambda({
projectDir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
stateMachineArn: "arn:aws:states:us-east-1:123456789012:stateMachine:hf",
config: {
...baseConfig,
// BigInt would throw at JSON.stringify time; catch it at the validator
@@ -445,7 +482,7 @@ describe("renderToLambda", () => {
renderToLambda({
projectDir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
stateMachineArn: "arn:aws:states:us-east-1:123456789012:stateMachine:hf",
config: baseConfig,
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
@@ -24,6 +24,7 @@ import type { SerializableDistributedRenderConfig } from "../events.js";
import { formatExtension } from "../formatExtension.js";
import { formatS3Uri } from "../s3Transport.js";
import { SITE_MANIFEST_INVALID } from "../siteManifest.js";
import { parseStateMachineArn, pinBucketOwner } from "./bucketOwner.js";
import { deploySite, ensureSiteStored, type SiteHandle } from "./deploySite.js";
import {
validateDistributedRenderConfig,
@@ -101,8 +102,10 @@ export async function renderToLambda(opts: RenderToLambdaOptions): Promise<Rende
throw new Error("[renderToLambda] either siteHandle or projectDir must be supplied");
}
const { account } = parseStateMachineArn(opts.stateMachineArn);
const sfn = opts.sfn ?? new SFNClient({ region: opts.region });
await assertStackReadsSites({ stateMachineArn: opts.stateMachineArn, sfn });
const s3 = pinBucketOwner(opts.s3 ?? new S3Client({ region: opts.region }), account);
const executionName = opts.executionName ?? `hf-render-${randomUUID()}`;
const ext = formatExtension(opts.config.format);
@@ -114,17 +117,13 @@ export async function renderToLambda(opts: RenderToLambdaOptions): Promise<Rende
const outputS3Uri = formatS3Uri({ bucket: opts.bucketName, key: outputKey });
const site = opts.siteHandle
? await ensureSiteStored(
opts.siteHandle,
opts.s3 ?? new S3Client({ region: opts.region }),
opts.projectDir,
)
? await ensureSiteStored(opts.siteHandle, s3, opts.projectDir)
: await deploySite({
projectDir: opts.projectDir as string,
bucketName: opts.bucketName,
region: opts.region,
onNotice: opts.onNotice,
s3: opts.s3,
s3,
});
const input = {
@@ -39,8 +39,8 @@ afterEach(() => {
const stack = {
stackName: "Demo",
region: "us-east-1",
bucketName: "b",
stateMachineArn: "s",
bucketName: "demo-bucket",
stateMachineArn: "arn:aws:states:us-east-1:123456789012:stateMachine:hf",
functionName: "f",
lambdaMemoryMb: 10240,
deployedAt: "2026-01-01T00:00:00Z",
@@ -229,7 +229,8 @@ export async function runRenderBatch(args: RenderBatchArgs): Promise<void> {
// Deploy the site once and reuse it across every entry. --site-id and
// --dry-run both skip the deploy via a synthesised handle.
let siteHandle: SiteHandle;
const { assertStackReadsSites, deploySite, siteHandleFromId } = await loadSDK();
const { assertStackReadsSites, deploySite, parseStateMachineArn, siteHandleFromId } =
await loadSDK();
if (!args.dryRun) {
await assertStackReadsSites({ stateMachineArn: stack.stateMachineArn, region: stack.region });
}
@@ -241,6 +242,7 @@ export async function runRenderBatch(args: RenderBatchArgs): Promise<void> {
siteHandle = await deploySite({
projectDir,
bucketName: stack.bucketName,
expectedBucketOwner: parseStateMachineArn(stack.stateMachineArn).account,
region: stack.region,
onNotice: (message) => console.error(c.dim(message)),
});
+2 -1
View File
@@ -30,11 +30,12 @@ export async function runSitesCreate(args: SitesCreateArgs): Promise<void> {
const stack = requireStack(args.stackName);
const projectDir = resolvePath(args.projectDir);
const { assertStackReadsSites, deploySite } = await loadSDK();
const { assertStackReadsSites, deploySite, parseStateMachineArn } = await loadSDK();
await assertStackReadsSites({ stateMachineArn: stack.stateMachineArn, region: stack.region });
const handle = await deploySite({
projectDir,
bucketName: stack.bucketName,
expectedBucketOwner: parseStateMachineArn(stack.stateMachineArn).account,
region: stack.region,
siteId: args.siteId,
onNotice: (message) => console.error(c.dim(message)),
@@ -9,12 +9,16 @@ const sdk = vi.hoisted(() => ({
renderToLambda: vi.fn(),
siteHandleFromId: vi.fn(),
}));
vi.mock("@hyperframes/aws-lambda/sdk", () => sdk);
vi.mock("@hyperframes/aws-lambda/sdk", async (importOriginal) => {
const { parseStateMachineArn } =
await importOriginal<typeof import("@hyperframes/aws-lambda/sdk")>();
return { ...sdk, parseStateMachineArn };
});
vi.mock("./state.js", () => ({
DEFAULT_STACK_NAME: "hyperframes",
requireStack: () => ({
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-2:1234:stateMachine:hf",
stateMachineArn: "arn:aws:states:us-east-2:123456789012:stateMachine:hf",
region: "us-east-2",
reservedConcurrency: 8,
}),
@@ -63,3 +67,36 @@ describe("a stack too old to read sites is refused before anything uploads", ()
expect(sdk.deploySite).not.toHaveBeenCalled();
});
});
describe("an upload names the state machine's account as the bucket's owner", () => {
beforeEach(() => {
sdk.assertStackReadsSites.mockResolvedValue(undefined);
sdk.deploySite.mockResolvedValue({
siteId: "s",
projectS3Uri: "s3://test-bucket/sites/s/files.json",
});
});
it("in sites create", async () => {
await runSitesCreate({ projectDir, stackName: "hyperframes", json: true });
expect(sdk.deploySite).toHaveBeenCalledWith(
expect.objectContaining({ bucketName: "test-bucket", expectedBucketOwner: "123456789012" }),
);
});
it("in render-batch", async () => {
await runRenderBatch({
projectDir,
stackName: "hyperframes",
batch: join(projectDir, "batch.jsonl"),
fps: 30,
width: 1920,
height: 1080,
format: "mp4",
json: true,
}).catch(() => {});
expect(sdk.deploySite).toHaveBeenCalledWith(
expect.objectContaining({ bucketName: "test-bucket", expectedBucketOwner: "123456789012" }),
);
});
});
+69 -2
View File
@@ -1,5 +1,5 @@
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import {
@@ -26,7 +26,7 @@ const sample: StackOutputs = {
stackName: "test",
region: "us-east-1",
bucketName: "bucket-x",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
stateMachineArn: "arn:aws:states:us-east-1:123456789012:stateMachine:hf",
functionName: "hf-render",
lambdaMemoryMb: 10240,
deployedAt: "2026-05-16T00:00:00Z",
@@ -81,4 +81,71 @@ describe("lambda state file", () => {
quiet.mockRestore();
}
});
function plant(stackName: string, contents: unknown): void {
const path = stateFilePath(stackName, workdir);
mkdirSync(dirname(path), { recursive: true });
writeFileSync(path, JSON.stringify(contents));
}
function refusal(stackName: string): string {
const said = vi.spyOn(console, "error").mockImplementation(() => {});
try {
expect(() => requireStack(stackName, workdir)).toThrow();
return String(said.mock.calls[0]?.[0]);
} finally {
said.mockRestore();
}
}
it.each([
["a bucket name S3 would not accept", { bucketName: "Not/A/Bucket" }, "bucketName"],
[
"a state machine ARN that is not one",
{ stateMachineArn: "arn:aws:s3:::bucket" },
"stateMachineArn",
],
[
"a short account in the ARN",
{ stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf" },
"stateMachineArn",
],
[
"a region other than the state machine's",
{ region: "eu-west-1" },
"a state machine in us-east-1",
],
["a region that is not one", { region: "../x" }, "region"],
["a memory size that is not a number", { lambdaMemoryMb: "10240" }, "lambdaMemoryMb"],
])("refuses a stack file with %s", (_name, change, reason) => {
plant("test", { ...sample, ...change });
expect(readStackOutputs("test", workdir)).toBeNull();
expect(refusal("test")).toContain(reason);
});
it.skipIf(process.platform === "win32")(
"refuses a stack file that is a link, and never follows it",
() => {
const elsewhere = join(workdir, "elsewhere.json");
writeFileSync(elsewhere, JSON.stringify(sample));
mkdirSync(join(workdir, ".hyperframes"));
symlinkSync(elsewhere, stateFilePath("test", workdir));
expect(readStackOutputs("test", workdir)).toBeNull();
expect(refusal("test")).toContain("is a link or not a plain file");
deleteStackOutputs("test", workdir);
expect(readFileSync(elsewhere, "utf8")).toBe(JSON.stringify(sample));
},
);
it.skipIf(process.platform === "win32")("refuses a .hyperframes folder that is a link", () => {
const elsewhere = mkdtempSync(join(tmpdir(), "hf-lambda-cli-elsewhere-"));
try {
writeStackOutputs(sample, elsewhere);
symlinkSync(join(elsewhere, ".hyperframes"), join(workdir, ".hyperframes"));
expect(readStackOutputs("test", workdir)).toBeNull();
expect(refusal("test")).toContain("is a link or not a plain file");
} finally {
rmSync(elsewhere, { recursive: true, force: true });
}
});
});
+72 -14
View File
@@ -7,13 +7,18 @@ import { failCommand } from "../../utils/commandResult.js";
* Stored at `<cwd>/.hyperframes/lambda-stack-<stackName>.json`. Project-
* local on purpose: a developer who runs `hyperframes lambda deploy` in
* two different worktrees will get two distinct stack files, which is
* the right default. If the user wants a shared default location, they
* can symlink the directory.
* the right default. The file arrives with any project someone else sent, so
* it is read only as a plain file and each field is checked before use.
*/
import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
import { existsSync, readdirSync } from "node:fs";
import { join } from "node:path";
import { writeRecord } from "../../utils/projectRecords.js";
import {
readRecordTail,
recordKind,
removeRecord,
writeRecord,
} from "../../utils/projectRecords.js";
export interface StackOutputs {
/** Project-name prefix passed to `deploy`. Used as CloudFormation stack-name suffix. */
@@ -58,25 +63,74 @@ export function writeStackOutputs(outputs: StackOutputs, cwd: string = process.c
return path;
}
const MAX_STATE_BYTES = 64 * 1024;
const REGION = /^[a-z]{2}(?:-[a-z]+)+-\d$/;
const BUCKET = /^(?!xn--)(?!.*\.\.)[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/;
const STATE_MACHINE_ARN =
/^arn:aws(?:-cn|-us-gov)?:states:([a-z]{2}(?:-[a-z]+)+-\d):\d{12}:stateMachine:[\w-]{1,80}$/;
const FUNCTION_NAME = /^[\w-]{1,64}$/;
const isText = (value: unknown, shape: RegExp): value is string =>
typeof value === "string" && shape.test(value);
const optional = (valid: (value: unknown) => boolean) => (value: unknown) =>
value === undefined || valid(value);
const isCount = (value: unknown) =>
typeof value === "number" && Number.isInteger(value) && value > 0;
const isFunctionName = (value: unknown) => isText(value, FUNCTION_NAME);
const FIELD_CHECKS: [keyof StackOutputs, (value: unknown) => boolean][] = [
["stackName", (value) => typeof value === "string"],
["region", (value) => isText(value, REGION)],
["bucketName", (value) => isText(value, BUCKET)],
["stateMachineArn", (value) => isText(value, STATE_MACHINE_ARN)],
["functionName", isFunctionName],
["lambdaMemoryMb", isCount],
["reservedConcurrency", optional(isCount)],
["videoFunctionName", optional(isFunctionName)],
["videoRepository", optional((value) => typeof value === "string")],
];
/** Why `value` is not the outputs `lambda deploy` writes, or null when it is. */
function stackOutputsProblem(value: unknown): string | null {
if (typeof value !== "object" || value === null) return "is not a JSON object";
const stack: Partial<Record<keyof StackOutputs, unknown>> = value;
const invalid = FIELD_CHECKS.find(([field, valid]) => !valid(stack[field]));
if (invalid) return `has no valid ${invalid[0]}`;
const arnRegion = STATE_MACHINE_ARN.exec(String(stack.stateMachineArn))?.[1];
return arnRegion === stack.region
? null
: `names region ${stack.region} but a state machine in ${arnRegion}`;
}
/** The stack file's outputs; null when there is none; why it cannot be used when it is a link or malformed. */
function loadStackOutputs(stackName: string, cwd: string): StackOutputs | string | null {
const name = `${STATE_FILE_PREFIX}${stackName}.json`;
if (recordKind(cwd, name) === "absent") return null;
const record = readRecordTail(cwd, name, MAX_STATE_BYTES);
if (!record) return "is a link or not a plain file in a real .hyperframes folder";
if (!record.whole) return "is too large";
let value: unknown;
try {
value = JSON.parse(record.text);
} catch {
return "is not valid JSON";
}
return stackOutputsProblem(value) ?? (value as StackOutputs);
}
export function readStackOutputs(
stackName: string = DEFAULT_STACK_NAME,
cwd: string = process.cwd(),
): StackOutputs | null {
const path = stateFilePath(stackName, cwd);
if (!existsSync(path)) return null;
try {
return JSON.parse(readFileSync(path, "utf-8")) as StackOutputs;
} catch {
return null;
}
const stack = loadStackOutputs(stackName, cwd);
return typeof stack === "string" ? null : stack;
}
export function deleteStackOutputs(
stackName: string = DEFAULT_STACK_NAME,
cwd: string = process.cwd(),
): void {
const path = stateFilePath(stackName, cwd);
if (existsSync(path)) rmSync(path);
removeRecord(cwd, `${STATE_FILE_PREFIX}${stackName}.json`);
}
export function listStackNames(cwd: string = process.cwd()): string[] {
@@ -96,9 +150,13 @@ const sameFileOnCaseInsensitiveDisk = (a: string, b: string): boolean =>
* hint is consistent.
*/
export function requireStack(stackName: string, cwd: string = process.cwd()): StackOutputs {
const stack = readStackOutputs(stackName, cwd);
const stack = loadStackOutputs(stackName, cwd);
const path = stateFilePath(stackName, cwd);
const deploy = `Run \`hyperframes lambda deploy${stackName === DEFAULT_STACK_NAME ? "" : ` --stack-name=${stackName}`}\``;
if (typeof stack === "string") {
console.error(`[hyperframes lambda] ${path} ${stack}. ${deploy} to rewrite it.`);
failCommand();
}
if (!stack) {
const known = listStackNames(cwd);
const hint = known.length ? ` Known stacks here: ${known.join(", ")}.` : "";
+1 -1
View File
@@ -10,7 +10,7 @@
"files": 80
},
"hyperframes-cli": {
"hash": "a1b8be77ce157ce4",
"hash": "8c7ba18bfc4e86c1",
"files": 13
},
"hyperframes-registry": {
+1 -1
View File
@@ -181,7 +181,7 @@ The default action set is deliberately broad (`Resource: "*"`) because CloudForm
## State, cost, and cleanup
`hyperframes lambda` stores per-stack metadata under `<cwd>/.hyperframes/lambda-stack-<name>.json` (bucket name, state-machine ARN, region). Not secret, but AWS-account-identifying. Commit it to a repo or `.gitignore` it per your workflow.
`hyperframes lambda` stores per-stack metadata under `<cwd>/.hyperframes/lambda-stack-<name>.json` (bucket name, state-machine ARN, region). Not secret, but AWS-account-identifying. Commit it to a repo or `.gitignore` it per your workflow. The CLI refuses a state file with malformed fields or one that is a symlink, and uploads only to a bucket owned by the account of the file's state machine.
- `lambda destroy` removes the SAM stack but **leaves the S3 bucket** (`Retain`). Delete it manually if you want the storage back.
- Lambda billing is per-invocation + duration. `progress` reports the accrued cost.