chit

package
v2026.0.153 Latest Latest
Warning

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

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

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

View Source
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
)
View Source
const (
	ChitPayloadJSONMaximumBytes  = 32 << 10
	ChitDocumentJSONMaximumBytes = 64 << 10
)
View Source
const (
	SigningDomainChitV1Token    = "primitive-chit-2026-1"
	SigningDomainCatalogV1Token = "primitive-chit-catalog-2026-1"
	SigningDomainQueryV1Token   = "primitive-chit-query-2026-1"
)
View Source
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
)
View Source
const (
	QueryPayloadJSONMaximumBytes  = 32 << 10
	QueryDocumentJSONMaximumBytes = 64 << 10
)

Variables

This section is empty.

Functions

This section is empty.

Types

type CatalogDocument

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

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 NewChitID

func NewChitID(value id.UUIDv7) (ChitID, error)

func ParseChitID

func ParseChitID(value string) (ChitID, error)

func (ChitID) MarshalJSON

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

func (ChitID) String

func (i ChitID) String() string

func (*ChitID) UnmarshalJSON

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

func (ChitID) Validate

func (i ChitID) Validate() error

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

func CursorFor(identity ChitID) (Cursor, error)

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 (c Cursor) MarshalJSON() ([]byte, error)

func (*Cursor) UnmarshalJSON

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

func (Cursor) Validate

func (c Cursor) Validate() error

type CustodyState

type CustodyState uint8

CustodyState is the authority-observed availability of one immutable chit.

const (
	CustodyStateUnknown CustodyState = iota
	CustodyStateStored
	CustodyStateRetrievalUnavailable
	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 Issue

func Issue(issuance Issuance) (Document, error)

func (Document) MarshalJSON

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

func (*Document) UnmarshalJSON

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

func (Document) Validate

func (d Document) Validate() error

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

func ParseEntryName(value string) (EntryName, error)

ParseEntryName closes product-owned display text into portable wire form.

func (EntryName) MarshalJSON

func (n EntryName) MarshalJSON() ([]byte, error)

MarshalJSON emits the portable name as one canonical JSON string.

func (EntryName) String

func (n EntryName) String() string

String returns the canonical portable name.

func (*EntryName) UnmarshalJSON

func (n *EntryName) UnmarshalJSON(data []byte) error

UnmarshalJSON admits one portable name transactionally.

func (EntryName) Validate

func (n EntryName) Validate() error

Validate rejects ambiguous, platform-dependent, or unbounded names.

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

type Expectation struct {
	Scope    receipt.Scope
	Identity ChitID
}

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 Issuance struct {
	Signer      crypto.Signer
	Existing    *Document
	Payload     Payload
	TrustedKeys attest.TrustedKeys
}

func (Issuance) Validate

func (i Issuance) Validate() error

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

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

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

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

MarshalJSON emits the commitment as canonical lowercase hexadecimal.

func (*Partition) UnmarshalJSON added in v2026.0.149

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

UnmarshalJSON admits one canonical nonzero commitment and preserves the receiver on every refusal.

func (Partition) Validate added in v2026.0.149

func (p Partition) Validate() error

Validate requires a set, nonzero SHA-256 commitment.

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 (p Payload) MarshalJSON() ([]byte, error)

func (*Payload) UnmarshalJSON

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

func (Payload) Validate

func (p Payload) Validate() error

func (Payload) WriteCanonical

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

type Position

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

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

func After

func After(cursor Cursor) (Position, error)

After requests the page after one authority-issued cursor.

func Start

func Start() Position

Start requests the first catalog page.

func (Position) MarshalJSON

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

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

func (Position) Validate

func (p Position) Validate() error

Validate enforces the exact tagged-union arm.

type Query

type Query struct {
	Scope     receipt.Scope         `json:"scope"`
	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.

func (Query) Validate

func (q Query) Validate() error

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

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 All

func All() Selection

All selects every chit in one authenticated scope.

func Specific

func Specific(identity ChitID) (Selection, error)

Specific selects one exact chit identity.

func (Selection) MarshalJSON

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

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

func (Selection) Validate

func (s Selection) Validate() error

Validate enforces the exact tagged-union arm.

type 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)

func (Verified) Document

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

func (Verified) Validate

func (v Verified) Validate() 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

Addition returns the exact authenticated entry admitted by the stream.

func (VerifiedManifestEntry) Summary added in v2026.0.102

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.

func NewVersion

func NewVersion(value uint64) (Version, error)

func (Version) MarshalJSON

func (v Version) MarshalJSON() ([]byte, error)

func (Version) Uint64

func (v Version) Uint64() uint64

func (*Version) UnmarshalJSON

func (v *Version) UnmarshalJSON(data []byte) error

func (Version) Validate

func (v Version) Validate() error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL