crlrefresh

type Alarm struct {
	Issuer    audit.SPKIHash
	Active    bool          // the alarm is on
	Critical  bool          // a gate would not accept the newest CRL now (gates are pausing)
	Age       time.Duration // now - thisUpdate of the newest CRL; zero when none is held
	Threshold time.Duration // the age beyond which the alarm is on
	Limit     time.Duration
	At        time.Time
	Detail    string
}

type Archive interface {
	// PutCRL stores der for issuer. meta.Marker is empty for a CRL of the series.
	PutCRL(ctx context.Context, issuer audit.SPKIHash, a ArchivedCRL, der []byte) error
	// List returns the issuer's CRL files, newest number first.
	List(ctx context.Context, issuer audit.SPKIHash) ([]ArchivedCRL, error)
	// Read returns the bytes of a listed file.
	Read(ctx context.Context, issuer audit.SPKIHash, a ArchivedCRL) ([]byte, error)
	// PutReset appends a reset record; Resets lists them (with Acked set) oldest first; AckReset marks
	// one acknowledged by an operator.
	PutReset(ctx context.Context, issuer audit.SPKIHash, r ResetRecord) error
	Resets(ctx context.Context, issuer audit.SPKIHash) ([]ResetRecord, error)
	AckReset(ctx context.Context, issuer audit.SPKIHash, r ResetRecord) error
}

type ArchivedCRL struct {
	Name       string
	Number     *big.Int
	ThisUpdate time.Time
	Marker     string
	// Source and Fetched record where and when the refresher got it (provenance, never evidence).
	Source  string
	Fetched time.Time
}

type DirArchive string

type Event struct {
	Kind     EventKind
	Issuer   audit.SPKIHash
	Feed     string // "base" or "delta"
	URL      string
	Detail   string
	Number   *big.Int // the CRL's number
	Held     *big.Int // the issuer's high-water mark, for a rollback or conflict
	Hash     [32]byte
	Err      error
	At       time.Time
	Outcomes []URLOutcome // per URL, for a fetched or failed attempt
}

type EventKind string

type Hooks struct {
	OnEvent func(Event)
	OnAlarm func(Alarm)
}

type IssuerHealth struct {
	Issuer              audit.SPKIHash
	URLs, DeltaURLs     []string // the effective list, without query or fragment
	LastAttempt         time.Time
	LastSuccess         time.Time // the last attempt that confirmed the newest CRL and found it fresh
	NewestNumber        *big.Int
	NewestThisUpdate    time.Time
	NewestNextUpdate    time.Time // the earlier of base and paired delta
	Age                 time.Duration
	NextExpected        time.Time // thisUpdate + declared skew + period
	NextAttempt         time.Time
	ConsecutiveFailures int
	LastError           string
	ArchiveBacklog      int
	Paired              bool // a delta is held and paired with its base (false when no deltas are configured)
	Alarm, Critical     bool
	Limit               time.Duration
	AlarmAge            time.Duration
	Loop                time.Time // the last time this issuer's loop ran: a watchdog for a dead loop
	UnackedResets       int
}

type IssuerResult struct {
	Issuer audit.SPKIHash
	Err    error
}

type Options struct {
	// Issuers are the certificates of the pinned intermediates (the policy pins them by key only). Each
	// must match a pinned key and chain to an anchor; a pinned intermediate with no certificate here is
	// refused. They are the only certificates a CRL signature is checked against besides the anchors.
	Issuers []*x509.Certificate
	// DeltaPeriodFor is the declared delta CRL period of each issuer that has DeltaURLs.
	DeltaPeriodFor map[audit.SPKIHash]time.Duration
	// StandIn is set when the approver was built from a declaration file (audit.StatusDecl.Approver) and
	// not by the gate: the start-up events then say whether the approver's policy digest can be compared
	// with the gate's. Nil means the approver is the gate's own.
	StandIn *StandIn
	// Client is the application's HTTP client (mTLS, a proxy, a resolver). Nil builds the library's: no
	// proxy, no compression, timeouts on every stage. The library cannot enforce proxy or DNS rules on a
	// client it did not build; it still bounds the body, the context and the redirects.
	Client *http.Client
	// Archive stores accepted CRLs and the rollback memory. Nil runs without: a restart forgets rollback
	// protection, and the refresher says so at start.
	Archive Archive
	// Hooks receives events and alarms.
	Hooks Hooks
	// Sleep waits for d or the context; nil uses a timer. Rand returns [0,1); nil uses math/rand/v2.
	// Both exist so a test can drive the schedule without a real clock.
	Sleep func(ctx context.Context, d time.Duration) error
	Rand  func() float64
	// MaxArchiveQueueBytes bounds the memory held for CRLs the archive refused (default 64 MiB); the
	// oldest are dropped and reported.
	MaxArchiveQueueBytes int
}

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

type ResetItem struct {
	Hash   string `json:"hash"`
	Number string `json:"number"`
}

type ResetRecord struct {
	Name     string      `json:"-"`
	Issuer   string      `json:"issuer"`
	SetAside []ResetItem `json:"set_aside"`
	// LostSerials are the certificate serials (decimal) the CRLs set aside listed and no CRL left in the
	// snapshot lists: the revocations the reset dropped from the live gate, for an auditor.
	LostSerials []string  `json:"lost_serials,omitempty"`
	Reason      string    `json:"reason"`
	Operator    string    `json:"operator"`
	Time        time.Time `json:"time"`
	Acked       bool      `json:"-"`
}

type ResetRequest struct {
	// Reason and Operator are required and recorded in the archive.
	Reason, Operator string
	// SetAside are the SHA-256 hashes of the archived CRLs to set aside. With none, the archived CRL at
	// the current mark.
	SetAside [][32]byte
	// AcceptLostListings allows the reset when a CRL set aside lists a certificate that no CRL left in the
	// snapshot lists: the reset would drop that revocation from the live gate until the CA publishes it
	// again. Without it such a reset is refused; with it the serials are written into the record.
	AcceptLostListings bool
}

type StandIn struct{ Missing []string }

type URLOutcome struct {
	URL string `json:"url"` // without query and fragment
	// Kind is "ok" (fetched; reported alone only when the attempt succeeded), "not-modified", "oversize",
	// "timeout", "redirect-refused", "http-status", "error", "not-a-crl", "refused" (fetched but not accepted:
	// a rollback, conflict, set-aside, future-dated, unverifiable or wrong-kind CRL; Detail says why) or
	// "stale" (fetched, archived and added, but already past its nextUpdate).
	Kind   string `json:"kind"`
	Status int    `json:"status,omitempty"`
	Detail string `json:"detail,omitempty"`
}