Specialized Signers — Aquilia Documentation
Comprehensive guide and documentation for Specialized Signers in the Aquilia framework. View API reference, examples, and implementation patterns.
SIGNING SYSTEM / SPECIALIZED SIGNERS Specialized Signers & Config Discover the subsystem-isolated signers and how to apply configurations globally at application startup. Subsystem-Specific Signers To prevent cross-subsystem token confusion (e.g. using a password reset token as a session cookie), Aquilia provides specialized classes with hardcoded namespace salts: class SessionSigner(TimestampSigner): # Salt: "aquilia.sessions". Used to secure session identifier cookies. class CSRFSigner(Signer): # Salt: "aquilia.csrf". Used to secure request CSRF tokens. Stateless. class ActivationLinkSigner(TimestampSigner): # Salt: "aquilia.activation". Enforces a default max_age of 24 hours. class CacheKeySigner(Signer): # Salt: "aquilia.cache". Used to sign cached bytes and prevent cache poisoning. class CookieSigner(TimestampSigner): # Salt: "aquilia.cookies". Used for user-space signed HTTP cookies. class APIKeySigner(TimestampSigner): # Salt: "aquilia.apikeys". Used to sign short-lived URL queries and access tokens. SigningConfig API Reference The SigningConfig dataclass defines configuration parameters mapped from the application config registry. @dataclass class SigningConfig: secret: str = "" fallback_secrets: list[str] = field(default_factory=list) algorithm: str = "HS256" salt: str = "aquilia.signing" session_salt: str = "aquilia.sessions" csrf_salt: str = "aquilia.csrf" activation_salt: str = "aquilia.activation" cache_salt: str = "aquilia.cache" def apply(self) -> None: """Configures the global secret registry.""" def make_session_signer(self) -> SessionSigner: ... def make_csrf_signer(self) -> CSRFSigner: ... def make_activation_signer(self) -> ActivationLinkSigner: ... def make_cache_signer(self) -> CacheKeySigner: ... def make_cookie_signer(self) -> CookieSigner: ... def make_api_key_signer(self) -> APIKeySigner: ... Scenario Walkthroughs Scenario 1: Applying Global Configurations Initialize signing configurations globally at application startup. This is typically invoked from your server entrypoint: from aquilia.signing import configure # 1. Load keys from environment variables or settings primary_secret = "master-secret-key-32-bytes-minimum" old_retired_key = "retired-key-32-bytes-minimum" # 2. Configure global signing registry configure( secret=primary_secret, fallback_secrets=[old_retired_key], algorithm="HS256" ) Scenario 2: Expirable Activation / Password Reset Links Generate signed password reset URLs. Verification enforces the default 24-hour limit: from aquilia.controller import Controller, GET, POST, RequestCtx from aquilia.signing import ActivationLinkSigner, SignatureExpired, BadSignature class ResetController(Controller): def initialize(self): self.signer = ActivationLinkSigner() @POST("/auth/reset-password/request") async def request_reset(self, ctx: RequestCtx): user_id = "user_984" # Generate token with activation-specific namespace token = self.signer.sign(user_id) reset_url = f"https://example.com/reset?token= " return @GET("/auth/reset-password/verify") async def verify_reset(self, ctx: RequestCtx): token = ctx.query.get("token", "") try: # Unsigns with default 24h max_age user_id = self.signer.unsign(token) return except SignatureExpired: return , 400 except BadSignature: return , 400 Core Signers Advanced Signing )
Go to Homepage