offboard

type DenyRef struct {
	ID    string `json:"id"`
	Claim string `json:"claim"`
	Value string `json:"value"`
}

type Failure struct {
	Surface string `json:"surface"`
	Detail  string `json:"detail"`
}

type LeaseRef struct {
	ID         string    `json:"id"`
	ExecutorID string    `json:"executor_id,omitempty"`
	ProjectID  string    `json:"project_id,omitempty"`
	Kinds      []string  `json:"kinds,omitempty"`
	ExpiresAt  time.Time `json:"expires_at,omitempty"`
}

type Leases interface {
	// LiveLeases reports every lease the broker would still honour.
	LiveLeases() []LeaseRef
	// Release ends one lease and destroys any credentials minted under it.
	Release(id string)
}

type Options struct {
	// DB is the hub's control-plane database. Required.
	DB *statedb.DB

	// Identity is the email or subject the operator typed. Required.
	Identity string

	// Reason is recorded on every audit event. Required: an offboarding with
	// no stated cause is not reviewable, and the reviewability is the point.
	Reason string

	// Actor is who is doing this — an operator's email, or an OS user for CLI
	// runs.
	Actor string

	// Via distinguishes "cli" from "ui" in the trail.
	Via string

	// DryRun resolves and reports without writing anything.
	DryRun bool

	// Leases, Tasks and Projects are optional. A nil collaborator means that
	// surface is skipped, and the report says so rather than implying it was
	// clean.
	Leases   Leases
	Tasks    Tasks
	Projects Projects

	// Sessions is the live session authority. Strongly preferred where one
	// exists — see the interface doc.
	Sessions Sessions

	// Now is the clock, swappable in tests.
	Now func() time.Time
}

type Plan struct {
	Target   Target       `json:"target"`
	Sessions []SessionRef `json:"sessions"`
	Tokens   []TokenRef   `json:"tokens"`
	Glasses  []TokenRef   `json:"glasses"`
	Denies   []DenyRef    `json:"denies"`
	Leases   []LeaseRef   `json:"leases"`
	Tasks    []TaskRef    `json:"tasks"`
	Projects []ProjectRef `json:"projects"`

	// Warnings name things the run cannot be sure about — most importantly
	// tokens whose owner binding did not decode, which cannot be proven *not*
	// to belong to this person.
	Warnings []string `json:"warnings,omitempty"`
}

type ProjectRef struct {
	Name  string `json:"name"`
	Path  string `json:"path"`
	Owner string `json:"owner,omitempty"`
}

type Projects interface {
	// Owned reports projects whose owner is any of the given owner keys.
	Owned(ownerKeys []string) ([]ProjectRef, error)
}

type Report struct {
	Plan
	DryRun bool      `json:"dry_run"`
	Actor  string    `json:"actor,omitempty"`
	Reason string    `json:"reason,omitempty"`
	At     time.Time `json:"at"`

	SessionsRevoked []string  `json:"sessions_revoked,omitempty"`
	TokensRevoked   []string  `json:"tokens_revoked,omitempty"`
	GlassesRevoked  []string  `json:"glasses_revoked,omitempty"`
	DeniesWritten   []string  `json:"denies_written,omitempty"`
	LeasesReleased  []string  `json:"leases_released,omitempty"`
	TasksStopped    []TaskRef `json:"tasks_stopped,omitempty"`

	// Failures is non-empty when a surface could not be severed. The run does
	// not abort on one: a lease that will not release is not a reason to leave
	// the sessions live. The caller decides what a partial run means, and both
	// front ends report it as an error with the detail attached.
	Failures []Failure `json:"failures,omitempty"`
}

type SessionRef struct {
	ID        string    `json:"id"`
	Subject   string    `json:"subject,omitempty"`
	Email     string    `json:"email,omitempty"`
	IP        string    `json:"ip,omitempty"`
	IssuedAt  time.Time `json:"issued_at,omitempty"`
	ExpiresAt time.Time `json:"expires_at,omitempty"`
}

type Sessions interface {
	// List reports every live session.
	List() ([]SessionRef, error)
	// Revoke ends one session and drops it from any in-process cache.
	// It reports whether a session was actually ended.
	Revoke(id, actor, reason string) (bool, error)
}

type Target struct {
	// Input is what the operator typed, preserved for the audit trail.
	Input string `json:"input"`

	// Key is the canonical owner key: lowercased email, or "sub:"+Subject.
	// This is what project ownership rows are recorded under.
	Key string `json:"key"`

	// Subjects and Emails are every identifier found to belong to this person.
	// Emails are lowercased; subjects are opaque and compared exactly.
	//
	// Always serialised, even when empty: a front end rendering "resolved to"
	// needs to distinguish "no subject" from a field that was omitted, and
	// omitempty would make an identity this hub has never seen indistinguishable
	// from a decoding bug.
	Subjects []string `json:"subjects"`
	Emails   []string `json:"emails"`
}

type TaskRef struct {
	ProjectPath string `json:"project_path"`
	ProjectName string `json:"project_name,omitempty"`
	ID          int    `json:"id"`
	Title       string `json:"title,omitempty"`
	Status      string `json:"status,omitempty"`

	// Attempt names the execution observed, so a kill filed here cannot land on
	// a later attempt of the same task (Task 20203). Not serialised: it is an
	// internal fencing token, not something an operator reads.
	Attempt string `json:"-"`
}

type Tasks interface {
	// Running reports in-flight tasks for one project path.
	Running(projectPath string) ([]TaskRef, error)
	// Stop requests that the named execution be killed. The ref carries the
	// attempt token, so the request cannot land on a later attempt.
	Stop(t TaskRef, actor, reason string) error
}

type TokenRef struct {
	ID        string    `json:"id"`
	Name      string    `json:"name,omitempty"`
	Prefix    string    `json:"prefix,omitempty"`
	Kind      string    `json:"kind,omitempty"`
	Owner     string    `json:"owner,omitempty"`
	Roles     []string  `json:"roles,omitempty"`
	ExpiresAt time.Time `json:"expires_at,omitempty"`
}