supcoflow 0.0.0-stage → 0.1.0

package/dist/comandos/login.js

@@ -0,0 +1,254 @@
+import { FalloDeLaTerminal, resultadoDeFallo, SALIDA, taparSecretos } from "../contrato.js";
+import { PLAZO_MINIMO_MS, RESERVA_PARA_CERRAR_MS, sondearUnTramo, TRAMO_MAXIMO_MS } from "../sondeo.js";
+const TECHO_DE_UN_PASO_MS = 5_000;
+const VOLVER_A_EMPEZAR = "Volvé a empezar con `supcoflow login --start`.";
+const fallo = (codigo, error, message, extra = {}) => ({
+    codigo, json: { ok: false, error, message, ...extra }, texto: message,
+});
+// Un error crudo del sistema (fs, el llavero) puede traer cualquier cosa: se tapa antes de mostrarlo.
+const motivo = (e) => e instanceof FalloDeLaTerminal ? e.message : taparSecretos(e instanceof Error ? e.message : String(e));
+// Las claves que un login o logout anterior no pudo revocar (Review Focus 14). Nunca lanza: es
+// limpieza de lo de antes y no puede trabar un login nuevo.
+export async function reintentarPorRevocar(d, limite) {
+    const origen = d.api.origin;
+    const noSe = () => {
+        d.avisar("No pude leer entera la lista de claves por revocar (el llavero no respondió); la reintento la próxima vez.");
+    };
+    let lectura;
+    try {
+        lectura = await d.guardado.leerPorRevocar(origen);
+    }
+    catch {
+        noSe();
+        return { revocadas: 0, quedan: null };
+    }
+    // «Cuántas quedan» sólo es un número si se pudo comprobar entero (Review Focus 15): con un
+    // almacén que no respondió puede haber claves que no se vieron, y decir 0 sería mentir.
+    let sabido = lectura.completa;
+    let revocadas = 0;
+    for (const clave of lectura.claves) {
+        const queda = limite - d.ahora();
+        if (queda < PLAZO_MINIMO_MS)
+            break;
+        try {
+            await d.revocarPropia(d.api, clave, Math.min(TECHO_DE_UN_PASO_MS, queda));
+        }
+        catch {
+            continue; // sigue anotada; el próximo login o logout la reintenta
+        }
+        revocadas++;
+        try {
+            if (!(await d.guardado.quitarPorRevocar(origen, clave)).completo)
+                sabido = false;
+        }
+        catch {
+            sabido = false;
+        }
+    }
+    if (!sabido) {
+        noSe();
+        return { revocadas, quedan: null };
+    }
+    return { revocadas, quedan: lectura.claves.length - revocadas };
+}
+export async function loginStart(d, flags) {
+    const origen = d.api.origin;
+    if (flags.dryRun) {
+        const haria = `pedir un código de dispositivo a ${origen}`;
+        return { codigo: SALIDA.ok, json: { ok: true, dry_run: true, haria }, texto: `Con --dry-run no hago nada; sin él, iría a ${haria}.` };
+    }
+    await reintentarPorRevocar(d, d.ahora() + 15_000);
+    let c;
+    try {
+        c = await d.pedirCodigo(d.api, d.maquina);
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+    // Sólo el pendiente, en su propia cuenta: la clave vigente sigue sirviendo hasta que la nueva
+    // quede guardada (Review Focus 7), así un login rechazado o abandonado no deja a nadie sin sesión.
+    const pendiente = {
+        deviceCode: c.deviceCode, userCode: c.userCode, verificationUriComplete: c.verificationUriComplete,
+        venceEn: d.ahora() + c.expiresIn * 1000, intervaloS: c.interval, ultimoSondeoEn: null,
+    };
+    try {
+        await d.guardado.guardarPendiente(origen, pendiente);
+    }
+    catch (e) {
+        return fallo(SALIDA.inesperado, e instanceof FalloDeLaTerminal ? e.error : "no_se_pudo_guardar", `No pude guardar el inicio de sesión en curso: ${motivo(e)}`);
+    }
+    return {
+        codigo: SALIDA.esperandoAUnaPersona,
+        json: {
+            ok: false, esperando: "persona", verification_uri: c.verificationUri,
+            verification_uri_complete: c.verificationUriComplete, user_code: c.userCode, expires_in: c.expiresIn,
+        },
+        texto: `Abrí ${c.verificationUriComplete} y confirmá el código ${c.userCode}. Después corré \`supcoflow login --wait\`.`,
+    };
+}
+export async function loginWait(d) {
+    const origen = d.api.origin;
+    const inicio = d.ahora();
+    const tramo = d.tramoMs ?? TRAMO_MAXIMO_MS;
+    const limite = inicio + tramo;
+    // La proporción sólo pesa con el tramo corto de las pruebas; con 90 s la reserva es la entera.
+    const finDeSondeos = limite - Math.min(RESERVA_PARA_CERRAR_MS, tramo / 3);
+    const techo = () => Math.max(0, Math.min(TECHO_DE_UN_PASO_MS, limite - d.ahora()));
+    const p = await d.guardado.leerPendiente(origen);
+    if (p === null) {
+        return fallo(SALIDA.entradaInvalida, "sin_login_en_curso", "No hay un inicio de sesión en curso: empezá con `supcoflow login --start`.");
+    }
+    // La anterior se lee ANTES de sondear, así no consume la reserva del cierre. Se pide por
+    // `leerClaveCompleta` para saber de paso si SUPCOFLOW_TOKEN está definida (sin costo: la variable
+    // se devuelve sin tocar los almacenes); en ese caso la anterior es la GUARDADA, nunca la del
+    // entorno, que no es de este login y no se revoca acá.
+    const vigente = await d.guardado.leerClaveCompleta(origen);
+    const conVariable = vigente.valor?.fuente === "env";
+    const lectura = conVariable ? await d.guardado.leerClaveGuardadaCompleta(origen) : vigente;
+    // Un llavero que no contestó no es «no había clave» (Review Focus 12 y 14): seguir guardaría la
+    // nueva encima de la anterior sin revocarla, viva y olvidada. Se corta antes de canjear el código
+    // y sin borrar el pendiente, así el mismo `--wait` sirve cuando el llavero vuelva.
+    if (!lectura.completa) {
+        const salida = conVariable
+            ? "desbloqueá el llavero y volvé a llamar `supcoflow login --wait`."
+            : "desbloqueá el llavero y volvé a llamar `supcoflow login --wait` (o, sin login, exportá SUPCOFLOW_TOKEN con una clave vigente).";
+        return fallo(SALIDA.inesperado, "no_pude_leer_la_clave", `No pude leer tu clave guardada (el llavero no respondió), y sin saber cuál es no la puedo reemplazar sin dejarla viva: ${salida}`);
+    }
+    const anterior = lectura.valor;
+    let fin;
+    try {
+        fin = await sondearUnTramo(p, {
+            ahora: d.ahora, dormir: d.dormir, finDeSondeos,
+            canjear: (deviceCode, plazoMs) => d.canjear(d.api, deviceCode, plazoMs),
+            persistir: (q, techoMs) => d.guardado.guardarPendiente(origen, q, techoMs),
+        });
+    }
+    catch (e) {
+        // El progreso de los sondeos anteriores ya quedó guardado: el próximo `--wait` sigue de ahí.
+        return resultadoDeFallo(e);
+    }
+    switch (fin.tipo) {
+        case "sigue":
+            return {
+                codigo: SALIDA.esperandoAUnaPersona,
+                json: { ok: false, esperando: "persona", user_code: fin.pendiente.userCode, verification_uri_complete: fin.pendiente.verificationUriComplete },
+                texto: `Todavía no se confirmó. Abrí ${fin.pendiente.verificationUriComplete} y confirmá el código ${fin.pendiente.userCode}; después volvé a correr \`supcoflow login --wait\`.`,
+            };
+        case "token": {
+            const r = await reemplazarClave(d, { clave: fin.clave, equipo: fin.equipo }, anterior?.clave ?? null, limite);
+            // Va acá y no adentro de `reemplazarClave` porque es acá donde se supo, antes de sondear, sin
+            // gastar reserva: preguntarlo al final costaría otra lectura lenta del guardado.
+            if (conVariable && r.json.guardada_en !== undefined) {
+                d.avisar("SUPCOFLOW_TOKEN está definida y tiene prioridad sobre la clave que acabo de guardar.");
+            }
+            return r;
+        }
+        case "rechazado":
+            await d.guardado.borrarPendiente(origen, techo());
+            return fallo(SALIDA.haceFaltaUnaPersona, "acceso_rechazado", "Rechazaron el acceso desde la consola; tu sesión anterior, si había, sigue igual.");
+        case "vencido":
+            await d.guardado.borrarPendiente(origen, techo());
+            return fallo(SALIDA.faltaLogin, "codigo_vencido", `El código venció. ${VOLVER_A_EMPEZAR}`);
+        case "invalido":
+            await d.guardado.borrarPendiente(origen, techo());
+            return fallo(SALIDA.faltaLogin, "codigo_invalido", `El código ya no vale. ${VOLVER_A_EMPEZAR}`);
+    }
+}
+// El login de una persona frente a la terminal: los mismos dos pasos, encadenados. Sin TTY (o con
+// `--json`) no pide código: nadie iba a ver la URL, y un pedido que nadie aprueba sólo gasta el tope
+// de pedidos por IP del motor. A un asistente le corresponde el camino partido.
+const PAUSA_ENTRE_TRAMOS_MS = 1_000;
+export async function loginInteractivo(d, flags) {
+    if (!d.esTty || flags.json) {
+        return fallo(SALIDA.entradaInvalida, "hace_falta_tty", "Sin terminal interactiva usá `supcoflow login --start --json` y después `supcoflow login --wait --json`.");
+    }
+    const inicio = await loginStart(d, flags);
+    if (inicio.codigo !== SALIDA.esperandoAUnaPersona)
+        return inicio;
+    // El texto de `--start` le dice a la persona que corra `--wait`; acá eso lo hace el comando solo.
+    const { verification_uri_complete: url, user_code: codigo } = inicio.json;
+    d.mostrar(`Abrí ${String(url)} y confirmá el código ${String(codigo)}. Espero acá…`);
+    // Cada tramo termina por su cuenta (≤ 90 s) y el código vence a los pocos minutos, así que el
+    // bucle tiene fin aunque la persona nunca conteste: termina en `codigo_vencido`.
+    let r;
+    do {
+        r = await loginWait(d);
+        // Un `loginWait` que devuelve 5 sin haber sondeado (el intervalo era más largo que la ventana
+        // que quedaba) volvería a girar sin esperar nada: este segundo evita quemar CPU en el vacío.
+        if (r.codigo === SALIDA.esperandoAUnaPersona)
+            await d.dormir(PAUSA_ENTRE_TRAMOS_MS);
+    } while (r.codigo === SALIDA.esperandoAUnaPersona);
+    return r;
+}
+// Por qué este orden (guardar → revocar → anotar → borrar el pendiente), Review Focus 13 y 14:
+// la nueva se guarda primero porque es la única copia; la anterior se revoca recién con la nueva a
+// salvo (si no, un fallo al guardar dejaba a la persona sin ninguna); si no se pudo revocar, se anota
+// para no olvidarla viva; y el borrado del pendiente va último y no lanza, porque ubicado antes era el
+// que podía impedir revocar la anterior, y un pendiente viejo es inofensivo.
+export async function reemplazarClave(d, nueva, anterior, limite) {
+    const origen = d.api.origin;
+    const queda = () => limite - d.ahora();
+    const techo = () => Math.max(0, Math.min(TECHO_DE_UN_PASO_MS, queda()));
+    // 1. Guardar la nueva. Con el techo agotado el guardado salta el llavero y escribe el archivo, que
+    // es local: la clave se guarda igual aunque el tramo esté por vencer.
+    let guardadaEn;
+    try {
+        guardadaEn = (await d.guardado.guardarClave(origen, nueva.clave, techo())).donde;
+    }
+    catch (e) {
+        // Una clave que nadie guardó no puede quedar viva: se revoca, aunque haga falta un plazo mínimo
+        // más allá del tramo, porque nadie más la va a poder revocar.
+        let revocada = true;
+        try {
+            await d.revocarPropia(d.api, nueva.clave, Math.min(TECHO_DE_UN_PASO_MS, Math.max(PLAZO_MINIMO_MS, queda())));
+        }
+        catch {
+            revocada = false;
+        }
+        const despues = revocada
+            ? "La revoqué para que no quede viva; tu sesión anterior, si había, sigue como estaba."
+            : "Tampoco pude revocarla: revocala en la consola, en «Accesos desde la terminal».";
+        return fallo(SALIDA.inesperado, "no_se_pudo_guardar", `No pude guardar la clave nueva (${motivo(e)}). ${despues}`);
+    }
+    // 2. Revocar la anterior, o anotarla.
+    let anteriorRevocada = null;
+    let quedaPorRevocar = false;
+    if (anterior !== null && anterior !== nueva.clave) {
+        anteriorRevocada = false;
+        if (queda() >= PLAZO_MINIMO_MS) {
+            try {
+                await d.revocarPropia(d.api, anterior, Math.min(TECHO_DE_UN_PASO_MS, queda()));
+                anteriorRevocada = true;
+            }
+            catch {
+                // cae a anotarla
+            }
+        }
+        if (!anteriorRevocada) {
+            try {
+                await d.guardado.anotarPorRevocar(origen, anterior, techo());
+                quedaPorRevocar = true;
+                d.avisar("No pude revocar tu clave anterior; quedó anotada y la reintento en el próximo login o logout.");
+            }
+            catch {
+                const message = "No pude revocar ni anotar tu clave anterior: revocala en la consola, en «Accesos desde la terminal».";
+                d.avisar(message);
+                if (queda() >= PLAZO_MINIMO_MS)
+                    await d.guardado.borrarPendiente(origen, techo());
+                // La nueva SÍ quedó guardada y anda: el json lo dice para que nadie vuelva a hacer login.
+                return fallo(SALIDA.inesperado, "clave_anterior_sin_revocar", message, {
+                    equipo: nueva.equipo, guardada_en: guardadaEn, anterior_revocada: false, queda_por_revocar: false,
+                });
+            }
+        }
+    }
+    // 3. Borrar el pendiente; su `false` no cambia nada.
+    if (queda() >= PLAZO_MINIMO_MS)
+        await d.guardado.borrarPendiente(origen, techo());
+    const donde = guardadaEn === "llavero" ? "el llavero del sistema" : "el archivo de credenciales";
+    return {
+        codigo: SALIDA.ok,
+        json: { ok: true, equipo: nueva.equipo, guardada_en: guardadaEn, anterior_revocada: anteriorRevocada, queda_por_revocar: quedaPorRevocar },
+        texto: `Sesión iniciada en el equipo ${nueva.equipo}; la clave quedó en ${donde}.`,
+    };
+}

package/dist/comandos/logout.js

@@ -0,0 +1,96 @@
+// `supcoflow logout`: cierra UNA credencial, la que se está usando, y nunca olvida una clave viva
+// (Review Focus 9 y 14). Borrar sin revocar dejaría la clave sirviendo en el motor y sin nadie que
+// la recuerde: por eso, si el motor no confirma, no se borra nada y el comando sale 1.
+import { FalloDeLaTerminal, SALIDA, taparSecretos } from "../contrato.js";
+import { reintentarPorRevocar } from "./login.js";
+const motivo = (e) => e instanceof FalloDeLaTerminal ? e.message : taparSecretos(e instanceof Error ? e.message : String(e));
+export async function comandoLogout(d, flags) {
+    const origen = d.api.origin;
+    // Sin nada legible y un almacén que no contestó, no se sabe si hay sesión: decir «no había»
+    // dejaría creer que no queda ninguna clave viva (Review Focus 12).
+    const noPudeLeer = (extra = {}) => {
+        const message = "No pude leer la clave guardada (el llavero no respondió); no cerré nada. Probá de nuevo.";
+        return { codigo: SALIDA.inesperado, json: { ok: false, error: "no_pude_leer_la_clave", message, ...extra }, texto: message };
+    };
+    if (flags.dryRun) {
+        const lectura = await d.guardado.leerClaveCompleta(origen);
+        const vigente = lectura.valor;
+        if (vigente === null && !lectura.completa)
+            return noPudeLeer({ dry_run: true });
+        if (vigente === null) {
+            return { codigo: SALIDA.ok, json: { ok: true, dry_run: true, habia_sesion: false }, texto: "No hay sesión iniciada: no haría nada." };
+        }
+        const haria = `revocar la clave de ${vigente.fuente} en ${origen}` + (vigente.fuente !== "env" ? " y borrarla" : "");
+        return { codigo: SALIDA.ok, json: { ok: true, dry_run: true, haria }, texto: `Con --dry-run no hago nada; sin él, iría a ${haria}.` };
+    }
+    // Lo pendiente de antes va primero: un logout es justo cuando la persona espera que no quede
+    // ninguna clave suya viva, y es la última oportunidad que tiene la terminal de revocarlas.
+    const { quedan } = await reintentarPorRevocar(d, d.ahora() + 15_000);
+    // `null` es «no lo pude comprobar» y se dice así: un 0 haría creer que no queda nada vivo.
+    if (quedan === null) {
+        d.avisar("No pude comprobar cuántas claves quedan por revocar; las que haya siguen anotadas y las reintento en el próximo login o logout.");
+    }
+    else if (quedan > 0) {
+        d.avisar(`Quedan ${quedan} clave(s) anterior(es) sin revocar; siguen anotadas y las reintento en el próximo login o logout.`);
+    }
+    const lectura = await d.guardado.leerClaveCompleta(origen);
+    const vigente = lectura.valor;
+    if (vigente === null && !lectura.completa)
+        return noPudeLeer({ quedan_por_revocar: quedan });
+    const conPendientes = (json) => ({ ...json, quedan_por_revocar: quedan, ...(lectura.completa ? {} : { lectura_completa: false }) });
+    if (vigente === null) {
+        await d.guardado.borrarPendiente(origen);
+        return { codigo: SALIDA.ok, json: conPendientes({ ok: true, habia_sesion: false }), texto: "No había sesión iniciada." };
+    }
+    let revocada;
+    try {
+        revocada = (await d.revocarPropia(d.api, vigente.clave)) === "revocada";
+    }
+    catch (e) {
+        const cual = vigente.fuente === "env" ? "la clave de SUPCOFLOW_TOKEN sigue viva" : "la clave sigue guardada";
+        const message = `No pude revocar la clave, así que no cerré la sesión (${motivo(e)}); ${cual}. Probá de nuevo.`;
+        const error = e instanceof FalloDeLaTerminal ? e.error : "inesperado";
+        return { codigo: SALIDA.inesperado, json: conPendientes({ ok: false, error, message }), texto: message };
+    }
+    // La variable no es nuestra: se revoca la clave que trae, pero lo guardado es OTRA credencial,
+    // que sólo se cierra revocándola a ella. Borrarla acá la dejaría viva y olvidada.
+    if (vigente.fuente === "env") {
+        d.avisar("Revoqué la clave de SUPCOFLOW_TOKEN; sacala de tu entorno.");
+        // `undefined` = no se pudo leer: no se afirma que no haya, el json lleva `null` en vez de mentir.
+        let guardada;
+        try {
+            const l = await d.guardado.leerClaveGuardadaCompleta(origen);
+            guardada = l.valor ?? (l.completa ? null : undefined);
+        }
+        catch {
+            guardada = undefined;
+        }
+        if (guardada) {
+            d.avisar(`Sigue guardada otra clave en ${guardada.fuente}; para cerrarla, corré \`supcoflow logout\` sin SUPCOFLOW_TOKEN.`);
+        }
+        return {
+            codigo: SALIDA.ok,
+            json: conPendientes({ ok: true, revocada, fuente: "env", queda_clave_guardada: guardada === undefined ? null : guardada !== null }),
+            texto: "Revoqué la clave de SUPCOFLOW_TOKEN.",
+        };
+    }
+    // Con la lectura incompleta se borra sólo la copia que se leyó y se acaba de revocar: la del
+    // almacén que no contestó puede ser otra clave, viva, y borrarla sin revocarla la olvidaría.
+    if (!lectura.completa) {
+        const otro = vigente.fuente === "archivo" ? "el llavero del sistema" : "el archivo de credenciales";
+        d.avisar(`Cierro la clave de ${vigente.fuente}, pero no pude leer ${otro}: puede quedar otra copia guardada ahí; cuando responda, volvé a correr \`supcoflow logout\`.`);
+    }
+    try {
+        if (lectura.completa)
+            await d.guardado.borrarClave(origen);
+        else
+            await d.guardado.borrarClaveDe(origen, vigente.fuente);
+    }
+    catch (e) {
+        // La clave ya no sirve en el motor, pero quedó escrita: el comando no puede decir que terminó bien.
+        const message = `La clave quedó revocada pero no pude borrarla: ${motivo(e)}`;
+        return { codigo: SALIDA.inesperado, json: conPendientes({ ok: false, error: "no_se_pudo_borrar", message }), texto: message };
+    }
+    await d.guardado.borrarPendiente(origen);
+    return { codigo: SALIDA.ok, json: conPendientes({ ok: true, revocada }), texto: "Sesión cerrada." };
+}

package/dist/comandos/quien-soy.js

@@ -0,0 +1,50 @@
+import { FalloDeLaTerminal, resultadoDeFallo, SALIDA } from "../contrato.js";
+export async function comandoQuienSoy(d) {
+    const origen = d.api.origin;
+    const lectura = await d.guardado.leerClaveCompleta(origen);
+    const vigente = lectura.valor;
+    // «Iniciá sesión» con la clave guardada en un llavero que no contestó invita a un login que la
+    // pisaría: no es «sin sesión», es «no pude mirar» (Review Focus 12).
+    if (vigente === null && !lectura.completa) {
+        const message = "No pude leer la clave guardada (el llavero no respondió). Desbloquealo y probá de nuevo.";
+        return { codigo: SALIDA.inesperado, json: { ok: false, error: "llavero_no_responde", message }, texto: message };
+    }
+    if (vigente === null) {
+        const message = "Iniciá sesión con `supcoflow login`.";
+        return { codigo: SALIDA.faltaLogin, json: { ok: false, error: "sin_sesion", message }, texto: message };
+    }
+    if (!lectura.completa) {
+        const otro = vigente.fuente === "archivo" ? "el llavero del sistema" : "el archivo de credenciales";
+        d.avisar(`Uso la clave de ${vigente.fuente}, pero no pude leer ${otro}: puede haber guardada otra más nueva.`);
+    }
+    // Leer no cuesta nada y avisa de algo que la persona no vería de otro modo: claves viejas vivas.
+    try {
+        const { claves, completa } = await d.guardado.leerPorRevocar(origen);
+        if (claves.length > 0) {
+            d.avisar(`Hay ${claves.length} clave(s) anterior(es) anotadas para revocar; se reintenta en el próximo login o logout.`);
+        }
+        if (!completa)
+            d.avisar("No pude leer entera la lista de claves por revocar.");
+    }
+    catch {
+        d.avisar("No pude leer entera la lista de claves por revocar.");
+    }
+    let yo;
+    try {
+        yo = await d.quienSoy(d.api, vigente.clave);
+    }
+    catch (e) {
+        // Con la variable definida, «iniciá sesión de nuevo» no arregla nada: la variable sigue
+        // ganándole a la clave nueva. Hay que decir cuál es la que no vale.
+        if (e instanceof FalloDeLaTerminal && e.codigo === SALIDA.faltaLogin && vigente.fuente === "env") {
+            return resultadoDeFallo(new FalloDeLaTerminal(e.codigo, e.error, "La clave de SUPCOFLOW_TOKEN no vale: sacala de tu entorno o reemplazala por una vigente."));
+        }
+        return resultadoDeFallo(e);
+    }
+    const quien = yo.usuario?.login ?? yo.usuario?.email ?? yo.via;
+    return {
+        codigo: SALIDA.ok,
+        json: { ok: true, via: yo.via, equipo: yo.equipo, usuario: yo.usuario, proyecto: yo.proyecto, fuente: vigente.fuente },
+        texto: `${quien} en el equipo ${yo.equipo} (clave en ${vigente.fuente})`,
+    };
+}

package/dist/contrato.js

@@ -0,0 +1,38 @@
+// El contrato de salida de la terminal (§13). Quien la llama es, muchas veces, un asistente
+// que lee el código de salida y la ÚLTIMA línea de stdout: por eso un resultado es siempre
+// UNA línea de JSON, y un 5 no es un error sino «volvé a llamarme cuando la persona termine».
+export const SALIDA = {
+    ok: 0,
+    inesperado: 1,
+    faltaLogin: 2,
+    entradaInvalida: 3,
+    haceFaltaUnaPersona: 4,
+    esperandoAUnaPersona: 5,
+    topeAlcanzado: 6,
+};
+export class FalloDeLaTerminal extends Error {
+    codigo;
+    error;
+    constructor(codigo, error, message) {
+        super(message);
+        this.codigo = codigo;
+        this.error = error;
+        this.name = "FalloDeLaTerminal";
+    }
+}
+// JSON.stringify escapa los saltos de línea de los valores, así que la salida cabe en una línea.
+export function emitir(r, modoJson, out) {
+    out(modoJson ? JSON.stringify(r.json) + "\n" : r.texto + "\n");
+}
+// Un mensaje de error de afuera (fetch, el sistema) podría traer la clave o el device_code
+// tal cual; la clave se tapa ANTES que los 64 hex porque los contiene.
+export function taparSecretos(s) {
+    return s.replace(/scf_[0-9a-f]{16}_[0-9a-f]{64}/g, "scf_…").replace(/\b[0-9a-f]{64}\b/g, "[device_code]");
+}
+export function resultadoDeFallo(e) {
+    if (e instanceof FalloDeLaTerminal) {
+        return { codigo: e.codigo, json: { ok: false, error: e.error, message: e.message }, texto: e.message };
+    }
+    const message = taparSecretos(e instanceof Error ? e.message : String(e));
+    return { codigo: SALIDA.inesperado, json: { ok: false, error: "inesperado", message }, texto: message };
+}

package/dist/entorno.js

@@ -0,0 +1,152 @@
+// Lo único que toca el mundo de verdad: el proceso, el disco, el llavero, la red y el reloj. Todo lo
+// demás recibe estas piezas inyectadas y se prueba con dobles; acá sólo se enchufan.
+import { spawn } from "node:child_process";
+import { chmodSync, closeSync, fchmodSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeSync } from "node:fs";
+import { homedir, hostname } from "node:os";
+import { join } from "node:path";
+import { canjear, pedirCodigo, quienSoy, revocarPropia, urlDeLaApi } from "./api.js";
+import { almacenDeArchivo } from "./guardado/archivo.js";
+import { crearGuardado } from "./guardado/index.js";
+import { almacenDeLlavero } from "./guardado/llavero.js";
+import { TRAMO_MAXIMO_MS } from "./sondeo.js";
+// El `.tmp` se crea en exclusiva (`wx`: falla si quedó algo, enlace incluido, en vez de escribir a
+// través de él) y el `fchmod` va aparte porque el modo de `open` pasa por la umask del proceso.
+// `rmSync` sobre un enlace borra el enlace, nunca su destino.
+export const fsReal = {
+    leer(p) {
+        try {
+            return readFileSync(p, "utf8");
+        }
+        catch (e) {
+            if (e.code === "ENOENT")
+                return null;
+            throw e;
+        }
+    },
+    crearDir: (p, modo) => void mkdirSync(p, { recursive: true, mode: modo }),
+    chmod: (p, modo) => chmodSync(p, modo),
+    borrarSiExiste: (p) => rmSync(p, { force: true }),
+    escribirExclusivo(p, s, modo) {
+        const fd = openSync(p, "wx", modo);
+        try {
+            fchmodSync(fd, modo);
+            writeSync(fd, s);
+        }
+        finally {
+            closeSync(fd);
+        }
+    },
+    renombrar: (a, b) => renameSync(a, b),
+    // Un enlace roto que no se puede resolver es un FALLO: el control del repo no puede saber adónde
+    // apunta, y escribir sin saberlo es justo lo que el control existe para impedir.
+    realpath(p) {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            throw new Error(`No puedo resolver la ruta real de ${p} (¿un enlace roto?); no guardo nada ahí.`);
+        }
+    },
+    // `lstat` y no `existsSync`: éste sigue el enlace y ante uno roto dice «no existe», y el control
+    // del repo pasaba de largo, resolvía al padre y daba una ruta «real» que no era por donde se iba a
+    // escribir (Review Focus 6). Con `lstat` el enlace existe, `realpath` no lo resuelve y falla cerrado.
+    existe(p) {
+        try {
+            lstatSync(p);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+};
+// Para hablar con `security`/`secret-tool`. stderr se captura sólo como señal (¿dijo algo?: es lo
+// que separa «no encontrado» de «sin D-Bus» en `secret-tool`), recortado, y nunca se muestra ni se
+// registra: podría traer algo del secreto. Al techo el hijo se mata con SIGKILL (un llavero bloqueado no atiende un SIGTERM) y se
+// resuelve sin esperar a que muera: un `close` que no llega no puede colgar el comando (Review Focus 2).
+// Un entorno mínimo para el hijo: con `process.env` entero, SUPCOFLOW_TOKEN (y cualquier otro
+// secreto del shell) llegaría a `security`/`secret-tool`, que no lo necesitan. Las variables de D-Bus
+// y XDG sí: sin ellas `secret-tool` no encuentra el bus del Secret Service.
+const VARIABLES_DEL_HIJO = ["PATH", "HOME", "USER", "LANG", "DBUS_SESSION_BUS_ADDRESS", "XDG_RUNTIME_DIR", "DISPLAY", "XDG_CONFIG_HOME"];
+function entornoDelHijo() {
+    const r = {};
+    for (const k of VARIABLES_DEL_HIJO) {
+        const v = process.env[k];
+        if (v !== undefined)
+            r[k] = v;
+    }
+    return r;
+}
+const MAXIMO_DE_STDERR = 2_048;
+export const correrReal = (bin, args, stdin, techoMs) => new Promise((resolve) => {
+    let listo = false;
+    let stdout = "";
+    let stderr = "";
+    const terminar = (r) => {
+        if (listo)
+            return;
+        listo = true;
+        clearTimeout(reloj);
+        resolve({ ...r, stdout, stderr });
+    };
+    const hijo = spawn(bin, args, { stdio: ["pipe", "pipe", "pipe"], env: entornoDelHijo() });
+    const reloj = setTimeout(() => {
+        hijo.kill("SIGKILL");
+        terminar({ codigo: null, vencido: true });
+    }, techoMs);
+    hijo.on("error", (e) => {
+        terminar({ codigo: null, vencido: false, ausente: e.code === "ENOENT" ? true : undefined });
+    });
+    hijo.stdout.on("data", (b) => (stdout += b.toString("utf8")));
+    // Se lee siempre (un pipe lleno que nadie vacía colgaría al hijo) pero se guarda poco.
+    hijo.stderr.on("data", (b) => {
+        if (stderr.length < MAXIMO_DE_STDERR)
+            stderr = (stderr + b.toString("utf8")).slice(0, MAXIMO_DE_STDERR);
+    });
+    hijo.on("close", (codigo) => terminar({ codigo, vencido: false }));
+    // Un hijo que muere antes de leer deja un EPIPE en stdin; sin este handler tumbaría el proceso.
+    hijo.stdin.on("error", () => { });
+    hijo.stdin.end(stdin ?? undefined);
+});
+const LOCALES = new Set(["localhost", "127.0.0.1", "[::1]"]);
+export function entornoReal(env = process.env) {
+    const api = urlDeLaApi(env);
+    // Perillas de PRUEBA, no del producto: sólo valen contra un motor en la propia máquina. Contra
+    // producción se ignoran, así una variable olvidada en el shell no saca la clave del llavero ni
+    // acorta los tramos de nadie.
+    const local = LOCALES.has(api.hostname);
+    const sinLlavero = local && env.SUPCOFLOW_SIN_LLAVERO === "1";
+    const tramo = Number(env.SUPCOFLOW_TRAMO_MS);
+    const tramoMs = local && Number.isInteger(tramo) && tramo > 0 && tramo <= TRAMO_MAXIMO_MS ? tramo : undefined;
+    const avisar = (s) => void process.stderr.write(s + "\n");
+    // `||` y no `??`: un XDG_CONFIG_HOME vacío daría una ruta RELATIVA, que cae donde esté parado el
+    // comando; la especificación de XDG lo trata como no definido.
+    const rutaDelArchivo = join(env.XDG_CONFIG_HOME || join(homedir(), ".config"), "supcoflow", "credenciales.json");
+    const llavero = sinLlavero ? null : almacenDeLlavero(process.platform, correrReal);
+    const guardado = crearGuardado({
+        env, llavero, archivo: almacenDeArchivo(rutaDelArchivo, fsReal), rutaDelArchivo, fs: fsReal, ahora: Date.now, avisar,
+    });
+    return {
+        env,
+        api,
+        esTty: process.stdin.isTTY === true && process.stdout.isTTY === true,
+        mostrar: avisar,
+        avisar,
+        rutaDelArchivo,
+        llavero,
+        guardado,
+        login: {
+            api,
+            guardado,
+            maquina: hostname(),
+            ahora: Date.now,
+            dormir: (ms) => new Promise((r) => setTimeout(r, ms)),
+            pedirCodigo: (a, maquina) => pedirCodigo(a, maquina, fetch),
+            canjear: (a, deviceCode, plazoMs) => canjear(a, deviceCode, fetch, plazoMs),
+            revocarPropia: (a, clave, plazoMs) => revocarPropia(a, clave, fetch, plazoMs),
+            avisar,
+            tramoMs,
+        },
+        quienSoy: (a, clave) => quienSoy(a, clave, fetch),
+    };
+}

package/dist/guardado/archivo.js

@@ -0,0 +1,63 @@
+// El archivo de credenciales, para cuando no hay llavero: un JSON `{ "<cuenta>": Registro }`.
+import path from "node:path";
+export function esRegistro(v) {
+    return typeof v === "object" && v !== null
+        && typeof v.valor === "string" && typeof v.escritoEn === "number";
+}
+export function almacenDeArchivo(ruta, fs) {
+    const dir = path.dirname(ruta);
+    const temporal = ruta + ".tmp";
+    // Un archivo que no se entiende es un FALLO, no un vacío: tratarlo como vacío y reescribirlo
+    // perdería claves por revocar que quizás siguen ahí.
+    function todo() {
+        const crudo = fs.leer(ruta);
+        if (crudo === null)
+            return {};
+        let v;
+        try {
+            v = JSON.parse(crudo);
+        }
+        catch {
+            v = undefined;
+        }
+        if (typeof v !== "object" || v === null || Array.isArray(v)) {
+            throw new Error(`No entiendo el archivo de credenciales ${ruta}; borralo y volvé a iniciar sesión.`);
+        }
+        return v;
+    }
+    // El `mkdir` no corrige los permisos de una carpeta que ya existía: por eso el `chmod` aparte.
+    // El `.tmp` viejo (o un enlace dejado ahí) se borra y el nuevo se crea en exclusiva, así nunca se
+    // escribe a través de un enlace ni se hereda un `0644`; el `rename` es atómico y, si `ruta` era un
+    // enlace, reemplaza el enlace y no su destino (Review Focus 6).
+    function persistir(t) {
+        fs.crearDir(dir, 0o700);
+        fs.chmod(dir, 0o700);
+        fs.borrarSiExiste(temporal);
+        fs.escribirExclusivo(temporal, JSON.stringify(t, null, 2) + "\n", 0o600);
+        fs.renombrar(temporal, ruta);
+    }
+    return {
+        nombre: "archivo",
+        async leer(cuenta) {
+            const t = todo();
+            if (!Object.hasOwn(t, cuenta))
+                return null;
+            const r = t[cuenta];
+            if (!esRegistro(r))
+                throw new Error(`No entiendo el archivo de credenciales ${ruta}; borralo y volvé a iniciar sesión.`);
+            return { valor: r.valor, escritoEn: r.escritoEn };
+        },
+        async escribir(cuenta, r) {
+            const t = todo();
+            t[cuenta] = { valor: r.valor, escritoEn: r.escritoEn };
+            persistir(t);
+        },
+        async borrar(cuenta) {
+            const t = todo();
+            if (!Object.hasOwn(t, cuenta))
+                return;
+            delete t[cuenta];
+            persistir(t);
+        },
+    };
+}