offboard

type ClaudeHomeRef struct {
	// Member names the hub process keeping this copy: a cluster member id, or
	// "" for the process running the offboarding.
	Member string `json:"member,omitempty"`
	// OwnerKey is the spelling of the identity the directory is keyed by.
	OwnerKey string `json:"owner_key"`
	// Dir is the directory on that member's filesystem.
	Dir string `json:"dir"`
	// Exists, Credential and Login are what was found there: the directory,
	// a non-empty credential file in it, and a `claude auth login` in flight
	// for this spelling on that member.
	Exists     bool `json:"exists"`
	Credential bool `json:"credential"`
	Login      bool `json:"login,omitempty"`
}

type ClaudeHomeResult struct {
	ClaudeHomeRef
	// LoginCancelled reports that a login in flight was killed.
	LoginCancelled bool `json:"login_cancelled,omitempty"`
	// LoggedOut reports that `claude auth logout` ran and succeeded, which
	// revokes the session at Anthropic and not only on this disk.
	LoggedOut bool `json:"logged_out,omitempty"`
	// Logout says why logout did not run, or how it failed. Best-effort: the
	// directory is removed either way.
	Logout string `json:"logout,omitempty"`
	// Removed reports that the directory is gone.
	Removed bool `json:"removed,omitempty"`
	// Kept reports that a legal hold left the directory in place.
	Kept bool `json:"kept,omitempty"`
	// Error is what failed when the copy could not be removed.
	Error string `json:"error,omitempty"`
}

type ClaudeHomes interface {
	// Inspect finds every copy of these owner keys' logins it can reach, and
	// names the hub processes it could not.
	Inspect(ownerKeys []string) ([]ClaudeHomeRef, []ClaudeUnreached, error)
	// Sever cancels the logins in flight and, unless keep is set, logs each
	// copy out and removes it.
	Sever(ownerKeys []string, keep bool, actor, reason string) ([]ClaudeHomeResult, []ClaudeUnreached, error)
}

type ClaudeUnreached struct {
	Member string `json:"member"`
	Detail string `json:"detail"`
}

type Credentials struct {
	Secrets  []PersonalSecretRef `json:"secrets"`
	Grants   []PersonalGrantRef  `json:"grants"`
	Requests []GrantRequestRef   `json:"requests"`
	// Claude lists every copy of a Claude login found for the identity,
	// on every hub process the run could reach.
	Claude []ClaudeHomeRef `json:"claude"`
	// ClaudeUnreached lists the hub processes the run could not ask.
	ClaudeUnreached []ClaudeUnreached `json:"claude_unreached,omitempty"`

	// Keep reports a legal hold: the secrets and the Claude homes listed
	// above are kept, everything else is severed.
	Keep bool `json:"keep"`

	// SecretsError, RequestsError and ClaudeError say why a part of this
	// footprint could not be read. A run with one set reports it as a
	// failure: what could not be listed could not be destroyed.
	SecretsError  string `json:"secrets_error,omitempty"`
	RequestsError string `json:"requests_error,omitempty"`
	ClaudeError   string `json:"claude_error,omitempty"`
}

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 GrantRequestRef struct {
	ID          string    `json:"id"`
	RequestedBy string    `json:"requested_by"`
	SecretName  string    `json:"secret_name,omitempty"`
	Kind        string    `json:"kind,omitempty"`
	Subject     string    `json:"subject"`
	CreatedAt   time.Time `json:"created_at,omitempty"`
}

type HoldRef struct {
	Identity string    `json:"identity"`
	Reason   string    `json:"reason"`
	PlacedAt time.Time `json:"placed_at"`
	PlacedBy string    `json:"placed_by,omitempty"`
}

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"`
	// GrantIDs are the grants whose material the lease carries, so a lease on
	// somebody else's project holding this identity's personal credential can
	// be named in the plan (Task 20400).
	GrantIDs []string `json:"grant_ids,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 LocalClaude struct {
	// Manager holds this process's in-flight logins. Nil — a shell has none.
	Manager *claudecodeauth.Manager
	// Member labels the copies this process finds: its cluster member id, or
	// "" when it is the process running the offboarding.
	Member string
	// Root is where the homes are. Empty — production — is
	// claudecodeauth.HomeRootPath, from this process's own environment.
	// Set by tests that run two hub members in one process, where the
	// environment is shared and the trees must not be.
	Root string
	// OperatorShell marks the process as an operator's shell on the hub host —
	// `cloop hub user offboard` — rather than a hub acting on a request. The
	// host-execution policy governs what a hub runs on a request's behalf; a
	// person at a shell runs what they choose, and the logout revokes the
	// session at Anthropic, so a shell runs it whatever the policy — the same
	// on every host, rather than depending on which directory's config the
	// CLI happened to load. Never set by a hub.
	OperatorShell bool
	// OnLoginCancelled runs after a login in flight was killed, so a cluster
	// member can give up its claim on it.
	OnLoginCancelled func(ownerKey string)
	// Logout runs `claude auth logout` against one directory. Nil is
	// claudecodeauth.Logout; tests substitute it, because the real one talks
	// to Anthropic.
	Logout func(ctx context.Context, configDir string) error
	// LogoutTimeout bounds one logout. Zero is defaultLogoutTimeout.
	LogoutTimeout time.Duration
}

type MembershipRef struct {
	Path string `json:"path"`
	Role string `json:"role"`
	// Identity is the spelling the grant was recorded under. Worth keeping: a
	// grant found under "sub:…" is the one an email-only sweep would miss.
	Identity string `json:"identity"`
}

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, unless
	// Target is set.
	Identity string

	// Target is an identity its caller already resolved (Task 20415): a SCIM
	// directory, which knows the person by the claim it matches on and must
	// not be widened past an ambiguous match by the expansion an operator's
	// input gets. When set, Identity is only the label the trail records.
	Target *Target

	// 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

	// Secrets and Claude reach what the identity keeps on the hub (Task
	// 20400). Optional like the others: nil means that part is not checked,
	// and the plan says so.
	Secrets Secrets
	Claude  ClaudeHomes

	// KeepCredentials is a legal hold. Access is severed exactly as without
	// it — grants revoked, requests withdrawn, logins in flight cancelled —
	// but the personal secrets and the Claude homes are kept as they are, and
	// the plan and the trail say what was kept.
	KeepCredentials bool

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

type PersonalGrantRef struct {
	ID         string    `json:"id"`
	SecretID   string    `json:"secret_id"`
	SecretName string    `json:"secret_name,omitempty"`
	Subject    string    `json:"subject"`
	ExpiresAt  time.Time `json:"expires_at,omitempty"`
}

type PersonalSecretRef struct {
	ID        string    `json:"id"`
	Name      string    `json:"name"`
	Kind      string    `json:"kind"`
	Owner     string    `json:"owner,omitempty"`
	CreatedAt time.Time `json:"created_at,omitempty"`
}

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"`

	// Memberships are projects this identity can reach without owning them
	// (Task 20366). Unlike Projects these are removed, in the credential
	// transaction.
	Memberships []MembershipRef `json:"memberships"`

	// Credentials is what the identity keeps on the hub — personal secrets,
	// the grants over them, pending requests, Claude logins (Task 20400).
	// Destroyed after the transaction, or kept under a legal hold.
	Credentials Credentials `json:"credentials"`

	// Hold is the legal hold placed on this identity, when there is one
	// (Task 20415): it keeps the stored credentials whatever the run was
	// asked, so an offboarding nobody ran by hand — the identity provider
	// deleting the account — honours it too.
	Hold *HoldRef `json:"hold,omitempty"`

	// 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"`

	// MembershipsRevoked are the project memberships actually removed, in
	// the same transaction as the credentials (Task 20366).
	MembershipsRevoked []MembershipRef `json:"memberships_revoked,omitempty"`

	// What became of the stored credentials (Task 20400). Under a legal hold
	// SecretsKept replaces SecretsDeleted, and each Claude copy reports Kept.
	GrantsRevoked     []PersonalGrantRef  `json:"grants_revoked,omitempty"`
	SecretsDeleted    []PersonalSecretRef `json:"secrets_deleted,omitempty"`
	SecretsKept       []PersonalSecretRef `json:"secrets_kept,omitempty"`
	RequestsWithdrawn []GrantRequestRef   `json:"requests_withdrawn,omitempty"`
	ClaudeResults     []ClaudeHomeResult  `json:"claude_results,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 Secrets interface {
	// Owned reports the personal secrets owned by any of these owner keys,
	// and every live grant over them.
	Owned(ownerKeys []string) ([]PersonalSecretRef, []PersonalGrantRef, error)
	// Pending reports the requests still awaiting a decision that were filed
	// by any of these identities.
	Pending(requesters []string) ([]GrantRequestRef, error)
	// RevokeGrant revokes one grant.
	RevokeGrant(id, actor, reason string) error
	// DeleteSecret destroys one secret: its sealed material, and every grant
	// still pointing at it.
	DeleteSecret(id, actor, reason string) error
	// WithdrawRequest withdraws one pending request on behalf of its departed
	// requester, reporting false when it had already been decided.
	WithdrawRequest(id, actor, reason string) (bool, error)
}

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"`
	// Kind is browser or cli: a terminal signed in with `cloop login` holds a
	// session like a browser does, and is severed with it (Task 20412).
	Kind string `json:"kind,omitempty"`
	// Username and OID are the preferred_username and oid claims the session
	// signed in with (Task 20415).
	Username string `json:"username,omitempty"`
	OID      string `json:"oid,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"`

	// Usernames and OIDs are preferred_username and Entra oid values that
	// address this person too (Task 20415). Only a SCIM directory matching on
	// one of those claims puts them here: they are what the identity provider
	// deactivated, and a deny binding on them refuses a sign-in that carries
	// neither a known subject nor a known email. Lowercased.
	Usernames []string `json:"usernames,omitempty"`
	OIDs      []string `json:"oids,omitempty"`
}

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"`
}