secretbroker

type AccessRequest struct {
	ID string `json:"id"`
	// RequestedBy is the identity that asked — an OIDC subject, a service
	// account, or "cli:<user>". It is the value ApproveRequest compares against
	// the decider, so it must identify a person and not a role.
	RequestedBy string `json:"requested_by"`

	SecretID   string `json:"secret_id"`
	SecretName string `json:"secret_name,omitempty"`
	Kind       Kind   `json:"kind,omitempty"`

	// Subject and Constraints are the grant this request is asking to have
	// created. They are replayed verbatim on approval.
	Subject     Subject     `json:"subject"`
	Constraints Constraints `json:"constraints"`
	Scope       string      `json:"scope,omitempty"`

	// TTL is the grant lifetime asked for. What was actually issued is
	// GrantExpiresAt minus DecidedAt, which will be shorter whenever the
	// approver or their delegation clamped it — and a reviewer comparing the
	// two is exactly how "did anyone actually narrow this" gets answered.
	TTL time.Duration `json:"ttl"`

	// Justification is why. Required, because a request with no stated reason
	// cannot be evaluated, only rubber-stamped.
	Justification string `json:"justification"`

	State     RequestState `json:"state"`
	CreatedAt time.Time    `json:"created_at"`
	// ExpiresAt is when this *request* lapses undecided. Never the credential's
	// expiry — that is GrantExpiresAt.
	ExpiresAt time.Time `json:"expires_at"`

	DecidedBy    string    `json:"decided_by,omitempty"`
	DecidedAt    time.Time `json:"decided_at,omitempty"`
	DecisionNote string    `json:"decision_note,omitempty"`

	// GrantID is the grant an approval minted, and empty in every other state.
	GrantID        string    `json:"grant_id,omitempty"`
	GrantExpiresAt time.Time `json:"grant_expires_at,omitempty"`
}

type AccessRequestInput struct {
	// SecretRef is a secret ID or name. The secret must already exist: a
	// request asks for access to a credential an operator stored, never for one
	// to be created, because creating one means supplying material and a
	// requester by definition does not have it.
	SecretRef     string
	Subject       Subject
	Constraints   Constraints
	Scope         string
	TTL           time.Duration
	Justification string
	// RequestTTL is how long to wait for a decision. Zero means
	// DefaultRequestTTL.
	RequestTTL time.Duration
	// Actor is the requesting identity. Required: an anonymous request cannot
	// be approved, because the self-approval check has nothing to compare.
	Actor string
}

type Action string

type AppCredential struct {
	AppID          int64
	InstallationID int64
	// BaseURL is the API root, defaulted to github.com.
	BaseURL string
	// contains filtered or unexported fields
}

type AppInstallation struct {
	// ID is the installation_id a github_app payload needs.
	ID int64 `json:"id"`
	// AppID is the app the installation belongs to. Echoed back so a caller
	// holding several keys can tell which one produced this list.
	AppID int64 `json:"app_id"`
	// Account is the org or user the App is installed on ("bb-selforg").
	Account string `json:"account"`
	// AccountType is "Organization" or "User".
	AccountType string `json:"account_type"`
	// RepositorySelection is "all" or "selected" — whether the installation
	// covers every repository the account owns or an explicitly chosen subset.
	// An operator who granted "all" and still cannot reach a repository has a
	// different problem from one who granted "selected" and forgot to tick it.
	RepositorySelection string `json:"repository_selection"`
}

type Auditor interface {
	Audit(ev Event)
}

type AuditorFunc func(Event)

type Broker struct {

	// GitGuard, when set, takes custody of a GitHub PAT so the sandbox
	// receives a git-proxy session instead of the token. It turns the
	// repository allowlist from something the workload is asked to respect
	// into something it cannot exceed. See gitguard.go.
	//
	// Exported and settable after construction because the proxy it fronts is
	// started by pkg/ui alongside the hub, later than the broker and from a
	// layer this package must not import.
	GitGuard GitGuard

	// KubeGuard, when set, takes custody of a kubeconfig so the sandbox
	// receives a monitor session instead of the cluster credential. It turns
	// the namespace allowlist from a client-side default into a bound, and it
	// is the only way a kubeconfig grant's verbs mean anything at all. See
	// kubeguard.go.
	//
	// Exported and settable after construction for the same reason GitGuard
	// is: the monitor it fronts is started by pkg/ui alongside the hub, later
	// than the broker and from a layer this package must not import.
	KubeGuard KubeGuard
	// contains filtered or unexported fields
}

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

type Constraints struct {
	// Repos is an owner/repo glob allowlist for github_pat and github_app.
	// Patterns match case-insensitively; "*" alone allows every repository.
	Repos []string `json:"repos,omitempty"`
	// Permissions is the permission set a github credential may exercise
	// ("contents:read", "pull_requests:write"). Enforced at cloop's own
	// GitHub call sites via AllowsPermission; GitHub cannot narrow an
	// already-issued PAT server-side.
	Permissions []string `json:"permissions,omitempty"`
	// Branches narrows where a github_pat or github_app grant may push:
	// branch-name globs such as "cloop/*", "feature/**" or "develop". Empty
	// means the grant adds no branch restriction of its own, and the hub's git
	// proxy policy (executors.git_proxy.allowed_refs) is the only limit.
	//
	// Only a grant that authorises a push may carry one — a branch list on a
	// read-only grant restricts nothing and would read as though it did — and
	// it restricts branches only: a push of a tag, or of any other ref, is
	// outside every branch list.
	//
	// Nothing inside a sandbox can enforce this, because git's credential
	// protocol never says which ref a push is for. The git proxy can, since it
	// reads every pushed command before forwarding it; see pkg/gitproxy
	// Policy.RestrictRefs. Where no proxy guards the grant, the broker withholds
	// the grant's write authority rather than deliver a credential that would
	// ignore the list: see RestrictsBranches.
	Branches []string `json:"branches,omitempty"`
	// Namespaces is the Kubernetes namespace allowlist for kubeconfig.
	Namespaces []string `json:"namespaces,omitempty"`
	// Contexts is the kubeconfig context allowlist. The delivered
	// kubeconfig contains only these contexts.
	Contexts []string `json:"contexts,omitempty"`
	// Verbs is the RBAC verb allowlist for a kubeconfig grant: what the
	// holder may *do* to the cluster, as opposed to which parts of it the
	// other two fields let them see.
	//
	// Empty means read-only — get, list and watch — which is the answer to
	// "an operator granted a cluster and said nothing about writes". It is
	// the one place in this struct where an empty list is neither "allow all"
	// nor a validation error, and the asymmetry is deliberate: the safe
	// reading of silence about a cluster credential is that nobody asked for
	// the ability to change anything.
	//
	// Unlike Namespaces and Contexts, this cannot be enforced by rewriting
	// the kubeconfig — a kubeconfig has no field for it. It is enforced by
	// pkg/kubeguard, the monitor the hub runs outside the sandbox, and it
	// therefore only takes effect when executors.kube_guard is enabled.
	// KubeconfigGuarded reports whether that is so for a given grant, and the
	// Secrets panel renders the difference rather than letting a grant claim
	// an enforcement that is not running.
	Verbs []string `json:"verbs,omitempty"`
	// Hosts is the allowed-host list for egress_proxy. A leading "*."
	// matches subdomains only, not the bare domain.
	Hosts []string `json:"hosts,omitempty"`
	// Registries is the container-registry allowlist for registry secrets.
	Registries []string `json:"registries,omitempty"`
	// EnvKeys restricts which keys of an env secret are delivered. Empty
	// means every key in the secret, which is safe because an env secret's
	// keys *are* its scope — there is nothing wider to fall open to.
	EnvKeys []string `json:"env_keys,omitempty"`
	// Devices is the device-name allowlist for host_device. Patterns match
	// case-sensitively against the inventory's handles; "*" alone allows
	// every device in the inventory.
	//
	// Case-sensitive for the reason the local_repo matcher is: these names
	// are chosen by an operator and matched exactly, and folding would make a
	// grant on "gpu0" also open "GPU0" — which, if both existed, would be two
	// different pieces of hardware nobody named.
	Devices []string `json:"devices,omitempty"`
	// Interfaces is the interface-name allowlist for host_interface. Patterns
	// match case-sensitively against the inventory's handles, exactly as
	// Devices does and for the same reason; "*" alone allows every interface
	// in the inventory.
	Interfaces []string `json:"interfaces,omitempty"`
	// Writable makes a local_repo grant read-write. It is the one constraint
	// that widens rather than narrows, so it is a bool that defaults to the
	// safe reading: a grant that says nothing delivers a read-only mount.
	//
	// Read-only is the useful default rather than a cautious one. The common
	// case is a sandbox that needs to *read* a developer's checkout — build
	// against it, grep it, copy from it — and a read-only bind means a
	// runaway harness cannot rewrite the history of a repository that exists
	// nowhere else. A project that genuinely needs to commit asks for it.
	Writable bool `json:"writable,omitempty"`
}

type DecideInput struct {
	RequestID string
	// Actor is the deciding identity, compared against the requester to refuse
	// self-approval.
	Actor string
	// Note is the approver's comment. Required on a denial — a refusal with no
	// reason is one the requester can only respond to by asking again — and
	// optional on an approval.
	Note string
	// TTL, when positive, shortens the minted grant. It can only ever narrow:
	// a value above what was requested, or above the delegation ceiling, is
	// clamped rather than honoured.
	TTL time.Duration
	// Delegation is the ceiling this approver may hand out.
	Delegation Delegation
}

type Decision string

type Delegation struct {
	// MaxTTL caps the minted grant's lifetime. Zero means
	// DefaultDelegationMaxTTL.
	MaxTTL time.Duration
	// AllowWildcardSubject permits approving a request aimed at every project,
	// every executor, or every requester.
	//
	// Its own flag rather than a TTL question because the two failure modes are
	// not comparable: a grant that lives too long is bounded by its expiry,
	// while a grant aimed at project:* reaches every tenant on the hub for as
	// long as it lasts. An approver entitled to the first is not automatically
	// entitled to the second.
	AllowWildcardSubject bool
}

type DeliveredFile struct {
	GrantID    string
	SecretName string
	Kind       Kind
	// Dir is the directory on the executor, mirroring Delivery.Dir so a
	// caller can build one flat list from several leases.
	Dir  string
	Name string
	Mode os.FileMode
	// Content is the plaintext.
	Content []byte
}

type Delivery struct {
	// Dir is where the workload will find the files. It is a path on the
	// executor, not on this host.
	Dir string
	// contains filtered or unexported fields
}

type Envelope struct {
	KeyID      string
	WrappedDEK []byte
	Ciphertext []byte
}

type Event struct {
	Time     time.Time `json:"time"`
	Action   Action    `json:"action"`
	Decision Decision  `json:"decision"`
	// Actor is who asked: an OIDC subject, "cli", "ui", or an executor ID.
	Actor string `json:"actor,omitempty"`
	// Subject is the grant subject the operation concerned, rendered in
	// the CLI's "--to" syntax.
	Subject string `json:"subject,omitempty"`
	// SecretID and SecretName identify the credential. The name is a
	// handle chosen by an operator, never the value.
	SecretID   string `json:"secret_id,omitempty"`
	SecretName string `json:"secret_name,omitempty"`
	Kind       Kind   `json:"kind,omitempty"`
	GrantID    string `json:"grant_id,omitempty"`
	// RequestID is the access request an event concerns (Task 20271). Present
	// on the request family above, and on nothing else: a grant minted directly
	// has no request behind it, and leaving the field empty is what makes
	// "which grants came through review" answerable from the trail.
	RequestID  string `json:"request_id,omitempty"`
	LeaseID    string `json:"lease_id,omitempty"`
	ExecutorID string `json:"executor_id,omitempty"`
	ProjectID  string `json:"project_id,omitempty"`
	// RunID names the execution a lease was issued to (Task 20282). It is what
	// makes "which credentials did this task hold" answerable exactly: a task
	// id may run many times and unions every attempt's leases, whereas a run id
	// names the one execution that spent them.
	//
	// Populated for dispatch-time leases. Empty for grant and mint events,
	// which are operator actions with no execution behind them.
	RunID string `json:"run_id,omitempty"`
	// Constraints is the allowlist summary that applied to the decision.
	Constraints string `json:"constraints,omitempty"`
	// ExpiresAt is the TTL stamp of the grant or lease involved.
	ExpiresAt time.Time `json:"expires_at,omitempty"`
	// Reason explains a denial, or annotates an allow ("2 grants matched").
	Reason string `json:"reason,omitempty"`

	// TaskID is the unit of work the decision was made for. Populated by
	// the egress broker, which knows it; the secret broker's leases are
	// per-executor rather than per-task and leave it empty.
	TaskID string `json:"task_id,omitempty"`
	// Host and Port name an egress destination. They are a hostname and a
	// port and nothing else — deliberately not a URL, because a URL has a
	// path and a query, and those are request contents rather than access
	// metadata.
	Host string `json:"host,omitempty"`
	Port int    `json:"port,omitempty"`
	// BytesUp and BytesDown are the session's transfer totals at the time of
	// the decision, from the workload's point of view.
	BytesUp   int64 `json:"bytes_up,omitempty"`
	BytesDown int64 `json:"bytes_down,omitempty"`
}

type File struct {
	// Name is a bare file name — no directory separators. Materialize
	// re-checks this before writing, so a crafted name cannot escape the
	// lease directory.
	Name    string
	Content []byte
	Mode    os.FileMode
	// EnvVar, when set, receives the file's absolute path after
	// materialisation (KUBECONFIG, GIT_CONFIG_GLOBAL, DOCKER_CONFIG).
	EnvVar string
	// EnvIsDir points EnvVar at the containing directory rather than the
	// file, which is what DOCKER_CONFIG expects.
	EnvIsDir bool
}

type GitGuard interface {
	// GuardGitHub takes a GitHub token and the constraints it was granted
	// under, and returns the credentials a sandbox should use in its place.
	//
	// Returning a zero GitGuardResult with a nil error means "not guarding
	// this one" — the delivery falls back to the in-sandbox helper. That is
	// how a hub with the proxy switched off keeps working, and it is a
	// decision the implementation makes deliberately rather than one this
	// package infers from an error it cannot interpret.
	GuardGitHub(ctx context.Context, req GitGuardRequest) (GitGuardResult, error)
}

type GitGuardRequest struct {
	// Token is the credential the guard takes custody of. It must not be
	// copied into the result, into a log, or into anything the sandbox reads.
	Token string
	// Repos is the grant's owner/name glob allowlist. The guard enforces it.
	Repos []string
	// Permissions is the grant's permission set ("contents:read"). The guard
	// translates it into what the proxy will allow — most importantly whether
	// the sandbox may push at all.
	Permissions []string
	// Branches is the grant's branch allowlist, as the grant stores it. The
	// guard narrows the session's ref policy to it, within the hub's own
	// allowlist. Empty means the grant adds no branch restriction.
	Branches []string

	// Labels. None is secret; all are audit bookkeeping.
	SecretName string
	SecretID   string
	GrantID    string
	LeaseID    string
	ProjectID  string
	ExecutorID string
	Actor      string
	// Owner is the identity a personal secret belongs to, or "" for a shared
	// one. It rides along so the proxy's audit rows name the person whose
	// credential is being spent, which for a personal PAT is the whole point.
	Owner string
}

type GitGuardResult struct {
	// BaseURL is the proxy's https base, with no path. GitHub URLs are
	// rewritten to it.
	BaseURL string
	// Username and Password authenticate to the proxy and to nothing else.
	Username string
	Password string
	// ExpiresAt is when the proxy stops honouring them.
	ExpiresAt time.Time
	// SessionID identifies the proxy session, for audit joins and revocation.
	SessionID string
	// Summary is an audit-safe description of what the proxy will enforce
	// ("read-only, acme/*"). It carries no credential.
	Summary string
	// ReadOnly records whether the grant's permissions left the session
	// unable to push. Surfaced so the lease's own summary can say so without
	// re-deriving the rule the guard already applied.
	ReadOnly bool
	// PushRefs is the hub's own ref allowlist for pushes — the ceiling the
	// grant's Branches narrow, as full ref patterns. Announced to the workload
	// so it can choose a branch the proxy will accept, rather than learn the
	// policy one refused push at a time. Empty when the session cannot push.
	PushRefs []string
}

type GitHubAppAPI interface {
	// CreateInstallationToken mints an installation access token.
	CreateInstallationToken(ctx context.Context, req InstallationTokenRequest) (InstallationToken, error)
	// ListInstallationRepos enumerates the repositories the *token* reaches.
	// It is authenticated with an installation token, not the app JWT —
	// GitHub offers no app-JWT route to this list.
	ListInstallationRepos(ctx context.Context, baseURL, installationToken string) ([]InstallationRepo, error)
	// RevokeInstallationToken destroys the token used to authenticate the
	// call. After it returns nil the credential is dead at GitHub, not merely
	// deleted from a sandbox's disk.
	RevokeInstallationToken(ctx context.Context, baseURL, installationToken string) error
	// ListAppInstallations enumerates where the App is installed. It is
	// authenticated with the app JWT rather than an installation token —
	// it is the one call that runs before any installation is known, which is
	// the whole reason it exists.
	ListAppInstallations(ctx context.Context, baseURL, appJWT string) ([]AppInstallation, error)
}

type Grant struct {
	ID       string `json:"id"`
	SecretID string `json:"secret_id"`
	// Scope is a free-form operator-facing label ("ci", "deploy") used for
	// grouping and filtering. It carries no authorisation weight — that is
	// entirely Subject plus Constraints — so an operator cannot widen a
	// grant by editing it.
	Scope       string      `json:"scope,omitempty"`
	Subject     Subject     `json:"subject"`
	Constraints Constraints `json:"constraints"`
	// ExpiresAt is when the grant stops being usable. Zero means no expiry,
	// which Validate permits only because the legacy import needs it; the
	// CLI always sets a TTL.
	ExpiresAt time.Time `json:"expires_at,omitempty"`
	CreatedAt time.Time `json:"created_at"`
	CreatedBy string    `json:"created_by,omitempty"`
	RevokedAt time.Time `json:"revoked_at,omitempty"`
	// Owner is copied from the secret this grant points at when that secret
	// is personal, and is empty otherwise.
	//
	// Denormalised on purpose. A grant listing is read far more often than a
	// secret is minted, and the alternative — resolving every grant's secret
	// to find out whether the row should be shown — is the N+1 read that the
	// listing handlers already go out of their way to avoid. More importantly
	// it keeps the row self-describing: when the secret is deleted, the
	// revoked grants it leaves behind still say whose credential they spent,
	// which is exactly the question an offboarding or incident review asks.
	Owner string `json:"owner,omitempty"`
}

type GrantFilter struct {
	// Subject, when set, keeps only grants whose subject renders to this
	// string (exact match on the "--to" syntax).
	Subject string
	// SecretRef, when set, keeps only grants for that secret.
	SecretRef string
	// ActiveOnly drops expired and revoked grants.
	ActiveOnly bool
}

type GrantRequest struct {
	// SecretRef is a secret ID or name.
	SecretRef   string
	Subject     Subject
	Constraints Constraints
	Scope       string
	// TTL is the grant's lifetime. Zero means DefaultGrantTTL unless
	// NoExpiry is set.
	TTL time.Duration
	// NoExpiry creates a grant that never expires. Reserved for the legacy
	// import, where imposing a TTL on secrets that previously had none
	// would break running projects at an unpredictable moment.
	NoExpiry bool
	Actor    string
	// Viewer is the identity the grant is created on behalf of. It gates
	// personal secrets: only their owner may hand one to an executor
	// (Task 20275). The zero value sees no personal secret at all, so a
	// caller that forgets it is refused rather than privileged.
	//
	// Shared secrets ignore it entirely, which is what keeps every existing
	// call site — the CLI, the legacy import, the approval path — correct
	// without change.
	Viewer Viewer
}

type GrantedDevice struct {
	// Name is the handle from the inventory, and what a grant's allowlist and
	// a sandbox spec's `devices:` list match against.
	Name string `json:"name"`
	// Source is the absolute device path on the executor's host.
	Source string `json:"source"`
	// Target is where it appears inside the sandbox. Equal to Source unless
	// the inventory remapped it.
	Target string `json:"target"`
	// Permissions is the rwm access string ("r", "rw", "rwm").
	Permissions string `json:"permissions"`
}

type GrantedInterface struct {
	// Name is the handle from the inventory, and what a grant's allowlist and
	// a sandbox spec's `interfaces:` list match against.
	Name string `json:"name"`
	// Source is the interface's name on the executor's host.
	Source string `json:"source"`
	// Target is the name it takes inside the sandbox. Equal to Source unless
	// the inventory renamed it.
	Target string `json:"target"`
	// Address is the optional CIDR to configure inside the sandbox.
	Address string `json:"address,omitempty"`
	// Gateway is the optional default route to install through it.
	Gateway string `json:"gateway,omitempty"`
	// MTU optionally overrides the interface's MTU. Zero means leave it.
	MTU int `json:"mtu,omitempty"`
}

type InstallationRepo struct {
	ID       int64  `json:"id"`
	FullName string `json:"full_name"`
	Private  bool   `json:"private"`
}

type InstallationToken struct {
	Token               string            `json:"token"`
	ExpiresAt           time.Time         `json:"expires_at"`
	Permissions         map[string]string `json:"permissions,omitempty"`
	RepositorySelection string            `json:"repository_selection,omitempty"`
}

type InstallationTokenRequest struct {
	// BaseURL and AppJWT authenticate the request as the app.
	BaseURL string
	AppJWT  string
	// InstallationID names the installation to mint for.
	InstallationID int64
	// RepositoryIDs narrows the token to these repositories. IDs rather than
	// names: a name is ambiguous across the owners an installation may span,
	// and an ID cannot be made to mean a different repository by a rename.
	RepositoryIDs []int64
	// Permissions narrows what the token may do. Nil asks for the
	// installation's full permission set.
	Permissions map[string]string
}

type KEKRecord struct {
	ID    string
	Salt  string // hex-encoded KDF salt; emptied on retirement
	State string // primary | active | retired
	// CheckValue is kekCheckPlaintext sealed under this KEK.
	CheckValue []byte
	CreatedAt  time.Time
	CreatedBy  string
	RetiredAt  time.Time
}

type KeyInfo struct {
	ID        string    `json:"id"`
	State     string    `json:"state"`
	Primary   bool      `json:"primary"`
	Openable  bool      `json:"openable"`
	CreatedAt time.Time `json:"created_at"`
	CreatedBy string    `json:"created_by,omitempty"`
	RetiredAt time.Time `json:"retired_at,omitempty"`
}

type KeyStore interface {
	// PutKEK inserts or replaces a KEK record.
	PutKEK(k KEKRecord) error
	// ListKEKs returns every KEK, including retired ones — retired rows are
	// kept so `cloop hub key list` can still explain what a row referencing
	// a dead key is referencing.
	ListKEKs() ([]KEKRecord, error)
	// PrimaryKEK returns the current primary, if there is one. It exists
	// separately from ListKEKs because it is on the seal path: every seal
	// re-reads it, so it must be a single indexed lookup rather than a scan.
	PrimaryKEK() (KEKRecord, bool, error)
	// PromoteKEK makes id the sole primary, demoting any incumbent, in one
	// transaction. Atomicity matters: two hubs promoting concurrently must
	// not both succeed and leave rows sealed under a key neither considers
	// current.
	PromoteKEK(id string, at time.Time) error
	// RetireKEK marks a KEK retired and destroys its salt. It must refuse
	// while any sealed row still references the key.
	RetireKEK(id string, at time.Time) error
}

type KeyUsage struct {
	KeyID string         `json:"key_id"`
	Total int            `json:"total"`
	BySet map[string]int `json:"by_set"`
}

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

type KeyringOption func(*keyringConfig)

type Kind string

type KubeGuard interface {
	// GuardKubeconfig takes custody of a kubeconfig and the constraints it
	// was granted under, and returns the document to deliver instead.
	//
	// Returning a zero result with a nil error means "declined": there is no
	// monitor on this hub, and the caller should deliver the minimised
	// kubeconfig as before. Returning an error means a monitor was required
	// and could not be provided, which must fail the lease rather than fall
	// back — a hub whose config promises enforcement and silently delivers
	// the raw credential is worse than one that never promised.
	GuardKubeconfig(ctx context.Context, req KubeGuardRequest) (KubeGuardResult, error)
}

type KubeGuardRequest struct {
	// Kubeconfig is the minimised document, already reduced to the contexts
	// the grant allows. The monitor takes custody of it; it must not be
	// copied into the result, into a log, or into anything the sandbox reads.
	//
	// Minimised rather than raw on purpose: the two narrowings compose, so a
	// monitor that was somehow pointed at the wrong context still cannot
	// reach a cluster the grant excluded.
	Kubeconfig []byte
	// Verbs is the grant's effective verb allowlist, already resolved from
	// Constraints.KubeVerbs — so the monitor never has to re-derive that an
	// empty list means read-only.
	Verbs []string
	// Namespaces is the grant's namespace allowlist. The monitor enforces it
	// on every request, which is the thing the delivered document could not.
	Namespaces []string

	// Labels. None is secret; all are audit bookkeeping.
	SecretName string
	SecretID   string
	GrantID    string
	LeaseID    string
	ProjectID  string
	ExecutorID string
	Actor      string
	// Owner is the identity a personal kubeconfig belongs to, or "" for a
	// shared one. It rides along so the monitor's audit rows name the person
	// whose cluster credential is being spent.
	Owner string
}

type KubeGuardResult struct {
	// Kubeconfig is the document to deliver into the sandbox. It points at
	// the monitor and carries a session token, and it contains no cluster
	// credential — that is the whole point, and kubeconfig_test.go in
	// pkg/kubeguard asserts it against a known plaintext.
	Kubeconfig []byte
	// SessionID identifies the monitor session, for audit joins and
	// revocation.
	SessionID string
	// ExpiresAt is when the monitor stops honouring the session.
	ExpiresAt time.Time
	// ReadOnly records whether the resulting session can only read. Surfaced
	// so the lease summary can say so without re-deriving the rule.
	ReadOnly bool
	// Summary is an audit-safe description of what the monitor will enforce
	// ("read-only, ns app|app-staging"). It carries no credential.
	Summary string
}

type Lease struct {
	ID         string    `json:"id"`
	ExecutorID string    `json:"executor_id,omitempty"`
	ProjectID  string    `json:"project_id,omitempty"`
	IssuedAt   time.Time `json:"issued_at"`
	ExpiresAt  time.Time `json:"expires_at"`
	// RunID is the execution this lease was issued to (Task 20282). Carried on
	// the lease so the renew and release rows correlate to the same run as the
	// issuance — a lease's *end* is as audit-relevant as its start, and a
	// release row that could not name its run would break the join at exactly
	// the point an auditor is checking that a credential stopped being held.
	RunID string `json:"run_id,omitempty"`
	// Materials carries the credentials. json:"-" on the sensitive fields
	// of Material keeps a marshalled Lease audit-safe.
	Materials []Material `json:"materials"`
}

type LeaseBinding struct {
	// GrantID is the grant this material came from.
	GrantID string
	// SecretID and SecretName identify the stored secret, for diagnostics.
	SecretID   string
	SecretName string
	// Kind is the credential kind.
	Kind Kind
	// EnvKeys are the variables this grant contributed, by name.
	EnvKeys []string
	// Files are the absolute paths written for this grant.
	Files []string
	// Dir is the lease directory holding Files.
	Dir string
	// Mounts are the host paths this grant opened, recorded for the audit
	// trail rather than for revocation.
	//
	// The distinction matters and is a real limitation: a revoked lease's
	// files are wiped and its variables scrubbed, but a bind already in a
	// running sandbox's mount namespace cannot be taken back from outside it.
	// A local_repo grant therefore lapses when the workload exits, not when
	// the grant is revoked. Narrowing that window means stopping the workload.
	Mounts []RepoMount
	// Devices are the host device nodes this grant opened, recorded for the
	// audit trail rather than for revocation.
	//
	// The same limitation as Mounts applies, and harder: a device already in a
	// running sandbox's cgroup and mount namespace cannot be taken back from
	// outside it. A host_device grant therefore lapses when the workload exits,
	// not when the grant is revoked, and narrowing that window means stopping
	// the workload.
	Devices []GrantedDevice
	// Interfaces are the host network interfaces this grant moved into the
	// sandbox, recorded for the audit trail rather than for revocation.
	//
	// The same limitation as Devices applies: an interface inside a running
	// sandbox's network namespace cannot be reached from outside it, so a
	// host_interface grant lapses when the workload exits rather than when
	// the grant is revoked.
	Interfaces []GrantedInterface
}

type LegacyImportResult struct {
	// Imported names the secrets newly minted into the broker.
	Imported []string
	// Skipped names entries already present (the import is idempotent).
	Skipped []string
}

type Material struct {
	GrantID     string      `json:"grant_id"`
	SecretID    string      `json:"secret_id"`
	SecretName  string      `json:"secret_name"`
	Kind        Kind        `json:"kind"`
	Constraints Constraints `json:"constraints"`
	// Env are variables to inject, already narrowed. Values are
	// credentials; this field is json:"-" so a Material cannot be
	// serialised into an API response by accident.
	Env map[string]string `json:"-"`
	// SensitiveEnv names the Env keys whose values are credentials rather
	// than the constraints those credentials were narrowed to.
	//
	// The distinction only exists because output redaction needs it. A
	// material delivers GITHUB_TOKEN *and* CLOOP_GITHUB_REPO_ALLOWLIST;
	// scrubbing the first out of a task transcript protects a credential,
	// and scrubbing the second would replace every mention of a repository
	// name with a marker. Nothing about the two values says which is which,
	// so the builder that knows says so here.
	//
	// Names only — a value here would be a second copy of the secret in a
	// struct whose whole point is to keep track of the first.
	SensitiveEnv []string `json:"-"`
	// Files are written into the lease's tmpfs directory.
	Files []File `json:"-"`
	// Mounts are host paths the grant opens to the workload. Unlike Files
	// they are not written anywhere: the path already exists and the grant
	// is permission to reach it, so materialisation validates it and the
	// driver binds it.
	//
	// This one is not json:"-", because a mount carries no secret — a source
	// path and a read-only flag are exactly what an operator inspecting a
	// lease needs to see, and hiding them would make the one material kind
	// with no credential in it the hardest to audit.
	Mounts []RepoMount `json:"mounts,omitempty"`
	// Devices are host device nodes the grant opens to the workload. Like
	// Mounts they are not written anywhere — the node already exists and the
	// grant is permission to reach it — and like Mounts they are not
	// json:"-", because a device name, path and access mode are exactly what
	// an operator inspecting a lease needs to see and carry no credential.
	Devices []GrantedDevice `json:"devices,omitempty"`
	// Interfaces are host network interfaces the grant moves into the
	// sandbox. Not written anywhere either, and not json:"-" for the reason
	// Devices is not: a handle, a host name and an address are what an
	// operator inspecting a lease needs to see and carry no credential.
	Interfaces []GrantedInterface `json:"interfaces,omitempty"`
	// Summary is the audit-safe description of what was delivered
	// (surviving kubeconfig contexts, allowed registries, env key names).
	Summary string `json:"summary,omitempty"`
	// contains filtered or unexported fields
}

type MintRequest struct {
	Name     string
	Kind     Kind
	Payload  []byte
	Metadata map[string]string
	Actor    string
	// Owner, when set, mints a *personal* secret belonging to that identity
	// rather than a shared one belonging to the organisation (Task 20275).
	// See ownership.go for everything that changes as a result.
	Owner string
	// Personal asserts that this mint is meant to produce a personal secret.
	//
	// Redundant with a non-empty Owner in the success case, and that is the
	// point: it separates "mint this for alice@corp" from "mint this for
	// whatever identity the caller happened to resolve", so a handler whose
	// identity lookup silently returned "" produces ErrOwnerRequired instead
	// of quietly minting the user's private credential as an organisation-wide
	// one that every maintainer can then spend.
	Personal bool
}

type Mount struct {
	// Dir is the lease directory. Mode 0700, on a tmpfs where one is
	// available.
	Dir string
	// contains filtered or unexported fields
}

type Option func(*Broker)

type RepoMount struct {
	// Name is the repository's directory name under the granted root, and
	// the handle a workload refers to it by.
	Name string `json:"name"`
	// Source is the absolute host path. Always inside the granted root:
	// selectRepos resolves symlinks before accepting one, so a symlink
	// planted under the root cannot redirect the bind out of it.
	Source string `json:"source"`
	// Target is the absolute path the repository appears at in the sandbox.
	Target string `json:"target"`
	// ReadOnly mirrors the grant's Writable constraint, inverted, because
	// read-only is the default and a zero value should mean the safe thing.
	ReadOnly bool `json:"read_only,omitempty"`
}

type RequestFilter struct {
	// State, when set, keeps only requests in that state.
	State RequestState
	// RequestedBy, when set, keeps only that identity's requests. This is what
	// scopes the list for a caller who may file requests but not decide them.
	RequestedBy string
	// SecretRef, when set, keeps only requests for that secret.
	SecretRef string
	// PendingOnly keeps only requests still awaiting a decision, including
	// dropping ones whose deadline has passed but which no sweep has moved yet.
	PendingOnly bool
}

type RequestState string

type RequestStore interface {
	// PutAccessRequest inserts or replaces a request by ID.
	PutAccessRequest(r AccessRequest) error
	// GetAccessRequest returns one request, or a wrapped ErrRequestNotFound.
	GetAccessRequest(id string) (AccessRequest, error)
	// ListAccessRequests returns every request, including decided ones — the
	// broker filters, so a review UI can still see history.
	ListAccessRequests() ([]AccessRequest, error)
	// ExpireAccessRequests moves pending requests past their deadline to
	// expired and returns the ones it changed.
	ExpireAccessRequests(now time.Time) ([]AccessRequest, error)
	// RecordRequestUse notes that a lease redeemed an approved request's
	// grant, upserting on (request, lease).
	RecordRequestUse(u RequestUse) error
	// ListRequestUses returns the uses recorded against one request, or every
	// use when requestID is empty.
	ListRequestUses(requestID string) ([]RequestUse, error)
}

type RequestUse struct {
	RequestID  string `json:"request_id"`
	LeaseID    string `json:"lease_id"`
	GrantID    string `json:"grant_id,omitempty"`
	ExecutorID string `json:"executor_id,omitempty"`
	ProjectID  string `json:"project_id,omitempty"`
	// TaskID is the unit of work that held the lease, or 0 when the lease was
	// issued for a whole project run rather than one task.
	//
	// Zero at the moment the lease is issued and filled in afterwards: the hub
	// leases credentials *before* it dispatches the workload that will hold
	// them, so at lease time there is genuinely no task to name. See
	// statedb.AttributeRequestUseTasks.
	TaskID    int       `json:"task_id,omitempty"`
	FirstSeen time.Time `json:"first_seen"`
	LastSeen  time.Time `json:"last_seen"`
}

type Requester struct {
	ExecutorID string
	ProjectID  string
	Labels     map[string]string
	// RunID names the execution the credentials are for (Task 20282). It is
	// recorded on the audit rows this request produces and is deliberately
	// never matched against: a grant is issued to a project or an executor, not
	// to one run, so letting a run id participate in Subject.Matches would
	// invent an authority scope that operators cannot see, list or revoke.
	//
	// Empty for every non-dispatch caller — a CLI lease, a UI inspection — and
	// an empty run id simply leaves the field off the row.
	RunID string
	// GitHubProxied says the caller will hand any GitHub credential in this
	// lease to cloop's git proxy itself, and never to a workload — which is
	// what workspace provisioning does when the hub runs a proxy
	// (pkg/executor/gitproxycreds). Like RunID it is never matched against.
	//
	// It matters to exactly one decision: whether a grant limited to certain
	// branches may be delivered with its push intact. Without a proxy in the
	// path the broker withholds that push (Task 20340), because nothing else
	// can hold a push to the list; with one, the proxy does, and withholding
	// would break the very pushes the grant authorises.
	//
	// Set it only when it is true of every material the lease will carry. A
	// caller that set it and then materialised the lease into a sandbox would
	// be delivering a push the grant restricted, unrestricted.
	GitHubProxied bool
}

type RotateOptions struct {
	// NewKey mints a fresh KEK and promotes it before rewrapping. This is
	// the normal case: rotating onto the *current* primary is an upgrade of
	// stragglers, not a rotation.
	NewKey bool
	// Actor is recorded on the new key and the rotation record.
	Actor string
	// DryRun reports what would be rewrapped without writing anything.
	DryRun bool
}

type RotationRecord struct {
	ID         string    `json:"id"`
	ToKeyID    string    `json:"to_key_id"`
	State      string    `json:"state"`
	StartedAt  time.Time `json:"started_at"`
	UpdatedAt  time.Time `json:"updated_at"`
	FinishedAt time.Time `json:"finished_at,omitempty"`
	StartedBy  string    `json:"started_by,omitempty"`
	Total      int       `json:"total"`
	Rewrapped  int       `json:"rewrapped"`
	Skipped    int       `json:"skipped"`
	Failed     int       `json:"failed"`
	LastError  string    `json:"last_error,omitempty"`
}

type RotationReport struct {
	RotationID  string      `json:"rotation_id,omitempty"`
	TargetKeyID string      `json:"target_key_id"`
	Sets        []SetReport `json:"sets"`
	Rewrapped   int         `json:"rewrapped"`
	Skipped     int         `json:"skipped"`
	Failed      int         `json:"failed"`
	Complete    bool        `json:"complete"`
	DryRun      bool        `json:"dry_run,omitempty"`
}

type RotationStatus struct {
	PrimaryKeyID string           `json:"primary_key_id"`
	Keys         []KeyInfo        `json:"keys"`
	Usage        []KeyUsage       `json:"usage"`
	Legacy       int              `json:"legacy_rows"`
	LegacyOpen   bool             `json:"legacy_openable"`
	Unrotated    int              `json:"unrotated_rows"`
	Rotations    []RotationRecord `json:"rotations,omitempty"`
}

type RotationStore interface {
	PutRotation(r RotationRecord) error
	ListRotations(limit int) ([]RotationRecord, error)
}

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

type SealedRow struct {
	ID  string
	AAD string
	Env Envelope
}

type SealedSet interface {
	// SealedSetName identifies the set in reports ("secrets", "sessions").
	SealedSetName() string
	// CountSealedByKey returns row counts keyed by key ID, including
	// LegacyKeyID for pre-envelope rows.
	CountSealedByKey() (map[string]int, error)
	// ListSealedNotUnder returns up to limit rows whose key ID differs from
	// keyID. Order is unspecified; the rotator does not depend on it.
	ListSealedNotUnder(keyID string, limit int) ([]SealedRow, error)
	// ReplaceSealed swaps a row's envelope if and only if the stored one
	// still matches expect exactly. It reports whether the swap happened;
	// false is a normal outcome (a concurrent writer got there first), not
	// an error.
	ReplaceSealed(id string, expect, next Envelope) (bool, error)
}

type Secret struct {
	ID   string `json:"id"`
	Kind Kind   `json:"kind"`
	// Name is a human-facing unique handle ("prod-deploy-pat"). Grants are
	// created against it from the CLI.
	Name string `json:"name"`
	// Sealed is the AES-256-GCM ciphertext of the payload, encrypted under
	// this secret's own data key (see WrappedDEK). Never logged.
	Sealed []byte `json:"-"`
	// KeyID names the KEK that WrappedDEK is sealed under. LegacyKeyID means
	// the pre-envelope construction: WrappedDEK is empty and Sealed is
	// encrypted directly under the passphrase-derived key (Task 20181).
	//
	// It is exported because storage must persist it, and json:"-" because a
	// key ID in an API response tells a caller nothing they can act on while
	// telling an attacker which rows a stolen key still opens.
	KeyID string `json:"-"`
	// WrappedDEK is this secret's data key, sealed under KeyID. Rotation
	// rewrites this field and leaves Sealed untouched.
	WrappedDEK []byte `json:"-"`
	// Metadata is non-sensitive descriptive data (rotation date, ticket).
	// It is included in audit payloads, so callers must not put credential
	// material here.
	Metadata  map[string]string `json:"metadata,omitempty"`
	CreatedAt time.Time         `json:"created_at"`
	CreatedBy string            `json:"created_by,omitempty"`
	// Owner is the identity this secret belongs to personally, in the
	// OwnerKey namespace the rest of the hub uses for people (a lowercased
	// email, or "sub:<issuer subject>"). Empty means a shared secret: the
	// organisation's credential, provisioned by a maintainer, which is what
	// every secret was before Task 20275.
	//
	// It is deliberately not a Metadata entry. Metadata is operator free text
	// that lands in audit payloads and that nothing enforces; Owner is an
	// authorisation input read by VisibleTo and by every mutation path in the
	// broker. A rule enforced against a map any caller may overwrite is not a
	// rule, and the two have opposite handling: metadata is for humans to
	// read, Owner is for this package to obey.
	Owner string `json:"owner,omitempty"`
}

type SetReport struct {
	Name      string   `json:"name"`
	Rewrapped int      `json:"rewrapped"`
	Skipped   int      `json:"skipped"`
	Failed    int      `json:"failed"`
	Errors    []string `json:"errors,omitempty"`
}

type Store interface {
	// PutSecret inserts or replaces a secret by ID.
	PutSecret(s Secret) error
	// GetSecret returns the secret with the given ID, or a wrapped
	// ErrSecretNotFound.
	GetSecret(id string) (Secret, error)
	// ListSecrets returns every stored secret.
	ListSecrets() ([]Secret, error)
	// DeleteSecret removes a secret. Removing a secret that does not exist
	// returns a wrapped ErrSecretNotFound.
	DeleteSecret(id string) error

	// PutGrant inserts or replaces a grant by ID.
	PutGrant(g Grant) error
	// GetGrant returns the grant with the given ID, or a wrapped
	// ErrGrantNotFound.
	GetGrant(id string) (Grant, error)
	// ListGrants returns every stored grant, including expired and revoked
	// ones — the broker filters, so that callers listing for an audit UI
	// can still see history.
	ListGrants() ([]Grant, error)
	// RevokeGrant stamps a grant revoked at the given time. Revoking an
	// already-revoked grant is a no-op, not an error: revocation is
	// idempotent by design, because a caller racing to revoke twice must
	// not be told the second attempt failed.
	RevokeGrant(id string, at time.Time) error

	// Meta reads a broker-scoped metadata value.
	Meta(key string) (value string, ok bool, err error)
	// SetMeta writes a broker-scoped metadata value.
	SetMeta(key, value string) error
}

type Subject struct {
	Type SubjectType `json:"type"`
	// Value is the project path or executor ID for those types, "*" for a
	// wildcard within the type, and unused for label/any.
	Value string `json:"value,omitempty"`
	// Labels is the selector for SubjectLabel: every pair must be present
	// on the requester for the grant to match.
	Labels map[string]string `json:"labels,omitempty"`
}

type SubjectType string

type UnavailableGitGuard struct {
	// Reason is shown to the operator. It should name the configuration that
	// is not in effect, not merely say that something is missing.
	Reason string
}

type UnavailableKubeGuard struct {
	// Reason is shown to the operator. It should name the configuration that
	// is not in effect, not merely say that something is missing.
	Reason string
}

type Viewer struct {
	// Identity is the viewer's OwnerKey, matched against Secret.Owner. It
	// authorises everything about the viewer's own personal secrets and
	// nothing about anybody else's.
	Identity string

	// Admin marks a caller entitled to administer *other people's* personal
	// secrets: to see that alice@corp keeps one here, and to destroy it when
	// she leaves.
	//
	// It confers visibility and deletion, never use. Offboarding requires both,
	// and pretending an admin cannot see the row would be theatre — the
	// material is sealed under a key the hub operator already holds. Spending
	// somebody else's credential is a different act, it is the one thing the
	// ownership model exists to prevent, and no flag here enables it.
	Admin bool
}