101 lines
3.0 KiB
Markdown
101 lines
3.0 KiB
Markdown
# mailcloak
|
||
|
||
Postfix policy + socketmap daemon that validates recipients/senders against Keycloak and serves a local aliases SQLite database.
|
||
|
||
## What it does
|
||
- **Policy service** (Postfix policy delegation):
|
||
- `RCPT` stage: accepts if the recipient exists in Keycloak (primary email) or as a local alias in SQLite.
|
||
- `MAIL` stage (authenticated submissions): accepts only if the sender is the user’s primary Keycloak email or one of their aliases.
|
||
- **Socketmap service**: exposes an `alias` map to Postfix, rewriting alias -> `username@domain`.
|
||
|
||
## Project layout
|
||
- `cmd/mailcloak/` – main package entrypoint
|
||
- `internal/mailcloak/` – daemon sources
|
||
- `go.mod` / `go.sum` – Go module files
|
||
- `configs/config.yaml.sample` – sample config to copy to `/etc/mailcloak/config.yaml`
|
||
- `configs/openrc-mailcloak` – OpenRC service file
|
||
- `db-init.sql` – SQLite schema (also auto-created by the app)
|
||
- `mailcloakctl` – CLI helper to manage aliases
|
||
|
||
## Build the binary
|
||
From the repository root:
|
||
|
||
```bash
|
||
make build
|
||
```
|
||
|
||
To install system-wide:
|
||
|
||
```bash
|
||
make install
|
||
```
|
||
|
||
To run locally:
|
||
|
||
```bash
|
||
make run
|
||
```
|
||
|
||
## Configuration
|
||
Copy the sample config and edit it:
|
||
|
||
```bash
|
||
install -d -m 0750 -o root -g postfix /etc/mailcloak
|
||
cp configs/config.yaml.sample /etc/mailcloak/config.yaml
|
||
```
|
||
|
||
Key settings:
|
||
- `keycloak.*` must point to your Keycloak realm and a client with permission to query users.
|
||
- `policy.domain` is the email domain enforced by the policy.
|
||
- `sqlite.path` is the aliases database path.
|
||
- `sockets.*` must be under the Postfix chroot (usually `/var/spool/postfix`).
|
||
|
||
## Mailcloak database
|
||
|
||
### Aliases
|
||
You can manage aliases using the helper script:
|
||
|
||
```bash
|
||
./mailcloakctl aliases add alias@example.com username
|
||
./mailcloakctl aliases list
|
||
```
|
||
|
||
The script creates the schema automatically if missing.
|
||
|
||
### Apps (Dovecot app passwords)
|
||
The helper script also manages application credentials. The application password is a token: updating the application ID and password is handled by the script and stored as a hash in SQLite. Dovecot can verify these credentials using plain authentication against the stored hash. Applications are restricted to sending emails only (they cannot receive them) and may use only their authorized sender addresses.
|
||
|
||
Examples:
|
||
|
||
```bash
|
||
./mailcloakctl apps add my-app-id "my-app-token"
|
||
./mailcloakctl apps allow my-app-id sender@example.com
|
||
./mailcloakctl apps list
|
||
./mailcloakctl apps disallow my-app-id sender@example.com
|
||
./mailcloakctl apps del my-app-id
|
||
```
|
||
|
||
## Postfix integration (example)
|
||
Policy service (smtpd_recipient_restrictions):
|
||
```
|
||
check_policy_service unix:private/mailcloak
|
||
```
|
||
|
||
Socketmap (virtual_alias_maps):
|
||
```
|
||
socketmap:unix:private/mailcloak-socketmap:alias
|
||
```
|
||
|
||
## OpenRC
|
||
Use the provided service file:
|
||
|
||
```bash
|
||
cp configs/openrc-mailcloak /etc/init.d/mailcloak
|
||
rc-update add mailcloak default
|
||
rc-service mailcloak start
|
||
```
|
||
|
||
## Notes
|
||
- If Keycloak is unavailable, the policy returns `451` by default (configurable via `policy.keycloak_failure_mode`).
|
||
- The policy caches lookups for `policy.cache_ttl_seconds`.
|