Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions docs/adr/email-outbound-relay.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,37 @@ are unchanged.
and that replies thread against the sender's Sent copy despite SES's
Message-ID rewrite. If threading fails, report it before switching relay.

## The business site's sender

The business site sends its own automated mail, such as sign-in codes and
invitations, straight through SES rather than through company Email
(#5400). It needs no mailbox, so it does not wait on the Email server's
sign-in, recovery or public submission work, and it cannot reach any mailbox.

- **A second send-only credential.** A separate IAM user may only
`ses:SendRawEmail` on the same domain identity, with the sender equal to
`no-reply@devantler.tech`. Its access key, policy and attachment are
platform-owned like the relay's, and no policy includes Delete.
- **Custody.** A platform PushSecret copies the key ID and the derived SMTP
password to `apps/business-site/smtp` in OpenBao, as `username` and
`password`. The business site reads that one key through its dedicated role,
which also reads its public disclosure and nothing else.
- **Use.** The site's mail client connects to
`email-smtp.eu-central-1.amazonaws.com` on port 587 with STARTTLS and SMTP
authentication, sending from `no-reply@devantler.tech`. The tenant owns its
own egress to that endpoint.
- **Rotation.** Declare a new access key; the PushSecret then writes the new
credential. Remove the old key afterwards, with Delete added to its
policies first.
- **Revocation.** No policy includes Delete, so removing a manifest leaves the
AWS object in place and the credential still sends. To stop sending, first
add Delete to the attachment's management policies and let it reconcile,
then remove the attachment and check in AWS that the user has no policy
attached.

While the account is in the SES sandbox, this sender too reaches only verified
recipients.

## Alternatives

- **Direct delivery:** needs a dedicated address, reverse DNS and egress
Expand Down
17 changes: 15 additions & 2 deletions k8s/bases/infrastructure/vault-config/job.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -836,14 +836,19 @@ spec:
}
POLICY

# Public staging reads one owner-maintained entry. It has no
# value writer, metadata listing or shared infrastructure policy.
# The business site reads two exact entries: its owner-maintained
# public disclosure, and its send-only SES SMTP credential, which a
# platform PushSecret writes (platform#5400). It has no value
# writer, metadata listing or shared infrastructure policy.
bao policy write app-business-site-disclosure-readonly - <<'BUSINESS_SITE_POLICY'
{
"path": {
"secret/data/apps/business-site/public-disclosure": {
"capabilities": ["read"]
},
"secret/data/apps/business-site/smtp": {
"capabilities": ["read"]
},
"auth/token/lookup-self": {
"capabilities": ["read"]
},
Expand Down Expand Up @@ -1086,6 +1091,11 @@ spec:
path "secret/data/infrastructure/email/ses-smtp" {
capabilities = ["create", "update", "read"]
}
# The business site's SES SMTP credential, pushed the same way
# into its own prefix (platform#5400). Exact key only.
path "secret/data/apps/business-site/smtp" {
capabilities = ["create", "update", "read"]
}
path "secret/data/apps/actual-budget/*" {
capabilities = ["create", "update", "read"]
}
Expand Down Expand Up @@ -1143,6 +1153,9 @@ spec:
path "secret/metadata/infrastructure/email/ses-smtp" {
capabilities = ["create", "update", "read"]
}
path "secret/metadata/apps/business-site/smtp" {
capabilities = ["create", "update", "read"]
}
path "secret/metadata/apps/actual-budget/*" {
capabilities = ["create", "update", "read"]
}
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# The business site's SES SMTP credential. The provider publishes the key ID as
# `username` and the SES SMTP password derived for its own region
# (eu-central-1) as `attribute.ses_smtp_password_v4`. The connection Secret
# stays in this namespace; push-secret-business-site-smtp.yaml copies those two
# values to the business site's OpenBao prefix, and nobody reads them. The
# password is only available when the key is created, so the OpenBao copy is
# the durable one. Rotate by declaring a new key, then remove this one with
# Delete added to its policies.
apiVersion: iam.aws.m.upbound.io/v1beta1
kind: AccessKey
metadata:
name: business-site-smtp
namespace: aws
labels:
app.kubernetes.io/managed-by: ksail
spec:
managementPolicies:
- Observe
- Create
- Update
- LateInitialize
forProvider:
userRef:
name: business-site-smtp
writeConnectionSecretToRef:
name: business-site-smtp-credentials
providerConfigRef:
kind: ProviderConfig
name: default
5 changes: 5 additions & 0 deletions k8s/providers/hetzner/apps/aws/kustomization.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,11 @@ resources:
- user-policy-attachment-email-smtp.yaml
- access-key-email-smtp.yaml
- push-secret-email-smtp.yaml
- user-business-site-smtp.yaml
- policy-business-site-smtp-send.yaml
- user-policy-attachment-business-site-smtp.yaml
- access-key-business-site-smtp.yaml
- push-secret-business-site-smtp.yaml
- role-ses-account-setup.yaml
- dns-endpoint.yaml
- external-secret.yaml
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# The only permission of the business site's SMTP identity: send raw mail
# through the company mail domain's SES identity in eu-central-1, from its one
# sender address. It cannot use any other sender, read, configure or verify
# anything in SES.
apiVersion: iam.aws.m.upbound.io/v1beta1
kind: Policy
metadata:
name: business-site-smtp-send
namespace: aws
labels:
app.kubernetes.io/managed-by: ksail
spec:
managementPolicies:
- Observe
- Create
- Update
- LateInitialize
forProvider:
description: >-
Lets the business site's SMTP identity send mail through the company mail
domain's SES identity, from its one sender address only.
policy: |
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "SendBusinessSiteMail",
"Effect": "Allow",
"Action": "ses:SendRawEmail",
"Resource": "arn:aws:ses:eu-central-1:939001610192:identity/devantler.tech",
"Condition": {
"StringEquals": {
"ses:FromAddress": "no-reply@devantler.tech"
}
}
}
]
}
providerConfigRef:
kind: ProviderConfig
name: default
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Copies the business site's SES SMTP credential into OpenBao under the
# business site's own prefix, where its tenant reads it through its dedicated
# role. Platform-applied, so it may use the shared store, which holds an
# exact-key grant for this one record. Replace keeps OpenBao equal to the
# current key; a missing or incomplete connection Secret writes nothing.
apiVersion: external-secrets.io/v1alpha1
kind: PushSecret
metadata:
name: business-site-smtp-credentials
namespace: aws
labels:
app.kubernetes.io/managed-by: ksail
spec:
updatePolicy: Replace
deletionPolicy: None
refreshInterval: 1h
secretStoreRefs:
- name: openbao
kind: ClusterSecretStore
selector:
secret:
name: business-site-smtp-credentials
data:
- match:
secretKey: username
remoteRef:
remoteKey: apps/business-site/smtp
property: username
- match:
secretKey: attribute.ses_smtp_password_v4
remoteRef:
remoteKey: apps/business-site/smtp
property: password
23 changes: 23 additions & 0 deletions k8s/providers/hetzner/apps/aws/user-business-site-smtp.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# The business site's send-only SMTP identity for Amazon SES (platform#5400).
# It sends the site's automated mail, such as sign-in codes and invitations,
# apart from company Email's own relay identity. Platform-owned like that
# identity, so the public aws tenant cannot widen what it may do. Delete is
# omitted so a prune cannot remove it; revoke by replacing its access key.
apiVersion: iam.aws.m.upbound.io/v1beta1
kind: User
metadata:
name: business-site-smtp
namespace: aws
labels:
app.kubernetes.io/managed-by: ksail
spec:
managementPolicies:
- Observe
- Create
- Update
- LateInitialize
forProvider:
path: /business-site/
providerConfigRef:
kind: ProviderConfig
name: default
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# Attaches the send-only policy to the business site's SMTP identity.
apiVersion: iam.aws.m.upbound.io/v1beta1
kind: UserPolicyAttachment
metadata:
name: business-site-smtp-send
namespace: aws
labels:
app.kubernetes.io/managed-by: ksail
spec:
managementPolicies:
- Observe
- Create
- Update
- LateInitialize
forProvider:
userRef:
name: business-site-smtp
policyArnRef:
name: business-site-smtp-send
providerConfigRef:
kind: ProviderConfig
name: default
1 change: 1 addition & 0 deletions scripts/check-business-disclosure-reader/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ func expectedPayload(kind string) string {
case "policy":
return `{"path":{
"secret/data/apps/business-site/public-disclosure":{"capabilities":["read"]},
"secret/data/apps/business-site/smtp":{"capabilities":["read"]},
"auth/token/lookup-self":{"capabilities":["read"]},
"auth/token/revoke-self":{"capabilities":["update"]}}}`
default:
Expand Down
144 changes: 144 additions & 0 deletions scripts/tests/arc-staging/business_site_sender_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
package arcstaging_test

import (
"encoding/json"
"errors"
"reflect"
"regexp"
"slices"
"strings"
"testing"
)

// businessSiteSeedGrants refuses any seed grant that can reach the business
// site's prefix other than the two exact SMTP credential grants, including a
// glob (`*`) or segment wildcard (`+`) that covers it.
func businessSiteSeedGrants(policy string) error {
stanzas := regexp.MustCompile(`(?s)path\s+"([^"]*)"\s*\{\s*capabilities\s*=\s*(\[[^\]]+\])\s*\}`).FindAllStringSubmatch(policy, -1)
if len(stanzas) == 0 || len(stanzas) != strings.Count(policy, "path \"") {
return errors.New("every seed policy path must parse as one capabilities stanza")
}
probes := []string{
"secret/data/apps/business-site/smtp",
"secret/data/apps/business-site/other",
"secret/metadata/apps/business-site/smtp",
"secret/metadata/apps/business-site/other",
}
want := map[string]bool{
"secret/data/apps/business-site/smtp": true,
"secret/metadata/apps/business-site/smtp": true,
}
for _, stanza := range stanzas {
pattern := regexp.QuoteMeta(stanza[1])
pattern = strings.ReplaceAll(pattern, `\+`, `[^/]+`)
if strings.HasSuffix(pattern, `\*`) {
pattern = strings.TrimSuffix(pattern, `\*`) + `.*`
}
matcher := regexp.MustCompile(`^` + pattern + `$`)
if !slices.ContainsFunc(probes, matcher.MatchString) {
continue
}
if !want[stanza[1]] {
return errors.New("the business site's seed authorization is duplicated or broader than its SMTP credential: " + stanza[1])
}
delete(want, stanza[1])
var capabilities []string
if err := json.Unmarshal([]byte(stanza[2]), &capabilities); err != nil {
return err
}
slices.Sort(capabilities)
if !reflect.DeepEqual(capabilities, []string{"create", "read", "update"}) {
return errors.New("the SMTP credential grant must write and read without list or delete authority")
}
}
if len(want) != 0 {
return errors.New("need exactly one data and one metadata grant for the business site's SMTP credential")
}
return nil
}

// The business site's send-only SES credential (platform#5400) reaches
// OpenBao only through its platform PushSecret, at one exact key under the
// business site's own prefix, and may send only from its one sender address.
func TestBusinessSiteSenderCredentialIsExactAndSendOnly(t *testing.T) {
_, seed := captureBaoWrite(t, "bao", "policy", "write", "vault-seed-write")
if err := businessSiteSeedGrants(seed); err != nil {
t.Fatal(err)
}
const exact = `path "secret/data/apps/business-site/smtp" {
capabilities = ["create", "update", "read"]
}`
for name, widened := range map[string]string{
"apps glob": `path "secret/data/apps/*" { capabilities = ["read"] }`,
"secret glob": `path "secret/*" { capabilities = ["read"] }`,
"prefix glob": `path "secret/data/apps/business-site*" { capabilities = ["read"] }`,
"segment wildcard": `path "secret/metadata/apps/+/smtp" { capabilities = ["read"] }`,
"other key": `path "secret/data/apps/business-site/other" { capabilities = ["read"] }`,
"duplicate": exact,
} {
if businessSiteSeedGrants(seed+"\n"+widened+"\n") == nil {
t.Fatalf("a %s grant over the business site's prefix was accepted", name)
}
}
withDelete := regexp.MustCompile(`(path\s+"secret/data/apps/business-site/smtp"\s*\{\s*capabilities\s*=\s*\[)`).ReplaceAllString(seed, `${1}"delete", `)
if withDelete == seed {
t.Fatal("the delete control did not change the seed policy")
}
if businessSiteSeedGrants(withDelete) == nil {
t.Fatal("a delete capability on the business site's SMTP credential was accepted")
}

push := readYAML(t, "k8s/providers/hetzner/apps/aws/push-secret-business-site-smtp.yaml")
equal(t, mailField[string](t, push, "metadata", "namespace"), "aws")
equal(t, mailField[string](t, push, "spec", "selector", "secret", "name"), "business-site-smtp-credentials")
equal(t, mailField[string](t, push, "spec", "updatePolicy"), "Replace")
equal(t, mailField[string](t, push, "spec", "deletionPolicy"), "None")
data := mailField[[]any](t, push, "spec", "data")
equal(t, len(data), 2)
pushed := map[string]string{}
for _, entry := range data {
equal(t, mailField[string](t, entry, "match", "remoteRef", "remoteKey"), "apps/business-site/smtp")
pushed[mailField[string](t, entry, "match", "secretKey")] = mailField[string](t, entry, "match", "remoteRef", "property")
}
equal(t, pushed["username"], "username")
equal(t, pushed["attribute.ses_smtp_password_v4"], "password")

key := readYAML(t, "k8s/providers/hetzner/apps/aws/access-key-business-site-smtp.yaml")
equal(t, mailField[string](t, key, "spec", "forProvider", "userRef", "name"), "business-site-smtp")
equal(t, mailField[string](t, key, "spec", "writeConnectionSecretToRef", "name"), "business-site-smtp-credentials")
attachment := readYAML(t, "k8s/providers/hetzner/apps/aws/user-policy-attachment-business-site-smtp.yaml")
equal(t, mailField[string](t, attachment, "spec", "forProvider", "userRef", "name"), "business-site-smtp")
equal(t, mailField[string](t, attachment, "spec", "forProvider", "policyArnRef", "name"), "business-site-smtp-send")
for _, path := range []string{
"user-business-site-smtp.yaml",
"policy-business-site-smtp-send.yaml",
"user-policy-attachment-business-site-smtp.yaml",
"access-key-business-site-smtp.yaml",
} {
policies := mailField[[]any](t, readYAML(t, "k8s/providers/hetzner/apps/aws/"+path), "spec", "managementPolicies")
if slices.Contains(policies, any("Delete")) || slices.Contains(policies, any("*")) {
t.Fatalf("%s must not let a prune delete the sender identity", path)
}
}

var document struct {
Version string
Statement []map[string]any
}
source := mailField[string](t, readYAML(t, "k8s/providers/hetzner/apps/aws/policy-business-site-smtp-send.yaml"), "spec", "forProvider", "policy")
if err := json.Unmarshal([]byte(source), &document); err != nil {
t.Fatal(err)
}
wantStatement := map[string]any{
"Sid": "SendBusinessSiteMail",
"Effect": "Allow",
"Action": "ses:SendRawEmail",
"Resource": "arn:aws:ses:eu-central-1:939001610192:identity/devantler.tech",
"Condition": map[string]any{
"StringEquals": map[string]any{"ses:FromAddress": "no-reply@devantler.tech"},
},
}
if document.Version != "2012-10-17" || len(document.Statement) != 1 || !reflect.DeepEqual(document.Statement[0], wantStatement) {
t.Fatal("the business site's SMTP identity may only send raw mail from its one sender address through the company mail domain")
}
}
Loading
Loading