authzguard

func AllowsVGet ¶

func AllowsVGet(ctx context.Context, checker RelationChecker, fgaType, id string) (bool, error)

AllowsVGet reports whether the ctx principal may read the object `<fgaType>:<id>`: it is a cluster-admin (flat super-gate, D-9) OR it holds the `v_get` relation on the object (owner-binding materializes it for the owner; an explicit `iam.<res>.get` grant materializes it for a delegate).

(false, nil) is a decision (hide existence); (false, err) means the decision could not be made (map to UNAVAILABLE, never to NotFound).

fgaType is the rights-model object_type (e.g. "account", "project", "iam_user"); id is the bare resource id (no type prefix). The object string is composed as `<fgaType>:<id>` — the SAME object the reconciler materializes and the gateway Check's against.

func AllowsVerb ¶

func AllowsVerb(ctx context.Context, checker RelationChecker, relation, fgaType, id string) (bool, error)

AllowsVerb is the generic verb-bearing read-authorization gate: cluster-admin super-gate OR the ctx principal holds `relation` on `<fgaType>:<id>`. AllowsVGet is the get-specialization (relation == "v_get"). Kept generic so a future read path (e.g. a v_list object-existence probe) reuses the same fail-closed posture.

An allow is returned as soon as ONE question answers yes, even if the other failed — an allow needs no second opinion. A non-allow is only reported as a decision when EVERY question this gate asked was actually answered; otherwise the error of the unanswered one is returned.

func AntiAnonymousStream ¶

func AntiAnonymousStream(logger *slog.Logger) grpc.StreamServerInterceptor

AntiAnonymousStream — symmetric stream-RPC interceptor (same policy).

func AntiAnonymousUnary ¶

func AntiAnonymousUnary(logger *slog.Logger) grpc.UnaryServerInterceptor

AntiAnonymousUnary — gRPC unary server interceptor. Policy: default-deny anonymous unless (a) FullMethod is in whitelistFullMethod, or (b) method-name ends in a read-only suffix (Get/List/Watch/Resolve/…). Everything else (Create/Update/Delete/Approve/Deny/Issue/Revoke/Generate/ Cancel/Activate/…) is rejected for anonymous principals.

func AuthzBackendUnavailable ¶

func AuthzBackendUnavailable() error

AuthzBackendUnavailable — canonical answer for "the model could not be asked".

It is NOT PermissionDenied, and the difference is the whole point: a refusal says "you may not", which tells the caller that retrying is pointless — the decision depends on (subject, relation, object) and an identical retry changes none of the three. A backend outage says nothing about rights at all; the same question a moment later gets an answer. Collapsing the two hands a caller a terminal verdict on a transient flap, and callers that classify peer answers by lane (outbox drainers, reconcilers, peer clients) will mark the intent permanently failed.

Fail-closed is unchanged either way: the request is refused, nothing runs. Only the code differs, and the code is the whole signal.

The text carries no detail of the backend failure (security.md §Hardening-инварианты п.1 — no leak); the raw error is logged, not surfaced. Single source for the three gates that already answered this way inline (RelationWriteGate, SystemViewerFloor, scope) and for those that used to collapse it into a refusal.

func CallerAuthorityGatedMethods ¶

func CallerAuthorityGatedMethods() []string

CallerAuthorityGatedMethods — RPC, которыми у модели СПРАШИВАЮТ, а не действуют: «можно ли субъекту S сделать A с объектом O».

Почему у них нет ОБЪЕКТА, о котором спросить ¶

Субъект такого RPC стоит В ЗАПРОСЕ, а вызывающий — модуль: край на пути каждого запроса и сервисы-соседи при сужении списочной выдачи. Вопрос задаётся ДО того, как решение о доступе принято, и задаёт его не тот, о ком спрашивают, поэтому единого объекта, которым дверь могла бы их гейтить, не существует: у `Check` это и объявлено контрактом (`scope_filtered`).

ЛИЧНОСТЬ АРЕНДАТОРА У НИХ ПРИ ЭТОМ БЫВАЕТ, и здесь стояло обратное («её нет by construction»). Сужатель списочной выдачи зовёт соседа под личностью ИНИЦИАТОРА — `pkg/listnarrow/client.go` передаёт `auth.PropagateOutgoing(ctx)`, — так что на пути «арендатор перечисляет свою страницу» вызывающий назван всегда. Разбор следствия и цена — в разделе о безусловности поправки ниже.

Кто их решает — ОДИН, и он назван ¶

`api/authorize/caller_authority.go` — единственный решатель вопроса «кто вправе спрашивать», и его шапка это заявляет прямо. Он строго fail-closed: вызывающий без личности проходит ТОЛЬКО с проверенным сертификатом модуля (`authorizeAnonymousPeer`), арендатор — только про себя, про объект, которым администрирует, либо будучи администратором кластера. Соседний рубеж того же слушателя (`AntiAnonymousUnary`) вычитает эти RPC по той же причине.

Дверь для них добавляла ровно одно требование — «вызывающий назван», — и именно оно неверно: модуль называет себя сертификатом, а не заголовком личности. Наблюдалось: пять шардов сквозных проб, у каждого 40+ отказов `authz_no_principal` на `AuthorizeService/Check`, при нуле таких записей на стволе; посев умирал на первой же мутации, потому что ОТКАЗОМ становилось всякое решение о доступе на стенде.

Круг узок намеренно, и у каждой записи назван ПРОИЗВОДИТЕЛЬ ¶

• `Check` — край, `gateway/internal/clients/iam_authorize_client.go` (вопрос на пути каждого запроса);
• `BatchCheck` — сужатель списочной выдачи, `pkg/listnarrow/client.go` (вопрос о странице у сервисов-соседей).

`ListSubjects` и `ExpandRelations` тот же обработчик судит тем же гейтом, но производителя вне iam у них в этом дереве НЕТ (предикат: `git grep -l 'ExpandRelations\|ListSubjects' -- gateway pkg services ':!services/iam'`), поэтому записи им здесь не заводится: освобождение заводится ВМЕСТЕ с тем, что оно освобождает, а не вперёд него. Появится производитель — запись приедет вместе с ним.

Поправка живёт В ЗВЕНЕ, а не в карте — и это решение, а не вкус ¶

Карту двери судит перепись публичной поверхности (`internal/publicauthzcensus`), и её шапка объявляет: перепись обязана читать ТУ ЖЕ карту, которую звено спрашивает в проде. Перекрой мы здесь выведенную запись — перепись назвала бы эти два RPC освобождёнными КОНТРАКТОМ, чего контракт не объявлял; получилось бы второе место об одном предмете, и разошлись бы они молча. Карта остаётся выведенной, а поправка стоит там, где её видно как отдельное звено, — рядом с двумя другими рубежами того же слушателя.

Поправка снимает дверь там, где у неё НЕТ ОБЪЕКТА, — и таких случаев ДВА ¶

Здесь стояло «дверь снимается ТОЛЬКО когда личности арендатора нет вовсе», а основанием ему служил абзац выше — «личности арендатора в их исходящем контексте нет by construction». ОСНОВАНИЕ НЕВЕРНО, и это измерено: сужатель списочной выдачи зовёт соседа через `auth.PropagateOutgoing(ctx)` (`pkg/listnarrow/client.go`), а тот дописывает принципала в исходящие метаданные, когда он непуст. На пути «арендатор перечисляет свою страницу» принципал непуст ВСЕГДА, то есть вызывающий назван, — и снятие по первому случаю к нему не относилось.

Для `Check` это не значило ничего: контракт объявляет его `scope_filtered`, и звено выходит до вопроса об объекте при любой личности. Для `BatchCheck` значило всё — он несёт `required_relation: viewer` и `scope_extractor{project, scope_id}`, поэтому названный вызывающий доходил до вопроса об объекте. Объекта у ЭТОГО вопроса нет: `scope_id` контракт объявляет НЕОБЯЗАТЕЛЬНЫМ дословно («Optional scope id for authz of the batch as a whole. When set, the gateway gates the entire batch on this scope's `iam.authorize.batchCheck` permission instead of per-item»), и не заполняет его ни один вызывающий в дереве — предикаты: `git grep -n 'ScopeId' -- pkg/listnarrow` → пусто, `git grep -n 'ScopeId:' -- . | grep -v _test` → среди попаданий нет ни одного `BatchAuthorizeCheckRequest`. Выведенный извлекатель читает поле как заданное всегда и отдаёт `project:` с пустым идентификатором; пустой отвергается `FormatObject` ДО вопроса к модели, то есть и до плоского надзора администратора облака, который живёт внутри `checkAdapter.Check`. Прежняя редакция называла эту полосу штатной («по объекту у `BatchCheck`»), тогда как пройти её нельзя было НИКОГДА.

Наблюдалось на голове `d1c7a4a89b`: журнал звена называл причину прямо — `authz_object_format_failed err="authz: empty object id"`, — край отдавал 503 на `GET /vpc/v1/securityGroups`, консоль показывала «Сервер не смог ответить · list filter: AuthorizeService.BatchCheck PermissionDenied», а СПИСКИ ВСЕХ РЕСУРСОВ ПРОЕКТА были пусты у каждого арендатора. В шарде vpc этим объясняются все 123 отказа (118 прямых + 5 каскадом), в шарде iam — ещё 4; пять сквозных проб консоли падали тем же корнем. Сужение страницы ломалось у КАЖДОГО соседа, который его делает.

Почему снятие привязано к ОТСУТСТВИЮ ОБЪЕКТА, а не сделано безусловным ¶

Починку писали две полосы одной волны, и разошлись они ровно в одном: снимать ли дверь и с запроса, НАЗВАВШЕГО `scope_id`. Измеренный дефект такого запроса не касается — у него объект ЕСТЬ, и вопрос `viewer @ project:<scope_id>` есть ровно тот, который контракт для этого поля и объявляет. Снять гейт заодно значило бы принять поле контракта и на него не смотреть, а послабление выдать ВПЕРЁД производителя, которого сегодня нет: запас здесь — не осторожность, а слепая зона, в которую уедет первый же настоящий вызывающий.

Поэтому снятие привязано к тому, что измерено: извлекатель отдал ПУСТОЙ идентификатор — спрашивать не о чем. Три исхода извлечения разведены в `questionNamesNoScope`, и средний, «извлечение отказало», двери НЕ снимает: неполученный ответ не есть «спрашивать не о чем».

Что остаётся и что не трогается ¶

Запрос, назвавший `scope_id`, проходит дверь как прежде: объект есть, и гейт контракта на нём осмыслен. `Check` не затронут вовсе — он объявлен `scope_filtered`, извлекателя у него нет by construction, и его полосой остаётся полоса данных.

Второго рубежа этим RPC не нужно ТАМ, ГДЕ ОБЪЕКТА НЕТ: `authorizeCaller` полон для ОБОИХ видов вызывающего — безымянный проходит только проверенным сертификатом модуля, названный арендатор — про себя, про объект, которым администрирует, либо будучи администратором кластера, — и он fail-closed. Дверь добавляла им не второе мнение, а вопрос об объекте, которого у вопроса о правах нет.

Порог свежести подтверждения (`required_acr_min`) поправка НЕ трогает: его держит отдельный страж того же слушателя (`acr_floor.go`), а не это звено.

func ClusterObject ¶

func ClusterObject() string

ClusterObject — the singleton every cluster-tier tuple hangs off. Named once so a caller composing the question by hand cannot spell it differently.

func DenyDetailUnary ¶

func DenyDetailUnary(catalog DenyActionLookup) grpc.UnaryServerInterceptor

DenyDetailUnary returns an interceptor that attaches the machine-readable reason to a refusal that does not already carry one.

What it does NOT attach, and why:

• the subject — the caller already knows who it is, and echoing it adds nothing a client can act on;
• the resource — on a data-filtered method there is no single resource by construction; naming one would be a claim the service cannot make. The edge fills that field only where it resolved a scope object.

WHAT IT ALSO ATTACHES, AND WHY THAT IS NOT AN ORACLE ---------------------------------------------------- A refusal exists so the caller can build the NEXT STEP. A bare one does not restore it: the administrator learns neither which permission to request nor from whom. So the refusal carries the step — in the DETAILS, never in the prose. The message stays the verbatim "permission denied" on every refusal, byte for byte, because a distinguishable text is exactly the existence oracle the fixed wording exists to close.

The form is not invented here: it is the one the step-up refusal already uses (acr_floor.go — a PreconditionFailure violation the edge turns into an RFC 9470 challenge). Type "authz.grant_required", Subject = the scope object type, Description = the permission to ask for and where it is granted.

A refusal that ALREADY names its own next step (the step-up one) gets no second advice: the caller there may hold the grant in full, and "ask for the permission" would send them the wrong way.

A method with no catalog row gets NOTHING attached. That is the whole point: an absent action is how a caller recognises a catalog miss, so inventing an empty one would erase the distinction this exists to create.

func GatewayFrontedInternalRPCs ¶

func GatewayFrontedInternalRPCs() []string

GatewayFrontedInternalRPCs returns the full-method set of internal RPCs that the api-gateway fronts on behalf of an end user (admin UI / admin tooling). These privileged RPCs may ONLY be called by the api-gateway SA — a direct call from any other module is a privilege-escalation attempt.

NOT in this set (any verified module — floor only):

• InternalIAMService/{Check,LookupSubject,PollSubjectChanges} — hot-path service→service RPCs.
• InternalSessionRevocationsService/IsRevoked — заведено под собственный запрос края, идущий до того, как может пойти пер-пользовательская проверка (курица и яйцо). ПРЕДМЕТ У ПОСЛАБЛЕНИЯ ЕСТЬ: клиент края экспонирует `IsSessionRevoked`, и он провязан в слой аутентификации (`middleware.NewLocalThenProviderRevocation`, #1122) — то есть край спрашивает эту полосу на каждом предъявлении удостоверения. Здесь стояло «этого вызывающего в дереве СЕГОДНЯ НЕТ (#797)»: утверждение пережило свой предмет (#1156). Исчезнет метод у края — снимать и эту строку.
• InternalUserService/Get — service→service lookup.
• Hydra hook callbacks are not in this set and cannot be: they are served over HTTP by internal/handler/iamhooks, not as gRPC methods. The gRPC declaration that once mirrored them (InternalIamHooksService) had no implementation and was retired — see retiredRPCSurface in internal/repohygiene.
• the fga-proxy writes InternalIAMService/{RegisterResource, UnregisterResource} — gated in-handler by RelationWriteGate (module SAs). The third one, WriteCreatorTuple, was retired with zero callers (#788).

func HumanUserID ¶

func HumanUserID(ctx context.Context) string

HumanUserID returns the principal's id ONLY when the principal is a human user; "" for a service account, a system/bootstrap principal, an unknown type, anonymous, or an empty ctx.

Use this — NOT PrincipalUserID — for a column that is a foreign key into `users(id)` (`users.invited_by` and anything like it). The distinction is not cosmetic: PrincipalUserID deliberately answers for machine and system principals too, so a caller that wants "the user" and reaches for the user-shaped name gets `sva…`/`bootstrap` back and writes it into a column where no such row can exist. That is a constraint violation at insert time, surfaced to the caller as the unmapped-FK fallback text, which names neither the column nor the cause.

A non-user principal is not an error here and must not be turned into one: it is a legitimate actor with no inviting/creating USER to record. Callers leave the column NULL and rely on the Operation's `principalType`/`principalId` for attribution, which is where a non-user actor belongs.

func IsAnonymous ¶

func IsAnonymous(ctx context.Context) bool

IsAnonymous — true if the principal is anonymous / empty / system+anonymous / system+bootstrap-fallback.

api-gateway injects anonymous as {Type:"system", ID:"anonymous"}; api-gateway may also fail to forward principal-headers entirely — in that case PrincipalFromContext returns SystemPrincipal{Type:"system", ID:"bootstrap"} (fallback). In a gRPC handler both cases = anonymous.

**Internal background-job bootstrap** uses `WithPrincipal` directly with a concrete {Type, ID} — never the empty-ctx fallback. So rejecting system/bootstrap here is safe.

func IsClusterAdmin ¶

func IsClusterAdmin(ctx context.Context, checker RelationChecker) bool

IsClusterAdmin reports whether the ctx principal holds the flat cluster super-admin relation. fail-closed: nil checker / anonymous / empty id / Check error → false.

func IsClusterAdminE ¶

func IsClusterAdminE(ctx context.Context, checker RelationChecker) (bool, error)

IsClusterAdminE is IsClusterAdmin with the reason kept: it separates "the store answered: not an admin" (false, nil) from "the store could not be asked" (false, err).

Когда обязателен именно он ¶

Всюду, где несработавший супер-гейт МЕНЯЕТ наблюдаемый ответ, а не просто «не срабатывает». Списочный путь — главный такой случай: проглоченная неполадка отдаёт well-formed `200` с молча суженной страницей, которую вызывающий не отличит от отзыва прав. Ровно это и требует godoc SubjectIsClusterAdminPlainE ниже; булева обёртка остаётся для мест, где обычная пообъектная полоса всё равно отработает и сама сообщит о неполадке.

func IsSelf ¶

func IsSelf(ctx context.Context, targetID string) bool

IsSelf — true if principal.ID == targetID.

func OwnDoorProtoPackages ¶

func OwnDoorProtoPackages() []string

OwnDoorProtoPackages — пакеты контракта, чьи службы iam поднимает на своих слушателях.

Перечень ЗАКРЫТ и обязан покрывать всё, что регистрируется: карта тотальна над названными пакетами, а RPC из НЕ названного пакета в неё не попадает вовсе и отвергается как незамапленный. То есть пропуск пакета здесь — не послабление, а отказ обслуживать его целиком; ошибка громкая, и это выбрано намеренно.

func PermissionDenied ¶

func PermissionDenied() error

PermissionDenied — canonical PermissionDenied gRPC error (Kachō error text).

func PrincipalSubject ¶

func PrincipalSubject(ctx context.Context) (string, bool)

PrincipalSubject is the ctx variant of SubjectFromPrincipal: it reads the principal from ctx and returns its FGA subject. Anonymous / empty ctx → ("", false) — fail-closed, the same posture as the FGA Check guards that consume it.

func PrincipalUserID ¶

func PrincipalUserID(ctx context.Context) string

PrincipalUserID returns the principal's user-id for user / service-account / system-bootstrap principals; empty string for anonymous or empty ctx.

Use this when writing DB rows or audit-log entries that must carry the authenticated caller's id. Never trust a request-body field for these.

NOTE the name is wider than it reads: the returned id is NOT necessarily a `users(id)`. For a foreign key into that table use HumanUserID above.

Bootstrap-principal (system/bootstrap) is treated as a legitimate identity so internal seeds / migrations / fixtures continue to work; the audit row carries `created_by="bootstrap"` which is correct.

func PublicPeerCallableRPCs ¶

func PublicPeerCallableRPCs() map[string][]string

PublicPeerCallableRPCs returns the public RPCs a NON-gateway module may call, mapped to the exact module service short-names permitted to call each.

Every entry is a QUERY, and that is a rule rather than a coincidence: a mutating RPC here would hand a neighbouring service the ability to change tenant data in a forwarded user's name, which is the very hole this policy closes. The lock TestPublicPeerCallableRPCs_CarryNoMutation enforces it against the proto itself — in Kachō a mutation is exactly an RPC that returns an Operation, so the check reads the contract rather than a naming habit.

The api-gateway is deliberately absent — it is admitted by its own arm, and naming it here too would create a second source of truth that drifts.

Membership is derived from the runtime edges, not from a name search:

• ProjectService/Get — vpc, compute, nlb, storage and registry each hold a ProjectServiceClient pointed at iam's PUBLIC address and call Get on the request path of their own Create (project existence + owning account).
• AuthorizeService/BatchCheck — the per-page visibility filter in vpc/compute/nlb/storage (internal/authzfilter, the sole AuthorizeService method any of them calls). Its edge belongs on the internal listener and most profiles put it there, but a profile pointing it at the public address exists, and a denial there would fail the filter closed and empty a tenant's own List.

func ReadFloorRPCs ¶

func ReadFloorRPCs() []string

ReadFloorRPCs returns the full-method set of cluster-internal READ RPCs that must pass the `system_viewer@cluster` floor. Membership is the single source of truth for the floor; the exemption set is expressed by ABSENCE from this list and asserted by TestReadFloorRPCs_Membership.

NOT in this set (exempt — see the package doc-comment for the rationale):

• InternalIAMService/Check — PDP, never floor-gated.
• InternalUserService/OnRecoveryCompleted — Kratos secret-authed hook.
• InternalSessionRevocationsService/IsRevoked — курица и яйцо: клиент края (`IsSessionRevoked`) спрашивает её до того, как может пойти проверка доступа (#1122).
• InternalIAMService/{RegisterResource,UnregisterResource} — fga_writer-gated mutations.
• ForceLogout / Cluster GrantAdmin/RevokeAdmin / Authorize WriteTuples/ReloadModel / SessionRevocations Revoke / UpsertFromIdentity — gateway-only / admin-tier mutations.

func RequireAuthenticated ¶

func RequireAuthenticated(ctx context.Context) error

RequireAuthenticated returns PermissionDenied if the principal in ctx is anonymous or absent. Only `user` and `service_account` are passed through.

system/bootstrap is REFUSED, exactly as the package comment says: that pair is what PrincipalFromContext returns when the request carried no principal at all, so admitting it would turn "the edge forwarded nothing" into a privileged identity. The previous edition of this sentence listed it among the passed-through principals — two statements about one subject, of which one was true — and the false one was read as a licence: three listing use-cases carried an "unfiltered page for the bootstrap identity" branch that no input could reach, because IsAnonymous had already refused (#648).

Message text is the Kachō canonical `"permission denied"` (no leak of internal details).

IMPORTANT: kacho-api-gateway injects an anonymous request as Principal{Type:"system", ID:"anonymous"} (see auth.go:189 — injectAnonymous). A principal with ID="anonymous" MUST NOT have privileges — despite type=system. Both fields are checked.

func RequireScopeRelation ¶

func RequireScopeRelation(
	ctx context.Context,
	checker RelationChecker,
	scopeType, scopeID, ownerUserID string,
	relations ...string,
) error

RequireScopeRelation — defense-in-depth authority gate for a mutating use-case. Authority is granted when EITHER:

• the principal owns the owning Account (ownerUserID, bootstrap path), OR
• the principal holds one of `relations` on the FGA scope object (delegated administration — e.g. a project-editor who is not the owner).

`scopeType`/`scopeID` identify the FGA object (`project:<id>`, `account:<id>`). `ownerUserID` is the owning Account's owner_user_id (may be empty for scopes without an owning Account — then only the FGA path applies).

When `checker` is nil (unit tests / degraded mode) the guard falls back to owner-only and DENIES non-owners — fail-closed, never fail-open.

func SANRestrictedInternalRPCs ¶

func SANRestrictedInternalRPCs() []string

SANRestrictedInternalRPCs returns the full-method set gated by arm 3 — an explicit client-certificate SPIFFE SAN allow-list.

The SET IS STATIC, deliberately independent of configuration: membership is a property of the RPC, not of what an operator happened to configure. A deployment that never supplies an allow-list must end up with the mint DENIED to everyone, not silently downgraded to the "any verified module cert" floor — a config omission must never open a cluster-admin mint.

func SANToServiceAccountID ¶

func SANToServiceAccountID(d grpcsrv.TrustDomain, san string) (string, bool)

SANToServiceAccountID maps a verified SPIRE SAN to the deterministic module ServiceAccount id.

func SANToServiceDomain ¶

func SANToServiceDomain(d grpcsrv.TrustDomain, san string) (string, bool)

SANToServiceDomain maps a verified SPIRE SAN to the module service short-name (the domain: `vpc`/`compute`/`nlb`). Accepts only `spiffe://<trust-domain>/ns/<ns>/sa/kacho-<svc>` with a non-empty <svc>; any other shape returns ("", false). The domain drives object-type binding in ValidateProxyTuple (a vpc module may only register `vpc_*` objects).

Почему домен доверия — АРГУМЕНТ, а не константа ¶

Домен объявляет установка, и разбор обязан спрашивать ТОТ ЖЕ домен, который впустил эту личность (`grpcsrv.CertIdentityDomainFromContext`). Пока он стоял здесь литералом, разбор утверждал о домене независимо от того, под каким доменом установка выпускает сертификаты, — и утверждал бы это молча.

Проверка домена здесь остаётся не как «второй независимый слой», а как требование к ВХОДУ: строка, не прошедшая извлекатель, сюда попасть не должна, и если попадёт — не будет принята. Называть это защитой в глубину было бы неточно: предикат и величина у обоих слоёв одни.

Необъявленный домен не признаёт своим никого (`TrustDomain.Matches`), поэтому нулевое значение здесь фейл-клоуз.

func ServiceAccountIDForService ¶

func ServiceAccountIDForService(svc string) string

ServiceAccountIDForService derives the deterministic module SA id from a service short-name (`'sva' || substr(md5('kacho-<svc>'),1,17)`). Single source of truth shared by the gate and the seed migration helper.

Формула ОДНА на дерево и живёт в `domain.DerivedIDSuffix`: своя копия здесь разошлась бы с постгресовой молча — полученный идентификатор остался бы синтаксически верным и перестал бы находить строку.

func ServiceNameFromSAN ¶

func ServiceNameFromSAN(d grpcsrv.TrustDomain, san string) (string, bool)

ServiceNameFromSAN extracts the module service short-name from a verified SPIRE SAN (`spiffe://<trust-domain>/ns/<ns>/sa/kacho-<svc>` → `<svc>`). Returns ("", false) for any other shape.

Одна реализация, а не две ¶

Здесь стояла ПОБАЙТОВАЯ КОПИЯ тела SANToServiceDomain — двадцать строк, повторяющих тот же разбор. Расходятся такие копии молча: правка одной не доезжает до другой, и вторая продолжает принимать то, что первая уже отвергает. Свели их вместе с переводом домена доверия в величину — иначе литерал пришлось бы снимать дважды, а копия осталась бы поводом завести его снова.

func SubjectFromPrincipal ¶

func SubjectFromPrincipal(p operations.Principal) (string, bool)

SubjectFromPrincipal builds the FGA subject string for a principal: `user:<id>` for users, `service_account:<id>` for service accounts. It is the single source of truth consolidating the previously-inline (`subjType:="user"; if p.Type=="service_account" {…}; subject:=t+":"+id`) copies scattered across the authz call-sites (#10).

Fail-closed: an unknown principal type, or an empty id, yields ("", false). This is STRICTLY SAFER than the inline copies it replaces, which defaulted unknown types to "user:" (a latent over-grant). Callers must treat ok=false as "no resolvable subject → deny".

func SubjectIsClusterAdmin ¶

func SubjectIsClusterAdmin(ctx context.Context, checker RelationChecker, subject string) bool

SubjectIsClusterAdmin is the subject-string variant of IsClusterAdmin — used by authorize_service.Check, whose request already carries a pre-formatted FGA subject ("user:usr_xxx" / "service_account:sva_xxx") rather than a ctx principal. fail-closed: nil checker / empty subject / Check error → false.

func SubjectIsClusterAdminE ¶

func SubjectIsClusterAdminE(ctx context.Context, chk ContextRelationChecker, subject string) (bool, error)

SubjectIsClusterAdminE answers "is this caller a cluster administrator" and keeps the reason.

(false, nil) is an ANSWER — the store said no. (false, err) means the question was not answered, and the caller must refuse (UNAVAILABLE) rather than narrow.

A nil checker or an unresolvable subject yields (false, nil): those are not outages, they are callers this gate does not apply to, and the list decides what to do about them before it gets here.

func SubjectIsClusterAdminPlainE ¶

func SubjectIsClusterAdminPlainE(ctx context.Context, checker RelationChecker, subject string) (bool, error)

SubjectIsClusterAdminPlainE is SubjectIsClusterAdmin with the reason kept: it separates "the store answered: not an admin" (false, nil) from "the store could not be asked" (false, err). Gates that turn a non-allow into a 404 need that distinction — see AllowsVerb. The bool-only wrappers above stay for the decision sites that are ALREADY fail-closed by construction (a super-gate that cannot be evaluated simply does not fire, and the ordinary per-object path still runs and still reports its own outage).

Which of the two E-variants to call ¶

This one and SubjectIsClusterAdminE (subject_question.go) ask the SAME question — same relation, same singleton — and differ only in the port they ask it through: this one over RelationChecker (plain `Check`), that one over the context-carrying `CheckWithContext`. Call the one matching the port the use-case already holds; do not wire a second port to reach the other.

A list whose page is a page of the visible must use an E-variant: swallowing this failure there produces a well-formed, silently narrowed `200` that the caller cannot tell from a revocation (task #645, acceptance §3.6).