authorization

type AuthorizationCode struct {
	Hash string

	TxnID    string
	ClientID string
	GrantID  string
	// FamilyID は、この Code の交換で作られる Token Family の ID をあらかじめ確定したもの。
	// Code の再利用を検知したとき、この Family を失効させる（RFC 6749 §4.1.2）。
	FamilyID string

	Subject             string
	RedirectURI         string
	RedirectURIExplicit bool
	Scopes              []string
	CodeChallenge       string
	CodeChallengeMethod string
	Nonce               string
	// Resource は認可要求の resource をそのまま引き継いだもの（ADR-0008 §3）。
	// Code 交換で発行する Access Token の Audience はこの部分集合になる（RFC 8707 §2.2）。
	Resource []string

	AuthenticatedAt time.Time
	AMR             []string
	ACR             string
	Claims          map[string]any

	CreatedAt  time.Time
	ExpiresAt  time.Time
	ConsumedAt time.Time // ゼロ値なら未消費
}

type Error struct {
	Code        string
	Description string
	RedirectURI string
	State       string
	// Cause はログ用の内部原因。Client には返さない。
	Cause error
}

type Outcome struct {
	// Subject はエンジンにとって不透明なユーザー識別子。
	Subject string
	// AuthenticatedAt は認証時刻。max_age の検証と ID Token の auth_time に使う。
	AuthenticatedAt time.Time
	// GrantedScopes は要求 scope の部分集合。
	GrantedScopes []string
	// AMR / ACR は ID Token にそのまま載せる（OIDC Core §2）。
	AMR []string
	ACR string
	// Claims は ID Token / UserInfo 用のスナップショット（ADR-0006 §3）。
	Claims map[string]any
}

type Patch struct {
	Outcome         *Outcome
	Rejection       *Rejection
	ResumeTokenHash string
}

type Rejection struct {
	// Error は RFC 6749 §4.1.2.1 / OIDC Core §3.1.2.6 のエラーコード。
	Error       string
	Description string
}

type Request struct {
	ClientID string

	// RedirectURI は登録情報と照合済みの、実際に使う redirect URI。
	RedirectURI string
	// RedirectURIExplicit は要求に redirect_uri パラメータが含まれていたか。
	// RFC 6749 §4.1.3 により、含まれていた場合はトークン要求でも同じ値を要求する。
	RedirectURIExplicit bool

	Scopes []string
	State  string

	// PKCE（RFC 7636）。Method は常に "S256"。
	CodeChallenge       string
	CodeChallengeMethod string

	// OIDC Core §3.1.2.1。Nonce は ID Token に転記する。他はエンジンが解釈しない。
	Nonce     string
	Prompt    []string
	MaxAge    time.Duration
	HasMaxAge bool
	LoginHint string
	UILocales string
	ACRValues string

	// Resource は RFC 8707 §2.1 の resource パラメータ。Engine の設定と Client の許可範囲で
	// 検証済みで、resource.Normalize の正規形・重複なし。要求になければ空（ADR-0008 §2、§3）。
	Resource []string
}

type Service struct {
	Clients client.Resolver
	Store   Store
	Grants  grant.Store
	Clock   clock.Clock

	// Resources は認可要求の resource パラメータで指定できる Resource Server の集合（RFC 8707 §2.1）。
	// nil なら空集合で、resource 付きの要求はすべて invalid_target になる。
	Resources *resource.Set

	// Issuer は認可サーバーの識別子（RFC 8414 の issuer）。認可応答の iss に使う（RFC 9207）。
	Issuer string

	// TransactionTTL / CodeTTL は 0 なら既定値。上限の検査は Engine の設定検証で行う。
	TransactionTTL time.Duration
	CodeTTL        time.Duration
}

type Status string

type Store interface {
	// CreateTransaction は Transaction を保存する。同じ ID があれば storage.ErrAlreadyExists。
	CreateTransaction(ctx context.Context, txn *Transaction) error

	// GetTransaction は ID で Transaction を返す。なければ storage.ErrNotFound。
	GetTransaction(ctx context.Context, id string) (*Transaction, error)

	// TransitionTransaction は Status が from のときだけ to に更新し、patch を適用する（CAS）。
	// Status が from でなければ storage.ErrStateConflict、存在しなければ storage.ErrNotFound。
	// 遷移の正当性（from.CanTransitionTo(to)）は呼び出し側が保証する。
	TransitionTransaction(ctx context.Context, id string, from, to Status, patch Patch) error

	// CreateAuthorizationCode は Code を保存する。同じ Hash があれば storage.ErrAlreadyExists。
	CreateAuthorizationCode(ctx context.Context, code *AuthorizationCode) error
}

type Transaction struct {
	ID     string
	Status Status

	// Request は検証済みの認可要求。Interaction App はこれを参照してログイン・同意 UI を描く。
	Request Request

	// BrowserBindingHash は、/authorize でブラウザに発行した結合 Cookie 値の SHA-256。
	// Resume 時に同じブラウザからの要求であることを確認する（ADR-0003 §3）。
	BrowserBindingHash string

	// Outcome は Complete で記録される結果。Status が completed / consumed のときのみ非 nil。
	Outcome *Outcome
	// Rejection は Reject で記録される結果。Status が rejected / consumed のときのみ非 nil。
	Rejection *Rejection
	// ResumeTokenHash は Complete / Reject で発行した単回使用トークンの SHA-256。
	ResumeTokenHash string

	CreatedAt time.Time
	ExpiresAt time.Time
}