@andco/sdk/cli

import { AndcoCliPresenter, createAndcoInstanceForCLI } from "@andco/sdk/cli";

createAndcoInstanceForCLI

createAndcoInstanceForCLI(options: AndcoCliOptions): AndcoSessionClient

Un cliente público con sesión, como el de navegador, pero con un presentador de terminal y sin suponer que existe window. AndcoCliOptions son las opciones del cliente con sesión, con presenter opcional.

const andco = createAndcoInstanceForCLI({
  clientId: "tu-client-id",
  redirectTo: "http://127.0.0.1:0/callback",
  storage: keychain,
  presenter: new AndcoCliPresenter({ open: (url) => openInBrowser(url.href) }),
});

AndcoCliPresenter

new AndcoCliPresenter(options?: AndcoCliPresenterOptions)

Levanta un receptor loopback de un solo uso: se ata al puerto, rechaza cualquier ruta que no sea la registrada, comprueba el state, responde una vez y cierra.

Todo integrador de línea de comandos necesita exactamente esto, y hasta ahora cada uno lo escribía. La versión de la propia CLI de Andco tenía noventa líneas. Equivocarse en cualquier parte —aceptar el callback en otra ruta, saltarse la comprobación del state, dejar el puerto abierto— es un fallo de seguridad en la herramienta de alguien.

El callback tiene que ser http sobre un host de loopback; cualquier otra cosa se rechaza con invalid_configuration.

Puerto libre

redirectTo: "http://127.0.0.1:0/callback";

El puerto 0 pide uno libre al sistema. El presentador reemplaza el redirect_uri de la autorización por el puerto que realmente obtuvo, porque el servidor de autorización tiene que redirigir a esa URI exacta.

Flujo de dispositivo

Cuando no hay navegador que abrir:

const { data: device } = await andco.oauth.createDeviceAuthorizationRequest({ scopes: ["openid", "email"] });
console.log(`Abre ${device.verificationUriComplete} y escribe ${device.userCode}`);

const { data: session } = await andco.oauth.awaitDeviceAuthorization(device);
await andco.session.set(session);

AndcoDeviceAuthorization trae deviceCode, userCode, verificationUri, verificationUriComplete, expiresIn, interval y la respuesta cruda.

awaitDeviceAuthorization hace el sondeo completo: respeta el intervalo, obedece los avisos de ir más lento y termina cuando la autorización se aprueba, se rechaza o vence. Acepta signal para cancelar.

Persistir la sesión

El almacenamiento por omisión vive en memoria y desaparece con el proceso. Para que la persona no se autentique en cada comando, entrega el tuyo:

const andco = createAndcoInstanceForCLI({ clientId, redirectTo, storage: keychain, lock: crossProcessLock });

lock importa cuando varios comandos pueden correr a la vez: los refresh tokens rotan, y dos renovaciones simultáneas invalidan una a la otra.