attention-manifest-protocol 0.4.2 → 0.4.4

package/lib/fingerprint/text.js

@@ -0,0 +1,155 @@
+/**
+ * Strict UTF-8 plus the `text` and `string` policies.
+ *
+ * `TextEncoder` replaces an unpaired surrogate with U+FFFD, so `"\uD800"` and
+ * `"\uFFFD"` would hash identically 鈥?the exact collision this module exists to
+ * prevent (the design audit measured it). `encodeUtf8Strict` therefore validates
+ * surrogate pairing before it writes a byte and is the only string-to-bytes
+ * path in the module; `json.ts`, `file.ts` and `tree.ts` all use it for that
+ * reason.
+ *
+ * The two policies answer two different questions and both are needed:
+ *
+ * - `text/utf8+nfc+lf` removes presentation differences that carry no content
+ *   (one leading BOM, CRLF versus LF) and applies NFC, so `"茅"` and `"e\u0301"`
+ *   are one value. NFC and not NFKC: compatibility decomposition is lossy
+ *   (`铿乣 becomes `fi`), which would make distinct texts collide on purpose.
+ * - `string/utf16-strict` preserves the code units exactly. Sometimes the byte
+ *   identity is what the caller wants to pin, and a generic `fingerprintOf`
+ *   dispatcher must not silently normalise what it was given.
+ */
+import { NormalizationRejected } from "./error.js";
+import { Policy } from "./policy.js";
+import { fingerprintPayload } from "./preimage.js";
+const HexRadix = 16;
+const SurrogateHighStart = 0xd800;
+const SurrogateHighEnd = 0xdbff;
+const SurrogateLowStart = 0xdc00;
+const SurrogateLowEnd = 0xdfff;
+const SurrogateBase = 0x10000;
+const hex4 = (value) => value.toString(HexRadix).toUpperCase().padStart(4, "0");
+/**
+ * Compute the UTF-8 length of `text` while rejecting any unpaired surrogate.
+ *
+ * The validation and the measurement happen in one pass because both walk the
+ * same code units: a separate validator would double the scans and could drift
+ * out of sync with the encoder. The returned length lets the encoder allocate
+ * once, so no intermediate array of code points is materialised.
+ */
+const utf8ByteLength = (text) => {
+    let length = 0;
+    for (let index = 0; index < text.length; index += 1) {
+        const unit = text.charCodeAt(index);
+        if (unit < 0x80) {
+            length += 1;
+            continue;
+        }
+        if (unit < 0x800) {
+            length += 2;
+            continue;
+        }
+        if (unit >= SurrogateHighStart && unit <= SurrogateHighEnd) {
+            const next = index + 1 < text.length ? text.charCodeAt(index + 1) : -1;
+            if (next < SurrogateLowStart || next > SurrogateLowEnd) {
+                throw new NormalizationRejected([`text contains a lone high surrogate U+${hex4(unit)} at index ${index}`]);
+            }
+            length += 4;
+            index += 1;
+            continue;
+        }
+        if (unit >= SurrogateLowStart && unit <= SurrogateLowEnd) {
+            throw new NormalizationRejected([`text contains a lone low surrogate U+${hex4(unit)} at index ${index}`]);
+        }
+        length += 3;
+    }
+    return length;
+};
+/**
+ * Encode a JavaScript string as UTF-8 without ever substituting U+FFFD.
+ *
+ * Two passes: the first measures and validates, the second writes. A paired
+ * surrogate is written as one four-byte sequence and the loop skips its low
+ * half, so the output is standard UTF-8 (the CESU-8 spelling of a pair would be
+ * six bytes and would collide with different text).
+ */
+export const encodeUtf8Strict = (text) => {
+    if (typeof (text) !== "string") {
+        throw new TypeError(`encodeUtf8Strict expects a string, received ${typeof (text)}`);
+    }
+    const bytes = new Uint8Array(utf8ByteLength(text));
+    let offset = 0;
+    for (let index = 0; index < text.length; index += 1) {
+        const unit = text.charCodeAt(index);
+        if (unit < 0x80) {
+            bytes[offset] = unit;
+            offset += 1;
+            continue;
+        }
+        if (unit < 0x800) {
+            bytes[offset] = 0xc0 | (unit >> 6);
+            bytes[offset + 1] = 0x80 | (unit & 0x3f);
+            offset += 2;
+            continue;
+        }
+        if (unit >= SurrogateHighStart && unit <= SurrogateHighEnd) {
+            const next = text.charCodeAt(index + 1);
+            const codePoint = SurrogateBase + ((unit - SurrogateHighStart) << 10) + (next - SurrogateLowStart);
+            bytes[offset] = 0xf0 | (codePoint >> 18);
+            bytes[offset + 1] = 0x80 | ((codePoint >> 12) & 0x3f);
+            bytes[offset + 2] = 0x80 | ((codePoint >> 6) & 0x3f);
+            bytes[offset + 3] = 0x80 | (codePoint & 0x3f);
+            offset += 4;
+            index += 1;
+            continue;
+        }
+        bytes[offset] = 0xe0 | (unit >> 12);
+        bytes[offset + 1] = 0x80 | ((unit >> 6) & 0x3f);
+        bytes[offset + 2] = 0x80 | (unit & 0x3f);
+        offset += 3;
+    }
+    return bytes;
+};
+/**
+ * Apply the `text/utf8+nfc+lf` normalisation, in the order the policy name
+ * implies: exactly one leading BOM is dropped (interior BOMs are content), CRLF
+ * and lone CR become LF, then NFC is applied.
+ *
+ * NUL is rejected rather than hashed: a NUL inside text truncates every C
+ * consumer of the string, so two texts that are equal only up to a NUL would be
+ * treated as identical downstream while this module would say they differ.
+ * Rejecting keeps the two views aligned.
+ */
+export const normalizeTextNfc = (text) => {
+    const withoutBom = text.startsWith("\uFEFF") ? text.slice(1) : text;
+    const lfOnly = withoutBom.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    const normalized = lfOnly.normalize("NFC");
+    const nulIndex = normalized.indexOf("\u0000");
+    if (nulIndex !== -1) {
+        throw new NormalizationRejected([`text contains U+0000 at index ${nulIndex}; the text policy forbids NUL`]);
+    }
+    return normalized;
+};
+/**
+ * Fingerprint text under the NFC policy (default) or the raw policy.
+ *
+ * `raw` still uses the strict encoder: "no normalisation" means no BOM, newline
+ * or Unicode folding, not "let the platform substitute replacement characters".
+ */
+export const fingerprintText = (text, options) => {
+    const policy = options?.policy ?? "nfc";
+    if (policy === "nfc") {
+        const payload = encodeUtf8Strict(normalizeTextNfc(text));
+        return fingerprintPayload("sha256", "text", Policy.textNfc, payload);
+    }
+    if (policy === "raw") {
+        return fingerprintPayload("sha256", "text", Policy.textRaw, encodeUtf8Strict(text));
+    }
+    throw new NormalizationRejected([`unknown text policy "${policy}"; expected "nfc" or "raw"`]);
+};
+/**
+ * Fingerprint the exact code units of a string: no BOM stripping, no newline
+ * folding, no NFC. `"茅"` (U+00E9) and `"e\u0301"` (e + U+0301) are different
+ * strings and therefore different fingerprints, which is the point of having a
+ * `string` kind next to `text`.
+ */
+export const fingerprintString = (text) => fingerprintPayload("sha256", "string", Policy.stringStrict, encodeUtf8Strict(text));

package/lib/fingerprint/tree.d.ts

@@ -0,0 +1,56 @@
+import type { AlgorithmId } from "./algorithm.js";
+import type { Fingerprint } from "./preimage.js";
+/**
+ * One entry of the tree.
+ *
+ * `digest` is the *child* digest that goes into the leaf record: the file
+ * content digest for a regular file, `sha256(utf8(target))` for a symlink, and
+ * `sha256(empty)` for a directory. Keeping the child digest (rather than the
+ * leaf digest) means a consumer can compare a file against a CAS object while
+ * still being able to rebuild the leaf —and therefore the root —from the
+ * returned entries.
+ */
+export interface TreeEntry {
+    readonly path: string;
+    readonly digest: string;
+    readonly size: number;
+    readonly mode: number;
+}
+/**
+ * A tree fingerprint plus its root and per-entry detail.
+ *
+ * `root` is the canonical tree root in bare lowercase hex; `ref.digest` is the
+ * same hex and `digest` is its CAS-compatible `<algorithm>:<hex>` spelling.
+ * `bytes` in the reference is the total length of the canonical leaf records
+ * that were folded, not the sum of the file sizes: it measures the serialised
+ * payload the Merkle tree was built from.
+ */
+export interface TreeFingerprint extends Fingerprint {
+    readonly root: string;
+    readonly entries: readonly TreeEntry[];
+    readonly excluded: readonly string[];
+}
+/**
+ * Option shape for `fingerprintTree`.
+ *
+ * `exclude` replaces the default exclusion set rather than extending it; there
+ * would otherwise be no way to fingerprint a directory that contains a
+ * `node_modules` folder on purpose. The applied set is echoed in `excluded` so
+ * a verifier can see what was in scope.
+ */
+export interface TreeFingerprintOptions {
+    readonly exclude?: readonly string[];
+    readonly algorithm?: AlgorithmId;
+    readonly chunkBytes?: number;
+}
+/**
+ * Fingerprint a directory tree.
+ *
+ * The returned entries are sorted by UTF-8 path bytes and carry the child digest
+ * each leaf was built from, so a caller can re-derive the root after changing
+ * one file without re-reading the whole tree. The algorithm is fixed to SHA-256
+ * in this build: the root composition in `amp.fp/1` is defined in terms of
+ * SHA-256, so naming another algorithm here would produce a reference whose
+ * verifier cannot exist.
+ */
+export declare const fingerprintTree: (root: string, options?: TreeFingerprintOptions) => Promise<TreeFingerprint>;

package/lib/fingerprint/tree.js

@@ -0,0 +1,288 @@
+/**
+ * Canonical directory-tree fingerprints: a Merkle tree over a sorted flat leaf
+ * list.
+ *
+ * Hashing a directory is meaningless until its serialisation is defined —tar
+ * and zip are not canonical, which is why Nix hashes NAR rather than raw bytes.
+ * The serialisation used here is:
+ *
+ *     leaf(pathBytes, mode, size, childDigest)
+ *         = sha256( 0x00 || u32be(pathBytes.length) || pathBytes
+ *                   || u32be(mode) || u64be(size) || childDigest )
+ *     node(left, right)
+ *         = sha256( 0x01 || left || right )
+ *     root
+ *         = sha256( 0x02 || u64be(entryCount) || merkleRoot || sha256(utf8(treePolicy)) )
+ *
+ * The `0x00`/`0x01`/`0x02` prefixes are domain separation in the sense of RFC
+ * 6962 §2.1: without them a leaf digest could be replayed as an interior node,
+ * which breaks second-preimage resistance. `entryCount` in the root makes `{}`
+ * differ from a tree whose only entry is an empty directory even before the
+ * leaves are considered, and folding the policy hash into the root binds the
+ * exclusion/digest rules to the value.
+ *
+ * Paths are `/`-separated, relative to the root, and sorted by UTF-8 byte order
+ * (`Buffer.compare`), never by locale. `mode` binds the file type and the
+ * executable bit; `size` is in the leaf so a verifier compares length before
+ * digest, as OCI does. Directories get `sha256(empty)` as their child digest:
+ * their content is represented by the leaves of their children, and the leaf's
+ * mode field is what keeps the entry from colliding with an empty file at the
+ * same path.
+ *
+ * Symlinks are **never followed**. A symlink is recorded as mode 4 with its
+ * target string hashed as the child digest, so a link loop cannot hang the walk
+ * and the same tree produces the same root on machines where the link would
+ * resolve differently.
+ */
+import { lstatSync, readdirSync, readlinkSync } from "node:fs";
+import { join } from "node:path";
+import { bytesToHex, createSha256, hexToBytes } from "./algorithm.js";
+import { FingerprintIOError, UnsupportedAlgorithm, describeError } from "./error.js";
+import { fileContentDigest, resolveChunkBytes } from "./file.js";
+import { Policy } from "./policy.js";
+import { SchemeName, shortForm } from "./preimage.js";
+import { encodeUtf8Strict } from "./text.js";
+const ModeFile = 1;
+const ModeExecutableFile = 2;
+const ModeDirectory = 3;
+const ModeSymlink = 4;
+const LeafPrefix = 0x00;
+const NodePrefix = 0x01;
+const RootPrefix = 0x02;
+const DigestBytes = 32;
+const LeafFixedBytes = 1 + 4 + 4 + 8 + DigestBytes;
+const NodeBytes = 1 + DigestBytes + DigestBytes;
+const RootFixedBytes = 1 + 8 + DigestBytes + DigestBytes;
+const PathLengthOffset = 1;
+const ModeOffsetBase = 5;
+const SizeOffsetBase = 9;
+const DigestOffsetBase = 17;
+const NodeLeftOffset = 1;
+const NodeRightOffset = 1 + DigestBytes;
+const RootCountOffset = 1;
+const RootMerkleOffset = 9;
+const RootPolicyOffset = 41;
+const Uint32Range = 0x100000000;
+/**
+ * Default exclusions. Version-control metadata, dependency trees, caches and
+ * build output are not content: including them would make the same source tree
+ * produce different roots on two machines. The set is echoed in `excluded`
+ * because "what was ignored" changes the digest and has to be auditable.
+ */
+const DefaultExclusions = ["node_modules", ".git", ".cache", "dist", "lib"];
+/**
+ * Child digest used for directories, and the Merkle root of an empty tree.
+ * Both are `sha256(empty)`, which is unambiguous because the leaf records carry
+ * path, mode and size, so a directory entry can never be confused with an empty
+ * file entry at a different position.
+ */
+const EmptyDigestHex = bytesToHex(createSha256().digest());
+/**
+ * Compare two relative paths by their UTF-8 bytes.
+ *
+ * `Array.prototype.sort()` compares UTF-16 code units, which orders astral
+ * characters before U+E000–U+FFFF; RFC 8785 and every content-addressed format
+ * expect byte order. Decoding through `Buffer` is the cheapest way to get it,
+ * and `Buffer.compare` returns the sign `sort` needs.
+ */
+const comparePaths = (left, right) => Buffer.compare(Buffer.from(left, "utf8"), Buffer.from(right, "utf8"));
+/**
+ * Validate the exclusion set once.
+ *
+ * A pattern is a plain entry name, not a glob and not a path: a value containing
+ * a separator would silently exclude nothing, and a silent no-op in an exclusion
+ * rule is exactly the kind of mistake that later looks like a digest mismatch.
+ */
+const resolveExclusions = (exclude) => {
+    const names = exclude ?? DefaultExclusions;
+    const unique = new Set();
+    for (let index = 0; index < names.length; index += 1) {
+        const name = names[index];
+        if (name.length === 0 || name.includes("/") || name.includes("\\")) {
+            throw new TypeError(`exclusion "${name}" must be a single path segment without separators`);
+        }
+        unique.add(name);
+    }
+    return [...unique];
+};
+const lstatOrThrow = (path) => {
+    try {
+        return lstatSync(path);
+    }
+    catch (error) {
+        throw new FingerprintIOError([`cannot stat ${path}: ${describeError(error)}`]);
+    }
+};
+const readDirectoryOrThrow = (path) => {
+    try {
+        return readdirSync(path);
+    }
+    catch (error) {
+        throw new FingerprintIOError([`cannot read directory ${path}: ${describeError(error)}`]);
+    }
+};
+const readLinkOrThrow = (path) => {
+    try {
+        return readlinkSync(path);
+    }
+    catch (error) {
+        throw new FingerprintIOError([`cannot read symlink ${path}: ${describeError(error)}`]);
+    }
+};
+/**
+ * Depth-first walk that records one entry per filesystem object and never
+ * descends through a symlink.
+ *
+ * Recursion is safe because the walk cannot loop: a symlink is recorded and
+ * skipped, so a cycle in the directory graph (which POSIX forbids anyway) is not
+ * reachable. Ordering is imposed later by a global sort, so the traversal order
+ * here only has to be deterministic, which sorting the child names provides.
+ */
+const collectEntries = (directory, prefix, state) => {
+    const names = readDirectoryOrThrow(directory);
+    names.sort(comparePaths);
+    for (let index = 0; index < names.length; index += 1) {
+        const name = names[index];
+        if (state.excluded.has(name)) {
+            continue;
+        }
+        const fullPath = join(directory, name);
+        const relativePath = prefix.length === 0 ? name : `${prefix}/${name}`;
+        const stats = lstatOrThrow(fullPath);
+        if (stats.isSymbolicLink()) {
+            const target = readLinkOrThrow(fullPath);
+            const targetBytes = encodeUtf8Strict(target);
+            state.entries.push({
+                path: relativePath,
+                digest: bytesToHex(createSha256().update(targetBytes).digest()),
+                size: targetBytes.length,
+                mode: ModeSymlink,
+            });
+            continue;
+        }
+        if (stats.isDirectory()) {
+            state.entries.push({ path: relativePath, digest: EmptyDigestHex, size: 0, mode: ModeDirectory });
+            collectEntries(fullPath, relativePath, state);
+            continue;
+        }
+        if (!stats.isFile()) {
+            throw new FingerprintIOError([`${fullPath} is not a regular file, directory or symlink`]);
+        }
+        const mode = (stats.mode & 0o111) !== 0 ? ModeExecutableFile : ModeFile;
+        const digest = fileContentDigest(fullPath, stats.size, state.chunkBytes);
+        state.entries.push({ path: relativePath, digest, size: stats.size, mode });
+    }
+};
+/**
+ * Serialise one entry into its leaf record.
+ *
+ * `size` is written as a big-endian u64 from its high and low 32-bit halves,
+ * which avoids BigInt conversion on the hot path and is exact for every
+ * JavaScript number that can be a file size (`Number.isSafeInteger`).
+ */
+const buildLeafRecord = (entry) => {
+    const pathBytes = encodeUtf8Strict(entry.path);
+    const record = new Uint8Array(LeafFixedBytes + pathBytes.length);
+    record[0] = LeafPrefix;
+    const view = new DataView(record.buffer);
+    view.setUint32(PathLengthOffset, pathBytes.length);
+    record.set(pathBytes, PathLengthOffset + 4);
+    const modeOffset = ModeOffsetBase + pathBytes.length;
+    const sizeOffset = SizeOffsetBase + pathBytes.length;
+    const digestOffset = DigestOffsetBase + pathBytes.length;
+    view.setUint32(modeOffset, entry.mode);
+    view.setUint32(sizeOffset, Math.floor(entry.size / Uint32Range));
+    view.setUint32(sizeOffset + 4, entry.size % Uint32Range);
+    record.set(hexToBytes(entry.digest), digestOffset);
+    return record;
+};
+/**
+ * Fold sorted leaf digests into a Merkle root.
+ *
+ * Adjacent pairs are combined bottom-up; an odd node is promoted unchanged to
+ * the next level, which is the Bitcoin/RFC 6962 style tree and keeps the fold
+ * well-defined for any entry count. The empty tree is `sha256(empty)` rather
+ * than a special constant, so the one-entry and zero-entry cases differ by an
+ * actual hash rather than by convention.
+ */
+const merkleFold = (leaves) => {
+    if (leaves.length === 0) {
+        return createSha256().digest();
+    }
+    let level = [];
+    for (let index = 0; index < leaves.length; index += 1) {
+        level.push(leaves[index]);
+    }
+    while (level.length > 1) {
+        const next = [];
+        for (let index = 0; index < level.length; index += 2) {
+            if (index + 1 === level.length) {
+                next.push(level[index]);
+                continue;
+            }
+            const pair = new Uint8Array(NodeBytes);
+            pair[0] = NodePrefix;
+            pair.set(level[index], NodeLeftOffset);
+            pair.set(level[index + 1], NodeRightOffset);
+            next.push(createSha256().update(pair).digest());
+        }
+        level = next;
+    }
+    return level[0];
+};
+/**
+ * Fingerprint a directory tree.
+ *
+ * The returned entries are sorted by UTF-8 path bytes and carry the child digest
+ * each leaf was built from, so a caller can re-derive the root after changing
+ * one file without re-reading the whole tree. The algorithm is fixed to SHA-256
+ * in this build: the root composition in `amp.fp/1` is defined in terms of
+ * SHA-256, so naming another algorithm here would produce a reference whose
+ * verifier cannot exist.
+ */
+export const fingerprintTree = async (root, options) => {
+    const algorithm = options?.algorithm ?? "sha256";
+    if (algorithm !== "sha256") {
+        throw new UnsupportedAlgorithm([`tree fingerprints compose with sha256; algorithm "${algorithm}" has no tree backend`]);
+    }
+    const chunkBytes = resolveChunkBytes(options?.chunkBytes);
+    const rootStats = lstatOrThrow(root);
+    if (rootStats.isSymbolicLink()) {
+        throw new FingerprintIOError([`${root} is a symbolic link; tree fingerprints never follow links`]);
+    }
+    if (!rootStats.isDirectory()) {
+        throw new FingerprintIOError([`${root} is not a directory`]);
+    }
+    const exclusions = resolveExclusions(options?.exclude);
+    const state = { excluded: new Set(exclusions), chunkBytes, entries: [] };
+    collectEntries(root, "", state);
+    const sorted = state.entries.slice();
+    sorted.sort((left, right) => comparePaths(left.path, right.path));
+    const leaves = [];
+    let totalBytes = 0;
+    for (let index = 0; index < sorted.length; index += 1) {
+        const record = buildLeafRecord(sorted[index]);
+        leaves.push(createSha256().update(record).digest());
+        totalBytes += record.byteLength;
+    }
+    const merkleRoot = merkleFold(leaves);
+    const policyDigest = createSha256().update(encodeUtf8Strict(Policy.treeV1)).digest();
+    const rootInput = new Uint8Array(RootFixedBytes);
+    rootInput[0] = RootPrefix;
+    const rootView = new DataView(rootInput.buffer);
+    rootView.setUint32(RootCountOffset, Math.floor(sorted.length / Uint32Range));
+    rootView.setUint32(RootCountOffset + 4, sorted.length % Uint32Range);
+    rootInput.set(merkleRoot, RootMerkleOffset);
+    rootInput.set(policyDigest, RootPolicyOffset);
+    const rootHex = bytesToHex(createSha256().update(rootInput).digest());
+    const excluded = [...exclusions].sort(comparePaths);
+    const ref = {
+        scheme: SchemeName,
+        algorithm,
+        kind: "tree",
+        policy: Policy.treeV1,
+        bytes: totalBytes,
+        digest: rootHex,
+    };
+    return { ref, digest: shortForm(algorithm, rootHex), root: rootHex, entries: sorted, excluded };
+};

package/lib/fingerprint/verify.d.ts

@@ -0,0 +1,20 @@
+import type { FingerprintRef } from "./preimage.js";
+/**
+ * True when both references name the same value under the same rules.
+ *
+ * Kind and policy are compared as strings because they are frozen vocabulary;
+ * digest comparison is constant-time-ish. `bytes` is deliberately not part of
+ * the identity here (RFC 6920 identity is algorithm + value), but `verify`
+ * compares it as well.
+ */
+export declare const matches: (expected: FingerprintRef, actual: FingerprintRef) => boolean;
+/**
+ * Assert that `actual` is the value `expected` names; throw `FingerprintMismatch`
+ * otherwise.
+ *
+ * The message contains both references (algorithm, kind, policy, bytes and hex)
+ * plus one line per differing field. A log line that only says "mismatch" cannot
+ * be acted on: the reader needs to know whether the policy changed or the bytes
+ * did.
+ */
+export declare const verify: (expected: FingerprintRef, actual: FingerprintRef) => void;

package/lib/fingerprint/verify.js

@@ -0,0 +1,99 @@
+/**
+ * Reference comparison and verification.
+ *
+ * Comparing digests alone is the bug this module exists to avoid: the same
+ * payload bytes hashed under two policies produce two different digests, so a
+ * verifier that only sees hex cannot know which rules to apply. `matches`
+ * therefore compares the identity quadruple — algorithm, kind, policy and
+ * digest — following RFC 6920 §2 (identity is algorithm + value; presentation
+ * fields are ignored) extended with the two fields that decide how the value was
+ * computed.
+ *
+ * `verify` is one step stricter and also compares the declared payload length,
+ * mirroring OCI's "compare size before digest" rule: a reference that claims a
+ * different length is a different descriptor even when the hash agrees. The
+ * length is cheap to compare and shrinks the space an attacker has to search.
+ *
+ * The hex comparison is length-checked first and then scans the whole string
+ * without an early exit, so a mismatch does not reveal the position of the first
+ * differing digit through timing. This is not a substitute for a MAC, but it
+ * costs nothing and avoids being the weakest link in an otherwise
+ * constant-time comparison chain.
+ */
+import { FingerprintMismatch } from "./error.js";
+/**
+ * Compare two equal-length strings without returning early.
+ *
+ * Different lengths fail immediately: the length is public (it is the algorithm
+ * identity), so no secret leaks, and scanning would need padding to be
+ * meaningful anyway.
+ */
+const constantTimeEquals = (left, right) => {
+    if (left.length !== right.length) {
+        return false;
+    }
+    let difference = 0;
+    for (let index = 0; index < left.length; index += 1) {
+        difference |= left.charCodeAt(index) ^ right.charCodeAt(index);
+    }
+    return difference === 0;
+};
+/**
+ * Describe a reference for a human reader without re-validating it.
+ *
+ * `formatRef` cannot be used in the mismatch message: it validates the fields
+ * and throws, which would replace the `FingerprintMismatch` the caller is
+ * supposed to catch with an unrelated `invalid_ref`.
+ */
+const describe = (ref) => `${ref.algorithm}:${ref.kind}:${ref.policy}:${ref.bytes}:${ref.digest}`;
+/**
+ * True when both references name the same value under the same rules.
+ *
+ * Kind and policy are compared as strings because they are frozen vocabulary;
+ * digest comparison is constant-time-ish. `bytes` is deliberately not part of
+ * the identity here (RFC 6920 identity is algorithm + value), but `verify`
+ * compares it as well.
+ */
+export const matches = (expected, actual) => {
+    if (expected.algorithm !== actual.algorithm) {
+        return false;
+    }
+    if (expected.kind !== actual.kind) {
+        return false;
+    }
+    if (expected.policy !== actual.policy) {
+        return false;
+    }
+    return constantTimeEquals(expected.digest, actual.digest);
+};
+/**
+ * Assert that `actual` is the value `expected` names; throw `FingerprintMismatch`
+ * otherwise.
+ *
+ * The message contains both references (algorithm, kind, policy, bytes and hex)
+ * plus one line per differing field. A log line that only says "mismatch" cannot
+ * be acted on: the reader needs to know whether the policy changed or the bytes
+ * did.
+ */
+export const verify = (expected, actual) => {
+    const problems = [];
+    if (expected.algorithm !== actual.algorithm) {
+        problems.push(`algorithm differs: expected ${expected.algorithm}, received ${actual.algorithm}`);
+    }
+    if (expected.kind !== actual.kind) {
+        problems.push(`kind differs: expected ${expected.kind}, received ${actual.kind}`);
+    }
+    if (expected.policy !== actual.policy) {
+        problems.push(`policy differs: expected ${expected.policy}, received ${actual.policy}`);
+    }
+    if (!constantTimeEquals(expected.digest, actual.digest)) {
+        problems.push("digest differs");
+    }
+    if (expected.bytes !== actual.bytes) {
+        problems.push(`bytes differs: expected ${expected.bytes}, received ${actual.bytes}`);
+    }
+    if (problems.length === 0) {
+        return;
+    }
+    throw new FingerprintMismatch([`expected ${describe(expected)} but received ${describe(actual)}`, ...problems]);
+};

package/lib/global/filesystem.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Global filesystem adapter.
+ *
+ * The adapter renames the local `amp_tool_filesystem_*` surface to
+ * `amp_tool_globalfs_*` and rewrites the response protocol. It owns no tree,
+ * cache or write journal of its own: every call goes through the bound
+ * `FilesystemSession`, so the session token, roots, quotas and isolation stay
+ * exactly as strong as the local surface. A future multi-root router can sit
+ * behind the same interface without changing the wire names.
+ */
+import type { FilesystemSession } from "../file/service.js";
+import type { FilesystemService } from "../file/service.js";
+import type { FilesystemToolDefinition } from "../protocol/filesystem.js";
+import type { GlobalFilesystemResponse } from "../protocol/globalFilesystem.js";
+export declare class GlobalFilesystemService {
+    private readonly base;
+    constructor(base: FilesystemService);
+    /**
+     * Bind one authenticated session to the global namespace.
+     */
+    bind(sessionId: string, token: string): GlobalFilesystemSession;
+    dispose(sessionId: string): void;
+}
+export declare class GlobalFilesystemSession {
+    private readonly base;
+    constructor(base: FilesystemSession);
+    get sessionId(): string;
+    get descriptor(): FilesystemSession["descriptor"];
+    tools(): FilesystemToolDefinition[];
+    /**
+     * Typed delegates keep hook and direct-embedder code identical for the
+     * local and global surfaces.
+     */
+    read: FilesystemSession["read"];
+    write: FilesystemSession["write"];
+    outline: FilesystemSession["outline"];
+    imports: FilesystemSession["imports"];
+    exports: FilesystemSession["exports"];
+    dependency: FilesystemSession["dependency"];
+    ast: FilesystemSession["ast"];
+    revision: FilesystemSession["revision"];
+    call(name: string, raw: unknown): Promise<GlobalFilesystemResponse>;
+}