Janady13/missionmatch / internal/modules/auth/invite_delivery.go

1package auth 2 3// INVITE DELIVERY THROUGH THE ORGANIZATION'S OWN MAIL SERVER. 4// 5// Until now this platform created an invite and handed the one time link back to whoever pressed the button, 6// who then delivered it by hand. That was the recorded Phase 2 decision and it was the right one at the time: 7// there was no mail transport, and inventing one that sent from a missionMATCH address would have meant every 8// customer's staff receiving activation links from a domain they had never heard of, which is exactly what 9// people are trained to treat as phishing. 10// 11// So delivery uses THE CUSTOMER'S OWN mail server and THEIR OWN sending address. An invitation from 12// talent@theiragency.com arrives looking like what it is, passes their own SPF and DKIM because it genuinely 13// came from them, and lands in an inbox rather than a spam folder. 14// 15// TWO PROPERTIES ARE LOAD BEARING. 16// 17// IT DEGRADES TO THE OLD BEHAVIOUR, ALWAYS. An organization that has not configured mail, or whose mail 18// server refuses the message, gets the link in the response exactly as before. A failed send never fails the 19// invitation: the account is created and the token is valid either way, because losing a colleague's account 20// creation over a mail server outage would be a worse product than the manual one this replaces. 21// 22// WHEN DELIVERY SUCCEEDS THE TOKEN IS WITHHELD. This is the security half. The token is a live credential 23// that redeems into an account; once it has reached the intended person by mail, there is no reason for a 24// copy of it to sit in an administrator's browser, in their network log, or in whatever they pasted it into. 25// Successful delivery therefore returns delivered true and NO token. 26 27import ( 28 "context" 29 "errors" 30 "fmt" 31 "net/url" 32 "strings" 33 "time" 34 35 "github.com/jackc/pgx/v5" 36 37 "github.com/missionworkforce/missionmatch/internal/platform/mailer" 38 "github.com/missionworkforce/missionmatch/internal/platform/orgsettings" 39) 40 41// deliverInvite attempts to mail an activation link. It reports whether the message was actually accepted by 42// the customer's mail server, and NEVER returns an error that should fail the invitation. 43// 44// It takes the token by value and holds it only for the length of the call. The token is written into the 45// message body and nowhere else: not the audit trail, not the settings row, not a log line. 46func (s *Service) deliverInvite(ctx context.Context, toEmail, toName, token string) (delivered bool, reason string) { 47 if s.deps.Settings == nil { 48 return false, "no settings store on this node" 49 } 50 if toEmail == "" || token == "" { 51 return false, "nothing to deliver" 52 } 53 54 var cfg mailer.Config 55 var orgName string 56 err := s.deps.DB.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 57 st, e := s.deps.Settings.LoadTx(ctx, tx) 58 if e != nil { 59 return e 60 } 61 // THREE CONDITIONS, ALL REQUIRED. Switched on, proven to work, and actually configured. Verification 62 // is checked rather than trusted because a settings row can be edited by hand and because the whole 63 // point of smtp_verified_at is that somebody proved this path once. 64 if !st.EmailDeliveryEnabled || st.SMTPVerifiedAt == nil { 65 return errDeliveryOff 66 } 67 if st.SMTPHost == "" || st.SMTPPort == 0 || st.EmailFromAddress == "" { 68 return errDeliveryOff 69 } 70 pw, e := s.deps.Settings.OpenSecret(ctx, tx, orgsettings.SecretSMTPPassword) 71 if e != nil && !errors.Is(e, orgsettings.ErrNoSecret) { 72 return e 73 } 74 cfg = mailer.Config{ 75 Host: st.SMTPHost, Port: st.SMTPPort, Username: st.SMTPUsername, Password: pw, 76 Security: st.SMTPSecurity, From: st.EmailFromAddress, FromName: st.EmailFromName, 77 ReplyTo: st.EmailReplyTo, 78 } 79 // Best effort: a missing organization name costs a slightly plainer subject line, nothing more. 80 _ = tx.QueryRow(ctx, `SELECT name FROM organizations LIMIT 1`).Scan(&orgName) 81 return nil 82 }) 83 if err != nil { 84 if errors.Is(err, errDeliveryOff) { 85 return false, "email delivery is not enabled and verified for this organization" 86 } 87 return false, "could not read the mail configuration" 88 } 89 90 sendCtx, cancel := context.WithTimeout(ctx, 30*time.Second) 91 defer cancel() 92 if err := mailer.Send(sendCtx, cfg, mailer.Message{ 93 To: toEmail, 94 Subject: inviteSubject(orgName), 95 Body: inviteBody(orgName, toName, s.deps.AppBaseURL, token, s.deps.InviteSeconds), 96 }); err != nil { 97 // Recorded on the settings row so an administrator sees that delivery is failing without having to 98 // read a server log. Scrubbed of the credentials by the store before it is written. 99 _ = s.deps.DB.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 100 return s.deps.Settings.MarkAttemptFailed(ctx, tx, err.Error(), cfg.Username, cfg.Password) 101 }) 102 return false, "the mail server refused the message, the link is returned instead" 103 } 104 return true, "" 105} 106 107var errDeliveryOff = errors.New("auth: organization mail delivery is off") 108 109func inviteSubject(orgName string) string { 110 if orgName != "" { 111 return "You have been invited to " + orgName + " on missionMATCH" 112 } 113 return "You have been invited to missionMATCH" 114} 115 116// inviteBody is deliberately plain and short. It says who invited them, what to do, and when it stops 117// working. It contains no images, no tracking, and no marketing, because this is an account credential 118// arriving at a cleared workforce professional and it should read like one. 119func inviteBody(orgName, toName, baseURL, token string, expirySeconds int) string { 120 greeting := "Hello," 121 if n := strings.TrimSpace(toName); n != "" { 122 greeting = "Hello " + n + "," 123 } 124 who := "your organization" 125 if orgName != "" { 126 who = orgName 127 } 128 hours := expirySeconds / 3600 129 if hours < 1 { 130 hours = 1 131 } 132 var b strings.Builder 133 b.WriteString(greeting + "\r\n\r\n") 134 b.WriteString(who + " has invited you to missionMATCH.\r\n\r\n") 135 b.WriteString("Open this link to choose a password and activate your account:\r\n\r\n") 136 b.WriteString(inviteLink(baseURL, token) + "\r\n\r\n") 137 b.WriteString(fmt.Sprintf("The link works once and expires in %d hours.\r\n\r\n", hours)) 138 b.WriteString("If you were not expecting this invitation, you can ignore this message and the link " + 139 "will expire on its own. Do not forward it to anyone: it grants access to your account.\r\n") 140 return b.String() 141} 142 143// inviteLink builds the activation URL. When no base URL is configured it returns the RAW TOKEN with a plain 144// instruction rather than a broken link to a guessed host, because a link to the wrong hostname is worse than 145// no link: it either fails silently or sends a live credential somewhere it does not belong. 146func inviteLink(baseURL, token string) string { 147 base := strings.TrimRight(strings.TrimSpace(baseURL), "/") 148 if base == "" { 149 return "Your activation code is " + token + "\r\n(Ask your administrator for the sign in address.)" 150 } 151 return base + "/activate?token=" + url.QueryEscape(token) 152} 153