token

type AccessStatus string

type AccessToken struct {
	Hash     string
	FamilyID string
	GrantID  string
	ClientID string
	Subject  string
	Scopes   []string
	// Audience はこのトークンが向けられる resource（RFC 8707 §2.2）。Family.Audience の部分集合。
	// Introspection の aud に載せる。空なら認可サーバー自身（UserInfo）向け。
	Audience []string

	Status    AccessStatus
	IssuedAt  time.Time
	ExpiresAt time.Time
	RevokedAt time.Time // ゼロ値なら未失効
}

type ByFormat map[resource.Format]Issuer

type Credentials struct {
	ClientID string
	Secret   string
	// Method は資格情報の提示方法。Secret が無ければ client.AuthNone。
	Method client.AuthMethod
}

type Error struct {
	Code        string
	Description string
}

type Family struct {
	ID       string
	GrantID  string
	ClientID string
	Subject  string
	// Scopes はこの Family のトークンに付く scope。Grant の scope の部分集合。
	Scopes []string
	// Audience はこの Family のトークンが向けられる resource（RFC 8707）の上限。
	// 認可要求の resource（Code の Resource）をそのまま引き継ぐ。Refresh で発行する Access Token の
	// Audience はこの部分集合（ADR-0008 §3）。resource なしの要求では空。
	Audience []string

	// AuthenticatedAt / AMR / ACR は元の認証の情報。Refresh 時に発行する ID Token の
	// auth_time / amr / acr は元の認証を表さなければならない（OIDC Core §12.2）ため、
	// Family に写しを持つ。client_credentials の Family ではゼロ値。
	AuthenticatedAt time.Time
	AMR             []string
	ACR             string

	Status    FamilyStatus
	CreatedAt time.Time
	// ExpiresAt は Refresh Token の絶対期限（Family 全体の寿命）。Refresh Token を
	// 発行しない Family ではゼロ値。
	ExpiresAt time.Time
	RevokedAt time.Time // ゼロ値なら未失効
}

type FamilyStatus string

type IDTokenInput struct {
	Subject         string
	AuthenticatedAt time.Time
	Nonce           string
	AMR             []string
	ACR             string
	// AccessToken は同時に発行した Access Token の平文（at_hash 用）。
	AccessToken string
	Scopes      []string
}

type IDTokenIssuer interface {
	IssueIDToken(ctx context.Context, c *client.Client, in IDTokenInput) (string, error)
}

type Introspection struct {
	Active bool
	// TokenType は Access Token なら "Bearer"。Refresh Token は RFC 6749 §5.1 の token_type を
	// 持たないので空。
	TokenType string
	Scopes    []string
	// Audience はトークンが向けられる resource（RFC 7662 §2.2 の aud）。Access Token はそのトークンの、
	// Refresh Token は Family の Audience。空なら認可サーバー自身向け。
	Audience  []string
	ClientID  string
	Subject   string
	IssuedAt  time.Time
	ExpiresAt time.Time
	// Kind は内部の種別（HintAccessToken / HintRefreshToken）。HTTP 応答には載せない。
	Kind string
}

type IntrospectionRequest struct {
	Token         string
	TokenTypeHint string
	Credentials   Credentials
}

type IssueInput struct {
	Client *client.Client
	// Family はトークンが属する Token Family。GrantID・Subject と、認可コード由来の認証情報
	// （AuthenticatedAt / AMR / ACR。client_credentials ではゼロ値）をここから取る。
	Family *Family
	// Scopes は Family.Scopes の、Audience は Family.Audience の部分集合（要求時の縮小を反映済み）。
	Scopes   []string
	Audience []string
	// Format は発行する形式。Audience の resource 設定で決まり、Audience が空なら FormatOpaque（ADR-0008 §3）。
	Format resource.Format
	// Alg は FormatJWT のときの署名アルゴリズム（resource.Resource.EffectiveAlg）。
	Alg string
	Now time.Time
}

type Issuer interface {
	Issue(ctx context.Context, in IssueInput) (plaintext string, rec *AccessToken, err error)
}

type JWTIssuer struct {
	// Issuer は iss クレーム（RFC 8414 の issuer と同じ値）。
	Issuer string
	Keys   *keys.Set
}

type OpaqueIssuer struct{}

type RefreshStatus string

type RefreshToken struct {
	Hash     string
	FamilyID string

	Status         RefreshStatus
	ReplacedByHash string // Status が rotated のとき、後継トークンの Hash
	IssuedAt       time.Time
	ExpiresAt      time.Time
	RotatedAt      time.Time // ゼロ値なら未 Rotation
	RevokedAt      time.Time // ゼロ値なら未失効
}

type Request struct {
	GrantType   string
	Credentials Credentials

	// authorization_code
	Code         string
	RedirectURI  string
	CodeVerifier string

	// refresh_token
	RefreshToken string

	// Scope は refresh_token / client_credentials の scope パラメータ（空白区切り、未指定なら空）。
	Scope string

	// Resource は resource パラメータ（RFC 8707 §2.2。複数可）。発行する Access Token の Audience を
	// 認可済みの範囲内で絞る。未指定なら認可済みの全部。
	Resource []string
}

type Response struct {
	AccessToken  string `json:"access_token"`
	TokenType    string `json:"token_type"`
	ExpiresIn    int64  `json:"expires_in"`
	Scope        string `json:"scope,omitempty"`
	RefreshToken string `json:"refresh_token,omitempty"`
	IDToken      string `json:"id_token,omitempty"`
}

type RevocationRequest struct {
	Token         string
	TokenTypeHint string
	Credentials   Credentials
}

type Service struct {
	Clients client.Resolver
	Store   Store
	// Grants は client_credentials が Grant を記録するのに使う。
	Grants grant.Store
	Clock  clock.Clock
	// Logger は監査イベント（発行、再利用検知）の出力先。nil なら slog.Default()。
	Logger *slog.Logger
	// IDTokens は openid scope が付与されたときに ID Token を発行する。nil なら発行しない。
	IDTokens IDTokenIssuer
	// Resources は resource パラメータ（RFC 8707 §2.2）で指定できる Resource Server の集合。
	// authorization.Service と同じ Set を Engine が配線する。nil なら空集合。
	Resources *resource.Set
	// Issuer は Access Token を発行する（ADR-0007 §4）。Engine は形式ごとの ByFormat（Opaque と JWT）を
	// 配線する。nil なら OpaqueIssuer だけで、JWT を要求する resource は内部エラーになる。
	Issuer Issuer

	// RefreshTokenTTL は Refresh Token の絶対期限、RefreshTokenIdleTTL はスライド期限。
	// 0 なら既定値（DefaultRefreshTokenTTL / DefaultRefreshTokenIdleTTL）。
	RefreshTokenTTL     time.Duration
	RefreshTokenIdleTTL time.Duration
}

type Store interface {
	// ConsumeAuthorizationCode は Code を消費済みにして内容を返す。
	//
	//   - 未消費かつ未期限: 消費済みにして Code を返す。
	//   - 既に消費済み: 消費済みの Code と storage.ErrCodeAlreadyUsed を返す。
	//     呼び出し側は Code.FamilyID の Family を失効させる。
	//   - 存在しない、または期限切れ: storage.ErrNotFound。
	//
	// 消費済みの Code は再利用検知のため、期限まで削除しない。
	ConsumeAuthorizationCode(ctx context.Context, codeHash string, now time.Time) (*authorization.AuthorizationCode, error)

	// IssueTokens は新しい Family と、それに属する最初のトークンを保存する。
	// refresh は nil でよい。Family の GrantID が指す Grant が active でなければ
	// storage.ErrGrantRevoked を返し、何も保存しない。
	IssueTokens(ctx context.Context, family *Family, access *AccessToken, refresh *RefreshToken) error

	// RotateRefreshToken は oldHash の Refresh Token を rotated にし、同じ Family に
	// next（Refresh Token）と access（Access Token）を保存する。
	//
	//   - oldHash が active かつ未期限: 成功。
	//   - oldHash が rotated: storage.ErrTokenReused。呼び出し側は Family を失効させる。
	//   - oldHash が revoked、または Family が revoked: storage.ErrFamilyRevoked。
	//   - Grant が revoked: storage.ErrGrantRevoked。
	//   - 存在しない、または期限切れ: storage.ErrNotFound。
	RotateRefreshToken(ctx context.Context, oldHash string, next *RefreshToken, access *AccessToken, now time.Time) error

	// LookupAccessToken は Access Token と、それが属する Grant を返す。
	// Grant の失効チェックを二重化するため、Grant も併せて返す。なければ storage.ErrNotFound。
	LookupAccessToken(ctx context.Context, hash string) (*AccessToken, *grant.Grant, error)

	// LookupRefreshToken は Refresh Token を返す。なければ storage.ErrNotFound。
	LookupRefreshToken(ctx context.Context, hash string) (*RefreshToken, error)

	// GetTokenFamily は Family を返す。なければ storage.ErrNotFound。
	// Refresh Token は Family を介して Client・subject・scope に結びつく。
	GetTokenFamily(ctx context.Context, id string) (*Family, error)

	// RevokeTokenFamily は Family と配下の全トークンを失効させる。
	// 既に失効済みなら何もせず nil。存在しなければ storage.ErrNotFound。
	RevokeTokenFamily(ctx context.Context, familyID string, now time.Time) error

	// RevokeAccessToken は Access Token 1 つを失効させる。存在しなければ storage.ErrNotFound。
	RevokeAccessToken(ctx context.Context, hash string, now time.Time) error
}