@cosmicdrift/kumiko-bundled-features 0.158.2 → 0.160.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.158.2",
+  "version": "0.160.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -48,6 +48,7 @@
     "./subscription-stripe": "./src/subscription-stripe/index.ts",
     "./subscription-mollie": "./src/subscription-mollie/index.ts",
     "./foundation-shared": "./src/foundation-shared/index.ts",
+    "./auth-foundation": "./src/auth-foundation/index.ts",
     "./mail-foundation": "./src/mail-foundation/index.ts",
     "./inbound-mail-foundation": "./src/inbound-mail-foundation/index.ts",
     "./inbound-provider-inmemory": "./src/inbound-provider-inmemory/index.ts",
@@ -116,11 +117,11 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.158.2",
-    "@cosmicdrift/kumiko-framework": "0.158.2",
-    "@cosmicdrift/kumiko-headless": "0.158.2",
-    "@cosmicdrift/kumiko-renderer": "0.158.2",
-    "@cosmicdrift/kumiko-renderer-web": "0.158.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.160.0",
+    "@cosmicdrift/kumiko-framework": "0.160.0",
+    "@cosmicdrift/kumiko-headless": "0.160.0",
+    "@cosmicdrift/kumiko-renderer": "0.160.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.160.0",
     "@mollie/api-client": "^4.5.0",
     "imapflow": "^1.3.3",
     "mailparser": "^3.9.8",

package/src/auth-email-password/__tests__/account-unlock.integration.test.ts

@@ -0,0 +1,283 @@
+// Account-unlock integration tests (#1266) — the self-service escape hatch
+// for the account-lockout monotonic counter: after a lock expires, the next
+// wrong password immediately re-locks (see account-lockout.integration.test.ts
+// "expired lock + wrong password → immediate re-lock"). This flow gives a
+// legitimate user a way out via mailbox-ownership proof instead of being
+// stuck retrying.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
+import { Temporal } from "temporal-polyfill";
+import { createChannelEmailFeature, createInMemoryTransport } from "../../channel-email";
+import { createConfigFeature } from "../../config";
+import { createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { createDeliveryFeature, createDeliveryTestContext } from "../../delivery";
+import { notificationPreferencesTable } from "../../delivery/tables";
+import { createRendererFoundationFeature } from "../../renderer-foundation/feature";
+import { createRendererSimpleFeature, simpleRenderer } from "../../renderer-simple";
+import { hashPassword } from "../../shared";
+import { createTemplateResolverFeature } from "../../template-resolver/feature";
+import { createTenantFeature } from "../../tenant";
+import { tenantMembershipsTable } from "../../tenant/membership-table";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { seedTenantMembership } from "../../tenant/testing";
+import { UserHandlers } from "../../user";
+import { createUserFeature } from "../../user/feature";
+import { userEntity, userTable } from "../../user/schema/user";
+import { AuthErrors, AuthHandlers } from "../constants";
+import { createAuthEmailPasswordFeature } from "../feature";
+import { getLockoutState, type LockoutState } from "../lockout-store";
+import { signUnlockToken } from "../unlock-token";
+
+const emailTransport = createInMemoryTransport();
+
+let stack: TestStack;
+const systemAdmin = TestUsers.systemAdmin;
+const encryptionKey = randomBytes(32).toString("base64");
+const unlockSecret = randomBytes(32).toString("base64");
+const appUnlockUrl = "https://app.example.com/unlock-account";
+
+const MAX_ATTEMPTS = 3;
+const LOCK_MINUTES = 1;
+
+beforeAll(async () => {
+  const encryption = createTestEnvelopeCipher(encryptionKey);
+  const resolver = createConfigResolver({ cipher: encryption });
+
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createUserFeature(),
+      createTenantFeature(),
+      createTemplateResolverFeature(),
+      createRendererFoundationFeature(),
+      createDeliveryFeature(),
+      createRendererSimpleFeature(),
+      createChannelEmailFeature({
+        transport: emailTransport,
+        renderer: simpleRenderer,
+        resolveEmail: async () => "unused@test.local",
+      }),
+      createAuthEmailPasswordFeature({
+        accountLockout: {
+          maxFailedAttempts: MAX_ATTEMPTS,
+          lockoutDurationMinutes: LOCK_MINUTES,
+        },
+        accountUnlock: { hmacSecret: unlockSecret, tokenTtlMinutes: 15, appUrl: appUnlockUrl },
+      }),
+    ],
+    extraContext: (deps) => ({
+      ...createDeliveryTestContext(deps),
+      configResolver: resolver,
+      configEncryption: encryption,
+    }),
+    authConfig: {
+      membershipQuery: "tenant:query:memberships",
+      loginHandler: AuthHandlers.login,
+      loginErrorStatusMap: {
+        [AuthErrors.invalidCredentials]: 401,
+        [AuthErrors.noMembership]: 403,
+        [AuthErrors.accountLocked]: 423,
+      },
+      accountUnlock: {
+        requestHandler: AuthHandlers.requestAccountUnlock,
+        confirmHandler: AuthHandlers.confirmAccountUnlock,
+      },
+    },
+  });
+
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafePushTables(stack.db, {
+    configValuesTable,
+    tenantMembershipsTable,
+    notificationPreferencesTable,
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${userTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+  await stack.redis.flushNamespace();
+  emailTransport.sent.length = 0;
+});
+
+async function seedLoginUser(
+  email: string,
+  password: string,
+): Promise<{ id: string; tenantId: TenantId }> {
+  const hash = await hashPassword(password);
+  const created = await stack.http.writeOk<{ id: string }>(
+    UserHandlers.create,
+    { email, passwordHash: hash, displayName: email.split("@")[0] ?? "user" },
+    systemAdmin,
+  );
+  const tenantId: TenantId = "00000000-0000-4000-8000-000000000001" as TenantId;
+  await seedTenantMembership(stack.db, { userId: created.id, tenantId, roles: ["User"] });
+  return { id: created.id, tenantId };
+}
+
+async function loginAttempt(email: string, password: string): Promise<Response> {
+  return stack.http.raw("POST", "/api/auth/login", { email, password });
+}
+
+async function post(path: string, body: unknown): Promise<Response> {
+  return stack.http.raw("POST", path, body);
+}
+
+async function readLockoutState(userId: string): Promise<LockoutState | null> {
+  return getLockoutState(stack.redis.redis, userId);
+}
+
+async function lockAccount(email: string): Promise<void> {
+  for (let i = 0; i < MAX_ATTEMPTS; i++) {
+    await loginAttempt(email, `wrong-${i}`);
+  }
+}
+
+describe("POST /auth/request-account-unlock", () => {
+  test("known email → 200, delivery sends mail with unlock URL", async () => {
+    await seedLoginUser("alice@example.com", "initial-pw!");
+
+    const res = await post("/api/auth/request-account-unlock", { email: "alice@example.com" });
+
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ isSuccess: true });
+    expect(emailTransport.sent).toHaveLength(1);
+    const sent = emailTransport.sent[0];
+    if (!sent) throw new Error("no email sent");
+    expect(sent.to).toBe("alice@example.com");
+    expect(sent.html).toContain(`${appUnlockUrl}?token=`);
+  });
+
+  test("unknown email → 200 with NO mail sent (enumeration-safe)", async () => {
+    const res = await post("/api/auth/request-account-unlock", { email: "ghost@example.com" });
+
+    expect(res.status).toBe(200);
+    expect(emailTransport.sent).toHaveLength(0);
+  });
+});
+
+describe("POST /auth/confirm-account-unlock", () => {
+  test("valid token on a locked account → clears failureCount AND lockedUntil", async () => {
+    const seed = await seedLoginUser("bob@example.com", "right-pw");
+    await lockAccount("bob@example.com");
+    expect((await readLockoutState(seed.id))?.lockedUntil).not.toBeNull();
+
+    const { token } = signUnlockToken(seed.id, 15, unlockSecret);
+    const res = await post("/api/auth/confirm-account-unlock", { token });
+
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ isSuccess: true });
+    expect(await readLockoutState(seed.id)).toBeNull();
+  });
+
+  // This is the actual bug fix from #1266: the monotonic counter otherwise
+  // re-locks on the very next wrong password once the lock window expires.
+  // Confirming the unlock token must clear the COUNT key, not just the
+  // until key — otherwise the escape hatch doesn't actually escape anything.
+  test("after unlock, a subsequent wrong password does NOT immediately re-lock", async () => {
+    const seed = await seedLoginUser("carol@example.com", "right-pw");
+    await lockAccount("carol@example.com");
+
+    const { token } = signUnlockToken(seed.id, 15, unlockSecret);
+    await post("/api/auth/confirm-account-unlock", { token });
+
+    const res = await loginAttempt("carol@example.com", "still-wrong-once");
+    expect(res.status).toBe(401);
+    const body = await res.json();
+    expect(body.error?.details?.reason).toBe(AuthErrors.invalidCredentials);
+
+    const state = await readLockoutState(seed.id);
+    expect(state?.failureCount).toBe(1);
+    expect(state?.lockedUntil).toBeNull();
+  });
+
+  test("unlocked account can log in again with the correct password", async () => {
+    const seed = await seedLoginUser("dana@example.com", "right-pw");
+    await lockAccount("dana@example.com");
+
+    const { token } = signUnlockToken(seed.id, 15, unlockSecret);
+    await post("/api/auth/confirm-account-unlock", { token });
+
+    const res = await loginAttempt("dana@example.com", "right-pw");
+    expect(res.status).toBe(200);
+  });
+
+  test("confirming on a non-locked account is a harmless no-op", async () => {
+    const seed = await seedLoginUser("erin@example.com", "right-pw");
+
+    const { token } = signUnlockToken(seed.id, 15, unlockSecret);
+    const res = await post("/api/auth/confirm-account-unlock", { token });
+
+    expect(res.status).toBe(200);
+    expect(await readLockoutState(seed.id)).toBeNull();
+  });
+
+  test("replaying the same unlock token twice is harmless (no burn-store)", async () => {
+    const seed = await seedLoginUser("frank@example.com", "right-pw");
+    await lockAccount("frank@example.com");
+
+    const { token } = signUnlockToken(seed.id, 15, unlockSecret);
+    const res1 = await post("/api/auth/confirm-account-unlock", { token });
+    const res2 = await post("/api/auth/confirm-account-unlock", { token });
+
+    expect(res1.status).toBe(200);
+    expect(res2.status).toBe(200);
+  });
+
+  test("tampered token → 422 invalid_unlock_token; lockout state untouched", async () => {
+    const seed = await seedLoginUser("greta@example.com", "right-pw");
+    await lockAccount("greta@example.com");
+    const { token } = signUnlockToken(seed.id, 15, unlockSecret);
+    const tampered = `${token.slice(0, -3)}XXX`;
+
+    const res = await post("/api/auth/confirm-account-unlock", { token: tampered });
+
+    expect(res.status).toBe(422);
+    const body = await res.json();
+    expect(body.error?.details?.reason).toBe(AuthErrors.invalidUnlockToken);
+    expect((await readLockoutState(seed.id))?.lockedUntil).not.toBeNull();
+  });
+
+  test("token signed with a different secret → 422", async () => {
+    const seed = await seedLoginUser("henry@example.com", "right-pw");
+    const { token } = signUnlockToken(seed.id, 15, "wrong-secret-wrong-secret-wrong!!");
+
+    const res = await post("/api/auth/confirm-account-unlock", { token });
+
+    expect(res.status).toBe(422);
+  });
+
+  test("expired token → 422 invalid_unlock_token", async () => {
+    const seed = await seedLoginUser("iris@example.com", "right-pw");
+    const past = Temporal.Now.instant().subtract({ minutes: 30 });
+    const { token } = signUnlockToken(seed.id, 15, unlockSecret, past);
+
+    const res = await post("/api/auth/confirm-account-unlock", { token });
+
+    expect(res.status).toBe(422);
+    const body = await res.json();
+    expect(body.error?.details?.reason).toBe(AuthErrors.invalidUnlockToken);
+  });
+
+  test("malformed body → 400 invalid_body", async () => {
+    const res = await post("/api/auth/confirm-account-unlock", { wrong: "shape" });
+    expect(res.status).toBe(400);
+  });
+});

package/src/auth-email-password/__tests__/auth-user-row.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { parseAuthUserRow } from "../auth-user-row";
+
+describe("parseAuthUserRow", () => {
+  test("returns null for null/undefined", () => {
+    expect(parseAuthUserRow(null)).toBeNull();
+    expect(parseAuthUserRow(undefined)).toBeNull();
+  });
+
+  test("returns null for a non-object value", () => {
+    expect(parseAuthUserRow("nope")).toBeNull();
+    expect(parseAuthUserRow(42)).toBeNull();
+  });
+
+  test("returns null when id is missing or not a string", () => {
+    expect(parseAuthUserRow({})).toBeNull();
+    expect(parseAuthUserRow({ id: 123 })).toBeNull();
+  });
+
+  test("returns the row as-is once id is a string", () => {
+    const row = {
+      id: "u1",
+      email: "a@example.com",
+      version: 3,
+      passwordHash: "hash",
+      status: "active",
+    };
+    expect(parseAuthUserRow(row)).toEqual(row);
+  });
+
+  test("passes through a row with only id set — other fields stay undefined", () => {
+    const result = parseAuthUserRow({ id: "u2" });
+    expect(result?.id).toBe("u2");
+    expect(result?.email).toBeUndefined();
+  });
+});

package/src/auth-email-password/__tests__/auth.integration.test.ts

@@ -236,6 +236,27 @@ describe("scenario 5: change-password success", () => {
   });
 });
 
+describe("scenario 5c: change-password common-password rejection (#1340)", () => {
+  test("common newPassword → 400 (schema rejects breach-list password)", async () => {
+    const seed = await seedLoginUser({ email: "common-cp@example.com", password: "good-old-pw" });
+    const signedIn = createTestUser({ id: seed.id, tenantId: seed.tenantId, roles: ["User"] });
+
+    const error = await stack.http.writeErr(
+      AuthHandlers.changePassword,
+      { oldPassword: "good-old-pw", newPassword: "password1" },
+      signedIn,
+    );
+    expect(error.httpStatus).toBe(400);
+
+    // Old password still works — the rejected change never landed.
+    const loginRes = await stack.http.raw("POST", "/api/auth/login", {
+      email: "common-cp@example.com",
+      password: "good-old-pw",
+    });
+    expect(loginRes.status).toBe(200);
+  });
+});
+
 describe("scenario 5b: change-password when the aggregate stream tenant != session tenant (sysadmin pattern)", () => {
   test("user whose stream lives in a non-session tenant still changes password", async () => {
     // Sysadmin pattern: created via systemAdmin (stream = systemAdmin.tenantId),

package/src/auth-email-password/__tests__/email-verification.integration.test.ts

@@ -286,7 +286,7 @@ describe("POST /auth/verify-email", () => {
     // memberships + recoverable stream", never blanket-opens zero-membership.
     // Build a fully-populated user row with NO event stream: seed a normal
     // user (gets all NOT-NULL columns), capture its row, then re-key it to a
-    // fresh id + email. getAggregateStreamTenant(orphanId) finds no events
+    // fresh id + email. getUnscopedAggregateStreamTenant(orphanId) finds no events
     // (the stream lives under the original id), and no membership is seeded
     // → tenantOrder is empty.
     const donor = await seedUser({ email: "donor@example.com", password: "donor-pw-1234" });

package/src/auth-email-password/__tests__/password-policy.test.ts

@@ -0,0 +1,15 @@
+import { expect, test } from "bun:test";
+import { isCommonPassword, passwordSchema } from "../password-policy";
+
+test("rejects a breach-list password (case-insensitive)", () => {
+  expect(isCommonPassword("Password1")).toBe(true);
+  expect(passwordSchema.safeParse("password1").success).toBe(false);
+});
+
+test("accepts a long unique password", () => {
+  expect(passwordSchema.safeParse("aX9-not-in-any-list-42").success).toBe(true);
+});
+
+test("still enforces min length", () => {
+  expect(passwordSchema.safeParse("tiny").success).toBe(false);
+});

package/src/auth-email-password/__tests__/password-reset.integration.test.ts

@@ -1,5 +1,6 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
+import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { SYSTEM_TENANT_ID, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
@@ -76,6 +77,7 @@ beforeAll(async () => {
       // "user.postSave" that triggers autoRevokeOnPasswordChange whenever
       // the passwordHash delta is present. Integration-test proves the
       // reset-flow's changes.passwordHash triggers the same hook.
+      authFoundationFeature,
       createSessionsFeature({
         autoRevokeOnPasswordChange: async (userId) => {
           autoRevokeCalls.push(userId);
@@ -252,6 +254,18 @@ describe("POST /auth/reset-password", () => {
     expect(res.status).toBe(400);
   });
 
+  test("common newPassword → 400 (schema rejects breach-list password)", async () => {
+    const seed = await seedUser({ email: "frank@example.com", password: "original" });
+    const { token } = signResetToken(seed.id, 15, resetSecret);
+
+    const res = await post("/api/auth/reset-password", {
+      token,
+      newPassword: "password1",
+    });
+
+    expect(res.status).toBe(400);
+  });
+
   test("expired token via the route → 422 invalid_reset_token", async () => {
     const seed = await seedUser({ email: "time@example.com", password: "once-valid-1234" });
     // Sign with now set far in the past so expiry already fired.
@@ -348,7 +362,7 @@ describe("POST /auth/reset-password", () => {
     // never blanket-opens zero-membership.
     // Build a fully-populated user row with NO event stream: seed a normal
     // user (gets all NOT-NULL columns), capture its row, then re-key it to a
-    // fresh id + email. getAggregateStreamTenant(orphanId) finds no events
+    // fresh id + email. getUnscopedAggregateStreamTenant(orphanId) finds no events
     // (the stream lives under the original id), and no membership is seeded
     // → tenantOrder is empty.
     const donor = await seedUser({ email: "donor@example.com", password: "donor-pw-1234" });

package/src/auth-email-password/__tests__/session-strict-mode.integration.test.ts

@@ -1,8 +1,6 @@
-// Tests the `sessionStrictMode` flag on AuthRoutesConfig. When enabled, a
-// JWT that arrives WITHOUT a `jti` is rejected at the middleware — useful
-// after a rolling deploy has been emitting sids longer than the JWT TTL,
-// so legacy stateless tokens are expected to have expired. Default false
-// keeps pre-upgrade tokens working; this suite flips it on and asserts.
+// Pins the default sessionChecker behavior: a JWT that arrives WITHOUT a
+// `jti` is rejected at the middleware. There is no relaxed mode — any app
+// that wires sessionChecker gets this for free.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
@@ -21,12 +19,8 @@ let stack: TestStack;
 const TENANT: TenantId = testTenantId(1);
 const userId = TestUsers.systemAdmin.id;
 
-// Stub checker that always accepts. The strictMode branch runs BEFORE the
-// checker is even consulted (no jti → nothing to check), so the stub never
-// fires in the strict-mode path. It's present to satisfy the framework's
-// "you wired sessionChecker, so we'll run it if we have an sid" contract.
-// Accepts the full AuthSessionChecker signature (sid + expectedUserId)
-// even though it doesn't use the args.
+// Stub checker that always accepts. Accepts the full AuthSessionChecker
+// signature (sid + expectedUserId) even though it doesn't use the args.
 async function stubChecker(_sid: string, _expectedUserId: string): Promise<"live"> {
   return "live";
 }
@@ -42,7 +36,6 @@ beforeAll(async () => {
     authConfig: {
       membershipQuery: "tenant:query:memberships",
       sessionChecker: stubChecker,
-      sessionStrictMode: true,
     },
   });
 });
@@ -51,7 +44,7 @@ afterAll(async () => {
   await stack.cleanup();
 });
 
-describe("sessionStrictMode: sidless JWTs are rejected", () => {
+describe("sessionChecker wired: sidless JWTs are rejected", () => {
   test("JWT without jti → 401 with reason=no_sid", async () => {
     // Hand-signed JWT that carries id + tenantId + roles but NO jti. The
     // standard testing request-helper signs JWTs the same way on user
@@ -93,7 +86,7 @@ describe("sessionStrictMode: sidless JWTs are rejected", () => {
     expect(res.status).not.toBe(401);
     // Narrow the "not 401" to exclude other 4xx middleware errors too.
     // A 403 from access-layer or a 400 from shape-validation wouldn't
-    // come from sessionStrictMode, but either would be a different code
+    // come from the sid gate, but either would be a different code
     // path than the one we're testing — flag them if they surface.
     expect(res.status).not.toBe(403);
     expect(res.status).not.toBe(400);

package/src/auth-email-password/__tests__/signup-flow.integration.test.ts

@@ -320,4 +320,16 @@ describe("POST /api/auth/signup-confirm", () => {
     const loginAttacker = await postLogin(email, attackerPassword);
     expect(loginAttacker.status).not.toBe(200);
   });
+
+  test("common password → 400 (schema rejects breach-list password) (#1340)", async () => {
+    const email = "common-signup@example.com";
+    const token = await requestSignup(email);
+
+    const confirmRes = await postSignupConfirm(token, "password1");
+    expect(confirmRes.status).toBe(400);
+
+    // No user created — the rejected confirm never landed.
+    const userRows = await selectMany(stack.db, userTable, { email });
+    expect(userRows).toHaveLength(0);
+  });
 });

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

@@ -19,6 +19,12 @@ export const AuthHandlers = {
   resetPassword: "auth-email-password:write:reset-password",
   requestEmailVerification: "auth-email-password:write:request-email-verification",
   verifyEmail: "auth-email-password:write:verify-email",
+  // Account-Unlock Magic-Link (fixes the lockout-DoS where the monotonic
+  // failure-counter re-locks immediately after expiry, #1266). Mirrors
+  // reset: request mints an HMAC token + mails it, confirm clears the
+  // Redis lockout state.
+  requestAccountUnlock: "auth-email-password:write:request-account-unlock",
+  confirmAccountUnlock: "auth-email-password:write:confirm-account-unlock",
   // Magic-Link Self-Signup (Pre-Activation-Token-Pattern). request mintet
   // einen opaken Random-Token, speichert ihn bidirektional in Redis und
   // sendet eine Aktivierungs-Mail. confirm löst den Token ein und legt
@@ -59,6 +65,11 @@ export const AuthErrors = {
   invalidVerificationToken: "invalid_verification_token",
   verificationNotConfigured: "email_verification_not_configured",
   emailNotVerified: "email_not_verified",
+  // Account-Unlock: mirrors the reset-token handling — every verify
+  // failure (malformed/bad-signature/expired) collapses to this single
+  // code so a probing client can't distinguish tampered from stale.
+  invalidUnlockToken: "invalid_unlock_token",
+  unlockNotConfigured: "account_unlock_not_configured",
   // Self-Signup: alle confirm-Failures (unbekannter Token, schon
   // konsumiert, abgelaufen) collapsen auf diesen Code — gleicher
   // anti-enumeration-Trade-off wie reset/verify.
@@ -103,6 +114,10 @@ export const AuthErrors = {
 export const AUTH_LOCKOUT_DEFAULT_MAX_FAILED_ATTEMPTS = 5;
 export const AUTH_LOCKOUT_DEFAULT_DURATION_MINUTES = 15;
 
+// Account-unlock token TTL — same as reset (15min): short-lived, the user
+// clicks it right after hitting the lockout screen.
+export const AUTH_UNLOCK_DEFAULT_TTL_MINUTES = 15;
+
 export const AUTH_RESET_DEFAULT_TTL_MINUTES = 15;
 // Verification tokens live longer by default because the user may not be
 // at their computer the moment they sign up — 24h covers "verify after

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

@@ -73,6 +73,14 @@ const STRINGS = {
     inviteExpiry: (when: string) => `Der Link läuft am ${when} ab.`,
     inviteIgnore:
       "Falls du diese Einladung nicht erwartet hast, kannst du diese E-Mail ignorieren.",
+    unlockSubject: (app: string) => `${app} — Konto entsperren`,
+    unlockGreeting: "Hallo,",
+    unlockIntro: (app: string) =>
+      `dein ${app}-Konto wurde nach mehreren fehlgeschlagenen Anmeldeversuchen vorübergehend gesperrt. Klicke auf den folgenden Link, um es sofort zu entsperren:`,
+    unlockButton: "Konto entsperren",
+    unlockExpiry: (when: string) => `Der Link läuft am ${when} ab.`,
+    unlockIgnore:
+      "Falls du diese Sperre nicht ausgelöst hast, kannst du diese E-Mail ignorieren — die Sperre läuft von selbst ab.",
   },
   en: {
     resetSubject: (app: string) => `${app} — Reset your password`,
@@ -105,6 +113,14 @@ const STRINGS = {
     inviteButton: "Accept invitation",
     inviteExpiry: (when: string) => `The link expires on ${when}.`,
     inviteIgnore: "If you weren't expecting this invitation, you can ignore this email.",
+    unlockSubject: (app: string) => `${app} — Unlock your account`,
+    unlockGreeting: "Hi,",
+    unlockIntro: (app: string) =>
+      `your ${app} account was temporarily locked after several failed sign-in attempts. Click the link below to unlock it immediately:`,
+    unlockButton: "Unlock account",
+    unlockExpiry: (when: string) => `The link expires on ${when}.`,
+    unlockIgnore:
+      "If you didn't trigger this lock, you can ignore this email — the lock expires on its own.",
   },
 } as const;
 
@@ -151,6 +167,22 @@ export function renderResetPasswordEmail(args: RenderTokenContentArgs): AuthMail
   });
 }
 
+export function renderUnlockAccountEmail(args: RenderTokenContentArgs): AuthMailContent {
+  const locale = args.locale ?? "en";
+  const appName = args.appName ?? (locale === "de" ? "Konto" : "Account");
+  const t = STRINGS[locale];
+  return tokenMailContent({
+    subject: t.unlockSubject(appName),
+    header: t.unlockButton,
+    greeting: t.unlockGreeting,
+    intro: t.unlockIntro(appName),
+    buttonLabel: t.unlockButton,
+    buttonUrl: args.url,
+    expiry: t.unlockExpiry(formatExpiry(args.expiresAt)),
+    ignore: t.unlockIgnore,
+  });
+}
+
 export function renderVerifyEmail(args: RenderTokenContentArgs): AuthMailContent {
   const locale = args.locale ?? "en";
   const appName = args.appName ?? (locale === "de" ? "Konto" : "Account");

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

@@ -37,6 +37,15 @@ export function invalidResetToken() {
   );
 }
 
+// @wrapper-known error-helper
+export function invalidUnlockToken() {
+  return writeFailure(
+    new UnprocessableError(AuthErrors.invalidUnlockToken, {
+      i18nKey: "auth.errors.invalidUnlockToken",
+    }),
+  );
+}
+
 // @wrapper-known error-helper
 export function invalidVerificationToken() {
   return writeFailure(