From 725bd460a5abbaf9b559ba942bbe945d85f0be51 Mon Sep 17 00:00:00 2001 From: Blake Ridgway Date: Sat, 21 Mar 2026 18:55:52 -0500 Subject: [PATCH] Initial commit --- CONTRIBUTING.md | 55 ++++++++++++++++++++++++++++++ LICENSE | 21 ++++++++++++ README.md | 78 +++++++++++++++++++++++++++++++++++++++++++ todo.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 243 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 README.md create mode 100644 todo.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..8ba5cf6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,55 @@ +# Contributing to arcline-email + +Thanks for your interest. This is a small project maintained by one person, so +keep expectations calibrated accordingly. + +## Getting Started + +1. Fork the repo and clone your fork +2. Make sure you have Go 1.22+ installed +3. Run `go mod tidy` to pull dependencies +4. Build with `go build ./...` and confirm it compiles clean + +## Reporting Issues + +Open a GitHub issue. Include: +- What you were trying to do +- What happened instead +- Relevant logs or error output +- Go version and OS + +For security vulnerabilities, do **not** open a public issue. Email +`blake@arclineit.com` directly with details. + +## Submitting Changes + +1. Open an issue first for anything non-trivial — discuss the approach before + writing code +2. Keep PRs focused: one fix or feature per PR +3. Write clear commit messages (what changed and why, not just what) +4. Make sure `go build ./...` and `go vet ./...` pass before submitting +5. If you add a new package, add a brief comment at the top explaining what + it does + +## Code Style + +- Standard `gofmt` formatting — no exceptions +- Exported identifiers get doc comments +- Errors are returned, not logged inside library code +- No `panic` in non-main packages +- Prefer the standard library over adding new dependencies; new deps need a + reason + +## What Gets Accepted + +This project has a specific scope (see `todo.md` and `README.md`). PRs that +add features outside that scope are unlikely to be merged, not because they're +bad ideas, but because scope creep is how small projects become unmaintainable. + +If you want to propose something outside current scope, open an issue and make +the case first. + +## License + +By contributing, you agree that your contributions will be licensed under the +same MIT license as the project. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..4bd71fa --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Arcline IT + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..bb8db70 --- /dev/null +++ b/README.md @@ -0,0 +1,78 @@ +# arcline-email + +A self-hosted mail server written in Go. Handles inbound and outbound SMTP, IMAP access, DKIM signing, and SPF/DMARC verification — no third-party relay required. + +## Status + +Early development. Not production-ready. + +## Goals + +- Full SMTP server (inbound on port 25, submission on 587/465) +- IMAP server (143/993) for client access +- Maildir-based message storage +- Username/password authentication with SASL +- TLS on all listeners (Let's Encrypt or bring-your-own cert) +- DKIM signing for outbound mail +- SPF and DMARC verification for inbound mail +- Outbound routing via MX DNS lookup +- Admin API for managing domains, mailboxes, and aliases + +## Non-Goals (for now) + +- Webmail UI +- Anti-spam scoring engine (may integrate rspamd via milter later) +- Multi-server clustering + +## Tech Stack + +- **Language:** Go 1.22+ +- **SMTP:** `emersion/go-smtp` +- **IMAP:** `emersion/go-imap` +- **Mail parsing:** `emersion/go-message` +- **SASL:** `emersion/go-sasl` +- **Storage:** Maildir (filesystem) +- **Config:** TOML + +## Project Layout + +``` +arcline-email/ +├── cmd/ +│ └── arcline-email/ — main entry point +├── internal/ +│ ├── smtp/ — SMTP server (inbound + submission) +│ ├── imap/ — IMAP server +│ ├── storage/ — Maildir storage layer +│ ├── auth/ — user authentication +│ ├── dkim/ — DKIM signing and verification +│ ├── spf/ — SPF checking +│ ├── dmarc/ — DMARC policy enforcement +│ └── admin/ — admin API +├── config/ — config parsing and validation +├── docs/ — protocol notes, architecture docs +├── todo.md +├── CONTRIBUTING.md +├── LICENSE +└── README.md +``` + +## Building + +```sh +go build ./cmd/arcline-email +``` + +## Running + +```sh +./arcline-email --config /etc/arcline-email/config.toml +``` + +## Configuration + +See `docs/config.md` (coming soon). + +## License + +MIT. See [LICENSE](LICENSE). diff --git a/todo.md b/todo.md new file mode 100644 index 0000000..4cb5cd1 --- /dev/null +++ b/todo.md @@ -0,0 +1,89 @@ +# arcline-email — Todo + +## Phase 1: MVP (Core Mail Flow) + +### Project Setup +- [ ] Initialize Go module (`go mod init arcline-email`) +- [ ] Set up directory structure (`cmd/`, `internal/`, `config/`) +- [ ] Add `.gitignore` +- [ ] Wire up config parsing (TOML) +- [ ] Structured logging (`log/slog`) +- [ ] Graceful shutdown (signal handling) + +### SMTP — Inbound (Port 25) +- [ ] Basic SMTP listener using `emersion/go-smtp` +- [ ] Receive inbound mail for local domains +- [ ] TLS support (STARTTLS) +- [ ] Reject mail for unknown domains +- [ ] Write received messages to Maildir + +### SMTP — Submission (Ports 587 / 465) +- [ ] Authenticated submission listener +- [ ] SASL PLAIN / LOGIN auth +- [ ] Enforce auth before relaying +- [ ] Outbound routing via MX DNS lookup +- [ ] Delivery retry queue with backoff + +### IMAP (Ports 143 / 993) +- [ ] IMAP server using `emersion/go-imap` +- [ ] Authenticate users +- [ ] Serve mailboxes from Maildir storage +- [ ] Support INBOX, Sent, Drafts, Trash folders +- [ ] IDLE command support + +### Storage +- [ ] Maildir layout per user (`/var/mail/{domain}/{user}/`) +- [ ] Message write (new mail delivery) +- [ ] Message read / list / delete (for IMAP) +- [ ] Quota tracking (basic) + +### Authentication +- [ ] User store (flat file or SQLite — TBD) +- [ ] Password hashing (bcrypt) +- [ ] Domain and mailbox management (add/remove) + +### TLS +- [ ] Load cert/key from disk +- [ ] Auto-renew via ACME / Let's Encrypt (optional) + +--- + +## Phase 2: Mail Hygiene + +- [ ] DKIM signing on outbound mail +- [ ] DKIM verification on inbound mail +- [ ] SPF record lookup and enforcement +- [ ] DMARC policy parsing and enforcement +- [ ] Reject or quarantine based on DMARC policy +- [ ] DNSBL checks on inbound connections (basic blocklist) + +--- + +## Phase 3: Admin & Operations + +- [ ] Admin HTTP API (manage domains, mailboxes, aliases) +- [ ] Alias support (forward `info@` → real mailbox) +- [ ] Catch-all address support +- [ ] Metrics endpoint (Prometheus) +- [ ] Log shipping / structured access logs +- [ ] Systemd unit file + +--- + +## Phase 4: Hardening + +- [ ] Rate limiting on SMTP connections +- [ ] Connection-level blocklist (IP deny list) +- [ ] Greylisting (optional) +- [ ] rspamd milter integration (optional) +- [ ] Deliverability testing (SPF/DKIM/DMARC pass verification) +- [ ] Blacklist monitoring + +--- + +## Stretch / Future + +- [ ] Webmail UI (separate project) +- [ ] Multi-domain virtual hosting +- [ ] Sieve filtering support +- [ ] JMAP support