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 (§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`, kacho#1122) — то есть край спрашивает эту полосу на каждом предъявлении удостоверения. Здесь стояло «этого вызывающего в дереве СЕГОДНЯ НЕТ (kacho#797)»: утверждение пережило свой предмет (kacho#1156). Исчезнет метод у края — снимать и эту строку. Ответ метода покрывает и отзыв СЕМЕЙСТВА выпуска (kaname#319); послабление под эту возможность выведено заново, а не унаследовано, — разбор у `session_revocations.Handler.IsRevoked`.
• InternalUserService/Get — service→service lookup.
• identity-provider hook callbacks are not in this set: they were served over HTTP, never as gRPC methods, and left together with the external provider (kaname#363). 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 (kacho#788).

func GatewayServiceName ¶ added in v0.5.0

func GatewayServiceName() string

GatewayServiceName — короткое имя службы края, каким его называет SAN проверенного клиентского сертификата. ОДНО объявление на дерево (Ф3 §8 инв. 7): его читают ярус gateway-only внутреннего слушателя и слушатель полосы формы (`internal/handler/loginlanehttp`, Р16) — второго литерала имени края у второго читателя нет.

func HopAdmits ¶ added in v0.7.0

func HopAdmits(modules moduleidentity.Roster, d grpcsrv.TrustDomain, st *tls.ConnectionState) bool

HopAdmits — пускает ли собственный внутренний REST-фронт предъявителя с состоянием рукопожатия st (см. шапку файла).

Непроверенный лист, лист вне перечня и лист чужого центра у личности с привязкой — не личность, отказ.

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 InternalAddressGateFindings ¶ added in v0.5.0

func InternalAddressGateFindings(circle, internalMethods []string, table map[string]InternalAddressGateRow) []string

InternalAddressGateFindings — сверка таблиц Р4в с двумя производителями (§9 п. 5 приёмки): кругом края (`GatewayFrontedInternalRPCs`) и перечнем методов внутренних служб контракта. Находки — строками с координатой: метод круга без строки круга, метод внутренней службы без строки ни в одной таблице, строка без метода. Пустой перечень любого производителя — находка: пустой обход не вердикт.

func InternalAddressGateTable ¶ added in v0.5.0

func InternalAddressGateTable() map[string]InternalAddressGateRow

InternalAddressGateTable — таблицы Р4в копией: метод → строка.

func InternalFrontAdmission ¶ added in v0.7.0

func InternalFrontAdmission(prodMode bool, modules moduleidentity.Roster, d grpcsrv.TrustDomain) func(*tls.ConnectionState) bool

InternalFrontAdmission — допуск предъявителя внутреннего фронта посадки.

Боевой режим — HopAdmits по перечню установки. Вне боевого режима политика вызывающего слушателя вырождается целиком (пол, перечни профилей и круг края пропускают всех), и допуск фронта вырождается с ней: суд строже слушателя на этой посадке был бы вторым местом об одном предмете.

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 IsAnonymousSelfCheck ¶ added in v0.7.0

func IsAnonymousSelfCheck(ctx context.Context, req *iamv1.AuthorizeCheckRequest, modules moduleidentity.Roster) bool

IsAnonymousSelfCheck admits only the credential-free, subject-free Check shape (kaname#959). Both public unary admission and the handler use this predicate. It grants no resource permission: the normal decision service evaluates the server-selected anonymous subject.

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 ModuleActor ¶ added in v0.7.0

func ModuleActor(ctx context.Context) (subject, module string, ok bool)

ModuleActor — машинная личность модуля-вызывающего по ПОДТВЕРЖДЁННОМУ сертификату: субъект `service_account:<учётка службы>` и имя службы (kaname#1005, аудит регистрации объектов модулем).

Личность выводится тем же разбором, которым ворота записи регистрации (`RelationWriteGate.Authorize`) узнают модуль: единственный разбор SAN (`moduleidentity.ParseSAN`, kaname#984) → учётка → служба (`moduleidentity.ServiceFromAccount`, та же функция, которой перечень личностей выводит `Identity.Service`) → учётка службы (`ServiceAccountIDForService`). Поэтому для вызова, пропущенного воротами, актор события аудита — ровно тот субъект, чьё право на запись проверено, а не слово вызывающего. Признание по перечню и привязку к выпустившему центру (kaname#984, kaname#988) судят ворота до use-case; здесь личность только называется. ok=false — подтверждённой личности по сертификату нет (вызов не по mTLS либо SAN не называет службу продукта).

func NarrowsCallerArgument ¶ added in v0.7.0

func NarrowsCallerArgument(fullMethod string, p moduleidentity.Profile) bool

NarrowsCallerArgument — сужает ли обработчик метода fullMethod довод вызова для личности профиля p.

func OwnDoorProtoPackages ¶

func OwnDoorProtoPackages() []string

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

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

func PeerIsGateway ¶ added in v0.5.0

func PeerIsGateway(modules moduleidentity.Roster, d grpcsrv.TrustDomain, st *tls.ConnectionState) bool

PeerIsGateway — пир HTTP-слушателя предъявил ПРОВЕРЕННЫЙ сертификат края: объявленная установкой личность, чья служба — api-gateway.

Один признак края на все HTTP-слушатели, читающие заголовок, который ставит край: полосу входа (допуск ровно края) и поверхность выдачи (адрес источника, приёмка ceremony-pace-is-named-by-number.md Р7). Сертификат, которого слушатель не проверил (нет проверенной цепочки), личности не доказывает. Необъявленный домен доверия и необъявленная пара не узнают никого.

Привязка к выпустившему центру (kaname#988) судится ТЕМ ЖЕ перечнем, что на gRPC-слушателях: лист края, выпущенный не центром края, краем не признаётся.

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 ProfileMethods ¶ added in v0.7.0

func ProfileMethods(p moduleidentity.Profile) []string

ProfileMethods — закрытый перечень методов внутреннего слушателя профиля p. Неизвестный профиль — пустой перечень: по нему не открыт ни один метод.

func PublicGatewayFloorExemptRPCs ¶ added in v0.6.0

func PublicGatewayFloorExemptRPCs() map[string]string

PublicGatewayFloorExemptRPCs — публичные глаголы с полом уровня, на которых второй замок службы на ветви края НЕ стоит, с основанием каждого.

Что держит второй замок ¶

На ветви края служба судит пол уровня из СВОЕГО встроенного каталога у КАЖДОГО глагола, чья запись объявляет пол выше «0» (kaname#767), а не у выписанного перечня. Перечень расходился бы с каталогом молча: новый глагол с полом в него сам не попадает, и его пол держал бы только край — по своей копии каталога, которая отстаёт от контракта службы на время между вливанием контракта и пересборкой края (так было с тремя глаголами ключа доступа: «1» в копии края при «2» в контракте, kaname#747). Выведенное из каталога множество закрыто по умолчанию: глагол, получивший пол в контракте, получает и второй замок тем же изменением.

Почему изъятие — перечень с основанием, а не настройка ¶

Изъятие ослабляет замок, и потому живёт в коде под ревью, как таблица соседей выше: расширяет его изменение, называющее основание, а не настройка посадки. Запись, чьего глагола нет среди публичных с полом, — находка (TestKN767_ExemptionExpiresWithItsSubject): изъятие истекает вместе с предметом.

func PublicPeerCallableRPCs ¶

func PublicPeerCallableRPCs() map[string][]string

PublicPeerCallableRPCs возвращает публичные глаголы, которые вправе звать модуль, НЕ являющийся краем, — с точными короткими именами служб, которым каждый из них разрешён.

Каждая запись — ЗАПРОС, и это правило, а не совпадение: мутирующий глагол здесь дал бы соседней службе возможность менять данные арендатора от имени переданного человека — ровно ту дыру, которую эта политика закрывает. Замок TestPublicPeerCallableRPCs_CarryNoMutation держит это по самому контракту: в Kachō мутация — это ровно глагол, возвращающий Operation, поэтому проверка читает контракт, а не привычку именования.

Края здесь намеренно нет — его пускает собственная ветвь, и назвать его ещё и здесь значило бы завести второй источник правды, который разъедется.

Членство выведено из рёбер во время работы, а не из поиска по имени:

• ProjectService/Get — vpc, compute, nlb, storage и registry держат по ProjectServiceClient, направленному на ПУБЛИЧНЫЙ адрес iam, и зовут Get на пути своего Create (существование проекта и владеющий аккаунт);
• AuthorizeService/BatchCheck — фильтр видимости страницы в vpc/compute/nlb/storage (internal/authzfilter — единственный метод AuthorizeService, который зовёт любой из них). Его ребру место на внутреннем слушателе, и большинство профилей его туда ставят, но профиль, направляющий его на публичный адрес, существует, и отказ там закрыл бы фильтр и опустошил собственный 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.
• InternalSessionRevocationsService/IsRevoked — курица и яйцо: клиент края (`IsSessionRevoked`) спрашивает её до того, как может пойти проверка доступа (kacho#1122).
• InternalIAMService/{RegisterResource,UnregisterResource} — fga_writer-gated mutations.
• ForceLogout / Cluster GrantAdmin/RevokeAdmin / Authorize WriteTuples/ReloadModel / SessionRevocations Revoke — 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 (kacho#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 RequireClusterAdmin ¶ added in v0.5.0

func RequireClusterAdmin(ctx context.Context, checker RelationChecker) error

RequireClusterAdmin — защитная проверка «вызывающий — администратор облака» в виде ответа RPC. Решение принимает модель (IsClusterAdminE); здесь только перевод её исхода в код:

модель ответила «да»                          → nil
модель ответила «нет», принципала не назвать,
проверяющий не подключён                      → PERMISSION_DENIED "permission denied"
спросить модель не удалось                    → UNAVAILABLE "authz backend unavailable"

Текст недоступности фиксированный: причина отказа хранилища в ответ не попадает (§Hardening-инварианты п. 1).

Один дом на всех, кто задаёт этот вопрос защитной проверкой: прежде он был выписан двумя рукописными копиями (защитная проверка выдачи администратора облака и принудительного выхода), и третью — право указать идентификатор аккаунта при создании (kaname#549) — заводить было нельзя.

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 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 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 kacho#645, acceptance §3.6).

func VerifiedPeerIdentity ¶ added in v0.6.0

func VerifiedPeerIdentity(d grpcsrv.TrustDomain, st *tls.ConnectionState) string

VerifiedPeerIdentity — идентификатор пира HTTP-слушателя: URI SAN нашего домена доверия с ПРОВЕРЕННОГО слушателем листа. Пусто — сертификата нет, цепочка не проверена либо лист не несёт идентификатора нашего домена.

Одно место, где решается «чей это пир» по сертификату: признак края выше и доверенный пересыльщик поверхности выдачи (`issuingsource`, kaname#930) спрашивают его, а не разбирают состояние рукопожатия каждый сам.