Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(baileys): write auth state atomically and keep unreadable creds
Yudhi Armyndharisd58a7548ca20
diff --git a/docs/03-system-architecture.md b/docs/03-system-architecture.mdindex 4bd393f14..2265b7a6d 100644--- a/docs/03-system-architecture.md+++ b/docs/03-system-architecture.md@@ -1090,7 +1090,9 @@ export class WhatsAppWebJsAdapter implements IWhatsAppEngine {```typescript// engine/adapters/baileys.adapter.ts-import makeWASocket, { DisconnectReason, useMultiFileAuthState } from '@whiskeysockets/baileys';+import makeWASocket, { DisconnectReason } from '@whiskeysockets/baileys';+import * as baileys from '@whiskeysockets/baileys';+import { useAtomicMultiFileAuthState } from './baileys-auth-store';import {IWhatsAppEngine,EngineEventCallbacks,@@ -1108,7 +1110,13 @@ export class BaileysAdapter implements IWhatsAppEngine {this.callbacks = callbacks;this.setStatus(EngineStatus.INITIALIZING);- const { state, saveCreds } = await useMultiFileAuthState(`${this.authDir}/${this.sessionId}`);+ // Same file layout as Baileys' useMultiFileAuthState, but every write is atomic and an+ // unparseable creds.json is moved aside with its key files before a new link starts.+ const { state, saveCreds } = await useAtomicMultiFileAuthState(+ `${this.authDir}/${this.sessionId}`,+ baileys,+ this.logger,+ );this.socket = makeWASocket({ auth: state });this.socket.ev.on('creds.update', saveCreds);this.setupEventHandlers();diff --git a/docs/05-database-design.md b/docs/05-database-design.mdindex 3aced1639..dac255f8b 100644--- a/docs/05-database-design.md+++ b/docs/05-database-design.md@@ -328,7 +328,7 @@ CREATE TABLE sessions (> The **types** above are illustrative — the schema is defined by the TypeORM entity (`src/modules/session/entities/session.entity.ts`) and column types are dialect-portable (`jsonColumnType()` → `simple-json`, dates via `DateTransformer`). The **column names are literal**: see the naming note in §5.3 below before writing SQL against any of these tables. The `sessions` entity declares only the index implied by the `UNIQUE` constraint on `name`; there are no separate `status`/`phone`/`createdAt` indexes.> [!NOTE]-> Auth state is **not** stored in this table. Both engines persist credentials on the **filesystem** (`whatsapp-web.js` LocalAuth; Baileys `useMultiFileAuthState`). The `baileys_stored_messages` table holds only Baileys' serialized message store (the library ships none), not credentials.+> Auth state is **not** stored in this table. Both engines persist credentials on the **filesystem**: `whatsapp-web.js` through LocalAuth, Baileys in a multi-file auth dir with the layout of its `useMultiFileAuthState`, written atomically. An unparseable Baileys `creds.json` is moved aside with its key files to `corrupt-<ms>-<suffix>/` and the session relinks by QR. The `baileys_stored_messages` table holds only Baileys' serialized message store (the library ships none), not credentials.**Session Status Values:**@@ -799,7 +799,7 @@ flowchart LRsubgraph FS["Engine Auth (not in sessions table)"]FSAUTH[whatsapp-web.js: filesystem LocalAuth]- BAUTH[Baileys: filesystem useMultiFileAuthState]+ BAUTH[Baileys: filesystem multi-file auth dir]endMemory -->|Sync| Persistentdiff --git a/src/engine/adapters/baileys-auth-store.spec.ts b/src/engine/adapters/baileys-auth-store.spec.tsnew file mode 100644index 000000000..99cdfb6b4--- /dev/null+++ b/src/engine/adapters/baileys-auth-store.spec.ts@@ -0,0 +1,179 @@+import * as fs from 'fs';+import * as os from 'os';+import * as path from 'path';+import { BufferJSON } from '@whiskeysockets/baileys';+import { type BaileysAuthLib, useAtomicMultiFileAuthState } from './baileys-auth-store';++describe('useAtomicMultiFileAuthState', () => {+ let dir: string;+ let lib: BaileysAuthLib;+ let initAuthCreds: jest.Mock;+ let fromObject: jest.Mock;+ let logger: { warn: jest.Mock; error: jest.Mock };++ const load = () => useAtomicMultiFileAuthState(dir, lib, logger);+ const write = (file: string, data: unknown) =>+ fs.writeFileSync(path.join(dir, file), JSON.stringify(data, BufferJSON.replacer));+ const leftovers = () => fs.readdirSync(dir).filter(f => f.endsWith('.tmp'));++ beforeEach(() => {+ dir = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'baileys-auth-')), 'session');+ initAuthCreds = jest.fn(() => ({ fresh: true }));+ fromObject = jest.fn((o: object) => ({ revived: o }));+ lib = { initAuthCreds, BufferJSON, proto: { Message: { AppStateSyncKeyData: { fromObject } } } } as never;+ logger = { warn: jest.fn(), error: jest.fn() };+ });++ afterEach(() => {+ jest.restoreAllMocks();+ fs.rmSync(path.dirname(dir), { recursive: true, force: true });+ });++ it('creates the folder and mints new creds on a first link', async () => {+ const { state } = await load();++ expect(state.creds).toEqual({ fresh: true });+ expect(initAuthCreds).toHaveBeenCalledTimes(1);+ expect(fs.statSync(dir).isDirectory()).toBe(true);+ });++ it('refuses a folder path that is a file', async () => {+ fs.mkdirSync(path.dirname(dir), { recursive: true });+ fs.writeFileSync(dir, 'x');++ await expect(load()).rejects.toThrow(/not a directory/);+ });++ it('saves creds atomically and loads them back with their Buffers', async () => {+ const first = await load();+ Object.assign(first.state.creds, { noiseKey: { private: Buffer.from([1, 2, 3]) } });+ await first.saveCreds();++ expect(leftovers()).toEqual([]);+ const second = await load();+ expect(initAuthCreds).toHaveBeenCalledTimes(1);+ expect(second.state.creds).toEqual({ fresh: true, noiseKey: { private: Buffer.from([1, 2, 3]) } });+ });++ it.each(['{"noiseKey":', '', 'null'])(+ 'moves an unusable creds.json (%j) aside with its key files and starts a new link',+ async raw => {+ fs.mkdirSync(path.join(dir, 'corrupt-1'), { recursive: true });+ const files = { 'creds.json': raw, 'pre-key-1.json': '{"k":1}', 'session-x.0.json': '{"s":1}' };+ for (const [name, body] of Object.entries(files)) fs.writeFileSync(path.join(dir, name), body);++ const { state } = await load();++ expect(state.creds).toEqual({ fresh: true });+ const entries = fs.readdirSync(dir);+ const quarantined = entries.filter(f => f.startsWith('corrupt-') && f !== 'corrupt-1');+ expect(quarantined).toHaveLength(1);+ expect(entries.sort()).toEqual(['corrupt-1', quarantined[0]].sort());+ expect(fs.readdirSync(path.join(dir, 'corrupt-1'))).toEqual([]);+ for (const [name, body] of Object.entries(files)) {+ expect(fs.readFileSync(path.join(dir, quarantined[0], name), 'utf-8')).toBe(body);+ }+ expect(await state.keys.get('session', ['x.0'])).toEqual({ 'x.0': null });+ expect(logger.error).toHaveBeenCalledWith(expect.stringContaining(quarantined[0]));+ },+ );++ it('keeps an unparseable creds.json in place until every key file has moved', async () => {+ fs.mkdirSync(dir, { recursive: true });+ const files = { 'creds.json': '{"noiseKey":', 'pre-key-1.json': '{"k":1}', 'session-x.0.json': '{"s":1}' };+ for (const [name, body] of Object.entries(files)) fs.writeFileSync(path.join(dir, name), body);+ // Both attempts land in the same millisecond, so the retry must not reuse the first attempt's folder name.+ const sameMs = () => jest.spyOn(Date, 'now').mockReturnValue(1_790_000_000_000);+ sameMs();+ // Directory order is filesystem-defined; list creds.json first, as a hash-ordered directory may.+ const readdir = fs.promises.readdir.bind(fs.promises) as (p: string) => Promise<string[]>;+ jest+ .spyOn(fs.promises, 'readdir')+ .mockImplementationOnce((async (p: string) => [+ 'creds.json',+ ...(await readdir(p)).filter(f => f !== 'creds.json'),+ ]) as never);+ const rename = fs.promises.rename.bind(fs.promises);+ jest+ .spyOn(fs.promises, 'rename')+ .mockImplementation(async (from, to) =>+ path.basename(String(from)) === 'session-x.0.json' ? Promise.reject(new Error('EBUSY')) : rename(from, to),+ );++ await expect(load()).rejects.toThrow('EBUSY');+ expect(fs.readFileSync(path.join(dir, 'creds.json'), 'utf-8')).toBe(files['creds.json']);+ expect(initAuthCreds).not.toHaveBeenCalled();++ jest.restoreAllMocks();+ sameMs();+ const { state } = await load();+ expect(state.creds).toEqual({ fresh: true });+ expect(fs.readdirSync(dir).every(f => f.startsWith('corrupt-'))).toBe(true);+ });++ it('fails instead of relinking when creds.json exists but cannot be read', async () => {+ fs.mkdirSync(path.join(dir, 'creds.json'), { recursive: true });++ await expect(load()).rejects.toThrow();+ expect(initAuthCreds).not.toHaveBeenCalled();+ });++ it('keeps the previous creds.json and no temp file when the write fails', async () => {+ fs.mkdirSync(dir, { recursive: true });+ write('creds.json', { old: true });+ const { state, saveCreds } = await load();+ Object.assign(state.creds, { old: false });+ jest.spyOn(fs.promises, 'rename').mockRejectedValueOnce(new Error('ENOSPC'));++ await expect(saveCreds()).rejects.toThrow('ENOSPC');++ expect(JSON.parse(fs.readFileSync(path.join(dir, 'creds.json'), 'utf-8'))).toEqual({ old: true });+ expect(leftovers()).toEqual([]);+ });++ it('leaves the last state after concurrent saves', async () => {+ const { state, saveCreds } = await load();+ const saves: Promise<void>[] = [];+ for (let i = 0; i < 20; i++) {+ Object.assign(state.creds, { counter: i });+ saves.push(saveCreds());+ }+ await Promise.all(saves);++ expect(JSON.parse(fs.readFileSync(path.join(dir, 'creds.json'), 'utf-8'))).toEqual({ fresh: true, counter: 19 });+ expect(leftovers()).toEqual([]);+ });++ it('reads key files in the Baileys multi-file layout and writes them back the same way', async () => {+ fs.mkdirSync(dir, { recursive: true });+ // Baileys maps '/' to '__' and ':' to '-' in file names.+ write('[email protected]', Buffer.from('abc'));+ write('app-state-sync-key-AAA__B.json', { keyData: 'k' });+ const { state } = await load();++ const sessions = await state.keys.get('session', ['123:[email protected]', 'missing']);+ expect(sessions).toEqual({ '123:[email protected]': Buffer.from('abc'), missing: null });+ const syncKeys = await state.keys.get('app-state-sync-key', ['AAA/B']);+ expect(syncKeys['AAA/B']).toEqual({ revived: { keyData: 'k' } });+ expect(fromObject).toHaveBeenCalledWith({ keyData: 'k' });++ await state.keys.set({ 'pre-key': { '7': { public: Buffer.from([7]), private: Buffer.from([8]) } } });+ expect(fs.existsSync(path.join(dir, 'pre-key-7.json'))).toBe(true);+ expect(await state.keys.get('pre-key', ['7'])).toEqual({+ '7': { public: Buffer.from([7]), private: Buffer.from([8]) },+ });+ expect(leftovers()).toEqual([]);++ await state.keys.set({ session: { '123:[email protected]': null } });+ expect(fs.existsSync(path.join(dir, '[email protected]'))).toBe(false);+ });++ it('reads an unparseable key file as absent', async () => {+ fs.mkdirSync(dir, { recursive: true });+ fs.writeFileSync(path.join(dir, 'pre-key-1.json'), '{');+ const { state } = await load();++ expect(await state.keys.get('pre-key', ['1'])).toEqual({ '1': null });+ expect(logger.warn).toHaveBeenCalled();+ });+});diff --git a/src/engine/adapters/baileys-auth-store.ts b/src/engine/adapters/baileys-auth-store.tsnew file mode 100644index 000000000..da6d8bba1--- /dev/null+++ b/src/engine/adapters/baileys-auth-store.ts@@ -0,0 +1,161 @@+import { promises as fsp } from 'fs';+import * as path from 'path';+import { randomBytes } from 'crypto';+import type * as BaileysLib from '@whiskeysockets/baileys';+import type { AuthenticationCreds, AuthenticationState, SignalDataTypeMap } from '@whiskeysockets/baileys';+import { type createLogger } from '../../common/services/logger.service';++/** The parts of the lazily loaded Baileys module the store needs (Baileys is ESM-only, never imported here). */+export type BaileysAuthLib = Pick<typeof BaileysLib, 'initAuthCreds' | 'BufferJSON' | 'proto'>;++/**+ * Per-file operation chains, module-level like Baileys' own file locks, so an old socket's in-flight+ * save and a reconnect's read of the same file stay ordered within this process.+ */+const fileChains = new Map<string, Promise<unknown>>();++function serialized<T>(file: string, task: () => Promise<T>): Promise<T> {+ const run = (fileChains.get(file) ?? Promise.resolve()).then(task);+ const tail = run.catch(() => undefined);+ fileChains.set(file, tail);+ void tail.then(() => {+ if (fileChains.get(file) === tail) fileChains.delete(file);+ });+ return run;+}++/**+ * Write to a sibling temp file, fsync it, then rename it over the target: a crash or a full disk+ * mid-write leaves the previous complete file, never a truncated one.+ */+async function writeFileAtomic(file: string, data: string): Promise<void> {+ const tmp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;+ try {+ const fh = await fsp.open(tmp, 'w', 0o600);+ try {+ await fh.writeFile(data);+ await fh.sync();+ } finally {+ await fh.close();+ }+ await fsp.rename(tmp, file);+ } catch (err) {+ await fsp.rm(tmp, { force: true });+ throw err;+ }+}++const isMissing = (err: unknown): boolean => (err as NodeJS.ErrnoException)?.code === 'ENOENT';++/**+ * Baileys' multi-file auth state (same folder layout and file names as its useMultiFileAuthState,+ * so existing auth dirs load unchanged) with two differences: every write is atomic, and a+ * creds.json that exists but does not parse is moved aside with its key files to `corrupt-<ms>-<suffix>/`+ * and logged before a new link is started, instead of being silently replaced by a fresh identity. A creds.json+ * that cannot be read for another reason (EACCES, EIO) fails the connect rather than relinking.+ */+export async function useAtomicMultiFileAuthState(+ folder: string,+ lib: BaileysAuthLib,+ logger: Pick<ReturnType<typeof createLogger>, 'warn' | 'error'>,+): Promise<{ state: AuthenticationState; saveCreds: () => Promise<void> }> {+ const { BufferJSON, proto, initAuthCreds } = lib;+ const filePath = (file: string): string => path.join(folder, file.replace(/\//g, '__').replace(/:/g, '-'));++ const writeData = (data: unknown, file: string): Promise<void> => {+ const target = filePath(file);+ const json = JSON.stringify(data, BufferJSON.replacer);+ return serialized(target, () => writeFileAtomic(target, json));+ };++ const readKey = (file: string): Promise<unknown> => {+ const target = filePath(file);+ return serialized(target, async () => {+ try {+ return JSON.parse(await fsp.readFile(target, 'utf-8'), BufferJSON.reviver) as unknown;+ } catch (err) {+ // A missing or unreadable key reads as absent, as in Baileys: the Signal session renegotiates.+ if (!isMissing(err)) logger.warn('Unreadable Baileys key file ignored', { file: target });+ return null;+ }+ });+ };++ const removeData = (file: string): Promise<void> => {+ const target = filePath(file);+ return serialized(target, () => fsp.rm(target, { force: true }).catch(() => undefined));+ };++ const folderInfo = await fsp.stat(folder).catch(() => undefined);+ if (folderInfo && !folderInfo.isDirectory()) {+ throw new Error(+ `found something that is not a directory at ${folder}, either delete it or specify a different location`,+ );+ }+ if (!folderInfo) await fsp.mkdir(folder, { recursive: true });++ const credsFile = filePath('creds.json');+ const creds = await serialized(credsFile, async (): Promise<AuthenticationCreds> => {+ let raw: string;+ try {+ raw = await fsp.readFile(credsFile, 'utf-8');+ } catch (err) {+ if (isMissing(err)) return initAuthCreds();+ throw err;+ }+ let parsed: unknown;+ try {+ parsed = JSON.parse(raw, BufferJSON.reviver);+ } catch {+ parsed = undefined;+ }+ // Baileys dereferences creds unconditionally, so `null` or a bare value is as unusable as bad JSON.+ if (parsed && typeof parsed === 'object') return parsed as AuthenticationCreds;+ // Move the key files aside too: a new identity must not reuse the old one's Signal sessions and pre-keys.+ const quarantined = await fsp.mkdtemp(path.join(folder, `corrupt-${Date.now()}-`));+ for (const entry of await fsp.readdir(folder)) {+ const from = path.join(folder, entry);+ if (!entry.startsWith('corrupt-') && from !== credsFile) await fsp.rename(from, path.join(quarantined, entry));+ }+ // creds.json goes last: an interrupted move keeps the trigger in place, so the next connect quarantines again.+ await fsp.rename(credsFile, path.join(quarantined, 'creds.json'));+ logger.error(+ `Stored Baileys credentials could not be parsed; moved them to ${quarantined}. The session needs a new QR link.`,+ );+ return initAuthCreds();+ });++ return {+ state: {+ creds,+ keys: {+ get: async <T extends keyof SignalDataTypeMap>(type: T, ids: string[]) => {+ const data: { [id: string]: SignalDataTypeMap[T] } = {};+ await Promise.all(+ ids.map(async id => {+ let value = await readKey(`${type}-${id}.json`);+ if (type === 'app-state-sync-key' && value) {+ value = proto.Message.AppStateSyncKeyData.fromObject(value);+ }+ data[id] = value as SignalDataTypeMap[T];+ }),+ );+ return data;+ },+ set: async data => {+ const tasks: Promise<void>[] = [];+ for (const category in data) {+ const entries = data[category as keyof SignalDataTypeMap] ?? {};+ for (const id in entries) {+ const value = entries[id];+ const file = `${category}-${id}.json`;+ tasks.push(value ? writeData(value, file) : removeData(file));+ }+ }+ await Promise.all(tasks);+ },+ },+ },+ saveCreds: () => writeData(creds, 'creds.json'),+ };+}diff --git a/src/engine/adapters/baileys-lifecycle.spec.ts b/src/engine/adapters/baileys-lifecycle.spec.tsnew file mode 100644index 000000000..7ab42e26a--- /dev/null+++ b/src/engine/adapters/baileys-lifecycle.spec.ts@@ -0,0 +1,30 @@+jest.mock('@whiskeysockets/baileys', () => ({ __esModule: true, initAuthCreds: jest.fn() }));+jest.mock('./baileys-auth-store', () => ({+ useAtomicMultiFileAuthState: jest.fn().mockRejectedValue(new Error('stop after auth load')),+}));++import * as BaileysLib from '@whiskeysockets/baileys';+import { useAtomicMultiFileAuthState } from './baileys-auth-store';+import { BaileysLifecycle, type BaileysLifecycleHost } from './baileys-lifecycle';++describe('BaileysLifecycle.connect', () => {+ it('loads the auth state through the atomic store with the session auth dir, library and logger', async () => {+ const logger = { log: jest.fn(), warn: jest.fn(), error: jest.fn(), debug: jest.fn() };+ const noCallback = (): undefined => undefined;+ const host = {+ authPath: '/data/baileys/session-sess-1',+ logger,+ config: { sessionId: 'sess-1' },+ getOnStateChanged: noCallback,+ getOnError: noCallback,+ } as unknown as BaileysLifecycleHost;++ await expect(new BaileysLifecycle(host).initialize()).rejects.toThrow('stop after auth load');++ expect(useAtomicMultiFileAuthState).toHaveBeenCalledTimes(1);+ const [folder, lib, authLogger] = jest.mocked(useAtomicMultiFileAuthState).mock.calls[0];+ expect(folder).toBe(host.authPath);+ expect(lib.initAuthCreds).toBe(BaileysLib.initAuthCreds);+ expect(authLogger).toBe(logger);+ });+});diff --git a/src/engine/adapters/baileys-lifecycle.ts b/src/engine/adapters/baileys-lifecycle.tsindex 762cd3413..c8dce3624 100644--- a/src/engine/adapters/baileys-lifecycle.ts+++ b/src/engine/adapters/baileys-lifecycle.ts@@ -15,6 +15,7 @@ import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error'import { createProxyDispatcher, hasUnauthenticatableSocks4Credentials } from '../../common/security/proxy-dispatcher';import { type createLogger } from '../../common/services/logger.service';import { BaileysAdapterConfig } from '../types/baileys.types';+import { useAtomicMultiFileAuthState } from './baileys-auth-store';import { createBaileysLogger } from './baileys-logger';import { BaileysVersionResolver } from './baileys-version-resolver';import { unappliedPatches, unappliedPatchesMessage } from './engine-patch-status';@@ -296,7 +297,7 @@ export class BaileysLifecycle {}}const b = await this.loadLib();- const { state, saveCreds } = await b.useMultiFileAuthState(this.host.authPath);+ const { state, saveCreds } = await useAtomicMultiFileAuthState(this.host.authPath, b, this.host.logger);const version = await this.versionResolver.resolve(b, { dispatcher: this.fetchDispatcher() });// BaileysLogger matches ILogger exactly; cast needed because the module resolves the type// through a deep import path that TypeScript does not auto-unify here. Shared by the keydiff --git a/src/engine/adapters/baileys.adapter.spec.ts b/src/engine/adapters/baileys.adapter.spec.tsindex 73566fcaf..d7bdcebb7 100644--- a/src/engine/adapters/baileys.adapter.spec.ts+++ b/src/engine/adapters/baileys.adapter.spec.ts@@ -101,6 +101,16 @@ jest.mock('qrcode', () => {return { ...actual, toDataURL: jest.fn().mockImplementation(actual.toDataURL) };});+// The auth store takes the loaded library as an argument; route it through the library mock's+// useMultiFileAuthState so the tests below keep controlling the auth state in one place.+jest.mock('./baileys-auth-store', () => ({+ useAtomicMultiFileAuthState: jest.fn((folder: string): unknown =>+ jest+ .requireMock<{ useMultiFileAuthState: (f: string) => unknown }>('@whiskeysockets/baileys')+ .useMultiFileAuthState(folder),+ ),+}));+jest.mock('@whiskeysockets/baileys', () => ({__esModule: true,default: jest.fn(() => {