@hyperframes/engine 0.6.118 → 0.6.120

package/src/utils/uint16-alignment-audit.test.ts

@@ -1,125 +0,0 @@
-/**
- * Audit test: Uint16Array vs Buffer.read/writeUInt16LE alignment.
- *
- * Captures the migration hazard documented in the HDR follow-up plan:
- * "Uint16Array over readUInt16LE / writeUInt16LE — ~105 touch points in the
- * hot path with an alignment-correctness concern (odd byteOffset on sliced
- * Buffers throws)."
- *
- * The hot path in `alphaBlit.ts` and `shaderTransitions.ts` reads/writes 16-bit
- * channels via `Buffer.readUInt16LE` / `Buffer.writeUInt16LE`. Those methods
- * accept arbitrary byte offsets — odd offsets are fine. A future perf PR may
- * migrate to `Uint16Array` views for ~2× throughput, but `Uint16Array` requires
- * 2-byte alignment of the underlying ArrayBuffer offset. If the source `Buffer`
- * was sliced from a parent at an odd byte offset, constructing a `Uint16Array`
- * view directly will throw `RangeError`.
- *
- * These tests pin down the contract so the migration PR can:
- *   1. Verify the migration is safe (current sub-buffers always start at even
- *      byte offsets) — see `rgb48le row stride` test.
- *   2. Provide a reference safe-wrap pattern when alignment is not guaranteed.
- */
-import { describe, expect, it } from "vitest";
-
-describe("Uint16 alignment audit", () => {
-  describe("Buffer.read/writeUInt16LE — current API", () => {
-    it("accepts odd byte offsets without throwing", () => {
-      const buf = Buffer.alloc(8);
-      buf.writeUInt16LE(0xabcd, 1);
-      expect(buf.readUInt16LE(1)).toBe(0xabcd);
-      buf.writeUInt16LE(0x1234, 3);
-      expect(buf.readUInt16LE(3)).toBe(0x1234);
-    });
-
-    it("preserves values across non-aligned slice round-trips", () => {
-      const buf = Buffer.alloc(10);
-      buf.writeUInt16LE(0xdead, 1);
-      buf.writeUInt16LE(0xbeef, 5);
-      const sub = buf.subarray(1);
-      expect(sub.readUInt16LE(0)).toBe(0xdead);
-      expect(sub.readUInt16LE(4)).toBe(0xbeef);
-    });
-  });
-
-  describe("Uint16Array — migration hazard", () => {
-    it("throws RangeError when byteOffset is odd", () => {
-      const ab = new ArrayBuffer(8);
-      expect(() => new Uint16Array(ab, 1, 2)).toThrow(RangeError);
-      expect(() => new Uint16Array(ab, 3, 1)).toThrow(RangeError);
-    });
-
-    it("succeeds when byteOffset is even", () => {
-      const ab = new ArrayBuffer(8);
-      expect(() => new Uint16Array(ab, 0, 4)).not.toThrow();
-      expect(() => new Uint16Array(ab, 2, 3)).not.toThrow();
-    });
-
-    it("a Buffer sliced at an odd offset cannot back a Uint16Array view directly", () => {
-      const parent = Buffer.alloc(8);
-      const odd = parent.subarray(1);
-      expect(odd.byteOffset % 2).toBe(1);
-      expect(
-        () => new Uint16Array(odd.buffer, odd.byteOffset, Math.floor(odd.byteLength / 2)),
-      ).toThrow(RangeError);
-    });
-
-    it("safe-wrap pattern: copy to a fresh aligned Buffer when offset is odd", () => {
-      const parent = Buffer.alloc(8);
-      parent.writeUInt16LE(0xfeed, 1);
-      const odd = parent.subarray(1, 3);
-
-      // Pattern the migration PR should use when alignment is not guaranteed:
-      // realign by copying into a freshly allocated Buffer (always page-aligned).
-      const aligned = odd.byteOffset % 2 === 0 ? odd : Buffer.from(odd);
-      expect(aligned.byteOffset % 2).toBe(0);
-      const view = new Uint16Array(
-        aligned.buffer,
-        aligned.byteOffset,
-        Math.floor(aligned.byteLength / 2),
-      );
-      expect(view[0]).toBe(0xfeed);
-    });
-  });
-
-  describe("HDR canvas/row alignment invariants", () => {
-    it("rgb48le canvas row strides are always even-byte multiples", () => {
-      // A row of an rgb48le canvas is `width * 6` bytes (3 channels × 2 bytes).
-      // For any width, the row stride is even, so per-row subarrays inherit
-      // even byte offsets when sliced from a Buffer whose byteOffset is also
-      // even (true for `Buffer.alloc(N)`, which is fresh-allocator-aligned).
-      for (const width of [1, 7, 33, 256, 1920]) {
-        const stride = width * 6;
-        expect(stride % 2).toBe(0);
-      }
-    });
-
-    it("Buffer.alloc canvases produce subarrays with even byte offsets", () => {
-      // This is the invariant the alphaBlit hot path relies on: as long as the
-      // working canvas is built with `Buffer.alloc(width * height * 6)`, each
-      // row subarray (`canvas.subarray(y * stride, (y + 1) * stride)`) starts
-      // at an even byte offset, so a future Uint16Array migration is safe
-      // without any realignment copy.
-      const width = 17; // odd width; stride = 102 (still even)
-      const height = 4;
-      const canvas = Buffer.alloc(width * height * 6);
-      const stride = width * 6;
-      for (let y = 0; y < height; y++) {
-        const row = canvas.subarray(y * stride, (y + 1) * stride);
-        expect(row.byteOffset % 2).toBe(0);
-      }
-    });
-
-    it("a 3-byte rgb24 stride would NOT be alignment-safe (counter-example)", () => {
-      // Documents why the rgb48le format is migration-friendly: an rgba8 or
-      // rgb24 canvas with odd width produces sub-buffers at odd byte offsets.
-      // If a future PR wants to use Uint16Array views, it must keep the data
-      // in an even-stride format (rgb48le ✓) or pay for a realignment copy.
-      const width = 3;
-      const height = 2;
-      const rgb24 = Buffer.alloc(width * height * 3); // stride = 9, odd!
-      const stride = width * 3;
-      const row1 = rgb24.subarray(stride, stride * 2);
-      expect(row1.byteOffset % 2).toBe(1);
-    });
-  });
-});

package/src/utils/urlDownloader.test.ts

@@ -1,65 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { assertPublicHttpsUrl } from "./urlDownloader.js";
-
-describe("assertPublicHttpsUrl — SSRF guard", () => {
-  it("accepts public HTTPS URLs", () => {
-    expect(() =>
-      assertPublicHttpsUrl("https://gen-os-static.s3.us-east-2.amazonaws.com/fonts/font.ttf"),
-    ).not.toThrow();
-    expect(() => assertPublicHttpsUrl("https://cdn.jsdelivr.net/npm/gsap.min.js")).not.toThrow();
-    expect(() => assertPublicHttpsUrl("https://fonts.gstatic.com/s/font.woff2")).not.toThrow();
-  });
-
-  it("rejects http:// (non-HTTPS)", () => {
-    expect(() => assertPublicHttpsUrl("http://example.com/font.ttf")).toThrow("Only HTTPS");
-  });
-
-  it("rejects AWS IMDS (169.254.169.254)", () => {
-    expect(() =>
-      assertPublicHttpsUrl("https://169.254.169.254/latest/meta-data/iam/security-credentials/"),
-    ).toThrow("private/reserved");
-    expect(() => assertPublicHttpsUrl("http://169.254.169.254/latest/user-data")).toThrow();
-  });
-
-  it("rejects loopback (127.x.x.x)", () => {
-    expect(() => assertPublicHttpsUrl("https://127.0.0.1/font.ttf")).toThrow("private/reserved");
-    expect(() => assertPublicHttpsUrl("https://127.1.2.3/secret")).toThrow("private/reserved");
-  });
-
-  it("rejects localhost", () => {
-    expect(() => assertPublicHttpsUrl("https://localhost/font.ttf")).toThrow("private/reserved");
-    expect(() => assertPublicHttpsUrl("http://localhost:3000/secret")).toThrow();
-  });
-
-  it("rejects RFC1918 — 10.x", () => {
-    expect(() => assertPublicHttpsUrl("https://10.0.0.1/secret")).toThrow("private/reserved");
-    expect(() => assertPublicHttpsUrl("https://10.255.255.255/secret")).toThrow("private/reserved");
-  });
-
-  it("rejects RFC1918 — 172.16–172.31", () => {
-    expect(() => assertPublicHttpsUrl("https://172.16.0.1/secret")).toThrow("private/reserved");
-    expect(() => assertPublicHttpsUrl("https://172.31.255.255/secret")).toThrow("private/reserved");
-  });
-
-  it("allows 172.0–172.15 and 172.32+ (not RFC1918)", () => {
-    expect(() => assertPublicHttpsUrl("https://172.15.0.1/font.ttf")).not.toThrow();
-    expect(() => assertPublicHttpsUrl("https://172.32.0.1/font.ttf")).not.toThrow();
-  });
-
-  it("rejects RFC1918 — 192.168.x", () => {
-    expect(() => assertPublicHttpsUrl("https://192.168.1.1/secret")).toThrow("private/reserved");
-  });
-
-  it("rejects unspecified address (0.x)", () => {
-    expect(() => assertPublicHttpsUrl("https://0.0.0.0/secret")).toThrow("private/reserved");
-  });
-
-  it("rejects loopback IPv6 ([::1])", () => {
-    expect(() => assertPublicHttpsUrl("https://[::1]/secret")).toThrow("private/reserved");
-  });
-
-  it("rejects invalid URLs", () => {
-    expect(() => assertPublicHttpsUrl("not-a-url")).toThrow("Invalid URL");
-    expect(() => assertPublicHttpsUrl("")).toThrow("Invalid URL");
-  });
-});

package/src/utils/urlDownloader.ts

@@ -1,143 +0,0 @@
-import { createWriteStream, existsSync, mkdirSync } from "fs";
-import { createHash } from "crypto";
-import { join, extname } from "path";
-import { Readable } from "stream";
-import { finished } from "stream/promises";
-
-const downloadPathCache = new Map<string, string>();
-const inFlightDownloads = new Map<string, Promise<string>>();
-
-// SSRF guard: these prefixes identify non-public address space that
-// compositions (customer-supplied) must never be able to reach via the
-// download path. Blocks AWS IMDS (169.254.169.254), loopback, RFC1918,
-// and unspecified addresses. All comparisons are on the raw hostname
-// string; DNS resolution is NOT performed here, so DNS-rebinding bypasses
-// are not closed by this check — that gap is acceptable for the risk level.
-const BLOCKED_HOST_PREFIXES = [
-  "169.254.", // link-local / AWS IMDS
-  "127.", // loopback IPv4
-  "10.", // RFC1918
-  "192.168.", // RFC1918
-  "0.", // unspecified
-  "[::1]", // loopback IPv6
-  "[fc", // RFC4193 unique-local IPv6
-  "[fd", // RFC4193 unique-local IPv6
-];
-// 172.16.0.0 – 172.31.255.255 (RFC1918)
-const BLOCKED_172_RANGE = { min: 16, max: 31 };
-
-function isBlockedHost(hostname: string): boolean {
-  const h = hostname.toLowerCase();
-  if (h === "localhost") return true;
-  if (BLOCKED_HOST_PREFIXES.some((p) => h.startsWith(p))) return true;
-  // 172.16–172.31
-  const m = h.match(/^172\.(\d{1,3})\./);
-  if (m) {
-    const octet = parseInt(m[1] ?? "0", 10);
-    if (octet >= BLOCKED_172_RANGE.min && octet <= BLOCKED_172_RANGE.max) return true;
-  }
-  return false;
-}
-
-/**
- * Validate that a URL is safe to fetch on behalf of customer-supplied
- * compositions. Throws if the URL is non-HTTPS or targets a private/reserved
- * address range (SSRF guard).
- */
-export function assertPublicHttpsUrl(url: string): void {
-  let parsed: URL;
-  try {
-    parsed = new URL(url);
-  } catch {
-    throw new Error(`[URLDownloader] Invalid URL: ${url}`);
-  }
-  if (parsed.protocol !== "https:") {
-    throw new Error(
-      `[URLDownloader] Only HTTPS URLs are permitted in compositions (got ${parsed.protocol}): ${url}`,
-    );
-  }
-  if (isBlockedHost(parsed.hostname)) {
-    throw new Error(
-      `[URLDownloader] URL targets a private/reserved address and is not permitted: ${url}`,
-    );
-  }
-}
-
-function getFilenameFromUrl(url: string): string {
-  const hash = createHash("md5").update(url).digest("hex").slice(0, 12);
-  const urlObj = new URL(url);
-  const ext = extname(urlObj.pathname) || ".mp4";
-  return `download_${hash}${ext}`;
-}
-
-export async function downloadToTemp(
-  url: string,
-  destDir: string,
-  timeoutMs: number = 300000,
-): Promise<string> {
-  // Reject non-HTTPS URLs and private/reserved address ranges before
-  // touching the cache or filesystem — customer-supplied compositions must
-  // not be able to trigger outbound fetches to internal infrastructure.
-  assertPublicHttpsUrl(url);
-
-  const cachedPath = downloadPathCache.get(url);
-  if (cachedPath && existsSync(cachedPath)) {
-    return cachedPath;
-  }
-  const inFlight = inFlightDownloads.get(url);
-  if (inFlight) {
-    return inFlight;
-  }
-
-  if (!existsSync(destDir)) {
-    mkdirSync(destDir, { recursive: true });
-  }
-
-  const filename = getFilenameFromUrl(url);
-  const localPath = join(destDir, filename);
-
-  if (existsSync(localPath)) {
-    downloadPathCache.set(url, localPath);
-    return localPath;
-  }
-
-  const downloadPromise = (async () => {
-    try {
-      const controller = new AbortController();
-      const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-
-      const response = await fetch(url, { signal: controller.signal });
-      clearTimeout(timeoutId);
-
-      if (!response.ok) {
-        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-      }
-
-      if (!response.body) {
-        throw new Error("Response body is empty");
-      }
-
-      const fileStream = createWriteStream(localPath);
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const readableStream = Readable.fromWeb(response.body as any);
-      await finished(readableStream.pipe(fileStream));
-
-      downloadPathCache.set(url, localPath);
-      return localPath;
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      if (message.includes("aborted")) {
-        throw new Error(`[URLDownloader] Download timeout after ${timeoutMs / 1000}s: ${url}`);
-      }
-      throw new Error(`[URLDownloader] Download failed: ${message}`);
-    } finally {
-      inFlightDownloads.delete(url);
-    }
-  })();
-  inFlightDownloads.set(url, downloadPromise);
-  return downloadPromise;
-}
-
-export function isHttpUrl(path: string): boolean {
-  return path.startsWith("http://") || path.startsWith("https://");
-}

package/tsconfig.json

@@ -1,19 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "esModuleInterop": true,
-    "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "skipLibCheck": true,
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-    "types": ["@webgpu/types"]
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "src/**/*.test.ts"]
-}

package/vitest.config.ts

@@ -1,7 +0,0 @@
-import { defineConfig } from "vitest/config";
-
-export default defineConfig({
-  test: {
-    include: ["src/**/*.test.ts"],
-  },
-});