Aura Auth
About

Security Model

Deep dive into the security mechanisms protecting Aura Auth

Aura Auth follows a secure by default philosophy. It provides strong security guarantees to TypeScript applications while reducing implementation complexity and configuration overhead.

Web Standards

OAuth 2.0

Aura Auth relies on the standard OAuth 2.0 Authorization Framework. OAuth 2.0 enables applications to access protected resources without requiring users to share credentials directly with the client.

Aura Auth implements a compliant OAuth 2.0 flow with additional security controls, including mandatory PKCE enforcement and strict state validation.

PKCE

Aura Auth enforces PKCE (RFC 7636) flow by default for authorization and access_token OAuth 2.0 flows, regardless of whether the provider strictly requires it.

PKCE introduces the following parameters:

  • code_verifier: A cryptographically secure, high-entropy random string.
  • code_challenge: A SHA-256 hash of the verifier.
  • code_challenge_method: The hashing algorithm used to derive the code_challenge.

This mechanism prevents authorization code interception attacks. Providers that do not support PKCE will safely ignore these parameters, as required by the OAuth 2.0 specification.

HTTP State Management

Aura Auth relies on the standard HTTP State Management Mechanism for maintaining session state and CSRF tokens. Cookies are configured with strict security attributes to mitigate common web vulnerabilities. so the cookies are configured with strict security flags automatically to provide secure by default.

  • HttpOnly: Prevents JavaScript access (mitigates XSS).
  • Secure: Ensures cookies are only sent over HTTPS (except on localhost).
  • SameSite: Defaults to Lax to balance security (CSRF protection) with usability.
  • Domain restrictions: Wildcard domains are never allowed.

HKDF (Key Derivation)

Aura Auth implements HKDF (HMAC-based Key Derivation Function) to derive cryptographic keys from the base secret. This approach ensures the original secret is never directly exposed during signing and encryption operations, following security best practices for key management. HMAC-based Extract-and-Expand Key Derivation Function (HKDF)

Token Management

Aura Auth uses stateless tokens stored in cookies to represent sessions, CSRF tokens, and transient OAuth state. All tokens are protected using standards defined by the JOSE (JSON Object Signing and Encryption) family.

Internally, Aura Auth relies on the @aura-stack/jose package, which provides a constrained and auditable API surface for:

  • JWT creation and validation
  • JWS signing and verification
  • JWE encryption and decryption
  • Deterministic key derivation

For security measures Aura Auth implements key derivation via HKDF (RFC 5869) functions to extract and derive the keys used for signing, encrypting and CSRF tokens. It ensures that the primary secret key is never used directly and remains unknown to the outside.

  • AURA_AUTH_SECRET is required and must contain at least 32 bytes of high-entropy data
  • AURA_AUTH_SALT is optional and provides additional deterministic entropy for key derivation

The secret values must be deterministic or rotate with caution. Changing either value invalidates all active sessions and CSRF tokens.

JSON Web Signature (JWS)

The session data stored in session_token cookie and CSRF Token in csrf_token are signed to ensure integrity. This prevents tampering; appropriate signature verification proves that the token was issued by your server and hasn't been altered. For more detailed information read Signing API (JWS).

JSON Web Encryption (JWE)

By default, session tokens in session_token are also encrypted. This ensures confidentiality. Even if a user (or attacker) reads the cookie, they cannot see the session contents (like user ID or email) without the AURA_AUTH_SECRET. For more detailed information read Encryption API (JWE).

For mutating actions (like Sign Out), Aura Auth employs a CSRF protection mechanism that ensures that critical actions are made by the original user. Otherwise, if the CSRF Token is not provided the action isn't going to be possible.

  1. A CSRF token is generated and stored in a csrf_token cookie.

  2. The client retrieves the token via the /csrfToken endpoint.

  3. The token must be sent back in the X-CSRF-Token request header.

  4. The server validates::

    • The CSRF Token must be present in the Cookie header.
    • The CSRF Token must be present in the X-CSRF-Token header.

    Once the csrf tokens are sent in these two ways and verified that they match, the critical action is allowed to dispatch.

Core Principles

Learn about the design principles behind Aura Auth.

Runtime Agnostic

Learn how Aura Auth is designed to run across multiple JavaScript runtimes.

On this page

Web StandardsOAuth 2.0PKCEHTTP State ManagementHKDF (Key Derivation)Token ManagementJSON Web Signature (JWS)JSON Web Encryption (JWE)Double Submit Cookie