verify

package
v0.7.1 Latest Latest
Warning

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

 Go to latest Published: Apr 23, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package verify runs the end-to-end cryptographic verification pipeline against a parsed proof bundle: signing-key lookup against the public keyring, Ed25519 signature check, Merkle-inclusion proof, block hash chain, and optional public-blockchain commitments (Stellar, Bitcoin). Callers receive a Report summarizing every check.

Index

Constants

View Source 
const (
	CatDataIntegrity = "data_integrity"
	CatCryptographic = "cryptographic"
	CatStructural    = "structural"
	CatTiming        = "timing"
	CatBlockchain    = "blockchain"
)

Category constants for user-friendly failure grouping.

Variables

View Source 
var CategoryOrder = map[string]int{
	CatDataIntegrity: 0,
	CatCryptographic: 1,
	CatStructural:    2,
	CatTiming:        3,
	CatBlockchain:    4,
}

CategoryOrder defines the display order for categories (most critical first).

Functions

func HexToBase64 

func HexToBase64(h string) string

HexToBase64 converts a hex string to standard base64 encoding.

func Present 

func Present(r *Report)

Present renders a Report to stdout with lipgloss styling.

Types

type BlockchainCommitment 

type BlockchainCommitment struct {
	Network             string `json:"network"`
	Ledger              int    `json:"ledger,omitempty"`
	BlockHeight         int    `json:"block_height,omitempty"`
	Timestamp           string `json:"timestamp,omitempty"`
	TxHash              string `json:"tx_hash"`
	CommittedHashHex    string `json:"committed_hash_hex"`
	CommittedHashBase64 string `json:"committed_hash_base64"`
	ExternallyVerified  bool   `json:"externally_verified"`
}

BlockchainCommitment holds data for a Stellar or Bitcoin commitment.

type Claims 

type Claims struct {
	Hash            string          `json:"hash"`
	HashType        string          `json:"hash_type"`
	Name            string          `json:"name"`
	Description     string          `json:"description,omitempty"`
	Timestamp       string          `json:"timestamp,omitempty"`
	URL             string          `json:"url,omitempty"`
	Location        *LatLong        `json:"location,omitempty"`
	HasMetadata     bool            `json:"-"`
	RawMetadata     json.RawMessage `json:"-"`
	TimestampStatus TimestampStatus `json:"-"`
	TimestampNote   string          `json:"-"`
}

Claims holds the parsed user claims for display in the report.

type CommitmentInfo 

type CommitmentInfo struct {
	Method        string `json:"method"`               // "stellar" or "bitcoin"
	Network       string `json:"network"`              // "testnet", "public", "mainnet", "regtest"
	Ledger        int    `json:"ledger"`               // Stellar ledger (0 if bitcoin)
	Height        int    `json:"height"`               // Bitcoin block height (0 if stellar)
	TxHash        string `json:"tx_hash"`              // Transaction hash (full, for explorer lookup)
	CommittedHash string `json:"committed_hash"`       // The value committed on-chain (memo_hash or op_return)
	BlockHash     string `json:"block_hash,omitempty"` // Bitcoin block header hash (for explorer lookup)
	Timestamp     string `json:"timestamp"`            // Public blockchain timestamp (ISO 8601)
	Skipped       bool   `json:"skipped"`              // true if external verification skipped
}

CommitmentInfo holds summary data about a commitment for display.

type EntropySubject 

type EntropySubject struct {
	RawSource  string // lowercase identifier emitted by ptype.Name (e.g. "entropy_nist")
	Source     string // humanized: "NIST Beacon"
	CapturedAt string // from entropy data timestamp (source-specific)

	// NIST Beacon fields
	PulseIndex  int    // pulse index number
	ChainIndex  int    // chain index
	Version     string // beacon version
	OutputValue string // pulse output value (hex)

	// Bitcoin Block fields
	BlockHash   string // block hash
	BlockHeight int    // block height
	BlockTime   int64  // block time (unix epoch)

	// Stellar Ledger fields
	LedgerHash     string // ledger hash
	LedgerSequence int    // ledger sequence number
	LedgerClosedAt string // ledger close timestamp
}

EntropySubject holds parsed entropy data for display (internal use by presenter). Fields are populated based on the entropy source type.

type ExternalCommit 

type ExternalCommit = proof.ExternalCommit

ExternalCommit is a type alias for convenience

type HashComparison 

type HashComparison struct {
	Provided string `json:"provided"`
	Found    string `json:"found"`
	Matched  bool   `json:"matched"`
}

HashComparison shows the result of --hash verification.

type JSONCommitments 

type JSONCommitments struct {
	Truestamp *TruestampCommitment  `json:"truestamp,omitempty"`
	Stellar   *BlockchainCommitment `json:"stellar,omitempty"`
	Bitcoin   *BlockchainCommitment `json:"bitcoin,omitempty"`
}

JSONCommitments holds structured commitment data keyed by blockchain.

type JSONIssue 

type JSONIssue struct {
	Severity string `json:"severity"` // "error", "warning"
	Category string `json:"category"`
	Message  string `json:"message"`
	Detail   string `json:"detail,omitempty"`
}

JSONIssue represents a non-passing verification check.

type JSONOutput 

type JSONOutput struct {
	Result         string           `json:"result"`
	SubjectType    string           `json:"subject_type"`
	SubjectID      string           `json:"subject_id"`
	Subject        any              `json:"subject"`
	HashComparison *HashComparison  `json:"hash_comparison,omitempty"`
	Timeline       *JSONTimeline    `json:"timeline,omitempty"`
	Commitments    *JSONCommitments `json:"commitments,omitempty"`
	Issues         []JSONIssue      `json:"issues,omitempty"`
	Summary        JSONSummary      `json:"summary"`
}

JSONOutput is the structured output for --json mode. It mirrors the visual terminal output sections.

func BuildJSONOutput 

func BuildJSONOutput(r *Report) *JSONOutput

BuildJSONOutput creates a presentation DTO from the internal Report.

type JSONSummary 

type JSONSummary struct {
	Passed   int `json:"passed"`
	Failed   int `json:"failed"`
	Warnings int `json:"warnings"`
	Skipped  int `json:"skipped"`
	Total    int `json:"total"`
}

JSONSummary holds check counts.

type JSONTimeline 

type JSONTimeline struct {
	ClaimedAt   string `json:"claimed_at,omitempty"`
	SubmittedAt string `json:"submitted_at,omitempty"`
	CapturedAt  string `json:"captured_at,omitempty"`
	CommittedAt string `json:"committed_at,omitempty"`
}

JSONTimeline holds the verified temporal bracket.

type LatLong 

type LatLong struct {
	Latitude  float64 `json:"latitude"`
	Longitude float64 `json:"longitude"`
}

LatLong holds geographic coordinates.

type Options 

type Options struct {
	KeyringURL     string
	APIURL         string // optional; populates Report.APIURL so the presenter can emit subject-detail + verify web links
	SkipExternal   bool
	SkipSignatures bool
	ExpectedHash   string // hex hash to compare against claims.hash

	// ExpectedSubjectType, when non-empty, asserts that the parsed
	// bundle's subject type name (ptype.Name) matches. A mismatch
	// surfaces as a StatusFail step in the "Subject Type" group —
	// crypto steps still run, the report still renders, and the
	// mismatch appears in the Issues section. Mirrors --type in the
	// download command so users can guard against verifying the wrong
	// file. Must be one of: item, entropy_nist, entropy_stellar,
	// entropy_bitcoin, block, beacon.
	ExpectedSubjectType string
}

Options holds CLI flags for the verifier.

type RemoteOptions 

type RemoteOptions struct {
	APIURL       string
	APIKey       string
	Team         string // team ID, sent as tenant header
	ExpectedHash string // hex hash to compare against claims.hash

	// ExpectedSubjectType, when non-empty, is sent to the server as
	// `data.type` on /proof/verify. The server then asserts the posted
	// bundle's `t` matches; a mismatch returns a structured 422 with
	// meta.code == "subject_type_mismatch" (see PROOF_FORMAT_IMPLEMENTERS_GUIDE
	// §12). Mirrors Options.ExpectedSubjectType for the local path.
	ExpectedSubjectType string
}

RemoteOptions holds configuration for remote verification.

type Report 

type Report struct {
	Filename        string
	FileSize        int64
	ProofVersion    int
	SubjectID       string
	SubjectType     string // ptype.Name(bundle.T): "item" | "entropy_nist" | "entropy_stellar" | "entropy_bitcoin" | "block" | "beacon"
	APIURL          string // the resolved API base URL, used by the presenter to emit subject-detail + verify web links
	GeneratedAt     string
	Source          string // raw entropy source identifier
	Temporal        TemporalSummary
	Claims          Claims
	Steps           []Step
	Remote          bool
	HashProvided    string // non-empty if --hash was used
	SkippedExternal bool
	ChainLength     int
	SigningKeyID    string
	CommitmentInfos []CommitmentInfo
	EntropySubject  EntropySubject
}

Report holds the complete verification results (internal use only). For JSON output, use BuildJSONOutput() to create a presentation DTO.

func Run 

func Run(filename string, opts Options) (*Report, error)

Run executes the full verification pipeline on a proof file.

func RunFromBytes 

func RunFromBytes(data []byte, displayName string, opts Options) (*Report, error)

RunFromBytes executes the full verification pipeline on raw proof bytes.

func RunRemote 

func RunRemote(filename string, opts RemoteOptions) (*Report, error)

RunRemote sends the proof to the Truestamp API for server-side verification and returns a Report compatible with the local verification output.

func (*Report) Counts 

func (r *Report) Counts() StepCounts

Counts computes all step status counts in a single pass.

func (*Report) FailedCount 

func (r *Report) FailedCount() int

FailedCount returns the number of failed steps.

func (*Report) HashMatched 

func (r *Report) HashMatched() bool

HashMatched returns true if a hash was provided and matched.

func (*Report) InfoCount 

func (r *Report) InfoCount() int

InfoCount returns the number of info steps.

func (*Report) PassCount 

func (r *Report) PassCount() int

PassCount returns the number of passed steps.

func (*Report) Passed 

func (r *Report) Passed() bool

Passed returns true if no steps have StatusFail.

func (*Report) ProofFailedCount 

func (r *Report) ProofFailedCount() int

ProofFailedCount returns the number of failures excluding hash comparison.

func (*Report) ProofPassed 

func (r *Report) ProofPassed() bool

ProofPassed returns true if all non-hash-comparison steps passed.

func (*Report) SkipCount 

func (r *Report) SkipCount() int

SkipCount returns the number of skipped steps.

func (*Report) WarnCount 

func (r *Report) WarnCount() int

WarnCount returns the number of warning steps.

type Status 

type Status int

Status represents the outcome of a verification step. 

const (
	StatusPass Status = iota
	StatusFail
	StatusSkip
	StatusWarn
	StatusInfo
)

func StatusFromString 

func StatusFromString(s string) (Status, error)

StatusFromString parses a status string. Returns an error for unknown values.

func (Status) MarshalJSON 

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

MarshalJSON encodes a Status as a JSON string.

func (*Status) UnmarshalJSON 

func (s *Status) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a JSON string into a Status. Unknown strings are mapped to StatusInfo for forward compatibility.

type Step 

type Step struct {
	Group    string `json:"group"`
	Category string `json:"category"`
	Status   Status `json:"status"`
	Message  string `json:"message"`
}

Step is a single verification result.

type StepCounts 

type StepCounts struct {
	Passed  int
	Failed  int
	Warned  int
	Info    int
	Skipped int
	Total   int
}

StepCounts holds all step status counts computed in a single pass.

type TemporalSummary 

type TemporalSummary struct {
	ClaimedAt   string `json:"claimed_at,omitempty"`
	SubmittedAt string `json:"submitted_at,omitempty"`
	CapturedAt  string `json:"captured_at,omitempty"`
	CommittedAt string `json:"committed_at,omitempty"`
}

TemporalSummary holds the verified temporal bracket timestamps.

type TimestampStatus 

type TimestampStatus int

TimestampStatus indicates the validation state of the claims timestamp. 

const (
	TimestampOK      TimestampStatus = iota // within expected range
	TimestampFuture                         // not before submission time
	TimestampStale                          // >7 days before submission
	TimestampMissing                        // no timestamp in claims
)

type TruestampCommitment 

type TruestampCommitment struct {
	ChainLength  int    `json:"chain_length"`
	SigningKeyID string `json:"signing_key_id"`
}

TruestampCommitment holds the internal chain summary.

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.