@cosmicdrift/kumiko-testing 0.383.1 → 0.384.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-testing",
-  "version": "0.383.1",
+  "version": "0.384.0",
   "description": "Test template for Kumiko apps: per-flow seedTenant, app test stack, canonical test preloads, bunfig generator and integration runner.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -99,9 +99,9 @@
     "kumiko-testing": "./bin/kumiko-testing.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.383.1",
-    "@cosmicdrift/kumiko-guards": "0.383.1",
-    "@cosmicdrift/kumiko-types": "0.383.1",
+    "@cosmicdrift/kumiko-framework": "0.384.0",
+    "@cosmicdrift/kumiko-guards": "0.384.0",
+    "@cosmicdrift/kumiko-types": "0.384.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
@@ -125,8 +125,8 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.383.1",
-    "@cosmicdrift/kumiko-dev-server": "0.383.1",
+    "@cosmicdrift/kumiko-bundled-features": "0.384.0",
+    "@cosmicdrift/kumiko-dev-server": "0.384.0",
     "@happy-dom/global-registrator": "^20.11.2",
     "@playwright/test": "^1.62.1",
     "@testing-library/dom": "^10.4.1",

package/src/helpers/access-assertions.ts

@@ -1,4 +1,7 @@
-import type { AccessRule } from "@cosmicdrift/kumiko-framework/engine";
+import type { AccessRule, SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { AccessDeniedError } from "@cosmicdrift/kumiko-framework/errors";
+import { createTestUser } from "@cosmicdrift/kumiko-framework/seeding";
+import type { TestStack } from "../stack/test-stack.ts";
 
 // Test-only helper: extracts the role list from a role-based AccessRule,
 // narrowing the union safely. Throws when the rule is openToAll or missing —
@@ -13,3 +16,69 @@ export function rolesOf(access: AccessRule | undefined): readonly string[] {
   }
   return access.roles;
 }
+
+const PROBE_ROLE = "access-contract-probe";
+
+type CheckedHandlerCounts = { checkedWriteHandlers: number; checkedQueryHandlers: number };
+
+function isRoleRestricted(access: AccessRule | undefined): boolean {
+  return access !== undefined && "roles" in access && access.roles.length > 0;
+}
+
+async function deniedOutcome(res: Response): Promise<string | undefined> {
+  const rawBody = await res.json().catch(() => undefined);
+  const body = rawBody as { error?: { code?: unknown } | string } | undefined; // @cast-boundary engine-bridge
+  const code =
+    typeof body?.error === "object" && typeof body.error.code === "string"
+      ? body.error.code
+      : undefined;
+  if (res.status === 403 && code === ACCESS_DENIED_CODE) return undefined;
+  return `HTTP ${res.status} ${code ?? "ok"}`;
+}
+
+const ACCESS_DENIED_CODE = new AccessDeniedError().code;
+
+/**
+ * Contract test: every role-restricted write/query handler in the stack rejects
+ * a signed-in caller who holds none of its roles with 403 access_denied, over
+ * real HTTP. Roles are checked centrally before payload parsing (pre-handler
+ * gates / dispatch-query), so an empty payload is enough. openToAll handlers
+ * and handlers without access are skipped. Throws once with all deviations;
+ * `minimumHandlerCount` guards against an empty registry walk passing silently.
+ */
+export async function expectRoleRestrictedHandlersDenyForeignRole(
+  stack: Pick<TestStack, "registry" | "http">,
+  options: { minimumHandlerCount?: number; probeUser?: SessionUser } = {},
+): Promise<CheckedHandlerCounts> {
+  const probe = options.probeUser ?? createTestUser({ roles: [PROBE_ROLE] });
+  const minimumHandlerCount = options.minimumHandlerCount ?? 1;
+  const deviations: string[] = [];
+  let checkedWriteHandlers = 0;
+  let checkedQueryHandlers = 0;
+
+  for (const [handlerName, handler] of stack.registry.getAllWriteHandlers()) {
+    if (!isRoleRestricted(handler.access)) continue;
+    checkedWriteHandlers++;
+    const outcome = await deniedOutcome(await stack.http.write(handlerName, {}, probe));
+    if (outcome) deviations.push(`write ${handlerName}: ${outcome}`);
+  }
+  for (const [handlerName, handler] of stack.registry.getAllQueryHandlers()) {
+    if (!isRoleRestricted(handler.access)) continue;
+    checkedQueryHandlers++;
+    const outcome = await deniedOutcome(await stack.http.query(handlerName, {}, probe));
+    if (outcome) deviations.push(`query ${handlerName}: ${outcome}`);
+  }
+
+  const checked = checkedWriteHandlers + checkedQueryHandlers;
+  if (checked < minimumHandlerCount) {
+    throw new Error(
+      `expected at least ${minimumHandlerCount} role-restricted handlers, checked ${checked}`,
+    );
+  }
+  if (deviations.length > 0) {
+    throw new Error(
+      `${deviations.length} role-restricted handler(s) did not answer 403 ${ACCESS_DENIED_CODE}:\n${deviations.join("\n")}`,
+    );
+  }
+  return { checkedWriteHandlers, checkedQueryHandlers };
+}

package/src/helpers/boot-validator-fixture.ts

@@ -103,8 +103,14 @@ function stubTranslations(feature: FeatureDefinition): FeatureDefinition {
       Object.entries(feature.translations ?? {}).map(([key, value]) => [key, { ...value }]),
     ),
   };
+  // Stub only the locales the feature already maintains, otherwise an en-only
+  // feature would become locale-inconsistent and trip the boot check.
+  const existingLocales = new Set(Object.values(keys).flatMap((entry) => Object.keys(entry)));
+  const stubLocales = existingLocales.size > 0 ? [...existingLocales] : ["de", "en"];
   for (const key of requiredKeysFromFeature(feature)) {
-    if (keys[key] === undefined) keys[key] = { de: "stub", en: "stub" };
+    if (keys[key] === undefined) {
+      keys[key] = Object.fromEntries(stubLocales.map((locale) => [locale, "stub"]));
+    }
   }
   return { ...feature, translations: keys };
 }

package/src/helpers/index.ts

@@ -13,7 +13,7 @@ export {
   resetEventPiiCatalogForTests,
   resetPiiSubjectKmsForTests,
 } from "@cosmicdrift/kumiko-framework/internal/testing";
-export { rolesOf } from "./access-assertions.ts";
+export { expectRoleRestrictedHandlersDenyForeignRole, rolesOf } from "./access-assertions.ts";
 export { expectError, expectSuccess } from "./assertions.ts";
 export { type Barrier, createBarrier } from "./barrier.ts";
 export { withBootValidatorFixture } from "./boot-validator-fixture.ts";

package/src/preload/dom.ts

@@ -87,7 +87,7 @@ if (typeof globalThis.Element !== "undefined") {
 // test files in one process, so without afterEach, React components from
 // file N stay mounted in file N+1's DOM.
 //
-// FIVE leak sources (b is NOT cleaned here):
+// SIX leak sources (b is NOT cleaned here):
 //
 //   a) testing-library/react container: cleanup() unmounts and removes
 //      every container node render() created.
@@ -103,6 +103,8 @@ if (typeof globalThis.Element !== "undefined") {
 //   d) Radix-injected style tags in head.
 //
 //   e) window.location / history.pushState.
+//
+//   f) document.cookie.
 afterEach(() => {
   // skip: this preload module runs its own afterEach unconditionally; plain
   // unit test files (no --dom) never get happy-dom registered, so document
@@ -135,6 +137,18 @@ afterEach(() => {
     }
   }
 
+  // (f) Cookies outlive the test file (e.g. an auth test's kumiko_csrf turns
+  //     up in a later CSRF-header assertion). happy-dom deletes a cookie only
+  //     for its exact stored path, which is '' when it was set without path.
+  for (const cookie of doc.cookie.split(";")) {
+    const name = cookie.split("=")[0]?.trim();
+    if (!name) continue;
+    for (const pathAttribute of ["", "; path=/"]) {
+      // biome-ignore lint/suspicious/noDocumentCookie: happy-dom has no Cookie Store API
+      doc.cookie = `${name}=; expires=Thu, 01 Jan 1970 00:00:00 GMT${pathAttribute}`;
+    }
+  }
+
   // (e) Reset window.location to happy-dom's initial url. replaceState
   // instead of pushState, otherwise a history stack of 3000+ entries
   // accumulates across all tests (memory leak, plus it breaks tests that