A modern, self-hosted backup solution for secure, encrypted backups across local and cloud storage.
refactor: request singing method of agent/server communication
towfiqie7ed29546d79
diff --git a/backend/__tests__/managers/SecurityKeyManager.test.ts b/backend/__tests__/managers/SecurityKeyManager.test.tsindex 1c9938b..332c286 100644--- a/backend/__tests__/managers/SecurityKeyManager.test.ts+++ b/backend/__tests__/managers/SecurityKeyManager.test.ts@@ -1,29 +1,4 @@-import path from 'path';-import { promises as fs } from 'fs';import crypto from 'crypto';-import Cryptr from 'cryptr';--const mockDataDir = path.join('/tmp', 'pluton-test-data');-const mockConfigDir = path.join('/tmp', 'pluton-test-config');--// Mock AppPaths BEFORE any imports that depend on it-jest.mock('../../src/utils/AppPaths', () => ({- appPaths: {- getDataDir: jest.fn(() => mockDataDir),- getConfigDir: jest.fn(() => mockConfigDir),- getBaseDir: jest.fn(),- getDbDir: jest.fn(),- getSchedulesPath: jest.fn(),- getLogsDir: jest.fn(),- getProgressDir: jest.fn(),- getStatsDir: jest.fn(),- getTempDir: jest.fn(),- getDownloadsDir: jest.fn(),- getRestoresDir: jest.fn(),- getSyncDir: jest.fn(),- getRescueDir: jest.fn(),- },-}));// Mock ConfigService BEFORE any imports that depend on itjest.mock('../../src/services/ConfigService', () => ({@@ -45,82 +20,26 @@ jest.mock('../../src/services/ConfigService', () => ({},}));-// IMPORTANT: mock 'fs' (not 'fs/promises') to match the implementation import-jest.mock('fs', () => ({- promises: {- readFile: jest.fn(),- writeFile: jest.fn(),- access: jest.fn(),- },-}));--// Mock crypto and cryptr-jest.mock('crypto');-jest.mock('cryptr');-describe('SecurityKeyManager', () => {- const keysFilePath = path.join(mockDataDir, 'keys.json');- const fakeKeyPair = {- publicKey: '---BEGIN FAKE PUBLIC KEY---',- privateKey: '---BEGIN FAKE PRIVATE KEY---',- };-- let mockFileSystem: Record<string, string>;let securityKeyManager: any;- const applyFsMocks = () => {- (fs.readFile as jest.Mock).mockImplementation(async (filePath: string, encoding?: string) => {- if (mockFileSystem[filePath]) return mockFileSystem[filePath];- const error = new Error(`ENOENT: no such file or directory`);- (error as any).code = 'ENOENT';- throw error;- });-- (fs.writeFile as jest.Mock).mockImplementation(async (filePath: string, data: string) => {- mockFileSystem[filePath] = data;- });+ // Per-device signing key used for all tests+ const testSigningKey = 'per-device-test-signing-key-abc123';- (fs.access as jest.Mock).mockImplementation(async (filePath: string) => {- if (!mockFileSystem[filePath]) {- const error = new Error('File not found');- (error as any).code = 'ENOENT';- throw error;- }- // If it exists, resolve with no error- return;- });+ /** Helper: compute the expected HMAC-SHA256 for given parts joined by newline. */+ const expectedHMAC = (...parts: string[]): string => {+ const hmac = crypto.createHmac('sha256', testSigningKey);+ hmac.update(parts.join('\n'));+ return hmac.digest('base64');};beforeAll(async () => {- // Import SecurityKeyManager after setting up module mocksconst module = await import('../../src/managers/SecurityKeyManager');securityKeyManager = module.securityKeyManager;-- // Allow async constructor loadKeys to settle (it will fail silently with no keys)- await new Promise(resolve => setImmediate(resolve));});beforeEach(() => {jest.clearAllMocks();- mockFileSystem = {};-- // Re-apply fs mocks after clearing- applyFsMocks();-- // Re-apply Cryptr mock after clearing- (Cryptr as unknown as jest.Mock).mockImplementation(() => ({- encrypt: jest.fn((data: string) => `encrypted-${data}`),- decrypt: jest.fn((data: string) => data.replace('encrypted-', '')),- }));-- // Re-apply crypto mocks after clearing- (crypto.generateKeyPairSync as unknown as jest.Mock).mockReturnValue(fakeKeyPair);- (crypto.sign as unknown as jest.Mock).mockReturnValue(Buffer.from('fake-signature'));- (crypto.verify as unknown as jest.Mock).mockReturnValue(true);-- // Reset internal state on the singleton- (securityKeyManager as any).keyData = null;- (securityKeyManager as any).decryptedPrivateKey = null;});it('should be a singleton', async () => {@@ -128,105 +47,183 @@ describe('SecurityKeyManager', () => {expect(module.securityKeyManager).toBe(securityKeyManager);});+ // ========================================================================+ // setupInitialKeys & getPublicKey+ // ========================================================================+describe('setupInitialKeys', () => {- it('should generate, encrypt, and save keys if keys.json does not exist', async () => {+ it('should be a no-op that resolves without error', async () => {+ const consoleSpy = jest.spyOn(console, 'log').mockImplementation();await securityKeyManager.setupInitialKeys();-- expect(crypto.generateKeyPairSync).toHaveBeenCalledWith('ed25519', expect.any(Object));- expect(Cryptr).toHaveBeenCalledWith('test-secret-key');- expect(fs.writeFile).toHaveBeenCalledTimes(1);- expect(fs.writeFile).toHaveBeenCalledWith(- keysFilePath,- expect.stringContaining(fakeKeyPair.publicKey),- { mode: 0o600 }+ expect(consoleSpy).toHaveBeenCalledWith(+ expect.stringContaining('HMAC-SHA256'));- expect(securityKeyManager.getPublicKey()).toBe(fakeKeyPair.publicKey);+ consoleSpy.mockRestore();+ });+ });++ describe('getPublicKey', () => {+ it('should return null (no Ed25519 keys)', () => {+ expect(securityKeyManager.getPublicKey()).toBeNull();});+ });- it('should not write keys if keys.json already exists', async () => {- // Pretend the file already exists with both required fields- mockFileSystem[keysFilePath] = JSON.stringify({- publicKey: 'existing',- encryptedPrivateKey: 'existing-encrypted',- });- // Access should succeed- (fs.access as jest.Mock).mockResolvedValue(undefined);+ // ========================================================================+ // Command Signing & Verification (Server → Agent)+ // ========================================================================++ describe('signCommand / verifyCommand', () => {+ const timestamp = '1700000000000';+ const commandID = 'cmd-abc-123';+ const commandType = 'backup:PERFORM_BACKUP';+ const payloadJSON = JSON.stringify({ planId: 'plan-1', backupId: 'bk-1' });++ it('should return a base64 HMAC-SHA256 signature for a command', () => {+ const sig = securityKeyManager.signCommand(testSigningKey, timestamp, commandID, commandType, payloadJSON);+ expect(sig).toBe(expectedHMAC(timestamp, commandID, commandType, payloadJSON));+ // Must be valid base64+ expect(() => Buffer.from(sig, 'base64')).not.toThrow();+ });- await securityKeyManager.setupInitialKeys();+ it('should verify a valid command signature', () => {+ const sig = securityKeyManager.signCommand(testSigningKey, timestamp, commandID, commandType, payloadJSON);+ const isValid = securityKeyManager.verifyCommand(testSigningKey, sig, timestamp, commandID, commandType, payloadJSON);+ expect(isValid).toBe(true);+ });++ it('should reject a tampered command signature', () => {+ const sig = securityKeyManager.signCommand(testSigningKey, timestamp, commandID, commandType, payloadJSON);+ const isValid = securityKeyManager.verifyCommand(testSigningKey, sig, timestamp, commandID, 'backup:DELETE_BACKUP', payloadJSON);+ expect(isValid).toBe(false);+ });++ it('should reject a completely invalid signature', () => {+ const isValid = securityKeyManager.verifyCommand(testSigningKey, 'bm90LXZhbGlk', timestamp, commandID, commandType, payloadJSON);+ expect(isValid).toBe(false);+ });++ it('should produce different signatures for different payloads', () => {+ const sig1 = securityKeyManager.signCommand(testSigningKey, timestamp, commandID, commandType, '{"a":1}');+ const sig2 = securityKeyManager.signCommand(testSigningKey, timestamp, commandID, commandType, '{"a":2}');+ expect(sig1).not.toBe(sig2);+ });++ it('should produce different signatures for different signing keys', () => {+ const sig1 = securityKeyManager.signCommand('device-key-1', timestamp, commandID, commandType, payloadJSON);+ const sig2 = securityKeyManager.signCommand('device-key-2', timestamp, commandID, commandType, payloadJSON);+ expect(sig1).not.toBe(sig2);+ });- expect(crypto.generateKeyPairSync).not.toHaveBeenCalled();- expect(fs.writeFile).not.toHaveBeenCalled();+ it('should not verify with a different signing key', () => {+ const sig = securityKeyManager.signCommand('device-key-1', timestamp, commandID, commandType, payloadJSON);+ const isValid = securityKeyManager.verifyCommand('device-key-2', sig, timestamp, commandID, commandType, payloadJSON);+ expect(isValid).toBe(false);});});- describe('Key Loading and Retrieval', () => {- it('should load keys from file on initialization', async () => {- mockFileSystem[keysFilePath] = JSON.stringify({- publicKey: 'loaded-public-key',- encryptedPrivateKey: 'encrypted-loaded-private-key',- });+ // ========================================================================+ // Request Verification (Agent → Server)+ // ========================================================================- // Manually call loadKeys to simulate fresh initialization- await (securityKeyManager as any).loadKeys();+ describe('verifyRequest', () => {+ const timestamp = '1700000000000';+ const method = 'POST';+ const path = '/api/agent/events';+ const body = JSON.stringify({ status: 'ok' });- expect(fs.readFile).toHaveBeenCalledWith(keysFilePath, 'utf-8');- expect(securityKeyManager.getPublicKey()).toBe('loaded-public-key');+ it('should verify a correctly signed request', () => {+ const sig = expectedHMAC(timestamp, method, path, body);+ expect(securityKeyManager.verifyRequest(testSigningKey, sig, timestamp, method, path, body)).toBe(true);});- it('should decrypt and cache the private key on first request', async () => {- mockFileSystem[keysFilePath] = JSON.stringify({- publicKey: 'loaded-public-key',- encryptedPrivateKey: 'encrypted-loaded-private-key',- });+ it('should reject a request with wrong method', () => {+ const sig = expectedHMAC(timestamp, method, path, body);+ expect(securityKeyManager.verifyRequest(testSigningKey, sig, timestamp, 'GET', path, body)).toBe(false);+ });- await (securityKeyManager as any).loadKeys();+ it('should reject a request with wrong path', () => {+ const sig = expectedHMAC(timestamp, method, path, body);+ expect(securityKeyManager.verifyRequest(testSigningKey, sig, timestamp, method, '/api/other', body)).toBe(false);+ });- const privateKey1 = (securityKeyManager as any).getPrivateKey();- const privateKey2 = (securityKeyManager as any).getPrivateKey();+ it('should reject a request with tampered body', () => {+ const sig = expectedHMAC(timestamp, method, path, body);+ expect(securityKeyManager.verifyRequest(testSigningKey, sig, timestamp, method, path, '{"status":"hacked"}')).toBe(false);+ });- expect(Cryptr).toHaveBeenCalledWith('test-secret-key');- expect(privateKey1).toBe('loaded-private-key');- expect(privateKey2).toBe('loaded-private-key');+ it('should handle empty body for GET requests', () => {+ const sig = expectedHMAC(timestamp, 'GET', '/api/agent/poll', '');+ expect(securityKeyManager.verifyRequest(testSigningKey, sig, timestamp, 'GET', '/api/agent/poll', '')).toBe(true);+ });++ it('should reject verification with wrong signing key', () => {+ const sig = expectedHMAC(timestamp, method, path, body);+ expect(securityKeyManager.verifyRequest('wrong-key', sig, timestamp, method, path, body)).toBe(false);});});- describe('Crypto Operations', () => {- beforeEach(async () => {- mockFileSystem[keysFilePath] = JSON.stringify({- publicKey: fakeKeyPair.publicKey,- encryptedPrivateKey: `encrypted-${fakeKeyPair.privateKey}`,- });- await (securityKeyManager as any).loadKeys();+ // ========================================================================+ // Timestamp Validation+ // ========================================================================++ describe('validateTimestamp', () => {+ it('should return null for a timestamp within the skew window', () => {+ const now = Date.now().toString();+ expect(securityKeyManager.validateTimestamp(now)).toBeNull();});- it('should sign a payload using the decrypted private key', () => {- const payload = { data: 'sign this' };- const signature = securityKeyManager.signPayload(payload);+ it('should return null for a timestamp slightly in the past (< 5 min)', () => {+ const fourMinAgo = (Date.now() - 4 * 60 * 1000).toString();+ expect(securityKeyManager.validateTimestamp(fourMinAgo)).toBeNull();+ });- expect(crypto.sign).toHaveBeenCalledTimes(1);- expect(crypto.sign).toHaveBeenCalledWith(- null,- Buffer.from(JSON.stringify(payload)),- fakeKeyPair.privateKey- );- expect(signature).toBe(Buffer.from('fake-signature').toString('base64'));+ it('should return an error string for a timestamp too far in the past (> 5 min)', () => {+ const sixMinAgo = (Date.now() - 6 * 60 * 1000).toString();+ const result = securityKeyManager.validateTimestamp(sixMinAgo);+ expect(result).not.toBeNull();+ expect(result).toContain('skew');});- it('should verify a payload signature', () => {- const payload = { data: 'verify this' };- const signature = 'base64-signature';- const publicKey = 'some-public-key';+ it('should return an error string for a timestamp too far in the future', () => {+ const sixMinAhead = (Date.now() + 6 * 60 * 1000).toString();+ const result = securityKeyManager.validateTimestamp(sixMinAhead);+ expect(result).not.toBeNull();+ expect(result).toContain('skew');+ });- const isValid = securityKeyManager.verifyPayload(payload, signature, publicKey);+ it('should return an error for non-numeric timestamp', () => {+ const result = securityKeyManager.validateTimestamp('not-a-number');+ expect(result).toBe('Invalid timestamp format');+ });- expect(crypto.verify).toHaveBeenCalledTimes(1);- expect(crypto.verify).toHaveBeenCalledWith(- null,- Buffer.from(JSON.stringify(payload)),- publicKey,- Buffer.from(signature, 'base64')- );- expect(isValid).toBe(true);+ it('should return an error for empty string', () => {+ const result = securityKeyManager.validateTimestamp('');+ expect(result).toBe('Invalid timestamp format');+ });+ });++ // ========================================================================+ // Legacy Compatibility+ // ========================================================================++ describe('signPayload (deprecated)', () => {+ it('should return empty string and warn', () => {+ const warnSpy = jest.spyOn(console, 'warn').mockImplementation();+ const payload = { data: 'sign this' };+ const sig = securityKeyManager.signPayload(payload);+ expect(sig).toBe('');+ expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('deprecated'));+ warnSpy.mockRestore();+ });+ });++ describe('verifyPayload (deprecated)', () => {+ it('should always return false', () => {+ const warnSpy = jest.spyOn(console, 'warn').mockImplementation();+ const isValid = securityKeyManager.verifyPayload({ data: 'test' }, 'signature', 'publicKey');+ expect(isValid).toBe(false);+ expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('deprecated'));+ warnSpy.mockRestore();});});});diff --git a/backend/src/managers/SecurityKeyManager.ts b/backend/src/managers/SecurityKeyManager.tsindex 8790434..f2e5c4f 100644--- a/backend/src/managers/SecurityKeyManager.ts+++ b/backend/src/managers/SecurityKeyManager.ts@@ -1,23 +1,21 @@-import { promises as fs } from 'fs';-import path from 'path';import crypto from 'crypto';-import Cryptr from 'cryptr';-import { appPaths } from '../utils/AppPaths';-import { configService } from '../services/ConfigService';--interface KeyData {- publicKey: string;- encryptedPrivateKey: string;-}+/**+ * SecurityKeyManager provides HMAC-SHA256 based signing and verification+ * for bidirectional command integrity between server and agent.+ *+ * Each device has its own unique signing key (stored encrypted in the DB).+ * All signing/verification methods require the caller to provide the+ * per-device signing key, ensuring key isolation between agents.+ *+ * Canonical message format (parts joined by newline):+ * - Server→Agent commands: timestamp + commandID + type + payloadJSON+ * - Agent→Server requests: timestamp + method + path + body+ */class SecurityKeyManager {private static instance: SecurityKeyManager;- private keyData: KeyData | null = null;- private decryptedPrivateKey: string | null = null;- private constructor() {- this.loadKeys();- }+ private constructor() {}public static getInstance(): SecurityKeyManager {if (!SecurityKeyManager.instance) {@@ -26,104 +24,120 @@ class SecurityKeyManager {return SecurityKeyManager.instance;}+ /**+ * No-op for backward compatibility.+ */public async setupInitialKeys(): Promise<void> {- const keysPath = path.join(appPaths.getDataDir(), 'keys.json');-- // 1. Check if keys already exist (Optimization)- try {- const existingContent = JSON.parse(await fs.readFile(keysPath, 'utf-8'));- if (existingContent.publicKey && existingContent.encryptedPrivateKey) {- console.log('[SecurityKeyManager] Keys already exist. Skipping generation.');- this.keyData = existingContent;- return;- }- } catch (e) {- // File might not exist or be corrupt, proceed to generate- }-- console.log('[SecurityKeyManager] Generating new Ed25519 key pair...');- const keyPair = crypto.generateKeyPairSync('ed25519', {- privateKeyEncoding: { type: 'pkcs8', format: 'pem' },- publicKeyEncoding: { type: 'spki', format: 'pem' },- });-- const cryptr = new Cryptr(configService.config.SECRET);- const encryptedPrivateKey = cryptr.encrypt(keyPair.privateKey);-- const newKeyData = {- publicKey: keyPair.publicKey,- encryptedPrivateKey: encryptedPrivateKey,- };-- // 2. MERGE with existing data (Crucial to preserve SECRET/APIKEY)- try {- let currentFileContent = {};- try {- const fileStr = await fs.readFile(keysPath, 'utf-8');- currentFileContent = JSON.parse(fileStr);- } catch (e) {- // File doesn't exist yet, that's fine- }-- const finalContent = {- ...currentFileContent,- ...newKeyData,- };-- await fs.writeFile(keysPath, JSON.stringify(finalContent, null, 2), { mode: 0o600 });- console.log(`[SecurityKeyManager] Cryptographic keys securely stored at ${keysPath}`);-- // Update local state- this.keyData = finalContent as KeyData; // Cast or update interface- } catch (error) {- console.error('[SecurityKeyManager] Error saving keys:', error);- throw error;- }+ console.log('[SecurityKeyManager] Using HMAC-SHA256 signing with per-device keys.');}- private async loadKeys(): Promise<void> {- try {- const keysPath = path.join(appPaths.getDataDir(), 'keys.json');- const fileContent = await fs.readFile(keysPath, 'utf-8');- this.keyData = JSON.parse(fileContent);- } catch (error) {}+ // ========================================================================+ // Core HMAC-SHA256 Operations+ // ========================================================================++ /**+ * Compute HMAC-SHA256 over parts joined by newline separator.+ * Returns base64-encoded signature.+ * @param signingKey - The per-device signing key to use+ */+ private computeHMAC(signingKey: string, ...parts: string[]): string {+ const message = parts.join('\n');+ const hmac = crypto.createHmac('sha256', signingKey);+ hmac.update(message);+ return hmac.digest('base64');}- public getPublicKey(): string | null {- return this.keyData?.publicKey || null;+ /**+ * Verify an HMAC-SHA256 signature using constant-time comparison.+ * @param signingKey - The per-device signing key to use+ */+ private verifyHMAC(signingKey: string, signature: string, ...parts: string[]): boolean {+ const expected = this.computeHMAC(signingKey, ...parts);+ const sigBuf = Buffer.from(signature, 'base64');+ const expectedBuf = Buffer.from(expected, 'base64');+ if (sigBuf.length !== expectedBuf.length) return false;+ return crypto.timingSafeEqual(sigBuf, expectedBuf);}- private getPrivateKey(): string {- if (this.decryptedPrivateKey) {- return this.decryptedPrivateKey;- }-- if (!this.keyData) {- throw new Error('Keys are not loaded.');- }-- try {- const cryptr = new Cryptr(configService.config.SECRET);- this.decryptedPrivateKey = cryptr.decrypt(this.keyData.encryptedPrivateKey);- return this.decryptedPrivateKey;- } catch (error) {- throw new Error('Failed to decrypt private key. The master SECRET may have changed.');- }+ // ========================================================================+ // Command Signing (Server → Agent)+ // ========================================================================++ /**+ * Sign a command being sent to an agent.+ * @param signingKey - The per-device signing key+ * @param timestamp - Unix milliseconds as string+ * @param commandID - Unique command identifier+ * @param commandType - Command type (e.g., "backup:PERFORM_BACKUP")+ * @param payloadJSON - JSON string of the command payload+ * @returns base64-encoded HMAC-SHA256 signature+ */+ public signCommand(+ signingKey: string,+ timestamp: string,+ commandID: string,+ commandType: string,+ payloadJSON: string+ ): string {+ return this.computeHMAC(signingKey, timestamp, commandID, commandType, payloadJSON);}- public signPayload(payload: object): string {- const privateKey = this.getPrivateKey();- const dataToSign = Buffer.from(JSON.stringify(payload));- const signature = crypto.sign(null, dataToSign, privateKey);-- return signature.toString('base64');+ /**+ * Verify a command signature.+ * @param signingKey - The per-device signing key+ */+ public verifyCommand(+ signingKey: string,+ signature: string,+ timestamp: string,+ commandID: string,+ commandType: string,+ payloadJSON: string+ ): boolean {+ return this.verifyHMAC(signingKey, signature, timestamp, commandID, commandType, payloadJSON);}- public verifyPayload(payload: object, signature: string, publicKey: string): boolean {- const dataToVerify = Buffer.from(JSON.stringify(payload));- const signatureBuffer = Buffer.from(signature, 'base64');+ // ========================================================================+ // Request Signing (Agent → Server)+ // ========================================================================++ /**+ * Verify a signed request from an agent.+ * @param signingKey - The per-device signing key+ * @param signature - base64-encoded HMAC-SHA256 from X-Signature header+ * @param timestamp - Unix milliseconds string from X-Signature-Timestamp header+ * @param method - HTTP method (GET, POST, etc.)+ * @param path - Request path (e.g., "/api/agent/events")+ * @param body - Request body as string (empty string for GET/no-body requests)+ * @returns true if signature is valid+ */+ public verifyRequest(+ signingKey: string,+ signature: string,+ timestamp: string,+ method: string,+ path: string,+ body: string+ ): boolean {+ return this.verifyHMAC(signingKey, signature, timestamp, method, path, body);+ }- return crypto.verify(null, dataToVerify, publicKey, signatureBuffer);+ /**+ * Validate that a timestamp is within the acceptable skew window (±5 minutes).+ * @param timestampStr - Unix milliseconds as string+ * @returns null if valid, error message string if invalid+ */+ public validateTimestamp(timestampStr: string): string | null {+ const ts = parseInt(timestampStr, 10);+ if (isNaN(ts)) {+ return 'Invalid timestamp format';+ }+ const skew = Math.abs(Date.now() - ts);+ const maxSkewMs = 5 * 60 * 1000; // 5 minutes+ if (skew > maxSkewMs) {+ return `Timestamp skew ${skew}ms exceeds maximum ${maxSkewMs}ms`;+ }+ return null;}}