@hartl-services/medusa-base 1.1.0 → 2.1.0

package/README.md

@@ -68,7 +68,7 @@ plugins: [
       // E-Mail, Documents and the /files gateway: see the sections below
       // (or let the Shop-Config-Preset fill them in).
       // email: { jwtSecret, shop },
-      // documents: { merchant, numbering, pdf, htmlFactory },
+      // documents: { numbering, pdf, htmlFactory },
       // files: { gateway },
     },
   },
@@ -83,7 +83,7 @@ every module of the plugin; each module reads only its own namespace:
 |---|---|---|
 | `settingsSecret` | `plugin_features` module | Key material for stored secret settings. Set it from an environment variable of the shop; unset or empty, the base uses `projectConfig.http.cookieSecret`. |
 | `email` | `email` module | `{ jwtSecret, shop }`: branding, URLs and the JWT secret of the e-mail links (see "E-Mail"). Without `email.shop` the module boots but sends nothing. |
-| `documents` | `documents` module | `{ merchant?, numbering?, pdf?, htmlFactory? }` (see "Dokumente"). Defaults: numbering time zone `Europe/Vienna`, PDF executable `google-chrome`. |
+| `documents` | `documents` module | `{ numbering?, pdf?, htmlFactory? }` (see "Dokumente"). Defaults: numbering time zone `Europe/Vienna`, PDF executable `google-chrome`. |
 | `files` | `/files` routes | `{ gateway: { signingSecret } }`, returned by `createS3CacheStorageConfig` (see "Dateispeicher (S3)"). |
 
 `options: {}` is valid: the base then only provides the feature toggles,
@@ -125,6 +125,7 @@ dashboard uses.
 | `POST` | `/admin/plugin-features/:plugin_key/settings` | Admin user | `AdminPluginFeaturesResponse` |
 | `POST` | `/admin/plugin-features/:plugin_key/actions/:action_key` | Admin user | `AdminPluginActionRunResponse` (200 sync, 202 background), 409 `AdminPluginActionConflictResponse` while it runs |
 | `GET` | `/admin/plugin-features/:plugin_key/actions/:action_key/runs` | Admin user | `AdminPluginActionRunsResponse` (`?limit=`, default 1, max 20) |
+| `POST` | `/store/customer-verification/resend` | publishable key | 202 `ResendCustomerVerificationResponse` (`{ accepted: true }`) for every address, 404 while `customer_verification` is off; see "Kontobestätigung per E-Mail" |
 
 Every authenticated Admin user may change toggles and settings and run
 actions (no RBAC by design). Admin plugin DTOs carry the toggles plus
@@ -272,7 +273,9 @@ Code on the cart and checkout hot path (cart middlewares, cart workflow hooks,
 `orderCreated` handling, cart subscribers) must never read toggles. It stays
 fail-safe and independent of the database state of this plugin. Toggles
 control visibility and reachability of features, not the integrity of
-existing data.
+existing data. Login is not the cart path: the E-Mail plugin's
+`customer_verification` toggle does switch customer logins, through an
+in-memory copy of the toggle (see "Kontobestätigung per E-Mail").
 
 ## Runtime settings
 
@@ -480,15 +483,13 @@ settings like any plugin's:
 | `iban`, `bic` | string | no |
 | `company_register_number` (Firmenbuchnummer), `company_register_court` (Firmenbuchgericht) | string | no |
 
-Server-side code reads them with a plugin's own medusa-config values as
-fallback (stored in the Admin wins per key):
+Server-side code reads them exactly as stored in the Admin; there is no
+medusa-config fallback:
 
 ```ts
 import { getShopMasterData } from "@hartl-services/medusa-base"
 
-const { values, configured, missing } = await getShopMasterData(container, {
-  legal_name: options.merchant?.legalName,
-})
+const { values, configured, missing } = await getShopMasterData(container)
 if (!configured) {
   throw new MedusaError(
     MedusaError.Types.UNEXPECTED_STATE,
@@ -834,8 +835,11 @@ Options of the `email` namespace:
   `projectConfig.http.jwtSecret`.
 - `shop` — a `ShopEmailConfiguration` object: `displayName`,
   `affiliatePortalUrl`, the `passwordResetUrl`/`inviteUrl` builders and the
-  `orderNotificationEmail` mailbox. `layout` and `renderers` are optional
-  overrides, see "Shop configuration and default templates".
+  `orderNotificationEmail` mailbox. `verifyAccountUrl` (optional builder,
+  like `passwordResetUrl`; the mail appends `#token=`) is the storefront page
+  that confirms an account, needed while `customer_verification` is on.
+  `layout` and `renderers` are optional overrides, see "Shop configuration and
+  default templates".
 
 Without `email.shop` the module still boots, but it cannot dispatch: no mail
 is sent (the dispatch configuration is requested lazily and fails with
@@ -884,7 +888,8 @@ feature is switched on again.
 | --------------------- | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
 | (plugin switch)       | E-Mail                 | on      | every route under `/admin/email/*` (mail log, resends, terms versions; 404); jobs `email-reconcile-attempts`, `email-reconcile-pending-messages`, `email-retry-messages`; every feature below                            | checkout and orders; already queued messages stay stored |
 | `order_mails`         | Bestell-Mails          | on      | subscribers `order-placed`, `email-shipment-created`, `email-order-canceled`, `return-requested`, `return-received`, `documents-shipment-invoice-assignment-decided`, `documents-order-cancellation-ready`, `documents-refund-ready` | jobs, Admin routes, already created messages             |
-| `account_mails`       | Konto-Mails            | on      | subscribers `password-reset`, `user-invite`                                                                                                                                                                              | jobs, Admin routes, already created messages             |
+| `account_mails`       | Konto-Mails            | on      | subscribers `password-reset`, `user-invite`, `customer-verification` (the last one only with `customer_verification` on as well)                                                                                          | jobs, Admin routes, already created messages             |
+| `customer_verification` | Kontobestätigung per E-Mail | off | Medusa's e-mail verification of customer logins (see "Kontobestätigung per E-Mail"), route `POST /store/customer-verification/resend` (404 while off), subscriber `customer-verification`; child of `account_mails` | checkout and orders; confirmed accounts stay confirmed, already created messages |
 | `affiliate_reminders` | Affiliate-Erinnerungen | on      | subscriber `affiliate-consignment-reminder-due`                                                                                                                                                                          | jobs, Admin routes, already created messages             |
 
 With the plugin switched off the three jobs return immediately, so nothing
@@ -904,6 +909,111 @@ and gates the Terms PDF versions and mail log sections below it on the
 plugin switch, showing `PluginFeatureDisabledNotice` in their place while it
 is off.
 
+### Kontobestätigung per E-Mail
+
+Feature `customer_verification` (child of `account_mails`, default **off**)
+makes customers confirm their e-mail address through a link before their
+first login. It builds on Medusa 2.19's own e-mail verification
+(`projectConfig.http.authVerificationsPerActor`) and adds the mail, the
+toggle and a resend route.
+
+How it works while the feature is on:
+
+1. A login (`POST /auth/customer/emailpass`) of an account whose address is
+   not confirmed answers `200 { verification_required: true, verification,
+   token }`. `token` is an actorless JWT, valid only for the verification
+   calls.
+2. The storefront calls Medusa's `POST /auth/verification/request`
+   (`{ code_provider: "token", entity_id: <e-mail>, entity_type: "email" }`)
+   with that token. Medusa emits `auth.verification_requested`; the
+   `customer-verification` subscriber sends the mail "Bestätige deine
+   E-Mail-Adresse" (kind `auth.verification`) to `entity_id`.
+3. The link is `<STOREFRONT_URL>/<cc>/verify-account#token=<token>`
+   (`verifyAccountUrl` plus the fragment, never a query string). The
+   storefront page calls `POST /auth/verification/confirm`
+   (`{ code: <token>, code_provider: "token" }`); the next login returns a
+   normal token.
+4. The token is valid for 15 minutes (Medusa's default `ttl_seconds` of the
+   token provider). Every new request issues a new token and invalidates the
+   previous one.
+5. `POST /store/customer-verification/resend` (`{ email }`, publishable key)
+   asks for a new mail without a login. It always answers 202
+   `{ accepted: true }`, whether or not an account exists, is confirmed or
+   was asked too recently, so addresses cannot be probed. The answer is sent
+   before any lookup (equal timing), the work runs detached. A mail follows
+   only for an existing, unconfirmed customer account whose last request is
+   older than 60 seconds. Admin users and addresses without a customer
+   account are ignored. A failure is logged with a fixed message and the
+   error class only (never the address), not answered. While the feature is
+   off the route answers 404.
+6. The same 60-second limit per account applies to Medusa's own
+   `POST /auth/verification/request`, which the storefront calls at every
+   blocked login: a base middleware answers a request within a minute of the
+   previous one with `201 { verification }` (Medusa's shape, without the
+   stored token hash) and sends nothing, so repeated logins cannot mail-bomb
+   an address; the earlier link stays valid. It applies only to the customer
+   account's own `emailpass` address while the feature is on, and fails open
+   (the request goes on to Medusa) if the check itself fails.
+
+Accounts that exist before the feature is switched on need no migration: they
+have no confirmation row, so their next login is answered with
+`verification_required` and the storefront sends them the mail. Social or
+other providers are not affected, only `emailpass` for `customer`.
+
+The mail is sent only while the plugin switch, `account_mails` and
+`customer_verification` are on. It is built from the event like the
+password-reset mail: only the token's hash (the business key) is stored, never
+the token or the link, and neither the generic retry job nor an Admin resend
+can touch it (the Event Bus retry and the 60-second resend are the retry paths).
+Medusa takes `entity_id` of the verification request from the request body
+without comparing it, so the subscriber sends only to an address that is the
+identity's own `emailpass` address and only for a customer actor.
+
+**Switching at run time.** The preset sets
+`projectConfig.http.authVerificationsPerActor` to an object whose `customer`
+is a getter: Medusa reads it on every login, and the getter answers from an
+in-memory copy of the effective toggle. The copy is loaded when the
+application starts (the E-Mail module's `onApplicationStart`) and, while
+an unref'd timer refreshes it every 30 seconds, also without traffic (stopped
+at shutdown); a read that finds the copy older than 30 seconds additionally
+starts a background refresh (stale-while-revalidate; the getter is synchronous
+and never throws). A change in the Admin therefore reaches a running instance
+within about 30 seconds plus the read (each instance has its own copy); the
+resend route, the request throttle and the subscriber read
+the toggle itself and follow at once. A failed read keeps the last value and
+logs a warning; before the first successful read the copy is off. The copy
+lives on `globalThis` because the preset (`dist`) and the plugin code Medusa
+loads (`.medusa/server`) are compiled separately. Only the preset
+(`buildFoodShopConfig` / `defineFoodShopConfig`) sets the getter; a shop with a
+hand-written config must set `authVerificationsPerActor` itself (a fixed list,
+changed by a restart) for the toggle to have any effect on logins.
+
+Login is not on the cart path, so the cart rule above is not affected.
+
+Things to know when switching it on:
+
+- Customers who are already logged in stay logged in until their session or
+  JWT expires: Medusa checks the confirmation at login and token generation
+  without an actor, and a token refresh of an existing actor skips it.
+  Only their next login asks for the confirmation.
+- A password reset does not confirm the address; the customer still
+  confirms through the link at the next login.
+- The storefront must not store the actorless `token` of a
+  `verification_required` response as the customer session. It is only for
+  the verification request, and it carries no customer.
+
+Storefront contract (DTOs, schema and path from the Contracts package,
+`types/customer-verification-store`, `schemas/customer-verification`,
+`paths/customer-verification`):
+
+- Read `GET /store/plugin-features/email` and show the confirmation flow only
+  while `features.customer_verification` is `true`.
+- Handle `verification_required` on login and registration: request the mail
+  with the actorless token, show "check your inbox" and offer "Bestätigungsmail
+  erneut senden" (`customerVerificationStorePaths.post.resend`).
+- Serve `/<cc>/verify-account`, read `token` from `location.hash`, confirm it
+  and then send the customer to the login.
+
 ### Ownership
 
 - Documents owns document issuance and publishes immutable document facts.
@@ -946,6 +1056,7 @@ installed Medusa 2.19 exports:
 | `order.return_requested` | `{ order_id: string; return_id: string }`                                                      |
 | `order.return_received`  | `{ order_id: string; return_id: string }`                                                      |
 | `auth.password_reset`    | `{ entity_id: string; actor_type: string; token: string; metadata?: Record<string, unknown> }` |
+| `auth.verification_requested` | `{ entity_id: string; entity_type: string; code_provider: string; auth_identity_id: string; code: string; expires_at: Date \| string; metadata?: Record<string, unknown> }`; not strict, `code` is missing for an already confirmed identity (ignored) |
 
 The shared immutable Documents artifact is:
 
@@ -1039,8 +1150,8 @@ has at most 35 characters. Email runtime-validates every contract before use.
 
 - The accepted kinds are exactly `order.received`, `order.received.admin`, `order.shipped`,
   `order.canceled`, `order.return_requested`, `order.return_received`,
-  `order.refunded`, `auth.password_reset`, and
-  `affiliate.consignment_report_due`.
+  `order.refunded`, `auth.password_reset`, `auth.verification`,
+  `affiliate.consignment_report_due` and `user.invite`.
 - Every automatic message has a deterministic business key.
 - Every placed Order creates independent customer and Shop intents. The customer
   intent honors `no_notification`; the Shop intent always targets the static
@@ -1062,10 +1173,11 @@ has at most 35 characters. Email runtime-validates every contract before use.
   including any invoice attachment; refund email has no Documents-disabled
   native fallback.
 - Recipients, rendered content, attachment bytes, SMTP responses, credentials,
-  reset tokens, and reset URLs are never logged.
-- Reset tokens and reset URLs are never persisted by Email or Notification.
-- Password-reset messages cannot be retried by the generic retry job or resent
-  by an Admin.
+  reset and verification tokens, and their URLs are never logged.
+- Reset and verification tokens and URLs are never persisted by Email or
+  Notification.
+- Password-reset and account-confirmation messages cannot be retried by the
+  generic retry job or resent by an Admin.
 - Unknown transport outcomes are never automatically resent.
 - Shop branding is the configured `displayName` plus the `logo` setting of
   the E-Mail plugin and the company details of the Shop-Stammdaten; a shop overrides the default layout or
@@ -1174,6 +1286,14 @@ without `iat`) and a note that the mail can be ignored. The lifetime is
 passed as the ephemeral `valid_minutes` next to `reset_url` and is never
 persisted.
 
+The account confirmation (`auth.verification`) has the subject "Bestätige
+deine E-Mail-Adresse", a "E-Mail-Adresse bestätigen" button, the link as
+copyable text, a note that the link is only valid for a limited time (a new
+one comes with the next login or "Bestätigungsmail erneut senden") and a note
+that the mail can be ignored. The link comes from `verifyAccountUrl` plus
+`#token=`; without that builder the message fails with `render_failed`. See
+"Kontobestätigung per E-Mail".
+
 The affiliate reminder (`affiliate.consignment_report_due`) greets the
 affiliate by `affiliate_display_name`, names the report month ("September
 2026", Austrian month names) and the due date ("10.10.2026") as calendar
@@ -1260,9 +1380,10 @@ process persists success, and a conscious resend can produce a duplicate.
 
 Email transport retries and Event Bus retries are separate. Once an ordinary
 message outcome is persisted, its subscriber completes and the Email retry job
-owns any `retry_pending` work. Password-reset token and URL data remain
-ephemeral; password reset is excluded from the generic retry job and Admin
-resend, and retryable handling stays bounded by the original Event Bus event.
+owns any `retry_pending` work. Password-reset and verification token and URL
+data remain ephemeral; both kinds are excluded from the generic retry job and
+Admin resend, and retryable handling stays bounded by the original Event Bus
+event.
 
 ### Admin API
 
@@ -1461,12 +1582,7 @@ export default defineConfig({
     },
     {
       resolve: "@hartl-services/medusa-tax-compliance",
-      options: {
-        merchant: {
-          countryCode: process.env.MERCHANT_COUNTRY_CODE!,
-          vatNumber: process.env.MERCHANT_VAT_NUMBER!,
-        },
-      },
+      options: {},
     },
   ],
 });
@@ -1487,10 +1603,9 @@ Options of the `documents` namespace (all optional; `{}` is valid):
   rejected at startup when invalid.
 - `pdf.executablePath` — Chromium/Chrome executable path or command name.
   Defaults to `"google-chrome"`.
-- `merchant` — optional fallback for the shop master data (see "Merchant
-  data" below), shape `DocumentMerchantOption`:
-  `{ countryCode, legalName, registeredAddress: { address1, address2?, city,
-  countryCode, postalCode }, vatNumber? }`.
+
+The sender (company, address, UID, contact, bank) is not an option: it comes
+only from the Shop-Stammdaten (see "Merchant data" below).
 
 The `documents` module is always registered with the base (no `documentsEnabled`
 switch); the Admin switches it off at run time through the feature toggles
@@ -1557,8 +1672,8 @@ Each render reads it and passes it to the `htmlFactory` as `input.merchant`
 (`DocumentMerchant`: `legal_name`, `address_line1`, `address_line2`,
 `postal_code`, `city`, `country_code`, `vat_number`, `email`, `phone`,
 `website`, `iban`, `bic`, `company_register_number`,
-`company_register_court`; unset optional fields are `null`). Per field, a
-value stored in the Admin wins over the `merchant` option.
+`company_register_court`; unset optional fields are `null`). There is no
+medusa-config fallback: what is stored in the Admin is what is printed.
 
 - `merchant` is not part of the stored snapshot: a regenerated document
   prints the master data current at regeneration time.
@@ -1638,8 +1753,8 @@ a toggle.
 ### Shop integration
 
 The demo shop (`apps/backend`) gets everything from the preset (see
-"Shop-Config-Preset"): `documents.merchant` is its `merchant` option,
-`documents.numbering.timeZone` its `timeZone` option and
+"Shop-Config-Preset"): `documents.numbering.timeZone` is its `timeZone`
+option, `documents.htmlFactory` its optional `documentHtmlFactory` and
 `documents.pdf.executablePath` the `DOCUMENT_PDF_EXECUTABLE` variable. The
 development UID `ATU00000000` is a placeholder: Documents never prints it,
 and Tax Compliance does not transmit it to FinanzOnline. Enter the real
@@ -2307,17 +2422,6 @@ pnpm add @hartl-services/medusa-base \
 import { defineFoodShopConfig } from "@hartl-services/medusa-base/shop-config"
 
 module.exports = defineFoodShopConfig({
-  merchant: {
-    countryCode: "at",
-    legalName: "Example Shop GmbH",
-    registeredAddress: {
-      address1: "Musterstrasse 1",
-      city: "Wien",
-      countryCode: "at",
-      postalCode: "1010",
-    },
-    vatNumber: "ATU12345678",
-  },
   displayName: "EXAMPLE SHOP",
   orderNotificationEmail: "orders@example.com",
   timeZone: "Europe/Vienna",
@@ -2358,11 +2462,10 @@ validate the environment; a missing variable fails with the variable's name.
 
 | Option | Meaning |
 | --- | --- |
-| `merchant` | `DocumentMerchantOption` (`countryCode`, `legalName`, `registeredAddress`, optional `vatNumber`). Fallback for the Shop-Stammdaten (Admin, "Hartl Services Plugins") that documents and tax compliance read per field; `legalName` is also the seeded store name. Country codes are 2-letter lowercase. |
-| `displayName` | Shop name in the default e-mail templates. |
+| `displayName` | Shop name in the default e-mail templates (a shop's initial seed may use it as store name). Company name, address and UID are no options: documents and tax compliance read them only from the Shop-Stammdaten (Admin, "Hartl Services Plugins"). |
 | `orderNotificationEmail` | Receives order notification e-mails; must look like an e-mail address. |
 | `timeZone` | IANA time zone (validated with `Intl`). Chooses the annual document-number period, the printed dates on documents and the affiliate consignment reminder time zone. |
-| `storefrontCountryCode` | 2-letter lowercase country code of the storefront route. Links: `<STOREFRONT_URL>/<cc>/partnerportal` (affiliate portal), `<STOREFRONT_URL>/<cc>/reset-password` (the e-mail plugin appends `#token=`), referral base `<STOREFRONT_URL>/<cc>`. The Admin invite link is `<MEDUSA_BACKEND_URL>/app/invite?token=`. |
+| `storefrontCountryCode` | 2-letter lowercase country code of the storefront route. Links: `<STOREFRONT_URL>/<cc>/partnerportal` (affiliate portal), `<STOREFRONT_URL>/<cc>/reset-password` and `<STOREFRONT_URL>/<cc>/verify-account` (the e-mail plugin appends `#token=`), referral base `<STOREFRONT_URL>/<cc>`. The Admin invite link is `<MEDUSA_BACKEND_URL>/app/invite?token=`. |
 | `documentHtmlFactory` | Optional `DocumentHtmlFactory` that replaces the default document markup, typically `createDefaultDocumentHtmlFactory({ timeZone, theme })` from `/config` with the shop's CSS and watermark (see "Layout, logo, payment terms and shop theme"). Must be a function. |
 | `loadEnvFile` | Default `true`: calls `loadEnv(NODE_ENV \|\| "development", process.cwd())`. Pass `false` when the environment is already complete (tests, isolated child processes). |
 
@@ -2402,4 +2505,6 @@ Not configurable on purpose: the plugin order (base first), the Redis event
 bus job policy (3 attempts, exponential backoff from 1 s), S3 cache defaults
 (15 min cleanup, 1 h TTL, absolute expiration), Stripe immediate capture with
 automatic payment methods, the 24 h session lifetime, Admin path `/app`,
-consignment reminders due on day 10, and the Documents module always being part of the base.
+consignment reminders due on day 10, the Documents module always being part of the base, and
+`http.authVerificationsPerActor.customer` (a getter that follows the E-Mail `customer_verification` toggle, see
+"Kontobestätigung per E-Mail").

package/dist/documents/types/documents.d.ts

@@ -144,28 +144,6 @@ export type DocumentMerchant = {
     company_register_number: string | null;
     company_register_court: string | null;
 };
-/**
- * Optional `merchant` plugin option: used per field only where the shop
- * master data in the base plugin has no value (same shape as the demo shop's
- * `merchant` constant in medusa-config).
- */
-export type DocumentMerchantOption = {
-    countryCode: string;
-    legalName: string;
-    registeredAddress: {
-        address1: string;
-        address2?: string;
-        city: string;
-        countryCode: string;
-        postalCode: string;
-    };
-    vatNumber?: string;
-};
-/**
- * The Documents settings (Admin -> "Hartl Services Plugins" -> Dokumente) a
- * render needs, read when a document is rendered. Not part of the stored
- * snapshot: a regenerated document shows the current values.
- */
 export type DocumentRenderSettings = {
     /**
      * The uploaded logo as a `data:` URL, ready for `<img src>`; `null` when no

package/dist/email/customer-verification-snapshot.d.ts

@@ -0,0 +1,53 @@
+/**
+ * In-memory copy of the effective `customer_verification` toggle for the one
+ * place that cannot await it: Medusa reads
+ * `projectConfig.http.authVerificationsPerActor.customer` synchronously on
+ * every login. The shop preset puts `customerVerificationActors()` behind a
+ * getter there, so a toggle change in the Admin takes effect without a
+ * restart.
+ *
+ * - Boot: `startCustomerVerificationSnapshot` loads the toggle once.
+ * - Afterwards an unref'd timer refreshes every 30 s, so a change reaches an
+ *   idle instance too. A read that finds the copy older than 30 s (a blocked
+ *   timer, say) also starts one refresh in the background
+ *   (stale-while-revalidate) and still answers from the copy. A change thus
+ *   reaches a running instance within about 30 s plus the duration of the
+ *   read.
+ * - A failed read keeps the last value (initially "off") and is logged; the
+ *   next attempt waits another 30 s.
+ *
+ * The state lives on `globalThis`: the preset (`dist`) and the Medusa-loaded
+ * plugin code (`.medusa/server`) are compiled separately and would otherwise
+ * each hold their own copy. Login is not on the cart path.
+ */
+export declare const CUSTOMER_VERIFICATION_REFRESH_MS = 30000;
+export type CustomerVerificationActor = Readonly<{
+    auth_provider: string;
+    entity_type: string;
+}>;
+/** Reads the toggle once; never rejects. Concurrent calls share one read. */
+export declare const refreshCustomerVerificationSnapshot: () => Promise<void>;
+/** Stops the periodic refresh (application shutdown). The value stays. */
+export declare const stopCustomerVerificationSnapshot: () => void;
+/**
+ * Registers the reader, loads the toggle once and keeps it fresh every 30 s
+ * (application start). `read` returns the effective toggle; `warn` is the
+ * container logger. Starting again replaces the reader and the timer.
+ */
+export declare const startCustomerVerificationSnapshot: (input: Readonly<{
+    read: () => Promise<boolean>;
+    warn: (message: string) => void;
+}>) => Promise<void>;
+/** Synchronous; starts a background refresh when the copy is stale. Never throws. */
+export declare const isCustomerVerificationEnabled: () => boolean;
+/**
+ * The value of `authVerificationsPerActor.customer`: Medusa's e-mail
+ * verification for the `emailpass` provider while the toggle is on, none
+ * while it is off. A fresh array per call.
+ */
+export declare const customerVerificationActors: () => CustomerVerificationActor[];
+/**
+ * Test hook: sets the value and counts as just refreshed, so it holds for
+ * 30 s without a reader; `null` forgets reader and value.
+ */
+export declare const setCustomerVerificationEnabledForTests: (enabled: boolean | null) => void;

package/dist/email/customer-verification-snapshot.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setCustomerVerificationEnabledForTests = exports.customerVerificationActors = exports.isCustomerVerificationEnabled = exports.startCustomerVerificationSnapshot = exports.stopCustomerVerificationSnapshot = exports.refreshCustomerVerificationSnapshot = exports.CUSTOMER_VERIFICATION_REFRESH_MS = void 0;
+/**
+ * In-memory copy of the effective `customer_verification` toggle for the one
+ * place that cannot await it: Medusa reads
+ * `projectConfig.http.authVerificationsPerActor.customer` synchronously on
+ * every login. The shop preset puts `customerVerificationActors()` behind a
+ * getter there, so a toggle change in the Admin takes effect without a
+ * restart.
+ *
+ * - Boot: `startCustomerVerificationSnapshot` loads the toggle once.
+ * - Afterwards an unref'd timer refreshes every 30 s, so a change reaches an
+ *   idle instance too. A read that finds the copy older than 30 s (a blocked
+ *   timer, say) also starts one refresh in the background
+ *   (stale-while-revalidate) and still answers from the copy. A change thus
+ *   reaches a running instance within about 30 s plus the duration of the
+ *   read.
+ * - A failed read keeps the last value (initially "off") and is logged; the
+ *   next attempt waits another 30 s.
+ *
+ * The state lives on `globalThis`: the preset (`dist`) and the Medusa-loaded
+ * plugin code (`.medusa/server`) are compiled separately and would otherwise
+ * each hold their own copy. Login is not on the cart path.
+ */
+exports.CUSTOMER_VERIFICATION_REFRESH_MS = 30_000;
+const STATE_KEY = Symbol.for("@hartl-services/medusa-base/customer-verification-snapshot");
+const state = () => {
+    const holder = globalThis;
+    holder[STATE_KEY] ??= {
+        enabled: false,
+        refreshedAt: null,
+        refreshing: null,
+        timer: null,
+        read: null,
+        warn: null,
+    };
+    return holder[STATE_KEY];
+};
+const logFailure = (current, error) => {
+    try {
+        current.warn?.(`Customer verification toggle could not be read, keeping "${current.enabled ? "on" : "off"}": ${error instanceof Error ? error.message : "unknown error"}`);
+    }
+    catch {
+        // A broken logger must not turn a failed refresh into a throw.
+    }
+};
+/** Reads the toggle once; never rejects. Concurrent calls share one read. */
+const refreshCustomerVerificationSnapshot = () => {
+    const current = state();
+    if (!current.read) {
+        return Promise.resolve();
+    }
+    if (current.refreshing) {
+        return current.refreshing;
+    }
+    const read = current.read;
+    // Started from a microtask so the assignment below always precedes `finally`.
+    const refreshing = Promise.resolve().then(async () => {
+        try {
+            current.enabled = (await read()) === true;
+        }
+        catch (error) {
+            logFailure(current, error);
+        }
+        finally {
+            current.refreshedAt = Date.now();
+            current.refreshing = null;
+        }
+    });
+    current.refreshing = refreshing;
+    return refreshing;
+};
+exports.refreshCustomerVerificationSnapshot = refreshCustomerVerificationSnapshot;
+const stopTimer = (current) => {
+    if (current.timer) {
+        clearInterval(current.timer);
+        current.timer = null;
+    }
+};
+/** Stops the periodic refresh (application shutdown). The value stays. */
+const stopCustomerVerificationSnapshot = () => {
+    stopTimer(state());
+};
+exports.stopCustomerVerificationSnapshot = stopCustomerVerificationSnapshot;
+/**
+ * Registers the reader, loads the toggle once and keeps it fresh every 30 s
+ * (application start). `read` returns the effective toggle; `warn` is the
+ * container logger. Starting again replaces the reader and the timer.
+ */
+const startCustomerVerificationSnapshot = (input) => {
+    const current = state();
+    current.read = input.read;
+    current.warn = input.warn;
+    stopTimer(current);
+    current.timer = setInterval(() => {
+        void (0, exports.refreshCustomerVerificationSnapshot)();
+    }, exports.CUSTOMER_VERIFICATION_REFRESH_MS);
+    // An idle timer must not keep the process (or a test run) alive.
+    current.timer.unref();
+    return (0, exports.refreshCustomerVerificationSnapshot)();
+};
+exports.startCustomerVerificationSnapshot = startCustomerVerificationSnapshot;
+/** Synchronous; starts a background refresh when the copy is stale. Never throws. */
+const isCustomerVerificationEnabled = () => {
+    const current = state();
+    if (current.read &&
+        !current.refreshing &&
+        (current.refreshedAt === null ||
+            Date.now() - current.refreshedAt >= exports.CUSTOMER_VERIFICATION_REFRESH_MS)) {
+        void (0, exports.refreshCustomerVerificationSnapshot)();
+    }
+    return current.enabled;
+};
+exports.isCustomerVerificationEnabled = isCustomerVerificationEnabled;
+/**
+ * The value of `authVerificationsPerActor.customer`: Medusa's e-mail
+ * verification for the `emailpass` provider while the toggle is on, none
+ * while it is off. A fresh array per call.
+ */
+const customerVerificationActors = () => (0, exports.isCustomerVerificationEnabled)()
+    ? [{ auth_provider: "emailpass", entity_type: "email" }]
+    : [];
+exports.customerVerificationActors = customerVerificationActors;
+/**
+ * Test hook: sets the value and counts as just refreshed, so it holds for
+ * 30 s without a reader; `null` forgets reader and value.
+ */
+const setCustomerVerificationEnabledForTests = (enabled) => {
+    const current = state();
+    if (enabled === null) {
+        stopTimer(current);
+        current.enabled = false;
+        current.refreshedAt = null;
+        current.refreshing = null;
+        current.read = null;
+        current.warn = null;
+        return;
+    }
+    current.enabled = enabled;
+    current.refreshedAt = Date.now();
+};
+exports.setCustomerVerificationEnabledForTests = setCustomerVerificationEnabledForTests;

package/dist/email/types/email-kinds.d.ts

@@ -1,5 +1,5 @@
 import { z } from "@medusajs/framework/zod";
-export declare const EMAIL_KINDS: readonly ["order.received", "order.received.admin", "order.shipped", "order.canceled", "order.return_requested", "order.return_received", "order.refunded", "auth.password_reset", "affiliate.consignment_report_due", "user.invite"];
+export declare const EMAIL_KINDS: readonly ["order.received", "order.received.admin", "order.shipped", "order.canceled", "order.return_requested", "order.return_received", "order.refunded", "auth.password_reset", "affiliate.consignment_report_due", "user.invite", "auth.verification"];
 export declare const EmailKindSchema: z.ZodEnum<{
     "order.received": "order.received";
     "order.received.admin": "order.received.admin";
@@ -11,5 +11,13 @@ export declare const EmailKindSchema: z.ZodEnum<{
     "auth.password_reset": "auth.password_reset";
     "affiliate.consignment_report_due": "affiliate.consignment_report_due";
     "user.invite": "user.invite";
+    "auth.verification": "auth.verification";
 }>;
 export type EmailKind = (typeof EMAIL_KINDS)[number];
+/**
+ * Kinds whose link carries a one-time token that is never persisted: the
+ * subscriber builds the mail from the event, so neither the generic retry
+ * job, the automatic dispatch nor an Admin resend may touch them.
+ */
+export declare const EPHEMERAL_EMAIL_KINDS: readonly ["auth.password_reset", "auth.verification"];
+export declare const isEphemeralEmailKind: (kind: EmailKind) => boolean;

package/dist/email/types/email-kinds.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EmailKindSchema = exports.EMAIL_KINDS = void 0;
+exports.isEphemeralEmailKind = exports.EPHEMERAL_EMAIL_KINDS = exports.EmailKindSchema = exports.EMAIL_KINDS = void 0;
 const zod_1 = require("@medusajs/framework/zod");
 exports.EMAIL_KINDS = [
     "order.received",
@@ -13,5 +13,17 @@ exports.EMAIL_KINDS = [
     "auth.password_reset",
     "affiliate.consignment_report_due",
     "user.invite",
+    "auth.verification",
 ];
 exports.EmailKindSchema = zod_1.z.enum(exports.EMAIL_KINDS);
+/**
+ * Kinds whose link carries a one-time token that is never persisted: the
+ * subscriber builds the mail from the event, so neither the generic retry
+ * job, the automatic dispatch nor an Admin resend may touch them.
+ */
+exports.EPHEMERAL_EMAIL_KINDS = [
+    "auth.password_reset",
+    "auth.verification",
+];
+const isEphemeralEmailKind = (kind) => exports.EPHEMERAL_EMAIL_KINDS.includes(kind);
+exports.isEphemeralEmailKind = isEphemeralEmailKind;

package/dist/email/types/shop-configuration.d.ts

@@ -49,6 +49,14 @@ export type ShopEmailConfiguration = Readonly<{
     passwordResetUrl: (input: Readonly<{
         locale: string | null;
     }>) => string;
+    /**
+     * Storefront page that confirms an account's e-mail address; the mail
+     * appends `#token=<token>`. Only needed while the E-Mail plugin's
+     * `customer_verification` feature is used; a mail cannot be built without it.
+     */
+    verifyAccountUrl?: (input: Readonly<{
+        locale: string | null;
+    }>) => string;
     renderers?: Partial<EmailRendererMap>;
     /**
      * IANA time zone of dates in the default templates (e.g. the order time in