@vapi-network/core 0.2.3 → 0.5.0

package/README.md

@@ -1,7 +1,20 @@
-# @vapi-network/core
+# `@vapi-network/core`
 
-The non-custodial x402 protocol, local-wallet policy, discovery merge, network
-guard, and append-only receipt primitives used by `vapi-network`.
+The non-custodial heart of [vAPI Network](https://github.com/vAPI-Network/vapi-network):
+the x402 protocol, the wallet store, spend policy, the network guard, discovery
+merge and the append-only receipt ledger. Keys stay on the caller's machine.
+This package proxies no payment and sends no telemetry.
 
-Keys remain on the caller's machine. This package does not proxy payments or
-send telemetry.
+Two entry points:
+
+- `@vapi-network/core` — everything an agent-driven surface may use: accounts,
+  balances, `WalletStore`, `SpendPolicy`, `resolvePassphrase`, receipts, stats
+  and the x402 primitives.
+- `@vapi-network/core/secrets` — human-only. `exportRecoveryPhrase`,
+  `exportKeystoreKeys`, `createKeystoreWithPhrase` and `decryptPrivateKey`
+  return a recovery phrase or a private key, so they are deliberately not
+  re-exported from the main index and the MCP package is forbidden to import
+  them.
+
+See the [root README](https://github.com/vAPI-Network/vapi-network#readme) for
+the SDK examples, the configuration layout and the custody model.

package/dist/accounts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"accounts.d.ts","sourceRoot":"","sources":["../src/accounts.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAY/C,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,cAAc,GAAG,IAAI,CAAC;IACnC,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;IAC3C,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,MAAM,CAAC,EAAE,QAAQ,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,CAClC,OAAO,EAAE,4BAA4B,KAClC,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;AAEzC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,UAAU,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC;CAC5D,CAAC;AAKF,sFAAsF;AACtF,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAyCjF"}
+{"version":3,"file":"accounts.d.ts","sourceRoot":"","sources":["../src/accounts.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAa/C,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,cAAc,GAAG,IAAI,CAAC;IACnC,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;IAC3C,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,MAAM,CAAC,EAAE,QAAQ,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,CAClC,OAAO,EAAE,4BAA4B,KAClC,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;AAEzC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,UAAU,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC;CAC5D,CAAC;AAKF,sFAAsF;AACtF,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAyCjF"}

package/dist/agent-guard.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Whether this run may put a secret on the screen.
+ *
+ * A recovery phrase, a private key and a passphrase are the only secrets vAPI
+ * has, and an agent never needs one to pay for an API. So they are shown only
+ * when a person is demonstrably present: stdin and stdout are both a real
+ * terminal, and no environment variable says an agent or a CI job is driving
+ * the command. Addresses, balances, receipts and wallet names are not secrets
+ * and are never gated here.
+ */
+/**
+ * The variables that mean "something other than a person is reading this".
+ * `VAPI_NO_SECRETS` is the documented way to lock down a machine's agent
+ * configuration; the rest are set by the agents and CI systems themselves.
+ */
+export declare const AGENT_MARKER_VARIABLES: readonly ["VAPI_NO_SECRETS", "CLAUDECODE", "CLAUDE_CODE", "CURSOR_AGENT", "CODEX_SANDBOX", "OPENAI_CODEX", "AGENT", "CI"];
+export type AgentMarker = (typeof AGENT_MARKER_VARIABLES)[number];
+/** Whether each standard stream is attached to a terminal. */
+export type SecretsStreams = {
+    stdinIsTTY: boolean;
+    stdoutIsTTY: boolean;
+};
+/**
+ * The verdict. `reason` is written to be shown to a person directly after the
+ * refusal line, so it names the stream or the variable that decided it.
+ */
+export type SecretsDecision = {
+    allowed: boolean;
+    reason?: string;
+    marker?: AgentMarker;
+};
+/** The first marker variable this environment sets to a non-empty value. */
+export declare function activeAgentMarker(env: NodeJS.ProcessEnv): AgentMarker | undefined;
+/**
+ * Decides whether a secret may be printed. Both streams must be a terminal,
+ * because a redirected stdout writes the secret into a file and a piped stdin
+ * means the answers are scripted; then no agent marker may be set.
+ */
+export declare function secretsAllowed(env: NodeJS.ProcessEnv, streams: SecretsStreams): SecretsDecision;
+//# sourceMappingURL=agent-guard.d.ts.map

package/dist/agent-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-guard.d.ts","sourceRoot":"","sources":["../src/agent-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,2HASzB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,8DAA8D;AAC9D,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,WAAW,GAAG,SAAS,CAEjF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,EAAE,cAAc,GAAG,eAAe,CAY/F"}

package/dist/agent-link.d.ts

@@ -0,0 +1,98 @@
+import type { SecretStore } from "./secret-store.js";
+import type { AgentLink, WalletName, WalletStore } from "./wallet-store.js";
+export declare const AGENT_LINK_STATEMENT = "Link this wallet to a vAPI account as an agent.";
+export declare const AGENT_LINK_REVOKED_MESSAGE = "This agent's link was revoked or has expired. Run vapi login to link it again.";
+export type DeviceLinkStart = {
+    clientId: string;
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    expiresIn: number;
+    interval: number;
+};
+export type AgentTokens = {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    scopes: string[];
+};
+export type LinkResult = {
+    tokens: AgentTokens;
+    owner: `0x${string}`;
+    routerKey?: string;
+    routerBaseUrl?: string;
+    routerKeyError?: string;
+};
+export declare class AgentLinkError extends Error {
+    readonly code: "access_denied" | "expired_token" | "invalid_agent_signature" | "invalid_scope" | "not_linked" | "http";
+    constructor(code: "access_denied" | "expired_token" | "invalid_agent_signature" | "invalid_scope" | "not_linked" | "http", message: string);
+}
+export declare const DEFAULT_AGENT_SCOPES: readonly ["mcp:call", "router.use"];
+export declare function startDeviceLink(args: {
+    apiBase: string;
+    account: {
+        address: `0x${string}`;
+        signMessage(a: {
+            message: string;
+        }): Promise<`0x${string}`>;
+    };
+    label: string;
+    scopes?: string[];
+    routerAllowanceUsd?: number;
+    fetchImpl?: typeof fetch;
+    now?: () => Date;
+}): Promise<DeviceLinkStart>;
+export declare function pollDeviceLink(args: {
+    apiBase: string;
+    start: DeviceLinkStart;
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}): Promise<LinkResult>;
+export declare const agentSecretAccounts: (wallet: WalletName) => {
+    tokens: string;
+    routerStake: string;
+    routerBalance: string;
+};
+/** Renames a linked wallet and its name-keyed credentials as one serialized operation. */
+export declare function renameAgentLinkWallet(args: {
+    secrets: SecretStore;
+    wallets: WalletStore;
+    from: string;
+    to: string;
+}): Promise<import("./wallet-store.js").ResolvedWallet>;
+export declare function saveAgentLink(args: {
+    secrets: SecretStore;
+    wallets: WalletStore;
+    wallet: WalletName;
+    start: DeviceLinkStart;
+    result: LinkResult;
+    apiBase: string;
+    label: string;
+    home?: string;
+}): Promise<AgentLink>;
+export declare function agentAccessToken(args: {
+    secrets: SecretStore;
+    wallets: WalletStore;
+    wallet: WalletName;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}): Promise<string>;
+export declare function agentFetch(args: {
+    secrets: SecretStore;
+    wallets: WalletStore;
+    wallet: WalletName;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}, url: string, init?: RequestInit): Promise<Response>;
+export declare function forgetAgentLink(args: {
+    secrets: SecretStore;
+    wallets: WalletStore;
+    wallet: WalletName;
+    fetchImpl?: typeof fetch;
+    home?: string;
+}): Promise<void>;
+/** Serializes reads and writes of one agent link's credentials across processes. */
+export declare function withAgentCredentialLock<T>(wallets: WalletStore, clientId: string, operation: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=agent-link.d.ts.map

package/dist/agent-link.d.ts.map

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