sc-auth is a foundational authentication module specifically designed for the SocketCluster real-time framework. It facilitates JSON Web Token (JWT) based authentication, which is the default mechanism in SocketCluster. This package, currently at version 6.0.0 (released approximately eight years ago), handles the core logic for signing and verifying JWTs within a SocketCluster environment. While newer SocketCluster documentation often guides developers towards using `agServer.auth.signToken` or `jsonwebtoken` directly, `sc-auth` provides a structured `AuthEngine` for this purpose. Its primary role is to enable persistent user sessions, cross-browser tab authentication, and secure access control by signing arbitrary data objects with a secret key. Due to its age, developers should be aware that active development is minimal, and practices may have evolved in the broader SocketCluster ecosystem. Its release cadence is effectively dormant, with its last major update occurring many years ago.
npm install sc-authVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to integrate `sc-auth` with a SocketCluster server to handle JWT-based authentication. It shows initializing the `AuthEngine`, using it to sign tokens upon a 'login' event, and implementing inbound middleware to verify token presence and perform basic role-based authorization for publishing to channels.
Refactor asynchronous calls using `await` or `.then()` to handle Promises instead of traditional Node.js callbacks.
Evaluate whether direct use of the `jsonwebtoken` package or SocketCluster's `agServer.auth` methods are more suitable for new projects or if this package's functionalities can be safely migrated. Regularly audit dependencies for vulnerabilities.
Always store the `authKey` in environment variables (e.g., `process.env.AUTH_SIGNATURE_KEY`) or a secure configuration management system. Ensure it is a long, cryptographically strong random string.
Only include non-sensitive information necessary for authorization (e.g., user ID, roles, permissions) in the JWT payload. Fetch sensitive user data from a secure backend store (e.g., database) after token verification.
Implement client-side logic to detect expired tokens and automatically request a new one (e.g., using a refresh token mechanism) or prompt the user to re-authenticate. Ensure server-side logic handles `TokenExpiredError` gracefully.
Verify that the same `authKey` (or signature key) is consistently used across all signing and verification points in your application. Ensure no part of the token was altered after signing. This often happens if an `authKey` is mismatched between different services or deployments.
For CommonJS, use `const AuthEngine = require('sc-auth').AuthEngine;`. If using ESM, `sc-auth` might not natively support it for direct named imports; consider `const { AuthEngine } = await import('sc-auth');` or wrapping it in a CommonJS file that exports an ESM-compatible module.Ensure the `AuthEngine` is initialized with the correct `authKey` (e.g., `new AuthEngine(process.env.AUTH_SIGNATURE_KEY)`). Double-check environment variable loading and configuration.