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"

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

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