nodebb-plugin-session-sharing 8.0.6 → 9.0.0

package/README.md

@@ -1,8 +1,8 @@
 # Session Sharing for NodeBB
 
 In a nutshell, this plugin allows you to share sessions between your application and NodeBB. You'll need to set a
-special cookie with a common domain, containing a JSON Web Token with user data. If sufficient, this plugin will
-handle the rest (user registration/login).
+special cookie with a common domain, containing a JSON Web Token (signed, or encrypted) with user data. If
+sufficient, this plugin will handle the rest (user registration/login).
 
 ## How is this related to SSO?
 
@@ -21,8 +21,8 @@ You can use this plugin and single sign-on plugins together, but they won't be s
 ## How does this work?
 
 This plugin checks incoming requests for a **shared cookie** that is saved by your application when a user
-logs in. This cookie contains in its value, a specially crafted signed token containing unique identifying
-information for that user.
+logs in. This cookie contains in its value, a specially crafted signed (JWS) or encrypted (JWE) token
+containing unique identifying information for that user.
 
 If the user can be found in NodeBB, that user will be logged in. If not, then a user is created, and that
 unique indentifier is saved for future reference.
@@ -36,10 +36,13 @@ to have a couple special attributes:
 * The `domain` should be set to the naked domain. That is, if your site is at `app.example.com`, and your
 forum is at `talk.example.com`, the cookie domain should be set to `example.com`.
 * The cookie name is up to you, and can be configured in this plugin's settings. *(Default: `token`)*
-* The cookie value is a [JSON Web Token](https://jwt.io/). See below.
+* The cookie value is a [JSON Web Token](https://jwt.io/) — signed (JWS) or encrypted (JWE). See below.
 
 ### Generating the JSON Web Token
 
+The steps below describe the default **JWS** format; if you've switched the plugin to **JWE**, see
+[Token Format (JWS / JWE)](#token-format-jws--jwe) instead.
+
 A list of compatible libraries can be obtained on the main website for [JSON Web Tokens](https://jwt.io/).
 
 You'll be encoding a payload that looks something like this...
@@ -87,14 +90,66 @@ it can properly decode and verify the JWT signature.
 
 In which case, you can set the "Parent Key" setting in this plugin to `d`.
 
+### Token Format (JWS / JWE)
+
+By default the shared cookie is a **JWS** (signed) JWT. The **Token Format** setting in the admin panel
+allows switching to **JWE** (encrypted) JWTs, in which case the payload is confidential and only decryptable
+with the corresponding key, so its contents are not visible in the cookie.
+
+This setting controls the format of tokens *generated* by NodeBB (the `nbb_token` reverse cookie and the
+development debug token). **Incoming cookies are auto-detected by their structure** (a JWS has 3
+dot-separated segments, a JWE has 5), so *both* formats are accepted regardless of the setting. This allows
+a gradual migration: flip the setting, then switch your application over to issuing JWE cookies at your own
+pace — users with cookies in either format will continue to log in throughout the transition.
+
+Tokens are created and verified with [`jose`](https://github.com/panva/jose). When issuing JWE cookies from
+your application, use the following parameters:
+
+| Signing method | `alg` | `enc` | Key |
+| --- | --- | --- | --- |
+| HMAC | `dir` | `A256GCM` | HKDF-derived from your shared secret (see below) |
+| RSA | `RSA-OAEP-256` | `A256GCM` | The RSA **public** key |
+
+**HMAC key derivation** — JWE's `dir` key method requires the key to be exactly 32 bytes, so
+arbitrary-length shared secrets cannot be used directly. NodeBB derives the JWE key with HKDF-SHA256:
+
+```
+HKDF(
+	ikm:	<your shared secret>,
+	salt:	"nodebb-plugin-session-sharing",
+	info:	"A256GCM",
+	length:	32
+)
+```
+
+Your application must perform the same derivation before encrypting. JWS is unaffected — `HS256` signing
+uses the raw secret as-is, so existing JWS setups keep working unchanged.
+
+**RSA key direction** — note that JWE inverts the key direction of JWS: your application *encrypts* with the
+RSA **public** key, and NodeBB *decrypts* with the RSA **private** key. If you use JWE with the RSA signing
+method, make sure the **RSA Private Key** is configured in the admin settings — without it, encrypted cookies
+cannot be decrypted (a warning is logged at startup).
+
+The `nbb_token` reverse cookie follows the same Token Format setting. If your application reads the reverse
+token, it must be able to decrypt JWE when this setting is enabled.
+
 ## Security
 
-Please note that according to the JWT spec, the payload itself is ***not encrypted***, only *signed*. That is,
+Please note that according to the JWT spec, a JWS payload is ***not encrypted***, only *signed*. That is,
 the Base64 Url Encoded payload is appended to the header. It can be decoded trivially (as base64 is not meant
-to be cryptographically secure), so **do not put any private information in the payload**. The header and
-payload themselves are *signed* against the secret, and NodeBB will only allow a JWT through if it has not been
-tampered with. That is, NodeBB will only continue with a login if the signature can be independently generated
-by the received payload and the secret.
+to be cryptographically secure), so **do not put any private information in the payload** of a JWS token. The
+header and payload themselves are *signed* against the secret, and NodeBB will only allow a JWT through if it
+has not been tampered with. That is, NodeBB will only continue with a login if the signature can be
+independently generated by the received payload and the secret.
+
+**Mitigating payload exposure with JWE** — if the exposure above is a concern for your setup (for example,
+your payload includes an `email` or `groups` you'd rather not be visible in a cookie, or you cannot guarantee
+HTTPS end-to-end), switch the **Token Format** setting to JWE (see
+[Token Format (JWS / JWE)](#token-format-jws--jwe)). A JWE token *encrypts* the payload — with `A256GCM` in
+this plugin — so the identifying information is not visible in the cookie at all, and can only be decrypted by
+NodeBB with the corresponding key. Note that JWE protects the payload's *confidentiality*; the token is still
+only as trustworthy as the key or secret it was sealed with, and a stolen private key (or shared secret) can
+still mint valid tokens — the rest of this section applies to both formats.
 
 Use secure cookies transmitted via HTTPS if at all possible.
 

package/eslint.config.mjs

@@ -6,5 +6,13 @@ import publicConfig from 'eslint-config-nodebb/public';
 export default [
 	...publicConfig,
 	...serverConfig,
+	{
+		files: ['library.js', 'lib/**/*.js'],
+		languageOptions: {
+			globals: {
+				nodebb: 'readonly',
+			},
+		},
+	},
 ];
 

package/library.js

@@ -4,9 +4,10 @@ const winston = nodebb.require('winston');
 const nconf = nodebb.require('nconf');
 
 const util = require('util');
+const crypto = require('crypto');
 
 const _ = require('lodash');
-const jwt = require('jsonwebtoken');
+const { jwtVerify, jwtDecrypt, SignJWT, EncryptJWT } = require('jose');
 
 const meta = nodebb.require('./src/meta');
 const user = nodebb.require('./src/user');
@@ -47,6 +48,10 @@ const plugin = {
 		cookieName: 'token',
 		cookieDomain: undefined,
 		secret: '',
+		signingMethod: 'hmac',
+		tokenFormat: 'jws',
+		publicKey: '',
+		privateKey: '',
 		behaviour: 'trust',
 		adminRevalidate: 'off',
 		noRegistration: 'off',
@@ -136,8 +141,93 @@ plugin.getUser = async (remoteId) => {
 	return user.getUserFields(uid, ['username', 'userslug', 'picture']);
 };
 
+/*
+ * JWE with a symmetric key ("dir" key method) requires the key to be exactly
+ * the length of the content encryption key (32 bytes for A256GCM). Shared
+ * secrets are arbitrary-length, so derive a fixed-length key with HKDF.
+ * Apps issuing JWE cookies must perform the same derivation.
+ */
+const JWE_HKDF_SALT = 'nodebb-plugin-session-sharing';
+const JWE_HKDF_INFO = 'A256GCM';
+
+plugin.getJwsKey = (isPrivate) => {
+	if (plugin.settings.signingMethod === 'rsa') {
+		const pem = isPrivate ? plugin.settings.privateKey : plugin.settings.publicKey;
+		if (!pem) {
+			throw new Error(isPrivate ? 'No RSA private key configured' : 'No RSA public key configured');
+		}
+		// jose v6 expects a KeyObject, not a PEM string
+		return isPrivate ? crypto.createPrivateKey(pem) : crypto.createPublicKey(pem);
+	}
+	if (!plugin.settings.secret) {
+		throw new Error('No JWT secret configured');
+	}
+	return crypto.createSecretKey(plugin.settings.secret, 'utf8');
+};
+
+/*
+ * Note the key direction differs from JWS: JWE is encrypted with the public
+ * key and decrypted with the private key, so verifying an incoming JWE
+ * cookie requires the RSA private key.
+ */
+plugin.getJweKey = (isDecryption) => {
+	if (plugin.settings.signingMethod === 'rsa') {
+		return plugin.getJwsKey(isDecryption);
+	}
+	if (!plugin.settings.secret) {
+		throw new Error('No JWT secret configured');
+	}
+	// jose expects a Uint8Array (not a Node Buffer) for symmetric JWE keys
+	return new Uint8Array(crypto.hkdfSync('sha256', plugin.settings.secret, JWE_HKDF_SALT, JWE_HKDF_INFO, 32));
+};
+
+/*
+ * Verifies an incoming token, accepting both JWS (3 segments) and JWE
+ * (5 segments) so that installs can migrate between the two formats
+ * without a hard cutover. Key selection is driven by the configured
+ * signing method, not the token header.
+ */
+plugin.verifyToken = async (token) => {
+	if (typeof token !== 'string' || !token.length) {
+		throw new Error('payload-invalid');
+	}
+
+	const isJWE = token.split('.').length === 5;
+
+	try {
+		if (isJWE) {
+			const { payload } = await jwtDecrypt(token, plugin.getJweKey(true), {
+				algorithms: plugin.settings.signingMethod === 'rsa' ? ['RSA-OAEP-256'] : ['dir'],
+			});
+			return payload; // already JSON-parsed by jose
+		}
+
+		const { payload } = await jwtVerify(token, plugin.getJwsKey(false), {
+			algorithms: plugin.settings.signingMethod === 'rsa' ? ['RS256'] : ['HS256'],
+		});
+		return payload;
+	} catch (error) {
+		throw new Error('payload-invalid', { cause: error });
+	}
+};
+
+/* Creates a JWS or JWE token according to the configured token format */
+plugin.createToken = async (payload) => {
+	if (plugin.settings.tokenFormat === 'jwe') {
+		const encrypted = new EncryptJWT(payload).setProtectedHeader(
+			plugin.settings.signingMethod === 'rsa' ? { alg: 'RSA-OAEP-256', enc: 'A256GCM' } : { alg: 'dir', enc: 'A256GCM' }
+		);
+		return encrypted.encrypt(plugin.getJweKey(false));
+	}
+
+	const signed = new SignJWT(payload).setProtectedHeader({
+		alg: plugin.settings.signingMethod === 'rsa' ? 'RS256' : 'HS256',
+	});
+	return signed.sign(plugin.getJwsKey(true));
+};
+
 plugin.process = async (token) => {
-	const payload = await jwt.verify(token, plugin.settings.secret, { algorithms: ['HS256'] });
+	const payload = await plugin.verifyToken(token);
 	const userData = await plugin.normalizePayload(payload);
 	const [uid, isNewUser] = await plugin.findOrCreateUser(userData);
 	await plugin.updateUserProfile(uid, userData, isNewUser);
@@ -526,13 +616,11 @@ plugin.addMiddleware = async function ({ req, res }) {
 };
 
 plugin.cleanup = async (data) => {
-	if (plugin.settings.cookieDomain) {
-		winston.verbose('[session-sharing] Clearing cookie');
-		data.res.clearCookie(plugin.settings.cookieName, {
-			domain: plugin.settings.cookieDomain,
-			path: '/',
-		});
-	}
+	winston.verbose('[session-sharing] Clearing cookie');
+	data.res.clearCookie(plugin.settings.cookieName, {
+		domain: plugin.settings.cookieDomain,
+		path: '/',
+	});
 
 	data.res.clearCookie('nbb_token', {
 		domain: plugin.settings.cookieDomain,
@@ -542,7 +630,7 @@ plugin.cleanup = async (data) => {
 	return true;
 };
 
-plugin.generate = function (req, res) {
+plugin.generate = async function (req, res) {
 	if (!plugin.ready) {
 		return res.sendStatus(404);
 	}
@@ -568,7 +656,7 @@ plugin.generate = function (req, res) {
 		payload = newPayload;
 	}
 
-	const token = jwt.sign(payload, plugin.settings.secret);
+	const token = await plugin.createToken(payload);
 	res.cookie(plugin.settings.cookieName, token, {
 		maxAge: 1000 * 60 * 60 * 24 * 21,
 		httpOnly: true,
@@ -595,10 +683,24 @@ plugin.reloadSettings = async (data) => {
 	}
 
 	const settings = await meta.settings.get('session-sharing');
-	if (!settings.hasOwnProperty('secret') || !settings.secret.length) {
+	const signingMethod = settings.signingMethod || 'hmac';
+	const tokenFormat = settings.tokenFormat || 'jws';
+	if (tokenFormat !== 'jws' && tokenFormat !== 'jwe') {
+		winston.error('[session-sharing] Invalid token format ("' + tokenFormat + '"), session sharing disabled.');
+		return;
+	}
+	if (signingMethod === 'rsa') {
+		if (!settings.publicKey || !settings.publicKey.length) {
+			winston.error('[session-sharing] RSA public key not found, session sharing disabled.');
+			return;
+		}
+	} else if (!settings.hasOwnProperty('secret') || !settings.secret.length) {
 		winston.error('[session-sharing] JWT Secret not found, session sharing disabled.');
 		return;
 	}
+	if (signingMethod === 'rsa' && (!settings.privateKey || !settings.privateKey.length)) {
+		winston.warn('[session-sharing] RSA private key not configured; JWE (encrypted) cookies cannot be decrypted and reverse tokens cannot be signed.');
+	}
 
 	// If "payload:parent" is found, but payloadParent is not, update the latter and delete the former
 	if (!settings.payloadParent && settings['payload:parent']) {
@@ -641,7 +743,7 @@ plugin.saveReverseToken = async ({ req, userData: data }) => {
 	const { res } = req;
 	const userData = await user.getUserFields(data.uid, ['uid', 'username', 'picture', 'reputation', 'postcount', 'banned']);
 	userData.groups = (await groups.getUserGroups([data.uid])).pop();
-	const token = jwt.sign(userData, plugin.settings.secret);
+	const token = await plugin.createToken(userData);
 
 	res.cookie('nbb_token', token, {
 		maxAge: meta.getSessionTTLSeconds() * 1000,