@zincapp/znvault-cli 4.7.0 → 4.8.0

package/dist/commands/mysql/mycnf.js

@@ -0,0 +1,136 @@
+// src/commands/mysql/mycnf.ts
+//
+// Writes the short-lived 0600 my.cnf that carries the leased MySQL credentials
+// (spec B2) and hands it to the child mysql as an OPEN FILE DESCRIPTOR rather
+// than a path on disk.
+//
+// F1 (no plaintext directory entry survives the run) is achieved by the
+// open → write → unlink-immediately pattern:
+//   1. openSync(path, 'wx+', 0600)   → exclusive create, returns fd.
+//   2. writeSync(fd, body)           → credentials written through the fd.
+//   3. unlinkSync(path)              → directory entry removed AT ONCE. The
+//      inode (and its plaintext bytes) stays alive ONLY because the open fd
+//      still references it; there is NO name in the filesystem from this point
+//      on, so a `kill -9` or crash leaves nothing on disk to recover.
+//   4. runMysql passes `/dev/fd/<fd>` as --defaults-extra-file and inherits the
+//      fd into the child at the SAME number, so mysql re-opens the still-alive
+//      inode through /dev/fd. (On macOS /dev/fd/N re-opens the inode — which is
+//      why the fd MUST be readable; see the 'wx+' note below. On Linux /dev/fd
+//      is /proc/self/fd and resolves the same inode.)
+//   5. cleanup() closes the fd → last reference gone → kernel reclaims the
+//      inode + its bytes. cleanup() is idempotent and best-effort.
+//
+// This replaces the old "spawn-then-unlink" approach, which raced: spawn()
+// returns when the child is forked but BEFORE it has exec'd mysql and read the
+// defaults file, so the unlink could win the race and mysql would die with
+// "Failed to open required defaults file". Keeping the inode alive via an open
+// fd removes the race entirely — the name is already gone before spawn, and the
+// fd guarantees the bytes survive until cleanup().
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { randomBytes } from 'node:crypto';
+function memBackedTmpBase() {
+    // Prefer a memory-backed fs so the plaintext never hits spinning disk (spec F1).
+    try {
+        fs.accessSync('/dev/shm', fs.constants.W_OK);
+        return '/dev/shm';
+    }
+    catch {
+        return os.tmpdir();
+    }
+}
+/**
+ * Create the temp my.cnf, unlink its directory entry immediately, and return an
+ * open fd plus an idempotent cleanup().
+ *
+ * The body is fully synchronous (all fs operations are *Sync), but the function
+ * returns a Promise to preserve the broker's `await createMyCnf(...)` contract
+ * (and so it can become genuinely async later without touching callers).
+ * Declared non-`async` + returning Promise.resolve avoids the require-await
+ * lint warning while keeping the Promise return type (M-5).
+ *
+ * @throws If the exclusive create fails (e.g. EEXIST on a suffix collision,
+ *         which is astronomically unlikely with 8 random bytes, or ENOSPC).
+ */
+export function createMyCnf(opts) {
+    const suffix = randomBytes(8).toString('hex');
+    const dir = path.join(memBackedTmpBase(), `znvault-my-${suffix}`);
+    // 0700 dir on a memory-backed fs (spec F1). Created before the file so the
+    // file's parent is owner-only even for the brief moment the name exists.
+    fs.mkdirSync(dir, { mode: 0o700 });
+    const file = path.join(dir, 'my.cnf');
+    const body = `[client]\nuser=${opts.user}\npassword=${opts.password}\nhost=${opts.host}\nport=${opts.port}\n`;
+    // 'wx+' = O_RDWR | O_CREAT | O_EXCL, mode 0600.
+    //   - O_EXCL  : fail if the file somehow already exists (no clobber / no
+    //               following an attacker-planted symlink).
+    //   - O_RDWR  : the fd MUST be READABLE. On macOS, `/dev/fd/N` RE-OPENS the
+    //               underlying inode (it is not a plain dup of the open file
+    //               description), so a write-only ('wx') fd would make mysql fail
+    //               with EBADF/permission when it tries to read /dev/fd/N. O_RDWR
+    //               keeps the inode re-openable for read by the child. Verified
+    //               against real mysql 9.4 on macOS.
+    let fd;
+    try {
+        fd = fs.openSync(file, 'wx+', 0o600);
+    }
+    catch (err) {
+        // mkdir succeeded but open failed — drop the empty dir so we don't leak it.
+        try {
+            fs.rmdirSync(dir);
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
+    let closed = false;
+    try {
+        // CRITICAL: write at an EXPLICIT position 0 (the 5-arg overload) so the fd's
+        // current file OFFSET stays at 0. On macOS, `/dev/fd/N` does NOT give the
+        // child a fresh offset-0 description — it shares the original fd's offset.
+        // A plain `writeSync(fd, body)` advances the offset to EOF, so mysql reading
+        // /dev/fd/N would start at EOF and parse an EMPTY defaults file (verified:
+        // `mysql --print-defaults` shows zero args). Positioned writes do not move
+        // the file pointer, so the offset remains 0 and mysql reads the whole body.
+        const bodyBuf = Buffer.from(body, 'utf8');
+        fs.writeSync(fd, bodyBuf, 0, bodyBuf.length, 0);
+        // F1: remove the directory entry IMMEDIATELY. The inode stays alive purely
+        // because `fd` is still open; there is no name on disk from here on.
+        fs.unlinkSync(file);
+    }
+    catch (err) {
+        // Writing or unlinking failed — don't leak the fd or the dir.
+        try {
+            fs.closeSync(fd);
+            closed = true;
+        }
+        catch { /* ignore */ }
+        try {
+            fs.unlinkSync(file);
+        }
+        catch { /* ignore */ }
+        try {
+            fs.rmdirSync(dir);
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
+    const cleanup = () => {
+        // Closing the last fd referencing the (already unlinked) inode releases it,
+        // so the kernel reclaims the plaintext bytes. Idempotent via `closed`.
+        if (!closed) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch { /* ignore */ }
+            closed = true;
+        }
+        // The file name is already gone; the dir should be empty. rmdir is
+        // best-effort (it may already be gone if cleanup ran twice).
+        try {
+            fs.rmdirSync(dir);
+        }
+        catch { /* ignore */ }
+    };
+    return Promise.resolve({ fd, fdPath: `/dev/fd/${fd.toString()}`, cleanup });
+}
+//# sourceMappingURL=mycnf.js.map

package/dist/commands/mysql/mycnf.js.map

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

package/dist/commands/mysql/resolve.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Resolve `target` (a connection name/id OR an alias) plus an optional role
+ * name/id into concrete IDs.
+ *
+ * Resolution rules:
+ *   1. If `target` matches a saved alias, expand to { connection, role }.
+ *      Validate both still exist; if not, throw a "dangling alias" error (F13).
+ *   2. Otherwise treat `target` as a connection name/id and fetch it.
+ *   3. Resolve the role:
+ *      - If a role name/id is given, find it in the connection's role list.
+ *      - If no role given and the connection has exactly one role, use it.
+ *      - Otherwise throw an error instructing the user to pass --role.
+ */
+export declare function resolveTarget(target: string, roleOpt?: string): Promise<{
+    connectionId: string;
+    roleId: string;
+}>;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/commands/mysql/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../../src/commands/mysql/resolve.ts"],"names":[],"mappings":"AA8DA;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA+DnD"}

package/dist/commands/mysql/resolve.js

@@ -0,0 +1,108 @@
+// src/commands/mysql/resolve.ts
+/**
+ * Resolve a target (connection name/id or alias) + optional role to concrete IDs.
+ *
+ * This is used by `znvault mysql exec/connect` to turn the user-supplied target
+ * and --role option into the { connectionId, roleId } pair needed by the broker.
+ */
+import { client } from '../../lib/client.js';
+import { getAlias } from './alias.js';
+/**
+ * Resolve a connection name or id to a concrete connection id.
+ *
+ * Strategy (avoids a guaranteed 404 round-trip on the common name case):
+ *   - If `target` looks like a connection id (starts with "dbc_"), try GET by id
+ *     first; if that 404s, fall back to listing and matching by name.
+ *   - Otherwise (target is a friendly name), list all connections and match by
+ *     name first; if not found, try GET by id as a last resort.
+ *   - If neither resolves, throw a clear "not found (by id or name)" error.
+ *
+ * Connection names are unique per tenant, so a name match is unambiguous.
+ * If somehow multiple entries share a name, the first match is used.
+ */
+async function resolveConnectionId(target) {
+    const looksLikeId = target.startsWith('dbc_');
+    if (looksLikeId) {
+        // Try direct GET by id first.
+        try {
+            const conn = await client.get(`/v1/dynamic-secrets/connections/${target}`);
+            return conn.id;
+        }
+        catch {
+            // Fall through to list-by-name.
+        }
+    }
+    // List all connections and match by name.
+    const connections = await client.get('/v1/dynamic-secrets/connections');
+    const byName = connections.find((c) => c.name === target);
+    if (byName !== undefined) {
+        return byName.id;
+    }
+    if (!looksLikeId) {
+        // Not found by name; try GET by id as a last resort.
+        try {
+            const conn = await client.get(`/v1/dynamic-secrets/connections/${target}`);
+            return conn.id;
+        }
+        catch {
+            // Fall through to error.
+        }
+    }
+    throw new Error(`Connection '${target}' not found (by id or name). ` +
+        `Run 'znvault dynamic-secrets connections list' to see available connections.`);
+}
+/**
+ * Resolve `target` (a connection name/id OR an alias) plus an optional role
+ * name/id into concrete IDs.
+ *
+ * Resolution rules:
+ *   1. If `target` matches a saved alias, expand to { connection, role }.
+ *      Validate both still exist; if not, throw a "dangling alias" error (F13).
+ *   2. Otherwise treat `target` as a connection name/id and fetch it.
+ *   3. Resolve the role:
+ *      - If a role name/id is given, find it in the connection's role list.
+ *      - If no role given and the connection has exactly one role, use it.
+ *      - Otherwise throw an error instructing the user to pass --role.
+ */
+export async function resolveTarget(target, roleOpt) {
+    const alias = getAlias(target);
+    if (alias !== undefined) {
+        // Alias path — validate that connection and role still exist.
+        const connectionTarget = alias.connection;
+        const roleTarget = alias.role;
+        let connectionId;
+        try {
+            connectionId = await resolveConnectionId(connectionTarget);
+        }
+        catch {
+            throw new Error(`Dangling alias '${target}': connection '${connectionTarget}' no longer exists`);
+        }
+        const roles = await client.get(`/v1/dynamic-secrets/connections/${connectionId}/roles`);
+        const role = roles.find((r) => r.name === roleTarget || r.id === roleTarget);
+        if (role === undefined) {
+            throw new Error(`Dangling alias '${target}': role '${roleTarget}' no longer exists on connection '${connectionTarget}'`);
+        }
+        return { connectionId, roleId: role.id };
+    }
+    // Direct connection path.
+    const connectionId = await resolveConnectionId(target);
+    const roles = await client.get(`/v1/dynamic-secrets/connections/${connectionId}/roles`);
+    if (roleOpt !== undefined) {
+        const role = roles.find((r) => r.name === roleOpt || r.id === roleOpt);
+        if (role === undefined) {
+            throw new Error(`Role '${roleOpt}' not found on connection '${target}'. ` +
+                `Available: ${roles.map((r) => r.name).join(', ') || '(none)'}`);
+        }
+        return { connectionId, roleId: role.id };
+    }
+    // No role given — require exactly one.
+    if (roles.length === 1) {
+        return { connectionId, roleId: roles[0].id };
+    }
+    if (roles.length === 0) {
+        throw new Error(`Connection '${target}' has no roles. Create one first, then pass --role <name>.`);
+    }
+    throw new Error(`Connection '${target}' has ${roles.length.toString()} roles. ` +
+        `Pass --role <name> to select one: ${roles.map((r) => r.name).join(', ')}`);
+}
+//# sourceMappingURL=resolve.js.map

package/dist/commands/mysql/resolve.js.map

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

package/dist/commands/mysql/run.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Resolve the absolute path to the `mysql` binary on the current PATH.
+ *
+ * Scans each directory in `process.env.PATH` for an executable named `mysql`.
+ * Logs the resolved path to stderr for auditability (spec F11).
+ *
+ * @returns Absolute path to the `mysql` binary.
+ * @throws If `mysql` is not found on PATH, with an actionable installation hint.
+ */
+export declare function assertMysqlOnPath(): string;
+/**
+ * Reject any passthrough token that is (or starts with `=`-form of) a forbidden
+ * connection/credential/defaults override flag.
+ *
+ * Recognised forms for a forbidden flag `--host`:
+ *   - exact:   `--host`        (its value is the next token)
+ *   - inline:  `--host=value`
+ *   - short:   `-h`            (value is next token)  / `-P`, `-p`
+ *
+ * Tokens that merely START with a forbidden name but are a different flag
+ * (e.g. `--hostgroup`, `--port-something`) are NOT rejected.
+ *
+ * @throws Error naming the offending flag and citing F2, on the first match.
+ */
+export declare function assertPassthroughAllowed(passthrough: readonly string[]): void;
+/**
+ * Options for the pure argv/env builder.
+ * `mode` is intentionally absent — stdin wiring is exec/connect-specific and
+ * is handled by runMysql, not by this pure builder.
+ */
+export interface BuildMysqlInvocationOpts {
+    /**
+     * Value for `--defaults-extra-file`. This is the `/dev/fd/<fd>` path returned
+     * by createMyCnf (B2) — mysql re-opens the inherited fd through it.
+     */
+    fdPath: string;
+    /** Optional default schema to select (positional arg — spec F8). */
+    database?: string;
+    /** Extra arguments appended verbatim to the mysql argv. */
+    passthrough?: string[];
+}
+/**
+ * Build the mysql argv and child environment.
+ *
+ * This is a PURE function — no spawning, no file I/O, no side effects.
+ * Export it so tests can assert security-critical argv/env invariants
+ * without spawning real mysql.
+ *
+ * Security invariants:
+ *   - `--defaults-extra-file=<fdPath>` is args[0].
+ *   - No --user / -u / --password / -p / MYSQL_PWD in args or env.
+ *   - No --host / --port / -h / -P flags (connection coords from cnf).
+ *   - Forbidden override flags in `passthrough` are rejected (spec F2).
+ *   - MYSQL_HISTFILE=/dev/null overrides any pre-existing value.
+ *
+ * @throws If `passthrough` contains a forbidden connection/credential/defaults
+ *         override flag (see assertPassthroughAllowed).
+ */
+export declare function buildMysqlInvocation(opts: BuildMysqlInvocationOpts): {
+    args: string[];
+    env: NodeJS.ProcessEnv;
+};
+/**
+ * A single entry of a child_process `stdio` array. A NUMBER means "inherit THIS
+ * parent fd at this child index"; the strings are the usual stdio dispositions.
+ */
+type StdioEntry = 'pipe' | 'inherit' | 'ignore' | number;
+/**
+ * Build the `stdio` array for spawning mysql so that the cnf fd is inherited by
+ * the child at the SAME numeric index `fd`. This is what makes
+ * `--defaults-extra-file=/dev/fd/<fd>` resolve correctly in the child: the
+ * child must have an fd open at exactly `fd`.
+ *
+ * Layout:
+ *   - index 0 (stdin):  `stdin0` — 'pipe' for exec (we feed SQL), 'inherit' for
+ *     connect (interactive terminal).
+ *   - index 1 (stdout): 'inherit'.
+ *   - index 2 (stderr): 'inherit'.
+ *   - indices 3 .. fd-1: 'ignore' (gaps the array must fill; the child does not
+ *     use them).
+ *   - index fd:         `fd` (a number → inherit the parent fd at this index).
+ *
+ * `fd` is always >= 3 in practice (0/1/2 are taken by the std streams of the
+ * Node process), so it never collides with stdin/stdout/stderr. We assert this
+ * defensively.
+ *
+ * @param fd     The parent fd to inherit at the same number in the child.
+ * @param stdin0 Disposition for the child's stdin (index 0).
+ * @returns A stdio array of length max(3, fd+1).
+ * @throws If `fd` is < 3 (would collide with std streams — never expected).
+ */
+export declare function buildChildStdio(fd: number, stdin0: 'pipe' | 'inherit'): StdioEntry[];
+/**
+ * Options for runMysql.
+ */
+export interface RunMysqlOpts {
+    /**
+     * The `/dev/fd/<fd>` path returned by createMyCnf — passed to mysql as
+     * --defaults-extra-file. This module never re-opens it; mysql reads the
+     * inherited fd through it.
+     */
+    fdPath: string;
+    /**
+     * The numeric fd backing `fdPath`. The child INHERITS this fd at the SAME
+     * number so `/dev/fd/<fd>` resolves inside it. The parent does NOT close it
+     * here — createMyCnf's cleanup() owns the close (after the child exits).
+     */
+    fd: number;
+    /** Default schema to select (positional arg — spec F8). */
+    database?: string;
+    /** 'connect' → interactive (stdio: inherit); 'exec' → non-interactive. */
+    mode: 'exec' | 'connect';
+    /**
+     * (exec mode) SQL files to read and concatenate as stdin.
+     * Precedence: files → sql → parent stdin (spec F-input).
+     */
+    files?: string[];
+    /**
+     * (exec mode) Inline SQL string to feed as stdin.
+     * Precedence: files → sql → parent stdin (spec F-input).
+     */
+    sql?: string;
+    /** Extra arguments appended verbatim to the mysql argv. */
+    passthrough?: string[];
+}
+/**
+ * Spawn the system `mysql` client and wait for it to exit.
+ *
+ * - Resolves with the child's numeric exit code (caller/CI relies on non-zero).
+ * - The cnf fd (`opts.fd`) is inherited by the child at the SAME number so
+ *   `--defaults-extra-file=/dev/fd/<fd>` resolves in the child (spec F1). The
+ *   directory entry was already unlinked in createMyCnf — there is NOTHING to
+ *   unlink here, and NO post-spawn unlink race.
+ * - 'connect' mode: stdin/stdout/stderr are inherited (interactive terminal);
+ *   the cnf fd is additionally inherited at index `fd`.
+ * - 'exec' mode: stdin (index 0) is wired as:
+ *     1. files (concatenated, in order) → stdin pipe
+ *     2. sql (string) → stdin pipe
+ *     3. parent stdin (if not a TTY) → piped through (inherit)
+ *     4. parent stdin is a TTY and neither files nor sql provided → Error
+ *   stdout/stderr are inherited; the cnf fd is inherited at index `fd`.
+ *
+ * The parent's own copy of `opts.fd` is intentionally NOT closed here — the
+ * child holds its own dup (created by spawn's file actions), and createMyCnf's
+ * cleanup() closes the parent's copy after this resolves. (Closing here would be
+ * safe too, since the child already has its dup, but leaving the single owner —
+ * cleanup() — avoids double-close races.)
+ *
+ * @throws If the `mysql` binary is not on PATH (via assertMysqlOnPath).
+ * @throws If `passthrough` contains a forbidden override flag (via the builder).
+ * @throws If the cnf fd collides with a standard stream (via buildChildStdio).
+ * @throws If exec mode is requested but no SQL source is available.
+ */
+export declare function runMysql(opts: RunMysqlOpts): Promise<number>;
+export {};
+//# sourceMappingURL=run.d.ts.map

package/dist/commands/mysql/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/commands/mysql/run.ts"],"names":[],"mappings":"AAwCA;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAsB1C;AAoCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAa7E;AAMD;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,wBAAwB,GAAG;IACpE,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB,CA+BA;AAMD;;;GAGG;AACH,KAAK,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,EAAE,CAoBpF;AAMD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAC;IACX,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAuElE"}