Auth and Security

Overview

Lexigram-auth provides JWT-based authentication, RBAC, and web-layer guards. The bundle is wired by AuthModule, which exports AuthenticatorProtocol, AuthorizerProtocol, TokenManagerProtocol, and PasswordHasherProtocol. In DI you normally resolve AuthenticationService (login/register), AuthProviderProtocol (async verify), or JWTTokenManager (tokens).

Core Pattern

from lexigram.auth.authn.services import AuthenticationService
from lexigram.contracts.auth.exceptions import InvalidCredentialsError
from lexigram.result import Err, Ok, Result

class LoginService:
    def __init__(self, auth_service: AuthenticationService,
                 tokens: TokenManagerProtocol):
        self.auth = auth_service          # constructor injection
        self.tokens = tokens

    async def login(self, email: str, password: str) -> Result[str, str]:
        result = await self.auth.authenticate_user(email, password)
        match result:
            case Err(InvalidCredentialsError()) | Err(_):
                return Err("invalid credentials")
            case Ok(user):
                token = self.tokens.create_token(user)
                return Ok(token.access_token)

    def require_admin(self, token: str) -> bool:
        verified = self.tokens.verify_token(token)  # sync, Result[VerifiedToken, TokenError]
        match verified:
            case Ok(vt):
                return "admin" in vt.roles   # VerifiedToken.roles: list[str]
            case Err(_):
                return False

For async verification resolve AuthProviderProtocol (await provider.verify_token(token)), not AuthenticatorProtocol — the bundle never binds it.

Guards

from lexigram.web.security import AuthGuard, RoleGuard, use_guards

# RoleGuard takes an authorizer via constructor injection
@use_guards(AuthGuard(), RoleGuard("admin", authorizer=my_authorizer))
@get("/admin/users")
async def admin_list(self, request):
    ...

Custom guards implement GuardProtocol.can_activate(context); check request.state.user (set by auth middleware).

Provider Config

auth:
  secret_key: ${JWT_SECRET}      # >= 32 bytes for HS algorithms
  token:
    secret_key: ${JWT_SECRET}
    algorithm: HS256
    access_token_expire: 60m
    refresh_token_expire: 7d

Env override prefix: LEX_AUTH__.

Module Registration

from lexigram.auth import AuthModule
from lexigram.auth.config import AuthConfig

@module(imports=[AuthModule.configure(AuthConfig(
    secret_key=os.environ["JWT_SECRET"],
    token=JWTConfig(secret_key=os.environ["JWT_SECRET"]),
))])
class AppModule(Module): ...

# later: service = await container.resolve(AuthenticationService)

Use AuthModule.stub() in tests — in-memory store, fixed dev secret.

Common Mistakes

• Resolving AuthenticatorProtocol — exported but never bound; use AuthenticationService or AuthProviderProtocol
• Reading verified.claims — VerifiedToken has typed fields (user_id, roles, permissions, expires_at)
• Calling svc.authenticate(...) — the method is authenticate_user(email, password)
• Storing JWT secrets in code — use $ env-var references; HS256 needs ≥ 32 bytes
• Using sync password hashing in async handlers — blocks the event loop