Eve library

@psyche/auth

Other

Revision 1

On this page

Authentication library for Psyche Python services, aligned with @oshun/auth-primitives.

Features#

  • JWT Service - Token signing, verification, and decoding
  • Session Management - In-memory and Redis session stores
  • API Key Management - Generation, validation, and storage
  • Password Utilities - Secure hashing with Argon2/bcrypt/PBKDF2
  • FastAPI Middleware - Ready-to-use authentication dependencies

Installation#

bash
# Core package
poetry add psyche-auth

# With all optional dependencies
poetry add "psyche-auth[all]"

# Specific extras
poetry add "psyche-auth[argon2]"  # Argon2 password hashing
poetry add "psyche-auth[bcrypt]"   # bcrypt password hashing
poetry add "psyche-auth[redis]"    # Redis session store

Quick Start#

JWT Authentication#

python
from psyche_auth import (
    JwtService,
    JwtConfig,
    JwtPayload,
    KeyConfig,
    KeyAlgorithm,
)

# Create JWT service
jwt_service = JwtService(
    JwtConfig(
        issuer="psyche",
        audience="psyche",
        access_token_ttl=900,  # 15 minutes
        refresh_token_ttl=604800,  # 7 days
        key=KeyConfig(
            algorithm=KeyAlgorithm.HS256,
            secret="your-secret-key",
        ),
    )
)

# Sign a token
token = await jwt_service.sign(
    JwtPayload(user_id="123", email="user@example.com", roles=["user"])
)

# Verify a token
result = await jwt_service.verify(token)
if result.valid:
    print(f"User ID: {result.payload.user_id}")
else:
    print(f"Error: {result.error}")

# Create token pair (access + refresh)
token_pair = await jwt_service.create_token_pair(
    JwtPayload(user_id="123", roles=["user"])
)
print(f"Access Token: {token_pair.access_token}")
print(f"Refresh Token: {token_pair.refresh_token}")

FastAPI Integration#

python
from fastapi import Depends, FastAPI
from psyche_auth import (
    AuthContext,
    AuthDependency,
    create_hmac_jwt_service,
)

app = FastAPI()

# Create JWT service
jwt_service = create_hmac_jwt_service(
    secret="your-secret-key",
    issuer="psyche",
)

# Create auth dependency
auth = AuthDependency(jwt_service)


@app.get("/protected")
async def protected_route(context: AuthContext = Depends(auth.required)):
    return {"user_id": context.user_id, "roles": context.roles}


@app.get("/optional")
async def optional_route(context: AuthContext = Depends(auth.optional)):
    if context.is_authenticated:
        return {"user_id": context.user_id}
    return {"user_id": None}


@app.get("/admin")
async def admin_route(
    context: AuthContext = Depends(auth.with_roles("admin"))
):
    return {"admin": True}

Session Management#

python
from psyche_auth import (
    InMemorySessionStore,
    RedisSessionStore,
    SessionConfig,
    SessionOptions,
)

# In-memory store (development)
store = InMemorySessionStore(
    SessionConfig(
        ttl=86400,  # 24 hours
        rolling=True,  # Extend TTL on activity
    )
)

# Create session
session = await store.create(
    user_id="123",
    data={"preferences": {"theme": "dark"}},
    options=SessionOptions(
        ip_address="192.168.1.1",
        user_agent="Mozilla/5.0...",
    ),
)

# Get session
session = await store.get(session.id)

# Update session
await store.update(session.id, {"last_action": "view_dashboard"})

# Delete session
await store.delete(session.id)

# Redis store (production)
import redis.asyncio as redis

redis_client = redis.from_url("redis://localhost:6379")
redis_store = RedisSessionStore(redis_client)

API Keys#

python
from psyche_auth import (
    InMemoryApiKeyStore,
    ApiKeyDependency,
)

# Create store
store = InMemoryApiKeyStore()

# Generate API key
api_key, full_key = await store.create(
    name="Production API Key",
    owner_id="user_123",
    owner_type="user",
    scopes=["read", "write"],
)

print(f"API Key (save this!): {full_key}")
print(f"Key Prefix: {api_key.key_prefix}")

# Validate API key
validated = await store.validate(full_key)
if validated:
    print(f"Valid! Scopes: {validated.scopes}")

# FastAPI integration
api_key_auth = ApiKeyDependency(store)

@app.get("/api/data")
async def get_data(api_key = Depends(api_key_auth.required)):
    return {"owner": api_key.owner_id}

Password Hashing#

python
from psyche_auth import (
    hash_password,
    verify_password,
    validate_password,
    generate_password,
    PasswordPolicy,
)

# Hash a password
result = hash_password("mypassword123")
print(f"Hash: {result.hash}")
print(f"Algorithm: {result.algorithm}")

# Verify a password
is_valid = verify_password("mypassword123", result)
print(f"Valid: {is_valid}")

# Validate password against policy
validation = validate_password(
    "weak",
    PasswordPolicy(
        min_length=8,
        require_uppercase=True,
        require_numbers=True,
    ),
)
print(f"Valid: {validation.valid}")
print(f"Errors: {validation.errors}")

# Generate a secure password
password = generate_password(
    length=16,
    include_special=True,
)
print(f"Generated: {password}")

Configuration#

Environment Variables#

bash
# JWT Configuration
JWT_SECRET=your-secret-key
JWT_ISSUER=psyche
JWT_AUDIENCE=psyche
JWT_ACCESS_TOKEN_TTL=900
JWT_REFRESH_TOKEN_TTL=604800

# Redis (for session store)
REDIS_URL=redis://localhost:6379

Pydantic Settings#

python
from pydantic_settings import BaseSettings
from psyche_auth import JwtConfig, KeyConfig, KeyAlgorithm


class AuthSettings(BaseSettings):
    jwt_secret: str
    jwt_issuer: str = "psyche"
    jwt_audience: str = "psyche"
    jwt_access_token_ttl: int = 900
    jwt_refresh_token_ttl: int = 604800

    class Config:
        env_prefix = "JWT_"

    def get_jwt_config(self) -> JwtConfig:
        return JwtConfig(
            issuer=self.jwt_issuer,
            audience=self.jwt_audience,
            access_token_ttl=self.jwt_access_token_ttl,
            refresh_token_ttl=self.jwt_refresh_token_ttl,
            key=KeyConfig(
                algorithm=KeyAlgorithm.HS256,
                secret=self.jwt_secret,
            ),
        )

Alignment with @oshun/auth-primitives#

This library provides Python equivalents for all key types and interfaces:

TypeScript Python
JwtPayload JwtPayload
JwtConfig JwtConfig
VerificationResult VerificationResult
TokenPair TokenPair
Session Session
SessionStore InMemorySessionStore
ApiKey ApiKey
AuthContext AuthContext
PasswordPolicy PasswordPolicy

Nx Targets#

Target Description
build Build the package
install Install dependencies
lint Run Ruff linter
lint-fix Fix linting issues
format Format with Black
format-check Check formatting
typecheck Run MyPy
test Run pytest
test-cov Run tests with coverage

License#

Proprietary - Oshun Platform