apikeys

type APIKey struct {
	ID             string            `json:"id"`
	Name           string            `json:"name"`
	Prefix         string            `json:"prefix"`
	KeyHash        string            `json:"key_hash"`
	UserID         string            `json:"user_id,omitempty"`
	OrganizationID string            `json:"organization_id,omitempty"`
	ServiceID      string            `json:"service_id,omitempty"`
	Scopes         []string          `json:"scopes,omitempty"`
	Permissions    []string          `json:"permissions,omitempty"`
	Metadata       map[string]string `json:"metadata,omitempty"`
	ExpiresAt      *time.Time        `json:"expires_at,omitempty"`
	RevokedAt      *time.Time        `json:"revoked_at,omitempty"`
	LastUsedAt     *time.Time        `json:"last_used_at,omitempty"`
	LastUsedIP     string            `json:"last_used_ip,omitempty"`
	LastUsedUA     string            `json:"last_used_ua,omitempty"`
	CreatedAt      time.Time         `json:"created_at"`
	UpdatedAt      time.Time         `json:"updated_at"`
}

type APIKeys interface {
	// Create generates and stores a new API key, returning the plaintext key once.
	Create(ctx context.Context, in CreateInput) (*CreateResult, error)

	// Get retrieves an API key by its unique ID.
	Get(ctx context.Context, id string) (*APIKey, error)

	// List queries API keys based on ownership filters.
	List(ctx context.Context, filter ListFilter) ([]*APIKey, error)

	// Revoke immediately revokes an API key and purges it from any cache.
	Revoke(ctx context.Context, id string) error

	// Rotate replaces an existing key with a newly generated key, optionally preserving
	// the old key during a grace period.
	Rotate(ctx context.Context, id string, opts ...RotateOption) (*RotateResult, error)

	// Authenticate validates a raw API key, checks expiration and scopes,
	// updates last-used telemetry, and resolves to an auth.Principal.
	Authenticate(ctx context.Context, rawKey string, opts ...AuthOption) (*AuthResult, error)

	// Delete permanently deletes an API key record and invalidates cache entries.
	Delete(ctx context.Context, id string) error

	// PurgeExpired deletes expired and revoked keys from persistence.
	PurgeExpired(ctx context.Context) (int, error)

	// Hooks provides access to the API key workflow lifecycle hooks.
	Hooks() *Hooks
}

type AuthOption func(*authConfig)

type AuthResult struct {
	Principal auth.Principal
	Key       *APIKey
}

type AuthenticatedPayload struct {
	ID             string `json:"id"`
	Prefix         string `json:"prefix"`
	UserID         string `json:"user_id,omitempty"`
	OrganizationID string `json:"organization_id,omitempty"`
	ServiceID      string `json:"service_id,omitempty"`
	IPAddress      string `json:"ip_address,omitempty"`
	UserAgent      string `json:"user_agent,omitempty"`
	PrincipalType  string `json:"principal_type"`
	Subject        string `json:"subject"`
}

type Config struct {
	// KeyPrefix is the default prefix prepended to issued API keys (defaults to "gma_").
	KeyPrefix string

	// DefaultExpiresIn sets a default expiration duration if none is specified at creation.
	DefaultExpiresIn time.Duration

	// CacheTTL defines how long active keys are retained in cache (defaults to 5m).
	CacheTTL time.Duration

	// MaxFailedAttempts specifies the maximum failed verification attempts before throttling.
	MaxFailedAttempts int

	// BruteForceWindow is the evaluation window for failed verification attempts.
	BruteForceWindow time.Duration

	// SubjectStrategy controls how auth.Principal.Subject is populated.
	SubjectStrategy SubjectStrategy

	// TouchLastUsedThreshold prevents database write amplification by updating LastUsedAt
	// only if the key was last used longer ago than this threshold (defaults to 1m).
	TouchLastUsedThreshold time.Duration
}

type CreateInput struct {
	Name           string
	UserID         string
	OrganizationID string
	ServiceID      string
	Scopes         []string
	Permissions    []string
	Metadata       map[string]string
	ExpiresAt      *time.Time
	ExpiresIn      time.Duration
	Prefix         string
}

type CreateResult struct {
	Key    *APIKey
	RawKey string
}

type CreatedPayload struct {
	ID             string     `json:"id"`
	Name           string     `json:"name"`
	Prefix         string     `json:"prefix"`
	UserID         string     `json:"user_id,omitempty"`
	OrganizationID string     `json:"organization_id,omitempty"`
	ServiceID      string     `json:"service_id,omitempty"`
	Scopes         []string   `json:"scopes,omitempty"`
	Permissions    []string   `json:"permissions,omitempty"`
	ExpiresAt      *time.Time `json:"expires_at,omitempty"`
}

type DeletedPayload struct {
	ID             string `json:"id"`
	Prefix         string `json:"prefix"`
	UserID         string `json:"user_id,omitempty"`
	OrganizationID string `json:"organization_id,omitempty"`
	ServiceID      string `json:"service_id,omitempty"`
}

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

type ListFilter struct {
	UserID         string
	OrganizationID string
	ServiceID      string
	IncludeRevoked bool
	Limit          int
	Offset         int
}

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

type Option func(*Config)

type RevokedPayload struct {
	ID             string    `json:"id"`
	Prefix         string    `json:"prefix"`
	UserID         string    `json:"user_id,omitempty"`
	OrganizationID string    `json:"organization_id,omitempty"`
	ServiceID      string    `json:"service_id,omitempty"`
	RevokedAt      time.Time `json:"revoked_at"`
}

type RotateOption func(*rotateConfig)

type RotateResult struct {
	NewKey *APIKey
	RawKey string
	OldKey *APIKey
}

type RotatedPayload struct {
	OldKeyID       string     `json:"old_key_id"`
	NewKeyID       string     `json:"new_key_id"`
	Prefix         string     `json:"prefix"`
	UserID         string     `json:"user_id,omitempty"`
	OrganizationID string     `json:"organization_id,omitempty"`
	ServiceID      string     `json:"service_id,omitempty"`
	GracePeriod    *time.Time `json:"grace_period_expires_at,omitempty"`
}

type SubjectStrategy string