@cosmicdrift/kumiko-bundled-features 0.346.0 → 0.348.0

package/dist/auth-email-password/handlers/signup-confirm.write.d.ts

@@ -1,4 +1,4 @@
-import { type SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { type SessionUser, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { type LoginHandlerOptions, type LoginResult } from "./login.write.js";
 export type SignupConfirmData = {
@@ -9,11 +9,23 @@ export type SignupConfirmData = {
         readonly entityType: string;
         readonly id: string;
     };
-} | Exclude<LoginResult, {
+} | (Exclude<LoginResult, {
     readonly kind: "auth-session";
-}>;
+}> & {
+    readonly signup: {
+        readonly roles: readonly string[];
+        readonly tenantId: TenantId;
+        readonly tenantKey: string;
+        readonly handover?: ClaimedHandover;
+    };
+});
 export type SignupConfirmOptions = Pick<LoginHandlerOptions, "mfaStatusChecker">;
+type ClaimedHandover = {
+    readonly entityType: string;
+    readonly id: string;
+};
 export declare function createSignupConfirmHandler(opts?: SignupConfirmOptions): import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"signup-confirm", z.ZodObject<{
     token: z.ZodString;
     password: z.ZodString;
 }, z.core.$strip>, SignupConfirmData, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+export {};

package/dist/auth-email-password/handlers/signup-confirm.write.js

@@ -168,7 +168,18 @@ export function createSignupConfirmHandler(opts = {}) {
                     await deleteSignupHandover(ctx.redis, event.payload.token);
                 if (mfaGate !== undefined) {
                     committed = true;
-                    return { isSuccess: true, data: mfaGate };
+                    return {
+                        isSuccess: true,
+                        data: {
+                            ...mfaGate,
+                            signup: {
+                                roles: session.roles,
+                                tenantId: provisioned.tenantId,
+                                tenantKey,
+                                ...(handover !== undefined && { handover }),
+                            },
+                        },
+                    };
                 }
                 committed = true;
                 return {

package/dist/auth-email-password/web/auth-client.d.ts

@@ -116,6 +116,7 @@ export type SignupConfirmResult = ({
     readonly kind: "signed-in";
 } & SignupConfirmSuccess) | {
     readonly kind: "mfa-pending";
+    readonly landingPath?: string;
 };
 export declare function confirmSignup(token: string, password: string): Promise<{
     ok: true;

package/dist/auth-email-password/web/auth-client.js

@@ -232,7 +232,13 @@ export async function confirmSignup(token, password) {
         // @cast-boundary engine-payload
         const body = (await res.json());
         if (body.mfaRequired === true || body.mfaSetupRequired === true) {
-            return { ok: true, data: { kind: "mfa-pending" } };
+            return {
+                ok: true,
+                data: {
+                    kind: "mfa-pending",
+                    ...(typeof body.landingPath === "string" && { landingPath: body.landingPath }),
+                },
+            };
         }
         return { ok: true, data: { kind: "signed-in", ...body } };
     }

package/dist/auth-email-password/web/auth-gate.d.ts

@@ -23,19 +23,31 @@ export type LoginRouteOptions = {
     readonly onAuthenticated?: () => void;
 };
 export declare function createLoginRoute(opts?: LoginRouteOptions): ComponentType<Record<string, never>>;
+/** 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 & {
     /** Where logout navigates to (root-relative path or http(s) URL). Without it, logout reloads the page. */
     readonly postLogoutUrl?: string;
 };
+type LoginRedirect = {
+    readonly kind: "on-login-route";
+} | {
+    readonly kind: "redirect";
+    readonly url: string;
+};
+export declare function resolveLoginRedirect(loginUrl: string | LoginUrlBuilder, locale: string, { origin, pathname, search, hash }: Pick<Location, "origin" | "pathname" | "search" | "hash">): LoginRedirect;
 export declare function makeAuthGate(opts?: AuthGateOptions): ComponentType<{
     children: ReactNode;
 }>;
 export declare function makeSessionAuthGate(opts?: SessionAuthGateOptions): ComponentType<{
     children: ReactNode;
 }>;
+export {};

package/dist/auth-email-password/web/auth-gate.js

@@ -9,8 +9,9 @@ import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 // damit das Gate der ClientFeatureDefinition-Signatur entspricht
 // (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 { useEffect, useState } from "react";
-import { assertNavigableUrl, buildLoginRedirectUrl } from "./auth-redirect.js";
+import { assertNavigableUrl, buildLoginRedirectUrl, followNextAfterLogin, } from "./auth-redirect.js";
 import { LoginScreen } from "./login-screen.js";
 import { SessionProvider, useSession } from "./session.js";
 import { SessionBootstrapErrorScreen } from "./session-bootstrap-error.js";
@@ -58,7 +59,10 @@ export function createLoginRoute(opts = {}) {
         if (status === "authenticated" && onAuthenticated)
             return null;
         if (challengeToken !== null && MfaVerifyComponent) {
-            return (_jsx(MfaVerifyComponent, { challengeToken: challengeToken, onSuccess: () => setChallengeToken(null), onCancel: () => setChallengeToken(null) }));
+            return (_jsx(MfaVerifyComponent, { challengeToken: challengeToken, onSuccess: () => {
+                    setChallengeToken(null);
+                    followNextAfterLogin();
+                }, onCancel: () => setChallengeToken(null) }));
         }
         // Pending preauthSetupToken from LoginScreen's onMfaSetupRequired. Same
         // reasoning as challengeToken — a UI-only transition, not session state.
@@ -69,7 +73,10 @@ export function createLoginRoute(opts = {}) {
                     // 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) }));
         }
         return (_jsx(LoginComponent, { ...opts.loginScreenProps, onMfaChallenge: MfaVerifyComponent ? setChallengeToken : opts.loginScreenProps?.onMfaChallenge, onMfaSetupRequired: MfaSetupComponent
@@ -78,31 +85,43 @@ export function createLoginRoute(opts = {}) {
     }
     return LoginRoute;
 }
-function redirectToLoginUrl(loginUrl) {
-    const { origin, pathname, search, hash } = window.location;
+// @internal — exported for unit tests only.
+export function resolveLoginRedirect(loginUrl, locale, { origin, pathname, search, hash }) {
+    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 = {}) {
     const { loginUrl } = opts;
-    if (loginUrl !== undefined)
+    if (typeof loginUrl === "string")
         assertNavigableUrl(loginUrl, "loginUrl");
     const LoginRoute = createLoginRoute(opts);
     function AuthGate({ children }) {
         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 _jsx(_Fragment, { children: children });
-        if (redirectsToLoginUrl)
+        if (redirectUrl !== null)
             return null;
         return _jsx(LoginRoute, {});
     }

package/dist/auth-email-password/web/auth-redirect.d.ts

@@ -3,3 +3,4 @@ export declare function isSafeNextPath(candidate: unknown): candidate is string;
 export declare function readNextFromSearch(search: string): string | null;
 export declare function assertNavigableUrl(url: string, optionName: string): void;
 export declare function buildLoginRedirectUrl(loginUrl: string, returnPath: string, currentOrigin: string): string;
+export declare function followNextAfterLogin(location?: Pick<Location, "search" | "pathname" | "replace">): boolean;

package/dist/auth-email-password/web/auth-redirect.js

@@ -56,3 +56,16 @@ export function buildLoginRedirectUrl(loginUrl, returnPath, currentOrigin) {
     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 = window.location) {
+    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/dist/auth-email-password/web/login-screen.js

@@ -13,6 +13,7 @@ import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { useState } from "react";
 import { requestEmailVerification, } from "./auth-client.js";
 import { AuthCard } from "./auth-form-primitives.js";
+import { followNextAfterLogin } from "./auth-redirect.js";
 import { useSession } from "./session.js";
 // Map vom Reason-Code des Login-Handlers auf einen i18n-Key plus
 // optional extrahierte Interpolations-Parameter. Ungekannte Codes
@@ -64,8 +65,10 @@ export function LoginScreen({ title, subtitle, submitLabel, forgotPasswordHref,
         setResendStatus({ kind: "idle" });
         const res = await session.login({ email, password });
         setSubmitting(false);
-        if (res.kind === "success")
+        if (res.kind === "success") {
+            followNextAfterLogin();
             return;
+        }
         if (res.kind === "mfa-challenge") {
             if (onMfaChallenge) {
                 onMfaChallenge(res.challengeToken);

package/dist/auth-email-password/web/signup-complete-screen.js

@@ -22,6 +22,7 @@ import { useState } from "react";
 import { confirmSignup } from "./auth-client.js";
 import { passwordPairIssue, resolvePostAuthHref } from "./auth-form-logic.js";
 import { AuthCard, useUrlToken } from "./auth-form-primitives.js";
+import { buildLoginRedirectUrl } from "./auth-redirect.js";
 export function SignupCompleteScreen({ title, token: tokenProp, loggedInHref = "/", loginHref = "/login", }) {
     const t = useTranslation();
     const { Form, Field, Input, Button, Banner, Link } = usePrimitives();
@@ -49,7 +50,9 @@ export function SignupCompleteScreen({ title, token: tokenProp, loggedInHref = "
         if (res.ok) {
             if (res.data.kind === "mfa-pending") {
                 setMfaPending(true);
-                setContinueHref(loginHref);
+                setContinueHref(res.data.landingPath === undefined
+                    ? loginHref
+                    : buildLoginRedirectUrl(loginHref, res.data.landingPath, window.location.origin));
                 return;
             }
             // Cookies are already set (auto-login). Show a confirmation with an

package/dist/cap-counter/book-cap-usage.d.ts

@@ -5,11 +5,14 @@ export type BookCapUsageOptions = {
     readonly periodStartIso: string;
     readonly amount?: number;
     readonly outsideTransaction?: boolean;
+    readonly guardCurrentValue?: (currentValue: number) => void;
 };
 export declare function bookCapUsage(ctx: HandlerContext, options: BookCapUsageOptions): Promise<WriteResult>;
+export declare function releaseCapUsage(ctx: HandlerContext, options: Omit<BookCapUsageOptions, "guardCurrentValue">): Promise<WriteResult>;
 export type MarkCapSoftWarnedOptions = {
     readonly capName: string;
     readonly periodStartIso: string;
+    readonly outsideTransaction?: boolean;
 };
 export declare function markCapSoftWarned(ctx: HandlerContext, options: MarkCapSoftWarnedOptions): Promise<WriteResult>;
 export type ReadRollingCapUsageOptions = {

package/dist/cap-counter/book-cap-usage.js

@@ -41,11 +41,21 @@ function requireOutsideTransactionDb(ctx) {
     return ctx.dbOutsideTransaction;
 }
 export async function bookCapUsage(ctx, options) {
+    return applyCapDelta(ctx, options, "add");
+}
+// Gives back a reservation whose operation failed afterwards; the counter never drops below 0.
+export async function releaseCapUsage(ctx, options) {
+    return applyCapDelta(ctx, options, "subtract");
+}
+async function applyCapDelta(ctx, options, direction) {
     const parsed = capBookingSchema.parse(options);
     const aggregateId = capCounterAggregateId(ctx.user.tenantId, parsed.capName, parsed.periodStartIso);
     async function attemptWrite(db) {
         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,
                 capName: parsed.capName,
@@ -60,10 +70,15 @@ export async function bookCapUsage(ctx, options) {
         }
         const currentValue = currentRow["value"]; // @cast-boundary db-row
         const currentVersion = currentRow["version"]; // @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);
     }
     if (options.outsideTransaction) {
@@ -75,8 +90,8 @@ export async function bookCapUsage(ctx, options) {
 export async function markCapSoftWarned(ctx, options) {
     const parsed = capPeriodSchema.parse(options);
     const aggregateId = capCounterAggregateId(ctx.user.tenantId, parsed.capName, parsed.periodStartIso);
-    return retryCounterWriteOnVersionConflict(async () => {
-        const existing = await ctx.db.selectMany(table, { id: aggregateId }, { limit: 1 });
+    async function attemptMark(db) {
+        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}`);
         }
@@ -94,8 +109,13 @@ export async function markCapSoftWarned(ctx, options) {
             id: aggregateId,
             version: currentVersion,
             changes: { lastSoftWarnedAt: Temporal.Now.instant() },
-        }, ctx.user, ctx.db);
-    });
+        }, ctx.user, db);
+    }
+    if (options.outsideTransaction) {
+        const outsideDb = requireOutsideTransactionDb(ctx);
+        return retryCounterWriteOnVersionConflict(() => runInOwnTransaction(outsideDb, attemptMark));
+    }
+    return retryCounterWriteOnVersionConflict(() => attemptMark(ctx.db));
 }
 // Sums usage without throwing — for callers that only need the raw number
 // (e.g. a CapSpec.usage callback), not the enforce-and-throw path.

package/dist/cap-counter/enforce-cap.d.ts

@@ -53,6 +53,11 @@ export type EnforceCapResult =
     /** True if this call CROSSED the soft-threshold and notified. */
     readonly crossed: boolean;
 };
+export declare function assertBelowHardCap(valueSeenByLastUnit: number, cap: {
+    readonly capName: string;
+    readonly limit: number;
+    readonly profile: CapToleranceProfileName;
+}): void;
 /**
  * Synchronous read-and-check of the calling tenant's counter for
  * (capName, period). Returns:
@@ -68,7 +73,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).
@@ -163,6 +169,7 @@ export declare function enforceCapAndMaybeNotify(ctx: HandlerContext, options: {
     readonly profile: CapToleranceProfileName;
     readonly notify: SoftHitNotifier;
     readonly amount?: number;
+    readonly markSoftWarnedOutsideTransaction?: boolean;
 }): Promise<EnforceCapResult>;
 /**
  * Rolling-Window-enforcement + immer-feuert-Notification beim soft-hit.

package/dist/cap-counter/enforce-cap.js

@@ -21,6 +21,12 @@ export const CAP_TOLERANCES = {
     /** Egress — Bursty-Traffic legitim, nur extreme Spikes blockieren. */
     egress: { soft: 1.1, hard: 1.3 },
 };
+export function assertBelowHardCap(valueSeenByLastUnit, cap) {
+    const tolerance = CAP_TOLERANCES[cap.profile];
+    if (valueSeenByLastUnit >= cap.limit * tolerance.hard) {
+        throw new CapExceededError(cap.capName, cap.limit, valueSeenByLastUnit, tolerance);
+    }
+}
 // =============================================================================
 // Enforce-Cap helper
 // =============================================================================
@@ -39,7 +45,8 @@ export const CAP_TOLERANCES = {
  *
  * **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).
@@ -54,15 +61,12 @@ export async function enforceCap(ctx, options) {
     }
     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, { capName: options.capName, periodStart: options.periodStartIso }, { limit: 1 });
     const row = rows[0];
     const storedValue = row ? row["value"] : 0; // @cast-boundary db-row
     // 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;
         return { state: "soft-hit", value, crossed: lastSoftWarnedAt === null };
@@ -200,6 +204,7 @@ export async function enforceCapAndMaybeNotify(ctx, options) {
         const marked = await markCapSoftWarned(ctx, {
             capName: options.capName,
             periodStartIso: options.periodStartIso,
+            ...(options.markSoftWarnedOutsideTransaction && { outsideTransaction: true }),
         });
         if (!marked.isSuccess)
             throw reraiseAsKumikoError(marked.error);

package/dist/cap-counter/with-cap-enforcement.d.ts

@@ -24,16 +24,12 @@ export type CalendarCapResolver = (event: WriteEvent, ctx: HandlerContext) => Pr
 /**
  * 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 declare function withCapEnforcement(handler: WriteHandlerDef, capResolver: CalendarCapResolver): WriteHandlerDef;
 export type RollingCapDef = {

package/dist/cap-counter/with-cap-enforcement.js

@@ -1,72 +1,75 @@
-// 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).
 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 { enforceCapAndMaybeNotify, enforceRollingCapAndMaybeNotify, } from "./enforce-cap.js";
+import { assertBelowHardCap, enforceCapAndMaybeNotify, enforceRollingCapAndMaybeNotify, } from "./enforce-cap.js";
 /**
  * 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, capResolver) {
     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);
-            // 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, {
+            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);
+            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);
+            };
         },
     };
 }

package/dist/personal-access-tokens/constants.d.ts

@@ -14,6 +14,7 @@ export declare const PatHandlers: {
 export declare const PatQueries: {
     readonly mine: "personal-access-tokens:query:mine";
     readonly availableScopes: "personal-access-tokens:query:available-scopes";
+    readonly availability: "personal-access-tokens:query:availability";
 };
 export declare const PAT_PREFIX_DISPLAY_LENGTH = 12;
 export type PatRateLimit = {

package/dist/personal-access-tokens/constants.js

@@ -26,6 +26,7 @@ export const PatHandlers = {
 export const PatQueries = {
     mine: "personal-access-tokens:query:mine",
     availableScopes: "personal-access-tokens:query:available-scopes",
+    availability: "personal-access-tokens:query:availability",
 };
 // Only the first chars of a minted token are stored (alongside the hash) so the
 // UI can show "kpat_ab12…" for recognition without ever holding the secret.

package/dist/personal-access-tokens/feature.d.ts

@@ -13,6 +13,10 @@ export type PersonalAccessTokensOptions = {
     readonly toggleable?: {
         readonly default: boolean;
     };
+    /** Screen (same-feature id or `<feature>:screen:<id>`, must not be gated itself)
+     *  shown in place of the token screens when the tenant's tier excludes the
+     *  feature, e.g. an upgrade notice. Default: the standard "unavailable" notice. */
+    readonly lockedFallbackScreen?: string;
     readonly mfaVerifier?: CreatePatOptions["mfaVerifier"];
     readonly autoRevokeOnPasswordChange?: (userId: string) => Promise<number>;
 };

package/dist/personal-access-tokens/feature.js

@@ -3,6 +3,7 @@ import { PAT_TOKEN_PREFIX } from "@cosmicdrift/kumiko-framework/api";
 import { deriveEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { API_TOKEN_ENTITY_NAME, PAT_DEFAULT_RATE_LIMIT, PAT_FEATURE, } from "./constants.js";
+import { availabilityQuery } from "./handlers/availability.query.js";
 import { buildAvailableScopesQuery } from "./handlers/available-scopes.query.js";
 import { createPatCreateHandler } from "./handlers/create.write.js";
 import { listPatQuery } from "./handlers/list.query.js";
@@ -105,12 +106,14 @@ export function createPersonalAccessTokensFeature(options) {
         };
         const queries = {
             mine: r.queryHandler(listPatQuery),
+            availability: r.queryHandler(availabilityQuery),
             availableScopes: r.queryHandler(buildAvailableScopesQuery(scopes)),
         };
         // Declarative screens — list-with-revoke + mint-with-reveal. The app
         // places `patListScreen` via r.nav in its logged-in settings area.
-        r.screen(patListScreen);
-        r.screen(createPatMintScreen(scopes));
+        const lockedFallback = options.lockedFallbackScreen === undefined ? {} : { fallback: options.lockedFallbackScreen };
+        r.screen({ ...patListScreen, ...lockedFallback });
+        r.screen({ ...createPatMintScreen(scopes), ...lockedFallback });
         r.translations({ keys: { ...PAT_FEATURE_I18N, ...patScopeOptionTranslations(scopes) } });
         // rateLimit flows into feature.exports so run-prod-app builds the
         // limiter from the same declaration — single source of truth. `scopes`

package/dist/personal-access-tokens/handlers/availability.query.d.ts

@@ -0,0 +1,4 @@
+import * as z from "zod";
+export declare const availabilityQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"availability", z.ZodObject<{}, z.core.$strip>, {
+    enabled: boolean;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/personal-access-tokens/handlers/availability.query.js

@@ -0,0 +1,17 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+// Screen gate probe: the dispatcher's feature gate rejects every handler of a
+// toggleable feature the tenant's tier does not include, so this query only
+// answers for tenants that may use tokens — a rejection makes the screens'
+// visibleWhen fall back instead of rendering an unusable token list.
+export const availabilityQuery = defineQueryHandler({
+    name: "availability",
+    schema: z.object({}),
+    access: {
+        openToAll: {
+            reason: "constant answer that only exists to be gated by the feature toggle; it carries no user or tenant data",
+        },
+    },
+    description: "Reports that personal access tokens are available to the caller's tenant; fails with feature_disabled when the tenant's tier excludes them. The token screens use it to decide whether to render.",
+    handler: async () => ({ enabled: true }),
+});

package/dist/personal-access-tokens/screens.js

@@ -1,9 +1,17 @@
 import { i18nKey, MAX_LIST_LIMIT, } from "@cosmicdrift/kumiko-framework/engine";
 import { PAT_MINT_SCREEN_ID, PAT_SCREEN_ID, PatHandlers, PatQueries } from "./constants.js";
 const PAT_STATUS_OPTION_KEY_PREFIX = "pat.list.status.";
+// Both screens render only for tenants whose tier includes the feature; the
+// availability query is rejected by the feature gate otherwise.
+const PAT_SCREEN_VISIBLE_WHEN = {
+    query: PatQueries.availability,
+    field: "enabled",
+    eq: true,
+};
 export const patListScreen = {
     id: PAT_SCREEN_ID,
     type: "projectionList",
+    visibleWhen: PAT_SCREEN_VISIBLE_WHEN,
     query: PatQueries.mine,
     // The `mine` handler honours `limit` only (no offset/total), so a pager would
     // show page 1 forever: send one max-size request and render no pager.
@@ -76,6 +84,7 @@ export function createPatMintScreen(scopes) {
     return {
         id: PAT_MINT_SCREEN_ID,
         type: "secretMint",
+        visibleWhen: PAT_SCREEN_VISIBLE_WHEN,
         handler: PatHandlers.create,
         fields: {
             name: { type: "text", required: true, maxLength: 120 },

package/dist/step-dispatcher/webhook-runner.js

@@ -184,6 +184,8 @@ export async function performWebhookDispatch(spec, deps) {
             signal: AbortSignal.timeout(deps.requestTimeoutMs ?? WEBHOOK_REQUEST_TIMEOUT_MS),
             body: spec.body !== undefined ? JSON.stringify(spec.body) : undefined,
         });
+        // Only the status is used; an unread body would pin the socket until the timeout fires.
+        await res.body?.cancel().catch(() => { });
         if (!res.ok) {
             return { ok: false, error: `HTTP ${res.status}: ${res.statusText}` };
         }

package/dist/tier-engine/feature.js

@@ -200,6 +200,7 @@ export function createTierEngineFeature(opts = {}) {
                 ],
             },
             submitLabel: "tier-admin.submit",
+            successMessage: "tier-admin.success",
             cancelTarget: false,
             description: "tier-admin.screen.subtitle",
             access: { roles: ["SystemAdmin"] },

package/dist/tier-engine/i18n.js

@@ -18,5 +18,6 @@ export const TIER_ENGINE_I18N = {
     "tier-engine:entity:__action-form__:field:tenantId": { en: "Tenant" },
     "tier-engine:entity:__action-form__:field:tier": { en: "New tier" },
     "tier-admin.submit": { en: "Assign tier" },
+    "tier-admin.success": { en: "Tier assigned: {tenantId} → {tier}" },
 };
 export const defaultTranslations = translationsByLocaleFromKeys(TIER_ENGINE_I18N);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.346.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>",
@@ -503,12 +503,12 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.346.0",
-    "@cosmicdrift/kumiko-framework": "0.346.0",
-    "@cosmicdrift/kumiko-headless": "0.346.0",
-    "@cosmicdrift/kumiko-renderer": "0.346.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.346.0",
-    "@cosmicdrift/kumiko-types": "0.346.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.348.0",
+    "@cosmicdrift/kumiko-framework": "0.348.0",
+    "@cosmicdrift/kumiko-headless": "0.348.0",
+    "@cosmicdrift/kumiko-renderer": "0.348.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.348.0",
+    "@cosmicdrift/kumiko-types": "0.348.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -1025,8 +1025,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.346.0",
-    "@cosmicdrift/kumiko-locale-es": "0.346.0",
+    "@cosmicdrift/kumiko-locale-de": "0.348.0",
+    "@cosmicdrift/kumiko-locale-es": "0.348.0",
     "jsqr": "^1.4.0"
   }
 }

package/src/auth-email-password/changes.json

@@ -1,4 +1,17 @@
 [
+  {
+    "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",
+    "title": "Signup-confirm under an MFA policy returns the signup landing path and the activation screen forwards it to login as next",
+    "detail": "Signup with an MFA requirement keeps its landing path\nWhen the MFA policy asks for a factor at self-registration, `/auth/signup-confirm` now also returns the `landingPath` that `auth.postAuthLanding` resolves for the signup flow (including a claimed handover). `SignupCompleteScreen` passes it to the login link as `?next=`, so the login that follows can land where a signup without MFA would have."
+  },
   {
     "version": "0.345.0",
     "type": "fix",

package/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/src/personal-access-tokens/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.347.0",
+    "type": "improvement",
+    "title": "API-token screens hide behind the tier gate and can fall back to an upgrade screen via lockedFallbackScreen",
+    "detail": "Token screens follow the tier gate of personal-access-tokens\nThe list and mint screens carry a `visibleWhen` on the new `personal-access-tokens:query:availability` probe. For a tenant whose tier excludes the feature (`toggleable`), the dispatcher already rejected every token handler with `feature_disabled`; now the screens also show the unavailable notice instead of an empty list with a broken Create button. A new option `lockedFallbackScreen` names a screen (for example an upgrade notice) to show in its place. Without `toggleable` nothing changes: the feature stays always on."
+  },
   {
     "version": "0.336.0",
     "type": "fix",

package/src/step-dispatcher/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.347.0",
+    "type": "fix",
+    "title": "Webhook dispatch cancels the unread response body so a stalling receiver cannot hold the connection",
+    "detail": "Webhook dispatch releases the connection right after the status\nThe step-dispatcher only needs the response status, so it now cancels the unread response body instead of leaving the socket open until the 10 s request timeout fires."
+  },
   {
     "version": "0.346.0",
     "type": "fix",