botanary 0.3.0 → 0.4.1

package/dist/src/commands/authority.js

@@ -0,0 +1,634 @@
+import { readFile } from 'node:fs/promises';
+import { submitIntent, describeSignOutcome } from './sign.js';
+import { group } from '../help/groups.js';
+import { printResult } from '../render/print.js';
+import { step } from '../progress.js';
+import { columns, dash, section, shortAddress } from '../render/kv.js';
+import { colors } from '../render/colors.js';
+import { confirmOrThrow, dryRunPayload, renderReview } from '../review.js';
+import { invalidArgs, notLoggedIn } from '../errors.js';
+/** Same duplication as `account.ts`/`tokens.ts` - see `sign.ts`'s own comment on why a shared helper
+ *  never gets pulled back out of sign.ts itself. */
+async function requireWalletToken(ctx) {
+    const session = await ctx.runtime.walletSession();
+    if (!session)
+        throw notLoggedIn();
+    return session.sessionToken;
+}
+async function reviewAndSubmit(ctx, title, rows, warnings, kind, params) {
+    if (ctx.dryRun) {
+        printResult(ctx, dryRunPayload(title, rows, warnings), () => renderReview('Dry run - nothing will be sent', rows, warnings));
+        return;
+    }
+    await confirmOrThrow(ctx, title, rows, warnings);
+    const outcome = await submitIntent(ctx, kind, params);
+    printResult(ctx, outcome.data, () => describeSignOutcome(outcome));
+}
+/** Same escape hatch `agent request --calls-file` established, and `wallet.ts`'s own `readJsonFile` -
+ *  duplicated per `sign.ts`'s own comment on why a shared helper never gets pulled back out. */
+async function readJsonFile(path, flag) {
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (e) {
+        throw invalidArgs(`Could not read ${flag} "${path}": ${e instanceof Error ? e.message : String(e)}`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw invalidArgs(`${flag} "${path}" is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+function findTopLevel(program, name) {
+    const cmd = program.commands.find((c) => c.name() === name);
+    if (!cmd) {
+        throw new Error(`authority.ts expected a top-level "${name}" command to already be registered - check registration order in cli.ts.`);
+    }
+    return cmd;
+}
+function renderGuardians(payload) {
+    const list = (Array.isArray(payload) ? payload : []);
+    if (!list.length) {
+        return `${section('Recovery guardians')}\n${colors.muted('  None installed - `botanary recovery install` to set up social recovery.')}`;
+    }
+    const rows = list.map((g) => [dash(g.id), dash(g.name), dash(g.kind), g.primary ? 'yes' : 'no', dash(g.addedAt)]);
+    return columns(['ID', 'NAME', 'KIND', 'PRIMARY', 'ADDED'], rows).length
+        ? [section('Recovery guardians'), columns(['ID', 'NAME', 'KIND', 'PRIMARY', 'ADDED'], rows)].join('\n')
+        : '';
+}
+function renderDevices(payload) {
+    const root = (payload ?? {});
+    const devices = Array.isArray(root.devices) ? root.devices : [];
+    const rows = devices.map((d) => [shortAddress(d.address), dash(d.label), d.isCurrentSigner ? 'yes' : 'no']);
+    return [
+        section('Devices'),
+        `  threshold ${dash(root.threshold)} of ${dash(root.deviceCount)}${root.deployed ? '' : ' (counterfactual)'}`,
+        devices.length ? columns(['ADDRESS', 'LABEL', 'THIS DEVICE'], rows) : colors.muted('  No devices enrolled.'),
+    ].join('\n');
+}
+function renderSigners(payload) {
+    const list = (Array.isArray(payload) ? payload : []);
+    if (!list.length) {
+        return `${section('Signers')}\n${colors.muted('  None enrolled yet.')}`;
+    }
+    const rows = list.map((s) => [String(s.index ?? '-'), dash(s.scheme), dash(s.address ?? s.credentialId)]);
+    return [section('Signers'), columns(['INDEX', 'SCHEME', 'ADDRESS / CREDENTIAL'], rows)].join('\n');
+}
+/**
+ * Recovery, signers, devices, panic, and the owner's verdict on an agent's request - every authority
+ * action the web app exposes outside the account/mandate groups already covered elsewhere. Every write
+ * here is a `submitIntent` call: an owner-signed op parked at `POST /sign-requests`, never a build route,
+ * never a local signature.
+ *
+ * `agents approve`/`agents deny` attach onto the `agents` Command `wallet.ts` already registers (its base
+ * action lists connected agents and pending requests) - registration order in cli.ts must put
+ * `registerWalletCommands` before `registerAuthorityCommands`.
+ */
+export function registerAuthorityCommands(program) {
+    // ---- recovery ------------------------------------------------------------------------------------
+    const recovery = group(program.command('recovery').description('Social recovery: guardians and the emergency signer-set replacement'), 'Wallet');
+    recovery
+        .command('status')
+        .description('The live guardian set on this account (GET /recovery/guardians)')
+        .action(async () => {
+        const ctx = program.opts().__ctx;
+        const token = await requireWalletToken(ctx);
+        const guardians = await step(ctx, 'Reading recovery guardians', () => ctx.runtime.api.get('/v1/recovery/guardians', token));
+        printResult(ctx, guardians, () => renderGuardians(guardians) || `${section('Recovery guardians')}\n${colors.muted('  None installed.')}`);
+    });
+    recovery
+        .command('install')
+        .description('Install social recovery with a guardian set and an M-of-N threshold')
+        .requiredOption('--guardian <address...>', 'A guardian EVM address - repeat for each (at least 2)')
+        .option('--threshold <n>', 'How many guardians must approve a recovery - at least 2')
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        if (!opts.guardian || opts.guardian.length < 2) {
+            throw invalidArgs('At least 2 --guardian addresses are required.', 'A single guardian could rotate the account unilaterally.');
+        }
+        const threshold = opts.threshold === undefined ? undefined : Number(opts.threshold);
+        if (threshold !== undefined && (!Number.isInteger(threshold) || threshold < 2)) {
+            throw invalidArgs(`--threshold must be an integer of at least 2, got ${JSON.stringify(opts.threshold)}.`);
+        }
+        const rows = [
+            { label: 'guardians', value: opts.guardian.join(', ') },
+            ...(threshold !== undefined ? [{ label: 'threshold', value: String(threshold) }] : []),
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this recovery install', rows, [], 'recovery.install', {
+            guardians: opts.guardian,
+            ...(threshold !== undefined ? { threshold } : {}),
+            ...(opts.accountId ? { accountId: opts.accountId } : {}),
+        });
+    });
+    const guardian = recovery.command('guardian').description('Add or remove one recovery guardian');
+    guardian
+        .command('add')
+        .description('Add a recovery guardian')
+        .requiredOption('--name <name>', 'A label for this guardian, e.g. "iPhone 15"')
+        .requiredOption('--kind <kind>', 'device or contact')
+        .requiredOption('--address <address>', 'The guardian\'s EVM address')
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        if (opts.kind !== 'device' && opts.kind !== 'contact') {
+            throw invalidArgs(`--kind must be "device" or "contact", got ${JSON.stringify(opts.kind)}.`);
+        }
+        const rows = [
+            { label: 'name', value: opts.name },
+            { label: 'kind', value: opts.kind },
+            { label: 'address', value: opts.address },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this guardian add', rows, [], 'recovery.guardian.add', {
+            name: opts.name,
+            guardianKind: opts.kind,
+            address: opts.address,
+            ...(opts.accountId ? { accountId: opts.accountId } : {}),
+        });
+    });
+    guardian
+        .command('remove <guardianId>')
+        .description('Remove a recovery guardian')
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (guardianId, opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const rows = [
+            { label: 'guardian', value: guardianId },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this guardian removal', rows, [], 'recovery.guardian.remove', {
+            guardianId,
+            ...(opts.accountId ? { accountId: opts.accountId } : {}),
+        });
+    });
+    recovery
+        .command('recover')
+        .description("Replace this account's whole signer set (the emergency lane - a guardian-signed rotation)")
+        .requiredOption('--new-signer <address...>', 'The complete new signer set - repeat for each')
+        .requiredOption('--new-threshold <n>', 'How many of the new signers must approve going forward')
+        .option('--op-count <n>', 'How many ops this recovery will produce - omit to let the backend size it')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        if (!opts.newSigner || opts.newSigner.length < 1) {
+            throw invalidArgs('At least one --new-signer address is required.');
+        }
+        const newThreshold = Number(opts.newThreshold);
+        if (!Number.isInteger(newThreshold) || newThreshold < 1) {
+            throw invalidArgs(`--new-threshold must be a positive integer, got ${JSON.stringify(opts.newThreshold)}.`);
+        }
+        const opCount = opts.opCount === undefined ? undefined : Number(opts.opCount);
+        if (opCount !== undefined && (!Number.isInteger(opCount) || opCount <= 0)) {
+            throw invalidArgs(`--op-count must be a positive integer, got ${JSON.stringify(opts.opCount)}.`);
+        }
+        const rows = [
+            { label: 'new signers', value: opts.newSigner.join(', ') },
+            { label: 'new threshold', value: String(newThreshold) },
+            { label: 'signed by', value: 'a guardian, in the emergency recovery flow' },
+        ];
+        const warnings = ['This replaces the whole signer set on this account.'];
+        await reviewAndSubmit(ctx, 'Review this recovery', rows, warnings, 'recovery.recover', {
+            newSigners: opts.newSigner,
+            newThreshold,
+            ...(opCount !== undefined ? { opCount } : {}),
+        });
+    });
+    // ---- signers (BotanaryPolicyValidator's own signer registry) -------------------------------------
+    const signers = group(program.command('signers').description("This account's enrolled signers (the v1 authority core)"), 'Wallet');
+    signers
+        .command('list')
+        .description("Every enrolled signer, by index (GET /account/signers)")
+        .action(async () => {
+        const ctx = program.opts().__ctx;
+        const token = await requireWalletToken(ctx);
+        const list = await step(ctx, 'Reading signers', () => ctx.runtime.api.get('/v1/account/signers', token));
+        printResult(ctx, list, () => renderSigners(list));
+    });
+    signers
+        .command('add')
+        .description('Enrol a new ECDSA signer on this chain')
+        .requiredOption('--address <address>', 'The new signer\'s EVM address')
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const rows = [
+            { label: 'address', value: opts.address },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this signer add', rows, [], 'policies.signer.add', {
+            address: opts.address,
+            ...(opts.accountId ? { accountId: opts.accountId } : {}),
+        });
+    });
+    signers
+        .command('remove')
+        .description('Remove a signer from this chain, by index')
+        .requiredOption('--index <index>', 'The signer\'s index - see `botanary signers list`')
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const index = Number(opts.index);
+        if (!Number.isInteger(index) || index < 0) {
+            throw invalidArgs(`--index must be a non-negative integer, got ${JSON.stringify(opts.index)}.`);
+        }
+        const rows = [
+            { label: 'index', value: String(index) },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this signer removal', rows, [], 'policies.signer.remove', {
+            index,
+            ...(opts.accountId ? { accountId: opts.accountId } : {}),
+        });
+    });
+    signers
+        .command('threshold')
+        .description('Set the account-wide signer approval threshold')
+        .requiredOption('--threshold <n>', 'How many enrolled signers must approve')
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const threshold = Number(opts.threshold);
+        if (!Number.isInteger(threshold) || threshold < 1) {
+            throw invalidArgs(`--threshold must be a positive integer, got ${JSON.stringify(opts.threshold)}.`);
+        }
+        const rows = [
+            { label: 'threshold', value: String(threshold) },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this threshold change', rows, [], 'policies.threshold', {
+            threshold,
+            ...(opts.accountId ? { accountId: opts.accountId } : {}),
+        });
+    });
+    signers
+        .command('trust-anchor')
+        .description("Mirror an issuer's currently-active signing key onto this account")
+        .option('--issuer <issuer>', 'Only "google" has a live JWKS source today', 'google')
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        if (opts.issuer !== undefined && opts.issuer !== 'google') {
+            throw invalidArgs(`--issuer must be "google" today, got ${JSON.stringify(opts.issuer)}.`);
+        }
+        const rows = [
+            { label: 'issuer', value: opts.issuer ?? 'google' },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this trust anchor mirror', rows, [], 'policies.trust_anchor', {
+            ...(opts.issuer ? { issuer: opts.issuer } : {}),
+            ...(opts.accountId ? { accountId: opts.accountId } : {}),
+        });
+    });
+    // `signers guardian` - BotanaryPolicyValidator's OWN guardian concept (a threshold over enrolled
+    // signer indexes), NOT `recovery guardian` above (SocialRecovery guardians, a different contract and
+    // route behind the same English word - see `sign-kinds.ts`'s own comment on the distinction).
+    const signersGuardian = signers
+        .command('guardian')
+        .description("Set BotanaryPolicyValidator's own guardian threshold over a subset of enrolled signers");
+    signersGuardian
+        .command('set')
+        .description('Set the policy-validator guardian threshold over a subset of enrolled signer indexes')
+        .option('--signer-index <index...>', 'An enrolled signer index to include - repeat for each; omit with --threshold 0 to opt out')
+        .requiredOption('--threshold <n>', 'How many of the listed indexes must approve - 0 opts out')
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const signerIndexes = (opts.signerIndex ?? []).map((raw) => {
+            const n = Number(raw);
+            if (!Number.isInteger(n) || n < 0) {
+                throw invalidArgs(`--signer-index must be a non-negative integer, got ${JSON.stringify(raw)}.`);
+            }
+            return n;
+        });
+        const threshold = Number(opts.threshold);
+        if (!Number.isInteger(threshold) || threshold < 0) {
+            throw invalidArgs(`--threshold must be a non-negative integer, got ${JSON.stringify(opts.threshold)}.`);
+        }
+        const rows = [
+            { label: 'signer indexes', value: signerIndexes.length ? signerIndexes.join(', ') : 'none' },
+            { label: 'threshold', value: String(threshold) },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this guardian threshold', rows, [], 'policies.guardian.set', {
+            signerIndexes,
+            threshold,
+            ...(opts.accountId ? { accountId: opts.accountId } : {}),
+        });
+    });
+    const signersPolicy = signers
+        .command('policy')
+        .description('Write or remove a conditional signing policy at a slot (BotanaryPolicyValidator)');
+    signersPolicy
+        .command('set')
+        .description('Write (or overwrite) the conditional signing policy at a slot')
+        .requiredOption('--slot <n>', 'Policy slot index')
+        .requiredOption('--approvals <n>', 'How many approvals this policy requires')
+        .requiredOption('--delay-seconds <seconds>', 'Timelock delay, in seconds, before this policy takes effect')
+        .option('--when-file <path>', 'JSON array of condition objects: [{ field, op, argOffset, value }] - omit for none')
+        .option('--signer-index <index...>', 'A signer index this policy accepts - repeat for each')
+        .option('--signer-key-ref <hex32...>', 'A signer key reference (bytes32 hex) this policy accepts - repeat for each')
+        .option('--inactive', 'Write this policy inactive rather than active')
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const slot = Number(opts.slot);
+        if (!Number.isInteger(slot) || slot < 0)
+            throw invalidArgs(`--slot must be a non-negative integer, got ${JSON.stringify(opts.slot)}.`);
+        const approvals = Number(opts.approvals);
+        if (!Number.isInteger(approvals) || approvals < 1) {
+            throw invalidArgs(`--approvals must be a positive integer, got ${JSON.stringify(opts.approvals)}.`);
+        }
+        const delaySeconds = Number(opts.delaySeconds);
+        if (!Number.isInteger(delaySeconds) || delaySeconds < 0) {
+            throw invalidArgs(`--delay-seconds must be a non-negative integer, got ${JSON.stringify(opts.delaySeconds)}.`);
+        }
+        const when = opts.whenFile ? await readJsonFile(opts.whenFile, '--when-file') : undefined;
+        if (when !== undefined && !Array.isArray(when))
+            throw invalidArgs('--when-file must contain a JSON array.');
+        const signerIndexes = opts.signerIndex?.map((raw) => {
+            const n = Number(raw);
+            if (!Number.isInteger(n) || n < 0)
+                throw invalidArgs(`--signer-index must be a non-negative integer, got ${JSON.stringify(raw)}.`);
+            return n;
+        });
+        const rows = [
+            { label: 'slot', value: String(slot) },
+            { label: 'approvals', value: String(approvals) },
+            { label: 'delay', value: `${delaySeconds}s` },
+            { label: 'active', value: opts.inactive ? 'no' : 'yes' },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this policy write', rows, [], 'policies.policy.set', {
+            slot,
+            approvals,
+            delaySeconds,
+            active: !opts.inactive,
+            ...(when !== undefined ? { when } : {}),
+            ...(signerIndexes?.length ? { signerIndexes } : {}),
+            ...(opts.signerKeyRef?.length ? { signerKeyRefs: opts.signerKeyRef } : {}),
+            ...(opts.accountId ? { accountId: opts.accountId } : {}),
+        });
+    });
+    signersPolicy
+        .command('remove')
+        .description('Remove the conditional signing policy at a slot')
+        .requiredOption('--slot <n>', 'Policy slot index')
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const slot = Number(opts.slot);
+        if (!Number.isInteger(slot) || slot < 0)
+            throw invalidArgs(`--slot must be a non-negative integer, got ${JSON.stringify(opts.slot)}.`);
+        const rows = [
+            { label: 'slot', value: String(slot) },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this policy removal', rows, [], 'policies.policy.remove', {
+            slot,
+            ...(opts.accountId ? { accountId: opts.accountId } : {}),
+        });
+    });
+    signers
+        .command('condition-set')
+        .description('Add or remove a condition-set member (BotanaryPolicyValidator)')
+        .requiredOption('--set-id <hex32>', 'The condition set id, a 32-byte hex value')
+        .requiredOption('--member <hex32>', 'The member to add or remove, a 32-byte hex value')
+        .option('--not-member', 'Remove the member instead of adding it')
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const isMember = !opts.notMember;
+        const rows = [
+            { label: 'set', value: opts.setId },
+            { label: 'member', value: opts.member },
+            { label: 'action', value: isMember ? 'add' : 'remove' },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this condition-set change', rows, [], 'policies.condition_set', {
+            setId: opts.setId,
+            member: opts.member,
+            isMember,
+            ...(opts.accountId ? { accountId: opts.accountId } : {}),
+        });
+    });
+    signers
+        .command('migrate')
+        .description("Upgrade this account's authority core onto BotanaryPolicyValidator (step 1 of 2)")
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const rows = [
+            { label: 'action', value: "upgrade this account's authority core (step 1 of 2)" },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        const warnings = [
+            'This is step 1 of 2. Step 2 (op-b) follows once this is signed, relayed and mined - not covered by this command yet.',
+        ];
+        await reviewAndSubmit(ctx, 'Review this authority-core migration', rows, warnings, 'policies.migrate', {
+            ...(opts.accountId ? { accountId: opts.accountId } : {}),
+        });
+    });
+    // ---- devices (OwnableValidator co-signer set) -----------------------------------------------------
+    const devices = group(program.command('devices').description('Co-signer devices on this account\'s OwnableValidator root'), 'Wallet');
+    devices
+        .command('list')
+        .description('The live device set and its M-of-N threshold (GET /account/devices)')
+        .action(async () => {
+        const ctx = program.opts().__ctx;
+        const token = await requireWalletToken(ctx);
+        const set = await step(ctx, 'Reading devices', () => ctx.runtime.api.get('/v1/account/devices', token));
+        printResult(ctx, set, () => renderDevices(set));
+    });
+    devices
+        .command('add')
+        .description('Add a device as a co-signer')
+        .requiredOption('--device <address>', 'The device\'s EVM address')
+        .option('--label <label>', 'A label for this device, e.g. "Work laptop"')
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const rows = [
+            { label: 'device', value: opts.device },
+            ...(opts.label ? [{ label: 'label', value: opts.label }] : []),
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this device add', rows, [], 'device.add', {
+            device: opts.device,
+            ...(opts.label ? { label: opts.label } : {}),
+            ...(opts.accountId ? { accountId: opts.accountId } : {}),
+        });
+    });
+    devices
+        .command('remove')
+        .description('Remove a device from the co-signer set')
+        .requiredOption('--device <address>', 'The device\'s EVM address')
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const rows = [
+            { label: 'device', value: opts.device },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this device removal', rows, [], 'device.remove', {
+            device: opts.device,
+            ...(opts.accountId ? { accountId: opts.accountId } : {}),
+        });
+    });
+    devices
+        .command('threshold')
+        .description('Set the M-of-N device signing threshold')
+        .requiredOption('--threshold <n>', 'How many devices must sign to move money or change rules')
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const threshold = Number(opts.threshold);
+        if (!Number.isInteger(threshold) || threshold < 1) {
+            throw invalidArgs(`--threshold must be a positive integer, got ${JSON.stringify(opts.threshold)}.`);
+        }
+        const rows = [
+            { label: 'threshold', value: String(threshold) },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this device threshold change', rows, [], 'device.threshold', {
+            threshold,
+            ...(opts.accountId ? { accountId: opts.accountId } : {}),
+        });
+    });
+    // ---- panic -----------------------------------------------------------------------------------------
+    const panic = group(program.command('panic').description('The panic freeze lane: any one listed device can freeze the account, gas-abstractedly'), 'Wallet');
+    panic
+        .command('install')
+        .description('Install the panic freeze lane (a 1-of-N session over the listed device keys)')
+        .option('--device-key <address...>', 'A device key to authorize - repeat for each; omit to use the account\'s own signer set')
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const rows = [
+            { label: 'device keys', value: opts.deviceKey?.length ? opts.deviceKey.join(', ') : "this account's own signer set" },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this panic-lane install', rows, [], 'panic.install', {
+            ...(opts.deviceKey?.length ? { deviceKeys: opts.deviceKey } : {}),
+            ...(opts.accountId ? { accountId: opts.accountId } : {}),
+        });
+    });
+    panic
+        .command('freeze')
+        .description('Freeze the account via the panic lane (any one listed device can sign)')
+        .option('--device-key <address...>', 'A device key to sign with - repeat for each; omit to use the account\'s own signer set')
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const rows = [
+            { label: 'action', value: 'freeze this account via the panic lane' },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        const warnings = ['This is the kill-switch. No further transfers will be authorized until you unfreeze.'];
+        await reviewAndSubmit(ctx, 'Review this panic freeze', rows, warnings, 'panic.freeze', {
+            ...(opts.deviceKey?.length ? { deviceKeys: opts.deviceKey } : {}),
+            ...(opts.accountId ? { accountId: opts.accountId } : {}),
+        });
+    });
+    // ---- rules (AgentGuard owner-lane caps and allowlist) -----------------------------------------------
+    // Caps and allowlist are complex, arbitrarily-sized nested shapes - JSON files here, the same escape
+    // hatch `agent request --calls-file` already established, rather than a wall of flags. See the LIVE
+    // CAVEAT in the workspace CLAUDE.md: accounts created since 2026-07-30 deploy permanently hookless, so
+    // this still parks and signs, but `RulesService.buildUpdate` declines rather than build an op that
+    // cannot bind on those accounts.
+    const rules = group(program.command('rules').description("Owner-lane caps and allowlist on this account's AgentGuard hook"), 'Wallet');
+    rules
+        .command('update')
+        .description('Update account caps and/or the contract/recipient allowlist - each half is left unchanged if omitted')
+        .option('--caps-file <path>', 'JSON array of cap rules: [{ token: { symbol }, limit, period }]')
+        .option('--allowlist-file <path>', 'JSON allowlist: { contracts: [...], recipients: [...], denied: [...] }, each an array of { name?, address }')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        if (!opts.capsFile && !opts.allowlistFile) {
+            throw invalidArgs('Nothing to change.', 'Pass --caps-file, --allowlist-file, or both.');
+        }
+        const caps = opts.capsFile ? await readJsonFile(opts.capsFile, '--caps-file') : undefined;
+        if (caps !== undefined && !Array.isArray(caps))
+            throw invalidArgs('--caps-file must contain a JSON array.');
+        const allowlist = opts.allowlistFile ? await readJsonFile(opts.allowlistFile, '--allowlist-file') : undefined;
+        if (allowlist !== undefined && (typeof allowlist !== 'object' || allowlist === null || Array.isArray(allowlist))) {
+            throw invalidArgs('--allowlist-file must contain a single JSON object.');
+        }
+        const rows = [
+            { label: 'caps', value: caps ? `${caps.length} rule(s)` : 'unchanged' },
+            { label: 'allowlist', value: allowlist ? 'updated' : 'unchanged' },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this rules update', rows, [], 'policy.update', {
+            ...(caps !== undefined ? { caps } : {}),
+            ...(allowlist !== undefined ? { allowlist } : {}),
+        });
+    });
+    // ---- agents approve/deny - attach onto wallet.ts's own `agents` Command --------------------------
+    const agents = findTopLevel(program, 'agents');
+    agents
+        .command('approve <id>')
+        .description("Approve an agent's request - the owner signs; the agent can never approve its own request")
+        .action(async (id) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const rows = [
+            { label: 'request', value: id },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this agent request', rows, [], 'agent.request.approve', { id });
+    });
+    agents
+        .command('deny <id>')
+        .description('There is no deny action - reads the request back and explains why')
+        .action(async (id) => {
+        const ctx = program.opts().__ctx;
+        const token = await requireWalletToken(ctx);
+        // The backend has NO decline/deny route for an agent request (`POST /agents/requests` /
+        // `GET /agents/requests` / `POST /agents/requests/{id}/approve` is the whole surface - see
+        // `AgentsController`), and the web app's own `AgentRequests.tsx` offers no deny action either: a
+        // request is either approved, or it expires on its own. Rather than fail with "unknown command"
+        // for something a person would reasonably expect, this reads the request back and says so plainly
+        // - a read, never a doomed write.
+        const requests = await step(ctx, 'Reading agent requests', () => ctx.runtime.api.get('/v1/agents/requests', token));
+        const list = Array.isArray(requests) ? requests : [];
+        const request = list.find((r) => r.id === id);
+        if (!request) {
+            throw invalidArgs(`No such agent request: ${id}.`, 'Run `botanary agents` to see open requests.');
+        }
+        const payload = {
+            request,
+            message: 'There is no deny action on this surface - an agent request is either approved or left to expire ' +
+                'on its own. Nothing was changed.',
+        };
+        printResult(ctx, payload, () => [
+            section(`Agent request ${id}`),
+            `  status: ${dash(request.status)}`,
+            `  expires: ${dash(request.expiresAt)}`,
+            '',
+            colors.muted(`  ${payload.message}`),
+        ].join('\n'));
+    });
+}
+//# sourceMappingURL=authority.js.map