Security

This guide explains gau’s security features.

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 /signout).

This is configured via the trustHosts option in createAuth.

• Default behavior: By default, trustHosts is an empty array ([]), which means gau will only allow requests that originate from the same host as your application. This is the most secure default setting.

• Configuring specific hosts: When your frontend and backend are on different domains, you can set specific hosts that your backend should trust.

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

• Trust all hosts: This is not recommended, although the only POST request gau uses is for signing out, you probably still don’t want to allow any host to tamper with that.

In addition to the Origin check, gau also uses a temporary state-based CSRF token (__gau-csrf-token cookie) during the OAuth flow itself to ensure that the user who starts the authentication process is the same one who finishes it.

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.