# Psyche Security

Comprehensive security and privacy framework for the Psyche AI Virtual Assistant
Platform.

Part of the Oshun Platform.

## Overview

This library provides enterprise-grade security capabilities for AI virtual
assistants, including authentication, authorization, data protection,
AI-specific security, privacy compliance, and security monitoring.

## Modules

### Authentication & Authorization

- OAuth2 / JWT token management
- Multi-factor authentication (MFA)
- Role-based access control (RBAC)
- Session management
- API key management
- SSO integration

### Data Protection

- AES-256 encryption at rest
- TLS 1.3 for data in transit
- PII detection and classification
- Data retention policies
- Secure key management

### AI Security

- Prompt injection detection
- Output filtering and sanitization
- Hallucination detection
- Bias detection and mitigation
- Model access control

### Privacy Controls

- Consent management (GDPR)
- Data subject rights handling
- Anonymization and pseudonymization
- Privacy preference management
- Data minimization

### Compliance

- HIPAA compliance manager
- SOC 2 controls
- Audit logging
- Compliance reporting
- Policy enforcement

### Security Monitoring

- Intrusion detection (IDS)
- Anomaly detection
- Rate limiting
- Threat intelligence
- Alert management

## Project Structure

```
src/security/
├── __init__.py           # Package exports
├── auth/                 # Authentication & Authorization
│   ├── types.py          # Auth data types
│   ├── authentication.py # Auth service
│   └── authorization.py  # RBAC/permissions
├── data_protection/      # Encryption & Data Safety
│   ├── encryption.py     # Crypto services
│   ├── pii_detector.py   # PII detection
│   └── classifier.py     # Data classification
├── ai_security/          # AI-Specific Security
│   ├── prompt_injection.py
│   ├── output_filter.py
│   └── hallucination.py
├── privacy/              # Privacy Controls
│   ├── consent.py        # Consent management
│   ├── dsr.py            # Data subject rights
│   └── anonymizer.py     # Anonymization
├── compliance/           # Regulatory Compliance
│   ├── hipaa.py          # HIPAA compliance
│   ├── audit.py          # Audit logging
│   └── reporter.py       # Compliance reports
└── monitoring/           # Security Monitoring
    ├── intrusion.py      # IDS
    ├── anomaly.py        # Anomaly detection
    └── alerts.py         # Alert management
```

## Development

### Using Nx

```bash
# Install dependencies
nx install psyche-security

# Build
nx build psyche-security

# Linting
nx lint psyche-security
nx lint-fix psyche-security

# Formatting
nx format psyche-security
nx format-check psyche-security

# Type checking
nx typecheck psyche-security

# Testing
nx test psyche-security
nx test-cov psyche-security
```

### Direct Commands

```bash
cd apps/psyche/security

# Install dependencies
poetry install

# Run tests
poetry run pytest

# Lint
poetry run ruff check src tests
```

## Usage Examples

### Authentication

```python
from security import get_authentication_service

auth = get_authentication_service("your-secret-key")

# Register a user
user = await auth.register_user("user@example.com", "password")

# Authenticate
token = await auth.authenticate("user@example.com", "password")

# Verify token
claims = await auth.verify_token(token.access_token)
```

### Authorization

```python
from security import get_authorization_service

authz = get_authorization_service()

# Check permission
if authz.has_permission(user.user_id, "resource:read"):
    # Access granted
    pass

# Check role
if authz.has_role(user.user_id, "admin"):
    # Admin access
    pass
```

### AI Security

```python
from security import get_ai_security_service

ai_security = get_ai_security_service()

# Check for prompt injection
result = await ai_security.check_prompt(user_input)
if result.is_safe:
    # Process the prompt
    pass
else:
    # Handle potential attack
    pass

# Filter AI output
safe_output = await ai_security.filter_output(model_response)
```

### Privacy

```python
from security import get_consent_manager

consent = get_consent_manager()

# Record consent
await consent.record_consent(
    user_id=user.user_id,
    purpose="analytics",
    granted=True,
)

# Check consent
if await consent.has_consent(user.user_id, "analytics"):
    # Collect analytics
    pass
```

## Configuration

### Environment Variables

| Variable              | Description                   |
| --------------------- | ----------------------------- |
| `SECURITY_SECRET_KEY` | Master secret for JWT signing |
| `ENCRYPTION_KEY`      | Key for data encryption       |
| `AUDIT_LOG_LEVEL`     | Audit logging verbosity       |
| `RATE_LIMIT_REQUESTS` | Rate limit per window         |
| `RATE_LIMIT_WINDOW`   | Rate limit window in seconds  |

## License

Proprietary - Oshun Platform