ctx-sync 1.0.0

package/dist/core/git-sync.js

@@ -0,0 +1,143 @@
+/**
+ * Git sync engine module.
+ *
+ * Manages the local Git repository used for syncing encrypted state
+ * files between machines. Provides operations for init, commit, push,
+ * pull, and status queries. All remote operations validate transport
+ * security before proceeding.
+ *
+ * @module core/git-sync
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { simpleGit } from 'simple-git';
+import { validateRemoteUrl } from './transport.js';
+/**
+ * Initialise a Git repository in the given directory.
+ *
+ * If the directory already contains a `.git/` folder, this is a no-op.
+ * Otherwise, a new Git repository is created with `git init`.
+ *
+ * @param dir - The directory to initialise.
+ * @returns `true` if a new repo was created, `false` if one already existed.
+ */
+export async function initRepo(dir) {
+    const gitDir = path.join(dir, '.git');
+    if (fs.existsSync(gitDir)) {
+        return false;
+    }
+    // Ensure the directory exists
+    fs.mkdirSync(dir, { recursive: true });
+    const git = simpleGit(dir);
+    await git.init();
+    return true;
+}
+/**
+ * Add a remote to the Git repository.
+ *
+ * Validates the URL using transport security before adding.
+ * If a remote with the given name already exists, it is updated.
+ *
+ * @param dir - The Git repository directory.
+ * @param url - The remote URL (SSH or HTTPS).
+ * @param remoteName - The name for the remote (default: 'origin').
+ * @throws If the URL uses an insecure protocol.
+ */
+export async function addRemote(dir, url, remoteName = 'origin') {
+    validateRemoteUrl(url);
+    const git = simpleGit(dir);
+    const remotes = await git.getRemotes(true);
+    const existing = remotes.find((r) => r.name === remoteName);
+    if (existing) {
+        await git.remote(['set-url', remoteName, url]);
+    }
+    else {
+        await git.addRemote(remoteName, url);
+    }
+}
+/**
+ * Stage files and commit changes to the sync repository.
+ *
+ * Stages the specified files, then commits with the given message.
+ * If there are no changes to commit (working tree is clean after staging),
+ * the commit is skipped and `null` is returned.
+ *
+ * @param dir - The Git repository directory.
+ * @param files - List of file paths (relative to dir) to stage.
+ * @param message - The commit message.
+ * @returns The commit hash, or `null` if no changes were committed.
+ */
+export async function commitState(dir, files, message) {
+    const git = simpleGit(dir);
+    // Stage specified files
+    await git.add(files);
+    // Check if there are staged changes
+    const status = await git.status();
+    const hasStagedChanges = status.staged.length > 0 || status.created.length > 0 || status.deleted.length > 0;
+    if (!hasStagedChanges) {
+        return null; // Nothing to commit
+    }
+    const result = await git.commit(message);
+    return result.commit || null;
+}
+/**
+ * Push the local sync repository to the remote.
+ *
+ * Validates the remote URL before pushing. If no remote is configured,
+ * the push is skipped.
+ *
+ * @param dir - The Git repository directory.
+ * @param remoteName - The remote name (default: 'origin').
+ * @param branch - The branch to push (default: 'main').
+ * @throws If the remote URL uses an insecure protocol.
+ */
+export async function pushState(dir, remoteName = 'origin', branch = 'main') {
+    const git = simpleGit(dir);
+    // Verify remote exists and URL is secure
+    const remotes = await git.getRemotes(true);
+    const remote = remotes.find((r) => r.name === remoteName);
+    if (!remote) {
+        return; // No remote configured — local only
+    }
+    validateRemoteUrl(remote.refs.push || remote.refs.fetch);
+    await git.push(remoteName, branch, ['--set-upstream']);
+}
+/**
+ * Pull the latest changes from the remote sync repository.
+ *
+ * Validates the remote URL before pulling. If no remote is configured,
+ * the pull is skipped.
+ *
+ * @param dir - The Git repository directory.
+ * @param remoteName - The remote name (default: 'origin').
+ * @param branch - The branch to pull (default: 'main').
+ * @throws If the remote URL uses an insecure protocol.
+ */
+export async function pullState(dir, remoteName = 'origin', branch = 'main') {
+    const git = simpleGit(dir);
+    // Verify remote exists and URL is secure
+    const remotes = await git.getRemotes(true);
+    const remote = remotes.find((r) => r.name === remoteName);
+    if (!remote) {
+        return; // No remote configured — local only
+    }
+    validateRemoteUrl(remote.refs.fetch || remote.refs.push);
+    await git.pull(remoteName, branch);
+}
+/**
+ * Get the current sync status of the repository.
+ *
+ * @param dir - The Git repository directory.
+ * @returns An object describing changed files, ahead/behind counts, and cleanliness.
+ */
+export async function getStatus(dir) {
+    const git = simpleGit(dir);
+    const status = await git.status();
+    return {
+        files: status.files.map((f) => f.path),
+        ahead: status.ahead,
+        behind: status.behind,
+        isClean: status.isClean(),
+    };
+}
+//# sourceMappingURL=git-sync.js.map

package/dist/core/git-sync.js.map

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

package/dist/core/key-store.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Key persistence module.
+ *
+ * Handles saving and loading the Age private key to/from disk
+ * with strict file permission enforcement. The private key file
+ * is stored at 0o600 (owner read/write only) and the config
+ * directory at 0o700 (owner read/write/execute only).
+ *
+ * @module core/key-store
+ */
+/** Required permissions for the private key file */
+export declare const KEY_FILE_PERMS = 384;
+/** Required permissions for the config directory */
+export declare const CONFIG_DIR_PERMS = 448;
+/** Default key file name */
+export declare const KEY_FILE_NAME = "key.txt";
+/**
+ * Save a private key to disk with strict permissions.
+ *
+ * Creates the config directory with 0o700 permissions if it does not exist,
+ * then writes the key file with 0o600 permissions.
+ *
+ * @param configDir - The config directory path (e.g. ~/.config/ctx-sync).
+ * @param privateKey - The Age private key string (AGE-SECRET-KEY-...).
+ */
+export declare function saveKey(configDir: string, privateKey: string): void;
+/**
+ * Load a private key from disk, verifying permissions are secure.
+ *
+ * Checks that the key file exists and has exactly 0o600 permissions
+ * before reading. Throws with a helpful error if permissions are insecure.
+ *
+ * @param configDir - The config directory path (e.g. ~/.config/ctx-sync).
+ * @returns The Age private key string.
+ * @throws If the key file does not exist or has insecure permissions.
+ */
+export declare function loadKey(configDir: string): string;
+/**
+ * Verify that key file and config directory have correct permissions.
+ *
+ * @param configDir - The config directory path.
+ * @returns An object describing the verification result.
+ */
+export declare function verifyPermissions(configDir: string): {
+    valid: boolean;
+    keyFileExists: boolean;
+    keyFilePerms: number | null;
+    configDirPerms: number | null;
+    issues: string[];
+};
+//# sourceMappingURL=key-store.d.ts.map

package/dist/core/key-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-store.d.ts","sourceRoot":"","sources":["../../src/core/key-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,oDAAoD;AACpD,eAAO,MAAM,cAAc,MAAQ,CAAC;AAEpC,oDAAoD;AACpD,eAAO,MAAM,gBAAgB,MAAQ,CAAC;AAEtC,4BAA4B;AAC5B,eAAO,MAAM,aAAa,YAAY,CAAC;AAEvC;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CASnE;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAwBjD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG;IACpD,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,OAAO,CAAC;IACvB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CA4CA"}

package/dist/core/key-store.js

@@ -0,0 +1,108 @@
+/**
+ * Key persistence module.
+ *
+ * Handles saving and loading the Age private key to/from disk
+ * with strict file permission enforcement. The private key file
+ * is stored at 0o600 (owner read/write only) and the config
+ * directory at 0o700 (owner read/write/execute only).
+ *
+ * @module core/key-store
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/** Required permissions for the private key file */
+export const KEY_FILE_PERMS = 0o600;
+/** Required permissions for the config directory */
+export const CONFIG_DIR_PERMS = 0o700;
+/** Default key file name */
+export const KEY_FILE_NAME = 'key.txt';
+/**
+ * Save a private key to disk with strict permissions.
+ *
+ * Creates the config directory with 0o700 permissions if it does not exist,
+ * then writes the key file with 0o600 permissions.
+ *
+ * @param configDir - The config directory path (e.g. ~/.config/ctx-sync).
+ * @param privateKey - The Age private key string (AGE-SECRET-KEY-...).
+ */
+export function saveKey(configDir, privateKey) {
+    // Create directory with 0o700 if it doesn't exist
+    fs.mkdirSync(configDir, { recursive: true, mode: CONFIG_DIR_PERMS });
+    // Ensure directory has correct permissions even if it already existed
+    fs.chmodSync(configDir, CONFIG_DIR_PERMS);
+    const keyPath = path.join(configDir, KEY_FILE_NAME);
+    fs.writeFileSync(keyPath, privateKey, { mode: KEY_FILE_PERMS });
+}
+/**
+ * Load a private key from disk, verifying permissions are secure.
+ *
+ * Checks that the key file exists and has exactly 0o600 permissions
+ * before reading. Throws with a helpful error if permissions are insecure.
+ *
+ * @param configDir - The config directory path (e.g. ~/.config/ctx-sync).
+ * @returns The Age private key string.
+ * @throws If the key file does not exist or has insecure permissions.
+ */
+export function loadKey(configDir) {
+    const keyPath = path.join(configDir, KEY_FILE_NAME);
+    // Check file exists
+    if (!fs.existsSync(keyPath)) {
+        throw new Error(`Key file not found: ${keyPath}\n` +
+            'Run `ctx-sync init` to generate an encryption key, or\n' +
+            'Run `ctx-sync init --restore` to restore from a backup.');
+    }
+    // Verify permissions before reading
+    const stats = fs.statSync(keyPath);
+    const mode = stats.mode & 0o777;
+    if (mode !== KEY_FILE_PERMS) {
+        throw new Error(`Key file has insecure permissions (${mode.toString(8)}). Expected 600.\n` +
+            `Fix with: chmod 600 ${keyPath}`);
+    }
+    return fs.readFileSync(keyPath, 'utf-8').trim();
+}
+/**
+ * Verify that key file and config directory have correct permissions.
+ *
+ * @param configDir - The config directory path.
+ * @returns An object describing the verification result.
+ */
+export function verifyPermissions(configDir) {
+    const issues = [];
+    const keyPath = path.join(configDir, KEY_FILE_NAME);
+    let keyFileExists = false;
+    let keyFilePerms = null;
+    let configDirPerms = null;
+    // Check config directory
+    if (fs.existsSync(configDir)) {
+        const dirStats = fs.statSync(configDir);
+        configDirPerms = dirStats.mode & 0o777;
+        if (configDirPerms !== CONFIG_DIR_PERMS) {
+            issues.push(`Config directory has permissions ${configDirPerms.toString(8)}, expected 700. ` +
+                `Fix with: chmod 700 ${configDir}`);
+        }
+    }
+    else {
+        issues.push(`Config directory does not exist: ${configDir}`);
+    }
+    // Check key file
+    if (fs.existsSync(keyPath)) {
+        keyFileExists = true;
+        const fileStats = fs.statSync(keyPath);
+        keyFilePerms = fileStats.mode & 0o777;
+        if (keyFilePerms !== KEY_FILE_PERMS) {
+            issues.push(`Key file has permissions ${keyFilePerms.toString(8)}, expected 600. ` +
+                `Fix with: chmod 600 ${keyPath}`);
+        }
+    }
+    else {
+        issues.push(`Key file not found: ${keyPath}`);
+    }
+    return {
+        valid: issues.length === 0,
+        keyFileExists,
+        keyFilePerms,
+        configDirPerms,
+        issues,
+    };
+}
+//# sourceMappingURL=key-store.js.map

package/dist/core/key-store.js.map

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

package/dist/core/log-sanitizer.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Log sanitizer module.
+ *
+ * Redacts known secret patterns from log messages, error messages,
+ * and stack traces. Wraps console output to ensure secrets never
+ * appear in logs — even when `DEBUG=*` is set.
+ *
+ * **Security property:** No secret value ever appears in any log output.
+ *
+ * Patterns detected and redacted:
+ * - Stripe keys (`sk_live_*`, `sk_test_*`)
+ * - GitHub PATs (`ghp_*`, `gho_*`, `github_pat_*`)
+ * - Slack tokens (`xoxb-*`, `xoxp-*`)
+ * - Google API keys (`AIzaSy*`)
+ * - AWS access keys (`AKIA*`)
+ * - SendGrid keys (`SG.*`)
+ * - Twilio SIDs (`AC` + 32 hex)
+ * - OpenAI keys (`sk-*` 20+ chars)
+ * - Age secret keys (`AGE-SECRET-KEY-*`)
+ * - JWTs (`eyJ*...*`)
+ * - PEM private keys
+ * - URLs with embedded credentials
+ * - Generic `password=`, `secret=`, `token=`, `key=` patterns
+ *
+ * @module core/log-sanitizer
+ */
+/**
+ * Sanitize a message by redacting known secret patterns.
+ *
+ * Applies all known secret pattern regexes and replaces matches
+ * with redacted placeholders. Safe values pass through unchanged.
+ *
+ * @param message - The log message to sanitize.
+ * @returns The sanitized message with secrets redacted.
+ */
+export declare function sanitizeForLog(message: string): string;
+/**
+ * Sanitize an error object's message and stack trace.
+ *
+ * Returns a new Error with sanitized message and stack. The original
+ * error is not modified.
+ *
+ * @param error - The error to sanitize.
+ * @returns A new Error with sanitized message and stack.
+ */
+export declare function sanitizeError(error: Error): Error;
+/**
+ * Wrap all console output methods through the sanitizer.
+ *
+ * After calling this function, all `console.log`, `console.error`,
+ * `console.warn`, and `console.debug` calls will have their arguments
+ * sanitized before output.
+ *
+ * Call `unwrapConsole()` to restore original behaviour.
+ *
+ * **Security:** This ensures that even if a developer accidentally
+ * logs a secret value, it will be redacted before reaching the terminal.
+ */
+export declare function wrapConsole(): void;
+/**
+ * Restore original console methods (unwrap the sanitizer).
+ *
+ * Safe to call even if `wrapConsole()` was never called.
+ */
+export declare function unwrapConsole(): void;
+/**
+ * Check whether the console is currently wrapped by the sanitizer.
+ *
+ * @returns `true` if `wrapConsole()` has been called and `unwrapConsole()` has not.
+ */
+export declare function isConsoleWrapped(): boolean;
+//# sourceMappingURL=log-sanitizer.d.ts.map

package/dist/core/log-sanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-sanitizer.d.ts","sourceRoot":"","sources":["../../src/core/log-sanitizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAkEH;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CActD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAOjD;AAWD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,IAAI,IAAI,CA0ClC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAgBpC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C"}

package/dist/core/log-sanitizer.js

@@ -0,0 +1,202 @@
+/**
+ * Log sanitizer module.
+ *
+ * Redacts known secret patterns from log messages, error messages,
+ * and stack traces. Wraps console output to ensure secrets never
+ * appear in logs — even when `DEBUG=*` is set.
+ *
+ * **Security property:** No secret value ever appears in any log output.
+ *
+ * Patterns detected and redacted:
+ * - Stripe keys (`sk_live_*`, `sk_test_*`)
+ * - GitHub PATs (`ghp_*`, `gho_*`, `github_pat_*`)
+ * - Slack tokens (`xoxb-*`, `xoxp-*`)
+ * - Google API keys (`AIzaSy*`)
+ * - AWS access keys (`AKIA*`)
+ * - SendGrid keys (`SG.*`)
+ * - Twilio SIDs (`AC` + 32 hex)
+ * - OpenAI keys (`sk-*` 20+ chars)
+ * - Age secret keys (`AGE-SECRET-KEY-*`)
+ * - JWTs (`eyJ*...*`)
+ * - PEM private keys
+ * - URLs with embedded credentials
+ * - Generic `password=`, `secret=`, `token=`, `key=` patterns
+ *
+ * @module core/log-sanitizer
+ */
+const REDACTED = '***REDACTED***';
+/**
+ * Secret patterns to redact from log output.
+ *
+ * Each entry maps a regex to a replacement function. The regex
+ * should match the full secret token; the replacement function
+ * returns the redacted version (preserving a prefix for debugging
+ * context where possible).
+ */
+const SECRET_PATTERNS = [
+    // Stripe keys
+    { pattern: /\bsk_live_[a-zA-Z0-9_]+/g, replacement: `sk_live_${REDACTED}` },
+    { pattern: /\bsk_test_[a-zA-Z0-9_]+/g, replacement: `sk_test_${REDACTED}` },
+    // GitHub tokens
+    { pattern: /\bghp_[a-zA-Z0-9]+/g, replacement: `ghp_${REDACTED}` },
+    { pattern: /\bgho_[a-zA-Z0-9]+/g, replacement: `gho_${REDACTED}` },
+    { pattern: /\bgithub_pat_[a-zA-Z0-9_]+/g, replacement: `github_pat_${REDACTED}` },
+    // Slack tokens
+    { pattern: /\bxoxb-[a-zA-Z0-9-]+/g, replacement: `xoxb-${REDACTED}` },
+    { pattern: /\bxoxp-[a-zA-Z0-9-]+/g, replacement: `xoxp-${REDACTED}` },
+    // Google API keys
+    { pattern: /\bAIzaSy[a-zA-Z0-9_-]+/g, replacement: `AIzaSy${REDACTED}` },
+    // AWS access keys
+    { pattern: /\bAKIA[A-Z0-9]{16,}/g, replacement: `AKIA${REDACTED}` },
+    // SendGrid keys
+    { pattern: /\bSG\.[a-zA-Z0-9_.-]+/g, replacement: `SG.${REDACTED}` },
+    // Twilio SIDs
+    { pattern: /\bAC[a-f0-9]{32}/g, replacement: `AC${REDACTED}` },
+    // OpenAI keys
+    { pattern: /\bsk-[a-zA-Z0-9]{20,}/g, replacement: `sk-${REDACTED}` },
+    // Age secret keys (critical — NEVER log private keys)
+    { pattern: /AGE-SECRET-KEY-[A-Z0-9]+/g, replacement: `AGE-SECRET-KEY-${REDACTED}` },
+    // JWTs (header.payload.signature)
+    { pattern: /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, replacement: `eyJ${REDACTED}` },
+    // PEM private keys (multiline — match the whole block)
+    {
+        pattern: /-----BEGIN\s+(?:RSA\s+)?PRIVATE KEY-----[\s\S]*?-----END\s+(?:RSA\s+)?PRIVATE KEY-----/g,
+        replacement: `-----BEGIN PRIVATE KEY-----\n${REDACTED}\n-----END PRIVATE KEY-----`,
+    },
+    // PEM certificates
+    {
+        pattern: /-----BEGIN\s+CERTIFICATE-----[\s\S]*?-----END\s+CERTIFICATE-----/g,
+        replacement: `-----BEGIN CERTIFICATE-----\n${REDACTED}\n-----END CERTIFICATE-----`,
+    },
+    // URLs with embedded credentials (e.g. postgres://user:pass@host/db, redis://:pass@host)
+    { pattern: /:\/\/[^:/?#\s]*:[^@/?#\s]+@/g, replacement: `://${REDACTED}:${REDACTED}@` },
+    // Generic key=value patterns for common secret field names
+    { pattern: /(\b(?:password|secret|token|key|apikey|api_key|auth)\s*=\s*)\S+/gi, replacement: `$1${REDACTED}` },
+];
+/**
+ * Sanitize a message by redacting known secret patterns.
+ *
+ * Applies all known secret pattern regexes and replaces matches
+ * with redacted placeholders. Safe values pass through unchanged.
+ *
+ * @param message - The log message to sanitize.
+ * @returns The sanitized message with secrets redacted.
+ */
+export function sanitizeForLog(message) {
+    if (!message || typeof message !== 'string') {
+        return message;
+    }
+    let sanitized = message;
+    for (const { pattern, replacement } of SECRET_PATTERNS) {
+        // Reset the regex lastIndex (global regexes are stateful)
+        pattern.lastIndex = 0;
+        sanitized = sanitized.replace(pattern, replacement);
+    }
+    return sanitized;
+}
+/**
+ * Sanitize an error object's message and stack trace.
+ *
+ * Returns a new Error with sanitized message and stack. The original
+ * error is not modified.
+ *
+ * @param error - The error to sanitize.
+ * @returns A new Error with sanitized message and stack.
+ */
+export function sanitizeError(error) {
+    const sanitized = new Error(sanitizeForLog(error.message));
+    if (error.stack) {
+        sanitized.stack = sanitizeForLog(error.stack);
+    }
+    sanitized.name = error.name;
+    return sanitized;
+}
+/** Original console methods (saved before wrapping) */
+let _originalConsoleLog = null;
+let _originalConsoleError = null;
+let _originalConsoleWarn = null;
+let _originalConsoleDebug = null;
+/** Whether console is currently wrapped */
+let _isWrapped = false;
+/**
+ * Wrap all console output methods through the sanitizer.
+ *
+ * After calling this function, all `console.log`, `console.error`,
+ * `console.warn`, and `console.debug` calls will have their arguments
+ * sanitized before output.
+ *
+ * Call `unwrapConsole()` to restore original behaviour.
+ *
+ * **Security:** This ensures that even if a developer accidentally
+ * logs a secret value, it will be redacted before reaching the terminal.
+ */
+export function wrapConsole() {
+    if (_isWrapped) {
+        return;
+    }
+    _originalConsoleLog = console.log;
+    _originalConsoleError = console.error;
+    _originalConsoleWarn = console.warn;
+    _originalConsoleDebug = console.debug;
+    const wrapMethod = (original) => (...args) => {
+        const sanitizedArgs = args.map((arg) => {
+            if (typeof arg === 'string') {
+                return sanitizeForLog(arg);
+            }
+            if (arg instanceof Error) {
+                return sanitizeError(arg);
+            }
+            // For objects, sanitize JSON representation then parse back
+            if (typeof arg === 'object' && arg !== null) {
+                try {
+                    const json = JSON.stringify(arg);
+                    const sanitized = sanitizeForLog(json);
+                    return JSON.parse(sanitized);
+                }
+                catch {
+                    // If JSON serialisation fails, return as-is
+                    return arg;
+                }
+            }
+            return arg;
+        });
+        original.apply(console, sanitizedArgs);
+    };
+    console.log = wrapMethod(_originalConsoleLog);
+    console.error = wrapMethod(_originalConsoleError);
+    console.warn = wrapMethod(_originalConsoleWarn);
+    console.debug = wrapMethod(_originalConsoleDebug);
+    _isWrapped = true;
+}
+/**
+ * Restore original console methods (unwrap the sanitizer).
+ *
+ * Safe to call even if `wrapConsole()` was never called.
+ */
+export function unwrapConsole() {
+    if (!_isWrapped) {
+        return;
+    }
+    if (_originalConsoleLog)
+        console.log = _originalConsoleLog;
+    if (_originalConsoleError)
+        console.error = _originalConsoleError;
+    if (_originalConsoleWarn)
+        console.warn = _originalConsoleWarn;
+    if (_originalConsoleDebug)
+        console.debug = _originalConsoleDebug;
+    _originalConsoleLog = null;
+    _originalConsoleError = null;
+    _originalConsoleWarn = null;
+    _originalConsoleDebug = null;
+    _isWrapped = false;
+}
+/**
+ * Check whether the console is currently wrapped by the sanitizer.
+ *
+ * @returns `true` if `wrapConsole()` has been called and `unwrapConsole()` has not.
+ */
+export function isConsoleWrapped() {
+    return _isWrapped;
+}
+//# sourceMappingURL=log-sanitizer.js.map

package/dist/core/log-sanitizer.js.map

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

package/dist/core/path-validator.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Path validation module.
+ *
+ * Validates and canonicalises project paths to prevent path traversal
+ * attacks and restrict operations to safe directories (within $HOME
+ * or explicitly approved locations).
+ *
+ * @module core/path-validator
+ */
+/**
+ * Canonicalise a path string.
+ *
+ * Resolves `~` to the home directory, normalises `.` and `..` segments,
+ * and returns an absolute path. Does NOT follow symlinks — use
+ * `fs.realpathSync` separately if you need the real path.
+ *
+ * @param p - The path to canonicalise (may contain `~`).
+ * @returns The resolved absolute path.
+ */
+export declare function canonicalize(p: string): string;
+/**
+ * Validate that a project path is safe to use.
+ *
+ * A path is valid if ALL of the following are true:
+ * - It is non-empty and resolves to an absolute path.
+ * - After canonicalisation, it is within the user's home directory.
+ * - It does not land inside a blocked system directory.
+ * - If the path exists and is a symlink, the symlink target is also
+ *   within the home directory.
+ *
+ * @param p - The path to validate (may contain `~`).
+ * @returns The canonicalised, validated absolute path.
+ * @throws If the path is outside the home directory, in a blocked
+ *         directory, or a symlink pointing outside the home directory.
+ */
+export declare function validateProjectPath(p: string): string;
+//# sourceMappingURL=path-validator.d.ts.map

package/dist/core/path-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-validator.d.ts","sourceRoot":"","sources":["../../src/core/path-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAyBH;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAmB9C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAqErD"}