Documentation
¶
Overview ¶
Package evidencebook is a reference implementation of the Evidence Layer: a local evidence store that records evidence and the typed links between records, keeps payload digests committed while payload bytes are resolved separately, maintains three distinct classes of index, and answers requests for evidence with portable, independently verifiable bundles.
A Book embeds a commitment substrate. The Checkpointed Local Log binding (OpenCLL) is the reference; a SCITT receipt-holding binding (NewSCITTReceiptSubstrate) shows that conformance does not depend on it. The substrate never appears in the Book's API: callers append records and ask for bundles, requests, reconciliations and closes, and the book composes every proof itself.
Every record is sealed as an Agent Action Capsule whose agent input digest commits the record header, so a bundle this package produces is checked by the neutral Evidence Bundle verifier with nothing from this package. Over the SCITT stub, which keeps no ordered log, that verifier reports interval coverage as withheld.
Index ¶
- Constants
- Variables
- func KeyID(s Signer) string
- func ReconcileHalves(a, b HalfSet, compare Comparator) ([]PairResult, Tallies)
- func SamePayloadCommitments(a, b Half) bool
- func VerifyKeyRange(root IndexRoot, lo, hi string, proof KeyRangeProof) ([]string, error)
- func VerifyLeaf(root IndexRoot, proof LeafProof) error
- type AbsenceStatement
- type AnsweredStatement
- type ArtifactResponse
- type AuthenticatedIndex
- type Book
- func (b *Book) Acknowledge(ctx context.Context, peerCloseID, counterparty string) (Record, error)
- func (b *Book) Append(ctx context.Context, entry Entry) (Record, error)
- func (b *Book) Bundle(ctx context.Context, req BundleRequest) (Bundle, error)
- func (b *Book) Checkpoint(ctx context.Context) (Checkpoint, error)
- func (b *Book) Checkpoints(ctx context.Context) ([]Checkpoint, error)
- func (b *Book) Close(ctx context.Context, in CloseInput) (Record, error)
- func (b *Book) Discover(ctx context.Context, query string, limit int) (Candidates, error)
- func (b *Book) Get(_ context.Context, recordID string) (Record, error)
- func (b *Book) IndexState(ctx context.Context) (string, error)
- func (b *Book) Info() (string, SubstrateInfo)
- func (b *Book) ProveKeyRange(ctx context.Context, index, lo, hi string) (KeyRangeAnswer, error)
- func (b *Book) Query(ctx context.Context, filter Filter) ([]Record, error)
- func (b *Book) Rebuild(ctx context.Context) (string, error)
- func (b *Book) Rebut(ctx context.Context, peerCloseID, counterparty string, reason json.RawMessage) (Record, error)
- func (b *Book) Reconcile(ctx context.Context, in ReconcileInput) (Reconciliation, error)
- func (b *Book) RecordAbsence(ctx context.Context, requestRecordID string, windowEnd time.Time, route string) (Record, error)
- func (b *Book) RecordResponse(ctx context.Context, requestRecordID string, resp Response, keys ResponderKeys) (Record, error)
- func (b *Book) Release() error
- func (b *Book) Request(ctx context.Context, req EvidenceRequest, responder string) (SentRequest, error)
- func (b *Book) ResolvePayload(ctx context.Context, recordID, digest string) ([]byte, error)
- func (b *Book) Respond(ctx context.Context, requestBytes []byte, opts RespondOptions) (Response, Record, error)
- func (b *Book) Retention(_ context.Context, recordID, digest string) (RetentionState, error)
- func (b *Book) SetRetention(ctx context.Context, recordID, digest string, state RetentionState, ...) (Record, error)
- func (b *Book) Size() uint64
- type Bundle
- type BundleCheckpoint
- type BundleClaims
- type BundleRequest
- type CLLSubstrate
- func (s *CLLSubstrate) Append(ctx context.Context, recordID string, at time.Time) (uint64, error)
- func (s *CLLSubstrate) Checkpoint(ctx context.Context, now time.Time) (Checkpoint, error)
- func (s *CLLSubstrate) Entries(ctx context.Context, afterSeq uint64, limit int) ([]SubstrateEntry, error)
- func (s *CLLSubstrate) Info() SubstrateInfo
- func (s *CLLSubstrate) Latest(ctx context.Context) (Checkpoint, error)
- func (s *CLLSubstrate) ProveConsistency(ctx context.Context, older, newer Checkpoint) (ConsistencyEvidence, error)
- func (s *CLLSubstrate) ProveInclusion(ctx context.Context, seq uint64, at Checkpoint) (InclusionEvidence, error)
- func (s *CLLSubstrate) ProveInterval(ctx context.Context, firstSeq uint64, at Checkpoint) (IntervalEvidence, error)
- func (s *CLLSubstrate) Release() error
- func (s *CLLSubstrate) Size(ctx context.Context) (uint64, error)
- type Candidates
- type Checkpoint
- type CloseInput
- type CloseStatement
- type CloseStatus
- type Comparator
- type CompletenessCertificate
- type Config
- type ConsistencyEvidence
- type Correlation
- type Coverage
- type DisclosureStatement
- type DiscoveryIndex
- type Ed25519Signer
- type Entry
- type EpistemicType
- type EvidenceRequest
- type ExchangeState
- type FileStore
- func (s *FileStore) Checkpoints(context.Context) ([]Checkpoint, error)
- func (s *FileStore) GetRecord(_ context.Context, recordID string) (StoredRecord, error)
- func (s *FileStore) PutCheckpoint(ctx context.Context, cp Checkpoint) error
- func (s *FileStore) PutRecord(ctx context.Context, record StoredRecord) error
- func (s *FileStore) Records(context.Context) ([]StoredRecord, error)
- func (s *FileStore) Release() error
- type Filter
- type Freshness
- type Half
- type HalfSet
- type Header
- type InclusionEvidence
- type IndexRoot
- type IntervalEvidence
- type KeyRangeAnswer
- type KeyRangeProof
- type LeafProof
- type LifecycleStatement
- type Link
- type LinkType
- type LogCoordinates
- type MMRInclusion
- type Membership
- type OperationalIndex
- type PairResult
- type PayloadDir
- func (p *PayloadDir) Delete(_ context.Context, digest string) error
- func (p *PayloadDir) Put(_ context.Context, digest string, data []byte) error
- func (p *PayloadDir) Resolve(_ context.Context, digest string) ([]byte, error)
- func (p *PayloadDir) StorageDigest(ctx context.Context, digest string) (string, error)
- type PayloadResolver
- type PayloadsMode
- type PeerRecord
- type Pin
- type RangeWitness
- type Receipt
- type ReconcileInput
- type Reconciliation
- type Record
- type RecordSource
- type Refusal
- type Registrar
- type RequestStatement
- type RespondOptions
- type ResponderKeys
- type Response
- type ResponseStatement
- type RetentionState
- type SCITTReceiptSubstrate
- func (s *SCITTReceiptSubstrate) Append(ctx context.Context, recordID string, at time.Time) (uint64, error)
- func (s *SCITTReceiptSubstrate) Checkpoint(ctx context.Context, _ time.Time) (Checkpoint, error)
- func (s *SCITTReceiptSubstrate) Entries(_ context.Context, afterSeq uint64, limit int) ([]SubstrateEntry, error)
- func (s *SCITTReceiptSubstrate) Info() SubstrateInfo
- func (s *SCITTReceiptSubstrate) Latest(context.Context) (Checkpoint, error)
- func (s *SCITTReceiptSubstrate) ProveConsistency(context.Context, Checkpoint, Checkpoint) (ConsistencyEvidence, error)
- func (s *SCITTReceiptSubstrate) ProveInclusion(_ context.Context, seq uint64, at Checkpoint) (InclusionEvidence, error)
- func (s *SCITTReceiptSubstrate) ProveInterval(context.Context, uint64, Checkpoint) (IntervalEvidence, error)
- func (s *SCITTReceiptSubstrate) Release() error
- func (s *SCITTReceiptSubstrate) Size(context.Context) (uint64, error)
- type SQLiteIndex
- func (x *SQLiteIndex) Add(ctx context.Context, record Record) error
- func (x *SQLiteIndex) Find(ctx context.Context, f Filter) ([]string, error)
- func (x *SQLiteIndex) Rebuild(ctx context.Context, source RecordSource) error
- func (x *SQLiteIndex) Release() error
- func (x *SQLiteIndex) StateDigest(ctx context.Context) (string, error)
- type SentRequest
- type SharePolicy
- type Signer
- type SortedMerkleIndex
- func (m *SortedMerkleIndex) Add(key, recordID string) error
- func (m *SortedMerkleIndex) KeyOf(record Record) (string, bool)
- func (m *SortedMerkleIndex) Name() string
- func (m *SortedMerkleIndex) ProveMember(key, recordID string) (LeafProof, error)
- func (m *SortedMerkleIndex) ProveRange(lo, hi string) (KeyRangeProof, error)
- func (m *SortedMerkleIndex) Reset()
- func (m *SortedMerkleIndex) Root() IndexRoot
- type Store
- type StoredRecord
- type Subject
- type SubjectKind
- type Substrate
- type SubstrateEntry
- type SubstrateInfo
- type Tallies
- type TokenIndex
- type UnavailableError
- type VerifiedBundle
- type WithheldItem
- type WitnessRow
Constants ¶
const ( ExtensionPayloads = "evidencebook/payloads" ExtensionInclusion = "evidencebook/inclusion" ExtensionSubject = "evidencebook/subject" )
Bundle extension keys this package writes. Extensions are integrity-covered by the bundle digest and uninterpreted by the neutral bundle verifier.
const ( JoinExchangeID = "exchange_id" JoinRequestDigest = "request_digest" )
Join keys a pair can be correlated by, in preference order.
const ( RecordTypeClose = "close" RecordTypeDisclosure = "disclosure" RecordTypeLifecycle = "lifecycle" RecordTypeIndexRoot = "index_root" RecordTypeRequest = "evidence_request" RecordTypeRequestAnswered = "evidence_request_answered" RecordTypeResponse = "evidence_response" RecordTypeAbsence = "recorded_absence" RecordTypeAcknowledgement = "acknowledgement" RecordTypeRebuttal = "rebuttal" )
Record types this package writes itself. Callers may use any other token; record_type is open vocabulary.
const ( ReasonNotAuthorized = "not_authorized" ReasonNoSuchSubject = "no_such_subject" ReasonCoverageUnsatisfiable = "coverage_unsatisfiable" ReasonDerivationUnsupported = "derivation_unsupported" ReasonPolicyDeclined = "policy_declined" ReasonDeadlineUnmet = "deadline_unmet" ReasonRequestMalformed = "request_malformed" ReasonRetentionExpired = "retention_expired" )
Refusal reason tokens (the request draft's initial registry).
const ( ArtifactEvidenceBundle = "evidence-bundle/v2" ArtifactCheckpoints = "checkpoints/v1" )
Artifact kinds an artifact response may carry.
const ( RelationshipStranger = "stranger" RelationshipIdentified = "identified" RelationshipCounterparty = "counterparty" )
Relationship of a requester to this book, checkable from local records.
const ( OutcomeArtifact = "artifact" OutcomeRefusal = "refusal" OutcomeArtifactFailed = "artifact_failed_verification" )
Response outcomes as recorded by a requester.
const ArtifactResponseType = "evidence-artifact-response/v1"
ArtifactResponseType is the context member of an artifact response's signing body, so its signature cannot be read as any other statement.
const DefaultClosureDepth = 2
DefaultClosureDepth is the citation depth a bundle follows from its root.
const DefaultDeveloper = "evidencebook"
DefaultDeveloper is the AAC developer value a book writes when none is set.
const HeaderMember = "agent_input"
HeaderMember is the AAC disclosure member that carries a record header.
const HeaderVersion = 1
HeaderVersion is the version of the record header wire form this package writes and accepts.
const MinimumAbsenceWindow = time.Minute
MinimumAbsenceWindow is the shortest waiting window an absence may claim, measured from when the request was recorded.
const SubstrateKindCLL = "cll"
SubstrateKindCLL labels checkpoints and proofs produced by the CLL binding.
const SubstrateKindSCITTReceipt = "scitt-receipt"
SubstrateKindSCITTReceipt labels the receipt-holding binding.
Variables ¶
var ( // ErrInvalid reports input that violates the record model or a request shape. ErrInvalid = errors.New("evidencebook: invalid") // ErrNotFound reports a record, payload or checkpoint the book does not hold. ErrNotFound = errors.New("evidencebook: not found") // ErrCorrupt reports stored state that disagrees with the commitment substrate. ErrCorrupt = errors.New("evidencebook: corrupt") // ErrUnsupported reports a capability the configured substrate or index does // not provide, such as range proofs over a receipt-only substrate. ErrUnsupported = errors.New("evidencebook: unsupported") // ErrNotCovered reports a record that no checkpoint covers yet. ErrNotCovered = errors.New("evidencebook: not checkpoint-covered") ErrUnavailable = errors.New("evidencebook: payload unavailable") // ErrLegalHold reports a deletion blocked by a legal hold. ErrLegalHold = errors.New("evidencebook: legal hold") )
Functions ¶
func KeyID ¶
KeyID is the lowercase hex encoding of the signer's raw public key, the same key_id convention the record envelopes and checkpoints use.
func ReconcileHalves ¶
func ReconcileHalves(a, b HalfSet, compare Comparator) ([]PairResult, Tallies)
ReconcileHalves pairs two sides' halves and classifies every exchange seen on either side into exactly one of six states.
Correlation runs in two passes over all halves, so the result does not depend on input order: first exchange_id (preferring a counterpart whose request_digest also agrees), then request_digest for halves still unpaired. An agreeing exchange_id with disagreeing request digests is CONFLICTING and is never re-paired on the weaker key. twin_bracket_id is recorded when both halves carry the same value and is never a join key.
One half unavailable is not disagreement: an unpaired half is A_ONLY or B_ONLY when the other side's account is complete, INSUFFICIENT otherwise, and never CONFLICTING.
func SamePayloadCommitments ¶
SamePayloadCommitments is a Comparator for deterministic content: the two halves committed identical payload digests. Content produced by sampling needs a comparator over the disclosed content instead.
func VerifyKeyRange ¶
func VerifyKeyRange(root IndexRoot, lo, hi string, proof KeyRangeProof) ([]string, error)
VerifyKeyRange checks a range proof against a committed root and returns the record ids it proves are exactly the leaves with keys in [lo, hi].
func VerifyLeaf ¶
VerifyLeaf checks one leaf proof against a committed root.
Types ¶
type AbsenceStatement ¶
type AbsenceStatement struct {
RequestDigest string `json:"request_digest"`
Route string `json:"route,omitempty"`
WindowStart string `json:"window_start"`
WindowEnd string `json:"window_end"`
}
AbsenceStatement is the body of a recorded absence: the requester's own signed statement that no answer arrived in its window. It states nothing about the responder's intent.
type AnsweredStatement ¶
type AnsweredStatement struct {
RequestDigest string `json:"request_digest"`
SubjectKind SubjectKind `json:"subject_kind,omitempty"`
Outcome string `json:"outcome"`
Reason string `json:"reason,omitempty"`
RequesterRef string `json:"requester_ref,omitempty"`
Relationship string `json:"relationship"`
Anchor string `json:"anchor,omitempty"`
}
AnsweredStatement is the body of the record a responder seals for every inbound request, whatever the outcome.
type ArtifactResponse ¶
type ArtifactResponse struct {
RequestDigest string `json:"request_digest"`
Anchor string `json:"anchor"`
ArtifactKind string `json:"artifact_kind"`
Artifact json.RawMessage `json:"artifact"`
ArtifactDigest string `json:"artifact_digest"`
IssuedAt string `json:"issued_at"`
KeyID string `json:"key_id"`
Sig string `json:"sig"`
}
ArtifactResponse is the signed granting answer: the artifact, the anchor it verifies against, and a signature binding both to the request.
func (ArtifactResponse) SigningBody ¶
func (a ArtifactResponse) SigningBody() ([]byte, error)
SigningBody is the exact bytes an artifact response signature covers.
func (ArtifactResponse) Verify ¶
func (a ArtifactResponse) Verify() error
Verify checks the signature and that the artifact bytes hash to the signed digest.
type AuthenticatedIndex ¶
type AuthenticatedIndex interface {
Name() string
// KeyOf returns the key a record contributes, or false for none.
KeyOf(record Record) (string, bool)
Add(key, recordID string) error
Reset()
Root() IndexRoot
ProveMember(key, recordID string) (LeafProof, error)
// ProveRange proves exactly which records carry a key in [lo, hi]; with
// lo == hi it is a completeness proof for one key, and an empty result is
// a non-membership proof.
ProveRange(lo, hi string) (KeyRangeProof, error)
}
AuthenticatedIndex is a deterministic structure whose root the book commits as a record.
What a party that does not trust the book can check, and what it cannot: a membership proof shows a (key, record id) leaf is under the committed root, with no further trust. Non-membership, range and completeness proofs additionally rely on the committed tree being sorted and holding every record: a book that commits an unsorted or incomplete tree can prove a false absence or omit a match. Only a party holding the full leaf set (for example the book's full history) can audit that, by rebuilding the root. Those three claims are therefore statements by the book, checkable against its commitment but not against a dishonest book.
type Book ¶
type Book struct {
// contains filtered or unexported fields
}
Book is an evidence store: records, typed links, payload separation, three index classes and request/reconcile mechanics over an embedded commitment substrate. The substrate is never exposed; callers get records, bundles and answers, and the book composes every proof itself.
func Open ¶
Open validates cfg, reconciles the record store with the substrate, and rebuilds every index from the committed history.
func (*Book) Acknowledge ¶
Acknowledge records that this book has seen and holds a counterparty's Close, which is what makes that Close AGREED from the counterparty's side.
func (*Book) Append ¶
Append validates entry, commits its payload bytes by digest, seals the header into a record capsule, stores the record, appends its identity to the substrate, and updates every index — in that order. When the record is committed but a later step (indexing, an automatic checkpoint) fails, the committed record is returned together with the error: do not retry it.
func (*Book) Bundle ¶
Bundle resolves the root's citation closure, constructs the disclosure, asks the substrate for interval and membership evidence under one anchor, and returns a portable bundle. It then commits a disclosure record citing every record whose header or payload the bundle disclosed.
func (*Book) Checkpoint ¶
func (b *Book) Checkpoint(ctx context.Context) (Checkpoint, error)
Checkpoint commits any changed authenticated-index roots as records, then checkpoints the commitment history underlying this book.
func (*Book) Checkpoints ¶
func (b *Book) Checkpoints(ctx context.Context) ([]Checkpoint, error)
Checkpoints returns every checkpoint this book has issued, oldest first.
func (*Book) Close ¶
Close reconciles, then seals a Close record: a closes link to every own record the reconciliation placed, and the full state population in its statement. Its status is read later from the links other records make to it.
func (*Book) Discover ¶
Discover returns approximate candidates. See Candidates for what that result may and may not be used for.
func (*Book) IndexState ¶
IndexState is the operational index's current state digest.
func (*Book) Info ¶
func (b *Book) Info() (string, SubstrateInfo)
Info names the book and the substrate it states it uses.
func (*Book) ProveKeyRange ¶
ProveKeyRange proves exactly which records carry a key in [lo, hi] of the named authenticated index. It first commits the index's current root as a record and checkpoints, so the proof is always against a root the book has committed and a checkpoint covers — never a live root that has drifted from the last committed one. An empty result is a non-membership proof.
func (*Book) Query ¶
Query answers from the operational index. Its result is a local lookup, not a proof; use Bundle or Respond for anything a stranger must check.
func (*Book) Rebuild ¶
Rebuild re-derives the operational and discovery indexes from the committed history alone and returns the operational index's state digest.
func (*Book) Rebut ¶
func (b *Book) Rebut(ctx context.Context, peerCloseID, counterparty string, reason json.RawMessage) (Record, error)
Rebut records that this book disputes a counterparty's Close.
func (*Book) Reconcile ¶
func (b *Book) Reconcile(ctx context.Context, in ReconcileInput) (Reconciliation, error)
Reconcile compares this book's halves in its window with the halves a peer disclosed in a verified bundle.
func (*Book) RecordAbsence ¶
func (b *Book) RecordAbsence(ctx context.Context, requestRecordID string, windowEnd time.Time, route string) (Record, error)
RecordAbsence commits that no response arrived for the recorded request between its recording and windowEnd. The request, its deadline and the window start come from the committed request record. It refuses while the request is still pending (window not closed, or closing before the request's own deadline) and once any response has been recorded, so an outcome is never converted into another.
func (*Book) RecordResponse ¶
func (b *Book) RecordResponse(ctx context.Context, requestRecordID string, resp Response, keys ResponderKeys) (Record, error)
RecordResponse verifies and records what came back for the request recorded as requestRecordID. Both responder keys are required. A response that does not verify under the pinned signer key is refused and is not recorded: an unauthenticated message can neither become an outcome nor foreclose the real one. An artifact that is genuinely signed by the responder but fails verification (wrong subject, anchor, freshness, or proofs) is recorded as received-and-failed, never as a grant and never as an absence.
func (*Book) Request ¶
func (b *Book) Request(ctx context.Context, req EvidenceRequest, responder string) (SentRequest, error)
Request records that this book is asking responder for evidence and returns the canonical bytes to transmit. An empty nonce is filled with a fresh random one, and a nonce this book already used is refused. Recording happens before sending, so "I asked" is committed whatever comes back.
func (*Book) ResolvePayload ¶
ResolvePayload returns one payload of one record when its retention state allows it.
func (*Book) Respond ¶
func (b *Book) Respond(ctx context.Context, requestBytes []byte, opts RespondOptions) (Response, Record, error)
Respond answers one request received as requestBytes with a signed artifact or a signed refusal, and seals a record of the request and its outcome. The artifact depends only on (subject, coverage): nonce, route and the requester's identity never change it.
func (*Book) Retention ¶
Retention returns the current retention state of one payload of one record: the state the record committed, folded forward through every lifecycle record that cites that record for that payload, in log order. State belongs to the (record, payload) pair, so two records that commit identical bytes have independent retention.
func (*Book) SetRetention ¶
func (b *Book) SetRetention(ctx context.Context, recordID, digest string, state RetentionState, reason string) (Record, error)
SetRetention appends a lifecycle record moving one payload of recordID to state. DELETED is permanent and is blocked while a legal hold stands. The bytes are destroyed after the lifecycle record is committed, and only when no other record still holds the same bytes in a resolvable state. Asking for DELETED again on a deleted payload retries a failed byte deletion and returns the existing lifecycle record.
type Bundle ¶
type Bundle struct {
JSON []byte
Digest string
Anchor Checkpoint
Disclosure Record
}
Bundle is a portable, self-verifying Evidence Bundle v2 plus the disclosure record the book committed about it.
type BundleCheckpoint ¶
type BundleCheckpoint struct {
Root string `json:"root"`
MMRSize uint64 `json:"mmr_size"`
COSE string `json:"cose,omitempty"`
}
BundleCheckpoint is the checkpoint member of an Evidence Bundle. COSE is the base64url signed checkpoint statement, so a verifier authenticates the root rather than trusting the producer's copy of it.
type BundleClaims ¶
BundleClaims is the status of each Evidence Bundle verifier claim.
type BundleRequest ¶
type BundleRequest struct {
Root string
// Include adds records to the selected set beyond the root's closure.
Include []string
// ClosureDepth is how many link hops to follow from Root; zero selects
// DefaultClosureDepth.
ClosureDepth int
// Payloads is the disclosure claim for the selected set: all carries
// every payload of every selected record (refused if any is unavailable),
// selected carries those not withheld.
Payloads PayloadsMode
// WithholdPayloads carries headers only: every payload of the selected
// set is withheld with its digest.
WithholdPayloads bool
// Suppress names disclosure members left out of the overlay; suppressing
// HeaderMember leaves every header as withheld-with-digest.
Suppress []string
// Withhold names payload digests this disclosure does not carry.
Withhold []string
// At pins the coverage anchor; nil checkpoints the book now.
At *Checkpoint
Extensions map[string]json.RawMessage
}
BundleRequest selects what a bundle carries and how much it discloses.
type CLLSubstrate ¶
type CLLSubstrate struct {
// contains filtered or unexported fields
}
CLLSubstrate embeds a Checkpointed Local Log. It is the only place this module touches CLL; everything it returns is an evidencebook type.
func OpenCLL ¶
func OpenCLL(path, logID string, checkpointKey ed25519.PrivateKey) (*CLLSubstrate, error)
OpenCLL opens (initializing if absent) a CLL journal at path. checkpointKey signs the log's checkpoints in the CLL checkpoint wire format; it is the substrate's key, held by the substrate, and may differ from the book signer.
func (*CLLSubstrate) Checkpoint ¶
func (s *CLLSubstrate) Checkpoint(ctx context.Context, now time.Time) (Checkpoint, error)
func (*CLLSubstrate) Entries ¶
func (s *CLLSubstrate) Entries(ctx context.Context, afterSeq uint64, limit int) ([]SubstrateEntry, error)
func (*CLLSubstrate) Info ¶
func (s *CLLSubstrate) Info() SubstrateInfo
func (*CLLSubstrate) Latest ¶
func (s *CLLSubstrate) Latest(ctx context.Context) (Checkpoint, error)
func (*CLLSubstrate) ProveConsistency ¶
func (s *CLLSubstrate) ProveConsistency(ctx context.Context, older, newer Checkpoint) (ConsistencyEvidence, error)
func (*CLLSubstrate) ProveInclusion ¶
func (s *CLLSubstrate) ProveInclusion(ctx context.Context, seq uint64, at Checkpoint) (InclusionEvidence, error)
func (*CLLSubstrate) ProveInterval ¶
func (s *CLLSubstrate) ProveInterval(ctx context.Context, firstSeq uint64, at Checkpoint) (IntervalEvidence, error)
func (*CLLSubstrate) Release ¶
func (s *CLLSubstrate) Release() error
type Candidates ¶
type Candidates struct {
// contains filtered or unexported fields
}
Candidates is the only result type a DiscoveryIndex returns. It is a list of places to look, never a statement about what exists or what is true: no function in this package that produces a proof, a bundle, or an answer to a request accepts it (enforced by TestDiscoveryCandidatesNeverReachProofs). To act on a candidate, fetch it by id through the book.
func (Candidates) IDs ¶
func (c Candidates) IDs() []string
IDs returns candidate record ids, best match first.
func (Candidates) Query ¶
func (c Candidates) Query() string
Query returns the text that produced these candidates.
type Checkpoint ¶
type Checkpoint struct {
Kind string `json:"kind"`
LogID string `json:"log_id"`
ID string `json:"id"`
Entries uint64 `json:"entries"`
Root string `json:"root,omitempty"`
TreeSize uint64 `json:"tree_size,omitempty"`
KeyID string `json:"key_id,omitempty"`
IssuedAt time.Time `json:"issued_at"`
Statement []byte `json:"statement,omitempty"`
}
Checkpoint names one committed state. ID is independent of which party serves the checkpoint: for the CLL binding it is "<root-hex>:<mmr_size>".
func VerifyCheckpoints ¶
func VerifyCheckpoints(checkpoints []Checkpoint, consistency []ConsistencyEvidence, pinnedKey string) (Checkpoint, error)
VerifyCheckpoints checks a checkpoints/v1 history and returns its newest checkpoint as the signed statement states it. Every field is taken from the signed statement, never from the listed copy: each statement must verify, sign under pinnedKey, name the same log as the first, and match its listed fields exactly; sizes must strictly grow; and each consistency proof must show the next signed root append-only extends the previous one.
func (Checkpoint) Covers ¶
func (c Checkpoint) Covers(seq uint64) bool
Covers reports whether seq is committed under this checkpoint.
type CloseInput ¶
type CloseInput struct {
Reconcile ReconcileInput
Counterparty string
// Profile names the contract or profile version whose comparator and
// windows produced the reconciliation.
Profile string
Supersedes string
Reason string
}
CloseInput states what a Close binds. The book computes the reconciliation itself from Reconcile; a caller never supplies tallies. Supersedes names a prior Close this one adjusts; the prior Close is never rewritten.
type CloseStatement ¶
type CloseStatement struct {
Counterparty string `json:"counterparty"`
Profile string `json:"profile"`
Reconciliation Reconciliation `json:"reconciliation"`
Reason string `json:"reason,omitempty"`
}
CloseStatement is the body of a Close record.
type CloseStatus ¶
type CloseStatus string
CloseStatus is read from links, never from a field the Close sets.
const ( Agreed CloseStatus = "AGREED" Unilateral CloseStatus = "UNILATERAL" Contested CloseStatus = "CONTESTED" )
func StatusOfClose ¶
func StatusOfClose(closeID, counterpartyBookID, counterpartyCheckpointKey string, counterparty VerifiedBundle) (CloseStatus, error)
StatusOfClose derives a Close's status from the counterparty's own records: a rebuts link makes it CONTESTED, an acknowledges link AGREED, and neither leaves it UNILATERAL. Only records that verified, carry the counterparty's book id, and sit under a checkpoint signed by the key the caller pinned for that counterparty count; a bundle from anyone else says nothing about the Close.
type Comparator ¶
Comparator is the content test a declared profile supplies. It runs only on covered, trusted, correlated pairs and returns whether the contents agree.
type CompletenessCertificate ¶
type CompletenessCertificate struct {
LogID string `json:"log_id"`
RangeRoot string `json:"range_root"`
FirstSeq uint64 `json:"first_seq"`
LastSeq uint64 `json:"last_seq"`
BodyDigests []string `json:"body_digests"`
RangeProof RangeWitness `json:"range_proof"`
Memberships map[string]Membership `json:"memberships"`
}
CompletenessCertificate is the Evidence Bundle v2 per-record range claim.
type Config ¶
type Config struct {
BookID string
Operator string
Developer string
Store Store
Substrate Substrate
Payloads PayloadResolver
Signer Signer
Operational OperationalIndex
Authenticated []AuthenticatedIndex
Discovery DiscoveryIndex
// CheckpointEvery checkpoints after every N appends; zero checkpoints
// only when Checkpoint is called or an answer requires it.
CheckpointEvery uint64
Now func() time.Time
}
Config assembles a book. Store, Substrate, Payloads and Signer are required; every index defaults to the reference implementation.
type ConsistencyEvidence ¶
type ConsistencyEvidence struct {
Kind string `json:"kind"`
Proof json.RawMessage `json:"proof"`
}
ConsistencyEvidence proves newer append-only extends older.
type Correlation ¶
type Correlation struct {
ExchangeID string `json:"exchange_id,omitempty"`
RequestDigest string `json:"request_digest,omitempty"`
TwinBracketID string `json:"twin_bracket_id,omitempty"`
}
Correlation carries the exchange correlation keys used to pair two halves of one interaction across independently held books. Join order is ExchangeID, then RequestDigest; TwinBracketID is recorded, never joined on.
type Coverage ¶
type Coverage struct {
ExpectedPin *Pin `json:"expected_pin,omitempty"`
MinFreshness *Freshness `json:"min_freshness,omitempty"`
}
Coverage carries exactly one of ExpectedPin or MinFreshness.
type DisclosureStatement ¶
type DisclosureStatement struct {
BundleDigest string `json:"bundle_digest"`
Anchor string `json:"anchor"`
Payloads PayloadsMode `json:"payloads"`
SuppressedFields []string `json:"suppressed_fields"`
Withheld []WithheldItem `json:"withheld"`
}
DisclosureStatement is the body of a disclosure record (Evidence Layer §6.2).
type DiscoveryIndex ¶
type DiscoveryIndex interface {
Add(ctx context.Context, record Record) error
Search(ctx context.Context, query string, limit int) (Candidates, error)
Rebuild(ctx context.Context, source RecordSource) error
}
DiscoveryIndex finds candidate records by approximate match. It is always rebuildable and is never proof of completeness or of truth.
type Ed25519Signer ¶
type Ed25519Signer struct {
// contains filtered or unexported fields
}
Ed25519Signer is the reference in-process Signer.
func NewEd25519Signer ¶
func NewEd25519Signer(private ed25519.PrivateKey) (*Ed25519Signer, error)
NewEd25519Signer copies private so later mutation by the caller has no effect.
func (*Ed25519Signer) PublicKey ¶
func (s *Ed25519Signer) PublicKey() ed25519.PublicKey
PublicKey returns a copy of the verifying key.
type Entry ¶
type Entry struct {
RecordType string
EpistemicType EpistemicType
EventTimeClaim time.Time
Payloads [][]byte
Links []Link
SubjectRef string
PrincipalRef string
CounterpartyRef string
Correlation Correlation
Statement json.RawMessage
}
Entry is what a caller asks the book to record. Seq, CommittedAt, BookID and the record identity are assigned by the book.
type EpistemicType ¶
type EpistemicType string
EpistemicType states how a record's content came to be known. It is a closed set (Evidence Layer §4.1), assigned once at commit and never upgraded by anything attached to the record later.
const ( ObservedEvent EpistemicType = "observed_event" SystemOfRecordFact EpistemicType = "system_of_record_fact" ProducerClaim EpistemicType = "producer_claim" HumanReport EpistemicType = "human_report" SemanticJudgment EpistemicType = "semantic_judgment" DerivedMetric EpistemicType = "derived_metric" Adjudication EpistemicType = "adjudication" ObligationReference EpistemicType = "obligation_reference" )
func EpistemicTypes ¶
func EpistemicTypes() []EpistemicType
EpistemicTypes returns the closed value set in registry order.
func (EpistemicType) Valid ¶
func (t EpistemicType) Valid() bool
Valid reports whether t is one of the eight registered values.
type EvidenceRequest ¶
type EvidenceRequest struct {
Subject Subject `json:"subject"`
Coverage Coverage `json:"coverage"`
Derivation string `json:"derivation,omitempty"`
Deadline string `json:"deadline,omitempty"`
Nonce string `json:"nonce,omitempty"`
Route string `json:"route,omitempty"`
}
EvidenceRequest is the request map. Nonce and Route never influence the artifact served.
type ExchangeState ¶
type ExchangeState string
ExchangeState is the per-exchange reconciliation state.
const ( Matched ExchangeState = "MATCHED" AOnly ExchangeState = "A_ONLY" BOnly ExchangeState = "B_ONLY" Conflicting ExchangeState = "CONFLICTING" Insufficient ExchangeState = "INSUFFICIENT" Unresolved ExchangeState = "UNRESOLVED" )
type FileStore ¶
type FileStore struct {
// contains filtered or unexported fields
}
FileStore is an append-only JSONL record journal plus a checkpoint journal.
func OpenFileStore ¶
OpenFileStore opens (creating if absent) a store in dir. A torn final line left by a crash is truncated; a malformed complete line is corruption.
func (*FileStore) Checkpoints ¶
func (s *FileStore) Checkpoints(context.Context) ([]Checkpoint, error)
func (*FileStore) PutCheckpoint ¶
func (s *FileStore) PutCheckpoint(ctx context.Context, cp Checkpoint) error
type Filter ¶
type Filter struct {
RecordType string
SubjectRef string
CounterpartyRef string
ExchangeID string
RequestDigest string
LinkType LinkType
LinkTarget string
FromSeq uint64
ToSeq uint64
}
Filter selects records from the operational index. Zero-valued fields do not constrain the result.
type Half ¶
type Half struct {
RecordID string
Seq uint64
Correlation Correlation
PayloadCommitments []string
Covered bool
Trusted bool
}
Half is one side's record of one exchange as the reconciliation sees it. Covered means inside an authenticated checkpoint; Trusted means the record verifies and its header matches what it committed.
type HalfSet ¶
HalfSet is one side's account of a period. Complete means that account is checkpoint-covered, so a missing counterpart on this side is a provable absence rather than an unknown.
type Header ¶
type Header struct {
Version int `json:"v"`
BookID string `json:"book_id"`
Seq uint64 `json:"seq"`
RecordType string `json:"record_type"`
EpistemicType EpistemicType `json:"epistemic_type"`
CommittedAt string `json:"committed_at"`
EventTimeClaim string `json:"event_time_claim,omitempty"`
PayloadCommitments []string `json:"payload_commitments,omitempty"`
RetentionState RetentionState `json:"retention_state,omitempty"`
Links []Link `json:"links"`
SubjectRef string `json:"subject_ref,omitempty"`
PrincipalRef string `json:"principal_ref,omitempty"`
CounterpartyRef string `json:"counterparty_ref,omitempty"`
Correlation *Correlation `json:"correlation,omitempty"`
Statement json.RawMessage `json:"statement,omitempty"`
}
Header is the durable, privacy-minimized record header (Evidence Layer §4). Its canonical JSON is committed as the record capsule's agent_input_digest, so every field below is fixed at commit.
type InclusionEvidence ¶
type InclusionEvidence struct {
Kind string `json:"kind"`
Seq uint64 `json:"seq"`
Proof json.RawMessage `json:"proof"`
}
InclusionEvidence is a substrate-specific inclusion proof for one record, labelled by Kind so a verifier knows which algorithm checks it.
type IndexRoot ¶
type IndexRoot struct {
Index string `json:"index"`
Root string `json:"root"`
Size uint64 `json:"size"`
}
IndexRoot is what the book commits: the index name, its Merkle root, and its leaf count.
type IntervalEvidence ¶
type IntervalEvidence struct {
Certificate CompletenessCertificate `json:"completeness_certificate"`
Checkpoint BundleCheckpoint `json:"checkpoint"`
}
IntervalEvidence carries the completeness certificate and authenticated checkpoint in the Evidence Bundle v2 wire shape.
type KeyRangeAnswer ¶
type KeyRangeAnswer struct {
Root IndexRoot `json:"root"`
RootRecordID string `json:"root_record_id"`
Anchor Checkpoint `json:"anchor"`
Proof KeyRangeProof `json:"proof"`
}
KeyRangeAnswer is a key-range proof bound to what the book committed: the index root it verifies under, the index_root record that committed that root, and the checkpoint that covers that record. This package ships no standalone verifier for the binding (that the root equals the index_root record's statement and that the record is included under Anchor); a relying party checks the proof with VerifyKeyRange and the binding from a bundle carrying the index_root record. See AuthenticatedIndex for what the proof does not establish against a dishonest book.
type KeyRangeProof ¶
type KeyRangeProof struct {
Lo string `json:"lo"`
Hi string `json:"hi"`
First uint64 `json:"first"`
Matches []LeafProof `json:"matches"`
Left *LeafProof `json:"left,omitempty"`
Right *LeafProof `json:"right,omitempty"`
}
KeyRangeProof proves the complete set of leaves whose key lies in [Lo, Hi]: the matches are contiguous, and the neighbours on either side (when the range does not touch an edge of the tree) have keys outside the range.
type LeafProof ¶
type LeafProof struct {
Key string `json:"key"`
RecordID string `json:"record_id"`
Index uint64 `json:"index"`
Path []string `json:"path"`
}
LeafProof proves one (key, record id) leaf sits at Index under a root.
type LifecycleStatement ¶
type LifecycleStatement struct {
PayloadCommitment string `json:"payload_commitment"`
RetentionState RetentionState `json:"retention_state"`
Reason string `json:"reason,omitempty"`
}
LifecycleStatement is the body of a lifecycle record: a later, separately committed statement that one payload of the cited record changed retention state. The record that committed the payload is never rewritten.
type Link ¶
Link is a typed, directed reference to another record by its record id. A link is committed inside the carrying record and never mutates its target.
type LinkType ¶
type LinkType string
LinkType is the closed typed-link vocabulary (Evidence Layer §5).
type LogCoordinates ¶
type LogCoordinates struct {
LogID string `json:"log_id"`
Seq uint64 `json:"seq"`
LeafIndex uint64 `json:"leaf_index"`
}
LogCoordinates locates a record in the log.
type MMRInclusion ¶
type MMRInclusion struct {
V uint64 `json:"v"`
Kind string `json:"kind"`
Size uint64 `json:"size"`
LeafIndex uint64 `json:"leaf_index"`
Witness []string `json:"witness"`
PeaksLeft []string `json:"peaks_left"`
PeaksRight []string `json:"peaks_right"`
}
MMRInclusion is the portable MMR inclusion proof.
type Membership ¶
type Membership struct {
LogCoordinates LogCoordinates `json:"log_coordinates"`
InclusionProof MMRInclusion `json:"inclusion_proof"`
}
Membership binds one record to its log coordinates with an inclusion proof.
type OperationalIndex ¶
type OperationalIndex interface {
Add(ctx context.Context, record Record) error
// Find returns matching record ids in log order.
Find(ctx context.Context, filter Filter) ([]string, error)
// Rebuild discards all state and re-derives it from source.
Rebuild(ctx context.Context, source RecordSource) error
// StateDigest is a deterministic digest of the full index contents.
StateDigest(ctx context.Context) (string, error)
Release() error
}
OperationalIndex is fast local lookup with no independent trust value: its answers are only as trustworthy as the store producing them, and nothing that produces a proof reads from it.
type PairResult ¶
type PairResult struct {
State ExchangeState `json:"state"`
JoinKey string `json:"join_key,omitempty"`
A string `json:"a,omitempty"`
B string `json:"b,omitempty"`
TwinBracketID string `json:"twin_bracket_id,omitempty"`
}
PairResult classifies one exchange.
type PayloadDir ¶
type PayloadDir struct {
// contains filtered or unexported fields
}
PayloadDir is the reference PayloadResolver.
func OpenPayloadDir ¶
func OpenPayloadDir(dir string) (*PayloadDir, error)
OpenPayloadDir stores payload bytes as files named by semantic digest, with no storage transform, so the storage digest equals the semantic digest.
func (*PayloadDir) StorageDigest ¶
type PayloadResolver ¶
type PayloadResolver interface {
Put(ctx context.Context, semanticDigest string, data []byte) error
// Resolve returns the bytes, or ErrNotFound when they are not held.
// Retention policy is applied by the book, not the resolver.
Resolve(ctx context.Context, semanticDigest string) ([]byte, error)
StorageDigest(ctx context.Context, semanticDigest string) (string, error)
Delete(ctx context.Context, semanticDigest string) error
}
PayloadResolver turns a committed payload digest back into bytes. It is digest-addressed: the header commits digests, never storage locations. The semantic digest (what the header commits) and the storage digest (of the bytes as held at rest, after any host transform) are independent values.
type PayloadsMode ¶
type PayloadsMode string
PayloadsMode is the disclosure record's payloads claim.
const ( PayloadsAll PayloadsMode = "all" PayloadsSelected PayloadsMode = "selected" )
type PeerRecord ¶
type PeerRecord struct {
RecordID string
Seq uint64
Header *Header
HeaderVerified bool
CapsuleOK bool
}
PeerRecord is one record read from a verified bundle. Header is nil when the bundle withheld it; HeaderVerified is true only when the disclosed header hashes to the digest the record's capsule commits.
type RangeWitness ¶
type RangeWitness struct {
FromSeq uint64 `json:"from_seq"`
ToSeq uint64 `json:"to_seq"`
Size uint64 `json:"size"`
FromIndex uint64 `json:"from_index"`
ToIndex uint64 `json:"to_index"`
Witness []string `json:"witness"`
}
RangeWitness is the index-shaped range proof a completeness certificate carries.
type Receipt ¶
type Receipt struct {
ServiceID string `json:"service_id"`
TreeSize uint64 `json:"tree_size"`
LeafIndex uint64 `json:"leaf_index"`
Bytes []byte `json:"bytes"`
}
Receipt is an opaque transparency-service receipt (for example a COSE Receipt) with the tree coordinates it attests.
type ReconcileInput ¶
type ReconcileInput struct {
Peer VerifiedBundle
// RecordType restricts both sides to one record type; empty takes every
// record that carries correlation keys.
RecordType string
// FromSeq and ToSeq bound this book's own window; zero leaves an end open.
FromSeq, ToSeq uint64
// PeerFromSeq and PeerToSeq bound the peer's window the same way.
PeerFromSeq, PeerToSeq uint64
Compare Comparator
}
ReconcileInput names the peer's disclosed account and the content test. Each side's window is in that side's own log positions.
type Reconciliation ¶
type Reconciliation struct {
OwnHead string `json:"own_head"`
PeerHead string `json:"peer_head"`
PeerLog string `json:"peer_log"`
PeerComplete bool `json:"peer_complete"`
FromSeq uint64 `json:"from_seq"`
ToSeq uint64 `json:"to_seq"`
PeerFromSeq uint64 `json:"peer_from_seq"`
PeerToSeq uint64 `json:"peer_to_seq"`
Pairs []PairResult `json:"pairs"`
Tallies Tallies `json:"states"`
}
Reconciliation is the result of comparing this book (side A) with a peer's verified bundle (side B). It is computed from bundles alone.
type Record ¶
Record is one committed entry: its identity, position, and header. RecordID is the Capsule ID of the sealed record capsule and is the exact 32-byte value appended to the commitment substrate.
type RecordSource ¶
RecordSource yields every committed record in log order. Index rebuilds read only from a RecordSource, so an index can always be reproduced from the committed history alone.
type Refusal ¶
type Refusal struct {
RequestDigest string `json:"request_digest"`
Reason string `json:"reason"`
IssuedAt string `json:"issued_at"`
KeyID string `json:"key_id"`
Sig string `json:"sig"`
}
Refusal is a signed answer declining one request. The signature covers the canonical JSON of request_digest, reason and issued_at.
func (Refusal) SigningBody ¶
SigningBody is the exact bytes a refusal signature covers.
type Registrar ¶
Registrar registers a record identity with a SCITT transparency service and returns the service's receipt. The service, not the book, assigns the position the receipt proves.
type RequestStatement ¶
type RequestStatement struct {
Request json.RawMessage `json:"request"`
ResponderRef string `json:"responder_ref,omitempty"`
}
RequestStatement is the body of the record a requester seals before it sends a request. The responder is named here, not in counterparty_ref: asking a party does not make it a counterparty of this book.
type RespondOptions ¶
type RespondOptions struct {
RequesterID string
Policy SharePolicy
}
RespondOptions carries the requester's declared identity and the policy. RequesterID is whatever the transport supplied; this package does not authenticate it. The relationship gate built on it is scope reduction, not access control: a caller that can claim another party's identity gets that party's answers, so authenticate the requester at the transport when the difference matters.
type ResponderKeys ¶
type ResponderKeys struct {
Signer string
Checkpoint string
Witnesses []WitnessRow
}
ResponderKeys are the responder's keys as the requester obtained them, independently of any response: Signer signs refusals and artifact responses, Checkpoint signs the checkpoints an artifact is anchored to. Witnesses is the requester's own witness directory: every witness receipt an artifact carries must verify under it, against the artifact's anchor, or the artifact is recorded as failed. Without it, an artifact carrying any receipt is recorded as failed; one carrying none is unaffected.
type Response ¶
type Response struct {
Artifact *ArtifactResponse `json:"artifact,omitempty"`
Refusal *Refusal `json:"refusal,omitempty"`
}
Response is exactly one of the two answers a responder can send.
type ResponseStatement ¶
type ResponseStatement struct {
RequestDigest string `json:"request_digest"`
Outcome string `json:"outcome"`
Reason string `json:"reason,omitempty"`
KeyID string `json:"key_id"`
CheckpointKey string `json:"checkpoint_key_id"`
ArtifactKind string `json:"artifact_kind,omitempty"`
Artifact string `json:"artifact_digest,omitempty"`
Anchor string `json:"anchor,omitempty"`
Failure string `json:"failure,omitempty"`
}
ResponseStatement is the body of the record a requester seals on receipt. KeyID is always the pinned responder key the response verified under.
type RetentionState ¶
type RetentionState string
RetentionState names whether a record's payload can currently be resolved (Evidence Layer §6.1).
const ( Available RetentionState = "AVAILABLE" Partial RetentionState = "PARTIAL" Withheld RetentionState = "WITHHELD" Deleted RetentionState = "DELETED" LegalHold RetentionState = "LEGAL_HOLD" )
func (RetentionState) Valid ¶
func (s RetentionState) Valid() bool
Valid reports whether s is a registered retention state.
type SCITTReceiptSubstrate ¶
type SCITTReceiptSubstrate struct {
// contains filtered or unexported fields
}
SCITTReceiptSubstrate is a stub binding: it holds one receipt per record in memory and answers inclusion with that receipt. It keeps no log of its own, so interval and consistency proofs are ErrUnsupported and the book's bundles over it carry receipts instead of a completeness certificate. It exists so the "no particular substrate required" property is exercised in code, not asserted in prose; it is not durable.
func NewSCITTReceiptSubstrate ¶
func NewSCITTReceiptSubstrate(serviceID string, registrar Registrar) (*SCITTReceiptSubstrate, error)
NewSCITTReceiptSubstrate returns the receipt-holding substrate stub.
func (*SCITTReceiptSubstrate) Checkpoint ¶
func (s *SCITTReceiptSubstrate) Checkpoint(ctx context.Context, _ time.Time) (Checkpoint, error)
Checkpoint names the latest receipt's tree state. The identity comes from the transparency service's coordinates, not from anything the book computes.
func (*SCITTReceiptSubstrate) Entries ¶
func (s *SCITTReceiptSubstrate) Entries(_ context.Context, afterSeq uint64, limit int) ([]SubstrateEntry, error)
func (*SCITTReceiptSubstrate) Info ¶
func (s *SCITTReceiptSubstrate) Info() SubstrateInfo
func (*SCITTReceiptSubstrate) Latest ¶
func (s *SCITTReceiptSubstrate) Latest(context.Context) (Checkpoint, error)
func (*SCITTReceiptSubstrate) ProveConsistency ¶
func (s *SCITTReceiptSubstrate) ProveConsistency(context.Context, Checkpoint, Checkpoint) (ConsistencyEvidence, error)
func (*SCITTReceiptSubstrate) ProveInclusion ¶
func (s *SCITTReceiptSubstrate) ProveInclusion(_ context.Context, seq uint64, at Checkpoint) (InclusionEvidence, error)
func (*SCITTReceiptSubstrate) ProveInterval ¶
func (s *SCITTReceiptSubstrate) ProveInterval(context.Context, uint64, Checkpoint) (IntervalEvidence, error)
func (*SCITTReceiptSubstrate) Release ¶
func (s *SCITTReceiptSubstrate) Release() error
type SQLiteIndex ¶
type SQLiteIndex struct {
// contains filtered or unexported fields
}
SQLiteIndex is the reference OperationalIndex.
func OpenSQLiteIndex ¶
func OpenSQLiteIndex(path string) (*SQLiteIndex, error)
OpenSQLiteIndex opens the reference operational index. An empty path keeps it in memory, which is safe because it is always rebuildable.
func (*SQLiteIndex) Rebuild ¶
func (x *SQLiteIndex) Rebuild(ctx context.Context, source RecordSource) error
func (*SQLiteIndex) Release ¶
func (x *SQLiteIndex) Release() error
func (*SQLiteIndex) StateDigest ¶
func (x *SQLiteIndex) StateDigest(ctx context.Context) (string, error)
type SentRequest ¶
SentRequest is a request as transmitted: its canonical bytes, their digest, and the id of the record of having asked. RecordResponse and RecordAbsence re-derive everything else from that committed record.
type SharePolicy ¶
type SharePolicy struct {
}
SharePolicy is the four-switch sharing policy, carried unchanged from the mesh plugin's share.* object. Every default keys on relationship.
func DefaultSharePolicy ¶
func DefaultSharePolicy() SharePolicy
DefaultSharePolicy returns the documented defaults.
func (SharePolicy) Validate ¶
func (p SharePolicy) Validate() error
Validate rejects any switch outside its enumerated values.
type Signer ¶
type Signer interface {
PublicKey() ed25519.PublicKey
Sign(ctx context.Context, message []byte) ([]byte, error)
}
Signer is the book's signing seam. A host plugs in any key custodian (a local key, an HSM, a KMS) that produces raw Ed25519 signatures; the book never holds or requires a particular key. Sign receives the exact bytes to be signed (for COSE, the Sig_structure), never a pre-hash.
type SortedMerkleIndex ¶
type SortedMerkleIndex struct {
// contains filtered or unexported fields
}
SortedMerkleIndex is the reference AuthenticatedIndex: a sorted list of (key, record id) leaves under an RFC 9162 Merkle tree.
func NewRecordIDIndex ¶
func NewRecordIDIndex() *SortedMerkleIndex
NewRecordIDIndex indexes every record under its own record id, so the book can prove that a record id is, or is not, committed.
func NewSubjectIndex ¶
func NewSubjectIndex() *SortedMerkleIndex
NewSubjectIndex indexes records under subject_ref, so the book can prove the complete set of records it holds for one correlation subject.
func (*SortedMerkleIndex) Add ¶
func (m *SortedMerkleIndex) Add(key, recordID string) error
func (*SortedMerkleIndex) Name ¶
func (m *SortedMerkleIndex) Name() string
func (*SortedMerkleIndex) ProveMember ¶
func (m *SortedMerkleIndex) ProveMember(key, recordID string) (LeafProof, error)
func (*SortedMerkleIndex) ProveRange ¶
func (m *SortedMerkleIndex) ProveRange(lo, hi string) (KeyRangeProof, error)
func (*SortedMerkleIndex) Reset ¶
func (m *SortedMerkleIndex) Reset()
func (*SortedMerkleIndex) Root ¶
func (m *SortedMerkleIndex) Root() IndexRoot
type Store ¶
type Store interface {
PutRecord(ctx context.Context, record StoredRecord) error
GetRecord(ctx context.Context, recordID string) (StoredRecord, error)
Records(ctx context.Context) ([]StoredRecord, error)
PutCheckpoint(ctx context.Context, cp Checkpoint) error
Checkpoints(ctx context.Context) ([]Checkpoint, error)
Release() error
}
Store holds complete records and the checkpoints the book has observed. A record is stored before its identity is appended to the substrate, so the substrate never commits an identity the book cannot produce.
type StoredRecord ¶
type StoredRecord struct {
Seq uint64 `json:"seq"`
RecordID string `json:"record_id"`
Header json.RawMessage `json:"header"`
Capsule json.RawMessage `json:"capsule"`
Envelope []byte `json:"envelope"`
}
StoredRecord is the durable form of one record: the canonical header bytes, the sealed signature-free capsule, and its Producer Envelope.
type Subject ¶
type Subject struct {
Kind SubjectKind `json:"kind"`
Digest string `json:"digest,omitempty"`
First uint64 `json:"first,omitempty"`
Last uint64 `json:"last,omitempty"`
Value string `json:"value,omitempty"`
}
Subject names what is asked for. Digest serves record and exchange, First and Last serve range, Value serves correlation.
type SubjectKind ¶
type SubjectKind string
SubjectKind is one of the request draft's six subject forms.
const ( SubjectFullHistory SubjectKind = "full_history" SubjectCheckpoints SubjectKind = "checkpoints" SubjectRecord SubjectKind = "record" SubjectRange SubjectKind = "range" SubjectCorrelation SubjectKind = "correlation" SubjectExchange SubjectKind = "exchange" )
type Substrate ¶
type Substrate interface {
Info() SubstrateInfo
// Append assigns the next position to recordID. Appending an identity
// that is already present returns its original position.
Append(ctx context.Context, recordID string, at time.Time) (uint64, error)
Size(ctx context.Context) (uint64, error)
Entries(ctx context.Context, afterSeq uint64, limit int) ([]SubstrateEntry, error)
// Checkpoint commits a checkpoint over everything appended so far.
Checkpoint(ctx context.Context, now time.Time) (Checkpoint, error)
// Latest returns the newest checkpoint, or ErrNotFound when none exists.
Latest(ctx context.Context) (Checkpoint, error)
ProveInclusion(ctx context.Context, seq uint64, at Checkpoint) (InclusionEvidence, error)
// ProveInterval returns the per-record range and membership evidence for
// positions [firstSeq, at.Entries]. Substrates that do not maintain an
// ordered log return ErrUnsupported.
ProveInterval(ctx context.Context, firstSeq uint64, at Checkpoint) (IntervalEvidence, error)
ProveConsistency(ctx context.Context, older, newer Checkpoint) (ConsistencyEvidence, error)
Release() error
}
Substrate is the commitment-substrate interface (Evidence Layer §8). A book needs exactly four properties from it: append order, inclusion, consistency, and checkpoint identity. A Checkpointed Local Log is the reference binding (OpenCLL); a SCITT receipt-holding binding (NewSCITTReceiptSubstrate) shows the book does not require one.
Record identities cross this interface as lowercase hex strings and every proof leaves it as an evidencebook type, so no substrate implementation type is ever visible to a book caller.
type SubstrateEntry ¶
SubstrateEntry is one committed position.
type SubstrateInfo ¶
SubstrateInfo names the substrate a book states it uses.
type Tallies ¶
type Tallies struct {
Matched int `json:"MATCHED"`
AOnly int `json:"A_ONLY"`
BOnly int `json:"B_ONLY"`
Conflicting int `json:"CONFLICTING"`
Insufficient int `json:"INSUFFICIENT"`
Unresolved int `json:"UNRESOLVED"`
}
Tallies counts exchanges per state.
type TokenIndex ¶
type TokenIndex struct {
// contains filtered or unexported fields
}
TokenIndex is the reference DiscoveryIndex.
func NewTokenIndex ¶
func NewTokenIndex() *TokenIndex
NewTokenIndex is a small reference DiscoveryIndex that matches word tokens in record_type, subject_ref and statement text.
func (*TokenIndex) Rebuild ¶
func (x *TokenIndex) Rebuild(ctx context.Context, source RecordSource) error
func (*TokenIndex) Search ¶
func (x *TokenIndex) Search(_ context.Context, query string, limit int) (Candidates, error)
type UnavailableError ¶
type UnavailableError struct {
}
UnavailableError reports why a payload yields no bytes. WITHHELD and DELETED both yield none; only DELETED is permanent, so callers read State.
func (*UnavailableError) Error ¶
func (e *UnavailableError) Error() string
func (*UnavailableError) Unwrap ¶
func (e *UnavailableError) Unwrap() error
type VerifiedBundle ¶
type VerifiedBundle struct {
Digest string
LogID string
Anchor BundleCheckpoint
AnchorAuthenticated bool
AnchorKeyID string
// AnchorStatement is the anchor's signed checkpoint statement, when
// AnchorAuthenticated.
AnchorStatement []byte
// Witnesses are the witness receipts the bundle carries
// (checkpoint.witnesses), as given. Nothing here verifies them: a
// requester checks them against the anchor under its own witness
// directory (RecordResponse does, through ResponderKeys.Witnesses).
Witnesses []json.RawMessage
IntervalFirst uint64
IntervalLast uint64
Records []PeerRecord
Payloads map[string][]byte
// Extensions are integrity-covered by the bundle digest but are the
// producer's statements; nothing in them is independently verified.
Extensions map[string]json.RawMessage
Findings []string
// Claims is each of the three verifier claims' status ("pass",
// "withheld", "unverified", ...). VerifyBundle refuses only "fail";
// FullyVerified reports whether everything passed.
Claims BundleClaims
}
VerifiedBundle is what a relying party learns from a bundle after the neutral Evidence Bundle verifier has checked it. AnchorAuthenticated means the checkpoint statement verifies under the key it names (AnchorKeyID); whether that key and log belong to the party the relying party expects is the relying party's check, against a key it obtained independently.
func VerifyBundle ¶
func VerifyBundle(data []byte) (VerifiedBundle, error)
VerifyBundle checks a bundle with the neutral AAC Evidence Bundle verifier and then reads the evidence-layer content out of what verified. It never trusts the producer's own verification member.
Everything is read from the one decoded tree the verifier checked, by exact key, so the verifier and this reader can never see different members: a second copy of a member under a case-variant key ("Disclosures", "CHECKPOINT") is refused outright, and a member present only under a case-variant key is simply absent, exactly as the verifier sees it.
func (VerifiedBundle) Covers ¶
func (v VerifiedBundle) Covers(seq uint64) bool
Covers reports whether the bundle proves seq is inside its authenticated interval.
func (VerifiedBundle) FullyVerified ¶
func (v VerifiedBundle) FullyVerified() error
FullyVerified returns nil only when all three claims passed and every record's capsule verified. VerifyBundle accepts a bundle whose claims are "withheld" or "unverified" (nothing in it is false); a caller that treats the bundle as proof of what it answers must also require this.
type WithheldItem ¶
type WithheldItem struct {
RecordID string `json:"record_id"`
Member string `json:"member,omitempty"`
PayloadCommitment string `json:"payload_commitment,omitempty"`
Digest string `json:"digest"`
RetentionState RetentionState `json:"retention_state,omitempty"`
}
WithheldItem names material committed but not carried, always with its digest.
type WitnessRow ¶ added in v0.1.1
type WitnessRow struct {
Name string `json:"name"`
Endpoint string `json:"endpoint"`
Binding string `json:"binding"`
KeyIDs []string `json:"key_ids"`
PublicKeys []string `json:"public_keys"`
}
WitnessRow is one row of a witness directory, in capsule-emit's witnesses.json format: the witness's endpoint, its binding (cll when absent) and its keys. A key id is a raw Ed25519 key in hex, or the SHA-256 of a DER key listed in public_keys. Other row fields are read past.
func ParseWitnessDirectory ¶ added in v0.1.1
func ParseWitnessDirectory(raw []byte) ([]WitnessRow, error)
ParseWitnessDirectory reads a witness directory: {"witnesses": [rows]} or a bare array of rows.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
capsulectl
module
|
|
|
report
module
|
|
|
test
|
|
|
interop/bundle
command
Command bundle writes an Evidence Bundle and a signed refusal produced by a fresh book, for verification by other implementations.
|
Command bundle writes an Evidence Bundle and a signed refusal produced by a fresh book, for verification by other implementations. |
|
interop/verify
command
Command verify checks a bundle produced by another implementation with evidencebook.VerifyBundle, and requires it to be fully verified: all three claims pass, the checkpoint is authenticated, and every record's capsule verifies.
|
Command verify checks a bundle produced by another implementation with evidencebook.VerifyBundle, and requires it to be fully verified: all three claims pass, the checkpoint is authenticated, and every record's capsule verifies. |