contract

type Deps struct {
	// Engine is the keysmith engine every handler reads and writes through.
	Engine *keysmith.Engine

	// DefaultTenantID is the tenant a request belongs to when the principal
	// carries no tenant_id claim and the context carries no forge Scope with
	// an org. Under an auth extension that sets the session's org, it only
	// answers for sessions without one. Leaving it empty makes those requests
	// refuse, which is correct: the empty string would match every tenant's
	// rows.
	DefaultTenantID string

	// DefaultAppID labels new rows when the principal carries no app_id
	// claim. It may be empty. Keysmith never filters by app, so a wrong or
	// missing app only mislabels a new row and never widens a read.
	DefaultAppID string

	// Plugins names the hook plugins the host registered. The settings
	// intent lists them, and the key detail uses it to decide whether to
	// link to Warden.
	Plugins []string

	// Logger receives the server-side detail of internal errors. It may be
	// nil, in which case nothing is logged.
	Logger forge.Logger
}

type EnforcementRow struct {
	Field    string `json:"field"`
	Label    string `json:"label"`
	Group    string `json:"group"`
	Enforced bool   `json:"enforced"`
	When     string `json:"when"`
}

type KeySummary struct {
	ID             string   `json:"id"`
	Name           string   `json:"name"`
	Description    string   `json:"description,omitempty"`
	Prefix         string   `json:"prefix"`
	Hint           string   `json:"hint"`
	Environment    string   `json:"environment"`
	State          string   `json:"state"`          // as stored
	EffectiveState string   `json:"effectiveState"` // what the page shows
	ExpiryPending  bool     `json:"expiryPending"`  // expired, not yet marked
	ExpiresSoon    bool     `json:"expiresSoon"`    // active, expires within 7 days
	PolicyID       string   `json:"policyId,omitempty"`
	Scopes         []string `json:"scopes"`
	CreatedBy      string   `json:"createdBy,omitempty"`
	ExpiresAt      string   `json:"expiresAt,omitempty"`
	LastUsedAt     string   `json:"lastUsedAt,omitempty"`
	RotatedAt      string   `json:"rotatedAt,omitempty"`
	RevokedAt      string   `json:"revokedAt,omitempty"`
	CreatedAt      string   `json:"createdAt"`
	UpdatedAt      string   `json:"updatedAt"`
}

type PolicyDetail struct {
	ID                     string   `json:"id"`
	Name                   string   `json:"name"`
	Description            string   `json:"description,omitempty"`
	MaxKeyLifetimeSeconds  *int64   `json:"maxKeyLifetimeSeconds"`
	GraceSeconds           *int64   `json:"graceSeconds"`
	AllowedScopes          []string `json:"allowedScopes"`
	RateLimit              *int64   `json:"rateLimit"`
	RateLimitWindowSeconds *int64   `json:"rateLimitWindowSeconds"`
	BurstLimit             *int64   `json:"burstLimit"`
	AllowedIPs             []string `json:"allowedIps"`
	AllowedOrigins         []string `json:"allowedOrigins"`
	AllowedMethods         []string `json:"allowedMethods"`
	AllowedPaths           []string `json:"allowedPaths"`
	RotationPeriodSeconds  *int64   `json:"rotationPeriodSeconds"`
	DailyQuota             *int64   `json:"dailyQuota"`
	MonthlyQuota           *int64   `json:"monthlyQuota"`
	CreatedAt              string   `json:"createdAt"`
	UpdatedAt              string   `json:"updatedAt"`
}

type PolicyRef struct {
	ID                    string `json:"id"`
	Name                  string `json:"name"`
	MaxKeyLifetimeSeconds *int64 `json:"maxKeyLifetimeSeconds"`
	GraceSeconds          *int64 `json:"graceSeconds"`
}

type PolicySummary struct {
	ID                    string   `json:"id"`
	Name                  string   `json:"name"`
	Description           string   `json:"description,omitempty"`
	MaxKeyLifetimeSeconds *int64   `json:"maxKeyLifetimeSeconds"`
	GraceSeconds          *int64   `json:"graceSeconds"`
	AllowedScopes         []string `json:"allowedScopes"` // never nil
}

type PreviousKey struct {
	RotationID string `json:"rotationId"`
	Hint       string `json:"hint"`
	Reason     string `json:"reason"`
	RotatedAt  string `json:"rotatedAt"`
	GraceEnds  string `json:"graceEnds"`
}

type RotationItem struct {
	ID    string `json:"id"`
	KeyID string `json:"keyId"`
	// KeyName, Prefix and Environment are null together when the key no
	// longer exists in this tenant.
	KeyName     *string `json:"keyName"`
	Prefix      *string `json:"prefix"`
	Environment *string `json:"environment"`
	// OldHint and NewHint are "" on records written before hints existed.
	OldHint string `json:"oldHint"`
	NewHint string `json:"newHint"`
	Reason  string `json:"reason"`
	// GraceSeconds is the window the rotation recorded. 0 is a real
	// zero-grace rotation, not unset, so it goes out as 0, never null.
	GraceSeconds int64  `json:"graceSeconds"`
	GraceEnds    string `json:"graceEnds"`
	// WindowOpen is true while the previous key can still validate: the key
	// exists in this tenant, is neither expired nor revoked, and is not past
	// its expiry; the record has an old hint; and GraceEnds is ahead of now.
	// A suspended key's window stays open while its expiry is ahead, since
	// it resumes on reactivation.
	WindowOpen bool   `json:"windowOpen"`
	RotatedBy  string `json:"rotatedBy,omitempty"`
	RotatedAt  string `json:"rotatedAt"` // the record's CreatedAt
}

type ScopeSummary struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Parent      string `json:"parent,omitempty"`
	Description string `json:"description,omitempty"`
}

type UsageBucket struct {
	Start        string `json:"start"`        // RFC3339 UTC bucket start
	Requests     int64  `json:"requests"`     // every recorded request
	ClientErrors int64  `json:"clientErrors"` // status 400 to 499
	ServerErrors int64  `json:"serverErrors"` // status 500 and up
	Succeeded    int64  `json:"succeeded"`    // status below 400
	// AvgLatencyMs is the mean latency rounded down, and null for an empty
	// bucket, where there is nothing to average.
	AvgLatencyMs *int64 `json:"avgLatencyMs"`
}

type UsageRecordItem struct {
	ID         string `json:"id"`
	KeyID      string `json:"keyId"`
	Method     string `json:"method"`
	Endpoint   string `json:"endpoint"`
	StatusCode int    `json:"statusCode"`
	LatencyMs  int64  `json:"latencyMs"`
	IPAddress  string `json:"ipAddress,omitempty"`
	At         string `json:"at"`
}