auth

type APIKeyConfig struct {
	// HeaderName is the request header carrying the key (default: X-Api-Key).
	HeaderName string
	// Keys is the legacy inline key map. Raw keys are hashed at construction.
	Keys map[string]APIKeyEntry
	// Store is an optional persisted, hashed key store. When set it is used
	// instead of Keys.
	Store KeyStore
	// SkipPaths bypass authentication entirely.
	SkipPaths []string

	// Quotas, when set, enforces per-key and per-tenant quotas on each request.
	Quotas QuotaStore
	// TenantQuotas maps a tenant ID to its quota, enforced when Quotas is set.
	TenantQuotas map[string]Quota
}

type APIKeyEntry struct {
	Scope    string
	UserID   string
	TenantID string
	Quota    Quota
}

type Audience []string

type JWTConfig struct {
	// Secret is the shared HMAC secret for HS256 tokens. Required to accept
	// HS256 tokens; leave empty to reject them.
	Secret string
	// Issuer, when set, is enforced against the token "iss" claim.
	Issuer string
	// Audience, when set, is enforced against the token "aud" claim.
	Audience string
	// SkipPaths are request paths that bypass authentication entirely.
	SkipPaths []string

	// AllowExpiredAt is the grace window during which an already-expired token
	// is still accepted, but ONLY on paths listed in AllowExpiredPaths (i.e.
	// explicit token-refresh endpoints). It has no effect elsewhere.
	AllowExpiredAt time.Duration
	// AllowExpiredPaths enumerates the refresh-flow paths on which
	// AllowExpiredAt applies.
	AllowExpiredPaths []string

	// RSAPublicKey is a static RSA public key for verifying RS256/384/512
	// tokens without JWKS. Mutually usable with JWKSURL (JWKS takes precedence
	// when a matching kid is found).
	RSAPublicKey *rsa.PublicKey
	// JWKSURL is an OIDC/JWKS endpoint. Keys are fetched, cached by "kid", and
	// re-fetched on cache miss (rotation) or expiry.
	JWKSURL string
	// JWKSCacheTTL bounds how long JWKS entries are cached before a refresh.
	// Defaults to defaultJWKSCacheTTL when zero.
	JWKSCacheTTL time.Duration
	// HTTPClient is used for JWKS fetches; defaults to a client with a short
	// timeout when nil.
	HTTPClient *http.Client

	// AllowNoExpiry permits tokens that omit the "exp" claim. It defaults to
	// false: a token with no expiry is rejected, so a signed token can never
	// become a permanent, unrevocable credential. Set true only for trusted
	// issuers that deliberately mint non-expiring service tokens.
	AllowNoExpiry bool
	// contains filtered or unexported fields
}

type KeyRecord struct {
	// ID is a stable, non-secret identifier/label for the key.
	ID string `json:"id"`
	// Hash is the hex-encoded SHA-256 of the raw key.
	Hash string `json:"hash"`
	// Scope is the RBAC scope/role granted to callers using this key.
	Scope string `json:"scope"`
	// UserID identifies the principal the key acts as.
	UserID string `json:"user_id"`
	// TenantID identifies the tenant for per-tenant quota accounting.
	TenantID string `json:"tenant_id,omitempty"`
	// Quota, when non-zero, is enforced per key on each request.
	Quota Quota `json:"quota,omitempty"`
	// Disabled revokes the key without deleting its record.
	Disabled bool `json:"disabled,omitempty"`
	// CreatedAt records when the key was added.
	CreatedAt time.Time `json:"created_at"`
}

type KeyStore interface {
	// Lookup resolves the raw key to its record using constant-time comparison.
	// It returns (record, true, nil) on match, (nil, false, nil) when no active
	// key matches, and a non-nil error only on backend failure.
	Lookup(ctx context.Context, rawKey string) (*KeyRecord, bool, error)
	// Add hashes rawKey and stores the record; the returned record has Hash and
	// CreatedAt populated. The raw key is not retained.
	Add(ctx context.Context, rawKey string, meta KeyRecord) (KeyRecord, error)
	// Remove deletes the record with the given ID.
	Remove(ctx context.Context, id string) error
	// List returns all stored records (without raw keys).
	List(ctx context.Context) ([]KeyRecord, error)
}

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

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

type Quota struct {
	// RequestsPerMinute caps requests within a rolling one-minute window.
	// Enforced by APIKeyMiddleware.
	RequestsPerMinute int `json:"requests_per_minute,omitempty"`
	// TokensPerDay caps model tokens within a rolling 24h window. Enforced only
	// once AddUsage is wired by the integrator (see the type doc).
	TokensPerDay int64 `json:"tokens_per_day,omitempty"`
	// MaxCostUSD caps cumulative spend (USD) within a rolling 24h window.
	// Enforced only once AddUsage is wired by the integrator (see the type doc).
	MaxCostUSD float64 `json:"max_cost_usd,omitempty"`
}

type QuotaStore interface {
	// Allow records one request against subject and reports whether it is within
	// the given quota (rate + budget). A subject over any limit returns false.
	Allow(ctx context.Context, subject string, q Quota) (bool, error)
	// AddUsage records token and cost consumption for a subject.
	AddUsage(ctx context.Context, subject string, tokens int64, costUSD float64) error
	// Usage returns the current usage snapshot for a subject.
	Usage(ctx context.Context, subject string) (Usage, error)
}

type Role string

type Service struct{}

type Usage struct {
	Requests int     `json:"requests"`
	Tokens   int64   `json:"tokens"`
	CostUSD  float64 `json:"cost_usd"`
}

type UserClaims struct {
	UserID   string   `json:"user_id,omitempty"`
	Roles    []string `json:"roles,omitempty"`
	Exp      int64    `json:"exp,omitempty"`
	Issuer   string   `json:"iss,omitempty"`
	Audience Audience `json:"aud,omitempty"`
	Subject  string   `json:"sub,omitempty"`
	TenantID string   `json:"tenant_id,omitempty"`
}