@hartl-services/medusa-base 2.0.0 → 2.2.0

package/README.md

@@ -39,6 +39,8 @@ packing lists) and S3 file storage, and the turnkey `medusa-config.ts` preset
 - Redirects `GET /` to the admin dashboard and repairs dangling
   `cart_promotion` links (see "Root redirect" and "Cart-promotion link
   repair").
+- Requires passwords of at least 15 characters for customers and Admin users
+  (see "Password policy").
 - Exports the shop's `medusa-config.ts` helpers from
   `@hartl-services/medusa-base/config` and Sentry's `register()` from
   `@hartl-services/medusa-base/instrumentation` (see "Config helpers" and
@@ -125,6 +127,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 +275,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
 
@@ -692,6 +697,30 @@ reverse-proxy rule. The redirect is temporary on purpose: browsers cache a
 should `/` ever get real content. A shop that needs its own `/` defines
 `src/api/route.ts` itself.
 
+## Password policy
+
+Medusa's `emailpass` provider accepts any non-empty password. The base runs a
+middleware on `POST /auth/:actor_type/emailpass/register` (customer sign-up,
+Admin invite) and `POST /auth/:actor_type/emailpass/update` (password reset)
+and answers a password shorter than 15 characters with
+`400 { type: "invalid_data", message: "Das Passwort muss mindestens 15 Zeichen lang sein." }`.
+It applies to every actor type, so customers and Admin users alike. The check
+runs before Medusa's reset-token check, so a rejected password leaves the
+single-use reset link valid for a second attempt.
+
+The rule follows NIST SP 800-63B Rev. 4 for a password that is the only
+factor: at least 15 characters, counted as Unicode code points, and no
+composition rules (digits and special characters are allowed, never required).
+The value and the check come from the Contracts package
+(`schemas/password-policy`: `PASSWORD_MIN_LENGTH`, `isPasswordLongEnough`), so
+a storefront validates its forms with the same rule.
+
+Login is not checked, so existing shorter passwords keep working until their
+next reset. Accounts created without HTTP (`medusa user`, seed scripts calling
+the Auth module) are not checked either.
+
+Nothing to configure.
+
 ## Cart-promotion link repair
 
 Medusa's `deletePromotionsWorkflow` only soft-deletes a promotion and leaves
@@ -832,8 +861,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
@@ -882,7 +914,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
@@ -902,6 +935,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.
@@ -944,6 +1082,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:
 
@@ -1037,8 +1176,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
@@ -1060,10 +1199,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
@@ -1172,6 +1312,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
@@ -1258,9 +1406,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
 
@@ -2342,7 +2491,7 @@ validate the environment; a missing variable fails with the variable's name.
 | `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). |
 
@@ -2382,4 +2531,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/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

package/dist/email/types/template-data.d.ts

@@ -363,6 +363,9 @@ export declare const EmailPersistedDataSchemas: {
         locale: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>;
     readonly "user.invite": z.ZodObject<{}, z.core.$strict>;
+    readonly "auth.verification": z.ZodObject<{
+        locale: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
 };
 export declare const EmailRenderDataSchemas: {
     readonly "auth.password_reset": z.ZodObject<{
@@ -374,6 +377,10 @@ export declare const EmailRenderDataSchemas: {
         invite_url: z.ZodString;
         expires_at: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
+    readonly "auth.verification": z.ZodObject<{
+        locale: z.ZodNullable<z.ZodString>;
+        verify_url: z.ZodString;
+    }, z.core.$strict>;
     readonly "order.received": z.ZodObject<{
         order_id: z.ZodString;
         summary: z.ZodOptional<z.ZodObject<{
@@ -601,6 +608,8 @@ export type EmailEphemeralRenderContextMap = {
     }> : Kind extends "user.invite" ? Readonly<{
         invite_url: string;
         expires_at?: string;
+    }> : Kind extends "auth.verification" ? Readonly<{
+        verify_url: string;
     }> : EmptyRenderContext;
 };
 export type EmailRenderDataMap = {

package/dist/email/types/template-data.js

@@ -215,6 +215,11 @@ exports.EmailPersistedDataSchemas = {
     })
         .strict(),
     "user.invite": zod_1.z.object({}).strict(),
+    "auth.verification": zod_1.z
+        .object({
+        locale: NullableLocaleSchema,
+    })
+        .strict(),
 };
 exports.EmailRenderDataSchemas = {
     ...exports.EmailPersistedDataSchemas,
@@ -228,4 +233,7 @@ exports.EmailRenderDataSchemas = {
         /** When the invite expires (ISO 8601), from the current invite. */
         expires_at: zod_1.z.string().datetime().optional(),
     }),
+    "auth.verification": exports.EmailPersistedDataSchemas["auth.verification"].extend({
+        verify_url: zod_1.z.string().url(),
+    }),
 };

package/dist/shop-config/build-food-shop-config.js

@@ -5,6 +5,7 @@ exports.defineFoodShopConfig = defineFoodShopConfig;
 const logger_1 = require("@medusajs/framework/logger");
 const utils_1 = require("@medusajs/framework/utils");
 const config_1 = require("../public/config");
+const customer_verification_snapshot_1 = require("../email/customer-verification-snapshot");
 const sentry_logger_1 = require("../public/sentry-logger");
 const options_1 = require("./options");
 /**
@@ -156,6 +157,9 @@ function buildFoodShopConfig(options, environment = process.env) {
                         orderNotificationEmail: options.orderNotificationEmail,
                         // The e-mail module appends "#token=<token>".
                         passwordResetUrl: () => (0, config_1.shopUrl)(storefrontOrigin, `${storefrontPath}/reset-password`),
+                        // Account confirmation (E-Mail toggle `customer_verification`);
+                        // the e-mail module appends "#token=<token>".
+                        verifyAccountUrl: () => (0, config_1.shopUrl)(storefrontOrigin, `${storefrontPath}/verify-account`),
                         timeZone: options.timeZone,
                     },
                 },
@@ -227,6 +231,17 @@ function buildFoodShopConfig(options, environment = process.env) {
                 authCors: env.AUTH_CORS,
                 jwtSecret: env.JWT_SECRET,
                 cookieSecret: env.COOKIE_SECRET,
+                // Medusa reads this synchronously on every login and keeps the
+                // `authVerificationsPerActor` object (defineConfig and ConfigManager
+                // copy `http` shallowly), so a getter switches e-mail confirmation of
+                // customer accounts at run time. It answers from an in-memory copy of
+                // the E-Mail plugin's `customer_verification` toggle, refreshed at
+                // most every 30 s (see customer-verification-snapshot.ts).
+                authVerificationsPerActor: {
+                    get customer() {
+                        return (0, customer_verification_snapshot_1.customerVerificationActors)();
+                    },
+                },
             },
             // The storefront turns its customer JWT into a Medusa browser session
             // at login, so its browser-side cart and payment calls carry the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hartl-services/medusa-base",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Base plugin for Hartl Services Medusa shops: per-plugin feature toggles with a generic Admin settings page, a Store endpoint for storefronts, enforcement helpers, the complete-cart hook composition, the root redirect, cart-promotion link repair, the built-in E-Mail, Documents and S3 file storage modules, config helpers with the turnkey food-shop preset, and the Sentry logger wrapper and instrumentation.",
   "license": "MIT",
   "files": [
@@ -88,7 +88,7 @@
     "mime-types": "3.0.1",
     "nodemailer": "6.10.1",
     "ulid": "^2.4.0",
-    "@hartl-services/medusa-food-supplements-contracts": "^0.17.0"
+    "@hartl-services/medusa-food-supplements-contracts": "^0.20.0"
   },
   "devDependencies": {
     "@medusajs/admin-sdk": "2.19.0",