extensions/signinwithx
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)
func Key() string
func PaymentRequiredHook() x402http.PaymentRequiredHook
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 stringVersion stringNetworks []stringExpirationSeconds 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.ContractSignatureVerifiertype 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() stringSignMessage 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 stringResource stringAddress stringNonce stringError 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
func EnrichDeclaration(declaration interface{}, transportContext interface{}) interface{}
func Key() string
func ProtectedRequestHook() x402http.ProtectedRequestHook
func ResourceServerExtensionHooks() x402.ResourceServerExtensionHooks
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 StorageOrigin stringVerifyOptions VerifyOptionsOnEvent 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() stringSignMessage func(ctx context.Context, message string) (string, error)SupportsChain func(chain SupportedChain) boolDefaultSignatureScheme func() stringFormatSignature 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() stringSignMessage 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.DurationCheckNonce 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 boolInvalidReason stringInvalidMessage string
type VerifyOptions
Source: extensions/signinwithx/types.go:147
VerifyOptions configures SIWX signature verification.
type VerifyOptions struct {
EVMVerifier EVMMessageVerifier
EVMContractVerifier EVMContractSignatureVerifier
}Fields
EVMVerifier EVMMessageVerifierEVMContractVerifier 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 boolInvalidReason stringInvalidMessage stringPayer string
