authz

const (
	// ClaimGroup matches a value from the ID token's group claim
	// (`groups`, Keycloak's `realm_access.roles` group paths, etc.).
	ClaimGroup ClaimKind = "group"

	// ClaimRole matches a value from the ID token's role claim.
	ClaimRole ClaimKind = "role"

	// ClaimEmail matches the email claim, case-insensitively.
	ClaimEmail ClaimKind = "email"

	// ClaimSub matches the issuer subject exactly (case-sensitively — it
	// is an opaque identifier, not a human-readable name). Useful when the
	// IdP does not release email.
	ClaimSub ClaimKind = "sub"
)

const (
	// PermProjectRead is the right to see a project at all: its state,
	// tasks, steps, analytics, and event history. A caller without it is
	// told the project does not exist (404), never that it is forbidden.
	PermProjectRead Permission = "project.read"

	// PermProjectWrite is the right to change a project's identity and
	// lifecycle: goal, instructions, initialization, reset, deletion.
	PermProjectWrite Permission = "project.write"

	// PermRunStart is the right to start execution — the permission that
	// actually spends tokens and money.
	PermRunStart Permission = "run.start"

	// PermRunStop is the right to halt a running plan. Deliberately
	// separate from PermRunStart: stopping a runaway plan is a safety
	// action and is granted to operators who may not be able to start one.
	PermRunStop Permission = "run.stop"

	// PermTaskMutate is the right to add, edit, reorder, retag, or delete
	// tasks, and to apply AI-proposed plan changes.
	PermTaskMutate Permission = "task.mutate"

	// PermExecutorRead is the right to list the executor fleet and see the
	// host-execution policy.
	PermExecutorRead Permission = "executor.read"

	// PermExecutorManage is the right to enroll, revoke, cordon, drain, or
	// bind executors. Enrolling a device grants it the right to run project
	// workloads, so this is an administrator-grade permission.
	PermExecutorManage Permission = "executor.manage"

	// PermSecretGrant is the right to lease a credential (GitHub PAT,
	// kubeconfig, egress allowance) to an executor.
	PermSecretGrant Permission = "secret.grant"

	// PermSecretRevoke is the right to revoke an outstanding credential
	// lease before its TTL expires.
	PermSecretRevoke Permission = "secret.revoke"

	// PermConfigWrite is the right to change provider/model selection,
	// budgets, rate limits, timeouts, and the persistent run options.
	PermConfigWrite Permission = "config.write"

	// PermAuditRead is the right to read the tamper-evident audit trail and
	// to verify its hash chain.
	//
	// Deliberately not granted to maintainer. The trail records who leased
	// which credential to which executor, who was denied what, and every
	// privileged grant across the fleet — including the actions of people
	// more privileged than the reader. Handing it to the same role that
	// brokers credentials would also let an operator watch their own
	// oversight. It is granted to admin alone, which is what makes "a plain
	// member cannot read the trail" a property of the role ladder rather
	// than of any one route's wiring.
	PermAuditRead Permission = "audit.read"

	// PermUserManage is the right to administer access itself: role
	// bindings, sessions, and the identity integration.
	PermUserManage Permission = "user.manage"

	// PermTokenAdmin is the right to mint, list, and revoke the API tokens
	// that authenticate non-interactive callers (CI, scripts, edge devices).
	//
	// Admin-only, like PermUserManage, because minting a token *is*
	// provisioning an identity: the holder acts with the roles stamped into
	// it, without a browser, an IdP session, or a human behind it. Handing
	// that to maintainer would let the role that brokers credentials also
	// manufacture the callers that consume them.
	//
	// Holding it is necessary but not sufficient: the mint path additionally
	// refuses to issue a role the caller does not already hold, so this
	// permission grants the ability to *delegate* authority, never to
	// escalate it. See pkg/ui/tokens_api.go.
	PermTokenAdmin Permission = "token.admin"

	// PermSessionAdmin is the right to list every signed-in session and to
	// terminate one (Task 20176).
	//
	// Deliberately separate from PermUserManage, which grants authority over
	// role bindings and the identity integration. Ending a session is a
	// containment action — the thing an on-call operator does at 3am when a
	// laptop goes missing — and it changes nobody's standing rights, so it
	// should not require the ability to rewrite who is an admin. The narrower
	// grant is the one that will actually be used in an incident.
	//
	// It is still an oversight-grade permission: the session list names who is
	// signed in, from where, and on what, which is reconnaissance for anyone
	// who should not have it. Admin-only in the default ladder; a deployment
	// that wants an operator-on-call role binds it explicitly.
	//
	// Ending one's *own* sessions needs nothing: POST /api/session/logout-all
	// is authenticated but ungated, because a user closing their own sessions
	// is never an escalation.
	PermSessionAdmin Permission = "session.admin"

	// PermSandboxAttach is the right to open an interactive session inside a
	// running workload's sandbox — a read-only terminal (Task 20265).
	//
	// Its own permission, and granted to nobody below admin by default. Two
	// reasons, and neither is "shells are scary":
	//
	// First, it is not a read of the project. project.read delivers the
	// transcript the harness chose to emit; attach delivers the sandbox's
	// filesystem, its process table, its environment, and whatever the
	// workload happens to be holding at that instant. The lease broker
	// deliberately never exports a bare token, and the redaction path scrubs
	// the values it knows about — but a terminal is a general-purpose reader
	// and a credential nobody declared is a credential nobody scrubs. Folding
	// this into project.read would silently promote every viewer on the hub.
	//
	// Second, it is the one action in the product that reaches *through* the
	// isolation boundary the rest of it exists to maintain. A permission that
	// says so by name is what makes "who may enter a sandbox" answerable from
	// the role binding rather than from reading route code.
	//
	// Deny-by-default in the strong sense: it appears in no role's list except
	// admin's, which holds every permission. A deployment that wants an
	// on-call engineer to debug without administering the fleet binds it
	// explicitly — the same shape as PermSessionAdmin, and for the same reason.
	PermSandboxAttach Permission = "sandbox.attach"

	// PermSandboxAttachWrite is the right to *type* into such a session.
	//
	// Separate from PermSandboxAttach because observing and intervening are
	// genuinely different acts, and the interesting grant is the narrow one: an
	// operator diagnosing a hung task needs to look, and the reason to stop
	// there is that anything they type runs as the workload, with the
	// workload's credentials, inside a run whose output is about to be
	// attributed to an AI agent. A write session makes the task's transcript a
	// record of two authors, and the audit event is the only thing that will
	// ever say so.
	//
	// Holding it is necessary but not sufficient: a writable session also
	// requires PermSandboxAttach, because there is no such thing as typing into
	// a terminal one may not open. The hub checks both.
	PermSandboxAttachWrite Permission = "sandbox.attach.write"

	// PermSecretRequest is the right to *ask* for a credential — to file an
	// access request, list one's own, and withdraw one (Task 20271).
	//
	// Granted from operator up, which makes it the only permission in the
	// secret family below maintainer, and that asymmetry is the whole point.
	// Asking confers nothing: a request is a row with a justification on it, and
	// until somebody who holds PermSecretGrant approves it there is no
	// credential, no lease, and nothing an executor can use. What it replaces is
	// a conversation in a chat window — which is where over-broad grants come
	// from, because the person minting one is reconstructing a scope from a
	// sentence and a wider guess is always the cheaper one.
	//
	// Deliberately not granted to viewer. A request names a secret, a project
	// and a repository allowlist, so the ability to file one is the ability to
	// enumerate what exists by probing — and a viewer is the role that cannot
	// start a run, which is to say the role with nothing to spend a credential
	// on.
	//
	// Approving is a different permission and stays where it was: PermSecretGrant
	// at maintainer. Holding both does not let one person do both — the broker
	// refuses an approval by the identity that filed the request, which is the
	// check that has to exist because on a small team those are frequently the
	// same person.
	PermSecretRequest Permission = "secret.request"

	// PermSecretOwn is the right to keep credentials of one's own on the hub:
	// to mint a personal secret, list the personal secrets one owns, grant one
	// to one's own work, and destroy it (Task 20275).
	//
	// Granted from operator up, alongside PermSecretRequest and for a related
	// reason: what it authorises is not reach into the organisation's
	// credentials but the ability to bring your own. The secrets it creates
	// carry an owner, and the broker refuses every attempt to list, grant or
	// delete one from any identity but that owner — so holding this permission
	// widens nobody's access to anything that already exists.
	//
	// It is emphatically not a weaker PermSecretGrant, and the distinction is
	// the one that makes the pair safe to hold together. secret.grant is
	// authority over the organisation's credentials — a maintainer deciding
	// that the fleet's deploy key may reach a repository. secret.own is
	// custody of your own, and the blast radius of misusing it is your own
	// account at GitHub. Merging them would mean either that a developer
	// cannot store a personal PAT without also being handed the fleet's, or
	// that the fleet's credentials become operator-reachable; both are worse
	// than a second permission.
	//
	// Not granted to viewer, on the same ground as secret.request: a viewer
	// cannot start a run, so a credential stored under their name is one
	// nothing they can do would ever spend.
	PermSecretOwn Permission = "secret.own"

	// PermViewPrefs is the right to change one's own dashboard presentation
	// — currently, which projects to hide from the project list.
	//
	// Granted from viewer up, making it the weakest permission in the
	// ladder, because it authorizes nothing about a project: it records a
	// preference under the caller's own viewer key, against a project they
	// can already see, and no other user can observe the result. Gating it
	// on project.write instead — the nearest existing permission a POST may
	// carry — would leave the roles that live in the dashboard all day as
	// the only ones unable to tidy it.
	//
	// It is not a weaker form of project.read. A hidden project is still
	// delivered to the caller and still reachable by index: hiding is
	// decluttering, not concealment, and must never be relied on to keep a
	// project out of someone's reach.
	PermViewPrefs Permission = "view.prefs"

	// PermPublic is not a permission. It is the explicit marker a route
	// declares when it must stay reachable before authorization can even be
	// evaluated — the login machinery, the SPA shell, static assets, and
	// /api/me. It exists so that "this route is unguarded" is a visible,
	// greppable decision in the route table rather than an omission.
	PermPublic Permission = "public"
)

const (
	// RoleNone holds no permissions. It is the default default: an
	// identity that matches no binding can do nothing until an operator
	// says otherwise.
	RoleNone Role = "none"

	// RoleViewer may read projects and see the executor fleet.
	RoleViewer Role = "viewer"

	// RoleOperator may additionally drive execution: start and stop runs
	// and mutate the task plan. This is the day-to-day engineer role.
	RoleOperator Role = "operator"

	// RoleMaintainer may additionally reshape a project and broker
	// credentials to executors: project write, config write, secret
	// grant/revoke.
	RoleMaintainer Role = "maintainer"

	// RoleAdmin holds every permission, including managing the executor
	// fleet and access control itself.
	RoleAdmin Role = "admin"
)

const (
	// SourceAuthzDisabled means RBAC is not in force (OIDC is off): the
	// single-tenant local behavior of granting everything.
	SourceAuthzDisabled Source = "authz_disabled"

	// SourceStaticToken means the caller presented the deployment's own
	// bearer token, which is an operator credential by definition.
	SourceStaticToken Source = "static_token"

	// SourceAPIToken means the caller presented a scoped personal access
	// token. Unlike SourceStaticToken this is *not* a bypass: the token
	// carries its own roles and the resulting decision is an ordinary
	// permission set, resolved by FromRoles rather than by binding lookup.
	SourceAPIToken Source = "api_token"

	// SourceBinding means a configured role mapping matched.
	SourceBinding Source = "binding"

	// SourceAdminEmail means the legacy oidc.admin_emails list matched.
	SourceAdminEmail Source = "admin_email"

	// SourceRuntimeBinding means a runtime binding — one written by an
	// operator rather than deployed in config — granted the role.
	SourceRuntimeBinding Source = "runtime_binding"

	// SourceRuntimeDeny means a runtime deny binding withdrew the caller's
	// authority. Distinct from SourceDefaultRole so the audit trail
	// distinguishes "nothing granted this person anything" from "somebody
	// took it away, deliberately, and there is a reason on file".
	SourceRuntimeDeny Source = "runtime_deny"

	// SourceDefaultRole means no binding matched and oidc.default_role
	// applied.
	SourceDefaultRole Source = "default_role"

	// SourceUnauthenticated means there was no identity to resolve.
	SourceUnauthenticated Source = "unauthenticated"
)