Skip to main content

​
Overview

The LocalAuth class provides persistent authentication storage using the local filesystem. It automatically encrypts session data using AES-256-GCM encryption with your bot’s UUID as the encryption key, ensuring sensitive credentials are protected at rest.

​
Key Features

  • Encrypted Storage: All session data is encrypted using AES-256-GCM
  • File-based Persistence: Sessions stored as encrypted files in a dedicated directory
  • Automatic Hashing: Keys are MD5-hashed for consistent filenames
  • In-memory Cache: Reduces disk I/O with intelligent caching
  • Zero Configuration: Works out of the box with minimal setup
LocalAuth is the default authentication strategy and is ideal for development, testing, and single-server deployments.

​
Constructor

​
new LocalAuth(uuid, directory)

Creates a new LocalAuth instance for managing bot authentication on the filesystem.
​
uuid
UUID
required
A valid UUID (v4) that uniquely identifies this bot instance. This UUID is used as the encryption key and as a subdirectory name.
​
directory
string
required
The base directory where encrypted session files will be stored. Can be relative or absolute. A subdirectory named after the UUID will be created inside this directory.

​
Example

import { Bot, LocalAuth } from "wapi";
import { randomUUID } from "node:crypto";

const uuid = randomUUID();
const auth = new LocalAuth(uuid, "./sessions");

const bot = new Bot({ auth });

​
Throws

  • Error: If the provided UUID is not a valid UUID v4 format

​
Properties

​
uuid

​
uuid
UUID
The UUID associated with this authentication instance. This is the same UUID provided to the constructor.
const auth = new LocalAuth(uuid, "./sessions");
console.log(auth.uuid); // "550e8400-e29b-41d4-a716-446655440000"

​
Methods

​
init()

Initializes the authentication system by loading or creating credentials and setting up the key store. 
init(): Promise<IBotAuthInit>

​
Behavior

  1. Directory Creation: Creates the session directory if it doesn’t exist
  2. Credential Loading: Attempts to load existing credentials from disk
  3. New Session: If no credentials exist, generates new authentication credentials
  4. Key Store Setup: Initializes the Signal protocol key store for WhatsApp encryption

​
Returns

​
Example

import { LocalAuth } from "wapi";
import { randomUUID } from "node:crypto";

const auth = new LocalAuth(randomUUID(), "./sessions");

// Initialize authentication
const { creds, keys } = await auth.init();

console.log("Credentials loaded:", !!creds);
console.log("Keys initialized:", !!keys);
This method is called automatically by the Bot class during initialization. You rarely need to call it directly.

​
save()

Persists the current authentication credentials to disk. 
save(): Promise<void>

​
Behavior

  1. Validation: Ensures credentials have been loaded via init()
  2. Serialization: Converts credentials to JSON format
  3. Encryption: Encrypts the data using AES-256-GCM
  4. Persistence: Writes the encrypted data to disk
  5. Cache Update: Updates the in-memory cache

​
Throws

  • Error: If credentials haven’t been initialized (“Credentials not loaded.”)

​
Example

import { LocalAuth } from "wapi";
import { randomUUID } from "node:crypto";

const auth = new LocalAuth(randomUUID(), "./sessions");

// Initialize and save
await auth.init();
await auth.save();

console.log("Session saved successfully");
The Bot class automatically saves credentials when authentication state changes. Manual calls to save() are typically unnecessary.

​
remove()

Deletes all authentication data from disk and clears the cache. 
remove(): Promise<void>

​
Behavior

  1. Directory Removal: Recursively deletes the entire session directory
  2. Cache Clearing: Clears the in-memory cache
  3. Force Delete: Uses force: true to ignore missing files

​
Example

import { LocalAuth } from "wapi";
import { randomUUID } from "node:crypto";

const uuid = randomUUID();
const auth = new LocalAuth(uuid, "./sessions");

// Remove session data
await auth.remove();
console.log("Session removed");
This operation is irreversible. After calling remove(), the bot will need to re-authenticate (scan QR code or enter OTP) on next startup.

​
Storage Details

​
Directory Structure

./sessions/
└── 550e8400-e29b-41d4-a716-446655440000/
    ├── 5f4dcc3b5aa765d61d8327deb882cf99.enc
    ├── 098f6bcd4621d373cade4e832627b4f6.enc
    └── ... (other encrypted files)

​
File Naming

  • Each key (e.g., “creds”, “pre-key-1”, “session-2”) is MD5-hashed
  • Files are stored with .enc extension
  • Example: creds → 5f4dcc3b5aa765d61d8327deb882cf99.enc

​
Encryption

  • Cipher: AES-256-GCM (Galois/Counter Mode)
  • Key: Derived from the bot’s UUID
  • Security: Authenticated encryption with associated data (AEAD)

​
Complete Example

import { Bot, LocalAuth } from "wapi";
import { randomUUID } from "node:crypto";

const uuid = randomUUID();
const auth = new LocalAuth(uuid, "./sessions");

const bot = new Bot({ auth });

bot.on("qr", (qr) => {
  console.log("Scan this QR code:", qr);
});

bot.on("open", (account) => {
  console.log("Connected as:", account.name);
});

bot.command("hello", (ctx) => {
  ctx.reply("Hello from LocalAuth!");
});

bot.launch();

​
Advantages

  • No external dependencies
  • Works out of the box
  • Perfect for development
  • Easy to backup (just copy directory)

​
Limitations

LocalAuth is not suitable for distributed systems or multi-server deployments. For those scenarios, use RedisAuth or MongoAuth.
  • Single Server Only: Cannot share sessions across multiple servers
  • No Redundancy: If directory is deleted, session is lost
  • Scaling: Each server instance needs its own session directory
  • Backups: Manual backup process required

​
When to Use

✅ Development and testing
✅ Single-server production
✅ Simple deployments
✅ Personal bots
✅ Low-scale applications

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us