extensions

type AuditEvent struct {
	// EventType categorizes the event for filtering and alerting.
	// Format: "category.action" (e.g., "auth.login", "chat.message")
	EventType string

	// Timestamp is when the event occurred (always use UTC).
	// If zero, implementations should set to time.Now().UTC().
	Timestamp time.Time

	// UserID identifies who performed the action.
	// Use "system" for automated actions, "anonymous" if unknown.
	UserID string

	// Action describes what operation was attempted.
	// Common values: "create", "read", "update", "delete", "send", "receive"
	Action string

	// ResourceType is the category of resource involved.
	// Examples: "message", "session", "evaluation", "model"
	ResourceType string

	// ResourceID is the specific resource instance (optional).
	// Examples: "msg-123", "sess-456", "eval-789"
	ResourceID string

	// Outcome indicates the result of the action.
	// Values: "success", "failure", "blocked", "error"
	Outcome string

	// Metadata holds additional event-specific data.
	// This is where implementation-specific details go.
	//
	// Common metadata keys:
	//   - "error": error message if Outcome is "failure" or "error"
	//   - "ip_address": client IP for security analysis
	//   - "user_agent": client identifier
	//   - "duration_ms": operation duration for performance analysis
	//   - "model": AI model used
	//   - "session_id": conversation session
	//
	// Use NewMetadata() and type-safe accessors:
	//
	//   Metadata: NewMetadata().
	//       Set("session_id", sessionID).
	//       Set("model", "claude-3"),
	Metadata Metadata
}

type AuditFilter struct {
	// EventTypes limits results to specific event types.
	// If empty, all event types are included.
	EventTypes []string

	// UserID limits results to events from a specific user.
	// If empty, events from all users are included.
	UserID string

	// StartTime is the earliest event timestamp to include (inclusive).
	// If zero, no lower bound is applied.
	StartTime time.Time

	// EndTime is the latest event timestamp to include (exclusive).
	// If zero, no upper bound is applied.
	EndTime time.Time

	// ResourceType limits results to events involving specific resource types.
	// If empty, all resource types are included.
	ResourceType string

	// ResourceID limits results to events involving a specific resource.
	// If empty, all resources are included.
	ResourceID string

	// Outcome limits results to events with specific outcomes.
	// If empty, all outcomes are included.
	Outcome string

	// Limit is the maximum number of events to return.
	// If zero, implementation-specific default is used.
	Limit int

	// Offset is the number of events to skip (for pagination).
	Offset int
}

type AuditLogger interface {
	// Log records a security-relevant event.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control
	//   - event: The audit event to record
	//
	// Returns:
	//   - error: nil on success, error if logging failed
	//
	// Implementations should:
	//   1. Set Timestamp if zero
	//   2. Validate required fields (EventType, UserID)
	//   3. Persist or transmit the event
	//   4. Return quickly (use async if needed)
	Log(ctx context.Context, event AuditEvent) error

	// Query retrieves audit events matching the filter criteria.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control
	//   - filter: Criteria for selecting events
	//
	// Returns:
	//   - []AuditEvent: Matching events, ordered by Timestamp descending
	//   - error: nil on success, error if query failed
	//
	// Note: NopAuditLogger returns empty slice (no events stored).
	Query(ctx context.Context, filter AuditFilter) ([]AuditEvent, error)

	// Flush ensures all buffered events are persisted.
	//
	// Call this before application shutdown to prevent event loss.
	// For sync implementations, this may be a no-op.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control
	//
	// Returns:
	//   - error: nil on success, error if flush failed
	Flush(ctx context.Context) error
}

type AuditableRequest struct {
	// Method is the HTTP method (GET, POST, etc.)
	Method string

	// Path is the request path (e.g., "/v1/chat/direct")
	Path string

	// Headers contains the HTTP request headers.
	// Sensitive headers (Authorization) should be redacted by caller.
	Headers HTTPHeaders

	// Body is the raw request body bytes.
	// This is what Enterprise will hash and potentially encrypt.
	Body []byte

	// UserID identifies who made the request.
	// Extracted from AuthInfo by the handler.
	UserID string

	// SessionID is the conversation session identifier (if applicable).
	SessionID string

	// RequestID is the unique identifier for this request.
	RequestID string

	// Timestamp is when the request was received (always UTC).
	Timestamp time.Time
}

type AuditableResponse struct {
	// StatusCode is the HTTP response status code.
	StatusCode int

	// Headers contains the HTTP response headers.
	Headers HTTPHeaders

	// Body is the raw response body bytes.
	// For streaming responses, this is all chunks concatenated.
	Body []byte

	// Timestamp is when the response was sent (always UTC).
	Timestamp time.Time
}

type AuthInfo struct {
	// UserID is the unique identifier for the authenticated user.
	// This is the only required field and must never be empty.
	UserID string

	// Email is the user's email address.
	// May be empty if not provided by the auth provider.
	Email string

	// Roles contains the user's role memberships for authorization decisions.
	// Common roles: "admin", "analyst", "viewer", "auditor"
	Roles []string

	// Metadata holds additional claims from the identity provider.
	// Enterprise implementations can store provider-specific data here
	// without requiring changes to the core struct.
	//
	// Common metadata keys:
	//   - "groups": []string of group memberships
	//   - "department": organizational unit
	//   - "mfa_verified": whether MFA was used
	//   - "session_id": identity provider session ID
	//
	// Use NewMetadata() and type-safe accessors:
	//
	//   Metadata: NewMetadata().
	//       Set("department", "engineering").
	//       Set("mfa_verified", true),
	Metadata Metadata
}

type AuthProvider interface {
	// Validate checks if the token is valid and returns the user's identity.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control
	//   - token: The authentication token (JWT, session ID, API key, etc.)
	//
	// Returns:
	//   - *AuthInfo: User identity information if valid
	//   - error: ErrUnauthorized (or wrapped) if invalid, other errors for failures
	//
	// The token format is implementation-specific:
	//   - JWT: "eyJhbGciOiJSUzI1NiIs..."
	//   - API Key: "ak_live_..."
	//   - Session: "sess_..."
	Validate(ctx context.Context, token string) (*AuthInfo, error)
}

type AuthzProvider interface {
	// Authorize checks if the user is permitted to perform the action.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control
	//   - req: The authorization request describing user, action, and resource
	//
	// Returns:
	//   - nil: Action is authorized
	//   - error: ErrUnauthorized (or wrapped) if denied
	Authorize(ctx context.Context, req AuthzRequest) error
}

type AuthzRequest struct {
	// User is the authenticated user making the request.
	// This comes from AuthProvider.Validate().
	User *AuthInfo

	// Action is the operation being attempted.
	// Common actions: "create", "read", "update", "delete", "execute"
	Action string

	// ResourceType is the category of resource being accessed.
	// Examples: "evaluation", "model", "session", "report"
	ResourceType string

	// ResourceID is the specific resource instance (optional).
	// If empty, the check is for the resource type in general.
	// Examples: "eval-123", "model-456"
	ResourceID string
}

type ChainVerificationResult struct {
	// IsValid is true if the entire chain is intact.
	IsValid bool

	// TotalEntries is the number of entries verified.
	TotalEntries int

	// BreakPoint is the sequence number where integrity failed.
	// Only meaningful when IsValid is false.
	// Zero means the chain is valid or empty.
	BreakPoint int

	// ExpectedHash is what the hash should be at BreakPoint.
	ExpectedHash string

	// ActualHash is what the hash actually was at BreakPoint.
	ActualHash string

	// Message provides human-readable verification status.
	Message string
}

type ClassificationFinding struct {
	// Classification is the sensitivity level of this finding.
	Classification DataClassification

	// Type describes what kind of data was found.
	// Examples: "ssn", "credit_card", "email", "api_key", "password"
	Type string

	// Location describes where in the content the data was found.
	// Format is implementation-specific (e.g., "line 5", "offset 100-120").
	Location string

	// Pattern identifies which detection rule matched.
	// Useful for debugging and tuning classification rules.
	// Examples: "ssn_regex", "credit_card_luhn", "api_key_entropy"
	Pattern string

	// Snippet is a truncated/redacted portion of the matched content.
	// Used for audit logs without exposing full sensitive data.
	// Should be safe to log (first/last few characters only).
	Snippet string
}

type ClassificationResult struct {
	// HighestLevel is the most sensitive classification found.
	// Use this for quick policy decisions (e.g., block if SECRET).
	HighestLevel DataClassification

	// Findings lists all detected sensitive data with details.
	// May be empty if nothing sensitive was found (HighestLevel == PUBLIC).
	Findings []ClassificationFinding

	// IsClean is true if no sensitive data was detected.
	// Equivalent to HighestLevel == ClassificationPublic && len(Findings) == 0.
	IsClean bool
}

type DataClassification string

type DataClassifier interface {
	// Classify analyzes content and returns its sensitivity classification.
	//
	// # Description
	//
	// Scans the provided content for patterns indicating sensitive data.
	// Returns the highest classification found along with detailed findings.
	//
	// # Inputs
	//
	//   - ctx: Context for cancellation and timeout control.
	//   - content: The text to classify. May be any length.
	//
	// # Outputs
	//
	//   - *ClassificationResult: Classification details, never nil on success.
	//   - error: Non-nil if classification failed (e.g., timeout, invalid input).
	//
	// # Examples
	//
	//   // Check a user message
	//   result, err := classifier.Classify(ctx, message)
	//   if result.HighestLevel >= ClassificationPII {
	//       // Apply PII handling procedures
	//   }
	//
	// # Limitations
	//
	//   - Large content may be slow to process
	//   - Binary content is not supported
	//
	// # Assumptions
	//
	//   - Content is valid UTF-8 text
	//   - Context deadline is respected for long operations
	//
	// # Thread Safety
	//
	// Safe to call concurrently from multiple goroutines.
	Classify(ctx context.Context, content string) (*ClassificationResult, error)

	// ClassifyBatch analyzes multiple content items efficiently.
	//
	// # Description
	//
	// Classifies multiple content items in a single call. Implementations
	// may process items in parallel for better performance.
	//
	// # Inputs
	//
	//   - ctx: Context for cancellation and timeout control.
	//   - contents: Slice of content items to classify.
	//
	// # Outputs
	//
	//   - []*ClassificationResult: Results in same order as input.
	//   - error: Non-nil if any classification failed.
	//
	// # Examples
	//
	//   contents := []string{message1, message2, message3}
	//   results, err := classifier.ClassifyBatch(ctx, contents)
	//   for i, result := range results {
	//       if !result.IsClean {
	//           log.Warn("sensitive data in item", "index", i)
	//       }
	//   }
	//
	// # Limitations
	//
	//   - If one item fails, the entire batch may fail
	//   - Memory usage scales with batch size
	//
	// # Assumptions
	//
	//   - All content items are valid UTF-8 text
	//   - Batch size is reasonable (implementation may limit)
	//
	// # Thread Safety
	//
	// Safe to call concurrently from multiple goroutines.
	ClassifyBatch(ctx context.Context, contents []string) ([]*ClassificationResult, error)
}

type Detection struct {
	// Type categorizes what was detected.
	// Common types: "ssn", "credit_card", "email", "phone", "api_key",
	// "profanity", "pii", "secret", "prompt_injection"
	Type string

	// Location describes where in the message the item was found.
	// Format is implementation-specific (e.g., "characters 10-20", "line 3")
	Location string

	// Action describes what was done with the detected item.
	// Values: "redacted", "masked", "replaced", "blocked", "flagged"
	Action string

	// Original is the detected content (only populated in debug mode).
	// WARNING: This may contain sensitive data - handle carefully.
	Original string

	// Replacement is what the content was replaced with (if Action is "replaced").
	Replacement string
}

type FilterResult struct {
	// Original is the input message before filtering.
	Original string

	// Filtered is the message after filtering transformations.
	// If WasModified is false, this equals Original.
	Filtered string

	// WasModified indicates if any transformations were applied.
	WasModified bool

	// WasBlocked indicates if the message was completely rejected.
	// If true, Filtered should not be used.
	WasBlocked bool

	// BlockReason explains why the message was blocked (if WasBlocked).
	BlockReason string

	// Detections lists what the filter found in the message.
	// Useful for audit logging and debugging.
	Detections []Detection
}

type HTTPHeaders map[string]string

type HashChainEntry struct {
	// SessionID identifies the chain this entry belongs to.
	// Each session has its own independent hash chain.
	SessionID string

	// SequenceNum is the position in the chain (1-indexed).
	// Used to verify chain completeness and ordering.
	SequenceNum int

	// ContentHash is the hash of the content being recorded.
	// For conversation turns: SHA256(question + answer)
	// For requests: SHA256(request body)
	ContentHash string

	// PreviousHash is the ChainHash of the preceding entry.
	// Empty string for the first entry in a chain (SequenceNum == 1).
	PreviousHash string

	// ChainHash is the cumulative hash incorporating all previous entries.
	// ChainHash = SHA256(PreviousHash + ContentHash)
	// This is the value stored and used for verification.
	ChainHash string

	// Timestamp is when this entry was created (always UTC).
	Timestamp time.Time

	// ContentType describes what kind of content was hashed.
	// Examples: "conversation_turn", "request", "response", "document"
	ContentType string

	// Metadata contains additional context about the entry.
	// May include: user_id, request_id, turn_number, etc.
	//
	// Use NewMetadata() and type-safe accessors:
	//
	//   Metadata: NewMetadata().
	//       Set("user_id", userID).
	//       Set("request_id", requestID),
	Metadata Metadata
}

type MessageFilter interface {
	// FilterInput processes a user message before LLM inference.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control
	//   - message: The raw user input
	//
	// Returns:
	//   - *FilterResult: The filtered message and metadata
	//   - error: Non-nil only for filter failures (not for blocks)
	//
	// If WasBlocked is true, the caller should:
	//  1. Log the block via AuditLogger
	//  2. Return ErrMessageBlocked to the user
	//  3. NOT send the message to the LLM
	FilterInput(ctx context.Context, message string) (*FilterResult, error)

	// FilterOutput processes an LLM response before returning to user.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control
	//   - message: The LLM response
	//
	// Returns:
	//   - *FilterResult: The filtered response and metadata
	//   - error: Non-nil only for filter failures (not for blocks)
	//
	// Common output filtering:
	//   - Remove accidentally leaked API keys
	//   - Add compliance disclaimers
	//   - Mask generated PII
	FilterOutput(ctx context.Context, message string) (*FilterResult, error)

	// FilterContext processes context/system prompts before use.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control
	//   - context: System prompt or context being injected
	//
	// Returns:
	//   - *FilterResult: The filtered context and metadata
	//   - error: Non-nil only for filter failures
	//
	// This is called when injecting retrieved documents (RAG),
	// system prompts, or other context into the conversation.
	FilterContext(ctx context.Context, contextMsg string) (*FilterResult, error)
}

type Metadata map[string]any

type NopAuditLogger struct{}

type NopAuthProvider struct{}

type NopAuthzProvider struct{}

type NopDataClassifier struct{}

type NopMessageFilter struct{}

type NopRequestAuditor struct{}

type RequestAuditor interface {

	// CaptureRequest records the raw request for audit purposes.
	//
	// # Description
	//
	// Called at the START of request processing with the raw request body.
	// Enterprise implementations receive the raw bytes to:
	//   1. Compute content_hash = SHA256(Body)
	//   2. Encrypt the body if required
	//   3. Store to immutable storage (GCS, QLDB, etc.)
	//
	// Returns an auditID that must be passed to CaptureResponse to link them.
	//
	// # Inputs
	//
	//   - ctx: Context for cancellation and timeout control.
	//   - req: Raw request data including body bytes.
	//
	// # Outputs
	//
	//   - string: Audit ID to pass to CaptureResponse. Empty for NopRequestAuditor.
	//   - error: Non-nil if capture failed.
	//
	// # Examples
	//
	//   auditID, err := auditor.CaptureRequest(ctx, &AuditableRequest{
	//       Method:    c.Request.Method,
	//       Path:      c.Request.URL.Path,
	//       Body:      requestBody,
	//       UserID:    authInfo.UserID,
	//       RequestID: req.RequestID,
	//       Timestamp: time.Now().UTC(),
	//   })
	//   if err != nil {
	//       log.Error("audit capture failed", "error", err)
	//   }
	//   // ... process request ...
	//   auditor.CaptureResponse(ctx, auditID, responseData)
	//
	// # Limitations
	//
	//   - Caller must preserve auditID to call CaptureResponse.
	//   - Request body should be read before calling (use io.TeeReader).
	//
	// # Assumptions
	//
	//   - Body contains the complete request payload.
	//   - Sensitive headers are redacted by caller if needed.
	//
	// # Thread Safety
	//
	// Safe to call concurrently.
	CaptureRequest(ctx context.Context, req *AuditableRequest) (auditID string, err error)

	// CaptureResponse records the raw response for audit purposes.
	//
	// # Description
	//
	// Called at the END of request processing with the raw response body.
	// The auditID links this response to its corresponding request.
	// Enterprise implementations receive the raw bytes to hash and store.
	//
	// For streaming endpoints, accumulate all chunks and call this once at the end.
	//
	// # Inputs
	//
	//   - ctx: Context for cancellation and timeout control.
	//   - auditID: The ID returned from CaptureRequest.
	//   - resp: Raw response data including body bytes.
	//
	// # Outputs
	//
	//   - error: Non-nil if capture failed.
	//
	// # Examples
	//
	//   err := auditor.CaptureResponse(ctx, auditID, &AuditableResponse{
	//       StatusCode: 200,
	//       Body:       responseBytes,
	//       Timestamp:  time.Now().UTC(),
	//   })
	//
	// # Limitations
	//
	//   - Must be called with valid auditID from CaptureRequest.
	//   - For streaming, caller must accumulate all chunks.
	//
	// # Assumptions
	//
	//   - Body contains the complete response payload.
	//   - auditID is valid and corresponds to a captured request.
	//
	// # Thread Safety
	//
	// Safe to call concurrently.
	CaptureResponse(ctx context.Context, auditID string, resp *AuditableResponse) error

	// RecordEntry adds a new entry to the hash chain.
	//
	// # Description
	//
	// Persists an audit entry and updates the chain hash. Implementations
	// should verify chain continuity before accepting the entry.
	//
	// # Inputs
	//
	//   - ctx: Context for cancellation and timeout control.
	//   - entry: The hash chain entry to record.
	//
	// # Outputs
	//
	//   - error: Non-nil if recording failed or chain continuity was violated.
	//
	// # Examples
	//
	//   err := auditor.RecordEntry(ctx, HashChainEntry{
	//       SessionID:   "sess-123",
	//       SequenceNum: 1,
	//       ContentHash: "abc...",
	//       ContentType: "conversation_turn",
	//   })
	//
	// # Limitations
	//
	//   - Entry cannot be modified after recording.
	//   - Requires PreviousHash for SequenceNum > 1.
	//
	// # Assumptions
	//
	//   - ContentHash is correctly computed by caller.
	//   - SequenceNum is monotonically increasing per session.
	//
	// # Thread Safety
	//
	// Safe to call concurrently, but entries for the same session
	// should be serialized to maintain chain order.
	RecordEntry(ctx context.Context, entry HashChainEntry) error

	// GetLastEntry retrieves the most recent entry for a session.
	//
	// # Description
	//
	// Returns the last recorded entry, which is needed to compute
	// PreviousHash for the next entry in the chain.
	//
	// # Inputs
	//
	//   - ctx: Context for cancellation and timeout control.
	//   - sessionID: The session to query.
	//
	// # Outputs
	//
	//   - *HashChainEntry: The last entry, or nil if chain is empty.
	//   - error: Non-nil if retrieval failed.
	//
	// # Examples
	//
	//   lastEntry, err := auditor.GetLastEntry(ctx, sessionID)
	//   if lastEntry != nil {
	//       newEntry.PreviousHash = lastEntry.ChainHash
	//       newEntry.SequenceNum = lastEntry.SequenceNum + 1
	//   } else {
	//       newEntry.PreviousHash = ""
	//       newEntry.SequenceNum = 1
	//   }
	//
	// # Limitations
	//
	//   - Returns nil for non-existent sessions (not an error).
	//
	// # Assumptions
	//
	//   - Session IDs are unique across the system.
	//
	// # Thread Safety
	//
	// Safe to call concurrently.
	GetLastEntry(ctx context.Context, sessionID string) (*HashChainEntry, error)

	// VerifyChain validates the integrity of a session's hash chain.
	//
	// # Description
	//
	// Retrieves all entries for a session and verifies that each entry's
	// ChainHash correctly incorporates the previous entry's hash.
	//
	// # Inputs
	//
	//   - ctx: Context for cancellation and timeout control.
	//   - sessionID: The session to verify.
	//
	// # Outputs
	//
	//   - *ChainVerificationResult: Verification outcome with details.
	//   - error: Non-nil if verification could not be performed.
	//
	// # Examples
	//
	//   result, err := auditor.VerifyChain(ctx, sessionID)
	//   if err != nil {
	//       return fmt.Errorf("verification failed: %w", err)
	//   }
	//   if !result.IsValid {
	//       alertSecurityTeam(sessionID, result.BreakPoint)
	//   }
	//
	// # Limitations
	//
	//   - Requires loading all entries (may be slow for long chains).
	//   - Empty chains are considered valid.
	//
	// # Assumptions
	//
	//   - All entries for the session are retrievable.
	//   - Hash algorithm matches what was used during recording.
	//
	// # Thread Safety
	//
	// Safe to call concurrently.
	VerifyChain(ctx context.Context, sessionID string) (*ChainVerificationResult, error)

	// GetChainLength returns the number of entries in a session's chain.
	//
	// # Description
	//
	// Returns the count of recorded entries without loading them all.
	// Useful for quick checks and display purposes.
	//
	// # Inputs
	//
	//   - ctx: Context for cancellation and timeout control.
	//   - sessionID: The session to query.
	//
	// # Outputs
	//
	//   - int: Number of entries (0 for non-existent sessions).
	//   - error: Non-nil if count could not be retrieved.
	//
	// # Examples
	//
	//   count, err := auditor.GetChainLength(ctx, sessionID)
	//   fmt.Printf("Session has %d recorded turns\n", count)
	//
	// # Limitations
	//
	//   - Does not verify chain integrity.
	//
	// # Assumptions
	//
	//   - Count is consistent with actual entries.
	//
	// # Thread Safety
	//
	// Safe to call concurrently.
	GetChainLength(ctx context.Context, sessionID string) (int, error)
}

type ServiceOptions struct {
	// AuthProvider validates authentication tokens.
	// Default: NopAuthProvider (always returns valid local user)
	AuthProvider AuthProvider

	// AuthzProvider checks authorization permissions.
	// Default: NopAuthzProvider (always allows all actions)
	AuthzProvider AuthzProvider

	// AuditLogger records security-relevant events.
	// Default: NopAuditLogger (discards all events)
	AuditLogger AuditLogger

	// MessageFilter transforms messages before/after processing.
	// Default: NopMessageFilter (passes through unchanged)
	MessageFilter MessageFilter

	// DataClassifier determines data sensitivity classification.
	// Default: NopDataClassifier (always returns PUBLIC)
	DataClassifier DataClassifier

	// RequestAuditor provides tamper-evident hash chain logging.
	// Default: NopRequestAuditor (discards entries, always valid)
	RequestAuditor RequestAuditor
}