@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

package/src/auth-email-password/handlers/login.write.ts

@@ -1,12 +1,15 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import {
+  buildSessionRoles,
   createSystemUser,
   defineWriteHandler,
   type SessionUser,
-  stripForbiddenMembershipRoles,
   type TenantId,
+  type WriteResult,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import { z } from "zod";
+import { verifyDummyPassword, verifyPassword } from "../../shared";
 import { USER_STATUS, UserQueries } from "../../user";
 import { parseAuthUserRow } from "../auth-user-row";
 import {
@@ -21,7 +24,6 @@ import {
   noMembership,
 } from "../errors";
 import { clearLockoutState, getLockoutState, recordFailedAttempt } from "../lockout-store";
-import { verifyPassword } from "../password-hashing";
 
 export type LoginHandlerOptions = {
   // When true, a valid (email + password) login fails with email_not_verified
@@ -40,10 +42,36 @@ export type LoginHandlerOptions = {
     readonly maxFailedAttempts?: number;
     readonly lockoutDurationMinutes?: number;
   };
+  // Optional second-factor gate. auth-mfa (if mounted) wires this in at
+  // app-composition time. Deliberately generic here — auth-email-password
+  // must not import auth-mfa's config, only this shape. Called AFTER a
+  // successful password verification (never before — the point is to add
+  // a second factor to a real credential match, not to gate on identity
+  // alone).
+  readonly mfaStatusChecker?: (
+    ctx: HandlerContext,
+    userId: string,
+    tenantId: TenantId,
+    // Merged global+tenant roles, computed by this handler BEFORE the
+    // gate runs — needed for policy values like "admins" that key off role.
+    roles: readonly string[],
+  ) => Promise<
+    | { readonly required: false }
+    | { readonly required: true; readonly challengeToken: string }
+    | { readonly setupRequired: true; readonly preauthSetupToken: string }
+  >;
 };
 
 const SYSTEM_USER_ID = "00000000-0000-4000-8000-000000000000";
 
+// Two possible success shapes: a straight login mints a session; a login
+// gated by MFA hands back a challenge instead — auth-routes.ts branches on
+// `kind` to decide whether to mint a JWT now or wait for /auth/mfa/verify.
+type LoginResult =
+  | { readonly kind: "auth-session"; readonly session: SessionUser }
+  | { readonly kind: "mfa-challenge"; readonly challengeToken: string }
+  | { readonly kind: "mfa-setup-required"; readonly preauthSetupToken: string };
+
 // Login — unauthenticated entry point. The route is wired public (no JWT
 // middleware), synthesising a guest SessionUser for the handler's access
 // check. Everything inside the handler goes through ctx.queryAs(system, ...)
@@ -62,7 +90,7 @@ export function createLoginHandler(opts: LoginHandlerOptions = {}) {
       password: z.string().min(1),
     }),
     access: { roles: ["all"] },
-    handler: async (event, ctx) => {
+    handler: async (event, ctx): Promise<WriteResult<LoginResult>> => {
       const systemUser = createSystemUser(SYSTEM_USER_ID);
 
       const found = parseAuthUserRow(
@@ -74,6 +102,9 @@ export function createLoginHandler(opts: LoginHandlerOptions = {}) {
       // Uniform response on any credential mismatch (no user, wrong password,
       // soft-deleted user) — prevents email enumeration.
       if (!found?.passwordHash || found.isDeleted) {
+        // Burn the same argon2 verify cost as the hit path so response
+        // latency doesn't reveal whether the email is registered (#774).
+        await verifyDummyPassword(event.payload.password);
         return invalidCredentials();
       }
 
@@ -82,6 +113,14 @@ export function createLoginHandler(opts: LoginHandlerOptions = {}) {
       // for a timing-oracle on the bcrypt verify). If Redis isn't wired,
       // lockout is silently skipped — login still works, brute-force
       // protection just degrades to the IP-rate-limiter at the edge.
+      //
+      // Deliberately fail-open here, unlike auth-mfa's enable-confirm-preauth
+      // (which fails closed without Redis): the secret guarded by THIS gate
+      // is a full password, not a 6-digit code — locking out every login
+      // app-wide because Redis is briefly unavailable is a self-inflicted
+      // outage across every tenant, for a backstop that the IP-rate-limiter
+      // still partially covers. auth-mfa's blast radius is one user's MFA
+      // enrollment, not global login availability — different tradeoff.
       if (ctx.redis) {
         const state = await getLockoutState(ctx.redis, found.id);
         if (state?.lockedUntil !== null && state?.lockedUntil !== undefined) {
@@ -107,6 +146,17 @@ export function createLoginHandler(opts: LoginHandlerOptions = {}) {
         return invalidCredentials();
       }
 
+      // Clear the lockout state as soon as the password is proven — the
+      // password itself is the thing this counter guards, and MFA (if
+      // gated below) has its own separate attempt-cap. Doing this before
+      // the MFA gate matters: without it, an MFA user who occasionally
+      // mistypes their password accumulates failures across otherwise-
+      // successful logins and eventually gets password-locked out even
+      // though every login they completed was legitimate.
+      if (ctx.redis) {
+        await clearLockoutState(ctx.redis, found.id);
+      }
+
       // Strict verification gate — runs AFTER password check so an attacker
       // probing "email_not_verified" needs valid credentials first. The
       // remaining enumeration surface is "valid-cred + unverified" → accepted
@@ -152,25 +202,45 @@ export function createLoginHandler(opts: LoginHandlerOptions = {}) {
         return noMembership();
       }
 
-      // Clear the lockout state on success. DEL is idempotent, so no need
-      // to gate on "was there a counter?" — skipping the Redis round-trip
-      // entirely for users who never failed a login would optimise the hot
-      // path, but the call is microseconds and the branch isn't free either.
-      if (ctx.redis) {
-        await clearLockoutState(ctx.redis, found.id);
-      }
-
       // Globale Rollen aus user.roles + tenant-membership-roles mergen.
       // Globale Rollen (SystemAdmin etc.) bleiben so über alle tenants
       // gleich; tenant-spezifische Rollen (Admin, User) kommen aus der
       // membership. Dedupe via Set damit eine Rolle die in beiden Quellen
       // steht nicht doppelt im Session-Roles landet.
+      //
+      // Computed BEFORE the MFA gate (moved up from its original spot below
+      // baseSession) because the gate's "admins" enforcement policy needs
+      // the MERGED set — a SystemAdmin whose admin-ness lives only in
+      // globalRoles would be missed if only chosen.roles were passed.
       const globalRoles = parseRoles(found.roles ?? null);
-      // Strip reserved roles from the membership portion only (globalRoles keeps
-      // SystemAdmin) — read-time backstop against a rebuild-resurrected role.
-      const mergedRoles = Array.from(
-        new Set([...globalRoles, ...stripForbiddenMembershipRoles(chosen.roles)]),
-      );
+      // buildSessionRoles calls stripForbiddenMembershipRoles to strip reserved
+      // only (globalRoles keeps SystemAdmin) — read-time backstop against a
+      // rebuild-resurrected role.
+      const mergedRoles = buildSessionRoles(globalRoles, chosen.roles);
+
+      // Second-factor gate. Runs AFTER password verification (correct
+      // credentials proven) and AFTER tenant resolution (need chosen.tenantId
+      // to scope the MFA-enabled check). Three outcomes: enrolled → mint a
+      // challenge instead of a session (/auth/mfa/verify completes the
+      // login); policy demands MFA but the user never enrolled → block with
+      // mfa-setup-required (no session, no challenge — see auth-mfa's
+      // config.ts for why this deliberately hard-blocks); neither → proceed.
+      if (opts.mfaStatusChecker) {
+        const mfaStatus = await opts.mfaStatusChecker(ctx, found.id, chosen.tenantId, mergedRoles);
+        if ("challengeToken" in mfaStatus) {
+          return {
+            isSuccess: true,
+            data: { kind: "mfa-challenge", challengeToken: mfaStatus.challengeToken },
+          };
+        }
+        if ("setupRequired" in mfaStatus) {
+          return {
+            isSuccess: true,
+            data: { kind: "mfa-setup-required", preauthSetupToken: mfaStatus.preauthSetupToken },
+          };
+        }
+      }
+
       const baseSession: SessionUser = {
         id: found.id,
         tenantId: chosen.tenantId,

package/src/auth-email-password/handlers/logout.write.ts

@@ -1,4 +1,4 @@
-import { access, defineWriteHandler, pipeline } from "@cosmicdrift/kumiko-framework/engine";
+import { access, defineWriteHandler, stepsPipeline } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 
 // Logout — JWT is stateless, so server-side we only return OK. A future
@@ -8,5 +8,7 @@ export const logoutWrite = defineWriteHandler({
   name: "logout",
   schema: z.object({}),
   access: { roles: access.authenticated },
-  perform: pipeline(({ r }) => [r.step.return({ isSuccess: true, data: { kind: "logged-out" } })]),
+  perform: stepsPipeline(({ r }) => [
+    r.step.return({ isSuccess: true, data: { kind: "logged-out" } }),
+  ]),
 });

package/src/auth-email-password/handlers/request-account-unlock.write.ts

@@ -0,0 +1,38 @@
+import { AUTH_UNLOCK_DEFAULT_TTL_MINUTES, AuthErrors } from "../constants";
+import { renderUnlockAccountEmail } from "../email-templates";
+import { signUnlockToken } from "../unlock-token";
+import {
+  createTokenRequestHandler,
+  type TokenRequestData,
+  type TokenRequestOptions,
+} from "./token-request-handler";
+
+const UNLOCK_NOTIFICATION_TYPE = "auth-email-password:account-unlock";
+
+export type RequestAccountUnlockOptions = TokenRequestOptions;
+
+// Public shape re-exported for callers that build custom routes on top of
+// the dispatcher (bypassing the framework's auth-routes).
+export type RequestUnlockData = TokenRequestData<"unlock-requested">;
+
+// @wrapper-known semantic-alias
+export function createRequestAccountUnlockHandler(opts: RequestAccountUnlockOptions) {
+  return createTokenRequestHandler(
+    {
+      handlerName: "request-account-unlock",
+      successKind: "unlock-requested",
+      defaultTtlMinutes: AUTH_UNLOCK_DEFAULT_TTL_MINUTES,
+      sign: signUnlockToken,
+      notConfiguredError: AuthErrors.unlockNotConfigured,
+      notConfiguredI18nKey: "auth.errors.unlockNotConfigured",
+      // No extra skip condition — any existing, non-deleted user can
+      // request an unlock link regardless of whether they're actually
+      // locked right now. Confirming just clears the (possibly already
+      // empty) lockout state — harmless no-op if they weren't locked.
+      extraSilentSkip: () => false,
+      notificationType: UNLOCK_NOTIFICATION_TYPE,
+      renderContent: renderUnlockAccountEmail,
+    },
+    opts,
+  );
+}

package/src/auth-email-password/handlers/reset-password.write.ts

@@ -1,9 +1,10 @@
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
+import { hashPassword } from "../../shared";
 import { AuthErrors } from "../constants";
 import { invalidResetToken } from "../errors";
-import { hashPassword } from "../password-hashing";
+import { passwordSchema } from "../password-policy";
 import { verifyResetToken } from "../reset-token";
 import { runConfirmTokenFlow } from "./confirm-token-flow";
 
@@ -22,7 +23,7 @@ export function createResetPasswordHandler(opts: ResetPasswordOptions) {
     name: "reset-password",
     schema: z.object({
       token: z.string().min(1),
-      newPassword: z.string().min(8).max(200),
+      newPassword: passwordSchema,
     }),
     access: { roles: ["all"] },
     handler: async (event, ctx) => {

package/src/auth-email-password/handlers/self-registration-status.query.ts

@@ -0,0 +1,23 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { AUTH_SELF_REGISTRATION_FEATURE } from "../self-registration-toggle";
+
+// Anonymous-readable status for the (unauthenticated) signup page: lets it
+// hide its own link/form when an operator has flipped self-registration
+// off, instead of collecting an email that signup-request will silently
+// no-op on. Lives in auth-email-password itself (never toggleable) rather
+// than on the auth-self-registration companion feature — the dispatcher's
+// per-feature gate would otherwise make this query unreachable exactly when
+// the toggle is off (same split as managed-pages' branding query vs.
+// css-gate.ts).
+export const selfRegistrationStatusQuery = defineQueryHandler({
+  name: "signup-registration-status",
+  schema: z.object({}),
+  access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  handler: async (_query, ctx) => {
+    // Same fail-open reasoning as signup-request.write.ts (#1468): only
+    // report disabled when the toggle feature is actually composed.
+    const gated = ctx.registry.getFeature(AUTH_SELF_REGISTRATION_FEATURE) !== undefined;
+    return { enabled: gated ? await ctx.hasFeature(AUTH_SELF_REGISTRATION_FEATURE) : true };
+  },
+});

package/src/auth-email-password/handlers/signup-confirm.write.ts

@@ -33,6 +33,7 @@ import { z } from "zod";
 // kumiko-lint-ignore cross-feature-import signup-confirm reads tenants.key for slug-uniqueness check (TOCTOU + DB-unique-index zusammen)
 import { tenantTable } from "../../tenant/schema/tenant";
 import { invalidSignupToken, signupEmailAlreadyRegistered } from "../errors";
+import { passwordSchema } from "../password-policy";
 // kumiko-lint-ignore cross-feature-import provisioning needs cross-feature seeding helpers
 import { INITIAL_SIGNUP_ROLES, provisionSignupAccount } from "../seeding";
 import {
@@ -44,7 +45,7 @@ import {
 
 const SignupConfirmSchema = z.object({
   token: z.string().min(8),
-  password: z.string().min(8).max(200),
+  password: passwordSchema,
 });
 
 // Mirror der login-handler-Shape (kind: "auth-session", session: SessionUser)
@@ -108,16 +109,23 @@ export function createSignupConfirmHandler() {
 
         let provisioned: { readonly userId: string; readonly tenantId: TenantId };
         try {
-          provisioned = await provisionSignupAccount(dbConn, {
-            email,
-            password: event.payload.password,
-            displayName,
-            tenantId,
-            tenantKey,
-            // Tenant-Display-Name als Default = Email. User wechselt das im
-            // Settings-Screen. Konzept "Tenant" leakt nicht in die Signup-UI.
-            tenantName: email,
-          });
+          provisioned = await provisionSignupAccount(
+            dbConn,
+            {
+              email,
+              password: event.payload.password,
+              displayName,
+              tenantId,
+              tenantKey,
+              // Tenant-Display-Name als Default = Email. User wechselt das im
+              // Settings-Screen. Konzept "Tenant" leakt nicht in die Signup-UI.
+              tenantName: email,
+            },
+            // #1463: seedTenant's postSave hooks (tier-engine's auto-default-
+            // tier, an app's auto-default-compliance) must fire on self-signup
+            // exactly like they do on the regular TenantHandlers.create path.
+            { registry: ctx.registry, context: ctx },
+          );
         } catch (err) {
           // Email hat bereits ein Konto — provisionSignupAccount ist create-only
           // (#365): sauberer User-Fehler, KEINE Session für den fremden Account.

package/src/auth-email-password/handlers/signup-request.write.ts

@@ -31,6 +31,7 @@ import { AUTH_SIGNUP_DEFAULT_TTL_MINUTES } from "../constants";
 import type { AuthMailLocale } from "../email-templates";
 import { renderActivationEmail } from "../email-templates";
 import { dispatchMagicLinkMail } from "../magic-link-mail";
+import { AUTH_SELF_REGISTRATION_FEATURE } from "../self-registration-toggle";
 import { getTokenForSignupEmail, normalizeEmail, storeSignupToken } from "../signup-token-store";
 
 const SIGNUP_NOTIFICATION_TYPE = "auth-email-password:signup-activation";
@@ -68,6 +69,27 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
     schema: SignupRequestSchema,
     access: { roles: ["all"] },
     handler: async (event, ctx) => {
+      // Silent no-op when off, matching the route's own always-200
+      // anti-enumeration contract (registerTokenRequestRoute swallows every
+      // handler failure into `{isSuccess:true}` regardless) — no mail goes
+      // out, but the caller can't distinguish "disabled" from "unknown
+      // email" either way. The client-visible signal is the `status` query
+      // on auth-self-registration, which the signup page uses to hide its
+      // own link/form instead of collecting input that silently no-ops.
+      // Fail-open when the companion toggle feature isn't composed at all —
+      // ctx.hasFeature() is fail-closed for *unregistered* names the moment
+      // feature-toggles/tier-engine is wired, which silently kills
+      // self-signup for every existing app that mounts auth-email-password
+      // without also composing createAuthSelfRegistrationToggleFeature()
+      // (#1468). Only gate when the toggle actually exists.
+      const gated = ctx.registry.getFeature(AUTH_SELF_REGISTRATION_FEATURE) !== undefined;
+      if (gated && !(await ctx.hasFeature(AUTH_SELF_REGISTRATION_FEATURE))) {
+        // No email address here — this fires on every no-op request, PII
+        // must not accumulate in logs just for the "was this toggled off"
+        // signal a support ticket needs.
+        ctx.log?.info("signup-request skipped: self-registration disabled");
+        return { isSuccess: true, data: { kind: "no-op" } };
+      }
       if (!ctx.redis) {
         return writeFailure(
           new InternalError({

package/src/auth-email-password/handlers/token-request-handler.ts

@@ -125,7 +125,9 @@ export function createTokenRequestHandler<TName extends string, TSuccessKind ext
           renderContent: spec.renderContent,
         },
         {
-          email: user.email,
+          // Row value is ciphertext with an active KMS; the byte-exact
+          // lookup above guarantees the payload IS the stored plaintext.
+          email: event.payload.email,
           appUrl: opts.appUrl,
           token,
           expiresAt: expiresAt.toString(),
@@ -136,7 +138,7 @@ export function createTokenRequestHandler<TName extends string, TSuccessKind ext
 
       const data: TokenRequestData<TSuccessKind> = {
         kind: spec.successKind,
-        email: user.email,
+        email: event.payload.email,
         token,
         expiresAt: expiresAt.toString(),
       };

package/src/auth-email-password/i18n.ts

@@ -18,6 +18,7 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.login.submit": "Einloggen",
     "auth.login.submitting": "…",
     "auth.login.forgotPassword": "Passwort vergessen?",
+    "auth.login.unlockAccount": "Konto entsperren?",
     "auth.login.resendVerification": "Bestätigungs-Mail erneut senden",
     "auth.login.resendSuccess": "Wir haben dir eine neue Bestätigungs-Mail geschickt.",
     "auth.login.resendRateLimited": "Bitte warte kurz und versuche es erneut.",
@@ -32,9 +33,15 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.errors.rateLimited": "Zu viele Login-Versuche. Bitte kurz warten.",
     "auth.errors.invalidBody": "Ungültige Eingabe.",
     "auth.errors.loginFailed": "Login fehlgeschlagen.",
+    "auth.errors.mfaNotSupported":
+      "Diese App unterstützt keine Zwei-Faktor-Bestätigung. Bitte an den Support wenden.",
+    "auth.errors.mfaSetupRequired":
+      "Zwei-Faktor-Authentifizierung erforderlich. Bitte an den Administrator wenden.",
     "auth.errors.invalidResetToken":
       "Der Link ist ungültig oder abgelaufen. Bitte fordere einen neuen an.",
     "auth.errors.invalidVerificationToken": "Der Bestätigungs-Link ist ungültig oder abgelaufen.",
+    "auth.errors.invalidUnlockToken":
+      "Der Entsperren-Link ist ungültig oder abgelaufen. Bitte fordere einen neuen an.",
     "auth.errors.invalidSignupToken":
       "Der Aktivierungs-Link ist ungültig oder abgelaufen. Bitte fordere einen neuen an.",
     "auth.errors.signupEmailAlreadyRegistered":
@@ -72,6 +79,26 @@ export const defaultTranslations: TranslationsByLocale = {
       "Der Link ist ungültig oder abgelaufen. Bitte fordere eine neue Bestätigungs-Mail an.",
     "auth.verifyEmail.goToLogin": "Zum Login",
     "auth.verifyEmail.missingToken": "Der Bestätigungs-Link enthält keinen Token.",
+    "auth.requestUnlock.title": "Konto entsperren",
+    "auth.requestUnlock.intro":
+      "Gib deine E-Mail-Adresse ein. Falls dein Konto gesperrt ist, schicken wir dir einen Entsperren-Link.",
+    "auth.requestUnlock.email": "E-Mail",
+    "auth.requestUnlock.submit": "Link anfordern",
+    "auth.requestUnlock.submitting": "…",
+    "auth.requestUnlock.successTitle": "Mail gesendet",
+    "auth.requestUnlock.successBody":
+      "Falls die E-Mail in unserem System existiert und gesperrt ist, ist eine Nachricht mit einem Entsperren-Link unterwegs. Bitte schau in deinen Posteingang.",
+    "auth.requestUnlock.backToLogin": "Zurück zum Login",
+    "auth.requestUnlock.rateLimited": "Zu viele Anfragen. Neuer Versuch in {minutes} Minuten.",
+    "auth.unlockAccount.verifying": "Konto wird entsperrt …",
+    "auth.unlockAccount.successTitle": "Konto entsperrt",
+    "auth.unlockAccount.successBody":
+      "Dein Konto ist wieder entsperrt. Du kannst dich jetzt anmelden.",
+    "auth.unlockAccount.errorTitle": "Entsperren fehlgeschlagen",
+    "auth.unlockAccount.errorBody":
+      "Der Link ist ungültig oder abgelaufen. Bitte fordere einen neuen Entsperren-Link an.",
+    "auth.unlockAccount.goToLogin": "Zum Login",
+    "auth.unlockAccount.missingToken": "Der Entsperren-Link enthält keinen Token.",
     "auth.signup.title": "Account erstellen",
     "auth.signup.intro":
       "Gib deine E-Mail-Adresse ein. Wir schicken dir einen Aktivierungs-Link, mit dem du dein Passwort setzt.",
@@ -120,6 +147,7 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.login.submit": "Sign in",
     "auth.login.submitting": "…",
     "auth.login.forgotPassword": "Forgot password?",
+    "auth.login.unlockAccount": "Unlock account?",
     "auth.login.resendVerification": "Send verification email again",
     "auth.login.resendSuccess": "We've sent you a new verification email.",
     "auth.login.resendRateLimited": "Please wait a moment and try again.",
@@ -134,8 +162,14 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.errors.rateLimited": "Too many login attempts. Please wait briefly.",
     "auth.errors.invalidBody": "Invalid input.",
     "auth.errors.loginFailed": "Login failed.",
+    "auth.errors.mfaNotSupported":
+      "This app doesn't support two-factor verification. Please contact support.",
+    "auth.errors.mfaSetupRequired":
+      "Two-factor authentication required. Please contact your administrator.",
     "auth.errors.invalidResetToken": "Link is invalid or expired. Please request a new one.",
     "auth.errors.invalidVerificationToken": "Verification link is invalid or expired.",
+    "auth.errors.invalidUnlockToken":
+      "Unlock link is invalid or expired. Please request a new one.",
     "auth.errors.invalidSignupToken":
       "Activation link is invalid or expired. Please request a new one.",
     "auth.errors.signupEmailAlreadyRegistered":
@@ -172,6 +206,24 @@ export const defaultTranslations: TranslationsByLocale = {
       "Link is invalid or expired. Please request a new verification email.",
     "auth.verifyEmail.goToLogin": "Go to sign in",
     "auth.verifyEmail.missingToken": "Verification link is missing a token.",
+    "auth.requestUnlock.title": "Unlock account",
+    "auth.requestUnlock.intro":
+      "Enter your email address. If your account is locked, we'll send you an unlock link.",
+    "auth.requestUnlock.email": "Email",
+    "auth.requestUnlock.submit": "Request link",
+    "auth.requestUnlock.submitting": "…",
+    "auth.requestUnlock.successTitle": "Email sent",
+    "auth.requestUnlock.successBody":
+      "If that email exists in our system and is locked, a message with an unlock link is on its way. Please check your inbox.",
+    "auth.requestUnlock.backToLogin": "Back to sign in",
+    "auth.requestUnlock.rateLimited": "Too many requests. Try again in {minutes} minutes.",
+    "auth.unlockAccount.verifying": "Unlocking account …",
+    "auth.unlockAccount.successTitle": "Account unlocked",
+    "auth.unlockAccount.successBody": "Your account is unlocked again. You can sign in now.",
+    "auth.unlockAccount.errorTitle": "Unlock failed",
+    "auth.unlockAccount.errorBody": "Link is invalid or expired. Please request a new unlock link.",
+    "auth.unlockAccount.goToLogin": "Go to sign in",
+    "auth.unlockAccount.missingToken": "Unlock link is missing a token.",
     "auth.signup.title": "Create account",
     "auth.signup.intro":
       "Enter your email. We'll send you an activation link to set your password.",

package/src/auth-email-password/index.ts

@@ -1,7 +1,13 @@
 // Convention paths for the auth pages (reset/verify/signup/invite); apps build
 // their magic-link appUrls from these. All mail now goes through delivery.
+
+// Kept as a public re-export (not just internal call sites) — this feature's
+// barrel is where consumers of the published package have always found
+// hashPassword/verifyPassword; removing it is a breaking change that needs
+// its own changeset + deliberate deprecation window, not a silent drop.
+export { hashPassword, verifyPassword } from "../shared/password-hashing";
 export { type AuthPaths, DEFAULT_AUTH_PATHS, makeAuthPaths } from "./auth-paths";
-export { AUTH_EMAIL_PASSWORD_FEATURE, AuthErrors, AuthHandlers } from "./constants";
+export { AUTH_EMAIL_PASSWORD_FEATURE, AuthErrors, AuthHandlers, AuthQueries } from "./constants";
 // Renderers for the auth mails. All four magic-link flows (reset, verify,
 // signup-activation, invite) emit structured AuthMailContent through delivery
 // (ctx.notify).
@@ -16,10 +22,12 @@ export {
   renderActivationEmail,
   renderInviteEmail,
   renderResetPasswordEmail,
+  renderUnlockAccountEmail,
   renderVerifyEmail,
 } from "./email-templates";
 export type {
   AccountLockoutOptions,
+  AccountUnlockOptions,
   AuthEmailPasswordOptions,
   EmailVerificationOptions,
   InviteOptions,
@@ -27,7 +35,10 @@ export type {
   SignupOptions,
 } from "./feature";
 export { authEmailPasswordEnvSchema, createAuthEmailPasswordFeature } from "./feature";
-export { hashPassword, verifyPassword } from "./password-hashing";
+export {
+  AUTH_SELF_REGISTRATION_FEATURE,
+  createAuthSelfRegistrationToggleFeature,
+} from "./self-registration-toggle";
 // Generic HMAC-signed single-purpose token helpers. Re-exported damit
 // app-spezifische out-of-band-Flows (subscriber-confirm, magic-links,
 // invite-tokens) denselben battle-tested signer/verifier nutzen können

package/src/auth-email-password/lockout-store.ts

@@ -31,9 +31,13 @@ export type LockoutState = {
 // Consequence of the monotonic counter: once a user has been locked, the
 // NEXT wrong password after the lock expires re-locks immediately — the
 // INCR still returns a value ≥ threshold, so the SET NX re-arms the lock.
-// A successful login is the only way to reset the streak. Intentional:
-// brute-force resistance favours strictness over UX, and a legitimate user
-// who hit the lock once can just log in correctly to clear it.
+// A successful login is one way to reset the streak; the other is the
+// account-unlock magic-link flow (#1266, see
+// handlers/confirm-account-unlock.write.ts), a deliberate escape hatch for
+// a legitimate user who can't currently produce the right password (e.g.
+// they forgot it too) but can prove mailbox ownership. Intentional:
+// brute-force resistance favours strictness over UX for anonymous login
+// attempts, while the unlock flow keeps the DoS from being permanent.
 const COUNT_KEY_PREFIX = "kumiko:auth:lockout:count:";
 const UNTIL_KEY_PREFIX = "kumiko:auth:lockout:until:";
 
@@ -111,8 +115,9 @@ export async function recordFailedAttempt(
   return { failureCount: count, lockedUntil };
 }
 
-// Called on successful login. Idempotent — deleting missing keys is a no-op.
-// The ONLY path that resets the counter; intentional.
+// Called on successful login, and on a confirmed account-unlock token
+// (#1266). Idempotent — deleting missing keys is a no-op, so a replayed
+// unlock link just re-clears harmlessly.
 export async function clearLockoutState(redis: Redis, userId: string): Promise<void> {
   await redis.del(countKey(userId), untilKey(userId));
 }