service

type AuditEvent = outboxtypes.AuditEvent

type AuditOutboxEmitter interface {
	EmitTx(ctx context.Context, tx Tx, ev AuditEvent) error
}

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

type AuthorizeServiceConfig struct {
	Relations Authorizer
	// ClusterAdminChecker — плоский надзор администратора облака.
	//
	// Спрашивает о ДРУГОМ объекте, чем тот, о котором идёт вопрос:
	// `cluster:<синглтон>#system_admin`. Именно поэтому три верхних уровня
	// супер-доступа сделаны каскадом, а не материализацией: человек, обязанный
	// всё починить, не должен зависеть от состояния доставки.
	//
	// Со снятия внешнего движка на этот вопрос отвечает ТА ЖЕ форма, что и на
	// вопрос об объекте, — обе стороны спрашивают одно значение, поэтому «два
	// действующих источника ответа» перестало быть возможным by construction.
	ClusterAdminChecker authzguard.RelationChecker
}

type Authorizer interface {
	// CheckWithContext — вердикт об объекте с условным контекстом запроса.
	CheckWithContext(ctx context.Context, subject, relation, object string, condCtx map[string]any) (bool, error)
	// BatchCheckWithContext — вердикт о СТРАНИЦЕ объектов ОДНИМ вопросом.
	//
	// Объявлен ОБЯЗАТЕЛЬНЫМ методом порта, а не «способностью, если она есть».
	// Необязательность здесь была бы запасным путём с тихой деградацией: дверь без
	// этого метода молча возвращала бы партию к пообъектной полосе, и свойство
	// «партия стоит один вопрос» держалось бы тем, какую реализацию провязал
	// композиционный корень, — то есть не держалось бы ничем.
	//
	// Ответ — той же длины и в порядке заданных объектов: верный, но
	// переставленный вердикт отфильтровал бы страницу чужим ответом.
	BatchCheckWithContext(ctx context.Context, subject, relation string, objects []string,
		condCtx map[string]any) ([]bool, error)
	// ListSubjects — кто держит отношение на объекте, страницей С КУРСОРОМ.
	ListSubjects(ctx context.Context, objectType, objectID, relation string, pageSize int, pageToken string) ([]string, string, error)
	// Sources — кого называют основания права на объекте (разбор «почему»).
	Sources(ctx context.Context, objectType, objectID, relation string) ([]string, error)
	// DirectRelations — какие отношения субъект уже держит НА ЭТОМ объекте.
	//
	// Читатель один — текст отказа («не хватает `editor`; сейчас есть [`viewer`]»).
	// Прежде на это отвечало чтение кортежей у движка; читатель и единица те же,
	// источник — своя таблица.
	DirectRelations(ctx context.Context, subject, objectType, objectID string, limit int) ([]string, error)
	// DirectRelationsMany — то же о СТРАНИЦЕ объектов одного типа, одним вопросом.
	//
	// Хвост текста отказа платится на КАЖДОМ отказанном объекте, а страница
	// списка отказами и состоит — она ими и сужается. Пообъектная диагностика
	// поэтому возвращала стоимость набора ровно там, где вердикт её уже перестал
	// платить: партия из ста отказов стоила ста вопросов диагностики.
	//
	// Ключ ответа — идентификатор объекта; объект без прямых отношений в ответе
	// отсутствует (пустой срез и отсутствие ключа означают одно и то же — «хвоста
	// не будет»).
	DirectRelationsMany(ctx context.Context, subject, objectType string, objectIDs []string,
		limit int) (map[string][]string, error)
}

type CheckRelationRequest struct {
	Subject  string // "user:usr_xxx" / "service_account:sva_xxx" / "group:grp_xxx#member"
	Relation string // pre-resolved FGA relation
	Object   string // FGA object string "<type>:<id>"
	// HigherConsistency — вызывающий требует чтения, которое НЕ отстаёт от его
	// собственной только что закоммиченной записи.
	//
	// ТРЕБОВАНИЕ ВЫПОЛНЯЕТСЯ ВСЕГДА, И ЭТО НЕ «ПОЛЕ, НА КОТОРОЕ НЕ СМОТРЯТ».
	// Просьба адресовалась ЧУЖОМУ хранилищу, у которого была своя копия и свои
	// кэши чтения: без неё оно отвечало со своей отстающей стороны. Реляционная
	// форма читает ведущую базу службы, поэтому read-after-write у неё держится
	// by construction — гарантия, которую поле просит, дана безусловно, а не
	// проигнорирована.
	//
	// Поле остаётся на контракте намеренно: оно называет ТРЕБОВАНИЕ вызывающего,
	// а не способ его исполнения. Появится путь чтения с реплики (§7 приёмки R7-3
	// держит его вне границ) — требование снова станет различающим, и различать
	// его будет тот, кто этот путь заведёт.
	HigherConsistency bool
}

type CheckRequest struct {
	Subject  string // "user:usr_xxx" / "service_account:sva_xxx" / "group:grp_xxx#member"
	Resource ResourceRef
	Action   string // "<domain>.<resource>.<verb>"
	// RequiredRelation — when non-empty, overrides verb-derived relation.
	// api-gateway middleware populates this from the catalog's
	// `required_relation` annotation so admin-only RPCs (e.g.
	// `vpc.address_pools.list` with `required_relation=system_admin`) gate
	// on the explicit relation instead of the auto-derived `viewer` which
	// would slip through `cluster.viewer = user:*`.
	RequiredRelation string
	Context          map[string]any // optional CEL-context
}

type CheckResult struct {
	Allowed     bool
	DenyReasons []string
	CheckedAt   time.Time
}

type ExpandRequest struct {
	ResourceType string
	ResourceID   string
	Relation     string
}

type ExpandResult struct {
	Resource ResourceRef
	Relation string
	Tree     *authztypes.ExpandTree
}

type ListSubjectsRequest struct {
	ResourceType      string
	ResourceID        string
	Action            string
	PageSize          int
	PageToken         string
	SubjectTypeFilter string
}

type ListSubjectsResult struct {
	Subjects      []string
	NextPageToken string
}

type PrincipalKind string

type RelationOutboxEmitter interface {
	EmitWriteTx(ctx context.Context, tx Tx, tuples []RelationTuple) error
	EmitDeleteTx(ctx context.Context, tx Tx, tuples []RelationTuple) error
}

type RelationTuple = outboxtypes.RelationTuple

type ResolvedPrincipal struct {
	// Kind — whose authority the token carries.
	Kind PrincipalKind
	// UserID — `users.id`. Set only when Kind is PrincipalUser.
	UserID string
	// StandingCredentialIssuedAt — when the long-lived credential behind this
	// exchange was issued, for the exchanges that HAVE one (a personal access
	// token). nil for an interactive exchange, where the session states its own
	// authentication instant and that is the instant to weigh.
	//
	// The distinction is the whole reason this field exists. A person forced out
	// re-authenticates and their session moves past the cutoff; a standing
	// credential never re-authenticates, so its anchor is the moment it was
	// minted — one minted after the cutoff is authority the subject established
	// since, and one minted before it is exactly what "log this person out
	// everywhere" is about.
	StandingCredentialIssuedAt *time.Time
}

type ResourceMirrorEmitter interface {
	UpsertTx(ctx context.Context, tx Tx, row ResourceMirrorRow) (applied, projectionUnchanged bool, err error)
	DeleteTx(ctx context.Context, tx Tx, objectType, objectID string, tombstone time.Time) error
}

type ResourceMirrorRow struct {
	ObjectType      string
	ObjectID        string
	ParentProjectID string
	ParentAccountID string
	// ParentChain — цепь предков от ближайшего к дальнему, каждый элемент
	// `"<type>:<id>"`. Двух колонок выше хватает не всякому объекту: модель
	// требует цепи произвольной формы, а объект без предка молча выпадает из
	// области выдачи и из каскада.
	ParentChain []string
	Labels      map[string]string
	// SourceVersion — monotonic per-object marker from the owner.
	// The mirror UPSERT applies a register only when this is strictly newer than
	// the stored version (last-source-state-wins). Zero → '-infinity' (legacy).
	SourceVersion time.Time
}

type ResourceRef struct {
	Type string
	ID   string
}

type SubjectChange struct {
	ID        int64
	SubjectID string
	Op        string
	// SubjectType — тип субъекта в словаре модели прав (`user` |
	// `service_account` | `group`). Пусто у строк, записанных до того, как
	// производители начали его проставлять.
	//
	// Едет наружу, потому что идентификатор БЕЗ типа субъекта не называет: пара
	// собирается только вместе, и вызывающий, получивший половину, не может ни
	// закрыть поток названного субъекта, ни сбросить его записи поимённо.
	SubjectType string
}

type SubjectChangePositionLostError struct {
	// EarliestResumable — нижняя позиция, с которой возобновление ещё ничего не
	// теряет: «самая ранняя удержанная строка минус один», а у вычищенного
	// целиком журнала — сама граница устоявшегося.
	EarliestResumable int64
}

type SubjectChangeReader interface {
	// PollSubjectChanges returns rows of the window `(sinceID, settled]` in
	// ascending order, at most limit rows, plus the position the caller may adopt
	// as its cursor — the settled boundary, narrowed to the last delivered row
	// when the page was cut by limit.
	//
	// Never "everything above the cursor" and never `MAX(id)`: a position issued
	// past a number still in flight loses that row silently and forever.
	// [ErrSubjectChangeNotSettled] when there is no settled position yet.
	// [SubjectChangePositionLostError] when sinceID sits BELOW the journal floor:
	// the rows between them have been removed and will never be delivered, so a
	// silent empty page would read as "nothing changed" — i.e. an unapplied
	// revocation, silently.
	PollSubjectChanges(ctx context.Context, sinceID int64, limit int32) (changes []SubjectChange, headID int64, err error)
}

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

type TokenEnrichmentConfig struct {
	// Domain — public Kachō audience.
	Domain string
	// HydraIssuer — token issuer URL.
	HydraIssuer string
}

type TokenEnrichmentOwnClientPort interface {
	// GetUserToken читает клиента пользовательского токена по нашему id.
	GetUserToken(ctx context.Context, id domain.UserOAuthClientID) (domain.UserOAuthClient, error)
	// GetSAKey читает клиента ключа служебной учётки по нашему id.
	GetSAKey(ctx context.Context, id domain.SAOAuthClientID) (domain.ServiceAccountOAuthClient, error)
}

type TokenEnrichmentSAPort interface {
	// LookupByOAuthClientID resolves the kaname SA + OAuth-client mapping
	// from a Hydra `client_id`. Returns iamerr.ErrNotFound when the client
	// id is unknown (e.g. legacy Hydra registration outside kaname).
	LookupByOAuthClientID(ctx context.Context, hydraClientID domain.OAuthClientID) (domain.ServiceAccountOAuthClient, error)
	// GetServiceAccount fetches the SA referenced by a mapping row.
	GetServiceAccount(ctx context.Context, id domain.ServiceAccountID) (domain.ServiceAccount, error)
	// FindByExternalSubject resolves the Phase 3b federated SA mapping by
	// (external OIDC issuer, external sub). Returns iamerr.ErrNotFound when
	// no `trusted_subjects` entry matches.
	FindByExternalSubject(ctx context.Context, issuer, sub string) (domain.ServiceAccountOAuthClient, error)
}

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

type TokenEnrichmentUserPort interface {
	// FindByExternalID returns EVERY User row for an identity across every
	// Account, whatever its state. The first row that may authenticate is the
	// default active account.
	//
	// An ACTIVE-filtering variant is deliberately absent. That filter answers
	// "give me the usable rows", which is the wrong question here: a blocked
	// user comes back as an empty result, indistinguishable from an identity
	// that has no mirror yet — and the reduced claim set that exists for the
	// latter was therefore minted for the former. Reading the rows as they are
	// lets the state be judged instead of inferred from an absence.
	FindByExternalID(ctx context.Context, externalID domain.ExternalSubject) ([]domain.User, error)
}

type TokenEnrichmentUserTokenPort interface {
	// LookupByOAuthClientID resolves the kaname User-token (UserOAuthClient)
	// mapping from a Hydra `client_id`. Returns iamerr.ErrNotFound when the
	// client id is not a User-token client.
	LookupByOAuthClientID(ctx context.Context, hydraClientID domain.OAuthClientID) (domain.UserOAuthClient, error)
	// GetUser fetches the User referenced by a mapping row.
	GetUser(ctx context.Context, id domain.UserID) (domain.User, error)
}

type TokenHookContext struct {
	// GrantedScopes — OAuth2 scopes granted for this token.
	GrantedScopes []string
	// AuthTime — session auth_time (unix seconds); 0 when unknown.
	AuthTime int64
	// ACR — Authentication Context Class Reference.
	ACR string
	// CnfJkt — DPoP confirmation thumbprint (RFC 9449).
	CnfJkt string
	// CnfX5tS256 — mTLS certificate confirmation thumbprint (RFC 8705).
	CnfX5tS256 string
	// OAuthClientID — `request.client_id` as Hydra knows it. For
	// client_credentials this equals `subject`; for jwt-bearer (Phase 3b
	// federation IN) this is the kaname-issued client_id while `subject`
	// is the EXTERNAL assertion sub (e.g. `repo:acme/infra:ref:refs/heads/
	// main`). Empty when the handler cannot recover it.
	OAuthClientID string
	// GrantType — OAuth2 grant exercised. Used to disambiguate the
	// federated path (`urn:ietf:params:oauth:grant-type:jwt-bearer`) from
	// `client_credentials`. Empty when not provided by Hydra.
	GrantType string
	// ExternalIssuer — `iss` of the external assertion in the jwt-bearer
	// flow, populated by the handler when it can decode the form payload.
	// Empty for the non-federated paths.
	ExternalIssuer string
}

type Tx interface {
	// Commit commits the transaction.
	Commit(ctx context.Context) error
	// Rollback aborts the transaction. Safe to call after Commit (no-op).
	Rollback(ctx context.Context) error
}

type TxBeginner interface {
	Begin(ctx context.Context) (Tx, error)
}