@downdraft/engine 0.0.0 → 0.1.1

package/core/src/sab/types.ts

@@ -0,0 +1,158 @@
+export type FieldType = "f32" | "f64" | "i32" | "u32" | "bool";
+
+export type ChannelMode = "record" | "slots" | "grid";
+
+export interface FieldDef {
+  type: FieldType;
+  count?: number;
+  atomic?: boolean;
+}
+
+export type FieldMap = Record<string, FieldDef>;
+
+export interface HeaderDef {
+  size: number;
+  fields: FieldMap;
+}
+
+export interface SlotSectionDef {
+  name: string;
+  maxSlots: number;
+  slotSize: number;
+  fields: FieldMap;
+}
+
+export interface GridLayerDef {
+  type: FieldType;
+  components: number;
+}
+
+export interface GridDef {
+  size: number;
+  layers: Record<string, GridLayerDef>;
+}
+
+export interface ChannelDef {
+  name: string;
+  magic: number;
+  version: number;
+  mode: ChannelMode;
+  pollHz?: number;
+  header: HeaderDef;
+  fields?: FieldMap;
+  sections?: SlotSectionDef[];
+  grid?: GridDef;
+}
+
+export interface ManifestDef {
+  [channelName: string]: ChannelInstance;
+}
+
+export interface FieldLayout {
+  name: string;
+  type: FieldType;
+  count: number;
+  atomic: boolean;
+  byteOffset: number;
+  index: number;
+}
+
+export interface HeaderLayout {
+  size: number;
+  fields: Record<string, FieldLayout>;
+  magicIndex: number;
+  versionIndex: number;
+  sequenceIndex: number;
+}
+
+export interface SlotSectionLayout {
+  name: string;
+  maxSlots: number;
+  slotSize: number;
+  byteOffset: number;
+  slotStride: number;
+  fields: Record<string, FieldLayout>;
+}
+
+export interface GridLayerLayout {
+  name: string;
+  type: FieldType;
+  components: number;
+  byteOffset: number;
+  length: number;
+}
+
+export interface ChannelLayout {
+  byteLength: number;
+  mode: ChannelMode;
+  magic: number;
+  version: number;
+  header: HeaderLayout;
+  fields?: Record<string, FieldLayout>;
+  sections?: SlotSectionLayout[];
+  grid?: {
+    size: number;
+    layers: Record<string, GridLayerLayout>;
+  };
+}
+
+export interface SlotViews {
+  f32: Float32Array;
+  u32: Uint32Array;
+  i32: Int32Array;
+  f64: Float64Array;
+}
+
+export interface HeaderViews {
+  u32: Uint32Array;
+  i32: Int32Array;
+  f32: Float32Array;
+  f64: Float64Array;
+}
+
+export interface ChannelInstance {
+  def: ChannelDef;
+  layout: ChannelLayout;
+  byteLength: number;
+  offsets: Record<string, unknown>;
+  allocate(): SharedArrayBuffer;
+  reader(sab: SharedArrayBuffer): ChannelReader;
+  writer(sab: SharedArrayBuffer): ChannelWriter;
+}
+
+export interface ChannelReader {
+  isValid(): boolean;
+  /** Why the header is invalid, or null when valid. See describeHeaderValidation. */
+  validationError(): string | null;
+  getSequence(): number;
+  hasChanged(lastSeen: number): boolean;
+  header: HeaderViews;
+  sections?: Record<string, SlotAccessor>;
+  layers?: Record<string, Float32Array | Int32Array | Uint32Array | Float64Array>;
+  fields?: Record<string, Float32Array | Int32Array | Uint32Array | Float64Array>;
+  snapshot(): Record<string, unknown>;
+}
+
+export interface ChannelWriter {
+  init(): void;
+  bumpSequence(): void;
+  getSequence(): number;
+  header: HeaderViews;
+  sections?: Record<string, SlotAccessor>;
+  layers?: Record<string, Float32Array | Int32Array | Uint32Array | Float64Array>;
+  fields?: Record<string, Float32Array | Int32Array | Uint32Array | Float64Array>;
+}
+
+export interface SlotAccessor {
+  slot(index: number): SlotViews;
+  maxSlots: number;
+  slotSize: number;
+  slotStride: number;
+  byteOffset: number;
+}
+
+export interface ManifestInstance {
+  channels: Record<string, ChannelInstance>;
+  allocate(): Record<string, SharedArrayBuffer>;
+  attach(buffers: Record<string, SharedArrayBuffer>): Record<string, { reader: ChannelReader; writer: ChannelWriter }>;
+}

package/core/src/safety/bounds.ts

@@ -0,0 +1,76 @@
+/**
+ * Safety bounds for asset parser validation.
+ * These limits prevent decompression bombs, OOM, and integer overflow from
+ * malformed or malicious files.
+ */
+export const MAX_VERTEX_COUNT = 50_000_000;
+export const MAX_FACE_COUNT = 100_000_000;
+export const MAX_TEXTURE_DIM = 16384;
+export const MAX_MIP_LEVELS = 16;
+export const MAX_DECOMPRESS_SIZE = 512 * 1024 * 1024; // 512 MB
+export const MAX_FETCH_SIZE = 256 * 1024 * 1024; // 256 MB
+export const MAX_NODE_DEPTH = 64;
+export const MAX_ARRAY_LENGTH = 100_000_000;
+
+/**
+ * Asserts that `offset + length` does not exceed `max`.
+ * Throws a `RangeError` with a descriptive message if violated.
+ */
+export function assertBounds(name: string, offset: number, length: number, max: number): void {
+  if (offset < 0 || length < 0) {
+    throw new RangeError(`${name}: negative offset (${offset}) or length (${length})`);
+  }
+  if (offset + length > max) {
+    throw new RangeError(`${name}: offset ${offset} + length ${length} exceeds max ${max}`);
+  }
+}
+
+/**
+ * Asserts that `count` is a non-negative integer not exceeding `max`.
+ * Throws a `RangeError` if violated.
+ */
+export function assertCount(name: string, count: number, max: number): void {
+  if (!Number.isInteger(count) || count < 0) {
+    throw new RangeError(`${name}: count ${count} is not a non-negative integer`);
+  }
+  if (count > max) {
+    throw new RangeError(`${name}: count ${count} exceeds max ${max}`);
+  }
+}
+
+/**
+ * Asserts that `value` is a finite number (not NaN, not Infinity).
+ * Throws a `RangeError` if violated.
+ */
+export function assertFinite(name: string, value: number): void {
+  if (!Number.isFinite(value)) {
+    throw new RangeError(`${name}: value ${value} is not finite`);
+  }
+}
+
+/**
+ * Asserts that `value` is a positive finite number.
+ * Throws a `RangeError` if violated.
+ */
+export function assertPositive(name: string, value: number): void {
+  assertFinite(name, value);
+  if (value <= 0) {
+    throw new RangeError(`${name}: value ${value} is not positive`);
+  }
+}
+
+/**
+ * Clamps a value to `[min, max]`.
+ */
+export function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+/**
+ * Clamps a value to `[0, Number.MAX_SAFE_INTEGER]`.
+ * Useful for gold/currency/quantity values.
+ */
+export function clampSafeInt(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.max(0, Math.min(value, Number.MAX_SAFE_INTEGER));
+}

package/core/src/safety/json.ts

@@ -0,0 +1,80 @@
+/**
+ * Keys that are blocked to prevent prototype pollution.
+ */
+const BLOCKED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+/**
+ * Recursively sanitizes a parsed JSON object:
+ * - Resets any prototype that was set via `__proto__` pollution
+ * - Removes own properties named `__proto__`, `constructor`, `prototype`
+ * - Recurses into nested objects and arrays
+ */
+function deepSanitize<T>(obj: T): T {
+  if (typeof obj !== "object" || obj === null) return obj;
+
+  if (Array.isArray(obj)) {
+    const arr = obj as unknown[];
+    for (let i = 0; i < arr.length; i++) {
+      arr[i] = deepSanitize(arr[i]);
+    }
+    return obj;
+  }
+
+  // Reset prototype in case __proto__ pollution occurred during JSON.parse
+  const proto = Object.getPrototypeOf(obj);
+  if (proto !== null && proto !== Object.prototype) {
+    Object.setPrototypeOf(obj, Object.prototype);
+  }
+
+  const record = obj as Record<string, unknown>;
+
+  // Check for own properties named with blocked keys (including non-enumerable)
+  for (const key of Object.getOwnPropertyNames(record)) {
+    if (BLOCKED_KEYS.has(key)) {
+      delete record[key];
+    }
+  }
+
+  // Recurse into remaining enumerable keys
+  for (const key of Object.keys(record)) {
+    record[key] = deepSanitize(record[key]);
+  }
+
+  return obj;
+}
+
+/**
+ * Parses JSON safely, preventing prototype pollution (`__proto__`,
+ * `constructor`, `prototype` keys are stripped).
+ *
+ * Throws on invalid JSON (same as `JSON.parse`).
+ */
+export function safeJsonParse<T>(text: string): T {
+  const parsed = JSON.parse(text);
+  return deepSanitize(parsed) as T;
+}
+
+/**
+ * Parses JSON safely and validates the result with a type guard.
+ * Returns `null` if parsing fails or validation rejects the result.
+ */
+export function safeJsonParseWithSchema<T>(
+  text: string,
+  validate: (obj: unknown) => obj is T,
+): T | null {
+  try {
+    const parsed = safeJsonParse<unknown>(text);
+    if (validate(parsed)) return parsed;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Recursively removes prototype-polluting keys from an already-parsed object.
+ * Useful for sanitizing objects received from untrusted sources.
+ */
+export function sanitizeObject<T>(obj: T): T {
+  return deepSanitize(obj);
+}

package/core/src/safety/path.ts

@@ -0,0 +1,167 @@
+/**
+ * Path validation utilities — browser-safe (no `node:path` dependency).
+ *
+ * These functions work with POSIX-style paths (`/` separator) which is
+ * sufficient for URI validation and path traversal prevention in both
+ * browser and Node.js contexts.
+ */
+
+/** Returns true if the path starts with `/` (POSIX absolute) or a Windows drive letter. */
+function isAbsolutePath(p: string): boolean {
+  if (p.startsWith("/")) return true;
+  // Windows drive: C:\ or C:/
+  return /^[A-Za-z]:[\\/]/.test(p);
+}
+
+/**
+ * Normalizes a path by resolving `.` and `..` segments.
+ * Does NOT resolve symlinks or check filesystem existence.
+ * Works on POSIX-style paths (forward slashes).
+ */
+function normalizePath(p: string): string {
+  const isAbs = isAbsolutePath(p);
+  const parts = p.replace(/\\/g, "/").split("/");
+  const result: string[] = [];
+
+  for (let _i = 0, _it = parts, _n = _it.length; _i < _n; _i++) { const part = _it[_i];
+    if (part === "" || part === ".") continue;
+    if (part === "..") {
+      if (result.length > 0 && result[result.length - 1] !== "..") {
+        result.pop();
+      } else if (!isAbs) {
+        result.push("..");
+      }
+      // For absolute paths, .. at root stays at root (pop nothing)
+    } else {
+      result.push(part);
+    }
+  }
+
+  let normalized = result.join("/");
+  if (isAbs) normalized = "/" + normalized;
+  return normalized || (isAbs ? "/" : ".");
+}
+
+/**
+ * Joins `base` and `target` into a single normalized path.
+ * If `target` is absolute, `base` is ignored.
+ */
+function joinPath(base: string, target: string): string {
+  if (isAbsolutePath(target)) return normalizePath(target);
+  const sep = base.endsWith("/") ? "" : "/";
+  return normalizePath(base + sep + target);
+}
+
+/**
+ * Computes the relative path from `from` to `to`.
+ * If `to` is not under `from`, the result starts with `..`.
+ */
+function relativePath(from: string, to: string): string {
+  const fromNorm = normalizePath(from);
+  const toNorm = normalizePath(to);
+  const fromParts = fromNorm.split("/").filter(Boolean);
+  const toParts = toNorm.split("/").filter(Boolean);
+
+  // Find common prefix
+  let commonLen = 0;
+  while (
+    commonLen < fromParts.length &&
+    commonLen < toParts.length &&
+    fromParts[commonLen] === toParts[commonLen]
+  ) {
+    commonLen++;
+  }
+
+  const upCount = fromParts.length - commonLen;
+  const downParts = toParts.slice(commonLen);
+
+  const result = [
+    ...Array(upCount).fill(".."),
+    ...downParts,
+  ];
+
+  if (result.length === 0) return ".";
+  return result.join("/");
+}
+
+/**
+ * Resolves `targetPath` relative to `baseDir` and ensures the result does not
+ * escape `baseDir` via `..` segments or absolute paths.
+ *
+ * Throws if the resolved path would be outside `baseDir`.
+ * Returns the resolved absolute path on success.
+ */
+export function confinePath(baseDir: string, targetPath: string): string {
+  const base = normalizePath(baseDir);
+  let target: string;
+  if (isAbsolutePath(targetPath)) {
+    target = normalizePath(targetPath);
+  } else {
+    target = joinPath(base, targetPath);
+  }
+
+  const rel = relativePath(base, target);
+  // If the relative path starts with `..` or is an absolute path (different drive on Windows),
+  // the target escapes the base directory.
+  if (rel.startsWith("..") || isAbsolutePath(rel)) {
+    throw new Error(
+      `Path "${targetPath}" escapes base directory "${baseDir}"`,
+    );
+  }
+  return target;
+}
+
+/**
+ * Boolean variant of {@link confinePath}. Returns `true` if `targetPath` is
+ * confined within `baseDir`, `false` otherwise.
+ */
+export function isPathSafe(baseDir: string, targetPath: string): boolean {
+  try {
+    confinePath(baseDir, targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validates a URI string (e.g. from glTF texture references). Only allows:
+ * - Relative paths without `..` segments
+ * - `data:` URIs
+ *
+ * Rejects: absolute paths, `file://`, `..` traversal, `http://`/`https://` to
+ * arbitrary hosts (unless `allowRemote` is true).
+ */
+export function sanitizeUri(
+  uri: string,
+  opts: { allowRemote?: boolean; baseDir?: string } = {},
+): string {
+  if (uri.startsWith("data:")) return uri;
+
+  if (uri.startsWith("file://")) {
+    throw new Error(`file:// URIs are not allowed: "${uri}"`);
+  }
+
+  if (uri.startsWith("http://") || uri.startsWith("https://")) {
+    if (!opts.allowRemote) {
+      throw new Error(`Remote URIs are not allowed: "${uri}"`);
+    }
+    return uri;
+  }
+
+  // Relative path — reject `..` segments
+  if (uri.includes("..")) {
+    throw new Error(`Path traversal detected in URI: "${uri}"`);
+  }
+
+  if (isAbsolutePath(uri)) {
+    throw new Error(`Absolute paths are not allowed: "${uri}"`);
+  }
+
+  // If baseDir provided, verify confinement
+  if (opts.baseDir) {
+    return confinePath(opts.baseDir, uri);
+  }
+
+  return uri;
+}

package/core/src/save/binary-format.ts

@@ -0,0 +1,117 @@
+// ============================================================================
+// Binary Save Format — uncompressed header + zstd-compressed body
+// ============================================================================
+//
+// Header layout (46 bytes, little-endian):
+//   Offset  Size  Field
+//   0       4     Magic: 0xDD5A0001
+//   4       2     Format version (header structure version)
+//   6       4     Engine version hash (packed semver: major<<22 | minor<<12 | patch)
+//   10      8     Timestamp (f64, Unix epoch seconds)
+//   18      4     Entity count
+//   22      4     Player count
+//   26      16    XXH128 hash of uncompressed body
+//   42      4     Uncompressed body length
+//   46      ...   Zstd-compressed body (JSON)
+
+export const SAVE_MAGIC = 0xdd5a0001;
+export const SAVE_FORMAT_VERSION = 1;
+export const HEADER_SIZE = 46;
+export const XXH128_SIZE = 16;
+
+// --- Engine version packing ---
+
+export function packEngineVersion(major: number, minor: number, patch: number): number {
+  return ((major & 0x3ff) << 22) | ((minor & 0x3ff) << 12) | (patch & 0xfff);
+}
+
+export function unpackEngineVersion(packed: number): { major: number; minor: number; patch: number } {
+  return {
+    major: (packed >>> 22) & 0x3ff,
+    minor: (packed >>> 12) & 0x3ff,
+    patch: packed & 0xfff,
+  };
+}
+
+export function engineVersionString(packed: number): string {
+  const v = unpackEngineVersion(packed);
+  return `${v.major}.${v.minor}.${v.patch}`;
+}
+
+// --- Header encode/decode ---
+
+export interface SaveHeader {
+  magic: number;
+  formatVersion: number;
+  engineVersionPacked: number;
+  timestamp: number;
+  entityCount: number;
+  playerCount: number;
+  bodyHash: Uint8Array; // 16 bytes
+  uncompressedBodyLength: number;
+}
+
+export function encodeHeader(header: SaveHeader): ArrayBuffer {
+  const buf = new ArrayBuffer(HEADER_SIZE);
+  const view = new DataView(buf);
+  const u8 = new Uint8Array(buf);
+
+  view.setUint32(0, header.magic, true);
+  view.setUint16(4, header.formatVersion, true);
+  view.setUint32(6, header.engineVersionPacked, true);
+  view.setFloat64(10, header.timestamp, true);
+  view.setUint32(18, header.entityCount, true);
+  view.setUint32(22, header.playerCount, true);
+
+  // XXH128 hash (16 bytes at offset 26)
+  u8.set(header.bodyHash.subarray(0, XXH128_SIZE), 26);
+
+  view.setUint32(42, header.uncompressedBodyLength, true);
+
+  return buf;
+}
+
+export function decodeHeader(buf: ArrayBuffer): SaveHeader | null {
+  if (buf.byteLength < HEADER_SIZE) return null;
+
+  const view = new DataView(buf);
+  const magic = view.getUint32(0, true);
+  if (magic !== SAVE_MAGIC) return null;
+
+  const formatVersion = view.getUint16(4, true);
+  if (formatVersion !== SAVE_FORMAT_VERSION) return null;
+
+  if (6 + 4 > buf.byteLength) return null;
+  const engineVersionPacked = view.getUint32(6, true);
+  if (10 + 8 > buf.byteLength) return null;
+  const timestamp = view.getFloat64(10, true);
+  if (18 + 4 > buf.byteLength) return null;
+  const entityCount = view.getUint32(18, true);
+  if (22 + 4 > buf.byteLength) return null;
+  const playerCount = view.getUint32(22, true);
+
+  const u8 = new Uint8Array(buf);
+  if (26 + XXH128_SIZE > buf.byteLength) return null;
+  const bodyHash = u8.slice(26, 26 + XXH128_SIZE);
+
+  if (42 + 4 > buf.byteLength) return null;
+  const uncompressedBodyLength = view.getUint32(42, true);
+
+  return {
+    magic,
+    formatVersion,
+    engineVersionPacked,
+    timestamp,
+    entityCount,
+    playerCount,
+    bodyHash,
+    uncompressedBodyLength,
+  };
+}
+
+// --- Read header only from a file buffer (for listSaves without decompression) ---
+
+export function readHeaderFromFile(fileBuffer: ArrayBuffer): SaveHeader | null {
+  if (fileBuffer.byteLength < HEADER_SIZE) return null;
+  return decodeHeader(fileBuffer.slice(0, HEADER_SIZE));
+}