authz

type Action string

type Authorizer interface {
	// Ready reports whether this authorizer is configured well enough to be
	// used. The controller refuses to start when it is not.
	//
	// This exists because the alternative failure mode is silent: an
	// unconfigured authorizer that merely rejects everything looks, to an
	// operator, exactly like a wrong token. A startup error names the problem.
	Ready() error

	// Authenticate resolves a request to a subject. An error is a 401.
	Authenticate(r *http.Request) (Subject, error)

	// Authorize reports whether s may perform act on the named application. An
	// empty application means the request is not scoped to one. An error is a
	// 403.
	Authorize(ctx context.Context, s Subject, act Action, application string) error

	// Visible narrows applications to the ones s may perform act on, in the
	// order it was given them. An authorizer with nothing to narrow returns its
	// input unchanged; an error is a 403, like Authorize's.
	//
	// It exists because Authorize answers about one application and the API has
	// two endpoints that answer about all of them — the list view and the event
	// stream. Authorising those once with an empty application is a decision
	// about the collection, not about its members, so an authorizer
	// implementing projects can only allow or deny the whole thing: a tenant
	// with read access to one application would enumerate every application's
	// name, repository URL, revision and error text.
	//
	// A separate method rather than a loop over Authorize because a companion
	// may back each decision with a policy engine, and a list endpoint should
	// cost one call rather than one per application. The event stream is the
	// other shape and keeps using Authorize: there the question really is about
	// one application at a time, as each event arrives.
	//
	// On this interface rather than beside it as an optional one, which is the
	// opposite of the call swarms makes for Lister and NodeReach — and the
	// difference is which way the absence fails. A registry that cannot
	// enumerate makes a sweep cover less; an authorizer that cannot narrow
	// would make a list disclose more, because the fallback for a missing
	// narrowing is to return everything. Authorisation may only degrade
	// closed, so there is no version of this a companion is allowed not to
	// implement.
	Visible(ctx context.Context, s Subject, act Action, applications []string) ([]string, error)
}

type Subject struct {
	// Name is who the subject is, for logs and for display. It is not a key:
	// nothing in this repository looks a subject up by it.
	Name string
	// Groups is whatever group, role or claim membership the authorizer
	// resolved. Every identity source this seam is likely to meet has the
	// concept — LDAP, OIDC, SAML — which is why it is named here rather than
	// left to Extra.
	Groups []string
	// Extra is the authorizer's own, carried from Authenticate to Authorize
	// unchanged.
	//
	// Nothing in this repository reads it, logs it, serialises it or copies
	// what it points at, and nothing ever will: it exists so that an
	// authorizer can carry state the core has no concept of — a tenant, a
	// licence entitlement, a decoded token — through core code, without that
	// concept having to be named in an Apache-2.0 tree that never uses it.
	//
	// The core treats the value as immutable. An implementation that puts a
	// pointer here gets the same pointer back.
	Extra any
}