APN security model

Agent Payment Node (APN) assumes the agent is not trusted with authority. The owner sets limits in advance, a human approves each transfer, bridge and swap in a foreground terminal, and APN refuses anything the limits do not admit. This page covers the owner allowlist, caps, approval, the custody threat model and how to verify a release.

Updated

How does APN stop an AI agent from overspending?

Nothing moves money without limits the owner set. APN never fills in a missing cap, account, recipient or amount. Three layers work together:

  • The owner allowlist admits each exact asset on a rail, with per-operation and daily caps.
  • The profile policy (wallet policy set) limits local x402 payments.
  • Foreground approval puts a human at a terminal before every transfer, bridge and swap signature. Standard x402 purchases run unattended, but only inside the profile policy.

The agent can prepare and track operations through the CLI or MCP. It cannot activate a policy, raise a limit or approve a transfer.

What is the owner allowlist?

APN ships a frozen inventory of networks and exact asset identities. Every rail is disabled in it and no caps exist. Money authority comes only from an owner policy that the owner stages and then activates in a foreground terminal.

The policy admits each exact asset on one of five rails: direct, x402, gasless, bridge or swap. Each admission carries a per-operation cap and a daily cap in atomic units. Every rail except direct also needs an exact mechanism, which is the provider and reference (for example a bridge route or the x402 Permit2 proxy).

  • The policy file is apn.allowlist-policy-file.v1 JSON. A missing or extra field refuses the whole file.
  • Every staged revision needs a new overlayVersion.
  • effectiveAt is required, and expiresAt is optional. After expiry the activation stops being usable.
  • The file must be an owner-owned regular file with an absolute canonical path, no symbolic links, not writable by group or others, and at most 256 KiB.
  • Resolution is exact: allowlist resolve has no symbol or address fallback.
apn allowlist policy stage --profile agent --file /absolute/path/policy.json
apn allowlist policy activate --profile agent --revision 1        # foreground terminal, typed code
apn allowlist policy status --profile <profile>
apn allowlist policy revoke --profile <profile> --revision <revision>

Staging never grants authority. Activation does, and only after the owner reviews the screen. See the quickstart for a worked first policy.

How do APN spending caps work?

Each admission has a positive per-operation cap that cannot exceed its daily cap. Caps are in atomic units of the asset. The README's example admits Base USDC with 3000000 per transfer and 10000000 per day, which is 3 USDC and 10 USDC. These numbers are examples only, and nothing in APN defaults to them.

  • Daily caps are per rail, but the usage ledger counts an asset's usage per account, network and asset across all rails, by UTC day. Spending on one rail can only narrow another rail, never widen it.
  • Approval reserves the amount in the shared usage ledger before signing.
  • An unproved hold counts on every day, because its effect could still land later. Abandoning an operation proves nothing about a payment that may have been sent, so it never silently releases the hold.
  • Recipient pins (recipients, 1 to 16 addresses) restrict who an admission may pay. Without a pin the policy does not restrict recipients, and the foreground approval screen shows the recipient instead.

How does foreground approval with a typed code work?

A prepare command freezes one exact effect and signs nothing. An approve or execute command re-checks the frozen facts and the active policy, shows the exact terms in a foreground terminal and asks for a typed code before signing.

  • Foreground approval requires stdin and stderr attached to real TTYs.
  • The code is exact and bound to the operation, and it must be typed within 60 seconds.
  • A timeout or interruption writes nothing.
  • For allowlist activation, the owner types the six-character code printed under the screen. The screen shows the profile, accounts, every admission with caps, the full mechanism pin and the digests.
  • Revoking an active policy shows the same screen and needs its own typed code.

The README states the limit of this: it is a human-confirmation boundary, not protection against a compromised user session. Over MCP, no approval can happen. apn_foreground_handoff returns the exact command for the human instead.

What is APN's custody and threat model?

Local wallets are local_software_disposable custody, not savings custody. The wallet file is a versioned AES-256-GCM envelope. A random 256-bit wrapping secret lives in the macOS login Keychain, and HKDF-SHA-256 derives a per-write key. State uses owner-only permissions, symlink and hardlink rejection, kernel advisory locks and fsync-plus-atomic-rename writes.

What encryption does and does not cover, in the README's words:

  • It protects a copied ~/.apn without the Keychain secret.
  • It does not protect against compromise of the same unlocked login session, process, user or host.
  • Transient key copies in JavaScript memory are not guaranteed to be zeroized.
  • Missing Keychain material, failed authentication, unsafe permissions or identity mismatch fail closed and never rotate a wallet silently.
  • Raw private keys, wrapping secrets, signed transaction bytes, x402 signatures and payment headers never appear in command output, public operation state or receipts.

A Coinbase sign-in passes the account email and a one-time code to the pinned awal as command-line arguments while that child runs, so another process of the same user could read the code with ps during the 30-second provider timeout. APN never prints, logs or stores that code. APN also treats seller text as untrusted: x402 refusals keep seller values out of the message.

How do I verify an APN release?

Release artifacts are built twice with Node 24.15.0 and must be byte-identical. The workflow emits the npm tarball, an SPDX 2.3 SBOM and a release manifest that binds names, sizes and SHA-256 digests to the exact commit. GitHub artifact attestations bind those bytes to the pinned workflow identity.

gh attestation verify nuanu-ai-apn-<version>.tgz \
  --repo nuanu-ai/agent-payment-node \
  --signer-workflow nuanu-ai/agent-payment-node/.github/workflows/release.yml \
  --source-ref refs/heads/main \
  --deny-self-hosted-runners

node scripts/verify-supply-chain.mjs verify \
  --artifact nuanu-ai-apn-<version>.tgz \
  --sbom nuanu-ai-apn-<version>.spdx.json \
  --manifest nuanu-ai-apn-<version>.release.json \
  --formula Formula/apn.rb
  • The verifier rejects mutable URLs, version drift and any digest not in the manifest.
  • Releases come only from the manually dispatched release workflow on a protected vX.Y.Z tag. Publication and Homebrew updates are separate owner actions.
  • The archive ships npm-shrinkwrap.json, so installation resolves the exact integrity-pinned dependency closure.
  • A matching version number does not prove an artifact contains a given change. Check apn --version, the release provenance and apn help --json together.

Release digests are listed on the releases page.

How do I report an APN vulnerability?

Use GitHub private vulnerability reporting for the repository. Do not open a public issue, and do not include wallet secrets, credentials, private keys, recovery material or live payment authorization in a report. Security fixes are provided for the most recent published release.

What does APN's test evidence prove?

The test suite covers encryption, permissions, concurrency, restart, byte-identical recovery, idempotency, receipts and every family's journeys without public network traffic or money. The README calls these source proof, not live payment proof. Live mainnet acceptance is recorded per family in its guide. See recovery for the proof boundary.

Questions

Can an AI agent spend money through APN without limits?

No. Nothing moves money without limits the owner set, and APN never fills in a missing cap, account, recipient or amount.

What is the APN allowlist?

It is the owner's policy that admits each exact asset on a rail (direct, x402, gasless, bridge or swap) with per-operation and daily caps. The owner stages it and activates it in a foreground terminal.

Does APN protect against malware on my Mac?

Not fully. Encryption does not protect against compromise of the same unlocked login session, process, user or host, and foreground approval is not protection against a compromised user session.

Is APN audited?

The repository does not state an external audit. It documents deterministic tests as source proof and records live acceptance per family in each guide.

How do I check that a release is genuine?

Run gh attestation verify on the tarball and node scripts/verify-supply-chain.mjs verify with the SBOM, manifest and Formula, as shown above.

Sources
  1. docs/allowlist-policy.md
  2. README: How APN works (Owner limits)
  3. README: Custody and threat model
  4. README: Verify a release
  5. README: Proof boundary
  6. SECURITY.md
  7. docs/x402-offer-selection.md: seller text is untrusted