#1: implement F0 foundation - monorepo, migrations, Go domain layer, service skeletons, CI

Stands up the LambdaMail monorepo per PLAN.md's F0 milestone: local dev
scaffolding (.env.example, Makefile, .gitignore excluding PLAN.md/docs/
.superpowers/), the full initial Postgres schema as a golang-migrate
migration, the complete Go domain layer for services/protocols (value
objects, entities, domain events - zero external imports beyond
github.com/google/uuid) with unit tests, health-checked service skeletons
for auth/storage (TypeScript) and webmail (Next.js), a local
docker-compose.yaml wiring all services together, a language-enforcement
lint script, and a GitHub Actions CI workflow.

Built via 11 sequential tasks under subagent-driven development, each with
an independent implementer + reviewer cycle. Fixes applied during review:
DomainName.IsPunycode() added to satisfy the promised interface; ioredis
default-import typing under NodeNext; next.js bumped 15.0.3->15.5.21 to
resolve high/critical CVEs; lang-lint.mjs corrected to not flag its own
banned-terms list; web service healthcheck added so compose --wait
actually waits on it; webmail Dockerfile's missing public/ directory:
protocols go.mod version aligned with CI's Go 1.22 pin.

Known follow-ups for later phases (not blocking F0): go-arch-lint isn't
wired into CI yet; live docker compose up and migration apply have not
been exercised in this dev environment (no Docker/psql available here)
and will get their first real run in CI, which does have Docker.

services/auth/Dockerfile

@@ -0,0 +1,14 @@
+FROM node:20-alpine AS build
+WORKDIR /app
+COPY package.json package-lock.json* ./
+RUN npm install
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine
+WORKDIR /app
+COPY --from=build /app/node_modules ./node_modules
+COPY --from=build /app/dist ./dist
+COPY package.json ./
+EXPOSE 3001
+CMD ["node", "dist/server.js"]

services/auth/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@lambdamail/auth",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/server.js",
+    "test": "vitest run",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "pg": "^8.12.0",
+    "ioredis": "^5.4.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@types/pg": "^8.11.6",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}

services/auth/src/health.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { buildHealthHandler } from "./health.js";
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+
+async function withServer(
+  handler: ReturnType<typeof buildHealthHandler>,
+  run: (baseUrl: string) => Promise<void>,
+) {
+  const server = createServer(handler);
+  await new Promise<void>((resolve) => server.listen(0, resolve));
+  const { port } = server.address() as AddressInfo;
+  try {
+    await run(`http://127.0.0.1:${port}`);
+  } finally {
+    server.close();
+  }
+}
+
+describe("buildHealthHandler", () => {
+  it("returns 200 on /health/live regardless of dependency state", async () => {
+    const handler = buildHealthHandler(
+      async () => { throw new Error("db down"); },
+      async () => { throw new Error("redis down"); },
+    );
+    await withServer(handler, async (base) => {
+      const res = await fetch(`${base}/health/live`);
+      expect(res.status).toBe(200);
+    });
+  });
+
+  it("returns 200 on /health/ready when both dependencies respond", async () => {
+    const handler = buildHealthHandler(async () => {}, async () => {});
+    await withServer(handler, async (base) => {
+      const res = await fetch(`${base}/health/ready`);
+      expect(res.status).toBe(200);
+    });
+  });
+
+  it("returns 503 on /health/ready when a dependency fails", async () => {
+    const handler = buildHealthHandler(
+      async () => { throw new Error("db down"); },
+      async () => {},
+    );
+    await withServer(handler, async (base) => {
+      const res = await fetch(`${base}/health/ready`);
+      expect(res.status).toBe(503);
+    });
+  });
+});

services/auth/src/health.ts

@@ -0,0 +1,26 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+type PingFn = () => Promise<void>;
+
+/**
+ * Builds the /health/live and /health/ready handler shared by the auth and
+ * storage services (PLAN.md section 11.5 and the compose healthcheck in section 13).
+ */
+export function buildHealthHandler(pingDb: PingFn, pingRedis: PingFn) {
+  return async (req: IncomingMessage, res: ServerResponse) => {
+    if (req.url === "/health/live") {
+      res.writeHead(200).end();
+      return;
+    }
+    if (req.url === "/health/ready") {
+      try {
+        await Promise.all([pingDb(), pingRedis()]);
+        res.writeHead(200).end();
+      } catch {
+        res.writeHead(503).end();
+      }
+      return;
+    }
+    res.writeHead(404).end();
+  };
+}

services/auth/src/server.ts

@@ -0,0 +1,25 @@
+import { createServer } from "node:http";
+import { Client } from "pg";
+import { Redis } from "ioredis";
+import { buildHealthHandler } from "./health.js";
+
+const port = Number(process.env.PORT ?? 3001);
+
+const handler = buildHealthHandler(
+  async () => {
+    const client = new Client({ connectionString: process.env.DATABASE_URL });
+    await client.connect();
+    await client.query("SELECT 1");
+    await client.end();
+  },
+  async () => {
+    const redis = new Redis(process.env.REDIS_URL ?? "");
+    await redis.ping();
+    redis.disconnect();
+  },
+);
+
+createServer(handler).listen(port, () => {
+  // F0 scaffold: only health endpoints are wired. Auth use cases land in F1+.
+  console.log(`auth service listening on ${port}`);
+});

services/auth/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"]
+}

services/auth/vitest.config.ts

@@ -0,0 +1,5 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: { environment: "node" },
+});

services/protocols/.go-arch-lint.yml

@@ -0,0 +1,19 @@
+version: 3
+workdir: .
+vendors: { golang: { in: golang } }
+excludeFiles:
+  - "**/*_test.go"
+components:
+  domain:
+    in: internal/domain/**
+  health:
+    in: internal/health/**
+  cmd:
+    in: cmd/**
+deps:
+  domain:
+    canUse: []          # zero-dependency layer 1 (PLAN.md section 3)
+  health:
+    canUse: []
+  cmd:
+    canUse: [domain, health]

services/protocols/Dockerfile

@@ -0,0 +1,12 @@
+FROM golang:1.22-alpine AS build
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 go build -o /out/lambdamail-protocols ./cmd/lambdamail-protocols
+
+FROM alpine:3.20
+RUN apk add --no-cache ca-certificates
+COPY --from=build /out/lambdamail-protocols /app/lambdamail-protocols
+EXPOSE 8080
+ENTRYPOINT ["/app/lambdamail-protocols"]

services/protocols/cmd/lambdamail-protocols/main.go

@@ -0,0 +1,30 @@
+// Command lambdamail-protocols is the entry point for the protocols service.
+// F0 boots only the health endpoint; SMTP/IMAP/POP3/ManageSieve listeners land in F1/F2.
+package main
+
+import (
+	"database/sql"
+	"log"
+	"net/http"
+	"os"
+
+	_ "github.com/lib/pq"
+	"lambdamail/protocols/internal/health"
+)
+
+func main() {
+	dbURL := os.Getenv("DATABASE_URL")
+	db, err := sql.Open("postgres", dbURL)
+	if err != nil {
+		log.Fatalf("open database: %v", err)
+	}
+	defer db.Close()
+
+	handler := health.Handler(func() error { return db.Ping() })
+
+	addr := ":8080"
+	log.Printf("lambdamail-protocols listening on %s (health only - F0 scaffold)", addr)
+	if err := http.ListenAndServe(addr, handler); err != nil {
+		log.Fatalf("serve: %v", err)
+	}
+}

services/protocols/go.mod

@@ -0,0 +1,8 @@
+module lambdamail/protocols
+
+go 1.22
+
+require (
+	github.com/google/uuid v1.6.0
+	github.com/lib/pq v1.10.9
+)

services/protocols/go.sum

@@ -0,0 +1,4 @@
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/lib/pq v1.10.9 h1:YXG7RB+JIjhP29X+OtkiDnYaXQwpS4JEWq7dtCCRUEw=
+github.com/lib/pq v1.10.9/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o=

services/protocols/internal/domain/entity/dkim_key_pair.go

@@ -0,0 +1,32 @@
+package entity
+
+import "github.com/google/uuid"
+
+// DkimStatus is the lifecycle state of a DkimKeyPair (PLAN.md section 9, dkim_keys.status).
+type DkimStatus int
+
+const (
+	DkimStatusPending DkimStatus = iota
+	DkimStatusActive
+	DkimStatusRetiring
+	DkimStatusRevoked
+)
+
+// DkimKeyPair is a DKIM signing key with a selector (PLAN.md section 3).
+// Invariant enforced at the aggregate boundary (Domain), not here: only one
+// ACTIVE key per (domain, algorithm) - see the unique partial index in migrations/0001.
+type DkimKeyPair struct {
+	domainID uuid.UUID
+	selector string
+	status   DkimStatus
+}
+
+func NewDkimKeyPair(domainID uuid.UUID, selector string) *DkimKeyPair {
+	return &DkimKeyPair{domainID: domainID, selector: selector, status: DkimStatusPending}
+}
+
+func (k *DkimKeyPair) Selector() string   { return k.selector }
+func (k *DkimKeyPair) Status() DkimStatus { return k.status }
+func (k *DkimKeyPair) Activate()          { k.status = DkimStatusActive }
+func (k *DkimKeyPair) Retire()            { k.status = DkimStatusRetiring }
+func (k *DkimKeyPair) Revoke()            { k.status = DkimStatusRevoked }

services/protocols/internal/domain/entity/dkim_key_pair_test.go

@@ -0,0 +1,22 @@
+package entity
+
+import (
+	"testing"
+
+	"github.com/google/uuid"
+)
+
+func TestNewDkimKeyPair_StartsPending(t *testing.T) {
+	k := NewDkimKeyPair(uuid.New(), "sel1")
+	if k.Status() != DkimStatusPending {
+		t.Errorf("Status() = %v, want DkimStatusPending", k.Status())
+	}
+}
+
+func TestDkimKeyPair_Activate_SetsActive(t *testing.T) {
+	k := NewDkimKeyPair(uuid.New(), "sel1")
+	k.Activate()
+	if k.Status() != DkimStatusActive {
+		t.Errorf("Status() = %v, want DkimStatusActive", k.Status())
+	}
+}

services/protocols/internal/domain/entity/domain.go

@@ -0,0 +1,44 @@
+// Package entity contains the domain's aggregate roots and entities (Clean Architecture layer 1).
+package entity
+
+import (
+	"errors"
+
+	"lambdamail/protocols/internal/domain/valueobject"
+)
+
+// Domain is the aggregate root for a hosted mail domain (PLAN.md section 3).
+type Domain struct {
+	name               valueobject.DomainName
+	active             bool
+	activeMailboxCount int
+}
+
+var ErrDomainHasActiveMailboxes = errors.New("domain: cannot deactivate while it has active mailboxes")
+
+func NewDomain(name valueobject.DomainName) *Domain {
+	return &Domain{name: name, active: true}
+}
+
+func (d *Domain) Name() valueobject.DomainName { return d.name }
+func (d *Domain) IsActive() bool               { return d.active }
+func (d *Domain) ActiveMailboxCount() int      { return d.activeMailboxCount }
+
+// RegisterMailboxCreated tracks a newly created active mailbox under this domain.
+func (d *Domain) RegisterMailboxCreated() { d.activeMailboxCount++ }
+
+// RegisterMailboxRemoved tracks a mailbox no longer counted as active under this domain.
+func (d *Domain) RegisterMailboxRemoved() {
+	if d.activeMailboxCount > 0 {
+		d.activeMailboxCount--
+	}
+}
+
+// Deactivate enforces the invariant "cannot deactivate with active mailboxes" (PLAN.md section 3).
+func (d *Domain) Deactivate() error {
+	if d.activeMailboxCount > 0 {
+		return ErrDomainHasActiveMailboxes
+	}
+	d.active = false
+	return nil
+}

services/protocols/internal/domain/entity/domain_test.go

@@ -0,0 +1,38 @@
+package entity
+
+import (
+	"testing"
+
+	"lambdamail/protocols/internal/domain/valueobject"
+)
+
+func TestNewDomain_StartsActiveWithNoMailboxes(t *testing.T) {
+	name, _ := valueobject.NewDomainName("example.com")
+	d := NewDomain(name)
+	if !d.IsActive() {
+		t.Error("IsActive() = false, want true for a newly created domain")
+	}
+	if d.ActiveMailboxCount() != 0 {
+		t.Errorf("ActiveMailboxCount() = %d, want 0", d.ActiveMailboxCount())
+	}
+}
+
+func TestDomain_Deactivate_SucceedsWithNoActiveMailboxes(t *testing.T) {
+	name, _ := valueobject.NewDomainName("example.com")
+	d := NewDomain(name)
+	if err := d.Deactivate(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if d.IsActive() {
+		t.Error("IsActive() = true after Deactivate(), want false")
+	}
+}
+
+func TestDomain_Deactivate_FailsWithActiveMailboxes(t *testing.T) {
+	name, _ := valueobject.NewDomainName("example.com")
+	d := NewDomain(name)
+	d.RegisterMailboxCreated()
+	if err := d.Deactivate(); err == nil {
+		t.Fatal("expected error: a domain with active mailboxes must not be deactivatable (PLAN.md section 3)")
+	}
+}

services/protocols/internal/domain/entity/folder.go

@@ -0,0 +1,24 @@
+package entity
+
+import "github.com/google/uuid"
+
+// Folder is an IMAP folder entity. uidNext is strictly monotonic (RFC 3501 section 2.3.1.1),
+// enforced per PLAN.md section 3.
+type Folder struct {
+	mailboxID uuid.UUID
+	name      string
+	uidNext   int64
+}
+
+func NewFolder(mailboxID uuid.UUID, name string) *Folder {
+	return &Folder{mailboxID: mailboxID, name: name, uidNext: 1}
+}
+
+func (f *Folder) Name() string { return f.name }
+
+// NextUID allocates and returns the next UID, then advances the counter.
+func (f *Folder) NextUID() int64 {
+	uid := f.uidNext
+	f.uidNext++
+	return uid
+}

services/protocols/internal/domain/entity/folder_test.go

@@ -0,0 +1,20 @@
+package entity
+
+import (
+	"testing"
+
+	"github.com/google/uuid"
+)
+
+func TestFolder_NextUID_StartsAtOneAndIsMonotonic(t *testing.T) {
+	f := NewFolder(uuid.New(), "INBOX")
+	first := f.NextUID()
+	second := f.NextUID()
+	third := f.NextUID()
+	if first != 1 {
+		t.Errorf("first NextUID() = %d, want 1 (RFC 3501 section 2.3.1.1 uid_next starts at 1)", first)
+	}
+	if second <= first || third <= second {
+		t.Errorf("NextUID() sequence not strictly increasing: %d, %d, %d", first, second, third)
+	}
+}

services/protocols/internal/domain/entity/mailbox.go

@@ -0,0 +1,36 @@
+package entity
+
+import (
+	"errors"
+
+	"github.com/google/uuid"
+	"lambdamail/protocols/internal/domain/valueobject"
+)
+
+// Mailbox is a mail account entity (PLAN.md section 3).
+type Mailbox struct {
+	domainID  uuid.UUID
+	address   valueobject.EmailAddress
+	hash      valueobject.PasswordHash
+	quota     valueobject.QuotaLimit
+	usedBytes int64
+}
+
+var ErrMailboxQuotaExceeded = errors.New("mailbox: recording this usage would exceed the quota")
+
+func NewMailbox(domainID uuid.UUID, address valueobject.EmailAddress, hash valueobject.PasswordHash, quota valueobject.QuotaLimit) *Mailbox {
+	return &Mailbox{domainID: domainID, address: address, hash: hash, quota: quota}
+}
+
+func (m *Mailbox) Address() valueobject.EmailAddress { return m.address }
+func (m *Mailbox) UsedBytes() int64                  { return m.usedBytes }
+func (m *Mailbox) Quota() valueobject.QuotaLimit      { return m.quota }
+
+// RecordUsage sets used_bytes, enforcing "used_bytes <= quota_bytes" (PLAN.md section 3).
+func (m *Mailbox) RecordUsage(bytes int64) error {
+	if m.quota.Exceeds(bytes) {
+		return ErrMailboxQuotaExceeded
+	}
+	m.usedBytes = bytes
+	return nil
+}

services/protocols/internal/domain/entity/mailbox_test.go

@@ -0,0 +1,40 @@
+package entity
+
+import (
+	"testing"
+
+	"github.com/google/uuid"
+	"lambdamail/protocols/internal/domain/valueobject"
+)
+
+func newTestMailbox(t *testing.T) *Mailbox {
+	t.Helper()
+	addr, _ := valueobject.NewEmailAddress("user@example.com")
+	hash, _ := valueobject.NewPasswordHash("$argon2id$v=19$m=65536,t=3,p=4$c29tZXNhbHQ$RdescudvJCsgt3ub+b+dWRWJTmaaJObG")
+	quota, _ := valueobject.NewQuotaLimit(1000)
+	return NewMailbox(uuid.New(), addr, hash, quota)
+}
+
+func TestNewMailbox_StartsWithZeroUsage(t *testing.T) {
+	m := newTestMailbox(t)
+	if m.UsedBytes() != 0 {
+		t.Errorf("UsedBytes() = %d, want 0", m.UsedBytes())
+	}
+}
+
+func TestMailbox_RecordUsage_AllowsUpToQuota(t *testing.T) {
+	m := newTestMailbox(t)
+	if err := m.RecordUsage(1000); err != nil {
+		t.Fatalf("unexpected error recording usage exactly at quota: %v", err)
+	}
+	if m.UsedBytes() != 1000 {
+		t.Errorf("UsedBytes() = %d, want 1000", m.UsedBytes())
+	}
+}
+
+func TestMailbox_RecordUsage_RejectsOverQuota(t *testing.T) {
+	m := newTestMailbox(t)
+	if err := m.RecordUsage(1001); err == nil {
+		t.Fatal("expected error: used_bytes must never exceed quota_bytes (PLAN.md section 3), got nil")
+	}
+}

services/protocols/internal/domain/entity/outbound_job.go

@@ -0,0 +1,51 @@
+package entity
+
+import (
+	"errors"
+	"time"
+)
+
+// OutboundJob is a delivery unit with retry state (PLAN.md section 3 and 6.3).
+type OutboundJob struct {
+	attempt     int
+	maxAttempts int
+}
+
+var ErrOutboundJobMaxAttemptsExceeded = errors.New("outbound job: attempt count would exceed max_attempts")
+
+func NewOutboundJob(maxAttempts int) *OutboundJob {
+	return &OutboundJob{maxAttempts: maxAttempts}
+}
+
+func (j *OutboundJob) Attempt() int { return j.attempt }
+
+// RecordAttempt enforces "attempt <= max_attempts" (PLAN.md section 3).
+func (j *OutboundJob) RecordAttempt() error {
+	if j.attempt >= j.maxAttempts {
+		return ErrOutboundJobMaxAttemptsExceeded
+	}
+	j.attempt++
+	return nil
+}
+
+// retrySchedule mirrors the accumulated-wait table in PLAN.md section 6.3.
+var retrySchedule = []time.Duration{
+	0,
+	5 * time.Minute,
+	15 * time.Minute,
+	1 * time.Hour,
+	2 * time.Hour,
+	4 * time.Hour,
+	8 * time.Hour,
+	12 * time.Hour,
+}
+
+// NextBackoff returns the wait before the next attempt, per the schedule in section 6.3.
+// Attempts beyond the table repeat the last (12h) step, matching the "9+: every 12h" rule.
+func (j *OutboundJob) NextBackoff() time.Duration {
+	idx := j.attempt
+	if idx >= len(retrySchedule) {
+		idx = len(retrySchedule) - 1
+	}
+	return retrySchedule[idx]
+}

services/protocols/internal/domain/entity/outbound_job_test.go

@@ -0,0 +1,40 @@
+package entity
+
+import "testing"
+
+func TestOutboundJob_RecordAttempt_AllowsUpToMax(t *testing.T) {
+	j := NewOutboundJob(3)
+	for i := 0; i < 3; i++ {
+		if err := j.RecordAttempt(); err != nil {
+			t.Fatalf("attempt %d: unexpected error: %v", i+1, err)
+		}
+	}
+	if j.Attempt() != 3 {
+		t.Errorf("Attempt() = %d, want 3", j.Attempt())
+	}
+}
+
+func TestOutboundJob_RecordAttempt_RejectsBeyondMax(t *testing.T) {
+	j := NewOutboundJob(1)
+	if err := j.RecordAttempt(); err != nil {
+		t.Fatalf("unexpected error on first attempt: %v", err)
+	}
+	if err := j.RecordAttempt(); err == nil {
+		t.Fatal("expected error: attempt must never exceed max_attempts (PLAN.md section 3), got nil")
+	}
+}
+
+func TestOutboundJob_NextBackoff_IsMonotonicPerRetryTable(t *testing.T) {
+	// Backoff schedule from PLAN.md section 6.3: attempts 1-4 map to
+	// immediate, +5m, +15m, +1h.
+	j := NewOutboundJob(8)
+	var prev int64 = -1
+	for i := 0; i < 4; i++ {
+		j.RecordAttempt()
+		d := j.NextBackoff()
+		if int64(d) < prev {
+			t.Errorf("attempt %d: backoff %v is not >= previous backoff", i+1, d)
+		}
+		prev = int64(d)
+	}
+}

services/protocols/internal/domain/entity/tls_policy.go

@@ -0,0 +1,25 @@
+package entity
+
+// TLSPolicy is the effective transport security policy for an outbound destination
+// (PLAN.md section 3: DANE has precedence over MTA-STS, RFC 8461 section 2).
+type TLSPolicy struct {
+	daneAvailable   bool
+	mtaSTSAvailable bool
+}
+
+func NewTLSPolicy(daneAvailable, mtaSTSAvailable bool) TLSPolicy {
+	return TLSPolicy{daneAvailable: daneAvailable, mtaSTSAvailable: mtaSTSAvailable}
+}
+
+// Effective returns "dane", "mta-sts" or "opportunistic" following the precedence
+// rule in PLAN.md section 5 / RFC 8461 section 2.
+func (p TLSPolicy) Effective() string {
+	switch {
+	case p.daneAvailable:
+		return "dane"
+	case p.mtaSTSAvailable:
+		return "mta-sts"
+	default:
+		return "opportunistic"
+	}
+}

services/protocols/internal/domain/entity/tls_policy_test.go

@@ -0,0 +1,25 @@
+package entity
+
+import "testing"
+
+func TestTLSPolicy_Effective_DANETakesPrecedenceOverMTASTS(t *testing.T) {
+	// RFC 8461 section 2, restated in PLAN.md section 5: DANE wins when both are present.
+	p := NewTLSPolicy(true, true)
+	if p.Effective() != "dane" {
+		t.Errorf("Effective() = %q, want %q when both DANE and MTA-STS are available", p.Effective(), "dane")
+	}
+}
+
+func TestTLSPolicy_Effective_FallsBackToMTASTSWithoutDANE(t *testing.T) {
+	p := NewTLSPolicy(false, true)
+	if p.Effective() != "mta-sts" {
+		t.Errorf("Effective() = %q, want %q", p.Effective(), "mta-sts")
+	}
+}
+
+func TestTLSPolicy_Effective_FallsBackToOpportunisticWithNeither(t *testing.T) {
+	p := NewTLSPolicy(false, false)
+	if p.Effective() != "opportunistic" {
+		t.Errorf("Effective() = %q, want %q", p.Effective(), "opportunistic")
+	}
+}

services/protocols/internal/domain/event/events.go

@@ -0,0 +1,87 @@
+// Package event contains the domain events listed in PLAN.md section 3.
+// They are persisted through the transactional outbox (section 9.4), never
+// published directly on a bus from inside a write transaction.
+package event
+
+import "github.com/google/uuid"
+
+// DomainEvent is implemented by every domain event.
+type DomainEvent interface {
+	Type() string
+	AggregateID() uuid.UUID
+}
+
+type EmailReceived struct{ MessageAggregateID uuid.UUID }
+
+func (e EmailReceived) Type() string          { return "EmailReceived" }
+func (e EmailReceived) AggregateID() uuid.UUID { return e.MessageAggregateID }
+
+type EmailAccepted struct{ MessageAggregateID uuid.UUID }
+
+func (e EmailAccepted) Type() string          { return "EmailAccepted" }
+func (e EmailAccepted) AggregateID() uuid.UUID { return e.MessageAggregateID }
+
+type EmailDelivered struct{ JobAggregateID uuid.UUID }
+
+func (e EmailDelivered) Type() string          { return "EmailDelivered" }
+func (e EmailDelivered) AggregateID() uuid.UUID { return e.JobAggregateID }
+
+type EmailDeferred struct{ JobAggregateID uuid.UUID }
+
+func (e EmailDeferred) Type() string          { return "EmailDeferred" }
+func (e EmailDeferred) AggregateID() uuid.UUID { return e.JobAggregateID }
+
+type EmailBounced struct{ JobAggregateID uuid.UUID }
+
+func (e EmailBounced) Type() string          { return "EmailBounced" }
+func (e EmailBounced) AggregateID() uuid.UUID { return e.JobAggregateID }
+
+type MailboxQuotaWarning struct{ MailboxAggregateID uuid.UUID }
+
+func (e MailboxQuotaWarning) Type() string          { return "MailboxQuotaWarning" }
+func (e MailboxQuotaWarning) AggregateID() uuid.UUID { return e.MailboxAggregateID }
+
+type MailboxQuotaExceeded struct{ MailboxAggregateID uuid.UUID }
+
+func (e MailboxQuotaExceeded) Type() string          { return "MailboxQuotaExceeded" }
+func (e MailboxQuotaExceeded) AggregateID() uuid.UUID { return e.MailboxAggregateID }
+
+type SpamDetected struct{ MessageAggregateID uuid.UUID }
+
+func (e SpamDetected) Type() string          { return "SpamDetected" }
+func (e SpamDetected) AggregateID() uuid.UUID { return e.MessageAggregateID }
+
+type VirusDetected struct{ MessageAggregateID uuid.UUID }
+
+func (e VirusDetected) Type() string          { return "VirusDetected" }
+func (e VirusDetected) AggregateID() uuid.UUID { return e.MessageAggregateID }
+
+type DkimRotationStarted struct{ DomainAggregateID uuid.UUID }
+
+func (e DkimRotationStarted) Type() string          { return "DkimRotationStarted" }
+func (e DkimRotationStarted) AggregateID() uuid.UUID { return e.DomainAggregateID }
+
+type DkimRotationCompleted struct{ DomainAggregateID uuid.UUID }
+
+func (e DkimRotationCompleted) Type() string          { return "DkimRotationCompleted" }
+func (e DkimRotationCompleted) AggregateID() uuid.UUID { return e.DomainAggregateID }
+
+type DnsRecordDrifted struct{ DomainAggregateID uuid.UUID }
+
+func (e DnsRecordDrifted) Type() string          { return "DnsRecordDrifted" }
+func (e DnsRecordDrifted) AggregateID() uuid.UUID { return e.DomainAggregateID }
+
+type CertificateRotated struct{ HostAggregateID uuid.UUID }
+
+func (e CertificateRotated) Type() string          { return "CertificateRotated" }
+func (e CertificateRotated) AggregateID() uuid.UUID { return e.HostAggregateID }
+
+type AuthenticationFailed struct{ MailboxAggregateID uuid.UUID }
+
+func (e AuthenticationFailed) Type() string          { return "AuthenticationFailed" }
+func (e AuthenticationFailed) AggregateID() uuid.UUID { return e.MailboxAggregateID }
+
+type RateLimitTriggered struct{ SubjectAggregateID uuid.UUID }
+
+func (e RateLimitTriggered) Type() string          { return "RateLimitTriggered" }
+func (e RateLimitTriggered) AggregateID() uuid.UUID { return e.SubjectAggregateID }

services/protocols/internal/domain/event/events_test.go

@@ -0,0 +1,22 @@
+package event
+
+import (
+	"testing"
+
+	"github.com/google/uuid"
+)
+
+func TestEmailReceived_ImplementsDomainEvent(t *testing.T) {
+	id := uuid.New()
+	e := EmailReceived{MessageAggregateID: id}
+	if e.Type() != "EmailReceived" {
+		t.Errorf("Type() = %q, want %q", e.Type(), "EmailReceived")
+	}
+	if e.AggregateID() != id {
+		t.Errorf("AggregateID() = %v, want %v", e.AggregateID(), id)
+	}
+}
+
+func TestEmailBounced_ImplementsDomainEvent(t *testing.T) {
+	var _ DomainEvent = EmailBounced{}
+}

services/protocols/internal/domain/valueobject/delivery_status_code.go

@@ -0,0 +1,24 @@
+package valueobject
+
+import (
+	"errors"
+	"fmt"
+)
+
+// DeliveryStatusCode is an RFC 3463 enhanced mail status code (class.subject.detail).
+type DeliveryStatusCode struct {
+	class, subject, detail int
+}
+
+var ErrDeliveryStatusInvalidClass = errors.New("delivery status code: class must be 2 (success), 4 (transient) or 5 (permanent)")
+
+func NewDeliveryStatusCode(class, subject, detail int) (DeliveryStatusCode, error) {
+	if class != 2 && class != 4 && class != 5 {
+		return DeliveryStatusCode{}, ErrDeliveryStatusInvalidClass
+	}
+	return DeliveryStatusCode{class: class, subject: subject, detail: detail}, nil
+}
+
+func (c DeliveryStatusCode) String() string {
+	return fmt.Sprintf("%d.%d.%d", c.class, c.subject, c.detail)
+}

services/protocols/internal/domain/valueobject/delivery_status_code_test.go

@@ -0,0 +1,29 @@
+package valueobject
+
+import "testing"
+
+func TestNewDeliveryStatusCode_AcceptsSuccess(t *testing.T) {
+	c, err := NewDeliveryStatusCode(2, 0, 0)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if c.String() != "2.0.0" {
+		t.Errorf("String() = %q, want %q", c.String(), "2.0.0")
+	}
+}
+
+func TestNewDeliveryStatusCode_AcceptsPermanentFailure(t *testing.T) {
+	c, err := NewDeliveryStatusCode(5, 1, 1)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if c.String() != "5.1.1" {
+		t.Errorf("String() = %q, want %q", c.String(), "5.1.1")
+	}
+}
+
+func TestNewDeliveryStatusCode_RejectsInvalidClass(t *testing.T) {
+	if _, err := NewDeliveryStatusCode(3, 0, 0); err == nil {
+		t.Fatal("expected error: RFC 3463 only defines classes 2, 4 and 5, got nil")
+	}
+}

services/protocols/internal/domain/valueobject/domain_name.go

@@ -0,0 +1,49 @@
+package valueobject
+
+import (
+	"errors"
+	"strings"
+)
+
+// DomainName is an RFC 1035 fully-qualified domain name, normalized to lowercase.
+type DomainName struct {
+	value string
+}
+
+var (
+	ErrDomainNameEmpty         = errors.New("domain name: must not be empty")
+	ErrDomainNameNotFQDN       = errors.New("domain name: must contain at least one dot (not a FQDN)")
+	ErrDomainNameInvalidLabel  = errors.New("domain name: label must not start or end with a hyphen")
+)
+
+// NewDomainName validates and normalizes raw into a DomainName.
+func NewDomainName(raw string) (DomainName, error) {
+	if raw == "" {
+		return DomainName{}, ErrDomainNameEmpty
+	}
+	lower := strings.ToLower(raw)
+	labels := strings.Split(lower, ".")
+	if len(labels) < 2 {
+		return DomainName{}, ErrDomainNameNotFQDN
+	}
+	for _, label := range labels {
+		if label == "" || strings.HasPrefix(label, "-") || strings.HasSuffix(label, "-") {
+			return DomainName{}, ErrDomainNameInvalidLabel
+		}
+	}
+	return DomainName{value: lower}, nil
+}
+
+func (d DomainName) String() string { return d.value }
+
+// IsPunycode reports whether the domain name is IDNA/punycode-encoded.
+// It returns true if any label of the domain starts with the ASCII Compatible Encoding prefix "xn--".
+func (d DomainName) IsPunycode() bool {
+	labels := strings.Split(d.value, ".")
+	for _, label := range labels {
+		if strings.HasPrefix(label, "xn--") {
+			return true
+		}
+	}
+	return false
+}

services/protocols/internal/domain/valueobject/domain_name_test.go

@@ -0,0 +1,51 @@
+package valueobject
+
+import "testing"
+
+func TestNewDomainName_AcceptsValidFQDN(t *testing.T) {
+	d, err := NewDomainName("Example.COM")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if d.String() != "example.com" {
+		t.Errorf("String() = %q, want lowercased %q", d.String(), "example.com")
+	}
+}
+
+func TestNewDomainName_RejectsEmpty(t *testing.T) {
+	if _, err := NewDomainName(""); err == nil {
+		t.Fatal("expected error for empty domain name, got nil")
+	}
+}
+
+func TestNewDomainName_RejectsLabelWithoutDot(t *testing.T) {
+	if _, err := NewDomainName("localhost"); err == nil {
+		t.Fatal("expected error for single-label name (not a FQDN), got nil")
+	}
+}
+
+func TestNewDomainName_RejectsTrailingHyphenLabel(t *testing.T) {
+	if _, err := NewDomainName("bad-.example.com"); err == nil {
+		t.Fatal("expected error for label ending in hyphen, got nil")
+	}
+}
+
+func TestDomainName_IsPunycode_WithPunycodeLabel(t *testing.T) {
+	d, err := NewDomainName("xn--exmple-cua.com")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !d.IsPunycode() {
+		t.Error("IsPunycode() = false, want true for punycode domain")
+	}
+}
+
+func TestDomainName_IsPunycode_WithoutPunycodeLabel(t *testing.T) {
+	d, err := NewDomainName("example.com")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if d.IsPunycode() {
+		t.Error("IsPunycode() = true, want false for plain ASCII domain")
+	}
+}

services/protocols/internal/domain/valueobject/email_address.go

@@ -0,0 +1,44 @@
+// Package valueobject contains the domain's immutable, self-validating value objects.
+// Zero external imports: this is layer 1 of Clean Architecture (see PLAN.md section 3).
+package valueobject
+
+import (
+	"errors"
+	"strings"
+)
+
+// EmailAddress is an RFC 5322 mailbox address, normalized with a lowercased domain.
+type EmailAddress struct {
+	localPart string
+	domain    string
+}
+
+var (
+	ErrEmailMissingAtSign  = errors.New("email address: missing '@' separator")
+	ErrEmailEmptyLocalPart = errors.New("email address: local part must not be empty")
+	ErrEmailEmptyDomain    = errors.New("email address: domain must not be empty")
+	ErrEmailLocalPartTooLong = errors.New("email address: local part exceeds 64 octets (RFC 5321 4.5.3.1.1)")
+)
+
+// NewEmailAddress validates and normalizes raw into an EmailAddress.
+func NewEmailAddress(raw string) (EmailAddress, error) {
+	at := strings.LastIndex(raw, "@")
+	if at < 0 {
+		return EmailAddress{}, ErrEmailMissingAtSign
+	}
+	local, domain := raw[:at], raw[at+1:]
+	if local == "" {
+		return EmailAddress{}, ErrEmailEmptyLocalPart
+	}
+	if len(local) > 64 {
+		return EmailAddress{}, ErrEmailLocalPartTooLong
+	}
+	if domain == "" {
+		return EmailAddress{}, ErrEmailEmptyDomain
+	}
+	return EmailAddress{localPart: local, domain: strings.ToLower(domain)}, nil
+}
+
+func (e EmailAddress) LocalPart() string { return e.localPart }
+func (e EmailAddress) Domain() string    { return e.domain }
+func (e EmailAddress) String() string    { return e.localPart + "@" + e.domain }

services/protocols/internal/domain/valueobject/email_address_test.go

@@ -0,0 +1,47 @@
+package valueobject
+
+import "testing"
+
+func TestNewEmailAddress_AcceptsValidAddress(t *testing.T) {
+	addr, err := NewEmailAddress("User.Name+tag@Example.com")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if addr.LocalPart() != "User.Name+tag" {
+		t.Errorf("local part = %q, want %q", addr.LocalPart(), "User.Name+tag")
+	}
+	if addr.Domain() != "example.com" {
+		t.Errorf("domain = %q, want lowercased %q", addr.Domain(), "example.com")
+	}
+	if addr.String() != "User.Name+tag@example.com" {
+		t.Errorf("String() = %q, want %q", addr.String(), "User.Name+tag@example.com")
+	}
+}
+
+func TestNewEmailAddress_RejectsMissingAtSign(t *testing.T) {
+	if _, err := NewEmailAddress("not-an-email"); err == nil {
+		t.Fatal("expected error for address without '@', got nil")
+	}
+}
+
+func TestNewEmailAddress_RejectsEmptyLocalPart(t *testing.T) {
+	if _, err := NewEmailAddress("@example.com"); err == nil {
+		t.Fatal("expected error for empty local part, got nil")
+	}
+}
+
+func TestNewEmailAddress_RejectsEmptyDomain(t *testing.T) {
+	if _, err := NewEmailAddress("user@"); err == nil {
+		t.Fatal("expected error for empty domain, got nil")
+	}
+}
+
+func TestNewEmailAddress_RejectsOverlongLocalPart(t *testing.T) {
+	longLocal := ""
+	for i := 0; i < 65; i++ {
+		longLocal += "a"
+	}
+	if _, err := NewEmailAddress(longLocal + "@example.com"); err == nil {
+		t.Fatal("expected error for local part over 64 octets (RFC 5321 4.5.3.1.1), got nil")
+	}
+}

services/protocols/internal/domain/valueobject/message_id.go

@@ -0,0 +1,28 @@
+package valueobject
+
+import (
+	"errors"
+	"strings"
+)
+
+// MessageID is an RFC 5322 Message-ID, always wrapped in angle brackets.
+type MessageID struct {
+	raw string
+}
+
+var (
+	ErrMessageIDEmpty       = errors.New("message id: must not be empty")
+	ErrMessageIDNotBracketed = errors.New("message id: must be wrapped in angle brackets")
+)
+
+func NewMessageID(raw string) (MessageID, error) {
+	if raw == "" {
+		return MessageID{}, ErrMessageIDEmpty
+	}
+	if !strings.HasPrefix(raw, "<") || !strings.HasSuffix(raw, ">") {
+		return MessageID{}, ErrMessageIDNotBracketed
+	}
+	return MessageID{raw: raw}, nil
+}
+
+func (m MessageID) String() string { return m.raw }

services/protocols/internal/domain/valueobject/message_id_test.go

@@ -0,0 +1,25 @@
+package valueobject
+
+import "testing"
+
+func TestNewMessageID_AcceptsAngleBracketForm(t *testing.T) {
+	id, err := NewMessageID("<abc123@mail.example.com>")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if id.String() != "<abc123@mail.example.com>" {
+		t.Errorf("String() = %q, want input preserved", id.String())
+	}
+}
+
+func TestNewMessageID_RejectsEmpty(t *testing.T) {
+	if _, err := NewMessageID(""); err == nil {
+		t.Fatal("expected error for empty Message-ID, got nil")
+	}
+}
+
+func TestNewMessageID_RejectsMissingAngleBrackets(t *testing.T) {
+	if _, err := NewMessageID("abc123@mail.example.com"); err == nil {
+		t.Fatal("expected error for Message-ID without angle brackets, got nil")
+	}
+}

services/protocols/internal/domain/valueobject/password_hash.go

@@ -0,0 +1,29 @@
+package valueobject
+
+import (
+	"errors"
+	"strings"
+)
+
+// PasswordHash wraps an Argon2id PHC-format hash string (see PLAN.md section 9, mailboxes.password_hash).
+type PasswordHash struct {
+	phc string
+}
+
+var (
+	ErrPasswordHashEmpty       = errors.New("password hash: must not be empty")
+	ErrPasswordHashWrongScheme = errors.New("password hash: only argon2id PHC strings are accepted")
+)
+
+// NewPasswordHash validates that phc is a well-formed argon2id PHC string.
+func NewPasswordHash(phc string) (PasswordHash, error) {
+	if phc == "" {
+		return PasswordHash{}, ErrPasswordHashEmpty
+	}
+	if !strings.HasPrefix(phc, "$argon2id$") {
+		return PasswordHash{}, ErrPasswordHashWrongScheme
+	}
+	return PasswordHash{phc: phc}, nil
+}
+
+func (p PasswordHash) String() string { return p.phc }

services/protocols/internal/domain/valueobject/password_hash_test.go

@@ -0,0 +1,26 @@
+package valueobject
+
+import "testing"
+
+func TestNewPasswordHash_AcceptsArgon2idPHCString(t *testing.T) {
+	phc := "$argon2id$v=19$m=65536,t=3,p=4$c29tZXNhbHQ$RdescudvJCsgt3ub+b+dWRWJTmaaJObG"
+	h, err := NewPasswordHash(phc)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if h.String() != phc {
+		t.Errorf("String() = %q, want %q", h.String(), phc)
+	}
+}
+
+func TestNewPasswordHash_RejectsNonArgon2idScheme(t *testing.T) {
+	if _, err := NewPasswordHash("$bcrypt$10$abcdefg"); err == nil {
+		t.Fatal("expected error for non-argon2id scheme, got nil")
+	}
+}
+
+func TestNewPasswordHash_RejectsEmpty(t *testing.T) {
+	if _, err := NewPasswordHash(""); err == nil {
+		t.Fatal("expected error for empty hash, got nil")
+	}
+}

services/protocols/internal/domain/valueobject/protocol_security_level.go

@@ -0,0 +1,21 @@
+package valueobject
+
+// ProtocolSecurityLevel is the effective TLS requirement for a listener (see PLAN.md section 4).
+type ProtocolSecurityLevel int
+
+const (
+	SecurityOpportunistic ProtocolSecurityLevel = iota // STARTTLS offered, plaintext fallback allowed (port 25 only)
+	SecurityRequired                                   // STARTTLS mandatory before AUTH (587/143/110/4190)
+	SecurityImplicit                                   // TLS from the first byte (465/993/995)
+)
+
+func (l ProtocolSecurityLevel) String() string {
+	switch l {
+	case SecurityRequired:
+		return "required"
+	case SecurityImplicit:
+		return "implicit"
+	default:
+		return "opportunistic"
+	}
+}

services/protocols/internal/domain/valueobject/protocol_security_level_test.go

@@ -0,0 +1,19 @@
+package valueobject
+
+import "testing"
+
+func TestProtocolSecurityLevel_StringRoundTrip(t *testing.T) {
+	cases := []struct {
+		level ProtocolSecurityLevel
+		want  string
+	}{
+		{SecurityOpportunistic, "opportunistic"},
+		{SecurityRequired, "required"},
+		{SecurityImplicit, "implicit"},
+	}
+	for _, c := range cases {
+		if got := c.level.String(); got != c.want {
+			t.Errorf("String() = %q, want %q", got, c.want)
+		}
+	}
+}

services/protocols/internal/domain/valueobject/quota_limit.go

@@ -0,0 +1,22 @@
+package valueobject
+
+import "errors"
+
+// QuotaLimit is a strictly positive byte quota (see PLAN.md section 3, Mailbox invariant).
+type QuotaLimit struct {
+	bytes int64
+}
+
+var ErrQuotaLimitNotPositive = errors.New("quota limit: must be a positive number of bytes")
+
+func NewQuotaLimit(bytes int64) (QuotaLimit, error) {
+	if bytes <= 0 {
+		return QuotaLimit{}, ErrQuotaLimitNotPositive
+	}
+	return QuotaLimit{bytes: bytes}, nil
+}
+
+func (q QuotaLimit) Bytes() int64 { return q.bytes }
+
+// Exceeds reports whether usedBytes violates the "used_bytes <= quota_bytes" invariant.
+func (q QuotaLimit) Exceeds(usedBytes int64) bool { return usedBytes > q.bytes }

services/protocols/internal/domain/valueobject/quota_limit_test.go

@@ -0,0 +1,35 @@
+package valueobject
+
+import "testing"
+
+func TestNewQuotaLimit_AcceptsPositiveBytes(t *testing.T) {
+	q, err := NewQuotaLimit(1073741824)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if q.Bytes() != 1073741824 {
+		t.Errorf("Bytes() = %d, want %d", q.Bytes(), 1073741824)
+	}
+}
+
+func TestNewQuotaLimit_RejectsZero(t *testing.T) {
+	if _, err := NewQuotaLimit(0); err == nil {
+		t.Fatal("expected error for zero quota, got nil")
+	}
+}
+
+func TestNewQuotaLimit_RejectsNegative(t *testing.T) {
+	if _, err := NewQuotaLimit(-1); err == nil {
+		t.Fatal("expected error for negative quota, got nil")
+	}
+}
+
+func TestQuotaLimit_Exceeds(t *testing.T) {
+	q, _ := NewQuotaLimit(1000)
+	if !q.Exceeds(1001) {
+		t.Error("Exceeds(1001) = false, want true for a 1000-byte quota")
+	}
+	if q.Exceeds(1000) {
+		t.Error("Exceeds(1000) = true, want false: used_bytes <= quota_bytes is the invariant (PLAN.md section 3)")
+	}
+}

services/protocols/internal/domain/valueobject/spam_verdict.go

@@ -0,0 +1,22 @@
+package valueobject
+
+// SpamVerdict classifies a message by Rspamd score (thresholds from PLAN.md section 10.1).
+type SpamVerdict int
+
+const (
+	SpamHam SpamVerdict = iota
+	SpamProbable
+	SpamReject
+)
+
+// SpamVerdictFromScore maps a Rspamd score to a verdict per the thresholds table in section 10.1.
+func SpamVerdictFromScore(score float64) SpamVerdict {
+	switch {
+	case score >= 9:
+		return SpamReject
+	case score >= 4:
+		return SpamProbable
+	default:
+		return SpamHam
+	}
+}

services/protocols/internal/domain/valueobject/spam_verdict_test.go

@@ -0,0 +1,23 @@
+package valueobject
+
+import "testing"
+
+func TestSpamVerdictFromScore_MatchesThresholds(t *testing.T) {
+	// Thresholds from PLAN.md section 10.1.
+	cases := []struct {
+		score float64
+		want  SpamVerdict
+	}{
+		{0, SpamHam},
+		{3.9, SpamHam},
+		{4, SpamProbable},
+		{8.9, SpamProbable},
+		{9, SpamReject},   // section 10.1: 9-15 greylists/defers, modeled here as reject-eligible
+		{15.1, SpamReject},
+	}
+	for _, c := range cases {
+		if got := SpamVerdictFromScore(c.score); got != c.want {
+			t.Errorf("SpamVerdictFromScore(%v) = %v, want %v", c.score, got, c.want)
+		}
+	}
+}

services/protocols/internal/domain/valueobject/tlsa_record.go

@@ -0,0 +1,33 @@
+package valueobject
+
+import "errors"
+
+// TLSARecord models a DANE TLSA RR (RFC 6698/7671). Usage 2 (PKIX-CA) is rejected
+// by explicit ADR - see PLAN.md section 5.1: Let's Encrypt rotates intermediates
+// without notice, making it unpredictable. Only usage 3 (DANE-EE) is supported.
+type TLSARecord struct {
+	usage        uint8
+	selector     uint8
+	matchingType uint8
+	data         string
+}
+
+var (
+	ErrTLSAUsageUnsupported = errors.New("tlsa record: only usage 3 (DANE-EE) is supported")
+	ErrTLSADataWrongLength  = errors.New("tlsa record: matching type 1 (SHA-256) requires a 64-hex-char digest")
+)
+
+func NewTLSARecord(usage, selector, matchingType uint8, data string) (TLSARecord, error) {
+	if usage != 3 {
+		return TLSARecord{}, ErrTLSAUsageUnsupported
+	}
+	if matchingType == 1 && len(data) != 64 {
+		return TLSARecord{}, ErrTLSADataWrongLength
+	}
+	return TLSARecord{usage: usage, selector: selector, matchingType: matchingType, data: data}, nil
+}
+
+func (r TLSARecord) Usage() uint8        { return r.usage }
+func (r TLSARecord) Selector() uint8     { return r.selector }
+func (r TLSARecord) MatchingType() uint8 { return r.matchingType }
+func (r TLSARecord) Data() string        { return r.data }

services/protocols/internal/domain/valueobject/tlsa_record_test.go

@@ -0,0 +1,29 @@
+package valueobject
+
+import "testing"
+
+func TestNewTLSARecord_AcceptsUsage3Selector1MatchingType1(t *testing.T) {
+	hash := "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+	r, err := NewTLSARecord(3, 1, 1, hash)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if r.Usage() != 3 || r.Selector() != 1 || r.MatchingType() != 1 {
+		t.Errorf("fields not preserved: got usage=%d selector=%d matchingType=%d", r.Usage(), r.Selector(), r.MatchingType())
+	}
+}
+
+func TestNewTLSARecord_RejectsUsage2(t *testing.T) {
+	// DANE_TLSA_USAGE=2 was explicitly rejected by ADR (PLAN.md section 5.1):
+	// Let's Encrypt rotates intermediates without notice, making usage 2 unpredictable.
+	hash := "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+	if _, err := NewTLSARecord(2, 1, 1, hash); err == nil {
+		t.Fatal("expected error for usage=2 (PKIX-CA), got nil - rejected by ADR in PLAN.md section 5.1")
+	}
+}
+
+func TestNewTLSARecord_RejectsWrongLengthHash(t *testing.T) {
+	if _, err := NewTLSARecord(3, 1, 1, "tooshort"); err == nil {
+		t.Fatal("expected error for a SHA-256 hash that isn't 64 hex chars, got nil")
+	}
+}

services/protocols/internal/health/health.go

@@ -0,0 +1,23 @@
+// Package health exposes liveness/readiness endpoints (PLAN.md section 11.5).
+package health
+
+import "net/http"
+
+// PingerFunc reports whether a dependency (e.g. Postgres) is reachable.
+type PingerFunc func() error
+
+// Handler serves /health/live (process up) and /health/ready (dependencies reachable).
+func Handler(ping PingerFunc) http.Handler {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/health/live", func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	})
+	mux.HandleFunc("/health/ready", func(w http.ResponseWriter, r *http.Request) {
+		if err := ping(); err != nil {
+			w.WriteHeader(http.StatusServiceUnavailable)
+			return
+		}
+		w.WriteHeader(http.StatusOK)
+	})
+	return mux
+}

services/protocols/internal/health/health_test.go

@@ -0,0 +1,38 @@
+package health
+
+import (
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestHandler_Live_AlwaysReturns200(t *testing.T) {
+	h := Handler(func() error { return errors.New("db down") })
+	req := httptest.NewRequest(http.MethodGet, "/health/live", nil)
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Errorf("GET /health/live status = %d, want %d", rec.Code, http.StatusOK)
+	}
+}
+
+func TestHandler_Ready_Returns200WhenPingSucceeds(t *testing.T) {
+	h := Handler(func() error { return nil })
+	req := httptest.NewRequest(http.MethodGet, "/health/ready", nil)
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Errorf("GET /health/ready status = %d, want %d", rec.Code, http.StatusOK)
+	}
+}
+
+func TestHandler_Ready_Returns503WhenPingFails(t *testing.T) {
+	h := Handler(func() error { return errors.New("db down") })
+	req := httptest.NewRequest(http.MethodGet, "/health/ready", nil)
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	if rec.Code != http.StatusServiceUnavailable {
+		t.Errorf("GET /health/ready status = %d, want %d", rec.Code, http.StatusServiceUnavailable)
+	}
+}

services/storage/Dockerfile

@@ -0,0 +1,14 @@
+FROM node:20-alpine AS build
+WORKDIR /app
+COPY package.json package-lock.json* ./
+RUN npm install
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine
+WORKDIR /app
+COPY --from=build /app/node_modules ./node_modules
+COPY --from=build /app/dist ./dist
+COPY package.json ./
+EXPOSE 3002
+CMD ["node", "dist/server.js"]

services/storage/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@lambdamail/storage",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/server.js",
+    "test": "vitest run",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "pg": "^8.12.0",
+    "ioredis": "^5.4.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@types/pg": "^8.11.6",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}

services/storage/src/health.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { buildHealthHandler } from "./health.js";
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+
+async function withServer(
+  handler: ReturnType<typeof buildHealthHandler>,
+  run: (baseUrl: string) => Promise<void>,
+) {
+  const server = createServer(handler);
+  await new Promise<void>((resolve) => server.listen(0, resolve));
+  const { port } = server.address() as AddressInfo;
+  try {
+    await run(`http://127.0.0.1:${port}`);
+  } finally {
+    server.close();
+  }
+}
+
+describe("buildHealthHandler", () => {
+  it("returns 200 on /health/live regardless of dependency state", async () => {
+    const handler = buildHealthHandler(
+      async () => { throw new Error("db down"); },
+      async () => { throw new Error("redis down"); },
+    );
+    await withServer(handler, async (base) => {
+      const res = await fetch(`${base}/health/live`);
+      expect(res.status).toBe(200);
+    });
+  });
+
+  it("returns 200 on /health/ready when both dependencies respond", async () => {
+    const handler = buildHealthHandler(async () => {}, async () => {});
+    await withServer(handler, async (base) => {
+      const res = await fetch(`${base}/health/ready`);
+      expect(res.status).toBe(200);
+    });
+  });
+
+  it("returns 503 on /health/ready when a dependency fails", async () => {
+    const handler = buildHealthHandler(
+      async () => { throw new Error("db down"); },
+      async () => {},
+    );
+    await withServer(handler, async (base) => {
+      const res = await fetch(`${base}/health/ready`);
+      expect(res.status).toBe(503);
+    });
+  });
+});

services/storage/src/health.ts

@@ -0,0 +1,26 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+type PingFn = () => Promise<void>;
+
+/**
+ * Builds the /health/live and /health/ready handler shared by the auth and
+ * storage services (PLAN.md section 11.5 and the compose healthcheck in section 13).
+ */
+export function buildHealthHandler(pingDb: PingFn, pingRedis: PingFn) {
+  return async (req: IncomingMessage, res: ServerResponse) => {
+    if (req.url === "/health/live") {
+      res.writeHead(200).end();
+      return;
+    }
+    if (req.url === "/health/ready") {
+      try {
+        await Promise.all([pingDb(), pingRedis()]);
+        res.writeHead(200).end();
+      } catch {
+        res.writeHead(503).end();
+      }
+      return;
+    }
+    res.writeHead(404).end();
+  };
+}

services/storage/src/server.ts

@@ -0,0 +1,25 @@
+import { createServer } from "node:http";
+import { Client } from "pg";
+import { Redis } from "ioredis";
+import { buildHealthHandler } from "./health.js";
+
+const port = Number(process.env.PORT ?? 3002);
+
+const handler = buildHealthHandler(
+  async () => {
+    const client = new Client({ connectionString: process.env.DATABASE_URL });
+    await client.connect();
+    await client.query("SELECT 1");
+    await client.end();
+  },
+  async () => {
+    const redis = new Redis(process.env.REDIS_URL ?? "");
+    await redis.ping();
+    redis.disconnect();
+  },
+);
+
+createServer(handler).listen(port, () => {
+  // F0 scaffold: only health endpoints are wired. Storage use cases land in F1+.
+  console.log(`storage service listening on ${port}`);
+});

services/storage/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"]
+}

services/storage/vitest.config.ts

@@ -0,0 +1,5 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: { environment: "node" },
+});

services/webmail/Dockerfile

@@ -0,0 +1,14 @@
+FROM node:20-alpine AS build
+WORKDIR /app
+COPY package.json package-lock.json* ./
+RUN npm install
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine
+WORKDIR /app
+COPY --from=build /app/.next/standalone ./
+COPY --from=build /app/.next/static ./.next/static
+COPY --from=build /app/public ./public
+EXPOSE 3000
+CMD ["node", "server.js"]

services/webmail/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+/// <reference path="./.next/types/routes.d.ts" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

services/webmail/next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  output: "standalone",
+};
+
+export default nextConfig;

services/webmail/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@lambdamail/webmail",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start -p 3000"
+  },
+  "dependencies": {
+    "next": "15.5.21",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4",
+    "@types/node": "^20.14.0",
+    "@types/react": "^18.3.3"
+  },
+  "overrides": {
+    "sharp": "^0.35.0"
+  }
+}

services/webmail/src/app/health/route.ts

@@ -0,0 +1,3 @@
+export function GET() {
+  return new Response(null, { status: 200 });
+}

services/webmail/src/app/layout.tsx

@@ -0,0 +1,7 @@
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

services/webmail/src/app/page.tsx

@@ -0,0 +1,8 @@
+export default function HomePage() {
+  return (
+    <main>
+      <h1>LambdaMail</h1>
+      <p>Webmail and admin console land in F4. This is the F0 boot scaffold.</p>
+    </main>
+  );
+}

services/webmail/tsconfig.json

@@ -0,0 +1,35 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "jsx": "preserve",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "allowJs": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": [
+    "**/*.ts",
+    "**/*.tsx",
+    "next-env.d.ts",
+    ".next/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}