@cosmicdrift/kumiko-bundled-features 0.285.2 → 0.287.0

package/src/auth-email-password/signup-token-store.ts

@@ -1,132 +1,69 @@
 // Redis-backed pre-activation token store for magic-link signup.
 //
-// Token material: opaque random 256-bit from crypto.randomBytes (see
-// signup-request.write.ts → generateToken() from framework/api),
-// base64url-encoded to 43 chars. Not designed for human typing — the
-// user clicks the mail link, nobody types the token.
+// Subject is the (normalized) email — the user doesn't exist yet, so
+// there's no userId claim for an HMAC-signed token to bind to. The store
+// mechanics (bidirectional token↔subject mapping, sha256-hashed keys,
+// single-use burn) live in shared/single-use-token-store.ts — this file
+// only wires the signup key prefixes onto it and normalizes the email
+// used as the subject id.
 //
-// Unlike reset/verify tokens (HMAC-signed, statelessly verifiable),
-// signup tokens need a server-side lookup: the user doesn't exist yet,
-// so there's no userId claim for the HMAC to bind to. We map token ↔
-// email bidirectionally in Redis and delete the pair on confirm.
-// Bidirectional because:
-//   - by-token: confirm-handler needs token → email
-//   - by-email: signup-request needs to know whether a token is still
-//     live for this email, so a resend can invalidate it instead of
-//     leaving two valid tokens for the same signup around
-//
-// Every key is derived from sha256(token), never the raw token —
-// Redis key names, MONITOR output, replica traffic, and memory/backup
-// dumps never carry the bearer secret in the clear (#2174). The
-// by-email entry stores the *hash* of the live token, not the token
-// itself, so it can only be used to invalidate (delete the matching
-// forward entry) — never to recover or resend the original token. A
-// resend therefore always mints a fresh token and invalidates the
-// previous one, rather than reusing the same link.
-//
-// No collision with reset/verify tokens: all signup keys carry the
+// No collision with reset/verify/invite tokens: all signup keys carry the
 // `signup:`-prefix.
 
-import { createHash } from "node:crypto";
 import type Redis from "ioredis";
+import { createSingleUseTokenStore } from "../shared";
 
-const TOKEN_KEY_PREFIX = "signup:by-token:";
-const EMAIL_KEY_PREFIX = "signup:by-email:";
-const BURN_KEY_PREFIX = "signup:burn:";
-
-/** Email-Normalisierung — single source für jede Lookup-Schicht (Store
- *  intern UND Caller die im Return-Body / Mail-Send eine konsistente
- *  Form brauchen). Vorher zwei Stellen mit `.toLowerCase()` — eine
- *  Quelle = kein Drift. */
+/** Email normalization — single source for every lookup layer (used
+ *  internally by the store AND by callers that need a consistent form
+ *  in the return body / mail send). Previously two places called
+ *  `.toLowerCase()` — one source means no drift. */
 export function normalizeEmail(email: string): string {
   return email.toLowerCase();
 }
 
-// Same sha256-hex pattern as hashPatToken (personal-access-tokens/hash.ts)
-// and preauthTokenKeyOf (framework/api/auth-routes.ts): the token is
-// high-entropy, so a single fast hash is enough — no brute-force surface
-// that would justify a slow password-hash.
-function hashToken(token: string): string {
-  return createHash("sha256").update(token).digest("hex");
-}
+const store = createSingleUseTokenStore({
+  tokenPrefix: "signup:by-token:",
+  subjectPrefix: "signup:by-email:",
+  burnPrefix: "signup:burn:",
+});
 
-function tokenKey(token: string): string {
-  return `${TOKEN_KEY_PREFIX}${hashToken(token)}`;
-}
-// Builds the forward key from an already-hashed value (e.g. read back from
-// the by-email entry) — does NOT hash again. Keeping this separate from
-// tokenKey() (which hashes a raw token) makes a double-hash mistake visible
-// at the call site instead of silently no-op'ing a delete.
-function forwardKeyForHash(tokenHash: string): string {
-  return `${TOKEN_KEY_PREFIX}${tokenHash}`;
-}
-// @wrapper-known semantic-alias
-function emailKey(email: string): string {
-  return `${EMAIL_KEY_PREFIX}${normalizeEmail(email)}`;
-}
-function burnKey(token: string): string {
-  return `${BURN_KEY_PREFIX}${hashToken(token)}`;
-}
-
-/** Speichert das Pair bidirektional und setzt TTL auf beiden Keys.
- *  Idempotent — re-write derselben Token-Email-Kombi ist OK. The
- *  by-email value is the token's hash, not the token — see file header. */
+/** Stores the pair bidirectionally and sets TTL on both keys.
+ *  Idempotent — re-writing the same token-email pair is fine. */
 export async function storeSignupToken(
   redis: Redis,
   args: { email: string; token: string; ttlSeconds: number },
 ): Promise<void> {
-  await Promise.all([
-    redis.set(tokenKey(args.token), normalizeEmail(args.email), "EX", args.ttlSeconds),
-    redis.set(emailKey(args.email), hashToken(args.token), "EX", args.ttlSeconds),
-  ]);
+  return store.store(redis, {
+    subjectId: normalizeEmail(args.email),
+    token: args.token,
+    ttlSeconds: args.ttlSeconds,
+  });
 }
 
-/** Lookup: Email für einen Token. Null wenn Token nicht (mehr) existiert
- *  (abgelaufen, schon konsumiert, oder ungültig). */
-export async function getEmailForSignupToken(redis: Redis, token: string): Promise<string | null> {
-  return redis.get(tokenKey(token));
-}
+/** Lookup: email for a token. Null if the token no longer exists
+ *  (expired, already consumed, or invalid). */
+export const getEmailForSignupToken = store.getSubjectForToken;
 
-/** Deletes a still-live signup token for this email, if one exists — both
- *  the forward entry (built from the hash already stored in the by-email
- *  entry, never recovers the raw token) and the by-email entry itself.
- *  Returns whether a live token existed. Used by signup-request on every
- *  request; a fresh token + by-email entry follows right after, so this
- *  is "at most one live token per email." Deleting the by-email entry
- *  here too (not just the forward key) avoids leaving a dangling hash
- *  pointing at nothing if the request crashes before storeSignupToken. */
+/** Deletes a still-live signup token for this email, if one exists. Used
+ *  by signup-request on every request; a fresh token + by-email entry
+ *  follows right after, so this is "at most one live token per email." */
 export async function invalidateExistingSignupToken(redis: Redis, email: string): Promise<boolean> {
-  const existingHash = await redis.get(emailKey(email));
-  if (existingHash === null) return false;
-  await Promise.all([redis.del(forwardKeyForHash(existingHash)), redis.del(emailKey(email))]);
-  return true;
+  return store.invalidateExistingBySubject(redis, normalizeEmail(email));
 }
 
-/** Single-Use-Burn: wenn zwei Tabs gleichzeitig den Confirm-Link klicken,
- *  gewinnt der erste, der zweite kriegt "already-used". TTL = 1 Stunde
- *  (kurz genug damit der Burn-Key Redis nicht dauerhaft belastet, lang
- *  genug damit Replays in normalen Race-Windows abgefangen werden). */
-export async function burnSignupToken(
-  redis: Redis,
-  token: string,
-): Promise<"burned" | "already-used"> {
-  // SET NX EX — atomic check-and-set. Returnt "OK" wenn Key neu, null
-  // wenn schon da.
-  const result = await redis.set(burnKey(token), "1", "EX", 3600, "NX");
-  return result === "OK" ? "burned" : "already-used";
-}
+/** Single-use burn: if two tabs click the confirm link at the same time,
+ *  the first one wins, the second gets "already-used". */
+export const burnSignupToken = store.burn;
 
-/** Cleanup nach erfolgreichem Confirm — beide Lookup-Keys löschen.
- *  Burn-Key bleibt (verhindert Replay innerhalb der Burn-TTL). */
+/** Cleanup after a successful confirm — deletes both lookup keys.
+ *  The burn key stays (prevents replay within the burn TTL). */
 export async function deleteSignupToken(
   redis: Redis,
   args: { email: string; token: string },
 ): Promise<void> {
-  await Promise.all([redis.del(tokenKey(args.token)), redis.del(emailKey(args.email))]);
+  return store.deleteBoth(redis, { subjectId: normalizeEmail(args.email), token: args.token });
 }
 
-/** Burn-Release für Failed-Confirm-Pfade (DB-Error etc.) damit ein
- *  legitimer Retry nicht durch einen stale Burn-Marker geblockt wird. */
-export async function unburnSignupToken(redis: Redis, token: string): Promise<void> {
-  await redis.del(burnKey(token));
-}
+/** Burn release for failed-confirm paths (DB error etc.) so a legitimate
+ *  retry isn't blocked by a stale burn marker. */
+export const unburnSignupToken = store.unburn;

package/src/auth-mfa/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.286.0",
+    "type": "improvement",
+    "title": "mfa-verify-attempts now delegates to shared/lockout-counter",
+    "detail": "No behavior change — same exported function/type names and Redis key prefixes as before the extraction."
+  },
   {
     "version": "0.259.0",
     "type": "improvement",

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,