evidence

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Jul 29, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package evidence verifies provider current-evidence claims against caller-owned immutable target bytes. It intentionally has no source-evidence, publication, storage, repair, provider, filesystem, or Git dependencies.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CurrentClaim 

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

CurrentClaim is an immutable, canonical current-evidence claim. Its target identity comes from the application, never from a provider verification assertion.

func NewCurrentClaim 

func NewCurrentClaim(input CurrentClaimInput) (CurrentClaim, error)

NewCurrentClaim validates and canonicalizes one current-evidence claim. TargetSHA256 accepts either lower-case hexadecimal or sha256:<hex> and is stored as sha256:<hex>. Path is converted to ports.SafeRelativePath only after UTF-8 NFC and logical-target-path checks succeed.

func (CurrentClaim) ExcerptSHA256 

func (claim CurrentClaim) ExcerptSHA256(excerpt []byte) (string, error)

ExcerptSHA256 computes the canonical source/current excerpt identity for exact bytes under this claim. It does not assert that the bytes were read from an immutable target; callers must retain a verifier-owned receipt for that authority.

func (CurrentClaim) LineEnd 

func (claim CurrentClaim) LineEnd() int

LineEnd returns the one-based inclusive final line.

func (CurrentClaim) LineStart 

func (claim CurrentClaim) LineStart() int

LineStart returns the one-based inclusive first line.

func (CurrentClaim) Path 

func (claim CurrentClaim) Path() ports.SafeRelativePath

Path returns the canonical relative logical target path.

func (CurrentClaim) Quote 

func (claim CurrentClaim) Quote() string

Quote returns the exact UTF-8 quote text. It does not trim or normalize it.

func (CurrentClaim) QuoteBytes 

func (claim CurrentClaim) QuoteBytes() []byte

QuoteBytes returns a defensive copy of the exact quote bytes.

func (CurrentClaim) Side 

func (claim CurrentClaim) Side() Side

Side returns the claimed immutable target side.

func (CurrentClaim) TargetSHA256 

func (claim CurrentClaim) TargetSHA256() string

TargetSHA256 returns the canonical sha256:<lowercase-hex> target identity.

type CurrentClaimInput 

type CurrentClaimInput struct {
	TargetSHA256 string
	Side         Side
	Path         string
	LineStart    int
	LineEnd      int
	Quote        string
}

CurrentClaimInput contains only a provider's untrusted location-and-quote claim plus a target SHA-256 supplied by trusted application code. There is deliberately no provider-supplied verification, excerpt digest, or source reference field.

type CurrentReceipt 

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

CurrentReceipt is an immutable system-owned result. Claim preserves the canonical input identity. ExcerptSHA256 is populated only after immutable bytes selected a valid line range; Excerpt exposes bytes only when verified.

func (CurrentReceipt) Claim 

func (receipt CurrentReceipt) Claim() CurrentClaim

Claim returns the canonical current claim identity that was verified.

func (CurrentReceipt) Excerpt 

func (receipt CurrentReceipt) Excerpt() []byte

Excerpt returns a defensive copy of the verified excerpt. It returns nil for stale, invalid, and unverifiable receipts even if a range was selected.

func (CurrentReceipt) ExcerptSHA256 

func (receipt CurrentReceipt) ExcerptSHA256() string

ExcerptSHA256 returns the canonical excerpt digest only when immutable bytes selected a valid range. A quote mismatch has a digest but never exposes its selected bytes.

func (CurrentReceipt) ReasonCode 

func (receipt CurrentReceipt) ReasonCode() ReasonCode

ReasonCode returns the system-computed safe diagnostic code.

func (CurrentReceipt) Status 

func (receipt CurrentReceipt) Status() ReceiptStatus

Status returns the system-computed closed verification status.

type ImmutableTargetAvailability 

type ImmutableTargetAvailability string

ImmutableTargetAvailability is the typed result of looking up immutable target bytes. Readers must return Available only for the exact requested target identity. Stale and Unavailable never authorize byte verification. 

const (
	ImmutableTargetAvailable   ImmutableTargetAvailability = "available"
	ImmutableTargetStale       ImmutableTargetAvailability = "stale"
	ImmutableTargetUnavailable ImmutableTargetAvailability = "unavailable"
)

func (ImmutableTargetAvailability) Valid 

func (availability ImmutableTargetAvailability) Valid() bool

Valid reports whether availability is a closed immutable-reader fact.

type ImmutableTargetReader 

type ImmutableTargetReader interface {
	ReadImmutableTarget(context.Context, string, Side, ports.SafeRelativePath) (ImmutableTargetAvailability, []byte, error)
}

ImmutableTargetReader is the consumer-owned port for exact immutable file bytes. The returned bytes must be newly allocated and owned by the caller. It receives the canonical target SHA-256, side, and SafeRelativePath that define the requested immutable file. A reader reports stale or unavailable lookup facts through ImmutableTargetAvailability rather than inferring them from provider output.

type ReasonCode 

type ReasonCode string

ReasonCode is a safe, closed diagnostic classification. It never embeds provider bytes, filesystem paths, or reader error strings. 

const (
	ReasonVerified                  ReasonCode = "verified"
	ReasonStaleTarget               ReasonCode = "stale_target"
	ReasonInvalidClaim              ReasonCode = "invalid_claim"
	ReasonInvalidPath               ReasonCode = "invalid_path"
	ReasonInvalidLineRange          ReasonCode = "invalid_line_range"
	ReasonLineRangeOutOfBounds      ReasonCode = "line_range_out_of_bounds"
	ReasonQuoteMismatch             ReasonCode = "quote_mismatch"
	ReasonTargetUnavailable         ReasonCode = "target_unavailable"
	ReasonReaderFailure             ReasonCode = "reader_failure"
	ReasonInvalidReaderAvailability ReasonCode = "invalid_reader_availability"
	ReasonNilReader                 ReasonCode = "nil_reader"
	ReasonNilContext                ReasonCode = "nil_context"
	ReasonContextCanceled           ReasonCode = "context_canceled"
)

func (ReasonCode) Valid 

func (code ReasonCode) Valid() bool

Valid reports whether code is a closed safe diagnostic classification.

type ReceiptStatus 

type ReceiptStatus string

ReceiptStatus is the closed verification outcome computed only by this package. Providers cannot construct receipts or set this status. 

const (
	ReceiptVerified     ReceiptStatus = "verified"
	ReceiptStale        ReceiptStatus = "stale"
	ReceiptInvalid      ReceiptStatus = "invalid"
	ReceiptUnverifiable ReceiptStatus = "unverifiable"
)

func (ReceiptStatus) Valid 

func (status ReceiptStatus) Valid() bool

Valid reports whether status is a closed verification outcome.

type Side 

type Side string

Side identifies one captured side of a current review target. 

const (
	SideBase     Side = "base"
	SideHead     Side = "head"
	SideWorktree Side = "worktree"
	SideIndex    Side = "index"
)

func (Side) Valid 

func (side Side) Valid() bool

Valid reports whether side is one of the closed current-target sides.

type Verifier 

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

Verifier owns the consumer-side immutable target reader used for current evidence verification.

func NewVerifier 

func NewVerifier(reader ImmutableTargetReader) (*Verifier, error)

NewVerifier creates a current-evidence verifier. A nil or typed-nil reader is rejected before it can weaken verification.

func (*Verifier) VerifyCurrent 

func (verifier *Verifier) VerifyCurrent(ctx context.Context, claim CurrentClaim) (CurrentReceipt, error)

VerifyCurrent validates claim identity, obtains immutable target bytes, and computes the receipt. Invalid evidence outcomes are returned as receipts; context and reader operation failures also return an error so callers retain cancellation and operational control flow while remaining fail-closed.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.