domain

type AuditLog struct {
	ID         uuid.UUID
	RequestID  uuid.UUID
	ClientID   uuid.UUID
	Capability Capability
	Path       string
	Metadata   map[string]any
	Signature  []byte     // HMAC-SHA256 signature (32 bytes) for tamper detection
	KekID      *uuid.UUID // KEK used for signing (NULL for legacy unsigned logs)
	IsSigned   bool       // True if signed, false for legacy logs
	CreatedAt  time.Time
}

type AuditLogRepository interface {
	// Create stores a new audit log entry recording an authorization decision.
	// Returns error if the audit log ID already exists or database operation fails.
	Create(ctx context.Context, auditLog *AuditLog) error

	// Get retrieves a single audit log by ID. Returns error if not found.
	// Used for signature verification of specific audit logs.
	Get(ctx context.Context, id uuid.UUID) (*AuditLog, error)

	// ListCursor retrieves audit logs ordered by created_at descending (newest first) with cursor-based pagination
	// and optional time-based filtering. If afterID is provided, returns logs with ID greater than afterID (UUIDv7 ordering).
	// Accepts createdAtFrom and createdAtTo as optional filters (nil means no filter). Both boundaries are inclusive (>= and <=).
	// Accepts clientID as an optional filter (nil means no filter).
	// All timestamps are expected in UTC. Returns empty slice if no audit logs found. Limit is pre-validated (1-1000).
	ListCursor(
		ctx context.Context,
		afterID *uuid.UUID,
		limit int,
		createdAtFrom, createdAtTo *time.Time,
		clientID *uuid.UUID,
	) ([]*AuditLog, error)

	// DeleteOlderThan removes audit logs with created_at before the specified timestamp.
	// When dryRun is true, returns count via SELECT COUNT(*) without deletion. When false,
	// executes DELETE and returns affected rows. Supports transaction-aware operations via
	// context propagation. All timestamps are expected in UTC.
	DeleteOlderThan(ctx context.Context, olderThan time.Time, dryRun bool) (int64, error)
}

type Capability string

type Client struct {
	ID             uuid.UUID        // Unique identifier (UUIDv7)
	Secret         string           //nolint:gosec // hashed client secret (not plaintext)
	Name           string           // Human-readable client name
	IsActive       bool             // Whether the client can authenticate
	Policies       []PolicyDocument // Authorization policies for this client
	FailedAttempts int              // Number of consecutive failed authentication attempts
	LockedUntil    *time.Time       // Time until which the client is locked (nil if not locked)
	CreatedAt      time.Time
}

type ClientRepository interface {
	// Create stores a new client in the repository.
	Create(ctx context.Context, client *Client) error

	// Update modifies an existing client in the repository.
	Update(ctx context.Context, client *Client) error

	// Get retrieves a client by ID. Returns ErrClientNotFound if not found.
	Get(ctx context.Context, clientID uuid.UUID) (*Client, error)

	// ListCursor retrieves clients ordered by ID descending (newest first) with cursor-based pagination.
	// If afterID is provided, returns clients with ID less than afterID (DESC order).
	// Returns empty slice if no clients found. Limit is pre-validated (1-1000).
	ListCursor(ctx context.Context, afterID *uuid.UUID, limit int) ([]*Client, error)

	// UpdateLockState atomically updates the failed attempt counter and lock expiry.
	// Pass failedAttempts=0 and lockedUntil=nil to reset the lock on successful auth.
	UpdateLockState(ctx context.Context, clientID uuid.UUID, failedAttempts int, lockedUntil *time.Time) error
}

type CreateClientInput struct {
	Name     string           // Human-readable name for identifying the client
	IsActive bool             // Whether the client can authenticate immediately after creation
	Policies []PolicyDocument // Authorization policies defining resource access permissions
}

type CreateClientOutput struct {
	ID          uuid.UUID        // Unique identifier for the created client (UUIDv7)
	PlainSecret string           // Plain text secret for authentication (transmit securely, never log)
	Name        string           // Human-readable client name
	IsActive    bool             // Whether the client can authenticate
	Policies    []PolicyDocument // Authorization policies for this client
	CreatedAt   time.Time        // Creation timestamp
}

type Decision int

type IssueTokenInput struct {
	ClientID     uuid.UUID
	ClientSecret string //nolint:gosec // authentication credential field
}

type IssueTokenOutput struct {
	PlainToken string
	ExpiresAt  time.Time
}

type LockoutPolicy struct {
	MaxAttempts int
	Duration    time.Duration
}

type LoginOutcome struct {
	Decision       Decision
	FailedAttempts int
	LockedUntil    *time.Time
}

type PolicyDocument struct {
	Path         string       `json:"path"`         // Resource path pattern (supports "*" and "/*" wildcards)
	Capabilities []Capability `json:"capabilities"` // List of allowed operations on the resource
}

type Token struct {
	ID        uuid.UUID  // Unique identifier (UUIDv7)
	TokenHash string     // SHA-256 hash of the token string
	ClientID  uuid.UUID  // ID of the client that owns this token
	ExpiresAt time.Time  // Token expiration timestamp
	RevokedAt *time.Time // Token revocation timestamp (nil if active)
	CreatedAt time.Time
}

type TokenRepository interface {
	// Create stores a new token in the repository.
	Create(ctx context.Context, token *Token) error

	// Update modifies an existing token in the repository.
	Update(ctx context.Context, token *Token) error

	// Get retrieves a token by ID. Returns ErrTokenNotFound if not found.
	Get(ctx context.Context, tokenID uuid.UUID) (*Token, error)

	// GetByTokenHash retrieves a token by its SHA-256 hash value.
	// Returns ErrTokenNotFound if no token matches the hash.
	GetByTokenHash(ctx context.Context, tokenHash string) (*Token, error)

	// RevokeByTokenID marks a specific token as revoked by setting its revoked_at timestamp.
	RevokeByTokenID(ctx context.Context, tokenID uuid.UUID) error

	// RevokeByClientID marks all active tokens for a specific client as revoked.
	RevokeByClientID(ctx context.Context, clientID uuid.UUID) error

	// PurgeExpiredAndRevoked permanently deletes tokens that are either expired or revoked
	// and were created before the specified timestamp. Returns the number of deleted tokens.
	PurgeExpiredAndRevoked(ctx context.Context, olderThan time.Time) (int64, error)
}

type UpdateClientInput struct {
	Name     string           // Updated human-readable name
	IsActive bool             // Updated active status (false prevents authentication)
	Policies []PolicyDocument // Updated authorization policies
}