@onesi/genesis-cli 0.0.1-stage → 0.2.0

package/README.md

@@ -0,0 +1,64 @@
+# @onesi/genesis-cli
+
+`genesis`, the OneOS command line. It works against the Genesis API at `https://os.one.ml/api`.
+
+```sh
+npx -y @onesi/genesis-cli@0.2.0 --help
+```
+
+## First run
+
+```sh
+npx -y @onesi/genesis-cli    # or: npm i -g @onesi/genesis-cli, then genesis
+```
+
+On a terminal, the first `genesis` opens `genesis setup`: six steps, about a minute, each skippable and resumable.
+
+![genesis setup: the ONE logotype wakes as One's eye, then sign-in, your project, your agents and a live status call](../../docs/media/genesis-setup/genesis-setup.gif)
+
+1. **Sign in with One**, in this browser or with a code on any device.
+2. **Organization, project and environment**, picked from your own (Sandbox).
+3. **An API key** for CI and other machines, only if you want one: read-only, your access, or chosen scopes; shown once or kept in Blinds.
+4. **Your agents**: the Genesis MCP server added to Claude Code, Claude Desktop, Cursor, VS Code, Windsurf or Codex. You see every file or command first; JSON files keep their other servers and a `.genesis-backup` copy.
+5. **A first live call**: every service's state and latency from the gateway.
+6. **What to do next.**
+
+Enter takes the default, `s` skips, Ctrl-C pauses. `genesis setup` picks up at the first open step, `genesis setup <step>` redoes one (`signin`, `context`, `key`, `mcp`, `try`, `next`), and `genesis setup --restart` starts over. `genesis setup --json` reports progress for scripts. Progress lives in `~/.config/genesis/setup.json` (no credentials; the login stays in the OS keychain).
+
+Setup draws with what your terminal can do, and asks it first: truecolor with edges blended against your real background (or your own ink when the terminal does not say), synchronized output, OSC 8 links, tab progress, and a desktop notification when sign-in finishes while you are in the browser. It is still with `NO_COLOR`, `TERM=dumb`, in CI or a pipe, with `--no-animation` or `GENESIS_REDUCED_MOTION=1`, and when your system asks for reduced motion. `--screen-reader` (or `GENESIS_SCREEN_READER=1`, or VoiceOver running) gives linear output with numbered choices.
+
+| Signing in with a code | Still, with `NO_COLOR` and `--no-animation` |
+|---|---|
+| ![Device sign-in beside One's eye](../../docs/media/genesis-setup/genesis-setup-device.gif) | ![The same setup, still and uncoloured](../../docs/media/genesis-setup/genesis-setup-still.gif) |
+
+The recordings were made with `--screencast` against the live services; `docs/media/genesis-setup/*.tape` are the [VHS](https://github.com/charmbracelet/vhs) scripts. `--sound` adds a soft chime. `--screencast` (or `GENESIS_SCREENCAST=1`) masks account names, emails and IDs, for recording demos. Only `genesis setup` and a bare `genesis` load any of this; other commands start exactly as fast as before.
+
+## 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 instances 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,162 @@
+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));
+    });
+    fleets.command('get <fleet-id>').description('Read one fleet in the current authorized scope').action(async (id) => {
+        const result = await (await client()).beacons.fleets.get(id);
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    fleets.command('dns <fleet-id>').description('Mesh DNS map: one A record per live peer').action(async (id) => {
+        const result = await (await client()).beacons.fleets.dns(id);
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    fleets.command('discovery <fleet-id>').description("Mesh discovery map: live peers' public keys, DNS and relay map").action(async (id) => {
+        const result = await (await client()).beacons.fleets.discovery(id);
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    fleets.command('client-profile <fleet-id> <platform>').description('beacons-agent profile: linux, macos, windows, ios or android').action(async (id, platform) => {
+        const result = await (await client()).beacons.fleets.clientProfile(id, platform);
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    fleets.command('wireguard-config <fleet-id> <peer-id>').description("One peer's WireGuard config: other peers' public keys, never a private key").action(async (id, peer) => {
+        const result = await (await client()).beacons.fleets.wireguardConfig(id, peer);
+        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));
+    });
+    const resources = fleets.command('resources').description('Fleet configuration records: gateways, private-gateways, sims (configuration only)');
+    const family = (value) => {
+        if (!['gateways', 'private-gateways', 'sims'].includes(value))
+            throw new Error('Family must be gateways, private-gateways or sims.');
+        return value;
+    };
+    const config = (value) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(value);
+        }
+        catch {
+            throw new Error('--config must be a JSON object.');
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            throw new Error('--config must be a JSON object.');
+        return parsed;
+    };
+    resources.command('list <fleet-id> <family>').description('List the fleet\'s records of one family').action(async (id, kind) => {
+        const result = await (await client()).beacons.fleets.resources.list(id, family(kind));
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    resources.command('create <fleet-id> <family>').description('Create one record; not idempotent')
+        .requiredOption('--name <name>', 'Record name, at most 128 UTF-8 bytes')
+        .requiredOption('--status <status>', 'active, inactive, disabled or pending')
+        .option('--config <json>', 'Family config object, e.g. \'{"type":"relay","routes":["10.0.0.0/24"]}\'', '{}')
+        .action(async (id, kind, opts) => {
+        const result = await (await client()).beacons.fleets.resources.create(id, family(kind), { name: opts.name, status: opts.status, config: config(opts.config) });
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    resources.command('update <fleet-id> <family> <resource-id>').description('Replace the given fields of one record')
+        .option('--name <name>', 'New name').option('--status <status>', 'active, inactive, disabled or pending')
+        .option('--config <json>', 'Replacement family config object')
+        .action(async (id, kind, resourceId, opts) => {
+        if (opts.name === undefined && opts.status === undefined && opts.config === undefined)
+            throw new Error('Supply --name, --status or --config.');
+        const result = await (await client()).beacons.fleets.resources.update(id, family(kind), resourceId, {
+            ...(opts.name === undefined ? {} : { name: opts.name }), ...(opts.status === undefined ? {} : { status: opts.status }),
+            ...(opts.config === undefined ? {} : { config: config(opts.config) })
+        });
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    resources.command('delete <fleet-id> <family> <resource-id>').description('Delete one configuration record')
+        .action(async (id, kind, resourceId) => {
+        await (await client()).beacons.fleets.resources.delete(id, family(kind), resourceId);
+        const result = { deleted: resourceId };
+        emit(result, () => `Deleted ${resourceId}`);
+    });
+    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;