Extensions

extensions/signinwithx

Package signinwithx provides helpers for the sign-in-with-x extension.

import "github.com/x402-foundation/x402/go/v2/extensions/signinwithx"

Package signinwithx provides helpers for the sign-in-with-x extension.

The helpers cover extension declaration, SIGN-IN-WITH-X header encoding and parsing, CAIP-122 SIWE/SIWS message construction, field validation, EVM EOA and smart-wallet signature verification, and Solana Ed25519 verification.

Constants

Source: extensions/signinwithx/types.go:12

const (
	// SolanaMainnet is the CAIP-2 identifier for Solana mainnet-beta.
	SolanaMainnet = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
	// SolanaDevnet is the CAIP-2 identifier for Solana devnet.
	SolanaDevnet = "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"
	// SolanaTestnet is the CAIP-2 identifier for Solana testnet.
	SolanaTestnet = "solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z"
)

Source: extensions/signinwithx/types.go:21

const (
	// ExtensionKey is the x402 extension identifier for sign-in-with-x.
	ExtensionKey = "sign-in-with-x"
	// HeaderName is the HTTP header carrying the base64-encoded SIWX payload.
	HeaderName = "SIGN-IN-WITH-X"
	// Version is the default CAIP-122 version.
	Version = "1"
)

Source: extensions/signinwithx/types.go:30

const (
	// SignatureTypeEIP191 identifies EIP-191 message signatures.
	SignatureTypeEIP191 = "eip191"
	// SignatureTypeEd25519 identifies Ed25519 message signatures.
	SignatureTypeEd25519 = "ed25519"
)

Source: extensions/signinwithx/types.go:37

const (
	// SignatureSchemeEIP191 is the default EVM EOA signature scheme.
	SignatureSchemeEIP191 = "eip191"
	// SignatureSchemeEIP1271 identifies EIP-1271 smart wallet verification.
	SignatureSchemeEIP1271 = "eip1271"
	// SignatureSchemeEIP6492 identifies EIP-6492 counterfactual wallet verification.
	SignatureSchemeEIP6492 = "eip6492"
	// SignatureSchemeSIWS identifies Sign-In-With-Solana signatures.
	SignatureSchemeSIWS = "siws"
)

Source: extensions/signinwithx/types.go:109

const (
	ErrInvalidSIWxDomainMismatch     = "invalid_siwx_domain_mismatch"
	ErrInvalidSIWxURIMismatch        = "invalid_siwx_uri_mismatch"
	ErrInvalidSIWxIssuedAt           = "invalid_siwx_issued_at"
	ErrInvalidSIWxIssuedAtTooOld     = "invalid_siwx_issued_at_too_old"
	ErrInvalidSIWxIssuedAtInFuture   = "invalid_siwx_issued_at_in_future"
	ErrInvalidSIWxExpirationTime     = "invalid_siwx_expiration_time"
	ErrInvalidSIWxExpired            = "invalid_siwx_expired"
	ErrInvalidSIWxNotBefore          = "invalid_siwx_not_before"
	ErrInvalidSIWxNotYetValid        = "invalid_siwx_not_yet_valid"
	ErrInvalidSIWxNonce              = "invalid_siwx_nonce"
	ErrInvalidSIWxSignature          = "invalid_siwx_signature"
	ErrInvalidSIWxChainID            = "invalid_siwx_chain_id"
	ErrInvalidSIWxUnsupportedChain   = "invalid_siwx_unsupported_chain"
	ErrInvalidSIWxMalformedSignature = "invalid_siwx_malformed_signature"
	ErrInvalidSIWxVerifierError      = "invalid_siwx_verifier_error"
)

Functions

func CreateClientExtension(signer EVMSigner) *ClientExtension

Source: extensions/signinwithx/client.go:41

CreateClientExtension creates a client extension that auto-wires SIWX HTTP auth retries.

func CreateClientExtensionWithSigners(signers ...Signer) *ClientExtension

Source: extensions/signinwithx/client.go:46

CreateClientExtensionWithSigners creates a client extension with ordered SIWX signers.

func CreateClientHook(signer EVMSigner) x402http.PaymentRequiredHook

Source: extensions/signinwithx/client.go:128

CreateClientHook creates an HTTP on-payment-required hook for SIWX authentication.

func CreateClientHookWithSigners(signers ...Signer) x402http.PaymentRequiredHook

Source: extensions/signinwithx/client.go:133

CreateClientHookWithSigners creates an HTTP on-payment-required hook using ordered SIWX signers.

func CreateHeader(ctx context.Context, declaration interface{}, signer EVMSigner) (string, error)

Source: extensions/signinwithx/client.go:110

CreateHeader creates a SIGN-IN-WITH-X header value from a server declaration.

func CreateHeaderWithSigners(ctx context.Context, declaration interface{}, signers ...Signer) (string, error)

Source: extensions/signinwithx/client.go:119

CreateHeaderWithSigners creates a SIGN-IN-WITH-X header value with ordered signers.

func CreateMessage(payload Payload) (string, error)

Source: extensions/signinwithx/message.go:26

CreateMessage creates the canonical SIWX message for signing.

func CreatePayload(ctx context.Context, declaration interface{}, signer EVMSigner) (Payload, error)

Source: extensions/signinwithx/client.go:65

CreatePayload creates and signs a SIWX payload from a server declaration.

func CreatePayloadWithSigners(ctx context.Context, declaration interface{}, signers ...Signer) (Payload, error)

Source: extensions/signinwithx/client.go:70

CreatePayloadWithSigners creates and signs a SIWX payload using the first compatible signer.

func CreateResourceServerExtension(options ServerOptions) (*ServerExtension, error)

Source: extensions/signinwithx/server.go:42

CreateResourceServerExtension creates a SIWX resource server extension.

func DeclareExtension(options DeclareOptions) map[string]interface{}

Source: extensions/signinwithx/declare.go:6

DeclareExtension creates a sign-in-with-x extension declaration.

func DecodeBase58(encoded string) ([]byte, error)

Source: extensions/signinwithx/solana.go:11

DecodeBase58 decodes a Bitcoin-alphabet Base58 string.

func EncodeBase58(bytes []byte) string

Source: extensions/signinwithx/solana.go:16

EncodeBase58 encodes bytes with the Bitcoin Base58 alphabet.

func EncodeHeader(payload Payload) (string, error)

Source: extensions/signinwithx/header.go:11

EncodeHeader encodes a SIWX payload for the SIGN-IN-WITH-X header.

func ExtractEVMChainID(chainID string) (int64, error)

Source: extensions/signinwithx/message.go:13

ExtractEVMChainID returns the numeric chain ID from an eip155 CAIP-2 chain ID.

func ExtractSolanaChainReference(chainID string) (string, error)

Source: extensions/signinwithx/message.go:79

ExtractSolanaChainReference returns the chain reference from a solana CAIP-2 chain ID.

func FormatSIWEMessage(payload Payload) (string, error)

Source: extensions/signinwithx/message.go:37

FormatSIWEMessage formats an EIP-4361 SIWE message for an EVM SIWX payload.

func FormatSIWSMessage(payload Payload) (string, error)

Source: extensions/signinwithx/message.go:92

FormatSIWSMessage formats a SIWS message for a Solana SIWX payload.

func MustCreateResourceServerExtension(options ServerOptions) *ServerExtension

Source: extensions/signinwithx/server.go:60

MustCreateResourceServerExtension creates a SIWX resource server extension and panics on invalid options.

func NewEVMSIWXSigner(signer EVMSigner) Signer

Source: extensions/signinwithx/signers.go:20

NewEVMSIWXSigner adapts an EVM message signer for SIWX.

func NewInMemoryStorage() *InMemoryStorage

Source: extensions/signinwithx/storage.go:29

NewInMemoryStorage creates an empty in-memory SIWX storage backend.

func NewSolanaSIWXSigner(signer SolanaSigner) Signer

Source: extensions/signinwithx/signers.go:34

NewSolanaSIWXSigner adapts a Solana message signer for SIWX.

func NewUniversalEVMVerifier(signer evm.FacilitatorEvmSigner) EVMMessageVerifier

Source: extensions/signinwithx/verify.go:147

NewUniversalEVMVerifier creates an EVM verifier for EOA and deployed EIP-1271 signatures.

func ParseHeader(header string) (Payload, error)

Source: extensions/signinwithx/header.go:20

ParseHeader decodes a SIGN-IN-WITH-X header into a SIWX payload.

func Schema() map[string]interface{}

Source: extensions/signinwithx/schema.go:4

Schema returns the JSON Schema for validating SIWX client payloads.

func SignatureTypeForNetwork(network string) string

Source: extensions/signinwithx/declare.go:36

SignatureTypeForNetwork returns the SIWX signature type for a CAIP-2 network.

func ValidateMessage(payload Payload, expectedOrigin *url.URL, options ValidationOptions) ValidationResult

Source: extensions/signinwithx/validate.go:55

ValidateMessage validates SIWX payload fields before cryptographic verification.

func VerifyEVMSignature(message string, address string, signature string) (bool, error)

Source: extensions/signinwithx/verify.go:94

VerifyEVMSignature verifies an EIP-191 message signature against an EVM address.

func VerifySignature(payload Payload) VerifyResult

Source: extensions/signinwithx/verify.go:23

VerifySignature verifies a SIWX payload signature.

func VerifySignatureWithOptions(ctx context.Context, payload Payload, options VerifyOptions) VerifyResult

Source: extensions/signinwithx/verify.go:28

VerifySignatureWithOptions verifies a SIWX payload signature with optional chain-specific verifiers.

func VerifySolanaSignature(message string, signature []byte, publicKey []byte) bool

Source: extensions/signinwithx/solana.go:21

VerifySolanaSignature verifies an Ed25519 SIWS signature.

Types

type ClientExtension

Source: extensions/signinwithx/client.go:36

ClientExtension signs SIWX challenges declared by HTTP PaymentRequired responses.

type ClientExtension struct {
	// contains filtered or unexported fields
}

func EnrichPaymentPayload(_ context.Context, payload types.PaymentPayload, _ types.PaymentRequired) (types.PaymentPayload, error)

Source: extensions/signinwithx/client.go:54

func Key() string

Source: extensions/signinwithx/client.go:50

func PaymentRequiredHook() x402http.PaymentRequiredHook

Source: extensions/signinwithx/client.go:58

type DeclareOptions

Source: extensions/signinwithx/types.go:95

DeclareOptions configures a SIWX extension declaration.

type DeclareOptions struct {
	Statement         string
	Version           string
	Networks          []string
	ExpirationSeconds int
}
Fields
  • Statement string
  • Version string
  • Networks []string
  • ExpirationSeconds int

type EVMContractSignatureVerifier

Source: extensions/signinwithx/types.go:144

EVMContractSignatureVerifier verifies SIWE smart-wallet signatures.

It matches siwe-go's contract verifier interface. Implementations can use siwe.NewEthCallerVerifier with an ethclient.Client to support deployed EIP-1271 and counterfactual EIP-6492 signatures.

type EVMContractSignatureVerifier = siwe.ContractSignatureVerifier

type EVMMessageVerifier

Source: extensions/signinwithx/types.go:137

EVMMessageVerifier verifies an EIP-191 SIWX message for an EVM address.

Servers can provide a verifier backed by on-chain reads to support smart wallet signatures such as EIP-1271 and ERC-6492.

type EVMMessageVerifier func(ctx context.Context, address string, message string, signature string) (bool, error)

type EVMSigner

Source: extensions/signinwithx/client.go:15

EVMSigner signs EIP-191 SIWX messages.

type EVMSigner interface {
	Address() string
	SignMessage(ctx context.Context, message string) (string, error)
}
Methods
  • Address func() string
  • SignMessage func(ctx context.Context, message string) (string, error)

type Extension

Source: extensions/signinwithx/types.go:68

Extension is the full extension declaration value.

type Extension struct {
	Info            Info                   `json:"info"`
	SupportedChains []SupportedChain       `json:"supportedChains"`
	Schema          map[string]interface{} `json:"schema"`
	Options         DeclareOptions         `json:"-"`
}
Fields
  • Info Info `json:"info"`
  • SupportedChains []SupportedChain `json:"supportedChains"`
  • Schema map[string]interface{} `json:"schema"`
  • Options DeclareOptions `json:"-"`

type HookEvent

Source: extensions/signinwithx/server.go:17

HookEvent describes SIWX server lifecycle events.

type HookEvent struct {
	Type     string
	Resource string
	Address  string
	Nonce    string
	Error    string
}
Fields
  • Type string
  • Resource string
  • Address string
  • Nonce string
  • Error string

type InMemoryStorage

Source: extensions/signinwithx/storage.go:22

InMemoryStorage is a process-local SIWX storage implementation.

type InMemoryStorage struct {
	// contains filtered or unexported fields
}

func HasPaid(_ context.Context, resource string, address string) (bool, error)

Source: extensions/signinwithx/storage.go:37

HasPaid reports whether address has paid for resource.

func HasUsedNonce(_ context.Context, nonce string) (bool, error)

Source: extensions/signinwithx/storage.go:62

HasUsedNonce reports whether nonce was already accepted.

func RecordNonce(_ context.Context, nonce string) error

Source: extensions/signinwithx/storage.go:71

RecordNonce marks nonce as accepted.

func RecordPayment(_ context.Context, resource string, address string) error

Source: extensions/signinwithx/storage.go:50

RecordPayment records address as paid for resource.

type Info

Source: extensions/signinwithx/types.go:47

Info contains server-provided SIWX message metadata.

type Info struct {
	Domain         string   `json:"domain,omitempty"`
	URI            string   `json:"uri,omitempty"`
	Statement      string   `json:"statement,omitempty"`
	Version        string   `json:"version"`
	Nonce          string   `json:"nonce,omitempty"`
	IssuedAt       string   `json:"issuedAt,omitempty"`
	ExpirationTime string   `json:"expirationTime,omitempty"`
	NotBefore      string   `json:"notBefore,omitempty"`
	RequestID      string   `json:"requestId,omitempty"`
	Resources      []string `json:"resources,omitempty"`
}
Fields
  • Domain string `json:"domain,omitempty"`
  • URI string `json:"uri,omitempty"`
  • Statement string `json:"statement,omitempty"`
  • Version string `json:"version"`
  • Nonce string `json:"nonce,omitempty"`
  • IssuedAt string `json:"issuedAt,omitempty"`
  • ExpirationTime string `json:"expirationTime,omitempty"`
  • NotBefore string `json:"notBefore,omitempty"`
  • RequestID string `json:"requestId,omitempty"`
  • Resources []string `json:"resources,omitempty"`

type NonceStorage

Source: extensions/signinwithx/storage.go:16

NonceStorage is implemented by Storage backends that prevent nonce reuse.

type NonceStorage interface {
	HasUsedNonce(ctx context.Context, nonce string) (bool, error)
	RecordNonce(ctx context.Context, nonce string) error
}
Methods
  • HasUsedNonce func(ctx context.Context, nonce string) (bool, error)
  • RecordNonce func(ctx context.Context, nonce string) error

type Payload

Source: extensions/signinwithx/types.go:76

Payload is the client proof carried in the SIGN-IN-WITH-X header.

type Payload struct {
	Domain          string   `json:"domain"`
	Address         string   `json:"address"`
	Statement       string   `json:"statement,omitempty"`
	URI             string   `json:"uri"`
	Version         string   `json:"version"`
	ChainID         string   `json:"chainId"`
	Type            string   `json:"type"`
	Nonce           string   `json:"nonce"`
	IssuedAt        string   `json:"issuedAt"`
	ExpirationTime  string   `json:"expirationTime,omitempty"`
	NotBefore       string   `json:"notBefore,omitempty"`
	RequestID       string   `json:"requestId,omitempty"`
	Resources       []string `json:"resources,omitempty"`
	SignatureScheme string   `json:"signatureScheme,omitempty"`
	Signature       string   `json:"signature"`
}
Fields
  • Domain string `json:"domain"`
  • Address string `json:"address"`
  • Statement string `json:"statement,omitempty"`
  • URI string `json:"uri"`
  • Version string `json:"version"`
  • ChainID string `json:"chainId"`
  • Type string `json:"type"`
  • Nonce string `json:"nonce"`
  • IssuedAt string `json:"issuedAt"`
  • ExpirationTime string `json:"expirationTime,omitempty"`
  • NotBefore string `json:"notBefore,omitempty"`
  • RequestID string `json:"requestId,omitempty"`
  • Resources []string `json:"resources,omitempty"`
  • SignatureScheme string `json:"signatureScheme,omitempty"`
  • Signature string `json:"signature"`

type ServerExtension

Source: extensions/signinwithx/server.go:33

type ServerExtension struct {
	// contains filtered or unexported fields
}

func DynamicInfoFields() []string

Source: extensions/signinwithx/server.go:72

func EnrichDeclaration(declaration interface{}, transportContext interface{}) interface{}

Source: extensions/signinwithx/server.go:90

func Key() string

Source: extensions/signinwithx/server.go:68

func ProtectedRequestHook() x402http.ProtectedRequestHook

Source: extensions/signinwithx/server.go:166

func ResourceServerExtensionHooks() x402.ResourceServerExtensionHooks

Source: extensions/signinwithx/server.go:160

type ServerOptions

Source: extensions/signinwithx/server.go:26

ServerOptions configures the SIWX resource server extension.

type ServerOptions struct {
	Storage       Storage
	Origin        string
	VerifyOptions VerifyOptions
	OnEvent       func(HookEvent)
}
Fields
  • Storage Storage
  • Origin string
  • VerifyOptions VerifyOptions
  • OnEvent func(HookEvent)

type Signer

Source: extensions/signinwithx/client.go:27

Signer is a chain-aware SIWX signer used by multi-signer clients.

type Signer interface {
	Address() string
	SignMessage(ctx context.Context, message string) (string, error)
	SupportsChain(chain SupportedChain) bool
	DefaultSignatureScheme() string
	FormatSignature(signature string) string
}
Methods
  • Address func() string
  • SignMessage func(ctx context.Context, message string) (string, error)
  • SupportsChain func(chain SupportedChain) bool
  • DefaultSignatureScheme func() string
  • FormatSignature func(signature string) string

type SolanaSigner

Source: extensions/signinwithx/client.go:21

SolanaSigner signs Ed25519 SIWS messages and returns Base58 signatures.

type SolanaSigner interface {
	Address() string
	SignMessage(ctx context.Context, message string) (string, error)
}
Methods
  • Address func() string
  • SignMessage func(ctx context.Context, message string) (string, error)

type Storage

Source: extensions/signinwithx/storage.go:10

Storage tracks SIWX payment and optional nonce state.

type Storage interface {
	HasPaid(ctx context.Context, resource string, address string) (bool, error)
	RecordPayment(ctx context.Context, resource string, address string) error
}
Methods
  • HasPaid func(ctx context.Context, resource string, address string) (bool, error)
  • RecordPayment func(ctx context.Context, resource string, address string) error

type SupportedChain

Source: extensions/signinwithx/types.go:61

SupportedChain describes a chain accepted for SIWX authentication.

type SupportedChain struct {
	ChainID         string `json:"chainId"`
	Type            string `json:"type"`
	SignatureScheme string `json:"signatureScheme,omitempty"`
}
Fields
  • ChainID string `json:"chainId"`
  • Type string `json:"type"`
  • SignatureScheme string `json:"signatureScheme,omitempty"`

type ValidationOptions

Source: extensions/signinwithx/types.go:103

ValidationOptions configures payload field validation.

type ValidationOptions struct {
	MaxAge     time.Duration
	CheckNonce func(string) bool
}
Fields
  • MaxAge time.Duration
  • CheckNonce func(string) bool

type ValidationResult

Source: extensions/signinwithx/types.go:127

ValidationResult is returned by ValidateMessage.

type ValidationResult struct {
	IsValid        bool
	InvalidReason  string
	InvalidMessage string
}
Fields
  • IsValid bool
  • InvalidReason string
  • InvalidMessage string

type VerifyOptions

Source: extensions/signinwithx/types.go:147

VerifyOptions configures SIWX signature verification.

type VerifyOptions struct {
	EVMVerifier         EVMMessageVerifier
	EVMContractVerifier EVMContractSignatureVerifier
}
Fields
  • EVMVerifier EVMMessageVerifier
  • EVMContractVerifier EVMContractSignatureVerifier

type VerifyResult

Source: extensions/signinwithx/types.go:153

VerifyResult is returned by VerifySignature.

type VerifyResult struct {
	IsValid        bool
	InvalidReason  string
	InvalidMessage string
	Payer          string
}
Fields
  • IsValid bool
  • InvalidReason string
  • InvalidMessage string
  • Payer string