Recommended Security Permissions for the wacli Store Directory: A Complete Guide

The wacli store directory must be created with POSIX mode 0700 (read, write, and execute permissions for the owner only) to protect sensitive WhatsApp session keys and chat data.

The steipete/wacli repository is a command-line interface for WhatsApp that stores cryptographic keys, SQLite databases, and media files in a local directory. To prevent unauthorized access to this sensitive data, the codebase enforces strict filesystem permissions at multiple layers. This guide explains the recommended security permissions, where they are enforced in the source code, and how to verify your installation is secure.

Why the wacli Store Directory Requires Strict Permissions

The wacli store directory contains highly sensitive user data that requires confidentiality and isolation:

• Cryptographic session keys used to encrypt WhatsApp messages
• SQLite databases containing chat history and metadata
• Downloaded media files (images, videos, documents)
• Lock files that prevent concurrent instance conflicts

If other users or processes on the same machine can read this directory, they could potentially access private conversations or impersonate the WhatsApp session. The repository addresses this threat by mandating that the store directory and its subdirectories always be created with mode 0700.

The Official Permission Standard: Mode 0700

The wacli project defines the recommended security permissions as POSIX mode 0700, which translates to:

• Owner (7): read (4) + write (2) + execute (1) permissions
• Group (0): no permissions
• Others (0): no permissions

This permission set ensures that only the user account running wacli can access the store directory. The specification is documented in docs/spec.md, which explicitly states "store dir 0700" as a requirement for secure operation.

How wacli Enforces Store Directory Permissions

The codebase enforces the 0700 permission mode at two critical initialization points to ensure security from the first run.

Application Initialization (internal/app/app.go)

When wacli starts, it creates the top-level store directory using os.MkdirAll with the strict permission mask. In internal/app/app.go, the initialization code explicitly sets the directory permissions:

// From internal/app/app.go
if err := os.MkdirAll(opts.StoreDir, 0700); err != nil {
    return nil, fmt.Errorf("cannot create store dir: %w", err)
}

This ensures that whether the application uses the default location (~/.wacli) or a custom path specified via --store DIR, the directory is created with the correct restrictive permissions.

Lock File Creation (internal/lock/lock.go)

To prevent multiple wacli instances from running simultaneously and corrupting the database, the application creates a hidden lock subdirectory. The lock implementation in internal/lock/lock.go also uses os.MkdirAll with mode 0700:

// From internal/lock/lock.go
if err := os.MkdirAll(storeDir, 0700); err != nil {
    return nil, fmt.Errorf("cannot create lock dir: %w", err)
}

This secondary enforcement ensures that even the lock files, which contain process IDs and instance metadata, are protected from unauthorized access.

Specification Documentation (docs/spec.md)

The requirement is formally documented in the project specification. The docs/spec.md file explicitly lists the permission requirement as "store dir 0700", providing authoritative documentation for system administrators auditing the installation.

Verifying and Setting Correct Permissions

If you need to manually create the wacli store directory or verify an existing installation, use these methods to ensure compliance with the recommended security permissions.

Checking Current Permissions

Use the stat command to verify the current mode:

stat -c "%a %n" ~/.wacli

The output should show 700. If you see 755, 775, or any other value, the directory is not properly secured.

Setting Permissions Manually

If the permissions are incorrect, fix them with chmod:

chmod 0700 ~/.wacli

For custom store locations, replace ~/.wacli with your specific path.

Runtime Verification in Go

If you are extending wacli or writing monitoring tools, verify permissions programmatically:

info, err := os.Stat(storeDir)
if err != nil {
    log.Fatalf("cannot stat store dir: %v", err)
}
if info.Mode().Perm() != 0700 {
    log.Printf("warning: store dir permissions are %o, should be 0700", 
               info.Mode().Perm())
}

Security Implications of Incorrect Permissions

Running wacli with permissions other than 0700 creates significant vulnerabilities:

• Data exposure: Other users on the system can read your WhatsApp database and extract chat history
• Key compromise: Session keys stored in the directory could be copied, allowing attackers to impersonate your account
• Lock bypass: Incorrect permissions on the lock directory might allow multiple instances to run, risking database corruption
• Backup risks: Automated backup tools running as different users might include sensitive wacli data if permissions are too permissive

The repository's strict enforcement of 0700 in internal/app/app.go and internal/lock/lock.go prevents these scenarios by default, but manual directory creation or permission changes by system administrators can bypass these protections.

Summary

• wacli requires POSIX mode 0700 for its store directory to protect WhatsApp session keys and chat data
• Enforcement occurs in internal/app/app.go when creating the main store and internal/lock/lock.go when creating the lock subdirectory
• The specification in docs/spec.md explicitly documents the "store dir 0700" requirement
• Use chmod 0700 ~/.wacli to manually set correct permissions if needed
• Never use 0755 or group-readable permissions, as this exposes cryptographic keys and private messages to other system users

Frequently Asked Questions

What permission mode does wacli require for its store directory?

wacli requires the store directory to have POSIX mode 0700, meaning the owner has full read, write, and execute permissions, while group and other users have no access. This is enforced by the code in internal/app/app.go and documented in docs/spec.md.

Where does wacli create the store directory?

By default, wacli creates the store directory at ~/.wacli (in the user's home directory). You can specify a custom location using the --store DIR command-line flag. Regardless of the location, the directory is always created with mode 0700 permissions.

How can I fix permission errors when running wacli?

If you encounter permission errors, ensure the store directory is owned by your user account and set to mode 0700. Run the command chmod 0700 ~/.wacli (or replace ~/.wacli with your custom store path). If the directory was created by another user, you may need to use chown to change ownership first.

Why does wacli use 0700 instead of 0755 for its store directory?

wacli uses 0700 instead of 0755 to prevent other users on the system from accessing sensitive WhatsApp data, including cryptographic session keys, chat databases, and downloaded media. Mode 0755 would allow any user to read the contents, compromising message confidentiality and account security. The lock file mechanism also relies on these restricted permissions to prevent race conditions between instances.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}