@certen.io/cli 0.4.0 → 0.7.0

package/dist/funding-guard.js

@@ -0,0 +1,120 @@
+import { CliError, EXIT } from './errors.js';
+import { normalizeChain } from './chains.js';
+/**
+ * The zero-balance abstract account guard.
+ *
+ * This is the most expensive silent failure in the product, and it is documented everywhere
+ * except where it happens. A fresh identity gets a deterministic abstract account on each linked
+ * chain, with a zero balance. An intent that moves value from it is accepted, signed and
+ * submitted — every step reports success — and then parks at `anchoring` forever, because the
+ * execution leg cannot run on chain. Nothing in any API response says so. The intent simply never
+ * reaches a terminal state, and the user is left debugging a gateway that is behaving correctly.
+ *
+ * So: refuse before submitting, and name the address that needs funding.
+ *
+ * The check is deliberately one-directional. It refuses ONLY on a positively observed zero
+ * balance. If the balance cannot be read — the chain is not in the portfolio, the account is not
+ * deployed yet, the lookup fails — the intent proceeds. A guard that blocked on missing data
+ * would break legitimate work every time the portfolio view lagged, which is a worse failure than
+ * the one it prevents.
+ */
+/** Where to send testnet gas, per chain. Printed with the refusal, because the fix is the point. */
+const FAUCETS = {
+    'ethereum-sepolia': 'https://sepoliafaucet.com',
+    'base-sepolia': 'https://www.alchemy.com/faucets/base-sepolia',
+    'arbitrum-sepolia': 'https://www.alchemy.com/faucets/arbitrum-sepolia',
+};
+export function faucetFor(chain) {
+    return FAUCETS[chain];
+}
+/** Does this intent move value? A zero or absent amount needs no funded account. */
+export function movesValue(intent) {
+    const amount = intent.amount ?? intent.value;
+    if (amount === undefined || amount === null)
+        return false;
+    const n = Number(String(amount));
+    // A non-numeric amount is not evidence of zero — let the gateway judge the shape.
+    return Number.isFinite(n) ? n > 0 : true;
+}
+function fromKnown(balances, chain) {
+    const want = normalizeChain(chain);
+    const onChain = balances.filter((b) => normalizeChain(b.chain_id) === want);
+    if (onChain.length === 0)
+        return null;
+    // The NATIVE balance is what pays for execution; a token balance on the same account does not
+    // make the execution leg runnable.
+    const native = onChain.find((b) => !b.token || b.token === 'ETH' || b.token === 'native');
+    return {
+        address: onChain[0].address,
+        balance: native ? native.balance : null,
+        // Not reported by this endpoint, and not read by anything: the guard decides on the balance.
+        deployed: true,
+    };
+}
+async function fundingFor(client, identityId, chain) {
+    try {
+        const portfolio = await client.portfolio.get(identityId);
+        // Both sides are normalized: the gateway returns `chain_id` as a slug on some chain accounts
+        // and as a numeric EVM id on others, in the same response. Comparing raw strings matched the
+        // slug entries and silently skipped the numeric ones — so the guard did nothing on exactly
+        // the accounts it was written to protect.
+        const want = normalizeChain(chain);
+        for (const identity of portfolio.identities ?? []) {
+            for (const c of identity.chains ?? []) {
+                if (normalizeChain(c.chain_id) !== want)
+                    continue;
+                // The native balance is the one that pays for execution. A token balance on the same
+                // account does not make the execution leg runnable.
+                const native = (c.balances ?? []).find((b) => !b.token || b.token === 'ETH' || b.token === 'native');
+                return {
+                    address: c.address,
+                    balance: native ? native.balance : null,
+                    deployed: c.deployed,
+                };
+            }
+        }
+        return null;
+    }
+    catch {
+        // An unavailable portfolio must never block a transaction. The guard is a courtesy, not a
+        // gate the product depends on.
+        return null;
+    }
+}
+/**
+ * Refuse a value-moving intent from an abstract account that is positively known to be empty.
+ *
+ * `force` exists because someone deliberately exercising the anchoring path should be able to,
+ * and because a guard with no override becomes something people work around rather than with.
+ */
+export async function assertFundedForValue(client, identityId, chain, intent, force, 
+/**
+ * Balances the caller has ALREADY fetched, from `identity.get()`.
+ *
+ * `GET /v1/identity/{id}` returns a `balances` array carrying the same chain, address and native
+ * balance this guard reads out of `/v1/portfolio`. `certen call` fetches the identity first (it
+ * needs `can_sign` before prompting for a passphrase) and then paid for a second read of numbers
+ * it was already holding — a round trip on the critical path of the main flow, for nothing.
+ *
+ * Omit it and the portfolio is fetched as before; `certen tx create` has no identity in hand.
+ */
+known) {
+    if (force || !chain || !movesValue(intent))
+        return;
+    const funding = known ? fromKnown(known, chain) : await fundingFor(client, identityId, chain);
+    if (!funding)
+        return;
+    const balance = funding.balance;
+    if (balance === null)
+        return;
+    if (Number(balance) > 0)
+        return;
+    const named = normalizeChain(chain);
+    const faucet = faucetFor(named);
+    throw new CliError(`The abstract account ${funding.address} on ${named} holds no ${named.includes('sepolia') ? 'testnet ' : ''}`
+        + 'gas. This intent would be accepted, signed and submitted, and would then park at "anchoring" '
+        + 'forever, because the execution leg cannot run on chain.\n'
+        + `  Fund it first${faucet ? `: ${faucet}` : '.'}\n`
+        + '  Then run this command again. Pass --force to submit anyway.', 'ABSTRACT_ACCOUNT_UNFUNDED', EXIT.FAILED);
+}
+//# sourceMappingURL=funding-guard.js.map

package/dist/funding-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"funding-guard.js","sourceRoot":"","sources":["../src/funding-guard.ts"],"names":[],"mappings":"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"}

package/dist/help-root.d.ts

@@ -0,0 +1,2 @@
+import { Command, Help } from 'commander';
+export declare function formatRootHelp(cmd: Command, helper: Help): string;

package/dist/help-root.js

@@ -0,0 +1,94 @@
+import { Help } from 'commander';
+/**
+ * The order here is the order of the journey, not of importance. Anything not listed still
+ * appears, under "Other" — a command must never become invisible because someone added it
+ * without touching this file.
+ */
+const GROUPS = [
+    {
+        title: 'Get started',
+        blurb: 'from nothing to a working setup',
+        commands: ['login', 'signup', 'init', 'chains', 'auth', 'keys', 'doctor', 'whoami'],
+    },
+    {
+        title: 'Build',
+        blurb: 'identities, and the work they authorize',
+        commands: ['identity', 'call', 'tx', 'proof'],
+    },
+    {
+        title: 'Approve',
+        blurb: 'multi-party signing',
+        commands: ['pending', 'governance'],
+    },
+    {
+        title: 'Money',
+        blurb: 'what it costs and how to pay',
+        commands: ['pricing', 'balance', 'quote', 'fund', 'payers'],
+    },
+    {
+        title: 'Audit',
+        blurb: 'what you were charged, and proof of it',
+        commands: ['ledger', 'receipts', 'verify'],
+    },
+    {
+        title: 'Operate',
+        blurb: 'across every identity and key',
+        commands: ['portfolio', 'webhooks', 'oauth-clients', 'orgs', 'admin', 'scopes', 'errors'],
+    },
+];
+const QUICKSTART = `
+  From nothing to a proof:
+
+    certen login                               # approve this machine in the portal
+    certen init                                # key, identity, funding — all checked
+    certen call --identity <id> --chain base-sepolia --to 0xContract \\
+        --fn 'confirm(bytes32)' --arg 0x... --sign-with dev --wait
+    certen proof get <intent-id>               # the evidence, to hand over
+
+  Stuck? Run: certen doctor
+`;
+export function formatRootHelp(cmd, helper) {
+    // Subcommands inherit this configuration, so anything that is not the root is handed straight
+    // back to commander's own renderer. Calling `helper.formatHelp` here would recurse into this
+    // function, because that is the property being overridden.
+    if (cmd.parent !== null) {
+        return Help.prototype.formatHelp.call(helper, cmd, helper);
+    }
+    const visible = cmd.commands.filter((c) => !c._hidden);
+    const byName = new Map(visible.map((c) => [c.name(), c]));
+    const grouped = new Set(GROUPS.flatMap((g) => g.commands));
+    const width = Math.max(...visible.map((c) => c.name().length), 10) + 2;
+    const lines = [];
+    lines.push(`${cmd.name()} — ${cmd.description()}`);
+    lines.push('');
+    lines.push(`Usage: ${cmd.name()} [options] <command> [args]`);
+    lines.push(QUICKSTART.replace(/^\n/, ''));
+    for (const group of GROUPS) {
+        const present = group.commands.filter((name) => byName.has(name));
+        if (present.length === 0)
+            continue;
+        lines.push(`${group.title} — ${group.blurb}`);
+        for (const name of present) {
+            lines.push(`  ${name.padEnd(width)}${byName.get(name).description()}`);
+        }
+        lines.push('');
+    }
+    const ungrouped = visible.filter((c) => !grouped.has(c.name()));
+    if (ungrouped.length > 0) {
+        lines.push('Other');
+        for (const c of ungrouped) {
+            lines.push(`  ${c.name().padEnd(width)}${c.description()}`);
+        }
+        lines.push('');
+    }
+    lines.push('Options');
+    for (const option of helper.visibleOptions(cmd)) {
+        lines.push(`  ${helper.optionTerm(option).padEnd(width + 12)}${helper.optionDescription(option)}`);
+    }
+    lines.push('');
+    lines.push(`Run \`${cmd.name()} <command> --help\` for the flags on any of them.`);
+    lines.push(`Scripting? \`${cmd.name()} --help --json\` returns the whole tree in one call.`);
+    lines.push('');
+    return lines.join('\n');
+}
+//# sourceMappingURL=help-root.js.map

package/dist/help-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-root.js","sourceRoot":"","sources":["../src/help-root.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -25,6 +25,19 @@ import { registerPendingCommands } from './commands/pending.js';
 import { registerGovernanceCommands } from './commands/governance.js';
 import { registerPortfolioCommands } from './commands/portfolio.js';
 import { registerAdminCommands } from './commands/admin.js';
+import { registerBillingCommands } from './commands/billing.js';
+import { registerChainsCommands } from './commands/chains.js';
+import { registerWhoamiCommands } from './commands/whoami.js';
+import { registerDoctorCommands } from './commands/doctor.js';
+import { registerProofCommands } from './commands/proof.js';
+import { registerCallCommands } from './commands/call.js';
+import { registerInitCommands } from './commands/init.js';
+import { registerSignupCommands } from './commands/signup.js';
+import { registerWebhookCommands } from './commands/webhooks.js';
+import { registerOAuthClientCommands } from './commands/oauth-clients.js';
+import { registerOrgCommands } from './commands/orgs.js';
+import { registerErrorsCommands } from './commands/errors-catalogue.js';
+import { formatRootHelp } from './help-root.js';
 const VERSION = readVersion();
 export function buildProgram() {
     const program = new Command();
@@ -37,19 +50,35 @@ export function buildProgram() {
         // Declared so it appears in --help. It is stripped from argv before parsing (see run()), because
         // a global flag that may appear after a subcommand is not something commander models.
         .option('--json', 'Emit one JSON envelope on stdout; human output goes to stderr');
+    registerSignupCommands(program);
+    registerInitCommands(program);
+    registerChainsCommands(program);
     registerAuthCommands(program);
     registerKeysCommands(program);
+    registerDoctorCommands(program);
+    registerWhoamiCommands(program);
     registerIdentityCommands(program);
     registerTransactionCommands(program);
+    registerCallCommands(program);
+    registerProofCommands(program);
     registerPendingCommands(program);
     registerGovernanceCommands(program);
     registerPortfolioCommands(program);
+    registerBillingCommands(program);
     registerAdminCommands(program);
+    registerWebhookCommands(program);
+    registerOAuthClientCommands(program);
+    registerOrgCommands(program);
+    registerErrorsCommands(program);
     // Every command, not just the root. `exitOverride()` is NOT inherited by subcommands, so without
     // this walk a missing required flag on `identity create` called process.exit(1) inside commander:
     // stdout stayed empty, no envelope was ever emitted, and a usage error was indistinguishable from
     // a failed request. Every nested command has to opt in explicitly.
     applyExitOverride(program);
+    // Grouped by journey stage rather than alphabetically. Applied AFTER every command is
+    // registered, so nothing can be missing from the listing it builds. Subcommand help is
+    // untouched — see help-root.ts.
+    program.configureHelp({ formatHelp: formatRootHelp });
     return program;
 }
 function applyExitOverride(cmd) {
@@ -77,14 +106,17 @@ function handleError(err) {
         });
     }
     if (err instanceof CertenError) {
-        // isRetryable is the SDK's own judgement — reuse it so both transports agree.
-        return emitFailure({
-            message: err.message,
-            code: err.code,
-            status: err.status,
-            requestId: err.requestId,
-            isRetryable: err.isRetryable,
-        });
+        // Pass the ERROR, not a copy of its fields.
+        //
+        // This used to flatten it into an object literal. The literal carried the same
+        // values but destroyed the class identity, so a 402 reached the reporter as an
+        // anonymous shape and its payment target was silently dropped — the refusal
+        // printed a code and a message while the fix sat unread on the error.
+        //
+        // Nothing is lost by passing the instance: message, code, status and requestId
+        // are all readable on it, and `isRetryable` is a getter, so the SDK's own retry
+        // judgement still reaches both transports.
+        return emitFailure(err);
     }
     return emitFailure(err);
 }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/output.d.ts

@@ -8,6 +8,14 @@ export declare function resetOutput(): void;
  */
 export declare function printOutput(data: Record<string, unknown>[] | Record<string, unknown>, opts?: {
     forceJson?: boolean;
+    /**
+     * Emit for machines only, and print nothing in table mode.
+     *
+     * For a command that renders its own readable summary. Without this the payload and the summary
+     * both reach a person, so every figure appears twice — and any long or nested field (a payment
+     * URI, a credit object) lands in the middle of the instructions someone is trying to follow.
+     */
+    machineOnly?: boolean;
 }): void;
 /**
  * A human-facing note — "API key saved", "(no keys)".
@@ -18,6 +26,21 @@ export declare function printOutput(data: Record<string, unknown>[] | Record<str
 export declare function human(message: string): void;
 /** A hint or warning. Always stderr — it is never the result of the command. */
 export declare function hint(message: string): void;
+/**
+ * `"12.340000"` -> `"$12.34"`, and `"-72.355716"` -> `"-$72.36"`.
+ *
+ * One implementation, here, because there were two. `billing.ts` handled a leading minus and
+ * `whoami.ts` did not, so the same drawn-down account rendered `-$72.35` in one command and the
+ * malformed `$-72.35` in the other. A money formatter is exactly the kind of four-line helper that
+ * gets copied rather than imported, and exactly the kind where the copy is wrong in the case nobody
+ * had yet.
+ *
+ * Works on the STRING. The gateway sends fixed-point decimal strings, and parsing money into a
+ * float to format it reintroduces the representation error those strings exist to avoid. The cents
+ * are rounded half-up from the remaining digits rather than truncated, so a balance of
+ * `-72.355716` reads `-$72.36` — a displayed figure should never flatter the account by a cent.
+ */
+export declare function usd(amount: string | number): string;
 /**
  * Emit the success envelope. No-op outside JSON mode, and safe to call more than once.
  *

package/dist/output.js

@@ -1,3 +1,4 @@
+import { CertenPaymentRequiredError } from '@certen.io/sdk';
 import { getOutputFormat } from './config.js';
 import { CliError, EXIT } from './errors.js';
 /**
@@ -40,6 +41,8 @@ export function printOutput(data, opts) {
         console.log(JSON.stringify(data, null, 2));
         return;
     }
+    if (opts?.machineOnly)
+        return;
     printTable(data);
 }
 /**
@@ -58,6 +61,37 @@ export function human(message) {
 export function hint(message) {
     console.error(message);
 }
+/**
+ * `"12.340000"` -> `"$12.34"`, and `"-72.355716"` -> `"-$72.36"`.
+ *
+ * One implementation, here, because there were two. `billing.ts` handled a leading minus and
+ * `whoami.ts` did not, so the same drawn-down account rendered `-$72.35` in one command and the
+ * malformed `$-72.35` in the other. A money formatter is exactly the kind of four-line helper that
+ * gets copied rather than imported, and exactly the kind where the copy is wrong in the case nobody
+ * had yet.
+ *
+ * Works on the STRING. The gateway sends fixed-point decimal strings, and parsing money into a
+ * float to format it reintroduces the representation error those strings exist to avoid. The cents
+ * are rounded half-up from the remaining digits rather than truncated, so a balance of
+ * `-72.355716` reads `-$72.36` — a displayed figure should never flatter the account by a cent.
+ */
+export function usd(amount) {
+    const raw = String(amount);
+    const negative = raw.trimStart().startsWith('-');
+    const [whole, frac = ''] = raw.replace('-', '').split('.');
+    // Round on the digit AFTER the cents, carrying into the whole part when it overflows.
+    const cents = Number((frac + '000').slice(0, 3));
+    let dollars = BigInt(whole || '0');
+    let rounded = Math.round(cents / 10);
+    if (rounded === 100) {
+        dollars += 1n;
+        rounded = 0;
+    }
+    // A residue too small to show is not a debt. `-0.004` rounding to `-$0.00` would be the only
+    // place in the CLI where zero has a sign.
+    const sign = negative && (dollars !== 0n || rounded !== 0) ? '-' : '';
+    return `${sign}$${dollars}.${String(rounded).padStart(2, '0')}`;
+}
 /**
  * Emit the success envelope. No-op outside JSON mode, and safe to call more than once.
  *
@@ -85,6 +119,10 @@ export function emitFailure(err) {
     const code = e.code ?? 'UNKNOWN_ERROR';
     const retryable = e instanceof CliError ? e.retryable : Boolean(e.isRetryable);
     const exitCode = resolveExitCode(e);
+    // A refusal for lack of funds is the one failure that carries its own fix, so it
+    // is rendered rather than reduced to a code and a message. The developer is
+    // already in a terminal; the next command belongs there, not in documentation.
+    const payment = err instanceof CertenPaymentRequiredError ? err : null;
     if (jsonMode) {
         flushed = true;
         process.stdout.write(`${JSON.stringify({
@@ -95,20 +133,72 @@ export function emitFailure(err) {
                 retryable,
                 ...(e.status !== undefined ? { status: e.status } : {}),
                 ...(e.requestId ? { requestId: e.requestId } : {}),
+                // A failure that still produced a result carries it, rather than throwing the result
+                // away in order to signal the failure. See CliError.details.
+                ...(e.details ? { details: e.details } : {}),
+                // Additive: a consumer that ignores unknown keys is unaffected, and one
+                // that wants to settle automatically no longer has to parse prose.
+                ...(payment
+                    ? {
+                        shortfall_usd: payment.shortfallUsd,
+                        quote_id: payment.quoteId,
+                        resolve: payment.resolution,
+                    }
+                    : {}),
             },
         })}\n`);
     }
     else {
         console.error(code === 'UNKNOWN_ERROR' ? `Error: ${message}` : `Error [${code}]: ${message}`);
+        if (payment)
+            emitPaymentFix(payment);
     }
     return exitCode;
 }
+/**
+ * Print the way out of a 402.
+ *
+ * All on stderr: it is guidance, not the result of the command, and a caller
+ * piping stdout must still get clean output (or, in JSON mode, exactly one
+ * envelope). The closing line matters as much as the address — a developer whose
+ * request was refused needs to know nothing was charged and nothing started.
+ */
+function emitPaymentFix(payment) {
+    console.error('');
+    console.error(`  ${payment.summary}`);
+    const r = payment.resolution;
+    if (r) {
+        console.error('');
+        console.error(`  Send exactly ${r.amount_usd} USD on ${r.chain} to:`);
+        console.error(`      ${r.to_address}`);
+        console.error(`  Reference ${r.payment_intent}`);
+        console.error('');
+        console.error(`  Or run:  ${r.cli_command}`);
+        console.error(`  Portal:  ${r.portal_url}`);
+    }
+    if (payment.quoteId) {
+        console.error('');
+        console.error(`  Then retry with --quote-id ${payment.quoteId} to keep this price.`);
+    }
+    console.error('');
+    console.error('  Nothing was charged and no work was started.');
+}
 function resolveExitCode(e) {
     if (typeof e.exitCode === 'number')
         return e.exitCode;
     // status 0 is how the SDK reports "the request never reached the gateway".
     if (e.code === 'NETWORK_ERROR' || e.status === 0)
         return EXIT.UNREACHABLE;
+    // Falling through to FAILED is correct for a genuine operation failure and WRONG for a plain
+    // `throw new Error('you forgot a flag')`, which should be a usage error and exit 2. Several
+    // commands shipped that mistake, and it is invisible: both cases exit 1 and read identically.
+    // There is no safe way to guess here — a bare Error carries nothing to distinguish them — so
+    // the fix is at the throw site, and this makes the throw site findable rather than silent.
+    if (process.env.CERTEN_DEBUG === '1' && e.code === undefined) {
+        const name = e.constructor?.name ?? 'unknown';
+        console.error(`[certen debug] exit 1 from an untyped ${name} — if this is a wrong invocation it should `
+            + 'throw UsageError and exit 2.');
+    }
     return EXIT.FAILED;
 }
 // ── table rendering (human mode only) ───────────────────────────────────────────────────────────

package/dist/output.js.map

@@ -1 +1 @@
-{"version":3,"file":"output.js","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"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"}

package/dist/passphrase.d.ts

@@ -7,6 +7,16 @@
  */
 declare const ENV_VAR = "CERTEN_KEY_PASSPHRASE";
 export declare function passphraseFromEnv(): string | null;
+export declare function isInteractive(): boolean;
+/**
+ * Read a secret from stdin when it is a pipe rather than a terminal.
+ *
+ * This is what makes `--api-key -` work: `echo $KEY | certen auth login --api-key -` keeps the
+ * secret out of shell history and out of the process table, which passing it as an argument
+ * cannot do. Only the first line is taken, so a trailing newline from `echo` is not part of the
+ * key.
+ */
+export declare function readSecretFromStdin(): Promise<string>;
 /**
  * Resolve the passphrase for reading an existing key.
  *
@@ -22,4 +32,12 @@ export declare function resolvePassphrase(encrypted: boolean, keyName: string):
  * because a script that set it once cannot mistype it twice differently.
  */
 export declare function resolveNewPassphrase(noPassphrase: boolean): Promise<string | null>;
+/**
+ * Prompt for a secret on the TTY without echoing it.
+ *
+ * Exported so `auth login` can ask for an API key the same way key commands ask for a passphrase.
+ * A key pasted at a hidden prompt never reaches shell history; one passed as `--api-key <value>`
+ * always does.
+ */
+export declare function promptSecret(prompt: string): Promise<string>;
 export { ENV_VAR as PASSPHRASE_ENV_VAR };

package/dist/passphrase.js

@@ -5,14 +5,33 @@
  * TTY, and the interactive prompt is the fallback rather than the default. A command that blocks
  * on a hidden prompt inside a pipeline looks like a hang, which is the worst failure mode here.
  */
+import { UsageError } from './errors.js';
 const ENV_VAR = 'CERTEN_KEY_PASSPHRASE';
 export function passphraseFromEnv() {
     const v = process.env[ENV_VAR];
     return v && v.length > 0 ? v : null;
 }
-function isInteractive() {
+export function isInteractive() {
     return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
+/**
+ * Read a secret from stdin when it is a pipe rather than a terminal.
+ *
+ * This is what makes `--api-key -` work: `echo $KEY | certen auth login --api-key -` keeps the
+ * secret out of shell history and out of the process table, which passing it as an argument
+ * cannot do. Only the first line is taken, so a trailing newline from `echo` is not part of the
+ * key.
+ */
+export function readSecretFromStdin() {
+    return new Promise((resolve, reject) => {
+        let buf = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => { buf += chunk; });
+        process.stdin.on('end', () => resolve(buf.split(/\r?\n/)[0].trim()));
+        process.stdin.on('error', reject);
+        process.stdin.resume();
+    });
+}
 /**
  * Read a line from the TTY without echoing it.
  *
@@ -79,7 +98,7 @@ export async function resolvePassphrase(encrypted, keyName) {
     if (fromEnv !== null)
         return fromEnv;
     if (!isInteractive()) {
-        throw new Error(`Key "${keyName}" is encrypted and there is no TTY to prompt on. Set ${ENV_VAR}, or run this interactively.`);
+        throw new UsageError(`Key "${keyName}" is encrypted and there is no TTY to prompt on. Set ${ENV_VAR}, or run this interactively.`, 'PASSPHRASE_REQUIRED');
     }
     return readHidden(`Passphrase for key "${keyName}": `);
 }
@@ -97,7 +116,7 @@ export async function resolveNewPassphrase(noPassphrase) {
     if (fromEnv !== null)
         return fromEnv;
     if (!isInteractive()) {
-        throw new Error(`No TTY to prompt for a passphrase. Set ${ENV_VAR}, or pass --no-passphrase to store the key unencrypted.`);
+        throw new UsageError(`No TTY to prompt for a passphrase. Set ${ENV_VAR}, or pass --no-passphrase to store the key unencrypted.`, 'PASSPHRASE_REQUIRED');
     }
     const first = await readHidden('Passphrase for the new key (empty to store unencrypted): ');
     if (first.length === 0)
@@ -107,5 +126,18 @@ export async function resolveNewPassphrase(noPassphrase) {
         throw new Error('Passphrases did not match. Nothing was written.');
     return first;
 }
+/**
+ * Prompt for a secret on the TTY without echoing it.
+ *
+ * Exported so `auth login` can ask for an API key the same way key commands ask for a passphrase.
+ * A key pasted at a hidden prompt never reaches shell history; one passed as `--api-key <value>`
+ * always does.
+ */
+export async function promptSecret(prompt) {
+    if (!isInteractive()) {
+        throw new Error('No TTY to prompt on.');
+    }
+    return readHidden(prompt);
+}
 export { ENV_VAR as PASSPHRASE_ENV_VAR };
 //# sourceMappingURL=passphrase.js.map