payment

package
v2026.0.153 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 27, 2026 License: MPL-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package payment owns authority-signed customer payment receipts and bounded receipt catalogs. It knows account and offering identities, exact currency, settlement time, and service period; it does not know Stripe, OGS, or any product-specific billing implementation.

Index

Constants

View Source 
const (
	// SigningDomainReceiptV1Token separates an immutable payment receipt.
	SigningDomainReceiptV1Token = "primitive-payment-receipt-2026-1"
	// SigningDomainCatalogV1Token separates an observed payment catalog.
	SigningDomainCatalogV1Token = "primitive-payment-catalog-2026-1"
	// SigningDomainQueryV1Token separates an installed device's catalog request.
	SigningDomainQueryV1Token = "primitive-payment-query-2026-1"
)
View Source 
const (
	// ReceiptPayloadJSONMaximumBytes bounds one canonical payment fact.
	ReceiptPayloadJSONMaximumBytes = 32 << 10
	// ReceiptDocumentJSONMaximumBytes bounds one signed payment receipt.
	ReceiptDocumentJSONMaximumBytes = 64 << 10
)
View Source 
const (
	QueryPayloadJSONMaximumBytes  = 32 << 10
	QueryDocumentJSONMaximumBytes = 64 << 10
)

Variables

This section is empty.

Functions

This section is empty.

Types

type CatalogDocument 

type CatalogDocument struct {
	Payload     CatalogPayload                 `json:"payload"`
	Attestation attest.Envelope[SigningDomain] `json:"attestation"`
}

CatalogDocument carries one authority-signed receipt page.

func IssueCatalog 

func IssueCatalog(issuance CatalogIssuance) (CatalogDocument, error)

IssueCatalog signs one exact payment catalog page.

func (CatalogDocument) MarshalJSON 

func (d CatalogDocument) MarshalJSON() ([]byte, error)

MarshalJSON emits one bounded canonical signed page.

func (*CatalogDocument) UnmarshalJSON 

func (d *CatalogDocument) UnmarshalJSON(data []byte) error

UnmarshalJSON strictly decodes and preserves the receiver on rejection.

func (CatalogDocument) Validate 

func (d CatalogDocument) Validate() error

Validate closes the page, envelope, and exact signing namespace.

type CatalogIssuance 

type CatalogIssuance struct {
	Signer  crypto.Signer
	Payload CatalogPayload
}

CatalogIssuance carries exact authority signing inputs for one page.

func (CatalogIssuance) Validate 

func (i CatalogIssuance) Validate() error

Validate closes the page and signer without issuing.

type CatalogPayload 

type CatalogPayload struct {
	Scope        receipt.Scope     `json:"scope"`
	Entries      []Document        `json:"entries"`
	Watermark    receipt.Watermark `json:"watermark"`
	ObservedAt   temporal.Instant  `json:"observed_at"`
	Continuation Continuation      `json:"continuation"`
	Request      QueryCommitment   `json:"query_commitment"`
}

CatalogPayload is one bounded, newest-first authority-observed receipt page.

func VerifyCatalog 

func VerifyCatalog(verification CatalogVerification) (CatalogPayload, error)

VerifyCatalog authenticates one exact payment page and binds it to the selection, cursor, limit, account, build, nonce, and revision requested.

func (CatalogPayload) AttestationDomain 

func (CatalogPayload) AttestationDomain() SigningDomain

AttestationDomain selects the payment-catalog namespace.

func (CatalogPayload) MarshalJSON 

func (p CatalogPayload) MarshalJSON() ([]byte, error)

MarshalJSON emits one bounded canonical payment page.

func (*CatalogPayload) UnmarshalJSON 

func (p *CatalogPayload) UnmarshalJSON(data []byte) error

UnmarshalJSON strictly decodes and preserves the receiver on rejection.

func (CatalogPayload) Validate 

func (p CatalogPayload) Validate() error

Validate closes page bounds, scope, monotonic watermark, ordering, and every embedded signed receipt structure.

func (CatalogPayload) WriteCanonical 

func (p CatalogPayload) WriteCanonical(destination io.Writer) error

WriteCanonical writes the exact compact signed page.

type CatalogVerification 

type CatalogVerification struct {
	Request     QueryPayload
	Document    CatalogDocument
	TrustedKeys attest.TrustedKeys
}

CatalogVerification carries one untrusted page, its exact signed query, and caller-selected authority keys.

func (CatalogVerification) Validate 

func (v CatalogVerification) Validate() error

Validate closes the complete catalog verification input.

type Continuation 

type Continuation struct {
	Cursor Cursor                        `json:"cursor"`
	State  core.CatalogContinuationState `json:"state"`
}

Continuation is a tagged union: End carries no cursor; More requires one.

func End 

func End() Continuation

End states that the authenticated catalog has no later page.

func More 

func More(cursor Cursor) (Continuation, error)

More binds another-page state to one opaque authority cursor.

func (Continuation) MarshalJSON 

func (c Continuation) MarshalJSON() ([]byte, error)

MarshalJSON emits only the member owned by the selected tagged-union arm.

func (Continuation) Validate 

func (c Continuation) Validate() error

Validate enforces the exact tagged-union arm.

type Cursor 

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

Cursor is Payment's nominal opaque closure of one catalog position.

func NewCursor 

func NewCursor(value core.SHA256Digest) (Cursor, error)

NewCursor applies Payment's catalog domain to one opaque digest.

func (Cursor) MarshalJSON 

func (c Cursor) MarshalJSON() ([]byte, error)

MarshalJSON emits the opaque digest.

func (*Cursor) UnmarshalJSON 

func (c *Cursor) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts one digest and preserves the receiver on rejection.

func (Cursor) Validate 

func (c Cursor) Validate() error

Validate rejects an unset cursor.

type Document 

type Document struct {
	Payload     Payload                        `json:"payload"`
	Attestation attest.Envelope[SigningDomain] `json:"attestation"`
}

Document carries one authority-signed immutable payment receipt.

func Issue 

func Issue(issuance Issuance) (Document, error)

Issue signs one exact payment receipt.

func (Document) MarshalJSON 

func (d Document) MarshalJSON() ([]byte, error)

MarshalJSON emits one bounded canonical signed receipt.

func (*Document) UnmarshalJSON 

func (d *Document) UnmarshalJSON(data []byte) error

UnmarshalJSON strictly decodes and preserves the receiver on rejection.

func (Document) Validate 

func (d Document) Validate() error

Validate closes the payload, signature envelope, and exact domain binding.

type Expectation 

type Expectation struct {
	Scope    receipt.Scope
	Identity PaymentID
}

Expectation prevents a valid receipt for another payment or tenant scope from satisfying a caller's request.

func (Expectation) Validate 

func (e Expectation) Validate() error

Validate closes the exact expected identity and scope.

type Issuance 

type Issuance struct {
	Signer  crypto.Signer
	Payload Payload
}

Issuance carries exact authority signing inputs.

func (Issuance) Validate 

func (i Issuance) Validate() error

Validate closes the payload and signing capability without issuing.

type Payload 

type Payload struct {
	Scope    receipt.Scope    `json:"scope"`
	Service  ServicePeriod    `json:"service_period"`
	Amount   currency.Amount  `json:"amount"`
	PaidAt   temporal.Instant `json:"paid_at"`
	Identity PaymentID        `json:"payment_id"`
}

Payload is the immutable authority statement for one settled payment.

func (Payload) AttestationDomain 

func (Payload) AttestationDomain() SigningDomain

AttestationDomain selects the immutable payment-receipt namespace.

func (Payload) MarshalJSON 

func (p Payload) MarshalJSON() ([]byte, error)

MarshalJSON emits one bounded canonical payload.

func (*Payload) UnmarshalJSON 

func (p *Payload) UnmarshalJSON(data []byte) error

UnmarshalJSON strictly decodes and preserves the receiver on rejection.

func (Payload) Validate 

func (p Payload) Validate() error

Validate closes identity, tenant scope, exact positive amount, settlement time, and service period.

func (Payload) WriteCanonical 

func (p Payload) WriteCanonical(destination io.Writer) error

WriteCanonical writes the exact compact signed payload.

type PaymentID 

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

PaymentID is the authority-issued UUIDv7 for one settled customer payment.

func NewPaymentID 

func NewPaymentID(value id.UUIDv7) (PaymentID, error)

NewPaymentID applies Payment's nominal identity boundary to a UUIDv7.

func ParsePaymentID 

func ParsePaymentID(value string) (PaymentID, error)

ParsePaymentID parses one canonical UUIDv7 payment identity.

func (PaymentID) MarshalJSON 

func (i PaymentID) MarshalJSON() ([]byte, error)

MarshalJSON emits the canonical UUIDv7 string.

func (PaymentID) String 

func (i PaymentID) String() string

String returns the canonical UUIDv7 or empty text for an invalid identity.

func (*PaymentID) UnmarshalJSON 

func (i *PaymentID) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts one canonical UUIDv7 and preserves the receiver on rejection.

func (PaymentID) Validate 

func (i PaymentID) Validate() error

Validate rejects the unset identity.

type Position 

type Position struct {
	Cursor Cursor                   `json:"cursor"`
	Kind   core.CatalogPositionKind `json:"kind"`
}

Position is the explicit first-page or after-cursor request arm.

func After 

func After(cursor Cursor) (Position, error)

After requests the page after one authority-issued cursor.

func Start 

func Start() Position

Start requests the first payment catalog page.

func (Position) MarshalJSON 

func (p Position) MarshalJSON() ([]byte, error)

MarshalJSON emits only the member owned by the selected tagged-union arm.

func (Position) Validate 

func (p Position) Validate() error

Validate enforces the exact tagged-union arm.

type Query 

type Query struct {
	Scope     receipt.Scope         `json:"scope"`
	Selection Selection             `json:"selection"`
	Position  Position              `json:"position"`
	Limit     core.CatalogPageLimit `json:"limit"`
}

Query is the complete typed input behind `receipt -all` or `receipt <id>`.

func NewQuery 

func NewQuery(request QueryRequest) (Query, error)

NewQuery constructs one completely typed payment catalog query.

func (Query) Validate 

func (q Query) Validate() error

Validate closes scope, selection, position, and the shared page bound.

type QueryCommitment added in v2026.0.96 

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

QueryCommitment is the non-secret domain-separated closure of one exact device-signed payment query payload.

func CommitQuery added in v2026.0.96 

func CommitQuery(payload QueryPayload) (QueryCommitment, error)

CommitQuery closes the exact selection, position, scope, build, nonce, and revision without retaining the encoded query.

func (QueryCommitment) MarshalJSON added in v2026.0.96 

func (c QueryCommitment) MarshalJSON() ([]byte, error)

func (*QueryCommitment) UnmarshalJSON added in v2026.0.96 

func (c *QueryCommitment) UnmarshalJSON(data []byte) error

func (QueryCommitment) Validate added in v2026.0.96 

func (c QueryCommitment) Validate() error

type QueryDocument added in v2026.0.56 

type QueryDocument struct {
	Payload     QueryPayload                   `json:"payload"`
	Attestation attest.Envelope[SigningDomain] `json:"attestation"`
}

QueryDocument carries one device signature over one exact payment query.

func IssueQuery added in v2026.0.56 

func IssueQuery(issuance QueryIssuance) (QueryDocument, error)

func (QueryDocument) MarshalJSON added in v2026.0.56 

func (d QueryDocument) MarshalJSON() ([]byte, error)

func (*QueryDocument) UnmarshalJSON added in v2026.0.56 

func (d *QueryDocument) UnmarshalJSON(data []byte) error

func (QueryDocument) Validate added in v2026.0.56 

func (d QueryDocument) Validate() error

type QueryIssuance added in v2026.0.56 

type QueryIssuance struct {
	Signer  crypto.Signer
	Payload QueryPayload
}

func (QueryIssuance) Validate added in v2026.0.56 

func (i QueryIssuance) Validate() error

type QueryPayload added in v2026.0.56 

type QueryPayload struct {
	Build    core.BuildIdentity       `json:"build"`
	Query    Query                    `json:"query"`
	Nonce    controlwire.RequestNonce `json:"request_nonce"`
	Revision controlwire.Revision     `json:"revision"`
}

QueryPayload is one exact payment catalog query signed by an installed device.

func (QueryPayload) AttestationDomain added in v2026.0.56 

func (QueryPayload) AttestationDomain() SigningDomain

func (QueryPayload) MarshalJSON added in v2026.0.56 

func (p QueryPayload) MarshalJSON() ([]byte, error)

func (*QueryPayload) UnmarshalJSON added in v2026.0.56 

func (p *QueryPayload) UnmarshalJSON(data []byte) error

func (QueryPayload) Validate added in v2026.0.56 

func (p QueryPayload) Validate() error

func (QueryPayload) WriteCanonical added in v2026.0.56 

func (p QueryPayload) WriteCanonical(destination io.Writer) error

type QueryRequest 

type QueryRequest struct {
	Scope     receipt.Scope
	Selection Selection
	Position  Position
	PageSize  uint16
}

QueryRequest is the constructor boundary for one customer receipt query. PageSize is immediately closed into Core's nominal page limit.

func (QueryRequest) Validate 

func (r QueryRequest) Validate() error

Validate closes every constructor input without constructing the query.

type QueryVerification added in v2026.0.56 

type QueryVerification struct {
	Document    QueryDocument
	TrustedKeys attest.TrustedKeys
}

func (QueryVerification) Validate added in v2026.0.56 

func (v QueryVerification) Validate() error

type Selection 

type Selection struct {
	Payment PaymentID                 `json:"payment_id"`
	Kind    core.CatalogSelectionKind `json:"kind"`
}

Selection is the exact all-or-one payment receipt selection.

func All 

func All() Selection

All selects every payment in one authenticated scope.

func Specific 

func Specific(identity PaymentID) (Selection, error)

Specific selects one exact payment identity.

func (Selection) MarshalJSON 

func (s Selection) MarshalJSON() ([]byte, error)

MarshalJSON emits only the member owned by the selected tagged-union arm.

func (Selection) Validate 

func (s Selection) Validate() error

Validate enforces the exact tagged-union arm.

type ServicePeriod 

type ServicePeriod struct {
	Start temporal.Instant `json:"start"`
	End   temporal.Instant `json:"end"`
}

ServicePeriod is the exact service interval paid for by one receipt.

func (ServicePeriod) Bounds 

func (p ServicePeriod) Bounds() (temporal.IntervalBounds, error)

Bounds returns the validated Temporal-owned interval projection.

func (ServicePeriod) Validate 

func (p ServicePeriod) Validate() error

Validate requires two valid, strictly increasing bounds.

type SigningDomain 

type SigningDomain uint8

SigningDomain closes the two payment authority statement namespaces. 

const (
	// SigningDomainUnknown is the invalid zero signing domain.
	SigningDomainUnknown SigningDomain = iota
	// SigningDomainReceiptV1 authenticates an immutable payment receipt.
	SigningDomainReceiptV1
	// SigningDomainCatalogV1 authenticates one bounded payment catalog page.
	SigningDomainCatalogV1
	// SigningDomainQueryV1 authenticates one installed device's catalog request.
	SigningDomainQueryV1
)

func (SigningDomain) IsValid 

func (d SigningDomain) IsValid() bool

IsValid reports whether d names one published payment signing namespace.

func (SigningDomain) MarshalJSON 

func (d SigningDomain) MarshalJSON() ([]byte, error)

func (SigningDomain) MarshalText 

func (d SigningDomain) MarshalText() ([]byte, error)

MarshalText emits the canonical signing token.

func (SigningDomain) ParseCanonicalText 

func (SigningDomain) ParseCanonicalText(text []byte) (SigningDomain, error)

ParseCanonicalText accepts one exact payment signing token.

func (SigningDomain) String 

func (d SigningDomain) String() string

String returns the canonical token or empty text for an invalid domain.

func (*SigningDomain) UnmarshalJSON 

func (d *SigningDomain) UnmarshalJSON(data []byte) error

func (SigningDomain) Validate 

func (d SigningDomain) Validate() error

Validate rejects signing domains outside the closed domain.

type Verification 

type Verification struct {
	Expected    Expectation
	Document    Document
	TrustedKeys attest.TrustedKeys
}

Verification carries one untrusted receipt and caller-selected authority keys.

func (Verification) Validate 

func (v Verification) Validate() error

Validate closes the complete verification input.

type Verified 

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

Verified is the sealed authentication result.

func Verify 

func Verify(verification Verification) (Verified, error)

Verify authenticates and binds one exact payment receipt.

func (Verified) Document 

func (v Verified) Document() (Document, error)

Document returns the authenticated payment receipt.

func (Verified) Validate 

func (v Verified) Validate() error

Validate revalidates the sealed authentication proof.

type VerifiedQuery added in v2026.0.56 

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

func VerifyQuery added in v2026.0.56 

func VerifyQuery(verification QueryVerification) (VerifiedQuery, error)

func (VerifiedQuery) Payload added in v2026.0.56 

func (v VerifiedQuery) Payload() (QueryPayload, error)

func (VerifiedQuery) Validate added in v2026.0.56 

func (v VerifiedQuery) Validate() error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.