/agents-pay

agents-pay security model

The threat model, and how each control is enforced. Read this before changing anything in scripts/ — several behaviors that look over-cautious are load-bearing.

Scope: this is the run-time skill

Worth stating before anything else, because there is an adjacent skill that looks like it does the same job.

That last row is why this skill exists separately. When a product mints a session per customer through its own approval flow, the agent is a component inside a system its author controls. When an agent spends its operator's money mid-task, the agent is the thing that might be compromised, so every limit has to hold against the agent. auto_session=True, while valid in build-time guidance, lets a runtime replace an exhausted budget and is unsuitable for this skill.

Neither is wrong. They answer different questions, and agents-build is left untouched by this branch.

The gate only covers what routes through it

A boundary condition worth stating before the trust table, because it is the easiest way to end up with none of these controls while believing you have them.

Strands and LangGraph ship AgentCore Payments integrations (AgentCorePaymentsPlugin, AgentCorePaymentsMiddleware) that intercept 402 from any tool call and settle it. They are genuinely more convenient than registering x402_fetch. They also sit entirely outside this skill: payment happens inside the framework's own wrapper, so x402_policy.py is never consulted.

What that costs, concretely:

An agent that can mint a session can replace a spent budget with a larger one, so the per-session cap stops bounding anything.

Do not run both paths in one process. If the native integration is active and x402_fetch is registered, the model chooses which one settles a given 402, so the gate becomes advisory. Pick one. For an agent spending an operator's money against the open web, pick x402_fetch; if the native path is used anyway, at minimum pass an explicit payment_session_id so budget still comes from a human.

Trust boundaries

The model is inside the threat model, not outside it. The controls hold when hostile model input reaches the registered payment tools. Unrestricted code execution under the same OS identity and AWS credentials is a host compromise and needs a separate process, container, OS account, or IAM boundary.

Why executable controls matter

Two design rules apply throughout this skill:

1. A control that a model can decline is not a control. Every limit in this skill is evaluated in Python before signing on the sanctioned runtime path.
2. Documentation must not claim a guarantee the code does not enforce. Every claim below names the function that implements it, so the two cannot drift silently.

Runtime design

The browser flow is worth stating plainly, because it is the one case where a proof must reach a caller: the model receives a handle, never proof bytes. The handle is single-use, expires in 90 seconds, and is bound to one origin and path, so a handle lifted from a transcript cannot be redeemed for another resource or redeemed twice. attach_browser_payment returns the real header and is therefore for trusted glue, not for the model's tool set.

Security controls and enforcement

Limits of the controls

• Cumulative ceiling. A per-session budget plus human-only session creation bounds spend per session and forces a human into the loop between sessions. It is not a service-side cumulative ceiling across sessions — that requires support in AgentCore Payments, outside a skill's reach. An operator who approves ten sessions has authorized ten budgets.

• Dependency pinning. A skill folder cannot ship a Python lockfile that the host environment will honor. Operators wanting reproducibility should install from a requirements.txt with hashes, or pip install --require-hashes. The skill states floors; it cannot enforce the resolution.

• DNS rebinding. IP pinning closes the common TOCTOU window by dialing the vetted address. A network-level egress allowlist remains the stronger control for a payment-capable agent, and is recommended, not replaced.

  Implementation note worth preserving: the pin must not be implemented by temporarily replacing socket.getaddrinfo. That global is shared, so two concurrent fetches can restore or observe each other's state and a request can end up resolving unpinned, silently reopening the window. The pin therefore lives in the connection pool's network backend, which is per-transport. test_pin_is_not_implemented_by_patching_a_global guards the regression.

• Same-identity code execution. A process with the runtime's OS identity and AWS credentials can modify owner-writable files or call the payment SDK directly. Restrict the model to registered tools, or place the signer and policy behind a separate process, container, OS account, or IAM role.

One config file, with a fixed runtime path

Resource identifiers and the payment policy live in one operator-owned file, ~/.agents-pay/config.json (0600, in a 0700 directory, written atomically):

{
  "resources": { "payment_session_id": "ps-...", "payment_manager_arn": "arn:...", ... },
  "policy":    { "max_per_payment_usd": "0.05", "allowed_networks": ["eip155:84532"], ... }
}

They were separate at first, which forced the operator to hand-copy identifiers between steps. Merging them removed that, but it also bought a control worth naming.

The session ID is a spending credential — it names the budget being drawn down. runtime_config_path() resolves .agents-pay/config.json from the OS account and ignores HOME, AGENTS_PAY_CONFIG, and X402_POLICY_FILE. resolve_resource() then reads the config file first and the environment second, deliberately reversing the usual precedence.

Containers and Lambda may inject resource identifiers when the fixed policy file omits them. The environment cannot select a replacement policy file. File modes protect against other principals; unrestricted code already running as the owner requires a stronger process, container, OS account, or IAM boundary. Tests: test_runtime_ignores_environment_selected_policy_file, test_runtime_config_path_ignores_home_environment, and test_config_file_beats_environment.

Recipient validation

The normal mode requires the payee (payTo) named by the publisher to match an operator-approved entry in allowed_recipients. Missing or empty recipient policy denies every payment. An operator may instead set allow_any_recipient: true, explicitly delegating beneficiary choice to the publisher. The modes are mutually exclusive, and non-boolean values fail closed.

Open-recipient mode does not relax scheme, network, exact asset, origin/resource, per-payment, or cumulative session controls. It does remove the deterministic beneficiary boundary, so it is a deliberate high-risk operator choice.

RecipientValidationTests covers unknown-recipient refusal, missing-allowlist denial, case-insensitive matching, open-recipient acceptance, mode conflicts, malformed values, and retention of the other policy checks.

Origins are optional

HTTPS only, internal-address rejection, manual redirect handling, DNS-rebinding protection, timeouts, and a strict byte limit are enforced unconditionally. An approved domain egress policy is an additional protection for payment-capable agents, but is not required.

So allowed_origins is optional: unset means any public HTTPS site, and a deployment with a known merchant set can still pin it. Test: OptionalOriginTests.

Two ceilings, not a duplicate

A reasonable objection: the session already has a budget, so why does the policy also carry max_per_payment_usd?

Because they bound different things:

With only the session budget, a hostile merchant returns one challenge for the entire remaining balance and drains it in a single payment. A positive, trusted maximum for each payment makes the per-payment bound necessary, not redundant. A missing per-payment ceiling is a refusal, never an unbounded payment. Test: test_missing_per_payment_cap_refuses_rather_than_paying_unbounded.

Role separation is the real boundary

The controls in this skill are meaningful only if the IAM separation described in the official guide holds in the account:

The agent must have neither the ManagementRole nor the ability to run agents_pay_admin.py. If it has both, it can mint a fresh budget whenever it exhausts one and the per-session cap bounds nothing.

The TTY requirement on new-session is defence in depth, not the boundary. An agent running as the operator's own user in an interactive terminal could still drive it — IAM is what actually stops that, which is why the runtime role must exclude CreatePaymentSession.

Validate one document, sign another

The gate can validate a challenge perfectly and still be useless if the signer is handed something else.

An x402 challenge may carry several accepts entries, and the terms can appear both in the payment-required header and in the body. If trusted code validates one entry but forwards the publisher's raw response to generate_payment_header, the SDK may settle terms the policy never saw:

• Ordering. accepts[0] = $50 to an attacker, accepts[1] = $0.10 to the merchant. The gate approves entry 1 and reports $0.10; the signer, given both, settles entry 0.
• Header/body split. A compliant header alongside a hostile body. The gate reads the header and approves; the signer reads the body and authorizes a larger amount on a different chain. The receipt then lies to the operator.

Both are silent: the returned receipt reflects the approved entry, not what was signed. A test that asserts only on the gate's return value can pass while the exploit still works.

The fix is structural: x402_policy rejects conflicting amount aliases and builds a version-canonical vetted entry. x402_fetch reserializes that single entry into a fresh minimal challenge ({"x402Version": ..., "accepts": [vetted]}) and passes only that, with a synthetic content-type header. SignerInputTests asserts on the object handed to the signer, not only the gate's return value.

Rule for anyone changing scripts/: the signer must receive data that trusted code constructed, never data a publisher supplied.

Verification

python3 scripts/test_x402_policy.py                 # all must pass
python3 scripts/agents_pay_admin.py show-config      # confirm 0600 + contents
python3 scripts/agents_pay_admin.py preflight        # wiring + secret exposure

The reproducible evidence is: the test suite passing, a show-config transcript, and a refusal captured against a live endpoint whose recipient is deliberately absent from the allowlist.

Residual risks the operator owns

• The policy is only as tight as its allowlists. A wildcard-ish policy (many recipients, high ceiling) is permitted by the code and is the operator's risk.
• Testnet first. Defaults target Base Sepolia. Moving to mainnet means real money; re-check the ceiling before switching --network.
• Wallet funding is a cap of last resort. Fund the wallet with only what the agent may plausibly spend. It is the final backstop if every other control fails.
• Host or runtime-role compromise is out of scope. An attacker who can execute arbitrary code as the runtime identity, change the policy as its owner, read process memory, or call ProcessPayment directly can bypass this local gate.