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

> Learn the recommended security permissions for the wacli store directory. Secure your WhatsApp session keys and chat data with POSIX mode 0700.

- Repository: [Peter Steinberger/wacli](https://github.com/steipete/wacli)
- Tags: best-practices
- Published: 2026-04-17

---

**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`](https://github.com/steipete/wacli/blob/main/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`](https://github.com/steipete/wacli/blob/main/internal/app/app.go), the initialization code explicitly sets the directory permissions:

```go
// 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`](https://github.com/steipete/wacli/blob/main/internal/lock/lock.go) also uses `os.MkdirAll` with mode `0700`:

```go
// 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`](https://github.com/steipete/wacli/blob/main/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:

```bash
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`:

```bash
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:

```go
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`](https://github.com/steipete/wacli/blob/main/internal/app/app.go) and [`internal/lock/lock.go`](https://github.com/steipete/wacli/blob/main/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`](https://github.com/steipete/wacli/blob/main/internal/app/app.go)** when creating the main store and **[`internal/lock/lock.go`](https://github.com/steipete/wacli/blob/main/internal/lock/lock.go)** when creating the lock subdirectory
- **The specification in [`docs/spec.md`](https://github.com/steipete/wacli/blob/main/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`](https://github.com/steipete/wacli/blob/main/internal/app/app.go) and documented in [`docs/spec.md`](https://github.com/steipete/wacli/blob/main/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.