Security

This guide explains gau’s security features.

Host Validation

To protect against common web vulnerabilities, gau uses the trustHosts option to validate where requests are coming from and where users are being sent. This is a critical defense against both Cross-Site Request Forgery (CSRF) and Open Redirect attacks.

This is configured via the trustHosts option in createAuth.

Open Redirect Prevention

An open redirect vulnerability occurs when an application redirects users to a URL that could be controlled by an attacker, often for phishing purposes. gau prevents this by validating the redirectTo parameter that can be passed during login.

When a user signs in, you can provide a redirectTo query parameter to send them to a specific page afterward. gau checks if the hostname in the redirectTo URL is in your trustHosts list. If it isn’t, the redirect is blocked.

Note

Client-side integrations automatically set redirectTo to their URL. You just need to whitelist the hostnames on the server’s createAuth config.

CSRF Protection

Cross-Site Request Forgery is an attack that tricks a user into submitting a malicious request. gau mitigates this by validating the Origin header on all POST requests to its API routes (like /api/auth/signout and /api/auth/unlink). Only origins from hosts in trustHosts are allowed.

Configuration

• Default behavior: By default, trustHosts is an empty array ([]), which means gau will only allow requests and redirects that originate from or point to the same host as your application.

  Note

  In development, localhost and 127.0.0.1 are automatically trusted.

• Configuring specific hosts: When your frontend and backend are on different domains, or you need to redirect to a subdomain, you must add those hosts to the list.

  trustHosts: [
    'app.example.com',  // Production frontend
    'tauri.localhost',  // Production Tauri app
  ]

• Trust all hosts ('all'): This setting disables host validation and is not recommended for production, as it exposes your application to both CSRF and open redirect risks.

In addition to trustHosts, gau also uses a temporary state-based CSRF token (__gau-csrf-token cookie) during the OAuth flow itself. This ensures that the user who starts the authentication process is the same one who finishes it, providing an extra layer of security against CSRF during login.

PKCE

PKCE is a security extension to the OAuth 2.0 protocol. It’s designed to prevent an attacker from intercepting the authorization code returned by the OAuth provider and exchanging it for an access token. This is especially critical for public clients like SPAs and mobile/desktop apps.

This is built in. gau automatically handles the entire PKCE flow for you.

1. When a sign-in is initiated, gau generates a secret code_verifier.
2. It creates a code_challenge by hashing the verifier and sends this challenge to the authorization server.
3. When the authorization code is exchanged for an access token, gau sends the original code_verifier.
4. The authorization server re-applies the hash and ensures it matches the original challenge.

Secure Cookie Defaults

When using cookie-based sessions, gau applies secure defaults to the session cookie (__gau-session-token):

• httpOnly: true: Prevents the cookie from being accessed by client-side JavaScript, mitigating XSS attacks.
• secure: true: Ensures the cookie is only sent over HTTPS connections.
• sameSite: 'lax': Provides a balance of security and usability, protecting against most CSRF attacks while allowing the cookie to be sent with top-level navigations.

You can customize these settings via the cookies option, for example, to enforce 'strict' same-site policies if your application’s flow allows for it.