apitoken

type Delegator struct {
	// Decision is the minter's own resolved authority, evaluated at the
	// global scope. Global rather than per-project because a token is a
	// fleet-level object: it is not created "inside" a project, and
	// resolving against one would let a caller who is maintainer on a single
	// project mint a hub-wide maintainer credential.
	Decision authz.Decision

	// ProjectScope is non-empty when the minter is itself a project-scoped
	// token. A scoped minter may only issue tokens at least as narrow.
	ProjectScope []string

	// Unrestricted marks a caller whose authority is not expressible as a
	// permission set — the OIDC-disabled local operator, and the static
	// bearer token. Both already act as the deployment itself, so bounding
	// them against their own (allow-all) decision would be theatre. Recorded
	// as a distinct flag rather than inferred, so the bypass is visible at
	// every call site instead of hiding inside an allow-all Decision.
	Unrestricted bool
}

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

type MintOptions struct {
	// Name is the operator-supplied label. Required: an unnamed credential
	// is one nobody can decide whether to revoke.
	Name string

	// Roles are the authz roles the bearer acts with. Required — a token
	// with no role can authenticate and do nothing, which is a support
	// ticket, not a security posture.
	Roles []string

	// ProjectScope optionally restricts which projects the token may
	// address, by registry name or filesystem path.
	ProjectScope []string

	// CreatedBy records the acting identity for the audit trail.
	CreatedBy string

	// ExpiresAt is when the token stops working. Zero means never, which
	// callers should discourage but which the model permits: an edge device
	// that cannot be re-provisioned needs a credential that outlives the
	// operator's calendar.
	ExpiresAt time.Time

	// Kind labels a hub-issued token; "" for an ordinary PAT.
	Kind string

	// Owner binds the token to the identity it acts for. See Token.Owner.
	Owner *Owner

	// Now overrides the clock, for tests.
	Now time.Time
}

type Minted struct {
	Token Token

	// Plaintext is the full `cloop_pat_<id>_<secret>` string. It exists only
	// in this struct and only until the caller returns it; nothing in cloop
	// stores it, and no later API call can retrieve it.
	Plaintext string
}

type Owner struct {
	Sub    string   `json:"sub,omitempty"`
	Email  string   `json:"email,omitempty"`
	Name   string   `json:"name,omitempty"`
	Groups []string `json:"groups,omitempty"`
	Roles  []string `json:"roles,omitempty"`
}

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

type Store interface {
	// Put writes a newly minted token. It must reject a duplicate ID rather
	// than overwrite: rewriting a live credential's roles is a privilege
	// change nobody asked for.
	Put(Token) error

	// Get returns the token with id, or an error wrapping ErrNotFound.
	Get(id string) (Token, error)

	// List returns every token, newest first, including revoked and expired
	// ones.
	List() ([]Token, error)

	// Revoke stamps a token as withdrawn. Revoking twice is a no-op success;
	// revoking an unknown id must wrap ErrNotFound.
	Revoke(id string, at time.Time) error

	// Touch records a token's last use. Called off the verification path;
	// failures are advisory.
	Touch(id string, at time.Time) error
}

type Token struct {
	ID           string
	Name         string
	Hash         string
	Prefix       string
	Roles        []string
	ProjectScope []string
	CreatedBy    string
	CreatedAt    time.Time
	ExpiresAt    time.Time
	LastUsedAt   time.Time
	RevokedAt    time.Time

	// Kind is "" for an ordinary PAT, or one of the Kind* constants.
	Kind string

	// Owner is set on a token minted on a user's behalf. When present, the
	// token's authority is the *intersection* of its own roles and whatever
	// the owner may currently do — see authz.Intersect and the ui package's
	// grant.decide. Roles alone are a ceiling, never a grant.
	Owner *Owner

	// OwnerUnreadable marks a row whose stored owner binding did not decode.
	// Only List sets it: the verification path refuses such a row outright
	// (see SQLStore.Get), but a listing has to keep showing it or an operator
	// would have no surface from which to revoke it. A token carrying this
	// flag must never be treated as unbound — "we cannot tell whose this is"
	// is not the same answer as "it belongs to nobody".
	OwnerUnreadable bool
}