sourceevidence

sourceevidence

import "github.com/agentstation/starmap/pkg/sourceevidence"

Package sourceevidence captures replayable normalized observations and protects short-lived raw upstream evidence.

Index

• func Replay(record NormalizedRecord) (sources.Observation, error)
• type Archive
  • func NewArchive(root string, key []byte, policy Policy) (*Archive, error)
  • func (a *Archive) LoadNormalized(observationID string) (NormalizedRecord, error)
  • func (a *Archive) OpenRaw(observationID string, now time.Time) (RawRecord, error)
  • func (a *Archive) PurgeExpiredRaw(now time.Time) (int, error)
  • func (a *Archive) ReplayObservation(observationID string) (sources.Observation, error)
  • func (a *Archive) RetainNormalized(record NormalizedRecord) error
  • func (a *Archive) RetainRaw(observationID string, record RawRecord) error
• type MinimizedIssue
• type NormalizedRecord
  • func Capture(observation sources.Observation) (NormalizedRecord, error)
• type Policy
  • func DefaultPolicy() Policy
  • func (p Policy) Validate() error
• type RawAccess
• type RawRecord
  • func OpenRaw(key []byte, sealed SealedRawRecord, now time.Time) (RawRecord, error)
• type SealedRawRecord
  • func SealRaw(key []byte, record RawRecord, expiresAt time.Time) (SealedRawRecord, error)

func Replay

func Replay(record NormalizedRecord) (sources.Observation, error)

Replay verifies and reconstructs the exact normalized candidate catalog and provenance.

type Archive

Archive durably retains minimized normalized evidence and encrypted raw evidence. Directory and file modes enforce owner-only access in addition to raw encryption.

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

func NewArchive

func NewArchive(root string, key []byte, policy Policy) (*Archive, error)

NewArchive creates a passive evidence archive configuration.

func (*Archive) LoadNormalized

func (a *Archive) LoadNormalized(observationID string) (NormalizedRecord, error)

LoadNormalized reads and validates one retained normalized record.

func (*Archive) OpenRaw

func (a *Archive) OpenRaw(observationID string, now time.Time) (RawRecord, error)

OpenRaw loads, authenticates, decrypts, and expiry-checks raw evidence.

func (*Archive) PurgeExpiredRaw

func (a *Archive) PurgeExpiredRaw(now time.Time) (int, error)

PurgeExpiredRaw removes raw evidence whose bounded retention window has elapsed.

func (*Archive) ReplayObservation

func (a *Archive) ReplayObservation(observationID string) (sources.Observation, error)

ReplayObservation loads and deterministically replays a retained observation.

func (*Archive) RetainNormalized

func (a *Archive) RetainNormalized(record NormalizedRecord) error

RetainNormalized atomically stores one validated long-term replay record.

func (*Archive) RetainRaw

func (a *Archive) RetainRaw(observationID string, record RawRecord) error

RetainRaw encrypts and atomically stores one short-lived raw response body.

type MinimizedIssue

MinimizedIssue retains machine-readable degradation without diagnostic text.

type MinimizedIssue struct {
    Scope   catalogmeta.ObservationIssueScope `json:"scope"`
    Code    catalogmeta.ObservationIssueCode  `json:"code"`
    Subject string                            `json:"subject,omitempty"`
}

type NormalizedRecord

NormalizedRecord is the long-term, secret-minimized replay record for one observation.

type NormalizedRecord struct {
    Version          uint64                              `json:"version"`
    ObservationID    string                              `json:"observation_id"`
    SourceID         catalogmeta.SourceID                `json:"source"`
    ObservedAt       time.Time                           `json:"observed_at"`
    Revision         catalogmeta.ObservationRevision     `json:"revision"`
    Completeness     catalogmeta.ObservationCompleteness `json:"completeness"`
    Status           catalogmeta.ObservationStatus       `json:"status"`
    Records          catalogmeta.ObservationRecordCounts `json:"records"`
    Issues           []MinimizedIssue                    `json:"issues,omitempty"`
    EvidenceChecksum string                              `json:"evidence_checksum"`
    Payload          []byte                              `json:"payload"`
}

func Capture

func Capture(observation sources.Observation) (NormalizedRecord, error)

Capture creates a long-term normalized evidence record from an observation.

type Policy

Policy defines raw and normalized evidence retention requirements.

type Policy struct {
    RawRetention      time.Duration `json:"raw_retention"`
    RawAccess         RawAccess     `json:"raw_access"`
    RequireEncryption bool          `json:"require_encryption"`
    RetainHeaders     bool          `json:"retain_headers"`
    RetainQuery       bool          `json:"retain_query"`
}

func DefaultPolicy

func DefaultPolicy() Policy

DefaultPolicy returns Starmap's bounded, encrypted, owner-only raw policy.

func (Policy) Validate

func (p Policy) Validate() error

Validate rejects policies that could expose raw credentials or retain raw data indefinitely.

type RawAccess

RawAccess describes the access boundary required for raw evidence storage.

type RawAccess string

const (
    // RawAccessOwnerOnly requires an OS/service identity boundary with no public access.
    RawAccessOwnerOnly RawAccess = "owner_only"
)

type RawRecord

RawRecord contains response-body evidence only; request headers, query values, and credentials have no representation in this type.

type RawRecord struct {
    SourceID   catalogmeta.SourceID `json:"source"`
    ObservedAt time.Time            `json:"observed_at"`
    MediaType  string               `json:"media_type"`
    Payload    []byte               `json:"payload"`
}

func OpenRaw

func OpenRaw(key []byte, sealed SealedRawRecord, now time.Time) (RawRecord, error)

OpenRaw decrypts non-expired raw evidence and authenticates its envelope.

type SealedRawRecord

SealedRawRecord is an encrypted, expiring raw evidence envelope.

type SealedRawRecord struct {
    Version       uint64    `json:"version"`
    Algorithm     string    `json:"algorithm"`
    ObservationID string    `json:"observation_id,omitempty"`
    Nonce         []byte    `json:"nonce"`
    Ciphertext    []byte    `json:"ciphertext"`
    ExpiresAt     time.Time `json:"expires_at"`
}

func SealRaw

func SealRaw(key []byte, record RawRecord, expiresAt time.Time) (SealedRawRecord, error)

SealRaw encrypts short-lived raw evidence with AES-256-GCM.

Generated by gomarkdoc