dossier

Documentation

Overview

Package dossier defines the self-contained, offline-verifiable Investigation dossier format. Integrity and signature verification do not imply current authorization, freshness, or continuing policy validity.

Index

• Constants
• func CanonicalJSON(value any) ([]byte, error)
• func DigestValue(domain string, value any) (string, error)
• func ValidityStatement() string
• func VisibleUnitSetDigest(values []string) (string, error)
• type AuthorizationScope
• type Entry
  • func NewEntry(path, mediaType string, value any) (Entry, error)
• type EvidenceReference
• type Manifest
• type ObjectReference
• type Sealed
  • func Decode(content []byte) (*Sealed, error)
  • func Seal(manifest Manifest, entries []Entry, keyID string, ...) (*Sealed, error)
• type Signature
• type Validity
• type Verification
  • func Verify(sealed Sealed, options VerifyOptions) (*Verification, error)
• type VerifyOptions

Constants

const (
	FormatVersion  = "phebs-investigation-dossier-v1"
	HashAlgorithm  = "sha256"
	MaxSealedBytes = 64 << 20
)

Functions

func CanonicalJSON

func CanonicalJSON(value any) ([]byte, error)

func DigestValue

func DigestValue(domain string, value any) (string, error)

func ValidityStatement

func ValidityStatement() string

func VisibleUnitSetDigest

func VisibleUnitSetDigest(values []string) (string, error)

Types

type AuthorizationScope

type AuthorizationScope struct {
	Principal              string   `json:"principal"`
	VisibilityProjectionID string   `json:"visibility_projection_id"`
	VisibleUnitIDs         []string `json:"visible_unit_ids"`
	VisibleUnitSetDigest   string   `json:"visible_unit_set_digest"`
	RedactionScope         string   `json:"redaction_scope"`
	HandlingClassification string   `json:"handling_classification"`
}

type Entry

type Entry struct {
	Path      string          `json:"path"`
	MediaType string          `json:"media_type"`
	Content   json.RawMessage `json:"content"`
	Digest    string          `json:"digest"`
}

func NewEntry

func NewEntry(path, mediaType string, value any) (Entry, error)

type EvidenceReference

type EvidenceReference struct {
	FactID            string `json:"fact_id"`
	FindingDigest     string `json:"finding_digest"`
	FindingEntryPath  string `json:"finding_entry_path"`
	Mode              string `json:"mode"`
	MaterialDigest    string `json:"material_digest"`
	AuthorizedLocator string `json:"authorized_locator,omitempty"`
	EntryPath         string `json:"entry_path,omitempty"`
}

type Manifest

type Manifest struct {
	FormatVersion      string              `json:"format_version"`
	DossierID          string              `json:"dossier_id"`
	Question           string              `json:"question"`
	Investigation      ObjectReference     `json:"investigation"`
	Revision           ObjectReference     `json:"revision"`
	PrimaryArtifact    ObjectReference     `json:"primary_artifact"`
	ConsumerSnapshot   ObjectReference     `json:"consumer_snapshot"`
	ChangeBrief        *ObjectReference    `json:"change_brief,omitempty"`
	Baseline           *ObjectReference    `json:"baseline,omitempty"`
	Decision           *ObjectReference    `json:"decision,omitempty"`
	SnapshotManifests  []string            `json:"snapshot_manifests"`
	InputManifests     []string            `json:"input_manifests"`
	PackCardIdentities []string            `json:"pack_card_identities"`
	Evidence           []EvidenceReference `json:"evidence"`
	Authorization      AuthorizationScope  `json:"authorization"`
	Validity           Validity            `json:"validity"`
	IssuedAt           string              `json:"issued_at"`
	PredecessorID      string              `json:"predecessor_id,omitempty"`
	VerificationKeyID  string              `json:"verification_key_id"`
}

type ObjectReference

type ObjectReference struct {
	Kind          string `json:"kind"`
	ID            string `json:"id"`
	ContentDigest string `json:"content_digest"`
	EntryPath     string `json:"entry_path"`
}

type Sealed

type Sealed struct {
	FormatVersion  string    `json:"format_version"`
	HashAlgorithm  string    `json:"hash_algorithm"`
	DossierID      string    `json:"dossier_id"`
	Manifest       Manifest  `json:"manifest"`
	ManifestDigest string    `json:"manifest_digest"`
	Entries        []Entry   `json:"entries"`
	RootDigest     string    `json:"root_digest"`
	Signature      Signature `json:"signature"`
}

func Decode

func Decode(content []byte) (*Sealed, error)

func Seal

func Seal(
	manifest Manifest,
	entries []Entry,
	keyID string,
	privateKey ed25519.PrivateKey,
) (*Sealed, error)

type Signature

type Signature struct {
	Algorithm string `json:"algorithm"`
	KeyID     string `json:"key_id"`
	PublicKey string `json:"public_key"`
	Value     string `json:"value"`
}

type Validity

type Validity struct {
	EligibilityResult string   `json:"eligibility_result"`
	SupportedClaims   []string `json:"supported_claims"`
	Blockers          []string `json:"blockers"`
	FreshnessState    string   `json:"freshness_state"`
	ValidationState   string   `json:"validation_state"`
	ReviewDueRule     string   `json:"review_due_rule"`
	ExpiresAt         string   `json:"expires_at,omitempty"`
	Statement         string   `json:"statement"`
}

type Verification

type Verification struct {
	DossierID       string
	RootDigest      string
	KeyID           string
	PublicKeySHA256 string
	EntryCount      int
}

func Verify

func Verify(sealed Sealed, options VerifyOptions) (*Verification, error)

type VerifyOptions

type VerifyOptions struct {
	TrustedKeyID  string
	TrustedPublic ed25519.PublicKey
}