@onesi/genesis-cli 0.0.0-stage → 0.1.13

package/README.md

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# @onesi/genesis-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`genesis`, the OneOS command line. It works against the Genesis API at `https://os.one.ml/api`.
+
+```sh
+npx -y @onesi/genesis-cli@0.1.13 --help
+```
+
+## Sign in
+
+```sh
+genesis login            # opens your browser to sign in with One
+genesis login --device   # on a machine without a browser: approve a code from any signed-in browser
+genesis whoami
+```
+
+For scripts and CI, skip login and set an organization API key from the Console (https://os.one.ml → API keys):
+
+```sh
+GENESIS_API_KEY=sk_... genesis hives projects list
+```
+
+## Use
+
+```sh
+genesis status                      # live state of each service
+genesis hives projects list
+genesis hives projects create my-app --kind worker
+genesis hives projects delete prj_...
+genesis --json silos projects list  # machine-readable output; errors include code, required_scope and request_id
+```
+
+`genesis <service> --help` lists every command for a service. `--base-url` or `GENESIS_BASE_URL` overrides the gateway, and `https://console.life.one/api` is an alias. Requires Node.js 20.19 or later.
+
+Use the same version as [`@onesi/genesis`](https://www.npmjs.com/package/@onesi/genesis) and [`@onesi/genesis-mcp`](https://www.npmjs.com/package/@onesi/genesis-mcp).
+
+Docs: https://os.one.ml/docs · Error codes: https://os.one.ml/api/v1/errors

package/bin/genesis.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from '../dist/index.js';
+main(process.argv).then((code) => { process.exitCode = code; });

package/dist/auth.d.ts

@@ -0,0 +1,30 @@
+import { type GenesisContextSelection } from '@onesi/genesis';
+import type { CredentialStore, SavedLogin } from './store.js';
+import { type NativeAttempt, type NativeRegistration } from './lifeid-native.js';
+/** One account's admitted native product bridge, never a direct AuthKit bearer. */
+export interface AuthConfig {
+    productId?: string;
+    redirectUri?: string;
+    audience?: string;
+    authApi: string;
+    fetch: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** One account's registration for the Genesis CLI (product `genesis-cli`, its one loopback callback, the platform audience). */
+export declare const GENESIS_CLI_REGISTRATION: NativeRegistration;
+/** The registered profile by default; GENESIS_AUTH_* override it (an empty value disables browser login). */
+export declare function authConfig(env?: NodeJS.ProcessEnv, f?: typeof fetch): AuthConfig;
+export declare function startLogin(c: AuthConfig, options?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    organizationHint?: string;
+}): Promise<NativeAttempt>;
+/** Scheduling/consistency only. The One account server and Genesis verifier own authority. */
+export declare function jwtExp(token: string): number | undefined;
+export declare function parseLifeSession(c: AuthConfig, value: unknown, now?: number): SavedLogin;
+export declare function completeLogin(c: AuthConfig, attempt: NativeAttempt): Promise<SavedLogin>;
+export declare function refresh(c: AuthConfig, s: SavedLogin, organizationId?: string): Promise<SavedLogin>;
+/** Commit both replacement credentials through the existing atomic keychain entry. */
+export declare function selectSavedContext(c: AuthConfig, store: CredentialStore, selection: GenesisContextSelection, signal?: AbortSignal): Promise<SavedLogin>;
+/** OS-keychain bridge session; one committed rotation per store, never raw AuthKit. */
+export declare function savedLoginProvider(c: AuthConfig, store: CredentialStore, now?: () => number): () => Promise<string | undefined>;

package/dist/auth.js

@@ -0,0 +1,273 @@
+import { selectGenesisContext } from '@onesi/genesis';
+import { refreshDeviceLogin, requireDeviceSaved } from './device-login.js';
+import { LIFEID_ISSUER, startNativeAttempt, validateRegistration } from './lifeid-native.js';
+/** One account's registration for the Genesis CLI (product `genesis-cli`, its one loopback callback, the platform audience). */
+export const GENESIS_CLI_REGISTRATION = {
+    productId: 'genesis-cli', redirectUri: 'http://127.0.0.1:53682/lifeid/callback', audience: 'l1fe-platform',
+};
+/** The registered profile by default; GENESIS_AUTH_* override it (an empty value disables browser login). */
+export function authConfig(env = process.env, f = fetch) {
+    return { productId: env.GENESIS_AUTH_PRODUCT ?? GENESIS_CLI_REGISTRATION.productId,
+        redirectUri: env.GENESIS_AUTH_REDIRECT_URI ?? GENESIS_CLI_REGISTRATION.redirectUri,
+        audience: env.GENESIS_AUTH_AUDIENCE ?? GENESIS_CLI_REGISTRATION.audience, authApi: LIFEID_ISSUER, fetch: f };
+}
+function registration(c) {
+    if (c.authApi !== LIFEID_ISSUER || !c.productId || !c.redirectUri || !c.audience) {
+        throw new Error('One account native login is not admitted here. Configure GENESIS_AUTH_PRODUCT, GENESIS_AUTH_REDIRECT_URI and GENESIS_AUTH_AUDIENCE from the registered One account profile, or use GENESIS_API_KEY.');
+    }
+    const r = { productId: c.productId, redirectUri: c.redirectUri, audience: c.audience };
+    validateRegistration(r);
+    return r;
+}
+export async function startLogin(c, options = {}) {
+    return startNativeAttempt(registration(c), options);
+}
+function object(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v) ? v : undefined;
+}
+function tokenClaims(token) {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3 || !parts.every(p => /^[A-Za-z0-9_-]+$/.test(p)) || token.length > 16_384)
+            return undefined;
+        return object(JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8')));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Scheduling/consistency only. The One account server and Genesis verifier own authority. */
+export function jwtExp(token) {
+    const exp = tokenClaims(token)?.exp;
+    return typeof exp === 'number' && Number.isSafeInteger(exp) ? exp : undefined;
+}
+function id(v, prefix) {
+    return typeof v === 'string' && new RegExp(`^${prefix}_[0-9A-HJKMNP-TV-Z]{26}$`).test(v);
+}
+function secret(v) {
+    return typeof v === 'string' && v.length > 0 && v.length <= 16_384 && !/[\s\x00-\x1f\x7f]/.test(v);
+}
+class LifeIdRequestError extends Error {
+}
+function invalidEnvelope() { throw new LifeIdRequestError('One account returned an invalid or mismatched session. Run `genesis login` again.'); }
+export function parseLifeSession(c, value, now = Date.now() / 1000) {
+    const r = registration(c);
+    const body = object(value), s = object(body?.session), p = object(body?.principal);
+    if (!s || !p || p.kind !== 'human' || !id(p.id, 'h') || s.principalKind !== 'human'
+        || !id(s.id, 'sess') || !id(s.organizationId, 'o') || s.issuer !== LIFEID_ISSUER
+        || s.audience !== r.audience || !secret(s.accessToken) || !secret(body?.refresh_token)
+        || typeof s.issuedAt !== 'string' || typeof s.expiresAt !== 'string')
+        invalidEnvelope();
+    const issued = Date.parse(s.issuedAt) / 1000, expires = Date.parse(s.expiresAt) / 1000;
+    const claims = tokenClaims(s.accessToken);
+    const exp = jwtExp(s.accessToken);
+    const audiences = typeof claims?.aud === 'string' ? [claims.aud] : claims?.aud;
+    if (!Number.isFinite(issued) || !Number.isFinite(expires) || issued > now + 60 || expires <= now || expires <= issued
+        || !claims || !exp || exp <= now || claims.iss !== LIFEID_ISSUER || !Array.isArray(audiences)
+        || !audiences.every(a => typeof a === 'string') || !audiences.includes(r.audience)
+        || claims.kind !== 'human' || claims.sid !== s.id || claims.sub !== p.id || claims.tid !== p.id || claims.org !== s.organizationId
+        || (s.tenantId !== undefined && s.tenantId !== null && s.tenantId !== p.id)
+        || claims.cnf !== undefined || claims.cap !== undefined || claims.obo !== undefined)
+        invalidEnvelope();
+    // The One account scope is the principal; the selected organization stays separate.
+    // Optional response projections are not required to retain committed rotation.
+    return { access_token: s.accessToken, refresh_token: body.refresh_token,
+        user: { id: p.id, ...(typeof p.email === 'string' ? { email: p.email } : {}) },
+        organization_id: s.organizationId, expires_at: Math.min(expires, exp), client_id: r.productId,
+        auth: { kind: 'lifeid-bridge', issuer: LIFEID_ISSUER, audience: r.audience, product_id: r.productId,
+            redirect_uri: r.redirectUri, principal_id: p.id, session_id: s.id } };
+}
+/** Bound headers AND body, forbid redirects, and never echo a provider payload. */
+async function post(c, path, body, signal) {
+    registration(c);
+    if (signal?.aborted)
+        throw new LifeIdRequestError('One account request cancelled. No automatic retry was made.');
+    const controller = new AbortController();
+    let reader;
+    let response;
+    let rejectDeadline;
+    const deadline = new Promise((_, reject) => { rejectDeadline = reject; });
+    const abort = () => { controller.abort(); rejectDeadline(new LifeIdRequestError('One account request cancelled. No automatic retry was made.')); };
+    const timer = setTimeout(() => {
+        controller.abort();
+        rejectDeadline(new LifeIdRequestError('One account request timed out. No automatic retry was made.'));
+    }, 15_000);
+    signal?.addEventListener('abort', abort, { once: true });
+    if (signal?.aborted)
+        abort();
+    try {
+        return await Promise.race([deadline, (async () => {
+                if (controller.signal.aborted)
+                    throw new LifeIdRequestError('One account request cancelled.');
+                response = await c.fetch(`${LIFEID_ISSUER}${path}`, { method: 'POST', headers: { 'content-type': 'application/json', accept: 'application/json' },
+                    body: JSON.stringify(body), redirect: 'error', cache: 'no-store', signal: controller.signal });
+                if (controller.signal.aborted) {
+                    void response.body?.cancel().catch(() => { });
+                    throw new LifeIdRequestError('One account request cancelled.');
+                }
+                if (!response.ok || !/^application\/json(?:;|$)/i.test(response.headers.get('content-type') ?? '')) {
+                    void response.body?.cancel().catch(() => { });
+                    throw new LifeIdRequestError(`One account request failed (${response.status}). Run \`genesis login\` again.`);
+                }
+                reader = response.body?.getReader();
+                if (!reader)
+                    invalidEnvelope();
+                const chunks = [];
+                let size = 0;
+                while (true) {
+                    const part = await reader.read();
+                    if (part.done)
+                        break;
+                    size += part.value.byteLength;
+                    if (size > 32_768) {
+                        void reader.cancel().catch(() => { });
+                        invalidEnvelope();
+                    }
+                    chunks.push(part.value);
+                }
+                try {
+                    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                }
+                catch {
+                    invalidEnvelope();
+                }
+            })()]);
+    }
+    catch (error) {
+        if (error instanceof LifeIdRequestError)
+            throw error;
+        throw new Error('One account transport failed. No automatic retry was made.');
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', abort);
+        if (controller.signal.aborted)
+            void reader?.cancel().catch(() => { });
+    }
+}
+export async function completeLogin(c, attempt) {
+    try {
+        const r = registration(c);
+        if (r.productId !== attempt.registration.productId || r.redirectUri !== attempt.registration.redirectUri
+            || r.audience !== attempt.registration.audience)
+            throw new Error('One account login registration changed.');
+        const code = await attempt.code;
+        const body = await post(c, '/v4/lifeid/exchange', { life_code: code, product_id: r.productId,
+            redirect_uri: r.redirectUri, code_verifier: attempt.codeVerifier }, attempt.signal);
+        return parseLifeSession(c, body);
+    }
+    finally {
+        attempt.close();
+    }
+}
+function requireSaved(c, s) {
+    if (s.auth?.kind === 'lifeid-device') {
+        requireDeviceSaved(s);
+        return;
+    }
+    const r = registration(c), a = s.auth;
+    if (!a || a.kind !== 'lifeid-bridge' || a.issuer !== LIFEID_ISSUER || a.audience !== r.audience
+        || a.product_id !== r.productId || a.redirect_uri !== r.redirectUri || s.client_id !== r.productId
+        || !id(s.organization_id, 'o') || !id(a.principal_id, 'h') || !id(a.session_id, 'sess')) {
+        throw new Error('Saved login is not an admitted One account bridge session. Run `genesis login` again.');
+    }
+    const claims = tokenClaims(s.access_token), aud = claims?.aud;
+    if (!claims || claims.iss !== a.issuer || !(aud === a.audience || (Array.isArray(aud) && aud.includes(a.audience)))
+        || claims.kind !== 'human' || claims.sid !== a.session_id || claims.sub !== a.principal_id || claims.tid !== a.principal_id
+        || claims.org !== s.organization_id || claims.cnf !== undefined || claims.cap !== undefined || claims.obo !== undefined) {
+        throw new Error('Saved One account session is inconsistent. Run `genesis login` again.');
+    }
+}
+export async function refresh(c, s, organizationId) {
+    requireSaved(c, s);
+    if (s.auth?.kind === 'lifeid-device') {
+        if (organizationId && organizationId !== s.organization_id) {
+            throw new Error('Changing organization requires a new verified One account login; refresh cannot select an organization.');
+        }
+        return refreshDeviceLogin(c, s);
+    }
+    if (organizationId && organizationId !== s.organization_id) {
+        throw new Error('Changing organization requires a new verified One account login; refresh cannot select an organization.');
+    }
+    if (!secret(s.refresh_token))
+        throw new Error('Session expired. Run `genesis login`.');
+    const n = parseLifeSession(c, await post(c, '/v4/auth/refresh', { refresh_token: s.refresh_token }));
+    if (n.organization_id !== s.organization_id || n.auth?.principal_id !== s.auth?.principal_id)
+        invalidEnvelope();
+    return n;
+}
+const rotations = new WeakMap();
+/** Queue before the first await, so parallel selection and refresh cannot use
+ * the same spent credential. A failed predecessor does not trigger a retry. */
+function serialize(store, run) {
+    const previous = rotations.get(store);
+    const pending = previous ? previous.then(run) : Promise.resolve().then(run);
+    rotations.set(store, pending);
+    return pending.finally(() => { if (rotations.get(store) === pending)
+        rotations.delete(store); });
+}
+async function commit(store, value) {
+    try {
+        await store.set(value);
+    }
+    catch {
+        throw new Error('The returned One account session could not be saved. No automatic retry was made.');
+    }
+}
+async function currentLogin(c, store) {
+    const saved = await store.get();
+    if (!saved)
+        throw new Error('Run `genesis login` before selecting a context.');
+    requireSaved(c, saved);
+    return saved;
+}
+function needsRefresh(saved, now) {
+    return Math.min(saved.expires_at ?? 0, jwtExp(saved.access_token) ?? 0) - 60 <= now;
+}
+/** Commit both replacement credentials through the existing atomic keychain entry. */
+export async function selectSavedContext(c, store, selection, signal) {
+    const requested = { ...selection };
+    return serialize(store, async () => {
+        let saved;
+        const response = await selectGenesisContext(requested, { signal, fetch: c.fetch, credential: async () => {
+                signal?.throwIfAborted();
+                saved = await currentLogin(c, store);
+                if (needsRefresh(saved, Date.now() / 1000)) {
+                    saved = await refresh(c, saved);
+                    await commit(store, saved);
+                }
+                signal?.throwIfAborted();
+                return saved.access_token;
+            } });
+        const next = parseLifeSession(c, response);
+        if (next.auth?.principal_id !== saved?.auth?.principal_id || next.organization_id !== requested.organizationId)
+            invalidEnvelope();
+        await commit(store, next);
+        return next;
+    });
+}
+/** OS-keychain bridge session; one committed rotation per store, never raw AuthKit. */
+export function savedLoginProvider(c, store, now = () => Date.now() / 1000) {
+    return async () => {
+        const mutation = rotations.get(store);
+        if (mutation)
+            return (await mutation).access_token;
+        const saved = await store.get();
+        if (!saved)
+            return undefined;
+        requireSaved(c, saved);
+        const newer = rotations.get(store);
+        if (newer)
+            return (await newer).access_token;
+        if (!needsRefresh(saved, now()))
+            return saved.access_token;
+        return (await serialize(store, async () => {
+            const current = await currentLogin(c, store);
+            if (!needsRefresh(current, now()))
+                return current;
+            const next = await refresh(c, current);
+            await commit(store, next);
+            return next;
+        })).access_token;
+    };
+}

package/dist/beacons.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { Genesis } from '@onesi/genesis';
+export declare function registerBeacons(program: Command, client: () => Promise<Genesis>, emit: (data: unknown, pretty: () => string) => void): void;

package/dist/beacons.js

@@ -0,0 +1,94 @@
+import { readFile } from 'node:fs/promises';
+import { createPrivateKey, sign } from 'node:crypto';
+export function registerBeacons(program, client, emit) {
+    const beacons = program.command('beacons').description('Beacons: Agent-native mesh');
+    const fleets = beacons.command('fleets').description('Fleet metadata and policy in your verified selection');
+    fleets.command('list').description('List actual fleets in the current authorized Sandbox scope').action(async () => {
+        const result = await (await client()).beacons.fleets.list();
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    fleets.command('rename <fleet-id>').requiredOption('--name <name>', 'Fleet name, at most 128 UTF-8 bytes').action(async (id, opts) => {
+        const result = await (await client()).beacons.fleets.update(id, { name: opts.name });
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    fleets.command('peers <fleet-id>').description('List actual peers, including durable revocation state').action(async (id) => {
+        const result = await (await client()).beacons.fleets.peers(id);
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    const policy = fleets.command('policy').description('Future enrollment admission; does not grant permissions or revoke devices');
+    policy.command('get <fleet-id>').action(async (id) => {
+        const result = await (await client()).beacons.fleets.policy.get(id);
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    policy.command('set <fleet-id>').requiredOption('--device-enrollment <mode>', 'allowed_with_permission or paused')
+        .option('--max-devices <count>', 'Integer 1–10000; omit to save the policy without a device cap')
+        .action(async (id, opts) => {
+        if (opts.deviceEnrollment !== 'allowed_with_permission' && opts.deviceEnrollment !== 'paused')
+            throw new Error('Invalid device enrollment mode.');
+        if (opts.maxDevices !== undefined && !/^[1-9][0-9]{0,4}$/.test(opts.maxDevices))
+            throw new Error('Invalid maximum device count.');
+        const result = await (await client()).beacons.fleets.policy.update(id, {
+            device_enrollment: opts.deviceEnrollment,
+            ...(opts.maxDevices === undefined ? {} : { max_devices: Number(opts.maxDevices) }),
+        });
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    fleets.command('provision').requiredOption('--request-id <uuid>', 'Stable UUID; reuse with the same name on retry')
+        .option('--name <name>', 'Optional fleet name')
+        .action(async (opts) => {
+        const result = await (await client()).beacons.fleets.provision(opts.requestId, opts.name === undefined ? {} : { name: opts.name });
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    const devices = beacons.command('devices').description('Manage Bridge devices in your signed-in organization');
+    devices.command('challenge <fleet-id>').requiredOption('--proof-key <key>', 'Base64url Ed25519 public key').requiredOption('--tunnel-key <key>', 'Base64url WireGuard public key').option('--transport <transport>', 't1_full or t2_sandboxed', 't1_full')
+        .action(async (fleetId, opts) => {
+        if (opts.transport !== 't1_full' && opts.transport !== 't2_sandboxed')
+            throw new Error('Unsupported device transport.');
+        const result = await (await client()).beacons.devices.challenge({ fleet_id: fleetId, proof_key: opts.proofKey, tunnel_key: opts.tunnelKey, transport: opts.transport });
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    devices.command('enroll <challenge-file>').requiredOption('--key-file <path>', 'Local Ed25519 PEM private key; never uploaded')
+        .action(async (challengeFile, opts) => {
+        const challenge = JSON.parse(await readFile(challengeFile, 'utf8'));
+        const fields = ['version', 'id', 'nonce', 'issuer', 'organization', 'principal', 'workspace', 'project', 'environment', 'binding_revision', 'transport', 'fleet_id', 'proof_key', 'tunnel_key', 'issued_at', 'expires_at'];
+        if (Object.keys(challenge).length !== fields.length || fields.some(field => challenge[field] === undefined))
+            throw new Error('Invalid challenge file.');
+        const canonical = Object.fromEntries(fields.map(field => [field, challenge[field]]));
+        const key = createPrivateKey(await readFile(opts.keyFile));
+        if (key.asymmetricKeyType !== 'ed25519')
+            throw new Error('An Ed25519 device key is required.');
+        const signature = sign(null, Buffer.from('Genesis Beacons device enrollment v1\n' + JSON.stringify(canonical)), key).toString('base64url');
+        const result = await (await client()).beacons.devices.enroll({ challenge, signature });
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    devices.command('revocations <id>').description('Poll durable transport teardown commands').action(async (id) => {
+        const result = await (await client()).beacons.devices.revocations(id);
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    devices.command('ack <id> <version>').requiredOption('--action <action>', 'Applied interface_torn_down or peer_key_removed; apply transport action first').action(async (id, version, opts) => {
+        const numeric = Number(version);
+        if (!Number.isSafeInteger(numeric) || numeric < 1)
+            throw new Error('Invalid revocation version.');
+        if (opts.action !== 'interface_torn_down' && opts.action !== 'peer_key_removed')
+            throw new Error('Invalid transport action.');
+        const result = await (await client()).beacons.devices.acknowledge(id, numeric, { action: opts.action });
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    devices.command('list', { isDefault: true }).action(async () => {
+        const result = await (await client()).beacons.devices.list();
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    devices.command('update <id>').option('--name <name>', 'Device name').option('--nickname <nickname...>', 'Replace nicknames').option('--clear-nicknames', 'Remove all nicknames')
+        .action(async (id, opts) => {
+        if (opts.clearNicknames && opts.nickname)
+            throw new Error('Choose --nickname or --clear-nicknames.');
+        if (opts.name === undefined && opts.nickname === undefined && !opts.clearNicknames)
+            throw new Error('Supply --name, --nickname or --clear-nicknames.');
+        const result = await (await client()).beacons.devices.update(id, { ...(opts.name === undefined ? {} : { name: opts.name }), ...(opts.clearNicknames ? { nicknames: [] } : opts.nickname ? { nicknames: opts.nickname } : {}) });
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    devices.command('revoke <id>').description('Request durable mesh teardown').action(async (id) => {
+        const result = await (await client()).beacons.devices.revoke(id);
+        emit(result ?? { status: 'revoked' }, () => JSON.stringify(result ?? { status: 'revoked' }, null, 2));
+    });
+}

package/dist/device-login.d.ts

@@ -0,0 +1,25 @@
+import type { SavedLogin } from './store.js';
+/** RFC 8628 device grant against One account, for agents and machines without a local browser. */
+export declare const DEVICE_CLIENT_ID = "genesis-cli-device";
+export declare const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+export interface DeviceConfig {
+    fetch: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface DeviceStart {
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    expiresIn: number;
+    interval: number;
+    /** Secret polled by this process; never printed. */
+    readonly deviceCode: string;
+}
+export declare function startDeviceLogin(c: DeviceConfig, signal?: AbortSignal): Promise<DeviceStart>;
+/** Saved session from an OAuth token response. Authority stays with the One account verifier. */
+export declare function parseDeviceTokens(body: Record<string, unknown>, now?: number): SavedLogin;
+/** Poll until approved, denied or expired, honouring `interval` and `slow_down`. */
+export declare function completeDeviceLogin(c: DeviceConfig, start: DeviceStart, signal?: AbortSignal): Promise<SavedLogin>;
+/** Rotate a device session through the OAuth refresh grant of the same public client. */
+export declare function refreshDeviceLogin(c: DeviceConfig, saved: SavedLogin): Promise<SavedLogin>;
+export declare function requireDeviceSaved(s: SavedLogin): void;

package/dist/device-login.js

@@ -0,0 +1,173 @@
+import { LIFEID_ISSUER } from './lifeid-native.js';
+import { errorToken } from '@onesi/genesis';
+/** RFC 8628 device grant against One account, for agents and machines without a local browser. */
+export const DEVICE_CLIENT_ID = 'genesis-cli-device';
+export const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+const DEVICE_SCOPE = 'openid offline_access email profile';
+const MAX_BODY = 32_768;
+class DeviceLoginError extends Error {
+}
+function object(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v) ? v : undefined;
+}
+function secret(v) {
+    return typeof v === 'string' && v.length > 0 && v.length <= 16_384 && !/[\s\x00-\x1f\x7f]/.test(v);
+}
+function claimsOf(token) {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3 || !parts.every(p => /^[A-Za-z0-9_-]+$/.test(p)))
+            return undefined;
+        return object(JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8')));
+    }
+    catch {
+        return undefined;
+    }
+}
+const ISSUER_HOST = new URL(LIFEID_ISSUER).host;
+/** https on exactly the issuer's host (and port), with no userinfo or control characters. */
+function onIssuer(u) {
+    if (typeof u !== 'string' || u.length > 2048 || /[\s\x00-\x1f\x7f-\x9f]/.test(u))
+        return false;
+    try {
+        const url = new URL(u);
+        return url.protocol === 'https:' && url.host === ISSUER_HOST && url.username === '' && url.password === '' && !/@/.test(u.split(/[/?#]/, 3)[2] ?? '');
+    }
+    catch {
+        return false;
+    }
+}
+function invalid() { throw new DeviceLoginError('One account returned an invalid device login response. Run `genesis login --device` again.'); }
+/** Form POST to One account: bounded body, no redirects, 15s deadline, and no response echo. */
+async function postForm(c, path, form, signal) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    const timer = setTimeout(abort, 15_000);
+    signal?.addEventListener('abort', abort, { once: true });
+    try {
+        const response = await c.fetch(`${LIFEID_ISSUER}${path}`, {
+            method: 'POST', redirect: 'error', cache: 'no-store', signal: controller.signal,
+            headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+            body: new URLSearchParams(form).toString(),
+        });
+        if (!/^application\/json(?:;|$)/i.test(response.headers.get('content-type') ?? '')) {
+            void response.body?.cancel().catch(() => { });
+            throw new DeviceLoginError(`One account request failed (${response.status}).`);
+        }
+        const reader = response.body?.getReader();
+        if (!reader)
+            invalid();
+        const chunks = [];
+        let size = 0;
+        for (;;) {
+            const part = await reader.read();
+            if (part.done)
+                break;
+            size += part.value.byteLength;
+            if (size > MAX_BODY) {
+                void reader.cancel().catch(() => { });
+                invalid();
+            }
+            chunks.push(part.value);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        }
+        catch {
+            invalid();
+        }
+        return { status: response.status, body: object(parsed) ?? invalid() };
+    }
+    catch (error) {
+        if (error instanceof DeviceLoginError)
+            throw error;
+        if (signal?.aborted)
+            throw new DeviceLoginError('One account device login cancelled.');
+        throw new DeviceLoginError('One account transport failed. No automatic retry was made.');
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', abort);
+    }
+}
+export async function startDeviceLogin(c, signal) {
+    const { status, body } = await postForm(c, '/v4/oauth/device_authorization', { client_id: DEVICE_CLIENT_ID, scope: DEVICE_SCOPE }, signal);
+    if (status !== 200)
+        throw new DeviceLoginError(`One account refused the device login (${status}).`);
+    const { device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval } = body;
+    if (!secret(device_code) || typeof user_code !== 'string' || !/^[BCDFGHJKLMNPQRSTVWXZ]{4}-[BCDFGHJKLMNPQRSTVWXZ]{4}$/.test(user_code)
+        || typeof expires_in !== 'number' || !Number.isInteger(expires_in) || expires_in < 1 || expires_in > 3600
+        || typeof interval !== 'number' || !Number.isInteger(interval) || interval < 1 || interval > 60)
+        invalid();
+    if (!onIssuer(verification_uri) || !onIssuer(verification_uri_complete)) {
+        throw new DeviceLoginError(`One account returned a verification URL outside ${ISSUER_HOST}. Refusing to show it; run \`genesis login --device\` again.`);
+    }
+    return { deviceCode: device_code, userCode: user_code, verificationUri: verification_uri,
+        verificationUriComplete: verification_uri_complete, expiresIn: expires_in, interval };
+}
+/** Saved session from an OAuth token response. Authority stays with the One account verifier. */
+export function parseDeviceTokens(body, now = Date.now() / 1000) {
+    const access = body.access_token, refresh = body.refresh_token;
+    if (body.token_type !== 'Bearer' || !secret(access) || !secret(refresh))
+        invalid();
+    const claims = claimsOf(access);
+    const exp = claims?.exp;
+    if (!claims || claims.iss !== LIFEID_ISSUER || claims.kind !== 'human' || typeof claims.sub !== 'string'
+        || typeof claims.sid !== 'string' || typeof exp !== 'number' || exp <= now
+        || claims.cnf !== undefined || claims.cap !== undefined || claims.obo !== undefined)
+        invalid();
+    const org = typeof claims.org === 'string' ? claims.org : undefined;
+    const email = typeof claims.email === 'string' ? claims.email : undefined;
+    return { access_token: access, refresh_token: refresh, user: { id: claims.sub, ...(email ? { email } : {}) },
+        ...(org ? { organization_id: org } : {}), expires_at: exp, client_id: DEVICE_CLIENT_ID,
+        auth: { kind: 'lifeid-device', issuer: LIFEID_ISSUER, client_id: DEVICE_CLIENT_ID, principal_id: claims.sub, session_id: claims.sid } };
+}
+/** Poll until approved, denied or expired, honouring `interval` and `slow_down`. */
+export async function completeDeviceLogin(c, start, signal) {
+    const sleep = c.sleep ?? ((ms) => new Promise(r => setTimeout(r, ms)));
+    const deadline = Date.now() + start.expiresIn * 1000;
+    let interval = start.interval;
+    for (;;) {
+        await sleep(interval * 1000);
+        if (signal?.aborted)
+            throw new DeviceLoginError('One account device login cancelled.');
+        if (Date.now() > deadline)
+            throw new DeviceLoginError('The device code expired. Run `genesis login --device` again.');
+        const { status, body } = await postForm(c, '/v4/oauth/token', { grant_type: DEVICE_GRANT, client_id: DEVICE_CLIENT_ID, device_code: start.deviceCode }, signal);
+        if (status === 200)
+            return parseDeviceTokens(body);
+        // RFC 8628 string errors from Auth; the envelope form (error.code) is accepted too.
+        switch (errorToken(body)) {
+            case 'authorization_pending': continue;
+            case 'slow_down':
+                interval = Math.min(interval + 5, 60);
+                continue;
+            case 'access_denied': throw new DeviceLoginError('Sign-in was denied on the verification page.');
+            case 'expired_token': throw new DeviceLoginError('The device code expired. Run `genesis login --device` again.');
+            default: throw new DeviceLoginError(`One account refused the device login (${status}). Run \`genesis login --device\` again.`);
+        }
+    }
+}
+/** Rotate a device session through the OAuth refresh grant of the same public client. */
+export async function refreshDeviceLogin(c, saved) {
+    if (!secret(saved.refresh_token))
+        throw new DeviceLoginError('Session expired. Run `genesis login --device`.');
+    const { status, body } = await postForm(c, '/v4/oauth/token', { grant_type: 'refresh_token', client_id: DEVICE_CLIENT_ID, refresh_token: saved.refresh_token });
+    if (status !== 200)
+        throw new DeviceLoginError(`One account refresh failed (${status}). Run \`genesis login --device\` again.`);
+    const next = parseDeviceTokens(body);
+    if (next.auth?.principal_id !== saved.auth?.principal_id)
+        invalid();
+    return next;
+}
+export function requireDeviceSaved(s) {
+    const a = s.auth;
+    const claims = claimsOf(s.access_token);
+    if (!a || a.kind !== 'lifeid-device' || a.issuer !== LIFEID_ISSUER || a.client_id !== DEVICE_CLIENT_ID || s.client_id !== DEVICE_CLIENT_ID
+        || !claims || claims.iss !== a.issuer || claims.kind !== 'human' || claims.sub !== a.principal_id || claims.sid !== a.session_id
+        || (s.organization_id !== undefined && claims.org !== s.organization_id)
+        || claims.cnf !== undefined || claims.cap !== undefined || claims.obo !== undefined) {
+        throw new Error('Saved One account device session is inconsistent. Run `genesis login --device` again.');
+    }
+}

package/dist/dials.d.ts

@@ -0,0 +1,7 @@
+import { Command } from 'commander';
+import type { Genesis } from '@onesi/genesis';
+export declare function registerDials(program: Command, dependencies: {
+    client: () => Promise<Genesis>;
+    orgId: (client: Genesis) => Promise<string>;
+    emit: (data: unknown, pretty: () => string) => void;
+}): void;