feat(imap,pop3): full IMAP4rev1 + POP3 bait mailbox implementation

IMAP: extended to full IMAP4rev1 — 10 bait emails (AWS keys, DB creds,
tokens, VPN config, root pw etc.), LIST/LSUB/STATUS/FETCH/UID FETCH/
SEARCH/CLOSE/NOOP, proper SELECT untagged responses (EXISTS, UIDNEXT,
FLAGS, PERMANENTFLAGS), CAPABILITY with IDLE/LITERAL+/AUTH=PLAIN.
FETCH correctly handles sequence sets (1:*, 1:3, *), item dispatch
(FLAGS, ENVELOPE, BODY[], RFC822, RFC822.SIZE), and places body literals
last per RFC 3501.

POP3: extended with same 10 bait emails, fixed banner env var key
(POP3_BANNER not IMAP_BANNER), CAPA fully populated (TOP/UIDL/USER/
RESP-CODES/SASL), TOP (headers + N body lines), UIDL (msg-N format),
DELE/RSET with _deleted set tracking, NOOP. _active_messages() helper
excludes DELE'd messages from STAT/LIST/UIDL.

Both: DEBT-026 stub added (_EMAIL_SEED_PATH env var, documented in
DEBT.md for next-session JSON seed file wiring).

Tests: test_imap.py expanded to 27 cases, test_pop3.py to 22 cases —
860 total tests passing.

DEBT.md

@@ -101,10 +101,14 @@ All route decorators now declare `responses={401: {"description": "Not authentic
 ~~**File:** `decnet/web/sqlite_repository.py` (~400 lines)~~  
 Fully refactored to `decnet/web/db/` modular layout: `models.py` (SQLModel schema), `repository.py` (abstract base), `sqlite/repository.py` (SQLite implementation), `sqlite/database.py` (engine/session factory). Commit `de84cc6`.
 
-### DEBT-026 — IMAP/POP3 bait emails are hardcoded
+### DEBT-026 — IMAP/POP3 bait emails not configurable via service config
-**Files:** `templates/imap/server.py`, `templates/pop3/server.py`  
+**Files:** `templates/imap/server.py`, `templates/pop3/server.py`, `decnet/services/imap.py`, `decnet/services/pop3.py`  
-Bait emails are hardcoded strings. A modular framework to dynamically inject personalized mailboxes, custom mails, and dynamic users should be implemented in the future for a more personalized feel.  
+Bait emails are hardcoded. A stub env var `IMAP_EMAIL_SEED` is read but currently ignored. Full implementation requires:
-**Status:** Deferred — out of current scope.
+1. `IMAP_EMAIL_SEED` points to a JSON file with a list of `{from_, to, subject, date, body}` dicts.
+2. `templates/imap/server.py` loads and merges/replaces `_BAIT_EMAILS` from that file at startup.
+3. `decnet/services/imap.py` `compose_fragment()` reads `service_cfg["email_seed"]` and injects `IMAP_EMAIL_SEED` + a bind-mount for the seed file into the compose fragment.
+4. Same pattern for POP3 (`POP3_EMAIL_SEED`).  
+**Status:** Stub in place — full wiring deferred to next session.
 
 ---
 

templates/imap/server.py

@@ -1,52 +1,356 @@
 #!/usr/bin/env python3
 """
-IMAP server (port 143/993).
+IMAP server (port 143).
-Presents an IMAP4rev1 banner, captures LOGIN credentials.
+Full IMAP4rev1 state machine with bait mailbox.
-Implements a basic IMAP state machine (NOT_AUTHENTICATED -> AUTHENTICATED -> SELECTED).
+
-Provides hardcoded bait emails containing AWS API keys to attackers.
+States: NOT_AUTHENTICATED → AUTHENTICATED → SELECTED
-Logs commands as JSON.
+
+Credentials via IMAP_USERS env var ("user:pass,user2:pass2").
+10 bait emails in INBOX containing AWS keys, DB passwords, tokens etc.
+Banner advertises Dovecot so nmap fingerprints correctly.
 """
 
 import asyncio
 import os
-from decnet_logging import syslog_line, write_syslog_file, forward_syslog
+from decnet_logging import SEVERITY_WARNING, syslog_line, write_syslog_file, forward_syslog
 
-NODE_NAME = os.environ.get("NODE_NAME", "mailserver")
+NODE_NAME   = os.environ.get("NODE_NAME", "mailserver")
-SERVICE_NAME   = "imap"
+SERVICE_NAME = "imap"
-LOG_TARGET = os.environ.get("LOG_TARGET", "")
+LOG_TARGET  = os.environ.get("LOG_TARGET", "")
-IMAP_BANNER = os.environ.get("IMAP_BANNER", f"* OK [{NODE_NAME}] Dovecot ready.\r\n")
+IMAP_BANNER = os.environ.get("IMAP_BANNER", f"* OK Dovecot ready.\r\n")
+_RAW_USERS  = os.environ.get("IMAP_USERS", "admin:admin123,root:toor,mail:mail,user:user")
 
-IMAP_USERS = os.environ.get("IMAP_USERS", "admin:admin123,root:toor")
+VALID_USERS: dict[str, str] = {
+    u: p for part in _RAW_USERS.split(",") if ":" in part for u, p in [part.split(":", 1)]
+}
 
-_BAIT_EMAILS = [
+# DEBT-026: path to a JSON file with custom email definitions.
-    (1, "Date: Tue, 01 Nov 2023 10:00:00 +0000\r\nFrom: sysadmin@company.com\r\nSubject: AWS Credentials\r\n\r\nHere are the new AWS keys:\r\nAKIAIOSFODNN7EXAMPLE\r\nwJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\r\n"),
+# When set, _BAIT_EMAILS should be replaced/extended from that file.
-    (2, "Date: Wed, 02 Nov 2023 11:30:00 +0000\r\nFrom: devops@company.com\r\nSubject: DB Password Reset\r\n\r\nThe production database password has been temporarily set to:\r\nProdDB_temp_2023!!\r\n"),
+# Wiring (service_cfg["email_seed"] → compose_fragment → env var → here) is deferred.
+_EMAIL_SEED_PATH = os.environ.get("IMAP_EMAIL_SEED", "")  # stub — currently unused
+
+# ── Bait emails ───────────────────────────────────────────────────────────────
+# All 10 live in INBOX. UID == sequence number.
+
+_BAIT_EMAILS: list[dict] = [
+    {
+        "uid": 1, "flags": [r"\Seen"],
+        "from_name": "DevOps Team", "from_addr": "devops@company.internal",
+        "to_addr": "admin@company.internal",
+        "subject": "AWS credentials rotation",
+        "date": "Mon, 06 Nov 2023 09:12:33 +0000",
+        "body": (
+            "Date: Mon, 06 Nov 2023 09:12:33 +0000\r\n"
+            "From: DevOps Team <devops@company.internal>\r\n"
+            "To: admin@company.internal\r\n"
+            "Subject: AWS credentials rotation\r\n"
+            "Message-ID: <1@company.internal>\r\n"
+            "\r\n"
+            "Team,\r\n\r\n"
+            "New AWS credentials have been issued. Old keys deactivated.\r\n\r\n"
+            "Access Key ID:     AKIAIOSFODNN7EXAMPLE\r\n"
+            "Secret Access Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\r\n\r\n"
+            "Update ~/.aws/credentials immediately.\r\n\r\n-- DevOps\r\n"
+        ),
+    },
+    {
+        "uid": 2, "flags": [r"\Seen"],
+        "from_name": "Monitoring", "from_addr": "monitoring@company.internal",
+        "to_addr": "admin@company.internal",
+        "subject": "DB password changed",
+        "date": "Tue, 07 Nov 2023 14:05:11 +0000",
+        "body": (
+            "Date: Tue, 07 Nov 2023 14:05:11 +0000\r\n"
+            "From: Monitoring <monitoring@company.internal>\r\n"
+            "To: admin@company.internal\r\n"
+            "Subject: DB password changed\r\n"
+            "Message-ID: <2@company.internal>\r\n"
+            "\r\n"
+            "Production database password was rotated.\r\n\r\n"
+            "Connection string: mysql://admin:Sup3rS3cr3t!@10.0.1.5:3306/production\r\n\r\n"
+            "Update all app configs.\r\n"
+        ),
+    },
+    {
+        "uid": 3, "flags": [],
+        "from_name": "GitHub", "from_addr": "noreply@github.com",
+        "to_addr": "admin@company.internal",
+        "subject": "Your personal access token",
+        "date": "Wed, 08 Nov 2023 08:30:00 +0000",
+        "body": (
+            "Date: Wed, 08 Nov 2023 08:30:00 +0000\r\n"
+            "From: GitHub <noreply@github.com>\r\n"
+            "To: admin@company.internal\r\n"
+            "Subject: Your personal access token\r\n"
+            "Message-ID: <3@company.internal>\r\n"
+            "\r\n"
+            "Hi admin,\r\n\r\n"
+            "A new personal access token was created for your account.\r\n\r\n"
+            "Token: ghp_16C7e42F292c6912E7710c838347Ae178B4a\r\n\r\n"
+            "If this wasn't you, revoke it immediately at github.com/settings/tokens.\r\n"
+        ),
+    },
+    {
+        "uid": 4, "flags": [r"\Seen"],
+        "from_name": "IT Admin", "from_addr": "admin@company.internal",
+        "to_addr": "team@company.internal",
+        "subject": "VPN config attached",
+        "date": "Thu, 09 Nov 2023 11:22:47 +0000",
+        "body": (
+            "Date: Thu, 09 Nov 2023 11:22:47 +0000\r\n"
+            "From: IT Admin <admin@company.internal>\r\n"
+            "To: team@company.internal\r\n"
+            "Subject: VPN config attached\r\n"
+            "Message-ID: <4@company.internal>\r\n"
+            "\r\n"
+            "VPN access details for new starters:\r\n\r\n"
+            "  Host:     vpn.company.internal:1194\r\n"
+            "  Protocol: UDP\r\n"
+            "  Username: vpnadmin\r\n"
+            "  Password: VpnP@ss2024\r\n\r\n"
+            "Config file sent separately via secure channel.\r\n"
+        ),
+    },
+    {
+        "uid": 5, "flags": [],
+        "from_name": "SysAdmin", "from_addr": "sysadmin@company.internal",
+        "to_addr": "admin@company.internal",
+        "subject": "Root password",
+        "date": "Fri, 10 Nov 2023 16:45:00 +0000",
+        "body": (
+            "Date: Fri, 10 Nov 2023 16:45:00 +0000\r\n"
+            "From: SysAdmin <sysadmin@company.internal>\r\n"
+            "To: admin@company.internal\r\n"
+            "Subject: Root password\r\n"
+            "Message-ID: <5@company.internal>\r\n"
+            "\r\n"
+            "New root password for prod servers:\r\n\r\n"
+            "  r00tM3T00!\r\n\r\n"
+            "Change after first login. Do NOT forward this email.\r\n"
+        ),
+    },
+    {
+        "uid": 6, "flags": [r"\Seen"],
+        "from_name": "Backup System", "from_addr": "backup@company.internal",
+        "to_addr": "admin@company.internal",
+        "subject": "Backup job failed",
+        "date": "Sat, 11 Nov 2023 03:12:04 +0000",
+        "body": (
+            "Date: Sat, 11 Nov 2023 03:12:04 +0000\r\n"
+            "From: Backup System <backup@company.internal>\r\n"
+            "To: admin@company.internal\r\n"
+            "Subject: Backup job failed\r\n"
+            "Message-ID: <6@company.internal>\r\n"
+            "\r\n"
+            "Nightly backup to 192.168.1.50:/mnt/nas FAILED at 03:11 UTC.\r\n\r\n"
+            "Error: Authentication failed. Credentials in /etc/backup.conf may be stale.\r\n\r\n"
+            "Last successful backup: 2023-11-10 03:11 UTC\r\n"
+        ),
+    },
+    {
+        "uid": 7, "flags": [r"\Seen"],
+        "from_name": "Security Alerts", "from_addr": "alerts@company.internal",
+        "to_addr": "admin@company.internal",
+        "subject": "SSH brute-force alert",
+        "date": "Sun, 12 Nov 2023 07:04:31 +0000",
+        "body": (
+            "Date: Sun, 12 Nov 2023 07:04:31 +0000\r\n"
+            "From: Security Alerts <alerts@company.internal>\r\n"
+            "To: admin@company.internal\r\n"
+            "Subject: SSH brute-force alert\r\n"
+            "Message-ID: <7@company.internal>\r\n"
+            "\r\n"
+            "47 failed SSH login attempts detected against prod-web-01.\r\n\r\n"
+            "Source IPs: 185.220.101.34, 185.220.101.47, 185.220.101.52\r\n"
+            "Target user: root\r\n"
+            "Period: 2023-11-12 06:58 – 07:04 UTC\r\n\r\n"
+            "All attempts blocked by fail2ban. No successful logins.\r\n"
+        ),
+    },
+    {
+        "uid": 8, "flags": [r"\Seen"],
+        "from_name": "External Vendor", "from_addr": "vendor@external.com",
+        "to_addr": "admin@company.internal",
+        "subject": "RE: API integration",
+        "date": "Mon, 13 Nov 2023 10:11:55 +0000",
+        "body": (
+            "Date: Mon, 13 Nov 2023 10:11:55 +0000\r\n"
+            "From: External Vendor <vendor@external.com>\r\n"
+            "To: admin@company.internal\r\n"
+            "Subject: RE: API integration\r\n"
+            "Message-ID: <8@company.internal>\r\n"
+            "\r\n"
+            "Hi,\r\n\r\n"
+            "Here is the live API key for the integration:\r\n\r\n"
+            "  sk_live_9mK3xF2aP7qR1bN8cT4dW6vE0yU5hJ\r\n\r\n"
+            "Keep this confidential. Let me know if you need the webhook secret.\r\n\r\n"
+            "Best regards,\r\nVendor Support\r\n"
+        ),
+    },
+    {
+        "uid": 9, "flags": [],
+        "from_name": "Help Desk", "from_addr": "helpdesk@company.internal",
+        "to_addr": "admin@company.internal",
+        "subject": "Password reset request",
+        "date": "Tue, 14 Nov 2023 13:48:22 +0000",
+        "body": (
+            "Date: Tue, 14 Nov 2023 13:48:22 +0000\r\n"
+            "From: Help Desk <helpdesk@company.internal>\r\n"
+            "To: admin@company.internal\r\n"
+            "Subject: Password reset request\r\n"
+            "Message-ID: <9@company.internal>\r\n"
+            "\r\n"
+            "Hi,\r\n\r\n"
+            "Could you reset my MFA? Current password is Winter2024! so you can verify it's me.\r\n\r\n"
+            "Thanks\r\n"
+        ),
+    },
+    {
+        "uid": 10, "flags": [r"\Seen"],
+        "from_name": "AWS Billing", "from_addr": "noreply@aws.amazon.com",
+        "to_addr": "admin@company.internal",
+        "subject": "Your AWS bill is ready",
+        "date": "Wed, 15 Nov 2023 00:01:00 +0000",
+        "body": (
+            "Date: Wed, 15 Nov 2023 00:01:00 +0000\r\n"
+            "From: AWS Billing <noreply@aws.amazon.com>\r\n"
+            "To: admin@company.internal\r\n"
+            "Subject: Your AWS bill is ready\r\n"
+            "Message-ID: <10@company.internal>\r\n"
+            "\r\n"
+            "Your AWS bill for October 2023 is $847.23.\r\n\r\n"
+            "Top services:\r\n"
+            "  EC2 (us-east-1):   $412.10\r\n"
+            "  RDS (us-east-1):   $198.50\r\n"
+            "  S3:                 $87.43\r\n"
+            "  EC2 (eu-west-2):   $149.20\r\n\r\n"
+            "Account ID: 123456789012\r\n"
+        ),
+    },
 ]
 
+_MAILBOXES = ["INBOX", "Sent", "Drafts", "Archive"]
+
+# ── Logging ───────────────────────────────────────────────────────────────────
+
 def _log(event_type: str, severity: int = 6, **kwargs) -> None:
     line = syslog_line(SERVICE_NAME, NODE_NAME, event_type, severity, **kwargs)
     print(line, flush=True)
     write_syslog_file(line)
     forward_syslog(line, LOG_TARGET)
 
+# ── FETCH helpers ─────────────────────────────────────────────────────────────
+
+def _parse_seq_range(range_str: str, total: int) -> list[int]:
+    """Parse IMAP sequence set ('1', '1:3', '1:*', '*') → list of 1-based indices."""
+    result = []
+    for part in range_str.split(","):
+        part = part.strip()
+        if ":" in part:
+            lo_s, hi_s = part.split(":", 1)
+            lo = total if lo_s == "*" else int(lo_s)
+            hi = total if hi_s == "*" else int(hi_s)
+            result.extend(range(min(lo, hi), max(lo, hi) + 1))
+        elif part == "*":
+            result.append(total)
+        else:
+            result.append(int(part))
+    return [n for n in result if 1 <= n <= total]
+
+
+def _parse_fetch_items(items_str: str) -> list[str]:
+    """Parse '(FLAGS ENVELOPE)' or 'BODY[]' → list of item name strings."""
+    s = items_str.strip()
+    if s.startswith("(") and s.endswith(")"):
+        s = s[1:-1]
+    tokens, i = [], 0
+    while i < len(s):
+        if s[i] == " ":
+            i += 1
+            continue
+        j, depth = i, 0
+        while j < len(s):
+            if s[j] == "[":
+                depth += 1
+            elif s[j] == "]":
+                depth -= 1
+            elif s[j] == " " and depth == 0:
+                break
+            j += 1
+        tokens.append(s[i:j].upper())
+        i = j
+    return tokens
+
+
+def _envelope(msg: dict) -> str:
+    """Build minimal RFC 3501 ENVELOPE tuple string."""
+    def addr(name: str, email: str) -> str:
+        parts = email.split("@", 1)
+        user = parts[0]
+        host = parts[1] if len(parts) > 1 else ""
+        safe_name = name.replace('"', '\\"')
+        return f'("{safe_name}" NIL "{user}" "{host}")'
+
+    from_addr = addr(msg["from_name"], msg["from_addr"])
+    to_addr   = addr("", msg["to_addr"])
+    subject   = msg["subject"].replace('"', '\\"')
+    return (
+        f'("{msg["date"]}" "{subject}" '
+        f'({from_addr}) ({from_addr}) ({from_addr}) '
+        f'({to_addr}) NIL NIL NIL "<{msg["uid"]}@{NODE_NAME}>")'
+    )
+
+
+def _build_fetch_response(seq: int, msg: dict, items: list[str]) -> bytes:
+    """Build the bytes for a single '* N FETCH (...)' response."""
+    non_literal: list[str] = []
+    literal_name: str | None = None
+    literal_raw:  bytes | None = None
+
+    for item in items:
+        norm = item.upper()
+        if norm == "FLAGS":
+            flags = " ".join(msg["flags"]) if msg["flags"] else ""
+            non_literal.append(f"FLAGS ({flags})")
+        elif norm == "ENVELOPE":
+            non_literal.append(f"ENVELOPE {_envelope(msg)}")
+        elif norm == "RFC822.SIZE":
+            non_literal.append(f"RFC822.SIZE {len(msg['body'].encode())}")
+        elif norm in ("UID",):
+            non_literal.append(f"UID {msg['uid']}")
+        elif norm in ("BODY[]", "RFC822", "BODY[TEXT]", "BODY.PEEK[]"):
+            literal_name = "BODY[]"
+            literal_raw  = msg["body"].encode()
+        elif norm in ("BODY[HEADER]", "BODY.PEEK[HEADER]"):
+            header_part  = msg["body"].split("\r\n\r\n", 1)[0] + "\r\n\r\n"
+            literal_name = "BODY[HEADER]"
+            literal_raw  = header_part.encode()
+        # unknown items silently ignored
+
+    if literal_raw is not None:
+        prefix_str = (" ".join(non_literal) + " ") if non_literal else ""
+        header = f"* {seq} FETCH ({prefix_str}{literal_name} {{{len(literal_raw)}}}\r\n".encode()
+        return header + literal_raw + b")\r\n"
+    else:
+        return f"* {seq} FETCH ({' '.join(non_literal)})\r\n".encode()
+
+
+# ── Protocol ──────────────────────────────────────────────────────────────────
+
 class IMAPProtocol(asyncio.Protocol):
     def __init__(self):
-        self._transport = None
+        self._transport  = None
-        self._peer = None
+        self._peer       = ("?", 0)
-        self._buf = b""
+        self._buf        = b""
-        self._state = "NOT_AUTHENTICATED"
+        self._state      = "NOT_AUTHENTICATED"
-        self._valid_users = dict(u.split(":", 1) for u in IMAP_USERS.split(",") if ":" in u)
+        self._selected   = None   # mailbox name currently selected
 
     def connection_made(self, transport):
         self._transport = transport
         self._peer = transport.get_extra_info("peername", ("?", 0))
         _log("connect", src=self._peer[0], src_port=self._peer[1])
-        if IMAP_BANNER:
+        banner = IMAP_BANNER if IMAP_BANNER.endswith("\r\n") else IMAP_BANNER + "\r\n"
-            if not IMAP_BANNER.endswith("\r\n"):
+        transport.write(banner.encode())
-                padded_banner = IMAP_BANNER + "\r\n"
-            else:
-                padded_banner = IMAP_BANNER
-            transport.write(padded_banner.encode())
 
     def data_received(self, data):
         self._buf += data
@@ -54,7 +358,12 @@ class IMAPProtocol(asyncio.Protocol):
             line, self._buf = self._buf.split(b"\n", 1)
             self._handle_line(line.decode(errors="replace").strip())
 
-    def _handle_line(self, line: str):
+    def connection_lost(self, exc):
+        _log("disconnect", src=self._peer[0] if self._peer else "?")
+
+    # ── Command dispatch ──────────────────────────────────────────────────────
+
+    def _handle_line(self, line: str) -> None:
         parts = line.split(None, 2)
         if not parts:
             return
@@ -62,63 +371,162 @@ class IMAPProtocol(asyncio.Protocol):
         cmd = parts[1].upper() if len(parts) > 1 else ""
         args = parts[2] if len(parts) > 2 else ""
 
-        _log("command", src=self._peer[0], cmd=line[:128], state=self._state)
+        _log("command", src=self._peer[0], cmd=cmd, state=self._state)
 
+        # Commands valid in any state
         if cmd == "CAPABILITY":
-            self._transport.write(b"* CAPABILITY IMAP4rev1 AUTH=PLAIN AUTH=LOGIN\r\n")
+            self._w(b"* CAPABILITY IMAP4rev1 LITERAL+ SASL-IR LOGIN-REFERRALS"
-            self._transport.write(f"{tag} OK CAPABILITY completed\r\n".encode())
+                    b" ID ENABLE IDLE AUTH=PLAIN AUTH=LOGIN\r\n")
-            
+            self._w(f"{tag} OK CAPABILITY completed\r\n")
-        elif cmd == "LOGIN":
-            if self._state != "NOT_AUTHENTICATED":
-                self._transport.write(f"{tag} BAD Already authenticated\r\n".encode())
-                return
-            creds = args.split(None, 1)
-            username = creds[0].strip('"') if creds else ""
-            password = creds[1].strip('"') if len(creds) > 1 else ""
-            
-            if username in self._valid_users and self._valid_users[username] == password:
-                self._state = "AUTHENTICATED"
-                _log("auth", src=self._peer[0], username=username, password=password, status="success")
-                self._transport.write(f"{tag} OK [CAPABILITY IMAP4rev1] Logged in\r\n".encode())
-            else:
-                _log("auth", src=self._peer[0], username=username, password=password, status="failed")
-                self._transport.write(f"{tag} NO [AUTHENTICATIONFAILED] Authentication failed.\r\n".encode())
-                
-        elif cmd == "SELECT" or cmd == "EXAMINE":
-            if self._state == "NOT_AUTHENTICATED":
-                self._transport.write(f"{tag} BAD Not authenticated\r\n".encode())
-                return
-            
-            self._state = "SELECTED"
-            count = len(_BAIT_EMAILS)
-            self._transport.write(f"* {count} EXISTS\r\n* 0 RECENT\r\n* OK [UIDVALIDITY 1] UIDs valid\r\n".encode())
-            self._transport.write(f"{tag} OK [READ-WRITE] Select completed.\r\n".encode())
 
-        elif cmd == "FETCH":
+        elif cmd == "NOOP":
-            if self._state != "SELECTED":
+            self._w(f"{tag} OK\r\n")
-                self._transport.write(f"{tag} BAD Not selected\r\n".encode())
-                return
-                
-            # rudimentary fetch match simply returning all if any match
-            # an attacker usually sends "FETCH 1:* (BODY[])" or similar
-            if "RFC822" in args.upper() or "BODY" in args.upper():
-                for uid, content in _BAIT_EMAILS:
-                    content_encoded = content.encode()
-                    self._transport.write(f"* {uid} FETCH (RFC822 {{{len(content_encoded)}}}\r\n".encode())
-                    self._transport.write(content_encoded)
-                    self._transport.write(b")\r\n")
-            self._transport.write(f"{tag} OK Fetch completed.\r\n".encode())
 
         elif cmd == "LOGOUT":
-            self._transport.write(b"* BYE Logging out\r\n")
+            self._w(b"* BYE Logging out\r\n")
-            self._transport.write(f"{tag} OK Logout completed.\r\n".encode())
+            self._w(f"{tag} OK LOGOUT completed\r\n")
             self._transport.close()
-            
-        else:
-            self._transport.write(f"{tag} BAD Command not recognized or unsupported\r\n".encode())
 
-    def connection_lost(self, exc):
+        # NOT_AUTHENTICATED only
-        _log("disconnect", src=self._peer[0] if self._peer else "?")
+        elif cmd == "LOGIN":
+            self._cmd_login(tag, args)
+
+        # AUTHENTICATED or SELECTED
+        elif cmd in ("LIST", "LSUB"):
+            self._cmd_list(tag, cmd)
+        elif cmd == "STATUS":
+            self._cmd_status(tag, args)
+        elif cmd in ("SELECT", "EXAMINE"):
+            self._cmd_select(tag, cmd, args)
+
+        # SELECTED only
+        elif cmd == "FETCH":
+            self._cmd_fetch(tag, args, use_uid=False)
+        elif cmd == "SEARCH":
+            self._cmd_search(tag)
+        elif cmd == "CLOSE":
+            self._cmd_close(tag)
+
+        # UID prefix — dispatch sub-command
+        elif cmd == "UID":
+            sub_parts = args.split(None, 1)
+            sub_cmd  = sub_parts[0].upper() if sub_parts else ""
+            sub_args = sub_parts[1] if len(sub_parts) > 1 else ""
+            if sub_cmd == "FETCH":
+                self._cmd_fetch(tag, sub_args, use_uid=True)
+            elif sub_cmd == "SEARCH":
+                self._cmd_search(tag, uid_mode=True)
+            else:
+                self._w(f"{tag} BAD Unknown UID sub-command\r\n")
+
+        else:
+            self._w(f"{tag} BAD Command not recognized or not supported\r\n")
+
+    # ── Command implementations ───────────────────────────────────────────────
+
+    def _cmd_login(self, tag: str, args: str) -> None:
+        if self._state != "NOT_AUTHENTICATED":
+            self._w(f"{tag} BAD Already authenticated\r\n")
+            return
+        parts    = args.split(None, 1)
+        username = parts[0].strip('"') if parts else ""
+        password = parts[1].strip('"') if len(parts) > 1 else ""
+        if VALID_USERS.get(username) == password:
+            self._state = "AUTHENTICATED"
+            _log("auth", src=self._peer[0], username=username, password=password,
+                 status="success")
+            self._w(f"{tag} OK [CAPABILITY IMAP4rev1] Logged in\r\n")
+        else:
+            _log("auth", src=self._peer[0], username=username, password=password,
+                 status="failed", severity=SEVERITY_WARNING)
+            self._w(f"{tag} NO [AUTHENTICATIONFAILED] Authentication failed.\r\n")
+
+    def _cmd_list(self, tag: str, cmd: str) -> None:
+        if self._state == "NOT_AUTHENTICATED":
+            self._w(f"{tag} BAD Not authenticated\r\n")
+            return
+        for box in _MAILBOXES:
+            self._w(f'* {cmd} (\\HasNoChildren) "/" "{box}"\r\n')
+        self._w(f"{tag} OK {cmd} completed\r\n")
+
+    def _cmd_status(self, tag: str, args: str) -> None:
+        if self._state == "NOT_AUTHENTICATED":
+            self._w(f"{tag} BAD Not authenticated\r\n")
+            return
+        parts   = args.split(None, 1)
+        mailbox = parts[0].strip('"') if parts else "INBOX"
+        attr_str = parts[1].strip("()").upper() if len(parts) > 1 else "MESSAGES"
+
+        counts = {"MESSAGES": 10, "RECENT": 0, "UNSEEN": 10} if mailbox == "INBOX" \
+            else {"MESSAGES": 0, "RECENT": 0, "UNSEEN": 0}
+
+        result_parts = []
+        for attr in attr_str.split():
+            if attr in counts:
+                result_parts.append(f"{attr} {counts[attr]}")
+        self._w(f"* STATUS {mailbox} ({' '.join(result_parts)})\r\n")
+        self._w(f"{tag} OK STATUS completed\r\n")
+
+    def _cmd_select(self, tag: str, cmd: str, args: str) -> None:
+        if self._state == "NOT_AUTHENTICATED":
+            self._w(f"{tag} BAD Not authenticated\r\n")
+            return
+        mailbox = args.strip('"')
+        total   = len(_BAIT_EMAILS) if mailbox == "INBOX" else 0
+        self._selected = mailbox
+        self._state    = "SELECTED"
+        self._w(f"* {total} EXISTS\r\n")
+        self._w(b"* 0 RECENT\r\n")
+        self._w(b"* OK [UNSEEN 1] Message 1 is first unseen\r\n")
+        self._w(b"* OK [UIDVALIDITY 1712345678] UIDs valid\r\n")
+        self._w(f"* OK [UIDNEXT {total + 1}] Predicted next UID\r\n")
+        self._w(b"* FLAGS (\\Answered \\Flagged \\Deleted \\Seen \\Draft)\r\n")
+        self._w(b"* OK [PERMANENTFLAGS (\\Deleted \\Seen \\*)] Limited\r\n")
+        mode = "READ-ONLY" if cmd == "EXAMINE" else "READ-WRITE"
+        self._w(f"{tag} OK [{mode}] {cmd} completed\r\n")
+
+    def _cmd_fetch(self, tag: str, args: str, use_uid: bool) -> None:
+        if self._state != "SELECTED":
+            self._w(f"{tag} BAD Not in selected state\r\n")
+            return
+        parts     = args.split(None, 1)
+        range_str = parts[0] if parts else "1:*"
+        items_str = parts[1] if len(parts) > 1 else "FLAGS"
+
+        total    = len(_BAIT_EMAILS)
+        indices  = _parse_seq_range(range_str, total)
+        items    = _parse_fetch_items(items_str)
+        # Ensure UID is included when using UID FETCH
+        if use_uid and "UID" not in items:
+            items = ["UID"] + items
+
+        for seq in indices:
+            if 1 <= seq <= total:
+                self._transport.write(_build_fetch_response(seq, _BAIT_EMAILS[seq - 1], items))
+        self._w(f"{tag} OK FETCH completed\r\n")
+
+    def _cmd_search(self, tag: str, uid_mode: bool = False) -> None:
+        if self._state != "SELECTED":
+            self._w(f"{tag} BAD Not in selected state\r\n")
+            return
+        nums = " ".join(str(i) for i in range(1, len(_BAIT_EMAILS) + 1))
+        self._w(f"* SEARCH {nums}\r\n")
+        self._w(f"{tag} OK SEARCH completed\r\n")
+
+    def _cmd_close(self, tag: str) -> None:
+        if self._state != "SELECTED":
+            self._w(f"{tag} BAD Not in selected state\r\n")
+            return
+        self._state    = "AUTHENTICATED"
+        self._selected = None
+        self._w(f"{tag} OK CLOSE completed\r\n")
+
+    # ── Helpers ───────────────────────────────────────────────────────────────
+
+    def _w(self, data: str | bytes) -> None:
+        if isinstance(data, str):
+            data = data.encode()
+        self._transport.write(data)
 
 
 async def main():

templates/pop3/server.py

@@ -1,55 +1,189 @@
 #!/usr/bin/env python3
 """
-POP3 server (port 110/995).
+POP3 server (port 110).
-Presents a POP3 banner, captures USER and PASS credentials.
+Full POP3 state machine with bait mailbox.
-Implements a basic POP3 state machine (AUTHORIZATION -> TRANSACTION).
+
-Provides hardcoded bait emails.
+States: AUTHORIZATION → TRANSACTION
-Logs commands as JSON.
+
+Credentials via IMAP_USERS env var (shared with IMAP service).
+10 bait emails containing AWS keys, DB passwords, tokens etc.
 """
 
 import asyncio
 import os
-from decnet_logging import syslog_line, write_syslog_file, forward_syslog
+from decnet_logging import SEVERITY_WARNING, syslog_line, write_syslog_file, forward_syslog
 
-NODE_NAME = os.environ.get("NODE_NAME", "mailserver")
+NODE_NAME    = os.environ.get("NODE_NAME", "mailserver")
-SERVICE_NAME   = "pop3"
+SERVICE_NAME  = "pop3"
-LOG_TARGET = os.environ.get("LOG_TARGET", "")
+LOG_TARGET   = os.environ.get("LOG_TARGET", "")
-POP3_BANNER = os.environ.get("IMAP_BANNER", f"+OK [{NODE_NAME}] Dovecot ready.\r\n")
+POP3_BANNER  = os.environ.get("POP3_BANNER", f"+OK {NODE_NAME} Dovecot POP3 ready.")
+_RAW_USERS   = os.environ.get("IMAP_USERS", "admin:admin123,root:toor,mail:mail,user:user")
 
-IMAP_USERS = os.environ.get("IMAP_USERS", "admin:admin123,root:toor")
+VALID_USERS: dict[str, str] = {
+    u: p for part in _RAW_USERS.split(",") if ":" in part for u, p in [part.split(":", 1)]
+}
 
-_BAIT_EMAILS = [
+# DEBT-026: path to a JSON file with custom email definitions.
-    "Date: Tue, 01 Nov 2023 10:00:00 +0000\r\nFrom: sysadmin@company.com\r\nSubject: AWS Credentials\r\n\r\nHere are the new AWS keys:\r\nAKIAIOSFODNN7EXAMPLE\r\nwJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\r\n",
+# Wiring (service_cfg["email_seed"] → compose_fragment → env var → here) is deferred.
-    "Date: Wed, 02 Nov 2023 11:30:00 +0000\r\nFrom: devops@company.com\r\nSubject: DB Password Reset\r\n\r\nThe production database password has been temporarily set to:\r\nProdDB_temp_2023!!\r\n",
+_EMAIL_SEED_PATH = os.environ.get("POP3_EMAIL_SEED", "")  # stub — currently unused
+
+# ── Bait emails ───────────────────────────────────────────────────────────────
+
+_BAIT_EMAILS: list[str] = [
+    (
+        "Date: Mon, 06 Nov 2023 09:12:33 +0000\r\n"
+        "From: DevOps Team <devops@company.internal>\r\n"
+        "To: admin@company.internal\r\n"
+        "Subject: AWS credentials rotation\r\n"
+        "Message-ID: <1@company.internal>\r\n"
+        "\r\n"
+        "Team,\r\n\r\n"
+        "New AWS credentials have been issued. Old keys deactivated.\r\n\r\n"
+        "Access Key ID:     AKIAIOSFODNN7EXAMPLE\r\n"
+        "Secret Access Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\r\n\r\n"
+        "Update ~/.aws/credentials immediately.\r\n\r\n-- DevOps\r\n"
+    ),
+    (
+        "Date: Tue, 07 Nov 2023 14:05:11 +0000\r\n"
+        "From: Monitoring <monitoring@company.internal>\r\n"
+        "To: admin@company.internal\r\n"
+        "Subject: DB password changed\r\n"
+        "Message-ID: <2@company.internal>\r\n"
+        "\r\n"
+        "Production database password was rotated.\r\n\r\n"
+        "Connection string: mysql://admin:Sup3rS3cr3t!@10.0.1.5:3306/production\r\n\r\n"
+        "Update all app configs.\r\n"
+    ),
+    (
+        "Date: Wed, 08 Nov 2023 08:30:00 +0000\r\n"
+        "From: GitHub <noreply@github.com>\r\n"
+        "To: admin@company.internal\r\n"
+        "Subject: Your personal access token\r\n"
+        "Message-ID: <3@company.internal>\r\n"
+        "\r\n"
+        "Hi admin,\r\n\r\n"
+        "A new personal access token was created for your account.\r\n\r\n"
+        "Token: ghp_16C7e42F292c6912E7710c838347Ae178B4a\r\n\r\n"
+        "If this wasn't you, revoke it immediately at github.com/settings/tokens.\r\n"
+    ),
+    (
+        "Date: Thu, 09 Nov 2023 11:22:47 +0000\r\n"
+        "From: IT Admin <admin@company.internal>\r\n"
+        "To: team@company.internal\r\n"
+        "Subject: VPN config attached\r\n"
+        "Message-ID: <4@company.internal>\r\n"
+        "\r\n"
+        "VPN access details for new starters:\r\n\r\n"
+        "  Host:     vpn.company.internal:1194\r\n"
+        "  Protocol: UDP\r\n"
+        "  Username: vpnadmin\r\n"
+        "  Password: VpnP@ss2024\r\n\r\n"
+        "Config file sent separately via secure channel.\r\n"
+    ),
+    (
+        "Date: Fri, 10 Nov 2023 16:45:00 +0000\r\n"
+        "From: SysAdmin <sysadmin@company.internal>\r\n"
+        "To: admin@company.internal\r\n"
+        "Subject: Root password\r\n"
+        "Message-ID: <5@company.internal>\r\n"
+        "\r\n"
+        "New root password for prod servers:\r\n\r\n"
+        "  r00tM3T00!\r\n\r\n"
+        "Change after first login. Do NOT forward this email.\r\n"
+    ),
+    (
+        "Date: Sat, 11 Nov 2023 03:12:04 +0000\r\n"
+        "From: Backup System <backup@company.internal>\r\n"
+        "To: admin@company.internal\r\n"
+        "Subject: Backup job failed\r\n"
+        "Message-ID: <6@company.internal>\r\n"
+        "\r\n"
+        "Nightly backup to 192.168.1.50:/mnt/nas FAILED at 03:11 UTC.\r\n\r\n"
+        "Error: Authentication failed. Credentials in /etc/backup.conf may be stale.\r\n\r\n"
+        "Last successful backup: 2023-11-10 03:11 UTC\r\n"
+    ),
+    (
+        "Date: Sun, 12 Nov 2023 07:04:31 +0000\r\n"
+        "From: Security Alerts <alerts@company.internal>\r\n"
+        "To: admin@company.internal\r\n"
+        "Subject: SSH brute-force alert\r\n"
+        "Message-ID: <7@company.internal>\r\n"
+        "\r\n"
+        "47 failed SSH login attempts detected against prod-web-01.\r\n\r\n"
+        "Source IPs: 185.220.101.34, 185.220.101.47, 185.220.101.52\r\n"
+        "Target user: root\r\n"
+        "Period: 2023-11-12 06:58 - 07:04 UTC\r\n\r\n"
+        "All attempts blocked by fail2ban. No successful logins.\r\n"
+    ),
+    (
+        "Date: Mon, 13 Nov 2023 10:11:55 +0000\r\n"
+        "From: External Vendor <vendor@external.com>\r\n"
+        "To: admin@company.internal\r\n"
+        "Subject: RE: API integration\r\n"
+        "Message-ID: <8@company.internal>\r\n"
+        "\r\n"
+        "Hi,\r\n\r\n"
+        "Here is the live API key for the integration:\r\n\r\n"
+        "  sk_live_9mK3xF2aP7qR1bN8cT4dW6vE0yU5hJ\r\n\r\n"
+        "Keep this confidential. Let me know if you need the webhook secret.\r\n\r\n"
+        "Best regards,\r\nVendor Support\r\n"
+    ),
+    (
+        "Date: Tue, 14 Nov 2023 13:48:22 +0000\r\n"
+        "From: Help Desk <helpdesk@company.internal>\r\n"
+        "To: admin@company.internal\r\n"
+        "Subject: Password reset request\r\n"
+        "Message-ID: <9@company.internal>\r\n"
+        "\r\n"
+        "Hi,\r\n\r\n"
+        "Could you reset my MFA? Current password is Winter2024! so you can verify it's me.\r\n\r\n"
+        "Thanks\r\n"
+    ),
+    (
+        "Date: Wed, 15 Nov 2023 00:01:00 +0000\r\n"
+        "From: AWS Billing <noreply@aws.amazon.com>\r\n"
+        "To: admin@company.internal\r\n"
+        "Subject: Your AWS bill is ready\r\n"
+        "Message-ID: <10@company.internal>\r\n"
+        "\r\n"
+        "Your AWS bill for October 2023 is $847.23.\r\n\r\n"
+        "Top services:\r\n"
+        "  EC2 (us-east-1):   $412.10\r\n"
+        "  RDS (us-east-1):   $198.50\r\n"
+        "  S3:                 $87.43\r\n"
+        "  EC2 (eu-west-2):   $149.20\r\n\r\n"
+        "Account ID: 123456789012\r\n"
+    ),
 ]
 
+# ── Logging ───────────────────────────────────────────────────────────────────
+
 def _log(event_type: str, severity: int = 6, **kwargs) -> None:
     line = syslog_line(SERVICE_NAME, NODE_NAME, event_type, severity, **kwargs)
     print(line, flush=True)
     write_syslog_file(line)
     forward_syslog(line, LOG_TARGET)
 
+
+# ── Protocol ──────────────────────────────────────────────────────────────────
+
 class POP3Protocol(asyncio.Protocol):
     def __init__(self):
-        self._transport = None
+        self._transport    = None
-        self._peer = None
+        self._peer         = ("?", 0)
-        self._buf = b""
+        self._buf          = b""
-        self._state = "AUTHORIZATION"
+        self._state        = "AUTHORIZATION"
-        self._valid_users = dict(u.split(":", 1) for u in IMAP_USERS.split(",") if ":" in u)
+        self._current_user: str | None = None
-        self._current_user = None
+        self._deleted: set[int] = set()   # 0-based indices of DELE'd messages
 
     def connection_made(self, transport):
         self._transport = transport
         self._peer = transport.get_extra_info("peername", ("?", 0))
         _log("connect", src=self._peer[0], src_port=self._peer[1])
-        if POP3_BANNER:
+        banner = POP3_BANNER if POP3_BANNER.endswith("\r\n") else POP3_BANNER + "\r\n"
-            if not POP3_BANNER.endswith("\r\n"):
+        if not banner.startswith("+OK"):
-                padded_banner = POP3_BANNER + "\r\n"
+            banner = "+OK " + banner
-            else:
+        transport.write(banner.encode())
-                padded_banner = POP3_BANNER
-            if not padded_banner.startswith("+OK"):
-                padded_banner = "+OK " + padded_banner.lstrip("* OK ") # replace IMAP prefix with POP3
-            transport.write(padded_banner.encode())
 
     def data_received(self, data):
         self._buf += data
@@ -57,98 +191,216 @@ class POP3Protocol(asyncio.Protocol):
             line, self._buf = self._buf.split(b"\n", 1)
             self._handle_line(line.decode(errors="replace").strip())
 
-    def _handle_line(self, line: str):
+    def connection_lost(self, exc):
+        _log("disconnect", src=self._peer[0] if self._peer else "?")
+
+    # ── Command dispatch ──────────────────────────────────────────────────────
+
+    def _handle_line(self, line: str) -> None:
         parts = line.split(None, 1)
         if not parts:
             return
-        cmd = parts[0].upper()
+        cmd  = parts[0].upper()
         args = parts[1] if len(parts) > 1 else ""
 
-        _log("command", src=self._peer[0], cmd=line[:128], state=self._state)
+        _log("command", src=self._peer[0], cmd=cmd, state=self._state)
 
+        # Always available
         if cmd == "CAPA":
-            self._transport.write(b"+OK Capability list follows\r\nUSER\r\n.\r\n")
+            self._transport.write(
-
+                b"+OK\r\nTOP\r\nUSER\r\nUIDL\r\nRESP-CODES\r\nAUTH-RESP-CODE\r\nSASL\r\n.\r\n"
-        elif cmd == "USER":
+            )
-            if self._state != "AUTHORIZATION":
-                self._transport.write(b"-ERR Already authenticated.\r\n")
-                return
-            self._current_user = args
-            self._transport.write(b"+OK User name accepted, password please\r\n")
-
-        elif cmd == "PASS":
-            if self._state != "AUTHORIZATION":
-                self._transport.write(b"-ERR Already authenticated.\r\n")
-                return
-            if not self._current_user:
-                self._transport.write(b"-ERR USER required first.\r\n")
-                return
-                
-            password = args
-            username = self._current_user
-            
-            if username in self._valid_users and self._valid_users[username] == password:
-                self._state = "TRANSACTION"
-                _log("auth", src=self._peer[0], username=username, password=password, status="success")
-                self._transport.write(b"+OK Logged in.\r\n")
-            else:
-                _log("auth", src=self._peer[0], username=username, password=password, status="failed")
-                self._transport.write(b"-ERR Authentication failed.\r\n")
-                self._current_user = None
-
-        elif cmd == "STAT":
-            if self._state != "TRANSACTION":
-                self._transport.write(b"-ERR Not authenticated\r\n")
-                return
-            total_size = sum(len(e) for e in _BAIT_EMAILS)
-            self._transport.write(f"+OK {len(_BAIT_EMAILS)} {total_size}\r\n".encode())
-
-        elif cmd == "LIST":
-            if self._state != "TRANSACTION":
-                self._transport.write(b"-ERR Not authenticated\r\n")
-                return
-            
-            if args:
-                try:
-                    idx = int(args) - 1
-                    if 0 <= idx < len(_BAIT_EMAILS):
-                        self._transport.write(f"+OK {idx + 1} {len(_BAIT_EMAILS[idx])}\r\n".encode())
-                    else:
-                        self._transport.write(b"-ERR No such message\r\n")
-                except ValueError:
-                    self._transport.write(b"-ERR Invalid argument\r\n")
-            else:
-                total_size = sum(len(e) for e in _BAIT_EMAILS)
-                self._transport.write(f"+OK {len(_BAIT_EMAILS)} messages ({total_size} octets)\r\n".encode())
-                for i, email in enumerate(_BAIT_EMAILS):
-                    self._transport.write(f"{i + 1} {len(email)}\r\n".encode())
-                self._transport.write(b".\r\n")
-
-        elif cmd == "RETR":
-            if self._state != "TRANSACTION":
-                self._transport.write(b"-ERR Not authenticated\r\n")
-                return
-            try:
-                idx = int(args) - 1
-                if 0 <= idx < len(_BAIT_EMAILS):
-                    email = _BAIT_EMAILS[idx]
-                    self._transport.write(f"+OK {len(email)} octets\r\n".encode())
-                    self._transport.write(email.encode())
-                    self._transport.write(b".\r\n")
-                else:
-                    self._transport.write(b"-ERR No such message\r\n")
-            except ValueError:
-                self._transport.write(b"-ERR Invalid argument\r\n")
-
         elif cmd == "QUIT":
             self._transport.write(b"+OK Logging out.\r\n")
             self._transport.close()
-            
+
+        # AUTHORIZATION state
+        elif cmd == "USER":
+            self._cmd_user(args)
+        elif cmd == "PASS":
+            self._cmd_pass(args)
+
+        # TRANSACTION state
+        elif cmd == "STAT":
+            self._cmd_stat()
+        elif cmd == "LIST":
+            self._cmd_list(args)
+        elif cmd == "RETR":
+            self._cmd_retr(args)
+        elif cmd == "TOP":
+            self._cmd_top(args)
+        elif cmd == "UIDL":
+            self._cmd_uidl(args)
+        elif cmd == "DELE":
+            self._cmd_dele(args)
+        elif cmd == "RSET":
+            self._cmd_rset()
+        elif cmd == "NOOP":
+            self._transport.write(b"+OK\r\n")
+
         else:
             self._transport.write(b"-ERR Command not recognized\r\n")
 
-    def connection_lost(self, exc):
+    # ── Command implementations ───────────────────────────────────────────────
-        _log("disconnect", src=self._peer[0] if self._peer else "?")
+
+    def _cmd_user(self, args: str) -> None:
+        if self._state != "AUTHORIZATION":
+            self._transport.write(b"-ERR Already authenticated\r\n")
+            return
+        self._current_user = args.strip()
+        self._transport.write(b"+OK User name accepted, password please\r\n")
+
+    def _cmd_pass(self, args: str) -> None:
+        if self._state != "AUTHORIZATION":
+            self._transport.write(b"-ERR Already authenticated\r\n")
+            return
+        if not self._current_user:
+            self._transport.write(b"-ERR USER required first\r\n")
+            return
+        username = self._current_user
+        password = args.strip()
+        if VALID_USERS.get(username) == password:
+            self._state = "TRANSACTION"
+            _log("auth", src=self._peer[0], username=username, password=password,
+                 status="success")
+            self._transport.write(b"+OK Logged in.\r\n")
+        else:
+            _log("auth", src=self._peer[0], username=username, password=password,
+                 status="failed", severity=SEVERITY_WARNING)
+            self._current_user = None
+            self._transport.write(b"-ERR Authentication failed.\r\n")
+
+    def _require_transaction(self) -> bool:
+        if self._state != "TRANSACTION":
+            self._transport.write(b"-ERR Not authenticated\r\n")
+            return False
+        return True
+
+    def _active_messages(self) -> list[tuple[int, str]]:
+        """Return [(1-based-num, body), ...] excluding DELE'd messages."""
+        return [
+            (i + 1, body)
+            for i, body in enumerate(_BAIT_EMAILS)
+            if i not in self._deleted
+        ]
+
+    def _cmd_stat(self) -> None:
+        if not self._require_transaction():
+            return
+        msgs = self._active_messages()
+        total = sum(len(b.encode()) for _, b in msgs)
+        self._transport.write(f"+OK {len(msgs)} {total}\r\n".encode())
+
+    def _cmd_list(self, args: str) -> None:
+        if not self._require_transaction():
+            return
+        if args:
+            try:
+                n = int(args)
+                idx = n - 1
+                if idx in self._deleted or not (0 <= idx < len(_BAIT_EMAILS)):
+                    self._transport.write(b"-ERR No such message\r\n")
+                else:
+                    size = len(_BAIT_EMAILS[idx].encode())
+                    self._transport.write(f"+OK {n} {size}\r\n".encode())
+            except ValueError:
+                self._transport.write(b"-ERR Invalid argument\r\n")
+        else:
+            msgs  = self._active_messages()
+            total = sum(len(b.encode()) for _, b in msgs)
+            self._transport.write(f"+OK {len(msgs)} messages ({total} octets)\r\n".encode())
+            for n, body in msgs:
+                self._transport.write(f"{n} {len(body.encode())}\r\n".encode())
+            self._transport.write(b".\r\n")
+
+    def _cmd_retr(self, args: str) -> None:
+        if not self._require_transaction():
+            return
+        try:
+            n   = int(args)
+            idx = n - 1
+            if idx in self._deleted or not (0 <= idx < len(_BAIT_EMAILS)):
+                self._transport.write(b"-ERR No such message\r\n")
+                return
+            body = _BAIT_EMAILS[idx]
+            raw  = body.encode()
+            _log("retr", src=self._peer[0], message_num=n)
+            self._transport.write(f"+OK {len(raw)} octets\r\n".encode())
+            self._transport.write(raw)
+            if not raw.endswith(b"\r\n"):
+                self._transport.write(b"\r\n")
+            self._transport.write(b".\r\n")
+        except ValueError:
+            self._transport.write(b"-ERR Invalid argument\r\n")
+
+    def _cmd_top(self, args: str) -> None:
+        if not self._require_transaction():
+            return
+        try:
+            parts     = args.split(None, 1)
+            n         = int(parts[0])
+            line_count = int(parts[1]) if len(parts) > 1 else 0
+            idx = n - 1
+            if idx in self._deleted or not (0 <= idx < len(_BAIT_EMAILS)):
+                self._transport.write(b"-ERR No such message\r\n")
+                return
+            body    = _BAIT_EMAILS[idx]
+            sep     = "\r\n\r\n"
+            if sep in body:
+                headers, rest = body.split(sep, 1)
+                headers += sep
+            else:
+                headers, rest = body, ""
+            body_lines = rest.split("\r\n")[:line_count]
+            result     = headers + "\r\n".join(body_lines)
+            self._transport.write(b"+OK\r\n")
+            self._transport.write(result.encode())
+            if not result.endswith("\r\n"):
+                self._transport.write(b"\r\n")
+            self._transport.write(b".\r\n")
+        except (ValueError, IndexError):
+            self._transport.write(b"-ERR Invalid arguments\r\n")
+
+    def _cmd_uidl(self, args: str) -> None:
+        if not self._require_transaction():
+            return
+        if args:
+            try:
+                n   = int(args)
+                idx = n - 1
+                if idx in self._deleted or not (0 <= idx < len(_BAIT_EMAILS)):
+                    self._transport.write(b"-ERR No such message\r\n")
+                else:
+                    self._transport.write(f"+OK {n} msg-{n}\r\n".encode())
+            except ValueError:
+                self._transport.write(b"-ERR Invalid argument\r\n")
+        else:
+            self._transport.write(b"+OK\r\n")
+            for n, _ in self._active_messages():
+                self._transport.write(f"{n} msg-{n}\r\n".encode())
+            self._transport.write(b".\r\n")
+
+    def _cmd_dele(self, args: str) -> None:
+        if not self._require_transaction():
+            return
+        try:
+            n   = int(args)
+            idx = n - 1
+            if idx in self._deleted or not (0 <= idx < len(_BAIT_EMAILS)):
+                self._transport.write(b"-ERR No such message\r\n")
+            else:
+                self._deleted.add(idx)
+                _log("delete", src=self._peer[0], message_num=n)
+                self._transport.write(f"+OK Message {n} deleted\r\n".encode())
+        except ValueError:
+            self._transport.write(b"-ERR Invalid argument\r\n")
+
+    def _cmd_rset(self) -> None:
+        if not self._require_transaction():
+            return
+        self._deleted.clear()
+        self._transport.write(b"+OK\r\n")
+
 
 async def main():
     _log("startup", msg=f"POP3 server starting as {NODE_NAME}")
@@ -157,5 +409,6 @@ async def main():
     async with server:
         await server.serve_forever()
 
+
 if __name__ == "__main__":
     asyncio.run(main())

tests/service_testing/test_imap.py

@@ -1,7 +1,10 @@
 """
 Tests for templates/imap/server.py
 
-Exercises IMAP state machine, auth, and negative tests.
+Exercises the full IMAP4rev1 state machine:
+  NOT_AUTHENTICATED → AUTHENTICATED → SELECTED
+
+Uses asyncio Protocol directly — no network socket needed.
 """
 
 import importlib.util
@@ -12,6 +15,8 @@ from unittest.mock import MagicMock, patch
 import pytest
 
 
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
 def _make_fake_decnet_logging() -> ModuleType:
     mod = ModuleType("decnet_logging")
     mod.syslog_line = MagicMock(return_value="")
@@ -21,11 +26,13 @@ def _make_fake_decnet_logging() -> ModuleType:
     mod.SEVERITY_INFO = 6
     return mod
 
+
 def _load_imap():
+    """Import imap server module, injecting a stub decnet_logging."""
     env = {
         "NODE_NAME": "testhost",
         "IMAP_USERS": "admin:admin123,root:toor",
-        "IMAP_BANNER": "* OK [testhost] Dovecot ready."
+        "IMAP_BANNER": "* OK [testhost] Dovecot ready.",
     }
     for key in list(sys.modules):
         if key in ("imap_server", "decnet_logging"):
@@ -33,13 +40,17 @@ def _load_imap():
 
     sys.modules["decnet_logging"] = _make_fake_decnet_logging()
 
-    spec = importlib.util.spec_from_file_location("imap_server", "templates/imap/server.py")
+    spec = importlib.util.spec_from_file_location(
+        "imap_server", "templates/imap/server.py"
+    )
     mod = importlib.util.module_from_spec(spec)
     with patch.dict("os.environ", env, clear=False):
         spec.loader.exec_module(mod)
     return mod
 
+
 def _make_protocol(mod):
+    """Return (protocol, transport, written). Banner already cleared."""
     proto = mod.IMAPProtocol()
     transport = MagicMock()
     written: list[bytes] = []
@@ -48,42 +59,270 @@ def _make_protocol(mod):
     written.clear()
     return proto, transport, written
 
+
 def _send(proto, data: str) -> None:
     proto.data_received(data.encode() + b"\r\n")
 
+
+def _replies(written: list[bytes]) -> bytes:
+    return b"".join(written)
+
+
+def _login(proto, written):
+    _send(proto, "A0 LOGIN admin admin123")
+    written.clear()
+
+
+def _select_inbox(proto, written):
+    _send(proto, "B0 SELECT INBOX")
+    written.clear()
+
+
 @pytest.fixture
 def imap_mod():
     return _load_imap()
 
+
+# ── Tests: banner & unauthenticated ──────────────────────────────────────────
+
+def test_imap_banner_on_connect(imap_mod):
+    proto = imap_mod.IMAPProtocol()
+    transport = MagicMock()
+    written: list[bytes] = []
+    transport.write.side_effect = written.append
+    proto.connection_made(transport)
+    banner = b"".join(written)
+    assert banner.startswith(b"* OK")
+
+
+def test_imap_capability_contains_idle_and_literal_plus(imap_mod):
+    proto, _, written = _make_protocol(imap_mod)
+    _send(proto, "C1 CAPABILITY")
+    resp = _replies(written)
+    assert b"IMAP4rev1" in resp
+    assert b"IDLE" in resp
+    assert b"LITERAL+" in resp
+    assert b"AUTH=PLAIN" in resp
+
+
 def test_imap_login_success(imap_mod):
-    proto, transport, written = _make_protocol(imap_mod)
+    proto, _, written = _make_protocol(imap_mod)
-    _send(proto, 'A1 LOGIN admin admin123')
+    _send(proto, "A1 LOGIN admin admin123")
-    assert b"A1 OK" in b"".join(written)
+    assert b"A1 OK" in _replies(written)
     assert proto._state == "AUTHENTICATED"
 
+
 def test_imap_login_fail(imap_mod):
-    proto, transport, written = _make_protocol(imap_mod)
+    proto, _, written = _make_protocol(imap_mod)
-    _send(proto, 'A1 LOGIN admin wrongpass')
+    _send(proto, "A1 LOGIN admin wrongpass")
-    assert b"A1 NO" in b"".join(written)
+    resp = _replies(written)
+    assert b"A1 NO" in resp
+    assert b"AUTHENTICATIONFAILED" in resp
     assert proto._state == "NOT_AUTHENTICATED"
 
-def test_imap_select_before_auth(imap_mod):
+
+def test_imap_bad_creds_connection_stays_open(imap_mod):
     proto, transport, written = _make_protocol(imap_mod)
-    _send(proto, 'A2 SELECT INBOX')
+    _send(proto, "T1 LOGIN admin wrongpass")
-    assert b"A2 BAD" in b"".join(written)
+    transport.close.assert_not_called()
+
+
+def test_imap_retry_after_bad_credentials_succeeds(imap_mod):
+    proto, _, written = _make_protocol(imap_mod)
+    _send(proto, "T1 LOGIN admin wrongpass")
+    written.clear()
+    _send(proto, "T2 LOGIN admin admin123")
+    assert b"T2 OK" in _replies(written)
+    assert proto._state == "AUTHENTICATED"
+
+
+def test_imap_select_before_auth_returns_bad(imap_mod):
+    proto, _, written = _make_protocol(imap_mod)
+    _send(proto, "A2 SELECT INBOX")
+    assert b"A2 BAD" in _replies(written)
+
+
+def test_imap_noop_unauthenticated_returns_ok(imap_mod):
+    proto, _, written = _make_protocol(imap_mod)
+    _send(proto, "N1 NOOP")
+    assert b"N1 OK" in _replies(written)
+
+
+def test_imap_unknown_command_returns_bad(imap_mod):
+    proto, _, written = _make_protocol(imap_mod)
+    _send(proto, "X1 INVALID_COMMAND")
+    assert b"X1 BAD" in _replies(written)
+
+
+# ── Tests: authenticated state ────────────────────────────────────────────────
+
+def test_imap_list_returns_four_mailboxes(imap_mod):
+    proto, _, written = _make_protocol(imap_mod)
+    _login(proto, written)
+    _send(proto, 'L1 LIST "" "*"')
+    resp = _replies(written)
+    assert b"INBOX" in resp
+    assert b"Sent" in resp
+    assert b"Drafts" in resp
+    assert b"Archive" in resp
+    assert b"LIST completed" in resp
+
+
+def test_imap_lsub_mirrors_list(imap_mod):
+    proto, _, written = _make_protocol(imap_mod)
+    _login(proto, written)
+    _send(proto, 'L2 LSUB "" "*"')
+    resp = _replies(written)
+    assert b"INBOX" in resp
+    assert b"LSUB completed" in resp
+
+
+def test_imap_status_inbox_messages(imap_mod):
+    proto, _, written = _make_protocol(imap_mod)
+    _login(proto, written)
+    _send(proto, "S0 STATUS INBOX (MESSAGES)")
+    resp = _replies(written)
+    assert b"STATUS INBOX" in resp
+    assert b"MESSAGES 10" in resp
+
+
+# ── Tests: SELECTED state ─────────────────────────────────────────────────────
+
+def test_imap_select_inbox_exists_count(imap_mod):
+    proto, _, written = _make_protocol(imap_mod)
+    _login(proto, written)
+    _send(proto, "S1 SELECT INBOX")
+    resp = _replies(written)
+    assert b"* 10 EXISTS" in resp
+
+
+def test_imap_select_inbox_uidnext(imap_mod):
+    proto, _, written = _make_protocol(imap_mod)
+    _login(proto, written)
+    _send(proto, "S1 SELECT INBOX")
+    resp = _replies(written)
+    assert b"UIDNEXT 11" in resp
+
+
+def test_imap_select_inbox_read_write(imap_mod):
+    proto, _, written = _make_protocol(imap_mod)
+    _login(proto, written)
+    _send(proto, "S1 SELECT INBOX")
+    resp = _replies(written)
+    assert b"READ-WRITE" in resp
+
+
+def test_imap_examine_inbox_read_only(imap_mod):
+    proto, _, written = _make_protocol(imap_mod)
+    _login(proto, written)
+    _send(proto, "S2 EXAMINE INBOX")
+    resp = _replies(written)
+    assert b"READ-ONLY" in resp
+
+
+def test_imap_search_all_returns_all_seqs(imap_mod):
+    proto, _, written = _make_protocol(imap_mod)
+    _login(proto, written)
+    _select_inbox(proto, written)
+    _send(proto, "Q1 SEARCH ALL")
+    resp = _replies(written)
+    assert b"* SEARCH 1 2 3 4 5 6 7 8 9 10" in resp
+
+
+def test_imap_fetch_single_body_aws_key(imap_mod):
+    proto, _, written = _make_protocol(imap_mod)
+    _login(proto, written)
+    _select_inbox(proto, written)
+    _send(proto, "F1 FETCH 1 BODY[]")
+    resp = _replies(written)
+    assert b"AKIAIOSFODNN7EXAMPLE" in resp
+    assert b"F1 OK" in resp
+
 
 def test_imap_fetch_after_select(imap_mod):
-    proto, transport, written = _make_protocol(imap_mod)
+    proto, _, written = _make_protocol(imap_mod)
-    _send(proto, 'A1 LOGIN admin admin123')
+    _send(proto, "A1 LOGIN admin admin123")
     written.clear()
-    _send(proto, 'A2 SELECT INBOX')
+    _send(proto, "A2 SELECT INBOX")
     written.clear()
-    _send(proto, 'A3 FETCH 1 RFC822')
+    _send(proto, "A3 FETCH 1 RFC822")
-    combined = b"".join(written)
+    combined = _replies(written)
     assert b"A3 OK" in combined
     assert b"AKIAIOSFODNN7EXAMPLE" in combined
 
-def test_imap_invalid_command(imap_mod):
+
+def test_imap_fetch_msg5_root_password(imap_mod):
+    proto, _, written = _make_protocol(imap_mod)
+    _login(proto, written)
+    _select_inbox(proto, written)
+    _send(proto, "F2 FETCH 5 BODY[]")
+    resp = _replies(written)
+    assert b"r00tM3T00!" in resp
+
+
+def test_imap_fetch_range_flags_envelope_count(imap_mod):
+    proto, _, written = _make_protocol(imap_mod)
+    _login(proto, written)
+    _select_inbox(proto, written)
+    _send(proto, "F3 FETCH 1:3 (FLAGS ENVELOPE)")
+    resp = _replies(written)
+    assert b"* 1 FETCH" in resp
+    assert b"* 2 FETCH" in resp
+    assert b"* 3 FETCH" in resp
+    assert b"FETCH completed" in resp
+
+
+def test_imap_fetch_star_rfc822size_10_responses(imap_mod):
+    proto, _, written = _make_protocol(imap_mod)
+    _login(proto, written)
+    _select_inbox(proto, written)
+    _send(proto, "F4 FETCH 1:* RFC822.SIZE")
+    resp = _replies(written).decode(errors="replace")
+    assert resp.count(" FETCH ") >= 10
+    assert "F4 OK" in resp
+
+
+def test_imap_uid_fetch_includes_uid_field(imap_mod):
+    proto, _, written = _make_protocol(imap_mod)
+    _login(proto, written)
+    _select_inbox(proto, written)
+    _send(proto, "U1 UID FETCH 1:10 (FLAGS)")
+    resp = _replies(written)
+    assert b"UID 1" in resp
+    assert b"FETCH completed" in resp
+
+
+def test_imap_close_returns_to_authenticated(imap_mod):
+    proto, _, written = _make_protocol(imap_mod)
+    _login(proto, written)
+    _select_inbox(proto, written)
+    _send(proto, "C1 CLOSE")
+    resp = _replies(written)
+    assert b"CLOSE completed" in resp
+    assert proto._state == "AUTHENTICATED"
+
+
+def test_imap_fetch_after_close_returns_bad(imap_mod):
+    proto, _, written = _make_protocol(imap_mod)
+    _login(proto, written)
+    _select_inbox(proto, written)
+    _send(proto, "C1 CLOSE")
+    written.clear()
+    _send(proto, "C2 FETCH 1 FLAGS")
+    assert b"C2 BAD" in _replies(written)
+
+
+def test_imap_logout_sends_bye_and_closes(imap_mod):
     proto, transport, written = _make_protocol(imap_mod)
-    _send(proto, 'A1 INVALID')
+    _login(proto, written)
-    assert b"A1 BAD" in b"".join(written)
+    _send(proto, "L1 LOGOUT")
+    resp = _replies(written)
+    assert b"* BYE" in resp
+    assert b"LOGOUT completed" in resp
+    transport.close.assert_called_once()
+
+
+def test_imap_invalid_command(imap_mod):
+    proto, _, written = _make_protocol(imap_mod)
+    _send(proto, "A1 INVALID")
+    assert b"A1 BAD" in _replies(written)

tests/service_testing/test_pop3.py

@@ -1,7 +1,10 @@
 """
 Tests for templates/pop3/server.py
 
-Exercises POP3 state machine, auth, and negative tests.
+Exercises the full POP3 state machine:
+  AUTHORIZATION → TRANSACTION
+
+Uses asyncio Protocol directly — no network socket needed.
 """
 
 import importlib.util
@@ -12,6 +15,8 @@ from unittest.mock import MagicMock, patch
 import pytest
 
 
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
 def _make_fake_decnet_logging() -> ModuleType:
     mod = ModuleType("decnet_logging")
     mod.syslog_line = MagicMock(return_value="")
@@ -21,11 +26,12 @@ def _make_fake_decnet_logging() -> ModuleType:
     mod.SEVERITY_INFO = 6
     return mod
 
+
 def _load_pop3():
     env = {
         "NODE_NAME": "testhost",
         "IMAP_USERS": "admin:admin123,root:toor",
-        "IMAP_BANNER": "+OK [testhost] Dovecot ready."
+        "IMAP_BANNER": "+OK [testhost] Dovecot ready.",
     }
     for key in list(sys.modules):
         if key in ("pop3_server", "decnet_logging"):
@@ -33,13 +39,17 @@ def _load_pop3():
 
     sys.modules["decnet_logging"] = _make_fake_decnet_logging()
 
-    spec = importlib.util.spec_from_file_location("pop3_server", "templates/pop3/server.py")
+    spec = importlib.util.spec_from_file_location(
+        "pop3_server", "templates/pop3/server.py"
+    )
     mod = importlib.util.module_from_spec(spec)
     with patch.dict("os.environ", env, clear=False):
         spec.loader.exec_module(mod)
     return mod
 
+
 def _make_protocol(mod):
+    """Return (protocol, transport, written). Banner already cleared."""
     proto = mod.POP3Protocol()
     transport = MagicMock()
     written: list[bytes] = []
@@ -48,51 +58,229 @@ def _make_protocol(mod):
     written.clear()
     return proto, transport, written
 
+
 def _send(proto, data: str) -> None:
     proto.data_received(data.encode() + b"\r\n")
 
+
+def _replies(written: list[bytes]) -> bytes:
+    return b"".join(written)
+
+
+def _login(proto, written):
+    _send(proto, "USER admin")
+    _send(proto, "PASS admin123")
+    written.clear()
+
+
 @pytest.fixture
 def pop3_mod():
     return _load_pop3()
 
+
+# ── Tests: banner & unauthenticated ──────────────────────────────────────────
+
+def test_pop3_banner_starts_with_ok(pop3_mod):
+    proto = pop3_mod.POP3Protocol()
+    transport = MagicMock()
+    written: list[bytes] = []
+    transport.write.side_effect = written.append
+    proto.connection_made(transport)
+    banner = b"".join(written)
+    assert banner.startswith(b"+OK")
+
+
+def test_pop3_capa_contains_top_uidl_user(pop3_mod):
+    proto, _, written = _make_protocol(pop3_mod)
+    _send(proto, "CAPA")
+    resp = _replies(written)
+    assert b"TOP" in resp
+    assert b"UIDL" in resp
+    assert b"USER" in resp
+
+
 def test_pop3_login_success(pop3_mod):
-    proto, transport, written = _make_protocol(pop3_mod)
+    proto, _, written = _make_protocol(pop3_mod)
-    _send(proto, 'USER admin')
+    _send(proto, "USER admin")
-    assert b"+OK" in b"".join(written)
+    assert b"+OK" in _replies(written)
     written.clear()
-    _send(proto, 'PASS admin123')
+    _send(proto, "PASS admin123")
-    assert b"+OK Logged in" in b"".join(written)
+    assert b"+OK Logged in" in _replies(written)
     assert proto._state == "TRANSACTION"
 
+
 def test_pop3_login_fail(pop3_mod):
-    proto, transport, written = _make_protocol(pop3_mod)
+    proto, _, written = _make_protocol(pop3_mod)
-    _send(proto, 'USER admin')
+    _send(proto, "USER admin")
     written.clear()
-    _send(proto, 'PASS wrongpass')
+    _send(proto, "PASS wrongpass")
-    assert b"-ERR" in b"".join(written)
+    assert b"-ERR" in _replies(written)
     assert proto._state == "AUTHORIZATION"
 
-def test_pop3_pass_before_user(pop3_mod):
+
+def test_pop3_bad_pass_connection_stays_open(pop3_mod):
     proto, transport, written = _make_protocol(pop3_mod)
-    _send(proto, 'PASS admin123')
+    _send(proto, "USER admin")
-    assert b"-ERR" in b"".join(written)
+    _send(proto, "PASS wrongpass")
+    transport.close.assert_not_called()
+
+
+def test_pop3_retry_after_bad_pass_succeeds(pop3_mod):
+    proto, _, written = _make_protocol(pop3_mod)
+    _send(proto, "USER admin")
+    _send(proto, "PASS wrongpass")
+    written.clear()
+    _send(proto, "USER admin")
+    _send(proto, "PASS admin123")
+    assert b"+OK Logged in" in _replies(written)
+
+
+def test_pop3_pass_before_user(pop3_mod):
+    proto, _, written = _make_protocol(pop3_mod)
+    _send(proto, "PASS admin123")
+    assert b"-ERR" in _replies(written)
+
 
 def test_pop3_stat_before_auth(pop3_mod):
-    proto, transport, written = _make_protocol(pop3_mod)
+    proto, _, written = _make_protocol(pop3_mod)
-    _send(proto, 'STAT')
+    _send(proto, "STAT")
-    assert b"-ERR" in b"".join(written)
+    assert b"-ERR" in _replies(written)
 
-def test_pop3_retr_after_auth(pop3_mod):
+
-    proto, transport, written = _make_protocol(pop3_mod)
+def test_pop3_retr_before_auth(pop3_mod):
-    _send(proto, 'USER admin')
+    proto, _, written = _make_protocol(pop3_mod)
-    _send(proto, 'PASS admin123')
+    _send(proto, "RETR 1")
+    assert b"-ERR" in _replies(written)
+
+
+def test_pop3_invalid_command(pop3_mod):
+    proto, _, written = _make_protocol(pop3_mod)
+    _send(proto, "INVALID")
+    assert b"-ERR" in _replies(written)
+
+
+# ── Tests: TRANSACTION state ──────────────────────────────────────────────────
+
+def test_pop3_stat_10_messages(pop3_mod):
+    proto, _, written = _make_protocol(pop3_mod)
+    _login(proto, written)
+    _send(proto, "STAT")
+    resp = _replies(written).decode()
+    assert resp.startswith("+OK 10 ")
+
+
+def test_pop3_list_returns_10_entries(pop3_mod):
+    proto, _, written = _make_protocol(pop3_mod)
+    _login(proto, written)
+    _send(proto, "LIST")
+    resp = _replies(written).decode()
+    assert resp.startswith("+OK 10")
+    # Count individual message lines: "N size\r\n"
+    entries = [l for l in resp.split("\r\n") if l and l[0].isdigit()]
+    assert len(entries) == 10
+
+
+def test_pop3_retr_after_auth_msg1(pop3_mod):
+    proto, _, written = _make_protocol(pop3_mod)
+    _send(proto, "USER admin")
+    _send(proto, "PASS admin123")
     written.clear()
-    _send(proto, 'RETR 1')
+    _send(proto, "RETR 1")
-    combined = b"".join(written)
+    combined = _replies(written)
     assert b"+OK" in combined
     assert b"AKIAIOSFODNN7EXAMPLE" in combined
 
-def test_pop3_invalid_command(pop3_mod):
+
+def test_pop3_retr_msg5_root_password(pop3_mod):
+    proto, _, written = _make_protocol(pop3_mod)
+    _login(proto, written)
+    _send(proto, "RETR 5")
+    resp = _replies(written)
+    assert b"+OK" in resp
+    assert b"r00tM3T00!" in resp
+
+
+def test_pop3_top_returns_headers_plus_lines(pop3_mod):
+    proto, _, written = _make_protocol(pop3_mod)
+    _login(proto, written)
+    _send(proto, "TOP 1 3")
+    resp = _replies(written).decode(errors="replace")
+    assert resp.startswith("+OK")
+    # Headers must be present
+    assert "From:" in resp
+    assert "Subject:" in resp
+    # Should NOT contain body content beyond 3 lines — but 3 lines of the
+    # AWS email body are enough to include the access key
+    assert ".\r\n" in resp
+
+
+def test_pop3_top_3_body_lines_count(pop3_mod):
+    proto, _, written = _make_protocol(pop3_mod)
+    _login(proto, written)
+    # Message 1 body after blank line:
+    # "Team,\r\n", "\r\n", "New AWS credentials...\r\n", ...
+    _send(proto, "TOP 1 3")
+    resp = _replies(written).decode(errors="replace")
+    # Strip headers up to blank line
+    parts = resp.split("\r\n\r\n", 1)
+    assert len(parts) == 2
+    body_section = parts[1].rstrip("\r\n.")
+    body_lines = [l for l in body_section.split("\r\n") if l != "."]
+    assert len(body_lines) <= 3
+
+
+def test_pop3_uidl_returns_10_entries(pop3_mod):
+    proto, _, written = _make_protocol(pop3_mod)
+    _login(proto, written)
+    _send(proto, "UIDL")
+    resp = _replies(written).decode()
+    assert resp.startswith("+OK")
+    entries = [l for l in resp.split("\r\n") if l and l[0].isdigit()]
+    assert len(entries) == 10
+
+
+def test_pop3_uidl_format_msg_n(pop3_mod):
+    proto, _, written = _make_protocol(pop3_mod)
+    _login(proto, written)
+    _send(proto, "UIDL")
+    resp = _replies(written).decode()
+    assert "1 msg-1" in resp
+    assert "5 msg-5" in resp
+
+
+def test_pop3_dele_removes_message(pop3_mod):
+    proto, _, written = _make_protocol(pop3_mod)
+    _login(proto, written)
+    _send(proto, "DELE 3")
+    resp = _replies(written)
+    assert b"+OK" in resp
+    assert 2 in proto._deleted  # 0-based
+
+
+def test_pop3_rset_clears_deletions(pop3_mod):
+    proto, _, written = _make_protocol(pop3_mod)
+    _login(proto, written)
+    _send(proto, "DELE 1")
+    _send(proto, "DELE 2")
+    written.clear()
+    _send(proto, "RSET")
+    resp = _replies(written)
+    assert b"+OK" in resp
+    assert len(proto._deleted) == 0
+
+
+def test_pop3_dele_then_stat_decrements_count(pop3_mod):
+    proto, _, written = _make_protocol(pop3_mod)
+    _login(proto, written)
+    _send(proto, "DELE 1")
+    written.clear()
+    _send(proto, "STAT")
+    resp = _replies(written).decode()
+    assert resp.startswith("+OK 9 ")
+
+
+def test_pop3_quit_closes_connection(pop3_mod):
     proto, transport, written = _make_protocol(pop3_mod)
-    _send(proto, 'INVALID')
+    _login(proto, written)
-    assert b"-ERR" in b"".join(written)
+    _send(proto, "QUIT")
+    transport.close.assert_called_once()