apikey

type APIKey struct {
	// ID is the unique identifier.
	ID uuid.UUID `json:"id"`

	// Name is a human-readable name.
	Name string `json:"name"`

	// Prefix is the visible portion of the key.
	Prefix string `json:"prefix"`

	// OwnerID is the user who owns this key.
	OwnerID uuid.UUID `json:"owner_id"`

	// OrganizationID is the org this key is scoped to (optional).
	OrganizationID *uuid.UUID `json:"organization_id,omitempty"`

	// Scopes are the permissions granted to this key.
	Scopes []string `json:"scopes,omitempty"`

	// Description is an optional note.
	Description string `json:"description,omitempty"`

	// Environment is live or test.
	Environment Environment `json:"environment"`

	// ExpiresAt is when the key expires.
	ExpiresAt *time.Time `json:"expires_at,omitempty"`

	// LastUsedAt is when the key was last used.
	LastUsedAt *time.Time `json:"last_used_at,omitempty"`

	// LastUsedIP is the IP that last used the key.
	LastUsedIP string `json:"last_used_ip,omitempty"`

	// Revoked indicates if the key is revoked.
	Revoked bool `json:"revoked"`

	// RevokedAt is when the key was revoked.
	RevokedAt *time.Time `json:"revoked_at,omitempty"`

	// RevokedReason is why the key was revoked.
	RevokedReason string `json:"revoked_reason,omitempty"`

	// Metadata is additional key-value data.
	Metadata map[string]string `json:"metadata,omitempty"`

	// CreatedAt is when the key was created.
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt is when the key was last updated.
	UpdatedAt time.Time `json:"updated_at"`
}

type CreateKeyRequest struct {
	// Name is a human-readable name (required).
	Name string

	// OwnerID is the user creating the key (required).
	OwnerID uuid.UUID

	// OrganizationID scopes the key to an organization (optional).
	OrganizationID *uuid.UUID

	// Scopes are the permissions to grant (optional).
	Scopes []string

	// Description is an optional note.
	Description string

	// Environment is live or test (default: live).
	Environment Environment

	// ExpiresIn is the key lifetime (optional, nil = never).
	ExpiresIn *time.Duration

	// Metadata is additional key-value data.
	Metadata map[string]string
}

type EntClientInterface interface {
	// CreateAPIKey stores a new API key.
	CreateAPIKey(ctx context.Context, key *APIKey, keyHash string) error

	// GetAPIKeyByPrefix retrieves a key by its prefix.
	// Returns the key and its hash for validation.
	// Returns ErrKeyNotFound if not found.
	GetAPIKeyByPrefix(ctx context.Context, prefix string) (*APIKey, string, error)

	// GetAPIKeyByID retrieves a key by its ID.
	// Returns ErrKeyNotFound if not found.
	GetAPIKeyByID(ctx context.Context, id uuid.UUID) (*APIKey, error)

	// ListAPIKeysByOwner lists all keys for a user.
	ListAPIKeysByOwner(ctx context.Context, ownerID uuid.UUID) ([]*APIKey, error)

	// ListAPIKeysByOrganization lists all keys for an organization.
	ListAPIKeysByOrganization(ctx context.Context, orgID uuid.UUID) ([]*APIKey, error)

	// UpdateAPIKey updates key metadata.
	UpdateAPIKey(ctx context.Context, key *APIKey) error

	// DeleteAPIKey permanently removes a key.
	DeleteAPIKey(ctx context.Context, id uuid.UUID) error

	// UpdateAPIKeyLastUsed updates the last used timestamp and IP.
	UpdateAPIKeyLastUsed(ctx context.Context, id uuid.UUID, ip string) error
}

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

type EntStoreConfig struct {
	// Client is the Ent client wrapper.
	// Apps must provide a wrapper that implements EntClientInterface.
	Client EntClientInterface
}

type Environment string

type GeneratedKey struct {
	// Key is the full API key value (only shown once).
	Key string `json:"key"`

	// APIKey is the key metadata.
	APIKey *APIKey `json:"api_key"`
}

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

type ServiceConfig struct {
	// Store is the key storage backend.
	Store Store

	// Prefix is the key prefix (default: "sf").
	Prefix string

	// AllowedScopes restricts which scopes can be granted. An entry ending in
	// ":*" allows every scope with that prefix. A key requesting a scope that
	// no entry allows is refused, including the wildcard scope "*" unless an
	// entry lists it exactly.
	//
	// If empty, no scopes can be granted unless AllowAnyScope is set: the
	// service cannot know what the caller is entitled to, so an unconfigured
	// service does not hand out arbitrary privilege.
	AllowedScopes []string

	// AllowAnyScope lets keys request any scope when AllowedScopes is empty.
	// Set it only when the caller of Create has already limited the scopes to
	// what its user may hold.
	AllowAnyScope bool

	// MaxKeysPerUser limits the active (unrevoked, unexpired) keys per user
	// (0 = unlimited). The count and the insert are not one atomic step, so
	// concurrent Create calls for one user can exceed the limit by the number
	// in flight; stores that need a hard cap should enforce it themselves.
	MaxKeysPerUser int

	// DefaultExpiry is the default key lifetime.
	DefaultExpiry *time.Duration
}

type Store interface {
	// Create stores a new API key.
	Create(ctx context.Context, key *APIKey, keyHash string) error

	// GetByPrefix retrieves a key by its prefix.
	GetByPrefix(ctx context.Context, prefix string) (*APIKey, string, error)

	// GetByID retrieves a key by its ID.
	GetByID(ctx context.Context, id uuid.UUID) (*APIKey, error)

	// ListByOwner lists all keys for a user.
	ListByOwner(ctx context.Context, ownerID uuid.UUID) ([]*APIKey, error)

	// ListByOrganization lists all keys for an organization.
	ListByOrganization(ctx context.Context, orgID uuid.UUID) ([]*APIKey, error)

	// Update updates key metadata.
	Update(ctx context.Context, key *APIKey) error

	// Delete permanently removes a key.
	Delete(ctx context.Context, id uuid.UUID) error

	// UpdateLastUsed updates the last used timestamp and IP.
	UpdateLastUsed(ctx context.Context, id uuid.UUID, ip string) error
}