Merge branch 'feat/custom-email-templates' into main

Author: Cryden Agent

cmd/smoketest/custom-email-templates/main.go

@@ -106,6 +106,28 @@ type Config struct {
 	// separates the label from the secret. Ignored unless APIKeys is
 	// set.
 	APIKeyPrefix string
+	// Webhooks is optional — set it to have the engine hand every
+	// subscribed event to the host app as it is recorded. Ships no
+	// implementation (see notify.WebhookSender's own doc comment): the
+	// engine makes no outbound HTTP call, so the endpoint, the signing
+	// and the retries are the host's. Left nil, nothing about the engine
+	// changes and no event is dispatched anywhere.
+	//
+	// Delivery is synchronous, on the request path, and a send error is
+	// logged rather than returned — a webhook never fails the login it
+	// was reporting.
+	Webhooks notify.WebhookSender
+	// WebhookEvents selects which events reach Webhooks. Left empty it is
+	// DefaultWebhookEvents(), which is the actionable, low-volume subset
+	// and deliberately excludes login_success, login_failed and
+	// token_rotated; set it to take exact control. Ignored unless
+	// Webhooks is set, and setting it without Webhooks is an error rather
+	// than a subscription to nowhere.
+	//
+	// An event type the engine never records is never delivered and is
+	// not an error — there is no canonical list to validate against, and
+	// inventing one would be a second place to keep the constants.
+	WebhookEvents []store.AuditEventType
 	// PasswordPolicy is checked on every SignUp/ChangePassword. Unlike
 	// TOTP/WebAuthn, this has no "unconfigured means off" state —
 	// leaving it as the entire zero value (security.PasswordPolicy{})
@@ -266,6 +288,14 @@ func (c *Config) validate() error {
 	if c.APIKeyPrefix != "" && strings.ContainsAny(c.APIKeyPrefix, " \t\r\n_") {
 		return ErrInvalidAPIKeyPrefix
 	}
+	if len(c.WebhookEvents) > 0 && c.Webhooks == nil {
+		return ErrMissingWebhookSender
+	}
+	for _, t := range c.WebhookEvents {
+		if t == "" {
+			return ErrInvalidWebhookEvent
+		}
+	}
 	return nil
 }
 
@@ -318,6 +348,9 @@ func (c *Config) applyDefaults() {
 	if c.APIKeyPrefix == "" {
 		c.APIKeyPrefix = "ck"
 	}
+	if c.Webhooks != nil && len(c.WebhookEvents) == 0 {
+		c.WebhookEvents = DefaultWebhookEvents()
+	}
 	if c.Logger == nil {
 		c.Logger = logger.NewConsoleJSONLogger()
 	}

cmd/smoketest/webhooks/main.go

@@ -0,0 +1,130 @@
+package cryden
+
+import (
+	"context"
+	"net/url"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/crydensync/cryden/v2/notify"
+	"github.com/crydensync/cryden/v2/store/memory"
+)
+
+// These tests pin a verdict rather than a feature: email templates are
+// already entirely the host app's, because the engine composes nothing
+// and offers nowhere to configure a template. That stays true only if
+// nobody later adds a subject, a body, a from-address or a template
+// field to Config — which is what the reflection below is for. It fails
+// on the commit that adds one, in `go test ./...`, instead of quietly
+// making the manual guide wrong.
+
+// The two send methods are the engine's entire outward email surface.
+// Both take a recipient and a raw token; neither has anywhere to put a
+// subject, a body, a URL or a locale.
+func TestEmailInterfaces_TakeOnlyARecipientAndAToken(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		typ  reflect.Type
+	}{
+		{"notify.EmailSender", reflect.TypeOf((*notify.EmailSender)(nil)).Elem()},
+		{"notify.MagicLinkSender", reflect.TypeOf((*notify.MagicLinkSender)(nil)).Elem()},
+	} {
+		if got := tc.typ.NumMethod(); got != 1 {
+			t.Errorf("%s has %d methods, want 1", tc.name, got)
+			continue
+		}
+		const want = "func(context.Context, string, string) error"
+		if got := tc.typ.Method(0).Type.String(); got != want {
+			t.Errorf("%s.%s is %s, want %s", tc.name, tc.typ.Method(0).Name, got, want)
+		}
+	}
+}
+
+// Config's only email-shaped fields are the two senders, and both are
+// interfaces the host implements. A new field named anything like
+// EmailSubject, EmailTemplate, FromAddress or SMTPHost fails this.
+func TestConfig_HasNoEmailTemplateKnobs(t *testing.T) {
+	var found []string
+	cfgType := reflect.TypeOf(Config{})
+	for i := 0; i < cfgType.NumField(); i++ {
+		f := cfgType.Field(i)
+		lower := strings.ToLower(f.Name)
+		for _, needle := range []string{"email", "mail", "sender", "template", "subject", "body", "smtp", "html", "from"} {
+			if strings.Contains(lower, needle) {
+				found = append(found, f.Name+" "+f.Type.Kind().String())
+				break
+			}
+		}
+	}
+	want := []string{"EmailSender interface", "MagicLinkSender interface"}
+	if !reflect.DeepEqual(found, want) {
+		t.Errorf("Config's email-shaped fields are %v, want exactly %v", found, want)
+	}
+}
+
+// composingSender is a host app's mailer: it receives two strings and
+// writes the whole email itself, including the URL and the domain.
+type composingSender struct {
+	subject, body, to string
+	calls             int
+}
+
+func (s *composingSender) SendVerification(_ context.Context, to, rawToken string) error {
+	s.calls++
+	s.to = to
+	s.subject = "Confirm your new address"
+	s.body = `<a href="https://host.example/confirm?token=` + url.QueryEscape(rawToken) + `">Confirm</a>`
+	return nil
+}
+
+var _ notify.EmailSender = (*composingSender)(nil)
+
+// The round trip that makes the verdict real: a link the host composed,
+// on the host's own domain, in the host's own markup, is accepted by
+// the engine — so owning the template costs the host nothing.
+func TestRequestEmailChange_AcceptsALinkTheHostComposed(t *testing.T) {
+	sender := &composingSender{}
+	cfg := validConfig()
+	cfg.Verifications = memory.NewVerificationStore()
+	cfg.EmailSender = sender
+	e, err := New(cfg)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	ctx := context.Background()
+
+	user, err := SignUp(ctx, e, "raymondproguy@dev.com", "Tr0ubl3-Fr33!2026", "1.2.3.4")
+	if err != nil {
+		t.Fatalf("SignUp: %v", err)
+	}
+	if err := RequestEmailChange(ctx, e, user.ID, "ray@acme.example"); err != nil {
+		t.Fatalf("RequestEmailChange: %v", err)
+	}
+	if sender.calls != 1 || sender.to != "ray@acme.example" {
+		t.Fatalf("sender got %d call(s) for %q, want 1 for the new address", sender.calls, sender.to)
+	}
+
+	// Pull the token back out of the host's own HTML, exactly as the
+	// user's browser would.
+	href := sender.body[strings.Index(sender.body, `"`)+1:]
+	link, err := url.Parse(href[:strings.Index(href, `"`)])
+	if err != nil {
+		t.Fatalf("the host's own link did not parse: %v", err)
+	}
+	raw := link.Query().Get("token")
+	if raw == "" {
+		t.Fatal("no token in the host's link")
+	}
+
+	if err := ConfirmEmailChange(ctx, e, raw); err != nil {
+		t.Fatalf("ConfirmEmailChange with the host-composed link: %v", err)
+	}
+	moved, err := GetUser(ctx, e, "ray@acme.example")
+	if err != nil {
+		t.Fatalf("the account did not move: %v", err)
+	}
+	if moved.ID != user.ID {
+		t.Errorf("moved account is %q, want %q", moved.ID, user.ID)
+	}
+}

config.go

@@ -214,9 +214,9 @@ re-derive it**:
   `CountTargetsForIP`, added by item 9 above against the same table.
 
 
-## Tier 3 — Infrastructure & Extensibility: IN PROGRESS (5 of 7)
+## Tier 3 — Infrastructure & Extensibility: DONE (7 of 7)
 
-Two items left. See `NEXT.md`.
+Tier 4 is next. See `NEXT.md`.
 
 ### Item 12 — Argon2id hasher: DONE, branch `feat/argon2id-hasher`
 
@@ -525,6 +525,104 @@ successes plus five unknown keys recording nothing). Manual guide:
 `docs/testing/api-keys.md`. `gofmt -l`, `go build ./...`, `go vet ./...`
 and `go test ./...` all clean here.
 
+### Item 17 — webhooks: DONE, branch `feat/webhooks`
+
+The engine tells the host app what happened instead of waiting to be
+asked. `Config.Webhooks` takes a `notify.WebhookSender` —
+`SendWebhook(ctx, notify.WebhookEvent) error`, one method, **zero
+shipped implementations**, the same shape as `EmailSender` and
+`IPGeolocator`. `Config.WebhookEvents` selects which events reach it and
+defaults to `cryden.DefaultWebhookEvents()`.
+
+Wired as a **decorator over `store.AuditStore`** (`webhookRecorder` in
+`webhooks.go`), not as a parameter on the 33 `audit.Record` call sites
+and not as a second event bus. `New` wraps `Config.Audit` when
+`Webhooks` is set; `Record` writes the row and then dispatches, so every
+existing call site notifies without a line changing and nothing in
+`auth/` knows the type exists. Reads pass straight through to the
+wrapped store.
+
+`DefaultWebhookEvents()` is sixteen events, the ones bounded by human
+action, and deliberately excludes `login_success`, `token_rotated` and
+`login_failed` — a thousand logged-in users at the default 15-minute
+`AccessTokenTTL` is 4,000 `token_rotated` deliveries an hour, and
+`login_failed` volume is chosen by whoever is attacking you. It returns
+a fresh slice, so `append(cryden.DefaultWebhookEvents(), ...)` is the
+documented way to add one back. There is deliberately **no "all"**
+switch: it would silently start delivering event types added after the
+host wrote its sender.
+
+Delivery is synchronous, on the request path, immediately after the
+audit write — so the doc comment on the interface says to enqueue rather
+than make the HTTP call there. A send error is logged at Error level and
+never fails the operation; a failed audit write still delivers; a
+**panic is not recovered** and takes the request, following
+`logger/multi.go`'s own stated rule that recovery exists only where a
+second sink can preserve the record. `Metadata` is copied before
+delivery so a sender cannot rewrite audit history, and `WebhookEvent.ID`
+is a delivery/idempotency key, explicitly not the audit row's ID — no
+backend reports that back.
+
+Two new sentinels: `ErrMissingWebhookSender` (events set, no sender) and
+`ErrInvalidWebhookEvent` (an empty type). A non-empty but misspelled
+event type builds and is never delivered; there is no canonical list to
+validate against and inventing one would duplicate the constants.
+
+No store change, **no migration**, no new dependency, no external
+service. Tests: 17 in `webhooks_test.go`. Smoke test:
+`cmd/smoketest/webhooks` (75 checks over ten sections, including five
+logins and five refreshes delivering nothing, a sender that errors, and
+a sender that panics). Manual guide: `docs/testing/webhooks.md`.
+`gofmt -l`, `go build ./...`, `go vet ./...` and `go test ./...` all
+clean here.
+
+### Item 18 — custom email templates: DONE (no engine change), branch `feat/custom-email-templates`
+
+**Nothing was built, and that is the finding.** The queue entry said to
+check `EmailSender`/`MagicLinkSender` first because there was "a real
+chance this needs no engine change at all." There is nothing to build.
+Checked and confirmed:
+
+- Two interfaces, two methods, **two call sites in the whole tree**:
+  `SendVerification` at `auth/email.go:70` (email change) and
+  `SendMagicLink` at `auth/magiclink.go:88` (passwordless login). Each
+  interface has exactly one purpose, so the "which email am I sending?"
+  ambiguity `notify/magic_link_sender.go`'s doc comment worried about
+  does not exist in practice.
+- Both methods pass `(ctx, to, rawToken)`. The engine composes no
+  subject, no body, no HTML, no plain-text part, no from-address and no
+  URL — it does not know the host's domain or routing, as both doc
+  comments already say.
+- `Config` has exactly two email-shaped fields and both are those
+  interfaces. There is no template, subject or from-address knob to
+  override.
+- No third or fourth template is missing either: there is no signup
+  verification flow (`store.PurposeEmailVerify` has no producer outside
+  a store smoke test) and no password-reset flow at all
+  (`ChangePassword` requires the current password), so nothing else in
+  the engine wants to send mail.
+
+Built instead of a feature: `docs/testing/custom-email-templates.md`
+answering the question behind the item (how a host controls what those
+emails say, in full), `cmd/smoketest/custom-email-templates` (54 checks
+over ten sections — a real host mailer with `html/template` bodies, two
+languages and two providers, whose own composed URL round-trips back
+into `ConfirmEmailChange` and `CompleteMagicLink`), and
+`custom_email_templates_test.go`, three tests that pin the verdict by
+reflection so a `Config.EmailSubject` added later fails `go test ./...`
+rather than quietly making the guide wrong.
+
+One real gap recorded rather than filled: both TTLs
+(`changeEmailTokenTTL` 1 hour, `magicLinkTTL` 15 minutes) are unexported
+and not passed to the sender, so a template that says "expires in 1
+hour" hardcodes a number that could drift. Exporting two constants would
+fix it; adding a parameter to either send method would break every
+existing host implementation at compile time, which is why
+`MagicLinkSender` was a new interface rather than a second method on
+`EmailSender`. Queue it as its own item if the project owner wants it —
+it is not done here, on the item's own "don't build something
+speculative to have built something" instruction.
+
 ## Tier 4 — AI-assisted admin features: NOT STARTED
 
 Four items, all read-only/surface-only by explicit, non-negotiable
@@ -605,6 +703,23 @@ project brief.
   **two migrations** that have to run before the feature works:
   `store/postgres/migrations/0007_api_keys.up.sql` and
   `store/sqlite/migrations/0002_api_keys.up.sql`. Unmerged and unpushed.
+- `feat/webhooks` — item 17, complete, 7 commits, branched from
+  `feat/api-keys` at `f11e40e`, the tip of the chain, so this branch
+  carries items 8 through 17. Touches engine files only (`config.go`,
+  `errors.go`, `engine.go`, the new `webhooks.go`) plus the new
+  `notify/webhook_sender.go`, so the same by-hand adjacency as items
+  10-12, 14, 15 and 16 applies if it is lifted onto `main` alone. It
+  adds **no dependency**, **no migration** and no store change at all —
+  it delivers events the audit table already recorded. Unmerged and
+  unpushed.
+- `feat/custom-email-templates` — item 18, complete, 4 commits,
+  branched from `feat/webhooks` at `6f84095`, the tip of the chain, so
+  this branch carries items 8 through 18. **Contains no engine change at
+  all** — the `feat/` prefix is the naming convention, not a claim. Adds
+  one root test file, one smoke test and one guide, touching no existing
+  Go file, so unlike every branch before it this one lifts onto `main`
+  with nothing to reconcile. No dependency, no migration. Unmerged and
+  unpushed.
 - `fix/committed-smoketest-binary` — not a queue item. A pre-existing
   bug found while working on item 14: a 9.8 MB compiled `argon2id-hasher`
   binary was committed to the repo by item 12's session (`57a5dbd`) and

custom_email_templates_test.go

@@ -12,29 +12,7 @@ patterns and note the assumption in `PROGRESS.md` — don't block on it.
 
 ---
 
-## Tier 3 — Infrastructure & Extensibility
-
-### 1. Webhooks (item 17)
-
-Notify the host app on key events. Same question as everything else
-that reaches outward: interface-only, zero shipped implementations
-(`notify.WebhookSender` or similar), matching `EmailSender` — the
-engine surfaces the event, the host app's implementation does the
-actual HTTP call, retries, signing, etc. Decide which existing audit
-events should also trigger a webhook call (probably a configurable
-subset, not all of them) and wire it in wherever `audit.Record` is
-already called for those events — don't build a second parallel event
-bus.
-
-### 2. Custom email templates (item 18)
-
-Check `notify.EmailSender`/`notify.MagicLinkSender` as they exist
-today first — there's a real chance this needs **no engine change at
-all**, since the host app's own implementation already owns the
-actual email body/template (the engine only ever hands over a raw
-token, per `EmailSender`'s own doc comment). If that's true, say so
-plainly in `PROGRESS.md` and mark the item done-as-a-non-issue rather
-than building something speculative to have built something.
+Tier 3 is complete — all seven items done. See `CURRENT-STATE.md`.
 
 ---
 
@@ -44,19 +22,19 @@ than building something speculative to have built something.
 automatic action — no auto-lock, no auto-config-change, nothing. Every
 one of these produces information for a human to act on.
 
-### 3. Weekly digest (item 19)
+### 1. Weekly digest (item 19)
 Reads `AuditStore`, summarizes in plain English, returns text. Nothing
 else.
 
-### 4. Support-ticket assistant (item 20)
+### 2. Support-ticket assistant (item 20)
 Read-only diagnosis ("why can't user X log in") — queries
 `AuditStore`/`UserStore`/session state, produces an explanation, never
 touches anything.
 
-### 5. Config tuning advisor (item 21)
+### 3. Config tuning advisor (item 21)
 Produces a report of suggested config changes. Never applies them.
 
-### 6. Ask-AI widget (item 22)
+### 4. Ask-AI widget (item 22)
 The most complex of the four. Needs its own full design pass before
 any code — at minimum: an LLM provider interface (zero shipped
 implementations, host brings their own key/provider, same pattern as