ag-auth (SocketCluster Auth Module)

Common errors

• JsonWebTokenError: invalid signature

  cause The JWT provided by the client was signed with a different secret key than the one the server is using for verification, or the token has been tampered with.
  fix Ensure the `authKey` used when initializing `AGServer` is identical to the key used to sign the token. Check for accidental whitespace or character discrepancies. If tokens are issued by an external service, verify key synchronization.

• TokenExpiredError: jwt expired

  cause The JWT's expiration time (`exp` claim) has passed, making the token invalid.
  fix Implement token refresh mechanisms on the client-side, where a valid refresh token is used to obtain a new access token before the current one expires. Configure appropriate `expiresIn` values during token signing.

• No authKey was specified when creating the AGServer instance.

  cause The `authKey` option was not provided to the `AGServer` constructor, which is required for `ag-auth` to sign and verify tokens.
  fix Pass a secure secret key to the `authKey` option of the `AGServer` constructor: `new AGServer({ authKey: process.env.AUTH_SECRET_KEY });`

Warnings

• breaking SocketCluster v15+ transitioned authentication functions to return Promises instead of accepting callbacks. Code relying on callback-based `agServer.auth` methods will break.
  Fix: Update all calls to `agServer.auth.signToken` and `agServer.auth.verifyToken` (and similar) to use `await` or `.then()` for Promise resolution.
• breaking Prior to SocketCluster v1.3.0, authentication was session-based. Since v1.3.0, it shifted entirely to JSON Web Tokens (JWT). Direct session manipulation methods are deprecated.
  Fix: Refactor authentication logic to exclusively use JWTs, leveraging `agServer.auth.signToken` and `agServer.auth.verifyToken` for all authentication flows. Migrate any persistent session data to be included within JWT payloads or external stores.
• gotcha JWTs are signed, not encrypted. Do not store sensitive or secret data directly in the token's payload, as it can be easily read by anyone with access to the token.
  Fix: Only store non-sensitive user identifiers (e.g., user ID, roles) in JWT payloads. Fetch sensitive user data from a secure database or service after verifying the token.
• gotcha Using a weak or compromised `authKey` (secret) makes JWTs vulnerable to forgery. An attacker could sign their own tokens and impersonate users.
  Fix: Always use a strong, randomly generated, long secret key for `agServer.authKey`. Store it securely (e.g., in environment variables) and rotate it periodically. Never hardcode it in source code.

Install

• npm install ag-auth npm
• yarn add ag-auth yarn
• pnpm add ag-auth pnpm

Imports

• AuthEngine
  wrong:

  const AuthEngine = require('ag-auth');

  correct:

  import { AuthEngine } from 'ag-auth';

  While `AuthEngine` can be imported for custom setups or direct usage, most users interact with `ag-auth` indirectly via the `agServer.auth` object within a SocketCluster worker.
• SignTokenOptions

  import { SignTokenOptions } from 'ag-auth';

  Type import for configuring JWT signing, primarily used with TypeScript for better type safety.
• VerifyTokenOptions

  import { VerifyTokenOptions } from 'ag-auth';

  Type import for configuring JWT verification, primarily used with TypeScript for better type safety.

Quickstart

This quickstart demonstrates how `ag-auth` (via `agServer.auth`) is used to sign and verify JWT tokens in a SocketCluster server, handling client authentication.

import { AGServer } from 'socketcluster-server';
import { AuthEngine } from 'ag-auth'; // Although usually accessed via agServer.auth

const SECRET_KEY = process.env.AUTH_SECRET_KEY ?? 'my-secret-key-123';

const agServer = new AGServer({
  authKey: SECRET_KEY,
  // If you were to override the default auth engine, you might do:
  // authEngine: new AuthEngine(SECRET_KEY)
});

(async () => {
  for await (const { socket } of agServer.listen()) {
    (async () => {
      // This is how ag-auth functionality is typically accessed
      // via the agServer instance.
      const tokenData = { username: 'testuser', roles: ['admin'] };

      try {
        // Sign a token using the configured authEngine (ag-auth)
        const token = await agServer.auth.signToken(tokenData, { expiresIn: '1h' });
        console.log(`Signed JWT: ${token}`);

        // Simulate client sending token and server verifying
        socket.on('login', async (data) => {
          try {
            const decodedToken = await agServer.auth.verifyToken(data.token);
            console.log(`Socket ${socket.id} authenticated:`, decodedToken);
            socket.emit('authSuccess', { message: 'Authenticated successfully', user: decodedToken.username });
          } catch (error) {
            console.error(`Socket ${socket.id} authentication failed:`, error.message);
            socket.emit('authFail', { message: 'Authentication failed', error: error.message });
          }
        });

        // Example: Client attempts to log in
        setTimeout(() => {
          console.log('Simulating client login attempt...');
          socket.emit('login', { token: token });
        }, 1000);

      } catch (error) {
        console.error('Error during auth setup:', error);
      }
    })();
  }
})();

console.log('SocketCluster server is listening for connections...');