defense-mcp-server 0.6.0

package/build/core/sanitizer.js

@@ -0,0 +1,459 @@
+import { resolve, normalize } from "node:path";
+import { getConfig } from "./config.js";
+/**
+ * Regex matching dangerous shell metacharacters.
+ * These characters could enable command injection if passed unsanitized.
+ */
+const SHELL_METACHAR_RE = /[;|&$`(){}<>!\\\n\r]/;
+/**
+ * Regex matching control characters (excluding tab, newline, carriage return
+ * which are handled by SHELL_METACHAR_RE where dangerous).
+ */
+const CONTROL_CHAR_RE = /[\x00-\x08\x0e-\x1f\x7f]/;
+/**
+ * Regex matching path traversal components (`..` as a directory segment).
+ */
+const PATH_TRAVERSAL_RE = /(^|[\/\\])\.\.([\/\\]|$)/;
+/**
+ * Validates a target string as hostname, IPv4, IPv6, or CIDR notation.
+ * Throws on invalid input.
+ */
+export function validateTarget(target, config) {
+    if (!target || typeof target !== "string") {
+        throw new Error("Target must be a non-empty string");
+    }
+    const trimmed = target.trim();
+    if (SHELL_METACHAR_RE.test(trimmed)) {
+        throw new Error(`Target contains forbidden shell metacharacters: ${trimmed}`);
+    }
+    if (CONTROL_CHAR_RE.test(trimmed)) {
+        throw new Error(`Target contains control characters: ${trimmed}`);
+    }
+    // IPv4 with optional CIDR
+    const ipv4Re = /^(\d{1,3}\.){3}\d{1,3}(\/\d{1,2})?$/;
+    // IPv6 (simplified)
+    const ipv6Re = /^[0-9a-fA-F:]+(%[a-zA-Z0-9]+)?(\/\d{1,3})?$/;
+    // Hostname
+    const hostnameRe = /^[a-zA-Z0-9]([a-zA-Z0-9._-]{0,253}[a-zA-Z0-9])?$/;
+    if (!ipv4Re.test(trimmed) &&
+        !ipv6Re.test(trimmed) &&
+        !hostnameRe.test(trimmed)) {
+        throw new Error(`Invalid target format: ${trimmed}`);
+    }
+    // Validate IPv4 octets if it looks like IPv4
+    if (ipv4Re.test(trimmed)) {
+        const ipPart = trimmed.split("/")[0];
+        const octets = ipPart.split(".").map(Number);
+        if (octets.some((o) => o < 0 || o > 255)) {
+            throw new Error(`Invalid IPv4 address: ${trimmed}`);
+        }
+        // Validate CIDR prefix
+        if (trimmed.includes("/")) {
+            const prefix = parseInt(trimmed.split("/")[1], 10);
+            if (prefix < 0 || prefix > 32) {
+                throw new Error(`Invalid CIDR prefix: ${trimmed}`);
+            }
+        }
+    }
+    return trimmed;
+}
+/**
+ * Validates a single port number (1-65535).
+ * Throws on invalid input.
+ */
+export function validatePort(port) {
+    const num = typeof port === "string" ? parseInt(port, 10) : port;
+    if (isNaN(num) || num < 1 || num > 65535 || !Number.isInteger(num)) {
+        throw new Error(`Invalid port number: ${port}. Must be 1-65535`);
+    }
+    return num;
+}
+/**
+ * Validates a port range specification (e.g., "80,443,1-1024").
+ * Throws on invalid input.
+ */
+export function validatePortRange(range) {
+    if (!range || typeof range !== "string") {
+        throw new Error("Port range must be a non-empty string");
+    }
+    const trimmed = range.trim();
+    if (SHELL_METACHAR_RE.test(trimmed)) {
+        throw new Error(`Port range contains forbidden shell metacharacters: ${trimmed}`);
+    }
+    const portRangeRe = /^(\d{1,5}(-\d{1,5})?,)*\d{1,5}(-\d{1,5})?$/;
+    if (!portRangeRe.test(trimmed)) {
+        throw new Error(`Invalid port range format: ${trimmed}`);
+    }
+    // Validate individual port numbers and ranges
+    const parts = trimmed.split(",");
+    for (const part of parts) {
+        if (part.includes("-")) {
+            const [startStr, endStr] = part.split("-");
+            const start = parseInt(startStr, 10);
+            const end = parseInt(endStr, 10);
+            if (start < 1 || start > 65535 || end < 1 || end > 65535) {
+                throw new Error(`Port out of range in: ${part}`);
+            }
+            if (start > end) {
+                throw new Error(`Invalid port range (start > end): ${part}`);
+            }
+        }
+        else {
+            const p = parseInt(part, 10);
+            if (p < 1 || p > 65535) {
+                throw new Error(`Port out of range: ${part}`);
+            }
+        }
+    }
+    return trimmed;
+}
+/**
+ * Validates a file path is within allowed directories,
+ * contains no traversal attacks, no null bytes, no shell metacharacters.
+ * Throws on invalid input.
+ */
+export function validateFilePath(filePath, config) {
+    if (!filePath || typeof filePath !== "string") {
+        throw new Error("File path must be a non-empty string");
+    }
+    // Check for null bytes
+    if (filePath.includes("\0")) {
+        throw new Error("File path contains null bytes");
+    }
+    // Check for path traversal
+    if (PATH_TRAVERSAL_RE.test(filePath)) {
+        throw new Error("Path contains forbidden directory traversal (..)");
+    }
+    // Check for shell metacharacters
+    if (SHELL_METACHAR_RE.test(filePath)) {
+        throw new Error(`File path contains forbidden shell metacharacters: ${filePath}`);
+    }
+    // Check for control characters
+    if (CONTROL_CHAR_RE.test(filePath)) {
+        throw new Error(`File path contains control characters: ${filePath}`);
+    }
+    const normalized = normalize(resolve(filePath));
+    const cfg = config ?? getConfig();
+    // Check path traversal - ensure resolved path doesn't escape allowed dirs
+    const isAllowed = cfg.allowedDirs.some((dir) => {
+        const normalizedDir = normalize(resolve(dir));
+        return (normalized === normalizedDir || normalized.startsWith(normalizedDir + "/"));
+    });
+    if (!isAllowed) {
+        throw new Error(`File path is not within allowed directories: ${filePath} (allowed: ${cfg.allowedDirs.join(", ")})`);
+    }
+    // Check against protected paths
+    const isProtected = cfg.protectedPaths.some((protectedPath) => {
+        const normalizedProtected = normalize(resolve(protectedPath));
+        return (normalized === normalizedProtected ||
+            normalized.startsWith(normalizedProtected + "/"));
+    });
+    if (isProtected) {
+        throw new Error(`File path is in a protected location: ${filePath}`);
+    }
+    return normalized;
+}
+/**
+ * Validates an array of arguments for shell metacharacters.
+ * Throws on invalid input.
+ */
+export function sanitizeArgs(args) {
+    if (!Array.isArray(args)) {
+        throw new Error("Arguments must be an array of strings");
+    }
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (typeof arg !== "string") {
+            throw new Error(`Argument at index ${i} is not a string`);
+        }
+        if (SHELL_METACHAR_RE.test(arg)) {
+            throw new Error(`Argument at index ${i} contains forbidden shell metacharacters: ${arg}`);
+        }
+        if (CONTROL_CHAR_RE.test(arg)) {
+            throw new Error(`Argument at index ${i} contains control characters: ${arg}`);
+        }
+    }
+    return args;
+}
+/**
+ * Validates a systemd service name.
+ * Only allows `[a-zA-Z0-9._@-]+`.
+ * Throws on invalid input.
+ */
+export function validateServiceName(name) {
+    if (!name || typeof name !== "string") {
+        throw new Error("Service name must be a non-empty string");
+    }
+    const trimmed = name.trim();
+    const serviceRe = /^[a-zA-Z0-9._@-]+$/;
+    if (!serviceRe.test(trimmed)) {
+        throw new Error(`Invalid service name: ${trimmed}. Only [a-zA-Z0-9._@-] allowed`);
+    }
+    return trimmed;
+}
+/**
+ * Validates a sysctl key (must be word.word.word... pattern).
+ * Throws on invalid input.
+ */
+export function validateSysctlKey(key) {
+    if (!key || typeof key !== "string") {
+        throw new Error("Sysctl key must be a non-empty string");
+    }
+    const trimmed = key.trim();
+    const sysctlRe = /^[a-zA-Z0-9_]+(\.[a-zA-Z0-9_]+)+$/;
+    if (!sysctlRe.test(trimmed)) {
+        throw new Error(`Invalid sysctl key: ${trimmed}. Must match word.word.word pattern`);
+    }
+    return trimmed;
+}
+/**
+ * Validates a configuration key.
+ * Only allows `[a-zA-Z0-9._-]+`.
+ * Throws on invalid input.
+ */
+export function validateConfigKey(key) {
+    if (!key || typeof key !== "string") {
+        throw new Error("Config key must be a non-empty string");
+    }
+    const trimmed = key.trim();
+    const configRe = /^[a-zA-Z0-9._-]+$/;
+    if (!configRe.test(trimmed)) {
+        throw new Error(`Invalid config key: ${trimmed}. Only [a-zA-Z0-9._-] allowed`);
+    }
+    return trimmed;
+}
+/**
+ * Validates a package name.
+ * Only allows `[a-zA-Z0-9._+:-]+`.
+ * Throws on invalid input.
+ */
+export function validatePackageName(name) {
+    if (!name || typeof name !== "string") {
+        throw new Error("Package name must be a non-empty string");
+    }
+    const trimmed = name.trim();
+    const pkgRe = /^[a-zA-Z0-9._+:-]+$/;
+    if (!pkgRe.test(trimmed)) {
+        throw new Error(`Invalid package name: ${trimmed}. Only [a-zA-Z0-9._+:-] allowed`);
+    }
+    return trimmed;
+}
+/**
+ * Validates an iptables chain name.
+ * Allows built-in chains `[A-Z_]+` (e.g., INPUT, OUTPUT, FORWARD)
+ * and custom chains matching `[A-Za-z_][A-Za-z0-9_-]{0,28}`.
+ * Throws on invalid input.
+ */
+export function validateIptablesChain(chain) {
+    if (!chain || typeof chain !== "string") {
+        throw new Error("Iptables chain must be a non-empty string");
+    }
+    const trimmed = chain.trim();
+    // Allow both built-in (e.g. INPUT) and custom chains (e.g. syn_flood)
+    const chainRe = /^[A-Za-z_][A-Za-z0-9_-]{0,28}$/;
+    if (!chainRe.test(trimmed)) {
+        throw new Error(`Invalid iptables chain: ${trimmed}. Must match [A-Za-z_][A-Za-z0-9_-]{0,28}`);
+    }
+    return trimmed;
+}
+/**
+ * Validates a network interface name.
+ * Only allows `[a-zA-Z0-9._-]+`, max 16 characters.
+ * Throws on invalid input.
+ */
+export function validateInterface(iface) {
+    if (!iface || typeof iface !== "string") {
+        throw new Error("Interface name must be a non-empty string");
+    }
+    const trimmed = iface.trim();
+    if (trimmed.length > 16) {
+        throw new Error(`Interface name too long: ${trimmed}. Maximum 16 characters`);
+    }
+    const ifaceRe = /^[a-zA-Z0-9._-]+$/;
+    if (!ifaceRe.test(trimmed)) {
+        throw new Error(`Invalid interface name: ${trimmed}. Only [a-zA-Z0-9._-] allowed`);
+    }
+    return trimmed;
+}
+/**
+ * Validates a Unix username.
+ * Only allows `[a-zA-Z0-9._-]+`, max 32 characters.
+ * Throws on invalid input.
+ */
+export function validateUsername(name) {
+    if (!name || typeof name !== "string") {
+        throw new Error("Username must be a non-empty string");
+    }
+    const trimmed = name.trim();
+    if (trimmed.length > 32) {
+        throw new Error(`Username too long: ${trimmed}. Maximum 32 characters`);
+    }
+    const usernameRe = /^[a-zA-Z0-9._-]+$/;
+    if (!usernameRe.test(trimmed)) {
+        throw new Error(`Invalid username: ${trimmed}. Only [a-zA-Z0-9._-] allowed`);
+    }
+    return trimmed;
+}
+/**
+ * Validates a YARA rule file path (must end in .yar or .yara).
+ * Throws on invalid input.
+ */
+export function validateYaraRule(path) {
+    if (!path || typeof path !== "string") {
+        throw new Error("YARA rule path must be a non-empty string");
+    }
+    const trimmed = path.trim();
+    if (PATH_TRAVERSAL_RE.test(trimmed)) {
+        throw new Error("Path contains forbidden directory traversal (..)");
+    }
+    if (SHELL_METACHAR_RE.test(trimmed)) {
+        throw new Error(`YARA rule path contains forbidden shell metacharacters: ${trimmed}`);
+    }
+    if (CONTROL_CHAR_RE.test(trimmed)) {
+        throw new Error(`YARA rule path contains control characters: ${trimmed}`);
+    }
+    if (!trimmed.endsWith(".yar") && !trimmed.endsWith(".yara")) {
+        throw new Error(`Invalid YARA rule file: ${trimmed}. Must end in .yar or .yara`);
+    }
+    return trimmed;
+}
+/**
+ * Validates a certificate file path (must end in .pem, .crt, .key, .p12, or .pfx).
+ * Throws on invalid input.
+ */
+export function validateCertPath(path) {
+    if (!path || typeof path !== "string") {
+        throw new Error("Certificate path must be a non-empty string");
+    }
+    const trimmed = path.trim();
+    if (PATH_TRAVERSAL_RE.test(trimmed)) {
+        throw new Error("Path contains forbidden directory traversal (..)");
+    }
+    if (SHELL_METACHAR_RE.test(trimmed)) {
+        throw new Error(`Certificate path contains forbidden shell metacharacters: ${trimmed}`);
+    }
+    if (CONTROL_CHAR_RE.test(trimmed)) {
+        throw new Error(`Certificate path contains control characters: ${trimmed}`);
+    }
+    const validExtensions = [".pem", ".crt", ".key", ".p12", ".pfx"];
+    const hasValidExt = validExtensions.some((ext) => trimmed.toLowerCase().endsWith(ext));
+    if (!hasValidExt) {
+        throw new Error(`Invalid certificate file: ${trimmed}. Must end in ${validExtensions.join(", ")}`);
+    }
+    return trimmed;
+}
+/**
+ * Validates a firewalld zone name.
+ * Only allows `[a-zA-Z0-9_-]+`.
+ * Throws on invalid input.
+ */
+export function validateFirewallZone(zone) {
+    if (!zone || typeof zone !== "string") {
+        throw new Error("Firewall zone must be a non-empty string");
+    }
+    const trimmed = zone.trim();
+    const zoneRe = /^[a-zA-Z0-9_-]+$/;
+    if (!zoneRe.test(trimmed)) {
+        throw new Error(`Invalid firewall zone: ${trimmed}. Only [a-zA-Z0-9_-] allowed`);
+    }
+    return trimmed;
+}
+/**
+ * Validates an auditd key name.
+ * Only allows `[a-zA-Z0-9_-]+`.
+ * Throws on invalid input.
+ */
+export function validateAuditdKey(key) {
+    if (!key || typeof key !== "string") {
+        throw new Error("Auditd key must be a non-empty string");
+    }
+    const trimmed = key.trim();
+    const keyRe = /^[a-zA-Z0-9_-]+$/;
+    if (!keyRe.test(trimmed)) {
+        throw new Error(`Invalid auditd key: ${trimmed}. Only [a-zA-Z0-9_-] allowed`);
+    }
+    return trimmed;
+}
+/**
+ * Validates a tool-supplied file path against traversal attacks and an explicit
+ * list of allowed root directories.
+ *
+ * 1. Rejects paths containing `..`
+ * 2. Uses `path.resolve()` to normalize
+ * 3. Verifies resolved path is within one of the allowed directories
+ *
+ * @param inputPath  The user-supplied path
+ * @param allowedDirs  Array of allowed root directories (e.g. ["/var/log", "/etc"])
+ * @param label  Human-readable label for error messages (default: "Path")
+ * @returns The resolved, validated path
+ */
+export function validateToolPath(inputPath, allowedDirs, label = "Path") {
+    if (!inputPath || typeof inputPath !== "string") {
+        throw new Error(`${label} must be a non-empty string`);
+    }
+    if (inputPath.includes("\0")) {
+        throw new Error(`${label} contains null bytes`);
+    }
+    // Defense-in-depth: reject any path containing `..` sequences
+    if (PATH_TRAVERSAL_RE.test(inputPath)) {
+        throw new Error(`${label} contains forbidden directory traversal (..): '${inputPath}'`);
+    }
+    if (SHELL_METACHAR_RE.test(inputPath)) {
+        throw new Error(`${label} contains forbidden shell metacharacters: '${inputPath}'`);
+    }
+    if (CONTROL_CHAR_RE.test(inputPath)) {
+        throw new Error(`${label} contains control characters: '${inputPath}'`);
+    }
+    const resolved = normalize(resolve(inputPath));
+    const isAllowed = allowedDirs.some((dir) => {
+        const normalizedDir = normalize(resolve(dir));
+        return (resolved === normalizedDir || resolved.startsWith(normalizedDir + "/"));
+    });
+    if (!isAllowed) {
+        throw new Error(`${label} '${resolved}' is not within allowed directories: ${allowedDirs.join(", ")}`);
+    }
+    return resolved;
+}
+// ── Error Sanitization ───────────────────────────────────────────────────────
+/**
+ * SECURITY (TOOL-029): Regex to match absolute paths in error messages.
+ * Matches paths like /home/user/... or /var/lib/...
+ */
+const ABS_PATH_RE = /\/(?:home|root|tmp|var|etc|usr|opt|srv|run|mnt|media)\/\S*/gi;
+/**
+ * SECURITY (TOOL-029): Regex to match stack traces in error messages.
+ * Matches lines starting with "    at " (Node.js stack trace format).
+ */
+const STACK_TRACE_RE = /\n\s+at .+/g;
+/**
+ * Sanitize error messages before returning them to MCP clients.
+ *
+ * Strips:
+ * 1. Absolute file paths (replaced with `[path]`)
+ * 2. Stack traces (removed entirely)
+ * 3. Overly long messages (truncated to 500 chars)
+ *
+ * @param error - The caught error (unknown type)
+ * @returns A sanitized error message string safe for external exposure
+ */
+export function sanitizeToolError(error) {
+    let message;
+    if (error instanceof Error) {
+        message = error.message;
+    }
+    else if (typeof error === "string") {
+        message = error;
+    }
+    else {
+        message = String(error);
+    }
+    // Strip stack traces
+    message = message.replace(STACK_TRACE_RE, "");
+    // Strip absolute paths
+    message = message.replace(ABS_PATH_RE, "[path]");
+    // Truncate overly long messages
+    if (message.length > 500) {
+        message = message.substring(0, 497) + "...";
+    }
+    return message;
+}

package/build/core/secure-fs.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Secure filesystem utilities for the defense-mcp-server.
+ * All state files (changelog, rollback, backups) must use these helpers
+ * to ensure restrictive permissions (owner-only read/write).
+ */
+/** Options for secureWriteFileSync. */
+export interface SecureWriteOptions {
+    /** Character encoding for string data. Defaults to `"utf-8"`. */
+    encoding?: BufferEncoding;
+    /** Use atomic write (write to temp file, then rename). Defaults to `false`. */
+    atomic?: boolean;
+}
+/**
+ * Write a file with owner-only permissions (0o600).
+ * Creates parent directories with 0o700 if they don't exist.
+ *
+ * @param filePath - Destination file path
+ * @param data - Content to write
+ * @param encodingOrOptions - Either a BufferEncoding string (legacy) or a SecureWriteOptions object
+ */
+export declare function secureWriteFileSync(filePath: string, data: string | Buffer, encodingOrOptions?: BufferEncoding | SecureWriteOptions): void;
+/**
+ * Create a directory with owner-only permissions (0o700).
+ */
+export declare function secureMkdirSync(dirPath: string): void;
+/**
+ * Copy a file and set owner-only permissions on the destination (0o600).
+ */
+export declare function secureCopyFileSync(src: string, dest: string): void;
+/**
+ * Verify that a state file has secure permissions.
+ * Returns true if the file is owner-only (no group/other read/write/execute).
+ * Returns false if permissions are too open or file doesn't exist.
+ */
+export declare function verifySecurePermissions(filePath: string): boolean;
+/**
+ * Fix permissions on an existing file to be owner-only.
+ */
+export declare function hardenFilePermissions(filePath: string): void;
+/**
+ * Fix permissions on an existing directory to be owner-only.
+ */
+export declare function hardenDirPermissions(dirPath: string): void;
+/** Options for atomicWriteFileSync. */
+export interface AtomicWriteOptions {
+    /** File permissions mode. Defaults to `0o600`. */
+    mode?: number;
+    /** Character encoding for string data. Defaults to `"utf-8"`. */
+    encoding?: BufferEncoding;
+}
+/**
+ * Write a file atomically using a write-to-temp-then-rename strategy.
+ *
+ * Steps:
+ * 1. Write data to a temporary file in the same directory (`.tmp` suffix)
+ * 2. Set file permissions on the temp file
+ * 3. Rename (atomic on POSIX) from temp to target path
+ * 4. If rename fails, clean up the temp file
+ *
+ * This prevents file corruption from interrupted writes (crash, signal, etc.).
+ *
+ * @param filePath - Destination file path
+ * @param data - Content to write (string or Buffer)
+ * @param options - Write options (mode, encoding)
+ */
+export declare function atomicWriteFileSync(filePath: string, data: string | Buffer, options?: AtomicWriteOptions): void;
+//# sourceMappingURL=secure-fs.d.ts.map

package/build/core/secure-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secure-fs.d.ts","sourceRoot":"","sources":["../../src/core/secure-fs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IAC/B,iEAAiE;IACjE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,+EAA+E;IAC/E,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,iBAAiB,CAAC,EAAE,cAAc,GAAG,kBAAkB,GACxD,IAAI,CA0BN;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAMrD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAOlE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMjE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAI5D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAI1D;AAID,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IAC/B,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC7B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,OAAO,CAAC,EAAE,kBAAkB,GAC7B,IAAI,CAkCN"}

package/build/core/secure-fs.js

@@ -0,0 +1,143 @@
+/**
+ * Secure filesystem utilities for the defense-mcp-server.
+ * All state files (changelog, rollback, backups) must use these helpers
+ * to ensure restrictive permissions (owner-only read/write).
+ */
+import { writeFileSync, mkdirSync, copyFileSync, chmodSync, existsSync, statSync, renameSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+/** File permission: owner read/write only (0o600) */
+const SECURE_FILE_MODE = 0o600;
+/** Directory permission: owner read/write/execute only (0o700) */
+const SECURE_DIR_MODE = 0o700;
+/**
+ * Write a file with owner-only permissions (0o600).
+ * Creates parent directories with 0o700 if they don't exist.
+ *
+ * @param filePath - Destination file path
+ * @param data - Content to write
+ * @param encodingOrOptions - Either a BufferEncoding string (legacy) or a SecureWriteOptions object
+ */
+export function secureWriteFileSync(filePath, data, encodingOrOptions) {
+    // Normalize options
+    let encoding = "utf-8";
+    let atomic = false;
+    if (typeof encodingOrOptions === "string") {
+        encoding = encodingOrOptions;
+    }
+    else if (encodingOrOptions !== undefined) {
+        encoding = encodingOrOptions.encoding ?? "utf-8";
+        atomic = encodingOrOptions.atomic ?? false;
+    }
+    // Ensure parent directory exists with secure permissions
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: SECURE_DIR_MODE });
+    }
+    if (atomic) {
+        atomicWriteFileSync(filePath, data, { mode: SECURE_FILE_MODE, encoding });
+    }
+    else {
+        // Write the file
+        writeFileSync(filePath, data, { encoding, mode: SECURE_FILE_MODE });
+        // Explicitly chmod in case umask interfered
+        chmodSync(filePath, SECURE_FILE_MODE);
+    }
+}
+/**
+ * Create a directory with owner-only permissions (0o700).
+ */
+export function secureMkdirSync(dirPath) {
+    if (!existsSync(dirPath)) {
+        mkdirSync(dirPath, { recursive: true, mode: SECURE_DIR_MODE });
+    }
+    // Explicitly chmod in case umask interfered
+    chmodSync(dirPath, SECURE_DIR_MODE);
+}
+/**
+ * Copy a file and set owner-only permissions on the destination (0o600).
+ */
+export function secureCopyFileSync(src, dest) {
+    const dir = dirname(dest);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: SECURE_DIR_MODE });
+    }
+    copyFileSync(src, dest);
+    chmodSync(dest, SECURE_FILE_MODE);
+}
+/**
+ * Verify that a state file has secure permissions.
+ * Returns true if the file is owner-only (no group/other read/write/execute).
+ * Returns false if permissions are too open or file doesn't exist.
+ */
+export function verifySecurePermissions(filePath) {
+    if (!existsSync(filePath))
+        return false;
+    const stats = statSync(filePath);
+    // Check that group and other have no permissions
+    // mode & 0o077 should be 0 (no group/other bits set)
+    return (stats.mode & 0o077) === 0;
+}
+/**
+ * Fix permissions on an existing file to be owner-only.
+ */
+export function hardenFilePermissions(filePath) {
+    if (existsSync(filePath)) {
+        chmodSync(filePath, SECURE_FILE_MODE);
+    }
+}
+/**
+ * Fix permissions on an existing directory to be owner-only.
+ */
+export function hardenDirPermissions(dirPath) {
+    if (existsSync(dirPath)) {
+        chmodSync(dirPath, SECURE_DIR_MODE);
+    }
+}
+/**
+ * Write a file atomically using a write-to-temp-then-rename strategy.
+ *
+ * Steps:
+ * 1. Write data to a temporary file in the same directory (`.tmp` suffix)
+ * 2. Set file permissions on the temp file
+ * 3. Rename (atomic on POSIX) from temp to target path
+ * 4. If rename fails, clean up the temp file
+ *
+ * This prevents file corruption from interrupted writes (crash, signal, etc.).
+ *
+ * @param filePath - Destination file path
+ * @param data - Content to write (string or Buffer)
+ * @param options - Write options (mode, encoding)
+ */
+export function atomicWriteFileSync(filePath, data, options) {
+    const mode = options?.mode ?? SECURE_FILE_MODE;
+    const encoding = options?.encoding ?? "utf-8";
+    // Ensure parent directory exists with secure permissions
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: SECURE_DIR_MODE });
+    }
+    // Generate a unique temp file path in the same directory
+    const tmpSuffix = `.tmp.${randomBytes(6).toString("hex")}`;
+    const tmpPath = join(dir, `${filePath.split("/").pop()}${tmpSuffix}`);
+    try {
+        // Step 1: Write to temp file
+        writeFileSync(tmpPath, data, { encoding, mode });
+        // Step 2: Explicitly set permissions (in case umask interfered)
+        chmodSync(tmpPath, mode);
+        // Step 3: Atomic rename
+        renameSync(tmpPath, filePath);
+    }
+    catch (error) {
+        // Step 4: Clean up temp file on failure
+        try {
+            if (existsSync(tmpPath)) {
+                unlinkSync(tmpPath);
+            }
+        }
+        catch {
+            // Best-effort cleanup — ignore errors
+        }
+        throw error;
+    }
+}