@cosmicdrift/kumiko-bundled-features 0.285.1 → 0.286.0

package/src/auth-mfa/mfa-verify-attempts.ts

@@ -13,78 +13,20 @@
 // This is INDEPENDENT of the AuthRoutesConfig.mfaVerifyRateLimit on the
 // framework route (IP-scoped abuse protection for the endpoint itself) —
 // both are needed, neither substitutes for the other.
+//
+// The counter mechanics (race-free INCR/NX, TTL rules, monotonic-counter
+// semantics) live in shared/lockout-counter.ts — this file only wires the
+// mfa-verify key prefixes onto it.
 
-import type Redis from "ioredis";
+import { createLockoutCounter, type LockoutCounterState } from "../shared";
 
-export type MfaVerifyLockoutState = {
-  readonly failureCount: number;
-  readonly lockedUntil: number | null;
-};
+export type MfaVerifyLockoutState = LockoutCounterState;
 
 const COUNT_KEY_PREFIX = "kumiko:auth:mfa-verify:count:";
 const UNTIL_KEY_PREFIX = "kumiko:auth:mfa-verify:until:";
 
-function countKey(userId: string): string {
-  return `${COUNT_KEY_PREFIX}${userId}`;
-}
-function untilKey(userId: string): string {
-  return `${UNTIL_KEY_PREFIX}${userId}`;
-}
-
-export async function getMfaVerifyLockoutState(
-  redis: Redis,
-  userId: string,
-): Promise<MfaVerifyLockoutState | null> {
-  const [countRaw, untilRaw] = await redis.mget(countKey(userId), untilKey(userId));
-  if (countRaw === null) return null;
-  const failureCount = Number(countRaw);
-  if (!Number.isFinite(failureCount)) return null;
-  const lockedUntil = untilRaw !== null ? Number(untilRaw) : null;
-  return {
-    failureCount,
-    lockedUntil: lockedUntil !== null && Number.isFinite(lockedUntil) ? lockedUntil : null,
-  };
-}
-
-// Race-free: INCR is atomic, NX on the until-key means only the attempt
-// that first crosses the threshold anchors the lock window — see
-// lockout-store.ts's recordFailedAttempt for the identical reasoning.
-export async function recordFailedMfaVerifyAttempt(
-  redis: Redis,
-  userId: string,
-  maxAttempts: number,
-  lockoutMinutes: number,
-): Promise<MfaVerifyLockoutState> {
-  const lockDurationMs = lockoutMinutes * 60 * 1000;
-  const ttlSec = Math.max(lockoutMinutes * 60, 24 * 3600);
-
-  const count = await redis.incr(countKey(userId));
-  if (count === 1) {
-    await redis.expire(countKey(userId), ttlSec);
-  }
-
-  let lockedUntil: number | null = null;
-  if (count >= maxAttempts) {
-    const computedUntil = Date.now() + lockDurationMs;
-    const setOk = await redis.set(
-      untilKey(userId),
-      String(computedUntil),
-      "PX",
-      lockDurationMs,
-      "NX",
-    );
-    if (setOk === "OK") {
-      lockedUntil = computedUntil;
-    } else {
-      const existing = await redis.get(untilKey(userId));
-      lockedUntil = existing !== null ? Number(existing) : null;
-    }
-  }
-
-  return { failureCount: count, lockedUntil };
-}
+const counter = createLockoutCounter(COUNT_KEY_PREFIX, UNTIL_KEY_PREFIX);
 
-// Called on a successful verify. The only path that resets the streak.
-export async function clearMfaVerifyAttempts(redis: Redis, userId: string): Promise<void> {
-  await redis.del(countKey(userId), untilKey(userId));
-}
+export const getMfaVerifyLockoutState = counter.getState;
+export const recordFailedMfaVerifyAttempt = counter.recordFailedAttempt;
+export const clearMfaVerifyAttempts = counter.clearState;

package/src/billing-foundation/__tests__/billing-info-query.test.ts

@@ -0,0 +1,103 @@
+// Unit tests for createBillingInfoQueryConfig — stub ctx/deps instead of a
+// real DB, see subscription-stripe/__tests__/runtime.test.ts for the same
+// stub pattern. Covers the three app-relevant branches: the
+// no-prices-early-return (no billing provider configured), that the
+// tier resolution is passed through unchanged, and the
+// subscription shape validation.
+
+import { describe, expect, mock, test } from "bun:test";
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { createBillingInfoQueryConfig } from "../billing-info-query";
+
+type TestTier = "free" | "starter" | "pro";
+
+function stubCtx(opts: {
+  fetchOne: (...args: unknown[]) => Promise<unknown>;
+  billingLive?: boolean;
+  apiKeySet?: boolean;
+  tenantId?: string;
+}): HandlerContext {
+  return {
+    db: { fetchOne: opts.fetchOne },
+    user: { tenantId: opts.tenantId ?? "tenant-1" },
+    config: async () => opts.billingLive ?? true,
+    secrets: { has: async () => opts.apiKeySet ?? true },
+    // biome-ignore lint/suspicious/noExplicitAny: minimal HandlerContext stub, see runtime.test.ts precedent
+  } as any as HandlerContext; // @cast-boundary test-stub — partial ctx
+}
+
+function buildConfig(overrides: { resolveTier?: () => Promise<TestTier> } = {}) {
+  return createBillingInfoQueryConfig<TestTier>({
+    roles: ["Admin"],
+    resolveTier: overrides.resolveTier ?? (async () => "free"),
+    getBillingPrices: () => ({ starter: "price_starter", pro: "price_pro" }),
+  });
+}
+
+describe("createBillingInfoQueryConfig", () => {
+  test("no billing prices configured → enabled:false, no DB query", async () => {
+    const fetchOne = mock(async () => ({ status: "active", tier: "pro", providerName: "stripe" }));
+    const config = createBillingInfoQueryConfig<TestTier>({
+      roles: ["Admin"],
+      resolveTier: async () => "free",
+      getBillingPrices: () => null,
+    });
+    const ctx = stubCtx({ fetchOne });
+
+    const result = await config.handler({} as never, ctx);
+
+    expect(result).toEqual({ enabled: false, tier: "free", subscription: null, prices: {} });
+    expect(fetchOne).not.toHaveBeenCalled();
+  });
+
+  test("resolveTier's result is passed through unchanged", async () => {
+    const fetchOne = mock(async () => null);
+    const config = buildConfig({ resolveTier: async () => "pro" });
+    const ctx = stubCtx({ fetchOne });
+
+    const result = await config.handler({} as never, ctx);
+
+    expect(result.tier).toBe("pro");
+  });
+
+  test("subscription row with all-string status/tier/providerName is returned", async () => {
+    const fetchOne = mock(async () => ({ status: "active", tier: "pro", providerName: "stripe" }));
+    const config = buildConfig();
+    const ctx = stubCtx({ fetchOne, billingLive: true, apiKeySet: true });
+
+    const result = await config.handler({} as never, ctx);
+
+    expect(result.enabled).toBe(true);
+    expect(result.subscription).toEqual({ status: "active", tier: "pro", providerName: "stripe" });
+  });
+
+  test("subscription row with a non-string field → null (fails the shape check)", async () => {
+    const fetchOne = mock(async () => ({ status: "active", tier: 42, providerName: "stripe" }));
+    const config = buildConfig();
+    const ctx = stubCtx({ fetchOne });
+
+    const result = await config.handler({} as never, ctx);
+
+    expect(result.subscription).toBeNull();
+  });
+
+  test("no subscription row → null", async () => {
+    const fetchOne = mock(async () => null);
+    const config = buildConfig();
+    const ctx = stubCtx({ fetchOne });
+
+    const result = await config.handler({} as never, ctx);
+
+    expect(result.subscription).toBeNull();
+  });
+
+  test("access.roles carries the caller's role list through unchanged", () => {
+    const config = createBillingInfoQueryConfig<TestTier>({
+      roles: ["Admin", "TenantAdmin"],
+      resolveTier: async () => "free",
+      getBillingPrices: () => null,
+    });
+    expect(config.access).toEqual({ roles: ["Admin", "TenantAdmin"] });
+    expect(config.name).toBe("billing-info");
+  });
+});

package/src/billing-foundation/billing-info-query.ts

@@ -0,0 +1,95 @@
+// Generic billing-info query-handler-config factory. Extracted from the
+// near-identical billing-info.query.ts app copies in show-pony and
+// publicstatus (infra#446) — the only per-app variables were the
+// TTier union/resolver, the allowed roles, and how Stripe prices are read
+// off the app's extraContext.
+//
+// Deliberately does NOT call defineQueryHandler itself: apps use different
+// wrappers around it (publicstatus's `@app/define`, which adds
+// `agent: { expose: false }`; show-pony's plain framework
+// `defineQueryHandler`). Calling defineQueryHandler here would bypass
+// whatever an app's own wrapper does. Instead this factory returns just the
+// handler-config object — name/schema/access/handler — and each app spreads
+// it into its own defineQueryHandler call, adding app-specific fields
+// (like `agent`) on top.
+
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { HandlerContext, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { QnTypes, qn, SYSTEM_TENANT_ID, toKebab } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+// kumiko-lint-ignore cross-feature-import SUBSCRIPTION_STRIPE_FEATURE is a plain string const in constants.ts (no imports); the barrel import (../subscription-stripe) would create a module cycle with billing-foundation via feature.ts → verify-webhook.ts, because billing-foundation/index.ts now re-exports billing-info-query.ts.
+import { SUBSCRIPTION_STRIPE_FEATURE } from "../subscription-stripe/constants";
+import { subscriptionAggregateId } from "./aggregate-id";
+import { subscriptionsProjectionTable } from "./projection";
+
+// subscription-stripe addresses its credentials + the live flag as config
+// keys (api-key via backing:"secrets" in the secrets store, billingLive
+// plain). We only READ them here to surface billing readiness on the
+// customer screen — the write-side UI is the feature's auto-derived
+// sysadmin settings screen.
+const stripeFeature = toKebab(SUBSCRIPTION_STRIPE_FEATURE);
+const STRIPE_API_KEY_CONFIG_QN = qn(stripeFeature, QnTypes.config, "api-key");
+const STRIPE_BILLING_LIVE_CONFIG_QN = qn(stripeFeature, QnTypes.config, toKebab("billingLive"));
+
+export type BillingInfo<TTier extends string> = {
+  readonly enabled: boolean;
+  readonly tier: TTier;
+  readonly subscription: {
+    readonly status: string;
+    readonly tier: string;
+    readonly providerName: string;
+  } | null;
+  readonly prices: Readonly<Partial<Record<string, string>>>;
+};
+
+export type BillingInfoQueryDeps<TTier extends string> = {
+  readonly roles: readonly string[];
+  readonly resolveTier: (db: TenantDb, tenantId: TenantId) => Promise<TTier>;
+  // ctx is the same HandlerContext the returned handler receives — app
+  // implementations read app-specific extraContext fields off it (e.g.
+  // publicstatus/show-pony's getBillingPrices(ctx) reads `billingPrices`),
+  // so they type their own ctx param as `unknown` and cast internally.
+  readonly getBillingPrices: (
+    ctx: HandlerContext,
+  ) => Readonly<Partial<Record<string, string>>> | null;
+};
+
+export function createBillingInfoQueryConfig<TTier extends string>(
+  deps: BillingInfoQueryDeps<TTier>,
+) {
+  return {
+    name: "billing-info",
+    schema: z.object({}),
+    access: { roles: deps.roles },
+    async handler(_event: unknown, ctx: HandlerContext): Promise<BillingInfo<TTier>> {
+      const tier = await deps.resolveTier(ctx.db, ctx.user.tenantId);
+      const prices = deps.getBillingPrices(ctx);
+      if (!prices) return { enabled: false, tier, subscription: null, prices: {} };
+
+      const billingLive = ctx.config
+        ? (await ctx.config(STRIPE_BILLING_LIVE_CONFIG_QN)) === true
+        : false;
+      const apiKeySet = ctx.secrets
+        ? await ctx.secrets.has(SYSTEM_TENANT_ID, STRIPE_API_KEY_CONFIG_QN)
+        : false;
+
+      const sub = await ctx.db.fetchOne<{
+        status?: unknown;
+        tier?: unknown;
+        providerName?: unknown;
+      }>(subscriptionsProjectionTable, { id: subscriptionAggregateId(ctx.user.tenantId) });
+      return {
+        enabled: billingLive && apiKeySet,
+        tier,
+        subscription:
+          sub &&
+          typeof sub.status === "string" &&
+          typeof sub.tier === "string" &&
+          typeof sub.providerName === "string"
+            ? { status: sub.status, tier: sub.tier, providerName: sub.providerName }
+            : null,
+        prices,
+      };
+    },
+  };
+}

package/src/billing-foundation/changes.json

@@ -1 +1,8 @@
-[]
+[
+  {
+    "version": "0.286.0",
+    "type": "improvement",
+    "title": "Add createBillingInfoQueryConfig factory for the billing-info query handler",
+    "detail": "Extracted from the near-identical app copies in show-pony and publicstatus. Returns a handler-config object rather than calling defineQueryHandler itself, so apps can pass it through their own wrapper."
+  }
+]

package/src/billing-foundation/index.ts

@@ -1,6 +1,11 @@
 // Public API of the subscription-foundation bundled-feature.
 
 export { paymentAggregateId, subscriptionAggregateId } from "./aggregate-id";
+export {
+  type BillingInfo,
+  type BillingInfoQueryDeps,
+  createBillingInfoQueryConfig,
+} from "./billing-info-query";
 export {
   BILLING_FOUNDATION_FEATURE,
   type BillingEventKind,

package/src/file-provider-s3-env/feature.ts

@@ -10,8 +10,8 @@
 // buckets, admin-seeded). This `"s3-env"` provider reads one credential set
 // from env and serves every tenant from one bucket — the
 // Hetzner-Object-Storage / single-bucket deploy case. Tenant isolation
-// still holds: file keys are tenant-prefixed (export ZIPs:
-// `<tenantId>/exports/<jobId>.zip`) or globally-unique UUIDs (fileRefs).
+// still holds: file keys carry the tenant (export ZIPs:
+// `exports/<tenantId>/<jobId>.zip`) or are globally-unique UUIDs (fileRefs).
 //
 // **Pattern-Vorbild:** mirrors file-provider-inmemory (zero admin seeding,
 // only the file-foundation plugin-point required).

package/src/files-tenant-data/__tests__/hooks.integration.test.ts

@@ -24,6 +24,7 @@ import {
   fileRefEntity,
   fileRefsTable,
   type InMemoryFileProvider,
+  tenantExportPrefix,
 } from "@cosmicdrift/kumiko-framework/files";
 import {
   setupTestStack,
@@ -203,10 +204,15 @@ describe("files-tenant-data :: tenant destroy", () => {
     );
     const derivativeKeyA = `${originalKeyA.replace(/\.jpg$/, "")}.thumb-0123456789abcdef.jpg`;
     const unrelatedKeyA = `${tenantA.tenantId}/some-other-file.bin`;
+    // Export ZIPs live under exports/{tenantId}/, not {tenantId}/ — a
+    // regression here would leave a tenant's decrypted GDPR export bundle
+    // behind after destroy (#3003 review finding).
+    const exportKeyA = `${tenantExportPrefix(tenantA.tenantId)}job-1.zip`;
     const { id: fileRefIdA } = await seedFileRef(tenantA.tenantId, originalKeyA);
     await provider.write(originalKeyA, new Uint8Array([1]));
     await provider.write(derivativeKeyA, new Uint8Array([2]));
     await provider.write(unrelatedKeyA, new Uint8Array([3]));
+    await provider.write(exportKeyA, new Uint8Array([5]));
 
     const originalKeyB = buildStorageKey(
       tenantB.tenantId,
@@ -233,6 +239,9 @@ describe("files-tenant-data :: tenant destroy", () => {
     // Storage wipe (EXT_STORAGE_PROVIDER "files" stage) — every key under the
     // tenant's prefix is gone, including the unrelated non-fileRef-tracked key.
     expect(await provider.list(`${tenantA.tenantId}/`)).toHaveLength(0);
+    // The export prefix is a separate top-level sweep, not covered by
+    // `${tenantId}/` — proves fileRefStorageDestroyHook sweeps it too.
+    expect(await provider.exists(exportKeyA)).toBe(false);
 
     // Tenant B's fileRef row and storage key are completely untouched.
     const rowsB = await selectMany(db, fileRefsTable, { tenantId: tenantB.tenantId });

package/src/files-tenant-data/hooks.ts

@@ -11,12 +11,12 @@
 //     tenant has no "restore from trash" future.
 //   - fileRefStorageDestroyHook ("files" stage, EXT_STORAGE_PROVIDER): wipes
 //     every BINARY (original + derivatives + anything else) under the
-//     tenant's storage prefix. A full `${tenantId}/` prefix sweep, not a
-//     per-row derivative lookup — buildStorageKey always puts tenantId first,
-//     so this needs only the tenantId, stays correct even though the "files"
-//     stage runs after "app-data" already forgot the rows, and can never
-//     cross into another tenant's keys (the provider's own list() prefix
-//     already scopes it).
+//     tenant's storage prefixes. A full prefix sweep per tenantStoragePrefixes()
+//     entry, not a per-row derivative lookup — not every layout puts tenantId
+//     first (see tenantExportPrefix), so this must sweep every known prefix,
+//     stays correct even though the "files" stage runs after "app-data"
+//     already forgot the rows, and can never cross into another tenant's keys
+//     (the provider's own list() prefix already scopes it).
 
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import {
@@ -28,6 +28,7 @@ import {
   assertSafeStorageKey,
   fileRefEntity,
   fileRefsTable,
+  tenantStoragePrefixes,
 } from "@cosmicdrift/kumiko-framework/files";
 
 const crud = createEventStoreExecutor(fileRefsTable, fileRefEntity, { entityName: "fileRef" });
@@ -83,9 +84,11 @@ export const fileRefStorageDestroyHook: StorageProviderDestroyTenantHook = async
   // the "files" stage throws, tenant-lifecycle's retry/abandon handling sees
   // it, and the next sweep tick retries (list+delete are idempotent, so this
   // converges rather than double-deleting or erroring on a missing key).
-  const keys = await provider.list(`${tenantId}/`);
-  for (const key of keys) {
-    assertSafeStorageKey(key);
-    await provider.delete(key);
+  for (const prefix of tenantStoragePrefixes(tenantId)) {
+    const keys = await provider.list(prefix);
+    for (const key of keys) {
+      assertSafeStorageKey(key);
+      await provider.delete(key);
+    }
   }
 };

package/src/shared/index.ts

@@ -16,11 +16,13 @@ export { entitiesOf } from "./entities-of";
 export { isWithinGracePeriod } from "./grace-period";
 export { hasWhereRule } from "./has-where-rule";
 export { isIdentityV3Hash, verifyIdentityV3Hash } from "./identity-v3-hash";
+export { createLockoutCounter, type LockoutCounterState } from "./lockout-counter";
 export { mapWithConcurrency } from "./map-with-concurrency";
 export { joinRowParentIsVisible, parentRowIsVisible } from "./parent-visibility";
 export { hashPassword, verifyDummyPassword, verifyPassword } from "./password-hashing";
 export { sessionField } from "./session-field";
 export { sessionLocaleField } from "./session-locale-field";
 export { sessionTimezoneField } from "./session-timezone-field";
+export { createSingleUseTokenStore } from "./single-use-token-store";
 export type { SystemQueryFn } from "./system-query";
 export { type BurnResult, burnToken, unburnToken } from "./token-burn-store";

package/src/shared/lockout-counter.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, test } from "bun:test";
+import { createLockoutCounter } from "./lockout-counter";
+
+// Production Redis has active lockout/mfa-verify entries under these exact
+// keys — only asserting the generated Redis key strings (not just behavior
+// through a mocked client) catches a prefix typo that would silently make
+// existing entries unreachable. The two prefix pairs below are byte-copies
+// of the ones lockout-store.ts and mfa-verify-attempts.ts wire onto this
+// factory; only integration tests exercised this logic before (which never
+// assert on the raw key string), so this is new coverage.
+// countKey/untilKey are not exported by the factory (only the bound
+// operations are) — verify the key shape indirectly through a fake Redis
+// client that records the keys it's called with.
+function fakeRedis() {
+  const calls: { method: string; args: unknown[] }[] = [];
+  const redis = {
+    mget: async (...args: unknown[]) => {
+      calls.push({ method: "mget", args });
+      return [null, null];
+    },
+    incr: async (...args: unknown[]) => {
+      calls.push({ method: "incr", args });
+      return 1;
+    },
+    expire: async (...args: unknown[]) => {
+      calls.push({ method: "expire", args });
+      return 1;
+    },
+    set: async (...args: unknown[]) => {
+      calls.push({ method: "set", args });
+      return "OK";
+    },
+    get: async (...args: unknown[]) => {
+      calls.push({ method: "get", args });
+      return null;
+    },
+    del: async (...args: unknown[]) => {
+      calls.push({ method: "del", args });
+      return 1;
+    },
+    // biome-ignore lint/suspicious/noExplicitAny: minimal ioredis stand-in for key-string assertions
+  } as any;
+  return { redis, calls };
+}
+
+describe("account-lockout Redis key strings", () => {
+  const counter = createLockoutCounter("kumiko:auth:lockout:count:", "kumiko:auth:lockout:until:");
+
+  test("getState reads the byte-identical count/until keys", async () => {
+    const { redis, calls } = fakeRedis();
+    await counter.getState(redis, "u1");
+    expect(calls[0]).toEqual({
+      method: "mget",
+      args: ["kumiko:auth:lockout:count:u1", "kumiko:auth:lockout:until:u1"],
+    });
+  });
+
+  test("clearState deletes the byte-identical count/until keys", async () => {
+    const { redis, calls } = fakeRedis();
+    await counter.clearState(redis, "u1");
+    expect(calls[0]).toEqual({
+      method: "del",
+      args: ["kumiko:auth:lockout:count:u1", "kumiko:auth:lockout:until:u1"],
+    });
+  });
+});
+
+describe("mfa-verify Redis key strings", () => {
+  const counter = createLockoutCounter(
+    "kumiko:auth:mfa-verify:count:",
+    "kumiko:auth:mfa-verify:until:",
+  );
+
+  test("getState reads the byte-identical count/until keys", async () => {
+    const { redis, calls } = fakeRedis();
+    await counter.getState(redis, "u1");
+    expect(calls[0]).toEqual({
+      method: "mget",
+      args: ["kumiko:auth:mfa-verify:count:u1", "kumiko:auth:mfa-verify:until:u1"],
+    });
+  });
+
+  test("clearState deletes the byte-identical count/until keys", async () => {
+    const { redis, calls } = fakeRedis();
+    await counter.clearState(redis, "u1");
+    expect(calls[0]).toEqual({
+      method: "del",
+      args: ["kumiko:auth:mfa-verify:count:u1", "kumiko:auth:mfa-verify:until:u1"],
+    });
+  });
+});

package/src/shared/lockout-counter.ts

@@ -0,0 +1,108 @@
+// Generic Redis-backed failed-attempt counter with auto-expiring lockout.
+// Extracted from auth-email-password/lockout-store.ts and
+// auth-mfa/mfa-verify-attempts.ts (infra#446) — both were byte-identical
+// INCR/NX logic, differing only in their Redis key prefixes.
+
+import type Redis from "ioredis";
+
+export type LockoutCounterState = {
+  readonly failureCount: number;
+  // Epoch milliseconds when the account/attempt auto-unlocks. null while the
+  // counter is still below threshold.
+  readonly lockedUntil: number | null;
+};
+
+// Two keys per subject so each can carry its own TTL:
+//   - count-key: 24h, carries the streak. Monotonic — once threshold is
+//     crossed it STAYS crossed until the caller explicitly clears it.
+//   - until-key: exactly the lockout duration, auto-expires when the lock
+//     ends (Redis TTL replaces a "timer" that would otherwise need a job).
+//
+// Consequence of the monotonic counter: once a subject has been locked, the
+// NEXT failure after the lock expires re-locks immediately — the INCR still
+// returns a value ≥ threshold, so the SET NX re-arms the lock. Clearing the
+// streak is the caller's responsibility (e.g. a successful login, or a
+// dedicated unlock flow) — intentional: brute-force resistance favours
+// strictness over UX for anonymous attempts.
+export function createLockoutCounter(countKeyPrefix: string, untilKeyPrefix: string) {
+  function countKey(subjectId: string): string {
+    return `${countKeyPrefix}${subjectId}`;
+  }
+  function untilKey(subjectId: string): string {
+    return `${untilKeyPrefix}${subjectId}`;
+  }
+
+  async function getState(redis: Redis, subjectId: string): Promise<LockoutCounterState | null> {
+    const [countRaw, untilRaw] = await redis.mget(countKey(subjectId), untilKey(subjectId));
+    if (countRaw === null) return null;
+    const failureCount = Number(countRaw);
+    if (!Number.isFinite(failureCount)) return null;
+    const lockedUntil = untilRaw !== null ? Number(untilRaw) : null;
+    return {
+      failureCount,
+      lockedUntil: lockedUntil !== null && Number.isFinite(lockedUntil) ? lockedUntil : null,
+    };
+  }
+
+  // Race-free: INCR is atomic at the Redis level, so N concurrent failed
+  // attempts produce exactly N increments — no GET-SET window to lose an
+  // increment through. The NX on the until-key likewise guarantees only one
+  // attempt out of a concurrent batch sets the lock timestamp; subsequent
+  // concurrent attempts find the key already set and leave it alone, so the
+  // lock window stays anchored to the first-to-cross, not the last.
+  async function recordFailedAttempt(
+    redis: Redis,
+    subjectId: string,
+    maxFailedAttempts: number,
+    lockoutDurationMinutes: number,
+  ): Promise<LockoutCounterState> {
+    const lockDurationMs = lockoutDurationMinutes * 60 * 1000;
+    // TTL on the count-key: 24h covers "I fat-fingered yesterday". The
+    // lockout duration is on the until-key; the count-key outlives it so an
+    // expired lock leaves a counter ≥ threshold — that's what makes the next
+    // miss immediately re-lock (strict-semantic; see the type-comment above).
+    const ttlSec = Math.max(lockoutDurationMinutes * 60, 24 * 3600);
+
+    const count = await redis.incr(countKey(subjectId));
+    if (count === 1) {
+      // First failure → set the TTL. INCR doesn't set one; a counter without
+      // TTL would leak forever for subjects that never return.
+      await redis.expire(countKey(subjectId), ttlSec);
+    }
+
+    let lockedUntil: number | null = null;
+    if (count >= maxFailedAttempts) {
+      const computedUntil = Date.now() + lockDurationMs;
+      // NX: only set if no lock is currently armed. A second concurrent attempt
+      // arriving after the first crossed the threshold must NOT reset the
+      // timer — the lock window should align with the attempt that crossed,
+      // not the one that happened a millisecond later.
+      const setOk = await redis.set(
+        untilKey(subjectId),
+        String(computedUntil),
+        "PX",
+        lockDurationMs,
+        "NX",
+      );
+      if (setOk === "OK") {
+        lockedUntil = computedUntil;
+      } else {
+        // Another concurrent attempt already locked — read the authoritative
+        // timestamp so the returned state matches what a follow-up
+        // getState would see.
+        const existing = await redis.get(untilKey(subjectId));
+        lockedUntil = existing !== null ? Number(existing) : null;
+      }
+    }
+
+    return { failureCount: count, lockedUntil };
+  }
+
+  // Idempotent — deleting missing keys is a no-op, so a replayed clear just
+  // re-clears harmlessly.
+  async function clearState(redis: Redis, subjectId: string): Promise<void> {
+    await redis.del(countKey(subjectId), untilKey(subjectId));
+  }
+
+  return { getState, recordFailedAttempt, clearState };
+}