hanna/fabrica

feat(mail): SMTP delivery, invite tokens, and user-add activation

7b0dd81 · hanna committed on 2026-07-25

Add the mail crate: three backends (smtp over native-TLS, stdout, none),
plain-text-primary/HTML-alternative activate and reset templates rendered
from the instance name/URL, and a best-effort Mailer::send_invite.

Invites are persisted hashed: the store gains create_invite /
invite_by_token_hash / single-use mark_invite_used over the invites
table, and model gains Invite. `fabrica user add` without --pass now
mints an activation invite (32-byte token, only its SHA-256 stored),
tries to email it, and always prints the {instance.url}/invite/{token}
link so an operator can deliver it when SMTP is off. Config gains
auth.invite_ttl_hours (default 72).

native-tls replaces the spec's rustls transport to keep ring out of the
license graph (see docs/decisions.md).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Signed by hannaSSH key fingerprint: SHA256:4g9cWhkAAw8gwqhJUcVbSnGEvdGwklW+1Aa/fMUu59k

Cargo.lock +223 −0

Cargo.toml +10 −0

crates/cli/Cargo.toml +1 −0

crates/cli/src/user_cmd.rs +56 −9

crates/config/src/types.rs +3 −0

crates/mail/Cargo.toml +6 −0

crates/mail/src/lib.rs +223 −1

crates/mail/src/templates.rs +117 −0

crates/model/src/entity.rs +20 −0

crates/model/src/lib.rs +1 −1

crates/store/src/invites.rs +113 −0

crates/store/src/lib.rs +2 −0

crates/store/src/tests.rs +53 −0

docs/decisions.md +17 −0

fabrica.example.toml +1 −0

@@ @@ -101,6 +101,16 @@ insta = "1" @@
 # is LGPL, which our license gate forbids (see docs/decisions.md).
 ssh-key = { version = "0.6.7", features = ["ed25519", "rsa", "p256", "std"] }
 pgp = "0.20"
 # SMTP mail. native-tls (system OpenSSL, already a build input) rather than the
 # spec's rustls transport, which pulls `ring` and would fail the license gate —
 # see docs/decisions.md.
 lettre = { version = "0.11", default-features = false, features = [
     "builder",
     "smtp-transport",
     "tokio1",
     "tokio1-native-tls",
     "hostname",
 ] }
 [workspace.lints.rust]
 unsafe_code = "forbid"

@@ @@ -14,6 +14,7 @@ config = { workspace = true } @@
 store = { workspace = true }
 auth = { workspace = true }
 git = { workspace = true }
 mail = { workspace = true }
 model = { workspace = true }
 anyhow = { workspace = true }
 clap = { workspace = true }

@@ @@ -10,7 +10,7 @@ use std::process::ExitCode; @@
 use clap::Subcommand;
 use config::Config;
 use model::User;
 use store::{NewUser, Store};
 use store::{NewInvite, NewUser, Store};
 use crate::context::{block_on, open_store};
 use crate::prompt::{confirm, resolve_password};
@@ @@ -160,18 +160,65 @@ async fn add( @@
         if user.is_admin { " (admin)" } else { "" }
     );
     if !has_password {
         // Email invitations are not implemented yet (phase 9), so there is no
         // out-of-band way to activate the account — point the operator at the
         // direct path. This is the SMTP-disabled fallback made explicit.
         eprintln!(
             "note: no password set; this account cannot log in yet. \
              Set one with: fabrica user passwd {}",
             user.username
         );
         // No password was set, so mint an activation invite, try to email it, and
         // always print the link so an operator can deliver it when SMTP is off.
         send_activation(&config, &store, &user).await?;
+    }
     Ok(ExitCode::SUCCESS)
+}
 /// Mint an activation invite for `user`, attempt to email it (best-effort), and
 /// print the activation URL to stdout regardless.
 async fn send_activation(config: &Config, store: &Store, user: &User) -> anyhow::Result<()> {
     // The emailed token is opaque 32-byte randomness; only its SHA-256 is stored.
     let token = auth::new_session_token();
     let ttl_ms = i64::from(config.auth.invite_ttl_hours).saturating_mul(3_600_000);
     store
         .create_invite(NewInvite {
             user_id: user.id.clone(),
             token_hash: token.id,
             purpose: mail::Purpose::Activate.as_str().to_string(),
             expires_at: now_ms().saturating_add(ttl_ms),
         })
         .await?;
     let link = format!(
         "{}/invite/{}",
         config.instance.url.trim_end_matches('/'),
         token.cookie
     );
     match mail::Mailer::build(&config.mail) {
         Ok(mailer) => match mailer
             .send_invite(
                 &config.instance.name,
                 &user.email,
                 user.display_name.as_deref(),
                 &link,
                 mail::Purpose::Activate,
+            )
             .await
+        {
             Ok(()) => println!("sent activation email to {}", user.email),
             Err(err) => eprintln!("warning: could not send activation email: {err}"),
         },
         Err(err) => eprintln!("warning: mail not configured: {err}"),
+    }
     println!(
         "activation link (valid {}h): {link}",
         config.auth.invite_ttl_hours
     );
     Ok(())
+}
 /// The current time in Unix milliseconds.
 fn now_ms() -> i64 {
     use std::time::{SystemTime, UNIX_EPOCH};
     SystemTime::now()
         .duration_since(UNIX_EPOCH)
         .map_or(0, |d| i64::try_from(d.as_millis()).unwrap_or(i64::MAX))
+}
 async fn passwd(
     config_path: Option<&Path>,
     name: &str,

@@ @@ -181,6 +181,8 @@ pub struct Auth { @@
     pub session_ttl_days: u32,
     /// API token lifetime, in days.
     pub token_ttl_days: u32,
     /// Activation/reset invite lifetime, in hours.
     pub invite_ttl_hours: u32,
     /// Name of the session cookie.
     pub cookie_name: String,
     /// Set the `Secure` attribute on the session cookie.
@@ @@ -200,6 +202,7 @@ impl Default for Auth { @@
             secret_file: None,
             session_ttl_days: 30,
             token_ttl_days: 90,
             invite_ttl_hours: 72,
             cookie_name: "fabrica_session".to_string(),
             cookie_secure: true,
             argon2_m_cost: 19456,

@@ @@ -10,6 +10,12 @@ repository.workspace = true @@
 publish.workspace = true
 [dependencies]
 config = { workspace = true }
 lettre = { workspace = true }
 thiserror = { workspace = true }
 [dev-dependencies]
 tokio = { workspace = true }
 [lints]
 workspace = true

@@ @@ -155,6 +155,17 @@ dependencies = [ @@
+]
 [[package]]
 name = "async-trait"
 version = "0.1.91"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ae36dc4177970ef04fde5178d3e2429882def40e57a451f919c098f72baa6cec"
 dependencies = [
  "proc-macro2",
  "quote",
  "syn 3.0.3",
+]
 [[package]]
 name = "atoi"
 version = "2.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
@@ @@ -467,6 +478,7 @@ dependencies = [ @@
  "clap",
  "config",
  "git",
  "mail",
  "model",
  "rpassword",
  "serde",
@@ @@ -546,6 +558,22 @@ dependencies = [ @@
+]
 [[package]]
 name = "core-foundation"
 version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b2a6cd9ae233e7f62ba4e9353e81a88df7fc8a5987b8d445b4d90c879bd156f6"
 dependencies = [
  "core-foundation-sys",
  "libc",
+]
 [[package]]
 name = "core-foundation-sys"
 version = "0.8.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
 [[package]]
 name = "cpufeatures"
 version = "0.2.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
@@ @@ -972,6 +1000,22 @@ dependencies = [ @@
+]
 [[package]]
 name = "email-encoding"
 version = "0.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9298e6504d9b9e780ed3f7dfd43a61be8cd0e09eb07f7706a945b0072b6670b6"
 dependencies = [
  "base64",
  "memchr",
+]
 [[package]]
 name = "email_address"
 version = "0.2.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e079f19b08ca6239f47f8ba8509c11cf3ea30095831f7fed61441475edd8c449"
 [[package]]
 name = "encode_unicode"
 version = "1.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"
 [[package]]
 name = "foreign-types"
 version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f6f339eb8adc052cd2ca78910fda869aefa38d22d5cb648e6485e4d3fc06f3b1"
 dependencies = [
  "foreign-types-shared",
+]
 [[package]]
 name = "foreign-types-shared"
 version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "00b0228411908ca8685dba7fc2cdd70ec9990a6e753e89b6ac91a84c40fbaf4b"
 [[package]]
 name = "form_urlencoded"
 version = "1.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
@@ @@ -1377,6 +1436,23 @@ dependencies = [ @@
+]
 [[package]]
 name = "hostname"
 version = "0.4.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "617aaa3557aef3810a6369d0a99fac8a080891b68bd9f9812a1eeda0c0730cbd"
 dependencies = [
  "cfg-if",
  "libc",
  "windows-link",
+]
 [[package]]
 name = "httpdate"
 version = "1.0.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
 [[package]]
 name = "hybrid-array"
 version = "0.4.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
@@ @@ -1622,6 +1698,33 @@ dependencies = [ @@
+]
 [[package]]
 name = "lettre"
 version = "0.11.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0da65617f6cb926332d039cb578aad56178da86e128db6a1b09f4c94fa5b3349"
 dependencies = [
  "async-trait",
  "base64",
  "email-encoding",
  "email_address",
  "fastrand",
  "futures-io",
  "futures-util",
  "hostname",
  "httpdate",
  "idna",
  "mime",
  "native-tls",
  "nom",
  "percent-encoding",
  "quoted_printable",
  "socket2",
  "tokio",
  "tokio-native-tls",
  "url",
+]
 [[package]]
 name = "libbz2-rs-sys"
 version = "0.2.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 [[package]]
 name = "mail"
 version = "0.1.0"
 dependencies = [
  "config",
  "lettre",
  "thiserror 2.0.19",
  "tokio",
+]
 [[package]]
 name = "md-5"
 checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
 [[package]]
 name = "mime"
 version = "0.3.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6877bb514081ee2a7ff5ef9de3281f14a4dd4bceac4c09388074a6b5df8a139a"
 [[package]]
 name = "miniz_oxide"
 version = "0.8.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
@@ @@ -1777,6 +1892,23 @@ dependencies = [ @@
+]
 [[package]]
 name = "native-tls"
 version = "0.2.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "465500e14ea162429d264d44189adc38b199b62b1c21eea9f69e4b73cb03bbf2"
 dependencies = [
  "libc",
  "log",
  "openssl",
  "openssl-probe",
  "openssl-sys",
  "schannel",
  "security-framework",
  "security-framework-sys",
  "tempfile",
+]
 [[package]]
 name = "nom"
 version = "8.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381"
 [[package]]
 name = "openssl"
 version = "0.10.81"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "77823a27f0babb03091cb9ed9ef80af3b39dbc82f97e8fa530374b7dafd87a45"
 dependencies = [
  "bitflags",
  "cfg-if",
  "foreign-types",
  "libc",
  "openssl-macros",
  "openssl-sys",
+]
 [[package]]
 name = "openssl-macros"
 version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a948666b637a0f465e8564c73e89d4dde00d72d4d473cc972f390fc3dcee7d9c"
 dependencies = [
  "proc-macro2",
  "quote",
  "syn 2.0.119",
+]
 [[package]]
 name = "openssl-probe"
 version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7c87def4c32ab89d880effc9e097653c8da5d6ef28e6b539d313baaacfbafcbe"
 [[package]]
 name = "openssl-sys"
 version = "0.9.117"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b47e7e6bb2c38cd930d25a23b40fa52e068c10e85f3e03a7f5ba5aaca5713695"
 dependencies = [
  "cc",
  "libc",
  "pkg-config",
  "vcpkg",
+]
 [[package]]
 name = "p256"
 version = "0.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
@@ @@ -2178,6 +2353,12 @@ dependencies = [ @@
+]
 [[package]]
 name = "quoted_printable"
 version = "0.5.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "478e0585659a122aa407eb7e3c0e1fa51b1d8a870038bd29f0cf4a8551eea972"
 [[package]]
 name = "r-efi"
 version = "5.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
 [[package]]
 name = "schannel"
 version = "0.1.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "91c1b7e4904c873ef0710c1f407dde2e6287de2bebc1bbbf7d430bb7cbffd939"
 dependencies = [
  "windows-sys 0.61.2",
+]
 [[package]]
 name = "scopeguard"
 version = "1.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
@@ @@ -2426,6 +2616,29 @@ dependencies = [ @@
+]
 [[package]]
 name = "security-framework"
 version = "3.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d"
 dependencies = [
  "bitflags",
  "core-foundation",
  "core-foundation-sys",
  "libc",
  "security-framework-sys",
+]
 [[package]]
 name = "security-framework-sys"
 version = "2.17.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6ce2691df843ecc5d231c0b14ece2acc3efb62c0a398c7e1d875f3983ce020e3"
 dependencies = [
  "core-foundation-sys",
  "libc",
+]
 [[package]]
 name = "semver"
 version = "1.0.28"
 source = "registry+https://github.com/rust-lang/crates.io-index"
@@ @@ -3069,6 +3282,16 @@ dependencies = [ @@
+]
 [[package]]
 name = "tokio-native-tls"
 version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bbae76ab933c85776efabc971569dd6119c580d8f5d448769dec1764bf796ef2"
 dependencies = [
  "native-tls",
  "tokio",
+]
 [[package]]
 name = "tokio-stream"
 version = "0.1.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"

@@ @@ -2,4 +2,226 @@ @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 //! Outbound mail: templates rendered to text and HTML, sent best-effort.
 //! Outbound mail: SMTP delivery plus the activation/reset templates.
 //!
 //! Three backends (`config::MailBackend`): `smtp` delivers over SMTP with
 //! native-TLS (`starttls`/`tls`/plaintext), `stdout` prints the rendered message
 //! (development), and `none` rejects any flow that needs mail. Sending is
 //! best-effort — the caller always has the activation URL to deliver by hand — so
 //! `send_invite` returns a `Result` the caller logs rather than fails on.
 mod templates;
 use std::time::Duration;
 use config::{Mail, MailBackend, MailEncryption};
 use lettre::message::{Mailbox, MultiPart};
 use lettre::transport::smtp::authentication::Credentials;
 use lettre::{AsyncSmtpTransport, AsyncTransport, Message, Tokio1Executor};
 pub use crate::templates::{Purpose, Rendered, render};
 /// An error from the mail layer.
 #[derive(Debug, thiserror::Error)]
 pub enum MailError {
     /// The `none` backend was asked to send.
     #[error("mail is disabled (mail.backend = \"none\")")]
     Disabled,
     /// An address failed to parse.
     #[error("invalid email address: {0}")]
     Address(String),
     /// Building the SMTP transport failed.
     #[error("smtp transport setup failed: {0}")]
     Transport(String),
     /// Building the message failed.
     #[error("message construction failed: {0}")]
     Message(String),
     /// Delivery failed.
     #[error("mail delivery failed: {0}")]
     Send(String),
+}
 /// A configured mailer. Cheap to build once and reuse.
 pub struct Mailer {
     from: Mailbox,
     backend: Delivery,
+}
 /// The delivery mechanism behind a [`Mailer`].
 enum Delivery {
     /// Deliver over SMTP.
     Smtp(Box<AsyncSmtpTransport<Tokio1Executor>>),
     /// Print the rendered message to stdout.
     Stdout,
     /// Reject sends.
     None,
+}
 impl Mailer {
     /// Build a mailer from configuration.
     ///
     /// # Errors
     ///
     /// Returns [`MailError::Address`] if `mail.from` is not a valid address, or
     /// [`MailError::Transport`] if the SMTP transport cannot be constructed.
     pub fn build(config: &Mail) -> Result<Self, MailError> {
         let from: Mailbox = config
             .from
             .parse()
             .map_err(|e| MailError::Address(format!("{}: {e}", config.from)))?;
         let backend = match config.backend {
             MailBackend::Stdout => Delivery::Stdout,
             MailBackend::None => Delivery::None,
             MailBackend::Smtp => Delivery::Smtp(Box::new(build_transport(config)?)),
         };
         Ok(Self { from, backend })
+    }
     /// Send an invite email to `to_email` (optionally named `to_name`) with the
     /// activation `link`.
     ///
     /// # Errors
     ///
     /// Returns [`MailError`] on address/message/transport failure, or
     /// [`MailError::Disabled`] under the `none` backend. Callers treat this as
     /// best-effort and still surface the link out of band.
     pub async fn send_invite(
         &self,
         instance_name: &str,
         to_email: &str,
         to_name: Option<&str>,
         link: &str,
         purpose: Purpose,
     ) -> Result<(), MailError> {
         let rendered = render(instance_name, link, purpose);
         let to = mailbox(to_email, to_name)?;
         match &self.backend {
             Delivery::None => Err(MailError::Disabled),
             Delivery::Stdout => {
                 println!("--- mail ({}) ---", purpose.as_str());
                 println!("From: {}", self.from);
                 println!("To: {to}");
                 println!("Subject: {}", rendered.subject);
                 println!();
                 println!("{}", rendered.plain);
                 println!("--- end mail ---");
                 Ok(())
+            }
             Delivery::Smtp(transport) => {
                 let email = Message::builder()
                     .from(self.from.clone())
                     .to(to)
                     .subject(rendered.subject)
                     .multipart(MultiPart::alternative_plain_html(
                         rendered.plain,
                         rendered.html,
                     ))
                     .map_err(|e| MailError::Message(e.to_string()))?;
                 transport
                     .send(email)
                     .await
                     .map_err(|e| MailError::Send(e.to_string()))?;
                 Ok(())
+            }
+        }
+    }
+}
 /// Build a `to` mailbox from an address and optional display name.
 fn mailbox(email: &str, name: Option<&str>) -> Result<Mailbox, MailError> {
     let address = email
         .parse()
         .map_err(|e| MailError::Address(format!("{email}: {e}")))?;
     Ok(Mailbox::new(name.map(str::to_string), address))
+}
 /// Construct the async SMTP transport for the `smtp` backend.
 fn build_transport(config: &Mail) -> Result<AsyncSmtpTransport<Tokio1Executor>, MailError> {
     let builder = match config.encryption {
         MailEncryption::Tls => AsyncSmtpTransport::<Tokio1Executor>::relay(&config.host)
             .map_err(|e| MailError::Transport(e.to_string()))?,
         MailEncryption::Starttls => {
             AsyncSmtpTransport::<Tokio1Executor>::starttls_relay(&config.host)
                 .map_err(|e| MailError::Transport(e.to_string()))?
+        }
         MailEncryption::None => {
             AsyncSmtpTransport::<Tokio1Executor>::builder_dangerous(&config.host)
+        }
     };
     let mut builder = builder
         .port(config.port)
         .timeout(Some(Duration::from_secs(config.timeout_secs)));
     if !config.username.is_empty() {
         let password = config
             .password
             .as_ref()
             .map(|s| s.expose().to_string())
             .unwrap_or_default();
         builder = builder.credentials(Credentials::new(config.username.clone(), password));
+    }
     Ok(builder.build())
+}
 #[cfg(test)]
 mod tests {
     #![allow(clippy::unwrap_used)]
     use config::Mail;
     use super::*;
     fn stdout_config() -> Mail {
         Mail {
             backend: MailBackend::Stdout,
             from: "Fabrica <fabrica@example.com>".to_string(),
             ..Mail::default()
+        }
+    }
     #[tokio::test]
     async fn stdout_backend_sends_without_error() {
         let mailer = Mailer::build(&stdout_config()).unwrap();
         mailer
             .send_invite(
                 "Forge",
                 "ada@example.com",
                 Some("Ada"),
                 "https://git.example.com/invite/tok",
                 Purpose::Activate,
+            )
             .await
             .unwrap();
+    }
     #[tokio::test]
     async fn none_backend_rejects() {
         let config = Mail {
             backend: MailBackend::None,
             ..stdout_config()
         };
         let mailer = Mailer::build(&config).unwrap();
         let err = mailer
             .send_invite(
                 "Forge",
                 "a@b.com",
                 None,
                 "https://x/invite/t",
                 Purpose::Activate,
+            )
             .await
             .unwrap_err();
         assert!(matches!(err, MailError::Disabled));
+    }
     #[test]
     fn invalid_from_is_rejected() {
         let config = Mail {
             from: "not an address".to_string(),
             ..stdout_config()
         };
         assert!(matches!(Mailer::build(&config), Err(MailError::Address(_))));
+    }
+}

@@ @@ -0,0 +1,117 @@ @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 //! Message templates. A plain-text primary and a minimal HTML alternative are
 //! rendered from the same data, with the instance name and URL interpolated.
 /// Why an invite was sent.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Purpose {
     /// A new-account activation link.
     Activate,
     /// A password-reset link.
     Reset,
+}
 impl Purpose {
     /// The `invites.purpose` token.
     #[must_use]
     pub fn as_str(self) -> &'static str {
         match self {
             Self::Activate => "activate",
             Self::Reset => "reset",
+        }
+    }
+}
 /// A rendered message: subject plus the two body alternatives.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Rendered {
     /// The `Subject:` header.
     pub subject: String,
     /// The plain-text body (primary).
     pub plain: String,
     /// The HTML body (alternative).
     pub html: String,
+}
 /// Render the invite message for `purpose`, interpolating the instance name/URL
 /// and the activation `link`.
 #[must_use]
 pub fn render(instance_name: &str, link: &str, purpose: Purpose) -> Rendered {
     let (subject, lead, action) = match purpose {
         Purpose::Activate => (
             format!("Activate your {instance_name} account"),
             format!("An account has been created for you on {instance_name}."),
             "set your password and activate your account",
         ),
         Purpose::Reset => (
             format!("Reset your {instance_name} password"),
             format!("A password reset was requested for your {instance_name} account."),
             "choose a new password",
         ),
     };
     let plain = format!(
         "{lead}\n\nOpen this link to {action}:\n\n    {link}\n\n\
          If you did not expect this email, you can safely ignore it.\n"
     );
     let html = format!(
         "<p>{}</p>\n<p>Open this link to {}:</p>\n<p><a href=\"{}\">{}</a></p>\n\
          <p>If you did not expect this email, you can safely ignore it.</p>\n",
         escape(&lead),
         escape(action),
         escape(link),
         escape(link),
     );
     Rendered {
         subject,
         plain,
         html,
+    }
+}
 /// Minimal HTML escaping for the interpolated values.
 fn escape(s: &str) -> String {
     s.replace('&', "&amp;")
         .replace('<', "&lt;")
         .replace('>', "&gt;")
         .replace('"', "&quot;")
+}
 #[cfg(test)]
 mod tests {
     use super::*;
     #[test]
     fn activate_body_contains_link_and_name() {
         let r = render(
             "Forge",
             "https://git.example.com/invite/abc123",
             Purpose::Activate,
         );
         assert!(r.subject.contains("Forge"));
         assert!(r.plain.contains("https://git.example.com/invite/abc123"));
         assert!(
             r.html
                 .contains("href=\"https://git.example.com/invite/abc123\"")
         );
         assert!(r.plain.contains("activate your account"));
+    }
     #[test]
     fn reset_uses_reset_wording() {
         let r = render("Forge", "https://x/invite/t", Purpose::Reset);
         assert!(r.subject.to_lowercase().contains("reset"));
         assert!(r.plain.contains("new password"));
+    }
     #[test]
     fn html_escapes_interpolated_values() {
         let r = render("A&B", "https://x/?a=1&b=2", Purpose::Activate);
         assert!(r.html.contains("&amp;"));
         assert!(!r.html.contains("a=1&b=2"), "raw ampersand must be escaped");
+    }
+}

@@ @@ -79,6 +79,26 @@ pub struct User { @@
     pub updated_at: Timestamp,
+}
 /// A pending activation or password-reset invite. The emailed token is never
 /// stored; `token_hash` is its SHA-256, matched on redemption.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Invite {
     /// ULID primary key.
     pub id: String,
     /// The user this invite activates.
     pub user_id: String,
     /// SHA-256 (hex) of the emailed token.
     pub token_hash: String,
     /// `"activate"` or `"reset"`.
     pub purpose: String,
     /// When the invite expires.
     pub expires_at: Timestamp,
     /// When it was redeemed, if it has been (single-use).
     pub used_at: Option<Timestamp>,
     /// Creation time.
     pub created_at: Timestamp,
+}
 /// A nested, user-owned group. Groups provide the repository hierarchy; `path` is
 /// the materialized `group/sub/leaf` under the owner.
 #[derive(Debug, Clone, PartialEq, Eq)]

@@ @@ -11,5 +11,5 @@ @@
 pub mod entity;
 pub mod name;
 pub use entity::{ApiToken, Group, Key, KeyKind, Repo, Timestamp, User};
 pub use entity::{ApiToken, Group, Invite, Key, KeyKind, Repo, Timestamp, User};
 pub use name::{MAX_NAME_LEN, NameError, RESERVED_NAMES, validate_name};

@@ @@ -0,0 +1,113 @@ @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 //! Activation and password-reset invites.
 //!
 //! The emailed token is never stored; only its SHA-256 (`token_hash`) is, and
 //! redemption looks the invite up by that hash. Invites are single-use
 //! (`used_at`) and time-limited (`expires_at`).
 use model::Invite;
 use sqlx::any::AnyRow;
 use sqlx::{AssertSqlSafe, Row};
 use crate::{Store, StoreError, new_id, now_ms};
 /// The columns of `invites` in a fixed order, shared by every `SELECT`.
 const INVITE_COLUMNS: &str = "id, user_id, token_hash, purpose, expires_at, used_at, created_at";
 /// Fields needed to mint an invite. The caller generates the token and passes its
 /// SHA-256 here; the store assigns the id and creation time.
 #[derive(Debug, Clone)]
 pub struct NewInvite {
     /// The user the invite activates.
     pub user_id: String,
     /// SHA-256 (hex) of the emailed token.
     pub token_hash: String,
     /// `"activate"` or `"reset"`.
     pub purpose: String,
     /// Absolute expiry, epoch ms.
     pub expires_at: i64,
+}
 impl Store {
     /// Create an invite row.
     ///
     /// # Errors
     ///
     /// Returns [`StoreError::Query`] on a database failure.
     pub async fn create_invite(&self, new: NewInvite) -> Result<Invite, StoreError> {
         let invite = Invite {
             id: new_id(),
             user_id: new.user_id,
             token_hash: new.token_hash,
             purpose: new.purpose,
             expires_at: new.expires_at,
             used_at: None,
             created_at: now_ms(),
         };
         let sql = "INSERT INTO invites (id, user_id, token_hash, purpose, expires_at, used_at, created_at) \
              VALUES ($1, $2, $3, $4, $5, $6, $7)";
         sqlx::query(sql)
             .bind(invite.id.clone())
             .bind(invite.user_id.clone())
             .bind(invite.token_hash.clone())
             .bind(invite.purpose.clone())
             .bind(invite.expires_at)
             .bind(invite.used_at)
             .bind(invite.created_at)
             .execute(&self.pool)
             .await?;
         Ok(invite)
+    }
     /// Look up an invite by its token hash, regardless of state. The caller checks
     /// `used_at`/`expires_at` so it can distinguish "already used" from "expired"
     /// from "unknown" for the redemption page.
     ///
     /// # Errors
     ///
     /// Returns [`StoreError::Query`] on a database failure.
     pub async fn invite_by_token_hash(
         &self,
         token_hash: &str,
     ) -> Result<Option<Invite>, StoreError> {
         let sql = format!("SELECT {INVITE_COLUMNS} FROM invites WHERE token_hash = $1");
         let row = sqlx::query(AssertSqlSafe(sql))
             .bind(token_hash)
             .fetch_optional(&self.pool)
             .await?;
         Ok(row.as_ref().map(map_invite).transpose()?)
+    }
     /// Mark an invite redeemed. Guards against a double-redeem with a
     /// `used_at IS NULL` predicate, so `true` means "this call redeemed it".
     ///
     /// # Errors
     ///
     /// Returns [`StoreError::Query`] on a database failure.
     pub async fn mark_invite_used(&self, invite_id: &str) -> Result<bool, StoreError> {
         let updated =
             sqlx::query("UPDATE invites SET used_at = $1 WHERE id = $2 AND used_at IS NULL")
                 .bind(now_ms())
                 .bind(invite_id)
                 .execute(&self.pool)
                 .await?
                 .rows_affected();
         Ok(updated > 0)
+    }
+}
 /// Map an `invites` row (selected via [`INVITE_COLUMNS`]) to an [`Invite`].
 fn map_invite(row: &AnyRow) -> Result<Invite, sqlx::Error> {
     Ok(Invite {
         id: row.try_get("id")?,
         user_id: row.try_get("user_id")?,
         token_hash: row.try_get("token_hash")?,
         purpose: row.try_get("purpose")?,
         expires_at: row.try_get("expires_at")?,
         used_at: row.try_get("used_at")?,
         created_at: row.try_get("created_at")?,
     })
+}

@@ @@ -26,6 +26,7 @@ @@
 //! set is embedded at build time and selected at runtime by [`Store::migrate`].
 mod groups;
 mod invites;
 mod keys;
 mod repos;
 mod tokens;
@@ @@ -39,6 +40,7 @@ use sqlx::Row; @@
 use sqlx::any::{AnyPoolOptions, AnyRow};
 use sqlx::migrate::Migrator;
 pub use crate::invites::NewInvite;
 pub use crate::keys::NewKey;
 pub use crate::repos::NewRepo;
 pub use crate::tokens::NewToken;

@@ @@ -732,6 +732,59 @@ async fn rename_and_delete_repo() { @@
+    }
+}
 #[tokio::test]
 async fn invites_round_trip_and_are_single_use() {
     use super::NewInvite;
     for fx in sqlite_fixtures().await {
         let user = fx
             .store
             .create_user(sample_user("i", "i@example.com"))
             .await
             .unwrap();
         let invite = fx
             .store
             .create_invite(NewInvite {
                 user_id: user.id.clone(),
                 token_hash: "hash-abc".to_string(),
                 purpose: "activate".to_string(),
                 expires_at: now_plus_a_day(),
             })
             .await
             .unwrap();
         assert!(invite.used_at.is_none());
         let found = fx
             .store
             .invite_by_token_hash("hash-abc")
             .await
             .unwrap()
             .unwrap();
         assert_eq!(found.user_id, user.id);
         assert_eq!(found.purpose, "activate");
         // Redemption is single-use: the first mark succeeds, the second does not.
         assert!(fx.store.mark_invite_used(&invite.id).await.unwrap());
         assert!(!fx.store.mark_invite_used(&invite.id).await.unwrap());
         let redeemed = fx
             .store
             .invite_by_token_hash("hash-abc")
             .await
             .unwrap()
             .unwrap();
         assert!(redeemed.used_at.is_some());
         assert!(
             fx.store
                 .invite_by_token_hash("nope")
                 .await
                 .unwrap()
                 .is_none()
         );
+    }
+}
 /// Postgres round-trips, mirroring the SQLite ones. Ignored unless the
 /// `postgres-tests` feature is on and `FABRICA_TEST_POSTGRES_URL` points at a
 /// reachable database; the test cleans up the rows it creates so it can rerun.

 happen there too. Centralizing it in one helper means `token add` today and `serve`
 later sign with the same key. `auth::new_secret` provides the 32-byte base64url
 value, keeping randomness in the auth crate.
 ## 2026-07-24 — Mail over native-TLS, not the spec's rustls transport
 **Decision:** `crates/mail` uses `lettre` with the `tokio1-native-tls` transport,
 not the `tokio1-rustls` transport the spec names.
 **Alternatives:** `tokio1-rustls-tls` (the spec's choice).
 **Rationale:** lettre's rustls transport pulls `rustls` → `ring`, whose license set
 is outside `deny.toml`'s allow-list — the same constraint that shaped the JWT and
 sqlx-TLS decisions. native-tls links the **system OpenSSL**, which is already a
 flake `buildInput` (and present in the Debian runtime image), so it adds no new C
 dependency and keeps `ring` out of the graph. Backends are `smtp` (native-TLS
 `starttls`/`tls`/plaintext), `stdout`, and `none`; tests exercise the `stdout` and
 `none` paths so `cargo test` needs no SMTP server. A **SHOULD** deviation logged
 here. The invite token reuses `auth::new_session_token`'s shape (32 bytes,
 base64url value emailed, SHA-256 stored).

@@ @@ -51,6 +51,7 @@ max_connections = 16 @@
 secret_file       = "/var/lib/fabrica/secret"  # generated on first run, mode 0600
 session_ttl_days  = 30
 token_ttl_days    = 90
 invite_ttl_hours  = 72      # activation/reset link lifetime
 cookie_name       = "fabrica_session"
 cookie_secure     = true    # set false only if instance.url is plain http (dev)
 argon2_m_cost     = 19456   # KiB