@phantomcodes/cli 0.0.0-stage → 1.0.0

package/dist/keys/command.mjs

@@ -0,0 +1,116 @@
+import { createInterface } from 'node:readline/promises';
+import { die } from "../core/errors.mjs";
+import { getBalance } from "../core/request.mjs";
+import { out } from "../core/helpers.mjs";
+import { resolveApiKey, readNamedKey, saveNamedKey, removeNamedKey, listNamedKeys, saveApiKey, removeApiKey } from "./saved.mjs";
+/** `--table` output for `balance`. */
+export function tableBalance(d) {
+    const b = d;
+    return [
+        `active          ${b.active}`,
+        `kind            ${b.kind}`,
+        `balance         $${b.credit_balance_usd.toFixed(4)}`,
+        `spent           $${b.credit_spent_usd.toFixed(4)}`,
+        `expires_at      ${b.expires_at}`,
+    ].join('\n');
+}
+/** `--table` output for `key list`. */
+export function tableKeys(d) {
+    const { keys } = d;
+    if (keys.length === 0)
+        return 'no saved keys';
+    return keys
+        .map((k) => {
+        const bal = k.credit_balance_usd === undefined ? '' : `  $${k.credit_balance_usd.toFixed(4)}${k.active === false ? '  inactive' : ''}`;
+        return `${k.name.padEnd(16)}${k.id}${bal}`;
+    })
+        .join('\n');
+}
+/** `phantom balance`: the key's credit and expiry. Run by `run()`. */
+export async function balanceCommand({ io, apiKey, table, baseUrl }) {
+    const result = await getBalance(apiKey, baseUrl);
+    out(result, table, tableBalance, io.stdout);
+    return 0;
+}
+/** `phantom key list|save|show|rm`: keys saved by name. Run by `run()`. */
+export async function keyCommand({ argv, env, io, subcommand, flags, table, baseUrl }) {
+    const name = argv[2] && !argv[2].startsWith('--') ? argv[2] : undefined;
+    if (!subcommand || subcommand === 'list') {
+        const list = listNamedKeys(env);
+        if (flags['balance']) {
+            const withBalance = await Promise.all(list.keys.map(async (k) => {
+                try {
+                    const b = await getBalance(readNamedKey(env, k.name), baseUrl);
+                    return { ...k, active: b.active, credit_balance_usd: b.credit_balance_usd, expires_at: b.expires_at };
+                }
+                catch {
+                    return { ...k, active: false };
+                }
+            }));
+            out({ keys: withBalance }, table, tableKeys, io.stdout);
+        }
+        else {
+            out(list, table, tableKeys, io.stdout);
+        }
+    }
+    else if (subcommand === 'save') {
+        if (!name)
+            die('key save requires a name: phantom key save <name> [key]');
+        let key = argv[3] && !argv[3].startsWith('--') ? argv[3] : undefined;
+        if (!key) {
+            const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: false });
+            if (io.isTTY)
+                io.stderr('Paste the key: ');
+            key = (await rl[Symbol.asyncIterator]().next()).value ?? '';
+            rl.close();
+        }
+        key = (key ?? '').trim();
+        if (!key.startsWith('sk-phantom-'))
+            die('That is not a Phantom AI key. Keys start with sk-phantom-');
+        await getBalance(key, baseUrl);
+        out(saveNamedKey(env, name, key), table, (d) => `saved           ${d.name}`, io.stdout);
+    }
+    else if (subcommand === 'show') {
+        // Raw, for PHANTOM_API_KEY=$(phantom key show <name>). With no name, the
+        // key phantom itself would use, which is what Claude Code's apiKeyHelper runs.
+        const key = name ? readNamedKey(env, name) : resolveApiKey(env);
+        if (!key)
+            die('No API key. Set PHANTOM_API_KEY or run: phantom login');
+        io.stdout(key + '\n');
+    }
+    else if (subcommand === 'rm') {
+        if (!name)
+            die('key rm requires a name');
+        out(removeNamedKey(env, name), table, (d) => `removed         ${d.removed}`, io.stdout);
+    }
+    else {
+        die(`Unknown key subcommand: ${subcommand}`);
+    }
+    return 0;
+}
+/** `phantom login`: checks a key and saves it as the login key. Run by `run()`. */
+export async function loginCommand({ env, io, subcommand, table, baseUrl }) {
+    let key = subcommand;
+    if (!key) {
+        // Prompt rather than take the key as an argument, so it stays out of
+        // shell history.
+        const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: false });
+        if (io.isTTY)
+            io.stderr('Paste your Phantom AI key: ');
+        key = (await rl[Symbol.asyncIterator]().next()).value ?? '';
+        rl.close();
+    }
+    key = (key ?? '').trim();
+    if (!key.startsWith('sk-phantom-'))
+        die('That is not a Phantom AI key. Keys start with sk-phantom-');
+    // Check the key works before saving it.
+    const balance = await getBalance(key, baseUrl);
+    const saved = saveApiKey(env, key);
+    out({ ...saved, ...balance }, table, (d) => `saved           ${d.saved}\n${tableBalance(d)}`, io.stdout);
+    return 0;
+}
+/** `phantom logout`: forgets the login key. Run by `run()`. */
+export async function logoutCommand({ env, io, table }) {
+    out(removeApiKey(env), table, (d) => `removed         ${d.removed}`, io.stdout);
+    return 0;
+}

package/dist/keys/saved.mjs

@@ -0,0 +1,172 @@
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync } from 'node:fs';
+import { die } from "../core/errors.mjs";
+import { stateDir } from "../core/state.mjs";
+import { writeSecret, readSecret, removeSecret } from "../core/secrets.mjs";
+/**
+ * `login` saves the key to a file only the user can read, so an agent that
+ * reaches the CLI through bash (pi has no MCP) needs no environment set up.
+ *
+ * Other keys can be saved by name in `keys/`, one file each, so an agent can
+ * find them again in a later session. The file holds nothing but the key.
+ * `phantom keys create` also keeps a record with no secret in it beside each key
+ * it makes (see {@link SessionRecord}).
+ *
+ * Which key a command runs as: the saved key named by PHANTOM_KEY_NAME, then
+ * PHANTOM_API_KEY, then the default key.
+ */
+const KEY_NAME = /^[a-z0-9][a-z0-9_-]{0,31}$/i;
+export function keyPath(env) {
+    return path.join(stateDir(env), 'key');
+}
+export function namedKeyPath(env, name) {
+    if (!KEY_NAME.test(name))
+        die(`Key names use letters, numbers, - and _ (up to 32): ${name}`);
+    return path.join(stateDir(env), 'keys', name);
+}
+/** A key's id: the start of its SHA-256 hash, safe to print. */
+export function keyId(key) {
+    return createHash('sha256').update(key.trim()).digest('hex').slice(0, 12);
+}
+/**
+ * Which key a command runs as: the saved key named by PHANTOM_KEY_NAME, then
+ * PHANTOM_API_KEY, then the default key. It only looks; {@link resolveApiKey}
+ * reads the key.
+ */
+export function keySource(env) {
+    // A named key is the more specific choice, so it wins. A subagent started
+    // with PHANTOM_KEY_NAME=<name> from a shell that also exports
+    // PHANTOM_API_KEY must run as the named key, not quietly spend the other.
+    if (env.PHANTOM_KEY_NAME)
+        return { from: 'named', name: env.PHANTOM_KEY_NAME };
+    if (env.PHANTOM_API_KEY)
+        return { from: 'env' };
+    return existsSync(keyPath(env)) ? { from: 'login' } : { from: 'none' };
+}
+/** The key a command runs as, chosen by {@link keySource}. An empty string when there is none. */
+export function resolveApiKey(env) {
+    const src = keySource(env);
+    if (src.from === 'env')
+        return env.PHANTOM_API_KEY ?? '';
+    if (src.from === 'named')
+        return readNamedKey(env, src.name);
+    if (src.from === 'login')
+        return readSecret(env, keyPath(env)).trim();
+    return '';
+}
+function writeKeyFile(env, file, key) {
+    const k = key.trim();
+    if (!k.startsWith('sk-phantom-'))
+        die('That is not a Phantom AI key. Keys start with sk-phantom-');
+    writeSecret(env, file, k + '\n');
+}
+/**
+ * A key saved by name.
+ * @throws {@link CliError} when no key has that name, or the name is not valid.
+ */
+export function readNamedKey(env, name) {
+    const file = namedKeyPath(env, name);
+    if (!existsSync(file))
+        die(`No saved key named ${name}. See: phantom key list`);
+    return readSecret(env, file).trim();
+}
+/**
+ * Saves a key by name, in the Keychain or a mode 600 file (see {@link keychain}).
+ * Refuses a name already in use unless `replace` is set, and anything that
+ * doesn't start with `sk-phantom-`.
+ * @returns The name, and the key's {@link keyId}.
+ */
+export function saveNamedKey(env, name, key, opts = {}) {
+    const file = namedKeyPath(env, name);
+    if (existsSync(file) && !opts.replace)
+        die(`A key named ${name} is already saved. Pick another name, or remove it first.`);
+    writeKeyFile(env, file, key);
+    return { name, id: keyId(key) };
+}
+/** Forgets a saved key. The key itself keeps working. */
+export function removeNamedKey(env, name) {
+    const file = namedKeyPath(env, name);
+    if (!existsSync(file))
+        return { name, removed: false };
+    removeSecret(file);
+    return { name, removed: true };
+}
+/** Every key saved by name, sorted, with its id. Never returns the keys. */
+export function listNamedKeys(env) {
+    const dir = path.join(stateDir(env), 'keys');
+    if (!existsSync(dir))
+        return { keys: [] };
+    const keys = readdirSync(dir)
+        .filter((n) => KEY_NAME.test(n))
+        .sort()
+        .map((name) => ({ name, id: keyId(readSecret(env, path.join(dir, name))) }));
+    return { keys };
+}
+/** The default key, the one `phantom keys create` saves when no name is given, or null when none is saved. */
+export function defaultKey(env) {
+    return existsSync(keyPath(env)) ? readSecret(env, keyPath(env)).trim() : null;
+}
+/** Saves the default key, the one used when neither PHANTOM_KEY_NAME nor PHANTOM_API_KEY is set. */
+export function saveApiKey(env, key) {
+    writeKeyFile(env, keyPath(env), key);
+    return { saved: keyPath(env) };
+}
+/** Forgets the default key. */
+export function removeApiKey(env) {
+    const p = keyPath(env);
+    if (!existsSync(p))
+        return { removed: false };
+    removeSecret(p);
+    return { removed: true };
+}
+/**
+ * Where a new key will be saved: the name in `save` (`--save`), or `default`.
+ * Run it before anything is asked for: it refuses a name already in use and,
+ * with no name, a default key that is saved already.
+ * @throws {@link CliError} `key_exists`, or `cli_error` for `--save` with no name.
+ */
+export function saveTarget(env, save) {
+    if (save === true)
+        die('--save requires a name for the key');
+    if (typeof save === 'string' && existsSync(namedKeyPath(env, save))) {
+        die(`A key named ${save} is already saved. Pick another name, or remove it first.`, 'key_exists');
+    }
+    if (save === undefined && existsSync(keyPath(env))) {
+        die('A default key is already saved. Name the new key with --save <name>.', 'key_exists');
+    }
+    return save ?? 'default';
+}
+/** Saves a key under a {@link saveTarget}: `default`, or a name. */
+export function saveKeyAs(env, target, key) {
+    if (target === 'default')
+        saveApiKey(env, key);
+    else
+        saveNamedKey(env, target, key);
+}
+/** Forgets a key saved under a {@link saveTarget}. */
+export function forgetKeyAs(env, target) {
+    if (target === 'default')
+        removeApiKey(env);
+    else
+        removeNamedKey(env, target);
+}
+/**
+ * True when PHANTOM_API_KEY holds the same key as the login. `phantom setup`'s
+ * shell block sets it that way, so a rotate or burn must update the login too.
+ */
+export function envIsLogin(env) {
+    return Boolean(env.PHANTOM_API_KEY) && existsSync(keyPath(env)) && readSecret(env, keyPath(env)).trim() === env.PHANTOM_API_KEY?.trim();
+}
+/** After a rotate, put the new key where the old one was saved. */
+export function replaceSavedKey(env, src, key) {
+    if (src.from === 'named') {
+        saveNamedKey(env, src.name, key, { replace: true });
+        return src.name;
+    }
+    if (src.from === 'login' || (src.from === 'env' && envIsLogin(env))) {
+        writeKeyFile(env, keyPath(env), key);
+        return 'login';
+    }
+    return null;
+}

package/dist/phantom.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * phantom: prepaid AI inference for coding agents with Phantom AI.
+ *
+ * Keys, money and setup for any AI agent: a Phantom AI key, model routing,
+ * and receipts that show which model answered. It runs as a CLI and through
+ * the phantom-ai skill, so pi, Claude Code, Codex and Cursor can all drive it
+ * by prompt.
+ *
+ * This file is the entry point. The code lives in one folder per feature
+ * beside it, and this file exports the public API from them. From a
+ * checkout: `node src/phantom.mts`.
+ */
+import { fileURLToPath } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { run } from "./cli/run.mjs";
+export { DEFAULT_BASE_URL, request, httpsOnly, getBalance } from "./core/request.mjs";
+export { VERSION } from "./core/version.mjs";
+export { PhantomApiError, CliError, die } from "./core/errors.mjs";
+export { getRoute, putRoute, patchRoute, clearRoute, testRoute, parseCondition } from "./spend/routing.mjs";
+export { checkReceipt, modelsMatch, verifyModel } from "./receipts/receipts.mjs";
+export { keychain } from "./core/secrets.mjs";
+export { keyId, keySource, resolveApiKey, readNamedKey, saveNamedKey, removeNamedKey, listNamedKeys, saveApiKey, removeApiKey } from "./keys/saved.mjs";
+// Supported setup interface: plan, preview, apply, and restore.
+export { SETUP_MODEL, agentBaseUrl } from "./setup/shared.mjs";
+export { planSetup } from "./setup/plan.mjs";
+export { applySetup, previewSetup, setupAgents, restoreSetup } from "./setup/apply.mjs";
+export { jsonEdit, tomlSet, tomlRemoveOurs, yamlSetTop, yamlAddModel, yamlRemoveOurs, shellRcFile, shellBlock } from "./setup/editors.mjs";
+export { SETUP_AGENTS } from "./setup/agents.mjs";
+export { claudeProvider } from "./setup/apply.mjs";
+export { ENV_VARS, HELP } from "./cli/help.mjs";
+export { run } from "./cli/run.mjs";
+/** The installed entry point: {@link run} with the process's arguments, then `process.exit` with its code when it is not 0. */
+export async function main() {
+    const code = await run();
+    if (code !== 0) {
+        process.exit(code);
+    }
+}
+/**
+ * True for `node src/phantom.mts`. Installed, the entry point is bin/phantom.mjs,
+ * which imports `main` and calls it, so this stays false there.
+ */
+const isDirectRun = (() => {
+    if (!process.argv[1])
+        return false;
+    // Compare real paths, so a run through a symlink (like /tmp on macOS) counts.
+    try {
+        return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+    }
+    catch {
+        return false;
+    }
+})();
+if (isDirectRun) {
+    void main();
+}

package/dist/receipts/command.mjs

@@ -0,0 +1,41 @@
+import { die } from "../core/errors.mjs";
+import { out } from "../core/helpers.mjs";
+import { checkReceipt, verifyModel } from "./receipts.mjs";
+/** `--table` output for `verify --model`. */
+export function tableVerifyModel(d) {
+    const v = d;
+    return [
+        `requested       ${v.model_requested}`,
+        `served          ${v.model_served ?? '-'}`,
+        `match           ${v.match}`,
+        `signature       ${v.signature_valid ? 'valid' : 'invalid'}`,
+        `cost            ${v.cost_usd === null ? '-' : `$${v.cost_usd.toFixed(6)}`}`,
+        ...(v.reason ? [`reason          ${v.reason}`] : []),
+    ].join('\n');
+}
+/** `--table` output for `verify --receipt`. */
+export function tableReceiptCheck(d) {
+    const c = d;
+    return [
+        `signature       ${c.valid ? 'valid' : 'invalid'}`,
+        `requested       ${c.receipt?.model_requested ?? '-'}`,
+        `served          ${c.receipt?.model_served ?? '-'}`,
+        `signed_at       ${c.receipt?.ts ?? '-'}`,
+        ...(c.reason ? [`reason          ${c.reason}`] : []),
+    ].join('\n');
+}
+/** `phantom verify`: checks a receipt, or makes one small call and checks its receipt. Run by `run()`. */
+export async function verifyCommand({ io, apiKey, flags, table, baseUrl }) {
+    const model = flags['model'];
+    const receipt = flags['receipt'];
+    if (typeof receipt === 'string') {
+        const result = await checkReceipt(receipt, baseUrl);
+        out(result, table, tableReceiptCheck, io.stdout);
+        return result.valid ? 0 : 1;
+    }
+    if (typeof model !== 'string')
+        die('verify requires --model <id> or --receipt <receipt>');
+    const result = await verifyModel(apiKey, model, baseUrl);
+    out(result, table, tableVerifyModel, io.stdout);
+    return result.match ? 0 : 1;
+}

package/dist/receipts/receipts.mjs

@@ -0,0 +1,82 @@
+import { createPublicKey, verify as cryptoVerify } from 'node:crypto';
+import { apiBase, apiError } from "../core/request.mjs";
+/**
+ * Every priced call returns a receipt signed with Phantom AI's Ed25519 key. The
+ * check runs here, against the public key from /receipts/key, so the answer
+ * never comes from Phantom AI saying it was honest.
+ */
+/** Matches RECEIPT_VERSION in lib/receipts.ts. */
+const RECEIPT_VERSION = 1;
+/**
+ * Checks a compact receipt (`payload.signature`, both base64url) against the
+ * public key from GET /receipts/key. Needs no API key.
+ * @throws {@link PhantomApiError} when the public key cannot be fetched.
+ */
+export async function checkReceipt(compact, baseUrl) {
+    const res = await fetch(`${apiBase(baseUrl)}/receipts/key`);
+    const json = (await res.json().catch(() => ({})));
+    if (!res.ok)
+        throw apiError(res.status, json);
+    if (!json.signs || !json.public_key_jwk) {
+        return { valid: false, receipt: null, reason: 'This deployment signs no receipts' };
+    }
+    const parts = compact.trim().split('.');
+    if (parts.length !== 2)
+        return { valid: false, receipt: null, reason: 'Not a receipt: expected payload.signature' };
+    const payload = Buffer.from(parts[0], 'base64url');
+    let receipt;
+    try {
+        receipt = JSON.parse(payload.toString('utf-8'));
+    }
+    catch {
+        return { valid: false, receipt: null, reason: 'Receipt payload is not JSON' };
+    }
+    if (!receipt || typeof receipt !== 'object')
+        return { valid: false, receipt: null, reason: 'Receipt payload is not an object' };
+    if (receipt.v !== RECEIPT_VERSION)
+        return { valid: false, receipt, reason: `Unknown receipt version ${receipt.v}` };
+    const key = createPublicKey({ key: json.public_key_jwk, format: 'jwk' });
+    const valid = cryptoVerify(null, payload, key, Buffer.from(parts[1], 'base64url'));
+    return valid ? { valid, receipt } : { valid, receipt, reason: 'Signature does not match the published key' };
+}
+/** The served id can drop the provider prefix, so a bare name counts as a match. */
+export function modelsMatch(requested, served) {
+    const bare = (id) => id.toLowerCase().split('/').pop();
+    return requested.toLowerCase() === served.toLowerCase() || bare(requested) === bare(served);
+}
+/** One small priced call to `model`, then a check of the receipt it returns. */
+export async function verifyModel(apiKey, model, baseUrl) {
+    const res = await fetch(`${apiBase(baseUrl)}/chat/completions`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ model, max_tokens: 16, messages: [{ role: 'user', content: 'Reply with ok.' }] }),
+    });
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok)
+        throw apiError(res.status, json);
+    const compact = res.headers.get('x-phantom-receipt');
+    if (!compact) {
+        return {
+            model_requested: model,
+            model_served: null,
+            match: false,
+            signature_valid: false,
+            cost_usd: null,
+            request_id: null,
+            receipt: null,
+            reason: 'The response carried no receipt',
+        };
+    }
+    const check = await checkReceipt(compact, baseUrl);
+    const r = check.receipt;
+    return {
+        model_requested: model,
+        model_served: r?.model_served ?? null,
+        match: check.valid && r !== null && modelsMatch(model, r.model_served),
+        signature_valid: check.valid,
+        cost_usd: r ? r.cost_micro_usd / 1_000_000 : null,
+        request_id: r?.request_id ?? null,
+        receipt: compact,
+        ...(check.reason ? { reason: check.reason } : {}),
+    };
+}