Documentation
¶
Overview ¶
Package proofevidencesvc implements selected-resource metadata observations. The restricted broker operation is separate from ordinary introspection and is not enabled by Proof's UI flag.
Index ¶
- Constants
- Variables
- func ValidateExecutionResult(grant proofevidence.Grant, observation Observation) error
- type Coordinator
- type ExecutionCredentials
- type ExecutionRequest
- type Executor
- type Intent
- type JobAudit
- type Ledger
- func (s *Ledger) BeginExecution(ctx context.Context, org, jobSlug slug.Slug) (ExecutionRequest, error)
- func (s *Ledger) Cancel(ctx context.Context, org, job slug.Slug) error
- func (s *Ledger) CheckExecution(ctx context.Context, grant proofevidence.Grant) error
- func (s *Ledger) Job(ctx context.Context, scope proofobservations.Scope, job slug.Slug) (*proofobservations.Job, error)
- func (s *Ledger) OpenIntent(scope proofobservations.Scope, actor slug.Slug, token, requestDigest string) (*Intent, error)
- func (s *Ledger) Policy(ctx context.Context, scope proofobservations.Scope) (*proofobservations.Policy, error)
- func (s *Ledger) ReadForReceipt(ctx context.Context, scope proofobservations.Scope, jobSlug slug.Slug) (*ReceiptObservation, error)
- func (s *Ledger) ReadForReceiptDigest(ctx context.Context, scope proofobservations.Scope, digest string) (*ReceiptObservation, error)
- func (s *Ledger) ReadSnapshot(ctx context.Context, org, jobSlug slug.Slug) (Observation, error)
- func (s *Ledger) Record(ctx context.Context, grant proofevidence.Grant, observation Observation) error
- func (s *Ledger) Reserve(ctx context.Context, request proofevidence.Request, ...) (*proofobservations.Job, error)
- func (s *Ledger) SealIntent(actor slug.Slug, request proofevidence.Request, ...) (string, error)
- func (s *Ledger) SetPolicy(ctx context.Context, scope proofobservations.Scope, ...) error
- func (s *Ledger) Start(ctx context.Context, grant proofevidence.Grant) error
- type Maintenance
- func (s *Maintenance) Activity(ctx context.Context) (proofevidence.ActivitySnapshot, error)
- func (s *Maintenance) Cleanup(ctx context.Context, scope proofobservations.Scope) error
- func (s *Maintenance) CleanupReceipts(ctx context.Context, org slug.Slug) error
- func (s *Maintenance) Health(ctx context.Context) (model.ProofMaintenanceHealth, error)
- func (s *Maintenance) Run(ctx context.Context) error
- type Observation
- type ReceiptObservation
- type Service
- type Snapshot
Constants ¶
const ManagedExecutorIdentity = "managed-connector-executor"
ManagedExecutorIdentity identifies the hosted connector execution pool, not an individual River job or database session. Remote assignments remain denied.
Variables ¶
var ErrAdmissionLimit = xerror.Unavailable(xerror.Pipeline).Detail("Proof observation admission limit reached")
Functions ¶
func ValidateExecutionResult ¶
func ValidateExecutionResult(grant proofevidence.Grant, observation Observation) error
ValidateExecutionResult applies the same boundary at delivery and storage. Non-complete results cannot smuggle a protected snapshot into either store.
Types ¶
type Coordinator ¶
type Coordinator struct {
// contains filtered or unexported fields
}
Coordinator belongs to the backend. Executors never receive this ledger or credential-store access; they receive one encrypted, bounded operation.
func NewCoordinator ¶
func NewCoordinator(ledger *Ledger, credentials ExecutionCredentials, executor Executor) (*Coordinator, error)
func (*Coordinator) Run ¶
func (s *Coordinator) Run(ctx context.Context, org, job slug.Slug) (proofevidence.Result, error)
Run consumes a durable reservation once. User intent, candidate/binding resolution, and permission checks precede Reserve; this API grants none.
type ExecutionCredentials ¶
type ExecutionCredentials interface {
credentialssvc.ProofResolver
CheckProofCredential(context.Context, proofevidence.Grant) error
}
type ExecutionRequest ¶
type ExecutionRequest struct {
Request proofevidence.Request `json:"request"`
Authorization proofevidence.Authorization `json:"authorization"`
Policy proofevidence.Policy `json:"policy"`
Deadline time.Time `json:"deadline"`
Plan proofevidence.MetadataPlan `json:"plan"`
Credential credentialssvc.RuntimeCredential `json:"credential"`
}
ExecutionRequest is private delivery material. Only authenticated, encrypted transport may carry it; River jobs contain only the broker's opaque ID.
func (ExecutionRequest) Grant ¶
func (r ExecutionRequest) Grant() (proofevidence.Grant, error)
func (ExecutionRequest) GrantAt ¶
func (r ExecutionRequest) GrantAt(now time.Time) (proofevidence.Grant, error)
GrantAt requires a clock sample from the authenticated delivery authority.
type Executor ¶
type Executor interface {
ObserveProof(context.Context, ExecutionRequest) (Observation, error)
}
type Intent ¶
type Intent struct {
Kind string
Actor slug.Slug
Request proofevidence.Request
Target proofevidence.MetadataPlan
ExpiresAt time.Time
}
Intent remains protected backend data. Only an explicitly authorized preview response may expose its selected target; it is never a worker job payload.
type JobAudit ¶
type JobAudit struct {
Scope proofobservations.Scope
Reference proofobservations.JobReference
Action model.EventAction
Outcome proofevidence.Outcome
}
JobAudit contains only safe persisted references shared by lifecycle and retention controls.
func (JobAudit) EventRecord ¶
func (e JobAudit) EventRecord() (eventrecorder.Record, error)
type Ledger ¶
type Ledger struct {
// contains filtered or unexported fields
}
Ledger is backend orchestration, separate from the metadata executor. Its caller must prepare canonical candidate/binding/claim identities and perform environment-policy and user permission checks before issuing authorization.
func NewLedger ¶
func NewLedger(txm postgres.TransactionManager, repo *proofobservations.Repository, evidenceCipher crypto.AES256, audit eventrecorder.Recorder) (*Ledger, error)
func (*Ledger) BeginExecution ¶
func (s *Ledger) BeginExecution(ctx context.Context, org, jobSlug slug.Slug) (ExecutionRequest, error)
BeginExecution loads only a reserved target and atomically spends its single dispatch. A backend crash after this point cannot authorize another attempt.
func (*Ledger) CheckExecution ¶
CheckExecution is backend-only and returns no credential or evidence payload.
func (*Ledger) Job ¶
func (s *Ledger) Job(ctx context.Context, scope proofobservations.Scope, job slug.Slug) (*proofobservations.Job, error)
func (*Ledger) OpenIntent ¶
func (*Ledger) Policy ¶
func (s *Ledger) Policy(ctx context.Context, scope proofobservations.Scope) (*proofobservations.Policy, error)
func (*Ledger) ReadForReceipt ¶
func (s *Ledger) ReadForReceipt(ctx context.Context, scope proofobservations.Scope, jobSlug slug.Slug) (*ReceiptObservation, error)
func (*Ledger) ReadForReceiptDigest ¶
func (s *Ledger) ReadForReceiptDigest(ctx context.Context, scope proofobservations.Scope, digest string) (*ReceiptObservation, error)
func (*Ledger) ReadSnapshot ¶
ReadSnapshot is for the protected receipt compiler, not a public receipt response. Expiry, policy replacement, or ciphertext substitution is non-pass.
func (*Ledger) Record ¶
func (s *Ledger) Record(ctx context.Context, grant proofevidence.Grant, observation Observation) error
Record is a backend completion boundary. The execution broker must authenticate and fence executor delivery before returning an observation to this service. Go validates the result; SQL atomically rejects cancellation, expiry, or replay.
func (*Ledger) Reserve ¶
func (s *Ledger) Reserve(ctx context.Context, request proofevidence.Request, authorization proofevidence.Authorization, target proofevidence.MetadataObserver) (*proofobservations.Job, error)
Reserve commits worst-case usage before dispatch. The reservation survives cancellation and host loss until the deadline plus the entire rate window. The per-operation policy limits are shared by all jobs in this environment.
func (*Ledger) SealIntent ¶
func (s *Ledger) SealIntent(actor slug.Slug, request proofevidence.Request, target proofevidence.MetadataPlan, expires time.Time) (string, error)
func (*Ledger) SetPolicy ¶
func (s *Ledger) SetPolicy(ctx context.Context, scope proofobservations.Scope, policy proofevidence.Policy, workerIdentity string) error
SetPolicy serializes policy replacement with reservations. A changed policy needs a new version; cancellation prevents an old version being resurrected.
type Maintenance ¶
type Maintenance struct {
// contains filtered or unexported fields
}
Maintenance never needs the evidence or credential encryption keys. It runs independently of feature exposure so disabling observations cannot stop erasure.
func NewMaintenance ¶
func NewMaintenance(txm postgres.TransactionManager, repo *proofobservations.Repository, receipts proofreceipts.MaintenanceRepository, audit eventrecorder.Recorder) (*Maintenance, error)
func (*Maintenance) Activity ¶
func (s *Maintenance) Activity(ctx context.Context) (proofevidence.ActivitySnapshot, error)
Activity reads deployment aggregates through the backend, without executor database access.
func (*Maintenance) Cleanup ¶
func (s *Maintenance) Cleanup(ctx context.Context, scope proofobservations.Scope) error
Cleanup commits each bounded mutation batch with its audit records. A busy environment or interrupted sweep must not repeatedly roll back prior erasure.
func (*Maintenance) CleanupReceipts ¶
CleanupReceipts shares the compiler's tenant lock. Each batch either erases content and records replay keys together, or leaves both unchanged.
func (*Maintenance) Health ¶
func (s *Maintenance) Health(ctx context.Context) (model.ProofMaintenanceHealth, error)
Health reads only deployment aggregates and bounds the work of each scrape.
type Observation ¶
type Observation struct {
Result proofevidence.Result
Snapshot *Snapshot `json:"-"`
}
func ExecuteMetadata ¶
func ExecuteMetadata(ctx context.Context, request ExecutionRequest, target proofevidence.MetadataObserver, authorityTime time.Time) Observation
ExecuteMetadata has no persistence or credential-store dependency. The backend must monitor current authorization and cancel delivery on revocation.
type ReceiptObservation ¶
type ReceiptObservation struct {
DispatchedAt time.Time `json:"-"`
Request proofevidence.Request `json:"-"`
Target proofevidence.MetadataPlan `json:"-"`
Observation Observation `json:"-"`
}
ReceiptObservation stays inside the authorized compiler. Its selector and snapshot must never be serialized into a public receipt or job.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
func New ¶
func New(credentials credentialssvc.ProofResolver) (*Service, error)
func (*Service) Observe ¶
func (s *Service) Observe(ctx context.Context, grant proofevidence.Grant, target proofevidence.MetadataObserver) Observation
Observe requires a fresh dispatch grant. The runner still owns current policy, durable cumulative admission, cancellation, persistence, and audit events.
type Snapshot ¶
type Snapshot struct {
TargetFingerprint string `json:"target_fingerprint"`
Metadata json.RawMessage `json:"metadata"`
}
Snapshot may contain private schema names. It belongs only in encrypted, tenant-protected evidence storage, never receipts, jobs, logs, or annotations.