@cosmicdrift/kumiko-bundled-features 0.48.1 → 0.51.0

package/src/config/__tests__/inherited-redaction.integration.test.ts

@@ -0,0 +1,180 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { createEncryptionProvider, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  type ConfigCascade,
+  createSystemConfig,
+  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 { type ConfigResolver, createConfigResolver } from "../resolver";
+import { configValuesTable } from "../table";
+
+// Proves the inheritedToTenant:false redaction end-to-end over real HTTP: a
+// tenant-side admin who is allowed to READ the key (access.admin) must never
+// receive the inherited system value through either config read handler, while
+// the SystemAdmin who owns the platform default still sees it.
+
+let stack: TestStack;
+let db: DbConnection;
+let resolver: ConfigResolver;
+
+const systemAdmin = TestUsers.systemAdmin; // roles ["SystemAdmin"]
+const tenantAdmin = createTestUser({ id: 2 }); // roles ["Admin"], same tenant
+
+const SMTP_HOST = "platform:config:smtp-host";
+const SMTP_PASS = "platform:config:smtp-pass";
+const LIST_HITS = "platform:config:list-hits";
+
+const configFeature = createConfigFeature();
+
+const platformFeature = defineFeature("platform", (r) => {
+  r.requires("config");
+  return r.config({
+    keys: {
+      // Hidden, plaintext: a tenant may read the key but not its system value.
+      smtpHost: createSystemConfig("text", {
+        inheritedToTenant: false,
+        write: access.systemAdmin,
+        read: access.admin,
+      }),
+      // Hidden + encrypted: composition — neither value nor "is set" may leak.
+      smtpPass: createSystemConfig("text", {
+        inheritedToTenant: false,
+        encrypted: true,
+        write: access.systemAdmin,
+        read: access.admin,
+      }),
+      // Control: default inheritance — a tenant sees the platform value.
+      listHits: createSystemConfig("number", {
+        default: 10,
+        write: access.systemAdmin,
+        read: access.admin,
+      }),
+    },
+  });
+});
+
+beforeAll(async () => {
+  const encryption = createEncryptionProvider(randomBytes(32).toString("base64"));
+  resolver = createConfigResolver({ encryption });
+
+  stack = await setupTestStack({
+    features: [configFeature, platformFeature],
+    extraContext: ({ registry }) => ({
+      configResolver: resolver,
+      configEncryption: encryption,
+      _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+    }),
+  });
+  db = stack.db;
+  await unsafePushTables(db, { configValuesTable });
+
+  // Seed the platform (system-row) values via the real write path.
+  await stack.http.writeOk(
+    ConfigHandlers.set,
+    { key: SMTP_HOST, value: "smtp.internal.example.com", scope: "system" },
+    systemAdmin,
+  );
+  await stack.http.writeOk(
+    ConfigHandlers.set,
+    { key: SMTP_PASS, value: "s3cr3t-password", scope: "system" },
+    systemAdmin,
+  );
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+type Cascades = Record<string, ConfigCascade>;
+const systemLevel = (c: Cascades, key: string) =>
+  c[key]?.levels.find((l) => l.source === "system-row");
+
+describe("inheritedToTenant redaction — config:query:cascade", () => {
+  test("SystemAdmin sees the inherited system value", async () => {
+    const res = await stack.http.queryOk<Cascades>(
+      ConfigQueries.cascade,
+      { keys: [SMTP_HOST] },
+      systemAdmin,
+    );
+    expect(systemLevel(res, SMTP_HOST)?.value).toBe("smtp.internal.example.com");
+    expect(res[SMTP_HOST]?.value).toBe("smtp.internal.example.com");
+  });
+
+  test("tenant-side admin gets the system value redacted (value AND hasValue)", async () => {
+    const res = await stack.http.queryOk<Cascades>(
+      ConfigQueries.cascade,
+      { keys: [SMTP_HOST] },
+      tenantAdmin,
+    );
+    const sys = systemLevel(res, SMTP_HOST);
+    expect(sys?.value).toBeUndefined();
+    expect(sys?.hasValue).toBe(false);
+    expect(res[SMTP_HOST]?.value).not.toBe("smtp.internal.example.com");
+  });
+
+  test("composition: encrypted + inheritedToTenant:false leaks neither value nor 'is set'", async () => {
+    const tenant = await stack.http.queryOk<Cascades>(
+      ConfigQueries.cascade,
+      { keys: [SMTP_PASS] },
+      tenantAdmin,
+    );
+    const tenantSys = systemLevel(tenant, SMTP_PASS);
+    expect(tenantSys?.value).toBeUndefined(); // not even the "••••••" mask
+    expect(tenantSys?.hasValue).toBe(false);
+
+    // SystemAdmin still sees it as set, value hidden by encryption masking.
+    const sa = await stack.http.queryOk<Cascades>(
+      ConfigQueries.cascade,
+      { keys: [SMTP_PASS] },
+      systemAdmin,
+    );
+    const saSys = systemLevel(sa, SMTP_PASS);
+    expect(saSys?.value).toBe("••••••");
+    expect(saSys?.hasValue).toBe(true);
+  });
+
+  test("control: a transparently-inherited system key stays visible to tenants", async () => {
+    const res = await stack.http.queryOk<Cascades>(
+      ConfigQueries.cascade,
+      { keys: [LIST_HITS] },
+      tenantAdmin,
+    );
+    expect(res[LIST_HITS]?.value).toBe(10);
+  });
+});
+
+describe("inheritedToTenant redaction — config:query:values", () => {
+  test("SystemAdmin sees the inherited system value", async () => {
+    const res = await stack.http.queryOk<Record<string, { value: unknown; source: string }>>(
+      ConfigQueries.values,
+      {},
+      systemAdmin,
+    );
+    expect(res[SMTP_HOST]?.value).toBe("smtp.internal.example.com");
+  });
+
+  test("tenant-side admin sees the key as unset, not the inherited value", async () => {
+    const res = await stack.http.queryOk<Record<string, { value: unknown; source: string }>>(
+      ConfigQueries.values,
+      {},
+      tenantAdmin,
+    );
+    expect(res[SMTP_HOST]?.value).not.toBe("smtp.internal.example.com");
+    // No keyDef.default on SMTP_HOST → after redaction the key is genuinely
+    // unset. values.query now resolves through the cascade (same path as
+    // config:query:cascade), so the source is "missing", matching cascade.query
+    // instead of the old values.query-only synthesized "default".
+    expect(res[SMTP_HOST]?.source).toBe("missing");
+  });
+});

package/src/config/__tests__/read-redaction.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, test } from "bun:test";
+import type { ConfigCascade, ConfigCascadeLevel } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  mayViewInheritedValue,
+  redactInheritedCascade,
+  shouldRedactInherited,
+} from "../read-redaction";
+
+function level(
+  source: ConfigCascadeLevel["source"],
+  value: string | number | boolean | undefined,
+  isActive = false,
+): ConfigCascadeLevel {
+  return { label: source, source, value, isActive, hasValue: value !== undefined };
+}
+
+function cascade(levels: ConfigCascadeLevel[]): ConfigCascade {
+  const active = levels.find((l) => l.isActive);
+  return { value: active?.value, source: active?.source ?? "missing", levels };
+}
+
+describe("read-redaction — viewer predicate", () => {
+  test("only SystemAdmin may view the inherited platform value", () => {
+    expect(mayViewInheritedValue(["SystemAdmin"])).toBe(true);
+    expect(mayViewInheritedValue(["Admin", "TenantAdmin"])).toBe(false);
+    expect(mayViewInheritedValue([])).toBe(false);
+  });
+
+  test("shouldRedactInherited requires inheritedToTenant:false AND a tenant-side viewer", () => {
+    expect(shouldRedactInherited({ inheritedToTenant: false }, ["Admin"])).toBe(true);
+    expect(shouldRedactInherited({ inheritedToTenant: false }, ["SystemAdmin"])).toBe(false);
+    expect(shouldRedactInherited({ inheritedToTenant: undefined }, ["Admin"])).toBe(false);
+    expect(shouldRedactInherited({ inheritedToTenant: true }, ["Admin"])).toBe(false);
+  });
+});
+
+describe("read-redaction — cascade redaction strips every inherited platform rung", () => {
+  test("strips system-row and falls through to missing", () => {
+    const out = redactInheritedCascade(
+      cascade([level("system-row", "smtp.internal", true), level("default", undefined)]),
+    );
+    const sys = out.levels.find((l) => l.source === "system-row");
+    expect(sys?.value).toBeUndefined();
+    expect(sys?.hasValue).toBe(false);
+    expect(out.value).toBeUndefined();
+    expect(out.source).toBe("missing");
+  });
+
+  test("strips the app-override rung too — the #376 leak via ENV-bridged value", () => {
+    const out = redactInheritedCascade(
+      cascade([
+        level("system-row", "secret", true),
+        level("app-override", "from-env"),
+        level("default", undefined),
+      ]),
+    );
+    // The platform env value must NOT become the new winner.
+    expect(out.value).toBeUndefined();
+    expect(out.source).toBe("missing");
+    expect(out.levels.find((l) => l.source === "app-override")?.value).toBeUndefined();
+    expect(out.levels.find((l) => l.source === "app-override")?.hasValue).toBe(false);
+  });
+
+  test("strips computed and static default rungs", () => {
+    const out = redactInheritedCascade(
+      cascade([
+        level("system-row", "sys", true),
+        level("computed", "plan-derived"),
+        level("default", "schema-default"),
+      ]),
+    );
+    expect(out.value).toBeUndefined();
+    expect(out.source).toBe("missing");
+    expect(out.levels.find((l) => l.source === "computed")?.hasValue).toBe(false);
+    expect(out.levels.find((l) => l.source === "default")?.hasValue).toBe(false);
+  });
+
+  test("a tenant's own override survives; every platform rung is hidden", () => {
+    const out = redactInheritedCascade(
+      cascade([
+        level("tenant-row", "tenant-value", true),
+        level("system-row", "platform-default"),
+        level("app-override", "from-env"),
+        level("default", "schema-default"),
+      ]),
+    );
+    expect(out.value).toBe("tenant-value");
+    expect(out.source).toBe("tenant-row");
+    expect(out.levels.find((l) => l.source === "tenant-row")?.isActive).toBe(true);
+    for (const source of ["system-row", "app-override", "default"] as const) {
+      expect(out.levels.find((l) => l.source === source)?.hasValue).toBe(false);
+    }
+  });
+
+  test("a user's own override survives over tenant-row", () => {
+    const out = redactInheritedCascade(
+      cascade([
+        level("user-row", "user-value", true),
+        level("tenant-row", "tenant-value"),
+        level("system-row", "platform"),
+      ]),
+    );
+    expect(out.value).toBe("user-value");
+    expect(out.source).toBe("user-row");
+    expect(out.levels.find((l) => l.source === "tenant-row")?.value).toBe("tenant-value");
+  });
+
+  test("no-op when no platform rung carries a value", () => {
+    const input = cascade([level("tenant-row", "x", true), level("default", undefined)]);
+    expect(redactInheritedCascade(input)).toEqual(input);
+  });
+});

package/src/config/__tests__/settings-hub-feature-name.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, test } from "bun:test";
+import { SETTINGS_HUB_FEATURE } from "@cosmicdrift/kumiko-framework/engine";
+import { CONFIG_FEATURE } from "../constants";
+
+// Cross-package pin: buildAppSchema merges the generated Settings-Hub into the
+// FeatureSchema named SETTINGS_HUB_FEATURE. The framework hard-codes that name
+// because it cannot import bundled-features (dependency points the other way).
+// This test lives where BOTH constants are visible — if the config feature is
+// ever renamed, the hub would silently land in a phantom feature; this fails first.
+describe("Settings-Hub feature-name pin", () => {
+  test("framework's SETTINGS_HUB_FEATURE equals the config feature's name", () => {
+    expect(SETTINGS_HUB_FEATURE).toBe(CONFIG_FEATURE);
+  });
+});

package/src/config/constants.ts

@@ -1,4 +1,6 @@
-// Feature name
+// @runtime client
+// Pure name/string constants — browser-safe, importable from web client code
+// (configClient() pins its feature name to CONFIG_FEATURE).
 export const CONFIG_FEATURE = "config" as const;
 
 // Qualified write handler names (QN format: scope:type:name)

package/src/config/feature.ts

@@ -4,6 +4,7 @@ import {
   type ConfigAccessorFactory,
   type ConfigKeyHandle,
   type ConfigKeyType,
+  type ConfigSecretsReader,
   type ConfigValue,
   defineFeature,
   type FeatureDefinition,
@@ -59,6 +60,7 @@ export function createConfigAccessor(
   tenantId: TenantId,
   userId: string,
   db: DbConnection | TenantDb,
+  secrets?: ConfigSecretsReader,
 ): ConfigAccessor {
   async function configAccessor(
     qualifiedKey: string,
@@ -72,7 +74,7 @@ export function createConfigAccessor(
     const qualifiedKey = typeof keyOrHandle === "string" ? keyOrHandle : keyOrHandle.name;
     const keyDef = registry.getConfigKey(qualifiedKey);
     if (!keyDef) return undefined;
-    return resolver.get(qualifiedKey, keyDef, tenantId, userId, db);
+    return resolver.get(qualifiedKey, keyDef, tenantId, userId, db, secrets);
   }
   return configAccessor;
 }
@@ -83,7 +85,8 @@ export function createConfigAccessorFactory(
   registry: Registry,
   resolver: ConfigResolver,
 ): ConfigAccessorFactory {
-  return ({ user, db }) => createConfigAccessor(registry, resolver, user.tenantId, user.id, db);
+  return ({ user, db, secrets }) =>
+    createConfigAccessor(registry, resolver, user.tenantId, user.id, db, secrets);
 }
 
 // Single point of truth for "this handler needs the resolver". Throws a

package/src/config/handlers/cascade.query.ts

@@ -5,6 +5,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { requireConfigResolver } from "../feature";
+import { redactInheritedCascade, shouldRedactInherited } from "../read-redaction";
 import { hasConfigAccess } from "../write-helpers";
 
 const MASKED = "••••••";
@@ -43,14 +44,24 @@ export const cascadeQuery = defineQueryHandler({
       query.user.tenantId,
       query.user.id,
       db,
+      ctx.secrets,
     );
 
     const result: Record<string, ConfigCascade> = {};
-    for (const [key, cascade] of cascades) {
+    for (const [key, rawCascade] of cascades) {
       const keyDef = keyDefs.get(key);
       if (!keyDef) continue;
 
-      if (keyDef.encrypted) {
+      // Redact the inherited platform value (system-row, app-override,
+      // computed, default) BEFORE masking — masking alone leaves hasValue=true
+      // and would still leak "it is set" to a tenant.
+      const cascade = shouldRedactInherited(keyDef, query.user.roles)
+        ? redactInheritedCascade(rawCascade)
+        : rawCascade;
+
+      // backing="secrets" is masked like encrypted — the resolver revealed the
+      // plaintext for internal reads, but it must never reach the cascade UI.
+      if (keyDef.encrypted || keyDef.backing === "secrets") {
         const maskedLevels: ConfigCascadeLevel[] = cascade.levels.map((l) => ({
           ...l,
           value: l.hasValue ? MASKED : l.value,

package/src/config/handlers/readiness.query.ts

@@ -98,6 +98,7 @@ export async function collectMissingRequiredConfig(
     user.tenantId,
     user.id,
     ctx.db,
+    ctx.secrets,
   );
   for (const [qualifiedKey, keyDef] of candidates) {
     const value = cascades.get(qualifiedKey)?.value;

package/src/config/handlers/reset.write.ts

@@ -1,5 +1,10 @@
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
-import { ConfigScopes, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  ConfigScopes,
+  defineWriteHandler,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { configValueEntity, configValuesTable } from "../table";
 import { findConfigRow, prepareConfigWrite } from "../write-helpers";
@@ -28,7 +33,23 @@ export const resetWrite = defineWriteHandler({
       scope: event.payload.scope,
     });
     if (!prep.ok) return prep.failure;
-    const { scope, tenantId, userId } = prep;
+    const { keyDef, scope, tenantId, userId } = prep;
+
+    // backing="secrets": clear the secret from the secrets store. delete() is
+    // idempotent (returns false if absent) — mirrors the config no-op contract.
+    if (keyDef.backing === "secrets") {
+      if (!ctx.secrets) {
+        throw new InternalError({
+          message:
+            `[config:write:reset] key "${event.payload.key}" declares backing="secrets" but ` +
+            `ctx.secrets is not wired — provide extraContext.secrets (and a MasterKeyProvider).`,
+        });
+      }
+      await ctx.secrets.delete(SYSTEM_TENANT_ID, event.payload.key, {
+        deletedBy: event.user.id,
+      });
+      return { isSuccess: true, data: { key: event.payload.key, scope } };
+    }
 
     const existing = await findConfigRow(db, event.payload.key, tenantId, userId);
 

package/src/config/handlers/set.write.ts

@@ -1,6 +1,10 @@
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
-import { ConfigScopes, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
-import { writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  ConfigScopes,
+  defineWriteHandler,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { requireConfigEncryption } from "../feature";
 import { configValueEntity, configValuesTable } from "../table";
@@ -8,6 +12,7 @@ import {
   findConfigRow,
   prepareConfigWrite,
   validateBounds,
+  validatePattern,
   validateScope,
   validateType,
 } from "../write-helpers";
@@ -52,6 +57,35 @@ export const setWrite = defineWriteHandler({
     const boundsError = validateBounds(event.payload.value, keyDef);
     if (boundsError) return writeFailure(boundsError);
 
+    const patternError = validatePattern(event.payload.value, keyDef);
+    if (patternError) return writeFailure(patternError);
+
+    // backing="secrets": persist into the secrets store (system tenant, own
+    // envelope encryption + audit) instead of config_values. Same JSON
+    // serialization as a config row so the read path round-trips via
+    // deserializeValue. system-scope is guaranteed by the boot-guard.
+    if (keyDef.backing === "secrets") {
+      if (!ctx.secrets) {
+        throw new InternalError({
+          message:
+            `[config:write:set] key "${event.payload.key}" declares backing="secrets" but ` +
+            `ctx.secrets is not wired — provide extraContext.secrets (and a MasterKeyProvider).`,
+        });
+      }
+      await ctx.secrets.set(
+        SYSTEM_TENANT_ID,
+        event.payload.key,
+        JSON.stringify(event.payload.value),
+        {
+          updatedBy: event.user.id,
+        },
+      );
+      return {
+        isSuccess: true,
+        data: { key: event.payload.key, value: event.payload.value, scope },
+      };
+    }
+
     let serialized = JSON.stringify(event.payload.value);
     if (keyDef.encrypted) {
       const encryption = requireConfigEncryption(ctx, "config:write:set");

package/src/config/handlers/values.query.ts

@@ -1,13 +1,16 @@
 import {
+  type ConfigKeyDefinition,
   type ConfigScope,
   type ConfigValueSource,
   defineQueryHandler,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { requireConfigResolver } from "../feature";
-import { deserializeValue } from "../resolver";
+import { redactInheritedCascade, shouldRedactInherited } from "../read-redaction";
 import { hasConfigAccess } from "../write-helpers";
 
+const MASKED = "••••••";
+
 export const valuesQuery = defineQueryHandler({
   name: "values",
   schema: z.object({}),
@@ -19,7 +22,25 @@ export const valuesQuery = defineQueryHandler({
     const resolver = requireConfigResolver(ctx, "config:query:values");
 
     const allKeys = registry.getAllConfigKeys();
-    const storedValues = await resolver.getAllWithSource(query.user.tenantId, query.user.id, db);
+    const keyDefs = new Map<string, ConfigKeyDefinition>();
+    const filteredKeys: string[] = [];
+    for (const [qualifiedKey, keyDef] of allKeys) {
+      if (!hasConfigAccess(keyDef.access.read, query.user.roles)) continue;
+      keyDefs.set(qualifiedKey, keyDef);
+      filteredKeys.push(qualifiedKey);
+    }
+
+    // Resolve through the full cascade (rows → app-override → computed →
+    // default) — the same path as config:query:cascade — so the mask shows the
+    // inherited default (e.g. an ENV-bridged app-override), not only DB rows.
+    const cascades = await resolver.getCascadeBatch(
+      filteredKeys,
+      keyDefs,
+      query.user.tenantId,
+      query.user.id,
+      db,
+      ctx.secrets,
+    );
 
     const result: Record<
       string,
@@ -30,22 +51,27 @@ export const valuesQuery = defineQueryHandler({
       }
     > = {};
 
-    for (const [qualifiedKey, keyDef] of allKeys) {
-      if (!hasConfigAccess(keyDef.access.read, query.user.roles)) continue;
+    for (const [qualifiedKey, keyDef] of keyDefs) {
+      const rawCascade = cascades.get(qualifiedKey);
+      if (!rawCascade) continue;
 
-      const stored = storedValues.get(qualifiedKey);
-      let value: string | number | boolean | undefined;
-      const source: ConfigValueSource = stored?.source ?? "default";
+      // Redact inherited platform rungs BEFORE masking — masking alone leaves
+      // a value present and would leak "it is set" to a tenant-side viewer.
+      const cascade = shouldRedactInherited(keyDef, query.user.roles)
+        ? redactInheritedCascade(rawCascade)
+        : rawCascade;
 
-      if (keyDef.encrypted) {
-        value = stored ? "••••••" : undefined;
-      } else if (stored?.value !== null && stored?.value !== undefined) {
-        value = deserializeValue(stored.value, keyDef.type);
+      // backing="secrets" carries a credential — mask it like an encrypted
+      // key so the plaintext (which the resolver revealed for internal reads)
+      // never reaches the UI response.
+      let value: string | number | boolean | undefined;
+      if (keyDef.encrypted || keyDef.backing === "secrets") {
+        value = cascade.value !== undefined ? MASKED : undefined;
       } else {
-        value = keyDef.default;
+        value = cascade.value;
       }
 
-      result[qualifiedKey] = { value, scope: keyDef.scope, source };
+      result[qualifiedKey] = { value, scope: keyDef.scope, source: cascade.source };
     }
 
     return result;

package/src/config/index.ts

@@ -21,7 +21,7 @@ export {
   collectMissingRequiredConfig,
 } from "./handlers/readiness.query";
 export type { AppConfigOverrides, ConfigResolver } from "./resolver";
-export { createConfigResolver, validateAppOverrides } from "./resolver";
+export { buildEnvConfigOverrides, createConfigResolver, validateAppOverrides } from "./resolver";
 export { configValuesTable } from "./table";
 
 // Boot helper for runDevApp / runProdApp: pulls every ConfigSeedDef from

package/src/config/read-redaction.ts

@@ -0,0 +1,54 @@
+import type {
+  ConfigCascade,
+  ConfigCascadeLevel,
+  ConfigKeyDefinition,
+  ConfigValueSource,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+const SYSTEM_ADMIN_ROLE = "SystemAdmin";
+
+// The viewer's own cascade rungs. Every other rung (system-row, app-override,
+// computed, default) carries a platform-inherited value — for an
+// inheritedToTenant:false key those must stay hidden from a tenant-side viewer.
+const OWN_SOURCES: ReadonlySet<ConfigValueSource> = new Set(["user-row", "tenant-row"]);
+
+// A SystemAdmin owns the platform-level values and may always see them. Every
+// other viewer (TenantAdmin, User) is tenant-side — for an
+// inheritedToTenant:false key they must learn neither the inherited platform
+// value nor that it is set.
+export function mayViewInheritedValue(roles: readonly string[]): boolean {
+  return roles.includes(SYSTEM_ADMIN_ROLE);
+}
+
+export function shouldRedactInherited(
+  keyDef: Pick<ConfigKeyDefinition, "inheritedToTenant">,
+  roles: readonly string[],
+): boolean {
+  return keyDef.inheritedToTenant === false && !mayViewInheritedValue(roles);
+}
+
+// Strips every platform-inherited level (system-row, app-override, computed,
+// default — anything that is not the viewer's own user-/tenant-row) so a
+// tenant-side viewer sees an inheritedToTenant:false key as if no platform
+// value existed, then recomputes the winning level among the survivors. A
+// no-op when the cascade carries no inherited value.
+export function redactInheritedCascade(cascade: ConfigCascade): ConfigCascade {
+  let redacted = false;
+  const levels: ConfigCascadeLevel[] = cascade.levels.map((level) => {
+    if (!OWN_SOURCES.has(level.source) && level.hasValue) {
+      redacted = true;
+      return { ...level, value: undefined, hasValue: false, isActive: false };
+    }
+    return { ...level, isActive: false };
+  });
+  if (!redacted) return cascade;
+
+  for (let i = 0; i < levels.length; i++) {
+    const level = levels[i];
+    if (level?.hasValue) {
+      levels[i] = { ...level, isActive: true };
+      return { value: level.value, source: level.source, levels };
+    }
+  }
+  return { value: undefined, source: "missing", levels };
+}