Skip to content

Add MPP decode and pay to the Link SDK - #563

Merged
ksn-stripe merged 4 commits into
mainfrom
ksn/mpp-sdk-clean
Nov 17, 2026
Merged

ksn-stripe merged 4 commits into
mainfrom
ksn/mpp-sdk-clean

Conversation

@ksn-stripe

@ksn-stripe ksn-stripe commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

SDK agents can now pay MPP (HTTP 402) merchants with a balance-backed shared payment token, the same flow link-cli mpp decode and mpp pay provide. link-cli mpp now runs on the same SDK code, so the CLI and SDK can't drift apart.

Reimplements #489 on current main to resolve merge conflicts. Two differences from #489:

SDK API

  • link.mpp.decode(request) probes the URL without credentials. It returns either { payment_required: false, response } or { payment_required: true, challenges, www_authenticate, request }, where request is the request after any safe redirects.
  • link.mpp.pay(request, { spendRequestId, approvedChallenge }) re-fetches the challenge and pays it with the approved spend request's SPT. Pass www_authenticate from decode as approvedChallenge.
  • The pure header parser decodeMppChallenges is exported, and link-cli mpp decode now calls it directly instead of parsing challenges itself.
  • New mpp_decode and mpp_pay tools in createLinkTools, the Eve extension, and the Mastra integration. mpp_pay takes an optional approved_challenge.
  • link-cli no longer depends on mppx at runtime; it moves to the CLI's devDependencies (used only by tests).

Pay-time checks

pay refuses to send a credential unless:

  • With approvedChallenge, the re-fetched challenge and the offer mppx selects to sign match it, ignoring only the challenge ID, expiry, and rotating _mppx_nonce (Fix MPP payments when mppx rotates challenge nonces #490). This is the pinning from main, moved into the SDK; the CLI full flow and its continuations pass it as before.
  • amount, currency and network ID match the spend request.
  • The challenge comes from exactly the request passed to pay. decode resolves redirects before approval; pay's re-fetch and payment follow none, so the credential can't move to another path (as on main).

Merchant requests use the caller's fetch without the Link client's defaultHeaders, so Link credentials never reach merchant hosts.

If the fetch no longer returns 402, pay returns that response without paying. So retrying with the same arguments after an uncertain result (for example a 503) doesn't create a second payment.

Review questions (carried over from #489)

  • After a challenge is re-fetched, it has a new ID, so Stripe's mpp_<challengeId>_<spt> idempotency key doesn't dedupe retries with the same SPT. Can someone confirm the SPT's reuse limits?
  • The SDK bundles mppx to avoid Eve discovery hanging on its viem graph. That adds about 136KB and slows Eve discovery (about 24s cold / 14.5s warm in CI vs 17.6s / 7.6s on main), so this raises the discovery test limits. Is that startup cost acceptable, and is it OK that picking up an mppx fix now requires an SDK release?

Validation
SDK, CLI, Eve, and Mastra typechecks and unit tests pass locally, including the pinning tests ported from main. CI covers packaged builds, command continuations, and Eve discovery.

@ksn-stripe ksn-stripe self-assigned this Nov 16, 2026
Add link.mpp.decode and link.mpp.pay, with matching mpp_decode and mpp_pay agent tools, and run link-cli mpp commands on them. Preserve the scope and behavior of #489 on current main, resolving conflicts only.

Co-authored-by: Ryan Aubrey <185865758+raubrey-stripe@users.noreply.github.com>
Committed-By-Agent: codex
Co-authored-by: codex <noreply@openai.com>
Committed-By-Agent: codex
Co-authored-by: codex <noreply@openai.com>
@ksn-stripe
ksn-stripe marked this pull request as ready for review November 17, 2026 14:21
@ksn-stripe
ksn-stripe requested a review from a team as a code owner November 17, 2026 14:21
ksn-stripe and others added 2 commits November 17, 2026 10:31
Restore the approved-challenge checks from main (#325, #525) instead of
replacing them. `link.mpp.pay` accepts an optional `approvedChallenge`
(the `www_authenticate` header returned by `decode`) and refuses a
re-fetched challenge, or an offer mppx selects, whose terms differ from
it. The `mpp_pay` tool exposes this as `approved_challenge`, and
`link-cli mpp pay --approved-challenge` and its continuations work as
on main, so the CLI change is no longer breaking.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Committed-By-Agent: claude
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Committed-By-Agent: claude

@raubrey-stripe raubrey-stripe left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks reasonable, if you can take a look at this agent safety feedback before we merge that'd be great otherwise I imagine it'll come up in a SAT


  1. High: configured headers can reach merchant hosts. The new MPP resource (https://github.com/stripe/link-cli/blob/1f5f0c616af93caf13f2dc72674dde58a6f0a7b9/packages/sdk/src/resources/mpp.ts#L227-L230) uses the SDK fetch wrapper, which adds defaultHeaders to requests. I reproduced defaultHeaders.Authorization being sent to a merchant URL and added again after a cross-origin redirect, before payment approval. Merchant requests need a fetch path that does not inherit credential-bearing Link API headers.
  2. Medium: payment can move to another path after approval. pay() (https://github.com/stripe/link-cli/blob/1f5f0c616af93caf13f2dc72674dde58a6f0a7b9/packages/sdk/src/resources/mpp.ts#L266-L275) rejects a changed origin but follows a same-origin redirect. I reproduced an approved /order-a request sending its payment credential to /order-b when that path returned the same challenge terms. The previous CLI rejected redirects during the approved payment step; that destination pin should be retained.

Merchant requests used the SDK's Link API fetch, so configured
defaultHeaders (such as Authorization) reached merchant hosts, including
after redirects. MppResource now uses the caller's fetch without them.

pay() also followed same-origin redirects when re-fetching an approved
request, so a credential approved for one path could be sent to another.
pay() now follows no redirects, restoring main's destination pin; decode()
still resolves redirects before approval.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Committed-By-Agent: claude
@ksn-stripe

Copy link
Copy Markdown
Contributor Author

Fixed both!

@ksn-stripe
ksn-stripe merged commit fb93282 into main Nov 17, 2026
15 checks passed
@ksn-stripe
ksn-stripe deleted the ksn/mpp-sdk-clean branch November 17, 2026 19:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants