@schema-weaver/pg-connector 0.0.0-stage → 2.0.0

package/dist/cjs/config/atomic-write.js

@@ -0,0 +1,289 @@
+"use strict";
+/**
+ * Atomic, symlink-refusing, permission-repairing file writes plus the advisory
+ * lock used to serialise read-modify-write sequences over config files.
+ *
+ * Every config file that can hold the agent token or a database password must
+ * go through {@link atomicWriteFile}: a plain `writeFileSync` applies `mode`
+ * only on create (so a pre-existing 0o644 file stays world-readable), follows
+ * symlinks planted by a local attacker, and can truncate the file — which for
+ * the machine config means permanent loss of the agent token.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AtomicWriteError = exports.ATOMIC_WRITE_DIR_MODE = exports.ATOMIC_WRITE_FILE_MODE = void 0;
+exports.assertNotSymlink = assertNotSymlink;
+exports.ensureDir = ensureDir;
+exports.ensureSecureDir = ensureSecureDir;
+exports.atomicWriteFile = atomicWriteFile;
+exports.atomicWriteJson = atomicWriteJson;
+exports.withFileLock = withFileLock;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+/** Mode every credential-bearing config file is written and repaired to. */
+exports.ATOMIC_WRITE_FILE_MODE = 0o600;
+/** Mode the containing directory is created and repaired to. */
+exports.ATOMIC_WRITE_DIR_MODE = 0o700;
+/** Raised when a config write is refused or cannot be completed. */
+class AtomicWriteError extends Error {
+    code;
+    constructor(message, code = 'write_failed') {
+        super(message);
+        this.name = 'AtomicWriteError';
+        this.code = code;
+    }
+}
+exports.AtomicWriteError = AtomicWriteError;
+const DEFAULT_LOCK_STALE_MS = 30_000;
+const DEFAULT_LOCK_TIMEOUT_MS = 5_000;
+const DEFAULT_LOCK_RETRY_MS = 25;
+const NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
+const TEMP_WRITE_FLAGS = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | NOFOLLOW;
+const heldLocks = new Set();
+function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function hasCode(err, code) {
+    return (typeof err === 'object' && err !== null && err.code === code);
+}
+function chmodIfPosix(target, mode) {
+    if (process.platform === 'win32')
+        return;
+    fs.chmodSync(target, mode);
+}
+function closeQuietly(fd) {
+    try {
+        fs.closeSync(fd);
+    }
+    catch {
+        // ignore
+    }
+}
+function unlinkQuietly(target) {
+    try {
+        fs.unlinkSync(target);
+    }
+    catch {
+        // ignore
+    }
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Fails when `target` is a symlink. A missing file is not a symlink, so the
+ * check is safe to run before every create. Use `lstat`, never `stat`: `stat`
+ * follows the link and reports the target's type, which is exactly the check
+ * that has to fail here.
+ */
+function assertNotSymlink(target) {
+    let stats;
+    try {
+        stats = fs.lstatSync(target);
+    }
+    catch (err) {
+        if (hasCode(err, 'ENOENT'))
+            return;
+        throw new AtomicWriteError(`Cannot inspect ${target}: ${errText(err)}`);
+    }
+    if (stats.isSymbolicLink()) {
+        throw new AtomicWriteError(`Refusing to write through the symlink ${target}. Remove it or point SW_AGENT_HOME somewhere else.`, 'symlink_refused');
+    }
+}
+/** Creates the containing directory if missing; leaves an existing one alone. */
+function ensureDir(dir) {
+    try {
+        fs.mkdirSync(dir, { recursive: true, mode: exports.ATOMIC_WRITE_DIR_MODE });
+    }
+    catch (err) {
+        if (!hasCode(err, 'EEXIST')) {
+            throw new AtomicWriteError(`Failed to create directory ${dir}: ${errText(err)}`);
+        }
+    }
+}
+/**
+ * Creates the containing directory and repairs the mode of a pre-existing one
+ * that is group- or world-accessible. Used for the agent home, which holds the
+ * token: a 0o755 home is a failed control, not a cosmetic detail.
+ */
+function ensureSecureDir(dir) {
+    ensureDir(dir);
+    chmodIfPosix(dir, exports.ATOMIC_WRITE_DIR_MODE);
+}
+/** fsync of the directory so the rename survives a power loss, where supported. */
+function fsyncDir(dir) {
+    if (process.platform === 'win32')
+        return;
+    let fd;
+    try {
+        fd = fs.openSync(dir, 'r');
+        fs.fsyncSync(fd);
+    }
+    catch {
+        // EINVAL/EPERM/EISDIR: the filesystem does not support directory fsync.
+    }
+    finally {
+        if (fd !== undefined)
+            closeQuietly(fd);
+    }
+}
+/**
+ * Writes `data` to `filePath` atomically:
+ * create a private temp file, fsync it, rename it over the target, then fsync
+ * the directory. A reader therefore only ever sees the complete old file or the
+ * complete new one, and a crash cannot truncate the config.
+ *
+ * The temp file is created with O_EXCL|O_NOFOLLOW, so it can never be
+ * pre-created (or symlinked) by another process, and is chmod'ed to `mode`
+ * unconditionally: `mode` passed to `open` is masked by the umask, so it alone
+ * cannot guarantee 0o600.
+ */
+function atomicWriteFile(filePath, data, mode = exports.ATOMIC_WRITE_FILE_MODE) {
+    const dir = path.dirname(filePath);
+    ensureDir(dir);
+    assertNotSymlink(filePath);
+    const tmp = `${filePath}.tmp-${process.pid}-${crypto.randomBytes(6).toString('hex')}`;
+    let fd;
+    try {
+        fd = fs.openSync(tmp, TEMP_WRITE_FLAGS, mode);
+        assertNotSymlink(tmp);
+        const buf = typeof data === 'string' ? Buffer.from(data, 'utf8') : data;
+        let written = 0;
+        while (written < buf.length) {
+            written += fs.writeSync(fd, buf, written, buf.length - written);
+        }
+        fs.fsyncSync(fd);
+        fs.closeSync(fd);
+        fd = undefined;
+        chmodIfPosix(tmp, mode);
+        fs.renameSync(tmp, filePath);
+        chmodIfPosix(filePath, mode);
+        fsyncDir(dir);
+    }
+    catch (err) {
+        if (fd !== undefined)
+            closeQuietly(fd);
+        unlinkQuietly(tmp);
+        if (err instanceof AtomicWriteError)
+            throw err;
+        throw new AtomicWriteError(`Failed to write ${filePath}: ${errText(err)}`);
+    }
+}
+/** `atomicWriteFile` for a JSON document, pretty-printed with a trailing newline. */
+function atomicWriteJson(filePath, value, mode = exports.ATOMIC_WRITE_FILE_MODE) {
+    atomicWriteFile(filePath, `${JSON.stringify(value, null, 2)}\n`, mode);
+}
+/**
+ * True when the lock file next to `target` was abandoned (older than `staleMs`)
+ * or is not a real lock file. Reaps it as a side effect.
+ */
+function reapStaleLock(lockPath, staleMs) {
+    let stats;
+    try {
+        stats = fs.lstatSync(lockPath);
+    }
+    catch (err) {
+        return hasCode(err, 'ENOENT');
+    }
+    if (stats.isSymbolicLink() || !stats.isFile()) {
+        unlinkQuietly(lockPath);
+        return true;
+    }
+    if (Date.now() - stats.mtimeMs > staleMs) {
+        unlinkQuietly(lockPath);
+        return true;
+    }
+    return false;
+}
+function acquireLock(lockPath, staleMs, timeoutMs, retryMs) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            const fd = fs.openSync(lockPath, 'wx', exports.ATOMIC_WRITE_FILE_MODE);
+            try {
+                fs.writeSync(fd, `${JSON.stringify({ pid: process.pid, acquired_at: new Date().toISOString() })}\n`);
+                fs.fsyncSync(fd);
+            }
+            finally {
+                closeQuietly(fd);
+            }
+            chmodIfPosix(lockPath, exports.ATOMIC_WRITE_FILE_MODE);
+            heldLocks.add(lockPath);
+            return;
+        }
+        catch (err) {
+            if (!hasCode(err, 'EEXIST')) {
+                throw new AtomicWriteError(`Failed to take the lock ${lockPath}: ${errText(err)}`);
+            }
+        }
+        if (reapStaleLock(lockPath, staleMs))
+            continue;
+        if (Date.now() >= deadline) {
+            throw new AtomicWriteError(`Timed out after ${timeoutMs}ms waiting for the lock ${lockPath}. Another sw-agent process is writing the same config; retry once it finishes.`, 'lock_timeout');
+        }
+        sleepSync(retryMs);
+    }
+}
+function releaseLock(lockPath) {
+    heldLocks.delete(lockPath);
+    unlinkQuietly(lockPath);
+}
+/**
+ * Runs `fn` while holding an exclusive advisory lock on `targetPath`. Use it
+ * around every load → mutate → save sequence so two concurrent CLI
+ * invocations cannot lose one another's update. The lock is an `O_EXCL` lock
+ * file, so it is released by the kernel even if the process is killed; a lock
+ * whose holder died is reaped after `staleMs`.
+ *
+ * Re-entrant within one process: a nested call for the same target runs `fn`
+ * directly instead of deadlocking against itself.
+ */
+function withFileLock(targetPath, fn, opts = {}) {
+    const lockPath = `${targetPath}.lock`;
+    if (heldLocks.has(lockPath)) {
+        return fn();
+    }
+    const dir = path.dirname(lockPath);
+    ensureSecureDir(dir);
+    acquireLock(lockPath, opts.staleMs ?? DEFAULT_LOCK_STALE_MS, opts.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS, opts.retryMs ?? DEFAULT_LOCK_RETRY_MS);
+    try {
+        return fn();
+    }
+    finally {
+        releaseLock(lockPath);
+    }
+}
+//# sourceMappingURL=atomic-write.js.map

package/dist/cjs/config/atomic-write.js.map

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

package/dist/cjs/config/db-config.d.ts

@@ -0,0 +1,134 @@
+import { PermissionLevel } from '../permissions/checker';
+/**
+ * Database-level config: databases.config.json
+ * Array of DB entries. Each entry binds one DB to one project.
+ * One project = one DB (schema weaver constraint).
+ */
+export interface DbEntry {
+    project_name: string;
+    db_alias: string;
+    host: string;
+    port: number;
+    database: string;
+    user: string;
+    password_env?: string;
+    /**
+     * Password in cleartext. Present only in memory: the on-disk form is an
+     * {@link EncryptedPassword} envelope (see `sealDbConfig`). A plain string is
+     * still accepted on read so configs written by earlier versions load, and is
+     * re-encrypted on the next write.
+     */
+    password_stored?: string;
+    ssl_mode: 'disable' | 'require' | 'verify-ca' | 'verify-full';
+    ssl_root_cert?: string | null;
+    permission_override: PermissionLevel | null;
+    created_at: string;
+}
+export type DbConfig = DbEntry[];
+/**
+ * Envelope written to disk in place of a cleartext password.
+ * The plaintext never leaves the process; `ct` is AES-256-GCM output whose
+ * authentication tag also covers the entry identity (AAD), so a ciphertext
+ * cannot be moved between entries.
+ */
+export interface EncryptedPassword {
+    v: 1;
+    kdf: 'scrypt';
+    iv: string;
+    tag: string;
+    ct: string;
+}
+/** Entry identity an encrypted password is bound to. */
+export interface PasswordBinding {
+    db_alias: string;
+    host: string;
+    port: number;
+    database: string;
+    user: string;
+}
+/**
+ * Builds the additional authenticated data for a stored password: the entry
+ * identity. Serialised as a JSON array so no field value can shift the
+ * boundaries of another one.
+ */
+export declare function buildPasswordAad(binding: PasswordBinding): string;
+/**
+ * True when a value is an encrypted-password envelope rather than cleartext.
+ */
+export declare function isEncryptedPassword(value: unknown): value is EncryptedPassword;
+/**
+ * Loads the key file, creating it on first use. The derived key is cached for
+ * the life of the process so repeated config reads cost one KDF run.
+ */
+export declare function loadCredentialKey(): Buffer;
+/**
+ * Encrypts a database password for storage. Generates a fresh random 96-bit
+ * IV and authenticates the entry identity as AAD.
+ */
+export declare function encryptDbPassword(binding: PasswordBinding, plaintext: string): EncryptedPassword;
+/**
+ * Decrypts a stored database password. Throws when the envelope fails
+ * authentication, which includes a ciphertext copied from another entry.
+ */
+export declare function decryptDbPassword(binding: PasswordBinding, env: EncryptedPassword): string;
+/**
+ * Encrypts every cleartext password in the config for storage.
+ * Entries that already hold an envelope are passed through unchanged, so a
+ * load/save round trip never double-encrypts.
+ */
+export declare function sealDbConfig(config: DbConfig): unknown[];
+/**
+ * Checks if the databases.config.json file exists.
+ */
+export declare function dbConfigExists(): boolean;
+/**
+ * Validates the database config.
+ * Accepts a cleartext `password_stored` (pre-encryption on-disk shape) or an
+ * encrypted envelope; both are narrowed to cleartext in memory by
+ * {@link loadDbConfig} and re-sealed by {@link saveDbConfig}.
+ */
+export declare function validateDbConfig(raw: unknown): DbConfig;
+/**
+ * Loads the database config. Returns empty array if file does not exist.
+ * Encrypted `password_stored` envelopes are decrypted in memory; a config
+ * written by an earlier version (cleartext) is returned as-is and is upgraded
+ * on the next save.
+ */
+export declare function loadDbConfig(): DbConfig;
+/**
+ * Saves the database config to disk with 0o600 permissions on POSIX.
+ * Every cleartext `password_stored` is replaced by an encrypted envelope bound
+ * to that entry's identity before anything is written.
+ */
+export declare function saveDbConfig(config: DbConfig): void;
+/**
+ * Runs a load → mutate → save cycle over databases.config.json under an
+ * advisory lock, so two concurrent CLI invocations cannot lose one another's
+ * update. `mutate` edits the array in place; its return value is passed back.
+ */
+export declare function mutateDbConfig<T>(mutate: (config: DbConfig) => T): T;
+/**
+ * Adds a database entry to config and saves it. Enforces one DB per project.
+ */
+export declare function addDbEntry(entry: Omit<DbEntry, 'created_at'>): DbEntry;
+/**
+ * Removes a database entry by its alias. Returns true if removed, false if not found.
+ */
+export declare function removeDbEntry(dbAlias: string): boolean;
+/**
+ * Finds a database entry by its alias.
+ */
+export declare function findDbEntry(dbAlias: string): DbEntry | null;
+/**
+ * Finds a database entry by its project name.
+ */
+export declare function findDbByProject(projectName: string): DbEntry | null;
+/**
+ * Lists unique project names across all configured databases, sorted alphabetically.
+ */
+export declare function listProjects(): string[];
+export interface DatabasesConfig {
+    databases: DbEntry[];
+}
+export declare function loadDatabasesConfig(): DatabasesConfig;
+//# sourceMappingURL=db-config.d.ts.map

package/dist/cjs/config/db-config.d.ts.map

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