attention-manifest-protocol 0.4.2 → 0.4.4

package/lib/file/path.js

@@ -0,0 +1,259 @@
+/**
+ * Root-confined path resolution.
+ *
+ * Every tool path is a POSIX path relative to one of the session's roots. The
+ * sandbox rejects absolute paths, `..`, NUL/control characters and backslashes,
+ * then verifies that no existing component is a symlink (unless the host opted
+ * into following them). The session root itself is resolved through `realpath`
+ * when the session is opened, so replacing a parent directory afterwards cannot
+ * move an already-authorized root.
+ */
+import { lstatSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, relative as relativePath, resolve as resolvePath, sep } from "node:path";
+import { fail } from "./errors.js";
+const ControlCharacters = /[\u0000-\u001f\u007f]/;
+const DriveLetter = /^[A-Za-z]:/;
+/**
+ * Normalize one caller-supplied relative path into slash-separated segments.
+ * A `.` or empty path means the root itself.
+ */
+const normalizeRelative = (input) => {
+    if (typeof (input) !== "string" || ControlCharacters.test(input)) {
+        return fail("invalid_path");
+    }
+    const text = input.trim();
+    if (text.length === 0 || text === "." || text === "./") {
+        return ".";
+    }
+    if (text.includes("\\")) {
+        return fail("invalid_path");
+    }
+    if (isAbsolute(text) || DriveLetter.test(text) || text.startsWith("//")) {
+        return fail("invalid_path");
+    }
+    const segments = [];
+    const parts = text.split("/");
+    for (let index = 0; index < parts.length; index += 1) {
+        const part = parts[index];
+        if (part === "" || part === ".") {
+            continue;
+        }
+        if (part === "..") {
+            return fail("path_escape");
+        }
+        segments.push(part);
+    }
+    return segments.length === 0 ? "." : segments.join("/");
+};
+/**
+ * Convert a host-relative path to POSIX separators without resolving it.
+ */
+const toPosix = (value) => value.split(sep).join("/");
+/**
+ * Case-fold only on case-insensitive platforms; the check must not make a
+ * POSIX host accept `Readme.md` as `README.md`.
+ */
+const fold = (value) => (process.platform === "win32" ? value.toLowerCase() : value);
+export class PathSandbox {
+    roots;
+    byId = new Map();
+    followSymlinks;
+    defaultRootId;
+    constructor(roots, options = {}) {
+        if (!Array.isArray(roots) || roots.length === 0) {
+            throw new Error("path sandbox requires at least one root");
+        }
+        const seenIds = new Set();
+        const seenPaths = new Set();
+        const normalized = [];
+        for (let index = 0; index < roots.length; index += 1) {
+            const root = roots[index];
+            if (root === null ||
+                typeof (root) !== "object" ||
+                typeof (root.id) !== "string" ||
+                root.id.trim().length === 0 ||
+                typeof (root.path) !== "string" ||
+                !isAbsolute(root.path) ||
+                typeof (root.writable) !== "boolean" ||
+                !Array.isArray(root.exclude) ||
+                root.exclude.some((entry) => typeof (entry) !== "string") ||
+                seenIds.has(root.id)) {
+                throw new Error("invalid or duplicate session root");
+            }
+            let real;
+            try {
+                if (!statSync(root.path).isDirectory()) {
+                    throw new Error("root is not a directory");
+                }
+                real = realpathSync(root.path);
+            }
+            catch {
+                throw new Error("invalid or inaccessible session root");
+            }
+            const identity = fold(real);
+            if (seenPaths.has(identity)) {
+                throw new Error("invalid or duplicate session root");
+            }
+            seenIds.add(root.id);
+            seenPaths.add(identity);
+            normalized.push({ id: root.id, path: real, writable: root.writable, exclude: [...root.exclude] });
+        }
+        this.roots = normalized;
+        for (const root of normalized) {
+            this.byId.set(root.id, root);
+        }
+        this.followSymlinks = options.followSymlinks === true;
+        this.defaultRootId = normalized[0].id;
+    }
+    /**
+     * All roots, in the order the session declared them.
+     */
+    listRoots() {
+        return this.roots.map((root) => ({ ...root, exclude: [...root.exclude] }));
+    }
+    /**
+     * The root used when a path does not name one explicitly.
+     */
+    defaultRoot() {
+        return this.root(this.defaultRootId);
+    }
+    /**
+     * Look up a root by id.
+     */
+    root(id) {
+        const root = this.byId.get(id);
+        return root === (void 0) ? fail("invalid_path") : { ...root, exclude: [...root.exclude] };
+    }
+    /**
+     * Resolve a caller path to a root, a normalized relative path and an
+     * absolute host path. The method does not require the target to exist; a
+     * write may create it. Symlink checks stop at the first missing component.
+     *
+     * @param input - Root-relative POSIX path, optionally prefixed by `rootId/`.
+     * @param operation - Operation used for writability checks.
+     * @returns Resolved path.
+     */
+    resolve(input, operation) {
+        if (typeof (input) !== "string") {
+            return fail("invalid_path");
+        }
+        const normalized = normalizeRelative(input);
+        let root = this.defaultRoot();
+        let relative = normalized;
+        const firstSlash = normalized.indexOf("/");
+        const firstSegment = firstSlash === -1 ? normalized : normalized.slice(0, firstSlash);
+        const named = this.byId.get(firstSegment);
+        if (named !== (void 0)) {
+            root = named;
+            relative = firstSlash === -1 ? "." : normalized.slice(firstSlash + 1);
+        }
+        if (this.isExcluded(root, relative)) {
+            return fail("excluded_path");
+        }
+        if ((operation === "write" || operation === "create" || operation === "remove") && !root.writable) {
+            return fail("permission_denied");
+        }
+        const absolute = resolvePath(join(root.path, relative));
+        if (!this.contains(root.path, absolute)) {
+            return fail("path_escape");
+        }
+        this.assertNoSymlinkEscape(root, relative, absolute);
+        return { root: { ...root, exclude: [...root.exclude] }, relative, absolute };
+    }
+    /**
+     * Whether an absolute path is inside a root, using the platform's case
+     * sensitivity.
+     */
+    contains(rootPath, absolute) {
+        const path = relativePath(rootPath, absolute);
+        if (path === "") {
+            return true;
+        }
+        if (isAbsolute(path)) {
+            return false;
+        }
+        return path !== ".." && !path.startsWith(`..${sep}`) && !path.startsWith("../");
+    }
+    /**
+     * Prefix/name exclusion. A bare name excludes a segment at any depth; a
+     * value containing `/` is a root-relative prefix.
+     */
+    isExcluded(root, relative) {
+        const target = relative === "." ? "" : relative;
+        return root.exclude.some((entry) => {
+            const value = entry.replace(/^\.?\//, "").replace(/\/+$/, "");
+            if (value.length === 0) {
+                return false;
+            }
+            if (value.includes("/")) {
+                return target === value || target.startsWith(`${value}/`);
+            }
+            return target.split("/").includes(value);
+        });
+    }
+    /**
+     * The root-relative POSIX path for an absolute path already known to be in
+     * the root.
+     */
+    relative(root, absolute) {
+        return toPosix(relativePath(root.path, absolute)) || ".";
+    }
+    /**
+     * Re-check that a path still resolves inside its root. Used after a write
+     * rename and before a read, so a component swapped for a symlink between
+     * resolution and I/O is rejected.
+     */
+    revalidate(rooted) {
+        const root = this.byId.get(rooted.root.id) ?? fail("invalid_path");
+        if (root.path !== rooted.root.path || rooted.absolute !== resolvePath(join(root.path, rooted.relative)) || !this.contains(root.path, rooted.absolute)) {
+            return fail("path_escape");
+        }
+        this.assertNoSymlinkEscape(root, rooted.relative, rooted.absolute);
+    }
+    assertNoSymlinkEscape(root, relative, absolute) {
+        try {
+            if (realpathSync(root.path) !== root.path) {
+                return fail("path_escape");
+            }
+        }
+        catch {
+            return fail("invalid_path");
+        }
+        if (relative === ".") {
+            return;
+        }
+        const segments = relative.split("/");
+        let current = root.path;
+        for (let index = 0; index < segments.length; index += 1) {
+            current = join(current, segments[index]);
+            let stat;
+            try {
+                stat = lstatSync(current);
+            }
+            catch {
+                return;
+            }
+            if (stat.isSymbolicLink()) {
+                if (!this.followSymlinks) {
+                    return fail("symlink_denied");
+                }
+                const real = realpathSync(current);
+                if (!this.contains(root.path, real)) {
+                    return fail("path_escape");
+                }
+                current = real;
+            }
+        }
+        if (this.followSymlinks) {
+            try {
+                const real = realpathSync(absolute);
+                if (!this.contains(root.path, real)) {
+                    return fail("path_escape");
+                }
+            }
+            catch {
+                return;
+            }
+        }
+    }
+}

package/lib/file/read.d.ts

@@ -0,0 +1,168 @@
+import type { PathSandbox } from "./path.js";
+import type { Charset } from "../syntax/types.js";
+import type { ReadPage, ReadRequest } from "./types.js";
+/**
+ * Options for {@link readPage}. `maxBytes` bounds the *file*, not the page; the
+ * page budget travels in {@link ReadRequest.maxBytes}.
+ */
+export interface ReadOptions {
+    readonly maxBytes?: number;
+    readonly timeZone?: "local" | "utc";
+}
+/**
+ * Per-session page cache.
+ *
+ * The value is the page text *without* line-number prefixes, so the same page
+ * can serve a numbered and an unnumbered request. Keys are built by the caller
+ * and must contain the root-relative path, the whole-file fingerprint, the
+ * 1-based start line and the effective line and byte budgets; the fingerprint
+ * is what makes a cached page impossible to serve against changed bytes.
+ */
+export declare class ReadCache {
+    private readonly pages;
+    constructor(options?: {
+        entries?: number;
+    });
+    /**
+     * Read a cached page and mark it most recently used.
+     */
+    get(key: string): string | undefined;
+    /**
+     * Insert or replace a page; the entry becomes most recently used.
+     */
+    set(key: string, value: string): void;
+    /**
+     * Number of cached pages.
+     */
+    get size(): number;
+}
+/**
+ * Read one bounded page of a workspace file.
+ *
+ * The flow is deliberately strict: sandbox resolution, regular-file check,
+ * file-size ceiling, a second sandbox revalidation before the read, charset
+ * sniffing, decode, line-index paging and finally the UTF-8 byte budget. A
+ * `startLine` past EOF returns an empty page with `nextStartLine: null` rather
+ * than an error, which lets a client keep paging without a special case.
+ *
+ * @param sandbox - Session sandbox that owns path resolution.
+ * @param request - Path, 1-based start line and page budgets.
+ * @param options - File-size ceiling and timestamp mode.
+ * @returns The decoded page plus its fingerprint and total sizes.
+ */
+export declare const readPage: (sandbox: PathSandbox, request: ReadRequest, options?: ReadOptions) => ReadPage;
+/**
+ * Canonical fingerprint of one raw byte range.
+ *
+ * The preimage binds the absolute offsets, so the same bytes at a different
+ * place do not share a fingerprint. Line spans are hashed through this same
+ * function after they are mapped to raw bytes, which is what lets the read and
+ * write helpers agree on a single range identity.
+ *
+ * @param startByte - 0-based inclusive start offset in the raw file.
+ * @param endByte - 0-based exclusive end offset in the raw file.
+ * @param bytes - Raw bytes of the range.
+ * @returns `sha256:<hex>` of the domain-separated range preimage.
+ */
+export declare const byteRangeFingerprint: (startByte: number, endByte: number, bytes: Uint8Array) => string;
+/**
+ * Dominant line terminator seen in a decoded text, or `none` when the text has
+ * no newline at all.
+ */
+export type LineEnding = "\n" | "\r\n" | "none";
+/**
+ * Request for {@link useByte}. Offsets are 0-based and half-open over the raw
+ * file bytes, including any BOM.
+ */
+export interface ByteUseRequest {
+    readonly path: string;
+    readonly startByte: number;
+    readonly endByte: number;
+}
+/**
+ * Raw byte range plus the fingerprints needed to patch it safely.
+ */
+export interface ByteUse {
+    readonly path: string;
+    readonly fingerprint: string;
+    readonly rangeFingerprint: string;
+    readonly charset: Charset;
+    readonly startByte: number;
+    readonly endByte: number;
+    readonly totalBytes: bigint;
+    readonly bytes: Uint8Array;
+    readonly text: string;
+    readonly binary: boolean;
+}
+/**
+ * Request for {@link useLine}. Line numbers are 1-based and inclusive;
+ * `endLine = startLine - 1` describes the empty insertion point before
+ * `startLine`.
+ */
+export interface LineUseRequest {
+    readonly path: string;
+    readonly startLine: number;
+    readonly endLine: number;
+}
+/**
+ * Byte span of one line range. `startByte`/`endByte` cover the raw bytes of the
+ * first character through the terminator of the last line, so a line write and
+ * a byte write address exactly the same region.
+ */
+export interface LineSpan {
+    readonly charset: Charset;
+    readonly startLine: number;
+    readonly endLine: number;
+    readonly startChar: number;
+    readonly endChar: number;
+    readonly startByte: number;
+    readonly endByte: number;
+    readonly totalLines: bigint;
+    readonly totalBytes: bigint;
+    readonly bomLength: number;
+    readonly lineEnding: LineEnding;
+    readonly finalNewline: boolean;
+    readonly text: string;
+    readonly rangeFingerprint: string;
+}
+/**
+ * Line range plus the whole-file fingerprint of the read.
+ */
+export interface LineUse extends LineSpan {
+    readonly path: string;
+    readonly fingerprint: string;
+}
+/**
+ * Read one raw byte range and return exact bytes, the whole-file fingerprint
+ * and the canonical range fingerprint. Binary content is allowed here: this is
+ * the byte-oriented companion to {@link readPage}, not a text tool.
+ *
+ * @param sandbox - Session sandbox that owns path resolution.
+ * @param request - Path and half-open raw byte offsets.
+ * @param options - File-size ceiling.
+ * @returns Range bytes, text, charset and both fingerprints.
+ */
+export declare const useByte: (sandbox: PathSandbox, request: ByteUseRequest, options?: ReadOptions) => ByteUse;
+/**
+ * Read one line range and return its decoded text plus the exact byte span and
+ * range fingerprint a matching write needs. An empty range (`endLine =
+ * startLine - 1`) describes an insertion point; EOF and empty files are
+ * supported because `startLine = totalLines + 1` is a valid insertion point.
+ *
+ * @param sandbox - Session sandbox that owns path resolution.
+ * @param request - Path and 1-based inclusive line range.
+ * @param options - File-size ceiling.
+ * @returns Line span, text, EOL metadata and both fingerprints.
+ */
+export declare const useLine: (sandbox: PathSandbox, request: LineUseRequest, options?: ReadOptions) => LineUse;
+/**
+ * Locate a line range directly from raw bytes. This is the shared mapping used
+ * by {@link useLine} and by the write-side line patch, so both sides compute the
+ * same byte span and range fingerprint.
+ *
+ * @param bytes - Raw file bytes.
+ * @param startLine - 1-based inclusive start line.
+ * @param endLine - 1-based inclusive end line, or `startLine - 1` for insertion.
+ * @returns The canonical line span.
+ */
+export declare const locateLineSpan: (bytes: Uint8Array, startLine: number, endLine: number) => LineSpan;