@cosmicdrift/kumiko-samples 0.347.0 → 0.348.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.347.0",
+  "version": "0.348.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.347.0",
+  "version": "0.348.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>",

package/packages/bundled-features/src/auth-email-password/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.348.0",
+    "type": "fix",
+    "title": "AuthGate accepts a loginUrl function, renders LoginScreen on the login route, and LoginScreen follows a validated next",
+    "detail": "AuthGate accepts a loginUrl function and LoginScreen follows a validated next\n`AuthGateOptions.loginUrl` may now be a function `(locale, returnPath) => string` in addition to a string. When the user is already on the login route, the gate renders the LoginScreen instead of redirecting. After a successful login (and MFA verify or setup), the screen follows the `next` query parameter, but only for relative same-origin paths: no `//`, no scheme, no backslash, no control characters.",
+    "migration": "No action needed. String loginUrl keeps working."
+  },
   {
     "version": "0.347.0",
     "type": "fix",

package/packages/bundled-features/src/auth-email-password/web/auth-gate.tsx

@@ -9,8 +9,13 @@
 // (nur `{ children }`-Prop). Der Sample kann so einen eigenen Login-
 // Screen rein konfigurieren, ohne den Gate selbst ersetzen zu müssen.
 
+import { useLocale } from "@cosmicdrift/kumiko-renderer";
 import { type ComponentType, type ReactNode, useEffect, useState } from "react";
-import { assertNavigableUrl, buildLoginRedirectUrl } from "./auth-redirect.js";
+import {
+  assertNavigableUrl,
+  buildLoginRedirectUrl,
+  followNextAfterLogin,
+} from "./auth-redirect.js";
 import { LoginScreen, type LoginScreenProps } from "./login-screen.js";
 import { SessionProvider, useSession } from "./session.js";
 import { SessionBootstrapErrorScreen } from "./session-bootstrap-error.js";
@@ -108,7 +113,10 @@ export function createLoginRoute(
       return (
         <MfaVerifyComponent
           challengeToken={challengeToken}
-          onSuccess={() => setChallengeToken(null)}
+          onSuccess={() => {
+            setChallengeToken(null);
+            followNextAfterLogin();
+          }}
           onCancel={() => setChallengeToken(null)}
         />
       );
@@ -126,7 +134,10 @@ export function createLoginRoute(
             // refresh() never rejects: a failed refresh surfaces as status
             // "error" (bootstrap error screen with retry), so only the
             // success path needs to clear setupRequest.
-            void refresh().then(() => setSetupRequest(null));
+            void refresh().then(() => {
+              setSetupRequest(null);
+              followNextAfterLogin();
+            });
           }}
           onCancel={() => setSetupRequest(null)}
         />
@@ -150,11 +161,16 @@ export function createLoginRoute(
   return LoginRoute;
 }
 
+/** Builds the login page URL. `returnPath` is the current path + query + hash;
+ *  append it as `next` yourself (use `NEXT_QUERY_PARAM`) if the login page should return there. */
+export type LoginUrlBuilder = (locale: string, returnPath: string) => string;
+
 export type AuthGateOptions = LoginRouteOptions & {
-  /** Login page outside the SPA (root-relative path or http(s) URL). Unauthenticated
-   *  visitors are sent there with `next=<current path>`; the built-in login screen
-   *  is not rendered. */
-  readonly loginUrl?: string;
+  /** Login page outside the SPA (root-relative path or http(s) URL), or a function
+   *  that builds it per locale. Unauthenticated visitors are sent there with
+   *  `next=<current path>` (a string gets `next` appended; a function decides itself).
+   *  On the login route itself the gate renders the built-in login screen instead. */
+  readonly loginUrl?: string | LoginUrlBuilder;
 };
 
 export type SessionAuthGateOptions = AuthGateOptions & {
@@ -162,30 +178,52 @@ export type SessionAuthGateOptions = AuthGateOptions & {
   readonly postLogoutUrl?: string;
 };
 
-function redirectToLoginUrl(loginUrl: string): void {
-  const { origin, pathname, search, hash } = window.location;
+type LoginRedirect =
+  | { readonly kind: "on-login-route" }
+  | { readonly kind: "redirect"; readonly url: string };
+
+// @internal — exported for unit tests only.
+export function resolveLoginRedirect(
+  loginUrl: string | LoginUrlBuilder,
+  locale: string,
+  { origin, pathname, search, hash }: Pick<Location, "origin" | "pathname" | "search" | "hash">,
+): LoginRedirect {
+  const returnPath = `${pathname}${search}${hash}`;
+  const target = typeof loginUrl === "function" ? loginUrl(locale, returnPath) : loginUrl;
+  if (typeof loginUrl === "function") assertNavigableUrl(target, "loginUrl()");
   // Compared before `next` is appended: the target always differs from the current
   // URL once it carries next, so a gate mounted on the login page itself would loop.
-  const loginLocation = new URL(loginUrl, origin);
-  if (loginLocation.origin === origin && loginLocation.pathname === pathname) return;
-  window.location.replace(buildLoginRedirectUrl(loginUrl, `${pathname}${search}${hash}`, origin));
+  const loginLocation = new URL(target, origin);
+  if (loginLocation.origin === origin && loginLocation.pathname === pathname) {
+    return { kind: "on-login-route" };
+  }
+  return {
+    kind: "redirect",
+    url:
+      typeof loginUrl === "function" ? target : buildLoginRedirectUrl(target, returnPath, origin),
+  };
 }
 
 export function makeAuthGate(opts: AuthGateOptions = {}): ComponentType<{
   children: ReactNode;
 }> {
   const { loginUrl } = opts;
-  if (loginUrl !== undefined) assertNavigableUrl(loginUrl, "loginUrl");
+  if (typeof loginUrl === "string") assertNavigableUrl(loginUrl, "loginUrl");
   const LoginRoute = createLoginRoute(opts);
   function AuthGate({ children }: { readonly children: ReactNode }): ReactNode {
     const { status } = useSession();
-    const redirectsToLoginUrl = loginUrl !== undefined && status === "unauthenticated";
+    const locale = useLocale().locale();
+    const loginRedirect =
+      loginUrl !== undefined && status === "unauthenticated"
+        ? resolveLoginRedirect(loginUrl, locale, window.location)
+        : null;
+    const redirectUrl = loginRedirect?.kind === "redirect" ? loginRedirect.url : null;
     // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
     useEffect(() => {
-      if (redirectsToLoginUrl) redirectToLoginUrl(loginUrl);
-    }, [redirectsToLoginUrl]);
+      if (redirectUrl !== null) window.location.replace(redirectUrl);
+    }, [redirectUrl]);
     if (status === "authenticated") return <>{children}</>;
-    if (redirectsToLoginUrl) return null;
+    if (redirectUrl !== null) return null;
     return <LoginRoute />;
   }
   return AuthGate;

package/packages/bundled-features/src/auth-email-password/web/auth-redirect.ts

@@ -58,3 +58,17 @@ export function buildLoginRedirectUrl(
   const isSameOrigin = target.origin === currentOrigin;
   return isSameOrigin ? `${target.pathname}${target.search}${target.hash}` : target.href;
 }
+
+// Login screens call this after a successful login. `next` is re-validated
+// here because it is read from the URL, i.e. attacker-controlled. Returns
+// true when it navigated.
+export function followNextAfterLogin(
+  location: Pick<Location, "search" | "pathname" | "replace"> = window.location,
+): boolean {
+  const next = readNextFromSearch(location.search);
+  if (next === null) return false;
+  // Following a next that points at the login page itself would reload it forever.
+  if (new URL(next, "https://next.invalid").pathname === location.pathname) return false;
+  location.replace(next);
+  return true;
+}

package/packages/bundled-features/src/auth-email-password/web/login-screen.tsx

@@ -17,6 +17,7 @@ import {
   requestEmailVerification,
 } from "./auth-client.js";
 import { AuthCard } from "./auth-form-primitives.js";
+import { followNextAfterLogin } from "./auth-redirect.js";
 import { useSession } from "./session.js";
 
 // Resend-Status für den "Bestätigungs-Mail erneut senden"-Flow, der bei
@@ -142,7 +143,10 @@ export function LoginScreen({
     setResendStatus({ kind: "idle" });
     const res = await session.login({ email, password });
     setSubmitting(false);
-    if (res.kind === "success") return;
+    if (res.kind === "success") {
+      followNextAfterLogin();
+      return;
+    }
     if (res.kind === "mfa-challenge") {
       if (onMfaChallenge) {
         onMfaChallenge(res.challengeToken);

package/packages/bundled-features/src/cap-counter/book-cap-usage.ts

@@ -59,6 +59,8 @@ export type BookCapUsageOptions = {
   readonly periodStartIso: string;
   readonly amount?: number;
   readonly outsideTransaction?: boolean;
+  // Runs on every attempt with the freshly read value, so a throw rejects the booking against the state it would actually be applied to (a version-conflict retry re-reads and re-checks).
+  readonly guardCurrentValue?: (currentValue: number) => void;
 };
 
 function requireOutsideTransactionDb(ctx: HandlerContext): TenantDb {
@@ -73,6 +75,22 @@ function requireOutsideTransactionDb(ctx: HandlerContext): TenantDb {
 export async function bookCapUsage(
   ctx: HandlerContext,
   options: BookCapUsageOptions,
+): Promise<WriteResult> {
+  return applyCapDelta(ctx, options, "add");
+}
+
+// Gives back a reservation whose operation failed afterwards; the counter never drops below 0.
+export async function releaseCapUsage(
+  ctx: HandlerContext,
+  options: Omit<BookCapUsageOptions, "guardCurrentValue">,
+): Promise<WriteResult> {
+  return applyCapDelta(ctx, options, "subtract");
+}
+
+async function applyCapDelta(
+  ctx: HandlerContext,
+  options: BookCapUsageOptions,
+  direction: "add" | "subtract",
 ): Promise<WriteResult> {
   const parsed = capBookingSchema.parse(options);
   const aggregateId = capCounterAggregateId(
@@ -84,6 +102,8 @@ export async function bookCapUsage(
   async function attemptWrite(db: TenantDb): Promise<WriteResult> {
     const existing = await db.selectMany(table, { id: aggregateId }, { limit: 1 });
     if (existing.length === 0) {
+      options.guardCurrentValue?.(0);
+      if (direction === "subtract") return { isSuccess: true, data: {} };
       return executor.create(
         {
           id: aggregateId,
@@ -103,11 +123,17 @@ export async function bookCapUsage(
     }
     const currentValue = currentRow["value"] as number; // @cast-boundary db-row
     const currentVersion = currentRow["version"] as number; // @cast-boundary db-row
+    options.guardCurrentValue?.(currentValue);
     return executor.update(
       {
         id: aggregateId,
         version: currentVersion,
-        changes: { value: currentValue + parsed.amount },
+        changes: {
+          value:
+            direction === "add"
+              ? currentValue + parsed.amount
+              : Math.max(0, currentValue - parsed.amount),
+        },
       },
       ctx.user,
       db,
@@ -124,6 +150,7 @@ export async function bookCapUsage(
 export type MarkCapSoftWarnedOptions = {
   readonly capName: string;
   readonly periodStartIso: string;
+  readonly outsideTransaction?: boolean;
 };
 
 export async function markCapSoftWarned(
@@ -137,8 +164,8 @@ export async function markCapSoftWarned(
     parsed.periodStartIso,
   );
 
-  return retryCounterWriteOnVersionConflict(async () => {
-    const existing = await ctx.db.selectMany(table, { id: aggregateId }, { limit: 1 });
+  async function attemptMark(db: TenantDb): Promise<WriteResult> {
+    const existing = await db.selectMany(table, { id: aggregateId }, { limit: 1 });
     if (existing.length === 0) {
       throw new Error(
         `cap-counter: cannot mark-soft-warned, no counter found for tenant=${ctx.user.tenantId} cap=${parsed.capName} period=${parsed.periodStartIso}`,
@@ -162,9 +189,15 @@ export async function markCapSoftWarned(
         changes: { lastSoftWarnedAt: Temporal.Now.instant() },
       },
       ctx.user,
-      ctx.db,
+      db,
     );
-  });
+  }
+
+  if (options.outsideTransaction) {
+    const outsideDb = requireOutsideTransactionDb(ctx);
+    return retryCounterWriteOnVersionConflict(() => runInOwnTransaction(outsideDb, attemptMark));
+  }
+  return retryCounterWriteOnVersionConflict(() => attemptMark(ctx.db));
 }
 
 export type ReadRollingCapUsageOptions = {

package/packages/bundled-features/src/cap-counter/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.348.0",
+    "type": "fix",
+    "title": "withCapEnforcement reserves cap usage before the handler transaction so parallel calls cannot exceed the hard limit",
+    "detail": "withCapEnforcement reserves cap usage before the handler transaction\n`withCapEnforcement` used to check the cap and book the usage in two separate steps, so parallel calls could all pass the same stale read and exceed the hard limit. The wrapper now only declares the cap through the new `WriteHandlerDef.reserveBeforeTransaction` hook. The dispatcher runs the hook after the access, feature and schema checks and before the handler transaction opens. The hard-cap check and the increment are one short, version-guarded write that commits at once, so no connection is held across the handler and capped calls on the same counter still run in parallel. The returned release gives the amount back (never below 0) after the transaction ended without committing: rollback, failure result, throw or failed commit. Each reservation covers exactly one top-level execution: a capped handler reached through a nested `ctx.write` or run a second time in the same command is rejected. A wrapped handler now keeps its own `rateLimit`, `escapeHatch` and `additionalRateLimits` (the old wrapper dropped them). The reservation runs before the rate-limit gate, so a rate-limited caller can still cause reserve and release writes. If a COMMIT fails with an unknown outcome, the release can under-count. `bookCapUsage` accepts a `guardCurrentValue` callback, `markCapSoftWarned` and `enforceCapAndMaybeNotify` can write outside the handler transaction, and the soft-warning pre-check now honors `amount`. `withRollingCapEnforcement` is unchanged and keeps its check-then-book race.",
+    "migration": "No action needed. Calls above the hard limit are now rejected with cap_exceeded even when they race. A capped handler must not be called through ctx.write from another handler."
+  },
   {
     "version": "0.338.0",
     "type": "improvement",

package/packages/bundled-features/src/cap-counter/enforce-cap.ts

@@ -63,6 +63,20 @@ export type EnforceCapResult =
       readonly crossed: boolean;
     };
 
+export function assertBelowHardCap(
+  valueSeenByLastUnit: number,
+  cap: {
+    readonly capName: string;
+    readonly limit: number;
+    readonly profile: CapToleranceProfileName;
+  },
+): void {
+  const tolerance = CAP_TOLERANCES[cap.profile];
+  if (valueSeenByLastUnit >= cap.limit * tolerance.hard) {
+    throw new CapExceededError(cap.capName, cap.limit, valueSeenByLastUnit, tolerance);
+  }
+}
+
 // =============================================================================
 // Enforce-Cap helper
 // =============================================================================
@@ -82,7 +96,8 @@ export type EnforceCapResult =
  *
  * **Sync read implication:** the counter reflects the state at this
  * exact transaction. Two parallel writes can each see "value < hard"
- * and both pass — that's a race. Cap-tolerance-buffers (soft 110% /
+ * and both pass — that's a race (withCapEnforcement closes it with an atomic reservation;
+ * bare enforceCap stays a read). Cap-tolerance-buffers (soft 110% /
  * hard 120% for burstable caps) cover this; truly hard slots
  * (apps-count) need stricter serialization at the create-handler
  * level (e.g. uniqueness-index on apps.tenantId+slot-number).
@@ -112,7 +127,6 @@ export async function enforceCap(
 
   const tolerance = CAP_TOLERANCES[options.profile];
   const softThreshold = options.limit * tolerance.soft;
-  const hardThreshold = options.limit * tolerance.hard;
 
   const rows = await ctx.db.selectMany(
     table,
@@ -125,9 +139,7 @@ export async function enforceCap(
   // The last of `amount` units sees this value before its own increment.
   const value = storedValue + amount - 1;
 
-  if (value >= hardThreshold) {
-    throw new CapExceededError(options.capName, options.limit, value, tolerance);
-  }
+  assertBelowHardCap(value, options);
 
   if (value >= softThreshold) {
     const lastSoftWarnedAt = row ? row["lastSoftWarnedAt"] : null;
@@ -299,6 +311,7 @@ export async function enforceCapAndMaybeNotify(
     readonly profile: CapToleranceProfileName;
     readonly notify: SoftHitNotifier;
     readonly amount?: number;
+    readonly markSoftWarnedOutsideTransaction?: boolean;
   },
 ): Promise<EnforceCapResult> {
   const result = await enforceCap(ctx, {
@@ -325,6 +338,7 @@ export async function enforceCapAndMaybeNotify(
     const marked = await markCapSoftWarned(ctx, {
       capName: options.capName,
       periodStartIso: options.periodStartIso,
+      ...(options.markSoftWarnedOutsideTransaction && { outsideTransaction: true }),
     });
     if (!marked.isSuccess) throw reraiseAsKumikoError(marked.error);
   }

package/packages/bundled-features/src/cap-counter/with-cap-enforcement.ts

@@ -1,21 +1,24 @@
-// withCapEnforcement / withRollingCapEnforcement — handler-wrapper die
-// pre-call enforceCap-And-Notify + post-call booking um den
-// gewrappten Handler legen.
+// withCapEnforcement / withRollingCapEnforcement: handler wrappers that put the
+// pre-call enforceCapAndMaybeNotify and a reservation around the wrapped handler.
 //
-// **Warum Wrapper statt manuelle Calls im Handler:**
-// Pattern-konsistenz. Wer einen cap-bedingten Handler schreibt,
-// darf nicht vergessen den counter zu incrementen oder den enforce-
-// pre-call zu machen — beides ist atomic-mit-dem-Handler-zusammen.
-// Wrapper macht das Pattern explizit + co-located.
+// **Why a wrapper instead of manual calls in the handler:** a cap-bound handler
+// must not forget the enforce pre-call, the reservation or the release on failure;
+// the wrapper keeps the pattern explicit and co-located.
+//
+// **Calendar reservation:** the wrapper only declares the cap; the dispatcher runs the
+// reservation (reserveBeforeTransaction) before the handler transaction opens, in its own short
+// committed write, and releases it after that transaction ended without committing (rollback,
+// failure result, failed COMMIT). No connection is held across the handler, so capped requests
+// cannot exhaust the pool, and the counter stream is not locked while the handler runs. If a
+// COMMIT fails with an unknown outcome the release can under-count; a wrapped handler must not
+// book the same counter itself. Reached through a nested ctx.write the cap is not reserved, so
+// the dispatcher rejects that call unless the top-level batch reserved the same handler.
 //
-// **Atomicity caveat:** calendar booking runs in-process via bookCapUsage
-// (see book-cap-usage.ts).
 // Rolling booking still dispatches the SystemAdmin-only increment-rolling
-// handler. In-process booking would work today only because the entity
-// executor appends without the event-ownership check (that check runs in
-// appendDomainEventCore alone); relying on that gap would break once the
-// executor path enforces ownership, so rolling callers need a SystemAdmin
-// identity until cap-counter declares an explicit foreign-booking opt-in.
+// handler and has no reservation: it would need a compensating event type,
+// a changed readRollingCapUsage and a version-guarded append behind the
+// SystemAdmin dispatch. Rolling callers need a SystemAdmin identity until
+// cap-counter declares an explicit foreign-booking opt-in.
 //
 // No automatic markSoftWarned here — that's inside enforceCapAndMaybeNotify
 // (enforce-cap.ts).
@@ -26,9 +29,10 @@ import type {
   WriteHandlerDef,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { reraiseAsKumikoError } from "@cosmicdrift/kumiko-framework/errors";
-import { bookCapUsage } from "./book-cap-usage.js";
+import { bookCapUsage, releaseCapUsage } from "./book-cap-usage.js";
 import { CapCounterHandlers } from "./constants.js";
 import {
+  assertBelowHardCap,
   type CapToleranceProfileName,
   enforceCapAndMaybeNotify,
   enforceRollingCapAndMaybeNotify,
@@ -68,53 +72,51 @@ export type CalendarCapResolver = (
 /**
  * Wrap a write-handler with calendar-period cap-enforcement.
  *
- * Flow:
+ * Flow (all before the handler transaction, in the dispatcher):
  *   1. resolve cap-spec via `capResolver(event, ctx)`
- *   2. pre-call: `enforceCapAndMaybeNotify` — throws CapExceededError
- *      on hard-hit (handler never runs), notifies on soft-hit-crossing
- *   3. invoke the wrapped handler
- *   4. post-success: book usage via `bookCapUsage` with `amount`
- *
- * The returned handler-def keeps the original name/schema/access
- * untouched — only the handler-fn is wrapped. The dispatcher sees
- * the same external contract.
+ *   2. `enforceCapAndMaybeNotify` — throws CapExceededError on hard-hit
+ *      (handler never runs), notifies on soft-hit-crossing
+ *   3. reserve `amount` (hard-cap check + increment in one short, immediately committed write)
+ *   4. the returned release gives the amount back if the transaction does not commit
  */
 export function withCapEnforcement(
   handler: WriteHandlerDef,
   capResolver: CalendarCapResolver,
 ): WriteHandlerDef {
   return {
-    name: handler.name,
-    schema: handler.schema,
-    access: handler.access,
-    handler: async (event, ctx) => {
+    ...handler,
+    reserveBeforeTransaction: async (event, ctx) => {
       const cap = await capResolver(event, ctx);
 
-      // Pre-enforce. Hard-hit throws CapExceededError (extends KumikoError,
-      // dispatcher auto-maps to HTTP 429 + cap_exceeded). Soft-hit-crossing
-      // notifies via the supplied notifier + flips lastSoftWarnedAt.
       await enforceCapAndMaybeNotify(ctx, {
         capName: cap.capName,
         periodStartIso: cap.periodStartIso,
         limit: cap.limit,
         profile: cap.profile,
         notify: cap.notify,
+        markSoftWarnedOutsideTransaction: true,
+        ...(cap.amount !== undefined && { amount: cap.amount }),
       });
 
-      const result = await handler.handler(event, ctx);
+      const amount = cap.amount ?? 1;
+      const reserved = await bookCapUsage(ctx, {
+        capName: cap.capName,
+        amount,
+        periodStartIso: cap.periodStartIso,
+        outsideTransaction: true,
+        guardCurrentValue: (currentValue) => assertBelowHardCap(currentValue + amount - 1, cap),
+      });
+      if (!reserved.isSuccess) throw reraiseAsKumikoError(reserved.error);
 
-      // Post-success increment. Skip on failure so a failed write
-      // doesn't burn cap-quota. amount default 1.
-      if (result.isSuccess) {
-        const booked = await bookCapUsage(ctx, {
+      return async () => {
+        const released = await releaseCapUsage(ctx, {
           capName: cap.capName,
-          amount: cap.amount ?? 1,
+          amount,
           periodStartIso: cap.periodStartIso,
+          outsideTransaction: true,
         });
-        if (!booked.isSuccess) throw reraiseAsKumikoError(booked.error);
-      }
-
-      return result;
+        if (!released.isSuccess) throw reraiseAsKumikoError(released.error);
+      };
     },
   };
 }