@maudecode/talaria-web 1.17.2 → 1.19.0

package/dist/workspace/escape.js

@@ -0,0 +1,149 @@
+/**
+ * Read-only escape grants (Python `workspace.py` `authorize_escape_target` and friends, TAL-263): a workspace symlink
+ * whose target sits outside the workspace opens through a short-lived token scoped to that one link. A directory
+ * target anchors the grant at the target; a file target anchors it at the parent with the file as the only reachable
+ * entry. Every use re-checks the link, and every read stays anchored at the grant root, so nested escaping links stay
+ * display-only.
+ */
+import { randomBytes } from 'node:crypto';
+import { lstatSync, statSync } from 'node:fs';
+import { basename, dirname, join, posix, relative } from 'node:path';
+import { stripSurroundingQuotes, isBlockedSystemPath } from './workspaces.js';
+import { isWithin, resolvePathLikePython } from './paths.js';
+import { dirSignature, listDir, NotFoundError, PathTraversalError, safeResolveWs, withPinnedRoot } from './fs.js';
+import { readFilePreview } from './preview.js';
+export const ESCAPE_GRANT_TTL_SECONDS = 300;
+/** Any failed re-check: the client asks for a new grant (403). */
+export class EscapeGrantExpired extends Error {
+    constructor() { super('Escape authorization expired'); }
+}
+/** Run `fn` with every anchored open of the grant root held to the inode the grant was minted for. */
+export function anchoredAt(req, fn) {
+    return withPinnedRoot(req.externalRoot, req.rootId, fn);
+}
+/** Python `_normalize_workspace_rel_path`: POSIX-normalised and workspace-relative; `..` and absolute paths fail. */
+export function normalizeWorkspaceRelPath(rel) {
+    const raw = stripSurroundingQuotes(rel).trim().replaceAll('\\', '/');
+    if (!raw || raw === '.')
+        return '.';
+    const norm = posix.normalize(raw).replace(/(.)\/+$/, '$1');
+    if (norm === '.')
+        return '.';
+    if (norm === '..' || norm.startsWith('../') || norm.startsWith('/'))
+        throw new PathTraversalError(`Path traversal blocked: ${rel}`);
+    return norm;
+}
+function virtualPath(root, rel) {
+    if (root === '.')
+        return rel;
+    return rel === '.' ? root : `${root}/${rel}`;
+}
+/** Python `_escape_surface_target`: the resolved target of an escaping, reachable, non-system workspace symlink. */
+function surfaceTarget(workspaceRoot, rel) {
+    const surfaceRel = normalizeWorkspaceRelPath(rel);
+    const parentRel = posix.dirname(surfaceRel);
+    const parent = parentRel === '.' ? workspaceRoot : safeResolveWs(workspaceRoot, parentRel);
+    const surface = join(parent, posix.basename(surfaceRel));
+    let isLink = false;
+    try {
+        isLink = lstatSync(surface).isSymbolicLink();
+    }
+    catch { /* missing */ }
+    if (!isLink)
+        throw new NotFoundError(`Path is not an escape-target symlink: ${rel}`);
+    let target;
+    try {
+        target = resolvePathLikePython(surface);
+        statSync(target);
+    }
+    catch {
+        throw new NotFoundError(`Path is no longer reachable: ${rel}`);
+    }
+    if (isWithin(target, workspaceRoot))
+        throw new NotFoundError(`Path does not escape workspace: ${rel}`);
+    if (isBlockedSystemPath(target))
+        throw new NotFoundError(`Path points to a system directory: ${target}`);
+    return target;
+}
+export class EscapeGrants {
+    now;
+    grants = new Map();
+    constructor(now) {
+        this.now = now;
+    }
+    /** Mint a grant for one surfaced escape-target symlink. */
+    authorize(workspace, sessionId, profile, rel) {
+        const workspaceRoot = resolvePathLikePython(workspace);
+        const target = surfaceTarget(workspaceRoot, rel);
+        const isDir = statSync(target).isDirectory();
+        const externalRoot = isDir ? target : dirname(target);
+        const { dev, ino } = statSync(externalRoot);
+        const token = randomBytes(24).toString('base64url');
+        const expiresAt = this.now() + ESCAPE_GRANT_TTL_SECONDS;
+        const surfacePath = normalizeWorkspaceRelPath(rel);
+        this.prune();
+        this.grants.set(token, { sessionId, profile, workspaceRoot, surfacePath, externalRoot, rootId: { dev, ino }, externalEntryRel: isDir ? '.' : basename(target), surfaceTarget: target, expiresAt });
+        return { token, path: surfacePath, is_dir: isDir, expires_at: expiresAt, expires_in: ESCAPE_GRANT_TTL_SECONDS, read_only: true };
+    }
+    /**
+     * Python `resolve_authorized_escape_request`: re-check the grant, then re-root a request path under the link onto
+     * the grant root. A path outside the link answers "Path traversal blocked".
+     */
+    resolve(workspace, sessionId, profile, token, rel) {
+        const grant = this.check(workspace, sessionId, profile, token);
+        const requestPath = normalizeWorkspaceRelPath(rel);
+        const under = grant.surfacePath === '.' ? requestPath : requestPath === grant.surfacePath ? '.' : requestPath.startsWith(`${grant.surfacePath}/`) ? requestPath.slice(grant.surfacePath.length + 1) : null;
+        if (under === null)
+            throw new PathTraversalError(`Path traversal blocked: ${rel}`);
+        const externalRel = grant.externalEntryRel === '.' ? under : under === '.' ? grant.externalEntryRel : `${grant.externalEntryRel}/${under}`;
+        return { surfacePath: grant.surfacePath, requestPath, externalRoot: grant.externalRoot, rootId: grant.rootId, externalRel };
+    }
+    /** Python `list_authorized_escape_dir`: entries re-pathed under the link; a target outside the grant root is dropped. */
+    list(req) {
+        const entries = anchoredAt(req, () => listDir(req.externalRoot, req.externalRel)).map((entry) => {
+            const out = { ...entry, path: virtualPath(req.surfacePath, entry.path), escape_read_only: true };
+            if (entry.target === undefined)
+                return out;
+            delete out.target;
+            if (isWithin(entry.target, req.externalRoot))
+                out.target = virtualPath(req.surfacePath, relative(req.externalRoot, entry.target) || '.');
+            return out;
+        });
+        return { path: req.requestPath, entries, signature: dirSignature(req.externalRoot, req.externalRel, entries), virtual_root: req.surfacePath, read_only: true };
+    }
+    /** Python `read_authorized_escape_file_content`, with the `/api/file` preview kind. */
+    read(req) {
+        return { ...anchoredAt(req, () => readFilePreview(req.externalRoot, req.externalRel)), path: req.requestPath, escape_read_only: true };
+    }
+    /** Python `raw_authorized_escape_target`: the file to serve, anchored at the grant root. */
+    rawTarget(req) {
+        return safeResolveWs(req.externalRoot, req.externalRel);
+    }
+    /** Python `_escape_authorization_record`: the link must still escape to the same reachable, non-system target and root inode. */
+    check(workspace, sessionId, profile, token) {
+        this.prune();
+        const grant = this.grants.get(token);
+        if (grant?.sessionId !== sessionId || grant.profile !== profile || grant.workspaceRoot !== resolvePathLikePython(workspace))
+            throw new EscapeGrantExpired();
+        try {
+            if (surfaceTarget(grant.workspaceRoot, grant.surfacePath) !== grant.surfaceTarget)
+                throw new EscapeGrantExpired();
+            const root = statSync(grant.externalRoot);
+            if (root.dev !== grant.rootId.dev || root.ino !== grant.rootId.ino)
+                throw new EscapeGrantExpired();
+        }
+        catch {
+            // A retargeted link kills the grant for good, even if it later points back.
+            this.grants.delete(token);
+            throw new EscapeGrantExpired();
+        }
+        return grant;
+    }
+    prune() {
+        const now = this.now();
+        for (const [token, grant] of this.grants)
+            if (grant.expiresAt <= now)
+                this.grants.delete(token);
+    }
+}
+//# sourceMappingURL=escape.js.map

package/dist/workspace/escape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape.js","sourceRoot":"","sources":["../../src/workspace/escape.ts"],"names":[],"mappings":"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"}

package/dist/workspace/extract.d.ts

@@ -0,0 +1,22 @@
+export declare const ARCHIVE_SUFFIXES: readonly [".zip", ".tar", ".tar.gz", ".tgz", ".tar.bz2", ".tbz2", ".tar.xz", ".txz"];
+/** A tiny archive of millions of empty members slips under the byte cap but exhausts inodes. */
+export declare const MAX_ARCHIVE_MEMBERS = 10000;
+/** Python `ValueError`: the archive was refused (format, slip, size, or member count). */
+export declare class ArchiveRejected extends Error {
+}
+/** Python `BadZipFile` / `TarError`: the archive could not be read. */
+export declare class CorruptArchive extends Error {
+}
+export interface Extraction {
+    extracted: number;
+    files: string[];
+    dest: string;
+}
+export declare function isArchiveName(name: string): boolean;
+/**
+ * Extract `bytes` into a new directory named for the archive under `parent`. `root` is the trusted directory (the
+ * workspace or the session inbox) that `parent` lives in; every directory and file is created by an anchored walk
+ * from it. The member count, total size, and every member path are checked before anything is created, and a failed
+ * write removes the partial directory. `files` are relative to `parent`.
+ */
+export declare function extractArchive(bytes: Buffer, filename: string, root: string, parent: string, cap: number): Promise<Extraction>;

package/dist/workspace/extract.js

@@ -0,0 +1,308 @@
+/**
+ * Archive extraction for `/api/upload/extract` and `/api/workspace/upload` (Python `extract_archive`). Zip and tar
+ * (plain, gzip, bzip2, xz) members land in a fresh `<parent>/<stem>` directory through the anchored exclusive create,
+ * so a slipped name or a symlinked component never writes outside it. Every decompressor stops once its output passes
+ * the extracted-bytes cap, and partial output is removed on any failure.
+ */
+import { closeSync, lstatSync } from 'node:fs';
+import { randomInt } from 'node:crypto';
+import { basename, join, relative } from 'node:path';
+import { gunzipSync } from 'node:zlib';
+import Bunzip from 'seek-bzip';
+import xzPkg from 'xz-decompress';
+import { writeFully } from '../fs/atomic.js';
+import { makeAnchoredDir, openAnchoredCreateFd, rmtreeAnchored, safeResolve } from './fs.js';
+import { resolvePathLikePython } from './paths.js';
+import { BadZipError, readZip } from './unzip.js';
+const { XzReadableStream } = xzPkg;
+export const ARCHIVE_SUFFIXES = ['.zip', '.tar', '.tar.gz', '.tgz', '.tar.bz2', '.tbz2', '.tar.xz', '.txz'];
+/** A tiny archive of millions of empty members slips under the byte cap but exhausts inodes. */
+export const MAX_ARCHIVE_MEMBERS = 10_000;
+/**
+ * A decompressed tar stream may exceed the file-byte cap only by its framing: each member costs a 512-byte header plus
+ * under 512 bytes of padding, and twice the member cap leaves room for directory and extended headers.
+ */
+const TAR_FRAMING_BYTES = 2 * MAX_ARCHIVE_MEMBERS * 1024;
+/** Python `ValueError`: the archive was refused (format, slip, size, or member count). */
+export class ArchiveRejected extends Error {
+}
+/** Python `BadZipFile` / `TarError`: the archive could not be read. */
+export class CorruptArchive extends Error {
+}
+export function isArchiveName(name) {
+    const lower = name.toLowerCase();
+    return ARCHIVE_SUFFIXES.some((suffix) => lower.endsWith(suffix));
+}
+/** Python `PurePath.stem`: the name without its last suffix (`a.tar.gz` -> `a.tar`, `.zip` -> `.zip`). */
+function pythonStem(name) {
+    const dot = name.lastIndexOf('.');
+    return dot > 0 && dot < name.length - 1 ? name.slice(0, dot) : name;
+}
+function lexists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function tooLarge(cap) {
+    return new ArchiveRejected(`Extraction too large (> ${String(Math.floor(cap / (1024 * 1024)))} MB limit). Possible zip bomb.`);
+}
+/**
+ * Extract `bytes` into a new directory named for the archive under `parent`. `root` is the trusted directory (the
+ * workspace or the session inbox) that `parent` lives in; every directory and file is created by an anchored walk
+ * from it. The member count, total size, and every member path are checked before anything is created, and a failed
+ * write removes the partial directory. `files` are relative to `parent`.
+ */
+export async function extractArchive(bytes, filename, root, parent, cap) {
+    const name = basename(filename);
+    const isZip = name.toLowerCase().endsWith('.zip');
+    if (!isZip && !isArchiveName(name))
+        throw new ArchiveRejected(`Unsupported archive format: ${filename}`);
+    const stem = pythonStem(name);
+    if (!stem || stem === '.' || stem === '..')
+        throw new ArchiveRejected(`Invalid archive name: ${filename}`);
+    const members = isZip ? zipMembers(bytes) : [...tarMembers(await decompressTar(bytes, cap + TAR_FRAMING_BYTES, cap))];
+    if (members.length > MAX_ARCHIVE_MEMBERS)
+        throw new ArchiveRejected(`Archive has too many files (> ${String(MAX_ARCHIVE_MEMBERS)}). Possible archive bomb.`);
+    // Declared sizes are binding: a zip member cannot inflate past its own, and a tar member is a slice of the stream.
+    if (members.reduce((sum, m) => sum + m.size, 0) > cap)
+        throw tooLarge(cap);
+    const parentResolved = resolvePathLikePython(parent);
+    let dest = join(parentResolved, stem);
+    for (let attempt = 0; lexists(dest); attempt += 1) {
+        if (attempt >= 1000)
+            throw new ArchiveRejected('Could not allocate a unique extraction directory');
+        dest = join(parentResolved, `${stem}_${String(randomInt(1000)).padStart(3, '0')}`);
+    }
+    const slip = isZip ? 'Zip' : 'Tar';
+    const plan = members.map((member) => {
+        let target;
+        try {
+            target = safeResolve(dest, member.name);
+        }
+        catch {
+            throw new ArchiveRejected(`${slip}-slip blocked: ${member.name}`);
+        }
+        if (target === dest)
+            throw new ArchiveRejected(`${slip}-slip blocked: ${member.name}`);
+        return { target, read: member.read };
+    });
+    makeAnchoredDir(root, dest);
+    try {
+        for (const { target, read } of plan) {
+            let data;
+            try {
+                data = read();
+            }
+            catch (error) {
+                throw error instanceof BadZipError ? new CorruptArchive(error.message) : error;
+            }
+            const fd = openAnchoredCreateFd(root, target);
+            try {
+                writeFully(fd, data);
+            }
+            finally {
+                closeSync(fd);
+            }
+        }
+    }
+    catch (error) {
+        try {
+            rmtreeAnchored(root, dest);
+        }
+        catch { /* the directory is already gone */ }
+        throw error;
+    }
+    return { extracted: plan.length, files: plan.map(({ target }) => relative(parentResolved, target)), dest };
+}
+function zipMembers(bytes) {
+    try {
+        return readZip(bytes).filter((entry) => !entry.isDir);
+    }
+    catch (error) {
+        throw error instanceof BadZipError ? new CorruptArchive(`File is not a zip file: ${error.message}`) : error;
+    }
+}
+/** The raw tar stream, decompressed by magic number like Python `tarfile.open(mode='r:*')`, never past `limit` bytes. */
+async function decompressTar(bytes, limit, cap) {
+    if (bytes[0] === 0x1f && bytes[1] === 0x8b) {
+        try {
+            return gunzipSync(bytes, { maxOutputLength: limit });
+        }
+        catch (error) {
+            if (error.code === 'ERR_BUFFER_TOO_LARGE')
+                throw tooLarge(cap);
+            throw new CorruptArchive('Invalid gzip data');
+        }
+    }
+    if (bytes.subarray(0, 3).toString('latin1') === 'BZh') {
+        let out = Buffer.allocUnsafe(64 * 1024);
+        let pos = 0;
+        const sink = {
+            writeByte(byte) {
+                if (pos >= limit)
+                    throw tooLarge(cap);
+                if (pos === out.length) {
+                    const grown = Buffer.allocUnsafe(Math.min(out.length * 2, limit));
+                    out.copy(grown);
+                    out = grown;
+                }
+                out[pos++] = byte;
+            },
+        };
+        try {
+            Bunzip.decode(bytes, sink, true);
+        }
+        catch (error) {
+            if (error instanceof ArchiveRejected)
+                throw error;
+            throw new CorruptArchive('Invalid bzip2 data');
+        }
+        return out.subarray(0, pos);
+    }
+    if (bytes.subarray(0, 6).equals(Buffer.from([0xfd, 0x37, 0x7a, 0x58, 0x5a, 0x00]))) {
+        const reader = new XzReadableStream(new Blob([bytes]).stream()).getReader();
+        const chunks = [];
+        let total = 0;
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                total += value.length;
+                if (total > limit) {
+                    await reader.cancel();
+                    throw tooLarge(cap);
+                }
+                chunks.push(Buffer.from(value));
+            }
+        }
+        catch (error) {
+            if (error instanceof ArchiveRejected)
+                throw error;
+            throw new CorruptArchive('Invalid xz data');
+        }
+        return Buffer.concat(chunks, total);
+    }
+    return bytes;
+}
+const BLOCK = 512;
+const REGULAR_TYPES = new Set(['0', '\0', '7']);
+/** Python `tarfile`: these member types carry no data blocks even when their size field is set. */
+const DATALESS_TYPES = new Set(['1', '2', '3', '4', '5', '6']);
+function cString(buf, start, length) {
+    const field = buf.subarray(start, start + length);
+    const nul = field.indexOf(0);
+    return (nul < 0 ? field : field.subarray(0, nul)).toString('utf8');
+}
+/** Python `tarfile.nti`: an octal field, or GNU base-256 when the high bit is set. */
+function tarNumber(header, start, length) {
+    const first = header[start] ?? 0;
+    if (first === 0o200) {
+        let n = 0;
+        for (let i = start + 1; i < start + length; i += 1)
+            n = n * 256 + (header[i] ?? 0);
+        return n;
+    }
+    if (first === 0o377)
+        throw new CorruptArchive('Invalid tar header');
+    const text = cString(header, start, length).trim();
+    if (!text)
+        return 0;
+    if (!/^[0-7]+$/.test(text))
+        throw new CorruptArchive('Invalid tar header');
+    return Number.parseInt(text, 8);
+}
+/** Python `tarfile.calc_chksums`: the stored checksum may be the unsigned or the signed byte sum. */
+function checksumOk(header) {
+    let unsigned = 256;
+    let signed = 256;
+    for (let i = 0; i < BLOCK; i += 1) {
+        if (i >= 148 && i < 156)
+            continue;
+        const byte = header[i] ?? 0;
+        unsigned += byte;
+        signed += byte > 127 ? byte - 256 : byte;
+    }
+    const stored = tarNumber(header, 148, 8);
+    return stored === unsigned || stored === signed;
+}
+function paxRecords(data) {
+    const records = new Map();
+    let pos = 0;
+    while (pos < data.length && data[pos] !== 0) {
+        const space = data.indexOf(0x20, pos);
+        const length = space < 0 ? Number.NaN : Number(data.subarray(pos, space).toString('latin1'));
+        if (!Number.isInteger(length) || length <= space - pos || pos + length > data.length || data[pos + length - 1] !== 0x0a)
+            throw new CorruptArchive('Invalid pax header');
+        const record = data.subarray(space + 1, pos + length - 1).toString('utf8');
+        const eq = record.indexOf('=');
+        if (eq < 0)
+            throw new CorruptArchive('Invalid pax header');
+        records.set(record.slice(0, eq), record.slice(eq + 1));
+        pos += length;
+    }
+    return records;
+}
+/** A small ustar/pax/GNU reader: yields regular-file members only (links, devices, and directories are skipped). */
+function* tarMembers(tar) {
+    if (tar.length < BLOCK)
+        throw new CorruptArchive('Invalid tar archive');
+    let offset = 0;
+    let longName = null;
+    let pax = new Map();
+    while (offset + BLOCK <= tar.length) {
+        const header = tar.subarray(offset, offset + BLOCK);
+        if (header.every((byte) => byte === 0))
+            return;
+        if (!checksumOk(header))
+            throw new CorruptArchive(offset === 0 ? 'Invalid tar archive' : 'Invalid tar header');
+        let name = cString(header, 0, 100);
+        if (header.subarray(257, 263).toString('latin1') === 'ustar\0') {
+            const prefix = cString(header, 345, 155);
+            if (prefix)
+                name = `${prefix}/${name}`;
+        }
+        let size = tarNumber(header, 124, 12);
+        let type = String.fromCharCode(header[156] ?? 0);
+        const dataStart = offset + BLOCK;
+        const padded = (n) => Math.ceil(n / BLOCK) * BLOCK;
+        if (type === 'x' || type === 'g' || type === 'L' || type === 'K') {
+            if (dataStart + size > tar.length)
+                throw new CorruptArchive('Unexpected end of tar data');
+            const data = tar.subarray(dataStart, dataStart + size);
+            if (type === 'x')
+                pax = paxRecords(data);
+            else if (type === 'L')
+                longName = cString(data, 0, data.length);
+            offset = dataStart + padded(size);
+            continue;
+        }
+        if (longName !== null)
+            name = longName;
+        const paxPath = pax.get('path');
+        if (paxPath !== undefined)
+            name = paxPath;
+        const paxSize = pax.get('size');
+        if (paxSize !== undefined) {
+            if (!/^\d+$/.test(paxSize))
+                throw new CorruptArchive('Invalid pax header');
+            size = Number(paxSize);
+        }
+        longName = null;
+        pax = new Map();
+        if (type === '\0' && name.endsWith('/'))
+            type = '5';
+        if (REGULAR_TYPES.has(type)) {
+            if (dataStart + size > tar.length)
+                throw new CorruptArchive('Unexpected end of tar data');
+            const data = tar.subarray(dataStart, dataStart + size);
+            yield { name, size, read: () => data };
+        }
+        offset = dataStart + (DATALESS_TYPES.has(type) ? 0 : padded(size));
+    }
+}
+//# sourceMappingURL=extract.js.map

package/dist/workspace/extract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../../src/workspace/extract.ts"],"names":[],"mappings":"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"}

package/dist/workspace/fs.d.ts

@@ -7,6 +7,11 @@ export declare class NotFoundError extends Error {
 export declare function safeResolveWs(root: string, requested: string): string;
 /** Python `helpers.safe_resolve`: same rule, different error text. */
 export declare function safeResolve(root: string, requested: string): string;
+/** Run `fn` with every anchored open of `root` refused unless the root is still the inode `id`. */
+export declare function withPinnedRoot<T>(root: string, id: {
+    dev: number;
+    ino: number;
+}, fn: () => T): T;
 /** Open `target` for reading with the anchored walk (Python `open_anchored_fd`). Caller closes the fd. */
 export declare function openAnchoredFd(root: string, target: string, opts: {
     wantDir: boolean;
@@ -20,6 +25,11 @@ export declare function openAnchoredWriteFd(root: string, target: string): numbe
 export declare function unlinkAnchored(root: string, target: string): void;
 /** Remove an empty directory through the anchored walk; a non-empty or symlinked target is left alone (throws). */
 export declare function rmdirAnchored(root: string, target: string): void;
+/**
+ * Remove a directory tree through the anchored walk (Python `shutil.rmtree(dir_fd=...)`): every directory is
+ * opened from its parent's descriptor with `O_NOFOLLOW` and emptied through its own, so an entry swapped for a
+ * symlink mid-walk is unlinked as a link and never followed.
+ */
 export declare function rmtreeAnchored(root: string, target: string): void;
 export declare function renameAnchored(root: string, source: string, dest: string): void;
 /**
@@ -59,6 +69,8 @@ export interface FileContent {
 }
 export declare class FileTooLargeError extends Error {
 }
+/** `raw` as UTF-8 text, or null for a binary file (a NUL byte, or bytes that do not round-trip). */
+export declare function decodeText(raw: Buffer): string | null;
 /** Python `read_file_content` (office previews were dropped with TAL-245). */
 export declare function readFileContent(workspace: string, rel: string, opts?: {
     statOnly?: boolean;