@timekast/factory 1.28.1 → 2.0.0

package/dist/lib/constants.js

@@ -7,9 +7,6 @@
 export const FACTORY_ORG = 'TimeKast';
 /** The Factory monorepo, source of the distribution releases. */
 export const FACTORY_REPO = 'TimeKast/TimeKast-Factory';
-// NOTE: the org secrets gate constants (SECRETS_GATE_URL, GITHUB_DEVICE_CLIENT_ID,
-// GITHUB_DEVICE_SCOPE, SECRETS_STATE_FILE) were REMOVED with the `secrets pull`/`sync`
-// device-flow gate — that droplet effort is parked; the future is Infisical.
 /** The static hub repo that hosts published proposals/mockups (`factory publish`). */
 export const PROPOSALS_HUB_REPO = `${FACTORY_ORG}/proposals`;
 /** HTTPS git URL of the hub (token is injected by the publish command). */
@@ -148,6 +145,66 @@ export const FACTORY_SCRIPTS = {
     [UNPUBLISH_SCRIPT_NAME]: UNPUBLISH_SCRIPT_CMD,
     [ENV_PUSH_SCRIPT_NAME]: ENV_PUSH_SCRIPT_CMD,
 };
+/**
+ * The local wrapper that injects the vault's environment into the kit's scripts (VAULT-003).
+ * Ships with the FULL brain (`scripts/**`); the `core` profile does not carry it.
+ */
+export const WITH_VAULT_SCRIPT_FILE = 'scripts/tools/with-vault.mjs';
+/** The prefix every wrapped script value starts with. */
+export const WITH_VAULT_SCRIPT_CMD = `node ${WITH_VAULT_SCRIPT_FILE}`;
+/**
+ * 🔴 THE single source of the kit's script values that go through the wrapper (VAULT-004). The
+ * Factory's own `package.json` carries exactly these values (a test in `package-json.test.ts`
+ * reads the real file and pins it), the wiring of `provision` (`wrapper-wiring.ts`) rewrites a
+ * derivative's scripts to them, and every older constant that names one of these scripts
+ * (`SETUP_E2E_VARS_SCRIPT_CMD`) reads it from here — nobody repeats the literal.
+ *
+ * `invite:admin` is NOT here: it reads its `--target` environment straight from the vault
+ * (VAULT-003), so its value did not change and there is nothing to wrap or to heal.
+ */
+const VAULT_WRAPPED_SCRIPT_SPECS = [
+    { name: 'dev', inner: 'node scripts/tools/dev.mjs' },
+    { name: 'build', inner: 'next build' },
+    // `analyze` runs its own `next build` (with ANALYZE on): the build needs the same env as `build`.
+    // The wrapper wraps only that first command — the bundle report after `&&` reads `.next/`, no secret.
+    { name: 'analyze', inner: 'next build && node scripts/tools/analyze-bundle.mjs' },
+    { name: 'start', inner: 'next start' },
+    { name: 'test:e2e', inner: 'tsx scripts/tools/e2e-runner.ts' },
+    { name: 'env:check', inner: 'tsx scripts/tools/env-check.ts' },
+    { name: 'db:generate', inner: 'drizzle-kit generate' },
+    { name: 'db:migrate', inner: 'drizzle-kit migrate' },
+    { name: 'db:push', inner: 'drizzle-kit push' },
+    { name: 'db:studio', inner: 'drizzle-kit studio' },
+    { name: 'db:harden-enum', inner: 'tsx scripts/tools/harden-enum.ts' },
+    { name: 'db:query', inner: 'tsx scripts/tools/db-query.ts' },
+    { name: 'db:query:dev', inner: 'tsx scripts/tools/db-query.ts' },
+    { name: 'db:query:main', inner: 'tsx scripts/tools/db-query.ts --main', vaultEnv: 'main' },
+    {
+        name: 'db:seed',
+        inner: 'tsx --require dotenv/config src/lib/db/seed.ts dotenv_config_path=.env.local',
+    },
+    { name: 'setup:e2e', inner: 'tsx scripts/tools/setup-e2e.ts', vaultEnv: 'develop' },
+    {
+        name: 'setup:e2e:vars',
+        inner: 'tsx scripts/tools/setup-e2e.ts --publish-vars',
+        vaultEnv: 'develop',
+    },
+    { name: 'generate:email-logo', inner: 'tsx scripts/tools/generate-email-logo.ts' },
+];
+/** Put the wrapper in front of `inner`, with its environment flag when it is not `local`. */
+function wrapWithVault(inner, vaultEnv) {
+    return vaultEnv
+        ? `${WITH_VAULT_SCRIPT_CMD} --vault-env=${vaultEnv} ${inner}`
+        : `${WITH_VAULT_SCRIPT_CMD} ${inner}`;
+}
+/** The registry, keyed by script name (see {@link VAULT_WRAPPED_SCRIPT_SPECS}). */
+export const VAULT_WRAPPED_SCRIPTS = Object.freeze(Object.fromEntries(VAULT_WRAPPED_SCRIPT_SPECS.map((spec) => [
+    spec.name,
+    {
+        cmd: wrapWithVault(spec.inner, spec.vaultEnv),
+        unwrapped: [spec.inner, ...(spec.historic ?? [])],
+    },
+])));
 /**
  * Kit-local convenience script: the readiness sweep (`pnpm preflight`, consumed
  * by the /deploy gate and /preflight). Unlike the npx-based `factory:*` scripts
@@ -175,11 +232,15 @@ export const INVITE_ADMIN_SCRIPT_FILE = 'scripts/tools/invite-admin.ts';
  * tsx-based (not npx) and FILE-GATED, same contract as `preflight`: a
  * core/non-Factory derivative without `scripts/tools/setup-e2e.ts` never gets
  * a broken `setup:e2e:vars`. Insert-if-missing; self-heals on the next update
- * once the script lands. Command confirmed verbatim against `package.json:50`
- * of the kit.
+ * once the script lands.
+ *
+ * Runs through the vault wrapper (VAULT-004): the value comes from `VAULT_WRAPPED_SCRIPTS`,
+ * and the unwrapped value the kit shipped before is registered in `OBSOLETE_SCRIPT_CMDS` so
+ * `factory update` heals it. Both the insertion and the healing are ALSO gated on the wrapper
+ * file (`kitLocalScripts`): a repo without it never gets a script pointing at a missing file.
  */
 export const SETUP_E2E_VARS_SCRIPT_NAME = 'setup:e2e:vars';
-export const SETUP_E2E_VARS_SCRIPT_CMD = 'tsx scripts/tools/setup-e2e.ts --publish-vars';
+export const SETUP_E2E_VARS_SCRIPT_CMD = VAULT_WRAPPED_SCRIPTS[SETUP_E2E_VARS_SCRIPT_NAME].cmd;
 export const SETUP_E2E_VARS_SCRIPT_FILE = 'scripts/tools/setup-e2e.ts';
 /**
  * Kit-local Playwright browser install alias (`pnpm e2e:setup`).
@@ -405,6 +466,9 @@ export const OBSOLETE_SCRIPT_CMDS = {
     // whole COMMANDS (not just the number) so healing stays exact-match: a derivative that
     // appended a flag of its own, or picked a ceiling the kit never shipped, is left alone.
     [VERIFY_SCRIPT_NAME]: VERIFY_OBSOLETE_CMDS,
+    // VAULT-004: the value the kit shipped before the vault wrapper. `invite:admin` has no entry:
+    // its value did not change in the release that brought the wrapper (VAULT-003).
+    [SETUP_E2E_VARS_SCRIPT_NAME]: VAULT_WRAPPED_SCRIPTS[SETUP_E2E_VARS_SCRIPT_NAME].unwrapped,
     [DEV_NEXT_SCRIPT_NAME]: DEV_NEXT_OBSOLETE_HEAPS_MB.map((mb) => `NODE_OPTIONS='--max-old-space-size=${mb}' next dev --turbopack`),
 };
 /**

package/dist/lib/env-file.js

@@ -10,6 +10,7 @@
 import { chmodSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { CLIError } from './cli-error.js';
+import { hasVaultLink } from './provision-state.js';
 import { generateAuthSecret } from './vercel-env.js';
 /**
  * Vars that provision owns and sets PER-ENVIRONMENT (or keeps local-only). The
@@ -35,6 +36,9 @@ export const PROVISION_OWNED = new Set([
     // (rpID must match the env's host) or the at-rest TOTP crypto.
     'MFA_ENCRYPTION_KEY',
     'WEBAUTHN_RP_ID',
+    // The origins allowed to run a ceremony for that rpID (Related Origin Requests): provision
+    // sets the develop origin so ONE rpID (the production host) serves both deploys.
+    'WEBAUTHN_RELATED_ORIGINS',
     // LOCAL-ONLY E2E credentials (like DATABASE_URL_MAIN): the E2E runner reads them
     // from `.env.local` to spin an isolated Neon branch per run. Both local and CI hold
     // the SAME project-scoped key (see `writeE2eLocalCreds`); they must NEVER reach
@@ -48,6 +52,29 @@ export const PROVISION_OWNED = new Set([
     'BACKLOG_API_KEY',
     'BACKLOG_PROJECT_ID',
 ]);
+/**
+ * The LOCAL-ONLY subset of {@link PROVISION_OWNED}: keys that must NEVER land in a vault folder
+ * that syncs to a deploy (Vercel production/preview). The vault client's write guard
+ * (`vault-api.ts`) reads THIS set — the per-key allowed destinations live there; this is only the
+ * membership. MUST stay a subset of `PROVISION_OWNED` (pinned by `tests/unit/env-file.test.ts`).
+ */
+export const LOCAL_ONLY_KEYS = new Set([
+    'NEON_API_KEY',
+    'NEON_PROJECT_ID',
+    'DATABASE_URL_MAIN',
+    'BACKLOG_API_KEY',
+    'BACKLOG_PROJECT_ID',
+]);
+/**
+ * 🔴 VAULT GUARD (VAULT-002) — every writer below refuses to touch `.env.local` in a repo linked
+ * to the vault (`vault` block in `.timekast/provision.json`). There the values live in the vault
+ * and each writer's caller routes them there; this check is the defense in depth that keeps a
+ * forgotten path from re-creating a file Next.js would load on top of the vault's values
+ * (`fx-secrets-vault §7`). Fail-closed: an unreadable state file throws (see `readVaultLink`).
+ */
+function linkedToVault(rootDir) {
+    return hasVaultLink(rootDir);
+}
 /**
  * Replace the value of `KEY=...` in an env-file body, preserving every other line.
  * Appends `KEY="value"` when the key is absent (so an older `.env.example` without
@@ -74,8 +101,12 @@ export function setEnvLine(body, key, value) {
  * → the main branch (read by `pnpm db:query:main`). NEVER clobbers an existing
  * `.env.local` (the dev may have edited it) unless `--force`. The `.env.example` stays
  * the SSOT of which keys exist; the keys are appended if absent (older scaffolds).
+ *
+ * Returns `'vault'` (and writes nothing) in a repo linked to the vault — see {@link linkedToVault}.
  */
 export function writeEnvLocal(rootDir, neon, opts = {}) {
+    if (linkedToVault(rootDir))
+        return 'vault';
     const examplePath = join(rootDir, '.env.example');
     if (!existsSync(examplePath))
         return 'no-example';
@@ -88,7 +119,7 @@ export function writeEnvLocal(rootDir, neon, opts = {}) {
     body = setEnvLine(body, 'AUTH_SECRET', generateAuthSecret());
     // `.env.local` holds DB strings + AUTH_SECRET → owner-only (0600) from birth.
     // The `mode: 0o600` makes the file created 0600 with no world-readable window
-    // between create and chmod — critical on the headless multi-tenant Agent Server
+    // between create and chmod — critical on a shared headless host
     // where the default umask would otherwise leave one tenant's secrets briefly
     // readable by others. `mode` only applies when the file is CREATED, so the
     // chmod below still covers the `--force` overwrite path (file already exists).
@@ -121,6 +152,8 @@ export function writeEnvLocal(rootDir, neon, opts = {}) {
 export function writeE2eLocalCreds(rootDir, projectId, apiKey) {
     if (!projectId)
         return false;
+    if (linkedToVault(rootDir))
+        return false;
     const localPath = join(rootDir, '.env.local');
     if (!existsSync(localPath))
         return false;
@@ -133,23 +166,26 @@ export function writeE2eLocalCreds(rootDir, projectId, apiKey) {
     return true;
 }
 /**
- * Write the org email config into `.env.local` so local sends (`invite:admin`, magic-link,
+ * Write the project's email config into `.env.local` so local sends (`invite:admin`, magic-link,
  * `db:seed`) actually DELIVER instead of falling back to the console. Sets `EMAIL_PROVIDER=resend`
- * + `RESEND_API_KEY` (the org key from the rail — already on the dev's host; global, not per-env)
- * + `EMAIL_FROM` (the fixed org sender). Non-production sends are auto-tagged `[Dev]` by the
- * dispatcher (`src/lib/email/index.ts`), so local delivery is safe AND distinguishable.
+ * + `RESEND_API_KEY` (the PROJECT's own send-only key that provision minted — never the rail's
+ * team key, which only mints) + `EMAIL_FROM` (the sender on the domain that key is limited to).
+ * Non-production sends are auto-tagged `[Dev]` by the dispatcher (`src/lib/email/index.ts`), so
+ * local delivery is safe AND distinguishable.
  *
  * This closes the source-inconsistency bug: `invite-admin --target main` writes to the prod DB
  * but the script always reads email config from `.env.local` — which provision otherwise never
  * populated (it only synced Resend to Vercel), so the invite email silently fell back to console.
  *
- * Returns false (no-op) when the rail key is missing or `.env.local` does not exist yet
- * (`writeEnvLocal` creates it first). Safe on an existing file: `setEnvLine` only touches these
+ * Returns false (no-op) when there is no project key, the repo lives in the vault, or
+ * `.env.local` does not exist yet (`writeEnvLocal` creates it first). Safe on an existing file: `setEnvLine` only touches these
  * three keys, preserving the rest.
  */
 export function writeEmailLocalCreds(rootDir, resendKey, emailFrom) {
     if (!resendKey)
         return false;
+    if (linkedToVault(rootDir))
+        return false;
     const localPath = join(rootDir, '.env.local');
     if (!existsSync(localPath))
         return false;
@@ -179,6 +215,8 @@ export function writeEmailLocalCreds(rootDir, resendKey, emailFrom) {
 export function writeBacklogLocalCreds(rootDir, projectId, apiKey) {
     if (!apiKey || !projectId)
         return false;
+    if (linkedToVault(rootDir))
+        return false;
     const localPath = join(rootDir, '.env.local');
     let body = '';
     if (existsSync(localPath)) {

package/dist/lib/env-wizard.js

@@ -16,6 +16,7 @@ import { join } from 'node:path';
 import { CLIError } from './cli-error.js';
 import { PROVISION_OWNED, setEnvLine } from './env-file.js';
 import PUBLIC_ENV_KEYS from './public-env-keys.json' with { type: 'json' };
+import { VAULT_ENV_DEVELOP, VAULT_ENV_LOCAL, VAULT_ENV_MAIN, VAULT_ROOT_PATH, } from './vault-api.js';
 /**
  * The real conditionals `.env.example` can't express. Keyed by the DEPENDENT var
  * → the driver answer that reveals it. Kept deliberately small — adding a new
@@ -130,7 +131,8 @@ export function questionKind(key, defaultValue) {
  *  - the GATED dependents (email creds, OAuth creds), active or commented.
  * Excludes provision-owned vars and advanced commented vars (rate-limit, VAPID,
  * Upstash, Sentry, NextAuth aliases) that aren't gated — those stay manual +
- * `pnpm env:push`.
+ * `pnpm env:push` (only without a vault: in a repo with a `vault` block they are set in the
+ * vault, and `env:push` does not write).
  */
 export function buildQuestionPlan(entries) {
     const questions = [];
@@ -403,7 +405,13 @@ export function generateVapidKeys() {
  * these same rows, so the agent-facing output obeys the identical rule.
  */
 export function buildEnvReview(questions, body) {
-    const env = parseEnvBody(body);
+    return buildEnvReviewFromEnv(questions, parseEnvBody(body));
+}
+/**
+ * {@link buildEnvReview} over an already-resolved `{ KEY: value }` map — the vault path
+ * (VAULT-002) resolves the `local` environment instead of reading `.env.local`. Same masking rule.
+ */
+export function buildEnvReviewFromEnv(questions, env) {
     return questions.map((q) => {
         const value = env[q.key] ?? '';
         const status = value ? 'set' : 'empty';
@@ -416,3 +424,59 @@ export function buildEnvReview(questions, body) {
         };
     });
 }
+const WIZARD_MAIN = { env: VAULT_ENV_MAIN, path: VAULT_ROOT_PATH };
+const WIZARD_DEVELOP = { env: VAULT_ENV_DEVELOP, path: VAULT_ROOT_PATH };
+const WIZARD_LOCAL = { env: VAULT_ENV_LOCAL, path: VAULT_ROOT_PATH };
+/**
+ * Write `entries` once in `main:/` (with `mode`) and reference each from `develop:/` and `local`.
+ * Returns the key names written. Never prints (the caller narrates, by name).
+ */
+export async function writeSharedToVault(target, entries, mode) {
+    const keys = Object.keys(entries);
+    if (keys.length === 0)
+        return [];
+    await target.client.writeSecrets(target.projectId, WIZARD_MAIN, entries, mode);
+    for (const key of keys) {
+        for (const location of [WIZARD_DEVELOP, WIZARD_LOCAL]) {
+            await target.client.writeReference(target.projectId, location, key, { ...WIZARD_MAIN, key }, 'upsert');
+        }
+    }
+    return keys;
+}
+/**
+ * The vault counterpart of {@link applyWizardAnswers}: the answers go to the vault (one copy in
+ * `main:/`, referenced from `develop:/` and `local`), never to a file. Provision-owned keys are
+ * skipped exactly as on the file path; EMPTY answers are not stored (the vault keeps answered
+ * values) and come back in `empty` so the caller can name them.
+ */
+export async function applyWizardAnswersToVault(target, answers) {
+    const entries = {};
+    const empty = [];
+    for (const [key, value] of Object.entries(answers)) {
+        if (PROVISION_OWNED.has(key))
+            continue; // provision owns these per-env
+        if (value === '') {
+            empty.push(key);
+            continue;
+        }
+        entries[key] = value;
+    }
+    const written = await writeSharedToVault(target, entries, 'upsert');
+    return { written, empty };
+}
+/**
+ * The `local` environment as the app would see it: its own values, the `develop:/ci` import and
+ * the references resolved (own values win over imported ones — ADR-005, check (c)). For the
+ * completeness warnings and the masked review; values never leave this process unmasked.
+ */
+export async function readVaultLocalEnv(target) {
+    const secrets = await target.client.readSecrets(target.projectId, WIZARD_LOCAL, {
+        expandReferences: true,
+        includeImports: true,
+    });
+    return Object.fromEntries(secrets);
+}
+/** Read `main:/` (unexpanded) — e.g. to seed `VAPID_SUBJECT` from `EMAIL_FROM`. */
+export async function readVaultMain(target) {
+    return Object.fromEntries(await target.client.readSecrets(target.projectId, WIZARD_MAIN));
+}

package/dist/lib/initial-migration.js

@@ -3,8 +3,9 @@
  * signal (GAP-001, fixed by `project/planning/decisions/ADR-003-factory-signal.md`).
  *
  * WHY THIS MODULE EXISTS. `factory provision` never ran `db:generate`, so a fresh
- * derivative was born with a schema and no migrations while its `vercel-build`
- * (`pnpm build && pnpm db:migrate`) migrated an empty database on the first deploy.
+ * derivative was born with a schema and no migrations while its deploy migration —
+ * `vercel-build` (`pnpm build && pnpm db:migrate`) on Vercel, the service's pre-deploy command
+ * (`pnpm db:migrate`) on Railway — migrated an empty database on the first deploy.
  * The provision step that closes that gap has to decide, from disk alone, whether
  * generating and committing a `0000` is the right thing to do — and the cost of a
  * wrong "yes" is asymmetric.

package/dist/lib/neon-api.js

@@ -12,7 +12,8 @@
  * Every call surfaces a typed {@link NeonApiError} on a non-2xx response that
  * carries the HTTP status, so the caller (`provision.ts`) can map the Neon edge
  * cases the issue calls out (§8) to actionable, es-MX `CLIError` messages:
- *   - 401  → `NEON_API_KEY` invalid/rotated → re-import the rail (`factory secrets <archivo>`)
+ *   - 401  → `NEON_API_KEY` invalid/rotated → check the vault session, then a rotation
+ *            in `rail-timekast` (`fx-secrets-vault §9`)
  *   - 402 / 429 → quota / billing          → billing message
  *   - 409  → project name already exists    → suggest `--force` or another name
  *
@@ -134,7 +135,7 @@ export async function listNeonOrgs(apiKey, deps = {}) {
  *   3. Neither: a key that sees exactly ONE org uses it; a key that sees several
  *      THROWS, naming them. Fail-closed on purpose — guessing here would create a
  *      client's database in the wrong organization, and there is no prompt to fall
- *      back on (headless Agent Server runs have nobody to answer it).
+ *      back on (headless runs have nobody to answer it).
  *
  * `selector` matches the `org-...` id verbatim, or the name/handle
  * case-insensitively, so both `--neon-org TimeKast` and `--neon-org org-abc123`
@@ -148,7 +149,7 @@ export async function listNeonOrgs(apiKey, deps = {}) {
 export async function resolveNeonOrg(apiKey, selector, deps = {}) {
     const orgs = await listNeonOrgs(apiKey, deps);
     if (orgs.length === 0) {
-        throw new Error('La `NEON_API_KEY` del archivo de secretos no ve ninguna organización de Neon.\n' +
+        throw new Error('La `NEON_API_KEY` del rail no ve ninguna organización de Neon.\n' +
             '  Debe ser la key PERSONAL de la cuenta de servicio, y esa cuenta tiene que ser ' +
             'Admin de la organización (solo un Admin puede acuñar API keys project-scoped).');
     }
@@ -167,8 +168,8 @@ export async function resolveNeonOrg(apiKey, selector, deps = {}) {
         return orgs[0];
     throw new Error(`La key ve ${orgs.length} organizaciones de Neon y no dijiste en cuál crear el proyecto.\n` +
         `  Visibles: ${orgs.map((o) => `${o.name} (${o.id})`).join(', ')}.\n` +
-        '  Elige una con `--neon-org "<nombre>"`, o fija el default del rail con ' +
-        '`NEON_ORG=<nombre>` en `~/.claude/.env`.');
+        '  Elige una con `--neon-org "<nombre>"`, o pide a un admin de la bóveda que fije el ' +
+        'default cargando `NEON_ORG` (el nombre de la organización) en `rail-timekast`.');
 }
 /**
  * The organization that owns a project, asked BY ID — `GET /projects/{id}`.
@@ -482,7 +483,7 @@ export async function createProjectApiKey(apiKey, orgId, projectId, keyName, dep
     // The value can't be reused, so delete the stale key(s) by name and re-mint — a
     // resume must converge, not 409. (Only the secret-pending path re-enters here;
     // the happy path sets apiKeySecretDone and short-circuits before minting again.)
-    if (response.status === 409) {
+    if (response.status === 409 && deps.onConflict !== 'fail') {
         await deleteNeonApiKeysByName(apiKey, orgId, keyName, { fetchImpl });
         response = await mint();
     }
@@ -495,15 +496,147 @@ export async function createProjectApiKey(apiKey, orgId, projectId, keyName, dep
     }
     return data.key;
 }
+/**
+ * The suffix of a ROTATED key name: a compact UTC timestamp `YYYYMMDDHHmmss`. Neon rejects a
+ * repeated `key_name` in the org with `409 already exists`, and a rotation mints the new key while
+ * the old one is still alive — so each rotation gets its own name, `<base>-<suffix>`.
+ */
+export const NEON_ROTATION_SUFFIX_RE = /^\d{14}$/;
+/** `<base>-YYYYMMDDHHmmss` for the rotation minted at `at` (UTC). */
+export function rotatedNeonKeyName(base, at) {
+    return `${base}-${at.toISOString().replace(/\D/g, '').slice(0, 14)}`;
+}
+/**
+ * Whether `name` belongs to the key FAMILY of `base`: the base name itself, or `<base>-<suffix>`
+ * with the rotation suffix EXACTLY ({@link NEON_ROTATION_SUFFIX_RE}). A bare `startsWith` would
+ * catch another project's keys — the base of a project called `foo-e2e-x` is `foo-e2e-x-e2e`,
+ * which starts with `foo-e2e-` — so the rest after the separator must be the timestamp and
+ * nothing else.
+ */
+export function isNeonKeyFamily(name, base) {
+    if (name === base)
+        return true;
+    if (!name.startsWith(`${base}-`))
+        return false;
+    return NEON_ROTATION_SUFFIX_RE.test(name.slice(base.length + 1));
+}
+/**
+ * The CURRENT key of a family — the newest one — which a settle must never revoke. By `createdAt`
+ * when EVERY key of the family carries a parseable one; otherwise by the rotation suffix of the
+ * name (`<base>-YYYYMMDDHHmmss`), where the bare base name counts as the oldest. Ties break by id.
+ * `null` when the family is empty.
+ */
+export function newestNeonFamilyKey(keys, base) {
+    const family = keys.filter((key) => isNeonKeyFamily(key.name, base));
+    if (family.length === 0)
+        return null;
+    const byDate = family.every((key) => key.createdAt && !Number.isNaN(Date.parse(key.createdAt)));
+    const rank = (key) => byDate
+        ? String(Date.parse(key.createdAt)).padStart(16, '0')
+        : key.name === base
+            ? ''
+            : key.name.slice(base.length + 1);
+    return family.reduce((best, key) => {
+        const a = rank(key);
+        const b = rank(best);
+        return a > b || (a === b && key.id > best.id) ? key : best;
+    });
+}
+/**
+ * The org API keys could not be LISTED (non-2xx, network, unexpected body). Distinct from an empty
+ * list on purpose: "I could not list" must never read as "there are none" — a rotation that took
+ * the failure for an empty list would mint a new key and leave the old one alive and unrecorded.
+ */
+export class NeonApiKeyListError extends Error {
+    /** The HTTP status when Neon answered; `null` for a network failure or an unreadable body. */
+    status;
+    constructor(orgId, status, detail) {
+        super(`No pude listar las API keys de la organización de Neon \`${orgId}\` ` +
+            `(${status === null ? detail : `Neon respondió ${status}`}).`);
+        this.name = 'NeonApiKeyListError';
+        this.status = status;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * List the org's API keys WITH their id — `GET /organizations/{org_id}/api_keys`. Read-only. The
+ * `--remint` rotation reads this BEFORE minting, so the keys it will revoke are known by id and
+ * the key it is about to mint (same name) is never among them.
+ *
+ * @returns every key that carries both an id and a name; `[]` when the org has none.
+ * @throws {NeonApiKeyListError} on a non-2xx answer, a network failure or a body of another shape.
+ */
+export async function listNeonApiKeys(apiKey, orgId, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    let response;
+    try {
+        response = await fetchImpl(`${NEON_API_BASE}/organizations/${encodeURIComponent(orgId)}/api_keys`, {
+            method: 'GET',
+            headers: neonHeaders(apiKey),
+            signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
+        });
+    }
+    catch {
+        throw new NeonApiKeyListError(orgId, null, 'sin respuesta de Neon');
+    }
+    if (!response.ok)
+        throw new NeonApiKeyListError(orgId, response.status, '');
+    let data;
+    try {
+        data = await response.json();
+    }
+    catch {
+        throw new NeonApiKeyListError(orgId, null, 'respuesta ilegible');
+    }
+    // Neon returns a bare array; a `{ api_keys: [...] }` wrapper is tolerated too.
+    const list = Array.isArray(data)
+        ? data
+        : data !== null &&
+            typeof data === 'object' &&
+            Array.isArray(data.api_keys)
+            ? data.api_keys
+            : null;
+    if (list === null)
+        throw new NeonApiKeyListError(orgId, null, 'respuesta con otra forma');
+    return list
+        .filter((k) => k !== null && k?.id != null && typeof k?.name === 'string')
+        .map((k) => ({
+        id: String(k.id),
+        name: String(k.name),
+        ...(typeof k.created_at === 'string' ? { createdAt: k.created_at } : {}),
+    }));
+}
+/**
+ * Revoke ONE org API key by id — `DELETE /organizations/{org_id}/api_keys/{id}`. A 404 is "it no
+ * longer existed" and counts as revoked. Never throws: the answer is whether Neon CONFIRMED it, so
+ * a caller keeps an unconfirmed id pending instead of forgetting it.
+ */
+export async function revokeNeonApiKey(apiKey, orgId, keyId, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    try {
+        const response = await fetchImpl(`${NEON_API_BASE}/organizations/${encodeURIComponent(orgId)}/api_keys/${encodeURIComponent(keyId)}`, {
+            method: 'DELETE',
+            headers: neonHeaders(apiKey),
+            signal: AbortSignal.timeout(NEON_API_TIMEOUT_MS),
+        });
+        return response.ok || response.status === 404;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Best-effort delete of every ORG API key whose name matches `keyName`
- * (`GET /organizations/{org_id}/api_keys` → `DELETE .../api_keys/{id}`). Three
+ * (`GET /organizations/{org_id}/api_keys` → `DELETE .../api_keys/{id}`). Two
  * callers:
- *   - the idempotent re-mint (clear a stale key before re-minting on resume),
- *   - `--remint` (revoke the live key before issuing its replacement), and
+ *   - the idempotent re-mint of a NON-rotation run (clear a stale key that was never
+ *     delivered before re-minting on resume — see {@link createProjectApiKey}), and
  *   - the ephemeral `--destroy` nuke (delete the project-scoped key it minted so
  *     the org does not accumulate dead keys across provisions/tests).
  *
+ * `--remint` does NOT use it: a rotation lists ids first ({@link listNeonApiKeys}) and revokes
+ * them by id ({@link revokeNeonApiKey}) only once the new key was delivered.
+ *
  * Org-scoped for the same reason the mint is (see {@link createProjectApiKey}):
  * the keys provision issues are owned by the org, so the personal `/api_keys`
  * listing never saw them — and with a service-account key it 404s outright.
@@ -528,7 +661,9 @@ export async function deleteNeonApiKeysByName(apiKey, orgId, keyName, deps = {})
         // Neon returns a bare array; tolerate a `{ api_keys: [...] }` wrapper too.
         const list = Array.isArray(data) ? data : (data?.api_keys ?? []);
         const ids = list
-            .filter((k) => k?.name === keyName && k?.id != null)
+            .filter((k) => k?.id != null &&
+            typeof k?.name === 'string' &&
+            (deps.family ? isNeonKeyFamily(k.name, keyName) : k.name === keyName))
             .map((k) => String(k.id));
         for (const id of ids) {
             const del = await fetchImpl(`${keysBase}/${encodeURIComponent(id)}`, {

package/dist/lib/package-json.js

@@ -8,7 +8,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { CLIError } from './cli-error.js';
-import { DEV_NEXT_GATE_FILE, DEV_NEXT_SCRIPT_CMD, DEV_NEXT_SCRIPT_NAME, E2E_SETUP_SCRIPT_CMD, E2E_SETUP_SCRIPT_FILE, E2E_SETUP_SCRIPT_NAME, EVIDENCE_VISUAL_SCRIPT_CMD, EVIDENCE_VISUAL_SCRIPT_FILE, EVIDENCE_VISUAL_SCRIPT_NAME, FACTORY_SCRIPTS, GENERATE_REFERENCE_CMD, GENERATE_REFERENCE_GATE_FILE, GENERATE_REFERENCE_NAME, GENERATOR_SCRIPTS, INVITE_ADMIN_SCRIPT_CMD, INVITE_ADMIN_SCRIPT_FILE, INVITE_ADMIN_SCRIPT_NAME, OBSOLETE_SCRIPT_CMDS, VERIFY_QUICK_SCRIPT_CMD, VERIFY_QUICK_SCRIPT_NAME, VERIFY_SCRIPT_CMD, VERIFY_SCRIPT_FILE, VERIFY_SCRIPT_NAME, PORTS_E2E_COMMENT, PORTS_E2E_COMMENT_KEY, PORTS_E2E_KEY, PORTS_KEY, PREFLIGHT_SCRIPT_CMD, PREFLIGHT_SCRIPT_FILE, PREFLIGHT_SCRIPT_NAME, PROFILES, RETIRED_SCRIPT_CMDS, SETUP_E2E_VARS_SCRIPT_CMD, SETUP_E2E_VARS_SCRIPT_FILE, SETUP_E2E_VARS_SCRIPT_NAME, SHIPPED_E2E_PORT, UPDATE_SCRIPT_NAME, VERCEL_BUILD_OBSOLETE_CMDS, VERCEL_BUILD_SCRIPT_CMD, VERCEL_BUILD_SCRIPT_NAME, } from './constants.js';
+import { DEV_NEXT_GATE_FILE, DEV_NEXT_SCRIPT_CMD, DEV_NEXT_SCRIPT_NAME, E2E_SETUP_SCRIPT_CMD, E2E_SETUP_SCRIPT_FILE, E2E_SETUP_SCRIPT_NAME, EVIDENCE_VISUAL_SCRIPT_CMD, EVIDENCE_VISUAL_SCRIPT_FILE, EVIDENCE_VISUAL_SCRIPT_NAME, FACTORY_SCRIPTS, GENERATE_REFERENCE_CMD, GENERATE_REFERENCE_GATE_FILE, GENERATE_REFERENCE_NAME, GENERATOR_SCRIPTS, INVITE_ADMIN_SCRIPT_CMD, INVITE_ADMIN_SCRIPT_FILE, INVITE_ADMIN_SCRIPT_NAME, OBSOLETE_SCRIPT_CMDS, VERIFY_QUICK_SCRIPT_CMD, VERIFY_QUICK_SCRIPT_NAME, VERIFY_SCRIPT_CMD, VERIFY_SCRIPT_FILE, VERIFY_SCRIPT_NAME, PORTS_E2E_COMMENT, PORTS_E2E_COMMENT_KEY, PORTS_E2E_KEY, PORTS_KEY, PREFLIGHT_SCRIPT_CMD, PREFLIGHT_SCRIPT_FILE, PREFLIGHT_SCRIPT_NAME, PROFILES, RETIRED_SCRIPT_CMDS, SETUP_E2E_VARS_SCRIPT_CMD, SETUP_E2E_VARS_SCRIPT_FILE, SETUP_E2E_VARS_SCRIPT_NAME, SHIPPED_E2E_PORT, UPDATE_SCRIPT_NAME, VERCEL_BUILD_OBSOLETE_CMDS, VERCEL_BUILD_SCRIPT_CMD, VERCEL_BUILD_SCRIPT_NAME, WITH_VAULT_SCRIPT_FILE, } from './constants.js';
 /**
  * Auto-detect the profile to install into an existing repo from its
  * `package.json`: a `factoryVersion` field means the repo was born from the
@@ -35,7 +35,7 @@ export function detectProfile(rootDir) {
     }
 }
 /** Detect the indentation used by an existing JSON document (defaults to 2 spaces). */
-function detectIndent(raw) {
+export function detectIndent(raw) {
     const match = raw.match(/^(\s+)"/m);
     if (!match)
         return 2;
@@ -57,6 +57,22 @@ export function parsePackageJson(raw) {
         throw new CLIError('El `package.json` desempacado no es JSON válido; no se puede continuar de forma segura.');
     }
 }
+/**
+ * THE one comparison every heal of a kit-owned script uses (`ensureFactoryScripts`,
+ * `healVercelBuildOrder`, the vault wiring of `wrapper-wiring.ts`): exact match, byte for byte,
+ * against the current command and the registered values the kit shipped. A variant nobody
+ * registered — a flag appended, different spacing, a step chained in front — is `own`: erring
+ * toward "leave it alone" is the safe side of this mistake.
+ */
+export function classifyKitScript(existing, current, shipped) {
+    if (existing === undefined)
+        return 'absent';
+    if (existing === current)
+        return 'current';
+    if (shipped.includes(existing))
+        return 'shipped';
+    return 'own';
+}
 /**
  * Pure core of the script insertion: mutate `pkg.scripts` in place to ensure ALL
  * `factory:*` convenience scripts exist (`update` / `doctor` / `status`), adding
@@ -79,18 +95,19 @@ function ensureFactoryScripts(pkg, extraScripts = {}) {
     for (const [name, cmd] of Object.entries({ ...FACTORY_SCRIPTS, ...extraScripts })) {
         const existing = scripts[name];
         let result;
-        if (existing === undefined) {
+        // The value is a KNOWN-OBSOLETE kit command (e.g. the old `node …mjs` that the .ts
+        // migration retired) → heal it to the current command. A genuinely dev-divergent value
+        // is a `conflict` and is left intact.
+        const kind = classifyKitScript(existing, cmd, OBSOLETE_SCRIPT_CMDS[name] ?? []);
+        if (kind === 'absent') {
             scripts[name] = cmd;
             changed = true;
             result = { action: 'added' };
         }
-        else if (existing === cmd) {
+        else if (kind === 'current') {
             result = { action: 'already-correct' };
         }
-        else if ((OBSOLETE_SCRIPT_CMDS[name] ?? []).includes(existing)) {
-            // The value is a KNOWN-OBSOLETE kit command (e.g. the old `node …mjs` that
-            // the .ts migration retired) — heal it to the current command. A genuinely
-            // dev-divergent value falls through to `conflict` and is left intact.
+        else if (kind === 'shipped') {
             scripts[name] = cmd;
             changed = true;
             result = { action: 'healed' };
@@ -112,7 +129,8 @@ function ensureFactoryScripts(pkg, extraScripts = {}) {
  *
  * - `preflight` — when its sweep script ships (full brain).
  * - `setup:e2e:vars` — publishes the CI E2E auth env vars (Fase 1 of the
- *   `e2e-ci-auth-env` retrofit), when `scripts/tools/setup-e2e.ts` ships (full brain).
+ *   `e2e-ci-auth-env` retrofit), when `scripts/tools/setup-e2e.ts` ships (full brain) AND the
+ *   vault wrapper `scripts/tools/with-vault.mjs` does too — its value runs through it (VAULT-004).
  * - `evidence:visual` — the visual-evidence harness (`fx-visual-evidence`), gated on the
  *   harness itself (`scripts/tools/visual-evidence/`) rather than on the runner: it is what
  *   this alias needs, and a `core` derivative receives neither. Forwards to `test:e2e`, so the
@@ -152,7 +170,10 @@ export function kitLocalScripts(rootDir) {
         scripts[PREFLIGHT_SCRIPT_NAME] = PREFLIGHT_SCRIPT_CMD;
     if (has(INVITE_ADMIN_SCRIPT_FILE))
         scripts[INVITE_ADMIN_SCRIPT_NAME] = INVITE_ADMIN_SCRIPT_CMD;
-    if (has(SETUP_E2E_VARS_SCRIPT_FILE))
+    // Its value runs through the vault wrapper, so it is ALSO gated on the wrapper: without it
+    // the alias is neither inserted nor healed (a script pointing at a missing file is worse than
+    // an old one that still runs).
+    if (has(SETUP_E2E_VARS_SCRIPT_FILE) && has(WITH_VAULT_SCRIPT_FILE))
         scripts[SETUP_E2E_VARS_SCRIPT_NAME] = SETUP_E2E_VARS_SCRIPT_CMD;
     if (has(E2E_SETUP_SCRIPT_FILE))
         scripts[E2E_SETUP_SCRIPT_NAME] = E2E_SETUP_SCRIPT_CMD;
@@ -401,15 +422,15 @@ export function healVercelBuildOrder(pkgPath) {
     const scripts = pkg.scripts;
     if (typeof scripts !== 'object' || scripts === null || Array.isArray(scripts))
         return 'absent';
-    const current = scripts[VERCEL_BUILD_SCRIPT_NAME];
-    if (current === undefined)
-        return 'absent';
-    if (current === VERCEL_BUILD_SCRIPT_CMD)
-        return 'already-correct';
     // Exact match against what the kit actually shipped, byte for byte. A dev who appended a flag
     // — or wrote the same two halves with different spacing — keeps their command through every
     // future update: an unlisted variant erring toward "leave it alone" is the safe side here.
-    if (!VERCEL_BUILD_OBSOLETE_CMDS.includes(current))
+    const kind = classifyKitScript(scripts[VERCEL_BUILD_SCRIPT_NAME], VERCEL_BUILD_SCRIPT_CMD, VERCEL_BUILD_OBSOLETE_CMDS);
+    if (kind === 'absent')
+        return 'absent';
+    if (kind === 'current')
+        return 'already-correct';
+    if (kind === 'own')
         return 'preserved';
     scripts[VERCEL_BUILD_SCRIPT_NAME] = VERCEL_BUILD_SCRIPT_CMD;
     writeFileSync(pkgPath, `${JSON.stringify(pkg, null, indent)}\n`, 'utf8');