hikoutei 0.9.6 → 0.9.7

package/dist/cli/envFileWriter.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Env-file writer and atomic private-file write for `hikoutei setup`.
+ *
+ * The secure, atomic `.env` output-write machinery of the setup flow,
+ * extracted verbatim: update only the two managed env keys while preserving
+ * unrelated lines, refuse to read or write through any symlink/hardlink
+ * alias of a reserved path, and always land the result via a unique private
+ * temp file plus rename (never pathname-chmodded). Also carries
+ * `revalidateSetupPaths`, the fail-closed re-run of the reserved-path
+ * collision check performed immediately before every checkpoint and `.env`
+ * write, so an alias planted mid-run can never redirect those writes.
+ */
+import { type SetupStateWriteFs } from "./checkpoint.js";
+import { type SetupErrorResult } from "./flowResult.js";
+import type { RunSetupOptions } from "./setupFlow.js";
+/** The two .env keys the setup CLI manages. */
+export declare const SETUP_ENV_KEYS: {
+    readonly CREDENTIALS: "GOOGLE_APPLICATION_CREDENTIALS";
+    readonly SPREADSHEET_URL: "HIKOUTEI_SYNC_SPREADSHEET_URL";
+};
+/** Result of writing the .env output file. */
+export interface EnvFileWriteResult {
+    /** True when the file did not exist before this write. */
+    readonly created: boolean;
+    /** True when the file content changed (created or keys added/updated). */
+    readonly modified: boolean;
+}
+/**
+ * Writes or updates the .env output file securely and atomically.
+ *
+ * An existing output must be a regular file at the lstat boundary (a
+ * symlink is rejected outright, and directories/FIFOs/devices/sockets are
+ * refused before any open so a FIFO can never block), the file is opened
+ * WITHOUT following symlinks (`O_NOFOLLOW` where supported) and
+ * non-blocking (`O_NONBLOCK` where supported), the descriptor is
+ * fstat-verified as a regular file BEFORE a single byte is read (covering
+ * a non-regular replacement between the lstat check and the open), and any
+ * alias of the credentials file or other reserved paths (hardlink/symlink
+ * alias — the key contents are never read through it) is refused before a
+ * single byte is read. The preserved env content is built in memory and written to a unique private sibling temp
+ * file (`O_CREAT|O_EXCL|O_WRONLY` plus `O_NOFOLLOW`, mode 0600, fsync +
+ * close), then atomically renamed over the output: rename replaces the
+ * directory entry and never follows a symlink or hardlink planted after
+ * validation, so it cannot overwrite the key inode. Cleanup removes only
+ * the temp inode this invocation created. Missing file is created; a file
+ * whose content is unchanged is not rewritten. An existing file whose
+ * owner bits are not exactly 0600 counts as modified and is atomically
+ * replaced by a fresh verified-0600 file — never pathname-chmodded — so
+ * hardlinks sharing the old inode keep their own mode and content. Throws on filesystem
+ * failure or an unsafe existing entry; the caller maps the throw to
+ * `output_write_failed`.
+ */
+export declare function writeSetupEnvFile(outputPath: string, credentialsPath: string, spreadsheetUrl: string, reservedPaths?: readonly string[]): EnvFileWriteResult;
+/**
+ * Writes content to the output path atomically via a unique private temp.
+ *
+ * The temp file (PID + UUID sibling name) is created with exclusive
+ * no-follow flags and mode 0600, owner-only mode is applied and verified
+ * THROUGH the still-open descriptor (`fchmod` + `fstat`) before the content
+ * is written and fsynced, the path is re-verified against the created
+ * inode, and the file is renamed over the output. No pathname `chmod` is
+ * ever performed. Rename replaces the directory entry rather than
+ * following a symlink/hardlink planted after validation. Cleanup removes
+ * only the temp inode this invocation created. Throws on failure. `fs` is
+ * injectable so tests can prove the descriptor-mode behavior.
+ *
+ * Exported for the injected descriptor-mode regression; the flow calls it
+ * through `writeSetupEnvFile` with the default filesystem.
+ */
+export declare function atomicWritePrivateFile(outputPath: string, content: string, fs?: SetupStateWriteFs): void;
+/** `O_NOFOLLOW` where the platform defines it, else 0. */
+export declare function noFollowFlag(): number;
+/** `O_NONBLOCK` where the platform defines it, else 0. */
+export declare function nonBlockFlag(): number;
+/**
+ * Re-runs the reserved-path collision check and fails closed when aliases
+ * changed after the initial preflight.
+ *
+ * The reserved paths (key, output, checkpoint, temp, lock) are re-resolved
+ * immediately before every checkpoint write and the .env write: a symlink
+ * or hardlink planted after the preflight must never redirect a write to a
+ * reserved file. Returns an error result on collision, `null` when safe.
+ */
+export declare function revalidateSetupPaths(options: RunSetupOptions): SetupErrorResult | null;
+//# sourceMappingURL=envFileWriter.d.ts.map

package/dist/cli/envFileWriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envFileWriter.d.ts","sourceRoot":"","sources":["../../src/cli/envFileWriter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAaH,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAe,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAErE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD,+CAA+C;AAC/C,eAAO,MAAM,cAAc;;;CAGjB,CAAC;AAEX,8CAA8C;AAC9C,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAeD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,EACvB,cAAc,EAAE,MAAM,EACtB,aAAa,GAAE,SAAS,MAAM,EAAO,GACpC,kBAAkB,CA0BpB;AAuGD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,EAAE,GAAE,iBAA4C,GAC/C,IAAI,CA0EN;AAED,0DAA0D;AAC1D,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,0DAA0D;AAC1D,wBAAgB,YAAY,IAAI,MAAM,CAErC;AA+BD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,eAAe,GAAG,gBAAgB,GAAG,IAAI,CAatF"}

package/dist/cli/envFileWriter.js

@@ -0,0 +1,314 @@
+/**
+ * Env-file writer and atomic private-file write for `hikoutei setup`.
+ *
+ * The secure, atomic `.env` output-write machinery of the setup flow,
+ * extracted verbatim: update only the two managed env keys while preserving
+ * unrelated lines, refuse to read or write through any symlink/hardlink
+ * alias of a reserved path, and always land the result via a unique private
+ * temp file plus rename (never pathname-chmodded). Also carries
+ * `revalidateSetupPaths`, the fail-closed re-run of the reserved-path
+ * collision check performed immediately before every checkpoint and `.env`
+ * write, so an alias planted mid-run can never redirect those writes.
+ */
+import { randomUUID } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, statSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { defaultSetupStateWriteFs, fsyncParentDirectory, writeAllSync, } from "./checkpoint.js";
+import { SETUP_ERROR_CODES } from "./errors.js";
+import { errorResult } from "./flowResult.js";
+import { findSetupPathCollision } from "./setupPathCollision.js";
+/** The two .env keys the setup CLI manages. */
+export const SETUP_ENV_KEYS = {
+    CREDENTIALS: "GOOGLE_APPLICATION_CREDENTIALS",
+    SPREADSHEET_URL: "HIKOUTEI_SYNC_SPREADSHEET_URL",
+};
+function isManagedEnvLine(line) {
+    return (line.startsWith(`${SETUP_ENV_KEYS.CREDENTIALS}=`) ||
+        line.startsWith(`${SETUP_ENV_KEYS.SPREADSHEET_URL}=`));
+}
+/** Prefix of the unique per-run private temp file for the .env write. */
+const ENV_TEMP_PREFIX = ".hikoutei-env-";
+/** .env file permission (owner read/write only). */
+const ENV_FILE_MODE = 0o600;
+/**
+ * Writes or updates the .env output file securely and atomically.
+ *
+ * An existing output must be a regular file at the lstat boundary (a
+ * symlink is rejected outright, and directories/FIFOs/devices/sockets are
+ * refused before any open so a FIFO can never block), the file is opened
+ * WITHOUT following symlinks (`O_NOFOLLOW` where supported) and
+ * non-blocking (`O_NONBLOCK` where supported), the descriptor is
+ * fstat-verified as a regular file BEFORE a single byte is read (covering
+ * a non-regular replacement between the lstat check and the open), and any
+ * alias of the credentials file or other reserved paths (hardlink/symlink
+ * alias — the key contents are never read through it) is refused before a
+ * single byte is read. The preserved env content is built in memory and written to a unique private sibling temp
+ * file (`O_CREAT|O_EXCL|O_WRONLY` plus `O_NOFOLLOW`, mode 0600, fsync +
+ * close), then atomically renamed over the output: rename replaces the
+ * directory entry and never follows a symlink or hardlink planted after
+ * validation, so it cannot overwrite the key inode. Cleanup removes only
+ * the temp inode this invocation created. Missing file is created; a file
+ * whose content is unchanged is not rewritten. An existing file whose
+ * owner bits are not exactly 0600 counts as modified and is atomically
+ * replaced by a fresh verified-0600 file — never pathname-chmodded — so
+ * hardlinks sharing the old inode keep their own mode and content. Throws on filesystem
+ * failure or an unsafe existing entry; the caller maps the throw to
+ * `output_write_failed`.
+ */
+export function writeSetupEnvFile(outputPath, credentialsPath, spreadsheetUrl, reservedPaths = []) {
+    const read = readExistingEnvFile(outputPath, [credentialsPath, ...reservedPaths]);
+    const existing = read.existing;
+    const created = read.created;
+    const rawLines = existing === "" ? [] : existing.split("\n");
+    // A trailing empty element comes from the final newline; drop it so
+    // unrelated content is preserved without a spurious blank line.
+    const lines = rawLines.length > 0 && rawLines[rawLines.length - 1] === "" ? rawLines.slice(0, -1) : rawLines;
+    const next = [
+        ...lines.filter((line) => !isManagedEnvLine(line)),
+        `${SETUP_ENV_KEYS.CREDENTIALS}=${credentialsPath}`,
+        `${SETUP_ENV_KEYS.SPREADSHEET_URL}=${spreadsheetUrl}`,
+    ];
+    const content = `${next.join("\n")}\n`;
+    // A mode repair is a modification: an existing file whose owner bits are
+    // not exactly 0600 must be atomically replaced by a fresh verified-0600
+    // file (never pathname-chmodded, so hardlinks sharing the old inode keep
+    // their own mode and content).
+    const modeNeedsRepair = !created && read.mode !== ENV_FILE_MODE;
+    const modified = created || content !== existing || modeNeedsRepair;
+    if (modified) {
+        atomicWritePrivateFile(outputPath, content);
+    }
+    return { created, modified };
+}
+/**
+ * Reads an existing .env output without following symlinks or aliases.
+ *
+ * A symlink at the output path is rejected outright (the target could be
+ * the key file, and the contents must never be read through an alias). An
+ * existing entry must be a regular file at the lstat boundary: directories,
+ * FIFOs, devices, and sockets are refused BEFORE any open, so a FIFO can
+ * never block the open or a later read. The file is opened with `O_NOFOLLOW`
+ * (where supported) plus `O_NONBLOCK` (where supported), the descriptor is
+ * fstat-verified as a regular file BEFORE a single byte is read — this
+ * covers a non-regular replacement (for example a FIFO planted between the
+ * lstat check and the open) and prevents a FIFO open/read from blocking —
+ * and the descriptor inode is compared against every reserved path; any
+ * match is refused before reading. A missing file is `created` with empty
+ * content. Throws on unsafe entries; the caller maps throws to
+ * `output_write_failed`.
+ */
+function readExistingEnvFile(outputPath, reservedPaths) {
+    try {
+        const lst = lstatSync(outputPath);
+        if (lst.isSymbolicLink()) {
+            throw new Error(`refusing to follow a symlink at the output path ${outputPath}; remove the symlink and retry`);
+        }
+        if (!lst.isFile()) {
+            // Directories, FIFOs, devices, and sockets are never opened or read:
+            // a FIFO open without O_NONBLOCK would block indefinitely.
+            throw new Error(`the output path ${outputPath} is not a regular file; remove it and retry`);
+        }
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return { existing: "", created: true, mode: 0 };
+        }
+        throw error;
+    }
+    let fd;
+    try {
+        fd = openSync(outputPath, constants.O_RDONLY | noFollowFlag() | nonBlockFlag());
+    }
+    catch (error) {
+        if (isNodeError(error) && (error.code === "ELOOP" || error.code === "EMLINK")) {
+            // The entry became a symlink between the lstat check and the open
+            // (or the platform lacks O_NOFOLLOW): refuse rather than follow.
+            throw new Error(`refusing to follow a symlink at the output path ${outputPath}; remove the symlink and retry`);
+        }
+        throw error;
+    }
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile()) {
+            // A non-regular entry replaced the output between the lstat check and
+            // the open (e.g. a FIFO planted mid-run): refuse without reading it
+            // (O_NONBLOCK made the open return instead of blocking on a FIFO).
+            throw new Error(`the output path ${outputPath} is not a regular file; remove it and retry`);
+        }
+        const alias = reservedPaths.find((path) => sameInodeAsPath(stat, path));
+        if (alias !== undefined) {
+            throw new Error(`the output path ${outputPath} aliases the reserved file ${alias}; refusing to read or write through it`);
+        }
+        // The owner bits come from the SAME secured descriptor read, so the
+        // mode-repair decision below can never race a check-then-use sequence.
+        return { existing: readFileSync(fd, "utf8"), created: false, mode: Number(stat.mode) & 0o777 };
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch {
+            // The read error is the one to report.
+        }
+    }
+}
+/** True when the given stat names the same device/inode as the path. */
+function sameInodeAsPath(stat, path) {
+    try {
+        const other = statSync(path);
+        return stat.dev === other.dev && stat.ino === other.ino && other.ino !== 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Writes content to the output path atomically via a unique private temp.
+ *
+ * The temp file (PID + UUID sibling name) is created with exclusive
+ * no-follow flags and mode 0600, owner-only mode is applied and verified
+ * THROUGH the still-open descriptor (`fchmod` + `fstat`) before the content
+ * is written and fsynced, the path is re-verified against the created
+ * inode, and the file is renamed over the output. No pathname `chmod` is
+ * ever performed. Rename replaces the directory entry rather than
+ * following a symlink/hardlink planted after validation. Cleanup removes
+ * only the temp inode this invocation created. Throws on failure. `fs` is
+ * injectable so tests can prove the descriptor-mode behavior.
+ *
+ * Exported for the injected descriptor-mode regression; the flow calls it
+ * through `writeSetupEnvFile` with the default filesystem.
+ */
+export function atomicWritePrivateFile(outputPath, content, fs = defaultSetupStateWriteFs) {
+    const tempPath = join(dirname(outputPath), `${ENV_TEMP_PREFIX}${process.pid}-${randomUUID()}.tmp`);
+    let fd;
+    let tempDev = 0;
+    let tempIno = 0;
+    try {
+        fd = fs.openSync(tempPath, exclusivePrivateOpenFlags(), ENV_FILE_MODE);
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "EEXIST") {
+            // A pre-existing entry at the unique temp path is never followed,
+            // truncated, or unlinked.
+            throw new Error(`a conflicting entry appeared at the env temp path ${tempPath}; nothing was written`);
+        }
+        throw error;
+    }
+    try {
+        const stat = fs.fstatSync(fd);
+        tempDev = stat.dev;
+        tempIno = stat.ino;
+        // Owner-only mode is applied and verified on the STILL-OPEN descriptor
+        // before any content is written, so the final mode never depends on the
+        // process umask and a pathname chmod race is impossible.
+        fs.fchmodSync(fd, ENV_FILE_MODE);
+        const secured = fs.fstatSync(fd);
+        if ((Number(secured.mode) & 0o777) !== ENV_FILE_MODE) {
+            throw new Error(`could not verify owner-only permissions on the env temp file ${tempPath}`);
+        }
+        writeAllSync(fd, content, fs.writeSync);
+        fs.fsyncSync(fd);
+    }
+    catch (error) {
+        try {
+            fs.closeSync(fd);
+        }
+        catch {
+            // The write error is the one to report.
+        }
+        removeOwnedTempFile(tempPath, tempDev, tempIno, fs);
+        throw error;
+    }
+    try {
+        fs.closeSync(fd);
+    }
+    catch (error) {
+        // A close failure after a successful write/fsync still leaves the temp
+        // inode this invocation created: remove it (identity-checked) and
+        // rethrow. The rename must never run after a failed close, and the
+        // descriptor is never closed twice.
+        removeOwnedTempFile(tempPath, tempDev, tempIno, fs);
+        throw error;
+    }
+    // Re-verify the temp path still names the inode we created before the
+    // rename; a swapped alias must never be renamed onto the output.
+    if (!pathNamesInode(tempPath, tempDev, tempIno, fs)) {
+        removeOwnedTempFile(tempPath, tempDev, tempIno, fs);
+        throw new Error(`the env temp path ${tempPath} changed while writing; nothing was written`);
+    }
+    try {
+        // The mode was already applied and verified on the descriptor above;
+        // NO pathname chmod is performed here.
+        fs.renameSync(tempPath, outputPath);
+    }
+    catch (error) {
+        removeOwnedTempFile(tempPath, tempDev, tempIno, fs);
+        throw error;
+    }
+    // The rename is durable only after the containing directory is fsynced
+    // (same durability step as the checkpoint save): without it, a power loss
+    // right after the rename could leave the old entry (or nothing) at the
+    // output path. A failure here reports the write as failed WITHOUT
+    // rolling back the rename — the destination is already in place.
+    fsyncParentDirectory(dirname(outputPath), fs);
+}
+/** `O_NOFOLLOW` where the platform defines it, else 0. */
+export function noFollowFlag() {
+    return constants.O_NOFOLLOW ?? 0;
+}
+/** `O_NONBLOCK` where the platform defines it, else 0. */
+export function nonBlockFlag() {
+    return constants.O_NONBLOCK ?? 0;
+}
+/** Exclusive no-follow create flags for a private temp file. */
+function exclusivePrivateOpenFlags() {
+    return constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | noFollowFlag();
+}
+/** True when the path currently names exactly the given device/inode. */
+function pathNamesInode(path, dev, ino, fs) {
+    try {
+        const stat = fs.lstatSync(path);
+        return stat.dev === dev && stat.ino === ino;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Removes the temp file only when it is still the inode this invocation
+ * created; a replaced or foreign entry is never touched.
+ */
+function removeOwnedTempFile(tempPath, dev, ino, fs) {
+    try {
+        if (pathNamesInode(tempPath, dev, ino, fs)) {
+            fs.unlinkSync(tempPath);
+        }
+    }
+    catch {
+        // Missing or already replaced: nothing of ours to clean up.
+    }
+}
+/**
+ * Re-runs the reserved-path collision check and fails closed when aliases
+ * changed after the initial preflight.
+ *
+ * The reserved paths (key, output, checkpoint, temp, lock) are re-resolved
+ * immediately before every checkpoint write and the .env write: a symlink
+ * or hardlink planted after the preflight must never redirect a write to a
+ * reserved file. Returns an error result on collision, `null` when safe.
+ */
+export function revalidateSetupPaths(options) {
+    const collision = findSetupPathCollision({
+        keyPath: options.keyPath,
+        outputPath: options.outputPath,
+        statePath: options.statePath,
+    });
+    if (collision.status === "collision") {
+        return errorResult(SETUP_ERROR_CODES.INVALID_ARGS, `${collision.message}; the reserved setup paths changed during the run, so nothing was written`);
+    }
+    return null;
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}
+//# sourceMappingURL=envFileWriter.js.map

package/dist/cli/envFileWriter.js.map

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

package/dist/cli/keyMaterial.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Service-account key material handling for `hikoutei setup`.
+ *
+ * The secure key-file reading and validation logic of the setup flow,
+ * extracted verbatim: parse/validate raw key JSON, securely read an existing
+ * key file through ONE descriptor boundary (no-follow, non-block,
+ * lstat/fstat inode binding, owner-only mode 0600 applied and verified
+ * through the still-open descriptor before any read, sanitized path-only
+ * failures), and promote either the non-secret metadata or the validated
+ * in-memory credential. The private key exists only in process memory for
+ * the run and never appears in results, messages, the checkpoint, or the
+ * `.env` file.
+ */
+import type { KeyMetadataResult, SecureKeyReadResult } from "./checkpoint.js";
+import { type Stats } from "node:fs";
+/**
+ * Parses and validates raw service-account key JSON (no filesystem access).
+ *
+ * Shared by the secure descriptor read and by tests. The key material is
+ * never returned; only the non-secret metadata is promoted. The validated
+ * in-memory key material is available to the credential reader
+ * (`readServiceAccountKeyCredentialSecurely`) for the SA verify phase.
+ */
+export declare function parseServiceAccountKeyJson(raw: string, sourceLabel: string): KeyMetadataResult;
+/**
+ * Filesystem operations the secure key read uses; injectable for tests.
+ */
+export interface KeyFileFs {
+    lstatSync(path: string): Stats;
+    openSync(path: string, flags: number): number;
+    fchmodSync(fd: number, mode: number): void;
+    fstatSync(fd: number): Stats;
+    readFileSync(fd: number, encoding: "utf8"): string;
+    closeSync(fd: number): void;
+}
+/**
+ * Securely reads an existing service-account key file through ONE
+ * descriptor boundary and enforces owner-only mode 0600.
+ *
+ * A missing file is `absent`. An existing entry must be a regular file (a
+ * symlink is refused outright; directories, FIFOs, and sockets are refused
+ * too). The file is opened with `O_NOFOLLOW` (where the platform defines it
+ * — a symlink swapped in between the type check and the open fails with
+ * ELOOP/EMLINK and is refused) plus `O_NONBLOCK` (where the platform
+ * defines it — a FIFO swapped in between the type check and the open
+ * returns from the open instead of blocking), the descriptor is
+ * fstat-verified as a regular file with the SAME device/inode the lstat
+ * observed BEFORE any fchmod (a directory, FIFO, socket, device, or
+ * replaced-file entry is refused with zero chmod and zero read calls), and
+ * only then is mode 0600 applied THROUGH the open descriptor
+ * with `fchmod` and the resulting mode verified on the same descriptor
+ * before a single byte is read — never an existsSync/readFileSync
+ * check-then-use sequence, so an alias planted mid-read cannot receive the
+ * chmod or be read through. Only after the descriptor is secured is the
+ * content parsed and validated (JSON shape, RSA private key, project,
+ * client email, and non-secret key id). Any inspect/open/type/chmod/read/
+ * parse failure fails closed with a stable path-only message that never
+ * contains raw error text or key material, and the descriptor is closed
+ * exactly once (a close failure never overrides the verdict). Supported
+ * platforms (macOS/Linux) can
+ * enforce owner-only modes; Windows automatic setup is refused before this
+ * code runs.
+ */
+export declare function readServiceAccountKeySecurely(keyPath: string, fs?: KeyFileFs): SecureKeyReadResult;
+/**
+ * Result of the secure, descriptor-based key credential read.
+ *
+ * Same descriptor boundary as `readServiceAccountKeySecurely`, but the
+ * validated `private_key` is promoted into process memory for the SA
+ * access verify phase: the verifier is given the credentials in memory and
+ * NEVER reopens the key pathname, so a mid-run replacement cannot redirect
+ * it. The key material exists only in memory for the run; it is never
+ * returned by the setup result, never written to the checkpoint or `.env`,
+ * and never included in any error message.
+ */
+export type SecureKeyCredentialReadResult = {
+    readonly status: "absent";
+} | {
+    readonly status: "ok";
+    readonly credentials: {
+        readonly projectId: string;
+        readonly clientEmail: string;
+        readonly privateKey: string;
+    };
+} | {
+    readonly status: "invalid";
+    readonly message: string;
+};
+/**
+ * Securely reads an existing service-account key file and promotes the
+ * validated credential into process memory.
+ *
+ * Identical descriptor security to `readServiceAccountKeySecurely`
+ * (regular file, no-follow, non-block, lstat/fstat inode binding, owner-only
+ * 0600 through the descriptor before any read, sanitized failures), but
+ * the returned credentials carry the validated `privateKey` so the SA
+ * access verifier can authenticate from memory. The private key is only in
+ * process memory for the run and never appears in results, messages, the
+ * checkpoint, or the `.env` file.
+ */
+export declare function readServiceAccountKeyCredentialSecurely(keyPath: string, fs?: KeyFileFs): SecureKeyCredentialReadResult;
+//# sourceMappingURL=keyMaterial.d.ts.map

package/dist/cli/keyMaterial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyMaterial.d.ts","sourceRoot":"","sources":["../../src/cli/keyMaterial.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAI9E,OAAO,EAQL,KAAK,KAAK,EACX,MAAM,SAAS,CAAC;AAEjB;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,iBAAiB,CAO9F;AAmED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9C,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,KAAK,CAAC;IAC7B,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IACnD,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,MAAM,EACf,EAAE,GAAE,SAA4B,GAC/B,mBAAmB,CAOrB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,6BAA6B,GACrC;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,GAC7B;IACA,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;KAC7B,CAAC;CACH,GACC;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D;;;;;;;;;;;GAWG;AACH,wBAAgB,uCAAuC,CACrD,OAAO,EAAE,MAAM,EACf,EAAE,GAAE,SAA4B,GAC/B,6BAA6B,CAO/B"}