policy

type AWSMatcher struct {
	// Account is the 12-digit AWS account id. Exact and required: a role
	// name means nothing without its account, and a pattern here would let
	// a role of that name in any account at all be admitted.
	Account string `yaml:"account"`
	// Role is the role's name, without its path. A glob in the sense of
	// path.Match.
	Role string `yaml:"role,omitempty"`
	// Path is the role's IAM path, `/` for a role with none and
	// `/service/team/` otherwise: leading and trailing slash, as AWS spells
	// it. A glob where `*` does not cross a `/`, so `/service/*/` is one
	// level; leave it out to match any path.
	Path string `yaml:"path,omitempty"`
	// Function pins the Lambda function the token was requested from, by
	// ARN (a glob). A role shared by several functions is admitted as a
	// role; this is for the rule that must admit one of them only. A
	// proof that carries no function never matches a rule that sets it.
	Function string `yaml:"function,omitempty"`
	// OrgID pins the AWS Organizations id of the account (a glob).
	OrgID string `yaml:"org_id,omitempty"`
}

type AWSRole struct {
	// Account is the 12-digit account id, taken from the configured row
	// that verified the token and cross-checked with the token's own
	// claim and the ARN.
	Account string
	// Name is the role's name without its path.
	Name string
	// Path is the role's IAM path: `/`, or `/service/team/`.
	Path string
	// OrgID is the account's AWS Organizations id, when the token states
	// one. Audit and matching only.
	OrgID string
	// Function is the Lambda function ARN the token was requested from,
	// when it says so. It qualifies a matcher and is recorded; it is never
	// the subject.
	Function string
}

type Access struct {
	Lifetimes       map[string]Duration    `yaml:"lifetimes,omitempty"`
	Groups          []AccessGroup          `yaml:"groups,omitempty"`
	People          []AccessPerson         `yaml:"people,omitempty"`
	Slack           []AccessWorkspace      `yaml:"slack,omitempty"`
	GitHub          []AccessOrg            `yaml:"github,omitempty"`
	Vocabulary      *AccessVocabulary      `yaml:"vocabulary,omitempty"`
	Clients         []AccessClient         `yaml:"clients,omitempty"`
	ClientDocuments *AccessClientDocuments `yaml:"clientDocuments,omitempty"`
	Resources       []AccessResource       `yaml:"resources,omitempty"`
}

type AccessAWSRole struct {
	Account string `yaml:"account,omitempty"`
	Role    string `yaml:"role,omitempty"`
	Path    string `yaml:"path,omitempty"`
}

type AccessClient struct {
	Name              string         `yaml:"name"`
	Kind              string         `yaml:"kind"`
	DisplayName       string         `yaml:"displayName,omitempty"`
	Description       string         `yaml:"description,omitempty"`
	Secret            string         `yaml:"secret,omitempty"`
	SecretKey         string         `yaml:"secretKey,omitempty"`
	Redirects         []string       `yaml:"redirects,omitempty"`
	SignedOut         []string       `yaml:"signedOut,omitempty"`
	BackchannelLogout string         `yaml:"backchannelLogout,omitempty"`
	TTLCap            Duration       `yaml:"ttlCap,omitempty"`
	SigningAlg        string         `yaml:"signingAlg,omitempty"`
	GroupsDelimiter   string         `yaml:"groupsDelimiter,omitempty"`
	SignInExchange    bool           `yaml:"signInExchange,omitempty"`
	Requires          []string       `yaml:"requires,omitempty"`
	Groups            GroupsOverride `yaml:"groups,omitempty"`
	Session           string         `yaml:"session,omitempty"`

	Hostname string `yaml:"hostname,omitempty"`
	Prefix   string `yaml:"prefix,omitempty"`
	Mount    string `yaml:"mount,omitempty"`
	Cluster  string `yaml:"cluster,omitempty"`
	Proxy    any    `yaml:"proxy,omitempty"`
	Deliver  any    `yaml:"deliver,omitempty"`
}

type AccessClientDocuments struct {
	Origins  []string       `yaml:"origins,omitempty"`
	Requires []string       `yaml:"requires,omitempty"`
	TTLCap   Duration       `yaml:"ttlCap,omitempty"`
	Groups   GroupsOverride `yaml:"groups,omitempty"`
	Session  string         `yaml:"session,omitempty"`
}

type AccessDocument struct {
	// Version is the policy schema's, as in [Policy.Version].
	Version int `yaml:"version"`
	// Access is the derived part, the same for every installation of an
	// estate.
	Access Access `yaml:"access"`
	// Overlay is the part that is this installation's own: how it is
	// reached before a directory can vouch for anybody, and the clients
	// that are not relying parties of the access matrix.
	Overlay AccessOverlay `yaml:"overlay,omitempty"`
}

type AccessGitHubJob struct {
	Repository     string `yaml:"repository,omitempty"`
	Owner          string `yaml:"owner,omitempty"`
	Visibility     string `yaml:"visibility,omitempty"`
	Ref            string `yaml:"ref,omitempty"`
	RefType        string `yaml:"ref_type,omitempty"`
	EventName      string `yaml:"event_name,omitempty"`
	WorkflowRef    string `yaml:"workflow_ref,omitempty"`
	JobWorkflowRef string `yaml:"job_workflow_ref,omitempty"`
}

type AccessGitHubTeam struct {
	Slug        string   `yaml:"slug"`
	Members     []string `yaml:"members,omitempty"`
	Maintainers []string `yaml:"maintainers,omitempty"`
}

type AccessGroup struct {
	Name string `yaml:"name"`
	// Members are directory groups.
	Members []string `yaml:"members,omitempty"`
	// Emails admit one signed-in address each.
	Emails []string `yaml:"emails,omitempty"`
	// GitHub admits a CI job by what its verified token says. Only the
	// fields below are carried; a derivation that needs another asks for
	// it here, in the open.
	GitHub []AccessGitHubJob `yaml:"github,omitempty"`
	// ServiceAccounts admit one ServiceAccount on one named cluster.
	ServiceAccounts []ServiceAccountMatcher `yaml:"service_accounts,omitempty"`
	// AWS admits one IAM role in one registered account.
	AWS []AccessAWSRole `yaml:"aws,omitempty"`
}

type AccessOrg struct {
	Org     string             `yaml:"org"`
	Members []string           `yaml:"members,omitempty"`
	Teams   []AccessGitHubTeam `yaml:"teams,omitempty"`
	Ignore  []string           `yaml:"ignore,omitempty"`
}

type AccessOverlay struct {
	// Groups add matchers to a group, appended after what the access
	// matrix derived. A group the matrix never produced is created with
	// only these: the matrix describes people, so a workload rule has
	// nothing there to attach to.
	Groups map[string]OverlayGroup `yaml:"groups,omitempty"`
	// Clients are declared in full. An id the access part also declares
	// is refused, not merged.
	Clients map[string]Client `yaml:"clients,omitempty"`
}

type AccessPerson struct {
	Name      string   `yaml:"name"`
	Addresses []string `yaml:"addresses,omitempty"`
}

type AccessResource struct {
	ID              string         `yaml:"id"`
	DisplayName     string         `yaml:"displayName,omitempty"`
	Description     string         `yaml:"description,omitempty"`
	Requires        []string       `yaml:"requires,omitempty"`
	TTLCap          Duration       `yaml:"ttlCap,omitempty"`
	AbsoluteCap     Duration       `yaml:"absoluteCap,omitempty"`
	ReadOnly        bool           `yaml:"readOnly,omitempty"`
	SigningAlg      string         `yaml:"signingAlg,omitempty"`
	GroupsDelimiter string         `yaml:"groupsDelimiter,omitempty"`
	Groups          GroupsOverride `yaml:"groups,omitempty"`
}

type AccessRole struct {
	Name    string   `yaml:"name"`
	Scopes  []string `yaml:"scopes,omitempty"`
	Implies []string `yaml:"implies,omitempty"`
}

type AccessScope struct {
	Name      string `yaml:"name"`
	Sensitive bool   `yaml:"sensitive,omitempty"`
}

type AccessSlackChannel struct {
	Name    string   `yaml:"name"`
	Private bool     `yaml:"private,omitempty"`
	Mode    string   `yaml:"mode,omitempty"`
	Adopt   string   `yaml:"adopt,omitempty"`
	Ignore  []string `yaml:"ignore,omitempty"`
	From    []string `yaml:"from,omitempty"`
}

type AccessThing struct {
	Name   string       `yaml:"name"`
	Scopes []string     `yaml:"scopes,omitempty"`
	Roles  []AccessRole `yaml:"roles,omitempty"`
}

type AccessVocabulary struct {
	Scopes []AccessScope `yaml:"scopes,omitempty"`
	Things []AccessThing `yaml:"things,omitempty"`
}

type AccessWorkspace struct {
	Workspace string               `yaml:"workspace"`
	Channels  []AccessSlackChannel `yaml:"channels,omitempty"`
}

type Client struct {
	// Kind is public, confidential or exchange.
	Kind string `yaml:"kind"`
	// DisplayName is what a person is told they are signing in to: "Sign
	// in to continue to Argo CD". Optional; see [Client.Title] for what
	// is shown without one.
	//
	// The id is the audience and is spelled for machines. A person who
	// arrives on the sign-in page redirected from somewhere else needs to
	// recognise where they are going, and a page that cannot say is the
	// shape of a phishing page.
	//
	// SHOWN TO ANYONE who starts a sign-in for this client, before they
	// have proved who they are. It is not a place for anything a stranger
	// should not read.
	DisplayName string `yaml:"display_name,omitempty"`
	// Description is one line under the name on the sign-in page: what
	// the application is for. Optional, and public in exactly the way
	// DisplayName is.
	Description string `yaml:"description,omitempty"`
	// Secret is how a confidential client gets its secret: a name, which
	// the installation delivers as an input (`clients/<id>/secret`), or
	// `{generate: true}`, which has the issuer make one and keep it with
	// its credentials. The secret itself is never in this file. See
	// [ClientSecret].
	Secret ClientSecret `yaml:"secret,omitempty" json:"secret,omitempty"`
	// Redirects are the allowed redirect URIs.
	Redirects []string `yaml:"redirects,omitempty"`
	// SignedOut are the allowed landing pages after an RP-initiated
	// sign-out (OIDC RP-Initiated Logout `post_logout_redirect_uri`).
	//
	// A separate list from Redirects on purpose. A redirect URI is where
	// a code is delivered -- `/oauth2/callback`, a path that starts a
	// sign-in; a post-logout URI is where a person is put down once their
	// session is gone, which is the application's front page. Sending
	// somebody to the callback after signing out starts the login they
	// just ended, and an open-redirect check that accepts either list
	// checks nothing about the difference.
	SignedOut []string `yaml:"signed_out,omitempty"`
	// Requires lists internal groups, any one of which admits a caller. A
	// caller in none is refused before a token exists.
	Requires []string `yaml:"requires,omitempty"`
	// TTLCap caps the lifetime the groups would otherwise grant.
	TTLCap Duration `yaml:"ttl_cap,omitempty"`
	// SignInExchange lets a person's sign-in to this client be traded for
	// a token for another client: `sluisctl login`, then `sluisctl
	// kube-token` or `sluisctl aws`. Only the access token of a live
	// session qualifies, presented by this same client, and what it opens
	// is still decided by the TARGET client's `requires`.
	//
	// Off everywhere else: a token issued to a relying party is for that
	// party. Only a public client may carry it -- a CLI on the person's own
	// machine, whose tokens go nowhere but back to this issuer.
	SignInExchange bool `yaml:"sign_in_exchange,omitempty"`
	// BackChannelLogout is where this client is TOLD that a session it
	// holds has ended (OIDC Back-Channel Logout 1.0). The issuer posts a
	// signed logout token there, server to server, at the moment of
	// sign-out.
	//
	// OPT-IN, per client, and that is what makes it safe to serve: a
	// client that names no address is never contacted and behaves
	// exactly as before. Nothing here forces a relying party to
	// implement anything.
	//
	// It is the only one of the three optional logout mechanisms worth
	// having. Session Management and Front-Channel both work by putting
	// an iframe from this origin inside the application's page, which
	// browsers now block by default; this is a POST between two servers
	// and does not care what the browser allows. It is also the only one
	// that can reach a proxy, which is what actually holds the session
	// for a console that runs no OpenID flow of its own.
	BackChannelLogout string `yaml:"backchannel_logout_uri,omitempty"`
	// SigningAlg pins which algorithm a token FOR THIS CLIENT is signed
	// with: an ID token always, an access token whenever this client is
	// its own audience (no `resource` named). Empty uses the installation
	// default -- today's one key's algorithm, ES384 in the chart. One of
	// [SigningAlgs]; refused at PARSE time if it is not, and refused at
	// ISSUER START if this installation configures no key for it -- see
	// [Client.validate] and [issuer.NewStorage].
	//
	// It exists because relying parties do not all keep up: OIDC Core
	// 15.1 expects a provider to be ABLE to sign with RS256, and EKS's
	// associated OIDC provider and Kargo's verifier accept nothing else.
	// Rather than pin the whole installation to the slowest relying
	// party forever, this is the one row that asks for it.
	SigningAlg string `yaml:"signing_alg,omitempty"`
	// Groups overrides which of a caller's held groups a token for this
	// client carries, beyond whatever [Client.Requires]'s own
	// <scope>:<thing> pairs already keep -- see [Policy.ScopeGroups] and
	// docs/decisions/0006-groups-claim-scoped-per-audience.md. Empty asks
	// for nothing beyond that pair matching. NOT YET APPLIED to a minted
	// token: `groupsScoping` governs whether this is only computed and
	// logged (`report`, the only mode this release ships) or actually
	// narrows a token (`enforce`, refused at load for now).
	Groups GroupsOverride `yaml:"groups,omitempty"`
	// GroupsDelimiter rewrites every `:` in each group name a token FOR
	// THIS CLIENT carries under `groups` to this string instead -- after
	// [Policy.ScopeGroups] has already decided which groups survive, never
	// changing which ones do. Empty (the default) leaves `groups` exactly
	// as every other audience sees it, the grant's own `:`. One of
	// [Client.SigningAlg]'s shape one row over: a per-audience exception
	// for a relying party this installation does not control, refused at
	// PARSE time if it could ever make two of this policy's own group
	// names collide -- see [validGroupsDelimiter] and
	// [Policy.checkGroupsDelimiterCollision].
	//
	// It exists for exactly one relying party today: opkssh's server-side
	// policy, `oidc:groups:<value>`, splits its own argument on EVERY `:`
	// and compares only the last segment -- so it can never match a group
	// named `<scope>:<thing>:<role>`, this schema's own separator, however
	// it is quoted. Until that is fixed upstream, an opkssh-facing client
	// may pin `groups_delimiter: "."` (or another delimiter this schema
	// accepts) so its tokens carry `env.ssh.admin` instead of
	// `env:ssh:admin` -- a name opkssh's own splitting can actually read.
	// See docs/decisions/0015-a-per-audience-groups-delimiter-for-opkssh.md
	// and docs/reference/sluis/policy.md#groups-delimiter-per-audience-opkssh-interop.
	GroupsDelimiter string `yaml:"groups_delimiter,omitempty"`
	// Session is the class of the refresh chains this client opens:
	// [SessionInteractive] (absent) or [SessionAgent]. An agent chain is
	// held to the service configuration's `lifetimes.agent` rather than to
	// the installation's absolute limit, and its access and ID tokens to
	// `lifetimes.agent.access`. The class is decided when an authorization
	// completes and recorded on the chain, so a later change here never
	// changes the class of a chain already open. Refused on an exchange
	// client, which opens no chain with an `auth_time`, and as `agent`
	// together with [Client.SignInExchange]. See
	// docs/decisions/0040-agent-class-sessions.md.
	Session string `yaml:"session,omitempty"`
}

type ClientDocuments struct {
	// Origins are the hosts that may serve a document. A host, or a host
	// and port; never a scheme, a path or a wildcard — the scheme is
	// always HTTPS and a path would be a client, not an origin.
	//
	// Empty turns the whole mechanism off, which is the default: an
	// installation that has not named a host does not accept documents.
	Origins []string `yaml:"origins,omitempty"`
	// Requires lists internal groups, any one of which admits a caller to
	// EVERY document client. It is the same gate a declared client's
	// `requires` is, and it is mandatory: turning this mechanism on
	// without saying who may use it would admit every person who can sign
	// in at all, which is not a decision anybody would make on purpose.
	Requires []string `yaml:"requires,omitempty"`
	// TTLCap caps the lifetime of a document client's tokens, as
	// `ttl_cap` does on a declared client. Optional, and worth setting:
	// these tokens go to software this installation did not deploy.
	TTLCap Duration `yaml:"ttl_cap,omitempty"`
	// Groups overrides which of a caller's held groups a token for EVERY
	// document client carries, beyond whatever [ClientDocuments.Requires]'s
	// own <scope>:<thing> pairs already keep -- the same key, the same
	// shape and the same validation as [Client.Groups] and
	// [Resource.Groups], one row over: see [Policy.ScopeGroups].
	Groups GroupsOverride `yaml:"groups,omitempty"`
	// Session is the class of the refresh chains EVERY document client
	// opens, as `session` is on a declared client: [SessionInteractive]
	// (absent) or [SessionAgent]. It is the installation's grant and never
	// the document's: the issuer reads no class from a fetched document. An
	// installation that needs one document client interactive and another
	// agent declares one of them as a client row, and an origin admitted
	// with `session: agent` must serve only documents its vendor controls,
	// because every document on it gets the class. See
	// docs/decisions/0040-agent-class-sessions.md.
	Session string `yaml:"session,omitempty"`
}

type ClientSecret struct {
	// Name is the input's name; empty when Generate is set.
	Name string
	// Generate says the issuer makes the secret.
	Generate bool
}

type ClientView struct {
	ID string
	Client
}

type Duration time.Duration

type Fragment map[string]any

type GitHubClaims struct {
	Repository  string
	Owner       string
	Ref         string
	Workflow    string
	Environment string
	// Visibility is the repository's visibility: public, private or
	// internal.
	Visibility string
	// WorkflowRef is the workflow file the run was started from, at the
	// ref it was read at: `org/repo/.github/workflows/release.yml@refs/heads/main`.
	WorkflowRef string
	// JobWorkflowRef is the workflow file the JOB is defined in. It
	// differs from WorkflowRef in a reusable workflow, and it is the one
	// that says which code holds the token.
	JobWorkflowRef string
	// SHA is the commit the run is for.
	SHA string
	// EventName is what started the run: push, pull_request,
	// workflow_dispatch...
	EventName string
	// RefType is branch or tag.
	RefType string
}

type GitHubMatcher struct {
	Repository  string `yaml:"repository,omitempty"`
	Owner       string `yaml:"owner,omitempty"`
	Ref         string `yaml:"ref,omitempty"`
	Workflow    string `yaml:"workflow,omitempty"`
	Environment string `yaml:"environment,omitempty"`
	// Visibility is the repository's: public, private or internal, as
	// GitHub states it in the token. `{owner: org, visibility: private}`
	// is every private repository of an organisation — which a fork's run
	// is not, because a fork is another repository.
	Visibility string `yaml:"visibility,omitempty"`
	// WorkflowRef and JobWorkflowRef pin the workflow FILE a run was
	// started from and the one its job is defined in, each at its ref:
	// `org/repo/.github/workflows/release.yml@refs/heads/main`. A
	// repository and a branch admit every workflow on that branch; one
	// of these admits the one file somebody reviewed. Globs, like the
	// rest, where `*` does not cross a `/`.
	WorkflowRef    string `yaml:"workflow_ref,omitempty"`
	JobWorkflowRef string `yaml:"job_workflow_ref,omitempty"`
	// SHA is the commit, for a rule that admits exactly one.
	SHA string `yaml:"sha,omitempty"`
	// EventName is what started the run: `push`, `workflow_dispatch`...
	// Pinning it keeps a `pull_request` run of the same file out.
	EventName string `yaml:"event_name,omitempty"`
	// RefType is `branch` or `tag`.
	RefType string `yaml:"ref_type,omitempty"`
}

type GitHubOrg struct {
	// Members are internal groups whose holders belong in the
	// organisation itself. Being in a bound team implies organisation
	// membership, so this is for the people who should be members
	// without a team — and it is what keeps them from being removed as
	// somebody no binding accounts for.
	Members []string `yaml:"members,omitempty"`
	// Teams are the organisation's teams, keyed by SLUG rather than
	// display name: the slug is what the API takes and what a rename
	// leaves alone.
	Teams map[string]GitHubTeam `yaml:"teams,omitempty"`
	// Ignore are work addresses and GitHub logins the controller leaves
	// alone in this organisation, whatever the bindings say: an address in
	// a bound directory group that nobody can take out of it, a temporary
	// owner. An ignored address is never wanted here; an ignored login is
	// never added, removed or changed, linked or not. Removing the line
	// brings them back under the bindings.
	Ignore []string `yaml:"ignore,omitempty"`
}

type GitHubTeam struct {
	// Members are internal groups whose holders belong in the team.
	Members []string `yaml:"members,omitempty"`
	// Maintainers are internal groups whose holders maintain it.
	Maintainers []string `yaml:"maintainers,omitempty"`
}

type Group struct {
	// Members are directory group addresses, from any connected
	// workspace. A caller is in this group when the directory confirms,
	// authoritatively, that its account is in one of them.
	Members []string `yaml:"members,omitempty"`
	// Matchers are conditions on a verified proof. A machine is in a
	// group because its CI token or ServiceAccount matches; a person can
	// be too, by address or domain, which is the escape hatch for the day
	// before any directory group exists.
	Matchers []Matcher `yaml:"matchers,omitempty"`
}

type GroupView struct {
	Name     string
	Members  []Member
	Matchers []string
	Rules    []MatcherView
	Claims   Fragment
	Lifetime time.Duration
}

type GroupsOverride struct {
	// All carries every held group, exactly as every token does today.
	// Written as `groups: all`.
	All bool
	// Things additionally carries every held group beyond whatever
	// requires-pair matching already keeps, one entry at a time, written
	// as `groups: [entry, entry, ...]`. Each entry is one of three
	// shapes, tried in this order against a held name:
	//
	//   - the held name's THING (in ANY scope) -- `grafana` keeps
	//     `devel:grafana:viewer` and `prod:grafana:admin` alike;
	//   - for a two-segment name (`rung:<name>`, `emp:<slug>`, neither of
	//     which is a grant and so has no thing to name), its FAMILY --
	//     `emp` keeps every `emp:<slug>` held, `rung` every `rung:<name>`
	//     held, the same way a thing keeps every role of it;
	//   - the held name OUTRIGHT, in full (`rung:sre`), for one specific
	//     two-segment name rather than every one of its family.
	//
	// See [Policy.ScopeGroups] for exactly how a held name is matched
	// against these, and [Policy.checkGroupsOverride] for what an entry
	// must look like to validate.
	Things []string
}

type Held struct {
	// Group is the internal group's name — always concrete, even when it
	// was reached through a mapping wildcard or through inheritance.
	Group string
	// Via names what put the caller in it: the directory groups matched,
	// or the matcher, rendered for a person to read. Empty when Group was
	// reached only through inheritance (Implies is set instead).
	Via []string
	// Key is the Groups-table key that matched directly — equal to Group
	// for an ordinary key, and different for a mapping wildcard: matching
	// `*:k8s:admin` for `devel:k8s:admin` records Key="*:k8s:admin". Empty
	// when Group was reached only through inheritance.
	Key string
	// Implies is the concrete group whose role implied this one, one hop
	// at a time, per [Vocabulary]'s declared implies graph: holding
	// `devel:k8s:admin` where admin implies operator implies viewer
	// produces a `devel:k8s:viewer` [Held] with Implies="devel:k8s:operator",
	// not "…admin" — the direct parent, so a reader (the console,
	// eventually) walks the chain one link at a time rather than being
	// handed a root it has to trust. Empty when Group was held directly.
	Implies string
}

type Input struct {
	// Email of the signed-in account, when the proof is a sign-in.
	Email string
	// DirectoryGroups the hub reports for that account.
	DirectoryGroups []string
	// Authoritative reports whether the hub's answer may be acted on.
	// Membership never grants anything without it.
	Authoritative bool
	// GitHub carries a CI identity token's verified claims.
	GitHub *GitHubClaims
	// ServiceAccount carries a verified Kubernetes ServiceAccount.
	ServiceAccount *ServiceAccountRef
	// AWS carries a verified AWS IAM role.
	AWS *AWSRole
}

type Matcher struct {
	// GitHub matches a CI identity token's claims. Every set field must
	// match; values are glob patterns in the sense of path.Match.
	GitHub *GitHubMatcher `yaml:"github,omitempty"`
	// ServiceAccount matches a Kubernetes ServiceAccount exactly.
	ServiceAccount *ServiceAccountMatcher `yaml:"service_account,omitempty"`
	// AWS matches an AWS IAM role that proved itself with its outbound
	// identity federation token.
	AWS *AWSMatcher `yaml:"aws,omitempty"`
	// Email matches one signed-in address, case-insensitively.
	Email string `yaml:"email,omitempty"`
	// EmailDomain matches every signed-in address in a domain.
	EmailDomain string `yaml:"email_domain,omitempty"`
}

type MatcherView struct {
	Kind string
	Rule string
}

type Member struct {
	Address string
}

type OrgView struct {
	Org     string
	Members []string
	// Ignore are the addresses and logins the controller leaves alone.
	Ignore []string
}

type OverlayGroup struct {
	Matchers []Matcher `yaml:"matchers,omitempty"`
}

type Policy struct {
	// Version is the schema's version. 1 is the only one; an unknown
	// version is refused rather than guessed at.
	Version int `yaml:"version"`
	// Vocabulary declares which scopes, things and roles a grant name may
	// use, and each thing's role ladder. OPTIONAL: nil means what it
	// always meant — any `<scope>:<thing>:<role>` spelling is accepted,
	// unchecked. Declared, it makes every concrete grant anywhere in this
	// file (see [Policy.checkGrantName]) and every mapping wildcard in
	// [Policy.Groups] (see [Policy.checkGroupKey]) a claim the loader can
	// check instead of trust. See docs/reference/sluis/policy.md#vocabulary and
	// docs/reference/sluis/taxonomy.md.
	Vocabulary *Vocabulary `yaml:"vocabulary,omitempty"`
	// Groups is every internal group name an installation uses, and how a
	// caller comes to be in it. A key may be a mapping wildcard — `*` in
	// the scope and/or thing position — when [Policy.Vocabulary] is
	// declared; see [Policy.checkGroupKey].
	Groups map[string]Group `yaml:"groups,omitempty"`
	// Claims is what a group adds to a token. Sparse: a group that adds
	// only its own name is absent here.
	Claims map[string]Fragment `yaml:"claims,omitempty"`
	// Lifetimes is how long a token lives, keyed by group, plus the
	// "default" key. The shortest across a caller's groups wins.
	Lifetimes map[string]Duration `yaml:"lifetimes,omitempty"`
	// Resources are what a token may be minted FOR, when that is not the
	// client asking. Keyed by the resource indicator a client sends as
	// `resource`; see [Resource] for when the two differ.
	Resources map[string]Resource `yaml:"resources,omitempty"`
	// ClientDocuments admits clients that are not declared here at all,
	// by fetching a document they serve about themselves. Off unless it
	// names an origin; see [ClientDocuments] for why that is safe here.
	ClientDocuments ClientDocuments `yaml:"client_documents,omitempty"`
	// Clients is who may be issued a token for what. A client's id is the
	// audience.
	Clients map[string]Client `yaml:"clients,omitempty"`
	// GitHub binds internal groups to GitHub teams, keyed by the
	// organisation's login. It grants nothing here and appears
	// in no token: a controller reads it and makes each organisation's
	// membership match.
	//
	// It lives in this file for one reason — a reader of the access model
	// sees every GitHub team's source without opening another file — and
	// a team is a consumer of a group exactly as a client's `requires`
	// is: the holders of these groups are the people that team should
	// contain. Which accounts hold a group is a question only the
	// directory answers, so nothing about a provider appears here.
	GitHub map[string]GitHubOrg `yaml:"github,omitempty"`
	// People says which addresses are the same person — someone with an
	// address in two companies' domains — keyed by a name we choose:
	// `jdoe: [j.doe@acme.example, john@globex.example]`.
	//
	// It is generic, not Slack's: any reconciler that looks a person up by
	// their address in one domain and might hold them under another
	// benefits. And it only LINKS addresses. It never says who holds a
	// group — the directory alone answers that — so a person listed here
	// gains nothing until the directory puts one of their addresses in a
	// group, and is not removed from anything by being left out. See
	// [Policy.PeopleByAddress].
	People map[string][]string `yaml:"people,omitempty"`
	// Slack binds internal groups to Slack channels across one or more
	// workspaces. It grants nothing and appears in no token; a controller
	// that reads it is being built, and until it ships nothing does.
	// See [Slack].
	Slack Slack `yaml:"slack,omitempty"`
}

type Resource struct {
	// DisplayName is what a person is told they are granting access to.
	// Shown on the sign-in page beside the client's own name, and public
	// in the same way.
	DisplayName string `yaml:"display_name,omitempty"`
	// Description is one line under it.
	Description string `yaml:"description,omitempty"`
	// Requires lists internal groups, any one of which admits a caller to
	// this resource. Mandatory, and checked in addition to the client's:
	// the client says who is asking, this says what may be asked for.
	Requires []string `yaml:"requires,omitempty"`
	// TTLCap caps the lifetime of tokens minted for this resource, as
	// `ttl_cap` does on a client. The shorter of the two applies.
	TTLCap Duration `yaml:"ttl_cap,omitempty"`
	// AbsoluteCap is the absolute session limit for a session whose
	// tokens are FOR this resource, in place of the installation's
	// `lifetimes.absolute`. Shorter than that is always allowed. LONGER
	// is allowed only when [Resource.ReadOnly] says the resource cannot
	// change anything, and never beyond [MaxAbsoluteCap]. Unset means
	// the installation's own limit. See [EffectiveAbsolute] for how it
	// combines when one session has touched several resources.
	//
	// The lengthening half is deprecated
	// (docs/decisions/0040-agent-class-sessions.md): a client that needs a
	// longer chain says `session: agent`. It is still honoured, with a
	// warning at start ([Resource.LengthensAbsolute]). For an agent-class
	// chain the cap is only ever a ceiling ([AgentAbsolute]).
	AbsoluteCap Duration `yaml:"absolute_cap,omitempty"`
	// ReadOnly declares that this resource only reads: a token for it
	// can observe the estate and cannot change it. It is the one thing
	// that lets [Resource.AbsoluteCap] exceed `lifetimes.absolute`, and
	// it is a claim the owner of the resource makes, not one the issuer
	// can verify -- which is why it is written down in the policy next to
	// the cap rather than inferred.
	ReadOnly bool `yaml:"read_only,omitempty"`
	// SigningAlg pins which algorithm an ACCESS token minted for this
	// resource is signed with -- an ID token never names a resource as
	// its audience, so this has no say over one. Empty uses the
	// installation default. See [Client.SigningAlg], which is the same
	// idea one row over: a resource's audience is a service just as a
	// client's is, and the two share one vocabulary of algorithms.
	SigningAlg string `yaml:"signing_alg,omitempty"`
	// Groups overrides which of a caller's held groups a token for this
	// resource carries, beyond whatever [Resource.Requires]'s own
	// <scope>:<thing> pairs already keep. See [Client.Groups], the same
	// idea one row over, and [Policy.ScopeGroups].
	Groups GroupsOverride `yaml:"groups,omitempty"`
	// GroupsDelimiter rewrites every `:` in each group name an ACCESS
	// token minted for this resource carries under `groups` -- an ID token
	// never names a resource as its audience, so this has no say over one.
	// See [Client.GroupsDelimiter], the same idea one row over, and
	// [validGroupsDelimiter] for what is refused and why.
	GroupsDelimiter string `yaml:"groups_delimiter,omitempty"`
}

type ResourceView struct {
	ID string
	Resource
}

type Result struct {
	// Groups are the internal groups held, sorted.
	Groups []string
	// Held carries the same, with the reason for each.
	Held []Held
	// Claims is the deep merge of the held groups' fragments, with the
	// group names themselves added under "groups".
	Claims map[string]any
	// Lifetime is the shortest across the held groups, or the default.
	Lifetime time.Duration
}

type RoleSpec struct {
	// Implies are the roles this role directly implies — see
	// [ThingSpec.Roles].
	Implies []string `yaml:"implies,omitempty"`
	// Scopes restricts this role to some of its thing's declared scopes.
	// Empty (the default, and the only thing the plain-list form can
	// mean) means the role is valid on every scope the thing declares. A
	// non-empty Scopes must be a subset of the thing's own — see
	// [Vocabulary.validate] — and a concrete grant naming a scope this
	// role does not list is refused, exactly like a scope the THING does
	// not list; see [Vocabulary.fits].
	Scopes []string `yaml:"scopes,omitempty"`
}

type ScopeSpec struct {
	// Sensitive marks a scope a mapping wildcard must never reach —
	// `staging` and `prod`, typically. A wildcard key still expands freely
	// across every OTHER scope a thing declares; see [Vocabulary.expand].
	// It has no effect on a concrete grant, which names its scope outright
	// and is checked like any other.
	Sensitive bool `yaml:"sensitive,omitempty"`
}

type ServiceAccountMatcher struct {
	// Cluster narrows the rule to one cluster's account. Empty matches
	// any, which is what every rule written before clusters were named
	// means — and what a single-cluster installation wants.
	Cluster   string `yaml:"cluster,omitempty"`
	Namespace string `yaml:"namespace"`
	Name      string `yaml:"name"`
}

type ServiceAccountRef struct {
	// Cluster names which cluster's API server vouched for it. The same
	// namespace and name exist on every cluster, so without it two
	// different machines are one subject — which is the collision `sub`
	// exists to prevent. Empty where a deployment has not named its
	// cluster, and empty in a matcher means any.
	Cluster   string
	Namespace string
	Name      string
}

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

type Slack struct {
	// Workspaces are the Slack workspaces, keyed by a name WE choose —
	// the workspace's own name is the operator's to change, so nothing
	// here depends on it. Each is connected by its own app, and so by its
	// own bot token, which is never written in this file.
	Workspaces map[string]SlackWorkspace `yaml:"workspaces,omitempty"`
}

type SlackChannel struct {
	// Private makes the channel private when the controller creates it.
	// For an adopted channel it must agree with the channel as it exists;
	// a disagreement is a hold at reconcile time, never a silent change
	// of visibility.
	Private bool `yaml:"private,omitempty"`
	// Mode is `extend` (the default) or `strict`; see above.
	Mode string `yaml:"mode,omitempty"`
	// Ignore lists people a strict channel never removes: addresses, or
	// Slack user ids (`U0123ABCD`) for somebody with no address here.
	// Only meaningful, and only allowed, with `mode: strict`.
	Ignore []string `yaml:"ignore,omitempty"`
	// From are the internal groups whose holders belong in the channel.
	// At least one: a channel fed by nothing would be a channel the
	// controller empties, and that is not something to express by leaving
	// a list out.
	From []string `yaml:"from,omitempty"`
	// Adopt is the ID (`C0123ABCD`, or `G…` for an older private channel)
	// of an existing channel to adopt, optionally. A channel with the
	// declared name is adopted by name without it; the ID is for a
	// renamed channel, or when two channels are candidates, and by ID
	// because a name can be changed or reused and an ID cannot. One ID may
	// be adopted once per workspace.
	Adopt string `yaml:"adopt,omitempty"`
}

type SlackWorkspace struct {
	// Channels are the channels bound in this workspace, keyed by channel
	// NAME as Slack spells it (lowercase letters, digits, `-` and `_`, at
	// most 80 characters). The controller creates a channel that is
	// missing and otherwise adopts the existing one BY NAME;
	// [SlackChannel.Adopt] is only a disambiguation.
	Channels map[string]SlackChannel `yaml:"channels,omitempty"`
}

type TeamView struct {
	Org         string
	Team        string
	Members     []string
	Maintainers []string
}

type ThingSpec struct {
	// Scopes are the declared scopes this thing exists in. A concrete
	// grant naming a scope this thing does not list is refused at load.
	Scopes []string `yaml:"scopes,omitempty"`
	// Roles is the thing's ladder: role name to [RoleSpec] — the roles it
	// directly implies and, optionally, the scopes it is valid on. Empty
	// Implies means it implies nothing (a leaf role, most often `viewer`);
	// empty Scopes means it is valid on every scope the thing declares,
	// which is what every role meant before per-role scoping existed.
	Roles map[string]RoleSpec `yaml:"roles,omitempty"`
}

type Vocabulary struct {
	// Scopes are the environments and tenant shapes an installation
	// recognises: `staging`, `prod`, `devel`, `stage`, or `all` for a thing
	// that exists once per installation rather than once per environment.
	Scopes map[string]ScopeSpec `yaml:"scopes,omitempty"`
	// Things are the subsystems, projects and applications a role is held
	// ON: `k8s`, `argocd`, `grafana`. Each names the scopes it exists in
	// and the roles its ladder has, with their implies edges.
	Things map[string]ThingSpec `yaml:"things,omitempty"`
}