@cosmicdrift/kumiko-bundled-features 0.59.1 → 0.60.1

package/src/subscription-stripe/__tests__/stripe-foundation.integration.test.ts

@@ -447,3 +447,108 @@ describe("scenario 5: runtime-secret resolution", () => {
     expect(res.status).toBe(401);
   });
 });
+
+// =============================================================================
+// Scenario 6: billing-live-Gate (#104) durch den vollen Stack.
+//
+// Die #104-Invariante (kein Live-Checkout solange billing-live nicht true) war
+// bislang nur mit gestubbter ctx.config getestet (runtime.test.ts) — kein Test
+// fuhr die Kette factory → r.config → ctx.config(handle) real durch. Eigener
+// Stack OHNE api-key/webhook-secret-Fallback, damit das Gate-Öffnen hermetisch
+// als UnconfiguredError sichtbar wird (api-key fehlt) statt in einem echten
+// Stripe-Netzwerk-Call. Ein reiner default-off-Beweis genügt nicht: er kann
+// "korrektes Handle, Wert fehlt" nicht von "falsches Handle, immer undefined"
+// trennen (beide → feature_disabled). Erst der positive Fall (billing-live via
+// config:write:set auf dem kanonischen QN setzen → Gate öffnet) beweist die
+// Handle-Resolution real.
+// =============================================================================
+
+const BILLING_LIVE_CONFIG_QN = "subscription-stripe:config:billing-live";
+
+describe("scenario 6: billing-live gate end-to-end (#104)", () => {
+  let gateStack: TestStack;
+
+  beforeAll(async () => {
+    const stripeFeature = createSubscriptionStripeFeature({ priceToTier: PRICE_TO_TIER });
+    const encryption = createEncryptionProvider(randomBytes(32).toString("base64"));
+    const resolver = createConfigResolver({ encryption });
+    const masterKeyProvider = createEnvMasterKeyProvider({
+      env: {
+        KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),
+        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+      },
+    });
+    gateStack = await setupTestStack({
+      features: [
+        createConfigFeature(),
+        createSecretsFeature(),
+        billingFoundationFeature,
+        stripeFeature,
+      ],
+      masterKeyProvider,
+      extraContext: ({ db: ctxDb, registry }) => ({
+        configResolver: resolver,
+        configEncryption: encryption,
+        _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+        secrets: createSecretsContext({ db: ctxDb, masterKeyProvider }),
+      }),
+    });
+    await createEventsTable(gateStack.db);
+    await unsafePushTables(gateStack.db, {
+      configValuesTable,
+      tenant_secrets: tenantSecretsTable,
+    });
+  });
+
+  afterAll(async () => {
+    await gateStack.cleanup();
+  });
+
+  const checkoutPayload = {
+    providerName: "stripe",
+    priceId: "price_pro_monthly",
+    successUrl: "https://app.example.com/ok",
+    cancelUrl: "https://app.example.com/cancel",
+  };
+
+  test("default-off → feature_disabled; config-flip → Gate öffnet (Handle-Resolution real)", async () => {
+    const tenantAdmin = createTestUser({
+      id: 6001,
+      tenantId: testTenantId(6001),
+      roles: ["TenantAdmin"],
+    });
+
+    // billing-live ungesetzt → Gate zu, throw VOR jedem api-key/Stripe-Schritt.
+    const closed = await gateStack.http.writeErr(
+      "billing-foundation:write:create-checkout-session",
+      checkoutPayload,
+      tenantAdmin,
+    );
+    expect(closed.code).toBe("feature_disabled");
+
+    // billing-live=true auf dem kanonischen QN setzen (was der abgeleitete
+    // Sysadmin-configEdit-Screen in prod dispatcht).
+    const sysAdmin = createTestUser({
+      id: 6002,
+      tenantId: SYSTEM_TENANT_ID,
+      roles: ["SystemAdmin"],
+    });
+    await gateStack.http.writeOk(
+      "config:write:set",
+      { key: BILLING_LIVE_CONFIG_QN, value: true, scope: "system" },
+      sysAdmin,
+    );
+
+    // Gate jetzt offen: nicht mehr feature_disabled. Der nächste Schritt
+    // (api-key-Resolution) schlägt fehl, weil weder secret noch fallback
+    // gesetzt sind → unconfigured. Wäre der billing-live-Handle falsch
+    // qualifiziert, bliebe ctx.config undefined → Fehler weiter feature_disabled.
+    const opened = await gateStack.http.writeErr(
+      "billing-foundation:write:create-checkout-session",
+      checkoutPayload,
+      tenantAdmin,
+    );
+    expect(opened.code).not.toBe("feature_disabled");
+    expect(opened.code).toBe("unconfigured");
+  });
+});

package/src/subscription-stripe/feature.ts

@@ -13,7 +13,8 @@
 //     wird er als config-Key. `mask` leitet den Sysadmin-configEdit-Screen
 //     + Settings-Hub-Nav ab — kein handgeschriebenes r.screen/r.nav in der
 //     App mehr (v2 hatte die Keys als `r.secret` + App-eigene Maske).
-//   - `subscription-stripe:config:billingLive` → **system config**
+//   - `subscription-stripe:config:billing-live` (shortKey `billingLive`,
+//     kebab-qualifiziert von r.config) → **system config**
 //     (boolean, default false). Der Master-Switch: ohne ihn darf kein
 //     checkout eine Stripe-Session erzeugen (#104-Invariante, write-side
 //     im createCheckoutSession-Gate durchgesetzt).

package/src/tags/__tests__/feature.test.ts

@@ -29,6 +29,18 @@ function queryAccess(
   return access.roles;
 }
 
+function rawWriteAccess(feature: ReturnType<typeof createTagsFeature>, nameMatch: string): unknown {
+  const entry = Object.entries(feature.writeHandlers).find(([qn]) => qn.includes(nameMatch));
+  if (!entry) throw new Error(`handler ${nameMatch} not registered`);
+  return entry[1].access;
+}
+
+function rawQueryAccess(feature: ReturnType<typeof createTagsFeature>, nameMatch: string): unknown {
+  const entry = Object.entries(feature.queryHandlers).find(([qn]) => qn.includes(nameMatch));
+  if (!entry) throw new Error(`query ${nameMatch} not registered`);
+  return entry[1].access;
+}
+
 describe("createTagsFeature shape", () => {
   test("registers tag + tag-assignment entities, 3 write-handlers, 2 query-handlers", () => {
     const feature = createTagsFeature();
@@ -75,6 +87,28 @@ describe("createTagsFeature access-options", () => {
     expect(queryAccess(feature, "tag:list")).toEqual(["Admin", "Editor"]);
     expect(queryAccess(feature, "tag-assignment:list")).toEqual(["Admin", "Editor"]);
   });
+
+  test("access:{openToAll} applies to every write- and query-path", () => {
+    const feature = createTagsFeature({ access: { openToAll: true } });
+    for (const path of ["create-tag", "assign-tag", "remove-tag"]) {
+      expect(rawWriteAccess(feature, path)).toEqual({ openToAll: true });
+    }
+    for (const query of ["tag:list", "tag-assignment:list"]) {
+      expect(rawQueryAccess(feature, query)).toEqual({ openToAll: true });
+    }
+  });
+
+  test("access takes precedence over the roles shorthand", () => {
+    const feature = createTagsFeature({ access: { openToAll: true }, roles: ["Admin"] });
+    expect(rawWriteAccess(feature, "create-tag")).toEqual({ openToAll: true });
+    expect(rawQueryAccess(feature, "tag:list")).toEqual({ openToAll: true });
+  });
+
+  test("access:{roles} threads through like the roles shorthand", () => {
+    const feature = createTagsFeature({ access: { roles: ["Owner"] } });
+    expect(writeAccess(feature, "remove-tag")).toEqual(["Owner"]);
+    expect(queryAccess(feature, "tag-assignment:list")).toEqual(["Owner"]);
+  });
 });
 
 describe("createTagPayloadSchema", () => {

package/src/tags/__tests__/tags.integration.test.ts

@@ -183,3 +183,69 @@ describe("tags integration — multi-tenant isolation", () => {
     expect(await countAssignments(otherTenant.tenantId)).toBe(0);
   });
 });
+
+// The access option must reach the runtime, not just the handler shape: a host
+// that mounts tags with openToAll lets a user WITHOUT any default tag role tag
+// freely (the exact failure that bit money-horse, whose signup users carry
+// "Admin", not "TenantAdmin"). Default-mounted tags deny that same user.
+describe("tags integration — openToAll access model", () => {
+  let openStack: TestStack;
+  // role deliberately not in DEFAULT_TAG_ROLES nor "Admin" — proves openToAll,
+  // not an accidental role match.
+  const unprivileged = createTestUser({ roles: ["Viewer"] });
+
+  beforeAll(async () => {
+    openStack = await setupTestStack({
+      features: [createTagsFeature({ access: { openToAll: true } })],
+    });
+    await unsafeCreateEntityTable(openStack.db, tagEntity);
+    await unsafeCreateEntityTable(openStack.db, tagAssignmentEntity);
+    await createEventsTable(openStack.db);
+  });
+
+  afterAll(async () => {
+    await openStack.cleanup();
+  });
+
+  test("a non-tag-role user can create, assign, list and remove", async () => {
+    const tag = await openStack.http.writeOk<{ id: string }>(
+      TagsHandlers.createTag,
+      { name: "Paket A" },
+      unprivileged,
+    );
+    await openStack.http.writeOk(
+      TagsHandlers.assignTag,
+      { tagId: tag.id, entityType: "credit", entityId: "c-1" },
+      unprivileged,
+    );
+
+    const tags = await openStack.http.queryOk<{ rows: unknown[] }>(
+      TagsQueries.tagList,
+      {},
+      unprivileged,
+    );
+    expect(tags.rows).toHaveLength(1);
+
+    const assigned = await openStack.http.queryOk<{ rows: unknown[] }>(
+      TagsQueries.assignmentList,
+      { filter: { field: "entityId", op: "eq", value: "c-1" } },
+      unprivileged,
+    );
+    expect(assigned.rows).toHaveLength(1);
+
+    await openStack.http.writeOk(
+      TagsHandlers.removeTag,
+      { tagId: tag.id, entityType: "credit", entityId: "c-1" },
+      unprivileged,
+    );
+  });
+
+  test("the SAME user is denied on a default-role-mounted feature", async () => {
+    const denied = await stack.http.writeErr(
+      TagsHandlers.createTag,
+      { name: "nope" },
+      unprivileged,
+    );
+    expect(denied.httpStatus).toBe(403);
+  });
+});

package/src/tags/constants.ts

@@ -4,6 +4,8 @@
 // Spec: kumiko-platform/docs/plans/features/tags.md
 // C#1 design: money-horse/docs/plans/cashcolt-vertragspakete.md
 
+import type { AccessRule } from "@cosmicdrift/kumiko-framework/engine";
+
 export const TAGS_FEATURE_NAME = "tags";
 
 // Qualified handler names (QN format: scope:type:name). Clients reference the
@@ -23,6 +25,13 @@ export const TagsQueries = {
 
 // Default RBAC for every tag write/read path. Tags are a low-sensitivity
 // collaboration tool, so both tenant roles may use them. Apps with their own
-// role vocabulary (e.g. "Admin"/"Editor") override via createTagsFeature({ roles })
-// — otherwise the hard-wired QNs are access_denied for their users.
+// role vocabulary (e.g. "Admin"/"Editor") override via createTagsFeature({ roles }),
+// or adopt the host's whole access model with createTagsFeature({ access }) —
+// otherwise the hard-wired QNs are access_denied for their users.
 export const DEFAULT_TAG_ROLES = ["TenantAdmin", "TenantMember"] as const;
+
+// The default access rule applied to every tag handler when the app passes
+// neither `access` nor `roles`. createTagsFeature({ access: { openToAll: true } })
+// makes tagging reachable for any authenticated tenant user — matching apps
+// whose other handlers are openToAll rather than role-gated.
+export const DEFAULT_TAG_ACCESS: AccessRule = { roles: DEFAULT_TAG_ROLES };

package/src/tags/feature.ts

@@ -17,54 +17,59 @@
 // (`wireTagsFor`), search indexing, user-data-rights anonymization.
 
 import {
+  type AccessRule,
   defineEntityListHandler,
   defineFeature,
   type FeatureRegistrar,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { DEFAULT_TAG_ROLES, TAGS_FEATURE_NAME } from "./constants";
+import { DEFAULT_TAG_ACCESS, TAGS_FEATURE_NAME } from "./constants";
 import { tagAssignmentEntity, tagEntity } from "./entity";
 import { createAssignTagHandler } from "./handlers/assign-tag.write";
 import { createCreateTagHandler } from "./handlers/create-tag.write";
 import { createRemoveTagHandler } from "./handlers/remove-tag.write";
 
-function registerTags(
-  r: FeatureRegistrar<typeof TAGS_FEATURE_NAME>,
-  roles: readonly string[],
-): void {
+function registerTags(r: FeatureRegistrar<typeof TAGS_FEATURE_NAME>, access: AccessRule): void {
   r.describe(
-    "Generic, host-agnostic tagging for any entity. Owns two event-sourced entities — the per-tenant `tag` catalog (`read_tags`) and `tag-assignment` join rows keyed by (entityType, entityId) (`read_tag_assignments`) — so tagging adds NO column to the host entity and needs no relational pivot or JOIN. Provides write-handlers `create-tag`, `assign-tag` (idempotent), `remove-tag` (idempotent) and list queries for the catalog and the assignments. Read which tags an entity has, or which entities carry a tag, by listing `tag-assignment` filtered on `entityId` or `tagId` and composing in the read-layer. Override the default tenant roles with createTagsFeature({ roles }).",
+    "Generic, host-agnostic tagging for any entity. Owns two event-sourced entities — the per-tenant `tag` catalog (`read_tags`) and `tag-assignment` join rows keyed by (entityType, entityId) (`read_tag_assignments`) — so tagging adds NO column to the host entity and needs no relational pivot or JOIN. Provides write-handlers `create-tag`, `assign-tag` (idempotent), `remove-tag` (idempotent) and list queries for the catalog and the assignments. Read which tags an entity has, or which entities carry a tag, by listing `tag-assignment` filtered on `entityId` or `tagId` and composing in the read-layer. Every path uses one access rule — adopt the host's model with createTagsFeature({ access: { openToAll: true } }) or pin roles with createTagsFeature({ roles }).",
   );
 
   r.entity("tag", tagEntity);
   r.entity("tag-assignment", tagAssignmentEntity);
 
-  r.writeHandler(createCreateTagHandler(roles));
-  r.writeHandler(createAssignTagHandler(roles));
-  r.writeHandler(createRemoveTagHandler(roles));
+  r.writeHandler(createCreateTagHandler(access));
+  r.writeHandler(createAssignTagHandler(access));
+  r.writeHandler(createRemoveTagHandler(access));
 
-  r.queryHandler(defineEntityListHandler("tag", tagEntity, { access: { roles } }));
-  r.queryHandler(
-    defineEntityListHandler("tag-assignment", tagAssignmentEntity, { access: { roles } }),
-  );
+  r.queryHandler(defineEntityListHandler("tag", tagEntity, { access }));
+  r.queryHandler(defineEntityListHandler("tag-assignment", tagAssignmentEntity, { access }));
 }
 
 export const tagsFeature = defineFeature(TAGS_FEATURE_NAME, (r) =>
-  registerTags(r, DEFAULT_TAG_ROLES),
+  registerTags(r, DEFAULT_TAG_ACCESS),
 );
 
 export type TagsFeatureOptions = {
-  /** RBAC roles for all tag write/read paths. Default ["TenantAdmin","TenantMember"].
-   *  Apps with their own role vocabulary (e.g. ["Admin","Editor"]) MUST set this,
-   *  else the hard-wired tag QNs are access_denied for their users. */
+  /** Access rule for all tag write/read paths. Default { roles: ["TenantAdmin","TenantMember"] }.
+   *  Adopt the host's model — e.g. { openToAll: true } when the host lets any
+   *  authenticated tenant user tag (like the rest of its handlers), or
+   *  { roles: ["Admin"] } for a custom role vocabulary. Takes precedence over `roles`. */
+  readonly access?: AccessRule;
+  /** Shorthand for { access: { roles } }. Ignored when `access` is set. */
   readonly roles?: readonly string[];
 };
 
+function resolveAccess(opts: TagsFeatureOptions): AccessRule {
+  if (opts.access !== undefined) return opts.access;
+  if (opts.roles !== undefined) return { roles: opts.roles };
+  return DEFAULT_TAG_ACCESS;
+}
+
 // Backwards-compat / options wrapper. Without options returns the module-level
-// singleton (no rebuild). A custom roles list builds a fresh feature-definition.
+// singleton (no rebuild). access/roles build a fresh feature-definition.
 export function createTagsFeature(opts: TagsFeatureOptions = {}): typeof tagsFeature {
-  if (opts.roles === undefined) {
+  if (opts.access === undefined && opts.roles === undefined) {
     return tagsFeature;
   }
-  const roles = opts.roles;
-  return defineFeature(TAGS_FEATURE_NAME, (r) => registerTags(r, roles));
+  const access = resolveAccess(opts);
+  return defineFeature(TAGS_FEATURE_NAME, (r) => registerTags(r, access));
 }

package/src/tags/handlers/assign-tag.write.ts

@@ -1,6 +1,6 @@
-import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { tagAssignmentAggregateId } from "../aggregate-id";
-import { DEFAULT_TAG_ROLES } from "../constants";
+import { DEFAULT_TAG_ACCESS } from "../constants";
 import { tagAssignmentExecutor } from "../executor";
 import { type AssignTagPayload, assignTagPayloadSchema } from "../schemas";
 
@@ -12,13 +12,11 @@ import { type AssignTagPayload, assignTagPayloadSchema } from "../schemas";
 // success when the assignment is already present (the requested end state). A
 // concurrent first-time race still version_conflicts (409); acceptable, since
 // assigning is a low-frequency UI action.
-export function createAssignTagHandler(
-  roles: readonly string[] = DEFAULT_TAG_ROLES,
-): WriteHandlerDef {
+export function createAssignTagHandler(access: AccessRule = DEFAULT_TAG_ACCESS): WriteHandlerDef {
   return {
     name: "assign-tag",
     schema: assignTagPayloadSchema,
-    access: { roles },
+    access,
     handler: async (event, ctx) => {
       const payload = event.payload as AssignTagPayload; // @cast-boundary engine-payload
       const id = tagAssignmentAggregateId(

package/src/tags/handlers/create-tag.write.ts

@@ -1,5 +1,5 @@
-import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
-import { DEFAULT_TAG_ROLES } from "../constants";
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { DEFAULT_TAG_ACCESS } from "../constants";
 import { tagExecutor } from "../executor";
 import { type CreateTagPayload, createTagPayloadSchema } from "../schemas";
 
@@ -8,13 +8,11 @@ import { type CreateTagPayload, createTagPayloadSchema } from "../schemas";
 // catalog is a free list and dedup is a UI concern (autocomplete from existing
 // tags). Rename/delete are deferred to a later iteration (v1 scope: create,
 // assign, remove, list).
-export function createCreateTagHandler(
-  roles: readonly string[] = DEFAULT_TAG_ROLES,
-): WriteHandlerDef {
+export function createCreateTagHandler(access: AccessRule = DEFAULT_TAG_ACCESS): WriteHandlerDef {
   return {
     name: "create-tag",
     schema: createTagPayloadSchema,
-    access: { roles },
+    access,
     handler: async (event, ctx) => {
       const payload = event.payload as CreateTagPayload; // @cast-boundary engine-payload
       return tagExecutor.create(payload, event.user, ctx.db);

package/src/tags/handlers/remove-tag.write.ts

@@ -1,19 +1,17 @@
-import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { tagAssignmentAggregateId } from "../aggregate-id";
-import { DEFAULT_TAG_ROLES } from "../constants";
+import { DEFAULT_TAG_ACCESS } from "../constants";
 import { tagAssignmentExecutor } from "../executor";
 import { type RemoveTagPayload, removeTagPayloadSchema } from "../schemas";
 
 // remove-tag — unlinks a tag from a host entity. Idempotent: removing an
 // assignment that doesn't exist is already the requested end state (not
 // assigned), so we pre-check and return success without a delete.
-export function createRemoveTagHandler(
-  roles: readonly string[] = DEFAULT_TAG_ROLES,
-): WriteHandlerDef {
+export function createRemoveTagHandler(access: AccessRule = DEFAULT_TAG_ACCESS): WriteHandlerDef {
   return {
     name: "remove-tag",
     schema: removeTagPayloadSchema,
-    access: { roles },
+    access,
     handler: async (event, ctx) => {
       const payload = event.payload as RemoveTagPayload; // @cast-boundary engine-payload
       const id = tagAssignmentAggregateId(

package/src/tags/index.ts

@@ -1,5 +1,6 @@
 export { tagAssignmentAggregateId } from "./aggregate-id";
 export {
+  DEFAULT_TAG_ACCESS,
   DEFAULT_TAG_ROLES,
   TAGS_FEATURE_NAME,
   TagsHandlers,

package/src/tier-engine/__tests__/drift.test.ts

@@ -18,6 +18,10 @@ describe("tier-engine drift pins", () => {
     expect(TierEngineHandlers.update).toBe("tier-engine:write:tier-assignment:update");
     expect(TierEngineQueries.list).toBe("tier-engine:query:tier-assignment:list");
     expect(TierEngineQueries.getActiveTier).toBe("tier-engine:query:get-active-tier");
+    // Screen↔Handler-Contract: der TierAdminScreen dispatcht exakt diese QNs.
+    expect(TierEngineHandlers.setTenantTier).toBe("tier-engine:write:set-tenant-tier");
+    expect(TierEngineQueries.getTenantTier).toBe("tier-engine:query:get-tenant-tier");
+    expect(TierEngineQueries.tierOptions).toBe("tier-engine:query:tier-options");
 
     // Every QN must start with the feature-name as scope.
     for (const qn of [...Object.values(TierEngineHandlers), ...Object.values(TierEngineQueries)]) {

package/src/tier-engine/__tests__/resolver.integration.test.ts

@@ -167,6 +167,36 @@ describe("createTierEngineFeature — per-tenant resolver", () => {
     expect(resolver(tenantA).has("feat-pro")).toBe(true);
   });
 
+  test("(4) set-tenant-tier reflects in resolver — effective gating, not just projection", async () => {
+    // Kern-Zweck von #434: ein manueller Grant muss das EFFEKTIVE Feature-Set
+    // ändern (Resolver-Cache), nicht nur die Projektion. set-tenant-tier
+    // schreibt direkt über den Executor — feuert das den postSave-Hook, der
+    // den Cache aktualisiert? Stale-Upgrade free→pro deckt den Fall ab, den
+    // der cache-miss-Fallback NICHT rettet.
+    const usage = findTierResolverUsage(features);
+    if (!usage) throw new Error("setup failure");
+    const plugin = usage.options as TierResolverPlugin;
+
+    const sysA = createTestUser({
+      id: "sys-4",
+      tenantId: tenantA,
+      roles: ["SystemAdmin", "TenantAdmin"],
+    });
+    await stack.http.writeOk("tier-engine:write:tier-assignment:create", { tier: "free" }, sysA);
+
+    const resolver = await plugin.build({ db: stack.db, registry: stack.registry });
+    expect(resolver(tenantA).has("feat-pro")).toBe(false);
+
+    // Manueller Grant via set-tenant-tier (cross-tenant-fähig, hier eigener Tenant).
+    await stack.http.writeOk(
+      "tier-engine:write:set-tenant-tier",
+      { tenantId: tenantA, tier: "pro" },
+      sysA,
+    );
+
+    expect(resolver(tenantA).has("feat-pro")).toBe(true);
+  });
+
   test("(3) SYSTEM_TENANT_ID returns union of all tier-features", async () => {
     const usage = findTierResolverUsage(features);
     if (!usage) throw new Error("setup failure");

package/src/tier-engine/__tests__/tier-engine.integration.test.ts

@@ -279,6 +279,7 @@ describe("scenario 6: access control", () => {
   });
 
   test("query handlers carry the admin-only access rule (config-level check)", () => {
+    // (siehe Scenario 7 für die set-tenant-tier/get-tenant-tier Reads)
     // Read-access is enforced by the same role-rule set on the query handler.
     // We assert the rule is registered correctly — covers regression when
     // someone changes adminAccess to openToAll without noticing.
@@ -294,3 +295,120 @@ describe("scenario 6: access control", () => {
     expect(JSON.stringify(activeTierRule)).toMatch(/SystemAdmin/);
   });
 });
+
+// --- Scenario 7: manueller cross-tenant Tier-Grant (set-tenant-tier) ---
+//
+// Kern-Sicherheitsgrenze von #434: ein SystemAdmin sitzt in seinem eigenen
+// Tenant, setzt aber das Tier eines FREMDEN Tenants — ohne Billing-Kauf.
+// Der Event muss im Stream des Ziel-Tenants landen (nicht im Admin-Tenant),
+// `source: "manual"` tragen und nur für SystemAdmin erreichbar sein.
+
+type SetTenantTierResult = { tenantId: string; tier: string; isNew: boolean };
+
+describe("scenario 7: cross-tenant manual grant", () => {
+  test("SystemAdmin sets a FOREIGN tenant's tier — lands in the target stream, source=manual", async () => {
+    const adminTenant = testTenantId(401);
+    const targetTenant = testTenantId(402);
+    const sysadmin = createTestUser({ id: 401, tenantId: adminTenant, roles: ["SystemAdmin"] });
+
+    const result = await stack.http.writeOk<SetTenantTierResult>(
+      TierEngineHandlers.setTenantTier,
+      { tenantId: targetTenant, tier: "pro" },
+      sysadmin,
+    );
+    expect(result.tenantId).toBe(targetTenant);
+    expect(result.tier).toBe("pro");
+    expect(result.isNew).toBe(true);
+
+    // Beweis, dass der Event im Ziel-Stream liegt: ein Admin IM Ziel-Tenant
+    // liest sein eigenes get-active-tier (own-tenant-scoped) und sieht "pro".
+    const targetAdmin = createTestUser({ id: 402, tenantId: targetTenant, roles: ["TenantAdmin"] });
+    const seenByTarget = await stack.http.queryOk<Record<string, unknown> | null>(
+      TierEngineQueries.getActiveTier,
+      {},
+      targetAdmin,
+    );
+    expect(seenByTarget!["tier"]).toBe("pro");
+
+    // get-tenant-tier (cross-tenant Read, SystemAdmin) liefert source=manual.
+    const grant = await stack.http.queryOk<Record<string, unknown> | null>(
+      TierEngineQueries.getTenantTier,
+      { tenantId: targetTenant },
+      sysadmin,
+    );
+    expect(grant!["tier"]).toBe("pro");
+    expect(grant!["source"]).toBe("manual");
+
+    // Der Admin-eigene Tenant bleibt unberührt — kein Tier dort geleakt.
+    const seenByAdmin = await stack.http.queryOk<Record<string, unknown> | null>(
+      TierEngineQueries.getActiveTier,
+      {},
+      sysadmin,
+    );
+    expect(seenByAdmin).toBeNull();
+  });
+
+  test("upsert is idempotent — second set updates the same aggregate (isNew:false)", async () => {
+    const sysadmin = createTestUser({
+      id: 410,
+      tenantId: testTenantId(410),
+      roles: ["SystemAdmin"],
+    });
+    const target = testTenantId(411);
+
+    const first = await stack.http.writeOk<SetTenantTierResult>(
+      TierEngineHandlers.setTenantTier,
+      { tenantId: target, tier: "pro" },
+      sysadmin,
+    );
+    expect(first.isNew).toBe(true);
+
+    const second = await stack.http.writeOk<SetTenantTierResult>(
+      TierEngineHandlers.setTenantTier,
+      { tenantId: target, tier: "business" },
+      sysadmin,
+    );
+    expect(second.isNew).toBe(false);
+    expect(second.tier).toBe("business");
+
+    const grant = await stack.http.queryOk<Record<string, unknown> | null>(
+      TierEngineQueries.getTenantTier,
+      { tenantId: target },
+      sysadmin,
+    );
+    expect(grant!["tier"]).toBe("business");
+  });
+
+  test("TenantAdmin cannot set a foreign tenant's tier — fail-closed", async () => {
+    const tenantAdmin = createTestUser({
+      id: 420,
+      tenantId: testTenantId(420),
+      roles: ["TenantAdmin"],
+    });
+
+    const error = await stack.http.writeErr(
+      TierEngineHandlers.setTenantTier,
+      { tenantId: testTenantId(421), tier: "pro" },
+      tenantAdmin,
+    );
+    expectErrorIncludes(error, "access_denied");
+  });
+
+  test("normal User cannot set a tier and cannot read get-tenant-tier", async () => {
+    const normalUser = TestUsers.user;
+
+    const writeError = await stack.http.writeErr(
+      TierEngineHandlers.setTenantTier,
+      { tenantId: testTenantId(431), tier: "pro" },
+      normalUser,
+    );
+    expectErrorIncludes(writeError, "access_denied");
+
+    const res = await stack.http.query(
+      TierEngineQueries.getTenantTier,
+      { tenantId: testTenantId(431) },
+      normalUser,
+    );
+    expect(res.status).toBe(403);
+  });
+});

package/src/tier-engine/constants.ts

@@ -1,3 +1,9 @@
+// @runtime client
+// Pure string-literal QNs/ids — von Server (feature.ts) UND Client
+// (web/tier-admin-screen, client-plugin) importiert. Als `client` markiert,
+// die im kumiko-Isolation-Modell permissivste Kategorie (runtime darf
+// client importieren, client nur client) — sonst wirft der Runtime-
+// Isolation-Guard auf den Client-Imports. Muster wie text-content/constants.
 // Feature name
 export const TIER_ENGINE_FEATURE = "tier-engine" as const;
 
@@ -6,10 +12,17 @@ export const TIER_ENGINE_FEATURE = "tier-engine" as const;
 export const TierEngineHandlers = {
   create: "tier-engine:write:tier-assignment:create",
   update: "tier-engine:write:tier-assignment:update",
+  setTenantTier: "tier-engine:write:set-tenant-tier",
 } as const;
 
 // Qualified query handler names.
 export const TierEngineQueries = {
   list: "tier-engine:query:tier-assignment:list",
   getActiveTier: "tier-engine:query:get-active-tier",
+  getTenantTier: "tier-engine:query:get-tenant-tier",
+  tierOptions: "tier-engine:query:tier-options",
 } as const;
+
+// Screen-id für den manuellen Tier-Grant-Screen. Apps referenzieren ihn
+// qualifiziert in r.nav: `tier-engine:screen:tier-admin`.
+export const TIER_ADMIN_SCREEN_ID = "tier-admin" as const;

package/src/tier-engine/entity.ts

@@ -26,5 +26,10 @@ export const tierAssignmentEntity = createEntity({
   table: "read_tier_assignments",
   fields: {
     tier: createTextField({ required: true, maxLength: 50 }),
+    // Woher das Assignment stammt: "manual" (Admin-Grant via tier-admin-Screen),
+    // "stripe" (future Billing-Sync), "default" (auto-default-on-signup-Hook).
+    // Optional für Back-Compat zu bestehenden Rows ohne source. Schützt manuelle
+    // Grants davor, von einem späteren Stripe→Tier-Sync geplättet zu werden.
+    source: createTextField({ required: false, maxLength: 20 }),
   },
 });