feat(extensions): SIWX Extension

[sragss]

Implements CAIP-122 compliant Sign-In-With-X (SIWX) extension for x402 v2 protocol aligned with CHANGELOG-v2.md and sign-in-with-x/TODO.md.

Supported Signature Schemes

• eip191 - personal_sign (EOAs)
• eip1271 - Smart contract wallets
• eip6492 - Counterfactual smart wallets
• siws - Sign-In-With-Solana

Missing: EIP-712 + Stellar.

Note the interface for using Smart Wallets is a bit odd, didn't want to bake the RPC into a generic extension.

  // EOA only
  const result = await verifySIWxSignature(payload);

  // Smart wallet support (EIP-1271/EIP-6492)
  const publicClient = createPublicClient({ chain: base, transport: http()
  });
  const result = await verifySIWxSignature(payload, {
    evmVerifier: publicClient.verifyMessage,
  });

Update 1/17/25

• Added spec.md
• Added wrapFetchWithSIWx exported from @x402/extensions/siwx to match wrapFetchWithPay
• Added examples/typescript/{client,server}/sign-in-with-x

Implementation note: we use conditional middleware in the server example. I considered putting special logic into paymentMiddleware but decided that was against the premise of optional extensions. Another pattern that could be clean would be to put a skipIf: (req) => bool lambda as an optional param in the paymentMiddleware which takes the simple SIWx verification function.

Example logs
Server

Server running at http://localhost:4021
Routes: GET /weather, GET /joke
Payment recorded: 0x6d157C00d034541020fF73A989960D22b299d8e1 for /weather
SIWX auth: 0x6d157C00d034541020fF73A989960D22b299d8e1 for /weather
Payment recorded: 0x6d157C00d034541020fF73A989960D22b299d8e1 for /joke
SIWX auth: 0x6d157C00d034541020fF73A989960D22b299d8e1 for /joke

Client

Client address: 0x6d157C00d034541020fF73A989960D22b299d8e1
Server: http://localhost:4021

--- /weather ---
1. First request (paying)...
   Response: { weather: 'sunny', temperature: 72 }
2. Second request (SIWX auth)...
   Response: { weather: 'sunny', temperature: 72 }

--- /joke ---
1. First request (paying)...
   Response: {
  joke: 'Why do programmers prefer dark mode? Because light attracts bugs.'
}
2. Second request (SIWX auth)...
   Response: {
  joke: 'Why do programmers prefer dark mode? Because light attracts bugs.'
}

Done. Each resource required payment once, then SIWX auth worked.

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 0 Sum 1

[vercel]

@sragss is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.

[CarsonRoscoe]

Amazing work @sragss, thank you, will give this a review shortly

[phdargen]

Thanks for your contribution @sragss, excited for this!

@CarsonRoscoe shall we have a spec document for extensions as well, like we have for schemes and transports?
The TODO.md deleted in this PR might be a good starting point for that

There is none for the discovery extension, but might be worth to add, especially for 3rd party sdk devs

[CarsonRoscoe]

@phdargen Agreed, we should have a top level /specs/extensions folder with specs per extension

[CarsonRoscoe]

Hey @sragss!

This is looking really good. Very happy with it from my readings,

My two asks are:

1. Can you add a /specs/extensions/sign-in-with-x.md file outlining the spec as implemented? This will become the north start to ensure Go/Python implementations remain compatible
2. Can you integrate these into an example for testing. For example, a /examples/typescript/clients/sign-in-with-x (using fetch) and /examples/typescript/servers/sign-in-with-x (using express) example that can be run to showcase how a client/server could leverage this extension to prove a client already paid? I'm imagining when running these examples, the flow would be that the server caches payments in memory, and is able to skip payments for clients who already paid. Then the first client run would make payment, while the second one would get the resource without needing payment due to siwx?

Please include a run of the client & server examples in your PR afterwards, we'll consider it additional testing

Great work, I think the examples & spec are all that I need to feel comfortable merging :)

[sragss]

Done.

Update 1/17/25

• Added spec.md
• Added wrapFetchWithSIWx exported from @x402/extensions/siwx to match wrapFetchWithPay and simplify client experience
• Added examples/typescript/{client,server}/sign-in-with-x

Implementation note: we use conditional middleware in the server example. I considered putting special logic into paymentMiddleware but decided that was against the premise of optional extensions. Another pattern that could be clean would be to put a skipIf: (req) => bool lambda as an optional param in the paymentMiddleware which takes the simple SIWx verification function. Punting on that for now.

Example logs
Server

Server running at http://localhost:4021
Routes: GET /weather, GET /joke
Payment recorded: 0x6d157C00d034541020fF73A989960D22b299d8e1 for /weather
SIWX auth: 0x6d157C00d034541020fF73A989960D22b299d8e1 for /weather
Payment recorded: 0x6d157C00d034541020fF73A989960D22b299d8e1 for /joke
SIWX auth: 0x6d157C00d034541020fF73A989960D22b299d8e1 for /joke

Client

Client address: 0x6d157C00d034541020fF73A989960D22b299d8e1
Server: http://localhost:4021

--- /weather ---
1. First request (paying)...
   Response: { weather: 'sunny', temperature: 72 }
2. Second request (SIWX auth)...
   Response: { weather: 'sunny', temperature: 72 }

--- /joke ---
1. First request (paying)...
   Response: {
  joke: 'Why do programmers prefer dark mode? Because light attracts bugs.'
}
2. Second request (SIWX auth)...
   Response: {
  joke: 'Why do programmers prefer dark mode? Because light attracts bugs.'
}

Done. Each resource required payment once, then SIWX auth worked.