@cosmicdrift/kumiko-bundled-features 0.158.2 → 0.160.0

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

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { MIN_HMAC_SECRET_LENGTH } from "./constants";
 import type { AuthMailLocale } from "./email-templates";
 import { changePasswordWrite } from "./handlers/change-password.write";
+import { createConfirmAccountUnlockHandler } from "./handlers/confirm-account-unlock.write";
 import { createInviteAcceptHandler } from "./handlers/invite-accept.write";
 import { createInviteAcceptWithLoginHandler } from "./handlers/invite-accept-with-login.write";
 import {
@@ -12,6 +13,10 @@ import {
 import { createInviteSignupCompleteHandler } from "./handlers/invite-signup-complete.write";
 import { createLoginHandler, type LoginHandlerOptions } from "./handlers/login.write";
 import { logoutWrite } from "./handlers/logout.write";
+import {
+  createRequestAccountUnlockHandler,
+  type RequestAccountUnlockOptions,
+} from "./handlers/request-account-unlock.write";
 import { createRequestEmailVerificationHandler } from "./handlers/request-email-verification.write";
 import { createRequestPasswordResetHandler } from "./handlers/request-password-reset.write";
 import { createResetPasswordHandler } from "./handlers/reset-password.write";
@@ -109,6 +114,15 @@ export type SignupOptions = SignupRequestOptions;
 // 7 Tage (industry standard).
 export type InviteOptions = InviteCreateOptions;
 
+// Account-Unlock Magic-Link (#1266). When set, registers the
+// request-account-unlock + confirm-account-unlock handlers — the
+// self-service escape hatch for the monotonic lockout counter (see
+// lockout-store.ts). Only meaningful paired with `accountLockout`, but
+// wired independently like passwordReset/emailVerification — no implicit
+// auto-enable, so apps without lockout don't get an unasked-for new
+// public endpoint.
+export type AccountUnlockOptions = RequestAccountUnlockOptions;
+
 export type AuthEmailPasswordOptions = {
   // Second-factor gate. auth-mfa (if mounted) wires this in via
   // mfaStatusCheckerFromFeature() at app-composition time — see
@@ -119,6 +133,7 @@ export type AuthEmailPasswordOptions = {
   readonly accountLockout?: AccountLockoutOptions;
   readonly signup?: SignupOptions;
   readonly invite?: InviteOptions;
+  readonly accountUnlock?: AccountUnlockOptions;
 };
 
 // Auth feature — email+password login. Depends on the user feature for
@@ -140,13 +155,18 @@ export function createAuthEmailPasswordFeature(
       `[auth-email-password] emailVerification.hmacSecret must be ≥${MIN_HMAC_SECRET_LENGTH} chars (HMAC-SHA256 token signing)`,
     );
   }
+  if (opts.accountUnlock && opts.accountUnlock.hmacSecret.length < MIN_HMAC_SECRET_LENGTH) {
+    throw new Error(
+      `[auth-email-password] accountUnlock.hmacSecret must be ≥${MIN_HMAC_SECRET_LENGTH} chars (HMAC-SHA256 token signing)`,
+    );
+  }
 
   const strictVerification =
     opts.emailVerification !== undefined && (opts.emailVerification.mode ?? "strict") === "strict";
 
   return defineFeature("auth-email-password", (r) => {
     r.describe(
-      "Provides email+password authentication: the always-on handlers are `login`, `changePassword`, and `logout`; optional flows \u2014 password reset, email verification, magic-link self-signup, and tenant invite \u2014 are registered only when you pass their respective option objects (`passwordReset`, `emailVerification`, `signup`, `invite`) to `createAuthEmailPasswordFeature(opts)`. All four magic-link flows (reset, verification, signup activation, tenant invite) dispatch their mail through the `delivery` feature via `ctx.notify`, so mounting any of them additionally requires `delivery`. Tokens are HMAC-signed (reset/verify) or opaque-random in Redis (signup/invite). Requires the `user` and `tenant` features, and declares `JWT_SECRET` (\u2265 32 chars) in `authEmailPasswordEnvSchema` so a missing secret surfaces at boot validation rather than on the first login attempt.",
+      "Provides email+password authentication: the always-on handlers are `login`, `changePassword`, and `logout`; optional flows — password reset, email verification, magic-link self-signup, tenant invite, and account-unlock — are registered only when you pass their respective option objects (`passwordReset`, `emailVerification`, `signup`, `invite`, `accountUnlock`) to `createAuthEmailPasswordFeature(opts)`. All five magic-link flows dispatch their mail through the `delivery` feature via `ctx.notify`, so mounting any of them additionally requires `delivery`. Tokens are HMAC-signed (reset/verify/unlock) or opaque-random in Redis (signup/invite). `accountUnlock` is the self-service escape hatch for `accountLockout`'s monotonic failure-counter (#1266): confirming the mailed token clears the Redis lockout state without touching the user entity. Requires the `user` and `tenant` features, and declares `JWT_SECRET` (≥ 32 chars) in `authEmailPasswordEnvSchema` so a missing secret surfaces at boot validation rather than on the first login attempt.",
     );
     r.uiHints({
       displayLabel: "Auth \u00b7 Email + Password",
@@ -162,14 +182,21 @@ export function createAuthEmailPasswordFeature(
         },
         { key: "signup", label: "Self-Signup-Flow", type: "boolean", default: false },
         { key: "invite", label: "Tenant-Invite-Flow", type: "boolean", default: false },
+        { key: "accountUnlock", label: "Account-Unlock-Flow", type: "boolean", default: false },
       ],
     });
     r.requires("user");
     r.requires("tenant");
-    // All four magic-link flows (reset/verify/signup/invite) dispatch via
-    // ctx.notify → delivery must be mounted. Fail closed at boot instead of
-    // silently dropping the mail.
-    if (opts.passwordReset || opts.emailVerification || opts.signup || opts.invite) {
+    // All five magic-link flows (reset/verify/signup/invite/unlock) dispatch
+    // via ctx.notify → delivery must be mounted. Fail closed at boot instead
+    // of silently dropping the mail.
+    if (
+      opts.passwordReset ||
+      opts.emailVerification ||
+      opts.signup ||
+      opts.invite ||
+      opts.accountUnlock
+    ) {
       r.requires("delivery");
     }
     r.envSchema(authEmailPasswordEnvSchema);
@@ -208,6 +235,11 @@ export function createAuthEmailPasswordFeature(
       r.writeHandler(createInviteSignupCompleteHandler());
     }
 
+    if (opts.accountUnlock) {
+      r.writeHandler(createRequestAccountUnlockHandler(opts.accountUnlock));
+      r.writeHandler(createConfirmAccountUnlockHandler(opts.accountUnlock));
+    }
+
     return { handlers };
   });
 }

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

@@ -8,6 +8,7 @@ import { z } from "zod";
 import { hashPassword, verifyPassword } from "../../shared";
 import { UserHandlers, UserQueries } from "../../user";
 import { invalidCredentials } from "../errors";
+import { passwordSchema } from "../password-policy";
 
 // Change-password — authenticated. The user supplies their current password
 // (re-auth) and the new one. The new hash is written via ctx.writeAs(system)
@@ -17,7 +18,7 @@ export const changePasswordWrite = defineWriteHandler({
   name: "change-password",
   schema: z.object({
     oldPassword: z.string().min(1),
-    newPassword: z.string().min(8).max(200),
+    newPassword: passwordSchema,
   }),
   access: { roles: access.authenticated },
   handler: async (event, ctx) => {

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

@@ -0,0 +1,59 @@
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  InternalError,
+  UnprocessableError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { AuthErrors } from "../constants";
+import { invalidUnlockToken } from "../errors";
+import { clearLockoutState } from "../lockout-store";
+import { verifyUnlockToken } from "../unlock-token";
+
+export type ConfirmAccountUnlockOptions = {
+  readonly hmacSecret: string;
+};
+
+// Confirm step of the unlock flow. Unlike reset/verify, there's no entity
+// write: the token's HMAC signature already proves it was minted for an
+// existing, non-deleted user (see request-account-unlock.write.ts's
+// findForAuth + extraSilentSkip), so there's no user to (re-)load or
+// validate here. Clearing the Redis lockout state is naturally idempotent
+// (DEL on an already-cleared/missing key is a no-op), so a replayed unlock
+// link within its TTL just re-clears — harmless, unlike reset which sets a
+// password. That's why this skips the single-use burn-store confirm-token-
+// flow.ts needs to protect a state-changing write.
+export function createConfirmAccountUnlockHandler(opts: ConfirmAccountUnlockOptions) {
+  return defineWriteHandler({
+    name: "confirm-account-unlock",
+    schema: z.object({
+      token: z.string().min(1),
+    }),
+    access: { roles: ["all"] },
+    handler: async (event, ctx) => {
+      if (!opts.hmacSecret) {
+        return writeFailure(
+          new UnprocessableError(AuthErrors.unlockNotConfigured, {
+            i18nKey: "auth.errors.unlockNotConfigured",
+          }),
+        );
+      }
+      if (!ctx.redis) {
+        return writeFailure(
+          new InternalError({
+            message: "account-unlock requires ctx.redis to clear lockout state",
+          }),
+        );
+      }
+
+      // All verify failures (malformed / bad_signature / expired) fold into
+      // the same invalid_unlock_token error — a probing caller can't
+      // distinguish tampered from stale from random-string.
+      const verify = verifyUnlockToken(event.payload.token, opts.hmacSecret);
+      if (!verify.ok) return invalidUnlockToken();
+
+      await clearLockoutState(ctx.redis, verify.userId);
+      return { isSuccess: true, data: { kind: "account-unlocked" as const } };
+    },
+  });
+}

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

@@ -108,6 +108,7 @@ export function createInviteAcceptWithLoginHandler() {
         const invitationTenantId = invitation.tenantId;
         const invitationEmail = await decryptStoredPii(
           invitation.email,
+          "email",
           "auth:invite-accept-with-login",
         );
         const invitationRole = invitation.role;

package/src/auth-email-password/handlers/invite-accept.write.ts

@@ -101,7 +101,11 @@ export function createInviteAcceptHandler() {
           return invalidInviteToken();
 
         const invitationTenantId = invitation.tenantId;
-        const invitationEmail = await decryptStoredPii(invitation.email, "auth:invite-accept");
+        const invitationEmail = await decryptStoredPii(
+          invitation.email,
+          "email",
+          "auth:invite-accept",
+        );
         const invitationRole = invitation.role;
         const invitationVersion = invitation.version;
 
@@ -112,7 +116,7 @@ export function createInviteAcceptHandler() {
           id: event.user.id,
         });
         const userEmail = userRow?.email
-          ? await decryptStoredPii(userRow.email, "auth:invite-accept")
+          ? await decryptStoredPii(userRow.email, "email", "auth:invite-accept")
           : undefined;
         if (!userRow || !userEmail || userEmail.toLowerCase() !== invitationEmail) {
           return inviteEmailMismatch();

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

@@ -112,6 +112,7 @@ export function createInviteSignupCompleteHandler() {
         const invitationTenantId = invitation.tenantId;
         const invitationEmail = await decryptStoredPii(
           invitation.email,
+          "email",
           "auth:invite-signup-complete",
         );
         const invitationRole = invitation.role;

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

@@ -4,6 +4,7 @@ import { z } from "zod";
 import { hashPassword } from "../../shared";
 import { AuthErrors } from "../constants";
 import { invalidResetToken } from "../errors";
+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/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)

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.",
@@ -37,6 +38,8 @@ export const defaultTranslations: TranslationsByLocale = {
     "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":
@@ -74,6 +77,25 @@ 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.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.",
@@ -122,6 +144,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.",
@@ -140,6 +163,8 @@ export const defaultTranslations: TranslationsByLocale = {
       "This app doesn't support two-factor verification. Please contact support.",
     "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":
@@ -176,6 +201,23 @@ 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.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

@@ -22,10 +22,12 @@ export {
   renderActivationEmail,
   renderInviteEmail,
   renderResetPasswordEmail,
+  renderUnlockAccountEmail,
   renderVerifyEmail,
 } from "./email-templates";
 export type {
   AccountLockoutOptions,
+  AccountUnlockOptions,
   AuthEmailPasswordOptions,
   EmailVerificationOptions,
   InviteOptions,

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));
 }