Skip to content

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

Closed
raubrey-stripe wants to merge 1 commit into
mainfrom
raubrey/mpp-pay-sdk
Closed

raubrey-stripe wants to merge 1 commit into
mainfrom
raubrey/mpp-pay-sdk

Conversation

@raubrey-stripe

@raubrey-stripe raubrey-stripe commented Oct 27, 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.

This picks up raubrey-stripe's branch, which first moved the MPP basics into the SDK.

SDK API

  • link.mpp.decode(request) probes the URL without credentials. It returns either { payment_required: false, response } or { payment_required: true, challenges, request }, where request is the request after any safe redirects.
  • link.mpp.pay(request, { spendRequestId }) re-fetches the challenge and pays it with the approved spend request's SPT.
  • 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 and the Eve extension.
  • link-cli no longer depends on mppx at runtime; it moves to the CLI's devDependencies (used only by tests).

Behavior change: pay-time verification replaces challenge pinning

Before, the CLI pinned the challenge decoded before approval and compared it, minus the rotating _mppx_nonce (#490), against the challenge fetched after approval. Now pay checks the freshly fetched challenge against the approved spend request instead:

  • amount, currency and network ID must match the spend request, or pay throws before retrieving the SPT.
  • The challenge must be on the same origin as the request passed to pay, or pay throws without sending a credential. The payment itself never follows redirects.
  • If the fetch no longer returns 402, pay returns that response without paying. So retrying with the same request and spend request after an uncertain result (for example a 503) doesn't create a second payment.

I checked this against mppx 0.13.4:

  • The mppx client pins nothing.
  • The server HMAC-binds every challenge field and charges the challenge's amount to the SPT.
  • The fields this check skips (description, metadata, externalId, paymentMethodTypes) don't change the amount or the recipient. The server checks externalId against the credential itself.

This also survives process restarts, and works for a future server-side /pay/mpp.

Review questions

  • Is checking against the spend request instead of the full pinned challenge acceptable as the security boundary?
  • After a challenge is re-fetched, it has a new ID. The server's PaymentIntent idempotency key is mpp_<challengeId>_<spt>, so Stripe's duplicate-payment check doesn't apply when retrying with the same SPT. Double-charge protection then rests on the SPT's own usage limits plus the merchant's request idempotency. Can someone confirm the SPT's reuse limits?
  • The SDK bundles mppx (tsup noExternal; it moves to devDependencies). mppx's entry points re-export viem-based payment methods. With mppx external, Eve's extension discovery compiled that graph and hung in CI. Bundled and tree-shaken, it adds about 136KB (mppx, ox, @noble/hashes, eventsource-parser) and no viem. Eve discovery is still slower: about 24s cold and 14.5s warm in CI, against 17.6s and 7.6s on main. So this PR raises the discovery test limits. Two questions: is that startup cost acceptable for Eve agents, and is it OK that picking up an mppx fix now requires an SDK release?
  • link-cli mpp pay drops --approved-challenge, which only generated continuation commands used; continuations now carry the request after redirects. This is a breaking change, so the CLI's changeset bumps minor instead of patch; passing the flag now fails fast with a specific INVALID_INPUT error telling callers to retry with --spend-request-id instead.

@raubrey-stripe
raubrey-stripe requested a review from a team as a code owner October 27, 2026 18:07
@ksn-stripe
ksn-stripe marked this pull request as draft October 30, 2026 21:51
@ksn-stripe ksn-stripe self-assigned this Oct 30, 2026
@ksn-stripe ksn-stripe changed the title feat: add MPP payment support to Link SDK Add MPP decode and pay to the Link SDK Oct 30, 2026
@ksn-stripe
ksn-stripe changed the base branch from main to ksn/sdk-approval-policy October 30, 2026 21:51
@ksn-stripe
ksn-stripe marked this pull request as ready for review November 4, 2026 14:53
ksn-stripe added a commit that referenced this pull request Nov 4, 2026
LinkAuthResource (device authorization, refresh, revocation), the
createAccessTokenProvider token-refresh wrapper, scope/authorization-detail
helpers, and auth-specific types/errors move from packages/cli/src/auth/ into
packages/sdk/src/auth/ and are exported from @stripe/link-sdk, so an app built
on the SDK can sign in and keep a token fresh without copying CLI internals
(same pattern #489 used for MPP).

LinkAuthResource now requires a clientId option instead of a hardcoded
constant, so an SDK-based app can't silently pose as link-cli.
createAccessTokenProvider now coalesces concurrent refreshes into a single
refreshToken call, since Link rotates the refresh token on every use and two
parallel refreshes would otherwise race.

The CLI keeps its credential storage, pending-device-auth workflow state,
auth upgrade merge logic, and login/logout/status commands. Its own
auth/session.ts becomes a thin wrapper over the SDK's
createAccessTokenProvider that supplies the CLI's exact, unchanged
user-facing messages via the new message options.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Committed-By-Agent: claude
Add link.mpp.decode and link.mpp.pay, with matching mpp_decode and mpp_pay
agent tools, and run link-cli's mpp commands on them. pay checks the fresh
challenge against the approved spend request's terms instead of pinning the
challenge, so link-cli mpp pay drops --approved-challenge.

Co-authored-by: Ryan Aubrey <185865758+raubrey-stripe@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Committed-By-Agent: claude
@ksn-stripe
ksn-stripe changed the base branch from ksn/sdk-approval-policy to main November 4, 2026 20:10
@ksn-stripe ksn-stripe closed this Nov 16, 2026
ksn-stripe added a commit that referenced this pull request 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

Copy link
Copy Markdown
Contributor

Reimplemented in #563 to address conflicts

ksn-stripe added a commit that referenced this pull request Nov 17, 2026
* Move MPP decode and pay into @stripe/link-sdk

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>

* Keep MPP challenge pinning in the SDK

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

* Mention Mastra MPP tools in changeset

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

* Keep merchant MPP requests off Link headers and pin the paid destination

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

---------

Co-authored-by: Ryan Aubrey <185865758+raubrey-stripe@users.noreply.github.com>
Co-authored-by: codex <noreply@openai.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
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.

3 participants