jishushell 0.4.24 → 0.5.15

package/dist/types.d.ts

@@ -26,6 +26,12 @@ export interface ServiceResult {
     eval_id?: string;
     /** Port allocation metadata from adapters (process-manager / nomad-manager). */
     port_allocation?: unknown;
+    /**
+     * Stable error code for callers that prefer machine-readable tags over
+     * regex-matching localized error messages. Populated by PR 3
+     * resolveConnections (`MISSING_REQUIRED_CONNECTION` / `AMBIGUOUS_CONNECTION` / etc).
+     */
+    code?: string;
 }
 export interface ExecResult {
     stdout: string;
@@ -105,6 +111,25 @@ export interface PanelConfig {
     };
     telemetry?: false;
     activation_reported?: boolean;
+    /**
+     * External mount points — let any host directory appear under
+     * ~/.jishushell/files/ as a virtual subtree. The user picks the
+     * alias; host_path can be any directory the panel user can read
+     * (sensitive system directories are flagged but allowed if the
+     * user insists). Mode "ro" forbids any write through the panel
+     * or WebDAV; "rw" allows it.
+     *
+     * Implementation: the panel does NOT create a real symlink in
+     * files/ — it virtualizes the path at the FilesManager layer.
+     * That avoids the symlink-defense conflict and works identically
+     * across docker / raw_exec / process modes.
+     */
+    external_mounts?: Array<{
+        alias: string;
+        host_path: string;
+        mode: "ro" | "rw";
+        description?: string;
+    }>;
     [key: string]: any;
 }
 export type AppTaskRuntime = "container" | "process" | "vm";
@@ -120,6 +145,16 @@ export interface AppTaskPort {
     host_port?: number;
     container_port?: number;
     visibility?: AppTaskPortVisibility;
+    /**
+     * Name of a Nomad `host_network` block declared in nomad.hcl. Default is
+     * "external" (eth0 / primary LAN interface). Use "docker_bridge" to
+     * publish on the docker0 IP (172.17.0.1) — required when peer containers
+     * in the same group dial this port via `host.docker.internal`. Without
+     * this, Nomad picks the wrong interface and cross-task
+     * host.docker.internal calls get "connection refused" (e.g. weknora-app
+     * → paradedb on port 18093).
+     */
+    host_network?: string;
 }
 export interface AppTaskHealth {
     http?: {
@@ -157,6 +192,29 @@ export interface AppTask {
     after?: string[];
     /** Volumes: string format "src:dest[:ro]" or object { source, target, readonly? } */
     volumes?: Array<string | AppTaskVolume>;
+    /**
+     * Container task user spec. Format: "uid:gid" (numeric) or "uid". Special
+     * value "host" resolves to the panel process's `process.getuid()`:`getgid()`
+     * at job-build time — keeps bind-mounted data dirs writable by the panel
+     * user (typically `pi`) without forcing the container to run as root and
+     * without needing `chown`/`CAP_DAC_OVERRIDE` gymnastics. Mirrors how the
+     * hermes / openclaw adapters set `User`. When omitted on container tasks
+     * the unified builder falls back to "host" by default.
+     */
+    user?: string;
+    /**
+     * Linux capabilities to add back on top of the runtime baseline
+     * (`cap_drop: ["ALL"]`). Validated against a tight allowlist
+     * (CHOWN / DAC_OVERRIDE / FOWNER / SETUID / SETGID / SETPCAP /
+     * NET_BIND_SERVICE) before passing to the docker driver. Required by
+     * canonical postgres/redis/-style images whose entrypoint runs as root
+     * and uses `gosu`+`chown` to drop privileges to a non-root user before
+     * exec'ing the main process. The container still drops to a non-root
+     * user before serving traffic — this only re-arms the kernel facilities
+     * the drop step needs. Caps outside the allowlist are silently dropped
+     * (fail-closed).
+     */
+    cap_add?: string[];
 }
 export interface AppTerminalCommandPreset {
     cmd: string;
@@ -173,25 +231,183 @@ export interface AppTerminalConfig {
     timeout_ms?: number;
     commands?: Record<string, Array<string | AppTerminalCommandPreset>>;
 }
+/**
+ * Health-probe spec attached to a provide. When omitted, the prober derives
+ * a default strategy from `protocol` (§5.6: http→HEAD, ws/tcp→connect,
+ * mcp→initialize, terminal→no-op).
+ */
+export interface ProvideHealthSpec {
+    kind?: "http" | "tcp" | "mcp" | "none";
+    /** HTTP path to probe (defaults to "/"). Ignored for non-http kinds. */
+    path?: string;
+    /** Custom port to probe; defaults to the provide's resolved hostPort. */
+    port?: number;
+}
 export interface AppProvide {
     capability: string;
+    /** Task that exposes this capability — required for resolveProvideEndpoint
+     *  (§5.5) to pick the right port when an app has multiple service tasks. */
+    task?: string;
+    /** Optional port-name disambiguator when multiple ports share a number. */
+    portName?: string;
     port?: number;
     path?: string;
     url?: string;
-    protocol?: "http" | "https" | "tcp" | "udp" | (string & {});
+    protocol?: "http" | "https" | "tcp" | "udp" | "ws" | "wss" | "sse" | "mcp" | "terminal" | (string & {});
     visibility?: string;
     description?: string;
     terminal?: AppTerminalConfig;
+    /** Optional explicit health probe; defaults derived from `protocol` (§5.6). */
+    health?: ProvideHealthSpec;
+    /**
+     * §17 (PR 8) — canonical MCP tool surface. Filled when this capability
+     * is meant to be re-exposed to an LLM agent through an MCP server. The
+     * jishushell MCP firewall uses these fields verbatim — upstream
+     * `tools/list` descriptions are discarded — to prevent third-party
+     * packages from prompt-injecting the LLM via their own tool wording.
+     * When absent, adapters fall back to the legacy per-capability path
+     * (PR 7 in-tree shim or direct `npx <pkg>` wiring).
+     */
+    tool_schema?: ToolSchema;
+    /**
+     * §6 — describes how a consumer that binds this `provides[]` capability
+     * should authenticate when calling the endpoint. Optional. Absent = no auth.
+     */
+    auth?: AppProvideAuth;
+    /**
+     * Controls how the instance detail page generates the iframe `src` for
+     * this capability:
+     *
+     *   - `"auto"` (default): direct LAN URL when the published port listens
+     *     on a non-loopback interface, fall back to panel proxy when only
+     *     loopback. Best for apps users typically reach by IP+port.
+     *   - `"proxy"`: always use the panel's same-origin reverse proxy path
+     *     (`/api/instances/:id/provides/:capability/`). Needed when the
+     *     upstream is on a network the browser can't dial directly (corp
+     *     firewall blocks high ports, VPN, mixed-content boundary) or when
+     *     the upstream emits `X-Frame-Options: SAMEORIGIN`/CSP that block
+     *     cross-origin iframe embedding — the proxy strips those headers.
+     *   - `"direct"`: always emit the direct LAN URL, never the proxy path.
+     *     Useful for upstreams that can't safely run behind a sub-path
+     *     reverse proxy (some SPAs hardcode absolute asset URLs).
+     */
+    embedded?: "auto" | "proxy" | "direct";
+}
+/**
+ * §6 — describes how a consumer that binds this `provides[]` capability
+ * should authenticate when calling the endpoint. Optional. Absent = no auth.
+ *
+ * `tokenSource` is a small DSL the apply hook resolves at apply time:
+ *   "instance.env.<NAME>"      — read from the provider instance's runtime env
+ *   "instance.config.<path>"   — read from the provider's openclaw.json (json-pointer)
+ *   "proxy.token"              — read from the embedded llm-proxy's per-instance token
+ *
+ * Validation rules (PR A): `tokenSource` is required when kind !== "none".
+ * At the type level we keep it optional because the validator catches violations.
+ */
+export interface AppProvideAuth {
+    kind: "none" | "bearer" | "header" | "query";
+    tokenSource?: string;
+    headerName?: string;
+    tokenPrefix?: string;
+}
+/**
+ * §17.3.1 — what the LLM sees for an MCP-class capability.
+ *
+ * `name` / `description` / `parameters` are forwarded verbatim by the
+ * MCP firewall's `tools/list` response, replacing whatever the upstream
+ * package would have advertised. `upstream` tells the firewall how to
+ * spawn the actual implementation.
+ */
+export interface ToolSchema {
+    /** MCP tool name. Must match `^[a-z][a-z0-9_]*$`. */
+    name: string;
+    /**
+     * Human-language description shown to the LLM. Keep minimal —
+     * "news / recent events / today" style suggestions invite query
+     * rewriting in some models (see §17.1).
+     */
+    description: string;
+    /**
+     * MCP `inputSchema`. Stored under the `parameters` key in yaml for
+     * brevity; the firewall publishes it as `inputSchema` on the wire.
+     */
+    parameters: {
+        type: "object";
+        properties: Record<string, Record<string, any>>;
+        required?: string[];
+    };
+    /**
+     * How the firewall spawns the actual upstream MCP server. Args are
+     * passed through unchanged. `env_template` values may reference
+     * `${SLOT}` placeholders that the writeMcpEntry helper resolves
+     * against the connection-resolver's env output before serializing
+     * into firewall config.
+     */
+    upstream: {
+        command: string;
+        args?: string[];
+        env_template?: Record<string, string>;
+    };
+    /**
+     * When true (default), wrap each `tools/call` result in
+     * `{untrusted: true, source: <capability_id>, content: ...}` so the
+     * LLM treats output as untrusted data, not instructions. Mirrors
+     * OpenClaw's `wrapWebContent` defense.
+     */
+    wrap_outputs?: boolean;
 }
 export interface AppRequire {
     capability: string;
     inject_as: string;
     required?: boolean;
+    /**
+     * Multi-candidate semantics. `"one"` (default) lets the user pick exactly
+     * one provider; `"many"` allows multiple providers (e.g. several MCP
+     * servers merged together).
+     */
+    cardinality?: "one" | "many";
+    /**
+     * LLM apply mode (§7.1.2). Only meaningful when `capability` resolves to
+     * the `llm` category. `"proxy-upstream"` writes the consumer instance's
+     * `x-jishushell.proxy.upstream` (OpenClaw / Hermes default); `"openai-env"`
+     * injects `OPENAI_API_BASE_URL` / `OPENAI_API_KEY` directly into runtime
+     * env (Open WebUI / generic OpenAI clients). Omit to fall back to the
+     * adapter-type default.
+     */
+    apply?: "proxy-upstream" | "openai-env";
+}
+/**
+ * Persisted binding state. Stored under `instance.json.connections[slot]`.
+ * `null` denotes user-explicit disconnect (do not auto-fall-back).
+ * Missing slot = "never set" (legacy single-candidate fallback may apply).
+ */
+export interface InstanceConnectionSingle {
+    kind: "single";
+    providerId: string;
+    capability: string;
+    /** LLM-only: which model the user picked. */
+    selectedModelId?: string;
+}
+export interface InstanceConnectionMany {
+    kind: "many";
+    providers: Array<{
+        providerId: string;
+        capability: string;
+    }>;
+}
+export type InstanceConnection = InstanceConnectionSingle | InstanceConnectionMany | null;
+export type InstanceConnections = Record<string, InstanceConnection>;
+export interface DismissedSuggestion {
+    slot: string;
+    until: string;
 }
 export type AppLifecycleStep = {
     run: string;
     timeout_ms?: number;
     successIfCommandExists?: string;
+    sudo?: boolean;
+    ifFileExists?: string;
 } | {
     downloadImage: string;
     timeout_ms?: number;
@@ -207,6 +423,12 @@ export type AppLifecycleStep = {
     deleteBinary: string;
 } | {
     mkdir: string;
+} | {
+    chown: {
+        path: string;
+        owner: string;
+        recursive?: boolean;
+    };
 } | {
     deleteDir: string;
 } | {
@@ -217,6 +439,14 @@ export interface AppLifecycle {
     pre_install?: AppLifecycleStep[];
     /** Steps run during `app install`, before the job is created. */
     install?: AppLifecycleStep[];
+    /**
+     * Steps run on every app start, immediately before the Nomad job is
+     * submitted. Use for idempotent invariants the runtime depends on but
+     * that may drift between starts (e.g. chowning a bind-mount to match
+     * the container's runtime user when `cap_drop: ALL` strips
+     * CAP_DAC_OVERRIDE).
+     */
+    pre_start?: AppLifecycleStep[];
     /** Steps run during `app uninstall`, before files are removed. */
     uninstall?: AppLifecycleStep[];
     /** Steps run after the Nomad job transitions to `running`. */

package/dist/utils/instance-lock.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Per-instance promise-chain mutex for serializing operations that mutate
+ * a single instance's durable state across multiple files (instance.json,
+ * provider.env, openclaw.json, mcporter.json, …).
+ *
+ * Mirrors the existing pattern in `llm-proxy/index.ts:_configSaveLocks`:
+ * each `withInstanceLock(id, fn)` call chains onto whatever promise was
+ * last queued for that id, so concurrent callers see strict FIFO ordering.
+ * The map self-cleans entries when the chain settles to keep memory flat.
+ *
+ * Use this for any code path that performs more than one file write on a
+ * given instance id (PUT /connections transactor, startApp, stopApp,
+ * restartApp). Operations on different instance ids never block each other.
+ */
+/**
+ * Run `fn` exclusively against `instanceId`. Returns `fn`'s value (or
+ * propagates its rejection). Pending callers form a FIFO chain — each
+ * waits for prior ones to settle, even if they reject.
+ */
+export declare function withInstanceLock<T>(instanceId: string, fn: () => Promise<T>): Promise<T>;
+/** Test-only helper for verifying the chain is empty between cases. */
+export declare function __instanceLockSize(): number;

package/dist/utils/instance-lock.js

@@ -0,0 +1,48 @@
+/**
+ * Per-instance promise-chain mutex for serializing operations that mutate
+ * a single instance's durable state across multiple files (instance.json,
+ * provider.env, openclaw.json, mcporter.json, …).
+ *
+ * Mirrors the existing pattern in `llm-proxy/index.ts:_configSaveLocks`:
+ * each `withInstanceLock(id, fn)` call chains onto whatever promise was
+ * last queued for that id, so concurrent callers see strict FIFO ordering.
+ * The map self-cleans entries when the chain settles to keep memory flat.
+ *
+ * Use this for any code path that performs more than one file write on a
+ * given instance id (PUT /connections transactor, startApp, stopApp,
+ * restartApp). Operations on different instance ids never block each other.
+ */
+const _instanceLocks = new Map();
+/**
+ * Run `fn` exclusively against `instanceId`. Returns `fn`'s value (or
+ * propagates its rejection). Pending callers form a FIFO chain — each
+ * waits for prior ones to settle, even if they reject.
+ */
+export async function withInstanceLock(instanceId, fn) {
+    const prev = _instanceLocks.get(instanceId) ?? Promise.resolve();
+    // Swallow prior rejections so the chain doesn't break — each caller still
+    // gets its own promise's result. The map only tracks ordering, not health.
+    const current = prev.catch(() => undefined).then(() => fn());
+    // Identity check uses the same reference we store; .finally() returns a
+    // new promise, so we must store `current` and attach the cleanup as a
+    // side-effect, not store the .finally() result. The trailing .catch()
+    // swallows the cleanup-promise's rejection — without it Node logs an
+    // "unhandled rejection" each time `fn()` throws even though the caller
+    // already handled it via the returned `current`.
+    current
+        .finally(() => {
+        if (_instanceLocks.get(instanceId) === current) {
+            _instanceLocks.delete(instanceId);
+        }
+    })
+        .catch(() => {
+        // intentional no-op — caller handles the original rejection
+    });
+    _instanceLocks.set(instanceId, current);
+    return current;
+}
+/** Test-only helper for verifying the chain is empty between cases. */
+export function __instanceLockSize() {
+    return _instanceLocks.size;
+}
+//# sourceMappingURL=instance-lock.js.map

package/dist/utils/instance-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-lock.js","sourceRoot":"","sources":["../../src/utils/instance-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,cAAc,GAAG,IAAI,GAAG,EAA4B,CAAC;AAE3D;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,UAAkB,EAClB,EAAoB;IAEpB,MAAM,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IACjE,0EAA0E;IAC1E,2EAA2E;IAC3E,MAAM,OAAO,GAAe,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IACzE,wEAAwE;IACxE,sEAAsE;IACtE,sEAAsE;IACtE,qEAAqE;IACrE,uEAAuE;IACvE,iDAAiD;IACjD,OAAO;SACJ,OAAO,CAAC,GAAG,EAAE;QACZ,IAAI,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,OAAO,EAAE,CAAC;YAC/C,cAAc,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACpC,CAAC;IACH,CAAC,CAAC;SACD,KAAK,CAAC,GAAG,EAAE;QACV,4DAA4D;IAC9D,CAAC,CAAC,CAAC;IACL,cAAc,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACxC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,kBAAkB;IAChC,OAAO,cAAc,CAAC,IAAI,CAAC;AAC7B,CAAC"}

package/dist/utils/path-locks.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Path-scoped advisory locks for the Files module (W1 PR-2).
+ *
+ * Single-process serialization: all callers using the same `path` string run
+ * in arrival order; different paths run independently in parallel.
+ *
+ * This is *advisory* — it only protects callers that opt in via withPathLock.
+ * It does not protect against external writers (Agent, WebDAV, ssh) that
+ * touch the file directly. Those paths have their own atomicity (POSIX
+ * rename) and the application's tolerance is "POSIX is source of truth".
+ *
+ * Stale locks (> 60s) are logged but not broken — correctness over recovery.
+ */
+/**
+ * Run `fn` while holding an advisory lock on `path`.
+ *
+ * If another caller holds the lock, this call queues behind it; the queue
+ * preserves arrival order.
+ *
+ * Throws (or resolves) propagate from `fn`. The lock is always released.
+ */
+export declare function withPathLock<T>(path: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Test-only: clear all locks. Do not use in production.
+ */
+export declare function _clearAllPathLocks(): void;
+/**
+ * Test-only: number of active locks. Do not use in production.
+ */
+export declare function _activePathLockCount(): number;

package/dist/utils/path-locks.js

@@ -0,0 +1,63 @@
+/**
+ * Path-scoped advisory locks for the Files module (W1 PR-2).
+ *
+ * Single-process serialization: all callers using the same `path` string run
+ * in arrival order; different paths run independently in parallel.
+ *
+ * This is *advisory* — it only protects callers that opt in via withPathLock.
+ * It does not protect against external writers (Agent, WebDAV, ssh) that
+ * touch the file directly. Those paths have their own atomicity (POSIX
+ * rename) and the application's tolerance is "POSIX is source of truth".
+ *
+ * Stale locks (> 60s) are logged but not broken — correctness over recovery.
+ */
+const locks = new Map();
+const STALE_LOCK_MS = 60_000;
+/**
+ * Run `fn` while holding an advisory lock on `path`.
+ *
+ * If another caller holds the lock, this call queues behind it; the queue
+ * preserves arrival order.
+ *
+ * Throws (or resolves) propagate from `fn`. The lock is always released.
+ */
+export async function withPathLock(path, fn) {
+    const existing = locks.get(path);
+    if (existing && Date.now() - existing.startedAt > STALE_LOCK_MS) {
+        console.warn(`[path-lock] stale lock detected for ${path} (held ${Date.now() - existing.startedAt}ms)`);
+    }
+    const previous = existing?.promise ?? Promise.resolve();
+    let release;
+    const next = new Promise((resolve) => {
+        release = resolve;
+    });
+    // Our slot in the chain: wait for previous holder, then release `next`
+    const ourPromise = previous.then(() => next);
+    const entry = { promise: ourPromise, startedAt: Date.now() };
+    locks.set(path, entry);
+    try {
+        await previous;
+        // Re-stamp startedAt to "actual hold start" for stale detection
+        entry.startedAt = Date.now();
+        return await fn();
+    }
+    finally {
+        release();
+        if (locks.get(path) === entry) {
+            locks.delete(path);
+        }
+    }
+}
+/**
+ * Test-only: clear all locks. Do not use in production.
+ */
+export function _clearAllPathLocks() {
+    locks.clear();
+}
+/**
+ * Test-only: number of active locks. Do not use in production.
+ */
+export function _activePathLockCount() {
+    return locks.size;
+}
+//# sourceMappingURL=path-locks.js.map

package/dist/utils/path-locks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-locks.js","sourceRoot":"","sources":["../../src/utils/path-locks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,MAAM,KAAK,GAAG,IAAI,GAAG,EAAqB,CAAC;AAC3C,MAAM,aAAa,GAAG,MAAM,CAAC;AAE7B;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAY,EACZ,EAAoB;IAEpB,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,QAAQ,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,SAAS,GAAG,aAAa,EAAE,CAAC;QAChE,OAAO,CAAC,IAAI,CACV,uCAAuC,IAAI,UACzC,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,SACxB,KAAK,CACN,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,QAAQ,EAAE,OAAO,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAExD,IAAI,OAAoB,CAAC;IACzB,MAAM,IAAI,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACzC,OAAO,GAAG,OAAO,CAAC;IACpB,CAAC,CAAC,CAAC;IAEH,uEAAuE;IACvE,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAc,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;IACxE,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAEvB,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC;QACf,gEAAgE;QAChE,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;YAAS,CAAC;QACT,OAAO,EAAE,CAAC;QACV,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC;YAC9B,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAChC,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,KAAK,CAAC,IAAI,CAAC;AACpB,CAAC"}

package/dist/utils/path-safety.d.ts

@@ -0,0 +1,41 @@
+export declare class PathSafetyError extends Error {
+    reason: string;
+    constructor(message: string, reason: string);
+}
+/**
+ * Validate a user-provided relative path string against common attack
+ * vectors. Performs no IO.
+ *
+ * Accepted:
+ *   - "" (root)
+ *   - "notes/x.md", "深/文件.txt", "with-dashes_and.dots"
+ *
+ * Rejected (PathSafetyError):
+ *   - leading "/" (absolute)
+ *   - drive letters ("C:\\foo", "Z:foo")
+ *   - any "..", ".", or all-dot ("...", "....") segment
+ *   - empty segments ("a//b")
+ *   - leading or trailing "/"
+ *   - backslash anywhere
+ *   - null bytes or control chars (< 0x20)
+ *   - segments ending in "." or " " (Windows quirk; some sync tools misbehave)
+ *   - segment > 255 bytes (ext4 NAME_MAX)
+ *   - total > 4096 bytes (Linux PATH_MAX)
+ *   - non-string input
+ */
+export declare function validateRelativePath(input: unknown): void;
+/**
+ * Resolve a validated relative path inside a fixed root, then verify the
+ * resolved path is still inside that root using a separator-explicit prefix
+ * check (so `/foo` does not match `/foobar`).
+ *
+ * Performs no IO. Symlink resolution is the caller's responsibility.
+ *
+ * @throws PathSafetyError on validation failure or escape attempt
+ */
+export declare function resolveSafe(root: string, rel: string): string;
+/**
+ * Returns true if any segment of the path begins with ".".
+ * Used to optionally hide dotfiles in directory listings.
+ */
+export declare function isHidden(input: string): boolean;

package/dist/utils/path-safety.js

@@ -0,0 +1,119 @@
+/**
+ * Path safety utilities for the Files module (W1).
+ *
+ * Three layers of defense (per .omc/plans/files-w1.md § 7.1):
+ *   1. validateRelativePath — string-level checks (this module, no IO)
+ *   2. resolveSafe          — path.resolve + prefix check (this module, no IO)
+ *   3. realpath/symlink     — performed by FilesManager (defense 3, IO)
+ *
+ * Empty string is the conventional root path and is accepted by both functions.
+ */
+import { resolve, sep } from "path";
+const PATH_MAX_BYTES = 4096;
+const NAME_MAX_BYTES = 255;
+export class PathSafetyError extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = "PathSafetyError";
+    }
+}
+/**
+ * Validate a user-provided relative path string against common attack
+ * vectors. Performs no IO.
+ *
+ * Accepted:
+ *   - "" (root)
+ *   - "notes/x.md", "深/文件.txt", "with-dashes_and.dots"
+ *
+ * Rejected (PathSafetyError):
+ *   - leading "/" (absolute)
+ *   - drive letters ("C:\\foo", "Z:foo")
+ *   - any "..", ".", or all-dot ("...", "....") segment
+ *   - empty segments ("a//b")
+ *   - leading or trailing "/"
+ *   - backslash anywhere
+ *   - null bytes or control chars (< 0x20)
+ *   - segments ending in "." or " " (Windows quirk; some sync tools misbehave)
+ *   - segment > 255 bytes (ext4 NAME_MAX)
+ *   - total > 4096 bytes (Linux PATH_MAX)
+ *   - non-string input
+ */
+export function validateRelativePath(input) {
+    if (typeof input !== "string") {
+        throw new PathSafetyError("path must be a string", "type");
+    }
+    if (input === "")
+        return; // root, ok
+    if (Buffer.byteLength(input, "utf8") > PATH_MAX_BYTES) {
+        throw new PathSafetyError("path too long", "path-length");
+    }
+    if (input.startsWith("/")) {
+        throw new PathSafetyError("path must be relative (no leading /)", "absolute");
+    }
+    if (input.includes("\\")) {
+        throw new PathSafetyError("backslash not allowed", "backslash");
+    }
+    // Windows drive letter: e.g. "C:\\foo", "Z:foo", "Z:/foo"
+    if (/^[A-Za-z]:/.test(input)) {
+        throw new PathSafetyError("drive letter not allowed", "drive-letter");
+    }
+    for (let i = 0; i < input.length; i++) {
+        const code = input.charCodeAt(i);
+        if (code === 0) {
+            throw new PathSafetyError("null byte not allowed", "null-byte");
+        }
+        if (code < 0x20) {
+            throw new PathSafetyError("control character not allowed", "control-char");
+        }
+    }
+    if (input.endsWith("/")) {
+        throw new PathSafetyError("path must not end with /", "trailing-slash");
+    }
+    const segments = input.split("/");
+    for (const seg of segments) {
+        if (seg === "") {
+            throw new PathSafetyError("empty path segment", "empty-segment");
+        }
+        // Reject "." ".." and any all-dots variant ("..." "...." etc.)
+        if (/^\.+$/.test(seg)) {
+            throw new PathSafetyError(`all-dots segment "${seg}" not allowed`, "dot-segment");
+        }
+        if (Buffer.byteLength(seg, "utf8") > NAME_MAX_BYTES) {
+            throw new PathSafetyError("path segment too long", "segment-length");
+        }
+        if (seg.endsWith(".") || seg.endsWith(" ")) {
+            throw new PathSafetyError(`segment ends with "." or space`, "windows-quirk");
+        }
+    }
+}
+/**
+ * Resolve a validated relative path inside a fixed root, then verify the
+ * resolved path is still inside that root using a separator-explicit prefix
+ * check (so `/foo` does not match `/foobar`).
+ *
+ * Performs no IO. Symlink resolution is the caller's responsibility.
+ *
+ * @throws PathSafetyError on validation failure or escape attempt
+ */
+export function resolveSafe(root, rel) {
+    validateRelativePath(rel);
+    const resolved = resolve(root, rel);
+    const rootWithSep = root.endsWith(sep) ? root : root + sep;
+    const rootNoSep = root.endsWith(sep) ? root.slice(0, -1) : root;
+    if (resolved !== rootNoSep && !resolved.startsWith(rootWithSep)) {
+        throw new PathSafetyError("path escapes root", "escape");
+    }
+    return resolved;
+}
+/**
+ * Returns true if any segment of the path begins with ".".
+ * Used to optionally hide dotfiles in directory listings.
+ */
+export function isHidden(input) {
+    if (input === "")
+        return false;
+    return input.split("/").some(s => s.startsWith("."));
+}
+//# sourceMappingURL=path-safety.js.map

package/dist/utils/path-safety.js.map

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