@timekast/factory 1.28.1 → 2.0.1

package/dist/lib/publish-engine.js

@@ -17,7 +17,7 @@ export const realGit = async (args, opts) => {
 };
 /**
  * Resolve a token with push access to the hub. Dual auth (plan B-1):
- *   - `TIMEKAST_PUBLISH_TOKEN` in env → headless (Agent Server, infra TimeKast).
+ *   - `TIMEKAST_PUBLISH_TOKEN` in env → headless (no TTY).
  *   - else → dev local: full preflight (gh + org member) then `gh auth token`.
  * Never reads a token from a derived repo.
  */

package/dist/lib/rail.js

@@ -0,0 +1,400 @@
+/**
+ * The single rail resolver (RAIL-001) — the ONLY place where the CLI asks the org secrets vault
+ * for a token of a rail project (`rail-timekast` by default, or a `rail-<client>` the caller
+ * names). Contract: `fx-secrets-vault §3` + ADR-006.
+ *
+ * HOW IT READS: one `infisical export --format=json` per rail project per process, with the
+ * PERSON's session (`infisical login`). The parsed map lives only in this process's memory:
+ * nothing is written to disk, nothing is copied into `process.env`, nothing survives the run.
+ *
+ * FAILURES ARE TYPED, never parsed by the caller (`RailError.kind`):
+ *   - `no-session`   — no session or an expired one → names `infisical login --domain=…`
+ *   - `no-access`    — live session, no access to the project — or the configured project id
+ *                      does not exist (infisical answers both alike) → names the project + its id
+ *   - `key-missing`  — the export worked and the key is not there → names the key.
+ *                      The ONLY failure a caller may treat as optional (`getOptional`).
+ *   - `unrecognized` — anything infisical said that we do not recognise (unknown stderr, invalid
+ *                      JSON, odd exit). NEVER mapped to `key-missing` nor to `no-access`: guessing
+ *                      there sends the person to the wrong fix, or silently skips a required token.
+ *   - `not-installed`— the `infisical` binary is not on PATH (ENOENT) — distinct from no-session,
+ *                      or the person is sent to a `login` command that does not exist.
+ *   - `timeout`      — the vault did not answer in time.
+ *
+ * 🔴 NO-ECHO — why every error here is built from the classification ONLY. The child's stdout IS
+ * the JSON with every token of the rail. execa 9 folds the child's stdout into `ExecaError.message`,
+ * `JSON.parse` quotes a snippet of its input in its `SyntaxError.message`, and `cli/src/index.ts`
+ * prints `console.error(error)` for any non-`CLIError`. So: `reject: false` (no ExecaError is ever
+ * built), `verbose: 'none'` (execa defaults to `'full'` under `NODE_DEBUG=execa`, which echoes the
+ * child's stdout), every error is a `RailError` built from exit code / timedOut / ENOENT, no
+ * `cause`, and a total catch converts anything else to `unrecognized` without its message.
+ *
+ * 🔴 stdin is ALWAYS closed (`stdin: 'ignore'`). Without a session, `infisical` does not fail
+ * cleanly: it starts an interactive login (a `login --silent` child), writes an ANSI prompt to
+ * STDOUT and blocks reading stdin until EOF. That child does NOT receive our `--domain`: it
+ * resolves the domain from `INFISICAL_DOMAIN`, then from a `.infisical.json` found walking up
+ * from the cwd, then its default — and it may open a BROWSER at that domain before it ever
+ * reads stdin. A `.infisical.json` planted in a repo would open an attacker's login page. So the
+ * child's environment ALWAYS pins `INFISICAL_DOMAIN` to the vault's domain (the first source it
+ * consults). Only after that does the closed stdin end the prompt; the timeout is the last belt.
+ *
+ * A rail token exported in the person's shell is IGNORED (the vault wins) and named on STDERR —
+ * never stdout (some commands' stdout is a machine contract) and never with its value.
+ *
+ * Tests: the runner is an injectable seam. Under Vitest a setup file (`cli/tests/setup/`)
+ * replaces the DEFAULT runner with one that refuses loudly, so a test that forgets to inject
+ * never reaches the real `infisical`. That override lives on `globalThis` of the Vitest process
+ * only — deliberately NOT an environment variable, which a CLI spawned as a subprocess would
+ * inherit.
+ */
+import { execa } from 'execa';
+import { CLIError } from './cli-error.js';
+import { VAULT_CONFIG } from './vault-config.js';
+/** The vault environment every rail is read from (`fx-secrets-vault §3`). */
+export const RAIL_ENV = 'main';
+/** Name of the vault CLI binary on PATH. */
+export const INFISICAL_BIN = 'infisical';
+/** How to install the vault CLI (`fx-secrets-vault §3`). */
+export const INFISICAL_INSTALL_HINT = 'brew install infisical';
+/** Default time budget (ms) for one rail read — a dead network or a stuck prompt must not hang. */
+export const RAIL_READ_TIMEOUT_MS = 30_000;
+/** Grace (ms) between SIGTERM and SIGKILL once the timeout fires. */
+const FORCE_KILL_AFTER_MS = 2_000;
+/**
+ * Environment variable the vault CLI would use INSTEAD of the person's session. Stripped from
+ * the child's environment so the rail is always read with `infisical login`'s session (a stale
+ * token or a machine identity exported in the shell must not decide who reads the rail).
+ */
+const INFISICAL_TOKEN_ENV = 'INFISICAL_TOKEN';
+/**
+ * Environment variable the vault CLI's auto-login consults FIRST to pick the domain it logs into
+ * (it does not inherit `--domain`). Always set to the vault's domain in the child's environment,
+ * so a `.infisical.json` in the cwd's ancestry can never choose where a login page opens.
+ */
+const INFISICAL_DOMAIN_ENV = 'INFISICAL_DOMAIN';
+/** The command that opens a session on the org vault. */
+export function loginCommand(config = VAULT_CONFIG) {
+    return `infisical login --domain=${config.domain}`;
+}
+/** The org rail, from the embedded copy of `.claude/policy/vault.json`. */
+export const RAIL_TIMEKAST = VAULT_CONFIG.rail;
+/** Base of every rail failure. A `CLIError`, so the top-level handler prints only its message. */
+export class RailError extends CLIError {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = 'RailError';
+        this.kind = kind;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** No session on the vault, or it expired. */
+export class RailNoSessionError extends RailError {
+    constructor(config = VAULT_CONFIG) {
+        super('no-session', 'No hay una sesión activa en la bóveda de secretos, o ya caducó. Entra con:\n' +
+            `  ${loginCommand(config)}\n` +
+            'y vuelve a intentar.');
+        this.name = 'RailNoSessionError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Live session without access to the rail project (access is per project). */
+export class RailNoAccessError extends RailError {
+    project;
+    constructor(project) {
+        super('no-access', `Tu sesión de la bóveda está activa, pero no tienes acceso al proyecto \`${project.name}\` ` +
+            `— o el proyecto configurado (id \`${project.projectId}\`) no existe.\n` +
+            'El acceso es por proyecto (estar en la organización no lo da): pide acceso a un admin de la ' +
+            'bóveda, o revisa el id.');
+        this.name = 'RailNoAccessError';
+        this.project = project.name;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** The read worked and the key is not in the rail (or is empty). */
+export class RailKeyMissingError extends RailError {
+    key;
+    constructor(key, project) {
+        super('key-missing', `La clave \`${key}\` no existe en \`${project.name}\` (entorno ${RAIL_ENV}) o está vacía.\n` +
+            'Pide a un admin de la bóveda que la cargue.');
+        this.name = 'RailKeyMissingError';
+        this.key = key;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** What infisical answered is not something this module recognises. */
+export class RailUnrecognizedError extends RailError {
+    constructor(project, detail, config = VAULT_CONFIG) {
+        super('unrecognized', `La bóveda respondió algo que no reconozco al leer \`${project.name}\` (${detail}).\n` +
+            'No lo trato como clave ausente ni como falta de acceso. Revisa que tu sesión funcione ' +
+            `(\`${loginCommand(config)}\`) y que \`infisical\` esté al día; si persiste, repórtalo al equipo del Factory.`);
+        this.name = 'RailUnrecognizedError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** The `infisical` binary is not installed / not on PATH. */
+export class RailNotInstalledError extends RailError {
+    constructor(config = VAULT_CONFIG) {
+        super('not-installed', 'El CLI de la bóveda (`infisical`) no está instalado o no está en el PATH.\n' +
+            `Instálalo con \`${INFISICAL_INSTALL_HINT}\` y entra con \`${loginCommand(config)}\`.`);
+        this.name = 'RailNotInstalledError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** The vault did not answer within the time budget. */
+export class RailTimeoutError extends RailError {
+    constructor(project, timeoutMs, config = VAULT_CONFIG) {
+        super('timeout', `La bóveda no respondió en ${Math.round(timeoutMs / 1000)} s al leer \`${project.name}\`.\n` +
+            `Revisa tu conexión a ${config.domain}; si tu sesión caducó, entra de nuevo con ` +
+            `\`${loginCommand(config)}\`.`);
+        this.name = 'RailTimeoutError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** A spawn that never produced an outcome we can read. */
+const NO_OUTCOME = {
+    exitCode: null,
+    stdout: '',
+    stderr: '',
+    timedOut: false,
+    notFound: false,
+};
+/** The real runner: execa with stdin closed, no rejection, no verbose echo, a hard timeout. */
+export function createExecaInfisicalRunner(options = {}) {
+    const bin = options.bin ?? INFISICAL_BIN;
+    return async (args, { timeoutMs, domain }) => {
+        const childEnv = { ...(options.env ?? process.env) };
+        delete childEnv[INFISICAL_TOKEN_ENV];
+        childEnv[INFISICAL_DOMAIN_ENV] = domain;
+        try {
+            const result = await execa(bin, [...args], {
+                stdin: 'ignore',
+                reject: false,
+                verbose: 'none',
+                timeout: timeoutMs,
+                forceKillAfterDelay: FORCE_KILL_AFTER_MS,
+                env: childEnv,
+                extendEnv: false,
+            });
+            return {
+                exitCode: typeof result.exitCode === 'number' ? result.exitCode : null,
+                stdout: typeof result.stdout === 'string' ? result.stdout : '',
+                stderr: typeof result.stderr === 'string' ? result.stderr : '',
+                timedOut: result.timedOut === true,
+                notFound: result.code === 'ENOENT',
+            };
+        }
+        catch (error) {
+            // `reject: false` should keep execa from throwing; if it still does (bad options, an
+            // internal failure), keep only the ENOENT bit — never the error itself.
+            return { ...NO_OUTCOME, notFound: error?.code === 'ENOENT' };
+        }
+    };
+}
+/**
+ * Key on `globalThis` where the Vitest setup installs its refusing default runner. Test-only
+ * seam: production code never sets it, and — unlike an environment variable — a CLI spawned as a
+ * subprocess does not inherit it. The string is duplicated in `cli/tests/setup/rail-fail-closed.ts`
+ * (which must not import this module: it would preload `execa` before test files mock it); the
+ * rail tests pin the link.
+ */
+export const DEFAULT_RUNNER_OVERRIDE_KEY = Symbol.for('@timekast/factory:rail.default-runner');
+/** The default runner: the test override when present, else the real execa runner. */
+function resolveDefaultRunner() {
+    const override = globalThis[DEFAULT_RUNNER_OVERRIDE_KEY];
+    return typeof override === 'function'
+        ? override
+        : createExecaInfisicalRunner();
+}
+// ---------------------------------------------------------------------------
+// Classification (stderr patterns — patterns, not equality: stderr may carry unrelated notices)
+//
+// 🔴 Replayed by hand in `scripts/tools/lib/rail.sh` (`RAIL_NO_SESSION_RE` / `RAIL_NO_ACCESS_RE`),
+// which travels to `core` derivatives where this source does not exist. Edit both together:
+// `cli/tests/unit/rail-classification-parity.test.ts` runs ONE corpus of transcripts
+// through this resolver and through `rail.sh`, and fails the moment the two classify apart.
+// ---------------------------------------------------------------------------
+/**
+ * No session / expired session. The first two are REAL infisical 0.43.96 texts, captured live
+ * with an empty HOME (RAIL-008; the transcript is pinned in the shared corpus
+ * `cli/tests/fixtures/infisical-transcripts.ts`). "login session has expired" was verified in CP-A but not reproduced live (it needs an expired session);
+ * `status-code=401` is an assumption.
+ */
+const NO_SESSION_PATTERNS = [
+    /no valid login session found/i,
+    /failed to automatically trigger login flow/i,
+    /login session has expired/i,
+    /status-code=401\b/i,
+];
+/**
+ * Live session without access. The LAST pattern is a REAL infisical 0.43.96 text, captured live
+ * against a project id that does not exist (RAIL-008: `404 … Project with ID '<id>' not found
+ * during bot lookup`; pinned in the shared corpus `cli/tests/fixtures/infisical-transcripts.ts`).
+ * It stays `no-access` on purpose, and the message says so ("— o el proyecto configurado no
+ * existe"): from outside, a missing project and a project you cannot see are the same answer.
+ * ⚠️ The others are ASSUMED texts for an EXISTING project the session is not a member of —
+ * reproducing that live means touching memberships of a real project, so it stays unverified.
+ */
+const NO_ACCESS_PATTERNS = [
+    /unable to access project/i,
+    /status-code=403\b/i,
+    /permission ?denied/i,
+    /\bforbidden\b/i,
+    /not allowed to/i,
+    /do(?:es)? not have (?:access|permission)/i,
+    /not (?:a )?(?:part|member) of/i,
+    /project with id \S+ (?:was )?not found/i,
+];
+/** Map a failed read to its typed error. Session is checked first: fix the session, then access. */
+function classifyFailure(result, project, config, timeoutMs, fallbackDetail) {
+    if (result.notFound)
+        return new RailNotInstalledError(config);
+    if (result.timedOut)
+        return new RailTimeoutError(project, timeoutMs, config);
+    if (NO_SESSION_PATTERNS.some((pattern) => pattern.test(result.stderr))) {
+        return new RailNoSessionError(config);
+    }
+    if (NO_ACCESS_PATTERNS.some((pattern) => pattern.test(result.stderr))) {
+        return new RailNoAccessError(project);
+    }
+    return new RailUnrecognizedError(project, fallbackDetail, config);
+}
+/**
+ * Parse the export into a key → value map, or `null` when the shape is not one we recognise.
+ * Accepted: an array of `{ key, value }` objects (infisical's `--format=json`), or a flat object
+ * of string values. Never throws — `JSON.parse`'s own error quotes the input (the secrets).
+ */
+function parseExport(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    const secrets = new Map();
+    if (Array.isArray(parsed)) {
+        for (const entry of parsed) {
+            if (entry === null || typeof entry !== 'object')
+                return null;
+            const { key, value } = entry;
+            if (typeof key !== 'string' || typeof value !== 'string')
+                return null;
+            // First occurrence wins (the project's own secret before an imported one).
+            if (!secrets.has(key))
+                secrets.set(key, value);
+        }
+        return secrets;
+    }
+    if (parsed !== null && typeof parsed === 'object') {
+        for (const [key, value] of Object.entries(parsed)) {
+            if (typeof value !== 'string')
+                return null;
+            secrets.set(key, value);
+        }
+        return secrets;
+    }
+    return null;
+}
+/** Build a resolver. Its cache is in memory and dies with the resolver (and the process). */
+export function createRailResolver(deps = {}) {
+    const config = deps.config ?? VAULT_CONFIG;
+    const timeoutMs = deps.timeoutMs ?? RAIL_READ_TIMEOUT_MS;
+    const cache = new Map();
+    const warned = new Set();
+    async function readProject(project) {
+        const runner = deps.runner ?? resolveDefaultRunner();
+        const args = [
+            'export',
+            '--format=json',
+            '--silent',
+            '--secret-overriding=false',
+            `--projectId=${project.projectId}`,
+            `--env=${RAIL_ENV}`,
+            `--domain=${config.domain}`,
+        ];
+        let result;
+        try {
+            result = await runner(args, { timeoutMs, domain: config.domain });
+        }
+        catch {
+            // A runner is not supposed to throw; if one does, its error may carry anything.
+            throw new RailUnrecognizedError(project, 'el lector de la bóveda falló sin respuesta', config);
+        }
+        if (result.notFound || result.timedOut) {
+            throw classifyFailure(result, project, config, timeoutMs, 'sin respuesta');
+        }
+        if (result.exitCode !== 0) {
+            const detail = result.exitCode === null
+                ? 'el proceso terminó sin código de salida'
+                : `código de salida ${result.exitCode}`;
+            throw classifyFailure(result, project, config, timeoutMs, detail);
+        }
+        const secrets = parseExport(result.stdout);
+        if (secrets === null) {
+            // Exit 0 with output we cannot read is NEVER classified by stderr: a successful exit says
+            // the session and the access worked, so a stray "login"/"forbidden" text there would send
+            // the person to the wrong fix. Same rule as `scripts/tools/lib/rail.sh` (exit 43) — the
+            // shared corpus test pins that the two readers agree.
+            throw new RailUnrecognizedError(project, 'salida que no es el JSON esperado', config);
+        }
+        return secrets;
+    }
+    function secretsOf(project) {
+        const cached = cache.get(project.projectId);
+        if (cached)
+            return cached;
+        const pending = readProject(project).catch((error) => {
+            // A failure is not cached: the next caller retries (e.g. after `infisical login`).
+            cache.delete(project.projectId);
+            throw error instanceof RailError
+                ? error
+                : new RailUnrecognizedError(project, 'error interno al leer la bóveda', config);
+        });
+        cache.set(project.projectId, pending);
+        return pending;
+    }
+    function noticeStaleEnv(key, project) {
+        const env = deps.env ?? process.env;
+        const stale = env[key];
+        // An EMPTY export (`KEY=`) is no copy of a secret — nothing to warn about, and it never wins.
+        if (typeof stale !== 'string' || stale === '' || warned.has(key))
+            return;
+        warned.add(key);
+        (deps.stderr ?? process.stderr).write(`⚠ Ignoro ${key} de tu entorno: el rail se lee de la bóveda (${project.name}). ` +
+            'Borra esa variable de tu shell (p. ej. un export en ~/.zshrc): es una copia que ya nadie rota.\n');
+    }
+    async function get(key, options = {}) {
+        const project = options.project ?? config.rail;
+        noticeStaleEnv(key, project);
+        const secrets = await secretsOf(project);
+        const value = secrets.get(key);
+        if (value === undefined || value === '')
+            throw new RailKeyMissingError(key, project);
+        return value;
+    }
+    async function getOptional(key, options = {}) {
+        try {
+            return await get(key, options);
+        }
+        catch (error) {
+            if (error instanceof RailKeyMissingError)
+                return null;
+            throw error;
+        }
+    }
+    return { get, getOptional };
+}
+/** The process-wide resolver behind `readRailSecret` / `readOptionalRailSecret`. */
+let processResolver;
+function defaultResolver() {
+    processResolver ??= createRailResolver();
+    return processResolver;
+}
+/** Read a required rail key with the default resolver (one vault read per project per process). */
+export function readRailSecret(key, options) {
+    return defaultResolver().get(key, options);
+}
+/** Read an optional rail key: `null` only when the key is missing; every other failure throws. */
+export function readOptionalRailSecret(key, options) {
+    return defaultResolver().getOptional(key, options);
+}