bearer

type AuthResult struct {
	// Principal is the core GoModularAuth authenticated identity.
	Principal auth.Principal `json:"principal"`

	// Token provides the metadata of the authenticated token (excluding secrets).
	Token *TokenInfo `json:"token"`
}

type AuthenticateInput struct {
	// Token is the raw bearer token supplied by the caller/client.
	Token string `json:"token"`

	// RequiredScopes is a list of scopes that MUST be granted by the token.
	// If any required scope is missing, authentication fails with ErrInsufficientScope.
	RequiredScopes []string `json:"required_scopes,omitempty"`
}

type AuthenticatedPayload struct {
	TokenID       string             `json:"token_id"`
	Subject       string             `json:"subject"`
	PrincipalType auth.PrincipalType `json:"principal_type"`
	Time          time.Time          `json:"time"`
}

type Bearer interface {
	// Authenticate validates bearer credentials against persistence (and optional cache),
	// checks expiration, revocation, and scope permissions, and resolves the credentials into a Principal.
	Authenticate(ctx context.Context, in AuthenticateInput) (*AuthResult, error)

	// Issue generates and stores a new cryptographically secure opaque bearer token for the specified subject.
	// The plaintext token is returned strictly once in IssueResult and is never stored in plaintext.
	Issue(ctx context.Context, in IssueInput) (*IssueResult, error)

	// Revoke revokes an individual token by its record ID, immediately invalidating subsequent authentication attempts.
	Revoke(ctx context.Context, tokenID string) error

	// RevokeBySubject revokes all active bearer tokens belonging to the specified subject (e.g., on logout or account compromise).
	RevokeBySubject(ctx context.Context, subject string) error

	// Get retrieves public metadata for a token by its ID.
	// Returns ErrTokenNotFound if not found. Plaintext tokens and hashes are never exposed.
	Get(ctx context.Context, tokenID string) (*TokenInfo, error)

	// ListBySubject retrieves metadata for all tokens belonging to the specified subject.
	ListBySubject(ctx context.Context, subject string) ([]*TokenInfo, error)

	// Delete permanently removes a token record by its ID from persistence and invalidates cache.
	Delete(ctx context.Context, tokenID string) error

	// PurgeExpired removes all expired or revoked tokens from persistence.
	PurgeExpired(ctx context.Context) (int, error)
}

type Config struct {
	// DefaultTTL specifies the default expiration duration for newly issued tokens.
	DefaultTTL time.Duration

	// CacheTTL specifies the maximum time-to-live for cached token records.
	CacheTTL time.Duration

	// TokenPrefix is prepended to generated tokens (e.g. "gmb_").
	TokenPrefix string

	// Hooks provides lifecycle interceptors for bearer operations.
	Hooks *Hooks
}

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

type IssueInput struct {
	// Subject identifies the owner/principal of the token (required).
	Subject string `json:"subject"`

	// PrincipalType classifies the identity (optional; defaults to auth.PrincipalUser).
	PrincipalType auth.PrincipalType `json:"principal_type,omitempty"`

	// Scopes defines the authorization permissions granted to this token (optional).
	Scopes []string `json:"scopes,omitempty"`

	// TTL specifies the token lifespan. If zero or negative, Config.DefaultTTL is used.
	TTL time.Duration `json:"ttl,omitempty"`

	// Metadata attaches custom key-value attributes (optional).
	Metadata map[string]string `json:"metadata,omitempty"`
}

type IssueResult struct {
	// Token is the raw, opaque secret bearer token to provide to the client.
	Token string `json:"token"`

	// Info contains the persisted non-sensitive token metadata.
	Info *TokenInfo `json:"info"`
}

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

type Option func(*Config)

type TokenExpiredPayload struct {
	TokenID   string    `json:"token_id"`
	Subject   string    `json:"subject"`
	ExpiresAt time.Time `json:"expires_at"`
	Time      time.Time `json:"time"`
}

type TokenInfo struct {
	// ID is the unique random identifier for this token record.
	ID string `json:"id"`

	// Subject represents the authenticated identity (e.g. User ID, Service Account ID).
	Subject string `json:"subject"`

	// PrincipalType classifies the identity type (e.g. auth.PrincipalUser, auth.PrincipalServiceAccount).
	PrincipalType auth.PrincipalType `json:"principal_type"`

	// Scopes lists the authorization scopes granted to this token.
	Scopes []string `json:"scopes"`

	// Metadata holds arbitrary key-value application properties attached to the token.
	Metadata map[string]string `json:"metadata,omitempty"`

	// ExpiresAt is the timestamp at which this token becomes invalid.
	ExpiresAt time.Time `json:"expires_at"`

	// RevokedAt is the timestamp when this token was revoked, or nil if active.
	RevokedAt *time.Time `json:"revoked_at,omitempty"`

	// CreatedAt is the timestamp when the token was issued.
	CreatedAt time.Time `json:"created_at"`
}

type TokenIssuedPayload struct {
	TokenID       string             `json:"token_id"`
	Subject       string             `json:"subject"`
	PrincipalType auth.PrincipalType `json:"principal_type"`
	Scopes        []string           `json:"scopes"`
	ExpiresAt     time.Time          `json:"expires_at"`
	CreatedAt     time.Time          `json:"created_at"`
}

type TokenRecord struct {
	ID            string            `json:"id"`
	TokenHash     string            `json:"token_hash"`
	Subject       string            `json:"subject"`
	PrincipalType string            `json:"principal_type"`
	Scopes        []string          `json:"scopes"`
	Metadata      map[string]string `json:"metadata,omitempty"`
	ExpiresAt     time.Time         `json:"expires_at"`
	RevokedAt     *time.Time        `json:"revoked_at,omitempty"`
	CreatedAt     time.Time         `json:"created_at"`
	UpdatedAt     time.Time         `json:"updated_at"`
}

type TokenRevokedPayload struct {
	TokenID   string    `json:"token_id,omitempty"`
	Subject   string    `json:"subject"`
	RevokedAt time.Time `json:"revoked_at"`
}

type TransportAuthenticator interface {
	// Authenticate validates the transport-neutral input and resolves the Principal.
	Authenticate(ctx context.Context, in AuthenticateInput) (*AuthResult, error)
}