Documentation
¶
Overview ¶
Package lease verifies and assesses one fixed-size, OGS-signed commercial decision.
OGS owns accounts, plans, payment standing, trials, device limits, policy, and the choice to issue a grant, refusal, or revocation. Package lease owns only the signed decision's typed shape, subject binding, exact timeline, monotonic generation advance, and pure local assessment.
The package performs no clock read, persistence, transport, retry, background work, command authorization, or product-specific rendering. Consumers supply real temporal observations and durably commit selected decisions and returned high-water instants before creating paid work.
Index ¶
- Constants
- type AdvanceRequest
- type AdvanceResult
- type AdvanceState
- type Assessment
- type ClockContradiction
- type ContactState
- type Decision
- func (Decision) AttestationDomain() Domain
- func (d Decision) Grant() (Grant, error)
- func (d Decision) Header() (Header, error)
- func (d Decision) MarshalJSON() ([]byte, error)
- func (d Decision) Outcome() Outcome
- func (d Decision) Refusal() (Refusal, error)
- func (d Decision) Revocation() (Revocation, error)
- func (d *Decision) UnmarshalJSON(data []byte) error
- func (d Decision) Validate() error
- func (d Decision) WriteCanonical(destination io.Writer) error
- type DeviceID
- type Document
- type Domain
- type EntitlementID
- type EvaluateRequest
- type Generation
- type Grant
- type GrantDecisionRequest
- type Header
- type Outcome
- type Refusal
- type RefusalDecisionRequest
- type Revision
- type Revocation
- type RevocationDecisionRequest
- type RevocationReason
- type ScopeMismatch
- type State
- type Subject
- type Verified
- type VerifyRequest
Constants ¶
const ( // GrantCanonicalJSONMaximumBytes is the exact compact grant maximum. GrantCanonicalJSONMaximumBytes = len( `{"not_before":,"contact_after":,"not_after":,"good_until":}`, ) + 4*temporal.InstantCanonicalJSONMaximumBytes // GrantJSONMaximumBytes bounds accepted grant JSON. GrantJSONMaximumBytes = GrantCanonicalJSONMaximumBytes + grantJSONWhitespaceAllowance // RefusalCanonicalJSONMaximumBytes is the exact compact refusal maximum. RefusalCanonicalJSONMaximumBytes = len(`{"contact_after":}`) + temporal.InstantCanonicalJSONMaximumBytes // RefusalJSONMaximumBytes bounds accepted refusal JSON. RefusalJSONMaximumBytes = RefusalCanonicalJSONMaximumBytes + refusalJSONWhitespaceAllowance // RevocationCanonicalJSONMaximumBytes is the exact compact revocation maximum. RevocationCanonicalJSONMaximumBytes = len(`{"reason":}`) + RevocationReasonCanonicalJSONMaximumBytes // RevocationJSONMaximumBytes bounds accepted revocation JSON. RevocationJSONMaximumBytes = RevocationCanonicalJSONMaximumBytes + revocationJSONWhitespaceAllowance // DecisionCanonicalJSONMaximumBytes is the exact compact decision maximum. DecisionCanonicalJSONMaximumBytes = decisionCommonCanonicalJSONBytes + len(`"`+outcomeGrantToken+`"`) + GrantCanonicalJSONMaximumBytes // DecisionJSONMaximumBytes bounds accepted decision JSON. DecisionJSONMaximumBytes = DecisionCanonicalJSONMaximumBytes + decisionJSONWhitespaceAllowance )
const ( // DocumentCanonicalJSONMaximumBytes is the exact compact signed-document // maximum. DocumentCanonicalJSONMaximumBytes = len(`{"decision":,"attestation":}`) + DecisionCanonicalJSONMaximumBytes + leaseEnvelopeCanonicalJSONMaximumBytes // DocumentJSONMaximumBytes bounds an accepted signed document. DocumentJSONMaximumBytes = DocumentCanonicalJSONMaximumBytes + documentJSONWhitespaceAllowance )
const ( // RevisionCanonicalJSONMaximumBytes is the exact compact revision maximum. RevisionCanonicalJSONMaximumBytes = len(`"` + revisionV1Token + `"`) // RevisionJSONMaximumBytes bounds accepted revision JSON. RevisionJSONMaximumBytes = RevisionCanonicalJSONMaximumBytes + enumJSONWhitespaceAllowance )
const ( OutcomeCanonicalJSONMaximumBytes = len(`"` + outcomeRevocationToken + `"`) OutcomeJSONMaximumBytes = OutcomeCanonicalJSONMaximumBytes + enumJSONWhitespaceAllowance )
const ( RevocationReasonCanonicalJSONMaximumBytes = len(`"` + revocationSecurityOrPlatformRiskToken + `"`) RevocationReasonJSONMaximumBytes = RevocationReasonCanonicalJSONMaximumBytes + enumJSONWhitespaceAllowance )
const ( // GenerationMaximumDecimalDigits is uint64's maximum decimal width. GenerationMaximumDecimalDigits = 20 // GenerationCanonicalJSONMaximumBytes is the exact compact JSON maximum. GenerationCanonicalJSONMaximumBytes = GenerationMaximumDecimalDigits + len(`""`) // GenerationJSONMaximumBytes bounds accepted generation JSON. GenerationJSONMaximumBytes = GenerationCanonicalJSONMaximumBytes + generationJSONWhitespaceAllowance )
const ( // IdentifierBytes is the exact extent of each opaque lease identifier. IdentifierBytes = 16 // IdentifierHexBytes is the exact lowercase-hex extent. IdentifierHexBytes = 2 * IdentifierBytes // IdentifierCanonicalJSONMaximumBytes is the exact compact JSON extent. IdentifierCanonicalJSONMaximumBytes = IdentifierHexBytes + len(`""`) // IdentifierJSONMaximumBytes bounds accepted identifier JSON. IdentifierJSONMaximumBytes = IdentifierCanonicalJSONMaximumBytes + identifierJSONWhitespaceAllowance )
const ( // SubjectCanonicalJSONMaximumBytes is the exact maximum compact subject extent. SubjectCanonicalJSONMaximumBytes = len(`{"offering":,"entitlement_id":,"device_id":}`) + core.OfferingCanonicalJSONMaximumBytes + 2*IdentifierCanonicalJSONMaximumBytes // SubjectJSONMaximumBytes bounds accepted subject JSON. SubjectJSONMaximumBytes = SubjectCanonicalJSONMaximumBytes + subjectJSONWhitespaceAllowance )
const ( // ClockRollbackToleranceNanoseconds is the exact accepted difference // between an observed wall reading and trusted time progress. ClockRollbackToleranceNanoseconds int64 = 5 * int64(temporal.NanosecondsPerMinute) )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AdvanceRequest ¶
AdvanceRequest compares one current and one candidate authentic decision.
func (AdvanceRequest) Validate ¶
func (r AdvanceRequest) Validate() error
Validate closes both authentic inputs.
type AdvanceResult ¶
type AdvanceResult struct {
// contains filtered or unexported fields
}
AdvanceResult selects exactly one authentic decision.
func Advance ¶
func Advance(request AdvanceRequest) (AdvanceResult, error)
Advance accepts an identical replay or a strictly newer, non-regressing decision for the same exact subject.
Lease identity is decided before sequence. Two decisions that name different subjects or different revisions never share one generation sequence, so their generation order carries no meaning and every such pair conflicts.
func (AdvanceResult) State ¶
func (r AdvanceResult) State() AdvanceState
State returns whether selection changed.
func (AdvanceResult) Validate ¶
func (r AdvanceResult) Validate() error
Validate rejects a zero or internally contradictory result.
func (AdvanceResult) Verified ¶
func (r AdvanceResult) Verified() (Verified, error)
Verified returns the selected authentic decision.
type AdvanceState ¶
type AdvanceState uint8
AdvanceState reports whether the current authentic decision changed.
const ( AdvanceStateUnknown AdvanceState = iota AdvanceStateUnchanged AdvanceStateAdvanced )
func (AdvanceState) IsValid ¶
func (s AdvanceState) IsValid() bool
IsValid reports membership in the advance-state domain.
func (AdvanceState) OffWireEnum ¶
func (AdvanceState) OffWireEnum()
OffWireEnum declares AdvanceState as a deliberate off-wire enum.
func (AdvanceState) String ¶
func (s AdvanceState) String() string
String returns one diagnostic label.
func (AdvanceState) Validate ¶
func (s AdvanceState) Validate() error
Validate rejects values outside the closed advance-state domain.
type Assessment ¶
type Assessment struct {
// contains filtered or unexported fields
}
Assessment is one pure, fixed-size decision at one effective instant.
func Evaluate ¶
func Evaluate(request EvaluateRequest) (Assessment, error)
Evaluate advances trusted time with Go's monotonic elapsed duration, detects excessive wall rollback, and classifies the authentic decision.
func (Assessment) ContactState ¶
func (a Assessment) ContactState() ContactState
ContactState returns whether the signed earliest contact is due.
func (Assessment) Decision ¶
func (a Assessment) Decision() (Decision, error)
Decision returns the exact authentic decision being assessed.
func (Assessment) EffectiveAt ¶
func (a Assessment) EffectiveAt() (temporal.Instant, error)
EffectiveAt returns the monotonic/durable high-water to persist.
func (Assessment) State ¶
func (a Assessment) State() State
State returns the local work-state fact.
func (Assessment) Validate ¶
func (a Assessment) Validate() error
Validate rejects the zero result and recomputes its classification.
type ClockContradiction ¶
type ClockContradiction interface {
error
Validate() error
Instants() (temporal.Instant, temporal.Instant, error)
// contains filtered or unexported methods
}
ClockContradiction is a sealed report that a wall reading trails trusted progress by more than ClockRollbackToleranceNanoseconds.
Only Lease can implement it. A caller therefore cannot forge the stable clock identity from unset, reordered, or merely tolerated instants.
type ContactState ¶
type ContactState uint8
ContactState is the local earliest-contact classification.
const ( ContactStateUnknown ContactState = iota ContactStateNotDue ContactStateDue ContactStateProhibited )
func (ContactState) IsValid ¶
func (s ContactState) IsValid() bool
IsValid reports membership in the contact-state domain.
func (ContactState) OffWireEnum ¶
func (ContactState) OffWireEnum()
OffWireEnum declares ContactState as a deliberate off-wire enum.
func (ContactState) String ¶
func (s ContactState) String() string
String returns one diagnostic label.
func (ContactState) Validate ¶
func (s ContactState) Validate() error
Validate rejects values outside the closed contact-state domain.
type Decision ¶
type Decision struct {
// contains filtered or unexported fields
}
Decision is one closed grant, refusal, or revocation union.
func NewGrantDecision ¶
func NewGrantDecision(request GrantDecisionRequest) (Decision, error)
NewGrantDecision constructs one valid grant decision.
func NewRefusalDecision ¶
func NewRefusalDecision(request RefusalDecisionRequest) (Decision, error)
NewRefusalDecision constructs one valid recoverable refusal.
func NewRevocationDecision ¶
func NewRevocationDecision(request RevocationDecisionRequest) (Decision, error)
NewRevocationDecision constructs one valid for-cause revocation.
func (Decision) AttestationDomain ¶
AttestationDomain returns Lease's one exact signing domain.
func (Decision) MarshalJSON ¶
MarshalJSON emits one canonical tagged union.
func (Decision) Refusal ¶
Refusal returns the refusal payload or a contract error for another outcome.
func (Decision) Revocation ¶
func (d Decision) Revocation() (Revocation, error)
Revocation returns the revocation payload or a contract error for another outcome.
func (*Decision) UnmarshalJSON ¶
UnmarshalJSON accepts one bounded strict tagged union without mutation on rejection.
type DeviceID ¶
type DeviceID struct {
// contains filtered or unexported fields
}
DeviceID is one opaque registered-installation identity.
func DeviceIDForPublicKey ¶ added in v2026.0.4
func DeviceIDForPublicKey(key core.Ed25519PublicKey) (DeviceID, error)
DeviceIDForPublicKey derives one registered-installation identity from the exact bytes of a validated Ed25519 public key.
The identity is the first IdentifierBytes of SHA-256 over all ed25519.PublicKeySize key bytes, in key order, with no prefix, salt, or separator. Every key byte is covered. The derivation is pure, total over set keys, and stable: it is the durable identity OGS registers, and it appears inside signed decision subjects, so any change to these bytes retires every registered installation.
Truncation to IdentifierBytes is the Lease identifier width, not a security budget increase: distinctness rests on 128 bits of SHA-256 output rather than 256. Callers that need the full digest keep the key and hash it themselves.
func NewDeviceID ¶
func NewDeviceID(value [IdentifierBytes]byte) (DeviceID, error)
NewDeviceID constructs one nonzero opaque device identity.
func ParseDeviceID ¶
ParseDeviceID parses exact lowercase hexadecimal.
func (DeviceID) MarshalJSON ¶
MarshalJSON emits exact lowercase hexadecimal.
func (*DeviceID) UnmarshalJSON ¶
UnmarshalJSON accepts one exact identity without mutating on rejection.
type Document ¶
type Document struct {
Decision Decision `json:"decision"`
Attestation attest.Envelope[Domain] `json:"attestation"`
}
Document is an untrusted decision and detached structural attestation. Validate proves shape only, never authority or signature validity.
func (Document) MarshalJSON ¶
MarshalJSON emits the exact document field order.
func (*Document) UnmarshalJSON ¶
UnmarshalJSON accepts one bounded strict document without receiver mutation on rejection.
type Domain ¶
type Domain uint8
Domain is the closed Attest domain for Lease decisions.
func (Domain) MarshalText ¶
MarshalText emits the exact Attest domain.
func (Domain) OffWireEnum ¶
func (Domain) OffWireEnum()
OffWireEnum declares that Attest owns Domain's canonical text projection; Domain itself is never a direct JSON enum.
func (Domain) ParseCanonicalText ¶
ParseCanonicalText reconstructs one exact Attest domain.
type EntitlementID ¶
type EntitlementID struct {
// contains filtered or unexported fields
}
EntitlementID is one opaque OGS entitlement identity.
func NewEntitlementID ¶
func NewEntitlementID(value [IdentifierBytes]byte) (EntitlementID, error)
NewEntitlementID constructs one nonzero opaque entitlement identity.
func ParseEntitlementID ¶
func ParseEntitlementID(text string) (EntitlementID, error)
ParseEntitlementID parses exact lowercase hexadecimal.
func (EntitlementID) MarshalJSON ¶
func (i EntitlementID) MarshalJSON() ([]byte, error)
MarshalJSON emits exact lowercase hexadecimal.
func (EntitlementID) String ¶
func (i EntitlementID) String() string
String returns exact lowercase hexadecimal or empty for an invalid value.
func (*EntitlementID) UnmarshalJSON ¶
func (i *EntitlementID) UnmarshalJSON(data []byte) error
UnmarshalJSON accepts one exact identity without mutating on rejection.
func (EntitlementID) Validate ¶
func (i EntitlementID) Validate() error
Validate rejects the unset entitlement identity.
type EvaluateRequest ¶
type EvaluateRequest struct {
StartedAt temporal.Observation
ObservedAt temporal.Observation
Decision Verified
DurableHighWater temporal.Instant
}
EvaluateRequest supplies real Temporal observations and the consumer's durably committed high-water. StartedAt and ObservedAt normally preserve Go's monotonic reading because the consumer obtains them from temporal.Observe.
func (EvaluateRequest) Validate ¶
func (r EvaluateRequest) Validate() error
Validate checks the complete pure evaluation ingress.
type Generation ¶
type Generation struct {
// contains filtered or unexported fields
}
Generation is a positive decision sequence number.
func NewGeneration ¶
func NewGeneration(value uint64) (Generation, error)
NewGeneration constructs one positive generation.
func ParseGeneration ¶
func ParseGeneration(text string) (Generation, error)
ParseGeneration parses canonical unsigned decimal.
func (Generation) MarshalJSON ¶
func (g Generation) MarshalJSON() ([]byte, error)
MarshalJSON emits a quoted canonical decimal to avoid numeric precision loss.
func (Generation) String ¶
func (g Generation) String() string
String returns canonical decimal or empty for an invalid value.
func (Generation) Uint64 ¶
func (g Generation) Uint64() (uint64, error)
Uint64 returns the exact sequence number.
func (*Generation) UnmarshalJSON ¶
func (g *Generation) UnmarshalJSON(data []byte) error
UnmarshalJSON accepts one quoted canonical decimal without mutation on rejection.
type Grant ¶
type Grant struct {
NotBefore temporal.Instant `json:"not_before"`
ContactAfter temporal.Instant `json:"contact_after"`
NotAfter temporal.Instant `json:"not_after"`
GoodUntil temporal.Instant `json:"good_until"`
}
Grant is an exact usable lease timeline selected by OGS.
func (Grant) MarshalJSON ¶
MarshalJSON emits exact grant field order.
func (*Grant) UnmarshalJSON ¶
UnmarshalJSON accepts one bounded strict grant.
type GrantDecisionRequest ¶
GrantDecisionRequest constructs one signed-grant body.
type Header ¶
type Header struct {
Subject Subject `json:"subject"`
IssuedAt temporal.Instant `json:"issued_at"`
Generation Generation `json:"generation"`
Revision Revision `json:"revision"`
}
Header is the common authenticated identity and sequence of every decision.
type Outcome ¶
type Outcome uint8
Outcome is the signed decision variant.
func ParseOutcome ¶
ParseOutcome parses one exact outcome token.
func (Outcome) MarshalJSON ¶
func (*Outcome) UnmarshalJSON ¶
type Refusal ¶
Refusal is a recoverable denial and its earliest next contact.
func (Refusal) MarshalJSON ¶
MarshalJSON emits exact refusal field order.
func (*Refusal) UnmarshalJSON ¶
UnmarshalJSON accepts one bounded strict refusal.
type RefusalDecisionRequest ¶
RefusalDecisionRequest constructs one signed-refusal body.
type Revision ¶
type Revision uint8
Revision is the closed lease wire revision.
func ParseRevision ¶
ParseRevision parses one exact revision token.
func (Revision) MarshalJSON ¶
func (*Revision) UnmarshalJSON ¶
type Revocation ¶
type Revocation struct {
Reason RevocationReason `json:"reason"`
}
Revocation is one contract-authorized for-cause denial.
func (Revocation) MarshalJSON ¶
func (r Revocation) MarshalJSON() ([]byte, error)
MarshalJSON emits exact revocation field order.
func (*Revocation) UnmarshalJSON ¶
func (r *Revocation) UnmarshalJSON(data []byte) error
UnmarshalJSON accepts one bounded strict revocation.
func (Revocation) Validate ¶
func (r Revocation) Validate() error
Validate closes the for-cause domain.
type RevocationDecisionRequest ¶
type RevocationDecisionRequest struct {
Header Header
Revocation Revocation
}
RevocationDecisionRequest constructs one signed-revocation body.
type RevocationReason ¶
type RevocationReason uint8
RevocationReason is one contract-authorized for-cause ground.
const ( RevocationReasonUnknown RevocationReason = iota RevocationReasonLicenceBreach RevocationReasonUnlawfulOrAbusiveUse RevocationReasonSecurityOrPlatformRisk RevocationReasonInsolvency )
func ParseRevocationReason ¶
func ParseRevocationReason(token string) (RevocationReason, error)
ParseRevocationReason parses one exact revocation token.
func (RevocationReason) IsValid ¶
func (r RevocationReason) IsValid() bool
func (RevocationReason) MarshalJSON ¶
func (r RevocationReason) MarshalJSON() ([]byte, error)
func (RevocationReason) String ¶
func (r RevocationReason) String() string
func (*RevocationReason) UnmarshalJSON ¶
func (r *RevocationReason) UnmarshalJSON(data []byte) error
func (RevocationReason) Validate ¶
func (r RevocationReason) Validate() error
type ScopeMismatch ¶
type ScopeMismatch interface {
error
Validate() error
Subjects() (Subject, Subject, error)
// contains filtered or unexported methods
}
ScopeMismatch is a sealed report that an authentic decision names a subject other than the one the caller asked Verify to accept.
Only Lease can implement it. A caller therefore cannot forge the stable scope identity from unset or equal subjects.
type State ¶
type State uint8
State is the complete local status of one authentic decision.
func (State) OffWireEnum ¶
func (State) OffWireEnum()
OffWireEnum declares State as a deliberate off-wire enum.
type Subject ¶
type Subject struct {
Offering core.Offering `json:"offering"`
EntitlementID EntitlementID `json:"entitlement_id"`
DeviceID DeviceID `json:"device_id"`
}
Subject binds one decision to an exact offering, entitlement, and registered installation.
func (Subject) MarshalJSON ¶
MarshalJSON emits the exact subject field order.
func (*Subject) UnmarshalJSON ¶
UnmarshalJSON accepts one bounded strict subject without mutation on rejection.
type Verified ¶
type Verified struct {
// contains filtered or unexported fields
}
Verified is an authentic decision bound to the caller's expected subject.
func Verify ¶
func Verify(request VerifyRequest) (Verified, error)
Verify authenticates one signed decision and binds its exact subject.
type VerifyRequest ¶
type VerifyRequest struct {
ExpectedSubject Subject
Document Document
TrustedKeys attest.TrustedKeys
}
VerifyRequest authenticates and subject-binds one untrusted document.
func (VerifyRequest) Validate ¶
func (r VerifyRequest) Validate() error
Validate proves request structure without claiming signature trust.