middleware

type AuthContext struct {
	TokenID            string
	Token              *signet.Token
	Purpose            string
	IssuerID           string
	MasterKeyHash      []byte
	EphemeralPublicKey crypto.PublicKey
	VerifiedAt         time.Time
}

type Config struct {
	// Core configuration
	ClockSkew         time.Duration
	TokenStore        TokenStore
	NonceStore        NonceStore
	KeyProvider       KeyProvider
	ErrorHandler      ErrorHandler
	RequestBuilder    RequestBuilder
	RevocationChecker revocation.Checker

	// Observability
	Logger   Logger
	Metrics  Metrics
	Observer ObserverHook // Context-based monitoring hook

	// Security settings
	MaxRequestSize int64 // Maximum request body size (0 = use default 1MB)

	// Advanced options
	SkipPaths        []string
	RequiredPurposes []string
}

type ErrorHandler func(w http.ResponseWriter, r *http.Request, err error)

type KeyProvider interface {
	// GetMasterKey retrieves the master public key for an issuer.
	// Returns ErrKeyNotFound if the key doesn't exist.
	GetMasterKey(ctx context.Context, issuerID string) (crypto.PublicKey, error)

	// RefreshKeys updates the key cache (optional).
	RefreshKeys(ctx context.Context) error
}

type Logger interface {
	Debug(msg string, args ...interface{})
	Info(msg string, args ...interface{})
	Warn(msg string, args ...interface{})
	Error(msg string, args ...interface{})
}

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

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

type Metrics interface {
	// RecordAuthResult records the result of an authentication attempt.
	RecordAuthResult(result string, duration time.Duration)

	// RecordTokenUsage records token usage statistics.
	RecordTokenUsage(tokenID string, purpose string)
}

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

type NetworkSettings struct {
	// ChunkedTransferTimeout limits the total time for reading chunked request bodies.
	// This prevents DoS attacks via slow-drip chunked transfers that bypass
	// Content-Length checks. Set to 0 to disable timeout.
	//
	// Background (Issue #28 enhancement):
	//   - Current DoS fix only validates Content-Length header
	//   - Chunked transfers don't have Content-Length
	//   - Attacker can send infinite chunks slowly to exhaust connections
	//   - This timeout closes the connection if chunks take too long
	//
	// Default: 30 seconds
	// Environment variable: SIGNET_CHUNKED_TIMEOUT
	//
	// Future Implementation (tracked in issue #23):
	//   - Add io.ReadCloser wrapper with deadline
	//   - Monitor total read time, not individual chunk time
	//   - Emit metrics on timeout events
	ChunkedTransferTimeout time.Duration `yaml:"chunked_timeout" toml:"chunked_timeout" env:"SIGNET_CHUNKED_TIMEOUT" default:"30s"`

	// ReadHeaderTimeout limits time to read request headers.
	// Default: 10 seconds
	// Environment variable: SIGNET_READ_HEADER_TIMEOUT
	ReadHeaderTimeout time.Duration `yaml:"read_header_timeout" toml:"read_header_timeout" env:"SIGNET_READ_HEADER_TIMEOUT" default:"10s"`

	// WriteTimeout limits time to write response.
	// Default: 30 seconds
	// Environment variable: SIGNET_WRITE_TIMEOUT
	WriteTimeout time.Duration `yaml:"write_timeout" toml:"write_timeout" env:"SIGNET_WRITE_TIMEOUT" default:"30s"`

	// IdleTimeout limits time for keep-alive connections.
	// Default: 90 seconds
	// Environment variable: SIGNET_IDLE_TIMEOUT
	IdleTimeout time.Duration `yaml:"idle_timeout" toml:"idle_timeout" env:"SIGNET_IDLE_TIMEOUT" default:"90s"`
}

type NoOpMetrics = noOpMetrics

type NonceStore interface {
	// CheckAndStore atomically checks if a nonce exists and stores it if not.
	// Returns ErrReplayDetected if the nonce was already used.
	// The expiry parameter hints when the nonce can be safely removed.
	CheckAndStore(ctx context.Context, nonceKey string, expiry int64) error

	// Cleanup removes expired nonces (optional, for maintenance).
	Cleanup(ctx context.Context) error
}

type ObservabilitySettings struct {
	// MetricsEnabled determines whether to emit Prometheus/StatsD metrics.
	// Default: true
	// Environment variable: SIGNET_METRICS_ENABLED
	MetricsEnabled bool `yaml:"metrics_enabled" toml:"metrics_enabled" env:"SIGNET_METRICS_ENABLED" default:"true"`

	// LogLevel controls logging verbosity.
	// Options: "debug", "info", "warn", "error"
	// Default: "info"
	// Environment variable: SIGNET_LOG_LEVEL
	LogLevel string `yaml:"log_level" toml:"log_level" env:"SIGNET_LOG_LEVEL" default:"info"`

	// TracingEnabled determines whether to emit distributed tracing spans.
	// Default: false
	// Environment variable: SIGNET_TRACING_ENABLED
	TracingEnabled bool `yaml:"tracing_enabled" toml:"tracing_enabled" env:"SIGNET_TRACING_ENABLED" default:"false"`

	// TracingProvider specifies the tracing backend.
	// Options: "opentelemetry", "jaeger", "zipkin"
	// Default: "opentelemetry"
	// Environment variable: SIGNET_TRACING_PROVIDER
	TracingProvider string `yaml:"tracing_provider" toml:"tracing_provider" env:"SIGNET_TRACING_PROVIDER" default:"opentelemetry"`
}

type ObserverHook interface {
	// OnAuthStart is called before authentication begins.
	// Returns a new context (possibly with trace IDs, span IDs, etc.)
	OnAuthStart(ctx context.Context, r *http.Request) context.Context

	// OnAuthSuccess is called after successful authentication.
	// Can emit metrics, log events, close spans, etc.
	OnAuthSuccess(ctx context.Context, authCtx *AuthContext)

	// OnAuthFailure is called after authentication failure.
	// Can emit metrics, log errors, close spans, etc.
	OnAuthFailure(ctx context.Context, err error, stage string)
}

type Option func(*Config)

type RequestBuilder interface {
	// Build creates the canonical request bytes that were signed.
	Build(r *http.Request, proof *header.SignetProof) ([]byte, error)
}

type SecuritySettings struct {
	// MaxRequestSize limits request body size to prevent DoS attacks.
	// Default: 1MB (1048576 bytes)
	// Environment variable: SIGNET_MAX_REQUEST_SIZE
	MaxRequestSize int64 `yaml:"max_request_size" toml:"max_request_size" env:"SIGNET_MAX_REQUEST_SIZE" default:"1048576"`

	// ClockSkew is the maximum allowed time difference between client and server.
	// Default: 30 seconds
	// Environment variable: SIGNET_CLOCK_SKEW
	ClockSkew time.Duration `yaml:"clock_skew" toml:"clock_skew" env:"SIGNET_CLOCK_SKEW" default:"30s"`

	// MaxTokensPerUser limits tokens per user to prevent resource exhaustion.
	// Default: 100
	// Environment variable: SIGNET_MAX_TOKENS_PER_USER
	MaxTokensPerUser int `yaml:"max_tokens_per_user" toml:"max_tokens_per_user" env:"SIGNET_MAX_TOKENS_PER_USER" default:"100"`
}

type Settings struct {
	// Security settings
	Security SecuritySettings

	// Storage settings
	Storage StorageSettings

	// Observability settings
	Observability ObservabilitySettings

	// Network settings
	Network NetworkSettings
}

type StorageSettings struct {
	// TokenStoreType specifies the token storage backend.
	// Options: "memory", "redis", "postgres", "dynamodb"
	// Default: "memory"
	// Environment variable: SIGNET_TOKEN_STORE
	TokenStoreType string `yaml:"token_store" toml:"token_store" env:"SIGNET_TOKEN_STORE" default:"memory"`

	// NonceStoreType specifies the nonce storage backend.
	// Options: "memory", "redis"
	// Default: "memory"
	// Environment variable: SIGNET_NONCE_STORE
	NonceStoreType string `yaml:"nonce_store" toml:"nonce_store" env:"SIGNET_NONCE_STORE" default:"memory"`

	// CleanupInterval determines how often expired tokens/nonces are removed.
	// Default: 5 minutes
	// Environment variable: SIGNET_CLEANUP_INTERVAL
	CleanupInterval time.Duration `yaml:"cleanup_interval" toml:"cleanup_interval" env:"SIGNET_CLEANUP_INTERVAL" default:"5m"`

	// RedisURL is the connection string for Redis storage backends.
	// Example: "redis://localhost:6379/0"
	// Environment variable: SIGNET_REDIS_URL
	RedisURL string `yaml:"redis_url" toml:"redis_url" env:"SIGNET_REDIS_URL"`

	// PostgresURL is the connection string for PostgreSQL storage.
	// Example: "postgres://user:pass@localhost/signet?sslmode=require"
	// Environment variable: SIGNET_POSTGRES_URL
	PostgresURL string `yaml:"postgres_url" toml:"postgres_url" env:"SIGNET_POSTGRES_URL"`
}

type TokenRecord struct {
	Token              *signet.Token
	MasterPublicKey    crypto.PublicKey
	EphemeralPublicKey crypto.PublicKey
	BindingSignature   []byte
	IssuedAt           time.Time
	Purpose            string
	Metadata           map[string]string // Optional metadata for extensions
}

type TokenStore interface {
	// Get retrieves a token record by its ID.
	// The tokenID parameter must be a 32-character hex string from hex.EncodeToString(JTI).
	// Returns ErrTokenNotFound if the token doesn't exist.
	Get(ctx context.Context, tokenID string) (*TokenRecord, error)

	// Store saves a token record and returns its ID.
	// The returned tokenID will be a 32-character hex string from hex.EncodeToString(token.JTI).
	Store(ctx context.Context, record *TokenRecord) (string, error)

	// Delete removes a token record (optional, for revocation).
	Delete(ctx context.Context, tokenID string) error

	// Cleanup removes expired tokens (optional, for maintenance).
	// Implementations may handle this automatically.
	Cleanup(ctx context.Context) error
}