Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.md
index 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.md
index 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 LR
subgraph FS["Engine Auth (not in sessions table)"]
FSAUTH[whatsapp-web.js: filesystem LocalAuth]
- BAUTH[Baileys: filesystem useMultiFileAuthState]
+ BAUTH[Baileys: filesystem multi-file auth dir]
end
Memory -->|Sync| Persistent
diff --git a/src/engine/adapters/baileys-auth-store.spec.ts b/src/engine/adapters/baileys-auth-store.spec.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 key
diff --git a/src/engine/adapters/baileys.adapter.spec.ts b/src/engine/adapters/baileys.adapter.spec.ts
index 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(() => {