grpcsrv

func ACRRank ¶

func ACRRank(acr string) int

ACRRank maps an ACR string to a comparable integer. Unknown / malformed values resolve to 0 (anonymous) — fail-closed when policy expects ≥ 1.

This is the single ranking table for the whole platform: both enforcement points reach it through EvaluateStepUp.

func ACRSatisfies ¶

func ACRSatisfies(presented, required string) bool

ACRSatisfies reports whether a presented acr meets a required floor.

• required == "" or "0" → no requirement → always true (no-op floor).
• otherwise → ACRRank(presented) >= ACRRank(required).

An absent / unknown presented acr ranks 0, so it fails any positive floor (fail-closed).

This is the ACR arm ONLY. Enforcement points must call EvaluateStepUp, which additionally applies the machine-principal exemption and the MFA-freshness arm; calling ACRSatisfies directly from an enforcement path re-creates half of the rule and is what the parity guards exist to catch.

func CertIdentityFromContext ¶

func CertIdentityFromContext(ctx context.Context) (id string, verified bool)

CertIdentityFromContext returns the extracted module identity and whether the peer was mTLS-verified. A ctx that never carried a cert-identity (no mTLS peer) reports ("", false) — i.e. NOT mTLS-verified (default-deny of trust).

func CertIdentitySubject ¶

func CertIdentitySubject(ctx context.Context) string

CertIdentitySubject — ключ ВНУТРЕННЕГО листенера: личность сертификата (SPIFFE-SAN проверенного пира), а НЕ личность конечного пользователя.

Разница не косметическая. Внутренний листенер зовут наши же модули, и запрос одного модуля несёт личности РАЗНЫХ арендаторов — ключ по арендатору дробил бы бюджет соседа на тысячу вёдер и душил бы его на ровном месте. Модуль же — один, известный и конечный, поэтому ключ по нему называет ровно того, чей поток мы ограничиваем.

func DefaultKeepaliveEnforcement ¶

func DefaultKeepaliveEnforcement() keepalive.EnforcementPolicy

DefaultKeepaliveEnforcement — server-side EnforcementPolicy, допускающая частые idle keepalive-пинги client'ов.

gRPC-дефолт (MinTime: 5m, PermitWithoutStream: false) забанил бы клиента с PermitWithoutStream-пингами каждые 10s → GOAWAY too_many_pings. Чтобы idle-prone conn'ы (compute→iam-internal authz, iam subject-drainer→api-gateway) могли держать conn теплым, сервер обязан разрешать такие пинги: MinTime <= клиентский Time (10s) и PermitWithoutStream=true.

func LogAdmissionStats ¶

func LogAdmissionStats(log *slog.Logger, msg string, limiters ...*Admission)

LogAdmissionStats печатает снимок счётчиков — по строке на листенер.

Отдельная от ReportAdmission функция затем, чтобы «напечатать счёт» было доступно и вне цикла (итог при остановке, отладочный снимок), и чтобы форма строки была ОДНА: две формы одного факта читаются как два разных факта.

func NewServer ¶

func NewServer(opts ...grpc.ServerOption) *grpc.Server

NewServer создает gRPC-сервер с зарегистрированными Health-сервисом в состоянии SERVING и server-reflection (для grpcurl, debug, dev-tooling).

DefaultKeepaliveEnforcement() и DefaultServerLimits() ставятся ПЕРВЫМИ в opts, чтобы caller-opts могли их переопределить.

Почему пределы стоят ЗДЕСЬ, а не у каждого вызывающего ¶

Умолчания библиотеки оставляют сервер без предела одновременных вызовов и без предела размера ответа (числа и координаты — в limits.go). Пока пределы выставлял бы каждый сервис у себя, «не выставил» было бы неотличимо от «выставил такие же»: опция не обязательна, её отсутствие ничего не печатает, и слушатель поднимается молча. Здесь у величин ОДИН источник, и ни один из слушателей платформы не может подняться без них — не потому, что это правило, а потому что другого конструктора сервера в дереве нет.

Следствие для гейта: «сервер без объявленного предела одновременных вызовов» перестал быть находкой, которую надо искать по дереву, — такого состояния не существует по построению. Утверждается это не прочтением, а на проводе: [TestServerAdvertisesItsConcurrentStreamLimit] читает кадр настроек соединения.

func PrincipalExtractStream ¶

func PrincipalExtractStream(d TrustDomain, f TrustedForwarders,
	opts ...TrustedPrincipalOption,
) []grpc.StreamServerInterceptor

PrincipalExtractStream — то же для stream RPC (тот же инвариант порядка).

func PrincipalExtractUnary ¶

func PrincipalExtractUnary(d TrustDomain, f TrustedForwarders,
	opts ...TrustedPrincipalOption,
) []grpc.UnaryServerInterceptor

PrincipalExtractUnary — пара звеньев, отвечающая на вопрос «чью личность несёт этот запрос», для unary RPC. ОДИН И ТОТ ЖЕ набор на ОБОИХ листенерах: «internal = доверенный» — запрещённое допущение.

Почему пара, а не одиночное звено: сертификат доказывает, ЧЕЙ это пир, и ничего не говорит о праве представляться другим. Первое звено достаёт личность сертификата, второе решает по ней, принимать ли переданные заголовки. Порядок обязателен — переставленные звенья означают решение о доверии по ещё не извлечённой личности.

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

Домен доверия стоит ПЕРВЫМ аргументом по той же причине, по какой первым стоит звено извлечения личности сертификата: сперва решается, чей это предъявитель, и только потом — вправе ли он представляться другим. Дополнительные опции ВАРИАДИЧНЫ намеренно: пара уже собирается семью композиционными корнями и двумя сборками, и расширение подписи развело бы их во времени — половина деревьев перестала бы собираться до сдвига пина. Сегодня отсюда приезжает счётчик исходов личности (WithIdentityArrival).

func PrincipalSubject ¶

func PrincipalSubject(ctx context.Context) string

PrincipalSubject — ключ ПУБЛИЧНОГО листенера: личность конечного пользователя, установленная парой звеньев `PrincipalExtract*` (личность сертификата → круг доверенных отправителей). Читается из того же носителя, что и всё остальное в процессе, поэтому ограничитель и аудит говорят об одном и том же субъекте.

Безымянная пара ключом не становится: `operations.Principal.IsAnonymous` покрывает и пустое значение, и зарезервированное слово, которым край помечает запрос без credential'а.

func ReportAdmission ¶

func ReportAdmission(ctx context.Context, log *slog.Logger, prefix string, limiters ...*Admission)

ReportAdmission — фоновая задача процесса: периодически печатает счётчики каждого ограничителя и убирает вёдра простаивающих субъектов. Возвращает управление по отмене контекста, напечатав итог.

Ограничители подаются перечнем, а не парой: у края и у сервиса их по два, но перечень не заставляет вызывающего изобретать пустышку там, где слушатель один. `nil` в перечне пропускается — это объявленное изъятие, а не ошибка; а перечень БЕЗ единого живого ограничителя означает, что считать нечего, и задача завершается сразу, не занимая горутину до конца процесса.

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

РЕПЛИКИ: на-реплику — печатает счётчики СВОЕГО процесса и вычищает его же память. Общего состояния не трогает, к соседям не ходит; предел допуска здесь и публикуется полом — «не менее», что остаётся истинным при любом числе реплик.

func SetPrincipalDisplayMD ¶

func SetPrincipalDisplayMD(md metadata.MD, displayName string)

SetPrincipalDisplayMD кладёт отображаемое имя в метаданные ЕДИНСТВЕННЫМ правильным способом — двоичным ключом.

Функция существует, чтобы у производителей не было выбора: имя, положенное обычным ключом, роняет вызов на первом же не-латинском символе, и падает он НЕ там, где имя записали, а на любом последующем запросе. Один вход в тракт делает этот класс невоспроизводимым по построению.

Пустое имя не кладётся вовсе: пустой ключ в метаданных и отсутствие ключа читаются одинаково, а лишняя пара стоит места в каждом запросе.

func StreamCertIdentityExtract ¶

func StreamCertIdentityExtract(d TrustDomain) grpc.StreamServerInterceptor

StreamCertIdentityExtract is the stream analogue of UnaryCertIdentityExtract.

func StreamPanicRecovery ¶

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

StreamPanicRecovery — stream-звено восстановления паники. Stream-листенер не освобождён: паника stream-обработчика завершает процесс тем же способом.

func StreamPrincipalExtract ¶

func StreamPrincipalExtract(opts ...PrincipalExtractOption) grpc.StreamServerInterceptor

StreamPrincipalExtract — то же для stream RPC.

func StreamTrustedPrincipalExtract ¶

func StreamTrustedPrincipalExtract(opts ...TrustedPrincipalOption) grpc.StreamServerInterceptor

StreamTrustedPrincipalExtract is the stream analogue.

func TLSServerCreds ¶

func TLSServerCreds(cfg TLSServer) (grpc.ServerOption, error)

TLSServerCreds returns the grpc.ServerOption carrying the transport credentials for this config. See package doc for the behavior contract.

Prefer TLSServerTransportCreds where the credentials THEMSELVES are the value being carried — a service descriptor, for one. Wrapping them into a server option too early loses the one question worth asking about them: what the transport says it IS. An option is opaque; `TransportCredentials.Info()` is not, and a start-time refusal reads that rather than trusting a knob.

func TLSServerTransportCreds ¶

func TLSServerTransportCreds(cfg TLSServer) (credentials.TransportCredentials, error)

TLSServerTransportCreds returns the transport credentials themselves.

Same contract as TLSServerCreds, one layer lower: `Enable=false` yields INSECURE credentials without an error, exactly as before. That is deliberate, and it is precisely why the value is worth carrying instead of the option: a caller inspecting only its own knob cannot tell a configured-but-degraded edge from a verified one, whereas `creds.Info().SecurityProtocol` answers for the transport itself.

func TrustedACRFromContext ¶

func TrustedACRFromContext(ctx context.Context) (acr string, trusted bool)

TrustedACRFromContext returns the forwarded JWT `acr` and whether it is trusted under the trust invariant. trusted=false means the acr came from an unverified peer on an mTLS listener (or no acr was carried) and an acr-floor must treat it as absent (rank 0, fail-closed). On the insecure dev listener the acr is accepted as today (back-compat), consistent with the principal.

func TrustedPrincipalFromContext ¶

func TrustedPrincipalFromContext(ctx context.Context) (operations.Principal, bool)

TrustedPrincipalFromContext returns the principal and whether it is trusted under the trust invariant. trusted=false means the principal-metadata came from an unverified peer on an mTLS listener and the authz layer must ignore it.

The returned principal is the ZERO Principal when the peer forwarded none, and likewise when ctx never carried the trust decision at all — trusted=true then says "this forwarder is recognised", not "someone was named". Callers must treat an empty Type/ID as "no principal" and never as an identity to compare against (operations.Principal.IsAnonymous is the shared predicate). The absent-carrier case deliberately does NOT fall back to the system principal: pairing a real-looking value with trusted=false only protects callers who read the flag, and the value would be the very identity the operation-ownership predicate honours everywhere.

func UnaryCertIdentityExtract ¶

func UnaryCertIdentityExtract(d TrustDomain) grpc.UnaryServerInterceptor

UnaryCertIdentityExtract is a server interceptor that classifies the peer's transport security and, for an mTLS-verified peer, extracts its module identity into ctx. It MUST run before UnaryTrustedPrincipalExtract.

• mTLS-verified peer → WithCertIdentity(ctx, CertIdentity(leaf), true).
• TLS peer without a verified client-cert → WithCertIdentity(ctx, "", false) (defense-in-depth: marks the peer not-verified so principal is dropped).
• insecure (plaintext) peer → ctx untouched (no cert-identity ever set); CertIdentityFromContext then reports ("", false) and the principal layer treats the insecure listener as dev backward-compat.

func UnaryPanicRecovery ¶

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

UnaryPanicRecovery — unary-звено восстановления паники.

logger == nil допустим и НЕ приводит к отказу: звено переходит на slog.Default(). Разыменовать здесь отсутствующий журнал значило бы уронить процесс внутри обработки паники, то есть отменить собственный предмет; а промолчать значило бы погасить падение невидимо, и «ноль паник за всю жизнь сервиса» стало бы неотличимо от «паники не записываются».

func UnaryPrincipalExtract ¶

func UnaryPrincipalExtract(opts ...PrincipalExtractOption) grpc.UnaryServerInterceptor

UnaryPrincipalExtract — gRPC unary interceptor для backend-сервисов. Должен стоять РАНЬШЕ бизнес-handler'ов в цепочке interceptor'ов.

Отказа при объявленной и не приехавшей личности здесь НЕТ, и это решение ¶

Отказ (identity_arrival.go) утверждает: пир, чью пересылку слушатель ПОЧИТАЕТ, назвал личность именем, которого эта сборка не читает. У безусловного извлекателя решения о доверии нет вовсе — он читает заголовки, не глядя ни на транспорт, ни на личность сертификата, — поэтому его посылка здесь НЕВЫРАЗИМА, а не опущена.

Провязок у него в дереве ноль (предикат: обращения к `grpcsrv.Unary/StreamPrincipalExtract` вне проб и вне этого файла), и у службы личности их отсутствие держит своя проба. Появится провязка — вместе с ней придётся завести и решение о доверии, то есть перейти на trust-aware пару, которая отказ несёт.

ВНИМАНИЕ (trust): этот extractor читает x-kacho-principal-* БЕЗУСЛОВНО, без проверки транспорта/cert-identity форвардера — он доверяет, что заголовки проставил только api-gateway. Монтировать ТОЛЬКО на listener'е, куда не может дозвониться неконтролируемый peer. Для cluster-internal mTLS-листенеров предпочтительна trust-aware связка UnaryCertIdentityExtract + UnaryTrustedPrincipalExtract(WithTrustedForwarders(<gateway-SAN>)): она снимает principal на недоверенном/не-форвардер peer'е (защита от confused-deputy). Для новых mTLS-листенеров предпочитайте именно trust-aware связку. При построении этот extractor выводит один startup-WARN об этом свойстве.

func UnaryTrustedPrincipalExtract ¶

func UnaryTrustedPrincipalExtract(opts ...TrustedPrincipalOption) grpc.UnaryServerInterceptor

UnaryTrustedPrincipalExtract reads x-kacho-principal-* metadata and exposes it downstream ONLY when it is trustworthy under the trust invariant. It MUST run after UnaryCertIdentityExtract.

Trust decision:

• mTLS-verified peer (CertIdentityFromContext verified=true) → principal trusted.
• insecure listener (no cert-identity ever set on ctx) → principal trusted as today, dev backward-compat. Distinguished from an unverified TLS peer by peerTLSState: insecure ⇒ no TLS transport at all.
• TLS peer without a verified client-cert → principal NOT trusted; dropped (defense-in-depth).

Trust answers "may this peer speak for a user", not "did this request name one". A trusted peer that forwarded NO principal-metadata leaves the request principal-less: the standard carrier reports no principal, and no identity is invented for it. Anything else would hand the system identity — the one the ownership predicate matches on every system-written operation — to a request that presented no credential at all.

The decision is recorded via withTrustedPrincipal so TrustedPrincipalFromContext returns (principal, trusted). cert-identity and principal are orthogonal and both remain available downstream for audit — neither substitutes the other.

func WithCertIdentityIn ¶

func WithCertIdentityIn(ctx context.Context, d TrustDomain, id string, verified bool) context.Context

WithCertIdentityIn stores the extracted cert-identity, the domain it was recognized under, and the mTLS-verified flag in ctx. Exposed so the principal-aware layer (and tests) can assert the invariant deterministically without a live TLS peer.

Почему домен здесь ОБЯЗАТЕЛЕН, а формы без него не существует ¶

Личность существует ОТНОСИТЕЛЬНО домена, и читатели ниже по цепочке (`authzguard.SANToServiceDomain` и соседи) разбирают эту же строку, спрашивая домен у контекста. Контекст, собранный без домена, отдал бы им нулевое значение — и они fail-closed отвергли бы личность, которую сами же признали нашей. Отказ при этом выглядел бы как отсутствие прав у законного модуля.

Форма с двумя аргументами существовала и была снята: она собиралась молча и давала ровно такой контекст. Запретить её значением было нечем — запретили подписью.

func WithTrustedACR ¶

func WithTrustedACR(ctx context.Context, acr string, trusted bool) context.Context

WithTrustedACR stores a forwarded JWT `acr` and the trust flag directly in ctx (bypassing the metadata extract). Exposed so the iam acr-floor and tests can assert the floor deterministically without a live mTLS peer — the mirror of WithCertIdentity for the principal/acr layer. Note: this overwrites any existing trusted-principal carrier's acr/trusted with the given values while keeping the principal as previously recorded — and leaving it EMPTY when none was: an acr says how strongly someone authenticated, never who they are, so this constructor has no business naming anyone.

func WithTrustedPrincipal ¶

func WithTrustedPrincipal(ctx context.Context, p operations.Principal, trusted bool) context.Context

WithTrustedPrincipal stores a forwarded principal and the trust flag directly in ctx (bypassing the metadata extract) — the principal-side mirror of WithTrustedACR, exposed for the same reason: so the iam floors and their tests can drive a machine-vs-user caller deterministically without a live mTLS peer. It keeps any acr already recorded on the carrier and overwrites the principal and the trust flag.

Note the asymmetry it preserves from the real extract path: on an untrusted peer the forwarded PRINCIPAL is still recorded (only `trusted` goes false), whereas the acr is scrubbed. Consumers must therefore consult the trusted flag before believing the principal type — a forged `service_account` from an unverified peer must never buy the step-up exemption.