@certen.io/cli 0.5.0 → 0.7.0

package/dist/commands/webhooks.js

@@ -0,0 +1,200 @@
+import { CertenClient } from '@certen.io/sdk';
+import { getApiKey, getApiUrl, getOutputFormat } from '../config.js';
+import { printOutput, human, hint, isJsonMode } from '../output.js';
+import { CliError, EXIT } from '../errors.js';
+/**
+ * Webhooks — where events go, and what happened to each one.
+ *
+ * CERTEN has pushed events since early on, with a delivery queue, a retry policy and a published
+ * signature-verification guide. None of it was reachable from here, so an endpoint could not be
+ * registered and a failed delivery could not be seen. That is the worst shape for a push mechanism:
+ * it fails quietly, and from the outside a dropped delivery is indistinguishable from an event that
+ * never happened.
+ *
+ * `deliveries` is the command that earns this group. Everything else configures; that one answers
+ * the question someone actually arrives with.
+ */
+async function getClient() {
+    return new CertenClient({ apiKey: await getApiKey(), baseUrl: getApiUrl() });
+}
+const machineOutput = () => isJsonMode() || getOutputFormat() === 'json';
+export function registerWebhookCommands(program) {
+    const webhooks = program
+        .command('webhooks')
+        .description('Where events are delivered, and what happened to each one');
+    webhooks
+        .command('list', { isDefault: true })
+        .description('Endpoints registered for this organization')
+        .action(async () => {
+        const { endpoints } = await (await getClient()).webhooks.list();
+        if (machineOutput()) {
+            printOutput({ endpoints });
+            return;
+        }
+        human('');
+        if (endpoints.length === 0) {
+            human('  No endpoints registered — CERTEN is not pushing events anywhere.');
+            hint('certen webhooks add https://example.com/hooks');
+            return;
+        }
+        for (const e of endpoints) {
+            // `verified` and `is_active` are the two states that decide whether anything arrives, so
+            // they belong on the same line as the URL rather than behind a second command.
+            const state = [
+                e.is_active ? 'active' : 'INACTIVE',
+                e.verified ? 'verified' : 'UNVERIFIED',
+            ].join(', ');
+            human(`  ${e.url}`);
+            human(`    ${e.id}  (${state})`);
+            if (e.event_types?.length)
+                human(`    events: ${e.event_types.join(', ')}`);
+            else
+                human('    events: all');
+            if (e.verification_error)
+                human(`    last verification error: ${e.verification_error}`);
+        }
+        human('');
+    });
+    webhooks
+        .command('add <url>')
+        .description('Register an endpoint to receive events')
+        .option('--events <list>', 'Comma-separated event types. Omit to receive everything.')
+        .option('--secret <secret>', 'Your own signing secret, so it is never in a response body')
+        .option('--description <text>', 'A note for your own reference')
+        .option('--skip-verification', 'Register without sending the verification ping')
+        .action(async (url, opts) => {
+        // Checked here so a typo does not become a registered endpoint that silently never fires.
+        if (!/^https?:\/\//i.test(url)) {
+            throw new CliError(`"${url}" is not a URL. Expected something starting http:// or https://`, 'INVALID_URL', EXIT.USAGE);
+        }
+        const created = await (await getClient()).webhooks.register({
+            url,
+            secret: opts.secret,
+            eventTypes: opts.events?.split(',').map((e) => e.trim()).filter(Boolean),
+            description: opts.description,
+            skipVerification: opts.skipVerification,
+        });
+        printOutput({ ...created });
+        if (machineOutput())
+            return;
+        human('');
+        human(`  Registered ${created.url}`);
+        human(`  ${created.id}`);
+        if (created.secret) {
+            human('');
+            human(`  Signing secret: ${created.secret}`);
+            // Said plainly because there is no second chance: rotating is the only recovery, and it
+            // invalidates whatever the previous secret was already signing.
+            human('  SAVE THIS NOW — it is shown once and cannot be retrieved. Verify every delivery');
+            human('  against it, or you cannot tell a real event from anything else that finds the URL.');
+        }
+        if (created.verified === false) {
+            human('');
+            human(`  Not verified${created.verification_error ? `: ${created.verification_error}` : '.'}`);
+            hint(`certen webhooks verify ${created.id}`);
+        }
+    });
+    webhooks
+        .command('remove <id>')
+        .description('Stop delivering to an endpoint')
+        .action(async (id) => {
+        const result = await (await getClient()).webhooks.remove(id);
+        printOutput({ ...result });
+        if (!machineOutput()) {
+            human('');
+            human(`  ${id} will no longer receive events.`);
+        }
+    });
+    webhooks
+        .command('verify <id>')
+        .description('Re-run the verification ping against an endpoint')
+        .action(async (id) => {
+        const result = await (await getClient()).webhooks.verify(id);
+        printOutput({ ...result });
+        if (machineOutput())
+            return;
+        human('');
+        human(result.verified
+            ? `  ${result.url} responded correctly.`
+            : `  ${result.url} did not verify${result.verification_error ? `: ${result.verification_error}` : '.'}`);
+    });
+    webhooks
+        .command('rotate-secret <id>')
+        .description('Issue a new signing secret (invalidates the current one)')
+        .action(async (id) => {
+        const result = await (await getClient()).webhooks.rotateSecret(id);
+        printOutput({ ...result });
+        if (machineOutput())
+            return;
+        human('');
+        human(`  New signing secret: ${result.secret}`);
+        human('  SAVE THIS NOW. The previous secret stopped working the moment this was issued, so');
+        human('  deliveries will fail verification until your receiver is using the new one.');
+    });
+    webhooks
+        .command('deliveries')
+        .description('Delivery attempts, newest first — including why one failed')
+        .option('--limit <n>', 'How many to fetch (page size with --all)', '50')
+        .option('--offset <n>', 'Skip this many')
+        .option('--all', 'Fetch every page')
+        .option('--failed', 'Only deliveries that did not succeed')
+        .action(async (opts) => {
+        const limit = Number(opts.limit);
+        if (!Number.isInteger(limit) || limit < 1) {
+            throw new CliError(`"${opts.limit}" is not a whole number for --limit.`, 'INVALID_NUMBER', EXIT.USAGE);
+        }
+        const offset = opts.offset === undefined ? undefined : Number(opts.offset);
+        if (opts.all && offset !== undefined) {
+            throw new CliError('--all starts from the beginning, so --offset has no meaning with it. Use one or the other.', 'CONFLICTING_PAGING_FLAGS', EXIT.USAGE);
+        }
+        const client = await getClient();
+        const all = [];
+        if (opts.all) {
+            for await (const d of client.webhooks.deliveriesAll(limit))
+                all.push(d);
+        }
+        else {
+            all.push(...(await client.webhooks.deliveries({ limit, offset })).deliveries);
+        }
+        // Filtered here rather than server-side because the endpoint takes no status filter; doing
+        // it locally is honest about that and still answers the question people arrive with.
+        const deliveries = opts.failed
+            ? all.filter((d) => d.status !== 'delivered' && d.status !== 'succeeded')
+            : all;
+        if (machineOutput()) {
+            printOutput({ deliveries });
+            return;
+        }
+        human('');
+        if (deliveries.length === 0) {
+            human(opts.failed ? '  No failed deliveries.' : '  No deliveries yet.');
+            return;
+        }
+        for (const d of deliveries) {
+            const when = String(d.created_at ?? '').slice(0, 19).replace('T', ' ');
+            human(`  ${when}  ${String(d.event_type ?? '?').padEnd(28)} ${d.status ?? '?'}`);
+            if (d.response_status)
+                human(`    HTTP ${d.response_status}, attempt ${d.attempts ?? 1}`);
+            if (d.error)
+                human(`    ${d.error}`);
+            if (d.status && d.status !== 'delivered' && d.status !== 'succeeded') {
+                human(`    retry it: certen webhooks redeliver ${d.id}`);
+            }
+        }
+        human('');
+    });
+    webhooks
+        .command('redeliver <id>')
+        .description('Send a delivery again')
+        .action(async (id) => {
+        const result = await (await getClient()).webhooks.redeliver(id);
+        printOutput({ ...result });
+        if (!machineOutput()) {
+            human('');
+            human('  Queued for delivery again.');
+            // Worth saying: this is one of the few genuinely non-idempotent operations on the API.
+            human('  Each call delivers again — make sure your receiver can handle a repeat.');
+        }
+    });
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/commands/webhooks.js.map

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

package/dist/commands/whoami.d.ts

@@ -0,0 +1,16 @@
+import { Command } from 'commander';
+/**
+ * `certen whoami` — which credential is this, against which gateway, and what standing does it
+ * have.
+ *
+ * Distinct from `certen auth status`, which reads local config and never contacts anything. The
+ * two questions are different and conflating them is how someone concludes their setup is fine
+ * while every request 401s.
+ *
+ * **What this deliberately does NOT show: the organization name and the caller's role.** With a
+ * machine API key there is no endpoint that returns either. `GET /v1/me` exists but requires a
+ * Firebase ID token from the self-service portal, and nothing on the API-key surface echoes an
+ * org name. Inventing a plausible-looking value, or silently omitting the fields as though they
+ * were merely absent, would both be worse than saying where they live.
+ */
+export declare function registerWhoamiCommands(program: Command): void;

package/dist/commands/whoami.js

@@ -0,0 +1,98 @@
+import { CertenClient, CertenError } from '@certen.io/sdk';
+import { getApiKey, getApiUrl, getPortalUrl, readConfig } from '../config.js';
+import { printOutput, hint, human, isJsonMode, usd } from '../output.js';
+/**
+ * `certen whoami` — which credential is this, against which gateway, and what standing does it
+ * have.
+ *
+ * Distinct from `certen auth status`, which reads local config and never contacts anything. The
+ * two questions are different and conflating them is how someone concludes their setup is fine
+ * while every request 401s.
+ *
+ * **What this deliberately does NOT show: the organization name and the caller's role.** With a
+ * machine API key there is no endpoint that returns either. `GET /v1/me` exists but requires a
+ * Firebase ID token from the self-service portal, and nothing on the API-key surface echoes an
+ * org name. Inventing a plausible-looking value, or silently omitting the fields as though they
+ * were merely absent, would both be worse than saying where they live.
+ */
+export function registerWhoamiCommands(program) {
+    program
+        .command('whoami')
+        .description('Which key, which gateway, and what standing it has (contacts the gateway)')
+        .action(async () => {
+        const config = readConfig();
+        const apiUrl = getApiUrl();
+        // Resolved rather than read from config, so the env var takes the precedence it actually has.
+        const apiKey = await getApiKey();
+        const source = process.env.CERTEN_API_KEY
+            ? 'CERTEN_API_KEY env'
+            : config.storage === 'keyring' ? 'OS keyring' : '~/.certen/config.json';
+        const client = new CertenClient({ apiKey, baseUrl: apiUrl });
+        // `me` is the credential asking about itself; `balance` is its standing. Each degrades
+        // independently, so a key that can read one but not the other still reports what it can.
+        //
+        // The old third call to `admin.getUsage` is gone. It existed only to INFER whether the key
+        // held `admin:read`, by seeing whether the call succeeded — and `me.scopes` now says so
+        // outright. Inferring permissions by making calls and reading the refusals is a strange way
+        // to answer a question the gateway can answer directly.
+        const [me, balance] = await Promise.all([
+            client.me().catch(() => null),
+            client.billing.balance().catch((err) => (err instanceof CertenError ? err : null)),
+        ]);
+        const balanceOk = balance !== null && !(balance instanceof CertenError);
+        const b = balanceOk ? balance : null;
+        // The full structure goes to machines; humans get the rendered summary below. The table
+        // renderer flattens `credit` and `usage` to raw JSON on one line, which is strictly worse
+        // than the three lines that follow.
+        if (isJsonMode()) {
+            printOutput({
+                api_url: apiUrl,
+                portal_url: getPortalUrl(),
+                key_prefix: `${apiKey.substring(0, 12)}...`,
+                key_source: source,
+                organization: me ? { id: me.org.id, name: me.org.name } : null,
+                key_id: me?.key?.id ?? null,
+                rate_limit_rpm: me?.key?.rate_limit_rpm ?? null,
+                account_status: b?.status ?? 'unknown',
+                spendable_usd: b?.spendable_usd ?? null,
+                available_usd: b?.available_usd ?? null,
+                held_usd: b?.held_usd ?? null,
+                credit: b?.credit ?? null,
+                // Granted, not observed. This used to be a guess assembled from which probe calls
+                // happened to succeed, which could only ever describe the scopes it had thought to test.
+                scopes: me?.scopes ?? null,
+            });
+            return;
+        }
+        human('');
+        human(`  Key      ${apiKey.substring(0, 12)}...  (${source})`);
+        human(`  Gateway  ${apiUrl}`);
+        if (b) {
+            human(`  Account  ${b.status}`);
+            human(`  Spendable ${usd(b.spendable_usd)}`);
+            if (b.credit && b.credit.kind !== 'none') {
+                if (b.credit.expired) {
+                    human(`  Credit   ${b.credit.kind} — EXPIRED`);
+                }
+                else if (b.credit.expires_at) {
+                    const days = Math.max(0, Math.round((new Date(b.credit.expires_at).getTime() - Date.now()) / 86_400_000));
+                    human(`  Credit   ${b.credit.label ?? b.credit.kind} — ends in ${days} day(s)`);
+                }
+            }
+        }
+        else if (balance instanceof CertenError && balance.status === 403) {
+            human('  Account  (this key has no billing:read scope)');
+        }
+        else {
+            human('  Account  (could not read)');
+        }
+        human('');
+        human('  Organization name, your role, and team management are not available to an API key.');
+        human('  Inviting a teammate needs a signed-in portal session — deliberately, since a leaked');
+        human('  machine key must not be able to add people to your organization.');
+        human(`  ${getPortalUrl()}`);
+        hint('');
+        hint('Check the whole setup end to end: certen doctor');
+    });
+}
+//# sourceMappingURL=whoami.js.map

package/dist/commands/whoami.js.map

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

package/dist/config.d.ts

@@ -10,7 +10,49 @@ export interface CliConfig {
      * which key is selected without round-tripping through the keyring.
      */
     key_prefix?: string;
+    /**
+     * Identities this machine created, most recent last.
+     *
+     * The gateway has no identity collection route, and `/v1/portfolio` — the only cross-identity
+     * view — keys on ADI URL and does not return the UUID that every other command takes. So an id
+     * that is not written down when it is minted is unrecoverable: `certen identity create` printed
+     * it once, and after that the only copy was the user's scrollback.
+     *
+     * That is what made `init` unable to be idempotent in a useful way. It could see that
+     * identities existed and still had nothing to put after `--identity`.
+     */
+    identities?: Array<{
+        id: string;
+        adi_url: string;
+        chains: string[];
+        created_at: string;
+    }>;
 }
+/**
+ * Record an identity this machine created.
+ *
+ * Deduplicated on id, and appended rather than replaced, so creating a second identity does not
+ * make the first unfindable.
+ */
+export declare function rememberIdentity(entry: {
+    id: string;
+    adi_url: string;
+    chains: string[];
+}): void;
+/** The most recently created identity on this machine, if any. */
+export declare function lastIdentity(): {
+    id: string;
+    adi_url: string;
+    chains: string[];
+} | undefined;
+/**
+ * Drop a retired identity from the local record.
+ *
+ * Without this, `certen init` would keep offering to reuse an identity the gateway no longer
+ * tracks. It recovers on its own — the lookup 404s and it creates a fresh one — but silently
+ * doing the right thing after an avoidable round trip is worse than not recording a dead id.
+ */
+export declare function forgetIdentity(id: string): void;
 export declare function readConfig(): CliConfig;
 /**
  * Write the config file with 0600 perms (owner read/write only). On Windows,
@@ -36,4 +78,18 @@ export declare function clearApiKey(): Promise<void>;
  */
 export declare const DEFAULT_API_URL = "https://gateway.kompendium.co";
 export declare function getApiUrl(): string;
+/**
+ * Where a human goes to do the things a machine key cannot — register a payer wallet, invite a
+ * teammate, revoke a key.
+ *
+ * Derived from the API URL rather than hardcoded, so a self-hosted gateway points at its own
+ * portal instead of at ours. `CERTEN_PORTAL_URL` overrides for a deployment that serves the two
+ * from different hosts.
+ *
+ * This exists because the funding hint printed the literal string "/portal" as an instruction — a
+ * bare path with no host, which is not somewhere anyone can go. The 402 handler had it right all
+ * along by reading `portal_url` off the error; there was simply nothing equivalent for the paths
+ * that have no error to read it from.
+ */
+export declare function getPortalUrl(): string;
 export declare function getOutputFormat(): 'table' | 'json';

package/dist/config.js

@@ -4,6 +4,38 @@ import { homedir } from 'os';
 import { UsageError } from './errors.js';
 const CONFIG_DIR = join(homedir(), '.certen');
 const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+/**
+ * Record an identity this machine created.
+ *
+ * Deduplicated on id, and appended rather than replaced, so creating a second identity does not
+ * make the first unfindable.
+ */
+export function rememberIdentity(entry) {
+    const cfg = readConfig();
+    const identities = (cfg.identities ?? []).filter((i) => i.id !== entry.id);
+    identities.push({ ...entry, created_at: new Date().toISOString() });
+    cfg.identities = identities;
+    writeConfig(cfg);
+}
+/** The most recently created identity on this machine, if any. */
+export function lastIdentity() {
+    const all = readConfig().identities ?? [];
+    return all.length > 0 ? all[all.length - 1] : undefined;
+}
+/**
+ * Drop a retired identity from the local record.
+ *
+ * Without this, `certen init` would keep offering to reuse an identity the gateway no longer
+ * tracks. It recovers on its own — the lookup 404s and it creates a fresh one — but silently
+ * doing the right thing after an avoidable round trip is worse than not recording a dead id.
+ */
+export function forgetIdentity(id) {
+    const cfg = readConfig();
+    if (!cfg.identities?.some((i) => i.id === id))
+        return;
+    cfg.identities = cfg.identities.filter((i) => i.id !== id);
+    writeConfig(cfg);
+}
 export function readConfig() {
     if (!existsSync(CONFIG_FILE)) {
         return {};
@@ -147,6 +179,25 @@ export function getApiUrl() {
     const cfg = readConfig();
     return cfg.api_url ?? DEFAULT_API_URL;
 }
+/**
+ * Where a human goes to do the things a machine key cannot — register a payer wallet, invite a
+ * teammate, revoke a key.
+ *
+ * Derived from the API URL rather than hardcoded, so a self-hosted gateway points at its own
+ * portal instead of at ours. `CERTEN_PORTAL_URL` overrides for a deployment that serves the two
+ * from different hosts.
+ *
+ * This exists because the funding hint printed the literal string "/portal" as an instruction — a
+ * bare path with no host, which is not somewhere anyone can go. The 402 handler had it right all
+ * along by reading `portal_url` off the error; there was simply nothing equivalent for the paths
+ * that have no error to read it from.
+ */
+export function getPortalUrl() {
+    const envUrl = process.env.CERTEN_PORTAL_URL;
+    if (envUrl)
+        return envUrl;
+    return `${getApiUrl().replace(/\/+$/, '')}/portal`;
+}
 export function getOutputFormat() {
     const cfg = readConfig();
     return cfg.output ?? 'table';

package/dist/config.js.map

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

package/dist/errors.d.ts

@@ -29,7 +29,20 @@ export declare class CliError extends Error {
     readonly code: string;
     readonly exitCode: ExitCode;
     readonly retryable: boolean;
-    constructor(message: string, code: string, exitCode?: ExitCode, retryable?: boolean);
+    /**
+     * Structured payload carried alongside the failure.
+     *
+     * Some commands fail and still have a result worth handing over — `doctor` is the case this
+     * exists for: the diagnosis ran successfully and every check it performed is exactly what an
+     * automated caller wants, but "a check failed" must still be a non-zero exit or CI treats a
+     * broken setup as a working one. Discarding the checks to signal the failure would make the
+     * machine interface strictly less useful than the human one.
+     *
+     * Additive, and rendered under `error.details`. A consumer that ignores unknown keys is
+     * unaffected, which is the same property the 402 payment fields rely on.
+     */
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code: string, exitCode?: ExitCode, retryable?: boolean, details?: Record<string, unknown>);
 }
 /** A wrong invocation: exits 2, never retryable. */
 export declare class UsageError extends CliError {

package/dist/errors.js

@@ -28,12 +28,26 @@ export class CliError extends Error {
     code;
     exitCode;
     retryable;
-    constructor(message, code, exitCode = EXIT.FAILED, retryable = false) {
+    /**
+     * Structured payload carried alongside the failure.
+     *
+     * Some commands fail and still have a result worth handing over — `doctor` is the case this
+     * exists for: the diagnosis ran successfully and every check it performed is exactly what an
+     * automated caller wants, but "a check failed" must still be a non-zero exit or CI treats a
+     * broken setup as a working one. Discarding the checks to signal the failure would make the
+     * machine interface strictly less useful than the human one.
+     *
+     * Additive, and rendered under `error.details`. A consumer that ignores unknown keys is
+     * unaffected, which is the same property the 402 payment fields rely on.
+     */
+    details;
+    constructor(message, code, exitCode = EXIT.FAILED, retryable = false, details) {
         super(message);
         this.name = 'CliError';
         this.code = code;
         this.exitCode = exitCode;
         this.retryable = retryable;
+        this.details = details;
     }
 }
 /** A wrong invocation: exits 2, never retryable. */

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,eAAe;IACf,EAAE,EAAE,CAAC;IACL,+FAA+F;IAC/F,MAAM,EAAE,CAAC;IACT,sFAAsF;IACtF,KAAK,EAAE,CAAC;IACR,sEAAsE;IACtE,WAAW,EAAE,CAAC;CACN,CAAC;AAIX;;;;;GAKG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,IAAI,CAAS;IACb,QAAQ,CAAW;IACnB,SAAS,CAAU;IAE5B,YAAY,OAAe,EAAE,IAAY,EAAE,WAAqB,IAAI,CAAC,MAAM,EAAE,SAAS,GAAG,KAAK;QAC5F,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAED,oDAAoD;AACpD,MAAM,OAAO,UAAW,SAAQ,QAAQ;IACtC,YAAY,OAAe,EAAE,IAAI,GAAG,aAAa;QAC/C,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,eAAe;IACf,EAAE,EAAE,CAAC;IACL,+FAA+F;IAC/F,MAAM,EAAE,CAAC;IACT,sFAAsF;IACtF,KAAK,EAAE,CAAC;IACR,sEAAsE;IACtE,WAAW,EAAE,CAAC;CACN,CAAC;AAIX;;;;;GAKG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,IAAI,CAAS;IACb,QAAQ,CAAW;IACnB,SAAS,CAAU;IAC5B;;;;;;;;;;;OAWG;IACM,OAAO,CAA2B;IAE3C,YACE,OAAe,EACf,IAAY,EACZ,WAAqB,IAAI,CAAC,MAAM,EAChC,SAAS,GAAG,KAAK,EACjB,OAAiC;QAEjC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,oDAAoD;AACpD,MAAM,OAAO,UAAW,SAAQ,QAAQ;IACtC,YAAY,OAAe,EAAE,IAAI,GAAG,aAAa;QAC/C,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF"}

package/dist/funding-guard.d.ts

@@ -0,0 +1,40 @@
+import type { CertenClient } from '@certen.io/sdk';
+export declare function faucetFor(chain: string): string | undefined;
+/** Does this intent move value? A zero or absent amount needs no funded account. */
+export declare function movesValue(intent: Record<string, unknown>): boolean;
+/**
+ * Read one identity's funding position on one chain.
+ *
+ * Returns null whenever the answer is not knowable, which the caller must treat as "do not
+ * block" rather than as zero.
+ */
+/**
+ * Per-chain balances as `GET /v1/identity/{id}` already returns them.
+ *
+ * Accepted so a caller that has just fetched the identity does not pay for a second read of the
+ * same numbers — see the note on `assertFundedForValue`.
+ */
+export type KnownBalances = Array<{
+    chain_id: string;
+    address: string;
+    token?: string;
+    balance: string;
+}>;
+/**
+ * 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 declare function assertFundedForValue(client: CertenClient, identityId: string, chain: string | undefined, intent: Record<string, unknown>, force: boolean, 
+/**
+ * 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?: KnownBalances): Promise<void>;