@av-pi-studio/server 0.0.1

package/dist/files/file-explorer.d.ts

@@ -0,0 +1,54 @@
+import type { HandlerRegistry } from "../ws/router.js";
+export interface DirEntry {
+    name: string;
+    kind: "file" | "directory" | "symlink" | "other";
+    size: number;
+    mtimeMs: number;
+    /** Lightweight icon hint (extension or "dir"); full theme mapping is a client concern. */
+    iconHint: string;
+}
+export type FileExplorerResult = {
+    ok: true;
+    kind: "directory";
+    path: string;
+    resolvedPath: string;
+    entries: DirEntry[];
+} | {
+    ok: true;
+    kind: "text";
+    path: string;
+    resolvedPath: string;
+    content: string;
+    truncated: boolean;
+} | {
+    ok: true;
+    kind: "binary";
+    path: string;
+    resolvedPath: string;
+    metadata: {
+        size: number;
+        mtimeMs: number;
+        mimeHint: string;
+    };
+    transferToken: string;
+} | {
+    ok: false;
+    error: string;
+};
+export interface FileExplorerDeps {
+    /** Issue a download token for a binary file (task-005 supplies the real store). */
+    issueDownloadToken?: (resolvedPath: string) => string;
+    previewBytes?: number;
+}
+export declare class FileExplorerService {
+    private readonly deps;
+    constructor(deps?: FileExplorerDeps);
+    registerHandlers(registry: HandlerRegistry): void;
+    /** Normalize + resolve a path (symlinks), then list a directory or preview a file. */
+    listOrPreview(inputPath: string): Promise<FileExplorerResult>;
+    private readDirectory;
+    private previewFile;
+    /** Immediate subdirectory paths under `base` (path picker). */
+    directorySuggestions(base: string): Promise<string[]>;
+}
+//# sourceMappingURL=file-explorer.d.ts.map

package/dist/files/file-explorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-explorer.d.ts","sourceRoot":"","sources":["../../src/files/file-explorer.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAavD,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,QAAQ,EAAE,CAAA;CAAE,GACxF;IACE,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB,GACD;IACE,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,aAAa,EAAE,MAAM,CAAC;CACvB,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC,MAAM,WAAW,gBAAgB;IAC/B,mFAAmF;IACnF,kBAAkB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,mBAAmB;IAClB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,GAAE,gBAAqB;IAExD,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAqBjD,sFAAsF;IAChF,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;YAgCrD,aAAa;YAmCb,WAAW;IA8CzB,+DAA+D;IACzD,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAa5D"}

package/dist/files/file-explorer.js

@@ -0,0 +1,182 @@
+import { randomUUID } from "node:crypto";
+import { open, readdir, realpath, stat } from "node:fs/promises";
+import { basename, extname, join, resolve } from "node:path";
+/**
+ * File explorer: directory listing + file preview with server-side path normalization and symlink
+ * resolution (features/file-explorer-transfer.md § Behavior (listOrPreview), § Trust boundary;
+ * architecture/auth-security.md § Trust model). Connected clients are trusted operators — a preview
+ * may read any regular file the daemon can read; workspace-relative paths are a UI convenience, not a
+ * security boundary. Normalization/symlink checks stay server-side.
+ */
+const DEFAULT_PREVIEW_BYTES = 256 * 1024;
+const BINARY_SNIFF_BYTES = 8192;
+export class FileExplorerService {
+    deps;
+    constructor(deps = {}) {
+        this.deps = deps;
+    }
+    registerHandlers(registry) {
+        registry.register("file_explorer_request", async (ctx) => ({
+            type: "file_explorer_response",
+            result: await this.listOrPreview(String(ctx.message.path ?? "")),
+        }));
+        registry.register("directory_suggestions_request", async (ctx) => ({
+            type: "directory_suggestions_response",
+            base: String(ctx.message.path ?? ctx.message.base ?? ""),
+            suggestions: await this.directorySuggestions(String(ctx.message.path ?? ctx.message.base ?? "")),
+        }));
+        registry.register("project_icon_request", (ctx) => ({
+            type: "project_icon_response",
+            projectId: String(ctx.message.projectId ?? ""),
+            icon: null, // resolution mechanism TODO(verify)
+        }));
+    }
+    /** Normalize + resolve a path (symlinks), then list a directory or preview a file. */
+    async listOrPreview(inputPath) {
+        if (!inputPath)
+            return { ok: false, error: "empty_path" };
+        const normalized = resolve(inputPath);
+        let resolvedPath;
+        try {
+            resolvedPath = await realpath(normalized); // server-side symlink resolution
+        }
+        catch {
+            return { ok: false, error: "not_found" };
+        }
+        let info;
+        try {
+            info = await stat(resolvedPath);
+        }
+        catch {
+            return { ok: false, error: "unreadable" };
+        }
+        if (info.isDirectory()) {
+            try {
+                const entries = await this.readDirectory(resolvedPath);
+                return { ok: true, kind: "directory", path: inputPath, resolvedPath, entries };
+            }
+            catch {
+                return { ok: false, error: "unreadable" };
+            }
+        }
+        if (!info.isFile())
+            return { ok: false, error: "unsupported" };
+        return this.previewFile(inputPath, resolvedPath, info.size, info.mtimeMs);
+    }
+    async readDirectory(dir) {
+        const dirents = await readdir(dir, { withFileTypes: true });
+        const entries = [];
+        for (const dirent of dirents) {
+            const full = join(dir, dirent.name);
+            let size = 0;
+            let mtimeMs = 0;
+            try {
+                const s = await stat(full);
+                size = s.size;
+                mtimeMs = s.mtimeMs;
+            }
+            catch {
+                // Unstattable entry (e.g. broken symlink) → keep with zeroed metadata.
+            }
+            const kind = dirent.isDirectory()
+                ? "directory"
+                : dirent.isSymbolicLink()
+                    ? "symlink"
+                    : dirent.isFile()
+                        ? "file"
+                        : "other";
+            entries.push({
+                name: dirent.name,
+                kind,
+                size,
+                mtimeMs,
+                iconHint: kind === "directory" ? "dir" : iconHintForFile(dirent.name),
+            });
+        }
+        return entries.toSorted((a, b) => {
+            if (a.kind !== b.kind)
+                return a.kind === "directory" ? -1 : b.kind === "directory" ? 1 : 0;
+            return a.name.localeCompare(b.name);
+        });
+    }
+    async previewFile(inputPath, resolvedPath, size, mtimeMs) {
+        const previewBytes = this.deps.previewBytes ?? DEFAULT_PREVIEW_BYTES;
+        let handle;
+        try {
+            handle = await open(resolvedPath, "r");
+        }
+        catch {
+            return { ok: false, error: "unreadable" };
+        }
+        try {
+            const sniffLen = Math.min(size, BINARY_SNIFF_BYTES);
+            const sniff = Buffer.alloc(sniffLen);
+            if (sniffLen > 0)
+                await handle.read(sniff, 0, sniffLen, 0);
+            if (isBinary(sniff)) {
+                const transferToken = this.deps.issueDownloadToken?.(resolvedPath) ?? randomUUID();
+                return {
+                    ok: true,
+                    kind: "binary",
+                    path: inputPath,
+                    resolvedPath,
+                    metadata: { size, mtimeMs, mimeHint: mimeHintForFile(resolvedPath) },
+                    transferToken,
+                };
+            }
+            const readLen = Math.min(size, previewBytes);
+            const buffer = Buffer.alloc(readLen);
+            if (readLen > 0)
+                await handle.read(buffer, 0, readLen, 0);
+            return {
+                ok: true,
+                kind: "text",
+                path: inputPath,
+                resolvedPath,
+                content: buffer.toString("utf8"),
+                truncated: size > previewBytes,
+            };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    /** Immediate subdirectory paths under `base` (path picker). */
+    async directorySuggestions(base) {
+        if (!base)
+            return [];
+        try {
+            const resolved = await realpath(resolve(base));
+            const dirents = await readdir(resolved, { withFileTypes: true });
+            return dirents
+                .filter((d) => d.isDirectory() && !d.name.startsWith("."))
+                .map((d) => join(resolved, d.name))
+                .toSorted((a, b) => basename(a).localeCompare(basename(b)));
+        }
+        catch {
+            return [];
+        }
+    }
+}
+/** A buffer is treated as binary if it contains a NUL byte in the sniffed prefix. */
+function isBinary(sniff) {
+    return sniff.includes(0);
+}
+function iconHintForFile(name) {
+    const ext = extname(name).slice(1).toLowerCase();
+    return ext || "file";
+}
+function mimeHintForFile(path) {
+    const ext = extname(path).slice(1).toLowerCase();
+    const map = {
+        png: "image/png",
+        jpg: "image/jpeg",
+        jpeg: "image/jpeg",
+        gif: "image/gif",
+        pdf: "application/pdf",
+        zip: "application/zip",
+        wasm: "application/wasm",
+    };
+    return map[ext] ?? "application/octet-stream";
+}
+//# sourceMappingURL=file-explorer.js.map

package/dist/files/file-explorer.js.map

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

package/dist/files/file-transfer.d.ts

@@ -0,0 +1,30 @@
+import type { BinaryHandler, HandlerRegistry } from "../ws/router.js";
+import { DownloadTokenStore } from "./download-token-store.js";
+export interface FileTransferDeps {
+    tokenStore?: DownloadTokenStore;
+    chunkBytes?: number;
+}
+export declare class FileTransferService {
+    readonly tokenStore: DownloadTokenStore;
+    private readonly chunkBytes;
+    /** Pending uploads keyed by stream number. */
+    private readonly uploads;
+    private nextStream;
+    constructor(deps?: FileTransferDeps);
+    /** Issue a download token for a resolved path (also used by the file explorer for binary files). */
+    issueDownloadToken: (resolvedPath: string) => string;
+    registerHandlers(registry: HandlerRegistry): void;
+    /**
+     * Validate + consume the token, then stream the file as `Begin → Chunk* → End` binary frames.
+     */
+    startDownload(token: string, stream: number, sink: (frame: Uint8Array) => void): Promise<{
+        ok: boolean;
+        error?: string;
+        transferId?: string;
+    }>;
+    /** Binary frame handler for upload streams (Begin → Chunk* → End). Frames are serialized per
+     * stream so an in-flight `Begin` (open) completes before any `Chunk` writes. */
+    binaryHandler(): BinaryHandler;
+    private handleUploadFrame;
+}
+//# sourceMappingURL=file-transfer.d.ts.map

package/dist/files/file-transfer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-transfer.d.ts","sourceRoot":"","sources":["../../src/files/file-transfer.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAU/D,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAWD,qBAAa,mBAAmB;IAC9B,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,OAAO,CAAC,UAAU,CAAK;gBAEX,IAAI,GAAE,gBAAqB;IAKvC,oGAAoG;IACpG,kBAAkB,GAAI,cAAc,MAAM,KAAG,MAAM,CAA8C;IAEjG,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAwCjD;;OAEG;IACG,aAAa,CACjB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAChC,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IA6BhE;oFACgF;IAChF,aAAa,IAAI,aAAa;YAUhB,iBAAiB;CA6BhC"}

package/dist/files/file-transfer.js

@@ -0,0 +1,132 @@
+import { createReadStream } from "node:fs";
+import { mkdir, open, realpath } from "node:fs/promises";
+import { basename, dirname } from "node:path";
+import { encodeFileTransferFrame, tryDecodeFileTransferFrame, } from "@av-pi-studio/protocol";
+import { DownloadTokenStore } from "./download-token-store.js";
+/**
+ * Chunked file download (token-authorized) + upload over the file-transfer binary frame format
+ * (features/file-explorer-transfer.md § Binary transfer frames, § Behavior). Downloads stream
+ * `Begin → Chunk* → End`; uploads consume the same frames and write to the target path.
+ */
+const DEFAULT_CHUNK_BYTES = 32 * 1024;
+export class FileTransferService {
+    tokenStore;
+    chunkBytes;
+    /** Pending uploads keyed by stream number. */
+    uploads = new Map();
+    nextStream = 1;
+    constructor(deps = {}) {
+        this.tokenStore = deps.tokenStore ?? new DownloadTokenStore();
+        this.chunkBytes = deps.chunkBytes ?? DEFAULT_CHUNK_BYTES;
+    }
+    /** Issue a download token for a resolved path (also used by the file explorer for binary files). */
+    issueDownloadToken = (resolvedPath) => this.tokenStore.issue(resolvedPath).token;
+    registerHandlers(registry) {
+        registry.register("file_download_token_request", async (ctx) => {
+            const path = String(ctx.message.path ?? "");
+            let resolved;
+            try {
+                resolved = await realpath(path);
+            }
+            catch {
+                return { type: "file_download_token_response", ok: false, error: "not_found" };
+            }
+            const { token, expiresAt } = this.tokenStore.issue(resolved);
+            return { type: "file_download_token_response", ok: true, token, expiresAt };
+        });
+        registry.register("file_download_request", async (ctx) => {
+            const token = String(ctx.message.token ?? "");
+            const stream = Number(ctx.message.stream ?? this.nextStream++);
+            const result = await this.startDownload(token, stream, (frame) => ctx.session.sendBinary(frame));
+            return { type: "file_download_response", stream, ...result };
+        });
+        registry.register("file_upload_request", (ctx) => {
+            const targetPath = String(ctx.message.path ?? "");
+            const transferId = String(ctx.message.transferId ?? "");
+            if (!targetPath || !transferId) {
+                return { type: "file_upload_response", ok: false, error: "missing_fields" };
+            }
+            const stream = this.nextStream++;
+            this.uploads.set(stream, {
+                transferId,
+                targetPath,
+                handle: null,
+                bytesWritten: 0,
+                chain: Promise.resolve(),
+            });
+            return { type: "file_upload_response", ok: true, stream };
+        });
+    }
+    /**
+     * Validate + consume the token, then stream the file as `Begin → Chunk* → End` binary frames.
+     */
+    async startDownload(token, stream, sink) {
+        const path = this.tokenStore.consume(token);
+        if (!path)
+            return { ok: false, error: "invalid_or_expired_token" };
+        const transferId = `dl-${stream}-${Date.now()}`;
+        sink(encodeFileTransferFrame({
+            opcode: "Begin",
+            stream,
+            meta: { transferId, fileName: basename(path) },
+        }));
+        await new Promise((resolve, reject) => {
+            const rs = createReadStream(path, { highWaterMark: this.chunkBytes });
+            rs.on("data", (chunk) => {
+                const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+                sink(encodeFileTransferFrame({ opcode: "Chunk", stream, data: new Uint8Array(bytes) }));
+            });
+            rs.on("end", () => resolve());
+            rs.on("error", reject);
+        }).catch(() => {
+            sink(encodeFileTransferFrame({ opcode: "Error", stream, message: "read_failed" }));
+        });
+        sink(encodeFileTransferFrame({ opcode: "End", stream, ok: true }));
+        return { ok: true, transferId };
+    }
+    /** Binary frame handler for upload streams (Begin → Chunk* → End). Frames are serialized per
+     * stream so an in-flight `Begin` (open) completes before any `Chunk` writes. */
+    binaryHandler() {
+        return (_session, bytes) => {
+            const frame = tryDecodeFileTransferFrame(bytes);
+            if (!frame)
+                return;
+            const upload = this.uploads.get(frame.stream);
+            if (!upload)
+                return; // unknown/closed stream
+            upload.chain = upload.chain.then(() => this.handleUploadFrame(frame));
+        };
+    }
+    async handleUploadFrame(frame) {
+        const upload = this.uploads.get(frame.stream);
+        if (!upload)
+            return; // unknown/closed stream
+        switch (frame.opcode) {
+            case "Begin": {
+                if (frame.meta.transferId !== upload.transferId)
+                    return; // mismatched transfer
+                await mkdir(dirname(upload.targetPath), { recursive: true });
+                upload.handle = await open(upload.targetPath, "w");
+                return;
+            }
+            case "Chunk": {
+                if (!upload.handle)
+                    return;
+                await upload.handle.write(Buffer.from(frame.data));
+                upload.bytesWritten += frame.data.length;
+                return;
+            }
+            case "End": {
+                await upload.handle?.close();
+                this.uploads.delete(frame.stream);
+                return;
+            }
+            case "Error": {
+                await upload.handle?.close();
+                this.uploads.delete(frame.stream);
+                return;
+            }
+        }
+    }
+}
+//# sourceMappingURL=file-transfer.js.map

package/dist/files/file-transfer.js.map

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

package/dist/files/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./file-explorer.js";
+export * from "./download-token-store.js";
+export * from "./file-transfer.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/files/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/files/index.ts"],"names":[],"mappings":"AACA,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oBAAoB,CAAC"}

package/dist/files/index.js

@@ -0,0 +1,5 @@
+// File explorer (list/preview + path safety) and binary file transfer.
+export * from "./file-explorer.js";
+export * from "./download-token-store.js";
+export * from "./file-transfer.js";
+//# sourceMappingURL=index.js.map

package/dist/files/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/files/index.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oBAAoB,CAAC"}

package/dist/http/host-allowlist.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Host-header allowlist — DNS-rebinding defense (architecture/auth-security.md § Host-header
+ * allowlist). Vite-style: `localhost`, `*.localhost`, and any literal IP are always allowed;
+ * `hostnames` extends the list (a `.`-prefixed entry matches a domain and its subdomains); the
+ * literal value `true` disables validation entirely.
+ */
+export type HostnamesSetting = true | string[];
+/** Extract the bare hostname (lowercased, port + IPv6 brackets stripped) from a Host header. */
+export declare function parseHostHeader(hostHeader: string | undefined): string | null;
+/**
+ * Build a Host-header checker for the given `hostnames` setting. Returns a predicate over the raw
+ * Host header value.
+ */
+export declare function createHostChecker(hostnames: HostnamesSetting): (hostHeader: string | undefined) => boolean;
+//# sourceMappingURL=host-allowlist.d.ts.map

package/dist/http/host-allowlist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-allowlist.d.ts","sourceRoot":"","sources":["../../src/http/host-allowlist.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,MAAM,EAAE,CAAC;AAE/C,gGAAgG;AAChG,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAe7E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,gBAAgB,GAC1B,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAwB7C"}

package/dist/http/host-allowlist.js

@@ -0,0 +1,52 @@
+import { isIP } from "node:net";
+/** Extract the bare hostname (lowercased, port + IPv6 brackets stripped) from a Host header. */
+export function parseHostHeader(hostHeader) {
+    if (!hostHeader)
+        return null;
+    const value = hostHeader.trim();
+    if (value.length === 0)
+        return null;
+    // IPv6 literal: [::1] or [::1]:6767
+    const bracket = value.match(/^\[(.+)\](?::\d+)?$/);
+    if (bracket)
+        return bracket[1].toLowerCase();
+    // Strip a trailing :port (only when it is numeric).
+    const idx = value.lastIndexOf(":");
+    if (idx !== -1 && /^\d+$/.test(value.slice(idx + 1))) {
+        return value.slice(0, idx).toLowerCase();
+    }
+    return value.toLowerCase();
+}
+/**
+ * Build a Host-header checker for the given `hostnames` setting. Returns a predicate over the raw
+ * Host header value.
+ */
+export function createHostChecker(hostnames) {
+    if (hostnames === true)
+        return () => true;
+    const extra = hostnames.map((h) => h.trim().toLowerCase()).filter((h) => h.length > 0);
+    return (hostHeader) => {
+        const host = parseHostHeader(hostHeader);
+        if (host === null)
+            return false;
+        // Always-allowed: localhost, *.localhost, and any literal IP (v4/v6).
+        if (host === "localhost" || host.endsWith(".localhost"))
+            return true;
+        if (isIP(host) !== 0)
+            return true;
+        for (const entry of extra) {
+            if (entry === "true")
+                return true; // defensive: `true` in an array still disables
+            if (entry.startsWith(".")) {
+                // ".example.com" matches example.com and any subdomain.
+                if (host === entry.slice(1) || host.endsWith(entry))
+                    return true;
+            }
+            else if (host === entry) {
+                return true;
+            }
+        }
+        return false;
+    };
+}
+//# sourceMappingURL=host-allowlist.js.map

package/dist/http/host-allowlist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-allowlist.js","sourceRoot":"","sources":["../../src/http/host-allowlist.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAWhC,gGAAgG;AAChG,MAAM,UAAU,eAAe,CAAC,UAA8B;IAC5D,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAC7B,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC;IAChC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEpC,oCAAoC;IACpC,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACnD,IAAI,OAAO;QAAE,OAAQ,OAAO,CAAC,CAAC,CAAY,CAAC,WAAW,EAAE,CAAC;IAEzD,oDAAoD;IACpD,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IAC3C,CAAC;IACD,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC;AAC7B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAA2B;IAE3B,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC;IAE1C,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAEvF,OAAO,CAAC,UAAU,EAAE,EAAE;QACpB,MAAM,IAAI,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC;QACzC,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QAEhC,sEAAsE;QACtE,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC;YAAE,OAAO,IAAI,CAAC;QACrE,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAElC,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;YAC1B,IAAI,KAAK,KAAK,MAAM;gBAAE,OAAO,IAAI,CAAC,CAAC,+CAA+C;YAClF,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC1B,wDAAwD;gBACxD,IAAI,IAAI,KAAK,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;oBAAE,OAAO,IAAI,CAAC;YACnE,CAAC;iBAAM,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;gBAC1B,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;AACJ,CAAC"}

package/dist/http/http-server.d.ts

@@ -0,0 +1,27 @@
+import { type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { type HostnamesSetting } from "./host-allowlist.js";
+/**
+ * Daemon HTTP server (architecture/auth-security.md § Behavior, daemon-bootstrap.md § Entry points).
+ *
+ * Request pipeline:
+ *  1. `OPTIONS` preflight and `GET /api/health` are exempt from Host + auth checks.
+ *  2. Host-header allowlist (403 on mismatch).
+ *  3. CORS headers (`daemon.cors.allowedOrigins`).
+ *  4. Optional bearer auth (wired in task-003).
+ *  5. Delegate to `onRequest` (mcp/file routes, later sprints) else 404.
+ */
+export declare const HEALTH_PATH = "/api/health";
+export interface HttpServerDeps {
+    hostnames?: HostnamesSetting;
+    allowedOrigins?: string[];
+    healthPath?: string;
+    /** Optional bearer-auth predicate (task-003). Return `false` to reject with 401. */
+    authenticate?: (req: IncomingMessage) => boolean;
+    /** Optional application route handler. Return `true` when it has written the response. */
+    onRequest?: (req: IncomingMessage, res: ServerResponse) => boolean | Promise<boolean>;
+}
+/** Build the `(req, res)` listener implementing the security pipeline. */
+export declare function createRequestListener(deps: HttpServerDeps): (req: IncomingMessage, res: ServerResponse) => void;
+/** Create (but do not start) the daemon HTTP server. */
+export declare function createHttpServer(deps?: HttpServerDeps): Server;
+//# sourceMappingURL=http-server.d.ts.map

package/dist/http/http-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../../src/http/http-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,eAAe,EAAE,KAAK,MAAM,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjG,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE/E;;;;;;;;;GASG;AAEH,eAAO,MAAM,WAAW,gBAAgB,CAAC;AAEzC,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC;IACjD,0FAA0F;IAC1F,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACvF;AAgBD,0EAA0E;AAC1E,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,cAAc,GACnB,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,IAAI,CAoDrD;AAED,wDAAwD;AACxD,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,cAAmB,GAAG,MAAM,CAElE"}

package/dist/http/http-server.js

@@ -0,0 +1,76 @@
+import { createServer } from "node:http";
+import { createHostChecker } from "./host-allowlist.js";
+/**
+ * Daemon HTTP server (architecture/auth-security.md § Behavior, daemon-bootstrap.md § Entry points).
+ *
+ * Request pipeline:
+ *  1. `OPTIONS` preflight and `GET /api/health` are exempt from Host + auth checks.
+ *  2. Host-header allowlist (403 on mismatch).
+ *  3. CORS headers (`daemon.cors.allowedOrigins`).
+ *  4. Optional bearer auth (wired in task-003).
+ *  5. Delegate to `onRequest` (mcp/file routes, later sprints) else 404.
+ */
+export const HEALTH_PATH = "/api/health";
+function applyCors(req, res, allowedOrigins) {
+    const origin = req.headers.origin;
+    if (origin && (allowedOrigins.includes("*") || allowedOrigins.includes(origin))) {
+        res.setHeader("Access-Control-Allow-Origin", origin);
+        res.setHeader("Vary", "Origin");
+        res.setHeader("Access-Control-Allow-Credentials", "true");
+    }
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Authorization, Content-Type, Sec-WebSocket-Protocol");
+}
+/** Build the `(req, res)` listener implementing the security pipeline. */
+export function createRequestListener(deps) {
+    const healthPath = deps.healthPath ?? HEALTH_PATH;
+    const allowedOrigins = deps.allowedOrigins ?? [];
+    const hostCheck = createHostChecker(deps.hostnames ?? []);
+    return (req, res) => {
+        void (async () => {
+            const method = (req.method ?? "GET").toUpperCase();
+            const path = (req.url ?? "/").split("?")[0];
+            // (1) CORS preflight — exempt from host + auth.
+            if (method === "OPTIONS") {
+                applyCors(req, res, allowedOrigins);
+                res.writeHead(204);
+                res.end();
+                return;
+            }
+            // (1) Health probe — exempt from host + auth.
+            if (method === "GET" && path === healthPath) {
+                applyCors(req, res, allowedOrigins);
+                res.writeHead(200, { "content-type": "application/json" });
+                res.end(JSON.stringify({ status: "ok" }));
+                return;
+            }
+            // (2) Host allowlist.
+            if (!hostCheck(req.headers.host)) {
+                res.writeHead(403, { "content-type": "text/plain" });
+                res.end("Host not allowed");
+                return;
+            }
+            // (3) CORS.
+            applyCors(req, res, allowedOrigins);
+            // (4) Auth (task-003).
+            if (deps.authenticate && !deps.authenticate(req)) {
+                res.writeHead(401, { "content-type": "text/plain" });
+                res.end("Unauthorized");
+                return;
+            }
+            // (5) Application routes.
+            if (deps.onRequest) {
+                const handled = await deps.onRequest(req, res);
+                if (handled)
+                    return;
+            }
+            res.writeHead(404, { "content-type": "text/plain" });
+            res.end("Not found");
+        })();
+    };
+}
+/** Create (but do not start) the daemon HTTP server. */
+export function createHttpServer(deps = {}) {
+    return createServer(createRequestListener(deps));
+}
+//# sourceMappingURL=http-server.js.map

package/dist/http/http-server.js.map

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