controlplane

package
v2026.0.146 Latest Latest
Warning

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

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

Documentation

Overview

Package controlplane owns the signed documents a product control plane and its installed clients exchange.

Both ends of the exchange run this same package, so there is no published contract for one side to mirror and no pair of copies that can drift. An authority issues a document and an installation verifies it against the same types, the same bounds, and the same canonical bytes.

The package owns the documents and the rules that make one document belong to one exact request: the response header and its binding to the request that produced it, the registration request an installation sends, the signed registration response it receives, the check-in an installation sends afterwards and the signed decision it receives, the commercial status those responses carry, and the usage watermark that orders one installation's accepted windows.

There is one shape of each document, and the product is a field on it rather than a type, a function, or a file. An authority cannot tell which tool is asking until it reads that field, and it never learns what a reported work-unit class means: it validates the ordinals, the window, and the arithmetic, and meaning stays with the product that owns it.

It does not own business decisions. Which installations are entitled, what a policy revision permits, how an account is billed, which provider instant is authoritative, and which key signs are the authority's business. It does own the pure mechanism that closes those caller-supplied facts: one-use registration verification, exact replay comparison, authenticated usage advancement, and construction of the response that those comparisons permit. Those operations perform no persistence and interpret no product policy. Controlwire owns the scalars underneath these documents, Lease owns the timeline a grant creates, Attest owns the envelope, and this package composes them.

Nothing here reaches the network, the clock, or the disk.

Index

Constants

View Source 
const (
	// CheckInPayloadJSONMaximumBytes bounds the device-signed body.
	CheckInPayloadJSONMaximumBytes = 64 << 10
	// CheckInRequestJSONMaximumBytes bounds a complete check-in request.
	CheckInRequestJSONMaximumBytes = 96 << 10
)
View Source 
const (
	// CheckInResponsePayloadJSONMaximumBytes bounds an accepted response payload.
	CheckInResponsePayloadJSONMaximumBytes = 48 << 10
	// CheckInResponseDocumentJSONMaximumBytes bounds a complete signed response.
	CheckInResponseDocumentJSONMaximumBytes = 64 << 10

	// UsageDispositionAcceptedToken names a window committed for the first time.
	UsageDispositionAcceptedToken = "accepted"
	// UsageDispositionReplayToken names a window already committed.
	UsageDispositionReplayToken = "replay"
	// UsageDispositionConflictToken names a window refused against the current
	// watermark.
	UsageDispositionConflictToken = "conflict"
)
View Source 
const (
	ProductStatusActiveToken          = "active"
	ProductStatusPaymentRetryToken    = "payment_retry"
	ProductStatusReadOnlyToken        = "read_only"
	ProductStatusStoppedToken         = "stopped"
	ProductStatusUpgradeRequiredToken = "upgrade_required"
	ProductStatusRevokedToken         = "revoked"
)

These are the exact status tokens an authority emits. They are the commercial state of one installation, so this package does not invent, abbreviate, or reorder them.

View Source 
const (
	// RegistrationRequestJSONMaximumBytes bounds an accepted request.
	RegistrationRequestJSONMaximumBytes = 16 << 10
	// InstallationCertificateBodyJSONMaximumBytes bounds a certificate body.
	InstallationCertificateBodyJSONMaximumBytes = 8 << 10
	// InstallationCertificateDocumentJSONMaximumBytes bounds a signed certificate.
	InstallationCertificateDocumentJSONMaximumBytes = 16 << 10
	// RegistrationPayloadJSONMaximumBytes bounds a response payload.
	RegistrationPayloadJSONMaximumBytes = 48 << 10
	// RegistrationDocumentJSONMaximumBytes bounds a complete signed response.
	RegistrationDocumentJSONMaximumBytes = 64 << 10
)
View Source 
const (
	SigningDomainInstallationCertificateV1Token = "ogs-control-installation-certificate-2026-1"
	SigningDomainRegistrationV1Token            = "ogs-control-registration-2026-1"
	SigningDomainCheckInV1Token                 = "ogs-control-check-in-2026-1"
	SigningDomainCheckInResponseV1Token         = "ogs-control-check-in-response-2026-1"
	SigningDomainResponseV1Token                = "ogs-control-response-2026-1"
)

These are the exact canonical domain texts. A signature is only meaningful inside one of them, so they are spelled once here and never rebuilt from parts. Two documents that shared a domain could have one's signature presented as the other's. #nosec G101 -- these are public namespace labels, not credentials. A domain text is emitted verbatim in every signed document and both ends must spell it identically for a signature to verify, so it is the opposite of a secret: nothing is authorized by knowing one.

View Source 
const (
	// UsageWatermarkJSONMaximumBytes bounds an accepted watermark document.
	UsageWatermarkJSONMaximumBytes = 8 << 10
	// UsageWatermarkInitialGeneration is the generation of a subject that has
	// no accepted usage window yet.
	UsageWatermarkInitialGeneration = uint64(1)
)
View Source 
const (
	// UsageWindowJSONMaximumBytes bounds one reported usage window.
	UsageWindowJSONMaximumBytes = 32 << 10
	// WorkUnitClassMaximum is the highest work-unit class ordinal a product may
	// report, and therefore also the longest legal unit list: the classes are
	// closed and the list is strictly ascending, so a longer one repeats a class.
	WorkUnitClassMaximum = 32
	// OutcomeClassMaximum is the same ceiling for result classes.
	OutcomeClassMaximum = 32
)
View Source 
const (
	// ResponseCommitmentJSONMaximumBytes bounds the canonical signed facts.
	ResponseCommitmentJSONMaximumBytes = 4 << 10
)
View Source 
const ResponseHeaderJSONMaximumBytes = 2 << 10

ResponseHeaderJSONMaximumBytes bounds an accepted response header.

Variables

This section is empty.

Functions

func NewResponseBindingError 

func NewResponseBindingError(field ResponseHeaderField) error

NewResponseBindingError reports that one exact bound fact disagreed.

A field outside the closed domain is itself a contract violation and returns the header identity instead, so a caller can never receive a binding failure that names nothing.

Types

type CheckInCommitRequest added in v2026.0.99 

type CheckInCommitRequest struct {
	Current        UsageWatermark
	CheckIn        VerifiedCheckIn
	RequiredPolicy controlwire.PolicyCursor
}

CheckInCommitRequest is the exact input to an authority's usage transaction. Current is the watermark read inside that transaction. RequiredPolicy is the authority's selected policy cursor; Primitive compares it but never interprets what the policy means.

func (CheckInCommitRequest) Validate added in v2026.0.99 

func (r CheckInCommitRequest) Validate() error

Validate closes all inputs before the authority uses them in its own transaction.

type CheckInPayload added in v2026.0.31 

type CheckInPayload struct {
	Build             core.BuildIdentity       `json:"build"`
	Window            UsageWindow              `json:"window"`
	PreviousWatermark UsageWatermark           `json:"previous_watermark"`
	AppliedPolicy     controlwire.PolicyCursor `json:"applied_policy"`
	LeaseGeneration   lease.Generation         `json:"lease_generation"`
	RequestNonce      controlwire.RequestNonce `json:"request_nonce"`
	Installation      lease.DeviceID           `json:"installation"`
	Revision          controlwire.Revision     `json:"revision"`
}

CheckInPayload is the exact device-signed check-in body.

One shape, every product. Which product is asking is a field on the build identity the payload already carries, so an authority reads it the way a border agent reads a nationality: after admitting the document, not before, and without a second reader for the next product.

func (CheckInPayload) AttestationDomain added in v2026.0.31 

func (CheckInPayload) AttestationDomain() SigningDomain

AttestationDomain names the namespace a device signs this payload under.

func (CheckInPayload) MarshalJSON added in v2026.0.31 

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

MarshalJSON emits one bounded canonical payload.

func (*CheckInPayload) UnmarshalJSON added in v2026.0.31 

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

UnmarshalJSON strictly decodes without mutating the receiver on rejection.

func (CheckInPayload) Validate added in v2026.0.31 

func (p CheckInPayload) Validate() error

Validate closes every signed fact and proves the payload describes this installation and the generation it claims to continue.

The offering is not compared against a constant. The binding re-derives the product from the offering the build declares and requires the watermark's subject to name that same product, which refuses a mismatched document without this package having to know which products exist.

func (CheckInPayload) WriteCanonical added in v2026.0.31 

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

WriteCanonical writes one validated compact payload.

type CheckInRequest added in v2026.0.31 

type CheckInRequest struct {
	Payload     CheckInPayload                  `json:"payload"`
	Certificate InstallationCertificateDocument `json:"certificate"`
	Attestation attest.Envelope[SigningDomain]  `json:"attestation"`
}

CheckInRequest is the complete body one installation sends: what it did, the credential proving it may, and its signature over both.

func IssueCheckIn added in v2026.0.31 

func IssueCheckIn(
	payload CheckInPayload,
	key ed25519.PrivateKey,
	certificate InstallationCertificateDocument,
) (CheckInRequest, error)

IssueCheckIn signs one validated payload with the device key and attaches the credential the authority issued for that device.

func (CheckInRequest) ControlNonce added in v2026.0.96 

func (r CheckInRequest) ControlNonce() controlwire.RequestNonce

ControlNonce projects the request identity already carried in the signed payload.

func (CheckInRequest) ControlRequestBodyLimit added in v2026.0.96 

func (CheckInRequest) ControlRequestBodyLimit() (core.ByteCount, error)

func (CheckInRequest) ControlRevision added in v2026.0.96 

func (r CheckInRequest) ControlRevision() controlwire.Revision

ControlRevision projects the exact signed revision carried by this request.

func (CheckInRequest) ControlRoute added in v2026.0.96 

func (r CheckInRequest) ControlRoute() (controlwire.RouteContract, error)

ControlRoute projects the only route this document may address.

func (CheckInRequest) MarshalJSON added in v2026.0.31 

func (r CheckInRequest) MarshalJSON() ([]byte, error)

MarshalJSON emits one bounded canonical request.

func (*CheckInRequest) UnmarshalJSON added in v2026.0.31 

func (r *CheckInRequest) UnmarshalJSON(data []byte) error

UnmarshalJSON strictly decodes without mutating the receiver on rejection.

func (CheckInRequest) Validate added in v2026.0.31 

func (r CheckInRequest) Validate() error

Validate closes the request and binds its payload to the credential it presents.

type CheckInResponseDocument 

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

CheckInResponseDocument is the response payload with its authority signature.

func IssueCheckInResponse 

func IssueCheckInResponse(payload CheckInResponsePayload, key ed25519.PrivateKey) (CheckInResponseDocument, error)

IssueCheckInResponse signs one validated response payload. It is the authority half of the exchange and is exercised by every client test, so the bytes a client verifies are produced by the same code a server runs.

func IssueCommittedCheckInResponse added in v2026.0.99 

func IssueCommittedCheckInResponse(
	preparation CheckInResponsePreparation,
	key ed25519.PrivateKey,
) (CheckInResponseDocument, error)

IssueCommittedCheckInResponse signs the response derived from one verified authority commit. It is the direct server-side counterpart to the installed client's VerifyCheckInResponse.

func (*CheckInResponseDocument) ControlResponseDocument added in v2026.0.96 

func (*CheckInResponseDocument) ControlResponseDocument()

func (CheckInResponseDocument) ControlResponseProjection added in v2026.0.96 

func (CheckInResponseDocument) ControlResponseProjection()

func (CheckInResponseDocument) MarshalJSON 

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

MarshalJSON emits one bounded canonical signed response.

func (*CheckInResponseDocument) UnmarshalJSON 

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

UnmarshalJSON strictly decodes without mutating the receiver on rejection.

func (CheckInResponseDocument) Validate 

func (d CheckInResponseDocument) Validate() error

Validate closes the signed response and binds its envelope to this payload's own domain.

func (CheckInResponseDocument) ValidateJSONProjection added in v2026.0.96 

func (d CheckInResponseDocument) ValidateJSONProjection(
	encoded []byte,
	limits core.StrictJSONLimits,
) error

type CheckInResponsePayload 

type CheckInResponsePayload struct {
	Header      ResponseHeader   `json:"header"`
	Watermark   UsageWatermark   `json:"watermark"`
	Lease       lease.Document   `json:"lease"`
	Disposition UsageDisposition `json:"disposition"`
}

CheckInResponsePayload is the complete signed authority result for one check-in.

func PrepareCheckInResponse added in v2026.0.99 

func PrepareCheckInResponse(
	preparation CheckInResponsePreparation,
) (CheckInResponsePayload, error)

PrepareCheckInResponse derives the only disposition and watermark the authenticated usage transaction permits, then closes the complete payload.

func (CheckInResponsePayload) AttestationDomain 

func (CheckInResponsePayload) AttestationDomain() SigningDomain

AttestationDomain names the namespace an authority signs this payload under.

func (CheckInResponsePayload) MarshalJSON 

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

MarshalJSON emits one bounded canonical payload.

func (*CheckInResponsePayload) UnmarshalJSON 

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

UnmarshalJSON strictly decodes without mutating the receiver on rejection.

func (CheckInResponsePayload) Validate 

func (p CheckInResponsePayload) Validate() error

Validate closes the payload and proves its signed facts agree with each other.

The lease decision and the header are signed together, so a document whose halves disagree is either an authority defect or a forgery assembled from two real responses. Either way it is refused rather than acted on in whichever half the reader happens to consult.

func (CheckInResponsePayload) WriteCanonical 

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

WriteCanonical writes one validated compact response payload.

type CheckInResponsePreparation added in v2026.0.99 

type CheckInResponsePreparation struct {
	Header ResponseHeader
	Lease  lease.Document
	Commit VerifiedCheckInCommit
}

CheckInResponsePreparation binds authority-owned response facts to one verified usage commit. Disposition and watermark are derived from Commit and cannot be repeated or substituted by the caller.

func (CheckInResponsePreparation) Validate added in v2026.0.99 

func (p CheckInResponsePreparation) Validate() error

Validate closes the authority response against the exact authenticated request and commit result it answers.

type CheckInResponseVerification 

type CheckInResponseVerification struct {
	Expected    ResponseExpectation
	Document    CheckInResponseDocument
	TrustedKeys attest.TrustedKeys
}

CheckInResponseVerification is the complete input one caller supplies to authenticate a response against the request that produced it.

func (CheckInResponseVerification) Validate 

func (v CheckInResponseVerification) Validate() error

Validate closes the complete verification input.

type CheckInVerification added in v2026.0.31 

type CheckInVerification struct {
	Request     CheckInRequest
	TrustedKeys attest.TrustedKeys
}

CheckInVerification carries the authority's trusted keys into exact credential and device-request authentication.

func (CheckInVerification) Validate added in v2026.0.31 

func (v CheckInVerification) Validate() error

Validate closes the complete verification input.

type InstallationCertificateBody 

type InstallationCertificateBody struct {
	Subject   lease.Subject           `json:"subject"`
	Build     core.BuildIdentity      `json:"build"`
	IssuedAt  temporal.Instant        `json:"issued_at"`
	DeviceKey core.Ed25519PublicKey   `json:"device_public_key"`
	Account   receipt.AccountIdentity `json:"account"`
	Revision  controlwire.Revision    `json:"revision"`
}

InstallationCertificateBody is the signed statement that one device key belongs to one entitlement under one account.

func (InstallationCertificateBody) AttestationDomain 

func (InstallationCertificateBody) AttestationDomain() SigningDomain

AttestationDomain returns the certificate's exact signing namespace.

func (InstallationCertificateBody) MarshalJSON 

func (b InstallationCertificateBody) MarshalJSON() ([]byte, error)

MarshalJSON emits one bounded canonical certificate body.

func (InstallationCertificateBody) Scope added in v2026.0.79 

func (b InstallationCertificateBody) Scope() (receipt.Scope, error)

Scope derives the exact receipt namespace from the two signed certificate facts that own it: account and build offering.

func (*InstallationCertificateBody) UnmarshalJSON 

func (b *InstallationCertificateBody) UnmarshalJSON(data []byte) error

UnmarshalJSON strictly decodes without mutating the receiver on rejection.

func (InstallationCertificateBody) Validate 

func (b InstallationCertificateBody) Validate() error

Validate closes the certificate's facts and re-derives both bindings it asserts.

func (InstallationCertificateBody) WriteCanonical 

func (b InstallationCertificateBody) WriteCanonical(destination io.Writer) error

WriteCanonical writes one validated compact certificate body.

type InstallationCertificateDocument 

type InstallationCertificateDocument struct {
	Body        InstallationCertificateBody    `json:"body"`
	Attestation attest.Envelope[SigningDomain] `json:"attestation"`
}

InstallationCertificateDocument is the certificate body with its signature.

func IssueInstallationCertificate 

func IssueInstallationCertificate(body InstallationCertificateBody, signer crypto.Signer) (InstallationCertificateDocument, error)

IssueInstallationCertificate signs one validated certificate body.

func IssueRegisteredInstallation added in v2026.0.99 

func IssueRegisteredInstallation(
	issuance RegistrationCertificateIssuance,
	signer crypto.Signer,
) (InstallationCertificateDocument, error)

IssueRegisteredInstallation signs a certificate derived from one authenticated registration. No caller can substitute build, offering, device key, installation, or revision beside the verified request.

func (InstallationCertificateDocument) MarshalJSON 

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

MarshalJSON emits one bounded canonical signed certificate.

func (*InstallationCertificateDocument) UnmarshalJSON 

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

UnmarshalJSON strictly decodes without mutating the receiver on rejection.

func (InstallationCertificateDocument) Validate 

func (d InstallationCertificateDocument) Validate() error

Validate closes the signed certificate and binds its envelope to the namespace the body declares.

Verification recomputes the domain from the body, so a mismatch cannot survive attest.Verify. It can survive decoding, and a document held, logged, or passed on before anyone verifies it would carry an envelope claiming one namespace over a body declaring another. A shape check that admits a document its own verifier will refuse has not closed.

type OutcomeClass added in v2026.0.31 

type OutcomeClass uint8

OutcomeClass names one way a unit of work ended, as an ordinal this package deliberately cannot interpret. It carries a kind, never a finding.

func NewOutcomeClass added in v2026.0.31 

func NewOutcomeClass(ordinal uint8) (OutcomeClass, error)

NewOutcomeClass admits one outcome class ordinal.

func (OutcomeClass) IsValid added in v2026.0.31 

func (c OutcomeClass) IsValid() bool

IsValid reports whether c is an admitted class ordinal.

func (OutcomeClass) MarshalJSON added in v2026.0.37 

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

MarshalJSON emits the canonical decimal ordinal and refuses an inadmissible class.

func (OutcomeClass) String added in v2026.0.37 

func (c OutcomeClass) String() string

String renders the opaque ordinal for diagnostics, exactly as WorkUnitClass does and for the same reason.

func (*OutcomeClass) UnmarshalJSON added in v2026.0.37 

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

UnmarshalJSON accepts only the canonical decimal spelling of an admitted ordinal and leaves c unchanged on every rejection.

func (OutcomeClass) Validate added in v2026.0.31 

func (c OutcomeClass) Validate() error

Validate rejects the unset ordinal and every ordinal above the ceiling.

type OutcomeCount added in v2026.0.31 

type OutcomeCount struct {
	Class OutcomeClass `json:"class"`
	Count uint64       `json:"count"`
}

OutcomeCount is one class of result and how many units ended that way.

func (OutcomeCount) Validate added in v2026.0.31 

func (c OutcomeCount) Validate() error

Validate rejects an inadmissible class and a zero count.

type ProductStatus 

type ProductStatus uint8

ProductStatus is the complete commercial status domain an authority may return for one installation.

The whole set is named even though several members are treated the same way, because an unrecognised status must fail loudly rather than fall through a default branch. The default a client would pick under uncertainty is "keep working", and that is precisely the case where it must not. 

const (
	// ProductStatusInvalid is the unset status and is never admitted on the wire.
	ProductStatusInvalid ProductStatus = iota
	// ProductStatusActive is a paid installation in good standing.
	ProductStatusActive
	// ProductStatusPaymentRetry is a payment failure inside its grace period.
	ProductStatusPaymentRetry
	// ProductStatusReadOnly may inspect existing records but start no new work.
	ProductStatusReadOnly
	// ProductStatusStopped has passed grace and starts no new work.
	ProductStatusStopped
	// ProductStatusUpgradeRequired runs a build the authority no longer accepts.
	ProductStatusUpgradeRequired
	// ProductStatusRevoked has had its entitlement withdrawn.
	ProductStatusRevoked
)

func ParseProductStatus 

func ParseProductStatus(value string) (ProductStatus, error)

ParseProductStatus accepts one exact published token.

func (ProductStatus) AdmitsGrant 

func (s ProductStatus) AdmitsGrant() bool

AdmitsGrant reports whether a signed Lease grant is consistent with s.

This is the consistency rule, not the gate. Gate decides whether new work may begin, and it decides that from the authenticated Lease assessment alone. What this answers is narrower and comes first: an authority must never issue a grant alongside a status that contradicts it, so a document pairing the two is either an authority bug or a forgery, and it is refused rather than acted on in whichever half the reader prefers.

Active and payment-retry admit a grant. Payment retry is deliberately included: a failed charge inside its grace period is still a paying customer, and cutting work off at the first failure would be a refund request rather than a sale. Read-only, stopped, upgrade-required, and revoked do not.

func (ProductStatus) IsValid 

func (s ProductStatus) IsValid() bool

IsValid reports whether s is a published commercial status.

func (ProductStatus) MarshalJSON 

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

MarshalJSON emits the canonical token and refuses an unset status.

func (ProductStatus) String 

func (s ProductStatus) String() string

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

func (*ProductStatus) UnmarshalJSON 

func (s *ProductStatus) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts only a published token and leaves s unchanged on every rejection.

func (ProductStatus) Validate 

func (s ProductStatus) Validate() error

Validate rejects the unset status and every status outside the domain.

func (ProductStatus) ValidateOutcome 

func (s ProductStatus) ValidateOutcome(outcome lease.Outcome) error

ValidateOutcome closes the exact status a decision may travel beside, for one offering.

This is the one rule an authenticated document is held to; a weaker outcome-blind sibling predicate was deleted so nothing softer can be reached for. Every outcome pins its admissible statuses: a grant needs a paying status, a revocation must say revoked, and a refusal must name a reason a customer can act on: stopped, upgrade-required, or read-only.

The rule is deliberately offering blind. What read-only means to a given product, whether anything remains readable once new work stops, is product meaning, and meaning stays with the product that owns it: the authority names the status without knowing what it describes, exactly as it validates work-unit classes without knowing what they count. A product for which read-only describes nothing simply never issues it, and that policy lives with the issuer and the product, never in this shared validator.

type RegistrationAuthorityVerification added in v2026.0.99 

type RegistrationAuthorityVerification struct {
	PriorReplay      *controlwire.ReplayIdentity
	Request          RegistrationRequest
	ExpectedVerifier controlwire.RegistrationTokenVerifier
}

RegistrationAuthorityVerification is the complete product-neutral input to one authority transaction. ExpectedVerifier is the one-way value read from the authority's own account record. PriorReplay is the request previously committed under that verifier, when it has already been consumed.

A server reads those two facts and calls VerifyRegistrationAuthority inside its own persistence transaction. Primitive deliberately owns no database or account policy.

func (RegistrationAuthorityVerification) Validate added in v2026.0.99 

func (v RegistrationAuthorityVerification) Validate() error

Validate closes the authority-supplied verification facts. Authentication is part of validation because accepting a structurally valid but wrong token is not a meaningful intermediate state.

type RegistrationCertificateIssuance added in v2026.0.99 

type RegistrationCertificateIssuance struct {
	Registration VerifiedRegistrationAuthority
	IssuedAt     temporal.Instant
	Account      receipt.AccountIdentity
	Entitlement  lease.EntitlementID
}

RegistrationCertificateIssuance binds authority-owned commercial facts to one verified registration. Build, device, installation, revision, and offering are derived from Registration and cannot be repeated beside it.

func (RegistrationCertificateIssuance) Validate added in v2026.0.99 

func (i RegistrationCertificateIssuance) Validate() error

Validate closes the authority-owned facts needed to issue a certificate.

type RegistrationDocument 

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

RegistrationDocument is the authenticated response body.

func IssueRegistration 

func IssueRegistration(payload RegistrationPayload, signer crypto.Signer) (RegistrationDocument, error)

IssueRegistration signs one validated registration payload.

func (*RegistrationDocument) ControlResponseDocument added in v2026.0.96 

func (*RegistrationDocument) ControlResponseDocument()

func (RegistrationDocument) ControlResponseProjection added in v2026.0.96 

func (RegistrationDocument) ControlResponseProjection()

func (RegistrationDocument) MarshalJSON 

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

MarshalJSON emits one bounded canonical signed response.

func (*RegistrationDocument) UnmarshalJSON 

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

UnmarshalJSON strictly decodes without mutating the receiver on rejection.

func (RegistrationDocument) Validate 

func (d RegistrationDocument) Validate() error

Validate closes the signed response and binds its envelope to the namespace the payload declares, for the reason the certificate above states.

func (RegistrationDocument) ValidateJSONProjection added in v2026.0.96 

func (d RegistrationDocument) ValidateJSONProjection(
	encoded []byte,
	limits core.StrictJSONLimits,
) error

type RegistrationIdentity added in v2026.0.99 

type RegistrationIdentity struct {
	Build        core.BuildIdentity
	RequestNonce controlwire.RequestNonce
	DeviceKey    core.Ed25519PublicKey
	Installation lease.DeviceID
	Revision     controlwire.Revision
}

RegistrationIdentity is the non-secret registration fact an authority may use after authenticating the one-use token. It cannot carry source, paths, output, evidence, or the registration secret.

func (RegistrationIdentity) Validate added in v2026.0.99 

func (i RegistrationIdentity) Validate() error

Validate closes the non-secret identity and re-derives its device binding.

type RegistrationPayload 

type RegistrationPayload struct {
	Certificate *InstallationCertificateDocument `json:"certificate,omitempty"`
	Header      ResponseHeader                   `json:"header"`
	Watermark   UsageWatermark                   `json:"watermark"`
	Lease       lease.Document                   `json:"lease"`
	Entitlement lease.EntitlementID              `json:"entitlement"`
}

RegistrationPayload is the complete signed registration decision.

Entitlement is explicit so that even a signed refusal can bind and authenticate its Lease subject without inventing a credential. The certificate is absent exactly when the decision grants nothing.

func (RegistrationPayload) AttestationDomain 

func (RegistrationPayload) AttestationDomain() SigningDomain

AttestationDomain returns the response's exact signing namespace.

func (RegistrationPayload) MarshalJSON 

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

MarshalJSON emits one bounded canonical payload.

func (*RegistrationPayload) UnmarshalJSON 

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

UnmarshalJSON strictly decodes without mutating the receiver on rejection.

func (RegistrationPayload) Validate 

func (p RegistrationPayload) Validate() error

Validate closes subject, offering, status, Lease outcome, and credential presence as one decision.

These facts are checked against each other rather than only in isolation. A document whose parts are individually well-formed but disagree with one another is the shape a partially forged or partially stale response takes.

func (RegistrationPayload) WriteCanonical 

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

WriteCanonical writes one validated compact response payload.

type RegistrationRequest 

type RegistrationRequest struct {
	Token        controlwire.RegistrationToken `json:"registration_token"`
	Build        core.BuildIdentity            `json:"build"`
	RequestNonce controlwire.RequestNonce      `json:"request_nonce"`
	DeviceKey    core.Ed25519PublicKey         `json:"device_public_key"`
	Installation lease.DeviceID                `json:"installation"`
	Revision     controlwire.Revision          `json:"revision"`
}

RegistrationRequest is the complete first-contact body one installation sends.

It carries no customer-controlled name, path, source, corpus, output, or run data. What an installation is entitled to is decided from its identity, not from anything it says about its work. Field order here is the machine's, not the protocol's. The token is the only pointer-bearing member, so it leads and the garbage collector scans eight bytes instead of the whole struct.

Declaration order and protocol order are decoupled on purpose. Decoding matches members by name and does not care about order, and encoding states the protocol's order explicitly in MarshalJSON rather than inheriting it from whatever the layout happens to be. A struct that had to be declared in protocol order would force a choice between the bytes the authority defined and the layout the machine wants, and neither is negotiable.

func (RegistrationRequest) ControlNonce added in v2026.0.96 

func (r RegistrationRequest) ControlNonce() controlwire.RequestNonce

ControlNonce projects the request identity already carried on the wire.

func (RegistrationRequest) ControlRequestBodyLimit added in v2026.0.96 

func (RegistrationRequest) ControlRequestBodyLimit() (core.ByteCount, error)

func (RegistrationRequest) ControlRevision added in v2026.0.96 

func (r RegistrationRequest) ControlRevision() controlwire.Revision

ControlRevision projects the exact revision carried by this request.

func (RegistrationRequest) ControlRoute added in v2026.0.96 

func (r RegistrationRequest) ControlRoute() (controlwire.RouteContract, error)

ControlRoute projects the only route this document may address.

func (RegistrationRequest) Identity added in v2026.0.99 

func (r RegistrationRequest) Identity() (RegistrationIdentity, error)

Identity projects only the non-secret facts carried by a valid request.

func (RegistrationRequest) MarshalJSON 

func (r RegistrationRequest) MarshalJSON() ([]byte, error)

MarshalJSON emits one bounded canonical request in the protocol's member order, which is stated here and nowhere else.

func (*RegistrationRequest) UnmarshalJSON 

func (r *RegistrationRequest) UnmarshalJSON(data []byte) error

UnmarshalJSON strictly decodes without mutating the receiver on rejection.

func (RegistrationRequest) Validate 

func (r RegistrationRequest) Validate() error

Validate closes every ingress fact and binds the installation to its device key.

The binding is the rule that matters. An installation identity is derived from a device public key, so a request naming any other identity is either a client defect or an attempt to enrol as somebody else. Deriving it again here means a mismatch is refused locally, with a reason, instead of being refused by the authority with nothing the caller can act on.

type RegistrationVerification 

type RegistrationVerification struct {
	Expected    ResponseExpectation
	Build       core.BuildIdentity
	Document    RegistrationDocument
	TrustedKeys attest.TrustedKeys
	DeviceKey   core.Ed25519PublicKey
}

RegistrationVerification carries the caller's exact trust and request facts into response authentication.

Every field is required. An installation that verified a response without naming the request it made, the build it is, and the key it holds would be checking only that somebody signed something.

func (RegistrationVerification) Validate 

func (v RegistrationVerification) Validate() error

Validate closes the verification request's own shape.

type ResponseBindingError 

type ResponseBindingError interface {
	error
	// Field names the exact bound fact that disagreed.
	Field() ResponseHeaderField
	// contains filtered or unexported methods
}

ResponseBindingError is a sealed report that an authentic, well-formed response belongs to a different request than the one the caller made.

Sealed because the field it names is a closed domain: a caller may read which fact disagreed and switch on it, but cannot construct a binding failure that names something outside the header. The interface is satisfied only by this package's own unexported type.

type ResponseCommitment added in v2026.0.96 

type ResponseCommitment struct {
	Header     ResponseHeader    `json:"header"`
	BodySHA256 core.SHA256Digest `json:"body_sha256"`
	BodyLength core.ByteLength   `json:"body_length_bytes"`
}

ResponseCommitment is the one authority-signed agreement joining a common control header to the exact canonical bytes of a product-owned response. The body remains typed on the wire while its digest keeps bearer documents receive-only after admission.

func (ResponseCommitment) AttestationDomain added in v2026.0.96 

func (ResponseCommitment) AttestationDomain() SigningDomain

func (ResponseCommitment) MarshalJSON added in v2026.0.96 

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

func (*ResponseCommitment) UnmarshalJSON added in v2026.0.96 

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

func (ResponseCommitment) Validate added in v2026.0.96 

func (c ResponseCommitment) Validate() error

func (ResponseCommitment) WriteCanonical added in v2026.0.96 

func (c ResponseCommitment) WriteCanonical(destination io.Writer) error

type ResponseDocument added in v2026.0.96 

type ResponseDocument[
	Body any,
	BodyPtr interface {
		*Body
		core.Validatable
		json.Unmarshaler
	},
] struct {
	// contains filtered or unexported fields
}

ResponseDocument is the receive-only authenticated wire response. Its fields remain inaccessible until VerifyResponse has authenticated the authority and bound the header to the originating request.

func (ResponseDocument[Body, BodyPtr]) ControlResponseDocument added in v2026.0.96 

func (ResponseDocument[Body, BodyPtr]) ControlResponseDocument()

func (*ResponseDocument[Body, BodyPtr]) UnmarshalJSON added in v2026.0.96 

func (d *ResponseDocument[Body, BodyPtr]) UnmarshalJSON(data []byte) error

func (ResponseDocument[Body, BodyPtr]) Validate added in v2026.0.96 

func (d ResponseDocument[Body, BodyPtr]) Validate() error

type ResponseExpectation 

type ResponseExpectation struct {
	Offering          core.Offering
	PriorProviderTime temporal.Instant
	RequestNonce      controlwire.RequestNonce
	Account           receipt.AccountIdentity
	Installation      lease.DeviceID
	Revision          controlwire.Revision
	Family            controlwire.RouteFamily
}

ResponseExpectation is the caller-owned state one authentic response header is checked against.

PriorProviderTime may be unset, which is the first-contact case. Once set, an authority's clock may not move backward.

func (ResponseExpectation) Validate 

func (e ResponseExpectation) Validate() error

Validate closes the complete caller expectation.

type ResponseHeader 

type ResponseHeader struct {
	Offering     core.Offering            `json:"offering"`
	Policy       controlwire.PolicyCursor `json:"policy"`
	ProviderTime temporal.Instant         `json:"provider_time"`
	RequestNonce controlwire.RequestNonce `json:"request_nonce"`
	Account      receipt.AccountIdentity  `json:"account"`
	Installation lease.DeviceID           `json:"installation"`
	Revision     controlwire.Revision     `json:"revision"`
	Family       controlwire.RouteFamily  `json:"route_family"`
	Status       ProductStatus            `json:"status"`
}

ResponseHeader is the decision-bearing header every authenticated control-plane response carries. A response signature must cover this header and its complete body together, never one without the other.

func (ResponseHeader) MarshalJSON 

func (h ResponseHeader) MarshalJSON() ([]byte, error)

MarshalJSON emits one validated canonical header.

func (*ResponseHeader) UnmarshalJSON 

func (h *ResponseHeader) UnmarshalJSON(data []byte) error

UnmarshalJSON strictly decodes without mutating the receiver on rejection.

func (ResponseHeader) Validate 

func (h ResponseHeader) Validate() error

Validate closes the header's intrinsic shape.

func (ResponseHeader) ValidateAgainst 

func (h ResponseHeader) ValidateAgainst(expectation ResponseExpectation) error

ValidateAgainst binds a received header to the exact request that produced it and refuses a clock that moved backward.

Every rejection carries a distinct compiler-visible identity: an intrinsic shape failure keeps its owning sentinel, a disagreeing bound fact returns a binding error naming that exact field, and a backward authority instant returns the rollback identity. A caller that can only see "invalid" cannot tell a forged response from a stale one.

type ResponseHeaderField 

type ResponseHeaderField uint8

ResponseHeaderField names one bound fact, so a binding failure says which fact disagreed rather than only that something did. 

const (
	// ResponseHeaderFieldUnknown is the unset field and names no disagreement.
	ResponseHeaderFieldUnknown ResponseHeaderField = iota
	ResponseHeaderFieldRequestNonce
	ResponseHeaderFieldAccount
	ResponseHeaderFieldInstallation
	ResponseHeaderFieldRevision
	ResponseHeaderFieldRouteFamily
	ResponseHeaderFieldOffering
)

func ParseResponseHeaderField 

func ParseResponseHeaderField(value string) (ResponseHeaderField, error)

ParseResponseHeaderField accepts one exact bound-fact name.

func (ResponseHeaderField) IsValid 

func (f ResponseHeaderField) IsValid() bool

IsValid reports whether f names a real bound fact.

func (ResponseHeaderField) MarshalJSON 

func (f ResponseHeaderField) MarshalJSON() ([]byte, error)

MarshalJSON emits the field's wire name and refuses the unset field.

A binding failure names the exact fact that disagreed, and that name travels in diagnostics. Emitting the unset field would report a disagreement about nothing, which reads as a passing check.

func (ResponseHeaderField) String 

func (f ResponseHeaderField) String() string

String returns the field's wire name, or empty text when unset.

func (*ResponseHeaderField) UnmarshalJSON 

func (f *ResponseHeaderField) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts only a named bound fact and leaves f unchanged on every rejection.

func (ResponseHeaderField) Validate 

func (f ResponseHeaderField) Validate() error

Validate rejects the unset field and every field outside the domain.

type ResponseIssuance added in v2026.0.96 

type ResponseIssuance[Body core.ValidatedJSONMarshaler] struct {
	Signer     crypto.Signer
	Body       Body
	Header     ResponseHeader
	Assessment controlwire.ProtocolAssessment
}

ResponseIssuance is the authority input for one authenticated response.

func (ResponseIssuance[Body]) Validate added in v2026.0.96 

func (i ResponseIssuance[Body]) Validate() error

func (ResponseIssuance[Body]) ValidateForFamily added in v2026.0.96 

func (i ResponseIssuance[Body]) ValidateForFamily(family controlwire.RouteFamily) error

ValidateForFamily closes the product-auth boundary: a product response wrapper names its one route family here, while the generic envelope remains blind to the product body it signs.

type ResponseProjection added in v2026.0.96 

type ResponseProjection[Body core.ValidatedJSONMarshaler] struct {
	// contains filtered or unexported fields
}

ResponseProjection is the issue-only authenticated wire response. The product body can therefore use an encode-only bearer projection.

func IssueResponse added in v2026.0.96 

func IssueResponse[Body core.ValidatedJSONMarshaler](
	issuance ResponseIssuance[Body],
) (ResponseProjection[Body], error)

IssueResponse signs one response header and the exact canonical product body as one indivisible authority agreement.

func IssueResponseForFamily added in v2026.0.96 

func IssueResponseForFamily[Body core.ValidatedJSONMarshaler](
	issuance ResponseIssuance[Body],
	family controlwire.RouteFamily,
) (ResponseProjection[Body], error)

IssueResponseForFamily is the product-auth issuance door. It prevents a valid body and assessment from being signed for a sibling route family.

func IssueUpgradeRequiredResponse added in v2026.0.96 

func IssueUpgradeRequiredResponse[Body core.ValidatedJSONMarshaler](
	issuance UpgradeRequiredIssuance,
) (ResponseProjection[Body], error)

IssueUpgradeRequiredResponse signs one request-bound refusal without a product body. Body selects the response document the client was expecting; no value of that type is constructed, encoded, or exposed.

func (ResponseProjection[Body]) ControlResponseProjection added in v2026.0.96 

func (ResponseProjection[Body]) ControlResponseProjection()

func (ResponseProjection[Body]) MarshalJSON added in v2026.0.96 

func (p ResponseProjection[Body]) MarshalJSON() ([]byte, error)

func (ResponseProjection[Body]) Validate added in v2026.0.96 

func (p ResponseProjection[Body]) Validate() error

func (ResponseProjection[Body]) ValidateJSONProjection added in v2026.0.96 

func (p ResponseProjection[Body]) ValidateJSONProjection(
	encoded []byte,
	limits core.StrictJSONLimits,
) error

ValidateJSONProjection proves the exact issue-only bytes through the real strict wire shape without making the producer type an external decoder. The corresponding ResponseDocument remains the only ingress type.

type ResponseVerification added in v2026.0.96 

type ResponseVerification[
	Body any,
	BodyPtr interface {
		*Body
		core.Validatable
		json.Unmarshaler
	},
] struct {
	Expected    ResponseExpectation
	Document    ResponseDocument[Body, BodyPtr]
	TrustedKeys attest.TrustedKeys
}

ResponseVerification supplies caller-owned trust and request facts.

func (ResponseVerification[Body, BodyPtr]) Validate added in v2026.0.96 

func (v ResponseVerification[Body, BodyPtr]) Validate() error

type SigningDomain 

type SigningDomain uint8

SigningDomain is the closed set of namespaces a control-plane document may be signed under.

Closed rather than open on purpose. An unrecognised domain is refused rather than carried, because a verifier that accepted an unknown domain would be verifying that a signature is valid for something it cannot name. 

const (
	// SigningDomainUnknown is the unset domain and never signs anything.
	SigningDomainUnknown SigningDomain = iota
	// SigningDomainInstallationCertificateV1 signs one installation's
	// certificate body.
	SigningDomainInstallationCertificateV1
	// SigningDomainRegistrationV1 signs a complete registration response.
	SigningDomainRegistrationV1
	// SigningDomainCheckInV1 signs a check-in request.
	SigningDomainCheckInV1
	// SigningDomainCheckInResponseV1 signs a complete check-in response. The
	// request and the response are separate namespaces so a signature over one
	// can never be presented as a signature over the other.
	SigningDomainCheckInResponseV1
	// SigningDomainResponseV1 authenticates one response header together with
	// the exact canonical product-body commitment carried beside it.
	SigningDomainResponseV1
)

func ParseSigningDomain 

func ParseSigningDomain(value string) (SigningDomain, error)

ParseSigningDomain accepts one exact canonical domain text.

func (SigningDomain) IsValid 

func (d SigningDomain) IsValid() bool

IsValid reports whether d is one of the closed set's domains.

func (SigningDomain) MarshalJSON 

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

MarshalJSON emits the canonical domain text and refuses an unset domain.

It emits exactly what MarshalText emits. The domain names the namespace a signature covers, so a document that carried one spelling and verified under another would be verifying a signature it cannot name.

func (SigningDomain) MarshalText 

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

MarshalText emits the canonical domain text and refuses an unset domain.

func (SigningDomain) ParseCanonicalText 

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

ParseCanonicalText reconstructs the domain whose canonical text is the supplied bytes.

This is the self-referential half of the Attest contract: the same type both renders the text a signature covers and decides which text it will accept back. A separate parser could drift from the renderer and let a signature verify under a domain the signer never used.

func (SigningDomain) String 

func (d SigningDomain) String() string

String returns the canonical domain text, or empty text when unset.

func (*SigningDomain) UnmarshalJSON 

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

UnmarshalJSON accepts only a domain inside the closed set and leaves d unchanged on every rejection.

func (SigningDomain) Validate 

func (d SigningDomain) Validate() error

Validate rejects the unset domain and every domain outside the closed set.

type UpgradeRequiredIssuance added in v2026.0.96 

type UpgradeRequiredIssuance struct {
	Signer     crypto.Signer
	Header     ResponseHeader
	Assessment controlwire.ProtocolAssessment
}

UpgradeRequiredIssuance is the authority input for one common signed refusal. It deliberately carries no product body: an incompatible client must never be asked to decode facts from a contract it cannot speak.

func (UpgradeRequiredIssuance) Validate added in v2026.0.96 

func (i UpgradeRequiredIssuance) Validate() error

type UsageDisposition 

type UsageDisposition uint8

UsageDisposition is the authority-owned result of attempting to commit one immutable usage window.

Replay and conflict are distinct on purpose. Replay is the same window arriving twice and is not an error: a client that lost the response must be able to retry without being told its accounting is wrong. Conflict is a different window presented against a watermark that has already moved, and the authority never advances on it. 

const (
	// UsageDispositionUnknown is the unset disposition and names no result.
	UsageDispositionUnknown UsageDisposition = iota
	// UsageDispositionAccepted commits the window and advances the watermark.
	UsageDispositionAccepted
	// UsageDispositionReplay returns the watermark the original acceptance set.
	UsageDispositionReplay
	// UsageDispositionConflict returns the current watermark and advances nothing.
	UsageDispositionConflict
)

func ParseUsageDisposition 

func ParseUsageDisposition(value string) (UsageDisposition, error)

ParseUsageDisposition accepts one exact published token.

func (UsageDisposition) AdvancesWatermark 

func (d UsageDisposition) AdvancesWatermark() bool

AdvancesWatermark reports whether the authority moved the watermark.

Only an acceptance does. A client that advanced its own watermark on replay or conflict would report its next window against a generation the authority never issued, and every later check-in would conflict.

func (UsageDisposition) IsValid 

func (d UsageDisposition) IsValid() bool

IsValid reports whether d is a published commit result.

func (UsageDisposition) MarshalJSON 

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

MarshalJSON emits the canonical token and refuses an unset disposition.

func (UsageDisposition) String 

func (d UsageDisposition) String() string

String returns the canonical token, or empty text when unset.

func (*UsageDisposition) UnmarshalJSON 

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

UnmarshalJSON accepts only a published token and leaves d unchanged on every rejection.

func (UsageDisposition) Validate 

func (d UsageDisposition) Validate() error

Validate rejects the unset disposition and every disposition outside the set.

type UsageWatermark 

type UsageWatermark struct {
	Subject      lease.Subject     `json:"subject"`
	Generation   lease.Generation  `json:"generation"`
	WindowDigest core.SHA256Digest `json:"window_digest"`
	ChainDigest  core.SHA256Digest `json:"chain_digest"`
}

UsageWatermark is the fixed-size accepted-usage high-water fact for one exact entitlement and registered device.

The Lease subject is part of the fact rather than context around it, so one installation's sequence cannot be replayed as another's. Receipt owns a watermark of the same shape scoped to an account and offering; this one is scoped per installation and orders accepted usage windows rather than accepted evidence.

func AdvanceUsageWatermark 

func AdvanceUsageWatermark(current UsageWatermark, window UsageWindow) (UsageWatermark, error)

AdvanceUsageWatermark accepts one typed usage window and returns the next watermark in the chain.

The window arrives as the type that owns it, not as bytes: this door derives the one canonical form itself, so a caller can neither hand it a document that never validated nor smuggle arbitrary bytes into the chain. What this owns beyond that is that the sequence cannot go backward, cannot skip, and cannot wrap: a saturated generation is refused rather than rolled over to one, which would make an installation's oldest accepted window indistinguishable from its newest.

func NewInitialUsageWatermark 

func NewInitialUsageWatermark(subject lease.Subject) (UsageWatermark, error)

NewInitialUsageWatermark creates the only admitted starting point for one subject. Generation one represents no accepted usage window yet.

func (UsageWatermark) MarshalJSON 

func (w UsageWatermark) MarshalJSON() ([]byte, error)

MarshalJSON emits the complete validated watermark.

func (*UsageWatermark) UnmarshalJSON 

func (w *UsageWatermark) UnmarshalJSON(data []byte) error

UnmarshalJSON strictly decodes without mutating the receiver on rejection.

func (UsageWatermark) Validate 

func (w UsageWatermark) Validate() error

Validate closes identity, generation, and both digest facts.

type UsageWindow added in v2026.0.31 

type UsageWindow struct {
	Units     []WorkUnitCount         `json:"units"`
	Outcomes  []OutcomeCount          `json:"outcomes"`
	Bounds    temporal.IntervalBounds `json:"bounds"`
	Freshness temporal.Instant        `json:"freshness"`
}

UsageWindow is the complete bounded aggregate one installation reports for one interval.

It carries counts over opaque classes and the exact interval they fall in, and nothing else. There is no name, path, source, input, output, or finding anywhere in it, and no field one could be smuggled through, because the type is closed and every member is an ordinal, a count, or an instant. That is the agreement with the customer expressed as a struct rather than as a promise.

It is also why there is one check-in rather than one per product. A window carrying a product's own counters would be a shape only that product could fill and only an authority that already knew that product could read.

func (UsageWindow) MarshalJSON added in v2026.0.31 

func (w UsageWindow) MarshalJSON() ([]byte, error)

MarshalJSON emits one bounded canonical usage window.

func (*UsageWindow) UnmarshalJSON added in v2026.0.31 

func (w *UsageWindow) UnmarshalJSON(data []byte) error

UnmarshalJSON strictly decodes without mutating the receiver on rejection.

func (UsageWindow) Validate added in v2026.0.31 

func (w UsageWindow) Validate() error

Validate closes every reported fact and every relationship between them.

type VerifiedCheckIn added in v2026.0.31 

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

VerifiedCheckIn is proof that a check-in authenticated. Its fields are unexported so it cannot be manufactured without verifying.

func VerifyCheckIn added in v2026.0.31 

func VerifyCheckIn(verification CheckInVerification) (VerifiedCheckIn, error)

VerifyCheckIn authenticates the authority-issued credential first, then uses the exact device key it names as the sole authority for the request.

func (VerifiedCheckIn) Request added in v2026.0.31 

func (v VerifiedCheckIn) Request() (CheckInRequest, error)

Request returns the authenticated request, revalidating first.

func (VerifiedCheckIn) Validate added in v2026.0.31 

func (v VerifiedCheckIn) Validate() error

Validate revalidates every proof the type claims to hold.

type VerifiedCheckInCommit added in v2026.0.99 

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

VerifiedCheckInCommit is the proof-carrying result of comparing one authenticated check-in with authoritative usage and policy facts. It owns no storage and performs no effect.

func CommitCheckIn added in v2026.0.99 

func CommitCheckIn(request CheckInCommitRequest) (VerifiedCheckInCommit, error)

CommitCheckIn resolves exactly three states from immutable facts: the window advances once, is the exact window already committed, or conflicts with a different authoritative watermark. It allocates no history and owns no persistence mechanism.

func (VerifiedCheckInCommit) Disposition added in v2026.0.99 

func (c VerifiedCheckInCommit) Disposition() (UsageDisposition, error)

Disposition reports whether the immutable comparison accepted, replayed, or conflicted.

func (VerifiedCheckInCommit) Validate added in v2026.0.99 

func (c VerifiedCheckInCommit) Validate() error

Validate replays the complete comparison and refuses a manufactured proof.

func (VerifiedCheckInCommit) Watermark added in v2026.0.99 

func (c VerifiedCheckInCommit) Watermark() (UsageWatermark, error)

Watermark returns the exact watermark the authority must sign and, only for an accepted disposition, persist.

type VerifiedCheckInResponse 

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

VerifiedCheckInResponse is proof that a response authenticated. Its fields are unexported so the type cannot be manufactured by a caller that skipped verification.

func VerifyCheckInResponse 

func VerifyCheckInResponse(verification CheckInResponseVerification) (VerifiedCheckInResponse, error)

VerifyCheckInResponse authenticates a response and binds it to the exact request that produced it.

The binding check runs before the signature check on purpose. A correctly signed response to somebody else's request is the interesting attack, and naming that failure as a binding error rather than a signature error is what lets a caller tell a replayed response from a forged one.

func (VerifiedCheckInResponse) Lease 

func (v VerifiedCheckInResponse) Lease() (lease.Verified, error)

Lease returns the authenticated lease proof.

func (VerifiedCheckInResponse) Payload 

func (v VerifiedCheckInResponse) Payload() (CheckInResponsePayload, error)

Payload returns the authenticated payload, revalidating first so a zero value cannot be presented as a verified one.

func (VerifiedCheckInResponse) Validate 

func (v VerifiedCheckInResponse) Validate() error

Validate revalidates every fact the proof claims to hold.

type VerifiedInstallationCertificate added in v2026.0.17 

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

VerifiedInstallationCertificate is returned only after an installation certificate's authority signature has verified.

Its fields are unexported and reachable only through accessors that revalidate, so a caller cannot construct one and possessing it is itself the proof that verification happened rather than a claim that it did.

The type exists because a certificate is sometimes the whole authority. A live exchange binds a response to the request that provoked it, but an installation loading a credential it stored earlier has no request to bind against: the certificate's own signature, and the device key it names, are all there is to check. Making that a first-class result keeps the weaker situation from being served by a weaker rule.

func VerifyInstallationCertificate added in v2026.0.17 

func VerifyInstallationCertificate(
	certificate InstallationCertificateDocument,
	trusted attest.TrustedKeys,
) (VerifiedInstallationCertificate, error)

VerifyInstallationCertificate authenticates one authority-issued installation certificate and returns the device key it names as a trust set.

The order is the security property, and it is the reason this is one function rather than two steps a caller sequences. The certificate is verified against the authority's keys first, and only then does the device key inside it become an authority for anything. A caller that read the device key out of an unverified certificate and then checked a request against it would be letting a self-signed document nominate the key that validates it.

func (VerifiedInstallationCertificate) Body added in v2026.0.17 

func (v VerifiedInstallationCertificate) Body() (InstallationCertificateBody, error)

Body returns the verified certificate body.

func (VerifiedInstallationCertificate) DeviceKeys added in v2026.0.17 

func (v VerifiedInstallationCertificate) DeviceKeys() (attest.TrustedKeys, error)

DeviceKeys returns the trust set holding exactly the device key the authority bound to this installation.

It is the only key an installation's own signatures may be checked against. Returning a trust set rather than a bare key keeps callers from assembling their own, which is where a second admitted key would creep in.

func (VerifiedInstallationCertificate) Proof added in v2026.0.17 

func (v VerifiedInstallationCertificate) Proof() (attest.Verified[SigningDomain], error)

Proof returns the authority's verified signature over the certificate.

func (VerifiedInstallationCertificate) Validate added in v2026.0.17 

func (v VerifiedInstallationCertificate) Validate() error

Validate revalidates every proof the value claims to hold, so a sealed type cannot be presented as evidence of something it never proved.

type VerifiedRegistration 

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

VerifiedRegistration is returned only after the response, the credential when one is present, the Lease, and the request binding have all verified.

Its fields are unexported and reachable only through accessors that revalidate. A caller cannot construct one, so possessing this value is itself the proof that verification happened rather than a claim that it did.

func VerifyRegistration 

func VerifyRegistration(request RegistrationVerification) (VerifiedRegistration, error)

VerifyRegistration authenticates one registration response against the exact request that produced it.

The order is deliberate. The binding check runs before any signature work, so a response for somebody else's request is refused without spending verification on it. The response signature comes next, then the Lease, then the certificate: each stage only runs on bytes an earlier stage has already accepted.

func (VerifiedRegistration) Certificate 

func (v VerifiedRegistration) Certificate() (InstallationCertificateDocument, error)

Certificate returns the authenticated installation certificate. A registration that granted nothing carries none, and reports that rather than a zero value.

func (VerifiedRegistration) Lease 

func (v VerifiedRegistration) Lease() (lease.Verified, error)

Lease returns the authenticated Lease, which is what Gate decides on.

func (VerifiedRegistration) Payload 

func (v VerifiedRegistration) Payload() (RegistrationPayload, error)

Payload returns the authenticated payload.

func (VerifiedRegistration) Validate 

func (v VerifiedRegistration) Validate() error

Validate rejects a zero or internally contradictory authenticated result.

type VerifiedRegistrationAuthority added in v2026.0.99 

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

VerifiedRegistrationAuthority is proof that the request matched the authority's persisted one-way verifier and was either fresh or byte-exact to the request that consumed it. Its fields are private so callers cannot claim that verification happened.

func VerifyRegistrationAuthority added in v2026.0.99 

func VerifyRegistrationAuthority(
	verification RegistrationAuthorityVerification,
) (verified VerifiedRegistrationAuthority, resultErr error)

VerifyRegistrationAuthority owns no persistence. It returns the exact replay record the server persists atomically with its own registration decision and destroys the presented token on every return path. A changed second use returns no proof and the replay-conflict identity, regardless of which request field changed.

func (VerifiedRegistrationAuthority) Identity added in v2026.0.99 

func (v VerifiedRegistrationAuthority) Identity() (RegistrationIdentity, error)

Identity returns the authenticated request's non-secret facts.

func (VerifiedRegistrationAuthority) Replay added in v2026.0.99 

func (v VerifiedRegistrationAuthority) Replay() (
	controlwire.ReplayIdentity,
	controlwire.ReplayDisposition,
	error,
)

Replay returns the exact record the authority persists and whether this was its first acceptance or an exact retry.

func (VerifiedRegistrationAuthority) Validate added in v2026.0.99 

func (v VerifiedRegistrationAuthority) Validate() error

Validate closes the sealed non-secret result. The token is deliberately not retained: VerifyRegistrationAuthority destroys it on every return path.

type VerifiedResponse added in v2026.0.96 

type VerifiedResponse[
	Body any,
	BodyPtr interface {
		*Body
		core.Validatable
		json.Unmarshaler
	},
] struct {
	// contains filtered or unexported fields
}

VerifiedResponse is the only path that exposes an authenticated product body. Its fields are deliberately unexported.

func VerifyResponse added in v2026.0.96 

func VerifyResponse[
	Body any,
	BodyPtr interface {
		*Body
		core.Validatable
		json.Unmarshaler
	},
](verification ResponseVerification[Body, BodyPtr]) (VerifiedResponse[Body, BodyPtr], error)

VerifyResponse authenticates the authority and binds the common header to the exact request before it exposes the product body.

func (VerifiedResponse[Body, BodyPtr]) Body added in v2026.0.96 

func (v VerifiedResponse[Body, BodyPtr]) Body() (Body, error)

func (VerifiedResponse[Body, BodyPtr]) Header added in v2026.0.96 

func (v VerifiedResponse[Body, BodyPtr]) Header() (ResponseHeader, error)

func (VerifiedResponse[Body, BodyPtr]) Validate added in v2026.0.96 

func (v VerifiedResponse[Body, BodyPtr]) Validate() error

type WorkUnitClass added in v2026.0.31 

type WorkUnitClass uint8

WorkUnitClass names one kind of work an installation performed, as an ordinal this package deliberately cannot interpret.

The authority validates the ordinal's range, the window it falls in, and the arithmetic between the counts. It never learns what a class means. Which command ran, what it was pointed at, and what it found stay on the machine that did the work, and the mapping from a product's own closed vocabulary into these ordinals is the product's, never crossing the wire in either direction.

This is the same reason a border agent reads a nationality field instead of keeping one reader per country. A named class here would write one product's vocabulary into a contract both ends share, and every product after it would have to add its own.

func NewWorkUnitClass added in v2026.0.31 

func NewWorkUnitClass(ordinal uint8) (WorkUnitClass, error)

NewWorkUnitClass admits one work-unit class ordinal.

func (WorkUnitClass) IsValid added in v2026.0.31 

func (c WorkUnitClass) IsValid() bool

IsValid reports whether c is an admitted class ordinal.

func (WorkUnitClass) MarshalJSON added in v2026.0.37 

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

MarshalJSON emits the canonical decimal ordinal and refuses an inadmissible class, the same bytes the bare integer produced before the contract was explicit.

func (WorkUnitClass) String added in v2026.0.37 

func (c WorkUnitClass) String() string

String renders the opaque ordinal for diagnostics. A number is all either end knows about a class, so a number is all either end may print.

func (*WorkUnitClass) UnmarshalJSON added in v2026.0.37 

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

UnmarshalJSON accepts only the canonical decimal spelling of an admitted ordinal and leaves c unchanged on every rejection.

func (WorkUnitClass) Validate added in v2026.0.31 

func (c WorkUnitClass) Validate() error

Validate rejects the unset ordinal and every ordinal above the ceiling.

type WorkUnitCount added in v2026.0.31 

type WorkUnitCount struct {
	Class WorkUnitClass `json:"class"`
	Count uint64        `json:"count"`
}

WorkUnitCount is one class of work and how many units of it ran.

func (WorkUnitCount) Validate added in v2026.0.31 

func (c WorkUnitCount) Validate() error

Validate rejects an inadmissible class and a zero count. A class that did no work is absent from the list rather than reported as having done none.

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.