burrow/evolution/proposals/BEP-0004-hosted-mail-and-saas-identity.md

BEP-0004 - Hosted Mail Backups and SaaS Identity

Status: Draft
Proposal: BEP-0004
Authors: gpt-5.4
Coordinator: gpt-5.4
Reviewers: Pending
Constitution Sections: II, III, V
Implementation PRs: Pending
Decision Date: Pending

Summary

Burrow should start with hosted mail on Forward Email instead of self-hosting SMTP and IMAP on the first forge machine. Backup retention should still be controlled by Burrow through custom S3-compatible storage backed by Burrow-owned object storage. In parallel, Burrow should treat SaaS identity as a separate track and converge on Authentik as the long-term IdP, with Linear SAML SSO as a planned downstream integration rather than an immediate bootstrap dependency.

Motivation

• The first forge host already carries source control, CI, and deployment bootstrap risk. Adding a self-hosted mail stack increases operational scope before the forge is stable.
• Forward Email already exposes SMTP and IMAP while allowing per-domain custom S3 backup storage, which preserves Burrow's data ownership over mailbox backups.
• The repository needs a durable decision record that separates hosted mail operations from future SaaS SSO work.

Detailed Design

• Use Forward Email as the operational mail provider for burrow.net and burrow.rs.
• Configure custom S3-compatible storage per domain using Burrow-controlled object storage credentials.
• Keep one backup bucket per domain and enforce lifecycle expiration at the bucket layer.
• Add repository-owned tooling and documentation for applying and testing the Forward Email custom S3 configuration.
• Treat Authentik as the future identity authority for SaaS applications, but keep Linear SAML as a later rollout once the workspace and vendor prerequisites are available. Linear's current docs place SAML and SCIM behind higher-tier workspace security settings, so Burrow should treat plan availability as an explicit precondition.

Security and Operational Considerations

• Forward Email API tokens and S3 credentials must stay in secret files and must not be passed directly on the shell command line.
• Buckets must remain private. Public bucket detection by the vendor should be treated as a hard failure, not a warning.
• Backup growth is unbounded without lifecycle rules. Retention policy is part of the rollout, not optional cleanup.
• Hosted mail reduces MTA attack surface on the forge host, but it adds third-party dependency risk; keeping backups in Burrow-owned storage limits that blast radius.

Contributor Playbook

• Put the Forward Email API token in intake/forwardemail_api_token.txt.
• Use Tools/forwardemail-custom-s3.sh to configure burrow.net and burrow.rs.
• Run the helper again with --test-only after any credential rotation.
• Record the chosen endpoint, region, bucket names, and lifecycle policy alongside rollout evidence.
• Do not claim Linear SAML is live until the Authentik app, Linear workspace settings, workspace plan prerequisites, and end-to-end login flow are verified.

Alternatives Considered

• Self-host Stalwart on the forge host immediately. Rejected for the first rollout because it expands host scope before source control and CI are stable.
• Rely on Forward Email default backup storage only. Rejected because it gives Burrow less control over retention and data location.
• Delay all SaaS identity planning until after forge cutover. Rejected because Linear and other SaaS integrations will otherwise accrete without an agreed authority.

Impact on Other Work

• Narrows the first forge host scope.
• Creates a clean mail path for contact@burrow.net without requiring self-hosted SMTP and IMAP.
• Leaves Authentik and Linear SAML as explicit follow-up work instead of hidden assumptions.

Decision

Pending.

References

• docs/FORWARDEMAIL.md
• Tools/forwardemail-custom-s3.sh
• Forward Email FAQ: custom S3-compatible storage for backups
• Linear docs: SAML SSO