@cosmicdrift/kumiko-bundled-features 0.48.1 → 0.50.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.48.1",
+  "version": "0.50.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>",
@@ -21,6 +21,7 @@
     "./audit": "./src/audit/index.ts",
     "./compliance-profiles": "./src/compliance-profiles/index.ts",
     "./config": "./src/config/index.ts",
+    "./config/web": "./src/config/web/index.ts",
     "./data-retention": "./src/data-retention/index.ts",
     "./readiness": "./src/readiness/index.ts",
     "./jobs": "./src/jobs/index.ts",

package/src/auth-email-password/__tests__/signup-flow.integration.test.ts

@@ -252,4 +252,55 @@ describe("POST /api/auth/signup-confirm", () => {
     }
     expect(new Set(keys).size).toBe(3);
   });
+
+  test("bereits registrierte Email → 422 signup_email_already_registered, keine Session, kein neuer Tenant/Membership, kein Account-Takeover (#365)", async () => {
+    const email = "victim@example.com";
+    const victimPassword = "victim-original-pw-1234";
+
+    // 1. Legitimer Erst-Signup: User + Tenant + Admin-Membership entstehen.
+    const firstToken = await requestSignup(email);
+    const firstRes = await postSignupConfirm(firstToken, victimPassword);
+    expect(firstRes.status).toBe(200);
+    const firstBody = (await firstRes.json()) as { user?: { id: string } };
+    const victimUserId = firstBody.user?.id ?? "";
+    expect(victimUserId).toBeTruthy();
+
+    const userBefore = await selectMany(stack.db, userTable, { email });
+    expect(userBefore).toHaveLength(1);
+    const passwordHashBefore = userBefore[0]?.["passwordHash"];
+
+    // 2. Zweiter Signup-Versuch für DIESELBE Email mit Angreifer-Passwort.
+    //    Request bleibt always-200 (Anti-Enumeration); nach dem Burn des
+    //    ersten Tokens mintet er einen frischen.
+    const attackerToken = await requestSignup(email);
+    const attackerPassword = "attacker-chosen-pw-9999";
+    const confirmRes = await postSignupConfirm(attackerToken, attackerPassword);
+
+    // 3. Sauberer Fehler, KEINE Session (kein auth-Cookie).
+    expect(confirmRes.status).toBe(422);
+    const body = (await confirmRes.json()) as { error?: { details?: { reason?: string } } };
+    expect(body.error?.details?.reason).toBe(AuthErrors.signupEmailAlreadyRegistered);
+    expect(confirmRes.headers.get("set-cookie") ?? "").not.toContain("kumiko_auth=");
+
+    // 4. Kein neuer Tenant (auch kein verwaister), keine neue Membership.
+    const allTenants = await selectMany(stack.db, tenantTable);
+    expect(allTenants).toHaveLength(1);
+    const memberships = await selectMany(stack.db, tenantMembershipsTable, {
+      userId: victimUserId,
+    });
+    expect(memberships).toHaveLength(1);
+
+    // 5. Account nicht übernommen: ein User, Passwort-Hash unverändert (NICHT
+    //    auf das Angreifer-Passwort überschrieben).
+    const userAfter = await selectMany(stack.db, userTable, { email });
+    expect(userAfter).toHaveLength(1);
+    expect(userAfter[0]?.["passwordHash"]).toBe(passwordHashBefore);
+
+    // 6. Authority-Beweis: der bestehende Account hängt weiter am Original-
+    //    Passwort, das Angreifer-Passwort loggt nicht ein.
+    const loginVictim = await postLogin(email, victimPassword);
+    expect(loginVictim.status).toBe(200);
+    const loginAttacker = await postLogin(email, attackerPassword);
+    expect(loginAttacker.status).not.toBe(200);
+  });
 });

package/src/auth-email-password/constants.ts

@@ -60,6 +60,12 @@ export const AuthErrors = {
   // anti-enumeration-Trade-off wie reset/verify.
   invalidSignupToken: "invalid_signup_token",
   signupNotConfigured: "signup_not_configured",
+  // Self-Signup: confirm lehnt eine bereits registrierte Email ab statt den
+  // bestehenden User wiederzuverwenden (Account-Takeover, #365). KEIN
+  // anti-enumeration-collapse wie invalidSignupToken: wer hier ankommt,
+  // kontrolliert die Inbox (hat den Magic-Link), das Reveal "Email existiert"
+  // ist also keine neue Info.
+  signupEmailAlreadyRegistered: "signup_email_already_registered",
   // Invite-Flow: alle Token-Failures collapsen auf invalidInviteToken
   // (anti-enumeration). emailMismatch wenn der invitee versucht den
   // Link mit einer anderen Email zu accepten als die eingeladene.

package/src/auth-email-password/errors.ts

@@ -1,6 +1,7 @@
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { AuthErrors } from "./constants";
 
+// @wrapper-known error-helper
 export function invalidCredentials() {
   return writeFailure(
     new UnprocessableError(AuthErrors.invalidCredentials, {
@@ -9,6 +10,7 @@ export function invalidCredentials() {
   );
 }
 
+// @wrapper-known error-helper
 export function invalidInviteToken() {
   return writeFailure(
     new UnprocessableError(AuthErrors.invalidInviteToken, {
@@ -17,6 +19,7 @@ export function invalidInviteToken() {
   );
 }
 
+// @wrapper-known error-helper
 export function inviteEmailMismatch() {
   return writeFailure(
     new UnprocessableError(AuthErrors.inviteEmailMismatch, {
@@ -25,6 +28,7 @@ export function inviteEmailMismatch() {
   );
 }
 
+// @wrapper-known error-helper
 export function invalidResetToken() {
   return writeFailure(
     new UnprocessableError(AuthErrors.invalidResetToken, {
@@ -33,6 +37,7 @@ export function invalidResetToken() {
   );
 }
 
+// @wrapper-known error-helper
 export function invalidVerificationToken() {
   return writeFailure(
     new UnprocessableError(AuthErrors.invalidVerificationToken, {
@@ -41,6 +46,7 @@ export function invalidVerificationToken() {
   );
 }
 
+// @wrapper-known error-helper
 export function invalidSignupToken() {
   return writeFailure(
     new UnprocessableError(AuthErrors.invalidSignupToken, {
@@ -49,6 +55,16 @@ export function invalidSignupToken() {
   );
 }
 
+// @wrapper-known error-helper
+export function signupEmailAlreadyRegistered() {
+  return writeFailure(
+    new UnprocessableError(AuthErrors.signupEmailAlreadyRegistered, {
+      i18nKey: "auth.errors.signupEmailAlreadyRegistered",
+    }),
+  );
+}
+
+// @wrapper-known error-helper
 export function noMembership() {
   return writeFailure(
     new UnprocessableError(AuthErrors.noMembership, {
@@ -57,6 +73,7 @@ export function noMembership() {
   );
 }
 
+// @wrapper-known error-helper
 export function emailNotVerified() {
   return writeFailure(
     new UnprocessableError(AuthErrors.emailNotVerified, {
@@ -66,6 +83,7 @@ export function emailNotVerified() {
 }
 
 // retryAfterSeconds drives the login/signup UI countdown — must stay > 0.
+// @wrapper-known error-helper
 export function accountLocked(retryAfterSeconds: number) {
   return writeFailure(
     new UnprocessableError(AuthErrors.accountLocked, {
@@ -75,6 +93,7 @@ export function accountLocked(retryAfterSeconds: number) {
   );
 }
 
+// @wrapper-known error-helper
 export function accountRestricted() {
   return writeFailure(
     new UnprocessableError(AuthErrors.accountRestricted, {

package/src/auth-email-password/handlers/request-email-verification.write.ts

@@ -10,6 +10,7 @@ export type RequestEmailVerificationOptions = TokenRequestOptions;
 
 export type RequestVerificationData = TokenRequestData<"verification-requested">;
 
+// @wrapper-known semantic-alias
 export function createRequestEmailVerificationHandler(opts: RequestEmailVerificationOptions) {
   return createTokenRequestHandler(
     {

package/src/auth-email-password/handlers/request-password-reset.write.ts

@@ -12,6 +12,7 @@ export type RequestPasswordResetOptions = TokenRequestOptions;
 // the dispatcher (bypassing the framework's auth-routes).
 export type RequestResetData = TokenRequestData<"reset-requested">;
 
+// @wrapper-known semantic-alias
 export function createRequestPasswordResetHandler(opts: RequestPasswordResetOptions) {
   return createTokenRequestHandler(
     {

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

@@ -26,13 +26,13 @@ import {
   type SessionUser,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { ConflictError, InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { generateUniqueName } from "@cosmicdrift/kumiko-framework/random";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { z } from "zod";
 // kumiko-lint-ignore cross-feature-import signup-confirm reads tenants.key for slug-uniqueness check (TOCTOU + DB-unique-index zusammen)
 import { tenantTable } from "../../tenant/schema/tenant";
-import { invalidSignupToken } from "../errors";
+import { invalidSignupToken, signupEmailAlreadyRegistered } from "../errors";
 // kumiko-lint-ignore cross-feature-import provisioning needs cross-feature seeding helpers
 import { INITIAL_SIGNUP_ROLES, provisionSignupAccount } from "../seeding";
 import {
@@ -106,16 +106,26 @@ export function createSignupConfirmHandler() {
         // den Tenant-Namen + sein eigenes displayName später ändern.
         const displayName = email.split("@")[0] ?? email;
 
-        const provisioned = await provisionSignupAccount(dbConn, {
-          email,
-          password: event.payload.password,
-          displayName,
-          tenantId,
-          tenantKey,
-          // Tenant-Display-Name als Default = Email. User wechselt das im
-          // Settings-Screen. Konzept "Tenant" leakt nicht in die Signup-UI.
-          tenantName: email,
-        });
+        let provisioned: { readonly userId: string; readonly tenantId: TenantId };
+        try {
+          provisioned = await provisionSignupAccount(dbConn, {
+            email,
+            password: event.payload.password,
+            displayName,
+            tenantId,
+            tenantKey,
+            // Tenant-Display-Name als Default = Email. User wechselt das im
+            // Settings-Screen. Konzept "Tenant" leakt nicht in die Signup-UI.
+            tenantName: email,
+          });
+        } catch (err) {
+          // Email hat bereits ein Konto — provisionSignupAccount ist create-only
+          // (#365): sauberer User-Fehler, KEINE Session für den fremden Account.
+          // committed bleibt false → der burn wird im finally released (ein
+          // Retry scheitert wieder gleich, kein stale-Marker-Block).
+          if (err instanceof ConflictError) return signupEmailAlreadyRegistered();
+          throw err;
+        }
 
         // Cleanup beider Token-Lookup-Keys. Burn-Key bleibt für die
         // restliche Burn-TTL als Replay-Schutz.

package/src/auth-email-password/handlers/signup-request.write.ts

@@ -2,9 +2,10 @@
 //
 // User gibt Email ein → wir minten einen opaken Random-Token, speichern
 // ihn bidirektional in Redis (token↔email), und der Route-Layer schickt
-// die Activation-Mail. Anders als reset/verify-Flows existiert der User
-// HIER NOCH NICHT — daher kein userId-lookup, kein HMAC-signing (wofür
-// gäbe es kein Subject), kein "skip if user already exists in DB"-pattern.
+// die Activation-Mail. Anders als reset/verify-Flows machen wir HIER keinen
+// userId-Lookup und kein HMAC-signing (es gäbe kein Subject — im Normalfall
+// existiert der User noch nicht). Ob die Email bereits ein Konto hat,
+// entscheidet bewusst der Confirm-Schritt, nicht dieser.
 //
 // Resend-Idempotenz: wenn für die Email bereits ein lebender Token in
 // Redis liegt, geben wir denselben Token zurück (und refreshen TTL auf
@@ -12,13 +13,14 @@
 // Activation-Link. Erste Mail bleibt gültig — kein "old link broken"-
 // annoyance.
 //
-// Always-200 (enumeration-safe): das Response sieht für jede Email
-// gleich aus, egal ob sie schon registriert ist oder nicht. Anders als
-// reset (das ein "no-op" zurückgibt wenn User nicht existiert) gibt's
-// hier nichts zu enumerieren — eine Email kann nicht "schon registriert
-// sein" weil bei Magic-Link der User-Row erst beim Confirm entsteht.
-// Was es geben könnte: dieselbe Email versucht es zum N-ten Mal —
-// Resend-Pfad ist by-design idempotent.
+// Always-200 (enumeration-safe): das Response sieht für jede Email gleich
+// aus, egal ob sie schon registriert ist oder nicht. Eine Email KANN bereits
+// ein Konto haben (Seeding oder früherer Signup) — die Sperre dagegen sitzt
+// bewusst im Confirm-Schritt (#365): signup-confirm lehnt eine bereits
+// registrierte Email ab statt den bestehenden User wiederzuverwenden. Hier
+// bleibt's always-200 + Resend-idempotent, damit der Request-Pfad nichts
+// leakt; ein request-seitiges Unterdrücken des Links wäre Defense-in-depth,
+// aber mit Enumeration-Risiko (separat).
 
 import { generateToken } from "@cosmicdrift/kumiko-framework/api";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";

package/src/auth-email-password/i18n.ts

@@ -37,6 +37,8 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.errors.invalidVerificationToken": "Der Bestätigungs-Link ist ungültig oder abgelaufen.",
     "auth.errors.invalidSignupToken":
       "Der Aktivierungs-Link ist ungültig oder abgelaufen. Bitte fordere einen neuen an.",
+    "auth.errors.signupEmailAlreadyRegistered":
+      "Für diese E-Mail-Adresse existiert bereits ein Konto. Bitte logge dich ein oder setze dein Passwort zurück.",
     "auth.errors.unknownError": "Etwas ist schief gegangen. Bitte erneut versuchen.",
     "auth.forgotPassword.title": "Passwort zurücksetzen",
     "auth.forgotPassword.intro":
@@ -135,6 +137,8 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.errors.invalidVerificationToken": "Verification link is invalid or expired.",
     "auth.errors.invalidSignupToken":
       "Activation link is invalid or expired. Please request a new one.",
+    "auth.errors.signupEmailAlreadyRegistered":
+      "An account already exists for this email. Please sign in or reset your password.",
     "auth.errors.unknownError": "Something went wrong. Please try again.",
     "auth.forgotPassword.title": "Reset password",
     "auth.forgotPassword.intro":

package/src/auth-email-password/password-hashing.ts

@@ -17,6 +17,7 @@ const HASH_OPTIONS = {
   parallelism: 1,
 } as const;
 
+// @wrapper-known semantic-alias
 export async function hashPassword(password: string): Promise<string> {
   return argonHash(password, HASH_OPTIONS);
 }

package/src/auth-email-password/reset-token.ts

@@ -10,6 +10,7 @@ export type VerifyResult =
   | { readonly ok: true; readonly userId: string; readonly expiresAtMs: number }
   | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
 
+// @wrapper-known semantic-alias
 export function signResetToken(
   userId: string,
   ttlMinutes: number,
@@ -19,6 +20,7 @@ export function signResetToken(
   return signToken(userId, TokenPurpose.passwordReset, ttlMinutes, secret, now);
 }
 
+// @wrapper-known semantic-alias
 export function verifyResetToken(
   token: string,
   secret: string,

package/src/auth-email-password/seeding.ts

@@ -12,11 +12,15 @@
 // Damit Sample-Server und Tests keine drei sub-paths zusammensammeln
 // müssen.
 
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { ConflictError } from "@cosmicdrift/kumiko-framework/errors";
 import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
 // kumiko-lint-ignore cross-feature-import auth-tests need user+tenant seed-helpers
 import { seedTenant, seedTenantMembership } from "../tenant/seeding";
+// kumiko-lint-ignore cross-feature-import signup create-only guard reads the user projection by email
+import { userTable } from "../user/schema/user";
 // kumiko-lint-ignore cross-feature-import auth-tests need user+tenant seed-helpers
 import { seedUser } from "../user/seeding";
 import { hashPassword } from "./password-hashing";
@@ -84,10 +88,13 @@ export async function seedUserWithPassword(
  *  ein orphan-Tenant zurückbleiben (Tenant ohne User → unused row;
  *  User ohne Membership → "no_membership" beim ersten Login).
  *
- *  Nicht idempotent: ein zweiter Aufruf für dieselbe Email wirft (über
- *  seedTenant + seedUser deren idempotenz-Check sich an key/email
- *  orientiert; bei collidierenden tenantKey ist der Caller
- *  verantwortlich, einen freien zu finden — siehe generateUniqueName). */
+ *  Create-only: existiert bereits ein User mit dieser Email (Seeding oder
+ *  früherer Signup), wirft die Funktion einen ConflictError BEVOR ein Tenant
+ *  entsteht. Der Self-Signup-Pfad darf einen bestehenden User nicht still
+ *  wiederverwenden — sonst würde der Confirm-Schritt eine Session für ihn
+ *  minten (Account-Takeover, #365). `seedUser` selbst bleibt idempotent
+ *  add-only (für Bootstrap/Tests); die create-only-Garantie sitzt hier.
+ *  tenantKey-Kollisionen löst der Caller via generateUniqueName. */
 /** Default-Roles für den Self-Signup-Admin. Geteilt zwischen
  *  provisionSignupAccount (DB-write) und signup-confirm-handler
  *  (SessionUser-Konstruktion für JWT-Mint) — sonst hätten zwei
@@ -109,6 +116,14 @@ export async function provisionSignupAccount(
   db: DbConnection,
   options: ProvisionSignupAccountOptions,
 ): Promise<{ readonly userId: string; readonly tenantId: TenantId }> {
+  // Create-only-Guard VOR seedTenant: bei bereits registrierter Email hart
+  // abbrechen, sonst entstünde ein verwaister Tenant und seedUser (idempotent
+  // add-only) gäbe still die bestehende userId zurück → Confirm mintet eine
+  // Session für den fremden Account (#365).
+  const existingUser = await fetchOne(db, userTable, { email: options.email });
+  if (existingUser) {
+    throw new ConflictError({ message: "signup: email already registered" });
+  }
   await seedTenant(db, {
     id: options.tenantId,
     key: options.tenantKey,

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

@@ -43,6 +43,7 @@ export function normalizeEmail(email: string): string {
 function tokenKey(token: string): string {
   return `${TOKEN_KEY_PREFIX}${token}`;
 }
+// @wrapper-known semantic-alias
 function emailKey(email: string): string {
   return `${EMAIL_KEY_PREFIX}${normalizeEmail(email)}`;
 }

package/src/auth-email-password/verification-token.ts

@@ -9,6 +9,7 @@ export type VerifyResult =
   | { readonly ok: true; readonly userId: string; readonly expiresAtMs: number }
   | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
 
+// @wrapper-known semantic-alias
 export function signVerificationToken(
   userId: string,
   ttlMinutes: number,
@@ -18,6 +19,7 @@ export function signVerificationToken(
   return signToken(userId, TokenPurpose.emailVerification, ttlMinutes, secret, now);
 }
 
+// @wrapper-known semantic-alias
 export function verifyVerificationToken(
   token: string,
   secret: string,

package/src/billing-foundation/aggregate-id.ts

@@ -16,6 +16,7 @@ const SUBSCRIPTION_NAMESPACE = "5c3b2d1e-9a4f-4e8c-b7a3-1f8d6c2e9a4b";
  * Stripe→Mollie-Migration) appended einen neuen event auf denselben
  * Stream — selber Tenant, selber Aggregate-Stream.
  */
+// @wrapper-known uuid-domain
 export function subscriptionAggregateId(tenantId: string): string {
   return uuidv5(tenantId, SUBSCRIPTION_NAMESPACE);
 }

package/src/cap-counter/aggregate-id.ts

@@ -32,6 +32,7 @@ const CAP_COUNTER_ROLLING_NAMESPACE = "8b2ad0c6-1f3e-4f7c-9b8a-3c4d5e6f7a8b";
  * vom event-store optimistic-lock serialisiert (version_conflict bei
  * Race → Caller-side Retry).
  */
+// @wrapper-known uuid-domain
 export function capCounterAggregateId(
   tenantId: string,
   capName: string,
@@ -56,6 +57,7 @@ export function capCounterAggregateId(
  * tenantId + capName auf, erzeugt Increment-Events am stream. Race-
  * frei: der event-store hängt mit auto-incrementing version an.
  */
+// @wrapper-known uuid-domain
 export function rollingCapAggregateId(tenantId: string, capName: string): string {
   return uuidv5(`${tenantId}|${capName}`, CAP_COUNTER_ROLLING_NAMESPACE);
 }

package/src/config/__tests__/app-override-visibility.integration.test.ts

@@ -0,0 +1,143 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  type ConfigCascade,
+  createTenantConfig,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { ConfigHandlers, ConfigQueries } from "../constants";
+import { createConfigAccessorFactory, createConfigFeature } from "../feature";
+import { buildEnvConfigOverrides, createConfigResolver } from "../resolver";
+import { configValuesTable } from "../table";
+
+// Proves the ENV→app-override bridge end-to-end over real HTTP:
+//   - a transparently-inherited key (default inheritedToTenant) surfaces the
+//     ENV-bridged app-override to a tenant (the D3 fix — values.query used to
+//     fall to keyDef.default and never showed the inherited app-override);
+//   - an inheritedToTenant:false key must NOT leak the platform ENV value to a
+//     tenant-side viewer through the app-override rung (the regression guard
+//     for the #376 redaction, which previously only stripped system-row);
+//   - a tenant's own row still beats the app-override.
+
+let stack: TestStack;
+let db: DbConnection;
+
+const systemAdmin = TestUsers.systemAdmin; // roles ["SystemAdmin"]
+const tenantAdmin = createTestUser({ id: 2 }); // roles ["Admin"]
+
+const PAGE_SIZE = "appcfg:config:page-size";
+const API_BASE = "appcfg:config:api-base";
+
+const FAKE_ENV = {
+  APPCFG_PAGE_SIZE: "25",
+  APPCFG_API_BASE: "https://internal.example.com",
+};
+
+const appcfgFeature = defineFeature("appcfg", (r) => {
+  r.requires("config");
+  return r.config({
+    keys: {
+      // Transparent inheritance + ENV-bridged: a tenant sees the platform's
+      // ENV default until it sets its own value.
+      pageSize: createTenantConfig("number", {
+        env: "APPCFG_PAGE_SIZE",
+        default: 10,
+        read: access.admin,
+        write: access.admin,
+      }),
+      // inheritedToTenant:false + ENV-bridged: the platform value must stay
+      // hidden from tenant-side viewers — including via app-override.
+      apiBase: createTenantConfig("text", {
+        env: "APPCFG_API_BASE",
+        inheritedToTenant: false,
+        read: access.admin,
+        write: access.systemAdmin,
+      }),
+    },
+  });
+});
+
+type Values = Record<string, { value: unknown; source: string }>;
+type Cascades = Record<string, ConfigCascade>;
+const overrideLevel = (c: Cascades, key: string) =>
+  c[key]?.levels.find((l) => l.source === "app-override");
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [createConfigFeature(), appcfgFeature],
+    extraContext: ({ registry }) => {
+      const resolver = createConfigResolver({
+        appOverrides: buildEnvConfigOverrides(registry, FAKE_ENV),
+      });
+      return {
+        configResolver: resolver,
+        _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+      };
+    },
+  });
+  db = stack.db;
+  await unsafePushTables(db, { configValuesTable });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("ENV→app-override bridge — config:query:values", () => {
+  test("D3: a transparently-inherited key surfaces the ENV app-override, not keyDef.default", async () => {
+    const res = await stack.http.queryOk<Values>(ConfigQueries.values, {}, tenantAdmin);
+    expect(res[PAGE_SIZE]?.value).toBe(25); // number, coerced from env — not 10 (default)
+    expect(res[PAGE_SIZE]?.source).toBe("app-override");
+  });
+
+  test("leak guard: inheritedToTenant:false hides the ENV app-override from a tenant", async () => {
+    const res = await stack.http.queryOk<Values>(ConfigQueries.values, {}, tenantAdmin);
+    expect(res[API_BASE]?.value).not.toBe("https://internal.example.com");
+    expect(res[API_BASE]?.source).not.toBe("app-override");
+  });
+});
+
+describe("ENV→app-override bridge — config:query:cascade", () => {
+  test("leak guard: the app-override level is redacted for a tenant on an inheritedToTenant:false key", async () => {
+    const res = await stack.http.queryOk<Cascades>(
+      ConfigQueries.cascade,
+      { keys: [API_BASE] },
+      tenantAdmin,
+    );
+    const ov = overrideLevel(res, API_BASE);
+    expect(ov?.value).toBeUndefined();
+    expect(ov?.hasValue).toBe(false);
+    expect(res[API_BASE]?.value).not.toBe("https://internal.example.com");
+  });
+
+  test("SystemAdmin still sees the inherited ENV app-override", async () => {
+    const res = await stack.http.queryOk<Cascades>(
+      ConfigQueries.cascade,
+      { keys: [API_BASE] },
+      systemAdmin,
+    );
+    expect(overrideLevel(res, API_BASE)?.value).toBe("https://internal.example.com");
+    expect(res[API_BASE]?.value).toBe("https://internal.example.com");
+  });
+});
+
+describe("ENV→app-override bridge — precedence", () => {
+  test("a tenant's own row beats the ENV app-override", async () => {
+    await stack.http.writeOk(
+      ConfigHandlers.set,
+      { key: PAGE_SIZE, value: 50, scope: "tenant" },
+      tenantAdmin,
+    );
+    const res = await stack.http.queryOk<Values>(ConfigQueries.values, {}, tenantAdmin);
+    expect(res[PAGE_SIZE]?.value).toBe(50);
+    expect(res[PAGE_SIZE]?.source).toBe("tenant-row");
+  });
+});