@cosmicdrift/kumiko-framework 0.345.0 → 0.347.0

package/dist/api/auth-routes.js

@@ -320,6 +320,11 @@ export function createRedisLoginRateLimiter(redis, maxAttempts = 10, windowMs =
         },
     };
 }
+// A missing, malformed or non-object body reads as {} so callers answer with their own 400.
+async function readJsonObjectOrEmpty(req) {
+    const raw = await req.json().catch(() => null);
+    return raw !== null && typeof raw === "object" ? raw : {};
+}
 export function createAuthRoutes(dispatcher, jwt, config) {
     const api = new Hono();
     // Default to "lax": CSRF control comes from the double-submit token, and
@@ -708,8 +713,12 @@ export function createAuthRoutes(dispatcher, jwt, config) {
             }
             // @cast-boundary engine-payload — generic dispatcher.write result for signup-confirm
             const data = result.data;
-            if (data.kind !== "auth-session")
-                return pendingMfaStepResponse(c, data);
+            if (data.kind !== "auth-session") {
+                // No session yet, but the account and a claimed handover exist: hand
+                // the signup landing to the client so the login that follows lands
+                // where a signup without the MFA gate would have.
+                return pendingMfaStepResponse(c, data, landingPathFragment({ flow: "signup", ...data.signup }));
+            }
             // Session creation + JWT sign + cookies — see mintSessionAndRespond.
             const token = await mintSessionAndRespond(c, data.session);
             const landingPath = landingPathFragment({
@@ -935,7 +944,7 @@ export function createAuthRoutes(dispatcher, jwt, config) {
     // POST /auth/switch-tenant — switch to a different tenant
     api.post(Routes.authSwitchTenant, async (c) => {
         const user = getUser(c);
-        const body = await c.req.json();
+        const body = await readJsonObjectOrEmpty(c.req);
         // The id seeds a SYSTEM identity in resolveActiveMembership — reject anything
         // that is not a non-empty string before it gets that far.
         if (!isNonEmptyString(body.tenantId)) {
@@ -1028,15 +1037,21 @@ export function createAuthRoutes(dispatcher, jwt, config) {
     });
     return api;
 }
-function pendingMfaStepResponse(c, step) {
+function pendingMfaStepResponse(c, step, landing = {}) {
     if (step.kind === "mfa-setup-required") {
         return c.json({
             isSuccess: true,
             mfaSetupRequired: true,
             preauthSetupToken: step.preauthSetupToken,
+            ...landing,
         });
     }
-    return c.json({ isSuccess: true, mfaRequired: true, challengeToken: step.challengeToken });
+    return c.json({
+        isSuccess: true,
+        mfaRequired: true,
+        challengeToken: step.challengeToken,
+        ...landing,
+    });
 }
 // --- shared route builders for token flows ---------------------------------
 // Password-reset, email-verification and signup share the exact same request

package/dist/api/request-context.d.ts

@@ -18,6 +18,7 @@ export type RequestContextData = {
         readonly qn: string;
         readonly risk: AgentRisk;
     };
+    readonly chargedRateLimitBuckets?: Set<string>;
 };
 export declare const requestContext: {
     run<T>(data: RequestContextData, fn: () => T): T;

package/dist/api/request-context.js

@@ -29,6 +29,9 @@ export function runWithOrigin(origin, fn) {
         // The outermost dispatch wins — a nested ctx.write/writeAs must not
         // overwrite the entry handler that the irreversible-operation gate reads.
         entryHandler: current?.entryHandler ?? origin.entryHandler,
+        chargedRateLimitBuckets: current?.entryHandler
+            ? current.chargedRateLimitBuckets
+            : new Set(),
     }, fn);
 }
 // Clears entryHandler so the next dispatch inside fn becomes the new entry —

package/dist/api/routes.js

@@ -26,7 +26,7 @@ export function createApiRoutes(dispatcher, options = {}) {
     const api = new Hono();
     api.post(Routes.write, async (c) => {
         const user = getUser(c);
-        const body = await c.req.json();
+        const body = await readDispatchBody(c);
         try {
             assertPayloadDepthAllowed(body.payload);
             assertPatAllowed(user, body.type);
@@ -42,7 +42,7 @@ export function createApiRoutes(dispatcher, options = {}) {
     });
     api.post(Routes.batch, async (c) => {
         const user = getUser(c);
-        const body = await c.req.json();
+        const body = await readJsonObject(c);
         if (!Array.isArray(body.commands)) {
             // Client-shape violation → ValidationError (400, code=validation_error)
             // matches what a Zod-level schema failure would produce if /batch had
@@ -91,7 +91,7 @@ export function createApiRoutes(dispatcher, options = {}) {
     });
     api.post(Routes.query, async (c) => {
         const user = getUser(c);
-        const body = await c.req.json();
+        const body = await readDispatchBody(c);
         try {
             assertPayloadDepthAllowed(body.payload);
             assertPatAllowed(user, body.type);
@@ -104,7 +104,7 @@ export function createApiRoutes(dispatcher, options = {}) {
     });
     api.post(Routes.command, async (c) => {
         const user = getUser(c);
-        const body = await c.req.json();
+        const body = await readDispatchBody(c);
         try {
             assertPayloadDepthAllowed(body.payload);
             assertPatAllowed(user, body.type);
@@ -127,7 +127,7 @@ export function createApiRoutes(dispatcher, options = {}) {
     // queryErrorResponse instead of a flushed-200 error frame (framework#1517).
     api.post(Routes.stream, async (c) => {
         const user = getUser(c);
-        const body = await c.req.json();
+        const body = await readDispatchBody(c);
         const requestId = requestContext.get()?.requestId;
         let generator;
         try {
@@ -255,6 +255,37 @@ function payloadDepth(value, depth) {
     }
     return max;
 }
+function invalidBodyError(path, expected, received) {
+    return new ValidationError({
+        fields: [
+            {
+                path,
+                code: "invalid_type",
+                i18nKey: "errors.validation.invalid_type",
+                params: { expected, received },
+            },
+        ],
+    });
+}
+// Malformed or non-object JSON is a client error; letting c.req.json() throw
+// would surface as an unclassified 500.
+// @cast-boundary request-body — shape is validated per route right after
+async function readJsonObject(c) {
+    const raw = await c.req.json().catch(() => undefined);
+    if (raw === undefined)
+        throw invalidBodyError("body", "json", "malformed");
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw invalidBodyError("body", "object", raw === null ? "null" : typeof raw);
+    }
+    return raw;
+}
+async function readDispatchBody(c) {
+    const body = await readJsonObject(c);
+    if (typeof body.type !== "string" || body.type === "") {
+        throw invalidBodyError("type", "string", typeof body.type);
+    }
+    return { type: body.type, payload: body.payload, requestId: body.requestId };
+}
 // Rejects payloads nested deeper than MAX_PAYLOAD_DEPTH before they reach
 // per-handler Zod validation — recursive Zod parsing (and any downstream
 // jsonb serialization of custom-fields payloads) walks the same object

package/dist/api/server.js

@@ -144,19 +144,19 @@ export function buildServer(options) {
         throw new Error(`ServerOptions.instanceId / KUMIKO_INSTANCE_ID cannot equal the reserved sentinel "${SHARED_INSTANCE_SENTINEL}" — ` +
             `pick any other stable string.`);
     }
-    // Warn when we fell back to a random UUID: the default SSE system-consumer
-    // is delivery="per-instance", so every boot gets a fresh cursor-row in
-    // kumiko_event_consumers. The previous boot's row stays behind on its last
-    // cursor and pins pruneEvents (retention-guard uses MIN(lastProcessedEventId)
-    // across all shards). Without a stable KUMIKO_INSTANCE_ID this accumulates
-    // on every restart, not just scale-down. Silent when options.instanceId or
-    // KUMIKO_INSTANCE_ID is explicit — those are deliberate choices (the test
-    // suite sets KUMIKO_INSTANCE_ID="test-instance" in vitest config).
+    // Warn when we fell back to a random UUID. The built-in SSE consumer is
+    // delivery="shared" (one cursor for all pods, fw#2625), so it no longer
+    // writes a row per instance. The id still labels this process in the
+    // app.started event and in per-instance consumers (opt-in delivery), where a
+    // fresh id per boot leaves an orphaned cursor-row that pins pruneEvents
+    // (retention-guard uses MIN(lastProcessedEventId) across all shards). Silent
+    // when options.instanceId or KUMIKO_INSTANCE_ID is explicit — those are
+    // deliberate choices (the test suite sets KUMIKO_INSTANCE_ID="test-instance").
     const instanceIdWasRandom = options.instanceId === undefined && !process.env["KUMIKO_INSTANCE_ID"];
     if (instanceIdWasRandom) {
         console.warn(`[kumiko:boot] No ServerOptions.instanceId / KUMIKO_INSTANCE_ID set — generated a random UUID (${resolvedInstanceId}). ` +
-            `Per-instance consumers (SSE by default) write one cursor-row per instance; without a stable id, each restart leaves an orphaned row behind and pins events-retention on its last cursor. ` +
-            `Set KUMIKO_INSTANCE_ID to a stable value (e.g. hostname, pod name) in production.`);
+            `SSE no longer needs a per-instance cursor, but the id labels this process in the app.started event and in per-instance consumers; without a stable id each restart leaves an orphaned cursor-row behind for those and pins events-retention on its last cursor. ` +
+            `Set KUMIKO_INSTANCE_ID to the pod name (e.g. from the Kubernetes downward API metadata.name) in production.`);
     }
     // Observability — Noop by default so no call-site needs to null-check.
     // Every handler/middleware that reaches for ctx.tracer / ctx.metrics gets

package/dist/engine/steps/webhook-send.d.ts

@@ -15,10 +15,6 @@ type WebhookSendArgs = {
     readonly body?: StepResolver<unknown>;
     readonly auth?: WebhookAuth;
     readonly mode: "deferred";
-    readonly retry?: {
-        readonly times: number;
-        readonly backoff: "exponential" | "linear";
-    };
 };
 export declare function buildWebhookSendStep(args: WebhookSendArgs): StepInstance;
 export {};

package/dist/engine/steps/webhook-send.js

@@ -3,7 +3,9 @@
 //
 // Writes a `kumiko:step:dispatch-requested` event onto a fresh step-dispatch
 // stream in the current TX. The step-dispatcher subscription (bundled-feature
-// `step-dispatcher`) reads after COMMIT and performs the fetch with retry.
+// `step-dispatcher`) reads after COMMIT and performs one fetch per request;
+// a repeat only happens when the consumer redelivers the event, under the
+// same Idempotency-Key.
 import { randomUUID } from "node:crypto";
 import { defineStep } from "../define-step.js";
 import { resolveOptional, resolveRequired } from "./_resolver-utils.js";
@@ -28,7 +30,6 @@ defineStep({
                 headersJson: JSON.stringify(headers),
                 ...(body !== undefined && { bodyJson: JSON.stringify(body) }),
                 ...(args.auth && { auth: args.auth }),
-                retry: args.retry ?? { times: 3, backoff: "exponential" },
             },
         });
     },

package/dist/pipeline/dispatch-shared.js

@@ -910,12 +910,23 @@ export async function enforceRateLimit(ctx, rateLimit, handlerName, user, isSyst
             message: `Handler "${handlerName}" declares rateLimit but no RateLimitResolver is configured. Load the rate-limiting feature or remove the option.`,
         });
     }
+    // A nested dispatch re-hitting a bucket its entry dispatch already charged
+    // (e.g. a per:"ip" handler delegating via queryAs) must not cost a second token.
+    // The mark is set only after a successful enforce and includes the limit
+    // parameters: a denied or failed check never lets a later nested call through,
+    // and a nested handler with a stricter limit on the same bucket is still checked.
+    const charged = reqCtx?.chargedRateLimitBuckets;
+    const chargedKey = `${bucket.key}|${effective.limit}|${effective.windowSeconds}|${effective.cost}`;
+    // skip: this exact bucket, limit and window was already charged by the entry dispatch
+    if (charged?.has(chargedKey))
+        return;
     try {
         await context.rateLimit.enforce(bucket.key, {
             limit: effective.limit,
             windowSeconds: effective.windowSeconds,
             cost: effective.cost,
         });
+        charged?.add(chargedKey);
     }
     catch (error) {
         // Backend failure (Redis down): fail closed as 503, same as L1/L2.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.345.0",
+  "version": "0.347.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -206,8 +206,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.345.0",
-    "@cosmicdrift/kumiko-types": "0.345.0",
+    "@cosmicdrift/kumiko-http": "0.347.0",
+    "@cosmicdrift/kumiko-types": "0.347.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -223,7 +223,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.345.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.347.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.347.0",
+    "type": "fix",
+    "title": "Dispatch routes reject malformed or type-less request bodies with 400 instead of 500",
+    "detail": "Dispatch routes answer 400 for unusable request bodies\n`/api/write`, `/api/query`, `/api/command`, `/api/batch` and `/api/stream` return a validation error (400) for malformed JSON, a non-object body or a missing handler `type`. Before, those requests ended in an unclassified 500. `/api/auth/switch-tenant` treats a non-object body like a missing `tenantId`."
+  },
+  {
+    "version": "0.347.0",
+    "type": "fix",
+    "title": "Missing-instance-id warning and docs reflect shared SSE delivery and recommend the pod name",
+    "detail": "Boot warning and docs no longer claim SSE is per instance\nThe built-in SSE consumers share one cursor since fw#2625 and fw#2630. The missing-`KUMIKO_INSTANCE_ID` warning, the consumer-state comment and `docs/reference/infra-requirements.md` now say what the id is still for (the `app.started` event and per-instance consumers) and recommend the pod name."
+  },
+  {
+    "version": "0.347.0",
+    "type": "fix",
+    "title": "A request costs one rate-limit token per bucket even when the handler nests queryAs or ctx.query calls into handlers sharing that bucket",
+    "detail": "Nested dispatches no longer charge a rate-limit bucket twice\nA handler that calls `ctx.query`, `ctx.queryAs` or `ctx.write` into another handler with a limit on the same bucket (for example `per: \"ip\"`) used to cost two tokens per request. Each entry dispatch now charges a bucket once, and nested calls reuse that charge. Nested handlers that limit a different bucket are still limited, and every command of a batch still charges on its own. The public `/media` route had half its advertised limit because of this."
+  },
   {
     "version": "0.345.0",
     "type": "fix",