@hartl-services/medusa-base 2.6.0 → 2.7.0

package/README.md

@@ -40,8 +40,9 @@ 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").
+- Requires passwords of at least 15 characters for Admin users and, by
+  default, customers; shops can set their own customer rules (see "Password
+  policy").
 - Starts Admin draft orders without a customer order confirmation and marks
   placed 0 € orders without payment as paid (see "Draft orders and 0 €
   orders").
@@ -53,6 +54,9 @@ packing lists) and S3 file storage, and the turnkey `medusa-config.ts` preset
   "E-Mail"), issues invoices, cancellation documents and packing lists as
   private PDFs (module `documents`, see "Dokumente") and stores files in
   S3-compatible storage behind the `/files` gateway (see "Dateispeicher (S3)").
+- Declares which login methods customers may use (module `customer_auth`:
+  e-mail + password and a one-time code by e-mail), provides the `email-otp`
+  auth provider and the code request route (see "Kunden-Login").
 - Builds a food shop's complete `medusa-config.ts` from a few shop facts
   (`@hartl-services/medusa-base/shop-config`, see "Shop-Config-Preset").
 
@@ -131,13 +135,19 @@ 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-auth/login-code` | publishable key | 202 `RequestLoginCodeResponse` (`{ accepted: true }`) for every address, 404 while `email_otp` is off; see "Kunden-Login" |
+| `POST` | `/auth/customer/email-otp` | publishable key | Medusa's own login route with the `email-otp` provider: `{ token }` for a right code, 401 for any other, 400 while `email_otp` is off; see "Kunden-Login" |
+| `GET` | `/store/customer-auth/password-policy` | publishable key | `PasswordPolicyResponse` (`{ password_policy }`, the effective customer rules), 404 while `email_password` is off; see "Password policy" |
 | `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
 `settings` (with `source`, never a secret's value), `configured`, `missing`,
 `settings_version`, `actions`, `admin_page` (the plugin's own page or
-`null`) and `switchable`, so the list is one round trip for the hub.
+`null`) and `switchable`, plus the presentation fields (`icon`, `summary`,
+`disable_hint`, `disable_confirm`, `features_heading`, `features_note`,
+`all_off_warning`, `require_enabled_feature`, `setting_groups`; see
+"Presentation fields for the Admin page"), so the list is one round trip for the hub.
 `POST` takes `{ plugin_key, expected_version, enabled, features }`; `features`
 holds configured values for declared keys, missing keys keep their default and
 an unknown key is 400. An unknown `plugin_key` is 404, a stale
@@ -196,6 +206,44 @@ base's own shop master data): the Admin shows no plugin switch, `enabled` is
 always `true` whatever is stored, and `POST /admin/plugin-features` with
 `enabled: false` is 400. It cannot be combined with `default_enabled: false`.
 
+### Presentation fields for the Admin page
+
+All optional; the Admin response always carries them (`null`, `[]` or
+`"full"` when not declared). Texts are non-empty trimmed strings;
+`definePluginFeatures` throws at import time otherwise.
+
+- `icon`: name from `PLUGIN_ICON_NAMES` (exported by the base; every name is a
+  `@medusajs/icons` component) for the hub card and the page header. The Admin
+  falls back to a default icon for `null`.
+- `summary`: one short sentence, hub card text and page subtitle (the Admin
+  falls back to `description`).
+- `disable_hint`: line under the "Plugin eingeschaltet" switch, e.g. "Aus:
+  keine UID-Nummer mehr im Warenkorb."; `disable_confirm`: body of the
+  confirmation shown before the plugin is switched off. Both only for
+  switchable plugins.
+- `features_heading` (default "Funktionen"), `features_note` (right-aligned note
+  in the features card header) and `all_off_warning` (shown while every
+  top-level feature is off; needs at least one feature).
+- `require_enabled_feature: true`: at least one top-level feature (without
+  `parent_key`) must stay enabled. Needs at least one top-level feature with
+  `default_enabled: true`. The update route answers `400` (`INVALID_DATA`,
+  "Mindestens eine Funktion muss eingeschaltet bleiben.") and stores nothing
+  when the update switches off the last enabled top-level feature; features not
+  sent count by their default. Only such a reducing update is rejected: an
+  already stored all-off state stays readable and can be left (or re-saved
+  unchanged, e.g. by the plugin switch of a switchable plugin). The Admin locks
+  the switch of the last enabled top-level feature with a hint. The Admin DTO
+  field is `require_enabled_feature: boolean` (`false` when not declared).
+- `setting_groups`: `{ name, description?, note?, requires_feature? }` per
+  settings group. `name` equals the `group` of at least one setting and is
+  unique; `requires_feature` is a declared feature key, the Admin dims the group
+  (still editable) while that feature is not effectively enabled.
+- Per setting: `hint` (short text under the field, shown instead of
+  `description`), `placeholder` (not for `boolean`, `select`, `image`,
+  `color`), `width` (`"full"` default or `"half"`: consecutive half settings
+  share a two-column row; not for `boolean`) and `section` (sub-heading inside
+  the group, shared by consecutive settings with the same value).
+
 ### Gating routes
 
 Put gate entries at the start of the plugin's `routes` array. An entry without
@@ -329,7 +377,7 @@ class DemoModuleService extends MedusaService({ /* models */ }) {
 ```
 
 - Types: `string`, `url` (http/https), `number` (finite, optional inclusive
-  `min`/`max`), `boolean`, `secret`, `select` (`options: [{ value, label }]`,
+  `min`/`max`, optional `integer: true` for whole numbers only), `boolean`, `secret`, `select` (`options: [{ value, label }]`,
   non-empty, unique values; the stored value must be one of them), `image`
   (the http(s) URL of a PNG/JPEG of at most 2 MiB that the Admin uploads
   through Medusa's `/admin/uploads` into the public File Module storage and
@@ -340,7 +388,7 @@ class DemoModuleService extends MedusaService({ /* models */ }) {
   that heading whenever the group changes from one setting to the next. Keys
   follow the feature key format and are unique. A `secret` has no default;
   any other default must match its type, options and bounds. `options` exist
-  only on `select`, `min`/`max` only on `number`. `required` defaults to
+  only on `select`, `min`/`max`/`integer` only on `number`. `required` defaults to
   `false`. `invalidates` (optional) lists secret settings of the same plugin
   that a change of this setting deletes, e.g. `invalidates: ["api_key"]` on
   `api_url` so a stored key is never sent to a new host. `definePluginFeatures`
@@ -372,7 +420,7 @@ class DemoModuleService extends MedusaService({ /* models */ }) {
   are dropped. When a setting with `invalidates` gets a different stored
   value (also when it is cleared), the listed secrets are deleted in the same
   transaction unless the update sets them anew; they appear in
-  `changed_keys`. Unknown keys and values of the wrong type, outside `min`/`max`
+  `changed_keys`. Unknown keys and values of the wrong type, outside `min`/`max`, a fraction for an `integer` number
   or not among a select's options answer 400 naming the key, a stale `expected_version` 409. The response is the full
   `AdminPluginFeaturesResponse`.
 - After a saved update the base emits `PLUGIN_SETTINGS_UPDATED_EVENT`
@@ -548,9 +596,11 @@ only when neither plugin had one.
 ## Admin pages
 
 - `/settings/hartl-services` (sidebar entry "Hartl Services Plugins") is the
-  hub: one card per plugin with status chips, the plugin switch (not for
-  `switchable: false`) and "Öffnen"; non-switchable plugins (Shop-Stammdaten)
-  come first.
+  hub: a banner for the Shop-Stammdaten (icon, summary, "Nicht konfiguriert"
+  while required data is missing, "Bearbeiten"), then one card per plugin with
+  its icon, `summary`, the plugin switch (not for `switchable: false`; switching
+  off asks for confirmation with `disable_confirm`), "Nicht konfiguriert"
+  while required settings are missing and "Öffnen".
 - The Aktionen section shows per action the progress of a running run
   ("läuft seit …", bar, label; the button is disabled) and the outcome of the
   last finished run; a finished run it watched and a second start ("läuft
@@ -559,7 +609,12 @@ only when neither plugin had one.
   otherwise the base's generic page
   `/settings/hartl-services/plugin/<plugin_key>` (Funktionen, Einstellungen,
   Aktionen). The static `plugin` segment keeps it from colliding with
-  plugin-owned routes.
+  plugin-owned routes. The page header shows the plugin's `icon`, label,
+  `summary` (the `description` moves into an info tooltip) and status badges;
+  the breadcrumb is "Hartl Services Plugins › label". Settings are grouped by
+  `setting_groups` (one save button for the page, groups of a feature that is
+  off are dimmed), the plugin switch is the first row of the Funktionen
+  section with `disable_hint` below it.
 - A plugin that needs more than the generic sections (its own forms, lists)
   declares `admin_page: "/settings/hartl-services/<plugin-slug>"` and composes
   that page from the base's components (below). Nested settings routes get no
@@ -574,8 +629,19 @@ build, with types) exports:
 
 | Export | Purpose |
 | --- | --- |
-| `PluginPageShell({ pluginKey, children })` | Back link to the hub, the plugin's label, description and status chips, then `children`; loading, "nicht installiert" and error states instead of `children` |
-| `PluginFeatureSections({ pluginKey })` | Funktionen, Einstellungen, Aktionen exactly as on the generic page |
+| `PluginPageShell({ pluginKey, variant?, children })` | Frame of a plugin page, then `children`; loading, "nicht installiert" and error states instead of `children`. `variant="back-link"` (default): back link to the hub above a title card with label, description and status chips. `variant="header"`: `AdminPageHeader` with the plugin's `icon`, `summary` and status badges, no back link; the route's `handle` carries the breadcrumb (as the generic page does) |
+| `PluginFeatureSections({ pluginKey })` | Warnings (required settings missing, `all_off_warning`), Funktionen, Einstellungen, Aktionen exactly as on the generic page |
+| `pluginBreadcrumb(pluginKey)`, `PluginLabelCrumb({ pluginKey })` | Route-`handle` breadcrumbs: `pluginBreadcrumb` returns "Hartl Services Plugins › plugin label" for a page of another plugin (`export const handle = { breadcrumb: () => pluginBreadcrumb("demo") }`); `PluginLabelCrumb` is the label alone, for pages whose parent crumbs the Admin already adds (same plugin) |
+| `AdminPageHeader({ icon, title, description?, info?, badges?, actions? })` | Title container of a page: large `IconBadge`, `h1`, subtitle, an `InfoTooltip` slot and badges and actions at the end. The breadcrumb belongs in the route `handle` |
+| `AdminSection({ title?, description?, note?, actions?, footer?, children })` | Section `Container` with dividers: optional header row (title, description, note, actions), one row per child (`SwitchRow` or own `px-6 py-5` blocks) and an optional right-aligned footer row (usually the save button) |
+| `SwitchRow({ id, label, info?, description?, hint?, checked, onCheckedChange, disabled?, indent?, trailing? })` | One switch row for an `AdminSection`; `indent` for a child feature, `trailing` for an element after the switch (e.g. "Öffnen") |
+| `BreadcrumbTrail({ items })`, type `BreadcrumbTrailItem` | Several crumbs (`{ label, to? }`) as ONE route-`handle` crumb, for a leaf route whose parents live in another plugin |
+| `InfoTooltip({ label, children })` | Small info button next to a label or heading; the tooltip holds the longer explanation |
+| `PluginIcon({ name })` | The `@medusajs/icons` icon a descriptor's `icon` names (default icon for `null` or an unknown name); for `IconBadge` / `AdminPageHeader` |
+| `FocusModalShell({ open, onOpenChange, title, description, submitLabel, onSubmit, isPending?, submitDisabled?, cancelLabel?, children })` | Full-screen form dialog: cancel and primary button in the header, centered 720 px body for the form sections; closing is blocked while `isPending`. `title` and `description` are for screen readers |
+| `MultiSelectDropdown({ options, value, onChange, id?, placeholder?, disabled? })`, type `MultiSelectOption` | Select for several values: chosen labels as badges in the trigger, one checkbox item per option, the menu stays open while ticking |
+| `FileDropField({ accept, label, text?, disabled?, isLoading?, id?, onFileSelected })` | Dashed drop area for one file: file dialog button plus drag and drop; the caller validates the file (`validateFile`) |
+| `WidgetHeader({ title, info?, actions? })` | Header of a compact side widget (order, inventory item): `h2`, optional `InfoTooltip` and actions on one line, at the top of a `Container className="divide-y p-0"` |
 | `usePluginFeature(pluginKey)` | Query of `GET /admin/plugin-features/:plugin_key` |
 | `pluginFeatureKeys` | Query key factory (`all`, `list()`, `detail(key)`) for invalidation after an own mutation |
 | `usePluginFeatureEnabled(pluginKey, ...featureKeys)` | `{ enabled, isPending, isError }` from the shared list query (30 s stale time); plugin switch and every key must be effective; `enabled` is `false` while loading and on error |
@@ -609,12 +675,19 @@ build, with types) exports:
 import {
   PluginFeatureSections,
   PluginPageShell,
+  pluginBreadcrumb,
 } from "@hartl-services/medusa-base/admin-components"
 
 import { DemoMappingSection } from "../../../../features/demo/DemoMappingSection"
 
+// The Admin adds parent crumbs only for routes of the same plugin, so a page
+// in another plugin names the hub itself.
+export const handle = {
+  breadcrumb: () => pluginBreadcrumb("demo"),
+}
+
 const DemoPage = () => (
-  <PluginPageShell pluginKey="demo">
+  <PluginPageShell pluginKey="demo" variant="header">
     <PluginFeatureSections pluginKey="demo" />
     <DemoMappingSection />
   </PluginPageShell>
@@ -925,29 +998,268 @@ 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.
 
+## Kunden-Login
+
+Module `customer_auth` (plugin key `customer_auth`, label "Kunden-Login")
+decides which login methods customers may use. The plugin cannot be switched
+off; it has two features:
+
+| Key              | Label                    | Default | Meaning |
+| ---------------- | ------------------------ | ------- | ------- |
+| `email_password` | E-Mail + Passwort        | on      | Medusa's `emailpass`: login, registration, password reset |
+| `email_otp`      | Anmeldecode per E-Mail   | off     | login with a six digit code from a mail (provider `email-otp`) |
+
+Existing shops are unchanged (password on, code off). At least one method
+must stay on (`require_enabled_feature`): the update route rejects switching
+off the last one with `400`, and the Admin locks that switch. Only a state
+stored before this rule (both off) can still exist; it stays readable, the
+`all_off_warning` shows in the Admin, and it can be left by switching one
+method on.
+Admin users always log in with e-mail and password. The plugin also holds the customer password rules
+(group "Passwort-Regeln", see "Password policy").
+
+**Enforcement.** The switches are not only hidden in the storefront: the shop
+preset sets `projectConfig.http.authMethodsPerActor` to
+`{ customer: <getter>, user: ["emailpass"] }`, and Medusa answers a method that
+is not allowed with `400` (`NOT_ALLOWED`) on every `/auth/<actor>/<provider>`
+route (login, register, reset, update, callback). So with `email_password` off
+a customer can neither log in, register nor reset a password, and the `user`
+list also keeps Admin users from using `email-otp` (an actor without a list may
+use every registered provider). The getter answers from an in-memory copy of
+the effective switches with the same technique as `authVerificationsPerActor`
+(`createRefreshingSnapshot` in `src/shared/lib`): loaded when the application
+starts (the module's `onApplicationStart`), refreshed every 30 seconds by an
+unref'd timer and in the background when a read finds the copy older than 30
+seconds, kept on `globalThis`. A change in the Admin reaches a running instance
+within about 30 seconds (a storefront that caches `GET /store/plugin-features`
+for a minute follows after that). Before the first successful read and after
+a failed one the copy holds the descriptor defaults (`["emailpass"]`), never
+an empty list: an empty list blocks every customer login. It is empty only
+when both switches really are off. A shop with a hand-written config must set
+`authMethodsPerActor` and the auth module entry itself.
+
+**Code login.** Two calls, no state in the storefront:
+
+1. `POST /store/customer-auth/login-code` with `{ email }` (publishable key).
+   It answers `202 { accepted: true }` at once, whatever happens next, and
+   `404` while `email_otp` is off. The rest runs detached.
+2. `POST /auth/customer/email-otp` with `{ email, code }` (Medusa's login
+   route) returns `{ token }`. A wrong, expired, used or unknown code answers
+   `401` with one message ("Der Code ist falsch oder abgelaufen. Fordere bei
+   Bedarf einen neuen Code an.") that never says which.
+
+A new address gets an actorless token (an auth identity without a customer):
+the storefront creates the customer with `POST /store/customers`
+(`{ email }`), then calls `POST /auth/token/refresh` and uses the refreshed
+token, which carries the customer id. An address with an account lands in that
+account. The address is normalized (trimmed, lowercased) everywhere; the
+customer must be created with exactly that address, any other is rejected
+with `400 invalid_data` by a middleware on `POST /store/customers` for
+tokens issued by `email-otp` (Medusa takes the address from the body
+unchecked, so without this a token for `a@x` could create a customer for
+`victim@x` that the victim's later login would be linked to).
+
+**The code.** Six digits from `crypto.randomInt`, valid for 10 minutes, used
+once, at most 3 guesses per code, at most one code per minute and address and
+at most 10 codes per address in a 24 hour window. It is stored only as a keyed
+hash (`HMAC-SHA256` over address and code) in
+`provider_identity.provider_metadata.login_code` of the address's `email-otp`
+identity (`{ hash, expires_at, attempts, sent_at }`); the issuance counter sits
+next to it as `login_code_budget` (`{ window_start, issued }`). A new code
+resets the guesses of the old one but not the budget, so an address offers at
+most 10 x 3 = 30 guesses per day (and 10 mails), not one per minute; the window
+is fixed from its first code and restarts when it has run out; a successful
+code login deletes the budget. When the cap is hit nothing is sent and a
+warning without the address is logged; the request still answers 202. Every
+transition is one conditional `UPDATE` in the database, so parallel requests
+cannot both pass: storing a new code (together with the spacing and budget
+rules) only succeeds if the last one is older than 55 seconds (the storefront
+starts its 60 second countdown at the 202, a little before `sent_at` is
+written; two parallel first requests send one mail), a guess is counted before
+it is compared, and the correct code is consumed by an `UPDATE ... WHERE hash =
+...` that exactly one parallel login wins. The limit lives in the provider and
+not in a route middleware on purpose: a middleware on
+`POST /auth/customer/email-otp` is bypassed by `GET` (the core route runs the
+same handler with the parsed body) and by other actor paths
+(`/auth/<anything>/email-otp`); the provider rejects any actor type but
+`customer` before it looks at the code. The provider uses the auth module's
+`PG_CONNECTION`. It supports neither register nor update, and the routes
+`register`, `update`, `reset-password` and `callback` below
+`/auth/:actor_type/email-otp` answer `404` (a middleware without `methods` in
+the base, so it runs before Medusa's handlers; `reset-password` would
+otherwise create a reset token for a code identity).
+
+Addresses are printable ASCII only (`RequestLoginCodeSchema` answers `400`
+otherwise): the case-insensitive match in the database (`lower()`) must not
+depend on Unicode case folding, e.g. KELVIN SIGN (U+212A) lowercases to `k`.
+
+**Key.** The HMAC key is derived with HKDF-SHA256 (`node:crypto` `hkdfSync`,
+`info` "email-otp-login-code") from the shop's JWT secret by one shared pure
+function (`hashLoginCode` in `src/customer-auth/domain/login-code.ts`). The
+code request reads the secret from `projectConfig.http.jwtSecret`; the
+`email-otp` provider has it as its `hmacSecret` option. **The two must be the
+same value**: the shop preset sets the option from the same `JWT_SECRET` it
+puts into `http.jwtSecret`. A shop with a hand-written config sets
+`hmacSecret: <value of http.jwtSecret>` on the provider entry in the auth
+module options; a mismatch means every code is rejected. Changing the JWT
+secret invalidates the codes in flight (10 minutes).
+
+**Existing accounts (protection against account takeover).** The code login
+joins an existing customer account only through an `emailpass` identity with
+the same address (letter case ignored, `emailpass` stores the address as
+typed) that has a customer, never through `customer.email` alone, and only
+if password login is **off** in this shop, or if that address was confirmed
+through Medusa's auth verification (the `customer_verification` feature of the
+E-Mail module; `auth_verification.verified_at` of that identity and address),
+and only if the account's customer record (not deleted) has the same address
+(`lower(customer.email)`). Otherwise anyone could register an account with
+somebody else's address and a password of their own, and the owner of the
+address would land in that account the first time they ask for a code. In that
+case no code is sent (and nothing is created). Candidates that must not be
+linked (unconfirmed while password login is on, customer address different)
+are dropped before anything else, so a planted account cannot lock the owner
+out of the real one. If several candidates remain, confirmed ones are
+preferred, then the one whose stored address is exactly the requested
+spelling; if more than one is still left, no code is sent and a warning
+without the address is logged. A customer-less `email-otp` identity (code
+requested, never used, an account registered later) is removed and the code
+login is added to the account's auth identity. Guest customers (no account)
+with the same address are never touched: the new account is a separate
+customer, and earlier guest orders stay with the guest.
+
+**Password identities of unconfirmed addresses.** After every successful code
+login the provider deletes (for good: the unique index on
+`provider_identity (entity_id, provider)` has no `deleted_at` filter, a soft
+delete would block a new registration) the `emailpass` identities of the
+logged-in auth identity whose address is not confirmed, by the same
+confirmation check as the linking rule, and logs that without the address. A
+password somebody may have planted for the address before the shop switched
+to the code login can then never be used, not even if password login is
+switched back on. The real owner of an unconfirmed password account keeps the
+account through the code login; the old password is gone.
+
+**The mail.** Kind `auth.login_code` (see "E-Mail"), sent through the E-Mail
+module with the delivery path of the password reset (two attempts), but
+independent of the E-Mail plugin's `account_mails` feature and of its plugin
+switch: with the code login on, login would otherwise be impossible. The code
+exists only in the render context and the rendered content, never in
+`template_data`, the notification record or a log; failures are logged with
+the error class only, never the address. The template can be edited in the
+Admin; the `login_code` block is required.
+
+**Back to password login ("Passwort vergessen").** A customer who so far only
+used codes has no `emailpass` identity, so Medusa's reset
+(`POST /auth/customer/emailpass/reset-password` with `{ identifier }`, which
+looks the identity up by the exact spelling and mails the address it was given)
+would do nothing. While `email_password` is on, a middleware in front of it
+(no `methods`, decoded and lowercased params like the others) prepares the
+request; whatever goes wrong there, the request goes on unchanged:
+
+1. Exactly one `emailpass` identity with a customer matches the address (letter
+   case ignored): the identifier becomes its stored spelling, so a differently
+   cased input still gets the mail.
+2. Otherwise, if the address has a code login (`email-otp`) whose account
+   carries a customer (not deleted) with that address, the address was proven
+   by a code. `emailpass` identities of the address without a customer (left by
+   a failed registration) are deleted for good first. Then an `emailpass`
+   identity with the normalized address is added to the account, **without any
+   password** (`emailpass` fails closed on a missing password, so nobody can
+   log in with it before the reset sets one), together with a verified auth
+   verification of the address (code provider `email-otp`). That verification
+   is the same confirmation the linking rule uses: `customer_verification`
+   never blocks the restored password login, and the clean-up after a code
+   login does not delete the identity as unconfirmed. The identifier becomes
+   the normalized address and Medusa's flow creates the token; the usual reset
+   mail goes out. A parallel request that creates the identity first wins the
+   unique index and the identity is read again.
+3. Anything else (unknown address, several accounts) changes nothing; Medusa
+   answers 201 as always and sends nothing.
+
+The reset then sets the first password (subject to the password rules), and
+password login works for the same customer. This is also the way back for a
+shop that returns to password-only: customers who only used codes set a
+password via "Passwort vergessen". The reverse protection: registering
+(`POST /auth/customer/emailpass/register`) an address for which any identity
+already belongs to a customer account (letter case ignored, password or code)
+answers `400` with "Zu dieser E-Mail-Adresse gibt es bereits ein Kundenkonto.
+Melde dich an oder setze über „Passwort vergessen?“ ein Passwort." instead of
+leaving a customer-less orphan identity next to the account. That reveals that
+an account exists, which Medusa's own refusal for an existing password account
+does already.
+
+Not covered by the code login: a per-IP limit (the limits are per address),
+changing the address.
+
+Storefront contract: DTOs, schemas and paths come from the Contracts package
+(`types/customer-auth-store`, `schemas/customer-auth`, `paths/customer-auth`);
+read `GET /store/plugin-features/customer_auth` and render only the enabled
+forms.
+
 ## 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.
+Admin invite) and `POST /auth/:actor_type/emailpass/update` (password reset).
+It is registered on `/auth/:actor_type/:auth_provider/:action` without
+`methods` and decides on the decoded, lowercased params, because Express
+matches literal path segments against the raw path: `/auth/customer/email%70ass/register`
+and `/auth/Customer/emailpass/register` reach Medusa's handler too, and
+`Customer` counts as the customer actor here.
+A password that breaks the rules of the actor is answered with
+`400 { type: "invalid_data", message }`; the one German message lists every
+unmet rule, e.g. `Das Passwort erfüllt nicht alle Regeln: mindestens 12
+Zeichen, eine Ziffer.` The check runs before Medusa's reset-token check, so a
+rejected password leaves the single-use reset link valid for a second attempt.
+
+**Admin users** (every actor type except `customer`) always need at least 15
+characters, counted as Unicode code points, and no composition rules. This
+follows NIST SP 800-63B Rev. 4 (the US guideline for digital identity) for a
+password that is the only factor.
+
+**Customers** follow the settings of the "Kunden-Login" plugin (group
+"Passwort-Regeln", Settings > "Hartl Services Plugins"). They apply only while
+`email_password` is on and take effect at once, without a cache:
+
+| Key                           | Label                                | Default | Meaning |
+| ----------------------------- | ------------------------------------ | ------- | ------- |
+| `password_min_length`         | Mindestlänge                         | 15      | 8 to 128 characters, whole numbers only (`integer`); NIST SP 800-63B Rev. 4 recommends at least 15 when the password is the only factor |
+| `password_require_mixed_case` | Groß- und Kleinbuchstaben verlangen  | off     | at least one uppercase and one lowercase letter |
+| `password_require_digit`      | Ziffer verlangen                     | off     | at least one digit |
+| `password_require_symbol`     | Sonderzeichen verlangen              | off     | at least one punctuation mark or symbol (Unicode category P or S; whitespace, combining marks and invisible characters do not count) |
+
+NIST SP 800-63B Rev. 4 advises against composition rules, because they lead to
+predictable passwords such as "Passwort1!"; a longer password protects better.
+The Admin texts say so. A missing or invalid stored value falls back to the
+default of that rule, and if the settings cannot be read at all the default
+policy (15 characters, no composition rules) applies and a warning is logged,
+so a registration is never blocked by a settings outage.
+
+**Route.** `GET /store/customer-auth/password-policy` (publishable key only)
+answers `{ password_policy: { min_length, require_mixed_case, require_digit,
+require_symbol } }`, the effective customer rules, and 404 while
+`email_password` is off. The storefront shows them in its forms and checks
+them with the same functions as the backend. The types, the path
+(`customerAuthStorePaths.get.passwordPolicy`) and the rules
+(`evaluatePasswordPolicy`, `isPasswordAllowed`, `DEFAULT_CUSTOMER_PASSWORD_POLICY`,
+`ADMIN_PASSWORD_POLICY` in `schemas/password-policy`) come from the Contracts
+package.
+
+**Admin passwords and the shared identity.** An `emailpass` identity is shared
+by all actor types: someone invited as an Admin could register through
+`/auth/customer/emailpass/register` with the (weaker) customer rules, log in at
+`/auth/user/emailpass` and accept the invite with that token, which would bind
+the weak password to an Admin. So the Admin login (`POST` and `GET`
+`/auth/user/emailpass`, decoded and lowercased like above) checks the body
+password against the Admin rules and answers the same `400` when the identity
+has no Admin yet (`app_metadata.user_id` unset). The login of an identity that
+already belongs to an Admin is never checked. Remaining limit, deliberately not
+closed: a customer could register through the Admin path with 15 characters and
+no composition rules although the shop asks for more; that only weakens their
+own password.
+
+Login of a customer is not checked, so existing passwords keep working until their next
+reset, whatever the rules are. Accounts created without HTTP (`medusa user`,
+seed scripts calling the Auth module) are not checked either.
 
 ## Cart-promotion link repair
 
@@ -1176,7 +1488,7 @@ feature is switched on again.
 | --------------------- | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
 | (plugin switch)       | E-Mail                 | on      | every route under `/admin/email/*` (mail log, resends, attachments; 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`; route `/admin/draft-orders/:id/order-confirmation` (404) and its draft-order widget | 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             |
+| `account_mails`       | Konto-Mails            | on      | subscribers `password-reset`, `user-invite`, `customer-verification` (the last one only with `customer_verification` on as well); not the login code mail, which depends on neither this feature nor the plugin switch (see "Kunden-Login") | 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-Mails        | on      | subscribers `affiliate-consignment-reminder-due` (reminders to affiliates) and `affiliate-application-submitted` (notification to the shop about a new partner application)                                              | jobs, Admin routes, already created messages             |
 
@@ -1190,11 +1502,13 @@ it) or fails the job run.
 The plugin declares no settings. Its logo and colors come from the
 Shop-Stammdaten (section "Erscheinungsbild").
 
-Admin surfaces of a disabled feature are hidden. The E-Mail settings page
-keeps `PluginFeatureSections` visible (so the plugin can be switched back on)
-and gates the Anhänge card above it, the mail log section below it and the
-Anhänge sub-page on the plugin switch, showing `PluginFeatureDisabledNotice`
-in place of the mail log and the sub-page while it is off.
+Admin surfaces of a disabled feature are hidden. The E-Mail overview page
+shows the plugin switch and the mail feature switches (section "Mails") and
+stays reachable while the plugin is off, so it can be switched back on; its
+rows are dimmed and their switches disabled then. All E-Mail sub-pages
+(group pages, templates, attachments, mail log) are gated on the plugin
+switch and show `PluginFeatureDisabledNotice` while it is off (the backend
+answers `404` for `/admin/email/*` then).
 
 ### Kontobestätigung per E-Mail
 
@@ -1462,8 +1776,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`, `auth.verification`,
-  `affiliate.consignment_report_due`, `affiliate.application_submitted.admin`
-  and `user.invite`.
+  `auth.login_code`, `affiliate.consignment_report_due`,
+  `affiliate.application_submitted.admin` 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
@@ -1621,6 +1935,14 @@ 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 login code (`auth.login_code`) has the subject "Dein Anmeldecode für
+<displayName>", the six digits in large type, "Der Code ist 10 Minuten gültig."
+and a note that the mail can be ignored if it was not requested. The code is
+passed as the ephemeral `code` (and `valid_minutes`) next to the empty
+persisted data and is never stored or logged; the message is ephemeral like
+the reset and confirmation mails. It is not gated by `account_mails` or by the
+plugin switch, see "Kunden-Login".
+
 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
@@ -1798,49 +2120,67 @@ a new UUID only after a new confirmation.
 
 ### Admin UI
 
-The E-Mail module has one Admin page, `/settings/hartl-services/email`
+The E-Mail module has an Admin area under `/settings/hartl-services/email`
 (**Settings → Hartl Services Plugins → E-Mail → Öffnen**; the descriptor's
-`admin_page` points the hub there) instead of a top-level sidebar item. It
-composes the base's `PluginPageShell` and `PluginFeatureSections` from
-`@hartl-services/medusa-base/admin-components` (the toggles above). Above
-them sits the **Anhänge** card (documents and the mails they are assigned to,
-"Bearbeiten" opens the sub-page) and the **Vorlagen** card (the editable
-mails with "Standard"/"angepasst", "Bearbeiten" opens the template editor,
-see "Mail templates"); below them, as the last section, the
-**E-Mail-Protokoll**. The mail
-log provides bounded server pagination, allowlisted status/kind filters, a
-search by the exact resource ID (e.g. `order_…`, `cus_…`, as pasted from
-elsewhere), safe message and attempt status, and an explicitly confirmed
-resend action.
-Recipient, template, and payload data are intentionally absent from the page.
+`admin_page` points the hub there) instead of a top-level sidebar item. The
+overview page shows the plugin summary with an Aktiv/Aus badge and two
+sections: **Mails** (the "Plugin eingeschaltet" row, then one row each for
+Bestell-Mails, Konto-Mails and Affiliate-Mails with its number of templates,
+its switch and "Öffnen" to the group page) and **Verwaltung** (links to
+**Anhänge** and **E-Mail-Protokoll**). Sub-pages, each with a breadcrumb:
+
+- `/email/order`, `/email/account`, `/email/affiliate`: one group page each,
+  listing the group's templates ("Standard"/"angepasst", "im Code
+  überschrieben", "Bearbeiten" opens the template editor, see "Mail
+  templates"). The Konto-Mails page also holds the switch "Kontobestätigung
+  per E-Mail" (`customer_verification`, locked while `account_mails` is off).
+  The login code mail (`auth.login_code`) is edited there too but is not
+  stopped by `account_mails`.
+- `/email/attachments` (table of the documents) and
+  `/email/attachments/:id` (detail page), see below.
+- `/email/log` and `/email/log/:id`: the mail log. The list provides bounded
+  server pagination, allowlisted status/kind filters and a search by the
+  exact resource ID (e.g. `order_…`, `cus_…`, as pasted from elsewhere);
+  filters and page live in the URL search params, and the entry page's back
+  link returns to the same view. The entry page shows the safe message
+  details, the delivery attempts and an explicitly confirmed resend action.
+  Recipient, template, and payload data are intentionally absent.
 
 The draft-order detail page carries the **Bestellbestätigung** widget (zone
 `draft_order.details.side.after`, hidden while `order_mails` is off). Its
-switch "An Kunden senden" starts off and decides whether the customer receives
+switch row "Bestellbestätigung an Kunden senden" (with an info tooltip) starts off and decides whether the customer receives
 the order confirmation when the draft is converted (see "Draft orders and
 0 € orders").
 
-The sub-page `/settings/hartl-services/email/attachments` manages the
-attachment library: "Neuer Anhang" creates a document (name, assigned mails,
-first PDF with its effective date), each document can be renamed and
-reassigned ("Bearbeiten") and gets further versions ("Neue Version"; PDF of
-at most 5 MiB). Versions are listed newest effective first, marked
-"aktuell" or "geplant", and can be downloaded. Every create and upload sends
-a fresh request UUID; downloads use the configured authenticated Admin SDK
-and never expose storage file IDs or URLs in the UI. There is no delete:
-removing every assigned mail lets a document rest.
+The sub-pages under `/settings/hartl-services/email/attachments` manage the
+attachment library. The list is a table (name, assigned mails, current
+version); "Neuer Anhang" opens a full-screen form that creates a document
+(name, assigned mails, first PDF with its effective date). The detail page
+`/attachments/:id` has a **Speichern** button for name and assigned mails
+(no autosave): a save first reloads the attachments and applies only what
+the user changed, so assignments toggled meanwhile in the template editor
+are not overwritten, and the name is sent only when it changed. Below it the
+**Versionen** table ("Neue Version" opens a full-screen form; PDF of at most
+5 MiB) lists the versions newest effective first, marked "aktuell" or
+"geplant", with a download button. Every create and upload sends a fresh
+request UUID; downloads use the configured authenticated Admin SDK and never
+expose storage file IDs or URLs in the UI. There is no delete: removing every
+assigned mail lets a document rest.
 
 ### Mail templates
 
-All twelve mails (`EMAIL_EDITABLE_KINDS`) are block templates an Admin edits
-on the E-Mail page (card **Vorlagen**, grouped into Bestell-, Konto- and
-Affiliate-Mails → editor page `/settings/hartl-services/email/templates/:kind`).
-The editor offers a toolbar, slash commands ("/" lists what the mail
-allows), a drag handle to move top-level blocks, a live preview, a test mail
-and, for the six customer order mails, the attachment checkboxes of the
-mail (`POST /admin/email/attachments/:id/mail-kinds`, one kind at a time;
-the Anhänge page's edit dialog likewise saves the name only when it changed
-and then each changed mail kind on its own).
+All 13 mails (`EMAIL_EDITABLE_KINDS`) are block templates an Admin edits
+from the group pages of the E-Mail area (Bestell-, Konto- and Affiliate-Mails
+→ editor page `/settings/hartl-services/email/templates/:kind`, breadcrumb
+E-Mail › group › template).
+The editor has the subject and, for the six customer order mails, an
+**Anhänge** multi select on top (every tick is saved at once through
+`POST /admin/email/attachments/:id/mail-kinds`, one kind of one document at a
+time; a document being saved is locked), and below it the text editor with a
+toolbar, slash commands ("/" lists what the mail allows) and a drag handle to
+move top-level blocks, next to a live preview; a test mail can be sent from
+the header. The attachment detail page saves the name only when it changed
+and then each changed mail kind on its own.
 
 - **Document:** a subset of the editor's ProseMirror JSON
   (`EmailTemplateDocumentSchema` in Contracts): paragraphs with bold, italic,
@@ -1851,12 +2191,13 @@ and then each changed mail kind on its own).
   `item_list` (items without prices, optional heading), `address`,
   `tracking`, `button` (the mail's action link: target fixed per kind from
   the data or the configuration, label editable; nothing without a URL),
-  `link_fallback` (the plain link, HTML only), `validity` and `message` (the
-  partner application's text). Dynamic blocks render the mail's real data at
+  `link_fallback` (the plain link, HTML only), `validity`, `message` (the
+  partner application's text) and `login_code` (the six digits, large). Dynamic blocks render the mail's real data at
   send time and render nothing without it. Conditions: `invoice_attached`,
   `cancellation_attached`, `more_to_follow`, `return_number`. Password reset,
-  account confirmation and admin invite must contain the `button` block
-  (`required_blocks`); a template without it is rejected.
+  account confirmation and admin invite must contain the `button` block, the
+  login code mail the `login_code` block (`required_blocks`); a template
+  without it is rejected.
 - **Placeholders** (`shop_name`, `order_number`, `customer_name`,
   `return_number`, `refund_amount`, `affiliate_name`, `report_month`,
   `applicant_name`, per kind as in the catalog) are escaped in
@@ -2383,8 +2724,10 @@ not import either the plugin implementation or generated `.medusa` output.
 ### Admin order detail
 
 When Documents is enabled, the Medusa Admin order detail shows a
-**Dokumente** widget. It lists the issued documents for that order and opens a
-private PDF preview. The widget obtains the PDF through the Medusa JS SDK, so
+**Dokumente** widget. It lists the issued documents for that order (kind and
+number, issue date and total) with a regenerate icon button and "Ansehen" per
+row, which opens a private PDF preview; the explanation sits in an info
+tooltip next to the title. The widget obtains the PDF through the Medusa JS SDK, so
 both session and bearer-token Admin authentication work without exposing a
 File-provider URL.
 
@@ -2401,9 +2744,12 @@ different order returns `404` from the download endpoint.
 #### Internal packing lists
 
 The separate **Packlisten** order widget lists every physical fulfillment in
-creation order. A ready entry can be previewed and downloaded as a private PDF;
-missing or failed entries can be generated again through the same idempotent
-workflow used by the automatic subscriber.
+creation order, each with a status badge (Nicht erstellt, Ausstehend, Wird
+erstellt, Bereit, Fehlgeschlagen, Storniert), the stock location and, for a
+failed one, the shortened error (full text in a tooltip). An entry with a
+generated PDF (ready or canceled) can be previewed as a private PDF; missing
+or failed entries can be generated again through the same idempotent workflow
+used by the automatic subscriber.
 
 - `GET /admin/orders/:id/packing-lists`
 - `POST /admin/orders/:id/packing-lists/:fulfillment_id/retry`
@@ -2421,8 +2767,9 @@ queries cannot expose them accidentally.
 
 #### Regenerating an invoice
 
-Once an invoice exists, the widget changes **Rechnung ausstellen** to
-**Rechnung regenerieren**. This action retains the document ID, document number
+The widget offers **Rechnung ausstellen** only while the order has no
+invoice; once one exists, every document row has a regenerate icon button
+(tooltip "Regenerieren"). For an invoice this action retains the document ID, document number
 and original issue date, but replaces its persisted PDF and snapshot with a
 fresh render. A prior artifact that is locked by a committed communication fact
 and its private File are retained permanently. Only an unlocked superseded
@@ -2902,8 +3249,8 @@ helpers above for environment parsing. It is a separate subpath because it
 loads the Sentry logger wrapper and with it `@sentry/node`; `/config` stays
 free of it.
 
-The preset registers the base (with its E-Mail, Documents and `/files` options)
-plus five feature plugins, in this order: `medusa-base`,
+The preset registers the base (with its E-Mail, Documents and `/files`
+options) plus five feature plugins, in this order: `medusa-base`,
 `medusa-tax-compliance`, `medusa-free-shipping`, `medusa-batch-management`,
 `medusa-affiliate`, `medusa-payload-sync`.
 
@@ -3012,4 +3359,6 @@ bus job policy (3 attempts, exponential backoff from 1 s), S3 cache defaults
 automatic payment methods, the 24 h session lifetime, Admin path `/app`,
 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").
+"Kontobestätigung per E-Mail"), `http.authMethodsPerActor` (customers: a getter that follows the `customer_auth` switches; Admin users: `["emailpass"]`) and the auth module entry
+(providers `emailpass` and `email-otp`, the latter with `hmacSecret` = `JWT_SECRET`, the same value as `http.jwtSecret`; see
+"Kunden-Login").