Compare commits

...
Author SHA1 Message Date
Cohee 0887658ac0 Merge branch 'staging' into feat/secret-data-encrypt 2026-05-02 20:10:56 +03:00
Cohee b2ed175a94 fix: eslint in test 2026-04-29 01:47:44 +03:00
Cohee 5e01aa6db8 fix: duplicate type check 2026-04-28 23:16:34 +03:00
CoheeandCopilot 49d8e6c308 fix: combine console logs on errors
Co-authored-by: Copilot <copilot@github.com>
2026-04-28 22:45:51 +03:00
CoheeandCopilot 94cc6dc812 feat: implement master password for encrypting secrets
Co-authored-by: Copilot <copilot@github.com>
2026-04-28 22:06:37 +03:00
6 changed files with 373 additions and 8 deletions
+3
View File
@@ -1,4 +1,7 @@
# -- DATA CONFIGURATION --
# This is the encryption password for user secrets and other sensitive data. If left empty, encryption will be disabled and data will be stored in plaintext.
# For better security, use a CLI argument or an environment variable (SILLYTAVERN_MASTERPASSWORD) instead of storing the password in the config file.
masterPassword: ''
# Root directory for user data storage
dataRoot: ./data
# -- SERVER CONFIGURATION --
+8
View File
@@ -9,6 +9,7 @@ import { initConfig } from './config-init.js';
/**
* @typedef {object} CommandLineArguments Parsed command line arguments
* @property {string} masterPassword Master password for encrypting secrets (if not set, secrets will be stored in plaintext)
* @property {string} configPath Path to the config file
* @property {string} dataRoot Data root directory
* @property {number} port Port number
@@ -57,6 +58,7 @@ export class CommandLineParser {
return Object.freeze({
configPath: configPath,
dataRoot: dataPath,
masterPassword: '',
port: 8000,
listen: false,
listenAddressIPv6: '[::]',
@@ -119,6 +121,11 @@ export class CommandLineParser {
default: null,
describe: 'Path to the config file (only for standalone mode)',
})
.option('masterPassword', {
type: 'string',
default: null,
describe: 'Master password for encrypting secrets (if not set, secrets will be stored in plaintext)',
})
.option('enableIPv6', {
type: 'string',
default: null,
@@ -300,6 +307,7 @@ export class CommandLineParser {
const result = {
configPath: configPath,
dataRoot: dataRoot,
masterPassword: cliArguments.masterPassword ?? getConfigValue('masterPassword', defaultConfig.masterPassword),
port: cliArguments.port ?? getConfigValue('port', defaultConfig.port, 'number'),
listen: cliArguments.listen ?? getConfigValue('listen', defaultConfig.listen, 'boolean'),
listenAddressIPv6: cliArguments.listenAddressIPv6 ?? getConfigValue('listenAddress.ipv6', defaultConfig.listenAddressIPv6),
+109 -7
View File
@@ -3,7 +3,8 @@ import path from 'node:path';
import express from 'express';
import { sync as writeFileAtomicSync } from 'write-file-atomic';
import { color, getConfigValue, uuidv4 } from '../util.js';
import { color, getConfigValue, tryParse, uuidv4 } from '../util.js';
import { decryptObjectAes256, encryptObjectAes256, isEncryptedData } from '../util-crypto.js';
export const SECRETS_FILE = 'secrets.json';
export const SECRET_KEYS = {
@@ -111,6 +112,14 @@ export const allowKeysExposure = !!getConfigValue('allowKeysExposure', false, 'b
* SecretManager class to handle all secret operations
*/
export class SecretManager {
/**
* Master password for encrypting secrets, loaded from command-line arguments or config (if set)
* @type {string}
*/
static get #masterPassword() {
return String(globalThis.COMMAND_LINE_ARGS.masterPassword ?? '');
}
/**
* @param {import('../users.js').UserDirectoryList} directories
*/
@@ -120,13 +129,92 @@ export class SecretManager {
this.defaultSecrets = {};
}
/**
* Ensures that the secrets file is encrypted if a master password is set, and migrates existing secrets if necessary
* @param {import('../users.js').UserDirectoryList[]} directoriesLists List of user directories to check and encrypt secrets for
* @return {Promise<import('../users.js').UserDirectoryList[]>} The input list of user directories, returned for chaining purposes
*/
static async ensureEncryption(directoriesLists) {
if (!SecretManager.#masterPassword) {
console.warn();
console.warn(color.yellow('Warning: masterPassword is not set. Secrets will be stored in plaintext.'));
console.warn();
return directoriesLists;
}
console.info();
console.info(color.green('Master password is set.'), 'Make sure to keep it secure. It cannot be recovered if lost.');
console.info();
for (const directories of directoriesLists) {
const manager = new SecretManager(directories);
if (!manager._isSecretsFileEncrypted()) {
console.info(path.basename(directories.root), color.yellow('Encrypting existing secrets file with master password...'));
try {
const secrets = manager._readSecretsFile();
manager._writeSecretsFile(secrets);
console.info(path.basename(directories.root), color.green('Secrets file encrypted successfully.'));
} catch (error) {
console.error(path.basename(directories.root), color.red('Failed to encrypt secrets file:'), error);
}
}
}
return directoriesLists;
}
/**
* Prepares secret data for writing, applying encryption if masterPassword is set
* @param {object} data The secret data to prepare
* @return {string} The prepared JSON-serialized data, encrypted if masterPassword is set
*/
#prepareDataWrite(data) {
if (SecretManager.#masterPassword) {
const encryptedData = encryptObjectAes256(data, SecretManager.#masterPassword);
return JSON.stringify(encryptedData, null, 4);
}
return JSON.stringify(data, null, 4);
}
/**
* Parses secret data from a string, applying decryption if masterPassword is set
* @param {string} data The secret data string to parse
* @returns {object} The parsed secret data
*/
#parseDataRead(data) {
const parsedData = tryParse(data);
if (!parsedData) {
throw new Error('Secrets file is empty or contains invalid JSON');
}
if (SecretManager.#masterPassword) {
try {
// Data is not encrypted, return as-is (handles unencrypted secrets file when master password is set)
if (!isEncryptedData(parsedData)) {
return parsedData;
}
return decryptObjectAes256(parsedData, SecretManager.#masterPassword);
} catch (error) {
throw new Error('Decryption failed', { cause: error });
}
}
if (isEncryptedData(parsedData)) {
throw new Error('Secrets file appears to be encrypted but no master password is set. Unable to read secrets.');
}
return parsedData;
}
/**
* Ensures the secrets file exists, creating an empty one if necessary
* @private
*/
_ensureSecretsFile() {
if (!fs.existsSync(this.filePath)) {
writeFileAtomicSync(this.filePath, JSON.stringify(this.defaultSecrets), 'utf-8');
writeFileAtomicSync(this.filePath, this.#prepareDataWrite(this.defaultSecrets), 'utf-8');
}
}
@@ -138,7 +226,21 @@ export class SecretManager {
_readSecretsFile() {
this._ensureSecretsFile();
const fileContents = fs.readFileSync(this.filePath, 'utf-8');
return /** @type {SecretKeys} */ (JSON.parse(fileContents));
return /** @type {SecretKeys} */ (this.#parseDataRead(fileContents));
}
/**
* Checks if the secrets file is encrypted by attempting to parse it as JSON and checking for the encrypted format
* @returns {boolean} True if the secrets file is encrypted, false otherwise
*/
_isSecretsFileEncrypted() {
this._ensureSecretsFile();
const fileContents = fs.readFileSync(this.filePath, 'utf-8');
const parsedData = tryParse(fileContents);
if (parsedData) {
return isEncryptedData(parsedData);
}
return false;
}
/**
@@ -147,7 +249,7 @@ export class SecretManager {
* @param {SecretKeys} secrets
*/
_writeSecretsFile(secrets) {
writeFileAtomicSync(this.filePath, JSON.stringify(secrets, null, 4), 'utf-8');
writeFileAtomicSync(this.filePath, this.#prepareDataWrite(secrets), 'utf-8');
}
/**
@@ -383,8 +485,8 @@ export class SecretManager {
return;
}
const fileContents = fs.readFileSync(this.filePath, 'utf8');
const secrets = /** @type {FlatSecretKeys} */ (JSON.parse(fileContents));
const fileContents = /** @type {any} */ (this._readSecretsFile());
const secrets = /** @type {FlatSecretKeys} */ (fileContents);
const values = Object.values(secrets);
// Check if already migrated
@@ -501,7 +603,7 @@ export function migrateFlatSecrets(directoriesList) {
const manager = new SecretManager(directories);
manager.migrateFlatSecrets();
} catch (error) {
console.warn(color.red(`Failed to migrate secrets for ${directories.root}:`), error);
console.warn(color.red(`Failed to migrate secrets for ${path.basename(directories.root)}:`), error);
}
}
}
+2 -1
View File
@@ -72,7 +72,7 @@ import { checkForNewContent } from './endpoints/content-manager.js';
import { init as settingsInit } from './endpoints/settings.js';
import { redirectDeprecatedEndpoints, ServerStartup, setupPrivateEndpoints } from './server-startup.js';
import { diskCache } from './endpoints/characters.js';
import { migrateFlatSecrets } from './endpoints/secrets.js';
import { migrateFlatSecrets, SecretManager } from './endpoints/secrets.js';
import { migrateGroupChatsMetadataFormat } from './endpoints/groups.js';
// Work around a node v20.0.0, v20.1.0, and v20.2.0 bug. The issue was fixed in v20.3.0.
@@ -479,6 +479,7 @@ function setDnsResolutionOrder() {
initUserStorage(globalThis.DATA_ROOT)
.then(setDnsResolutionOrder)
.then(ensurePublicDirectoriesExist)
.then(SecretManager.ensureEncryption.bind(SecretManager))
.then(migrateUserData)
.then(migrateSystemPrompts)
.then(migratePublicOverrides)
+72
View File
@@ -0,0 +1,72 @@
import crypto from 'node:crypto';
const SALT_LENGTH = 32;
const KEY_LENGTH = 32;
/**
* @typedef {object} EncryptedData
* @property {string} salt Hex string of the salt used for key derivation
* @property {string} iv Hex string of the initialization vector used for encryption
* @property {string} encrypted Hex string of the encrypted data
* @property {string} authTag Hex string of the authentication tag from encryption
*/
/**
* Decrypts data encrypted with AES-256-OCB using the provided key.
* The key is derived from the password using scrypt.
* @param {EncryptedData} data Encrypted data in the format { salt, iv, encrypted, authTag }
* @param {string} keyString Encryption key as a UTF-8 string
* @returns {any} Decrypted data
*/
export function decryptObjectAes256(data, keyString) {
const salt = new Uint8Array(Buffer.from(data.salt, 'hex'));
const iv = new Uint8Array(Buffer.from(data.iv, 'hex'));
const key = new Uint8Array(crypto.scryptSync(keyString, salt, KEY_LENGTH));
const decipher = crypto.createDecipheriv('aes-256-ocb', key, iv, { authTagLength: 16 });
decipher.setAuthTag(new Uint8Array(Buffer.from(data.authTag, 'hex')));
const decrypted = decipher.update(data.encrypted, 'hex', 'utf8') + decipher.final('utf8');
return JSON.parse(decrypted);
}
/**
* Encrypts data using AES-256-OCB with the provided key.
* The key is derived from the password using scrypt with a random salt.
* @param {any} data JSON-serializable data to encrypt
* @param {string} keyString Encryption key as a UTF-8 string
* @returns {EncryptedData} Encrypted data in the format { salt, iv, encrypted, authTag }
*/
export function encryptObjectAes256(data, keyString) {
const salt = new Uint8Array(crypto.randomBytes(SALT_LENGTH));
const iv = new Uint8Array(crypto.randomBytes(12));
const key = new Uint8Array(crypto.scryptSync(keyString, salt, KEY_LENGTH));
const cipher = crypto.createCipheriv('aes-256-ocb', key, iv, { authTagLength: 16 });
const encrypted = cipher.update(JSON.stringify(data), 'utf8', 'hex') + cipher.final('hex');
const authTag = cipher.getAuthTag().toString('hex');
const saltString = Buffer.from(salt).toString('hex');
const ivString = Buffer.from(iv).toString('hex');
return { salt: saltString, iv: ivString, encrypted, authTag };
}
/**
* Checks if the given object is an encrypted data object by verifying it has the required properties and that they are valid hex strings.
* @param {EncryptedData} data Data object to check
* @returns {boolean} True if the data is in the format of encrypted data, false otherwise
*/
export function isEncryptedData(data) {
if (!data || typeof data !== 'object' || Array.isArray(data)) {
return false;
}
const requiredProps = ['salt', 'iv', 'encrypted', 'authTag'];
for (const prop of requiredProps) {
if (!Object.hasOwn(data, prop)) {
return false;
}
const value = data[prop];
if (typeof value !== 'string' || !/^[0-9a-fA-F]+$/.test(value)) {
return false;
}
}
return true;
}
+179
View File
@@ -0,0 +1,179 @@
import { describe, test, expect } from '@jest/globals';
import { encryptObjectAes256, decryptObjectAes256, isEncryptedData } from '../src/util-crypto.js';
describe('encryptObjectAes256', () => {
test('returns an object with salt, iv, encrypted, and authTag properties', () => {
const result = encryptObjectAes256({ hello: 'world' }, 'secret');
expect(result).toBeInstanceOf(Object);
expect(typeof result.salt).toBe('string');
expect(typeof result.iv).toBe('string');
expect(typeof result.encrypted).toBe('string');
expect(typeof result.authTag).toBe('string');
});
test('all properties are valid hex strings', () => {
const result = encryptObjectAes256({ hello: 'world' }, 'secret');
expect(result.salt).toMatch(/^[0-9a-f]+$/i);
expect(result.iv).toMatch(/^[0-9a-f]+$/i);
expect(result.encrypted).toMatch(/^[0-9a-f]+$/i);
expect(result.authTag).toMatch(/^[0-9a-f]+$/i);
});
test('produces different salt and IV each call', () => {
const a = encryptObjectAes256({ value: 42 }, 'key');
const b = encryptObjectAes256({ value: 42 }, 'key');
expect(a.salt).not.toBe(b.salt);
expect(a.iv).not.toBe(b.iv);
});
test('salt is 32 bytes (64 hex characters)', () => {
const result = encryptObjectAes256({}, 'anykey');
expect(result.salt).toHaveLength(64);
});
test('IV is 12 bytes (24 hex characters)', () => {
const result = encryptObjectAes256({}, 'anykey');
expect(result.iv).toHaveLength(24);
});
test('authTag is 16 bytes (32 hex characters)', () => {
const result = encryptObjectAes256({}, 'anykey');
expect(result.authTag).toHaveLength(32);
});
});
describe('decryptObjectAes256', () => {
test('round-trips a plain object', () => {
const original = { foo: 'bar', num: 123 };
const encrypted = encryptObjectAes256(original, 'mypassword');
const decrypted = decryptObjectAes256(encrypted, 'mypassword');
expect(decrypted).toEqual(original);
});
test('round-trips a nested object', () => {
const original = { a: { b: { c: [1, 2, 3] } } };
const encrypted = encryptObjectAes256(original, 'nestedkey');
const decrypted = decryptObjectAes256(encrypted, 'nestedkey');
expect(decrypted).toEqual(original);
});
test('round-trips a string value', () => {
const original = 'hello world';
const encrypted = encryptObjectAes256(original, 'strkey');
const decrypted = decryptObjectAes256(encrypted, 'strkey');
expect(decrypted).toBe(original);
});
test('round-trips a number value', () => {
const original = 9007199254740991;
const encrypted = encryptObjectAes256(original, 'numkey');
const decrypted = decryptObjectAes256(encrypted, 'numkey');
expect(decrypted).toBe(original);
});
test('round-trips an array', () => {
const original = [1, 'two', { three: 3 }];
const encrypted = encryptObjectAes256(original, 'arrkey');
const decrypted = decryptObjectAes256(encrypted, 'arrkey');
expect(decrypted).toEqual(original);
});
test('round-trips null', () => {
const encrypted = encryptObjectAes256(null, 'nullkey');
const decrypted = decryptObjectAes256(encrypted, 'nullkey');
expect(decrypted).toBeNull();
});
test('round-trips boolean false', () => {
const encrypted = encryptObjectAes256(false, 'boolkey');
const decrypted = decryptObjectAes256(encrypted, 'boolkey');
expect(decrypted).toBe(false);
});
test('throws with wrong key (auth tag mismatch)', () => {
const encrypted = encryptObjectAes256({ secret: 'data' }, 'correctkey');
expect(() => decryptObjectAes256(encrypted, 'wrongkey')).toThrow();
});
test('throws when authTag is tampered', () => {
const encrypted = encryptObjectAes256({ v: 1 }, 'k');
const tamperedTag = encrypted.authTag.slice(0, -2) + (encrypted.authTag.slice(-2) === 'ff' ? '00' : 'ff');
const tampered = { ...encrypted, authTag: tamperedTag };
expect(() => decryptObjectAes256(tampered, 'k')).toThrow();
});
test('throws when ciphertext is tampered', () => {
const encrypted = encryptObjectAes256({ v: 'hello' }, 'k');
const tamperedCipher = encrypted.encrypted.slice(0, -2) + (encrypted.encrypted.slice(-2) === 'ff' ? '00' : 'ff');
const tampered = { ...encrypted, encrypted: tamperedCipher };
expect(() => decryptObjectAes256(tampered, 'k')).toThrow();
});
});
describe('isEncryptedData', () => {
test('returns true for a valid encrypted object', () => {
const encrypted = encryptObjectAes256({ a: 1 }, 'key');
expect(isEncryptedData(encrypted)).toBe(true);
});
test('returns false for a plain string', () => {
expect(isEncryptedData('hello world')).toBe(false);
});
test('returns false for null', () => {
expect(isEncryptedData(null)).toBe(false);
});
test('returns false for an array', () => {
expect(isEncryptedData(['ab', 'cd', 'ef', '12'])).toBe(false);
});
test('returns false for a number', () => {
expect(isEncryptedData(42)).toBe(false);
});
test('returns false when a required property is missing', () => {
const encrypted = encryptObjectAes256({ a: 1 }, 'key');
const { salt: _salt, ...withoutSalt } = encrypted;
expect(_salt).toBeDefined();
expect(isEncryptedData(withoutSalt)).toBe(false);
const { iv: _iv, ...withoutIv } = encrypted;
expect(_iv).toBeDefined();
expect(isEncryptedData(withoutIv)).toBe(false);
const { encrypted: _enc, ...withoutEncrypted } = encrypted;
expect(_enc).toBeDefined();
expect(isEncryptedData(withoutEncrypted)).toBe(false);
const { authTag: _tag, ...withoutAuthTag } = encrypted;
expect(_tag).toBeDefined();
expect(isEncryptedData(withoutAuthTag)).toBe(false);
});
test('returns false when a property contains non-hex characters', () => {
const base = encryptObjectAes256({ a: 1 }, 'key');
expect(isEncryptedData({ ...base, salt: 'zzzz' })).toBe(false);
expect(isEncryptedData({ ...base, iv: 'zzzz' })).toBe(false);
expect(isEncryptedData({ ...base, encrypted: 'zzzz' })).toBe(false);
expect(isEncryptedData({ ...base, authTag: 'zzzz' })).toBe(false);
});
test('returns false when a property is an empty string', () => {
const base = encryptObjectAes256({ a: 1 }, 'key');
expect(isEncryptedData({ ...base, salt: '' })).toBe(false);
expect(isEncryptedData({ ...base, iv: '' })).toBe(false);
expect(isEncryptedData({ ...base, authTag: '' })).toBe(false);
});
test('returns true for valid hex values with uppercase characters', () => {
const base = encryptObjectAes256({ a: 1 }, 'key');
const upper = {
salt: base.salt.toUpperCase(),
iv: base.iv.toUpperCase(),
encrypted: base.encrypted.toUpperCase(),
authTag: base.authTag.toUpperCase(),
};
expect(isEncryptedData(upper)).toBe(true);
});
});