@timekast/factory 1.28.1 → 2.0.1

package/dist/lib/vault-api.js

@@ -0,0 +1,1106 @@
+/**
+ * The vault API client (VAULT-001) — the ONLY place where the CLI talks to the REST API of the
+ * org secrets vault (self-hosted Infisical) about a PROJECT's secrets: create/adopt the project of
+ * a repo, its environments, folders and members, read and write secrets per environment + folder,
+ * create imports between folders and write keys that are references to another key.
+ * Contract: `fx-secrets-vault §3/§6/§7`. Layout it writes into: ADR-005.
+ *
+ * CREDENTIAL: the PERSON's session — the token of `infisical user get token --domain=… --plain`,
+ * obtained through the rail's runner seam (`rail.ts`) and kept only in this client's memory.
+ * There is no machine-identity path. The domain comes from the embedded copy of
+ * `.claude/policy/vault.json` (`VAULT_CONFIG`) — NEVER from the repo's file at runtime, which a
+ * pull request could point at another host that would then receive the person's session.
+ *
+ * IDEMPOTENT: every create ADOPTS what already exists (project by slug, environment, folder,
+ * membership, import), so a second full run creates nothing and leaves the same state.
+ *
+ * SECRET SYNCS (SYNC-001, ADR-005 §8): the client also resolves the organization's app connections
+ * (by TYPE — `vercel`, `github` — never by a fixed name) and lists / creates / deletes the syncs of
+ * a project. A create goes through {@link assertSyncAllowed} before any call: the only pairs are
+ * `main:/` → Vercel production, `develop:/` → Vercel preview and `develop:/ci` → GitHub, always with
+ * deletion in the destination ON and first sync "overwrite the destination". Which sync already
+ * exists, and whether it may be adopted, is `provision`'s decision (it knows the destinations).
+ * No sync the client creates has deletion in the destination OFF.
+ *
+ * FAILURES ARE TYPED (`CLIError` subclasses, never a raw 401/403):
+ *   - no session / expired session → `RailNoSessionError` (names `infisical login --domain=…`)
+ *   - `infisical` not installed    → `RailNotInstalledError`
+ *   - live session, no access      → `VaultNoAccessError` (names the project)
+ *   - slug held by a project the session cannot see → `VaultSlugTakenError` (names the slug; never
+ *     invents an alternate one)
+ *   - a write the guard refuses    → `VaultGuardError` (names the key and the destination)
+ *
+ * 🔴 WRITE GUARD — the real protection against a local-only key (`LOCAL_ONLY_KEYS` of
+ * `env-file.ts`) reaching a folder that syncs to a deploy. It runs BEFORE any network call
+ * (session included) and compares NORMALIZED environment + path, and the client then writes to
+ * that same normalized location, so what the guard judged is exactly where the value lands.
+ * It covers the three ways the client puts a key in a folder: a plain write, an import, and a
+ * reference. Residue (declared in ADR-005 and the skill): the dashboard and `infisical secrets
+ * set` do not go through it.
+ *
+ * 🔴 NO-ECHO — errors, logs and exceptions carry key NAMES, never values nor the session token.
+ * No response body is ever quoted (an API error may echo the request body, i.e. the value), no
+ * error carries a `cause`, and the transport's own failures are rebuilt without their message.
+ * This module never writes to stdout/stderr.
+ *
+ * 🔴 FAIL-CLOSED UNDER TESTS — the CLI's Vitest setup (`cli/tests/setup/isolate-home-path.ts`)
+ * installs a marker on `globalThis` (`VAULT_TEST_ISOLATION_KEY`). While it is present, a client
+ * without an injected transport AND session source THROWS on its first network call, before
+ * touching the network or the `infisical` binary. Same pattern as the rail (ADR-006): deliberately
+ * NOT `process.env.VITEST`, which a CLI spawned as a subprocess by a test would inherit and turn
+ * a real run into a refusal — `globalThis` lives only in the Vitest process. The same setup also
+ * points `PATH`/`HOME` at a temp dir, so the real binary and the person's `~/.infisical` config
+ * are out of reach.
+ */
+import { CLIError } from './cli-error.js';
+import { LOCAL_ONLY_KEYS } from './env-file.js';
+import { DEFAULT_RUNNER_OVERRIDE_KEY, RailNoSessionError, RailNotInstalledError, createExecaInfisicalRunner, loginCommand, } from './rail.js';
+import { VAULT_CONFIG } from './vault-config.js';
+// ---------------------------------------------------------------------------
+// Layout constants (ADR-005)
+// ---------------------------------------------------------------------------
+/** Environment of production (syncs to Vercel production). */
+export const VAULT_ENV_MAIN = 'main';
+/** Environment of preview (syncs to Vercel preview). */
+export const VAULT_ENV_DEVELOP = 'develop';
+/** The developer machine's environment — never synced. */
+export const VAULT_ENV_LOCAL = 'local';
+/** The folder of each deploy environment that is NOT the runtime (`develop:/ci` → GitHub). */
+export const VAULT_CI_PATH = '/ci';
+/** The root folder of an environment. */
+export const VAULT_ROOT_PATH = '/';
+/** The three environments of a repo's vault project, in creation order. */
+export const VAULT_LAYOUT_ENVIRONMENTS = [
+    { name: VAULT_ENV_MAIN, slug: VAULT_ENV_MAIN },
+    { name: VAULT_ENV_DEVELOP, slug: VAULT_ENV_DEVELOP },
+    { name: VAULT_ENV_LOCAL, slug: VAULT_ENV_LOCAL },
+];
+/**
+ * Environments Infisical creates by default with a new project. The layout does not use them, so
+ * a project CREATED in this run drops them; an ADOPTED project is never pruned (someone may use
+ * them).
+ */
+export const VAULT_DEFAULT_ENV_SLUGS = ['dev', 'staging', 'prod'];
+/** Role given to the organization admins added to a project (Decision 22). */
+const MEMBER_ROLE_SLUG = 'admin';
+/** Org role that marks an organization admin. */
+const ORG_ADMIN_ROLE = 'admin';
+/** Time budget (ms) per API call and for obtaining the session. */
+export const VAULT_API_TIMEOUT_MS = 30_000;
+/**
+ * Key on `globalThis` where the CLI's Vitest setup installs its isolation marker. Test-only seam:
+ * production code never sets it, and a subprocess does not inherit it. The string is duplicated in
+ * `cli/tests/setup/isolate-home-path.ts` (which must not import `src/`); `vault-api.test.ts` pins
+ * the link.
+ */
+export const VAULT_TEST_ISOLATION_KEY = Symbol.for('@timekast/factory:vault.test-isolation');
+/** The single import the guard allows: `develop:/ci` → `local:/`. */
+const ALLOWED_IMPORT = {
+    from: { env: VAULT_ENV_DEVELOP, path: VAULT_CI_PATH },
+    to: { env: VAULT_ENV_LOCAL, path: VAULT_ROOT_PATH },
+};
+/** Base of the client's own failures. A `CLIError`: the top-level handler prints only the message. */
+export class VaultApiError extends CLIError {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = 'VaultApiError';
+        this.kind = kind;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Live session without access to the project (access is per project). */
+export class VaultNoAccessError extends VaultApiError {
+    project;
+    constructor(project) {
+        super('no-access', `Tu sesión de la bóveda está activa, pero no tienes acceso al proyecto \`${project}\` ` +
+            '— o ese proyecto 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.');
+        this.name = 'VaultNoAccessError';
+        this.project = project;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** The slug belongs to a project the session cannot see. Never answered with an alternate slug. */
+export class VaultSlugTakenError extends VaultApiError {
+    slug;
+    constructor(slug) {
+        super('slug-taken', `Ya existe en la bóveda un proyecto con el slug \`${slug}\` y tu sesión no tiene acceso a él.\n` +
+            'No creo otro con un nombre distinto: pide a un admin de la bóveda que te dé acceso a ese proyecto ' +
+            'y vuelve a correr.');
+        this.name = 'VaultSlugTakenError';
+        this.slug = slug;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** The write guard refused a key/import/reference. Names key + destination, never the value. */
+export class VaultGuardError extends VaultApiError {
+    key;
+    destination;
+    constructor(key, destination, detail) {
+        super('guard', `No escribo \`${key}\` en \`${destination}\`: ${detail}\n` +
+            'Las claves sólo-locales (key de Neon, credenciales del backlog central) nunca van a una carpeta ' +
+            'que se sincroniza a un despliegue (ver fx-secrets-vault §7).');
+        this.name = 'VaultGuardError';
+        this.key = key;
+        this.destination = destination;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Under the CLI's Vitest setup without an injected transport/session: refuses before touching anything. */
+export class VaultSeamMissingError extends VaultApiError {
+    constructor(seam) {
+        super('seam-missing', `vault-api: falta el seam \`${seam}\` bajo Vitest. Un test NUNCA habla con la bóveda real: ` +
+            'pasa `transport` y `session` a createVaultClient (tests/unit/vault-api.test.ts tiene el patrón).');
+        this.name = 'VaultSeamMissingError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+// ---------------------------------------------------------------------------
+// Location normalization + the write guard (pure, no network)
+// ---------------------------------------------------------------------------
+/**
+ * Canonical form of a location: environment trimmed + lowercased; path with every empty/`.`
+ * segment dropped, `\` treated as `/`, segments lowercased, one leading `/`. `..` is refused.
+ * The client both GUARDS and WRITES with this form, so a spelling variant (`/CI`, `ci`, `//`,
+ * `MAIN`) cannot make the guard judge one place while the value lands in another.
+ */
+export function normalizeLocation(location) {
+    const env = location.env.trim().toLowerCase();
+    if (env === '') {
+        throw new VaultApiError('invalid-location', 'Destino inválido en la bóveda: falta el entorno.');
+    }
+    const segments = location.path
+        .split(/[\\/]/)
+        .map((segment) => segment.trim())
+        .filter((segment) => segment !== '' && segment !== '.');
+    if (segments.includes('..')) {
+        throw new VaultApiError('invalid-location', `Destino inválido en la bóveda: la ruta de \`${env}\` no puede subir de carpeta (\`..\`).`);
+    }
+    return { env, path: `/${segments.map((segment) => segment.toLowerCase()).join('/')}` };
+}
+/** `env:/path` — how a destination is named in messages. */
+export function formatLocation(location) {
+    return `${location.env}:${location.path}`;
+}
+function isLocalEnv(location) {
+    return location.env === VAULT_ENV_LOCAL;
+}
+function isCiFolderOf(location, env) {
+    return location.env === env && location.path === VAULT_CI_PATH;
+}
+/**
+ * Where each local-only key MAY be written (ADR-005) — directly OR as a reference: a reference to a
+ * local-only key may only be written where that key could be written itself, because a sync
+ * resolves the reference and ships the value. (`develop:/ci` IS synced — to GitHub Secrets — so a
+ * "synced or not" boolean cannot tell that the Neon key may go there and the backlog key may not.)
+ * A key of `LOCAL_ONLY_KEYS` without an entry here is refused everywhere (fail-closed).
+ *   - Neon key + project id: `develop:/ci` (CI's E2E branches) and `local`.
+ *   - Backlog-central credentials: `local` only.
+ *   - `DATABASE_URL_MAIN`: nowhere — a repo in the vault reads `main`'s `DATABASE_URL` instead.
+ */
+export const LOCAL_ONLY_ALLOWED_DESTINATIONS = {
+    NEON_API_KEY: (location) => isLocalEnv(location) || isCiFolderOf(location, VAULT_ENV_DEVELOP),
+    NEON_PROJECT_ID: (location) => isLocalEnv(location) || isCiFolderOf(location, VAULT_ENV_DEVELOP),
+    BACKLOG_API_KEY: isLocalEnv,
+    BACKLOG_PROJECT_ID: isLocalEnv,
+    DATABASE_URL_MAIN: () => false,
+};
+/** The local-only key a (possibly misspelled) name stands for, or `null`. */
+function localOnlyKeyOf(key) {
+    const canonical = key.trim().toUpperCase();
+    return LOCAL_ONLY_KEYS.has(canonical) ? canonical : null;
+}
+/** Key names referenced by `${…}` expressions in a value (the last dotted segment of each). */
+export function referencedKeys(value) {
+    const keys = [];
+    for (const match of value.matchAll(/\$\{([^}]*)\}/g)) {
+        const segments = (match[1] ?? '').split('.');
+        const last = segments[segments.length - 1]?.trim();
+        if (last)
+            keys.push(last);
+    }
+    return keys;
+}
+/** Whether the local-only key `canonical` may be written at `location` (fail-closed). */
+function localOnlyAllowedAt(canonical, location) {
+    const allowed = LOCAL_ONLY_ALLOWED_DESTINATIONS[canonical];
+    return Boolean(allowed && allowed(location));
+}
+/**
+ * Throws `VaultGuardError` when writing `key` (with `value`) at `location` would put a local-only
+ * key — directly or through a reference — where {@link LOCAL_ONLY_ALLOWED_DESTINATIONS} does not
+ * admit it. The DESTINATION is judged per key, never with a "synced or not" boolean: a reference to
+ * `BACKLOG_API_KEY` in `develop:/ci` is refused (that folder syncs to GitHub), one to `NEON_API_KEY`
+ * there is accepted (the key itself may live there). `location` must be normalized. Never looks at
+ * the value beyond its `${…}` references, and never quotes it.
+ */
+export function assertWriteAllowed(key, value, location) {
+    const destination = formatLocation(location);
+    const localOnly = localOnlyKeyOf(key);
+    if (localOnly !== null && !localOnlyAllowedAt(localOnly, location)) {
+        throw new VaultGuardError(key, destination, 'es una clave sólo-local y ese destino no la admite.');
+    }
+    for (const referenced of referencedKeys(value)) {
+        const referencedLocalOnly = localOnlyKeyOf(referenced);
+        if (referencedLocalOnly !== null && !localOnlyAllowedAt(referencedLocalOnly, location)) {
+            throw new VaultGuardError(key, destination, `es una referencia a \`${referenced}\`, clave sólo-local que ese destino no admite.`);
+        }
+    }
+}
+/** Throws `VaultGuardError` for any import other than `develop:/ci` → `local:/` (allowlist). */
+export function assertImportAllowed(from, to) {
+    const allowed = from.env === ALLOWED_IMPORT.from.env &&
+        from.path === ALLOWED_IMPORT.from.path &&
+        to.env === ALLOWED_IMPORT.to.env &&
+        to.path === ALLOWED_IMPORT.to.path;
+    if (!allowed) {
+        throw new VaultGuardError(`import de ${formatLocation(from)}`, formatLocation(to), `el único import permitido es ${formatLocation(ALLOWED_IMPORT.from)} → ${formatLocation(ALLOWED_IMPORT.to)}.`);
+    }
+}
+/**
+ * `syncOptions.initialSyncBehavior` of every repo sync (field and value from the instance's
+ * OpenAPI of `POST /api/v1/secret-syncs/{vercel|github}`): the destination was checked EMPTY
+ * before the sync is created, so the vault overwrites it. A destination with foreign keys never
+ * gets here — it stops and points at the adoption (`factory vault adopt`).
+ */
+export const VAULT_SYNC_INITIAL_BEHAVIOR = 'overwrite-destination';
+/**
+ * `syncOptions.disableSecretDeletion` of every sync the client creates: `false` — the sync DELETES
+ * in the destination what is deleted in the vault (ADR-005 §4: the vault is the only writer of its
+ * destination).
+ */
+export const VAULT_SYNC_DISABLE_DELETION = false;
+/**
+ * The ONLY sources a Railway sync may have: the root of a deploy environment — `main:/` or
+ * `develop:/` ("cada entorno a su igual en Railway", `fx-secrets-vault §7`). Never `local`, never a
+ * `/ci` folder (the project's Neon key lives in `develop:/ci`, and a deploy must not receive it).
+ */
+export const VAULT_RAILWAY_SYNC_SOURCES = [
+    { env: VAULT_ENV_MAIN, path: VAULT_ROOT_PATH },
+    { env: VAULT_ENV_DEVELOP, path: VAULT_ROOT_PATH },
+];
+/** Throws `VaultGuardError` unless `source` (normalized) is one of {@link VAULT_RAILWAY_SYNC_SOURCES}. */
+export function assertRailwaySyncAllowed(source) {
+    const allowed = VAULT_RAILWAY_SYNC_SOURCES.some((pair) => pair.env === source.env && pair.path === source.path);
+    if (!allowed) {
+        throw new VaultGuardError(`sync de ${formatLocation(source)}`, 'Railway', 'un sync a Railway sólo sale de main:/ o de develop:/.');
+    }
+}
+/**
+ * The ONLY source → destination pairs a repo sync may have (ADR-005 §1): `main:/` → Vercel
+ * production, `develop:/` → Vercel preview, `develop:/ci` → GitHub. Everything else — a sync from
+ * `local`, from `/ci` to Vercel, from `/` to GitHub, from `main:/ci` — is refused before any call.
+ */
+export const VAULT_SYNC_ALLOWED = [
+    {
+        destination: 'vercel',
+        source: { env: VAULT_ENV_MAIN, path: VAULT_ROOT_PATH },
+        vercelTarget: 'production',
+    },
+    {
+        destination: 'vercel',
+        source: { env: VAULT_ENV_DEVELOP, path: VAULT_ROOT_PATH },
+        vercelTarget: 'preview',
+    },
+    { destination: 'github', source: { env: VAULT_ENV_DEVELOP, path: VAULT_CI_PATH } },
+];
+/**
+ * Throws `VaultGuardError` when `spec` pairs a source and a destination that ADR-005 does not
+ * allow (see {@link VAULT_SYNC_ALLOWED}). `source` must be normalized. The local-only keys of
+ * `develop:/ci` (the Neon key) reach GitHub by design; what this guard stops is that folder — or
+ * `local` — ever reaching Vercel.
+ */
+export function assertSyncAllowed(spec, source) {
+    const target = spec.destination === 'vercel' ? spec.vercel.target : undefined;
+    const allowed = VAULT_SYNC_ALLOWED.some((pair) => pair.destination === spec.destination &&
+        pair.source.env === source.env &&
+        pair.source.path === source.path &&
+        pair.vercelTarget === target);
+    if (!allowed) {
+        const destination = spec.destination === 'vercel' ? `Vercel ${target ?? ''}`.trim() : 'GitHub';
+        throw new VaultGuardError(`sync de ${formatLocation(source)}`, destination, 'los únicos syncs permitidos son main:/ → Vercel production, develop:/ → Vercel preview y ' +
+            'develop:/ci → GitHub.');
+    }
+}
+/**
+ * The `${…}` expression that references `target` from `from` (both normalized): `${KEY}` in the
+ * same folder, `${env.KEY}` at another root, `${env.folder.KEY}` inside a folder.
+ */
+export function referenceExpression(from, target) {
+    if (from.env === target.env && from.path === target.path)
+        return `\${${target.key}}`;
+    const folders = target.path === VAULT_ROOT_PATH ? [] : target.path.slice(1).split('/');
+    return `\${${[target.env, ...folders, target.key].join('.')}}`;
+}
+// ---------------------------------------------------------------------------
+// Real seams
+// ---------------------------------------------------------------------------
+/** The real transport: `fetch` with a timeout. Its failures are rebuilt without their message. */
+export function createFetchVaultTransport(timeoutMs = VAULT_API_TIMEOUT_MS) {
+    return async ({ method, url, token, body }) => {
+        const host = new URL(url).origin;
+        const headers = {
+            Authorization: `Bearer ${token}`,
+            Accept: 'application/json',
+        };
+        if (body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        let response;
+        try {
+            response = await fetch(url, {
+                method,
+                headers,
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (error) {
+            const name = error?.name;
+            if (name === 'TimeoutError' || name === 'AbortError') {
+                throw new VaultApiError('timeout', `La bóveda (${host}) no respondió en ${Math.round(timeoutMs / 1000)} s. Revisa tu conexión.`);
+            }
+            throw new VaultApiError('unrecognized', `No pude conectar con la bóveda (${host}). Revisa tu conexión.`);
+        }
+        let text = '';
+        try {
+            text = await response.text();
+        }
+        catch {
+            text = '';
+        }
+        let parsed = null;
+        if (text !== '') {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = null;
+            }
+        }
+        return { status: response.status, body: parsed };
+    };
+}
+/** The rail's default runner (the Vitest refusing one when installed), else the real execa one. */
+function resolveDefaultRunner() {
+    const override = globalThis[DEFAULT_RUNNER_OVERRIDE_KEY];
+    return typeof override === 'function'
+        ? override
+        : createExecaInfisicalRunner();
+}
+/**
+ * The person's session token (`infisical user get token --plain`). Decided by the EXIT CODE only
+ * (`fx-secrets-vault §3`): without a session infisical prints its login notice on stdout and exits
+ * non-zero, so reading the output would call a dead session alive.
+ */
+async function obtainSessionToken(runner, config, timeoutMs) {
+    let result;
+    try {
+        result = await runner(['user', 'get', 'token', `--domain=${config.domain}`, '--plain'], {
+            timeoutMs,
+            domain: config.domain,
+        });
+    }
+    catch {
+        throw new VaultApiError('unrecognized', `No pude obtener tu sesión de la bóveda. Revisa \`${loginCommand(config)}\`.`);
+    }
+    if (result.notFound)
+        throw new RailNotInstalledError(config);
+    if (result.timedOut) {
+        throw new VaultApiError('timeout', `\`infisical\` no respondió en ${Math.round(timeoutMs / 1000)} s al pedir tu sesión. ` +
+            `Si caducó, entra de nuevo con \`${loginCommand(config)}\`.`);
+    }
+    if (result.exitCode !== 0)
+        throw new RailNoSessionError(config);
+    const token = result.stdout.trim();
+    if (token === '' || /\s/.test(token)) {
+        throw new VaultApiError('unrecognized', 'La bóveda devolvió una sesión que no reconozco. Actualiza `infisical` (`brew upgrade infisical`) ' +
+            `y entra con \`${loginCommand(config)}\`.`);
+    }
+    return token;
+}
+function asObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function asString(value) {
+    return typeof value === 'string' ? value : null;
+}
+/** Build a client. Its session token is cached in memory and dies with the client. */
+export function createVaultClient(deps = {}) {
+    const config = deps.config ?? VAULT_CONFIG;
+    const timeoutMs = deps.timeoutMs ?? VAULT_API_TIMEOUT_MS;
+    const projectLabels = new Map();
+    let sessionToken;
+    function labelOf(projectId) {
+        return projectLabels.get(projectId) ?? projectId;
+    }
+    function assertSeams() {
+        if (globalThis[VAULT_TEST_ISOLATION_KEY] === undefined)
+            return;
+        if (!deps.transport)
+            throw new VaultSeamMissingError('transport');
+        if (!deps.session && !deps.runner)
+            throw new VaultSeamMissingError('session');
+    }
+    function token() {
+        if (!sessionToken) {
+            const source = deps.session ??
+                (() => obtainSessionToken(deps.runner ?? resolveDefaultRunner(), config, timeoutMs));
+            sessionToken = source().catch((error) => {
+                sessionToken = undefined;
+                throw error instanceof CLIError
+                    ? error
+                    : new VaultApiError('unrecognized', 'No pude obtener tu sesión de la bóveda.');
+            });
+        }
+        return sessionToken;
+    }
+    /**
+     * One API call. 401 → no session; 403 → no access. Other statuses go back to the caller, which
+     * decides (404 on a delete = already gone). The response body is NEVER quoted in an error.
+     */
+    async function call(operation, method, pathname, options = {}) {
+        assertSeams();
+        const transport = deps.transport ?? createFetchVaultTransport(timeoutMs);
+        const bearer = await token();
+        const url = new URL(pathname, config.domain);
+        for (const [name, value] of Object.entries(options.query ?? {}))
+            url.searchParams.set(name, value);
+        let response;
+        try {
+            response = await transport({
+                method,
+                url: url.toString(),
+                token: bearer,
+                ...(options.body === undefined ? {} : { body: options.body }),
+            });
+        }
+        catch (error) {
+            if (error instanceof VaultApiError)
+                throw error;
+            throw new VaultApiError('unrecognized', `La llamada a la bóveda falló al ${operation}.`);
+        }
+        if (response.status === 401)
+            throw new RailNoSessionError(config);
+        if (response.status === 403) {
+            throw new VaultNoAccessError(options.projectId ? labelOf(options.projectId) : operation);
+        }
+        return response;
+    }
+    function unexpected(operation, status) {
+        return new VaultApiError('unrecognized', `La bóveda respondió ${status} al ${operation}. No lo reconozco; si persiste, repórtalo al equipo del Factory.`);
+    }
+    function ok(response, operation) {
+        if (response.status < 200 || response.status >= 300)
+            throw unexpected(operation, response.status);
+        return response.body;
+    }
+    function parseProject(raw, operation) {
+        const object = asObject(raw);
+        const id = asString(object?.id) ?? asString(object?._id);
+        const slug = asString(object?.slug);
+        if (!object || !id || !slug) {
+            throw new VaultApiError('unrecognized', `Respuesta inesperada de la bóveda al ${operation}.`);
+        }
+        const environments = asArray(object.environments).flatMap((entry) => {
+            const env = asObject(entry);
+            const envSlug = asString(env?.slug);
+            if (!env || !envSlug)
+                return [];
+            return [{ id: asString(env.id) ?? '', name: asString(env.name) ?? envSlug, slug: envSlug }];
+        });
+        const project = {
+            id,
+            name: asString(object.name) ?? slug,
+            slug,
+            orgId: asString(object.orgId) ?? '',
+            environments,
+            hasDeleteProtection: typeof object.hasDeleteProtection === 'boolean' ? object.hasDeleteProtection : null,
+        };
+        projectLabels.set(id, slug);
+        return project;
+    }
+    // -- identity (MDEP-001) --------------------------------------------------
+    async function whoAmI() {
+        const operation = 'leer tu usuario de la bóveda';
+        const noPerson = new VaultApiError('no-person', 'El token de la bóveda no corresponde a una persona: este comando sólo corre con tu sesión. ' +
+            `Entra con \`${loginCommand(config)}\` y vuelve a correr. No se escribió nada.`);
+        let response;
+        try {
+            response = await call(operation, 'GET', '/api/v1/user');
+        }
+        catch (error) {
+            // 403 — the instance knows the token but not as a user.
+            if (error instanceof VaultNoAccessError)
+                throw noPerson;
+            throw error;
+        }
+        if (response.status < 200 || response.status >= 300)
+            throw noPerson;
+        const identity = identityOf(asObject(response.body)?.user);
+        if (!identity)
+            throw noPerson;
+        return { identity };
+    }
+    // -- projects ------------------------------------------------------------
+    async function findProjectBySlug(slug) {
+        const operation = 'listar tus proyectos';
+        const body = asObject(ok(await call(operation, 'GET', '/api/v1/workspace'), operation));
+        for (const entry of asArray(body?.workspaces)) {
+            if (asString(asObject(entry)?.slug) === slug)
+                return parseProject(entry, operation);
+        }
+        return null;
+    }
+    async function getProject(projectId) {
+        const operation = `leer el proyecto \`${labelOf(projectId)}\``;
+        const response = await call(operation, 'GET', `/api/v1/workspace/${encodeURIComponent(projectId)}`, {
+            projectId,
+        });
+        if (response.status === 404)
+            throw new VaultNoAccessError(labelOf(projectId));
+        return parseProject(asObject(ok(response, operation))?.workspace, operation);
+    }
+    async function ensureProject(spec) {
+        const existing = await findProjectBySlug(spec.slug);
+        if (existing && spec.mustCreate) {
+            // The caller planned a creation: a project that appeared meanwhile is someone's — never adopted.
+            throw new VaultApiError('project-exists', `El proyecto \`${spec.slug}\` ya existe en la bóveda y esta corrida iba a crearlo: no lo adopto ` +
+                '(no escribí nada en él).');
+        }
+        if (existing)
+            return { project: existing, created: false };
+        const operation = `crear el proyecto \`${spec.slug}\``;
+        // Born protected, in the SAME request (ADOPT-006): a PATCH afterwards could fail and leave a
+        // brand-new project deletable.
+        const response = await call(operation, 'POST', '/api/v2/workspace', {
+            body: { projectName: spec.name, slug: spec.slug, hasDeleteProtection: true },
+        });
+        if (response.status === 409)
+            throw new VaultSlugTakenError(spec.slug);
+        if (response.status === 400 || response.status === 422) {
+            // Only a duplicate-slug answer becomes slug-taken; the message is tested, never quoted.
+            const message = asString(asObject(response.body)?.message) ?? '';
+            if (/slug|already exists|duplicate|conflict/i.test(message))
+                throw new VaultSlugTakenError(spec.slug);
+            throw unexpected(operation, response.status);
+        }
+        const project = parseProject(asObject(ok(response, operation))?.project, operation);
+        return { project, created: true };
+    }
+    /** The `PATCH /api/v1/workspace/{id}` of the protection. A failure names the project + cause. */
+    async function patchDeleteProtection(projectId, operation, body) {
+        const label = labelOf(projectId);
+        let response;
+        try {
+            response = await call(operation, 'PATCH', `/api/v1/workspace/${encodeURIComponent(projectId)}`, {
+                body,
+                projectId,
+            });
+        }
+        catch (error) {
+            // A dead session and a missing test seam keep their own typed error.
+            if (error instanceof RailNoSessionError || error instanceof VaultSeamMissingError)
+                throw error;
+            const cause = error instanceof Error ? error.message : 'error desconocido';
+            throw new VaultApiError('delete-protection', `No pude ${operation} (proyecto \`${label}\`): ${cause}`);
+        }
+        if (response.status === 404) {
+            throw new VaultApiError('delete-protection', `No pude ${operation} (proyecto \`${label}\`): la bóveda ya no lo encuentra (404).`);
+        }
+        if (response.status < 200 || response.status >= 300) {
+            throw new VaultApiError('delete-protection', `No pude ${operation} (proyecto \`${label}\`): la bóveda respondió ${response.status}.`);
+        }
+    }
+    async function ensureDeleteProtection(projectId) {
+        // Read BY ID: the listing never carries the field. Only a `true` read is "already on"; an
+        // unknown answer is turned on like an OFF one (the PATCH is idempotent on the instance).
+        const current = await getProject(projectId);
+        if (current.hasDeleteProtection === true) {
+            return { deleteProtection: 'already-on', slug: current.slug };
+        }
+        await patchDeleteProtection(projectId, 'encender la protección contra borrado', {
+            hasDeleteProtection: true,
+        });
+        return { deleteProtection: 'enabled-now', slug: current.slug };
+    }
+    async function disableDeleteProtection(projectId) {
+        await patchDeleteProtection(projectId, 'apagar la protección contra borrado', {
+            hasDeleteProtection: false,
+        });
+    }
+    async function deleteProject(projectId) {
+        const operation = `borrar el proyecto \`${labelOf(projectId)}\``;
+        const response = await call(operation, 'DELETE', `/api/v1/workspace/${encodeURIComponent(projectId)}`, {
+            projectId,
+        });
+        if (response.status === 404)
+            return { deleted: false };
+        ok(response, operation);
+        return { deleted: true };
+    }
+    // -- environments --------------------------------------------------------
+    async function ensureEnvironments(projectId, environments) {
+        const project = await getProject(projectId);
+        const existing = new Set(project.environments.map((env) => env.slug));
+        const created = [];
+        const unchanged = [];
+        for (const env of environments) {
+            const slug = env.slug.trim().toLowerCase();
+            if (existing.has(slug)) {
+                unchanged.push(slug);
+                continue;
+            }
+            const operation = `crear el entorno \`${slug}\` en \`${labelOf(projectId)}\``;
+            ok(await call(operation, 'POST', `/api/v1/workspace/${encodeURIComponent(projectId)}/environments`, {
+                body: { name: env.name, slug },
+                projectId,
+            }), operation);
+            existing.add(slug);
+            created.push(slug);
+        }
+        return { created, unchanged };
+    }
+    async function deleteEnvironment(projectId, slug) {
+        const project = await getProject(projectId);
+        const target = project.environments.find((env) => env.slug === slug.trim().toLowerCase());
+        if (!target)
+            return { deleted: false };
+        const operation = `borrar el entorno \`${target.slug}\` de \`${labelOf(projectId)}\``;
+        const response = await call(operation, 'DELETE', `/api/v1/workspace/${encodeURIComponent(projectId)}/environments/${encodeURIComponent(target.id)}`, { projectId });
+        if (response.status === 404)
+            return { deleted: false };
+        ok(response, operation);
+        return { deleted: true };
+    }
+    // -- folders -------------------------------------------------------------
+    function splitFolder(location) {
+        const segments = location.path.slice(1).split('/');
+        const name = segments.pop() ?? '';
+        if (name === '') {
+            throw new VaultApiError('invalid-location', 'La raíz de un entorno no es una carpeta que se cree o borre.');
+        }
+        return { parent: `/${segments.join('/')}`, name };
+    }
+    async function listFolders(projectId, env, parent) {
+        const operation = `listar las carpetas de \`${env}:${parent}\``;
+        const body = asObject(ok(await call(operation, 'GET', '/api/v1/folders', {
+            query: { workspaceId: projectId, environment: env, path: parent },
+            projectId,
+        }), operation));
+        return asArray(body?.folders).flatMap((entry) => {
+            const folder = asObject(entry);
+            const name = asString(folder?.name);
+            return name ? [{ id: asString(folder?.id) ?? name, name }] : [];
+        });
+    }
+    async function ensureFolder(projectId, rawLocation) {
+        const location = normalizeLocation(rawLocation);
+        const { parent, name } = splitFolder(location);
+        const folders = await listFolders(projectId, location.env, parent);
+        if (folders.some((folder) => folder.name.toLowerCase() === name))
+            return { created: false };
+        const operation = `crear la carpeta \`${formatLocation(location)}\``;
+        ok(await call(operation, 'POST', '/api/v1/folders', {
+            body: { workspaceId: projectId, environment: location.env, name, path: parent },
+            projectId,
+        }), operation);
+        return { created: true };
+    }
+    async function deleteFolder(projectId, rawLocation) {
+        const location = normalizeLocation(rawLocation);
+        const { parent, name } = splitFolder(location);
+        const folder = (await listFolders(projectId, location.env, parent)).find((entry) => entry.name.toLowerCase() === name);
+        if (!folder)
+            return { deleted: false };
+        const operation = `borrar la carpeta \`${formatLocation(location)}\``;
+        const response = await call(operation, 'DELETE', `/api/v1/folders/${encodeURIComponent(folder.id)}`, {
+            body: { workspaceId: projectId, environment: location.env, path: parent },
+            projectId,
+        });
+        if (response.status === 404)
+            return { deleted: false };
+        ok(response, operation);
+        return { deleted: true };
+    }
+    // -- members (Decision 22) -----------------------------------------------
+    function identityOf(raw) {
+        const user = asObject(raw);
+        const identity = asString(user?.username) ?? asString(user?.email);
+        return identity ? identity.toLowerCase() : null;
+    }
+    async function ensureMembers(projectId) {
+        const project = await getProject(projectId);
+        const label = labelOf(projectId);
+        const selfOperation = 'leer tu usuario de la bóveda';
+        const self = identityOf(asObject(ok(await call(selfOperation, 'GET', '/api/v1/user'), selfOperation))?.user);
+        const adminsOperation = 'consultar los admins de la organización';
+        const orgBody = asObject(ok(await call(adminsOperation, 'GET', `/api/v2/organizations/${encodeURIComponent(project.orgId)}/memberships`), adminsOperation));
+        const admins = asArray(orgBody?.users).flatMap((entry) => {
+            const membership = asObject(entry);
+            if (asString(membership?.role) !== ORG_ADMIN_ROLE)
+                return [];
+            const status = asString(membership?.status);
+            if (status !== null && status !== 'accepted')
+                return [];
+            const identity = identityOf(membership?.user);
+            return identity ? [identity] : [];
+        });
+        const membersOperation = `leer los miembros de \`${label}\``;
+        const membersBody = asObject(ok(await call(membersOperation, 'GET', `/api/v1/workspace/${encodeURIComponent(projectId)}/memberships`, { projectId }), membersOperation));
+        const current = new Set(asArray(membersBody?.memberships).flatMap((entry) => {
+            const identity = identityOf(asObject(entry)?.user);
+            return identity ? [identity] : [];
+        }));
+        const desired = [...new Set([...(self ? [self] : []), ...admins])];
+        const missing = desired.filter((identity) => !current.has(identity));
+        const unchanged = desired.filter((identity) => current.has(identity));
+        if (missing.length > 0) {
+            const addOperation = `agregar miembros a \`${label}\``;
+            ok(await call(addOperation, 'POST', `/api/v2/workspace/${encodeURIComponent(projectId)}/memberships`, {
+                body: { usernames: missing, roleSlugs: [MEMBER_ROLE_SLUG] },
+                projectId,
+            }), addOperation);
+        }
+        return { added: missing, unchanged };
+    }
+    // -- secrets -------------------------------------------------------------
+    function secretEntries(raw) {
+        return asArray(raw).flatMap((entry) => {
+            const secret = asObject(entry);
+            const key = asString(secret?.secretKey);
+            const value = asString(secret?.secretValue);
+            return key !== null && value !== null ? [[key, value]] : [];
+        });
+    }
+    async function readSecrets(projectId, rawLocation, options = {}) {
+        const location = normalizeLocation(rawLocation);
+        const operation = `leer los secretos de \`${formatLocation(location)}\``;
+        const body = asObject(ok(await call(operation, 'GET', '/api/v3/secrets/raw', {
+            query: {
+                workspaceId: projectId,
+                environment: location.env,
+                secretPath: location.path,
+                expandSecretReferences: String(options.expandReferences === true),
+                include_imports: String(options.includeImports === true),
+            },
+            projectId,
+        }), operation));
+        // Own values first: they win over an imported key of the same name (ADR-005, check (c)).
+        const secrets = new Map(secretEntries(body?.secrets));
+        if (options.includeImports === true) {
+            for (const imported of asArray(body?.imports)) {
+                for (const [key, value] of secretEntries(asObject(imported)?.secrets)) {
+                    if (!secrets.has(key))
+                        secrets.set(key, value);
+                }
+            }
+        }
+        return secrets;
+    }
+    async function writeNormalized(projectId, location, entries, mode) {
+        const existing = await readSecrets(projectId, location);
+        const result = { created: [], updated: [], unchanged: [] };
+        for (const [key, value] of entries) {
+            const current = existing.get(key);
+            if (current !== undefined && (mode === 'create-if-missing' || current === value)) {
+                result.unchanged.push(key);
+                continue;
+            }
+            const method = current === undefined ? 'POST' : 'PATCH';
+            const operation = `escribir \`${key}\` en \`${formatLocation(location)}\``;
+            ok(await call(operation, method, `/api/v3/secrets/raw/${encodeURIComponent(key)}`, {
+                body: {
+                    workspaceId: projectId,
+                    environment: location.env,
+                    secretPath: location.path,
+                    secretValue: value,
+                    type: 'shared',
+                },
+                projectId,
+            }), operation);
+            (current === undefined ? result.created : result.updated).push(key);
+        }
+        return result;
+    }
+    async function writeSecrets(projectId, rawLocation, entries, mode) {
+        const location = normalizeLocation(rawLocation);
+        const list = Object.entries(entries).map(([key, value]) => [key.trim(), value]);
+        // The guard judges EVERY key before the first network call: a refused batch writes nothing.
+        for (const [key, value] of list)
+            assertWriteAllowed(key, value, location);
+        return writeNormalized(projectId, location, list, mode);
+    }
+    async function writeReference(projectId, rawLocation, key, rawTarget, mode) {
+        const location = normalizeLocation(rawLocation);
+        const targetLocation = normalizeLocation(rawTarget);
+        const target = { ...targetLocation, key: rawTarget.key.trim() };
+        const expression = referenceExpression(location, target);
+        const name = key.trim();
+        assertWriteAllowed(name, expression, location);
+        // A reference to a key that does not exist would sync a literal or an empty value.
+        const targetSecrets = await readSecrets(projectId, targetLocation);
+        if (!targetSecrets.has(target.key)) {
+            throw new VaultApiError('reference-target-missing', `No escribo \`${name}\` en \`${formatLocation(location)}\` como referencia: la clave \`${target.key}\` ` +
+                `no existe en \`${formatLocation(targetLocation)}\`. Escríbela primero.`);
+        }
+        return writeNormalized(projectId, location, [[name, expression]], mode);
+    }
+    // -- imports -------------------------------------------------------------
+    async function ensureImport(projectId, rawFrom, rawTo) {
+        const from = normalizeLocation(rawFrom);
+        const to = normalizeLocation(rawTo);
+        assertImportAllowed(from, to);
+        const listOperation = `leer los imports de \`${formatLocation(to)}\``;
+        const body = asObject(ok(await call(listOperation, 'GET', '/api/v1/secret-imports', {
+            query: { workspaceId: projectId, environment: to.env, path: to.path },
+            projectId,
+        }), listOperation));
+        const exists = asArray(body?.secretImports).some((entry) => {
+            const imported = asObject(entry);
+            const env = asString(asObject(imported?.importEnv)?.slug);
+            const path = asString(imported?.importPath);
+            return (env !== null &&
+                path !== null &&
+                normalizeLocation({ env, path }).path === from.path &&
+                env === from.env);
+        });
+        if (exists)
+            return { created: false };
+        const operation = `importar \`${formatLocation(from)}\` en \`${formatLocation(to)}\``;
+        ok(await call(operation, 'POST', '/api/v1/secret-imports', {
+            body: {
+                workspaceId: projectId,
+                environment: to.env,
+                path: to.path,
+                import: { environment: from.env, path: from.path },
+            },
+            projectId,
+        }), operation);
+        return { created: true };
+    }
+    // -- the full layout -----------------------------------------------------
+    async function ensureProjectLayout(spec) {
+        const { project, created: projectCreated } = await ensureProject(spec);
+        // A new project was born protected in its POST; a pre-existing one is read by id and turned on
+        // only when it is not (zero writes when it already is).
+        const deleteProtection = projectCreated
+            ? 'enabled-now'
+            : (await ensureDeleteProtection(project.id)).deleteProtection;
+        const pruned = [];
+        if (projectCreated) {
+            const keep = new Set(VAULT_LAYOUT_ENVIRONMENTS.map((env) => env.slug));
+            for (const env of project.environments) {
+                if (VAULT_DEFAULT_ENV_SLUGS.includes(env.slug) && !keep.has(env.slug)) {
+                    if ((await deleteEnvironment(project.id, env.slug)).deleted)
+                        pruned.push(env.slug);
+                }
+            }
+        }
+        const environments = await ensureEnvironments(project.id, VAULT_LAYOUT_ENVIRONMENTS);
+        const folders = { created: [], unchanged: [] };
+        for (const env of [VAULT_ENV_MAIN, VAULT_ENV_DEVELOP]) {
+            const location = { env, path: VAULT_CI_PATH };
+            const { created } = await ensureFolder(project.id, location);
+            (created ? folders.created : folders.unchanged).push(formatLocation(location));
+        }
+        let members;
+        try {
+            members = await ensureMembers(project.id);
+        }
+        catch (error) {
+            if (error instanceof RailNoSessionError)
+                throw error;
+            throw new VaultApiError('members-incomplete', `El proyecto \`${project.slug}\` existe, pero no pude completar sus miembros (quien lo crea + los admins ` +
+                'de la organización): puede haber quedado sólo contigo, e invisible para los demás. ' +
+                'Vuelve a correr el alta: adopta lo que ya existe y agrega a los que falten.');
+        }
+        const { created: importCreated } = await ensureImport(project.id, ALLOWED_IMPORT.from, ALLOWED_IMPORT.to);
+        return {
+            project: await getProject(project.id),
+            projectCreated,
+            environments: { ...environments, pruned },
+            folders,
+            members,
+            importCreated,
+            deleteProtection,
+        };
+    }
+    // -- secret syncs (SYNC-001) ----------------------------------------------
+    async function listSecretKeys(projectId, location) {
+        return [...(await readSecrets(projectId, location)).keys()];
+    }
+    /** `vercel` / `github` only — the destinations a repo syncs to — so nothing else reaches a URL. */
+    function assertDestination(destination) {
+        if (destination !== 'vercel' && destination !== 'github') {
+            throw new VaultApiError('unrecognized', `Destino de sync desconocido: \`${destination}\` (sólo vercel y github).`);
+        }
+    }
+    async function findAppConnection(app) {
+        // A closed list, so nothing else reaches the URL.
+        if (app !== 'railway')
+            assertDestination(app);
+        const operation = `consultar la conexión de la organización con ${app}`;
+        const body = asObject(ok(await call(operation, 'GET', `/api/v1/app-connections/${app}`), operation));
+        const connections = asArray(body?.appConnections).flatMap((entry) => {
+            const connection = asObject(entry);
+            const id = asString(connection?.id);
+            const connectionApp = asString(connection?.app);
+            if (!connection || !id || connectionApp !== app)
+                return [];
+            // A connection scoped to ONE vault project (a client with infrastructure of its own)
+            // is not the organization's: the instance lets only that project use it. It never
+            // counts toward — or breaks — the choice of the org-wide connection.
+            if (asString(connection.projectId))
+                return [];
+            return [
+                {
+                    id,
+                    name: asString(connection.name) ?? id,
+                    app: connectionApp,
+                    method: asString(connection.method),
+                },
+            ];
+        });
+        if (connections.length > 1) {
+            throw new VaultApiError('app-connection-ambiguous', `La organización tiene ${connections.length} conexiones con ${app} ` +
+                `(${connections.map((c) => `\`${c.name}\``).join(', ')}) y no elijo una a ciegas. ` +
+                'Pide a un admin de la bóveda que deje una sola de ese tipo en la organización y vuelve a correr.');
+        }
+        return connections[0] ?? null;
+    }
+    function parseSync(raw, operation) {
+        const sync = asObject(raw);
+        const id = asString(sync?.id);
+        if (!sync || !id) {
+            throw new VaultApiError('unrecognized', `Respuesta inesperada de la bóveda al ${operation}.`);
+        }
+        const envSlug = asString(asObject(sync.environment)?.slug);
+        const folderPath = asString(asObject(sync.folder)?.path);
+        const options = asObject(sync.syncOptions);
+        return {
+            id,
+            name: asString(sync.name) ?? id,
+            destination: asString(sync.destination) ?? '',
+            connectionId: asString(sync.connectionId) ?? asString(asObject(sync.connection)?.id),
+            source: envSlug !== null && folderPath !== null
+                ? normalizeLocation({ env: envSlug, path: folderPath })
+                : null,
+            initialSyncBehavior: asString(options?.initialSyncBehavior),
+            disableSecretDeletion: options?.disableSecretDeletion === true,
+            isAutoSyncEnabled: typeof sync.isAutoSyncEnabled === 'boolean' ? sync.isAutoSyncEnabled : null,
+            keySchema: asString(options?.keySchema),
+            destinationConfig: asObject(sync.destinationConfig) ?? {},
+            syncStatus: asString(sync.syncStatus),
+            lastSyncJobId: asString(sync.lastSyncJobId),
+        };
+    }
+    async function listSecretSyncs(projectId) {
+        const operation = `listar los syncs de \`${labelOf(projectId)}\``;
+        const body = asObject(ok(await call(operation, 'GET', '/api/v1/secret-syncs', {
+            query: { projectId },
+            projectId,
+        }), operation));
+        return asArray(body?.secretSyncs).map((entry) => parseSync(entry, operation));
+    }
+    async function createSecretSync(projectId, spec) {
+        const source = normalizeLocation(spec.source);
+        // The guard runs BEFORE any network call: a refused pair never reaches the instance.
+        assertSyncAllowed(spec, source);
+        return postSecretSync(projectId, spec, source);
+    }
+    async function postSecretSync(projectId, spec, source) {
+        const destinationConfig = spec.destination === 'vercel'
+            ? {
+                scope: 'project',
+                app: spec.vercel.projectId,
+                appName: spec.vercel.projectName,
+                env: spec.vercel.target,
+                teamId: spec.vercel.teamId,
+            }
+            : { scope: 'repository', owner: spec.github.owner, repo: spec.github.repo };
+        return postSyncRequest(projectId, spec.destination, spec.name, spec.connectionId, source, destinationConfig);
+    }
+    async function createRailwaySync(projectId, spec) {
+        const source = normalizeLocation(spec.source);
+        // The guard runs BEFORE any network call: a refused source never reaches the instance.
+        assertRailwaySyncAllowed(source);
+        const r = spec.railway;
+        return postSyncRequest(projectId, 'railway', spec.name, spec.connectionId, source, {
+            projectId: r.projectId,
+            projectName: r.projectName,
+            environmentId: r.environmentId,
+            environmentName: r.environmentName,
+            serviceId: r.serviceId,
+            serviceName: r.serviceName,
+        });
+    }
+    async function postSyncRequest(projectId, destination, name, connectionId, source, destinationConfig) {
+        const operation = `crear el sync ${formatLocation(source)} → ${destination}`;
+        const response = await call(operation, 'POST', `/api/v1/secret-syncs/${destination}`, {
+            body: {
+                name,
+                projectId,
+                connectionId,
+                environment: source.env,
+                secretPath: source.path,
+                isAutoSyncEnabled: true,
+                syncOptions: {
+                    initialSyncBehavior: VAULT_SYNC_INITIAL_BEHAVIOR,
+                    // Fixed for every sync the client creates: none is born with deletion OFF (ADR-005 §4).
+                    disableSecretDeletion: VAULT_SYNC_DISABLE_DELETION,
+                },
+                destinationConfig,
+            },
+            projectId,
+        });
+        return parseSync(asObject(ok(response, operation))?.secretSync, operation);
+    }
+    async function deleteSecretSync(sync) {
+        // RWAY-006: a Railway sync is deleted by the id `provision` recorded (`--destroy`).
+        if (sync.destination !== 'railway')
+            assertDestination(sync.destination);
+        const operation = `borrar el sync \`${sync.id}\``;
+        const response = await call(operation, 'DELETE', `/api/v1/secret-syncs/${sync.destination}/${encodeURIComponent(sync.id)}`);
+        if (response.status === 404)
+            return { deleted: false };
+        ok(response, operation);
+        return { deleted: true };
+    }
+    async function triggerSecretSync(sync) {
+        assertDestination(sync.destination);
+        const operation = `pedir que corra el sync \`${sync.id}\``;
+        ok(await call(operation, 'POST', `/api/v1/secret-syncs/${sync.destination}/${encodeURIComponent(sync.id)}/sync-secrets`), operation);
+    }
+    return {
+        whoAmI,
+        findProjectBySlug,
+        getProject,
+        ensureProject,
+        ensureDeleteProtection,
+        disableDeleteProtection,
+        deleteProject,
+        ensureEnvironments,
+        deleteEnvironment,
+        ensureFolder,
+        deleteFolder,
+        ensureMembers,
+        readSecrets,
+        writeSecrets,
+        writeReference,
+        ensureImport,
+        ensureProjectLayout,
+        listSecretKeys,
+        findAppConnection,
+        listSecretSyncs,
+        createSecretSync,
+        createRailwaySync,
+        deleteSecretSync,
+        triggerSecretSync,
+    };
+}