@springbrand/eval-harness 0.1.0-alpha.1 → 0.1.0-alpha.2

package/dist/utils/src/ooxml.js

@@ -0,0 +1,170 @@
+import { SaxesParser } from "saxes";
+import { inspectStrictZip, STRICT_ZIP_OOXML_LIMITS, } from "./strict-zip.js";
+export class OoxmlPackageError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "OoxmlPackageError";
+    }
+}
+const REQUIRED_PARTS = {
+    docx: ["[Content_Types].xml", "_rels/.rels", "word/document.xml"],
+    xlsx: [
+        "[Content_Types].xml",
+        "_rels/.rels",
+        "xl/workbook.xml",
+        "xl/_rels/workbook.xml.rels",
+    ],
+    pptx: [
+        "[Content_Types].xml",
+        "_rels/.rels",
+        "ppt/presentation.xml",
+        "ppt/_rels/presentation.xml.rels",
+    ],
+};
+const UNSAFE_METADATA = /(?:macroenabled|vbaproject|activex|oleobject)/iu;
+const XML_DECODER = new TextDecoder("utf-8", { fatal: true, ignoreBOM: false });
+export async function inspectSafeOoxml(bytes, kind, options = {}) {
+    options.signal?.throwIfAborted();
+    const absoluteTargets = new Set();
+    const result = await inspectStrictZip(bytes, STRICT_ZIP_OOXML_LIMITS, undefined, {
+        onEntry: async (entry) => {
+            options.signal?.throwIfAborted();
+            validateOoxmlPart(entry, absoluteTargets, options.allowExternalHyperlinks === true);
+            await options.onPart?.(entry);
+            options.signal?.throwIfAborted();
+        },
+    });
+    options.signal?.throwIfAborted();
+    const paths = new Set(result.entries.filter((entry) => !entry.directory).map((entry) => entry.path));
+    for (const target of absoluteTargets) {
+        if (!paths.has(target)) {
+            throw new OoxmlPackageError(`Absolute relationship target ${target} is not a package part`, "unsafe-content");
+        }
+    }
+    for (const path of REQUIRED_PARTS[kind]) {
+        if (!paths.has(path))
+            throw new OoxmlPackageError(`Missing required ${kind.toUpperCase()} part ${path}`, "missing-part");
+    }
+    return result;
+}
+function validateOoxmlPart({ path, bytes }, absoluteTargets, allowExternalHyperlinks) {
+    const folded = path.toLocaleLowerCase("en-US");
+    const segments = folded.split("/");
+    if (folded.includes("vbaproject") ||
+        segments.some((segment) => segment.startsWith("activex")) ||
+        segments.some((segment) => /^(?:encryptioninfo|encryptedpackage|dataspaces)(?:\.|$)/u.test(segment)) ||
+        (segments.includes("embeddings") && segments.some((segment) => segment.includes("oleobject") || segment.endsWith(".bin")))) {
+        throw new OoxmlPackageError(`Unsafe OOXML part ${path}`, "unsafe-content");
+    }
+    if (!/\.(?:xml|rels)$/iu.test(path))
+        return;
+    const parser = new SaxesParser({ xmlns: true, fragment: false });
+    parser.on("doctype", () => {
+        throw new OoxmlPackageError(`${path} contains a DOCTYPE`, "unsafe-content");
+    });
+    parser.on("processinginstruction", () => {
+        throw new OoxmlPackageError(`${path} contains a processing instruction`, "unsafe-content");
+    });
+    parser.on("opentag", (tag) => {
+        if (/\.rels$/iu.test(path)) {
+            assertSafeRelationship(tag, path, absoluteTargets, allowExternalHyperlinks);
+        }
+        if (path === "[Content_Types].xml") {
+            const contentType = attributeValue(tag, "contenttype");
+            if (contentType && UNSAFE_METADATA.test(contentType)) {
+                throw new OoxmlPackageError(`${path} contains unsafe metadata`, "unsafe-content");
+            }
+        }
+    });
+    try {
+        parser.write(XML_DECODER.decode(bytes)).close();
+    }
+    catch (error) {
+        if (error instanceof OoxmlPackageError)
+            throw error;
+        throw new OoxmlPackageError(`${path} contains invalid or unsafe XML`, "unsafe-content");
+    }
+}
+function assertSafeRelationship(tag, path, absoluteTargets, allowExternalHyperlinks) {
+    if (tag.local.toLocaleLowerCase("en-US") !== "relationship")
+        return;
+    const target = attributeValue(tag, "target");
+    const resolved = target === undefined ? undefined : resolveOoxmlRelationshipPart(sourcePartForRelationships(path), target);
+    const relationshipType = attributeValue(tag, "type") ?? "";
+    const targetMode = attributeValue(tag, "targetmode")?.toLocaleLowerCase("en-US");
+    if (targetMode === "external" && allowExternalHyperlinks && isSafeExternalHyperlink(relationshipType, target)) {
+        return;
+    }
+    if (targetMode === "external" ||
+        (target !== undefined && resolved === null)) {
+        throw new OoxmlPackageError(`${path} contains an unsafe relationship target`, "unsafe-content");
+    }
+    if (target?.startsWith("/") && resolved)
+        absoluteTargets.add(resolved);
+    if (UNSAFE_METADATA.test(relationshipType)) {
+        throw new OoxmlPackageError(`${path} contains an unsafe relationship type`, "unsafe-content");
+    }
+}
+function isSafeExternalHyperlink(type, target) {
+    return /\/hyperlink$/iu.test(type) && safeOoxmlExternalHyperlinkUrl(target) !== null;
+}
+export function safeOoxmlExternalHyperlinkUrl(target) {
+    if (!target)
+        return null;
+    try {
+        const url = new URL(target);
+        return (url.protocol === "http:" || url.protocol === "https:") && !url.username && !url.password
+            ? url.href
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveOoxmlRelationshipPart(sourcePart, target) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(target);
+    }
+    catch {
+        return null;
+    }
+    const path = decoded.split(/[?#]/u, 1)[0] ?? "";
+    if (!path || path.startsWith("//") || decoded.includes("\\") ||
+        (decoded.startsWith("/") && !target.startsWith("/")) ||
+        /[\u0000-\u001f\u007f]/u.test(decoded) ||
+        /^[A-Za-z][A-Za-z\d+.-]*:/u.test(decoded) ||
+        /%(?:2e|2f|5c|3a)/iu.test(target) ||
+        /%(?:2e|2f|5c|3a)/iu.test(decoded))
+        return null;
+    const absolute = path.startsWith("/");
+    const segments = (absolute ? path.slice(1) : path).split("/");
+    if (segments.some((segment) => !segment) || (absolute && segments.includes("..")))
+        return null;
+    const normalized = absolute ? [] : sourcePart.split("/").slice(0, -1);
+    for (const segment of segments) {
+        if (segment === ".")
+            continue;
+        if (segment === "..") {
+            if (normalized.length === 0)
+                return null;
+            normalized.pop();
+        }
+        else {
+            normalized.push(segment);
+        }
+    }
+    const resolved = normalized.join("/");
+    return resolved || null;
+}
+function sourcePartForRelationships(path) {
+    if (path === "_rels/.rels")
+        return "";
+    const separator = path.lastIndexOf("/_rels/");
+    return separator < 0 ? "" : `${path.slice(0, separator)}/${path.slice(separator + 7, -5)}`;
+}
+function attributeValue(tag, name) {
+    return Object.values(tag.attributes).find((attribute) => attribute.local.toLocaleLowerCase("en-US") === name)?.value;
+}

package/dist/utils/src/serialized-size.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The byte cost of a value once it is JSON.
+ *
+ * Every budget that bounds what a model may receive is stated in bytes, and a
+ * string's `length` is UTF-16 code units — so measuring with `length` silently
+ * under-counts any non-ASCII payload, which is exactly the payload most likely
+ * to be near a limit.
+ */
+export declare function serializedSize(value: unknown): number;

package/dist/utils/src/serialized-size.js

@@ -0,0 +1,11 @@
+/**
+ * The byte cost of a value once it is JSON.
+ *
+ * Every budget that bounds what a model may receive is stated in bytes, and a
+ * string's `length` is UTF-16 code units — so measuring with `length` silently
+ * under-counts any non-ASCII payload, which is exactly the payload most likely
+ * to be near a limit.
+ */
+export function serializedSize(value) {
+    return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+}

package/dist/utils/src/strict-zip.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Strict-ZIP structural safety limits. Every field is required so each caller
+ * states its own budget explicitly; pass `Infinity` for a check the caller does
+ * not want the shared inspector to enforce.
+ */
+export type StrictZipLimits = {
+    /** Maximum number of entries in the archive. */
+    entries: number;
+    /** Maximum uncompressed size of a single entry. */
+    maxEntryBytes: number;
+    /** Maximum aggregate uncompressed size across all entries. */
+    maxExpandedBytes: number;
+    /** Maximum compression ratio (uncompressed / compressed) for a non-empty entry. */
+    maxCompressionRatio: number;
+    /** Maximum filename length in characters. */
+    pathCharacters: number;
+};
+/**
+ * Default limits for OOXML packages (DOCX/XLSX/PPTX). These match the bounds the
+ * existing Attachment XLSX validator enforced and the Creation admission matrix
+ * requires.
+ */
+export declare const STRICT_ZIP_OOXML_LIMITS: StrictZipLimits;
+export type StrictZipErrorCode = "not-zip" | "invalid-archive" | "too-many-entries" | "path-too-long" | "unsafe-path" | "duplicate-path" | "case-collision" | "non-regular" | "encrypted" | "unsupported-compression" | "invalid-size" | "entry-too-large" | "aggregate-too-large" | "compression-ratio" | "invalid-entry" | "size-mismatch";
+export declare class StrictZipError extends Error {
+    readonly code: StrictZipErrorCode;
+    readonly path?: string | undefined;
+    constructor(message: string, code: StrictZipErrorCode, path?: string | undefined);
+}
+/** One inspected archive entry with its safe logical path and optional expanded bytes. */
+export type StrictZipEntry = {
+    path: string;
+    bytes?: Uint8Array;
+    directory: boolean;
+};
+/** Bounded package facts returned to a caller for further policy validation. */
+export type StrictZipResult = {
+    /** All entries sorted by path. Directory entries carry an empty byte array. */
+    entries: StrictZipEntry[];
+    compressedBytes: number;
+    expandedBytes: number;
+};
+/** Optional per-path ceiling, so a caller can state its own budget for a known path. */
+export type StrictZipEntryLimit = (path: string) => {
+    maxBytes: number;
+    message: string;
+} | undefined;
+export type StrictZipInspectOptions = {
+    /** Consume one validated file while its expanded bytes are live. */
+    onEntry?: (entry: Required<StrictZipEntry>) => void | Promise<void>;
+    /** Retain every expanded file in the returned result. Defaults to false. */
+    retainBytes?: boolean;
+    signal?: AbortSignal;
+};
+export declare function hasZipSignature(bytes: Uint8Array): boolean;
+/**
+ * Inspects an untrusted ZIP archive and returns bounded package facts. Every
+ * structural bound that protects a caller from a hostile archive — path shape,
+ * entry count, regular-file type, encryption, compression method, per-entry and
+ * aggregate expansion, compression ratio, overlapping entries, invalid CRCs,
+ * duplicate and case-colliding paths — is enforced here so no consumer needs to
+ * copy archive safety logic.
+ *
+ * Callers that inspect content should use `onEntry`, which releases each
+ * expanded file before the next is read. Only callers that need a complete
+ * in-memory archive should opt into `retainBytes`.
+ */
+export declare function inspectStrictZip(untrustedBytes: Uint8Array, limits: StrictZipLimits, entryLimit?: StrictZipEntryLimit, options?: StrictZipInspectOptions): Promise<StrictZipResult>;

package/dist/utils/src/strict-zip.js

@@ -0,0 +1,177 @@
+const MiB = 1024 * 1024;
+/**
+ * Default limits for OOXML packages (DOCX/XLSX/PPTX). These match the bounds the
+ * existing Attachment XLSX validator enforced and the Creation admission matrix
+ * requires.
+ */
+export const STRICT_ZIP_OOXML_LIMITS = {
+    entries: 2_048,
+    maxEntryBytes: 64 * MiB,
+    maxExpandedBytes: 200 * MiB,
+    maxCompressionRatio: 1_000,
+    pathCharacters: 768,
+};
+export class StrictZipError extends Error {
+    code;
+    path;
+    constructor(message, code, path) {
+        super(path ? `${path}: ${message}` : message);
+        this.code = code;
+        this.path = path;
+        this.name = "StrictZipError";
+    }
+}
+function strictZipFail(message, code, path) {
+    throw new StrictZipError(message, code, path);
+}
+export function hasZipSignature(bytes) {
+    return (bytes.length >= 4 &&
+        bytes[0] === 0x50 &&
+        bytes[1] === 0x4b &&
+        ((bytes[2] === 0x03 && bytes[3] === 0x04) ||
+            (bytes[2] === 0x05 && bytes[3] === 0x06) ||
+            (bytes[2] === 0x07 && bytes[3] === 0x08)));
+}
+function logicalPath(entry, pathCharacters) {
+    const raw = entry.filename;
+    if (raw.length > pathCharacters) {
+        strictZipFail(`Path exceeds ${pathCharacters} characters`, "path-too-long", raw);
+    }
+    if (!raw || raw.includes("\\") || raw.includes("\0") || raw.startsWith("/") || /^[A-Za-z]:/u.test(raw)) {
+        strictZipFail("Unsafe archive path", "unsafe-path", raw || "<empty path>");
+    }
+    const path = entry.directory && raw.endsWith("/") ? raw.slice(0, -1) : raw;
+    if (!path || path.split("/").some((segment) => !segment || segment === "." || segment === "..")) {
+        strictZipFail("Unsafe archive path", "unsafe-path", raw);
+    }
+    return path;
+}
+function assertRegularFile(entry, path, limits) {
+    const unixType = entry.unixMode === undefined ? 0 : entry.unixMode & 0o170000;
+    if (unixType !== 0 && unixType !== 0o100000) {
+        strictZipFail("Archive entry must be a regular file", "non-regular", path);
+    }
+    if (entry.encrypted)
+        strictZipFail("Encrypted archive entries are not supported", "encrypted", path);
+    if (entry.compressionMethod !== 0 && entry.compressionMethod !== 8) {
+        strictZipFail(`Unsupported ZIP compression method ${entry.compressionMethod}`, "unsupported-compression", path);
+    }
+    if (!Number.isSafeInteger(entry.compressedSize) ||
+        !Number.isSafeInteger(entry.uncompressedSize) ||
+        entry.compressedSize < 0 ||
+        entry.uncompressedSize < 0) {
+        strictZipFail("Invalid declared size", "invalid-size", path);
+    }
+    if (entry.uncompressedSize > limits.maxEntryBytes) {
+        strictZipFail(`Entry exceeds ${limits.maxEntryBytes} bytes`, "entry-too-large", path);
+    }
+    if (entry.uncompressedSize > 0 &&
+        entry.compressedSize > 0 &&
+        entry.uncompressedSize / entry.compressedSize > limits.maxCompressionRatio) {
+        strictZipFail("Compression ratio exceeds the allowed ceiling", "compression-ratio", path);
+    }
+}
+/**
+ * Inspects an untrusted ZIP archive and returns bounded package facts. Every
+ * structural bound that protects a caller from a hostile archive — path shape,
+ * entry count, regular-file type, encryption, compression method, per-entry and
+ * aggregate expansion, compression ratio, overlapping entries, invalid CRCs,
+ * duplicate and case-colliding paths — is enforced here so no consumer needs to
+ * copy archive safety logic.
+ *
+ * Callers that inspect content should use `onEntry`, which releases each
+ * expanded file before the next is read. Only callers that need a complete
+ * in-memory archive should opt into `retainBytes`.
+ */
+export async function inspectStrictZip(untrustedBytes, limits, entryLimit, options = {}) {
+    options.signal?.throwIfAborted();
+    if (!hasZipSignature(untrustedBytes))
+        strictZipFail("Body is not a ZIP archive", "not-zip");
+    const { Uint8ArrayReader, Uint8ArrayWriter, ZipReader } = await import("@zip.js/zip.js");
+    const reader = new ZipReader(new Uint8ArrayReader(untrustedBytes), {
+        strictness: "strict",
+        useWebWorkers: false,
+    });
+    try {
+        let entries;
+        try {
+            entries = await reader.getEntries({ strictness: "strict" });
+        }
+        catch (error) {
+            options.signal?.throwIfAborted();
+            strictZipFail(error instanceof Error ? `Invalid ZIP archive: ${error.message}` : "Invalid ZIP archive", "invalid-archive");
+        }
+        options.signal?.throwIfAborted();
+        if (entries.length > limits.entries) {
+            strictZipFail(`ZIP contains more than ${limits.entries} entries`, "too-many-entries");
+        }
+        const seen = new Set();
+        const seenCaseFolded = new Set();
+        const paths = new Map();
+        const directories = [];
+        let totalSize = 0;
+        for (const entry of entries) {
+            options.signal?.throwIfAborted();
+            const path = logicalPath(entry, limits.pathCharacters);
+            const folded = path.toLocaleLowerCase("en-US");
+            if (seen.has(path))
+                strictZipFail("Duplicate normalized archive path", "duplicate-path", path);
+            if (seenCaseFolded.has(folded))
+                strictZipFail("Case-insensitive archive path collision", "case-collision", path);
+            seen.add(path);
+            seenCaseFolded.add(folded);
+            paths.set(entry, path);
+            if (entry.directory) {
+                directories.push(path);
+                continue;
+            }
+            assertRegularFile(entry, path, limits);
+            totalSize += entry.uncompressedSize;
+            if (totalSize > limits.maxExpandedBytes) {
+                strictZipFail(`Total uncompressed size exceeds ${limits.maxExpandedBytes} bytes`, "aggregate-too-large");
+            }
+            const limit = entryLimit?.(path);
+            if (limit && entry.uncompressedSize > limit.maxBytes)
+                strictZipFail(limit.message, "entry-too-large", path);
+        }
+        const fileEntries = entries
+            .filter((entry) => !entry.directory)
+            .sort((left, right) => paths.get(left).localeCompare(paths.get(right)));
+        const result = [];
+        for (const entry of fileEntries) {
+            options.signal?.throwIfAborted();
+            const path = paths.get(entry);
+            let bytes;
+            try {
+                bytes = await entry.getData(new Uint8ArrayWriter(), {
+                    checkSignature: true,
+                    checkOverlappingEntry: true,
+                    strictness: "strict",
+                    ...(options.signal ? { signal: options.signal } : {}),
+                });
+            }
+            catch (error) {
+                options.signal?.throwIfAborted();
+                strictZipFail(error instanceof Error ? `Invalid ZIP entry: ${error.message}` : "Invalid ZIP entry", "invalid-entry", path);
+            }
+            options.signal?.throwIfAborted();
+            if (bytes.byteLength !== entry.uncompressedSize)
+                strictZipFail("Declared and actual sizes differ", "size-mismatch", path);
+            await options.onEntry?.({ path, bytes, directory: false });
+            options.signal?.throwIfAborted();
+            result.push({ path, ...(options.retainBytes ? { bytes } : {}), directory: false });
+        }
+        for (const directory of directories.sort((left, right) => left.localeCompare(right))) {
+            options.signal?.throwIfAborted();
+            result.push({ path: directory, bytes: new Uint8Array(), directory: true });
+        }
+        return {
+            entries: result,
+            compressedBytes: untrustedBytes.byteLength,
+            expandedBytes: totalSize,
+        };
+    }
+    finally {
+        await reader.close();
+    }
+}

package/dist/utils/src/uuid.d.ts

@@ -0,0 +1,9 @@
+/**
+ * UUID pattern without anchors, for embedding in larger patterns such as route
+ * matchers. Matches the RFC 4122 shape produced by `crypto.randomUUID()`.
+ */
+export declare const UUID_PATTERN = "[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}";
+/** Generates the opaque UUID used by newly persisted application entities. */
+export declare function createId(): string;
+export declare function isUuid(value: unknown): value is string;
+export declare function deterministicUuid(value: string): Promise<string>;

package/dist/utils/src/uuid.js

@@ -0,0 +1,27 @@
+import { sha256Hex } from "./content-hash.js";
+/**
+ * UUID pattern without anchors, for embedding in larger patterns such as route
+ * matchers. Matches the RFC 4122 shape produced by `crypto.randomUUID()`.
+ */
+export const UUID_PATTERN = "[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}";
+const UUID_RE = new RegExp(`^${UUID_PATTERN}$`);
+/** Generates the opaque UUID used by newly persisted application entities. */
+export function createId() {
+    if (typeof crypto.randomUUID === "function")
+        return crypto.randomUUID();
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+export function isUuid(value) {
+    return typeof value === "string" && UUID_RE.test(value);
+}
+export async function deterministicUuid(value) {
+    const chars = (await sha256Hex(value)).slice(0, 32).split("");
+    chars[12] = "5";
+    chars[16] = ((Number.parseInt(chars[16], 16) & 0x3) | 0x8).toString(16);
+    const hex = chars.join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@springbrand/eval-harness",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "type": "module",
   "license": "UNLICENSED",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "types": "./dist/eval-harness/src/index.d.ts",
+      "import": "./dist/eval-harness/src/index.js"
     }
   },
   "files": [
@@ -15,6 +15,9 @@
   ],
   "sideEffects": false,
   "dependencies": {
+    "@zip.js/zip.js": "^2.8.34",
+    "ipaddr.js": "2.5.0",
+    "saxes": "^6.0.0",
     "zod": "^4.6.5"
   },
   "publishConfig": {