Architecture: where does business logic belong — CMS extensions vs. the Nuxt website server?

[Jan0707]

Summary

We need a deliberate, one-time decision on where business logic lives: in the Directus CMS (as coded, versioned, tested extensions) or in the Nuxt website's server layer (server/api/**). Right now it's drifting into both, apparently without a decision ever having been made — and we should settle it once, then refactor to match.

Where this came from

While building the newsletter double-opt-in flow ([#PR], branch newsletter-signup), the confirmation step raised the question: should the website flip a subscriber's status (pending → confirmed) via the authenticated Directus client, or should it hand a token to the CMS and let the CMS own that transition?

That turned out to be an instance of a broader, unspoken pattern rather than a one-off.

The observation

The Nuxt app was, as far as we can tell, originally intended as the presentation layer. But privileged business logic has already accumulated in its server layer. Concrete examples today:

• nuxt-app/server/utils/authenticatedDirectus.ts holds the Directus admin token and exposes privileged mutations: createTicketOrder, updateTicketOrder, updateSpeaker, updateTicket, createNewsletterSubscriber, and now confirmNewsletterSubscriber.
• Token-validate-then-mutate flows live in the website server: server/api/ticket-portal/*, server/api/speaker-portal/*, and (proposed) server/api/newsletter/confirm.get.ts.
• Domain rules (e.g. VAT, order state transitions, the DOI confirm state-machine) are partly encoded website-side.

Meanwhile the CMS bundle (directus-cms/extensions/directus-extension-programmierbar-bundle) is clearly the intended home for business logic: coded hooks/endpoints, version-controlled, and jest-tested (196 tests today).

So the same class of logic currently lives in two places depending on which flow you look at.

The core question

Do we accept business logic in the website, or do we treat the website strictly as presentation and keep all domain logic in the CMS (as coded extensions)?

Sub-questions that fall out of it:

1. Should the website hold the Directus admin token at all, or only ever talk to purpose-built CMS endpoints authenticated with a narrowly-scoped credential (or a per-operation token, e.g. a confirm token as proof)?
2. If logic belongs in the CMS, what's the boundary the website is still allowed to own? (Input validation? Spam/honeypot? Rate limiting? Purely presentational data shaping?)
3. What's the authentication model between website → CMS for these privileged operations?

Options (high level)

• A — Status quo, made explicit. The website's Nitro server is an accepted backend-for-frontend and may hold privileged logic. Document it as a deliberate choice and standardise the pattern (it's coded/versioned/tested either way).
• B — CMS owns all domain logic. The website becomes presentation + thin proxy. Privileged operations move to coded Directus endpoint extensions; the website passes proof (tokens) and shapes responses. Requires refactoring the ticket/speaker/newsletter flows and rethinking the admin-token's presence in the website.
• C — Hybrid with an explicit rule. Define exactly which concerns are allowed website-side (e.g. validation, anti-spam, presentation) vs. CMS-side (all state transitions / domain rules), and refactor to the line.

Note: we've already agreed we do not want no-code Directus Flows for logic — any CMS-side logic should be coded extensions (versioned, ideally tested). This debate is CMS-extension vs website-server, not code vs no-code.

What we should NOT do

• Keep making this call per-feature by whoever is writing it. That's how we got a half-and-half boundary.

Ask

Have the debate, decide once, write the decision down (e.g. an ADR or a section in CLAUDE.md / the .claude/rules/*), and then refactor as necessary to match. The newsletter flow is currently built the pragmatic way (logic in the Nuxt server route, consistent with the existing ticket/speaker flows) — it should be refactored along with the others once we've decided, not treated as a special case.

Current pragmatic decision (for context, not a prejudgement)

For the newsletter PR we chose cohesion over architectural purity: the confirm flip stays in the Nuxt server route to match ticket-portal / speaker-portal. This issue is about whether that whole class of decisions should stand.

[Jan0707]

Erstes konkretes Beispiel aus der Praxis (PR #219)

Zwei Tage nach dieser Entscheidung hat der Review-Agent in #219 genau die vorhergesagte Reibung gefunden — es lohnt sich, das hier als Datenpunkt festzuhalten, weil es zeigt, wie sich die Kopplung konkret äußert.

Befund: die 24h-TTL des Confirm-Tokens war zweimal hartcodiert — im CMS-Hook (Create-Pfad) und in refreshNewsletterConfirmation der Website (Refresh-Pfad nach abgelaufenem Link). Divergieren die beiden, schlägt nichts fehl; man bekommt nur unterschiedlich lange Link-Lebensdauern zwischen Anmeldung und Resend.

Dupliziert war dabei nicht nur die Konstante, sondern die ganze Token-Regel:

Fakt	beim Create	beim Refresh
confirm_token	Directus uuid-Special	randomUUID() in der Website
confirm_token_expires_at	CMS-Filter-Hook	Date.now() + 24h in der Website

Was daran lehrreich ist: eine geteilte Konstante war keine Option. nuxt-app und das Extension-Bundle sind getrennte Deploy-Einheiten ohne gemeinsames Modul — man hätte über eine ENV-Variable oder eine automation_settings-Row synchronisieren müssen, also Config-Kopplung eingeführt, um ein Layering-Problem zu übertünchen. Genau die Art von Folgekosten, um die es in diesem Issue geht.

Behoben in 1373c01, soweit ohne Architektur-Entscheidung möglich: das CMS besitzt das Ablaufdatum jetzt auch beim Update (neuer filter auf newsletter_subscribers.items.update, der bei rotiertem confirm_token das Fenster stempelt). Die Website schreibt nur noch { confirm_token: randomUUID() }. Die TTL existiert damit genau einmal.

Was offen bleibt und direkt an dieser Entscheidung hängt: die Token-Erzeugung ist weiterhin doppelt, weil Directus' uuid-Special nur beim Insert greift. Um sie zu entfernen, braucht es eines von beiden:

1. ein zusätzliches Schema-Feld als reines "reissue"-Signal, das die Website setzt — Workaround, der ein Feld nur zur Kommunikation zwischen den Layern einführt; oder
2. den CMS-seitigen Confirm-Endpoint (Custom Endpoint im Bundle), der Lookup, Confirm und Refresh besitzt, während die Website nur den Token weiterreicht — die Variante, die in diesem Issue zur Debatte steht.

Fällt die Entscheidung für "Business-Logik ins CMS", ist Variante 2 der Refactor-Schritt für den Newsletter-Flow, und refreshNewsletterConfirmation / confirmNewsletterSubscriber / readNewsletterSubscriberByToken in nuxt-app/server/utils/authenticatedDirectus.ts entfallen zugunsten eines Proxy-Calls.

[Jan0707]

Zweiter Datenpunkt aus PR #219: Atomarität ist von außen nicht erreichbar

Nach der duplizierten TTL hat der Review-Agent in #219 einen zweiten Fund gemeldet, der dieselbe Wurzel hat — und diesmal ist die Grenze eine harte, nicht bloß eine Frage von Disziplin.

Der Fund: die Confirm-Route liest per Token und schreibt dann per id. Zwei gleichzeitige Requests (doppelt geklickter Link, Retry, zwei Tabs) können damit beide auf demselben Read handeln. Schärfster Fall war der Refresh abgelaufener Links: jede Rotation löst eine Mail aus und nur der neueste Token funktioniert — zwei blinde Writes verschicken also zwei Mails, von denen die zuerst zugestellte einen toten Link enthält.

Behoben in 0ca91e6, soweit von außen möglich: beide Mutationen sind jetzt an den gelesenen Zustand gebunden (status = pending, confirm_token aus dem Link, beim Refresh zusätzlich ein bereits abgelaufenes Fenster) und melden zurück, ob überhaupt eine Zeile geschrieben wurde. Verliert ein Request das Rennen, antwortet der Handler aus dem aktuellen Zustand der Zeile statt aus seinem eigenen, veralteten Read.

Die eigentliche Erkenntnis für dieses Issue: das ist bewusst nur eine Verkürzung des Fensters, kein Verschließen — und zwar nicht aus Bequemlichkeit, sondern weil die REST-API es nicht hergibt. @directus/api@11.17.4, dist/services/items.js:351:

async updateByQuery(query, data, opts) {
    const keys = await this.getKeysByQuery(query);
    return keys.length ? await this.updateMany(keys, data, opts) : [];
}

getKeysByQuery ist ein SELECT über eine eigene ItemsService-Instanz ohne Transaktion (:74), danach ein UPDATE per Primary Key. Ein gefiltertes Update ist also selbst wieder read-then-write; das TOCTOU-Fenster wandert nur aus unserem Handler nach Directus hinein (von zig Millisekunden über Serverless-Instanzen auf Sub-Millisekunden in-process).

Ein echtes Compare-and-Swap braucht ein einzelnes Statement plus rowCount:

UPDATE newsletter_subscribers
   SET status = 'confirmed', confirmed_at = now()
 WHERE id = ? AND status = 'pending' AND confirm_token = ?

Das setzt direkten DB-Zugriff voraus — in einem Custom Endpoint im Bundle über knex trivial, von der Website aus grundsätzlich nicht erreichbar, egal wie sauber wir dort programmieren.

Was die zwei Funde zusammen für die Entscheidung bedeuten

Der TTL-Fund war eine Frage von Disziplin: Duplizierung, die man mit Sorgfalt (oder wie geschehen: mit einer Verschiebung der Zuständigkeit) auch außerhalb des CMS in den Griff bekommt. Dieser Fund ist eine Frage von Fähigkeiten: Invarianten, die mehrere Zeilen oder mehrere Schritte umspannen — Compare-and-Swap, Transaktionen, "genau einmal senden" — kann die Website nicht garantieren, weil ihr das dafür nötige Werkzeug fehlt.

Das ist meiner Meinung nach das brauchbarste Kriterium für die Debatte hier, brauchbarer als "Logik gehört ins CMS" als Prinzip:

• Read-only-Aggregation, Präsentation, Formularvalidierung → Website-Server ist völlig in Ordnung.
• Schreibpfade mit Nebenläufigkeits- oder Exactly-once-Anforderungen → gehören dorthin, wo Transaktionen existieren, also ins CMS. Sonst schreibt man auf Dauer Guards, die fast korrekt sind, und dokumentiert daneben, warum sie es nicht ganz sind (siehe die Kommentare an beiden Methoden in authenticatedDirectus.ts).

Der Newsletter-Confirm-Flow fällt klar in die zweite Kategorie. Wenn die Entscheidung so ausfällt, ist der Refactor: Custom Endpoint im Bundle mit Lookup + Confirm + Refresh in einer Transaktion, Website reicht nur den Token weiter; readNewsletterSubscriberByToken / confirmNewsletterSubscriber / refreshNewsletterConfirmation in nuxt-app/server/utils/authenticatedDirectus.ts entfallen.

[Jan0707]

Data point: permissions follow the writer, not the logic owner

Found while testing the opt-out flow (#220). It's a concrete example of a split-ownership seam leaking, so it belongs in this discussion.

Setup. The newsletter double-opt-in deliberately gives the CMS ownership of the 24h confirmation TTL: the website only rotates confirm_token, and the newsletter-double-opt-in hook's filter stamps confirm_token_expires_at. The point was that create and refresh can't drift apart, since the TTL exists in exactly one place.

What happened. Clicking an expired confirmation link returned a technical error. The website's Directus call failed with:

403 You don't have permission to access field "confirm_token_expires_at"
in collection "newsletter_subscribers" or it does not exist. Queried in root.

Why. Directus runs filter hooks before validating permissions, and then validates the post-hook payload against the caller's policy — ItemsService.updateMany:

const payloadAfterHooks = opts.emitEvents !== false
    ? await emitter.emitFilter(['items.update', `${collection}.items.update`], payload, …)
    : payload
…
validateItemAccess({ action: 'update', fields: Object.keys(payloadAfterHooks) })

So a field the CMS adds is charged to the website's token. Moving the TTL into the CMS moved the value, not the authority: the website's policy still needs create + update permission on a field it never sets. Resolved for now by granting it; the required per-action field lists are in docs/newsletter.md.

Why this is an argument for consolidating the write. Once the confirm/refresh compare-and-swap lives in the CMS (which this issue already contemplates, since a real CAS needs one UPDATE … WHERE … and therefore direct DB access), the website stops writing this collection altogether and the field permissions disappear with it. Partial ownership is what creates the mismatch: the hook is the author of the value, but permission is assessed against whoever opened the request.

The intermediate option, if the write stays on the website side. Stop stamping in the filter and do it in the action with an admin service:

const service = new services.ItemsService(COLLECTION, { schema, accountability: { admin: true } })
await service.updateOne(key, { confirm_token_expires_at: … }, { emitEvents: false })

Both mechanisms verified in the installed Directus: permissions/modules/validate-access/validate-access.js short-circuits on accountability.admin === true, and every filter/action emission in services/items.js is gated on opts.emitEvents !== false (needed here, or the write re-enters the same action and mails twice).

Costs, for the record: a second write per refresh plus an extra revision; a transient row carrying the new token with the old expired window; and stamping that is invisible to all hooks on the collection, not just ours. It also only removes the update requirement — confirm_token_expires_at is NOT NULL with no DB default, so the value must be in the INSERT and therefore in a create filter under the website's accountability. Removing that too needs a CURRENT_TIMESTAMP column default (rows born expired) plus stamping in the create action as well.

Two related Directus behaviours worth writing down

Both are non-obvious and both shaped the code:

1. Filters in a query-based update are not permission-checked. ItemsService.getKeysByQuery resolves them through an ItemsService constructed without accountability, so only payload fields are validated. My first hypothesis (that the guard's filter fields needed permission) was wrong.

2. A guarded write's success signal depends on read permission. PATCH /items/:collection reads the updated rows back, and the controller swallows a Forbidden there (controllers/items.js):

   try {
       const result = await service.readMany(keys, req.sanitizedQuery)
       res.locals['payload'] = { data: result }
   } catch (error) {
       if (isDirectusError(error, ErrorCode.Forbidden)) return next()
       throw error
   }

   Our conditional writes infer "did I win the race?" from updated.length. With no read permission the response carries no data, so a successful write reports as a lost race and the confirm route answers already_confirmed / invalid — silently wrong, no error anywhere. Another argument for the write living where it can be a single statement with an unambiguous result.