domain

type AccessBinding ¶

type AccessBinding struct {
	ID              AccessBindingID
	SubjectType     SubjectType
	SubjectID       SubjectID
	RoleID          RoleID
	ResourceType    ResourceType
	ResourceID      string              // opaque id (any prefix, cross-service OK)
	Scope           Scope               // RBAC v2 — anchor tier (CLUSTER/ACCOUNT/PROJECT)
	Status          AccessBindingStatus // PENDING|ACTIVE|REVOKED
	ExpiresAt       *time.Time          // nullable — TTL
	GrantedByUserID UserID              // audit
	RevokedAt       *time.Time          // nullable
	RevokedByUserID *UserID             // nullable
	CreatedAt       time.Time

	// MaterializedAt — OUTPUT-ONLY. When this binding's per-object access last
	// became live: MAX(updated_at) over its ACTIVE rows in
	// access_binding_target_members (the reconciler's ledger). Zero when nothing
	// has materialized yet.
	//
	// It exists because Kachō is eventually-consistent by contract: Operation.done
	// means the binding row is DURABLE, never that the FGA tuples are visible
	// (gating done on downstream visibility is forbidden — ban #9). In that window
	// the grantee's 403 is byte-identical to a real denial, leaving the granting
	// admin with nothing to distinguish "propagating" from "wrong grant" and
	// nothing to poll. This field is the observable — NOT a barrier: it is filled
	// by the read path from an already-written ledger and never blocks a write.
	//
	// Legitimately zero forever for a binding that materializes no per-object
	// membership (CLUSTER scope — served by the flat short-circuit; a legacy
	// permissions-only role with no authored rules[]). Zero therefore means "no
	// ACTIVE per-object member", NOT "the grant is broken".
	//
	// Not persisted on the access_bindings row; filled by the read-side batch
	// projection, like Subjects.
	MaterializedAt time.Time

	// DeletionProtection guards the binding from Delete (RBAC explicit-model 2026
	// P6 — D-10, by the image of vpc.address.deletion_protection). The owner
	// auto-binding created on Account.Create sets it true; Delete on a protected
	// binding → FAILED_PRECONDITION (sync pre-check + atomic CAS backstop). Cleared
	// via Update(update_mask=["deletion_protection"]) (C-03). Default false.
	DeletionProtection bool

	// GrantedRelation — ВТОРАЯ ФОРМА выдачи: имя отношения модели, выдаваемое
	// напрямую на области выдачи, взаимоисключающе с RoleID (ограничение БД
	// `access_bindings_grant_form_ck`). Роль раздаёт ГЛАГОЛЫ через свои правила, а
	// встроенные права платформы выражены именованными отношениями
	// (`system_viewer`, `fga_writer`, `viewer` на кластере) — подобрать роль под
	// каждое означало бы завести роли с пустыми правилами.
	//
	// Непусто ТОЛЬКО у системной выдачи: отношение — внутреннее имя, от которого
	// зависит решение о доступе, и выдавать его вправе только платформа. На вход
	// создания это поле не принимается вовсе — его нет в запросе, поэтому «принято
	// и проигнорировано» здесь невозможно by construction.
	GrantedRelation string

	// System — выдача заведена платформой (встроенный доступ: права служебных
	// учёток, публичное чтение справочников). OUTPUT-ONLY на публичном контракте.
	//
	// Отвечает на вопрос «кто выдал» точнее, чем подставленная учётка: выдал не
	// человек, а платформа, поэтому GrantedByUserID у такой выдачи пуст, и это не
	// пробел аудита, а его содержание.
	System bool

	// Subjects — the full multi-subject set (RBAC rules-model 2026).
	// Persisted in the access_binding_subjects child table; SubjectType/
	// SubjectID above remain the legacy single = Subjects[0] (projection +
	// the active-grant UNIQUE anchor). Empty on a row read without the child
	// load — read-side Get/List fills it. On Create the use-case
	// NormalizeSubjects-resolves it from the request before persisting.
	Subjects []Subject

	// Labels — tenant-facing метки САМОГО ресурса AccessBinding. Делают
	// AccessBinding label-selectable наравне с account/project (ARM_LABELS-грант
	// на iam.accessBinding → v_list по `labels @> matchLabels`; List фильтрует
	// viewer ∪ v_list).
	Labels Labels

	// Target — WHICH objects under the scope-anchor the grant applies to
	// (redesign-2026 F8). AllInScope = whole anchor (incl. future); Resources =
	// closed per-object set. The zero value is treated as AllInScope (legacy /
	// internal rows); the public Create RPC rejects a missing target (least-priv).
	Target AccessTarget

	// RevocationReason — почему выдача отозвана (kaname#963, Д2). Пусто у
	// действующей выдачи и у отозванной до заведения поля (Д7).
	RevocationReason RevocationReason

	// DelegationID — делегирование права выдавать, по которому выдачу сделал
	// делегат (kaname#986, Р2). Пусто у выдачи держателя права выдавать. Ставит
	// только делегированный путь права выдавать; на вход запроса поле не
	// принимается.
	DelegationID GrantDelegationID

	// HeldTargets — НЕ ХРАНИТСЯ. Объекты цели, которые на приёме выдачи были
	// зарегистрированы (Р8 приёмки `unregistration-revokes-its-grants.md`). Запись
	// выдачи берёт на каждом замок строки регистрации и отказывает, если строки
	// уже нет: выдача, принятая до снятия и записанная после, живой не остаётся
	// (URG-24). Пусто — судить нечего (ключи свободны либо цель — вся область).
	HeldTargets []ResourceRef
}

AccessBinding — link (subject_type, subject_id) ↔ role_id ↔ (resource_type, resource_id) with lifecycle fields (status, expires_at, granted_by, revoked_at/revoked_by).

State machine: PENDING → ACTIVE → REVOKED (terminal). Transitions are atomic CAS-style UPDATEs (no TOCTOU). REVOKED is irreversible via `WHERE status IN ('PENDING','ACTIVE')`.

DB partial UNIQUE access_bindings_active_grant_uniq (migration 0003; WHERE revoked_at IS NULL) → strict INSERT: a duplicate active grant raises ErrAlreadyExists with verbatim text «these permissions are already granted to <subject_id> on <res_type>:<res_id>». Re-grant after revoke is allowed (revoked rows are out of the partial UNIQUE scope).

func (b AccessBinding) StructuralParent() (StructuralTuple, bool)

project:<resourceID>  →  project  →  iam_access_binding:<id>
account:<resourceID>  →  account  →  iam_access_binding:<id>
cluster:<resourceID>  →  cluster  →  iam_access_binding:<id>

func (b AccessBinding) Validate() error

type AccessBindingID ¶

type AccessBindingID string

type AccessBindingStatus ¶

type AccessBindingStatus string

AccessBindingStatus — enum lifecycle (migration 0011 CHECK).

const (
	AccessBindingStatusPending AccessBindingStatus = "PENDING"
	AccessBindingStatusActive  AccessBindingStatus = "ACTIVE"
	AccessBindingStatusRevoked AccessBindingStatus = "REVOKED"
)

func (s AccessBindingStatus) Validate() error

type AccessKey ¶ added in v0.5.0

type AccessKey struct {
	ID     AccessKeyID
	UserID UserID
	// CredentialID — идентификатор удостоверения WebAuthn: байты нормы,
	// глобально уникальны; наружу не выходят (Р10).
	CredentialID []byte
	// PublicKey — открытый ключ в форме COSE_Key, байт в байт как принят.
	PublicKey []byte
	// Algorithm — идентификатор алгоритма COSE.
	Algorithm int64
	// SignCount — сохранённое значение счётчика подписи (Р6).
	SignCount uint32
	// UserHandle — рукоятка `user.id`, которую церемония регистрации положила
	// в ЭТОТ ключ: байты `CeremonyHandle` человека (64 случайных байта, Ф13
	// Р3). С ней сверяется каждое утверждение ключа (Ф13-06 «з»).
	UserHandle  []byte
	Name        AccessKeyName
	Description AccessKeyDescription
	CreatedAt   time.Time
	// LastUsedAt — момент последнего успешного предъявления; нулевой указатель
	// — предъявлений не было.
	LastUsedAt *time.Time
	// Discoverability — признак обнаружимости удостоверения (Р12): сообщается
	// аутентификатором ОДИН раз, в церемонии регистрации, и после неё его
	// негде прочитать заново. Читатель — страж последнего способа входа.
	Discoverability Discoverability
}

AccessKey — строка ключа.

func (k AccessKey) Presentable() bool

func (k AccessKey) Validate() error

type AccessKeyChallenge ¶ added in v0.5.0

type AccessKeyChallenge struct {
	// Challenge — случайные байты; ключ строки.
	Challenge []byte
	// UserID — кому выдано: из чужой сессии испытание не находится (Ф7-55).
	UserID  UserID
	Purpose AccessKeyChallengePurpose
	// IssuedAt / ExpiresAt — момент выдачи и предел срока.
	IssuedAt  time.Time
	ExpiresAt time.Time
	// ConsumedAt — момент предъявления; нулевой указатель — не предъявлено.
	ConsumedAt *time.Time
}

AccessKeyChallenge — выданное испытание: привязано к ВЫЗЫВАЮЩЕМУ (Р11), однократно (Ф7-03, Ф7-53) и срочно (Ф7-34, Ф7-54). Срок у обеих процедур — одна величина контракта (§7 инв. 5).

func (c AccessKeyChallenge) StateAt(now time.Time) AccessKeyChallengeState

func (c AccessKeyChallenge) Validate() error

type AccessKeyChallengePurpose ¶ added in v0.5.0

type AccessKeyChallengePurpose string

AccessKeyChallengePurpose — процедура, для которой выдано испытание. Испытание регистрации утверждением не предъявить и наоборот: словарь закрыт ограничением схемы.

const (
	// ChallengeForRegistration — испытание церемонии регистрации (§7.1).
	ChallengeForRegistration AccessKeyChallengePurpose = "registration"
	// ChallengeForAssertion — испытание предъявления (§7.2).
	ChallengeForAssertion AccessKeyChallengePurpose = "assertion"
)

func AccessKeyChallengePurposes() []AccessKeyChallengePurpose

type AccessKeyChallengeState ¶ added in v0.5.0

type AccessKeyChallengeState string

AccessKeyChallengeState — состояние испытания регистрации на момент предъявления: три различимых состояния (Ф7-34), плюс «выдано».

const (
	// ChallengeIssued — выдано, не предъявлено, срок не вышел.
	ChallengeIssued AccessKeyChallengeState = "issued"
	// ChallengeUnknown — служба такого не выдавала (Ф7-02).
	ChallengeUnknown AccessKeyChallengeState = "unknown"
	// ChallengeConsumed — уже предъявлено (Ф7-03).
	ChallengeConsumed AccessKeyChallengeState = "consumed"
	// ChallengeExpired — срок вышел (Ф7-34).
	ChallengeExpired AccessKeyChallengeState = "expired"
)

type AccessKeyDescription ¶ added in v0.5.0

type AccessKeyDescription string

AccessKeyDescription — описание ключа: свободный текст с пределом в ЗНАКАХ.

Тип свой, а не `Description` соседей, потому что у них проверка входа считает БАЙТЫ (`len > 256`), а схема — знаки: на кириллической метке две формы расходятся — 200 знаков есть 400 байт. Здесь единица одна — знак, как у схемы и у фундаментного валидатора `corevalidate.Description` (Р10). Расхождение у соседей — их предмет, здесь оно только названо.

func (d AccessKeyDescription) Validate() error

type AccessKeyID ¶ added in v0.5.0

type AccessKeyID string

AccessKeyID — платформенный идентификатор ключа (Р10). Единственное, чем ключ адресуется извне.

func (id AccessKeyID) Validate() error

type AccessKeyLoginChallenge ¶ added in v0.5.0

type AccessKeyLoginChallenge struct {
	// Challenge — случайные байты; ключ строки. Длина — та же, что у
	// испытаний церемоний (`AccessKeyChallengeBytes`).
	Challenge []byte
	// FormContext — контекст формы, под которым испытание выдано. Одно ЖИВОЕ
	// испытание на контекст держит частичная уникальность схемы, а не
	// проверка перед вставкой (ban #10).
	FormContext string
}

AccessKeyLoginChallenge — выдаваемое испытание полосы входа: привязано к контексту формы (Р2), однократно (Ф13-08) и срочно.

func (c AccessKeyLoginChallenge) Validate() error

type AccessKeyName ¶ added in v0.5.0

type AccessKeyName string

AccessKeyName — имя ключа одной формы дерева (DNS label RFC 1123). Форма — у фундамента; здесь тип для колонки, чтобы «что записывается» судилось тем же валидатором, что у всех именуемых ресурсов службы.

func (n AccessKeyName) Validate() error

type AccessTarget ¶

type AccessTarget struct {
	AllInScope bool          // whole-anchor grant (incl. future objects)
	Resources  []ResourceRef // per-object grant (mutually exclusive with AllInScope)
}

AccessTarget — выбор объектов выдачи (F8). Значима ровно одна ветвь; нулевое значение — выдача на весь якорь (смысл AllInScope).

func (t AccessTarget) Contains(dottedType, id string) bool

func (t AccessTarget) Digest() string

func (t AccessTarget) DistinctTypes() []string

func (t AccessTarget) FirstNonLiveType(cat TargetTypeCatalog) (string, bool)

func (t AccessTarget) IsEmpty() bool

func (t AccessTarget) ResourceIDsForTypes(types []string) []string

func (t AccessTarget) Validate() error

type Account ¶

type Account struct {
	ID          AccountID
	Name        AccountName
	Description Description
	Labels      Labels
	OwnerUserID UserID
	CreatedAt   time.Time
}

Account — top-level tenant («организация» как товар продукта IAM). Замещает прежнюю связку tenant+folder из retired kacho-resource-manager. Уникальное имя глобально (DB UNIQUE accounts_name_unique).

FK: owner_user_id → users(id) ON DELETE RESTRICT. Удаление RESTRICT при наличии Project / ServiceAccount / Group / custom Role.

func (a Account) StructuralFacts() []StructuralTuple

cluster:<singleton>  →  cluster  →  account:<id>     (levels 1-2 reach it here)
user:<owner>         →  owner    →  account:<id>

func (a Account) Validate() error

type AccountID ¶

type AccountID string

AccountID / ProjectID / ... — newtypes over string, never bare ids.

type AccountName ¶

type AccountName string

Every newtype below has its own regex.

func (n AccountName) Validate() error

type Arm ¶

type Arm int

Arm classifies a rule's selector arm.

const (
	ArmAnchor Arm = iota
	ArmNames
	ArmLabels
)

type AssertionClient ¶

type AssertionClient struct {
	// ID — НАШ идентификатор строки реестра. Им и только им клиент себя
	// называет: он же издатель и субъект утверждения.
	ID string
	// Kind — из какой таблицы реестра строка прочитана.
	Kind AssertionClientKind
	// OwnerID — принципал, от чьего имени клиент получает токен.
	OwnerID string
	// PublicKeyPEM — зарегистрированный открытый ключ.
	PublicKeyPEM string
	// Algorithm — ЗАРЕГИСТРИРОВАННЫЙ алгоритм. Пустое значение — законный вход
	// схемы, и означает оно «ключа нет», а НЕ «любой алгоритм».
	Algorithm string
	// ExpiresAt — момент истечения клиента в Unix-секундах; 0 означает
	// «бессрочно», и это законное состояние схемы (колонка допускает NULL).
	ExpiresAt int64
	// Отзыв ключа НЕ является здесь полем, и это не упущение: колонки отзыва в
	// схеме обеих таблиц НЕТ — отзыв выражен СНЯТИЕМ СТРОКИ. Завести поле
	// значило бы описать состояние, которого схема не допускает, и построить
	// на нём пробу, которую нечем поставить (F1 §14 п. 2). Отозванный клиент
	// не резолвится вовсе, и отказ наступает на том же шаге, что для
	// несуществующего, — то есть требование «отозванный токена не получает»
	// выполняется by construction, а не проверкой поля.
	// OwnerActive — владелец в состоянии ACTIVE. Не-ACTIVE — это ДВА значения
	// словаря (PENDING и BLOCKED), и оба обязаны давать один исход.
	OwnerActive bool
	// DeclaredAudiences — сужение адресатов, ОБЪЯВЛЕННОЕ заказчиком ключа при
	// его выдаче (`IssueSAKeyRequest.audience`, задача kacho#1136).
	//
	// ПУСТОЙ ПЕРЕЧЕНЬ ОЗНАЧАЕТ «СУЖЕНИЯ НЕ ОБЪЯВЛЕНО», А НЕ «ЛЮБОЙ АДРЕСАТ», и
	// это НЕ тот класс, что пустой список доверенных отправителей. Там пустое
	// значение снимало единственный контроль; здесь оно оставляет ВНЕШНЮЮ
	// границу — объявленный посадкой перечень адресатов, который страж старта
	// требует непустым и без которого выдача не строится вовсе. Сужение ключа
	// действует ВНУТРИ этой границы и никогда её не расширяет: адресат, которого
	// посадка не объявила, не выдаётся ни одному ключу, как бы он ни объявился.
	//
	// У клиента пользовательского токена перечня нет BY CONSTRUCTION: адресата
	// его токена проставляет сам сервис из своей настройки, и заказчик не вправе
	// назвать его вовсе (решение Р2, `interactive_client.proto`). Поэтому сужать
	// там нечем, и пустое значение на том пути — не умолчание, а отсутствие
	// предмета.
	DeclaredAudiences []string
}

AssertionClient — строка реестра, способная предъявить утверждение.

Зеркального значения (идентификатора клиента во внешнем сервере) здесь НЕТ, и это не упущение: оно не участвует в разрешении клиента ни как второй ключ поиска, ни как запасной (приёмка F2 §2.1). Субъект с двумя именами дал бы две записи журнала об одном действии и два ключа однократности на одно утверждение — то есть отменил бы однократность, сохранив её форму.

func (c AssertionClient) CanPresentAssertion() bool

type AssertionClientKind ¶

type AssertionClientKind string

AssertionClientKind — вид клиента, способного доказать владение ключом.

Словарь ЗАКРЫТ и содержит ровно те виды, у которых в схеме есть ключевой материал. Интерактивного клиента здесь нет НАМЕРЕННО: у него нет способа доказать владение ключом by construction, поэтому он не резолвится ни во что, и отказ наступает на том же шаге, что и для несуществующего клиента (приёмка F2 §2.9). Формулировка «нашли строку, ключ пуст» потребовала бы, чтобы кто-то поддерживал в третьей таблице инвариант «ключа быть не должно»; инвариант, который надо поддерживать, ломается, а выраженный отсутствием таблицы на пути — нет.

const (
	// AssertionClientUser — клиент, через который выдаётся токен пользователя.
	AssertionClientUser AssertionClientKind = "user"
	// AssertionClientServiceAccount — клиент ключа служебной учётки.
	AssertionClientServiceAccount AssertionClientKind = "service_account"
)

func AssertionClientKinds() []AssertionClientKind

type AssignableRole ¶

type AssignableRole struct {
	RoleID      RoleID
	Name        RoleName
	Description Description
	IsSystem    bool
	ScopeGroup  RoleScopeGroup
	CreatedAt   time.Time
}

AssignableRole — the lean projection of a Role for the grant-form picker Carries only publicly-safe fields the UI needs to render + group the picker (id / resolved name / description / is_system / server-computed scope_group / created_at) — NO permissions array and no infra-sensitive fields. ScopeGroup is computed via ScopeGroupOf.

type AuditEventID ¶

type AuditEventID string

AuditEventID — идентификатор записи журнала: `evt_` плюс 20…30 символов crockford-base32 (ограничение `audit_outbox_id_check`, миграция `0001_initial.sql`).

Тело СЛУЧАЙНО, а не производно от времени: производитель (`pg.newAuditEventID`) берёт 14 байт у источника случайности и печатает из них 22 символа. Порядок по идентификатору поэтому НЕ является порядком по времени; сортировать журнал надо по `created_at`. Прежняя редакция называла его ULID — то есть обещала ровно ту сортируемость, которой нет.

func (id AuditEventID) Validate() error

type AuditOutboxEntry ¶

type AuditOutboxEntry struct {
	ID              AuditEventID
	EventType       EventTypeName
	TenantAccountID *AccountID
	EventPayload    json.RawMessage
	Status          AuditOutboxStatus
	Attempts        int
	CreatedAt       time.Time
	NextAttemptAt   time.Time
}

AuditOutboxEntry — строка журнала аудита `kaname.audit_outbox` (заведён миграцией `0001_initial.sql`), дописываемая только вперёд.

Что происходит на самом деле ¶

Строка ложится в ТУ ЖЕ транзакцию, что и мутация домена, и оттуда вывозится в приёмник журнала — поток структурных записей службы (`cmd/kaname/audit_shipper_wiring.go`, механизм — `pkg/audit`). Состояние строки после этого помечено доставленным, а состояние очереди целиком снимает периодический сканер (`cmd/kaname/outbox_metrics_wiring.go`).

Здесь было описано ОТСУТСТВИЕ доставки — у него больше нет предмета ¶

Прежняя редакция объясняла, почему дренаж неконструируем: приёмника аудита не существовало ни одного, и из четырёх объявленных состояний достижимо было ровно одно. Оба утверждения были верны на день записи и перестали быть верными вместе с приёмником (kacho#812): состояний теперь ДВА и оба достижимы, потому что словарь сужен до того, что продукт производит.

Здесь стояло описание, неверное ЧЕТЫРЕЖДЫ ¶

Прежняя редакция объявляла: дренаж отправляет строки в топик брокера; журнал заведён миграцией 0013; идентификатор — ULID; ULID сортируется по времени. Верно из этого ноль. Брокера в продукте нет и он запрещён non-negotiable #7; миграция 0013 — про снятие перечня условий обхода; идентификатор собирается из СЛУЧАЙНЫХ байт (`newAuditEventID`, 22 символа crockford-base32), то есть по времени не сортируется ни в каком порядке. Опасен был не сам текст, а его направление: он описывал систему СЛОЖНЕЕ и исправнее, чем она есть, поэтому читатель уходил искать дренаж и топик вместо того, чтобы увидеть, что доставки нет вовсе.

func (e AuditOutboxEntry) Validate() error

type AuditOutboxStatus ¶

type AuditOutboxStatus string

AuditOutboxStatus — состояние ДОСТАВКИ строки журнала.

Значений ровно два, и столько же допускает ограничение таблицы (миграция `20260823001500_audit_journal_gets_its_receiver.sql`). Прежде их объявлялось четыре: «в полёте» и «отказ» не писал никто и никогда — полёта не существует, потому что строка держится блокировкой своей транзакции от клейма до пометки, а терминального отказа не существует, потому что у приёмника нет класса «не приму никогда». Значение, которого продукт произвести не умеет, обещает подсистему, которой нет.

const (
	AuditOutboxStatusPending AuditOutboxStatus = "pending"
	AuditOutboxStatusSent    AuditOutboxStatus = "sent"
)

func (s AuditOutboxStatus) Validate() error

type BasicCredential ¶

type BasicCredential struct {
	// PrincipalType — "user" | "service_account".
	PrincipalType string
	PrincipalID   string
	DisplayName   string
	// CredentialID — идентификатор СТРОКИ; им адресуется отзыв.
	CredentialID string
	ExpiresAt    time.Time
}

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

type BasicCredentialRefusalReason ¶ added in v0.5.0

type BasicCredentialRefusalReason string

BasicCredentialRefusalReason — ПРИЧИНА единого отказа полосы базового секрета (задача kaname#379). Закрытый словарь.

Почему причина есть, а отказ всё равно один ¶

Наружу полоса отвечает ОДНИМ отказом — ErrBasicCredentialRefused: различимый исход был бы оракулом. Но отказ, неотличимый и внутри, делает каждый контроль полосы ненаблюдаемым: отсечка отзыва-всех, сработавшая тысячу раз, выглядит так же, как перебор секрета, и так же, как контроль, не сработавший ни разу.

Поэтому причина едет ВНУТРЬ — значением ошибки (RefuseBasicCredential) — и читается только BasicCredentialRefusalReasonOf. Текст ошибки остаётся дословно текстом единого отказа: вызывающий, напечатавший её, различия не увидит, а на провод полоса отдаёт свой фиксированный текст и вовсе не значение ошибки.

const (
	// BasicRefusalMalformed — предъявленное не называет удостоверения, которое
	// у нас может быть: пусто, форма или контрольная сумма не сходятся, вид по
	// приставке идентификатора не наш. База не спрашивалась.
	BasicRefusalMalformed BasicCredentialRefusalReason = "malformed"
	// BasicRefusalNotFound — живой строки нет: отозвано, истекло, владелец
	// неактивен либо её не было никогда. Внутри эти случаи тоже неразличимы, и
	// это не упущение: их отсекает один предикат одного оператора, а не
	// развилка, и развести их значило бы завести второй запрос.
	BasicRefusalNotFound BasicCredentialRefusalReason = "not-found"
	// BasicRefusalSecretMismatch — строка есть, секрет не тот.
	BasicRefusalSecretMismatch BasicCredentialRefusalReason = "secret-mismatch"
	// BasicRefusalOwnerRevoked — удостоверение выдано не позже отсечки
	// отзыва-всех его владельца-человека. Имя то же, что у исхода полосы ключа
	// токен-эндпоинта: один контроль — одно имя на всех полосах, которые его
	// исполняют.
	BasicRefusalOwnerRevoked BasicCredentialRefusalReason = "owner-revoked"
	// BasicRefusalOwnerUnverified — владелец-человек удостоверения не
	// подтвердил адрес (kaname#456, Р5). Имя то же, что у исхода полосы ключа
	// токен-эндпоинта: один вердикт правила выдачи — одно имя.
	BasicRefusalOwnerUnverified BasicCredentialRefusalReason = "owner-unverified"
)

func BasicCredentialRefusalReasonOf(err error) (BasicCredentialRefusalReason, bool)

func BasicCredentialRefusalReasons() []BasicCredentialRefusalReason

type BearerDigest ¶ added in v0.5.0

type BearerDigest string

BearerDigest — свёртка носителя в хранилище (шестнадцатеричная запись SHA-256). Сама по себе носителем не является: обратно значение не восстанавливается.

type CeremonyContext ¶ added in v0.5.0

type CeremonyContext struct {
	FamilyID  string
	ClientID  string
	UserID    string
	SessionID string
	Scope     []string
}

CeremonyContext — контекст церемонии: он один на семейство, код и всякий обновляющий токен семейства. Расхождение его копий отвергает СОСТАВНОЙ внешний ключ схемы, а не проверка писателя.

func (c CeremonyContext) Validate() error

type CeremonyHandle ¶ added in v0.5.0

type CeremonyHandle struct {
	// contains filtered or unexported fields
}

CeremonyHandle — рукоятка человека: случайные байты, ни с чем не связанные. Нулевое значение — «рукоятки нет», а не рукоятка.

func NewCeremonyHandle() (CeremonyHandle, error)

func RestoreCeremonyHandle(stored []byte) (CeremonyHandle, error)

func (h CeremonyHandle) Bytes() []byte

func (h CeremonyHandle) CarriesNoNameOf(u User) error

func (h CeremonyHandle) IsZero() bool

func (h CeremonyHandle) Validate() error

type ClientDescription ¶ added in v0.5.0

type ClientDescription struct {
	// contains filtered or unexported fields
}

ClientDescription — приведённое описание клиента; нулевое значение — описания нет.

func NewClientDescription(raw string) ClientDescription

func (c ClientDescription) IsZero() bool

func (c ClientDescription) Value() string

type Cluster ¶

type Cluster struct {
	ID          ClusterID
	Name        ClusterName
	Description Description
	CreatedAt   time.Time
}

Cluster — singleton (id = `cluster_root`). Корень иерархии cluster → account → project → resource. Используется как объект модели прав для `cluster:cluster_root#system_admin@user:usr_xxx`.

func (c Cluster) Validate() error

type ClusterAdminEntry ¶

type ClusterAdminEntry struct {
	ClusterAdminGrantID string
	SubjectType         string
	SubjectID           string
	SubjectEmail        string
	SubjectDisplayName  string
	GrantedByUserID     string
	GrantedByEmail      string // "" when granted_by == "bootstrap"
	GrantedAt           time.Time
}

ClusterAdminEntry — read-projection of one active cluster-admin grant with denormalised user fields (subject email/display_name, granter email) resolved by the ListActive read-adapter's users JOIN. Pure domain view used by the InternalClusterService.ListAdmins use-case + handler; the pg adapter maps its rows INTO this type so the use-case/handler never import the pgx adapter package (Clean-Architecture dependency rule — the port speaks in domain types).

Denormalised fields (SubjectEmail / SubjectDisplayName / GrantedByEmail) are output-only mirrors; the authoritative subject/granter ids are SubjectID / GrantedByUserID.

type ClusterAdminGrant ¶

type ClusterAdminGrant struct {
	ID           ClusterAdminGrantID
	ClusterID    ClusterID
	SubjectType  GrantSubjectType
	SubjectID    SubjectID
	GrantedBy    string // 'bootstrap' либо user_id (verbatim text)
	GrantedAt    time.Time
	GrantedUntil *time.Time // NULL = permanent
}

ClusterAdminGrant — permanent root grant. Один источник истины для FGA-tuple `cluster_admin`.

Partial UNIQUE (subject_type, subject_id) WHERE granted_until IS NULL гарантирует на DB-уровне, что **permanent** grant у одного subject — один. Temporary grants не входят в модель — есть только permanent.

func (g ClusterAdminGrant) IsActive() bool

func (g ClusterAdminGrant) Validate() error

type ClusterAdminGrantID ¶

type ClusterAdminGrantID string

ClusterAdminGrantID — self-validating newtype, format `cag_<17-crockford>`.

func (id ClusterAdminGrantID) Validate() error

type ClusterID ¶

type ClusterID string

ClusterID — fixed literal `cluster_root` (singleton constraint в DB).

func (id ClusterID) Validate() error

type ClusterName ¶

type ClusterName string

ClusterName — отображаемое имя singleton-кластера: длина 1..64 и БОЛЬШЕ ничего. Здесь стояло «kebab-case», и это было обещанием алфавита, которого проверка не делает ни в одной ветке.

Форму имени ресурса (`pkg/validate/nameform`) поле НЕ несёт намеренно: оно не задаётся клиентом — значение пишет посевная миграция, а у службы кластера нет глагола, который бы его менял.

func (n ClusterName) Validate() error

type CodeDigest ¶ added in v0.5.0

type CodeDigest string

CodeDigest — свёртка кода в хранилище (шестнадцатеричная запись SHA-256).

type ContainerSelector ¶ added in v0.5.0

type ContainerSelector struct {
	// Type — точечный тип контейнера (`registry.registries`), словарь каталога.
	Type string
	// OwnerFP — отпечаток правила-владельца: его селектор и выбирает контейнер.
	// По нему разворачивание выдачи классу узнаёт, что контейнер в составе выдачи
	// ИМЕННО этим правилом (а не соседним), прежде чем писать `public_reader`.
	// В хранимую строку селектора не едет: решению о доступе он не нужен.
	OwnerFP       string
	Arm           Arm
	ResourceNames []string          // ArmNames only
	MatchLabels   map[string]string // ArmLabels only
}

ContainerSelector — тип и отбор правила-владельца вложенного правила (kaname#874). Ветвь — та же, что у правила верхнего уровня: якорь выбирает все контейнеры типа, имена — названные, метки — с совпавшими метками.

type CredentialKind ¶

type CredentialKind string

CredentialKind — ЧЕМ УДОСТОВЕРЕНИЕ СЕБЯ ПРЕДЪЯВЛЯЕТ (задача kacho#1142, приёмка BAT-1 §2.5, §4.1).

Значение — то же, что лежит в колонке `credential_kind` обеих таблиц удостоверений: второго написания не заводится. Вид ЗАПИСЫВАЕТСЯ при вставке и читателем НЕ вычисляется: правила вывода вида по содержимому строки в службе нет.

Словарь закрыт, и видов в нём три. Четвёртый, LEGACY, описывал строки прежнего потока без собственного ключевого материала и снят вместе со столбцом имени клиента у прежнего издателя (kaname#362): вид был определён через этот столбец, и строк этого вида миграция снятия не допускает.

const (
	// CredentialKindUnspecified — вид не назван вызывающим. Встречается ТОЛЬКО
	// во входе выдачи и разрешается сохранённым поведением; в строке
	// удостоверения не бывает.
	CredentialKindUnspecified CredentialKind = ""

	// CredentialKindKeypair — ключевая пара ES256: вызывающий сам собирает и
	// подписывает `client_assertion` и обменивает его.
	CredentialKindKeypair CredentialKind = "KEYPAIR"

	// CredentialKindSecret — однострочный непрозрачный секрет, предъявляемый
	// как есть.
	CredentialKindSecret CredentialKind = "SECRET"

	// CredentialKindFederated — удостоверение предъявляет ВНЕШНИЙ издатель по
	// перечню доверенных субъектов; ни материала, ни секрета у нас нет.
	CredentialKindFederated CredentialKind = "FEDERATED"
)

func ResolveIssuedKind(asked CredentialKind, hasTrustedSubjects, federationSupported bool) (CredentialKind, error)

func (k CredentialKind) IsIssuable() bool

func (k CredentialKind) String() string

type Description ¶

type Description string

func (d Description) Validate() error

type Discoverability ¶ added in v0.5.0

type Discoverability string

Discoverability — область значений признака обнаружимости: ТРИ состояния (Р12). «Не сообщено» — своё значение, а не пустое и не «нет»: пустая строка состоянием не является и до записи не доживает.

const (
	// DiscoverabilityConfirmed — расширение результата церемонии сообщило
	// «обнаруживаемое» (`credProps.rk = true`).
	DiscoverabilityConfirmed Discoverability = "discoverable"
	// DiscoverabilityNotDiscoverable — расширение сообщило «не обнаруживаемое».
	// Писателя у состояния сегодня нет: приём церемонии такой результат
	// отвергает (Ф7-41), — но область значений факта его содержит (Ф7-57).
	DiscoverabilityNotDiscoverable Discoverability = "not-discoverable"
	// DiscoverabilityUnreported — расширения в результате нет.
	DiscoverabilityUnreported Discoverability = "unreported"
)

func AccessKeyDiscoverabilities() []Discoverability

func DiscoverabilityFromExtension(rk *bool) Discoverability

func (d Discoverability) Validate() error

type DisplayName ¶

type DisplayName string

func (d DisplayName) Validate() error

type Email ¶

type Email string

func (e Email) Validate() error

type EmailChangeCode ¶ added in v0.5.0

type EmailChangeCode struct {
	ID     EmailChangeCodeID
	UserID UserID
	// NewEmail — новый адрес в приведённом виде.
	NewEmail Email
	// Digest — свёртка кода; пусто — новый адрес занят на запросе, кода нет.
	Digest CodeDigest
	// IssuedAt — момент запроса (часы полосы); по нему считается темп (Р6).
	IssuedAt time.Time
	// ExpiresAt — абсолютный срок; величина — настройка.
	ExpiresAt time.Time
}

EmailChangeCode — запись принятого запроса смены адреса. Состав закрыт.

func (c EmailChangeCode) Validate() error

type EmailChangeCodeID ¶ added in v0.5.0

type EmailChangeCodeID string

EmailChangeCodeID — идентификатор строки отложенной смены. Наружу не адресуется.

type EventTypeName ¶

type EventTypeName string

EventTypeName — `^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$` (CHECK).

func (n EventTypeName) Validate() error

type ExternalSubject ¶

type ExternalSubject string // OIDC sub

func NewOwnLaneSubject() ExternalSubject

func (s ExternalSubject) IsOwnLane() bool

func (s ExternalSubject) Validate() error

type FamilyRevocationReason ¶ added in v0.5.0

type FamilyRevocationReason string

FamilyRevocationReason — причина отзыва семейства. Словарь ЗАКРЫТ и совпадает с ограничением `token_families_revoked_reason_ck`: корзины «прочее» у него нет, и значение вне перечня — наша ошибка, а не чужая. Совпадение в обе стороны держит проба живой схемы `TestIntegration_RevocationVocabularyAgreesWithTheDomain`, а то, что у каждого слова есть писатель, — гейт `TestFamilyRevocationVocabulary_KN_FRV_17_EveryWordHasAWriter`: слово, которого никто не пишет, перечень превращает в обещание (kaname#339).

const (
	// FamilyRevokedByCodeReplay — повторное предъявление кода авторизации.
	FamilyRevokedByCodeReplay FamilyRevocationReason = "code-replay"
	// FamilyRevokedByRefreshReplay — повторное предъявление обновляющего токена.
	FamilyRevokedByRefreshReplay FamilyRevocationReason = "refresh-replay"
	// FamilyRevokedBySessionEnd — сессия, в которой шла церемония, снята.
	FamilyRevokedBySessionEnd FamilyRevocationReason = "session-ended"
	// FamilyRevokedByClientRevocation — клиент, которому выдан грант, сам
	// попросил отзыва (RFC 7009). Написание — дословно причина фундамента
	// `oauthceremony.RevocationClientRevoke`: адаптер порта отзыва сопрягает
	// словари ПО ЗНАЧЕНИЮ (`ceremonyport.FamilyReasonOf`), и другое написание
	// оставило бы причину без слова (kaname#406).
	FamilyRevokedByClientRevocation FamilyRevocationReason = "client-revoke"
)

func FamilyRevocationReasons() []FamilyRevocationReason

func (r FamilyRevocationReason) Validate() error

type FeedSource ¶

type FeedSource int8

FeedSource — where the reconciler reads candidate objects for a selectable type (D7).

const (
	// FeedMirror — candidates read from kaname.resource_mirror (labels @>
	// matchLabels); containment from mirror.parent_* (D7). Mirror-fed types can be
	// PENDING_VERIFICATION (object not yet mirrored). Consumer-owned resources:
	// compute / vpc / loadbalancer.
	FeedMirror FeedSource = iota
	// FeedIAMDirect — candidates read SAME-DB from IAM's own resource table;
	// containment via iam-hierarchy (project ⊑ account ⊑ cluster). Never PENDING
	// (the object is always in its own table the instant it exists). Покрывает ВСЕ
	// iam-native типы (любой `iam.*`): account / project / user / serviceAccount /
	// group / role / accessBinding — все label-selectable под единой моделью.
	FeedIAMDirect
)

func FeedSourceForType(objectType string) FeedSource

type FormKind ¶ added in v0.5.0

type FormKind string

FormKind — вид формы, к которому привязан признак защиты от подделки запроса (Р12). Перечень ЗАКРЫТ и объявлен один раз; Ф4 и Ф5 дописывают свои виды сюда, а не заводят второй перечень.

const (
	FormLogin    FormKind = "login"
	FormLogout   FormKind = "logout"
	FormPassword FormKind = "password"
	// FormRegister — форма регистрации (Ф4 Р1; форма защищена признаком, как и
	// прочие, меняющие состояние, — Ф1-39…43).
	FormRegister FormKind = "register"
	// Восстановление доступа (Ф5, `kacho#1271`) — две формы, два вида: запрос
	// кода и его предъявление с новым паролем. Признак одной не годится другой
	// (Ф1 Р6): у них разные предметы и разные последствия.
	FormRecovery         FormKind = "recovery"
	FormRecoveryComplete FormKind = "recovery-complete"
	// Второй фактор (Ф12, `kacho#1281`, Р4): один вид на четыре глагола
	// семейства `second-factor/*` — у них один предмет (заведённый фактор
	// самого человека) — и свой вид у церемонии повышения: её зовут и без
	// фактора, ветвью пароля (Ф11-09), и признак семейства ей не годится.
	FormSecondFactor FormKind = "second-factor"
	FormStepUp       FormKind = "step-up"
	// FormStepUpAccessKeyBegin — выдача испытания повышения ключом доступа под
	// живой сессией (kaname#827, приёмка SUA Р2): свой вид, а не вид
	// церемонии — выдача меняет состояние (заводит испытание сессии), и признак
	// церемонии на форме выдачи не предъявим, и наоборот.
	FormStepUpAccessKeyBegin FormKind = "step-up-access-key-begin"
	// Подтверждение адреса (kaname#456, Р6; имена ратифицированы — Ф6 Р15):
	// запрос письма и предъявление кода — две формы, два вида, и признак одного
	// другому не годится.
	FormVerifyEmail        FormKind = "verify-email"
	FormVerifyEmailConfirm FormKind = "verify-email-confirm"
	// Вход ключом доступа (Ф13 Р1, решение владельца 2026-09-22): ДВА вида на
	// два глагола `access-key/begin` и `access-key/login`. Оба меняют состояние
	// — `begin` заводит испытание и считается попыткой, `login` выдаёт сессию,
	// — и проверка «вид признака — вид ЭТОЙ формы» (Ф3 Р12) обязана их
	// различать: признак формы запроса на форме подтверждения не предъявим, и
	// наоборот. Контекст при этом ОДИН (печенье `kaname_form`).
	FormAccessKeyBegin FormKind = "access-key-begin"
	FormAccessKeyLogin FormKind = "access-key-login"
	// FormPasswordEnroll — заведение первого пароля из живой сессии (kaname#213,
	// приёмка A7 Р1): свой вид, не вид смены — заведение и смена суть разные
	// действия с разными основаниями.
	FormPasswordEnroll FormKind = "password-enroll"
	// Смена адреса почты (kaname#635, приёмка email-change Р1): запрос смены и
	// предъявление кода с нового адреса — две формы, два вида; признак одного
	// другому не годится.
	FormEmailChange        FormKind = "email-change"
	FormEmailChangeConfirm FormKind = "email-change-confirm"
	// FormSessionEnd — снятие своих записей сессии (kaname#634, Р1): ОДИН вид на
	// оба снимающих глагола — выход из выбранной и из всех, кроме текущей. Предмет
	// у них один (снятие своих записей), и признак различает формы, а не исходы —
	// как у семейства второго фактора.
	FormSessionEnd FormKind = "session-end"
)

func FormKinds() []FormKind

func ParseFormKind(s string) (FormKind, error)

type GrantDelegation ¶ added in v0.7.0

type GrantDelegation struct {
	ID        GrantDelegationID
	AccountID AccountID
	// DelegateID — служебная учётка-делегат. Тип делегата один
	// (`SubjectTypeServiceAccount`), поэтому хранится только идентификатор.
	DelegateID   ServiceAccountID
	RoleIDs      []RoleID
	TargetTypes  []string
	SubjectTypes []SubjectType
	// Module — модуль ролей и типов делегирования; выводится, на вход не
	// принимается.
	Module      string
	Status      GrantDelegationStatus
	DelegatedBy GrantDelegationActor
	CreatedAt   time.Time
	RevokedAt   *time.Time
	RevokedBy   *GrantDelegationActor
}

GrantDelegation — делегирование права выдавать.

func SortedGrantDelegationAxes(d GrantDelegation) GrantDelegation

func (d GrantDelegation) Active() bool

func (d GrantDelegation) AllowsRole(id RoleID) bool

func (d GrantDelegation) AllowsSubjectType(t SubjectType) bool

func (d GrantDelegation) AllowsTargetType(dotted string) bool

func (d GrantDelegation) IsDelegate(principalType, principalID string) bool

func (d GrantDelegation) IsDelegateSubject(s Subject) bool

type GrantDelegationActor ¶ added in v0.7.0

type GrantDelegationActor struct {
	Type string
	ID   string
}

GrantDelegationActor — принципал шага жизненного цикла: вид ("user" | "service_account") и идентификатор.

type GrantDelegationID ¶ added in v0.7.0

type GrantDelegationID string

GrantDelegationID — идентификатор делегирования.

type GrantDelegationStatus ¶ added in v0.7.0

type GrantDelegationStatus string

GrantDelegationStatus — состояние делегирования; слово хранения.

const (
	// GrantDelegationActive — делегирование действует.
	GrantDelegationActive GrantDelegationStatus = "ACTIVE"
	// GrantDelegationRevoked — отозвано; конечное состояние.
	GrantDelegationRevoked GrantDelegationStatus = "REVOKED"
)

type GrantSubjectType ¶

type GrantSubjectType string

GrantSubjectType — enum: user|service_account (NOT group: cluster-admin grant — strictly individual identity for audit). Backed by migration 0011 CHECK.

const (
	GrantSubjectTypeUser           GrantSubjectType = "user"
	GrantSubjectTypeServiceAccount GrantSubjectType = "service_account"
)

func (t GrantSubjectType) Validate() error

type Group ¶

type Group struct {
	ID          GroupID
	AccountID   AccountID
	Name        GroupName
	Description Description
	Labels      Labels
	CreatedAt   time.Time
}

Group — Account-scoped (account_id FK ON DELETE RESTRICT), имеет members (User или ServiceAccount — полиморфно через `group_members.member_type`). Используется в AccessBinding для упрощения раздачи прав.

func (g Group) Validate() error

type GroupID ¶

type GroupID string

type GroupMember ¶

type GroupMember struct {
	GroupID    GroupID
	MemberType SubjectType // user | service_account (group из enum'а исключен)
	MemberID   SubjectID
	AddedAt    time.Time
}

GroupMember — связка group_id ↔ (member_type, member_id). Целостность member_id обеспечивается DB-триггером `group_members_member_exists_trg` (нет полиморфного FK в Postgres).

func (m GroupMember) Validate() error

type GroupName ¶

type GroupName string

func (n GroupName) Validate() error

type HumanSession ¶ added in v0.5.0

type HumanSession struct {
	ID     HumanSessionID
	UserID UserID
	// AuthenticatedAt — момент аутентификации. Неподвижен всю жизнь записи
	// (Ф11 Р6): край сравнивает его с отсечкой.
	AuthenticatedAt time.Time
	// LastPresentedAt — момент последнего ПРЕДЪЯВЛЕНИЯ СПОСОБА (сверка
	// пароля, кода, ключа), не носителя запросу. Читается внутри службы.
	LastPresentedAt time.Time
	// ExpiresAt — абсолютный срок, ОДИН (F4d-27): окна бездействия нет.
	ExpiresAt time.Time
	// AssuranceLevel — по правилу Ф11 от множества предъявленного.
	AssuranceLevel string
	// PresentedMethods — множество предъявленного (Ф11 Р2), слова словаря
	// `assurance.Methods`. Читается внутри службы правилом уровня.
	PresentedMethods []string
	// Client — описание клиента, каким его назвал запрос выдачи (kaname#634,
	// Р3). Пишет его ТОЛЬКО операция выдачи; перевыпуск носителя его не трогает.
	// Читатель — ровно перечень своих сессий: в ответ краю и в событие аудита оно
	// не идёт.
	Client ClientDescription
	// CreatedAt назначает запись.
	CreatedAt time.Time
}

HumanSession — запись сессии (Р1). Состав закрыт: поле без читателя есть значение, которое пишут и не читают.

func (s HumanSession) Expired(now time.Time) bool

func (s HumanSession) Validate() error

type HumanSessionID ¶ added in v0.5.0

type HumanSessionID string

HumanSessionID — идентификатор записи сессии. Адресуется ровно одним внешним путём — её ВЛАДЕЛЬЦЕМ на полосе формы (kaname#634, приёмка `own-sessions-are-listed-and-ended-by-their-owner.md`, Р4, Р5): перечень своих сессий его называет, выход из выбранной его принимает. Края он достигает ровно одним путём — ответом `Resolve` о носителе, и край возвращает его службе метаданным доверенного отправителя, чтобы снятие ключа доступа оставило текущую запись живой (Ф13 Р8, kaname#677). Носителем он не является и о субъекте ничего не говорит; субъект глагола — всегда субъект носителя запроса (у снятия ключа — переданная личность).

func ParseHumanSessionID(s string) (id HumanSessionID, ok bool)

type InteractiveClient ¶

type InteractiveClient struct {
	ID          InteractiveClientID
	CreatedAt   time.Time
	Name        InteractiveClientName
	Description Description
	Labels      Labels

	// RedirectURIs — where the provider may deliver an authorization code.
	// At least one, every one an absolute https:// URL.
	RedirectURIs []string
	// PostLogoutRedirectURIs — optional; same https:// rule when present.
	PostLogoutRedirectURIs []string

	// ClientID — provider-side client id (output-only).
	ClientID string
	// Audiences — stamped by iam from its own configuration (output-only).
	Audiences []string
	// GrantTypes — always exactly authorization_code + refresh_token (output-only).
	GrantTypes []string
	// TokenEndpointAuthMethod — provider-side auth method (output-only).
	TokenEndpointAuthMethod string

	Status InteractiveClientStatus
}

InteractiveClient — the OAuth2 client through which a HUMAN completes an interactive sign-in ceremony.

Provider-side fields (ClientID, Audiences, GrantTypes, TokenEndpointAuthMethod) are OUTPUT-ONLY: they are decided by iam and the identity provider, never by the caller. Audiences in particular is a decision, not an omission — see Р2 in the acceptance: a field that can be set but cannot be set CORRECTLY is a field without a reader, and one that can be set incorrectly breaks the edge silently.

func (c InteractiveClient) Validate() error

type InteractiveClientID ¶

type InteractiveClientID string

InteractiveClientID — id of an InteractiveClient. Hyphen canon `ic-<17>` (ids.PrefixInteractiveClientHyphen), immutable for the life of the resource and the only externally addressable identity (core rule #15).

type InteractiveClientName ¶

type InteractiveClientName string

InteractiveClientName — cluster-unique cosmetic label. Judged by the single resource-name form of the tree, so the DB CHECK and this validator agree.

func (n InteractiveClientName) Validate() error

type InteractiveClientStatus ¶

type InteractiveClientStatus string

InteractiveClientStatus — lifecycle status.

const (
	InteractiveClientActive   InteractiveClientStatus = "ACTIVE"
	InteractiveClientDeleting InteractiveClientStatus = "DELETING"
)

func (s InteractiveClientStatus) Validate() error

type InviteStatus ¶

type InviteStatus string

InviteStatus — invite-flow state for a User row.

PENDING — created via `UserService.Invite`, external_id="" until first login; the invitee has not yet registered and verified the address. ACTIVE — either self-registration on our sign-in lane without a pending invite, or a PENDING row activated by confirming the invited address. BLOCKED — административный запрет на членство в Account'е. Ставится и снимается ДЕЙСТВИЯМИ `UserService.Block` / `Unblock` (право `identity_suspender@iam_user` = админ аккаунта плюс каскад облака; `v_update` с этого типа снят, kacho#1128); писатель — `userWriter.SetInviteStatus`.

Состояние принадлежит СТРОКЕ ЧЛЕНСТВА, а не человеку. Одна личность держит по строке на каждый Account, поэтому запрет принадлежит тому аккаунту, который его наложил, и не отключает личность там, где она законно активна: выдача токена перебирает набор членств и обслуживает первое аутентифицирующееся, отказывая лишь когда ни одно не может (token_enrichment_service.go).

Снимать запрет самостоятельным действием нельзя: восстановление пароля доказывает владение почтовым ящиком — ровно то, чего администратор, ставя запрет, под сомнение не ставил (см. humansession/recovery_complete.go). Поэтому у пути блокировки ОБЯЗАН быть административный путь снятия, иначе заблокированный окажется заперт навсегда. Гейт blocked_state_reachability_test.go требует, чтобы каждый писатель этого состояния был объявлен вместе со ссылкой на снятие, — и делает появление одностороннего пути упавшей сборкой, а не открытием.

const (
	InviteStatusPending InviteStatus = "PENDING"
	InviteStatusActive  InviteStatus = "ACTIVE"
	InviteStatusBlocked InviteStatus = "BLOCKED"
)

func (s InviteStatus) MayAuthenticate() bool

func (s InviteStatus) MaySignInToOwnLane() bool

func (s InviteStatus) Validate() error

type KeyID ¶

type KeyID string

KeyID — идентификатор ключа (`kid`).

func (k KeyID) Validate() error

type LabelKey ¶

type LabelKey string

func (k LabelKey) Validate() error

type LabelVal ¶

type LabelVal string

func (v LabelVal) Validate() error

type Labels ¶

type Labels map[LabelKey]LabelVal

Labels — key→val map.

func (l Labels) Validate() error

type LimitKind ¶

type LimitKind string

LimitKind — a dotted token naming what is being counted. Two forms, and only two:

`<domain>.<resource>`            — a resource counted in its carrier
`<domain>.<parent>.<child>`      — how many <child> fit in ONE <parent>

Both forms name REAL types of the authorization model, and the three-part form names two of them. That is a gate rather than a convention: a ceiling stated on a name the platform does not know is a ceiling nobody can check and nobody can show the tenant (§7 п.9 of the acceptance).

func AccountScopedKinds() []LimitKind

func IdentityCarriedKinds() []LimitKind

func PostureStatedKinds() []LimitKind

func (k LimitKind) ChildKind() LimitKind

func (k LimitKind) Nested() bool

func (k LimitKind) ParentKind() LimitKind

func (k LimitKind) Parts() []string

func (k LimitKind) Service() string

type LoginMethod ¶ added in v0.5.0

type LoginMethod struct {
	UserID   UserID
	Kind     LoginMethodKind
	Verifier LoginVerifier
	// State — состояние строки (Ф12 Р1). Обязательно у всякого вида: значение,
	// подставленное молча, было бы вторым местом об одном предмете рядом с
	// умолчанием колонки.
	State LoginMethodState
	// AcceptedStep — последний принятый шаг кода по времени (Ф12 Р5);
	// StepAccepted отделяет «шага ещё не было» от значения: нулевой шаг —
	// законная величина оси, а не отсутствие.
	AcceptedStep int64
	StepAccepted bool
	// CreatedAt назначает запись. У строки `pending` — момент заведения, от
	// которого считается срок (Ф12 Р8); у `active` — момент подтверждения.
	CreatedAt time.Time
	// LastUsedAt — момент последнего ПРИНЯТОГО предъявления способа второго
	// фактора (kaname#827, приёмка SUA Р6): у `totp` — принятый код, у
	// `lookup_secret` — снятый запасной код. LastUsed отделяет «не
	// использовали» от значения: нулевой момент значением оси не является, и
	// отсутствие наружу — отсутствие ключа ответа, а не нулевое время. Пишут
	// его только операторы предъявления; у пароля момента нет — его не
	// допускает проверка схемы.
	LastUsedAt time.Time
	LastUsed   bool
}

LoginMethod — строка способа входа.

Ключ — пара (`UserID`, `Kind`): второй способ того же вида человеку отвергается базой. `UserID` — идентификатор ЧЕЛОВЕКА (`users.id`), а не внешний субъект и не почта: у приглашённого внешнего субъекта нет, почта изменяема.

func (m LoginMethod) Enrolled() bool

func (m LoginMethod) Validate() error

type LoginMethodKind ¶ added in v0.5.0

type LoginMethodKind string

LoginMethodKind — вид способа входа. Словарь ЗАКРЫТ и совпадает с ограничением таблицы `user_login_methods_kind_check`.

ИМЕНА БЕРУТСЯ У СЛОВАРЯ СПОСОБОВ ПРЕДЪЯВЛЕНИЯ (`internal/assurance`, Ф11 Р8), а не пишутся здесь литералами: словарь объявлен ОДИН раз, и второе объявление перечня имён в прод-коде службы — находка гейта `TestAssuranceMethodVocabularyIsDeclaredOnce`. Видов три (Ф12 Р1): пароль · код по времени · набор запасных кодов; ключ доступа (`webauthn`) строкой этой таблицы не является — его хранилище заводит Ф7 своей приёмкой.

func LoginMethodKinds() []LoginMethodKind

func ParseLoginMethodKind(s string) (LoginMethodKind, error)

func (k LoginMethodKind) Validate() error

type LoginMethodState ¶ added in v0.5.0

type LoginMethodState string

LoginMethodState — состояние строки способа (Ф12 Р1). Значений ровно два, закреплены ограничением схемы `user_login_methods_state_check`.

const (
	// LoginMethodStatePending — секрет чеканен, первый код не предъявлен.
	// Способом входа такая строка не является и живёт не дольше окна свежести
	// правки своих данных (Ф12 Р8); снимает её уборка либо новое заведение.
	LoginMethodStatePending LoginMethodState = "pending"
	// LoginMethodStateActive — подтверждён; единственное состояние `password`
	// и `lookup_secret`.
	LoginMethodStateActive LoginMethodState = "active"
)

func (s LoginMethodState) Validate() error

type LoginVerifier ¶ added in v0.5.0

type LoginVerifier struct {
	// contains filtered or unexported fields
}

LoginVerifier — проверочный материал способа входа: хеш пароля в той форме, в какой его создала функция хеширования (прежнего поставщика либо наша). Это СЕКРЕТ: хеш не пароль, но перебор офлайн по нему возможен.

Устройство выбрано так, чтобы материал не уезжал из процесса ни одним общим путём вывода:

• форматирование, журнал и `String` отдают заглушку;
• JSON и текстовая форма ОТКАЗЫВАЮТ;
• материал лежит ЗА УКАЗАТЕЛЕМ. Форматирование обходит неэкспортированное поле, не вызывая методов типа, и печатает его содержимое сырым; указатель на вложенной глубине печатается адресом, а не содержимым. Так тип защищён и там, где его методы не спрашиваются.

Выход у материала ОДИН — `Reveal`. Его вызывающих держит гейт дерева `internal/check` `TestLoginVerifierStaysInside`.

Нулевое значение означает «материала нет» и в строку способа не проходит: отсутствие материала выражается ОТСУТСТВИЕМ строки.

Сравнение через `==` сверяет указатели, а не материал. Сверка предъявленного с хранимым — дело проверяющего (часть П2), и только постоянным временем.

func NewLoginVerifier(material string) (LoginVerifier, error)

func (v LoginVerifier) Format(f fmt.State, verb rune)

func (v LoginVerifier) GoString() string

func (v LoginVerifier) IsZero() bool

func (v LoginVerifier) LogValue() slog.Value

func (v LoginVerifier) MarshalJSON() ([]byte, error)

func (v LoginVerifier) MarshalText() ([]byte, error)

func (v LoginVerifier) Reveal() string

func (v LoginVerifier) SameMaterial(other LoginVerifier) bool

func (v LoginVerifier) String() string

type Membership ¶

type Membership struct {
	ID        MembershipID
	AccountID AccountID
	// AccountName — ЗЕРКАЛО имени аккаунта, источник истины сам аккаунт.
	// Заполняется на чтении соединением в той же БД; пустое значение означает
	// «имя не задано», а НЕ «аккаунта нет».
	AccountName AccountName
	UserID      UserID
	State       MembershipState
	// InvitedBy — кто пригласил. Это и есть след приглашения, ПЕРЕЖИВАЮЩИЙ вход:
	// активация трогает состояние и отметку правки и не трогает это поле.
	// Пусто у членства, заведённого не приглашением.
	InvitedBy UserID
	// CreatedAt — когда членство заведено; для приглашения — когда оно выписано.
	CreatedAt time.Time
	// UpdatedAt — когда состояние менялось в последний раз.
	UpdatedAt time.Time
}

Membership — принадлежность человека аккаунту как ОТДЕЛЬНАЯ связь.

Ресурс ВЫХОДНОЙ: глаголов создания, правки и снятия у него на читающей поверхности нет. Заводит членство приглашение, снимает — исключение из аккаунта, и оба принадлежат потоку человека.

type MembershipID ¶

type MembershipID string

MembershipID — идентификатор членства, дефис-форма `mbr-<17>`.

Он ВЫЧИСЛЯЕТСЯ из пары «человек × аккаунт» неизменяемой SQL-функцией без соли, а не чеканится: писателей строки членства больше одного, и все обязаны прийти к ОДНОЙ строке на одну пару. Отсюда два следствия, которые здесь названы, потому что они меняют решения читающего кода:

• идентификатор ПЕРЕИСПОЛЬЗУЕТСЯ. Уникальность пары полная, снятие есть удаление строки, функция неизменяема — значит повторное приглашение того же человека в тот же аккаунт вернёт ТОТ ЖЕ идентификатор. Признак «строка заведена заново» — `CreatedAt`, а не `ID`;
• идентификатор ВЫЧИСЛИМ ПОСТОРОННИМ. Зная человека и аккаунт, его получает кто угодно, ни разу не обратившись к платформе. Поэтому одиночное чтение обязано быть суженным по аккаунту в САМОМ ЗАПРОСЕ: без этого адрес чужого членства строится арифметикой, а не перебором.

type MembershipState ¶

type MembershipState string

MembershipState — состояние членства. Значений ровно два, и словарь закреплён CHECK'ом на таблице: третьего в колонке не появится.

Согласованность состояния членства со статусом человека конструкцией НЕ закреплена — её держат писатели (зеркалящий триггер строки человека и два стейтмента репозитория). Читающий код поэтому судит то, что в строке лежит, и не выводит одно из другого.

const (
	// MembershipStatePending — человек приглашён и ещё не входил.
	//
	// Наблюдаемо АККАУНТ-СКОУПНЫМ чтением и не наблюдаемо своим списком: у
	// приглашённого нет внешнего субъекта, значит нечем аутентифицироваться,
	// значит своего чтения он вызвать не может. Это не расхождение проекций, а
	// арифметика — разные наблюдатели видят разное.
	MembershipStatePending MembershipState = "PENDING"
	// MembershipStateActive — человек состоит в аккаунте.
	MembershipStateActive MembershipState = "ACTIVE"
)

type MembershipTuple ¶

type MembershipTuple struct {
	User     string // e.g. "user:usr-…", "group:grp-…#member"
	Relation string // tier relation (e.g. "editor")
	Object   string // e.g. "compute_instance:inst-1"
}

MembershipTuple — a per-object FGA relation tuple the reconciler emits/revokes for a materialized membership (subject → tier → object). A flat value so the reconcile use-case stays transport/storage-agnostic; the pg adapter maps it to the fga_outbox payload.

type MirrorObject ¶

type MirrorObject struct {
	ObjectType      string
	ObjectID        string
	ParentProjectID string
	// ParentAccountIDs — АККАУНТЫ, под которыми лежит объект. Множественное
	// число здесь не запас на будущее: у ЛИЧНОСТИ принадлежность аккаунту
	// перестала быть свойством её строки и стала отдельной связью, которых у
	// человека бывает несколько (kacho#470/#471), поэтому скалярное поле называло бы
	// ОДИН аккаунт из многих — и выдача второго аккаунта не находила бы своего
	// человека by construction (kacho#1172).
	//
	// У всех прочих типов набор вырожден: ноль элементов (объект не лежит ни в
	// одном аккаунте) либо один. Пустые строки в набор НЕ КЛАДУТСЯ — «аккаунта
	// нет» выражается отсутствием элемента, а не элементом-пустышкой, иначе
	// область с пустым идентификатором совпала бы с ним.
	ParentAccountIDs []string
	Labels           map[string]string
}

MirrorObject — the same-DB parent-scope projection of an owner object read from resource_mirror (β fed it; γ reads it). Pure value; the reader adapter fills it.

func (m MirrorObject) IsContainedIn(scope ScopeAnchor) bool

project:P ⊑ project:P                         (same project)
project:P ⊑ account:A  if A ∈ mirror.ParentAccountIDs
any       ⊑ cluster:*                          (cluster contains everything)

func (m MirrorObject) MatchesLabels(matchLabels map[string]string) bool

type ModuleSet ¶

type ModuleSet interface {
	// IsKnownModule — состоит ли модуль в наборе.
	IsKnownModule(module string) bool
}

ModuleSet — членство в наборе модулей платформы, каким его знает ВЫЗЫВАЮЩИЙ.

Подстановочный знак `*` членом набора не является ни в одной реализации: он не имя модуля, а маркер политики, и разбирается Rule.Validate отдельно.

func ModuleSetOf(names ...string) ModuleSet

type OAuthClientName ¶

type OAuthClientName string

OAuthClientName — человекочитаемое имя токена (SA-key / user-token). Судится единственной формой имени дерева, как и остальные имена iam.

Пустая строка остаётся законным ВХОДОМ выпуска и означает «назови сам»: до записи её заменяет имя, производное от идентификатора (`validate.NameOrDefault` в use-case). Здесь пустое уже не проходит — эта проверка судит то, что БУДЕТ ЗАПИСАНО, а записи с пустым именем не бывает.

func (n OAuthClientName) Validate() error

type OperationID ¶

type OperationID string

type PasswordCostClass ¶ added in v0.5.0

type PasswordCostClass struct {
	Format PasswordHashFormat
	Params map[PasswordHashCostParam]uint32
}

PasswordCostClass — формат и полный набор параметров стоимости этого формата.

func (c PasswordCostClass) Key() string

func (c PasswordCostClass) ParamsLabel() string

func (c PasswordCostClass) Validate() error

type PasswordHashCostParam ¶ added in v0.5.0

type PasswordHashCostParam string

PasswordHashCostParam — параметр СТОИМОСТИ формата: тот, что назначает цену одной проверки. Соль и длина ключа параметрами стоимости не являются и потолка не несут — они не меняют ни времени, ни памяти проверки.

const (
	// CostParamBcryptCost — показатель стоимости bcrypt: время растёт вдвое на
	// каждую единицу, память от него не зависит вовсе.
	CostParamBcryptCost PasswordHashCostParam = "cost"
	// CostParamArgon2Memory — память argon2id в КиБ: она же и есть память
	// одной проверки, которую страж старта сверяет с пределом процесса.
	CostParamArgon2Memory PasswordHashCostParam = "memory"
	// CostParamArgon2Iterations — число проходов argon2id.
	CostParamArgon2Iterations PasswordHashCostParam = "iterations"
	// CostParamArgon2Parallelism — степень параллельности argon2id.
	CostParamArgon2Parallelism PasswordHashCostParam = "parallelism"
)

type PasswordHashFormat ¶ added in v0.5.0

type PasswordHashFormat string

PasswordHashFormat — признак формата проверочного значения: первый сегмент его разметки, как он лежит в самом значении.

const (
	// PasswordHashFormatBcrypt — НАСЛЕДУЕМЫЙ формат: значения, заведённые
	// прежним поставщиком личности. Продукт их читает и не пишет.
	//
	// Признак — `2a`. Соседние написания bcrypt (`2b`, `2y`) в перечень НЕ
	// внесены: популяция их не несёт, а запись без предмета обещала бы
	// возможность, которой нет. Встретится такое значение — его назовёт
	// перепись переноса, громко и с числом строк, а не примет молча.
	PasswordHashFormatBcrypt PasswordHashFormat = "2a"

	// PasswordHashFormatArgon2id — ОБЪЯВЛЕННЫЙ и растущий формат: им заводится
	// каждое новое значение.
	PasswordHashFormatArgon2id PasswordHashFormat = "argon2id"
)

func (f PasswordHashFormat) Admissibility(p PasswordHashCostParam) (PasswordHashParamRange, bool)

func (f PasswordHashFormat) CostParams() []PasswordHashCostParam

type PasswordHashFormatRecord ¶ added in v0.5.0

type PasswordHashFormatRecord struct {
	// Format — признак формата.
	Format PasswordHashFormat
	// Writable — пишет ли продукт значения этого формата.
	Writable bool
	// Ceiling — потолок по каждому параметру стоимости формата.
	Ceiling map[PasswordHashCostParam]uint32
	// Floor — пол; ТОЛЬКО у записываемой записи.
	Floor map[PasswordHashCostParam]uint32
	// Why — чем выбран потолок. Потолок выводится из ЁМКОСТИ, а не из переписи
	// одной установки, и причина обязана стоять рядом с числом.
	Why string
}

PasswordHashFormatRecord — запись перечня.

func PasswordHashFormatByMarker(marker string) (PasswordHashFormatRecord, bool)

func PasswordHashFormats() []PasswordHashFormatRecord

func (r PasswordHashFormatRecord) MemoryPerVerificationAtCeilingBytes() uint64

func (r PasswordHashFormatRecord) Validate() error

type PasswordHashParamRange ¶ added in v0.5.0

type PasswordHashParamRange struct {
	// Min — наименьшее значение, которое читатель считает без искажения.
	Min uint32
	// Max — наибольшее. Где строже спецификация, берётся она; где строже
	// читатель — он.
	Max uint32
	// Why — чем граница обоснована. Запись без причины неотличима от записи
	// без предмета.
	Why string
}

PasswordHashParamRange — область ДОПУСТИМОСТИ параметра: пересечение того, что допускает спецификация формата, и того, что читатель исполняет без искажения. Обе границы включительны.

type Permission ¶

type Permission string

func (p Permission) Validate() error

type Permissions ¶

type Permissions []Permission

func CompileRules(rules []Rule) (Permissions, error)

func (p Permissions) Validate() error

func (p Permissions) ValidateCompiled() error

type PrivilegeDerivation ¶

type PrivilegeDerivation string

PrivilegeDerivation — how a subject obtained a privilege.

const (
	// DerivationDirect — the binding's subject IS the requested subject. Also the
	// zero value's meaning (see SubjectPrivilege.Derivation).
	DerivationDirect PrivilegeDerivation = ""
	// DerivationGroup — the binding's subject is a GROUP the requested subject is
	// a member of. Groups do not nest, so this is exactly one hop.
	DerivationGroup PrivilegeDerivation = "GROUP"
)

type Project ¶

type Project struct {
	ID          ProjectID
	AccountID   AccountID
	Name        ProjectName
	Description Description
	Labels      Labels
	CreatedAt   time.Time
}

Project — child Account-а («folder» в YC-стилистике, но без промежуточного Cloud). Уникальное имя per-Account (DB UNIQUE projects_account_name_unique).

FK: account_id → accounts(id) ON DELETE RESTRICT. account_id — hard-immutable после Create (Update его reject'ит).

func (p Project) StructuralFacts() []StructuralTuple

func (p Project) Validate() error

type ProjectID ¶

type ProjectID string

type ProjectName ¶

type ProjectName string

func (n ProjectName) Validate() error

type PrunedSelectorType ¶

type PrunedSelectorType struct {
	// ObjectType — точечный тип объекта, чью строку каталога сняли.
	ObjectType string
	// Outcome — что стало со строкой отбора, из которой тип вырезан.
	Outcome SelectorPruneOutcome
	// Reason — причина снятия строки каталога, записанная применителем
	// манифеста. Причина ПЛАТФОРМЫ, а не действие арендатора: своё правило он не
	// менял. ПУСТАЯ строка означает «строка каталога причины не несла» (снята
	// ранней миграцией), а не «причину потеряли».
	Reason string
	// PrunedAt — момент вырезания. Время ТРАНЗАКЦИИ применения: у всего, что
	// вырезано одним применением, он совпадает дословно.
	PrunedAt time.Time
	// AppliedBy — АВТОР применения, вырезавшего этот тип (kacho#2005). Та же величина
	// и тот же источник, что у соседа: вопрос «кто снял» у обеих ведомостей
	// общий — арендатор не различает, какой из проекций правила он лишился.
	//
	// ПУСТАЯ строка означает «строка вырезана ДО заведения колонки».
	AppliedBy string
}

PrunedSelectorType — точечный тип, ВЫРЕЗАННЫЙ применителем каталога из отбора правила роли при снятии строки ресурса платформы (kacho#1988).

Чем это отличается от соседней [WithdrawnGrant], и почему они не сложены ¶

Переселение адресуется парой «тип объекта + глагол» и означает «право по этой паре действовало и перестало». Вырезание глагола не имеет ВООБЩЕ: отбор правила называет типы, а не пары, — поэтому у него своя ведомость и свой тип здесь. Сложить их значило бы дать вырезанному пустой глагол, а пустой глагол в соседе есть ЯКОРЬ объявления правила, то есть уже занятое значение.

Отпечаток правила сюда НЕ ПЕРЕЕЗЖАЕТ ¶

Ведомость ключуется тройкой «роль + отпечаток правила + тип»: отпечаток нужен ХРАНЕНИЮ, чтобы два правила, потерявшие один тип, не схлопнулись в одну строку. Читающему он не нужен и не отдаётся — это содержательный хеш, которого нет ни в одном контракте платформы; выставь мы его, способ хеширования стал бы частью контракта, а арендатор своё правило знает содержанием, а не дайджестом.

Следствие названо прямо: строки, различавшиеся ТОЛЬКО отпечатком, для читающего есть ОДИН факт и произносятся один раз.

type PublicReadContainer ¶ added in v0.5.0

type PublicReadContainer struct {
	// Type — точечный тип, о котором ответ (kaname#874): по нему ворота находят
	// вложенные правила, стоящие под этим типом.
	Type string
	// Declared — тип объявлен контейнером публичного чтения.
	Declared bool
	// ChildTypes — точечные типы живых строк каталога, чей указатель называет
	// этот тип, отсортированно. Пусто — детей у типа нет либо каталог их не знает.
	ChildTypes []string
}

PublicReadContainer — что живой каталог говорит о типе цели выдачи классу.

func (c PublicReadContainer) CoveredChild(rules Rules) (string, bool)

type PublishedKey ¶

type PublishedKey struct {
	KID          KeyID
	Algorithm    SigningAlgorithm
	PublicKeyPEM string
}

PublishedKey — ПУБЛИКУЕМАЯ форма ключа.

Поля приватной половины у этого типа НЕТ и быть не может (F1-05): положить её сюда не выражается, а не «запрещено правилом».

type RecoveryCode ¶ added in v0.5.0

type RecoveryCode struct {
	ID     RecoveryCodeID
	UserID UserID
	Digest CodeDigest
	// IssuedAt — момент чеканки (часы полосы).
	IssuedAt time.Time
	// ExpiresAt — абсолютный срок, ОДИН столбец; величина — настройка.
	ExpiresAt time.Time
	// ConsumedAt — момент применения; nil — не применён. Ставит его один
	// оператор базы (Ф5-05).
	ConsumedAt *time.Time
}

RecoveryCode — запись кода (Р1). Состав закрыт: личность, свёртка, момент выдачи, срок, момент применения.

func (c RecoveryCode) Expired(now time.Time) bool

func (c RecoveryCode) Validate() error

type RecoveryCodeID ¶ added in v0.5.0

type RecoveryCodeID string

RecoveryCodeID — идентификатор ПОТОКА восстановления: строка кода и ключ идемпотентности журнала завершений (Р4). Наружу не адресуется.

type RecoveryCodeValue ¶ added in v0.5.0

type RecoveryCodeValue struct {
	// contains filtered or unexported fields
}

RecoveryCodeValue — значение кода (Р1). Тип не печатается и не сериализуется; значение выходит ровно двумя методами: `Digest` (в хранилище) и `Letter` (в письмо).

func NewRecoveryCodeValue() (RecoveryCodeValue, error)

func PresentedRecoveryCode(value string) RecoveryCodeValue

func (v RecoveryCodeValue) Digest() CodeDigest

func (v RecoveryCodeValue) Format(f fmt.State, verb rune)

func (v RecoveryCodeValue) GoString() string

func (v RecoveryCodeValue) IsZero() bool

func (v RecoveryCodeValue) Letter() string

func (v RecoveryCodeValue) LogValue() slog.Value

func (v RecoveryCodeValue) MarshalJSON() ([]byte, error)

func (v RecoveryCodeValue) MarshalText() ([]byte, error)

func (v RecoveryCodeValue) String() string

type RecoveryCompletion ¶

type RecoveryCompletion struct {
	RecoveryJTI         string
	ExternalID          ExternalSubject
	UserID              UserID
	RevokedSessionCount int32
}

RecoveryCompletion — one row of the recovery-completed idempotency ledger. PK recovery_jti dedups at-least-once delivery. The row stores the deterministic primary user_id and the revoked session count so a duplicate delivery can replay the same Operation.metadata without re-running any side-effect.

Источника события ДВА (Ф5 Р4): обратный вызов поставщика личности называет внешнего субъекта; наш поток восстановления (Ф5, `kacho#1271`) называет человека его строкой, а внешнего субъекта не несёт — у личности, заведённой нашей регистрацией, его нет. Поэтому `ExternalID` необязателен; заданный по-прежнему ограничен длиной.

func (r RecoveryCompletion) Validate() error

type ResourceRef ¶

type ResourceRef struct {
	Type string
	ID   string
}

ResourceRef — пообъектный указатель {type,id} (redesign-2026 F8 / B1). В отличие от общего Referrer имени НЕ несёт: цель iam — строгая форма {type,id}. `Type` — точечный ключ `<module>.<resource>`.

type ResourceType ¶

type ResourceType string

ResourceType — ЯКОРЬ ОБЛАСТИ привязки: один из трёх ярусов иерархии (`cluster`/`account`/`project`). Вокабуляр объявлен ОДИН раз — `scopeAnchorTiers` в access_binding_scope.go, — и `Validate()` судит по нему. Пообъектный тип якорем не бывает: он живёт на оси `target` (F8).

func (r ResourceType) Validate() error

type RevocationReason ¶ added in v0.7.0

type RevocationReason string

RevocationReason — закрытый словарь причин отзыва выдачи (kaname#963, Д2). Написание — слово хранения (`access_bindings.revocation_reason`).

const (
	// RevocationReasonNone — выдача не отозвана либо отозвана до заведения поля.
	RevocationReasonNone RevocationReason = ""
	// RevocationReasonRevoke — глагол `Revoke`.
	RevocationReasonRevoke RevocationReason = "REVOKE"
	// RevocationReasonExpired — истёк срок, отозвал проход срока.
	RevocationReasonExpired RevocationReason = "EXPIRED"
	// RevocationReasonResourceUnregistered — снята регистрация объекта цели.
	RevocationReasonResourceUnregistered RevocationReason = "RESOURCE_UNREGISTERED"
	// RevocationReasonDelegationRevoked — отозвано делегирование, по которому
	// выдача сделана (kaname#986, Р4).
	RevocationReasonDelegationRevoked RevocationReason = "DELEGATION_REVOKED"
)

type Role ¶

type Role struct {
	ID          RoleID
	ClusterID   ClusterID // set for system role
	AccountID   AccountID // set for account-scoped custom
	ProjectID   ProjectID // set for project-scoped custom
	Name        RoleName
	Description Description
	// Rules — authored policy (RBAC rules-model 2026). Source of truth + public
	// API surface. Compiled into Permissions (internal, FGA-emit) by CompileRules.
	Rules Rules
	// Permissions — INTERNAL compiled form (anchor/names arms; match_labels NOT
	// compiled). Derived from Rules via CompileRules; NOT a public API field for
	// rules-roles. Legacy permissions-only roles (no Rules) keep their stored set.
	Permissions Permissions
	IsSystem    bool
	// OwnerModule — модуль, которому роль принадлежит. Пусто у ПЛАТФОРМЕННОЙ
	// роли (admin/edit/view/owner, system.*), непусто у роли, объявленной
	// манифестом этого модуля.
	//
	// Носит ровно ОДИН смысл — владение, — и потому отделяет послабление
	// подстановки от кластерного якоря: `IsSystem` продолжает означать «арендатор
	// эту роль не правит» и больше не означает «этой роли можно подставлять
	// звёздочку». Политика выводится из пары ОДНИМ местом — [PolicyOfRole].
	//
	// Наружу не проецируется: `Role` публичного контракта этой колонки не несёт
	// (задача продукта kacho#1032, тип изменения — ВВОДЯЩЕЕ, без нового поля API).
	OwnerModule string
	CreatedAt   time.Time
	// CreatedByUserID — authoring principal (governance/audit). Optional.
	CreatedByUserID UserID
	// UpdatedAt — last-mutation timestamp. Zero until first Update.
	UpdatedAt time.Time
	// Labels — tenant-facing метки САМОГО ресурса Role (НЕ путать с
	// Rule.MatchLabels, отбирающим объекты под грантом). Делают Role
	// label-selectable наравне с account/project (ARM_LABELS-грант на iam.role →
	// v_list по `labels @> matchLabels`; List фильтрует viewer ∪ v_list).
	Labels Labels
	// Integrity — целость роли: даёт ли она то, что объявляет (kacho#1035).
	//
	// ВЫВОДИТСЯ НА ЧТЕНИИ и НЕ ХРАНИТСЯ: колонки у неё нет, в перечень колонок
	// писателя она не входит и [Role.Validate] её не судит. Нулевое значение
	// означает «этим путём не вычислено» — так её и видят пути, которые роль не
	// читают, а возвращают эхом мутации.
	Integrity RoleIntegrity

	// Lifecycle — ОБЪЯВЛЕНА роль манифестом модуля сегодня либо СНЯТА (kacho#1913).
	//
	// Отдельно от `Integrity` рядом, и различие несущее: `RoleHealthEmpty` даёт
	// и снятая роль, и объявленная, чьи строки каталога сняты, — а следующий шаг
	// у арендатора разный. Довод целиком — [RoleLifecycle].
	//
	// ПРИХОДИТ ЧТЕНИЕМ: колонки пометки у строки есть, но заполняют это поле
	// `Get` и `List`, а ответ операции его не несёт — нулевое состояние там
	// означает «этим ответом не вычислено», ровно как у соседа.
	Lifecycle RoleLifecycle

	// Withdrawn — ЧТО у роли отобрано и почему (kacho#1992): строки ведомости
	// переселения. ОБЪЯСНЯЕТ состояние целости и не определяет его — у роли,
	// пострадавшей третьим путём, переселения не было вовсе, и список пуст при
	// нездоровом состоянии.
	//
	// Пустой срез означает «отобранного нет», а не «не читали»: разводит их
	// [RoleIntegrity.Health] рядом, у которого нулевое состояние есть «этим
	// ответом не вычислено».
	Withdrawn []WithdrawnGrant

	// PrunedSelectorTypes — какие точечные типы ВЫРЕЗАНЫ из отбора правил этой
	// роли и почему (kacho#1988): строки ведомости вырезания.
	//
	// Сосед [Role.Withdrawn] отвечает про ДВЕ проекции правила, у которых есть
	// пара «тип + глагол»; эта — про ТРЕТЬЮ, где глагола нет вовсе. Разные
	// ведомости, разные события, поэтому два поля, а не одно.
	//
	// Пустой срез означает «вырезанного нет», а не «не читали»: разводит их
	// [RoleIntegrity.Health] рядом, у которого нулевое состояние есть «этим
	// ответом не вычислено».
	PrunedSelectorTypes []PrunedSelectorType

	// RuleStates — состояние КАЖДОГО правила роли (kacho#1962): действует, отозвано
	// платформой либо не разрешилось. Записей ровно по числу правил.
	//
	// Отвечает на вопрос, которого нет ни у `Integrity`, ни у `Withdrawn`: КАКОЕ
	// правило пострадало и по КАКОЙ ИЗ ДВУХ причин. Картина счётчиков у причин
	// ОДИНАКОВА, а следующий шаг арендатора — разный.
	//
	// ПРИХОДИТ ЧТЕНИЕМ, НЕ ХРАНИТСЯ — тем же доводом, что `Integrity` рядом.
	// ПУСТОЙ СРЕЗ означает «этим путём не вычислено» и законен: ответ операции
	// состояния не несёт. У роли БЕЗ правил он пуст и на чтении — состояние есть
	// свойство правила, и у роли без правил его нет.
	RuleStates []RuleState

	// TypeVerbs — набор глаголов ТИПА, каким его объявляет ЖИВАЯ строка каталога
	// (kacho#1994). Тем же набором идёт материализация, поэтому превью и эмиссия не
	// могут разойтись.
	//
	// ПРИХОДИТ ПРОВЯЗКОЙ, НЕ ХРАНИТСЯ — как и `Integrity` рядом: колонки у неё
	// нет, писатель её не пишет, [Role.Validate] её не судит. Отличие от
	// `Integrity` в том, чем является НУЛЕВОЕ значение: там оно означает «этим
	// путём не вычислено» и законно, здесь — ОТКАЗ проекции. Показ по словарю,
	// порождённому сборкой, неотличим от честного превью, поэтому «нечем
	// ответить» обязано быть отказом, а не тихим запасным путём.
	TypeVerbs TypeVerbLookup

	// HeldNames — НЕ ХРАНИТСЯ. Ключи объектов, названные в `resourceNames`
	// правил, которые на приёме роли были зарегистрированы (Р8 приёмки
	// `unregistration-revokes-its-grants.md`). Запись роли берёт на каждом замок
	// строки регистрации и отказывает, если строки уже нет: роль, принятая до
	// снятия и записанная после, снятого ключа не называет (URG-26).
	HeldNames []RuleNameHold
}

Role — multi-scope. Exactly one scope field is non-NULL:

• is_system=true + ClusterID set: system role (`system.admin`, ...).
• is_system=false + AccountID set: account-scoped custom role.
• is_system=false + ProjectID set: project-scoped custom role.

Enforced by DB CHECK `roles_definition_tier_xor` + a partial UNIQUE per scope. Domain.Validate duplicates the CHECK to give friendly errors before reaching the DB. (The legacy B2B-tenant role scope was removed; a custom role is scoped to exactly one of {account, project}.)

func (r Role) AuthoredVerbs(lookup TypeVerbLookup) []string

func (r Role) CanonicalRank() int

func (r Role) DefinitionTierID() string

func (r Role) DefinitionTierType() string

func (r Role) DisplayName() string

func (r Role) EffectiveVerbs(lookup TypeVerbLookup) []string

func (r Role) GrantsReadsOnly() bool

func (r Role) IsClusterAdminRole() bool

func (r Role) IsSystemDerived() bool

func (r Role) Purpose() string

func (r Role) Validate(modules ModuleSet) error

func (r Role) VerbNotes(lookup TypeVerbLookup) map[string]string

func (r Role) WithoutComputedState() Role

type RoleHealth ¶

type RoleHealth uint8

RoleHealth — состояние целости роли.

Нулевой вариант несёт ЕДИНСТВЕННЫЙ смысл: «этим ответом не вычислено». Он не является ни одним из трёх исходов и HealthOf его не возвращает никогда — иначе «посчитано, терять нечего» стало бы неотличимо от «не считали».

const (
	// RoleHealthUnknown — не вычислено ЭТИМ ответом. НИКОГДА не «здорова».
	RoleHealthUnknown RoleHealth = iota
	// RoleHealthHealthy — каждый адресуемый сегмент имеет строку проекции.
	RoleHealthHealthy
	// RoleHealthDegraded — часть сегментов проекции не даёт, часть даёт.
	RoleHealthDegraded
	// RoleHealthEmpty — сегменты объявлены, проекции нет НИ ОДНОЙ.
	RoleHealthEmpty
)

type RoleID ¶

type RoleID string

func SystemRoleID(name RoleName) RoleID

type RoleIntegrity ¶

type RoleIntegrity struct {
	Health RoleHealth
	// Declared — сколько адресуемых сегментов объявляют правила роли.
	Declared int
	// Unresolved — сколько из них не дают ни одной строки проекции.
	Unresolved int
}

RoleIntegrity — состояние целости и пара величин, из которых оно выведено.

Счётчики без состояния были бы двусмысленны: ноль есть И законная величина (роль без адресуемых сегментов), И признак «не считали». Разводит их RoleHealth: у вычисленной целости состояние непустое всегда.

func HealthOf(declared, unresolved int) RoleIntegrity

type RoleLifecycle ¶

type RoleLifecycle struct {
	State RoleLifecycleState
	// RetiredAt — момент снятия. Нулевое время у объявленной роли.
	RetiredAt time.Time
	// RetiredReason — причина снятия. Без неё «отобрали» неотличимо от
	// «сломалось».
	RetiredReason string
	// RetiredBy — кто снял. Сегодня производитель один — путь старта, и он
	// называет процессного актора; глагол применения придёт с `kacho#1034` и назовёт
	// проверенную личность вызывающего. Пустая строка у снятой роли означает
	// «помечено до заведения колонки», а не «автора потеряли».
	RetiredBy string
}

RoleLifecycle — состояние роли и обстоятельства её снятия.

Три сопутствующие величины непусты ТОЛЬКО у снятой роли, и это свойство СХЕМЫ, а не кода: `roles_live_matches_retired` делает состояние «снята и жива» неконструируемым.

func (l RoleLifecycle) Withdrawn() bool

type RoleLifecycleState ¶

type RoleLifecycleState uint8

RoleLifecycleState — объявлена роль манифестом либо снята.

Нулевой вариант несёт ЕДИНСТВЕННЫЙ смысл: «этим ответом не вычислено». Он не является ни одним из двух исходов, и путь чтения его не возвращает никогда — иначе «прочитано, роль объявлена» стало бы неотличимо от «не читали».

const (
	// RoleLifecycleUnknown — не вычислено ЭТИМ ответом. НИКОГДА не «объявлена».
	RoleLifecycleUnknown RoleLifecycleState = iota
	// RoleLifecycleDeclared — строка жива: объявление за ней стоит.
	RoleLifecycleDeclared
	// RoleLifecycleWithdrawn — строка помечена снятой: объявления больше нет.
	RoleLifecycleWithdrawn
)

func (s RoleLifecycleState) String() string

type RoleName ¶

type RoleName string

func (n RoleName) Validate() error

func (n RoleName) ValidateAtTier(isSystem bool) error

type RoleRetirement ¶

type RoleRetirement struct {
	// Marked — строка роли помечена снятой. Ложно означает, что оператор пометки
	// не нашёл своей строки: роль уже снята либо владелец не тот.
	Marked bool
	// ResettledVerbs — строк проекции глаголов переселено в ведомость и снято.
	ResettledVerbs int
	// ResettledRuleRefs — строк проекции сегментов переселено и снято.
	ResettledRuleRefs int
	// RemovedSelectors — строк проекции отбора снято. В ведомость они не
	// переселяются: у строки селектора нет пары «тип + глагол», которой
	// адресуются сироты.
	RemovedSelectors int
	// RemovedTargetMembers — строк материализованного состава цели снято.
	RemovedTargetMembers int
}

RoleRetirement — перепись ОДНОГО отзыва роли: что унесено и что помечено.

Числа возвращаются, а не логируются внутри: вызывающий собирает из них перепись применения, а «снято» без чисел неотличимо от «прошло мимо».

type RoleRuleRef ¶

type RoleRuleRef struct {
	Module   string
	Resource string
	// Verb — пустая строка означает ЯКОРЬ (глаголы не сужены), а не отсутствие
	// значения: см. абзац выше.
	Verb string
}

RoleRuleRef — один ОБЪЯВЛЕННЫЙ сегмент правила роли: «эта роль называет вот этот (модуль, ресурс) и вот этот глагол».

Чем это НЕ является — и различие несущее ¶

Это НЕ `RoleVerb`. Та проекция отвечает на вопрос вердикта «разрешено ли действие» и содержит только то, что РЕЗОЛВИТСЯ: тип, которого не знает словарь модели, пар не даёт (`RoleVerbsFromSelectors`). Здесь наоборот — строка кладётся на КАЖДЫЙ объявленный сегмент, резолвится он или нет, потому что предмет этой таблицы есть ссылочная целостность: молчаливый пропуск и есть тот дефект, ради которого заводится ключ, и воспроизвести его в новом писателе значило бы завести ключ, которому нечего отвергать.

Пустой глагол — это ЯКОРЬ, а не «глагол не задан» ¶

Правило, не сузившее глаголы (`verbs: ["*"]`), даёт строку с пустым `Verb`, которая ложится в хранилище значением NULL. Ключ ресурса на ней проверяется, ключ глагола — пропускается `MATCH SIMPLE`, и это ПРАВИЛЬНО: ресурс уже проверен первым ключом. Ключей поэтому два, а не один: под одним составным ключом `MATCH SIMPLE` снял бы проверку целиком, и правило, называющее несуществующий ресурс, принималось бы успешно.

func RuleRefsOf(rules Rules) []RoleRuleRef

func (r RoleRuleRef) Dotted() string

func (r RoleRuleRef) IsAnchor() bool

type RoleScopeGroup ¶

type RoleScopeGroup int8

RoleScopeGroup — server-computed scope tier of a role, surfaced to the UI in AssignableRole.scope_group so the picker groups without client-side logic Maps 1:1 to the proto ScopeGroup enum.

const (
	RoleScopeGroupUnspecified RoleScopeGroup = 0
	RoleScopeGroupSystem      RoleScopeGroup = 1
	RoleScopeGroupAccount     RoleScopeGroup = 2
	RoleScopeGroupProject     RoleScopeGroup = 3
)

func ScopeGroupOf(r Role) RoleScopeGroup

func (g RoleScopeGroup) String() string

type RoleSegment ¶

type RoleSegment struct {
	RoleID     RoleID
	ObjectType string
	// Verb — пустая строка означает ЯКОРЬ (правило не сузило глаголы): годится
	// любая строка проекции своего типа.
	Verb string
}

RoleSegment — объявленный сегмент роли в форме, которой спрашивают проекцию.

Точечный тип приходит ОДНИМ выражением (RoleRuleRef.Dotted) — тем же, каким его строит переселение и каким его хранит каталог. Второе написание разошлось бы молча: соединение по разным словарям не совпадает никогда.

func SegmentsOf(id RoleID, rules Rules) []RoleSegment

type RoleVerb ¶

type RoleVerb struct {
	ObjectType string
	Verb       string
}

RoleVerb — одна пара проекции «роль даёт этот глагол на этом типе».

Тип — тип объекта модели прав (`vpc_network`), не точечное имя ресурса: вердикт спрашивает именно им. Глагол — в канонической форме и БЕЗ приставки отношения: приставку знает компилятор модели, и дублировать её здесь значило бы завести второе место, где она может смениться.

type RotatedRefreshToken ¶ added in v0.5.0

type RotatedRefreshToken struct {
	Context    CeremonyContext
	Generation int32
}

RotatedRefreshToken — то, что вернул ОДИН оператор ротации.

type Rule ¶

type Rule struct {
	Module        string // exactly one module per rule
	Resources     []string
	Verbs         []string
	ResourceNames []string
	MatchLabels   map[string]string
	// Children — вложенные правила (kaname#874, nested_rule.go): правила над
	// типами, лежащими под типом-контейнером этого правила. nil — вложенных нет;
	// пустой непустой срез формой не является (второй способ сказать «нет»).
	// У вложенного правила Module пуст (берётся у владельца) и своих Children нет.
	Children []Rule
}

Rule — one authored grant over ONE module. The element lists are validated 1..16 each, the selector is resource_names XOR match_labels.

func (r Rule) Arm() Arm

func (r Rule) EffectiveChildren() []Rule

func (r Rule) Fingerprint() string

func (r Rule) OwnerType() string

func (r Rule) ReadsWholeType(dotted string) bool

func (r Rule) Validate(policy RulePolicy, modules ModuleSet) error

type RuleLabelSelector ¶

type RuleLabelSelector struct {
	RuleFP      string
	ObjectTypes []string
	MatchLabels map[string]string
	Verbs       []string
}

RuleLabelSelector — the reconciler-facing projection of ONE ARM_LABELS rule: the rule_fp it is keyed by, the dotted object types it selects (cartesian modules×resources), the matchLabels equality selector, and the authored verbs (which drive the per-object tier + v_* relations the reconciler emits — the tier is NOT taken from the role's compiled permissions, since ARM_LABELS rules are excluded from CompileRules). It carries no pgx/grpc — pure domain.

type RuleLifecycle ¶

type RuleLifecycle uint8

RuleLifecycle — состояние ОДНОГО правила роли.

Нулевой вариант несёт ЕДИНСТВЕННЫЙ смысл: «этим ответом не вычислено». RuleStatesOf его не возвращает никогда — иначе «посчитано, терять нечего» стало бы неотличимо от «не считали».

const (
	// RuleLifecycleUnknown — не вычислено ЭТИМ ответом. НИКОГДА не «действует».
	RuleLifecycleUnknown RuleLifecycle = iota
	// RuleLifecycleActive — ни один адресуемый сегмент правила не потерян.
	RuleLifecycleActive
	// RuleLifecycleWithdrawn — потерянные сегменты есть, и КАЖДЫЙ объяснён
	// ведомостью переселения: объявление сняла платформа.
	RuleLifecycleWithdrawn
	// RuleLifecycleUnresolved — потерянные сегменты есть, и ХОТЯ БЫ ОДИН не
	// объяснён: правило ссылается на то, чего сейчас нет.
	RuleLifecycleUnresolved
)

type RuleNameHold ¶ added in v0.7.0

type RuleNameHold struct {
	Rule int
	Ref  ResourceRef
}

RuleNameHold — ключ объекта, названный правилом `Rule` (индекс в `Rules`).

type RulePolicy ¶

type RulePolicy struct {
	// contains filtered or unexported fields
}

RulePolicy — политика послабления подстановки в правилах роли.

Почему политик ТРИ, а не две (задача продукта kacho#1032) ¶

До неё политика была одна булева — «системный контекст». Признак `is_system` вычисляется ровно из непустого кластерного якоря и несёт ДВА смысла сразу: «арендатор эту роль не правит» и «этой роли можно подставлять звёздочку». Базовая роль модуля обязана быть системной в первом смысле — иначе её правит арендатор, — и вместе с ним получала второй: прямой путь к `*.*.*`. В диффе это выглядит обычной строкой роли, и ни один обзор её не поймает.

Политики различает ВЛАДЕЛЕЦ, а не ярус:

арендаторская   якоря кластера нет            module: "*" ✗   ресурс "*" ✗
модульная       якорь есть, владелец назван   module: "*" ✗   ресурс "*" ✓ только в своём модуле
платформенная   якорь есть, владельца нет     module: "*" ✓   ресурс "*" ✓

Одно правило, а не три исключения: подстановка в роли с владельцем законна ровно в пределах её модуля. Отсюда обе строки механически — `module: "*"` не находится ни в одном модуле, поэтому отвергается всегда; ресурс `*` находится в модуле своего правила, поэтому законен ровно тогда, когда этот модуль и есть владелец.

Глагол `*` не затрагивается — решение, а не пропуск ¶

Он разрешён и в арендаторской роли, безусловно ([validateVerbs]): он не сегмент пространства имён, а «все действия названного типа». Сузить его здесь значило бы отобрать уже выданное под видом починки.

Носитель — ЗНАЧЕНИЕ, а не второй булев флаг ¶

Два булевых параметра дают четыре сочетания при трёх законных, и четвёртое («не системная, но с владельцем») пришлось бы отвергать четвёртым правилом. Политика передаётся одним значением закрытого перечня, выводимым из строки функцией ОДНОГО места — PolicyOfRole. Второе объявление «системная ли роль для целей подстановки» есть находка, и её ловит гейт дерева.

func PolicyOfRole(isSystem bool, ownerModule string) RulePolicy

func TenantPolicy() RulePolicy

func (p RulePolicy) OwnerModule() string

func (p RulePolicy) UpdateImpliesDelete() bool

type RuleSelector ¶

type RuleSelector struct {
	RuleFP        string
	Arm           Arm
	ObjectTypes   []string
	ResourceNames []string          // ARM_NAMES only
	MatchLabels   map[string]string // ARM_LABELS only
	Verbs         []string
	// Container — контейнер вложенного правила (kaname#874); nil у правила
	// верхнего уровня. Селектор с контейнером охватывает объекты своих
	// ObjectTypes, у которых среди предков есть объект типа Container.Type,
	// прошедший отбор Container и входящий в цель выдачи.
	Container *ContainerSelector
	// Grants — глаголы, которые ЭТО правило даёт на каждом своём типе (ключ —
	// точечный тип из ObjectTypes), по живому каталогу (kaname#878). Решение о
	// доступе даёт глагол на объекте только тем правилом, чей селектор объект
	// выбрал: глагол соседнего правила той же роли охвата этого правила не
	// получает.
	//
	// nil — НЕ ВЫЧИСЛЕНО (заполняет `catalog.Facts.GrantSelectors`), и писатель
	// селекторов такую строку отвергает: молча записанное «правило не даёт
	// ничего» было бы отказом, неотличимым от честного. Пустая карта — вычислено:
	// живой каталог не даёт правилу ни одного глагола.
	//
	// Карта — функция ОТПЕЧАТКА правила (RuleFP — хэш всего содержимого правила,
	// включая глаголы и вложенные), каталога и владельца роли (политика роли
	// решает, влечёт ли правка удаление, kaname#1006): от прочих правил роли она
	// не зависит.
	Grants map[string][]string
}

RuleSelector — the UNIFIED reconciler-facing projection of ONE materializing rule (RBAC explicit-model 2026). It carries the arm so the reconciler picks the match strategy: ARM_ANCHOR(all) → every object of ObjectTypes inside scope; ARM_NAMES → only ResourceNames; ARM_LABELS → labels @> MatchLabels. The per-object FGA tuples (v_* + tier) are derived from Verbs (the tier is NOT taken from the role's compiled permissions — ARM_LABELS/ARM_ANCHOR-materialized rules are not in CompileRules). Pure domain, no pgx/grpc.

func (s RuleSelector) PublicReadsChildOf(containerType string, children []string) bool

func (s RuleSelector) ReadsWholeType(dotted string) bool

type RuleState ¶

type RuleState struct {
	// RuleIndex — индекс правила в `Role.Rules`. КЛЮЧ записи: порядок самих
	// записей не значим, сверять надо по нему.
	//
	// Индекс законен как ключ потому, что `roles.rules` — массив JSONB под одним
	// кодеком, и порядок сохраняется by construction: правило читается тем же
	// индексом, каким записано. Действителен он в пределах ОДНОГО ответа:
	// `Update` перестраивает массив, и мутацию индекс не переживает.
	RuleIndex int
	// State — состояние правила. У вычисленного оно непусто ВСЕГДА.
	State RuleLifecycle
	// Segments — сколько АДРЕСУЕМЫХ сегментов объявляет это правило.
	// Ноль законен (подстановка в модуле или ресурсе сегментов не даёт).
	//
	// ЕДИНИЦА ДРУГАЯ, ЧЕМ У [RoleIntegrity.Declared], и потому имя другое:
	// счётчик роли дедуплицирует сегмент по ВСЕЙ роли, здесь — только внутри
	// правила. Равенство сумм поэтому НЕ ГАРАНТИРОВАНО и нарушается ровно
	// тогда, когда один сегмент назван двумя правилами; на прочих ролях суммы
	// совпадают, и это совпадение, а не инвариант.
	Segments int
	// Lost — сколько из объявленных сегментов этого правила не дают ни одной
	// строки проекции, которую читает вердикт.
	//
	// ПРЕДИКАТ ТОТ ЖЕ, что у [RoleIntegrity.Unresolved]: ведомость здесь не
	// спрашивается — её спрашивает [RuleState.Explained] рядом. Различает
	// величины только единица дедупликации.
	Lost int
	// Explained — сколько из потерянных ОБЪЯСНЕНЫ ведомостью переселения.
	// Необъяснённые выводятся вычитанием: третье поле, равное разности двух
	// соседних, разошлось бы с ними при первой же правке.
	Explained int
	// Children — состояния вложенных правил ЭТОГО правила (kaname#874), в
	// порядке `Rule.Children`; RuleIndex у записи — индекс в Children. Пусто у
	// правила без вложенных.
	Children []RuleState
}

RuleState — состояние одного правила роли и три величины, из которых оно выведено.

Почему слово И счётчики, а не одно из двух ¶

Правило, у которого часть потерь объяснена, а часть нет, читается RuleLifecycleUnresolved — слово называет состояние, ТРЕБУЮЩЕЕ разбора. Схлопыванием это не является ровно потому, что рядом стоят обе величины: `Withdrawn` и `Unresolved` видны одновременно, и ни одна не потеряна.

Четвёртое значение («частично отозвано») рассмотрено и отвергнуто: у него нет ни своего действия у арендатора, ни своего производителя, при том что счётчики уже несут ровно ту же величину.

func RuleStatesOf(rules Rules, unresolved []RoleSegment, withdrawn []WithdrawnGrant) []RuleState

type Rules ¶

type Rules []Rule

Rules — a role's authored policy. Cardinality 1..64.

func DecodeRules(raw []byte) (Rules, error)

func OwnerRoleRules() Rules

func (rs Rules) CoversType(dottedType string) bool

func (rs Rules) HasAnchorRule() bool

func (rs Rules) HasChildren() bool

func (rs Rules) LabelSelectors() []RuleLabelSelector

func (rs Rules) MaterializingSelectors() []RuleSelector