oauthceremony

type AccessTokenIssuer interface {
	// IssueAccessToken выпускает токен доступа по гранту.
	//
	// # Что порт получает
	//
	// Грант — тот же, что церемония положит под jti этого выпуска
	// (AccessTokenVault.StoreAccessToken), очищенный тем же перечнем полей.
	// Отличие одно: срок токена доступа в сеансе у порта — граница (см. ниже),
	// а у записи — exp этого выпуска. Предъявленных секретов — кода,
	// `code_verifier`, токена обновления, секрета клиента — в гранте нет.
	//
	// # Что идёт в токен
	//
	// Утверждения о доступе берутся ТОЛЬКО из того, что назначили согласие и
	// церемония: субъект — grant.Session.Subject, клиент — grant.ClientID,
	// области и получатели — grant.GrantedScopes и grant.GrantedAudiences.
	// grant.RequestedScopes и grant.RequestedAudiences — то, что клиент ПРОСИЛ
	// в запросе авторизации, а не то, что дало согласие; в токен они не идут.
	// grant.Form — протокольные поля запроса, а не утверждения; тоже не идут.
	//
	// Контекст входа — grant.Session.SessionID, grant.Session.ACR и
	// grant.Session.AuthTime: сессия, уровень (`acr`) и момент (`auth_time`)
	// аутентификации, снятые на выдаче кода. У всего семейства они одни —
	// обмен и оборот их не пересчитывают, — и токен, несущий `acr` или
	// `auth_time`, берёт их ОТСЮДА: карта grant.Session.Claims ключей
	// контекста входа не несёт (церемония отвергает их при выдаче), и второго
	// источника у этих значений нет.
	//
	// Токен несёт КЛЮЧ СЕМЕЙСТВА — grant.GrantID. Проверка предъявленного
	// токена сверяет по нему отзыв семейства (см. GrantRevoker, «Отзыв
	// действует и там, где токен доступа ПРЕДЪЯВЛЯЮТ»): токен без ключа
	// семейства отзыв пережил бы до своего exp.
	//
	// # Срок и момент выпуска
	//
	// Срок назначает церемония: grant.Session.ExpiresAt[TokenKindAccess] —
	// граница, позже которой токен истечь НЕ ВПРАВЕ (срок из
	// Config.AccessTokenLifespan от мига обмена, сжатый границей семейства).
	// Выпуск раньше неё законен: подписант режет срок до своего потолка или
	// до целых секунд. Позже неё — ErrPortContract, и выпуск клиенту не
	// уезжает.
	//
	// Момент выпуска — не раньше начала секунды, в которой церемония позвала
	// порт: iat в целых секундах законен, iat раньше этой секунды —
	// ErrPortContract. Срок в ответе обмена — ExpiresAt − IssuedAt, и момент
	// выпуска раньше вызова удлинил бы его сверх того, что токену осталось
	// жить.
	//
	// Исход — IssuedAccessToken, у которого названо всё: значение, jti,
	// момент выпуска и exp, причём exp позже момента выпуска. Под jti
	// церемония кладёт грант (AccessTokenVault.StoreAccessToken), а срок в
	// ответе обмена считает как ExpiresAt − IssuedAt — те же exp и iat, что
	// лежат в самом токене; незаполненное поле — ErrPortContract.
	IssueAccessToken(ctx context.Context, grant GrantRecord) (IssuedAccessToken, error)

	// IdentifyAccessToken проверяет предъявленный токен и отдаёт его jti.
	//
	// Проверяет ТОЛЬКО ПОДЛИННОСТЬ: подпись ключом издателя и форму. Срок
	// порт НЕ судит: его судит церемония по записи гранта. Исходов три, и все
	// три названы:
	//
	//  1. Токен выпущен этим издателем → (jti, nil) — в том числе ИСТЁКШИЙ и
	//     в том числе токен отозванного семейства. Истёкший церемония называет
	//     негодным по записи гранта (`active: false`, RFC 7662 §2.2), а отзыв
	//     по нему снимает семейство (RFC 7009 §2.1) — так же, как по живому.
	//     Пустой jti при nil — ErrPortContract.
	//  2. Токен не его: чужая подпись, неизвестный ключ, не та форма →
	//     ("", ErrGrantNotFound). На интроспекции это `active: false`, на
	//     отзыве — успех без действия (RFC 7662 §2.2, RFC 7009 §2.2).
	//  3. Проверить не удалось: сбой, недоступность, срок или отмена вызова →
	//     отказ ОПЕРАЦИИ. Опознание, которое не состоялось, не вправе стать ни
	//     «негоден», ни «отозвано»: отзыв ответил бы успехом, не сняв живой
	//     токен.
	//
	// Всякий иной названный портом случай — вердикт о токене вместо jti:
	// ErrTokenExpired, ErrInactiveToken, ErrTokenSignatureMismatch и прочие.
	// Это ErrPortContract, и операция отказывает, а не отвечает: прочитанный
	// как «не наш», вердикт «истёк» сделал бы отзыв по истёкшему токену
	// доступа успехом, оставив живым токен обновления его семейства.
	//
	// Грант ищется ТОЛЬКО по опознанному jti. Поэтому значение, jti которого
	// взято из чужого токена, а подпись не сходится, гранта не находит.
	//
	// # Значение token — предъявительский секрет
	//
	// Порт получает предъявленное значение как есть: токен доступа, а на
	// интроспекции и отзыве без подсказки вида — и токен обновления. Порт НЕ
	// пишет его в журнал и НЕ кладёт в текст своего отказа — ни целиком, ни
	// частью. Церемония со своей стороны вырезает предъявленное значение из
	// каждого текста отказа опознания (описание, подсказка, подробности), но
	// отказ порта остаётся причиной отказа (Unwrap) таким, каким порт его
	// вернул.
	IdentifyAccessToken(ctx context.Context, token string) (string, error)
}

type AccessTokenVault interface {
	// StoreAccessToken кладёт грант под подписью токена доступа — его jti,
	// названным при выпуске (AccessTokenIssuer.IssueAccessToken). Ожидается
	// ровно одна затронутая строка.
	StoreAccessToken(ctx context.Context, signature string, grant GrantRecord) (StoreOutcome, error)

	// FetchAccessToken отдаёт грант по подписи. Нет → ErrGrantNotFound.
	// Токен отозванного семейства (см. GrantRevoker) — тоже ErrGrantNotFound,
	// когда бы он ни был положен.
	FetchAccessToken(ctx context.Context, signature string) (GrantRecord, error)

	// DropAccessToken снимает токен доступа по подписи.
	//
	// Затронуто 0 строк — ЗАКОННЫЙ исход, а не отказ: снятие
	// несуществующего артефакта идемпотентно по RFC 7009 §2.2, и служба
	// не обязана знать, кто снял его первым. Больше одной строки →
	// ErrPortContract.
	DropAccessToken(ctx context.Context, signature string) (StoreOutcome, error)
}

type AuthorizationCodeRecord struct {
	// Grant — грант, выданный кодом.
	Grant GrantRecord

	// ProofKey — привязка кода к доказательству владения ключом.
	ProofKey ProofKeyBinding
}

type AuthorizationCodeVault interface {
	// StoreAuthorizationCode кладёт запись кода под его подписью — sha256
	// значения кода в hex, 64 знака. Само значение сюда не приходит: код
	// непрозрачен, и строка хранилища его не выдаёт.
	//
	// Подпись уникальна: ожидается INSERT, затронувший ровно одну строку.
	// Затронуто 0 → ErrPortContract (вставка, ничего не вставившая, —
	// дефект). Затронуто больше 1 → ErrPortContract (подпись не
	// уникальна). Столкновение подписей → ErrStorageConflict.
	//
	// Привязка в записи ВСЕГДА годна (метод S256, вызов — свёртка в
	// base64url): запрос без неё отвергается до выдачи, и служба вправе
	// держать оба столбца обязательными.
	StoreAuthorizationCode(ctx context.Context, signature string, code AuthorizationCodeRecord) (StoreOutcome, error)

	// FetchAuthorizationCode отдаёт запись кода по его подписи.
	//
	// Исходов ТРИ, и все три названы:
	//
	//  1. Код есть и не погашен → (запись, nil).
	//  2. Кода нет вовсе → (пустая запись, ErrGrantNotFound).
	//  3. Код есть и УЖЕ ПОГАШЕН → (ЗАПИСЬ, ErrAuthorizationCodeConsumed).
	//
	// Третий исход обязан отдавать запись ВМЕСТЕ с ошибкой. Это не
	// небрежность контракта: повторное предъявление кода отзывает ВСЕ
	// артефакты того гранта (RFC 6749 §4.1.2, замечание о безопасности) —
	// отзыв исполняет церемония по завершении операции, — а для отзыва
	// нужен идентификатор гранта. Грант без идентификатора при третьем
	// исходе — ErrPortContract: реализация превратила бы обнаруженную атаку
	// в тихий отказ, оставив выданные токены живыми.
	//
	// Третий исход обязан отдаваться, пока может жить семейство гранта, — и
	// после срока самого кода. Повтор узнаётся по записи, а не по сроку:
	// движок сверяет повтор раньше срока, и срока погашенного кода церемония
	// не судит. Запись, снятая по сроку кода, превратила бы повтор после срока
	// во второй исход — «кода нет», — и семейство осталось бы живым. Порог
	// уборки записи поэтому считается от tokenpolicy.MaxRefreshTokenFamilyTTL,
	// а не от tokenpolicy.MaxAuthorizationCodeTTL.
	//
	// Привязка отдаётся ТАКОЙ, КАКОЙ ЛЕГЛА: живой код без годной привязки S256
	// — ErrPortContract (порча записи), а не «PKCE не было».
	FetchAuthorizationCode(ctx context.Context, signature string) (AuthorizationCodeRecord, error)

	// ConsumeAuthorizationCode гасит код.
	//
	// ОДНОЙ ИНСТРУКЦИЕЙ, с условием внутри неё:
	//
	//	UPDATE authorization_codes
	//	   SET consumed_at = now()
	//	 WHERE signature = $1 AND consumed_at IS NULL
	//
	// и возвратом RowsTouched(tag.RowsAffected()).
	//
	// Исходы по числу строк:
	//   1 → код погашен нами; обмен продолжается;
	//   0 → код уже был погашен — одновременный ПОВТОР: выборку кода прошли
	//       двое, и этот обмен опередили. Церемония отвечает
	//       ErrAuthorizationCodeConsumed и отзывает семейство гранта (через
	//       GrantRevoker, вне единицы работы движка) — вместе с парой,
	//       которую получил опередивший; обмен не состоится;
	//   иное → ErrPortContract: подпись не уникальна либо драйвер не
	//       умеет считать строки.
	//
	// ЗАПРЕЩЕНО: читать, сравнивать в коде и потом писать. Запрещено
	// возвращать StoreOutcome{} — незаполненный исход отвергается как
	// нарушение контракта, а не толкуется как ноль строк.
	ConsumeAuthorizationCode(ctx context.Context, signature string) (StoreOutcome, error)
}

type AuthorizationGrant struct {
	// Subject — от чьего имени выдаётся грант. Пусто — отказ.
	Subject string

	// Username — человекочитаемое имя. Необязательно.
	Username string

	// SessionID — сессия входа, из которой служба выдаёт грант. Пусто —
	// отказ: семейство гранта кончается вместе с этой сессией, и без её
	// имени кончить его было бы нечем.
	SessionID string

	// ACR — уровень аутентификации этой сессии (`acr`, RFC 9470 §3). Словарь
	// ЗАКРЫТ и один на платформу — ранжирование acrlevel: годен уровень,
	// который оно ставит выше анонима. Прочее, в том числе пустое значение и
	// "0" (аноним), — отказ: грант выдаётся после входа, а у входа уровень
	// есть.
	ACR string

	// AuthTime — момент аутентификации этой сессии (`auth_time`). Нулевое
	// время — отказ: момента нет.
	AuthTime time.Time

	// GrantedScopes — области, которые служба РЕШИЛА выдать. Выдача может
	// сузить запрос, но не расширить: область, не покрытая запрошенными по
	// правилу Config.ScopeMatching, отвергается ЦЕРЕМОНИЕЙ
	// (ErrCeremonyMisuse) до выпуска кода. Движок выданное не сверяет.
	//
	// Каждая область — `scope-token` (RFC 6749 §3.3,
	// `1*( %x21 / %x23-5B / %x5D-7E )`); иная отвергается так же — до выпуска
	// кода и раньше сверки с запросом: образец `tenant.*` покрыл бы и
	// `tenant.a b`, а клиент прочёл бы её двумя областями.
	GrantedScopes []string

	// GrantedAudiences — получатели, которых служба решила выдать. Тоже не
	// шире запроса: получатель, которого нет среди запрошенных (точное
	// совпадение), отвергается церемонией (ErrCeremonyMisuse).
	GrantedAudiences []string

	// Claims — дополнительные утверждения в сеанс. Ключ контекста входа
	// (`sid`, `acr`, `auth_time`) — отказ (ErrCeremonyMisuse): у значения
	// есть поле выше, и второе место у него разошлось бы с первым.
	Claims map[string]any

	// ExpiresAt — ГРАНИЦА годности по видам артефактов для всего семейства
	// гранта: код, первая пара и каждая пара оборота живут не дольше. Срок
	// каждого артефакта — меньшее из границы и срока из настроек церемонии,
	// отсчитанного от его выпуска. Вид без записи — срок из настроек.
	// Нулевое время — не граница и отвергается церемонией по имени вида
	// (ErrCeremonyMisuse) до выпуска кода: движок читает нулевой срок
	// токена обновления как «без срока», и граница-ноль сделала бы семейство
	// бессрочным. Вид вне словаря TokenKinds отвергается так же: церемония
	// его не выпускает, и граница под ним не ограничила бы ничего.
	ExpiresAt map[TokenKind]time.Time
}

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

type AuthorizationRequest struct {
	// ClientID — `client_id`.
	ClientID string

	// RedirectURI — `redirect_uri`. Пусто означает «взять единственный
	// зарегистрированный»; при нескольких зарегистрированных пустое
	// значение — отказ, и его выносит движок.
	RedirectURI string

	// ResponseKinds — `response_type`, разобранный по пробелу.
	ResponseKinds []ResponseKind

	// Scopes — `scope`, разобранный по пробелу. Область вне грамматики
	// `scope-token` (RFC 6749 §3.3) Authorize отвергает случаем
	// CodeInvalidScope и возвращает намерение, годное для DenyAuthorization.
	Scopes []string

	// Audiences — `audience`.
	Audiences []string

	// State — `state`. Непрозрачное значение клиента против CSRF.
	State string

	// Delivery — `response_mode`.
	Delivery ResponseDelivery

	// Additional — прочие протокольные поля: `code_challenge`,
	// `code_challenge_method`, `nonce`, `prompt`, `request_uri`, поля
	// расширений. Дублировать именованные поля запрещено.
	Additional map[string][]string
}

type AuthorizationResult struct {
	// Status — состояние ответа HTTP, которое следует выставить.
	Status int

	// Headers — заголовки, которые следует выставить. Для доставки
	// query и fragment сюда входит Location.
	Headers map[string][]string

	// Body — тело ответа. Непусто только для доставки form_post: там
	// ответ — самоотправляющаяся форма HTML, и собирает её движок.
	Body []byte

	// RedirectURI — адрес возврата целиком, включая параметры. Пусто для
	// доставки form_post.
	RedirectURI string

	// Parameters — параметры ответа, разобранные из адреса возврата:
	// `code`, `state`, `scope`, либо `error`+`error_description` на
	// пути отказа.
	Parameters map[string][]string

	// Delivery — способ доставки, которым ответ собран. Никогда не
	// DeliveryDefault: к этому мигу выбор уже сделан.
	Delivery ResponseDelivery
}

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

type ClientAuthMethod string

type ClientDirectory interface {
	// LookupClient отдаёт запись клиента по его публичному
	// идентификатору.
	//
	// Клиента нет → ErrGrantNotFound. Отдавать пустую запись без ошибки
	// запрещено: «клиента нет» и «клиент есть, но пуст» — разные события.
	//
	// ErrGrantNotFound — ЕДИНСТВЕННЫЙ случай пакета в контракте этого
	// вызова. Любой другой наш случай церемония читает как нарушение
	// контракта (ErrPortContract), а не как исход протокола; прочий отказ —
	// отказ операции (срок и отмена — своими случаями).
	//
	// В операции, где клиент доказывает себя (обмен, интроспекция, отзыв),
	// «клиента нет» доказательства не обрывает: церемония всё равно зовёт
	// порт сверки (ClientSecretVerifier) — ровно один раз, как для известного
	// клиента, — и отвечает тем же отказом, что неверному секрету.
	LookupClient(ctx context.Context, clientID string) (ClientRegistration, error)
}

type ClientRegistration struct {
	// ClientID — публичный идентификатор клиента.
	ClientID string

	// RedirectURIs — точный перечень разрешённых адресов возврата.
	RedirectURIs []string

	// GrantKinds — способы получения токена, разрешённые клиенту.
	GrantKinds []GrantKind

	// ResponseKinds — разрешённые СОЧЕТАНИЯ типов ответа. Каждый элемент —
	// одно сочетание; составное записывается через пробел (RFC 6749 §3.1.1).
	// Церемония обслуживает одно сочетание — `code` (ResponseKindCode).
	ResponseKinds []string

	// Scopes — области, которые клиенту дозволено запрашивать.
	Scopes []string

	// Audiences — получатели, которых клиенту дозволено запрашивать.
	Audiences []string

	// Public — клиент не может хранить секрет (приложение в браузере,
	// мобильное приложение). PKCE церемония требует от всякого клиента, и
	// публичного, и конфиденциального (см. ProofKeyBinding).
	Public bool

	// ResponseDeliveries — разрешённые способы доставки ответа. Пустой
	// перечень означает «только тот, что движок выберет по умолчанию».
	ResponseDeliveries []ResponseDelivery
}

type ClientSecretVerifier interface {
	// VerifyClientSecret сверяет секрет, предъявленный от имени клиента
	// clientID. Идентификатор — такой, каким его назвал клиент: знает ли его
	// служба, порт выясняет сам.
	VerifyClientSecret(ctx context.Context, clientID string, presented PresentedSecret) (SecretVerdict, error)
}

type Config struct {
	// AuthorizationEndpoint и TokenEndpoint — адреса точек авторизации и
	// выдачи (RFC 6749 §3.1, §3.2), под которыми служба публикует
	// церемонию, например `https://iam.example.net/iam/v1/authorize` и
	// `https://iam.example.net/iam/v1/token`. Названы явно: путь, на котором
	// служба публикует точки, — её решение, и ни из какого другого поля
	// церемония его не выводит.
	//
	// Адрес точки авторизации — адрес запроса, который церемония подаёт
	// движку от имени Authorize. Адрес точки выдачи — адрес запросов от имени
	// Exchange, Introspect и Revoke (интроспекция и отзыв синтезируются на
	// нём же) и значение TokenURL в настройках движка: с ним движок сверял бы
	// `aud` утверждения клиента (RFC 7523 §3), но на путях церемонии эта
	// сверка не исполняется — утверждение клиента церемония не обслуживает
	// и движок отвергает его раньше (TestClientAssertionIsRefused).
	//
	// Каждый обязан быть абсолютным адресом с именем хоста (порт без имени,
	// `https://:8443/…`, хостом не считается), без сведений пользователя,
	// строки запроса и фрагмента, и записан так, как его получит движок:
	// разбор и обратная запись адреса дают ту же строку. Адрес с пробелом,
	// буквой не-ASCII или схемой в верхнем регистре разбирается, но в запросе к
	// движку уехал бы в другом написании — экранированным или в нижнем
	// регистре, — и адрес, который служба публикует, разошёлся бы с адресом, на
	// который церемония подаёт запросы. Фрагмент адресу точки
	// запрещает сам RFC 6749 (§3.1, §3.2). Строку запроса он разрешает, и
	// здесь она отвергается у обоих адресов: у точки авторизации церемония
	// ставит параметры запроса строкой запроса поверх адреса, и принесённая
	// адресом строка слилась бы с ними; у точки выдачи её пришлось бы
	// сохранять каждому клиенту и в `aud`, — контракт один на оба адреса, и
	// он узкий. Сведения пользователя отвергаются потому, что адрес точки
	// служба публикует клиентам, а учётные данные в публикуемом адресе —
	// секрет в открытом виде; доказательство клиента приезжает заголовком
	// или телом запроса (RFC 6749 §2.3.1), а не адресом.
	AuthorizationEndpoint string
	TokenEndpoint         string

	// AccessTokenLifespan, RefreshTokenLifespan, AuthorizationCodeLifespan
	// — сроки жизни артефактов, каждый от выпуска артефакта. Все три обязаны
	// быть положительными и не длиннее своих потолков фундамента —
	// tokenpolicy.MaxTokenTTL, tokenpolicy.MaxRefreshTokenFamilyTTL и
	// tokenpolicy.MaxAuthorizationCodeTTL. Срок выше потолка New отвергает,
	// называя поле и потолок, а не урезает молча; решение, из которого взято
	// значение каждого потолка, записано у самой константы.
	//
	// У AccessTokenLifespan причина потолка ещё и в выпуске: токен доступа
	// подписывает служба (Ports.AccessTokenIssuer), а её подписант выше
	// потолка платформы не выпускает. Выпуск короче границы законен (контракт
	// порта), поэтому церемония со сроком длиннее обменивала бы исправно, но
	// срок настроек не исполнялся бы ни на одном выпуске — настройка лгала бы
	// молча; отказ при сборке её не допускает.
	//
	// RefreshTokenLifespan — срок ОДНОГО токена обновления: оборот выпускает
	// преемника с тем же сроком от своего выпуска. Предел всего семейства New
	// не держит — его держат граница гранта (AuthorizationGrant.ExpiresAt) и
	// база службы (tokenpolicy.MaxRefreshTokenFamilyTTL называет обоих).
	//
	// Подписного материала в настройках нет: код авторизации и токен
	// обновления непрозрачны (случайные байты, в хранилище — sha256
	// значения), а токен доступа подписывает порт службы.
	AccessTokenLifespan       time.Duration
	RefreshTokenLifespan      time.Duration
	AuthorizationCodeLifespan time.Duration

	// ScopeMatching — правило сопоставления областей.
	ScopeMatching ScopeMatching

	// RefreshTokenIssuance — когда выдавать токен обновления.
	RefreshTokenIssuance RefreshTokenIssuance

	// RefreshTokenScopes — области, дающие токен обновления. Обязателен
	// и непуст при RefreshTokenIssuanceOnScope; обязан быть пуст при
	// RefreshTokenIssuanceAlways, иначе у правила было бы два места.
	RefreshTokenScopes []string

	// MinParameterEntropy — минимальная длина `state` и `nonce` в
	// символах. Обязана быть не меньше 8 (RFC 6749 §10.10 требует не
	// менее 128 бит для непредсказуемых значений; 8 символов — нижняя
	// граница, ниже которой параметр перестаёт быть защитой от CSRF).
	MinParameterEntropy int

	// PortTimeout — срок ОДНОГО вызова порта службы: порта хранения и порта
	// выпуска токена доступа (Ports.AccessTokenIssuer) — и выпуска, и
	// опознания.
	PortTimeout time.Duration

	// OperationTimeout — срок ВСЕЙ операции церемонии. Обязан быть не
	// меньше PortTimeout: иначе первый же вызов порта не уложился бы в
	// операцию, и срок порта не значил бы ничего.
	OperationTimeout time.Duration

	// NewGrantID — крючок чеканки идентификатора гранта. Обязателен.
	//
	// Идентификатор гранта — ключ семейства: по нему служба отзывает все
	// артефакты одной выдачи и под ним ведёт свою запись семейства, форму
	// которой держит ограничение её схемы. Поэтому его выбирает СЛУЖБА:
	// движок, получив запрос без идентификатора, чеканит свой при первом
	// чтении, и ключ, которого служба не выбирала, лёг бы во все её записи.
	// Приставки платформы — предмет пакета `ids`, а не этого.
	//
	// Церемония зовёт крючок ровно один раз на грант — в CompleteAuthorization,
	// после своих проверок выдачи и до выпуска кода — и ставит идентификатор
	// запросу движка раньше, чем тот его прочтёт. Разбор запроса, отказ в
	// согласии, обмен кода, оборот токена обновления, интроспекция и отзыв
	// крючка не зовут: идентификатор едет из записи хранилища.
	//
	// Вызову назначается срок Config.PortTimeout, как вызову порта. Отказ
	// крючка — отказ выдачи (случай разбирается, как отказ порта), и записи
	// кода в хранилище не появляется. Пустой идентификатор — нарушение
	// контракта (ErrPortContract): на пустом движок начеканил бы свой.
	// Уникальность — забота службы: церемония её не сверяет, её держит ключ
	// записи семейства в хранилище службы.
	NewGrantID func(ctx context.Context) (string, error)
}

type FailureCode uint16

type GrantKind string

type GrantRecord struct {
	// GrantID — идентификатор гранта. По нему отзываются ВСЕ артефакты
	// одного гранта (RFC 7009 §2.1, замечание о реализации).
	//
	// Его чеканит служба крючком Config.NewGrantID при выдаче кода; записи
	// токенов наследуют его от записи кода. Запись, которую хранилище отдаёт
	// живой, обязана его нести: пустой — нарушение контракта порта
	// (ErrPortContract), а не повод движку начеканить свой.
	GrantID string

	// ClientID — клиент, которому выдан грант.
	ClientID string

	// IssuedAt — когда грант возник.
	IssuedAt time.Time

	// RequestedScopes / GrantedScopes — что просили и что дали. Хранятся
	// ОБА: отказ в области — это разница между ними, и она обязана быть
	// восстановима из записи, а не вычисляема заново.
	//
	// Каждая выданная область — `scope-token` (RFC 6749 §3.3): иной
	// церемония на хранение не отдаёт, и запись из хранилища с такой областью —
	// нарушение контракта порта (ErrPortContract): по ней обмен и оборот
	// выдали бы область заново.
	RequestedScopes []string
	GrantedScopes   []string

	// RequestedAudiences / GrantedAudiences — то же про получателей.
	RequestedAudiences []string
	GrantedAudiences   []string

	// Form — протокольные поля запроса, породившего грант, ОЧИЩЕННЫЕ
	// перечнем полей: всякая запись несёт лишь `grant_type`,
	// `response_type`, `scope` и `client_id`, а сверх них запись кода —
	// `redirect_uri`: по нему при обмене сверяется адрес возврата. Привязки к
	// доказательству владения ключом здесь НЕТ: у кода она — поле его записи
	// (AuthorizationCodeRecord.ProofKey), и второго места у неё нет.
	// Предъявленных секретов — кода, `code_verifier`, токена обновления,
	// секрета клиента — в Form нет ни у одной записи и ни у гранта, который
	// получает порт выпуска токена доступа.
	Form map[string][]string

	// Session — состояние сеанса.
	Session SessionRecord
}

type GrantRevoker interface {
	// RevokeGrantRefreshTokens снимает ВСЕ токены обновления гранта по
	// причине reason. Ноль строк — законный исход (нечего снимать).
	RevokeGrantRefreshTokens(ctx context.Context, grantID string, reason RevocationReason) (StoreOutcome, error)

	// RevokeGrantAccessTokens снимает ВСЕ токены доступа гранта по причине
	// reason. Ноль строк — законный исход.
	RevokeGrantAccessTokens(ctx context.Context, grantID string, reason RevocationReason) (StoreOutcome, error)
}

type IntrospectionRequest struct {
	// Token — предъявленный артефакт.
	Token string

	// KindHint — подсказка о виде артефакта. TokenKindUnspecified
	// означает «подсказки нет», и это законное значение.
	KindHint TokenKind

	// Scopes — области, наличие которых требуется подтвердить.
	Scopes []string

	// ClientID / ClientSecret / AuthMethod — чем доказывает себя тот, кто
	// спрашивает. Интроспекция без доказательства запрещена RFC 7662 §2.1.
	//
	// AuthMethod принимает ОДИН способ — ClientAuthBasic
	// (IntrospectionAuthMethods): движок на этой точке берёт доказательство
	// только заголовком Authorization. Пустое значение разрешается так же, как
	// в TokenRequest: при непустом секрете — ClientAuthBasic, при пустом —
	// ClientAuthNone. ClientAuthPost и ClientAuthNone, названные явно или
	// полученные разрешением пустого, Introspect отвергает по имени до
	// обращения к движку (ErrCeremonyMisuse): иначе они уезжали бы в движок и
	// получали его отказ «заголовка Authorization нет», не называющий способа.
	ClientID     string
	ClientSecret string
	AuthMethod   ClientAuthMethod
}

type IntrospectionResult struct {
	Active bool

	// Kind — вид артефакта, если его удалось определить.
	Kind TokenKind

	// AccessTokenType — тип токена доступа ("bearer"). Пусто для токена
	// обновления.
	AccessTokenType string

	// GrantID — идентификатор гранта, породившего артефакт: тот, что выдал
	// крючок Config.NewGrantID.
	GrantID string

	ClientID  string
	Subject   string
	Username  string
	Scopes    []string
	Audiences []string

	// SessionID, ACR, AuthTime — контекст входа гранта: снимок сессии на
	// выдаче кода (SessionRecord).
	SessionID string
	ACR       string
	AuthTime  time.Time

	// IssuedAt — когда возник грант.
	IssuedAt time.Time

	// ExpiresAt — когда артефакт перестаёт быть годным. Нулевое время
	// означает «срок не назначен», а не «уже истёк».
	ExpiresAt time.Time

	// Claims — дополнительные утверждения сеанса.
	Claims map[string]any
}

type IssuedAccessToken struct {
	// Token — значение токена, которое уезжает клиенту как есть.
	Token string

	// ID — идентификатор токена (утверждение `jti`). Под ним церемония кладёт
	// грант и под ним же ищет его при предъявлении.
	ID string

	// IssuedAt, ExpiresAt — момент выпуска и срок годности, ровно те, что
	// лежат в токене (`iat`, `exp`).
	IssuedAt  time.Time
	ExpiresAt time.Time
}

type Ports struct {
	Clients            ClientDirectory
	AuthorizationCodes AuthorizationCodeVault
	AccessTokens       AccessTokenVault
	RefreshTokens      RefreshTokenVault
	Grants             GrantRevoker
	AccessTokenIssuer  AccessTokenIssuer
	ClientSecrets      ClientSecretVerifier

	// Transaction — необязателен. Пусто означает «хранилище службы не
	// умеет транзакций», и церемония ведёт себя соответственно.
	Transaction UnitOfWork
}

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

type ProofKeyBinding struct {
	// Challenge — `code_challenge`.
	Challenge string

	// Method — `code_challenge_method`.
	Method ProofKeyMethod
}

type ProofKeyMethod string

type ProtocolError struct {
	// Code — случай. Единственное поле, по которому дозволено ветвиться.
	Code FailureCode

	// Description — описание случая для человека. Годится проводу.
	Description string

	// Hint — подсказка, что делать. Годится проводу.
	Hint string

	// Debug — внутренние подробности: текст отказа хранилища, имя порта,
	// имя обработчика. НЕ ГОДИТСЯ ПРОВОДУ никогда: здесь оседают строки
	// движка и строки подключения к базе. Годится журналу.
	Debug string
	// contains filtered or unexported fields
}

type RefreshTokenIssuance uint8

type RefreshTokenVault interface {
	// StoreRefreshToken кладёт грант под подписью токена обновления —
	// sha256 его значения в hex, — связывая его с подписью (jti)
	// выпущенного вместе с ним токена доступа. Связь нужна, чтобы отзыв
	// одного снимал второй.
	StoreRefreshToken(ctx context.Context, signature, accessSignature string, grant GrantRecord) (StoreOutcome, error)

	// FetchRefreshToken отдаёт грант по подписи.
	//
	// Исходов ТРИ, и все три названы:
	//
	//  1. Токен есть и не обёрнут → (грант, nil).
	//  2. Токена нет вовсе либо его семейство отозвано (см. GrantRevoker) →
	//     (пустой грант, ErrGrantNotFound).
	//  3. Токен есть и УЖЕ ОБЁРНУТ → (ГРАНТ, ErrRefreshTokenRotated).
	//
	// Третий исход — ПОВТОР (RFC 9700 §4.14.2): токеном владеют двое, и
	// сервер не знает, кто из них законный. Грант обязан ехать ВМЕСТЕ с
	// ошибкой по той же причине, что у погашенного кода: по нему отзывается
	// семейство. Обёрнутый токен, отданный как живой, превращает повтор в
	// обычный оборот, и пара, выданная первым оборотом, переживает его; грант
	// без идентификатора при третьем исходе — ErrPortContract (отзывать
	// нечего).
	FetchRefreshToken(ctx context.Context, signature string) (GrantRecord, error)

	// DropRefreshToken снимает токен обновления по подписи. Ноль строк —
	// законный исход, как и у DropAccessToken.
	DropRefreshToken(ctx context.Context, signature string) (StoreOutcome, error)

	// RotateRefreshToken помечает токен обновления использованным при
	// обороте.
	//
	// ОДНОЙ ИНСТРУКЦИЕЙ, по тем же основаниям, что и погашение кода:
	//
	//	UPDATE refresh_tokens
	//	   SET rotated_at = now()
	//	 WHERE grant_id = $1 AND signature = $2 AND rotated_at IS NULL
	//
	// Исходы: 1 → оборот наш; 0 → токен уже обернули — одновременный ПОВТОР:
	// выборку прошли двое, и этот оборот опередили. Церемония отвечает
	// ErrRefreshTokenRotated и отзывает семейство гранта; иное →
	// ErrPortContract.
	RotateRefreshToken(ctx context.Context, grantID, signature string) (StoreOutcome, error)
}

type ResponseDelivery string

type ResponseKind string

type RevocationReason string

type RevocationRequest struct {
	// Token — отзываемый артефакт.
	Token string

	// KindHint — подсказка о виде.
	KindHint TokenKind

	ClientID     string
	ClientSecret string
	AuthMethod   ClientAuthMethod
}

type ScopeMatching uint8

type SecretVerdict uint8

type SessionRecord struct {
	// Subject — устойчивый идентификатор того, от чьего имени выдан грант.
	Subject string

	// Username — человекочитаемое имя. Необязательно; уезжает в ответ
	// интроспекции.
	Username string

	// SessionID, ACR, AuthTime — контекст входа: сессия, из которой рождён
	// грант, её уровень аутентификации (`acr`) и момент аутентификации
	// (`auth_time`). Это СНИМОК, сделанный на выдаче кода
	// (AuthorizationGrant): обмен кода и каждый оборот токена обновления
	// переносят его без изменения, и у всего семейства гранта он один.
	//
	// Все три обязательны и в записи из хранилища: пустая сессия, уровень,
	// который ранжирование acrlevel не ставит выше анонима, и нулевое время —
	// нарушение контракта порта (ErrPortContract), а не «значения нет».
	SessionID string
	ACR       string
	AuthTime  time.Time

	// ExpiresAt — срок годности по каждому виду артефакта, записанный
	// церемонией в миг выпуска. Служба возвращает карту такой, какой её
	// получила: ключ, который церемония записала, пропасть не может — без
	// срока токена обновления движок считает токен бессрочным. Нулевое
	// время церемония не пишет, и ноль в записи из хранилища — нарушение
	// контракта порта (ErrPortContract), а не «ключа нет».
	ExpiresAt map[TokenKind]time.Time

	// NotAfter — граница годности СЕМЕЙСТВА гранта по видам артефактов:
	// ни один артефакт вида, выпущенный по этому гранту, — ни первый, ни
	// выпущенный оборотом, — не живёт дольше. Отсутствие ключа — границы
	// нет. Служба хранит границу вместе с сеансом и отдаёт её в каждой
	// выборке: без неё оборот назначил бы срок из настроек поверх и
	// продлил бы семейство за границу. Нулевое время границей не бывает
	// (выдача его отвергает), и ноль в записи из хранилища — нарушение
	// контракта порта (ErrPortContract), а не «ключа нет»: нулевая граница
	// сжала бы к себе срок токена обновления, а нулевой срок движок читает
	// как «без срока».
	NotAfter map[TokenKind]time.Time

	// Claims — дополнительные утверждения, которые служба кладёт в сеанс.
	// Переживают сериализацию через JSON, поэтому значения обязаны быть
	// представимы в JSON.
	//
	// Ключей контекста входа (`sid`, `acr`, `auth_time`) в карте нет: у
	// этих значений есть поля, и второе место у них разошлось бы с первым.
	// Такой ключ в записи из хранилища — нарушение контракта порта
	// (ErrPortContract).
	Claims map[string]any
}

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

type TokenKind string

type TokenRequest struct {
	// Grant — `grant_type`. Обязательно, и обязано входить в словарь.
	Grant GrantKind

	// ClientID — `client_id`.
	ClientID string

	// ClientSecret — секрет клиента В ЧИСТОМ ВИДЕ, как его прислал
	// клиент. Живёт ровно до конца вызова и уезжает ровно в одно место — в
	// порт сверки службы (ClientSecretVerifier), обёрнутым в PresentedSecret:
	// ни в GrantRecord, ни в ProtocolError, ни в журнале он не оседает.
	ClientSecret string

	// AuthMethod — каким способом доказывать клиента. Пустое значение
	// означает ClientAuthNone при пустом секрете и ClientAuthBasic при
	// непустом; иного умолчания здесь быть не может, и оно названо, а не
	// подразумевается.
	AuthMethod ClientAuthMethod

	// Code — `code`. Только для GrantAuthorizationCode.
	Code string

	// RedirectURI — `redirect_uri`. Обязателен, если был в запросе
	// авторизации (RFC 6749 §4.1.3).
	RedirectURI string

	// CodeVerifier — `code_verifier` (PKCE, RFC 7636).
	CodeVerifier string

	// RefreshToken — `refresh_token`. Только для GrantRefreshToken.
	RefreshToken string

	// Scopes — `scope`. Сужение относительно гранта.
	Scopes []string

	// Audiences — `audience`.
	Audiences []string

	// Additional — прочие протокольные поля: поля расширений. Утверждение
	// клиента (`client_assertion`) сюда класть бесполезно — движок его
	// отвергает (см. ClientAuthMethod).
	Additional map[string][]string
}

type TokenResult struct {
	// AccessToken — токен доступа.
	AccessToken string

	// TokenType — тип токена доступа; для церемонии всегда "bearer".
	TokenType string

	// ExpiresIn — срок жизни выпущенного токена доступа: его exp минус
	// момент выпуска, ровно те, что порт выпуска положил в токен
	// (AccessTokenIssuer, RFC 6749 §5.1 `expires_in`).
	ExpiresIn time.Duration

	// RefreshToken — токен обновления. Пусто, если не выдавался.
	RefreshToken string

	// Scopes — выданные области.
	Scopes []string

	// Additional — прочие поля ответа, положенные обработчиками
	// расширений. Именованные поля выше сюда НЕ дублируются.
	Additional map[string]any
}

type UnitOfWork interface {
	// Begin открывает единицу работы и возвращает контекст, несущий её.
	// Все последующие вызовы портов придут с этим контекстом.
	Begin(ctx context.Context) (context.Context, error)

	// Commit закрепляет единицу работы, найденную в контексте.
	Commit(ctx context.Context) error

	// Rollback отменяет единицу работы, найденную в контексте.
	Rollback(ctx context.Context) error
}