registry

type DEKFilter struct {
	// KEKID and KEKVersion select the records wrapped under a KEK, or under
	// one of its versions when KEKVersion is non-zero.
	KEKID      envelope.ID
	KEKVersion uint32
	// Purpose selects one purpose when non-empty.
	Purpose keyforge.Purpose
	// After is the cursor: only identifiers greater than it are returned.
	After envelope.ID
	// Limit is the page size. Zero means [DefaultPageSize].
	Limit int
}

type DEKTransitionError struct {
	From, To keyforge.DEKState
}

type KEK struct {
	ID          envelope.ID
	Purpose     keyforge.Purpose
	Provider    string
	ProviderRef string
	State       KeyState
	CreatedAt   time.Time
}

type KeyState uint8

type Rewrap struct {
	ID envelope.ID
	// FromKEKID and FromVersion are what the caller believes the record is
	// wrapped under now. The change applies only if that is still so.
	FromKEKID   envelope.ID
	FromVersion uint32
	// ToKEKID and ToVersion are the active version to wrap under, and Wrapped
	// is the key wrapped under it.
	ToKEKID   envelope.ID
	ToVersion uint32
	Wrapped   []byte
}

type Sentinel struct {
	KEKID     envelope.ID
	Version   uint32
	Envelope  string // the envelope's text form
	CreatedAt time.Time
}

type ShredRecord struct {
	Purpose     keyforge.Purpose
	Subject     string
	RequestedAt time.Time
	// Versions is every KEK version that ever wrapped one of the subject's
	// data keys, in order of KEK and version.
	Versions []keyforge.KEKVersionRef
	// DEKs is how many data keys were destroyed.
	DEKs int
	// CompletedAt is when the last of Versions was destroyed. It is zero while
	// the shred is pending.
	CompletedAt time.Time
}

type Store interface {
	keyforge.Store

	// CreateKEK registers a KEK. It returns [ErrKEKExists] for a known
	// identifier and [ErrPurposeBound] if the purpose already has an active
	// KEK.
	CreateKEK(ctx context.Context, k KEK) error
	// GetKEK returns a KEK by identifier, or [keyforge.ErrKEKNotFound].
	GetKEK(ctx context.Context, id envelope.ID) (KEK, error)
	// KEKForPurpose returns the active KEK for a purpose, or
	// [keyforge.ErrKEKNotFound].
	KEKForPurpose(ctx context.Context, purpose keyforge.Purpose) (KEK, error)
	// ListKEKs returns every KEK ordered by identifier.
	ListKEKs(ctx context.Context) ([]KEK, error)

	// AddVersion registers a new version, which must be pending and greater
	// than the KEK's latest. Version numbers need not be consecutive: a
	// managed provider assigns them.
	AddVersion(ctx context.Context, v VersionRecord) error
	// GetVersion returns one version, or [ErrVersionNotFound].
	GetVersion(ctx context.Context, kekID envelope.ID, version uint32) (VersionRecord, error)
	// ListVersions returns a KEK's versions in ascending order.
	ListVersions(ctx context.Context, kekID envelope.ID) ([]VersionRecord, error)
	// TransitionVersion moves a version to a new state under the transition
	// table. Activating a version demotes the previous active version in the
	// same transaction, and reactivating one is allowed only for the most
	// recent decrypt-only version. Retirement is refused before its delay has
	// passed and while any data key is wrapped under the version.
	TransitionVersion(ctx context.Context, kekID envelope.ID, version uint32, to VersionState, opts TransitionOptions) error

	// ListDEKs returns data key records matching the filter, ordered by
	// identifier, at most one page.
	ListDEKs(ctx context.Context, f DEKFilter) ([]keyforge.DEKRecord, error)
	// CountDEKs returns how many data keys are wrapped under a KEK version, in
	// any state but destroyed.
	CountDEKs(ctx context.Context, kekID envelope.ID, version uint32) (int, error)
	// CountDEKStates returns how many data keys a purpose has in each state, for
	// reporting, without listing them.
	CountDEKStates(ctx context.Context, purpose keyforge.Purpose) (map[keyforge.DEKState]int, error)
	// RewrapDEK moves a data key to a new KEK version and wrapped value. It is
	// a compare-and-set on the version the key is wrapped under now and is
	// idempotent: repeating a completed rewrap succeeds, so a resumed job is
	// safe. The target must be active.
	RewrapDEK(ctx context.Context, r Rewrap) error
	// MarkDEK moves a data key to compromised or destroyed. A current key is
	// demoted only by advancing the epoch. Destroying a key removes its wrapped
	// value; the record remains.
	MarkDEK(ctx context.Context, id envelope.ID, to keyforge.DEKState) error

	// ShredSubject destroys every data key of a subject under a purpose, in
	// every state, removes their wrapped values, clears the current key, and
	// records the KEK versions that ever wrapped them, atomically. It leaves a
	// tombstone: a new key for the subject is refused with
	// [keyforge.ErrSubjectShredded]. Repeating it returns the existing record
	// and changes nothing. The subject must not be empty. If the subject had no
	// keys the shred is complete at once.
	ShredSubject(ctx context.Context, purpose keyforge.Purpose, subject string, at time.Time) (ShredRecord, error)
	// GetShred returns a subject's shred record, or [ErrShredNotFound].
	GetShred(ctx context.Context, purpose keyforge.Purpose, subject string) (ShredRecord, error)
	// ListShreds returns every shred record ordered by purpose and subject.
	ListShreds(ctx context.Context) ([]ShredRecord, error)
	// CompleteShred records that the shred is complete, provided every KEK
	// version in it has been destroyed. Otherwise it is [ErrShredPending] and
	// nothing changes. Repeating it on a complete shred returns the record.
	CompleteShred(ctx context.Context, purpose keyforge.Purpose, subject string, at time.Time) (ShredRecord, error)

	// PutSentinel stores the sentinel for a KEK version. The version must
	// exist. A version has one sentinel: storing an identical one again
	// succeeds, and a different one is [ErrConflict].
	PutSentinel(ctx context.Context, s Sentinel) error
	// GetSentinel returns a version's sentinel, or [ErrSentinelNotFound].
	GetSentinel(ctx context.Context, kekID envelope.ID, version uint32) (Sentinel, error)
	// ListSentinels returns a KEK's sentinels in ascending version order.
	ListSentinels(ctx context.Context, kekID envelope.ID) ([]Sentinel, error)
}

type TransitionError struct {
	From, To VersionState
}

type TransitionOptions struct {
	// At is when the change happens, from the caller's clock. Required.
	At time.Time
	// RetireAfter is the earliest time retirement may complete. Required, and
	// later than At, when moving to retire-requested.
	RetireAfter time.Time
}

type VersionRecord struct {
	KEKID       envelope.ID
	Version     uint32
	State       VersionState
	ProviderRef string // the provider's identifier for this version, if it has one
	CreatedAt   time.Time
	ActivatedAt time.Time // when the version last became active
	RotatedAt   time.Time // when the version stopped being active
	RetireAfter time.Time // earliest time retirement may complete
}

type VersionState uint8