agentvault 1.0.2 → 1.0.5

package/dist/src/trading/ip-whitelist.js

@@ -0,0 +1,239 @@
+/**
+ * IP Whitelist Manager
+ *
+ * Manages the set of IPs / CIDR blocks that are permitted to reach the
+ * trading VPS.  Provides:
+ *   - Validation of individual addresses and CIDR blocks.
+ *   - Membership testing (does this source IP pass the whitelist?).
+ *   - Firewall rule generation for iptables and ufw so the VPS can be
+ *     bootstrapped from the same config that the application uses.
+ *
+ * Threat model: only traffic originating from known, controlled IPs should
+ * reach the Binance proxy endpoint.  This module makes that policy explicit
+ * and machine-verifiable.
+ */
+import * as net from 'node:net';
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+/** Return true if `s` is a plain IPv4 or IPv6 address (no prefix length). */
+function isPlainIp(s) {
+    return net.isIP(s) !== 0;
+}
+/**
+ * Return true if `s` is a valid CIDR block.
+ * Accepts both IPv4 (e.g. "192.168.1.0/24") and IPv6 (e.g. "2001:db8::/32").
+ */
+function isCidr(s) {
+    const slashIdx = s.lastIndexOf('/');
+    if (slashIdx === -1)
+        return false;
+    const ip = s.slice(0, slashIdx);
+    const prefixStr = s.slice(slashIdx + 1);
+    const prefix = parseInt(prefixStr, 10);
+    if (isNaN(prefix) || prefixStr.trim() === '')
+        return false;
+    const ipVersion = net.isIP(ip);
+    if (ipVersion === 4 && prefix >= 0 && prefix <= 32)
+        return true;
+    if (ipVersion === 6 && prefix >= 0 && prefix <= 128)
+        return true;
+    return false;
+}
+/** Validate a single CIDR / address string. */
+export function validateCidr(value) {
+    const errors = [];
+    const trimmed = value.trim();
+    if (!trimmed) {
+        errors.push('Entry is empty');
+        return { valid: false, errors };
+    }
+    if (!isPlainIp(trimmed) && !isCidr(trimmed)) {
+        errors.push(`"${trimmed}" is not a valid IPv4/IPv6 address or CIDR block`);
+    }
+    return { valid: errors.length === 0, errors };
+}
+// ---------------------------------------------------------------------------
+// Membership testing
+// ---------------------------------------------------------------------------
+/**
+ * Convert an IPv4 address string to a 32-bit unsigned integer.
+ */
+function ipv4ToInt(ip) {
+    return ip
+        .split('.')
+        .reduce((acc, octet) => (acc << 8) | parseInt(octet, 10), 0) >>> 0;
+}
+/**
+ * Return true if `ip` falls within the given IPv4 CIDR block.
+ */
+function ipv4InCidr(ip, cidr) {
+    const parts = cidr.split('/');
+    if (parts.length !== 2)
+        return false;
+    const [network, prefixStr] = parts;
+    const prefix = parseInt(prefixStr, 10);
+    if (isNaN(prefix) || prefix < 0 || prefix > 32)
+        return false;
+    const mask = prefix === 0 ? 0 : (~0 << (32 - prefix)) >>> 0;
+    return (ipv4ToInt(ip) & mask) === (ipv4ToInt(network) & mask);
+}
+/**
+ * Normalise an IPv6 address to its fully-expanded form using the Node.js
+ * URL API (cheapest reliable approach without external deps).
+ */
+function normaliseIpv6(ip) {
+    try {
+        // Wrapping in brackets lets URL parse it as a host.
+        const url = new URL(`http://[${ip}]`);
+        // url.hostname strips brackets.
+        return url.hostname.slice(1, -1);
+    }
+    catch {
+        return ip;
+    }
+}
+/**
+ * Return true if `ip` falls within the given IPv6 CIDR block.
+ * Uses BigInt for correct 128-bit arithmetic.
+ */
+function ipv6InCidr(ip, cidr) {
+    const parts = cidr.split('/');
+    if (parts.length !== 2)
+        return false;
+    const [network, prefixStr] = parts;
+    const prefixNum = parseInt(prefixStr, 10);
+    if (isNaN(prefixNum) || prefixNum < 0 || prefixNum > 128)
+        return false;
+    const prefix = BigInt(prefixNum);
+    const expand = (addr) => {
+        const norm = normaliseIpv6(addr).replace(/:/g, '');
+        return BigInt('0x' + norm.padStart(32, '0'));
+    };
+    const mask = prefix === 0n ? 0n : (~0n << (128n - prefix)) & ((1n << 128n) - 1n);
+    return (expand(ip) & mask) === (expand(network) & mask);
+}
+/**
+ * Test whether `sourceIp` is permitted by the given whitelist entries.
+ */
+export function isIpAllowed(sourceIp, entries) {
+    const ipVersion = net.isIP(sourceIp.trim());
+    if (ipVersion === 0)
+        return false; // Not a valid IP at all.
+    for (const entry of entries) {
+        const cidr = entry.cidr.trim();
+        // Plain IP — exact match.
+        if (isPlainIp(cidr)) {
+            if (cidr === sourceIp.trim())
+                return true;
+            continue;
+        }
+        // CIDR block.
+        if (isCidr(cidr)) {
+            const networkIp = cidr.split('/')[0];
+            if (!networkIp)
+                continue;
+            const networkVersion = net.isIP(networkIp);
+            if (networkVersion !== ipVersion)
+                continue; // IPv4 vs IPv6 mismatch.
+            if (ipVersion === 4 && ipv4InCidr(sourceIp.trim(), cidr))
+                return true;
+            if (ipVersion === 6 && ipv6InCidr(sourceIp.trim(), cidr))
+                return true;
+        }
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Firewall rule generation
+// ---------------------------------------------------------------------------
+/**
+ * Generate iptables / ufw / ip6tables rules that allow only whitelisted IPs
+ * to reach `port` (TCP) and drop everything else.
+ *
+ * The generated commands are idempotent-safe: they use INSERT (iptables) and
+ * `ufw allow from ... to any port ...` forms that are safe to run repeatedly.
+ */
+export function generateFirewallRules(entries, port, chain = 'INPUT') {
+    const iptables = [];
+    const ip6tables = [];
+    const ufw = [];
+    for (const entry of entries) {
+        const cidr = entry.cidr.trim();
+        const comment = entry.label.replace(/[^a-zA-Z0-9_-]/g, '-');
+        if (isPlainIp(cidr) || isCidr(cidr)) {
+            const networkIp = isPlainIp(cidr) ? cidr : cidr.split('/')[0];
+            if (!networkIp)
+                continue;
+            const version = net.isIP(networkIp);
+            if (version === 4) {
+                iptables.push(`iptables -I ${chain} -p tcp --dport ${port} -s ${cidr} -j ACCEPT -m comment --comment "av-whitelist-${comment}"`);
+                ufw.push(`ufw allow from ${cidr} to any port ${port} proto tcp comment "av-whitelist-${comment}"`);
+            }
+            else if (version === 6) {
+                ip6tables.push(`ip6tables -I ${chain} -p tcp --dport ${port} -s ${cidr} -j ACCEPT -m comment --comment "av-whitelist-${comment}"`);
+                ufw.push(`ufw allow from ${cidr} to any port ${port} proto tcp comment "av-whitelist-${comment}"`);
+            }
+        }
+    }
+    // Default-deny rules go last (lowest priority in iptables INSERT order).
+    iptables.push(`iptables -A ${chain} -p tcp --dport ${port} -j DROP -m comment --comment "av-whitelist-default-deny"`);
+    ip6tables.push(`ip6tables -A ${chain} -p tcp --dport ${port} -j DROP -m comment --comment "av-whitelist-default-deny"`);
+    ufw.push(`ufw deny ${port}/tcp comment "av-whitelist-default-deny"`);
+    return { iptables, ufw, ip6tables };
+}
+// ---------------------------------------------------------------------------
+// IpWhitelistManager
+// ---------------------------------------------------------------------------
+export class IpWhitelistManager {
+    entries;
+    constructor(entries = []) {
+        this.entries = entries;
+    }
+    /** Add a new entry, validating first. Throws on invalid input. */
+    add(entry) {
+        const result = validateCidr(entry.cidr);
+        if (!result.valid) {
+            throw new Error(`Invalid whitelist entry "${entry.cidr}": ${result.errors.join('; ')}`);
+        }
+        this.entries.push(entry);
+    }
+    /** Remove all entries matching `label`. */
+    remove(label) {
+        this.entries = this.entries.filter(e => e.label !== label);
+    }
+    /** Return all entries. */
+    getEntries() {
+        return this.entries;
+    }
+    /** Test whether `sourceIp` is allowed by the current whitelist. */
+    isAllowed(sourceIp) {
+        return isIpAllowed(sourceIp, this.entries);
+    }
+    /**
+     * Assert that `sourceIp` is whitelisted. Throws if it is not.
+     * Use this as a guard at trade-execution entry points.
+     */
+    assertAllowed(sourceIp) {
+        if (!this.isAllowed(sourceIp)) {
+            throw new Error(`Blocked: source IP ${sourceIp} is not in the trading whitelist. ` +
+                'Update the whitelist configuration and restart the service.');
+        }
+    }
+    /** Validate every entry and return aggregated errors. */
+    validate() {
+        const errors = [];
+        for (const entry of this.entries) {
+            const r = validateCidr(entry.cidr);
+            if (!r.valid) {
+                errors.push(`[${entry.label}] ${r.errors.join('; ')}`);
+            }
+        }
+        return { valid: errors.length === 0, errors };
+    }
+    /** Generate firewall rules for a given port. */
+    generateRules(port, chain) {
+        return generateFirewallRules(this.entries, port, chain);
+    }
+}
+//# sourceMappingURL=ip-whitelist.js.map

package/dist/src/trading/ip-whitelist.js.map

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

package/dist/src/trading/skill-sandbox.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Skill Sandbox
+ *
+ * Enforces isolation constraints when executing OpenClaw / Clawdbot skills:
+ *
+ *   1. **No root** — the process must NOT run as uid 0 (root).
+ *   2. **Write confinement** — file writes are only permitted under /tmp.
+ *      Any attempt to write outside /tmp is blocked with an explicit error.
+ *
+ * Threat model: assume the skill code (an untrusted, domain-specific script
+ * loaded at runtime) could be compromised.  The sandbox prevents privilege
+ * escalation and permanent host mutation beyond the ephemeral /tmp scratch
+ * space.
+ *
+ * Usage:
+ *   const sandbox = new SkillSandbox();
+ *   sandbox.assertSafe();                      // throws if uid=0
+ *   sandbox.assertWritePath('/tmp/output.txt'); // throws if outside /tmp
+ *   const safeFn = sandbox.wrapWrite(fs.writeFileSync);
+ */
+/** The only directory tree in which skill file-writes are permitted. */
+export declare const SKILL_WRITE_ROOT = "/tmp";
+export interface SandboxViolation {
+    type: 'root-process' | 'write-outside-tmp' | 'absolute-path-required';
+    message: string;
+    detail?: string;
+}
+export declare class SkillSandbox {
+    private readonly writeRoot;
+    /**
+     * @param writeRoot   The only directory tree skills may write to.
+     *                    Defaults to `/tmp` (or `os.tmpdir()` on non-Linux).
+     */
+    constructor(writeRoot?: string);
+    /**
+     * Throw if the process is running as root (uid 0).
+     *
+     * Root execution is prohibited for skills because a compromised skill
+     * running as root can bypass every other OS-level control.
+     */
+    assertNotRoot(): void;
+    /**
+     * Throw if `filePath` resolves to a location outside the allowed write root.
+     *
+     * This is the central enforcement point.  Wrap every `fs.writeFile`,
+     * `fs.writeFileSync`, `fs.open`, etc. call with this check.
+     */
+    assertWritePath(filePath: string): void;
+    /**
+     * Run all pre-execution safety checks.  Call this once at skill load time
+     * before any skill code runs.
+     */
+    assertSafe(): void;
+    /**
+     * Wrap `fs.writeFileSync` (or any function whose first argument is a file
+     * path) so that the path check is applied automatically.
+     *
+     * Example:
+     *   import * as fs from 'node:fs';
+     *   const safeWrite = sandbox.wrapWrite(fs.writeFileSync.bind(fs));
+     *   safeWrite('/tmp/output.txt', data);          // OK
+     *   safeWrite('/etc/cron.d/evil', payload);      // throws
+     */
+    wrapWrite<Args extends unknown[], R>(fn: (filePath: string, ...rest: Args) => R): (filePath: string, ...rest: Args) => R;
+    /**
+     * Wrap an async write function (e.g. `fs.promises.writeFile`).
+     */
+    wrapWriteAsync<Args extends unknown[], R>(fn: (filePath: string, ...rest: Args) => Promise<R>): (filePath: string, ...rest: Args) => Promise<R>;
+    /** Return the current write-root this sandbox enforces. */
+    getWriteRoot(): string;
+    /** Return true if the process uid check would pass (not root). */
+    isRunningAsRoot(): boolean;
+    /**
+     * Return a summary of the sandbox configuration suitable for logging.
+     * Never includes sensitive information.
+     */
+    describe(): {
+        uid: number;
+        writeRoot: string;
+        isRoot: boolean;
+    };
+}
+/**
+ * A default SkillSandbox instance using the standard /tmp write root.
+ * Import this directly if you don't need custom configuration.
+ */
+export declare const defaultSandbox: SkillSandbox;
+//# sourceMappingURL=skill-sandbox.d.ts.map

package/dist/src/trading/skill-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-sandbox.d.ts","sourceRoot":"","sources":["../../../src/trading/skill-sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AASH,wEAAwE;AACxE,eAAO,MAAM,gBAAgB,SAAS,CAAC;AAMvC,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,cAAc,GAAG,mBAAmB,GAAG,wBAAwB,CAAC;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAmCD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC;;;OAGG;gBACS,SAAS,CAAC,EAAE,MAAM;IAO9B;;;;;OAKG;IACH,aAAa,IAAI,IAAI;IAerB;;;;;OAKG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAoCvC;;;OAGG;IACH,UAAU,IAAI,IAAI;IAMlB;;;;;;;;;OASG;IACH,SAAS,CAAC,IAAI,SAAS,OAAO,EAAE,EAAE,CAAC,EACjC,EAAE,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,GACzC,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC;IAOzC;;OAEG;IACH,cAAc,CAAC,IAAI,SAAS,OAAO,EAAE,EAAE,CAAC,EACtC,EAAE,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAClD,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC;IASlD,2DAA2D;IAC3D,YAAY,IAAI,MAAM;IAItB,kEAAkE;IAClE,eAAe,IAAI,OAAO;IAI1B;;;OAGG;IACH,QAAQ,IAAI;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE;CAOhE;AAMD;;;GAGG;AACH,eAAO,MAAM,cAAc,cAAqB,CAAC"}

package/dist/src/trading/skill-sandbox.js

@@ -0,0 +1,175 @@
+/**
+ * Skill Sandbox
+ *
+ * Enforces isolation constraints when executing OpenClaw / Clawdbot skills:
+ *
+ *   1. **No root** — the process must NOT run as uid 0 (root).
+ *   2. **Write confinement** — file writes are only permitted under /tmp.
+ *      Any attempt to write outside /tmp is blocked with an explicit error.
+ *
+ * Threat model: assume the skill code (an untrusted, domain-specific script
+ * loaded at runtime) could be compromised.  The sandbox prevents privilege
+ * escalation and permanent host mutation beyond the ephemeral /tmp scratch
+ * space.
+ *
+ * Usage:
+ *   const sandbox = new SkillSandbox();
+ *   sandbox.assertSafe();                      // throws if uid=0
+ *   sandbox.assertWritePath('/tmp/output.txt'); // throws if outside /tmp
+ *   const safeFn = sandbox.wrapWrite(fs.writeFileSync);
+ */
+import * as path from 'node:path';
+import * as os from 'node:os';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** The only directory tree in which skill file-writes are permitted. */
+export const SKILL_WRITE_ROOT = '/tmp';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Return the effective uid of the current process.
+ * On Windows this is always -1 (Windows does not have POSIX uids;
+ * skills should still be allowed to run there without triggering this check).
+ */
+function getEffectiveUid() {
+    if (typeof process.getuid === 'function') {
+        return process.getuid();
+    }
+    // Windows / non-POSIX — no uid concept.
+    return -1;
+}
+/**
+ * Resolve `filePath` to an absolute path and verify it is under `root`.
+ * Uses `path.resolve` so relative paths and `..` components are handled
+ * before the containment check.
+ */
+function isUnderRoot(filePath, root) {
+    const resolved = path.resolve(filePath);
+    // Ensure we compare with a trailing separator to avoid "/tmpfoo" matching "/tmp".
+    const normalRoot = root.endsWith(path.sep) ? root : root + path.sep;
+    return resolved === root || resolved.startsWith(normalRoot);
+}
+// ---------------------------------------------------------------------------
+// SkillSandbox
+// ---------------------------------------------------------------------------
+export class SkillSandbox {
+    writeRoot;
+    /**
+     * @param writeRoot   The only directory tree skills may write to.
+     *                    Defaults to `/tmp` (or `os.tmpdir()` on non-Linux).
+     */
+    constructor(writeRoot) {
+        // On Linux, always use /tmp.  On other platforms use the OS temp dir.
+        this.writeRoot = writeRoot ?? (os.platform() === 'linux' ? SKILL_WRITE_ROOT : os.tmpdir());
+    }
+    // ── Root check ────────────────────────────────────────────────────────────
+    /**
+     * Throw if the process is running as root (uid 0).
+     *
+     * Root execution is prohibited for skills because a compromised skill
+     * running as root can bypass every other OS-level control.
+     */
+    assertNotRoot() {
+        const uid = getEffectiveUid();
+        if (uid === 0) {
+            throw Object.assign(new Error('SkillSandbox: skill execution is forbidden under the root (uid 0) account. ' +
+                'Re-run the agent as a non-privileged user.'), { sandboxViolation: { type: 'root-process', message: 'uid is 0' } });
+        }
+    }
+    // ── Write path check ──────────────────────────────────────────────────────
+    /**
+     * Throw if `filePath` resolves to a location outside the allowed write root.
+     *
+     * This is the central enforcement point.  Wrap every `fs.writeFile`,
+     * `fs.writeFileSync`, `fs.open`, etc. call with this check.
+     */
+    assertWritePath(filePath) {
+        if (!path.isAbsolute(path.resolve(filePath))) {
+            // Should never happen — path.resolve always returns absolute — but be
+            // defensive.
+            throw Object.assign(new Error(`SkillSandbox: could not resolve path "${filePath}" to an absolute path.`), {
+                sandboxViolation: {
+                    type: 'absolute-path-required',
+                    message: `Path could not be resolved: ${filePath}`,
+                },
+            });
+        }
+        if (!isUnderRoot(filePath, this.writeRoot)) {
+            const resolved = path.resolve(filePath);
+            throw Object.assign(new Error(`SkillSandbox: write to "${resolved}" is blocked. ` +
+                `Skills may only write inside ${this.writeRoot}. ` +
+                'Move the output path to a location under that directory.'), {
+                sandboxViolation: {
+                    type: 'write-outside-tmp',
+                    message: `Attempted write to ${resolved}`,
+                    detail: `Allowed root: ${this.writeRoot}`,
+                },
+            });
+        }
+    }
+    // ── Combined safety assertion ─────────────────────────────────────────────
+    /**
+     * Run all pre-execution safety checks.  Call this once at skill load time
+     * before any skill code runs.
+     */
+    assertSafe() {
+        this.assertNotRoot();
+    }
+    // ── Write wrappers ────────────────────────────────────────────────────────
+    /**
+     * Wrap `fs.writeFileSync` (or any function whose first argument is a file
+     * path) so that the path check is applied automatically.
+     *
+     * Example:
+     *   import * as fs from 'node:fs';
+     *   const safeWrite = sandbox.wrapWrite(fs.writeFileSync.bind(fs));
+     *   safeWrite('/tmp/output.txt', data);          // OK
+     *   safeWrite('/etc/cron.d/evil', payload);      // throws
+     */
+    wrapWrite(fn) {
+        return (filePath, ...rest) => {
+            this.assertWritePath(filePath);
+            return fn(filePath, ...rest);
+        };
+    }
+    /**
+     * Wrap an async write function (e.g. `fs.promises.writeFile`).
+     */
+    wrapWriteAsync(fn) {
+        return async (filePath, ...rest) => {
+            this.assertWritePath(filePath);
+            return fn(filePath, ...rest);
+        };
+    }
+    // ── Introspection ─────────────────────────────────────────────────────────
+    /** Return the current write-root this sandbox enforces. */
+    getWriteRoot() {
+        return this.writeRoot;
+    }
+    /** Return true if the process uid check would pass (not root). */
+    isRunningAsRoot() {
+        return getEffectiveUid() === 0;
+    }
+    /**
+     * Return a summary of the sandbox configuration suitable for logging.
+     * Never includes sensitive information.
+     */
+    describe() {
+        return {
+            uid: getEffectiveUid(),
+            writeRoot: this.writeRoot,
+            isRoot: this.isRunningAsRoot(),
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Module-level singleton (convenience export)
+// ---------------------------------------------------------------------------
+/**
+ * A default SkillSandbox instance using the standard /tmp write root.
+ * Import this directly if you don't need custom configuration.
+ */
+export const defaultSandbox = new SkillSandbox();
+//# sourceMappingURL=skill-sandbox.js.map

package/dist/src/trading/skill-sandbox.js.map

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

package/dist/src/utils/path-validation.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Path validation utilities
+ *
+ * SEC-12: rejects user-supplied path segments that could traverse outside
+ * their intended directory. Use on every untrusted string before joining
+ * it into a filesystem path.
+ *
+ * SEC-17: provides atomicWriteFileSync that writes to a temp file and
+ * renames into place, preventing partial writes on crash.
+ */
+/**
+ * Validate and normalize a path component that came from untrusted input.
+ *
+ * Rejects empty strings, `..`, anything containing path separators or NUL,
+ * and anything outside the allowed character set. Returns the validated
+ * value so the call site can use the return rather than the original.
+ *
+ * @throws Error with a stable, non-leaky message on invalid input
+ */
+export declare function sanitizePathPart(part: string): string;
+/**
+ * Sanitize multiple path components in one call.
+ */
+export declare function sanitizePathParts(...parts: string[]): string[];
+/**
+ * SEC-17: atomically write a file by writing to a temp sibling and
+ * renaming over the target. Survives process kill mid-write without
+ * corrupting the destination.
+ */
+export declare function atomicWriteFileSync(targetPath: string, data: string | Buffer | Uint8Array, options?: {
+    mode?: number;
+    encoding?: BufferEncoding;
+}): void;
+//# sourceMappingURL=path-validation.d.ts.map

package/dist/src/utils/path-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-validation.d.ts","sourceRoot":"","sources":["../../../src/utils/path-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAmBrD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAE9D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,EAClC,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,cAAc,CAAA;CAAO,GACzD,IAAI,CAuCN"}

package/dist/src/utils/path-validation.js

@@ -0,0 +1,88 @@
+/**
+ * Path validation utilities
+ *
+ * SEC-12: rejects user-supplied path segments that could traverse outside
+ * their intended directory. Use on every untrusted string before joining
+ * it into a filesystem path.
+ *
+ * SEC-17: provides atomicWriteFileSync that writes to a temp file and
+ * renames into place, preventing partial writes on crash.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+const VALID_PATH_PART = /^[a-zA-Z0-9._-]{1,128}$/;
+/**
+ * Validate and normalize a path component that came from untrusted input.
+ *
+ * Rejects empty strings, `..`, anything containing path separators or NUL,
+ * and anything outside the allowed character set. Returns the validated
+ * value so the call site can use the return rather than the original.
+ *
+ * @throws Error with a stable, non-leaky message on invalid input
+ */
+export function sanitizePathPart(part) {
+    if (typeof part !== 'string' || part.length === 0) {
+        throw new Error('Invalid path component: must be a non-empty string');
+    }
+    if (part === '.' ||
+        part === '..' ||
+        part.includes('/') ||
+        part.includes('\\') ||
+        part.includes('\0')) {
+        throw new Error('Invalid path component: contains forbidden characters');
+    }
+    if (!VALID_PATH_PART.test(part)) {
+        throw new Error('Invalid path component: only [a-zA-Z0-9._-] up to 128 chars allowed');
+    }
+    return part;
+}
+/**
+ * Sanitize multiple path components in one call.
+ */
+export function sanitizePathParts(...parts) {
+    return parts.map(sanitizePathPart);
+}
+/**
+ * SEC-17: atomically write a file by writing to a temp sibling and
+ * renaming over the target. Survives process kill mid-write without
+ * corrupting the destination.
+ */
+export function atomicWriteFileSync(targetPath, data, options = {}) {
+    const dir = path.dirname(targetPath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    // Unique temp name so concurrent writers don't clobber each other
+    const tmpPath = path.join(dir, `.${path.basename(targetPath)}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+    let fd = null;
+    try {
+        fd = fs.openSync(tmpPath, 'w', options.mode ?? 0o600);
+        const buf = typeof data === 'string'
+            ? Buffer.from(data, options.encoding ?? 'utf8')
+            : Buffer.from(data);
+        fs.writeSync(fd, buf, 0, buf.length, 0);
+        fs.fsyncSync(fd);
+        fs.closeSync(fd);
+        fd = null;
+        fs.renameSync(tmpPath, targetPath);
+    }
+    catch (err) {
+        if (fd !== null) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch {
+            /* ignore */
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=path-validation.js.map

package/dist/src/utils/path-validation.js.map

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