admin

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

type AdminAuth interface {
	// Authenticate checks whether the request is authorized.
	// Returns nil if authorized, or an error describing why not.
	Authenticate(r *http.Request) error
}

type AppRegistrar struct {
	KeyStore keys.KeyStorage
	Auth     AdminAuth

	// KidStore retains old keys during rotation grace periods so that
	// in-flight tokens signed with the previous key remain verifiable.
	// If nil, rotation replaces the key immediately with no grace period.
	// Typed as the KidStorage interface so deployments can plug in a
	// persistent backend (FS/GORM/GAE) without losing in-memory KidStore
	// compatibility (*KidStore satisfies KidStorage).
	KidStore keys.KidStorage

	// DefaultGracePeriod is the default grace period for key rotation
	// when not specified in the request. Defaults to 24h.
	DefaultGracePeriod time.Duration

	// Store persists app registration metadata. It is the source of truth;
	// the apps map below is a hot-path cache hydrated on construction and
	// updated synchronously on every write.
	Store core.AppRegistrationStore

	// AllowPrivateBCLHosts opts in to registering a backchannel_logout_uri
	// whose host resolves (or is literally) loopback / RFC1918 / link-local
	// / unspecified / multicast. Off by default so a client cannot register
	// a URI that, on session revoke, makes the AS POST to internal services
	// on its behalf (classic SSRF). Closed-network deployments where the AS
	// and the RS receivers share a private network can flip this on. When
	// flipped, the dispatcher's HTTP client must also opt in via
	// BCLDispatcher.AllowPrivateHosts or the dial-time guard still blocks.
	AllowPrivateBCLHosts bool
	// contains filtered or unexported fields
}

type ClientRegistrar interface {
	// Register handles RFC 7591 Dynamic Client Registration. The wire format
	// of the request and response is the RFC 7591 / 7592 client metadata
	// shape — RegisterRequest.Metadata is the standard DCR request body,
	// RegisterResponse.Registration is the standard DCR response body
	// (extended with the RFC 7592 §3 management credentials).
	Register(ctx context.Context, req *RegisterRequest) (*RegisterResponse, error)

	// ListClients returns every registration in the registry. Reads from
	// the in-memory cache hydrated from the core.AppRegistrationStore on
	// AppRegistrar construction.
	ListClients(ctx context.Context, req *ListClientsRequest) (*ListClientsResponse, error)

	// GetClient returns the registration for req.ClientID, or
	// core.ErrAppNotFound. This is the ADMIN read — distinct from
	// ClientRegistrationManager.GetRegistration which authenticates with
	// the client's own registration_access_token.
	GetClient(ctx context.Context, req *GetClientRequest) (*GetClientResponse, error)

	// DeleteClient removes the registration for req.ClientID and
	// invalidates its KeyStore entry. Returns core.ErrAppNotFound if the
	// client does not exist. This is the ADMIN delete — distinct from
	// ClientRegistrationManager.DeleteRegistration which authenticates
	// with the client's own token.
	DeleteClient(ctx context.Context, req *DeleteClientRequest) (*DeleteClientResponse, error)

	// RotateSecret rotates the signing key for req.ClientID. For symmetric
	// algorithms a fresh secret is generated and returned. For asymmetric
	// algorithms the caller MUST supply a new PublicKey (PEM) — there is
	// no server-side keypair generation today. When KidStore is configured
	// on AppRegistrar, the previous key is retained for the grace period
	// so in-flight tokens stay verifiable.
	RotateSecret(ctx context.Context, req *RotateSecretRequest) (*RotateSecretResponse, error)
}

type ClientRegistrationManager interface {
	// GetRegistration returns the registration for req.ClientID iff
	// req.AccessToken matches its stored registration_access_token. Any
	// auth failure — wrong token, missing token, unknown client_id — yields
	// ErrUnauthorized so callers (and attackers) cannot distinguish them.
	GetRegistration(ctx context.Context, req *GetRegistrationRequest) (*GetRegistrationResponse, error)

	// UpdateRegistration replaces the metadata for req.ClientID per RFC 7592
	// §2.2 (full replacement, not PATCH-style merge). The request's body-level
	// client_id (req.Metadata.ClientID) MUST equal req.ClientID — mismatch
	// returns ErrInvalidClientMetadata, mapped to HTTP 400 by the wrapper.
	// Auth failures return ErrUnauthorized as with GetRegistration.
	//
	// On success the registration_access_token is rotated (RFC 7592 §2.2
	// recommended) and the new token is returned in the response; the old
	// token is invalid for any subsequent management request.
	//
	// Out of scope for #169: changing token_endpoint_auth_method (which would
	// require re-keying / new secret). Such requests return
	// ErrInvalidClientMetadata. Clients that need to change auth method
	// DELETE and re-register.
	UpdateRegistration(ctx context.Context, req *UpdateRegistrationRequest) (*UpdateRegistrationResponse, error)

	// DeleteRegistration removes the registration for req.ClientID iff
	// req.AccessToken matches the stored registration_access_token, and
	// invalidates the client's signing credentials so already-issued tokens
	// fail subsequent validation (RFC 7592 §2.3 — "the authorization server
	// MUST invalidate" all tokens for the deleted client). The same uniform
	// ErrUnauthorized envelope as the other methods covers every auth failure.
	//
	// Idempotency is intentional but limited: a second DELETE on the same
	// client_id returns ErrUnauthorized (the registration is gone, so the
	// token check fails at lookup) rather than a special "already deleted"
	// error — preserves the no-enumeration guard.
	DeleteRegistration(ctx context.Context, req *DeleteRegistrationRequest) (*DeleteRegistrationResponse, error)
}

type DCRHandler struct {
	// KeyStore stores client credentials (same KeyStore as AppRegistrar).
	KeyStore keys.KeyStorage

	// Auth authenticates the caller. Supports both:
	//   - Initial access token via Authorization: Bearer header (RFC 7591 §3)
	//   - X-Admin-Key header (OneAuth custom, backward-compatible)
	// If nil, registration is open (not recommended for production).
	Auth AdminAuth

	// Registrar is the underlying AppRegistrar for metadata storage.
	// If nil, client metadata is not persisted (only KeyStore is used).
	Registrar *AppRegistrar

	// IssuerBaseURL is the public base URL used to construct
	// registration_client_uri values returned in DCR responses
	// (e.g. "https://auth.example.com"). When empty, the URI is
	// built from the incoming request's scheme + Host header — fine
	// for tests but unreliable behind proxies, so production
	// deployments should set this explicitly.
	IssuerBaseURL string
}

type DCRManagementHandler struct {
	// Manager is the transport-agnostic core. Required.
	Manager ClientRegistrationManager
}

type DCRRequest struct {
	// ClientID is required for PUT (RFC 7592 §2.2), ignored for register.
	ClientID string `json:"client_id,omitempty"`

	// Client metadata
	ClientName   string   `json:"client_name,omitempty"`
	ClientURI    string   `json:"client_uri,omitempty"`
	RedirectURIs []string `json:"redirect_uris,omitempty"`
	GrantTypes   []string `json:"grant_types,omitempty"`
	Scope        string   `json:"scope,omitempty"`

	// Authentication method
	TokenEndpointAuthMethod string `json:"token_endpoint_auth_method,omitempty"`

	// RFC 9396 — authorization details types this client intends to use
	AuthorizationDetailsTypes []string `json:"authorization_details_types,omitempty"`

	// Keys — for asymmetric auth methods (private_key_jwt)
	JWKS *utils.JWKSet `json:"jwks,omitempty"`

	// OIDC Back-Channel Logout 1.0 §3.1 — clients advertise a logout receiver.
	// Empty disables BCL dispatch for this client.
	BackchannelLogoutURI             string `json:"backchannel_logout_uri,omitempty"`
	BackchannelLogoutSessionRequired bool   `json:"backchannel_logout_session_required,omitempty"`
}

type DCRResponse struct {
	ClientID                  string   `json:"client_id"`
	ClientSecret              string   `json:"client_secret,omitempty"`
	ClientIDIssuedAt          int64    `json:"client_id_issued_at"`
	ClientSecretExpiresAt     int64    `json:"client_secret_expires_at"`
	ClientName                string   `json:"client_name,omitempty"`
	ClientURI                 string   `json:"client_uri,omitempty"`
	RedirectURIs              []string `json:"redirect_uris,omitempty"`
	GrantTypes                []string `json:"grant_types,omitempty"`
	TokenEndpointAuthMethod   string   `json:"token_endpoint_auth_method,omitempty"`
	Scope                     string   `json:"scope,omitempty"`
	AuthorizationDetailsTypes []string `json:"authorization_details_types,omitempty"` // RFC 9396

	// RFC 7592 §3 — management credentials.
	RegistrationAccessToken string `json:"registration_access_token,omitempty"`
	RegistrationClientURI   string `json:"registration_client_uri,omitempty"`

	// OIDC Back-Channel Logout 1.0 §3.1 — echo of the registered receiver
	// metadata so clients can confirm what the AS persisted.
	BackchannelLogoutURI             string `json:"backchannel_logout_uri,omitempty"`
	BackchannelLogoutSessionRequired bool   `json:"backchannel_logout_session_required,omitempty"`
}

type DeleteClientRequest struct {
	ClientID string
}

type DeleteClientResponse struct{}

type DeleteRegistrationRequest struct {
	// ClientID identifies the registration to remove.
	ClientID string

	// AccessToken is the registration_access_token currently on the
	// registration — must match for the deletion to be authorized.
	AccessToken string
}

type DeleteRegistrationResponse struct{}

type GetClientRequest struct {
	ClientID string
}

type GetClientResponse struct {
	Registration *core.AppRegistration
}

type GetRegistrationRequest struct {
	// ClientID identifies the registration to read.
	ClientID string

	// AccessToken is the registration_access_token issued at registration time
	// (RFC 7592 §3). Must match the value stored on the registration.
	AccessToken string
}

type GetRegistrationResponse struct {
	Registration *DCRResponse
}

type ListClientsRequest struct{}

type ListClientsResponse struct {
	Apps []*core.AppRegistration
}

type NoAuth struct{}

type RegisterRequest struct {
	// Metadata is the RFC 7591 §2 client metadata payload. Required.
	Metadata *DCRRequest

	// IssuerBaseURL is the public-facing AS base URL used to construct the
	// registration_client_uri returned in the response (RFC 7592 §3). When
	// empty, callers are expected to substitute a value (e.g., the HTTP
	// wrapper falls back to scheme + r.Host) before invoking the manager.
	IssuerBaseURL string
}

type RegisterResponse struct {
	Registration *DCRResponse
}

type RotateSecretRequest struct {
	ClientID string

	// PublicKey is the new public key in PEM form. Required for
	// asymmetric (RS256 / ES256 / etc.) clients; ignored for symmetric.
	PublicKey string

	// GracePeriod retains the OLD key in KidStore for this duration so
	// in-flight tokens signed with the previous material remain verifiable.
	// When zero, AppRegistrar.DefaultGracePeriod is used (default 24h).
	// Has no effect when KidStore is nil.
	GracePeriod time.Duration
}

type RotateSecretResponse struct {
	ClientID     string
	ClientSecret string        // present only for symmetric algs
	Kid          string        // computed from the new key material
	PreviousKid  string        // only when the previous key was retained
	GracePeriod  time.Duration // grace period actually applied
}

type UpdateRegistrationRequest struct {
	// ClientID identifies the registration to update. The wrapper guarantees
	// this matches Metadata.ClientID before invoking the manager.
	ClientID string

	// AccessToken is the registration_access_token issued at registration time
	// (or the rotated value from a previous UpdateRegistration). Must match
	// the value currently stored on the registration.
	AccessToken string

	// Metadata is the RFC 7591 / 7592 client metadata to replace the existing
	// registration with. Treated as a full-replacement payload per
	// RFC 7592 §2.2 — fields omitted from Metadata are cleared on the server.
	Metadata *DCRRequest
}

type UpdateRegistrationResponse struct {
	Registration *DCRResponse
}