Documentation
¶
Overview ¶
Package chit owns the customer-facing custody ticket above accepted object receipts: UUIDv7 identities, versioned collections, streaming manifest closure, authority-signed immutable chits, and bounded signed catalog pages.
Chit never interprets product evidence. Consumers decide which local objects are eligible and which display names are safe. Receipt proves that each exact object entered custody; Chit organizes those facts into versions a customer can list and retrieve.
Index ¶
- Constants
- type CatalogDocument
- type CatalogEntry
- type CatalogIssuance
- type CatalogPayload
- type CatalogVerification
- type ChitID
- type CollectionID
- type Continuation
- type Cursor
- type CustodyState
- type Document
- type EntryName
- type EntrySequence
- type Expectation
- type Issuance
- type ManifestAccumulator
- type ManifestAddition
- type ManifestDigest
- type ManifestEntry
- type ManifestEntryVerifier
- type ManifestSummary
- type ObjectCount
- type Partition
- type Payload
- type Position
- type Query
- type QueryCommitment
- type QueryDocument
- type QueryIssuance
- type QueryPayload
- type QueryRequest
- type QueryVerification
- type Selection
- type SigningDomain
- func (d SigningDomain) IsValid() bool
- func (d SigningDomain) MarshalJSON() ([]byte, error)
- func (d SigningDomain) MarshalText() ([]byte, error)
- func (SigningDomain) ParseCanonicalText(text []byte) (SigningDomain, error)
- func (d SigningDomain) String() string
- func (d *SigningDomain) UnmarshalJSON(data []byte) error
- func (d SigningDomain) Validate() error
- type Verification
- type Verified
- type VerifiedManifestEntry
- type VerifiedQuery
- type Version
Constants ¶
const ( // CatalogCursorCommitmentDomain separates catalog positions from every // other SHA-256 use in Primitive. CatalogCursorCommitmentDomain = "primitive.chit.catalog-cursor.v1" // CatalogCursorFrameSeparator makes the domain/identity frame injective. CatalogCursorFrameSeparator byte = 0 )
const ( ChitPayloadJSONMaximumBytes = 32 << 10 ChitDocumentJSONMaximumBytes = 64 << 10 )
const ( SigningDomainChitV1Token = "primitive-chit-2026-1" SigningDomainCatalogV1Token = "primitive-chit-catalog-2026-1" SigningDomainQueryV1Token = "primitive-chit-query-2026-1" )
const ( // EntryNameMaximumBytes bounds one portable customer-visible manifest name. EntryNameMaximumBytes = 4096 // EntryNameMaximumComponents bounds slash-delimited logical nesting. EntryNameMaximumComponents = 256 // EntryNameComponentMaximumBytes is the portable component byte ceiling. EntryNameComponentMaximumBytes = 255 )
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"`
}
func IssueCatalog ¶
func IssueCatalog(issuance CatalogIssuance) (CatalogDocument, error)
func (CatalogDocument) MarshalJSON ¶
func (d CatalogDocument) MarshalJSON() ([]byte, error)
func (*CatalogDocument) UnmarshalJSON ¶
func (d *CatalogDocument) UnmarshalJSON(data []byte) error
func (CatalogDocument) Validate ¶
func (d CatalogDocument) Validate() error
type CatalogEntry ¶
type CatalogEntry struct {
Chit Document `json:"chit"`
State CustodyState `json:"state"`
}
CatalogEntry binds one immutable chit to its current availability.
func (CatalogEntry) Validate ¶
func (e CatalogEntry) Validate() error
Validate closes the signed chit and current custody-state structure without inventing an observation instant for the temporal retention decision.
func (CatalogEntry) ValidateAt ¶
func (e CatalogEntry) ValidateAt(observed temporal.Instant) error
type CatalogIssuance ¶
type CatalogIssuance struct {
Signer crypto.Signer
Payload CatalogPayload
}
func (CatalogIssuance) Validate ¶
func (i CatalogIssuance) Validate() error
type CatalogPayload ¶
type CatalogPayload struct {
Scope receipt.Scope `json:"scope"`
Entries []CatalogEntry `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 authority-observed page. Entries are newest first by UUIDv7 text, making pagination deterministic across large histories.
func VerifyCatalog ¶
func VerifyCatalog(verification CatalogVerification) (CatalogPayload, error)
func (CatalogPayload) AttestationDomain ¶
func (CatalogPayload) AttestationDomain() SigningDomain
func (CatalogPayload) MarshalJSON ¶
func (p CatalogPayload) MarshalJSON() ([]byte, error)
func (*CatalogPayload) UnmarshalJSON ¶
func (p *CatalogPayload) UnmarshalJSON(data []byte) error
func (CatalogPayload) Validate ¶
func (p CatalogPayload) Validate() error
func (CatalogPayload) WriteCanonical ¶
func (p CatalogPayload) WriteCanonical(destination io.Writer) error
type CatalogVerification ¶
type CatalogVerification struct {
Request QueryPayload
Document CatalogDocument
TrustedKeys attest.TrustedKeys
}
func (CatalogVerification) Validate ¶
func (v CatalogVerification) Validate() error
type ChitID ¶
type ChitID struct {
// contains filtered or unexported fields
}
ChitID is the authority-issued UUIDv7 for one immutable uploaded version.
func ParseChitID ¶
func (ChitID) MarshalJSON ¶
func (*ChitID) UnmarshalJSON ¶
type CollectionID ¶
type CollectionID struct {
// contains filtered or unexported fields
}
CollectionID is the stable UUIDv7 joining versions of one product-owned evidence collection without disclosing a repository or project name.
func NewCollectionID ¶
func NewCollectionID(value id.UUIDv7) (CollectionID, error)
func ParseCollectionID ¶
func ParseCollectionID(value string) (CollectionID, error)
func (CollectionID) MarshalJSON ¶
func (i CollectionID) MarshalJSON() ([]byte, error)
func (CollectionID) String ¶
func (i CollectionID) String() string
func (*CollectionID) UnmarshalJSON ¶
func (i *CollectionID) UnmarshalJSON(data []byte) error
func (CollectionID) Validate ¶
func (i CollectionID) Validate() error
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
func More ¶
func More(cursor Cursor) (Continuation, error)
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
type Cursor ¶
type Cursor struct {
// contains filtered or unexported fields
}
Cursor is the opaque closure of the last entry represented by a page.
func CursorFor ¶ added in v2026.0.101
CursorFor closes one exact Chit identity into the opaque position used after that entry. The identity is the catalog ordering key; custody-state changes therefore do not invalidate a customer's position.
func (Cursor) MarshalJSON ¶
func (*Cursor) UnmarshalJSON ¶
type CustodyState ¶
type CustodyState uint8
CustodyState is the authority-observed availability of one immutable chit.
const ( CustodyStateUnknown CustodyState = iota CustodyStateStored CustodyStateDeleted )
func (CustodyState) IsValid ¶
func (s CustodyState) IsValid() bool
IsValid reports whether s is one published custody state.
func (CustodyState) MarshalJSON ¶
func (s CustodyState) MarshalJSON() ([]byte, error)
func (CustodyState) String ¶
func (s CustodyState) String() string
func (*CustodyState) UnmarshalJSON ¶
func (s *CustodyState) UnmarshalJSON(data []byte) error
func (CustodyState) Validate ¶
func (s CustodyState) Validate() error
type Document ¶
type Document struct {
Payload Payload `json:"payload"`
Attestation attest.Envelope[SigningDomain] `json:"attestation"`
}
Document carries one authority-signed immutable chit.
func (Document) MarshalJSON ¶
func (*Document) UnmarshalJSON ¶
type EntryName ¶
type EntryName struct {
// contains filtered or unexported fields
}
EntryName is one portable slash-delimited manifest display path. It is not a local filesystem path and never implies that the named local path exists.
func ParseEntryName ¶
ParseEntryName closes product-owned display text into portable wire form.
func (EntryName) MarshalJSON ¶
MarshalJSON emits the portable name as one canonical JSON string.
func (*EntryName) UnmarshalJSON ¶
UnmarshalJSON admits one portable name transactionally.
type EntrySequence ¶
type EntrySequence struct {
// contains filtered or unexported fields
}
EntrySequence is a positive contiguous manifest position.
func NewEntrySequence ¶
func NewEntrySequence(value uint64) (EntrySequence, error)
func (EntrySequence) MarshalJSON ¶
func (s EntrySequence) MarshalJSON() ([]byte, error)
func (EntrySequence) Uint64 ¶
func (s EntrySequence) Uint64() uint64
func (*EntrySequence) UnmarshalJSON ¶
func (s *EntrySequence) UnmarshalJSON(data []byte) error
func (EntrySequence) Validate ¶
func (s EntrySequence) Validate() error
type Expectation ¶
Expectation prevents a valid chit for another account, offering, or ID from satisfying a caller's request.
func (Expectation) Validate ¶
func (e Expectation) Validate() error
type Issuance ¶
type ManifestAccumulator ¶
type ManifestAccumulator struct {
// contains filtered or unexported fields
}
ManifestAccumulator closes entries in one pass and O(1) retained memory.
func NewManifestAccumulator ¶
func NewManifestAccumulator() *ManifestAccumulator
func (*ManifestAccumulator) Add ¶
func (a *ManifestAccumulator) Add(addition ManifestAddition) error
Add admits exactly the next authenticated receipt and sequence, then folds the entry's canonical wire bytes.
func (*ManifestAccumulator) Seal ¶
func (a *ManifestAccumulator) Seal() (ManifestSummary, error)
Seal returns the immutable stream closure. Sealing twice is refused because the accumulator represents one construction boundary, not a reusable cache.
type ManifestAddition ¶
type ManifestAddition struct {
Entry ManifestEntry
Evidence receipt.VerifiedEvidence
}
ManifestAddition is the issuance-only proof that one wire entry carries the exact Receipt document already authenticated by Receipt's sealed verifier.
func (ManifestAddition) Validate ¶
func (a ManifestAddition) Validate() error
Validate refuses structurally plausible but unauthenticated receipt documents at the manifest-construction boundary.
type ManifestDigest ¶
type ManifestDigest struct {
// contains filtered or unexported fields
}
ManifestDigest is the domain-separated digest of the canonical entry stream.
func (ManifestDigest) MarshalJSON ¶
func (d ManifestDigest) MarshalJSON() ([]byte, error)
func (*ManifestDigest) UnmarshalJSON ¶
func (d *ManifestDigest) UnmarshalJSON(data []byte) error
func (ManifestDigest) Validate ¶
func (d ManifestDigest) Validate() error
type ManifestEntry ¶
type ManifestEntry struct {
Name EntryName `json:"name"`
ContentType core.HTTPMediaType `json:"content_type"`
Evidence receipt.EvidenceDocument `json:"evidence"`
Sequence EntrySequence `json:"sequence"`
}
ManifestEntry is one customer-visible object in a logical uploaded version. Name is a product-owned safe display path, never an inferred local path.
func (ManifestEntry) Validate ¶
func (e ManifestEntry) Validate() error
type ManifestEntryVerifier ¶ added in v2026.0.102
type ManifestEntryVerifier struct {
// contains filtered or unexported fields
}
ManifestEntryVerifier recomputes one persisted manifest stream while retaining only the exact requested entry. Its memory is constant in the number and extent of manifest objects.
func NewManifestEntryVerifier ¶ added in v2026.0.102
func NewManifestEntryVerifier(sequence EntrySequence) (*ManifestEntryVerifier, error)
NewManifestEntryVerifier begins one O(1) lookup over a manifest stream.
func (*ManifestEntryVerifier) Add ¶ added in v2026.0.102
func (v *ManifestEntryVerifier) Add(addition ManifestAddition) error
Add admits the next authenticated manifest entry and retains it only when it is the requested sequence.
func (*ManifestEntryVerifier) Seal ¶ added in v2026.0.102
func (v *ManifestEntryVerifier) Seal(expected ManifestSummary) (VerifiedManifestEntry, error)
Seal proves the recomputed stream equals the authenticated summary before releasing the selected entry. The underlying accumulator owns terminal use.
type ManifestSummary ¶
type ManifestSummary struct {
Digest ManifestDigest `json:"digest"`
TotalBytes core.ByteLength `json:"total_bytes"`
Objects ObjectCount `json:"objects"`
}
ManifestSummary closes the exact ordered object set without materializing it.
func (ManifestSummary) Validate ¶
func (s ManifestSummary) Validate() error
type ObjectCount ¶
type ObjectCount struct {
// contains filtered or unexported fields
}
ObjectCount is a positive number of objects in one manifest.
func NewObjectCount ¶
func NewObjectCount(value uint64) (ObjectCount, error)
func (ObjectCount) MarshalJSON ¶
func (c ObjectCount) MarshalJSON() ([]byte, error)
func (ObjectCount) Uint64 ¶
func (c ObjectCount) Uint64() uint64
func (*ObjectCount) UnmarshalJSON ¶
func (c *ObjectCount) UnmarshalJSON(data []byte) error
func (ObjectCount) Validate ¶
func (c ObjectCount) Validate() error
type Partition ¶ added in v2026.0.149
type Partition struct {
// contains filtered or unexported fields
}
Partition is an opaque nonzero commitment supplied by product policy to bound one custody catalog without disclosing what the partition means.
func NewPartition ¶ added in v2026.0.149
func NewPartition(digest core.SHA256Digest) (Partition, error)
NewPartition closes one product-owned commitment into Chit's blind catalog namespace.
func (Partition) MarshalJSON ¶ added in v2026.0.149
MarshalJSON emits the commitment as canonical lowercase hexadecimal.
func (*Partition) UnmarshalJSON ¶ added in v2026.0.149
UnmarshalJSON admits one canonical nonzero commitment and preserves the receiver on every refusal.
type Payload ¶
type Payload struct {
Scope receipt.Scope `json:"scope"`
Manifest ManifestSummary `json:"manifest"`
AcceptedAt temporal.Instant `json:"accepted_at"`
RetainUntil temporal.Instant `json:"retain_until"`
Version Version `json:"version"`
Identity ChitID `json:"chit_id"`
Collection CollectionID `json:"collection_id"`
Partition Partition `json:"partition"`
}
Payload is the immutable authority statement for one logical uploaded version. The manifest summary closes every object without embedding a slice.
func (Payload) AttestationDomain ¶
func (Payload) AttestationDomain() SigningDomain
func (Payload) MarshalJSON ¶
func (*Payload) UnmarshalJSON ¶
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 (Position) MarshalJSON ¶
MarshalJSON emits only the member owned by the selected tagged-union arm.
type Query ¶
type Query struct {
Scope receipt.Scope `json:"scope"`
Partition Partition `json:"partition"`
Selection Selection `json:"selection"`
Position Position `json:"position"`
Limit core.CatalogPageLimit `json:"limit"`
}
Query is the complete typed input behind `chit -all` or `chit <id>`.
func NewQuery ¶
func NewQuery(request QueryRequest) (Query, error)
NewQuery constructs one completely typed catalog query.
type QueryCommitment ¶ added in v2026.0.81
type QueryCommitment struct {
// contains filtered or unexported fields
}
QueryCommitment is the non-secret domain-separated closure of one exact device-signed query payload.
func CommitQuery ¶ added in v2026.0.81
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.81
func (c QueryCommitment) MarshalJSON() ([]byte, error)
func (*QueryCommitment) UnmarshalJSON ¶ added in v2026.0.81
func (c *QueryCommitment) UnmarshalJSON(data []byte) error
func (QueryCommitment) Validate ¶ added in v2026.0.81
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 catalog 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 chit 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
Partition Partition
Selection Selection
Position Position
PageSize uint16
}
QueryRequest is the constructor boundary for one customer catalog 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 {
Chit ChitID `json:"chit_id"`
Kind core.CatalogSelectionKind `json:"kind"`
}
Selection is the exact all-or-one customer catalog selection.
func (Selection) MarshalJSON ¶
MarshalJSON emits only the member owned by the selected tagged-union arm.
type SigningDomain ¶
type SigningDomain uint8
SigningDomain separates one immutable chit from a catalog observation.
const ( SigningDomainUnknown SigningDomain = iota SigningDomainChitV1 SigningDomainCatalogV1 SigningDomainQueryV1 )
func (SigningDomain) IsValid ¶
func (d SigningDomain) IsValid() bool
IsValid reports whether d names one published chit signing namespace.
func (SigningDomain) MarshalJSON ¶
func (d SigningDomain) MarshalJSON() ([]byte, error)
func (SigningDomain) MarshalText ¶
func (d SigningDomain) MarshalText() ([]byte, error)
func (SigningDomain) ParseCanonicalText ¶
func (SigningDomain) ParseCanonicalText(text []byte) (SigningDomain, error)
func (SigningDomain) String ¶
func (d SigningDomain) String() string
func (*SigningDomain) UnmarshalJSON ¶
func (d *SigningDomain) UnmarshalJSON(data []byte) error
func (SigningDomain) Validate ¶
func (d SigningDomain) Validate() error
type Verification ¶
type Verification struct {
Expected Expectation
Document Document
TrustedKeys attest.TrustedKeys
}
func (Verification) Validate ¶
func (v Verification) Validate() error
type Verified ¶
type Verified struct {
// contains filtered or unexported fields
}
Verified is the sealed authentication result.
func Verify ¶
func Verify(verification Verification) (Verified, error)
type VerifiedManifestEntry ¶ added in v2026.0.102
type VerifiedManifestEntry struct {
// contains filtered or unexported fields
}
VerifiedManifestEntry is sealed proof that one authenticated receipt entry participated at its exact sequence in one exact manifest summary.
func (VerifiedManifestEntry) Addition ¶ added in v2026.0.102
func (v VerifiedManifestEntry) Addition() (ManifestAddition, error)
Addition returns the exact authenticated entry admitted by the stream.
func (VerifiedManifestEntry) Summary ¶ added in v2026.0.102
func (v VerifiedManifestEntry) Summary() (ManifestSummary, error)
Summary returns the exact recomputed manifest closure.
func (VerifiedManifestEntry) Validate ¶ added in v2026.0.102
func (v VerifiedManifestEntry) Validate() error
Validate closes the sealed entry and the exact stream summary that proved it.
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
type Version ¶
type Version struct {
// contains filtered or unexported fields
}
Version is the positive monotonic version within one collection.