mpp

func AdvertisedCredentialHeader ¶ added in v0.4.0

func AdvertisedCredentialHeader(header string) string

AdvertisedCredentialHeader returns a challenge header parameter value, or empty for the implicit Authorization default.

func B64Decode ¶

func B64Decode(s string) (map[string]any, error)

B64Decode decodes a base64url (no padding) string into a map.

Numbers decode as json.Number rather than float64. The challenge ID is an HMAC over the re-encoded request, so a decode that cannot reproduce the bytes it was given cannot reproduce the ID either: float64 carries 53 bits of mantissa, and any JSON integer above 2^53 comes back rounded, making a challenge the server itself issued fail to verify.

func ChallengeBoundJSONEqual ¶ added in v0.4.0

func ChallengeBoundJSONEqual(left, right any) bool

ChallengeBoundJSONEqual compares values using the RFC 8785 representation used to bind challenge requests and opaque values into their HMAC IDs.

func CheckExpires ¶ added in v0.5.1

func CheckExpires(expires string, now time.Time) error

CheckExpires checks a challenge's expires parameter at now, as mppx's Expires.assert does. It returns an invalid-challenge PaymentError when expires is empty or malformed, and ErrPaymentExpired when now is at or after it: a challenge is no longer valid at its exact expiry instant.

func ComputeBodyDigest ¶ added in v0.5.1

func ComputeBodyDigest(body []byte) string

ComputeBodyDigest returns the SHA-256 digest of body in the form "sha-256=<base64>", the value of a challenge's digest parameter. Pass the raw request bytes so the digest binds exactly what the client sent.

func ConstantTimeEqual ¶

func ConstantTimeEqual(a, b string) bool

ConstantTimeEqual returns true if a and b are equal, using constant-time comparison to avoid timing side-channels.

func ExpiresIn ¶ added in v0.5.1

func ExpiresIn(d time.Duration) string

ExpiresIn returns the RFC 3339 timestamp d from now, in UTC with millisecond precision and a Z suffix, as mppx's Expires helpers emit. Use it for a challenge's expires parameter:

mpp.WithExpires(mpp.ExpiresIn(5 * time.Minute))

package main

import (
	"fmt"
	"time"

	"github.com/tempoxyz/mpp-go/pkg/mpp"
)

func main() {
	expires := mpp.ExpiresIn(5 * time.Minute)

	// Issue a challenge with mpp.WithExpires(expires); verify it later.
	fmt.Println(mpp.CheckExpires(expires, time.Now()))
	fmt.Println(mpp.CheckExpires(expires, time.Now().Add(10*time.Minute)) != nil)
}

Output:
<nil>
true

func ExtractAuthorizationScheme ¶

func ExtractAuthorizationScheme(header, scheme string) string

ExtractAuthorizationScheme returns the first authorization value that matches the requested scheme from a possibly merged Authorization header.

func ExtractAuthorizationSchemeStrict ¶ added in v0.2.0

func ExtractAuthorizationSchemeStrict(header, scheme string) (string, error)

ExtractAuthorizationSchemeStrict returns a single authorization value that matches scheme, or an error if the header includes multiple matching values.

func FindPaymentAuthorization ¶

func FindPaymentAuthorization(header string) string

FindPaymentAuthorization returns the Payment credential from an Authorization header. It tolerates comma-separated schemes and ignores non-Payment values.

func FindPaymentAuthorizationStrict ¶ added in v0.2.0

func FindPaymentAuthorizationStrict(header string) (string, error)

FindPaymentAuthorizationStrict returns the Payment credential from an Authorization header, or an error if more than one Payment credential exists.

func FormatChallenge ¶ added in v0.5.1

func FormatChallenge(c *Challenge) (string, error)

FormatChallenge formats c as a WWW-Authenticate header value, the inverse of ParseChallenge:

Payment id="...", realm="...", method="...", intent="...", request="..."

It writes c.Realm, the realm the challenge ID binds. It rejects a nil challenge, values that cannot be safely represented in quoted auth-params, an invalid advertised credential header, empty required auth-params (id, realm, method, intent, request), which would otherwise be omitted and yield a challenge ParseChallenge rejects, a method that is not a valid method name (lowercase ASCII letters), a RequestB64 that is not base64url-encoded JSON, and a header over the size limit.

package main

import (
	"fmt"

	"github.com/tempoxyz/mpp-go/pkg/mpp"
)

func main() {
	challenge, err := mpp.NewChallengeWithError(
		"server-secret", "api.example.com", "tempo", mpp.IntentCharge,
		map[string]any{"amount": "1000000", "currency": "0x20c0000000000000000000006a37DA5C996874BE"},
	)
	if err != nil {
		panic(err)
	}
	header, err := mpp.FormatChallenge(challenge)
	if err != nil {
		panic(err)
	}
	fmt.Println(header)
}

Output:
Payment id="qEJM3P0jKiqImybGyCeUMeHy2beC0JTnqS_TTde14lY", realm="api.example.com", method="tempo", intent="charge", request="eyJhbW91bnQiOiIxMDAwMDAwIiwiY3VycmVuY3kiOiIweDIwYzAwMDAwMDAwMDAwMDAwMDAwMDAwMDZhMzdEQTVDOTk2ODc0QkUifQ"

func FormatCredential ¶ added in v0.5.1

func FormatCredential(c *Credential) (string, error)

FormatCredential formats c as an Authorization (or Payment-Authorization) header value, the inverse of ParseCredential:

Payment <base64url-json>

It returns an error for a nil credential, for a credential ParseCredential would reject because its challenge echo lacks id, method, intent or request, its method is not a valid method name, its advertised credential header is not a valid header name or its payload is nil (payload must be a JSON object), for values JSON cannot encode, and for a header over the size limit.

func FormatReceiptWithError ¶ added in v0.5.1

func FormatReceiptWithError(r *Receipt) (string, error)

FormatReceiptWithError formats r as a Payment-Receipt header value, the inverse of ParseReceipt:

<base64url-json>

It returns an error for a nil receipt, for a receipt ParseReceipt would reject because its status is not "success", its reference or method is missing, its method is not a valid method name or the encoded header exceeds the size limit, and for Extensions values JSON cannot encode.

func GenerateChallengeIDWithError ¶ added in v0.4.0

func GenerateChallengeIDWithError(opts GenerateChallengeIDInput) (string, error)

GenerateChallengeIDWithError produces an HMAC-SHA256 challenge ID from the given inputs and rejects ambiguous fields, invalid advertised credential headers and request values that JCS cannot represent exactly. The HMAC is computed over pipe-delimited fields:

realm|method|intent|request_b64|expires|digest|opaque_b64

Challenges that advertise a credential header insert it immediately before the final opaque slot. Authorization is the implicit default and is never included, preserving the legacy binding. The result is base64url-encoded without padding.

func JSONEqual ¶

func JSONEqual(left, right any) bool

JSONEqual compares two JSON-like values using Go's stable JSON encoding.

func MCPErrorCode ¶ added in v0.5.0

func MCPErrorCode(err error) int

MCPErrorCode maps a payment error to its MCP JSON-RPC error code. A nil error or a payment-required error maps to MCPPaymentRequiredCode, malformed credentials and invalid payloads to MCPInvalidParamsCode, internal payment errors and non-payment errors to MCPInternalErrorCode, and every other payment error to MCPPaymentVerificationFailedCode.

func ParseAmount ¶ added in v0.5.1

func ParseAmount(value string, decimals int) (*big.Int, error)

ParseAmount converts a human-readable decimal string to base units. For example, ParseAmount("1.5", 6) returns 1500000. The result is unbounded, so 18-decimal token amounts do not overflow. It returns an error if value is empty, negative or not a plain decimal (digits with an optional single "."), if it would produce fractional base units, or if decimals is negative.

func ParseExpires ¶ added in v0.5.1

func ParseExpires(s string) (time.Time, error)

ParseExpires parses an expires timestamp in the RFC 3339 format challenges use, with or without fractional seconds.

func SplitAuthenticate ¶

func SplitAuthenticate(header string) []string

SplitAuthenticate splits a potentially merged authentication header value into individual scheme values while preserving commas inside quoted auth-param values.

func VerifyBodyDigest ¶ added in v0.5.1

func VerifyBodyDigest(digest string, body []byte) bool

VerifyBodyDigest reports whether digest is the ComputeBodyDigest of body, using constant-time comparison.