parasor 0.1.0

package/server/fs/media.js

@@ -0,0 +1,271 @@
+import { Buffer } from "node:buffer";
+import { open } from "node:fs/promises";
+const EXTENSION_MAP = {
+    png: { kind: "image", contentType: "image/png" },
+    jpg: { kind: "image", contentType: "image/jpeg" },
+    jpeg: { kind: "image", contentType: "image/jpeg" },
+    gif: { kind: "image", contentType: "image/gif" },
+    webp: { kind: "image", contentType: "image/webp" },
+    svg: { kind: "image", contentType: "image/svg+xml" },
+    avif: { kind: "image", contentType: "image/avif" },
+    bmp: { kind: "image", contentType: "image/bmp" },
+    ico: { kind: "image", contentType: "image/x-icon" },
+    mp4: { kind: "video", contentType: "video/mp4" },
+    webm: { kind: "video", contentType: "video/webm" },
+    mov: { kind: "video", contentType: "video/quicktime" },
+    mp3: { kind: "audio", contentType: "audio/mpeg" },
+    wav: { kind: "audio", contentType: "audio/wav" },
+    ogg: { kind: "audio", contentType: "audio/ogg" },
+    m4a: { kind: "audio", contentType: "audio/mp4" },
+    pdf: { kind: "pdf", contentType: "application/pdf" },
+};
+const SIGNATURES = [
+    // PNG
+    {
+        bytes: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a],
+        result: { kind: "image", contentType: "image/png" },
+    },
+    // JPEG (FF D8 FF ..)
+    {
+        bytes: [0xff, 0xd8, 0xff],
+        result: { kind: "image", contentType: "image/jpeg" },
+    },
+    // GIF87a / GIF89a
+    {
+        bytes: [0x47, 0x49, 0x46, 0x38, 0x37, 0x61],
+        result: { kind: "image", contentType: "image/gif" },
+    },
+    {
+        bytes: [0x47, 0x49, 0x46, 0x38, 0x39, 0x61],
+        result: { kind: "image", contentType: "image/gif" },
+    },
+    // BMP
+    {
+        bytes: [0x42, 0x4d],
+        result: { kind: "image", contentType: "image/bmp" },
+    },
+    // ICO (00 00 01 00)
+    {
+        bytes: [0x00, 0x00, 0x01, 0x00],
+        result: { kind: "image", contentType: "image/x-icon" },
+    },
+    // PDF "%PDF-"
+    {
+        bytes: [0x25, 0x50, 0x44, 0x46, 0x2d],
+        result: { kind: "pdf", contentType: "application/pdf" },
+    },
+    // MP3 (ID3 header)
+    {
+        bytes: [0x49, 0x44, 0x33],
+        result: { kind: "audio", contentType: "audio/mpeg" },
+    },
+    // OGG
+    {
+        bytes: [0x4f, 0x67, 0x67, 0x53],
+        result: { kind: "audio", contentType: "audio/ogg" },
+    },
+];
+function bytesMatch(buf, sig) {
+    if (buf.length < sig.bytes.length)
+        return false;
+    for (let i = 0; i < sig.bytes.length; i++) {
+        const expected = sig.bytes[i];
+        if (expected === null)
+            continue;
+        if (buf[i] !== expected)
+            return false;
+    }
+    return true;
+}
+function isWebpSignature(buf) {
+    if (buf.length < 12)
+        return false;
+    return (buf[0] === 0x52 &&
+        buf[1] === 0x49 &&
+        buf[2] === 0x46 &&
+        buf[3] === 0x46 &&
+        buf[8] === 0x57 &&
+        buf[9] === 0x45 &&
+        buf[10] === 0x42 &&
+        buf[11] === 0x50);
+}
+function isWavSignature(buf) {
+    if (buf.length < 12)
+        return false;
+    return (buf[0] === 0x52 &&
+        buf[1] === 0x49 &&
+        buf[2] === 0x46 &&
+        buf[3] === 0x46 &&
+        buf[8] === 0x57 &&
+        buf[9] === 0x41 &&
+        buf[10] === 0x56 &&
+        buf[11] === 0x45);
+}
+function isAvifSignature(buf) {
+    if (buf.length < 12)
+        return false;
+    // ISO BMFF "ftyp" at offset 4, brand at offset 8 = "avif" or "avis"
+    if (buf[4] !== 0x66 || buf[5] !== 0x74 || buf[6] !== 0x79 || buf[7] !== 0x70)
+        return false;
+    const brand = String.fromCharCode(buf[8], buf[9], buf[10], buf[11]);
+    return brand === "avif" || brand === "avis";
+}
+function isMp4Signature(buf) {
+    if (buf.length < 12)
+        return false;
+    if (buf[4] !== 0x66 || buf[5] !== 0x74 || buf[6] !== 0x79 || buf[7] !== 0x70)
+        return false;
+    const brand = String.fromCharCode(buf[8], buf[9], buf[10], buf[11]);
+    // common MP4 brands
+    return [
+        "isom",
+        "iso2",
+        "iso3",
+        "iso4",
+        "iso5",
+        "iso6",
+        "mp41",
+        "mp42",
+        "avc1",
+        "M4V ",
+        "MSNV",
+        "dash",
+    ].includes(brand);
+}
+function isMovSignature(buf) {
+    if (buf.length < 12)
+        return false;
+    if (buf[4] !== 0x66 || buf[5] !== 0x74 || buf[6] !== 0x79 || buf[7] !== 0x70)
+        return false;
+    const brand = String.fromCharCode(buf[8], buf[9], buf[10], buf[11]);
+    return brand === "qt  ";
+}
+function isWebmSignature(buf) {
+    // EBML header used by Matroska/WebM
+    return (buf.length >= 4 &&
+        buf[0] === 0x1a &&
+        buf[1] === 0x45 &&
+        buf[2] === 0xdf &&
+        buf[3] === 0xa3);
+}
+function isM4aSignature(buf) {
+    if (buf.length < 12)
+        return false;
+    if (buf[4] !== 0x66 || buf[5] !== 0x74 || buf[6] !== 0x79 || buf[7] !== 0x70)
+        return false;
+    const brand = String.fromCharCode(buf[8], buf[9], buf[10], buf[11]);
+    return brand === "M4A " || brand === "mp42";
+}
+function isSvgText(buf) {
+    // SVG is text -- accept either `<?xml` or a leading `<svg` (allowing BOM and whitespace).
+    if (buf.length === 0)
+        return false;
+    let i = 0;
+    // strip UTF-8 BOM
+    if (buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf)
+        i = 3;
+    // skip ASCII whitespace
+    while (i < buf.length &&
+        (buf[i] === 0x20 || buf[i] === 0x09 || buf[i] === 0x0a || buf[i] === 0x0d)) {
+        i++;
+    }
+    if (i >= buf.length)
+        return false;
+    const slice = buf.subarray(i, Math.min(buf.length, i + 16)).toString("utf8");
+    return slice.startsWith("<?xml") || slice.toLowerCase().startsWith("<svg");
+}
+function getExtension(absPath) {
+    const idx = absPath.lastIndexOf(".");
+    if (idx < 0)
+        return "";
+    return absPath.slice(idx + 1).toLowerCase();
+}
+/**
+ * Identify a media file by its first 32 bytes plus extension. Magic-number
+ * match wins; if the magic match disagrees with the extension, the magic
+ * match is authoritative. SVG sniff is conservative -- only accepted when the
+ * extension claims SVG so a plain XML file is not mis-classified.
+ */
+export async function detectMedia(absPath) {
+    const fh = await open(absPath, "r");
+    try {
+        return await detectMediaFromHandle(fh, absPath);
+    }
+    finally {
+        await fh.close();
+    }
+}
+/**
+ * Same magic-number + extension pipeline as `detectMedia`, but reads through
+ * a caller-owned `FileHandle`. Use this when the route layer has already
+ * `O_NOFOLLOW`-opened the file and needs detection, size validation, and
+ * streaming all anchored to the same inode (so a leaf swap between checks
+ * cannot bypass the size cap or content-type lock). Caller retains ownership
+ * of the handle.
+ */
+export async function detectMediaFromHandle(handle, pathHint) {
+    const ext = getExtension(pathHint);
+    const head = Buffer.alloc(32);
+    const { bytesRead } = await handle.read(head, 0, 32, 0);
+    const buf = head.subarray(0, bytesRead);
+    return classify(buf, ext);
+}
+/**
+ * Pure classifier so tests can hand it raw bytes without touching disk.
+ * Exposed for unit testing -- `detectMedia` is the production entry point.
+ */
+export function classify(buf, ext) {
+    // Magic-number passes (specific shapes first)
+    if (isWebpSignature(buf))
+        return { kind: "image", contentType: "image/webp" };
+    if (isAvifSignature(buf))
+        return { kind: "image", contentType: "image/avif" };
+    if (isMovSignature(buf))
+        return { kind: "video", contentType: "video/quicktime" };
+    if (isMp4Signature(buf))
+        return { kind: "video", contentType: "video/mp4" };
+    if (isM4aSignature(buf))
+        return { kind: "audio", contentType: "audio/mp4" };
+    if (isWebmSignature(buf))
+        return { kind: "video", contentType: "video/webm" };
+    if (isWavSignature(buf))
+        return { kind: "audio", contentType: "audio/wav" };
+    for (const sig of SIGNATURES) {
+        if (bytesMatch(buf, sig))
+            return { ...sig.result };
+    }
+    // SVG only when extension agrees and content looks like SVG/XML
+    if (ext === "svg" && isSvgText(buf)) {
+        return { kind: "image", contentType: "image/svg+xml" };
+    }
+    // Extension-only fallback for audio/video formats whose containers we did
+    // not match (e.g. bare-frame MP3 without ID3 header). Images and PDFs are
+    // intentionally NOT accepted via fallback: their magic numbers are
+    // reliable, and a misclassified text/binary file rendered as an image is
+    // a much smaller foothold than rendered as a video. Restricted to the
+    // explicit whitelist below so the route never serves arbitrary bytes.
+    const FALLBACK_OK = new Set([
+        "mp3",
+        "m4a",
+        "ogg",
+        "wav",
+        "mp4",
+        "webm",
+        "mov",
+    ]);
+    if (FALLBACK_OK.has(ext)) {
+        const fallback = EXTENSION_MAP[ext];
+        if (fallback)
+            return { ...fallback };
+    }
+    return { kind: null, contentType: null };
+}
+/**
+ * Lightweight extension-only check. Used by the route for the cheap
+ * pre-filter before opening the file (so we never read an executable just
+ * to learn it isn't media).
+ */
+export function isMediaExtension(absPath) {
+    return getExtension(absPath) in EXTENSION_MAP;
+}
+//# sourceMappingURL=media.js.map

package/server/fs/media.js.map

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

package/server/fs/service.d.ts

@@ -0,0 +1,97 @@
+import type { ReadStream, Stats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+export interface FileEntry {
+    name: string;
+    path: string;
+    type: "file" | "directory";
+    isGitignored?: boolean;
+    isHidden?: boolean;
+}
+export declare class PathTraversalError extends Error {
+    constructor();
+}
+export declare class CopySourceNotFoundError extends Error {
+    constructor();
+}
+export declare class CopyDestinationExistsError extends Error {
+    constructor();
+}
+export declare class FilesystemService {
+    private readonly projectRoot;
+    private ignoreInstance;
+    constructor(projectRoot: string);
+    listDir(relPath: string): Promise<FileEntry[]>;
+    readFile(relPath: string, maxBytes?: number): Promise<string | null>;
+    /**
+     * Stat a single file, returning `null` when missing. Wraps node `stat()`
+     * to surface `PathTraversalError` consistently and never leak ENOENT
+     * details to the route layer.
+     */
+    statFile(relPath: string): Promise<Stats | null>;
+    /**
+     * Open a regular file inside the project root for inline media serving.
+     * The leaf is opened with `O_NOFOLLOW` so a symlink swapped in between
+     * the parent-directory resolve and this open cannot redirect to a target
+     * outside the project tree. The returned `FileHandle` is the single
+     * authoritative reference: callers do `fstat`, magic-number sniff via
+     * `read`, and stream creation through the same handle so size limits and
+     * content-type detection apply to the exact bytes about to be served.
+     * The caller MUST `close()` the handle (or pass it to `createReadStream`
+     * with `autoClose: true`).
+     *
+     * `O_NONBLOCK` keeps `open()` from blocking when the path happens to be a
+     * FIFO/socket/character device (a `*.mp4` FIFO in a cloned repo would
+     * otherwise pin a libuv worker until a writer connects); the post-open
+     * `isFile()` check then rejects everything that isn't a regular file.
+     *
+     * `O_NOFOLLOW` only protects the leaf -- an attacker with FS write access
+     * can still swap a parent directory to a symlink between `resolve()`'s
+     * realpath check and this `open()`. We close that gap by re-resolving the
+     * path *after* open and comparing the canonical result's inode to the
+     * fd's inode. A mid-open swap leaves the fd bound to a file outside the
+     * project tree while the second realpath resolves to the legitimate
+     * (or missing) in-tree entry, so the inodes diverge and we reject.
+     *
+     * Returns `null` for ENOENT so missing files surface as 404 rather than
+     * leaking the absolute path. ELOOP (the leaf was a symlink) raises a
+     * `PathTraversalError` because following symlinks at the leaf is exactly
+     * what we are refusing.
+     */
+    openInlineFile(relPath: string): Promise<{
+        handle: FileHandle;
+        stats: Stats;
+    } | null>;
+    /**
+     * Build a read stream from an already-open `FileHandle`, optionally clamped
+     * to a byte range. Uses `FileHandle.createReadStream` with `autoClose: true`
+     * so stream ownership of the handle is explicit -- closing the stream
+     * releases the underlying fd through the FileHandle, avoiding the
+     * double-close hazard of passing the raw `handle.fd` to `createReadStream`
+     * (where the FileHandle's own GC finalizer could close an fd the stream
+     * already returned to the OS). Pairs with `openInlineFile` -- callers must
+     * not reuse the handle after this call returns.
+     */
+    createStreamFromHandle(handle: FileHandle, size: number, range?: {
+        start: number;
+        end: number;
+    }): {
+        stream: ReadStream;
+        start: number;
+        end: number;
+    };
+    writeFile(relPath: string, content: string): Promise<void>;
+    mkdir(relPath: string): Promise<void>;
+    /**
+     * Recursive copy of a file or directory inside the project root. Both
+     * sides are routed through `resolve()` so symlink-escape and `..` traversal
+     * remain blocked. Refuses to overwrite an existing destination -- callers
+     * pick a unique name (Finder-style "<n> copy", "<n> copy 2") before invoking.
+     */
+    cp(srcRelPath: string, destRelPath: string): Promise<void>;
+    reloadIgnore(): void;
+    isIgnored(relPath: string, isDir: boolean): boolean;
+    private resolve;
+    private loadIgnore;
+    private isIgnoredWith;
+}
+//# sourceMappingURL=service.d.ts.map

package/server/fs/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/fs/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAOjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAgCnD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,qBAAa,kBAAmB,SAAQ,KAAK;;CAK5C;AAED,qBAAa,uBAAwB,SAAQ,KAAK;;CAKjD;AAED,qBAAa,0BAA2B,SAAQ,KAAK;;CAKpD;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,cAAc,CAAS;gBAEnB,WAAW,EAAE,MAAM;IAUzB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAkC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAkB1E;;;;OAIG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;IAUtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,cAAc,CAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QAAE,MAAM,EAAE,UAAU,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,GAAG,IAAI,CAAC;IAmDvD;;;;;;;;;OASG;IACH,sBAAsB,CACpB,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GACrC;QAAE,MAAM,EAAE,UAAU,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;IAc/C,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS1D,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK3C;;;;;OAKG;IACG,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBhE,YAAY,IAAI,IAAI;IAIpB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO;IAKnD,OAAO,CAAC,OAAO;IAyBf,OAAO,CAAC,UAAU;IAelB,OAAO,CAAC,aAAa;CAItB"}