@voyant-travel/runtime 0.3.0

package/dist/node-server.d.ts

@@ -0,0 +1,56 @@
+import { type ServerType } from "@hono/node-server";
+import type { ExecutionContextLike, FetchHandler, ScheduledHandler } from "./types.js";
+import { type WaitUntilRegistry } from "./wait-until.js";
+/** Path that health probes hit — always exempt from the origin-trust gate. */
+export declare const HEALTHZ_PATH = "/healthz";
+/** Trust-protected HTTP hook Cloud Scheduler POSTs to trigger `scheduled()`. */
+export declare const SCHEDULED_PATH = "/__voyant/scheduled";
+export interface ScheduledHandlerArgs<Env> {
+    request: Request;
+    scheduled: ScheduledHandler<Env>;
+    env: Env;
+    ctx: ExecutionContextLike;
+}
+/**
+ * Invoke a Worker-style `scheduled()` handler from an HTTP request. Reads the
+ * cron expression from the `cron` query param. Returns `202` on success, `500`
+ * on handler error, `400` when `cron` is missing. Exported standalone so it can
+ * be mounted into any server loop, not just {@link createNodeServer}.
+ */
+export declare function scheduledHandler<Env>(args: ScheduledHandlerArgs<Env>): Promise<Response>;
+export interface CreateNodeServerOptions<Env> {
+    /** The app's Worker-style fetch entrypoint — identical to the Workers build. */
+    fetch: FetchHandler<Env>;
+    /** Optional Worker-style scheduled handler, exposed at {@link SCHEDULED_PATH}. */
+    scheduled?: ScheduledHandler<Env>;
+    /** The composed env bag (see `composeNodeEnv`). */
+    env: Env;
+    /** Listen port. Defaults to `PORT` env or `8080`. */
+    port?: number;
+    /**
+     * Per-app shared secret for the `x-voyant-origin-trust` header. When set,
+     * every request except {@link HEALTHZ_PATH} must present a matching header or
+     * receives `403`. Leave unset only for a fully private network boundary.
+     */
+    originTrustSecret?: string;
+    /** Milliseconds to wait for in-flight `waitUntil` work on shutdown. Default 10s. */
+    drainTimeoutMs?: number;
+}
+export interface NodeServerHandle {
+    server: ServerType;
+    /** The `waitUntil` registry backing per-request execution contexts. */
+    registry: WaitUntilRegistry;
+    /** Resolved listen port. */
+    port: number;
+    /** Stop accepting, drain background work, close. Idempotent. */
+    close(): Promise<void>;
+}
+/**
+ * Boot a Node HTTP server that runs an operator app's `fetch(request, env, ctx)`
+ * unchanged. Adds the pieces Cloudflare provides implicitly: a real per-request
+ * `waitUntil` context, an origin-trust gate, an HTTP `scheduled()` hook for
+ * Cloud Scheduler, and graceful SIGTERM/SIGINT shutdown that drains in-flight
+ * background work before exit.
+ */
+export declare function createNodeServer<Env>(options: CreateNodeServerOptions<Env>): NodeServerHandle;
+//# sourceMappingURL=node-server.d.ts.map

package/dist/node-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-server.d.ts","sourceRoot":"","sources":["../src/node-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAS,MAAM,mBAAmB,CAAA;AAG1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AACtF,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAEjF,8EAA8E;AAC9E,eAAO,MAAM,YAAY,aAAa,CAAA;AACtC,gFAAgF;AAChF,eAAO,MAAM,cAAc,wBAAwB,CAAA;AAEnD,MAAM,WAAW,oBAAoB,CAAC,GAAG;IACvC,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAA;IAChC,GAAG,EAAE,GAAG,CAAA;IACR,GAAG,EAAE,oBAAoB,CAAA;CAC1B;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,IAAI,EAAE,oBAAoB,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,CAY9F;AAED,MAAM,WAAW,uBAAuB,CAAC,GAAG;IAC1C,gFAAgF;IAChF,KAAK,EAAE,YAAY,CAAC,GAAG,CAAC,CAAA;IACxB,kFAAkF;IAClF,SAAS,CAAC,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAA;IACjC,mDAAmD;IACnD,GAAG,EAAE,GAAG,CAAA;IACR,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,oFAAoF;IACpF,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,UAAU,CAAA;IAClB,uEAAuE;IACvE,QAAQ,EAAE,iBAAiB,CAAA;IAC3B,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,gEAAgE;IAChE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,uBAAuB,CAAC,GAAG,CAAC,GAAG,gBAAgB,CAmD7F"}

package/dist/node-server.js

@@ -0,0 +1,74 @@
+import { serve } from "@hono/node-server";
+import { originTrustMiddleware } from "./trust.js";
+import { createWaitUntilRegistry } from "./wait-until.js";
+/** Path that health probes hit — always exempt from the origin-trust gate. */
+export const HEALTHZ_PATH = "/healthz";
+/** Trust-protected HTTP hook Cloud Scheduler POSTs to trigger `scheduled()`. */
+export const SCHEDULED_PATH = "/__voyant/scheduled";
+/**
+ * Invoke a Worker-style `scheduled()` handler from an HTTP request. Reads the
+ * cron expression from the `cron` query param. Returns `202` on success, `500`
+ * on handler error, `400` when `cron` is missing. Exported standalone so it can
+ * be mounted into any server loop, not just {@link createNodeServer}.
+ */
+export async function scheduledHandler(args) {
+    const cron = new URL(args.request.url).searchParams.get("cron");
+    if (!cron) {
+        return new Response("Missing `cron` query param", { status: 400 });
+    }
+    try {
+        await args.scheduled({ cron, scheduledTime: Date.now() }, args.env, args.ctx);
+        return new Response(null, { status: 202 });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return new Response(`scheduled handler failed: ${message}`, { status: 500 });
+    }
+}
+/**
+ * Boot a Node HTTP server that runs an operator app's `fetch(request, env, ctx)`
+ * unchanged. Adds the pieces Cloudflare provides implicitly: a real per-request
+ * `waitUntil` context, an origin-trust gate, an HTTP `scheduled()` hook for
+ * Cloud Scheduler, and graceful SIGTERM/SIGINT shutdown that drains in-flight
+ * background work before exit.
+ */
+export function createNodeServer(options) {
+    const port = options.port ?? Number.parseInt(process.env.PORT ?? "8080", 10);
+    const registry = createWaitUntilRegistry();
+    const trustGate = options.originTrustSecret
+        ? originTrustMiddleware(options.originTrustSecret, { exemptPaths: [HEALTHZ_PATH] })
+        : undefined;
+    async function handler(request) {
+        const url = new URL(request.url);
+        if (url.pathname === HEALTHZ_PATH) {
+            return new Response("ok", { status: 200 });
+        }
+        if (trustGate) {
+            const rejection = trustGate(request);
+            if (rejection)
+                return rejection;
+        }
+        const ctx = registry.context();
+        if (options.scheduled && request.method === "POST" && url.pathname === SCHEDULED_PATH) {
+            return scheduledHandler({ request, scheduled: options.scheduled, env: options.env, ctx });
+        }
+        return options.fetch(request, options.env, ctx);
+    }
+    const server = serve({ fetch: handler, port });
+    let closing;
+    const close = () => {
+        closing ??= (async () => {
+            await new Promise((resolve, reject) => {
+                server.close((err) => (err ? reject(err) : resolve()));
+            });
+            await registry.drain(options.drainTimeoutMs);
+        })();
+        return closing;
+    };
+    const onSignal = () => {
+        void close().then(() => process.exit(0), () => process.exit(1));
+    };
+    process.once("SIGTERM", onSignal);
+    process.once("SIGINT", onSignal);
+    return { server, registry, port, close };
+}

package/dist/node-server.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=node-server.test.d.ts.map

package/dist/node-server.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-server.test.d.ts","sourceRoot":"","sources":["../src/node-server.test.ts"],"names":[],"mappings":""}

package/dist/node-server.test.js

@@ -0,0 +1,86 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createNodeServer } from "./node-server.js";
+import { ORIGIN_TRUST_HEADER } from "./trust.js";
+const handles = [];
+afterEach(async () => {
+    while (handles.length) {
+        await handles.pop()?.close();
+    }
+});
+async function ready(handle) {
+    const server = handle.server;
+    if (!server.listening) {
+        await new Promise((resolve) => server.once("listening", () => resolve()));
+    }
+    const addr = server.address();
+    return addr.port;
+}
+function boot(options) {
+    const handle = createNodeServer({ ...options, port: 0 });
+    handles.push(handle);
+    return handle;
+}
+describe("createNodeServer", () => {
+    it("runs the app fetch with the composed env and a real waitUntil ctx", async () => {
+        let sideEffectDone = false;
+        const handle = boot({
+            env: { GREETING: "hi" },
+            fetch: (_req, env, ctx) => {
+                ctx.waitUntil(new Promise((resolve) => setTimeout(() => {
+                    sideEffectDone = true;
+                    resolve();
+                }, 20)));
+                return new Response(env.GREETING);
+            },
+        });
+        const port = await ready(handle);
+        const res = await fetch(`http://127.0.0.1:${port}/anything`);
+        expect(await res.text()).toBe("hi");
+        await handle.close();
+        expect(sideEffectDone).toBe(true);
+    });
+    it("rejects requests without a valid origin-trust header, exempting /healthz", async () => {
+        const handle = boot({
+            env: {},
+            originTrustSecret: "top-secret",
+            fetch: () => new Response("app"),
+        });
+        const port = await ready(handle);
+        const denied = await fetch(`http://127.0.0.1:${port}/v1/admin/x`);
+        expect(denied.status).toBe(403);
+        const health = await fetch(`http://127.0.0.1:${port}/healthz`);
+        expect(health.status).toBe(200);
+        const allowed = await fetch(`http://127.0.0.1:${port}/v1/admin/x`, {
+            headers: { [ORIGIN_TRUST_HEADER]: "top-secret" },
+        });
+        expect(await allowed.text()).toBe("app");
+    });
+    it("dispatches the scheduled handler over HTTP with the cron expression", async () => {
+        let seenCron;
+        const handle = boot({
+            env: {},
+            originTrustSecret: "top-secret",
+            fetch: () => new Response("app"),
+            scheduled: (event) => {
+                seenCron = event.cron;
+            },
+        });
+        const port = await ready(handle);
+        const res = await fetch(`http://127.0.0.1:${port}/__voyant/scheduled?cron=${encodeURIComponent("*/2 * * * *")}`, { method: "POST", headers: { [ORIGIN_TRUST_HEADER]: "top-secret" } });
+        expect(res.status).toBe(202);
+        expect(seenCron).toBe("*/2 * * * *");
+    });
+    it("requires trust for the scheduled hook", async () => {
+        const handle = boot({
+            env: {},
+            originTrustSecret: "top-secret",
+            fetch: () => new Response("app"),
+            scheduled: () => undefined,
+        });
+        const port = await ready(handle);
+        const res = await fetch(`http://127.0.0.1:${port}/__voyant/scheduled?cron=x`, {
+            method: "POST",
+        });
+        expect(res.status).toBe(403);
+    });
+});

package/dist/r2.d.ts

@@ -0,0 +1,41 @@
+import type { R2BucketLike, R2ObjectLike } from "@voyant-travel/storage/providers/r2";
+/**
+ * An `R2Bucket`-shaped client backed by R2's S3-compatible API. Signing reuses
+ * `@voyant-travel/storage`'s SigV4 implementation (verified against AWS test
+ * vectors) rather than reimplementing it here. The shim satisfies the
+ * structural {@link R2BucketLike} the storage providers depend on, plus the
+ * richer `bucket.get(key) -> { arrayBuffer(), body, httpMetadata }` surface the
+ * operator's document routes use.
+ */
+export type R2Fetch = typeof fetch;
+/** The object returned by {@link R2BucketShim.get}. Superset of {@link R2ObjectLike}. */
+export interface R2ShimObject extends R2ObjectLike {
+    /** Buffered body bytes, re-readable as a stream. */
+    body: ReadableStream<Uint8Array> | null;
+    httpMetadata?: {
+        contentType?: string;
+    };
+    customMetadata?: Record<string, string>;
+    size: number;
+}
+export interface R2BucketShim extends R2BucketLike {
+    get(key: string): Promise<R2ShimObject | null>;
+    head(key: string): Promise<Omit<R2ShimObject, "arrayBuffer" | "body"> | null>;
+}
+export interface R2BucketShimOptions {
+    /** R2 S3 endpoint, e.g. `https://<accountid>.r2.cloudflarestorage.com`. */
+    endpoint: string;
+    /** Bucket name. */
+    bucket: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** S3 region — R2 ignores it but SigV4 requires one. Defaults to `"auto"`. */
+    region?: string;
+    /** Override the fetch implementation (tests / custom agents). */
+    fetchImpl?: R2Fetch;
+}
+/**
+ * Build an {@link R2BucketShim} over the R2 S3-compatible API.
+ */
+export declare function createR2BucketShim(options: R2BucketShimOptions): R2BucketShim;
+//# sourceMappingURL=r2.d.ts.map

package/dist/r2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2.d.ts","sourceRoot":"","sources":["../src/r2.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAEb,MAAM,qCAAqC,CAAA;AAE5C;;;;;;;GAOG;AACH,MAAM,MAAM,OAAO,GAAG,OAAO,KAAK,CAAA;AAElC,yFAAyF;AACzF,MAAM,WAAW,YAAa,SAAQ,YAAY;IAChD,oDAAoD;IACpD,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAA;IACvC,YAAY,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACvC,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,YAAa,SAAQ,YAAY;IAChD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAA;IAC9C,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,aAAa,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC,CAAA;CAC9E;AAED,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAA;IAChB,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,eAAe,EAAE,MAAM,CAAA;IACvB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,iEAAiE;IACjE,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAID;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CA4G7E"}

package/dist/r2.js

@@ -0,0 +1,147 @@
+import { signRequest } from "@voyant-travel/storage/lib/sigv4";
+const CUSTOM_META_PREFIX = "x-amz-meta-";
+/**
+ * Build an {@link R2BucketShim} over the R2 S3-compatible API.
+ */
+export function createR2BucketShim(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const region = options.region ?? "auto";
+    const endpoint = options.endpoint.replace(/\/$/, "");
+    const credentials = {
+        accessKeyId: options.accessKeyId,
+        secretAccessKey: options.secretAccessKey,
+    };
+    function objectUrl(key) {
+        return `${endpoint}/${encodeURIComponent(options.bucket)}/${encodeKey(key)}`;
+    }
+    async function send(method, key, init = {}) {
+        const url = objectUrl(key);
+        const signed = await signRequest({
+            method,
+            url,
+            headers: init.headers,
+            body: init.body,
+            credentials,
+            region,
+            service: "s3",
+        });
+        return fetchImpl(url, {
+            method,
+            headers: signed.headers,
+            body: init.body,
+        });
+    }
+    function readMetadata(response) {
+        const contentType = response.headers.get("content-type") ?? undefined;
+        const customMetadata = {};
+        response.headers.forEach((value, name) => {
+            if (name.toLowerCase().startsWith(CUSTOM_META_PREFIX)) {
+                customMetadata[name.slice(CUSTOM_META_PREFIX.length)] = value;
+            }
+        });
+        const contentLength = response.headers.get("content-length");
+        const result = { size: contentLength ? Number.parseInt(contentLength, 10) : 0 };
+        if (contentType !== undefined)
+            result.httpMetadata = { contentType };
+        if (Object.keys(customMetadata).length > 0)
+            result.customMetadata = customMetadata;
+        return result;
+    }
+    return {
+        async put(key, value, putOptions) {
+            const bytes = await toBytes(value);
+            const headers = putHeaders(putOptions);
+            const response = await send("PUT", key, { headers, body: bytes });
+            if (!response.ok) {
+                const text = await response.text().catch(() => "");
+                throw new Error(`R2 put failed (${response.status}): ${text}`);
+            }
+            return { key };
+        },
+        async delete(key) {
+            const keys = Array.isArray(key) ? key : [key];
+            for (const k of keys) {
+                const response = await send("DELETE", k);
+                // 204 on success, 404 on missing — both are effectively "gone".
+                if (!response.ok && response.status !== 404) {
+                    const text = await response.text().catch(() => "");
+                    throw new Error(`R2 delete failed (${response.status}): ${text}`);
+                }
+            }
+        },
+        async get(key) {
+            const response = await send("GET", key);
+            if (response.status === 404)
+                return null;
+            if (!response.ok) {
+                const text = await response.text().catch(() => "");
+                throw new Error(`R2 get failed (${response.status}): ${text}`);
+            }
+            const buffer = await response.arrayBuffer();
+            const meta = readMetadata(response);
+            const object = {
+                arrayBuffer: async () => buffer.slice(0),
+                body: bytesToStream(new Uint8Array(buffer)),
+                size: meta.size || buffer.byteLength,
+            };
+            if (meta.httpMetadata)
+                object.httpMetadata = meta.httpMetadata;
+            if (meta.customMetadata)
+                object.customMetadata = meta.customMetadata;
+            return object;
+        },
+        async head(key) {
+            const response = await send("HEAD", key);
+            if (response.status === 404)
+                return null;
+            if (!response.ok) {
+                const text = await response.text().catch(() => "");
+                throw new Error(`R2 head failed (${response.status}): ${text}`);
+            }
+            return readMetadata(response);
+        },
+    };
+}
+function putHeaders(putOptions) {
+    const headers = {};
+    if (putOptions?.httpMetadata?.contentType) {
+        headers["content-type"] = putOptions.httpMetadata.contentType;
+    }
+    if (putOptions?.customMetadata) {
+        for (const [k, v] of Object.entries(putOptions.customMetadata)) {
+            headers[`${CUSTOM_META_PREFIX}${k.toLowerCase()}`] = v;
+        }
+    }
+    return headers;
+}
+function encodeKey(key) {
+    return key
+        .split("/")
+        .map((segment) => encodeURIComponent(segment).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`))
+        .join("/");
+}
+async function toBytes(value) {
+    if (value === null)
+        return new Uint8Array();
+    if (typeof value === "string")
+        return new TextEncoder().encode(value);
+    if (value instanceof Uint8Array)
+        return value;
+    if (value instanceof ArrayBuffer)
+        return new Uint8Array(value);
+    if (ArrayBuffer.isView(value)) {
+        return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+    }
+    if (value instanceof Blob)
+        return new Uint8Array(await value.arrayBuffer());
+    // ReadableStream
+    return new Uint8Array(await new Response(value).arrayBuffer());
+}
+function bytesToStream(bytes) {
+    return new ReadableStream({
+        start(controller) {
+            controller.enqueue(bytes);
+            controller.close();
+        },
+    });
+}

package/dist/r2.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=r2.test.d.ts.map

package/dist/r2.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2.test.d.ts","sourceRoot":"","sources":["../src/r2.test.ts"],"names":[],"mappings":""}

package/dist/r2.test.js

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import { createR2BucketShim } from "./r2.js";
+function mockFetch(responder) {
+    const calls = [];
+    const fetch = async (input, init = {}) => {
+        const rec = {
+            url: String(input),
+            method: init.method ?? "GET",
+            headers: init.headers ?? {},
+            body: init.body,
+        };
+        calls.push(rec);
+        const { status = 200, body, headers } = responder(rec);
+        return new Response(body ?? null, { status, headers });
+    };
+    return { fetch, calls };
+}
+const base = {
+    endpoint: "https://acct.r2.cloudflarestorage.com",
+    bucket: "documents",
+    accessKeyId: "AKIA_TEST",
+    secretAccessKey: "secret",
+    region: "auto",
+};
+describe("createR2BucketShim", () => {
+    it("PUTs a signed, path-style object URL with content-type and custom metadata", async () => {
+        const { fetch, calls } = mockFetch(() => ({ status: 200 }));
+        const bucket = createR2BucketShim({ ...base, fetchImpl: fetch });
+        await bucket.put("invoices/2026/x.pdf", "PDFDATA", {
+            httpMetadata: { contentType: "application/pdf" },
+            customMetadata: { Owner: "acme" },
+        });
+        const call = calls[0];
+        expect(call.method).toBe("PUT");
+        expect(call.url).toBe("https://acct.r2.cloudflarestorage.com/documents/invoices/2026/x.pdf");
+        expect(call.headers.Authorization).toMatch(/^AWS4-HMAC-SHA256 Credential=AKIA_TEST\//);
+        expect(call.headers["x-amz-date"]).toMatch(/^\d{8}T\d{6}Z$/);
+        expect(call.headers["content-type"]).toBe("application/pdf");
+        expect(call.headers["x-amz-meta-owner"]).toBe("acme");
+    });
+    it("GETs an object exposing arrayBuffer, body, size, and httpMetadata", async () => {
+        const { fetch } = mockFetch(() => ({
+            body: "file-bytes",
+            headers: { "content-type": "text/plain", "x-amz-meta-tag": "v1" },
+        }));
+        const bucket = createR2BucketShim({ ...base, fetchImpl: fetch });
+        const obj = await bucket.get("a.txt");
+        expect(obj).not.toBeNull();
+        const bytes = new Uint8Array(await obj.arrayBuffer());
+        expect(new TextDecoder().decode(bytes)).toBe("file-bytes");
+        expect(obj.httpMetadata?.contentType).toBe("text/plain");
+        expect(obj.customMetadata?.tag).toBe("v1");
+        expect(obj.body).toBeInstanceOf(ReadableStream);
+    });
+    it("returns null when the object is missing (404)", async () => {
+        const { fetch } = mockFetch(() => ({ status: 404 }));
+        const bucket = createR2BucketShim({ ...base, fetchImpl: fetch });
+        expect(await bucket.get("missing")).toBeNull();
+    });
+    it("DELETEs and tolerates a 404", async () => {
+        const { fetch, calls } = mockFetch(() => ({ status: 404 }));
+        const bucket = createR2BucketShim({ ...base, fetchImpl: fetch });
+        await expect(bucket.delete("gone")).resolves.toBeUndefined();
+        expect(calls[0]?.method).toBe("DELETE");
+    });
+    it("supports array delete keys", async () => {
+        const { fetch, calls } = mockFetch(() => ({ status: 204 }));
+        const bucket = createR2BucketShim({ ...base, fetchImpl: fetch });
+        await bucket.delete(["a", "b"]);
+        expect(calls.map((c) => c.method)).toEqual(["DELETE", "DELETE"]);
+    });
+    it("HEAD returns metadata without a body", async () => {
+        const { fetch } = mockFetch(() => ({
+            headers: { "content-type": "image/png", "content-length": "1024" },
+        }));
+        const bucket = createR2BucketShim({ ...base, fetchImpl: fetch });
+        const meta = await bucket.head("img.png");
+        expect(meta?.httpMetadata?.contentType).toBe("image/png");
+        expect(meta?.size).toBe(1024);
+    });
+});

package/dist/ssr-manifest.d.ts

@@ -0,0 +1,51 @@
+/**
+ * SSR-manifest restriction for TanStack Start workers.
+ *
+ * By default the SSR stream emits preload/asset hints for every route in the
+ * manifest; on large admins that floods the first paint with hundreds of
+ * speculative preloads. Restricting the manifest to the matched routes keeps
+ * the initial response lean. Typed structurally so this package needs no
+ * dependency on the router — any router exposing `stores.matches` and an
+ * `ssr.manifest` fits.
+ */
+type ManifestRoute = {
+    assets?: Array<unknown>;
+    preloads?: Array<unknown>;
+};
+export type SsrManifest = {
+    inlineCss?: unknown;
+    routes: Record<string, ManifestRoute | undefined>;
+};
+export interface SsrManifestRouter {
+    stores: {
+        matches: {
+            get(): ReadonlyArray<{
+                routeId: string;
+            }>;
+        };
+    };
+    ssr?: {
+        readonly manifest?: SsrManifest;
+    };
+}
+/**
+ * Replace `router.ssr.manifest` with a view filtered to the active route
+ * matches. The filter runs lazily (getter) because matches settle after the
+ * handler installs the restriction.
+ */
+export declare function restrictSsrManifestToActiveRoutes(router: SsrManifestRouter): void;
+/**
+ * Wrap a TanStack Start stream-handler callback so every SSR render gets the
+ * active-route manifest restriction:
+ *
+ * ```ts
+ * const startHandler = createStartHandler(
+ *   withActiveRouteSsrManifest(defaultStreamHandler),
+ * )
+ * ```
+ */
+export declare function withActiveRouteSsrManifest<TCtx extends {
+    router: unknown;
+}, TResult>(handler: (ctx: TCtx) => TResult): (ctx: TCtx) => TResult;
+export {};
+//# sourceMappingURL=ssr-manifest.d.ts.map

package/dist/ssr-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssr-manifest.d.ts","sourceRoot":"","sources":["../src/ssr-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,KAAK,aAAa,GAAG;IACnB,MAAM,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IACvB,QAAQ,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,CAAC,CAAA;CAClD,CAAA;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE;QACN,OAAO,EAAE;YACP,GAAG,IAAI,aAAa,CAAC;gBAAE,OAAO,EAAE,MAAM,CAAA;aAAE,CAAC,CAAA;SAC1C,CAAA;KACF,CAAA;IACD,GAAG,CAAC,EAAE;QACJ,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAA;KAChC,CAAA;CACF;AAED;;;;GAIG;AACH,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAoBjF;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,SAAS;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,EAAE,OAAO,EAClF,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,OAAO,GAC9B,CAAC,GAAG,EAAE,IAAI,KAAK,OAAO,CAKxB"}

package/dist/ssr-manifest.js

@@ -0,0 +1,49 @@
+/**
+ * SSR-manifest restriction for TanStack Start workers.
+ *
+ * By default the SSR stream emits preload/asset hints for every route in the
+ * manifest; on large admins that floods the first paint with hundreds of
+ * speculative preloads. Restricting the manifest to the matched routes keeps
+ * the initial response lean. Typed structurally so this package needs no
+ * dependency on the router — any router exposing `stores.matches` and an
+ * `ssr.manifest` fits.
+ */
+/**
+ * Replace `router.ssr.manifest` with a view filtered to the active route
+ * matches. The filter runs lazily (getter) because matches settle after the
+ * handler installs the restriction.
+ */
+export function restrictSsrManifestToActiveRoutes(router) {
+    const ssr = router.ssr;
+    if (!ssr?.manifest)
+        return;
+    router.ssr = {
+        get manifest() {
+            const manifest = ssr.manifest;
+            if (!manifest)
+                return manifest;
+            const activeRouteIds = new Set(router.stores.matches.get().map((match) => match.routeId));
+            const routes = Object.fromEntries(Object.entries(manifest.routes).filter(([routeId]) => activeRouteIds.has(routeId)));
+            return {
+                ...manifest,
+                routes,
+            };
+        },
+    };
+}
+/**
+ * Wrap a TanStack Start stream-handler callback so every SSR render gets the
+ * active-route manifest restriction:
+ *
+ * ```ts
+ * const startHandler = createStartHandler(
+ *   withActiveRouteSsrManifest(defaultStreamHandler),
+ * )
+ * ```
+ */
+export function withActiveRouteSsrManifest(handler) {
+    return (ctx) => {
+        restrictSsrManifestToActiveRoutes(ctx.router);
+        return handler(ctx);
+    };
+}

package/dist/trust.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pinned cross-repo constant: the header the platform dispatcher stamps on
+ * every request it forwards to a dedicated (Cloud Run) app. The value is a
+ * per-app shared secret. Do NOT rename — the platform side depends on it.
+ */
+export declare const ORIGIN_TRUST_HEADER = "x-voyant-origin-trust";
+/**
+ * Constant-time string comparison. Returns `false` for length mismatches
+ * without leaking the comparison via early return timing (the length check is
+ * unavoidable and is itself not secret-length-dependent beyond equality).
+ */
+export declare function constantTimeEqual(a: string, b: string): boolean;
+/**
+ * Verify that a request carries a valid origin-trust header for `secret`.
+ */
+export declare function verifyOriginTrust(request: Request, secret: string): boolean;
+export interface OriginTrustOptions {
+    /**
+     * Paths that skip the trust check entirely (exact match). Defaults to
+     * `["/healthz"]` so container health probes never need the secret.
+     */
+    exemptPaths?: string[];
+}
+/**
+ * Build a low-level trust gate. Returns a function that, given a request,
+ * yields a `403` {@link Response} when the request must be rejected, or
+ * `undefined` when it may proceed. Composable — used by {@link createNodeServer}
+ * but exported so callers can wire it into their own server loop.
+ */
+export declare function originTrustMiddleware(secret: string, options?: OriginTrustOptions): (request: Request) => Response | undefined;
+//# sourceMappingURL=trust.d.ts.map

package/dist/trust.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust.d.ts","sourceRoot":"","sources":["../src/trust.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,0BAA0B,CAAA;AAE1D;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAU/D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAI3E;AAED,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,IAE5E,SAAS,OAAO,KAAG,QAAQ,GAAG,SAAS,CAMhD"}