attention-manifest-protocol 0.4.2 → 0.4.4

package/lib/file/zip.d.ts

@@ -0,0 +1,35 @@
+/**
+ * One central-directory entry.
+ *
+ * `offset` is the local file header offset in the archive, not the payload
+ * offset; `compressedSize` and `uncompressedSize` are the central-directory
+ * values, which are authoritative even when a data descriptor follows the
+ * payload.
+ */
+export interface ZipEntry {
+    readonly name: string;
+    readonly compressedSize: number;
+    readonly uncompressedSize: number;
+    readonly method: number;
+    readonly offset: number;
+}
+/**
+ * Read every ZIP entry into an in-memory map.
+ *
+ * The archive is never extracted to disk. Names are validated before the map is
+ * built, so a caller cannot receive a key that would be unsafe to join against
+ * a path. Duplicate names are rejected because the map would otherwise silently
+ * let the last entry win, which is a classic archive-confusion bug.
+ *
+ * @param bytes - Archive bytes.
+ * @returns Entry name to expanded bytes.
+ */
+export declare const readZipEntries: (bytes: Uint8Array) => Map<string, Uint8Array>;
+/**
+ * Decode a UTF-8 text part and remove a leading byte-order mark.
+ *
+ * @param entries - Entry map from `readZipEntries`.
+ * @param name - Part name, for example `word/document.xml`.
+ * @returns Decoded text, or `undefined` when the part is absent.
+ */
+export declare const zipText: (entries: ReadonlyMap<string, Uint8Array>, name: string) => string | undefined;

package/lib/file/zip.js

@@ -0,0 +1,349 @@
+/**
+ * Bounded, read-only ZIP container reader.
+ *
+ * Office Open XML documents are ZIP archives. Parsing them does not require a
+ * general-purpose unzip implementation, but it does require the same resource
+ * discipline as the rest of the filesystem domain: every offset is checked
+ * against the buffer, every chain is bounded, unsupported features are rejected
+ * instead of guessed, and expansion is capped per entry and in aggregate.
+ *
+ * The reader deliberately implements only what OOXML packages use:
+ *
+ * - the end-of-central-directory record (EOCD), including the archive comment;
+ * - the central directory and its local file headers;
+ * - method `0` (stored) and method `8` (deflate, through `node:zlib`);
+ * - entry names as UTF-8 (or Latin-1 when the UTF-8 flag is absent).
+ *
+ * Encrypted entries, ZIP64 archives, multi-disk archives and out-of-bounds
+ * offsets are rejected with the closed `parse_failed` / `quota_exceeded` error
+ * codes. Central-directory CRCs are not verified because Office readers rely on
+ * the XML parser and the per-entry size checks instead; a caller that needs CRC
+ * verification should do it on the extracted bytes.
+ *
+ * Expansion limits are 64 MiB for one entry and 256 MiB in total. Both are
+ * enforced against the declared size *and* the actual inflate output so a lying
+ * header cannot exhaust memory.
+ */
+import { inflateRawSync } from "node:zlib";
+import { fail } from "./errors.js";
+const EocdSignature = 0x06054b50;
+const CentralSignature = 0x02014b50;
+const LocalSignature = 0x04034b50;
+const EocdLength = 22;
+const CentralLength = 46;
+const LocalLength = 30;
+const MaxCommentLength = 0xffff;
+const MaxEntries = 16384;
+const MaxCentralBytes = 64 * 1024 * 1024;
+const MaxEntryBytes = 64 * 1024 * 1024;
+const MaxTotalBytes = 256 * 1024 * 1024;
+const Zip64ExtraId = 0x0001;
+const Utf8Flag = 0x0800;
+const EncryptedFlag = 0x0001;
+const StrongEncryptionFlag = 0x0040;
+const MaskedHeaderFlag = 0x2000;
+const Zip64Sentinel16 = 0xffff;
+const Zip64Sentinel32 = 0xffffffff;
+/**
+ * Create a little-endian view over the exact bytes the caller supplied.
+ * A Node `Buffer` is a `Uint8Array` with its own `byteOffset`, so the view must
+ * not assume that the backing array starts at zero.
+ *
+ * @param bytes - Archive bytes.
+ * @returns A view sharing the caller's memory.
+ */
+const viewOf = (bytes) => new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+const uint16 = (view, offset) => view.getUint16(offset, true);
+const uint32 = (view, offset) => view.getUint32(offset, true);
+/**
+ * Decode an entry name. The UTF-8 flag is optional for ASCII-only archives,
+ * where Latin-1 and UTF-8 agree; a genuinely non-ASCII name without the flag is
+ * decoded as Latin-1 rather than rejected, matching common ZIP writers.
+ *
+ * @param bytes - Archive bytes.
+ * @param offset - Name start.
+ * @param length - Name byte length.
+ * @param utf8 - Whether the UTF-8 name flag was set.
+ * @returns Decoded name.
+ */
+const decodeName = (bytes, offset, length, utf8) => {
+    const slice = bytes.subarray(offset, offset + length);
+    if (utf8) {
+        try {
+            return new TextDecoder("utf-8", { fatal: true }).decode(slice);
+        }
+        catch {
+            return fail("parse_failed");
+        }
+    }
+    let name = "";
+    for (let index = 0; index < slice.length; index += 1) {
+        name += String.fromCharCode(slice[index]);
+    }
+    return name;
+};
+/**
+ * Reject an entry name that could escape the conceptual archive root.
+ *
+ * The returned map is keyed by the entry name, not extracted to disk, so this
+ * is defence in depth rather than the only barrier: an OOXML parser that joins
+ * a relationship target with a part name must never see `..` in a part name.
+ * Absolute names, backslashes, drive letters and NUL/control characters are
+ * rejected for the same reason.
+ *
+ * @param name - Decoded entry name.
+ * @returns The same name when safe.
+ */
+const assertSafeName = (name) => {
+    if (name.length === 0 || name.length > 4096) {
+        return fail("parse_failed");
+    }
+    if (name.startsWith("/") || name.startsWith("\\") || name.startsWith("//") || /^[A-Za-z]:/.test(name)) {
+        return fail("parse_failed");
+    }
+    if (name.includes("\\")) {
+        return fail("parse_failed");
+    }
+    for (let index = 0; index < name.length; index += 1) {
+        const code = name.charCodeAt(index);
+        if (code < 0x20 || code === 0x7f) {
+            return fail("parse_failed");
+        }
+    }
+    const segments = name.split("/");
+    for (let index = 0; index < segments.length; index += 1) {
+        if (segments[index] === "..") {
+            return fail("parse_failed");
+        }
+    }
+    return name;
+};
+/**
+ * Scan a ZIP extra field for the ZIP64 marker. The sizes in the central
+ * directory are then usually `0xffffffff`, but the extra field alone is enough
+ * to reject the archive: silently reading a ZIP64 entry as 4 GiB is worse than
+ * a clear failure.
+ *
+ * @param bytes - Archive bytes.
+ * @param offset - Extra field start.
+ * @param length - Extra field byte length.
+ * @returns Nothing; throws when a ZIP64 field is present.
+ */
+const rejectZip64Extra = (bytes, offset, length) => {
+    const end = offset + length;
+    let cursor = offset;
+    while (cursor + 4 <= end) {
+        const id = bytes[cursor] | (bytes[cursor + 1] << 8);
+        const size = bytes[cursor + 2] | (bytes[cursor + 3] << 8);
+        if (id === Zip64ExtraId) {
+            return fail("parse_failed");
+        }
+        cursor += 4 + size;
+    }
+};
+/**
+ * Parse the EOCD and return its byte offset. The comment length is validated so
+ * a `PK\x05\x06` byte sequence inside a comment is not mistaken for the record.
+ *
+ * @param view - Archive view.
+ * @param length - Archive byte length.
+ * @returns EOCD offset.
+ */
+const findEocd = (view, length) => {
+    if (length < EocdLength) {
+        return fail("parse_failed");
+    }
+    const first = Math.max(0, length - EocdLength - MaxCommentLength);
+    for (let offset = length - EocdLength; offset >= first; offset -= 1) {
+        if (uint32(view, offset) !== EocdSignature) {
+            continue;
+        }
+        const commentLength = uint16(view, offset + 20);
+        if (offset + EocdLength + commentLength === length) {
+            return offset;
+        }
+    }
+    return fail("parse_failed");
+};
+/**
+ * Read and expand one entry from its local file header.
+ *
+ * The local header is re-read rather than trusted from the central directory so
+ * a payload offset is always derived from bytes this reader has validated. The
+ * local name must match the central name; a mismatch means the archive is
+ * malformed or deliberately ambiguous.
+ *
+ * @param view - Archive view.
+ * @param bytes - Archive bytes.
+ * @param entry - Parsed central-directory entry.
+ * @param offset - Local header offset.
+ * @param utf8 - Whether the central name used UTF-8.
+ * @param remaining - Bytes still allowed by the aggregate expansion limit.
+ * @returns Expanded entry bytes.
+ */
+const readPayload = (view, bytes, entry, offset, utf8, remaining) => {
+    if (offset < 0 || offset + LocalLength > bytes.byteLength) {
+        return fail("parse_failed");
+    }
+    if (uint32(view, offset) !== LocalSignature) {
+        return fail("parse_failed");
+    }
+    const localFlags = uint16(view, offset + 6);
+    if ((localFlags & EncryptedFlag) !== 0 || (localFlags & StrongEncryptionFlag) !== 0 || (localFlags & MaskedHeaderFlag) !== 0) {
+        return fail("parse_failed");
+    }
+    const localMethod = uint16(view, offset + 8);
+    if (localMethod !== entry.method) {
+        return fail("parse_failed");
+    }
+    const localNameLength = uint16(view, offset + 26);
+    const localExtraLength = uint16(view, offset + 28);
+    const nameStart = offset + LocalLength;
+    const nameEnd = nameStart + localNameLength;
+    if (nameEnd > bytes.byteLength) {
+        return fail("parse_failed");
+    }
+    const localName = decodeName(bytes, nameStart, localNameLength, utf8);
+    if (localName !== entry.name) {
+        return fail("parse_failed");
+    }
+    rejectZip64Extra(bytes, nameEnd, localExtraLength);
+    const payloadStart = nameEnd + localExtraLength;
+    const payloadEnd = payloadStart + entry.compressedSize;
+    if (payloadStart < 0 || payloadEnd > bytes.byteLength) {
+        return fail("parse_failed");
+    }
+    if (entry.method === 0) {
+        if (entry.compressedSize !== entry.uncompressedSize) {
+            return fail("parse_failed");
+        }
+        return bytes.slice(payloadStart, payloadEnd);
+    }
+    const allowance = Math.min(MaxEntryBytes, remaining);
+    if (allowance <= 0 || entry.uncompressedSize > allowance) {
+        return fail("quota_exceeded");
+    }
+    let output;
+    try {
+        output = inflateRawSync(bytes.subarray(payloadStart, payloadEnd), { maxOutputLength: allowance });
+    }
+    catch {
+        return fail("parse_failed");
+    }
+    if (output.byteLength !== entry.uncompressedSize) {
+        return fail("parse_failed");
+    }
+    return output;
+};
+/**
+ * Read every ZIP entry into an in-memory map.
+ *
+ * The archive is never extracted to disk. Names are validated before the map is
+ * built, so a caller cannot receive a key that would be unsafe to join against
+ * a path. Duplicate names are rejected because the map would otherwise silently
+ * let the last entry win, which is a classic archive-confusion bug.
+ *
+ * @param bytes - Archive bytes.
+ * @returns Entry name to expanded bytes.
+ */
+export const readZipEntries = (bytes) => {
+    const view = viewOf(bytes);
+    const eocd = findEocd(view, bytes.byteLength);
+    const diskNumber = uint16(view, eocd + 4);
+    const centralDisk = uint16(view, eocd + 6);
+    const entriesOnDisk = uint16(view, eocd + 8);
+    const entryCount = uint16(view, eocd + 10);
+    const centralSize = uint32(view, eocd + 12);
+    const centralOffset = uint32(view, eocd + 16);
+    if (diskNumber !== 0 || centralDisk !== 0 || entriesOnDisk !== entryCount) {
+        return fail("parse_failed");
+    }
+    if (entryCount === Zip64Sentinel16 || centralSize === Zip64Sentinel32 || centralOffset === Zip64Sentinel32) {
+        return fail("parse_failed");
+    }
+    if (entryCount > MaxEntries) {
+        return fail("quota_exceeded");
+    }
+    if (centralSize > MaxCentralBytes) {
+        return fail("quota_exceeded");
+    }
+    if (centralOffset < 0 || centralOffset + centralSize > eocd) {
+        return fail("parse_failed");
+    }
+    const centralEnd = centralOffset + centralSize;
+    const entries = new Map();
+    let cursor = centralOffset;
+    let expanded = 0;
+    for (let index = 0; index < entryCount; index += 1) {
+        if (cursor < 0 || cursor + CentralLength > centralEnd) {
+            return fail("parse_failed");
+        }
+        if (uint32(view, cursor) !== CentralSignature) {
+            return fail("parse_failed");
+        }
+        const flags = uint16(view, cursor + 8);
+        const method = uint16(view, cursor + 10);
+        const compressedSize = uint32(view, cursor + 20);
+        const uncompressedSize = uint32(view, cursor + 24);
+        const nameLength = uint16(view, cursor + 28);
+        const extraLength = uint16(view, cursor + 30);
+        const commentLength = uint16(view, cursor + 32);
+        const diskStart = uint16(view, cursor + 34);
+        const localOffset = uint32(view, cursor + 42);
+        if ((flags & EncryptedFlag) !== 0 || (flags & StrongEncryptionFlag) !== 0 || (flags & MaskedHeaderFlag) !== 0) {
+            return fail("parse_failed");
+        }
+        if (method !== 0 && method !== 8) {
+            return fail("parse_failed");
+        }
+        if (compressedSize === Zip64Sentinel32 || uncompressedSize === Zip64Sentinel32 || localOffset === Zip64Sentinel32 || diskStart === Zip64Sentinel16) {
+            return fail("parse_failed");
+        }
+        if (diskStart !== 0) {
+            return fail("parse_failed");
+        }
+        if (uncompressedSize > MaxEntryBytes || expanded + uncompressedSize > MaxTotalBytes) {
+            return fail("quota_exceeded");
+        }
+        const nameStart = cursor + CentralLength;
+        const nameEnd = nameStart + nameLength;
+        const extraStart = nameEnd;
+        const extraEnd = extraStart + extraLength;
+        const next = extraEnd + commentLength;
+        if (nameLength === 0 || nameEnd > centralEnd || extraEnd > centralEnd || next > centralEnd) {
+            return fail("parse_failed");
+        }
+        rejectZip64Extra(bytes, extraStart, extraLength);
+        const name = assertSafeName(decodeName(bytes, nameStart, nameLength, (flags & Utf8Flag) !== 0));
+        if (entries.has(name)) {
+            return fail("parse_failed");
+        }
+        const entry = { name, compressedSize, uncompressedSize, method, offset: localOffset };
+        const payload = readPayload(view, bytes, entry, localOffset, (flags & Utf8Flag) !== 0, MaxTotalBytes - expanded);
+        expanded += payload.byteLength;
+        if (expanded > MaxTotalBytes || payload.byteLength !== uncompressedSize) {
+            return fail("quota_exceeded");
+        }
+        entries.set(name, payload);
+        cursor = next;
+    }
+    return entries;
+};
+/**
+ * Decode a UTF-8 text part and remove a leading byte-order mark.
+ *
+ * @param entries - Entry map from `readZipEntries`.
+ * @param name - Part name, for example `word/document.xml`.
+ * @returns Decoded text, or `undefined` when the part is absent.
+ */
+export const zipText = (entries, name) => {
+    const bytes = entries.get(name);
+    if (bytes === (void 0)) {
+        return undefined;
+    }
+    let start = 0;
+    if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
+        start = 3;
+    }
+    return new TextDecoder("utf-8").decode(bytes.subarray(start));
+};

package/lib/fingerprint/algorithm.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Frozen algorithm identifiers. Adding one is a wire-format change: it must ship
+ * with known-answer vectors and a cross-check against `node:crypto`.
+ */
+export type AlgorithmId = "sha256" | "sha512" | "sha3-256" | "blake2b-512";
+/**
+ * Registry row. `digestBytes` is needed even for algorithms without a backend
+ * because `parseShort`/`parseRef` must reject a hex string of the wrong length
+ * for the algorithm it claims to be.
+ */
+export interface AlgorithmSpec {
+    readonly id: AlgorithmId;
+    readonly digestBytes: number;
+    readonly backend: "portable" | "unavailable";
+}
+/**
+ * Declaration order is the canonical listing order; nothing in the module
+ * depends on iteration order, but diagnostics and future catalogues do.
+ */
+export declare const AlgorithmIds: readonly AlgorithmId[];
+/**
+ * True for a value that is one of the four registered identifiers. Used by the
+ * parsers, which must reject an unknown algorithm instead of guessing.
+ */
+export declare const isAlgorithmId: (value: string) => value is AlgorithmId;
+/**
+ * Look up a registered algorithm. A value that is syntactically fine but not
+ * registered is an `UnsupportedAlgorithm`, because at this point a hasher is
+ * required and there is nothing safe to substitute.
+ */
+export declare const algorithmSpec: (algorithm: AlgorithmId) => AlgorithmSpec;
+/**
+ * Expected lowercase-hex length of a digest for this algorithm. Both parsers
+ * use it so "wrong length" and "wrong algorithm" cannot be confused.
+ */
+export declare const digestHexLength: (algorithm: AlgorithmId) => number;
+/**
+ * Lowercase hex encoding. Lowercase is required by the OCI digest grammar and
+ * by every existing `sha256:` reference in this repository; emitting uppercase
+ * would create a second spelling of the same digest.
+ */
+export declare const bytesToHex: (bytes: Uint8Array) => string;
+/**
+ * Decode a hex digest back to bytes. Used by the tree leaf serialisation, which
+ * has to embed a child digest as 32 raw bytes.
+ */
+export declare const hexToBytes: (hex: string) => Uint8Array;
+/**
+ * Strict lowercase-hex check. Uppercase is rejected rather than folded, because
+ * `sha256:AB...` and `sha256:ab...` are different strings and a parser that
+ * accepts both silently creates two names for one digest.
+ */
+export declare const isLowerHex: (text: string, length: number) => boolean;
+/**
+ * A streaming digest sink.
+ *
+ * `update` accepts arbitrary chunk boundaries and buffers a partial block
+ * internally, so a file can be read in 1 MiB slices without the caller tracking
+ * alignment. `digest` finalises the hash and is single-shot: a second call would
+ * need a second padding pass over state that is already mutated, so it throws
+ * instead of returning a silently wrong value.
+ */
+export interface ByteHasher {
+    update(bytes: Uint8Array): ByteHasher;
+    digest(): Uint8Array;
+}
+/**
+ * Portable incremental SHA-256 over raw bytes.
+ *
+ * The implementation tracks the total byte count separately from the buffered
+ * block because the FIPS padding needs the input length in bits; computing the
+ * final eight bytes from `totalBytes` (high = bits >> 32, low = low 32 bits)
+ * avoids the overflow a 32-bit byte counter would hit at 512 MiB.
+ */
+export declare const createSha256: () => ByteHasher;
+/**
+ * One-shot SHA-256 over raw bytes. Thin wrapper so call sites do not repeat the
+ * create/update/digest sequence and cannot forget the update.
+ */
+export declare const sha256Bytes: (bytes: Uint8Array) => Uint8Array;
+/**
+ * Fail closed unless this build can actually compute the named algorithm.
+ *
+ * The registry must answer before any payload is touched: a caller that gets a
+ * hasher is entitled to assume the algorithm in the reference is the algorithm
+ * that ran. The same guard is called by the file layer before it opens a file,
+ * so an unsupported algorithm fails without a pointless read instead of after
+ * the work has already been done.
+ */
+export declare const assertBackend: (algorithm: AlgorithmId) => AlgorithmSpec;
+/**
+ * Construct a hasher for any registered algorithm, or fail closed.
+ *
+ * Kept as a thin wrapper over `assertBackend` so the availability rule lives in
+ * exactly one place.
+ */
+export declare const createHasher: (algorithm: AlgorithmId) => ByteHasher;