@cosmicdrift/kumiko-bundled-features 0.124.0 → 0.125.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.124.0",
+  "version": "0.125.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>",
@@ -19,13 +19,18 @@
   },
   "exports": {
     "./audit": "./src/audit/index.ts",
+    "./audit/web": "./src/audit/web/index.ts",
+    "./admin-shell": "./src/admin-shell/index.ts",
+    "./admin-shell/web": "./src/admin-shell/web/index.ts",
     "./compliance-profiles": "./src/compliance-profiles/index.ts",
+    "./compliance-profiles/web": "./src/compliance-profiles/web/index.ts",
     "./config": "./src/config/index.ts",
     "./crypto-shredding": "./src/crypto-shredding/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",
+    "./jobs/web": "./src/jobs/web/index.ts",
     "./tier-engine": "./src/tier-engine/index.ts",
     "./tier-engine/web": "./src/tier-engine/web/index.ts",
     "./cap-counter": "./src/cap-counter/index.ts",
@@ -55,6 +60,7 @@
     "./user-data-rights-defaults": "./src/user-data-rights-defaults/index.ts",
     "./tenant": "./src/tenant/index.ts",
     "./tenant/constants": "./src/tenant/constants.ts",
+    "./tenant/web": "./src/tenant/web/index.ts",
     "./tenant/seeding": "./src/tenant/seeding.ts",
     "./tenant/testing": "./src/tenant/testing.ts",
     "./user": "./src/user/index.ts",
@@ -68,6 +74,7 @@
     "./auth-email-password/testing": "./src/auth-email-password/testing.ts",
     "./auth-email-password/web": "./src/auth-email-password/web/index.ts",
     "./delivery": "./src/delivery/index.ts",
+    "./delivery/web": "./src/delivery/web/index.ts",
     "./channel-in-app": "./src/channel-in-app/index.ts",
     "./channel-email": "./src/channel-email/index.ts",
     "./channel-push": "./src/channel-push/index.ts",
@@ -81,6 +88,7 @@
     "./personal-access-tokens": "./src/personal-access-tokens/index.ts",
     "./personal-access-tokens/web": "./src/personal-access-tokens/web/index.ts",
     "./feature-toggles": "./src/feature-toggles/index.ts",
+    "./feature-toggles/web": "./src/feature-toggles/web/index.ts",
     "./text-content": "./src/text-content/index.ts",
     "./text-content/seeding": "./src/text-content/seeding.ts",
     "./text-content/web": "./src/text-content/web/index.ts",
@@ -98,11 +106,11 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.124.0",
-    "@cosmicdrift/kumiko-framework": "0.124.0",
-    "@cosmicdrift/kumiko-headless": "0.124.0",
-    "@cosmicdrift/kumiko-renderer": "0.124.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.124.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.125.0",
+    "@cosmicdrift/kumiko-framework": "0.125.0",
+    "@cosmicdrift/kumiko-headless": "0.125.0",
+    "@cosmicdrift/kumiko-renderer": "0.125.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.125.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/nodemailer": "^8.0.0",

package/src/admin-shell/__tests__/admin-shell-security.integration.test.ts

@@ -0,0 +1,199 @@
+// Security integration: workspace role gates + HTTP 403 on platform queries for TenantAdmin.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  access,
+  createRegistry,
+  type SessionUser,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createAuditFeature } from "../../audit/feature";
+import { hashPassword } from "../../auth-email-password/password-hashing";
+import { ConfigQueries } from "../../config/constants";
+import { createConfigFeature } from "../../config/feature";
+import { createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { createFeatureTogglesFeature } from "../../feature-toggles/feature";
+import { globalFeatureStateTable } from "../../feature-toggles/global-feature-state-table";
+import { JobQueries } from "../../jobs/constants";
+import { createJobsFeature } from "../../jobs/feature";
+import { jobRunLogsTable, jobRunsTable } from "../../jobs/job-run-table";
+import { TenantQueries } from "../../tenant/constants";
+import { createTenantFeature } from "../../tenant/feature";
+import { tenantInvitationEntity } from "../../tenant/invitation-table";
+import { tenantMembershipsTable } from "../../tenant/membership-table";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { seedTenant, seedTenantMembership } from "../../tenant/seeding";
+import { tierEngineFeature } from "../../tier-engine/feature";
+import { createUserFeature } from "../../user/feature";
+import { userEntity } from "../../user/schema/user";
+import { seedUser } from "../../user/seeding";
+import {
+  ADMIN_SHELL_FEATURE,
+  DEFAULT_PLATFORM_WORKSPACE_ID,
+  DEFAULT_TENANT_WORKSPACE_ID,
+} from "../constants";
+import { createAdminShellFeature } from "../feature";
+import {
+  TENANT_OVERVIEW_ALLOWED_QUERIES,
+  TENANT_OVERVIEW_FORBIDDEN_QUERIES,
+} from "../overview-allowlist";
+
+let stack: TestStack;
+let TENANT_ID: TenantId;
+let tenantAdminId: string;
+
+const adminShell = createAdminShellFeature();
+const features = [
+  createConfigFeature(),
+  createUserFeature(),
+  createTenantFeature(),
+  createAuditFeature(),
+  createJobsFeature(),
+  createFeatureTogglesFeature(),
+  tierEngineFeature,
+  adminShell,
+];
+
+function tenantAdmin(): SessionUser {
+  return { id: tenantAdminId, tenantId: TENANT_ID, roles: ["TenantAdmin"] };
+}
+
+function regularUser(): SessionUser {
+  return { id: tenantAdminId, tenantId: TENANT_ID, roles: ["User"] };
+}
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features,
+    extraContext: () => ({ configResolver: createConfigResolver() }),
+  });
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafeCreateEntityTable(stack.db, tenantInvitationEntity);
+  await unsafePushTables(stack.db, {
+    configValuesTable,
+    tenantMembershipsTable,
+    globalFeatureStateTable,
+    jobRunsTable,
+    jobRunLogsTable,
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+  TENANT_ID = crypto.randomUUID() as TenantId;
+  await seedTenant(stack.db, {
+    id: TENANT_ID,
+    key: `t-${TENANT_ID.slice(0, 8)}`,
+    name: "Shell Tenant",
+  });
+  ({ id: tenantAdminId } = await seedUser(stack.db, {
+    email: `ta-${TENANT_ID.slice(0, 8)}@example.com`,
+    displayName: "Tenant Admin",
+    passwordHash: await hashPassword("pw-shell-ta-1234"),
+    emailVerified: true,
+  }));
+  await seedTenantMembership(stack.db, {
+    userId: tenantAdminId,
+    tenantId: TENANT_ID,
+    roles: ["TenantAdmin"],
+  });
+});
+
+describe("workspace access matrix", () => {
+  test("tenant workspace is access.admin; platform is SystemAdmin-only", () => {
+    const registry = createRegistry(features);
+    const tenantWs = registry.getWorkspace(
+      `${ADMIN_SHELL_FEATURE}:workspace:${DEFAULT_TENANT_WORKSPACE_ID}`,
+    );
+    const platformWs = registry.getWorkspace(
+      `${ADMIN_SHELL_FEATURE}:workspace:${DEFAULT_PLATFORM_WORKSPACE_ID}`,
+    );
+    expect(tenantWs?.access).toEqual({ roles: access.admin });
+    expect(platformWs?.access).toEqual({ roles: access.systemAdmin });
+  });
+});
+
+describe("TenantAdmin HTTP surface", () => {
+  test("can list members and audit for own tenant", async () => {
+    const members = await stack.http.queryOk<readonly unknown[]>(
+      TenantQueries.members,
+      {},
+      tenantAdmin(),
+    );
+    expect(members.some((m) => (m as { userId: string }).userId === tenantAdminId)).toBe(true);
+    const audit = await stack.http.queryOk<{ rows: readonly unknown[] }>(
+      "audit:query:list",
+      {},
+      tenantAdmin(),
+    );
+    expect(Array.isArray(audit.rows)).toBe(true);
+  });
+
+  test("403 on platform jobs:list and tenant:list", async () => {
+    expect((await stack.http.query(JobQueries.list, {}, tenantAdmin())).status).toBe(403);
+    expect((await stack.http.query(TenantQueries.list, {}, tenantAdmin())).status).toBe(403);
+  });
+});
+
+describe("regular User denied tenant-admin nav data", () => {
+  test("403 on members and audit", async () => {
+    expect((await stack.http.query(TenantQueries.members, {}, regularUser())).status).toBe(403);
+    expect((await stack.http.query("audit:query:list", {}, regularUser())).status).toBe(403);
+  });
+});
+
+describe("SystemAdmin platform queries", () => {
+  test("can list tenants and job runs", async () => {
+    const tenants = await stack.http.queryOk<{ rows: readonly unknown[] }>(
+      TenantQueries.list,
+      {},
+      TestUsers.systemAdmin,
+    );
+    expect(tenants.rows.length).toBeGreaterThanOrEqual(1);
+    const jobs = await stack.http.queryOk<{ rows: readonly unknown[] }>(
+      JobQueries.list,
+      {},
+      TestUsers.systemAdmin,
+    );
+    expect(Array.isArray(jobs.rows)).toBe(true);
+  });
+});
+
+describe("tenant overview query allowlist", () => {
+  test("static allowlist excludes every forbidden platform query", () => {
+    for (const qn of TENANT_OVERVIEW_FORBIDDEN_QUERIES) {
+      expect(TENANT_OVERVIEW_ALLOWED_QUERIES).not.toContain(qn);
+    }
+  });
+
+  test("TenantAdmin can run tenant-overview allowed queries", async () => {
+    await stack.http.queryOk(TenantQueries.invitations, {}, tenantAdmin());
+    await stack.http.queryOk(TenantQueries.members, {}, tenantAdmin());
+    const readiness = await stack.http.queryOk<{ missing: readonly unknown[] }>(
+      ConfigQueries.readiness,
+      {},
+      tenantAdmin(),
+    );
+    expect(Array.isArray(readiness.missing)).toBe(true);
+  });
+
+  test("TenantAdmin gets 403 on every forbidden overview query", async () => {
+    for (const qn of TENANT_OVERVIEW_FORBIDDEN_QUERIES) {
+      expect((await stack.http.query(qn, {}, tenantAdmin())).status).toBe(403);
+    }
+  });
+});

package/src/admin-shell/__tests__/admin-shell.boot.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, test } from "bun:test";
+import { access, createRegistry, validateBoot } from "@cosmicdrift/kumiko-framework/engine";
+import { createAuditFeature } from "../../audit/feature";
+import { createConfigFeature } from "../../config/feature";
+import { createJobsFeature } from "../../jobs/feature";
+import { createTenantFeature } from "../../tenant/feature";
+import { tierEngineFeature } from "../../tier-engine/feature";
+import {
+  ADMIN_SHELL_FEATURE,
+  DEFAULT_PLATFORM_WORKSPACE_ID,
+  DEFAULT_TENANT_WORKSPACE_ID,
+} from "../constants";
+import { createAdminShellFeature } from "../feature";
+
+const features = [
+  createConfigFeature(),
+  createTenantFeature(),
+  createAuditFeature(),
+  createJobsFeature(),
+  tierEngineFeature,
+  createAdminShellFeature(),
+];
+
+describe("admin-shell boot + workspace composition", () => {
+  test("validateBoot with tenant, audit, jobs, tier-engine", () => {
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
+  test("registers tenant + platform workspaces with qualified ids", () => {
+    const registry = createRegistry(features);
+    expect(
+      registry.getWorkspace(`${ADMIN_SHELL_FEATURE}:workspace:${DEFAULT_TENANT_WORKSPACE_ID}`)?.id,
+    ).toBe(`${ADMIN_SHELL_FEATURE}:workspace:${DEFAULT_TENANT_WORKSPACE_ID}`);
+    expect(
+      registry.getWorkspace(`${ADMIN_SHELL_FEATURE}:workspace:${DEFAULT_PLATFORM_WORKSPACE_ID}`)
+        ?.id,
+    ).toBe(`${ADMIN_SHELL_FEATURE}:workspace:${DEFAULT_PLATFORM_WORKSPACE_ID}`);
+  });
+
+  test("tenant workspace nav references owner-feature navs", () => {
+    const registry = createRegistry(features);
+    const navs = registry.getWorkspaceNavs(
+      `${ADMIN_SHELL_FEATURE}:workspace:${DEFAULT_TENANT_WORKSPACE_ID}`,
+    );
+    expect(navs).toEqual([
+      "admin-shell:nav:tenant-overview",
+      "tenant:nav:members",
+      "audit:nav:audit-log",
+    ]);
+  });
+
+  test("platform workspace nav includes overview, tenants, jobs, tier-admin", () => {
+    const registry = createRegistry(features);
+    const navs = registry.getWorkspaceNavs(
+      `${ADMIN_SHELL_FEATURE}:workspace:${DEFAULT_PLATFORM_WORKSPACE_ID}`,
+    );
+    expect(navs).toEqual([
+      "admin-shell:nav:platform-overview",
+      "admin-shell:nav:tenants",
+      "jobs:nav:job-runs",
+      "admin-shell:nav:tier-admin",
+    ]);
+  });
+
+  test("workspace access: tenant=access.admin, platform=systemAdmin", () => {
+    const registry = createRegistry(features);
+    const tenantWs = registry.getWorkspace(
+      `${ADMIN_SHELL_FEATURE}:workspace:${DEFAULT_TENANT_WORKSPACE_ID}`,
+    );
+    const platformWs = registry.getWorkspace(
+      `${ADMIN_SHELL_FEATURE}:workspace:${DEFAULT_PLATFORM_WORKSPACE_ID}`,
+    );
+    expect(tenantWs?.access).toEqual({ roles: access.admin });
+    expect(platformWs?.access).toEqual({ roles: access.systemAdmin });
+    expect(tenantWs?.default).toBe(true);
+  });
+
+  test("custom workspace ids via options", () => {
+    const custom = createAdminShellFeature({
+      workspaceIds: { tenant: "admin", platform: "sysadmin" },
+      includeTierAdmin: false,
+    });
+    const registry = createRegistry([
+      createConfigFeature(),
+      createTenantFeature(),
+      createAuditFeature(),
+      createJobsFeature(),
+      custom,
+    ]);
+    expect(registry.getWorkspace("admin-shell:workspace:admin")?.id).toBeDefined();
+    expect(registry.getWorkspace("admin-shell:workspace:sysadmin")?.id).toBeDefined();
+    expect(registry.getWorkspaceNavs("admin-shell:workspace:sysadmin")).toEqual([
+      "admin-shell:nav:platform-overview",
+      "admin-shell:nav:tenants",
+      "jobs:nav:job-runs",
+    ]);
+  });
+
+  test("registerWorkspaces:false registers overview screens only", () => {
+    const shellOnly = createAdminShellFeature({
+      registerWorkspaces: false,
+      includeTierAdmin: false,
+    });
+    const registry = createRegistry([
+      createConfigFeature(),
+      createTenantFeature(),
+      createAuditFeature(),
+      createJobsFeature(),
+      shellOnly,
+    ]);
+    expect(
+      registry.getWorkspace(`${ADMIN_SHELL_FEATURE}:workspace:${DEFAULT_TENANT_WORKSPACE_ID}`),
+    ).toBeUndefined();
+    expect(registry.getScreen("admin-shell:screen:tenant-overview")?.id).toBeDefined();
+    expect(registry.getScreen("admin-shell:screen:platform-overview")?.id).toBeDefined();
+  });
+
+  test("admin-shell nav entries declare icons (sidebar standard)", () => {
+    const shell = createAdminShellFeature({ includeTierAdmin: true });
+    const navIds = ["tenant-overview", "platform-overview", "tenants", "tier-admin"] as const;
+    for (const id of navIds) {
+      expect(shell.navs[id]?.icon, `admin-shell:nav:${id}`).toBeDefined();
+    }
+  });
+
+  test("admin-shell registers server translations bundle", () => {
+    const shell = createAdminShellFeature();
+    expect(shell.translations?.["admin-shell:nav.tenantOverview"]?.["de"]).toBe("Übersicht");
+    expect(shell.translations?.["screen:tenant-overview.title"]?.["en"]).toBe("Overview");
+  });
+});

package/src/admin-shell/__tests__/overview-allowlist.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "bun:test";
+import { JobQueries } from "../../jobs/constants";
+import { TenantQueries } from "../../tenant/constants";
+import {
+  isOverviewQueryAllowed,
+  PLATFORM_OVERVIEW_ALLOWED_QUERIES,
+  TENANT_OVERVIEW_ALLOWED_QUERIES,
+  TENANT_OVERVIEW_FORBIDDEN_QUERIES,
+} from "../overview-allowlist";
+
+describe("overview query allowlist", () => {
+  test("tenant allowlist excludes platform-only queries", () => {
+    for (const forbidden of TENANT_OVERVIEW_FORBIDDEN_QUERIES) {
+      expect(isOverviewQueryAllowed("tenant", forbidden)).toBe(false);
+      expect(TENANT_OVERVIEW_ALLOWED_QUERIES).not.toContain(forbidden);
+    }
+  });
+
+  test("tenant allowlist includes members, invitations, readiness", () => {
+    expect(TENANT_OVERVIEW_ALLOWED_QUERIES).toContain(TenantQueries.members);
+    expect(TENANT_OVERVIEW_ALLOWED_QUERIES).toContain(TenantQueries.invitations);
+    expect(TENANT_OVERVIEW_ALLOWED_QUERIES).toContain("config:query:readiness");
+  });
+
+  test("platform allowlist is tenant:list + jobs:list only", () => {
+    expect(PLATFORM_OVERVIEW_ALLOWED_QUERIES).toEqual([TenantQueries.list, JobQueries.list]);
+  });
+
+  test("platform queries are not tenant-allowlisted", () => {
+    expect(isOverviewQueryAllowed("tenant", TenantQueries.list)).toBe(false);
+    expect(isOverviewQueryAllowed("tenant", JobQueries.list)).toBe(false);
+  });
+});

package/src/admin-shell/__tests__/overview-screens.boot.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "bun:test";
+import { access, createRegistry } from "@cosmicdrift/kumiko-framework/engine";
+import { createAuditFeature } from "../../audit/feature";
+import { createConfigFeature } from "../../config/feature";
+import { createJobsFeature } from "../../jobs/feature";
+import { createTenantFeature } from "../../tenant/feature";
+import { tierEngineFeature } from "../../tier-engine/feature";
+import { PLATFORM_OVERVIEW_SCREEN_ID, TENANT_OVERVIEW_SCREEN_ID } from "../constants";
+import { createAdminShellFeature } from "../feature";
+
+const features = [
+  createConfigFeature(),
+  createTenantFeature(),
+  createAuditFeature(),
+  createJobsFeature(),
+  tierEngineFeature,
+  createAdminShellFeature(),
+];
+
+describe("overview screens boot", () => {
+  test("tenant-overview screen is access.admin", () => {
+    const registry = createRegistry(features);
+    const screen = registry.getScreen(`admin-shell:screen:${TENANT_OVERVIEW_SCREEN_ID}`);
+    expect(screen?.access).toEqual({ roles: access.admin });
+    expect(screen?.type).toBe("custom");
+  });
+
+  test("platform-overview screen is SystemAdmin-only", () => {
+    const registry = createRegistry(features);
+    const screen = registry.getScreen(`admin-shell:screen:${PLATFORM_OVERVIEW_SCREEN_ID}`);
+    expect(screen?.access).toEqual({ roles: access.systemAdmin });
+  });
+});

package/src/admin-shell/constants.ts

@@ -0,0 +1,11 @@
+// @runtime client
+export const ADMIN_SHELL_FEATURE = "admin-shell" as const;
+
+export const DEFAULT_TENANT_WORKSPACE_ID = "tenant-admin" as const;
+export const DEFAULT_PLATFORM_WORKSPACE_ID = "platform" as const;
+
+/** Tenant workspace home — attention cards, query-allowlisted. */
+export const TENANT_OVERVIEW_SCREEN_ID = "tenant-overview" as const;
+
+/** Platform workspace home — attention cards, query-allowlisted. */
+export const PLATFORM_OVERVIEW_SCREEN_ID = "platform-overview" as const;

package/src/admin-shell/feature.ts

@@ -0,0 +1,134 @@
+// admin-shell — role-gated workspaces + provider nav for tenant vs platform operators.
+// Screens live in owner features (tenant, audit, jobs, …); this feature only
+// composes workspaces and cross-feature nav entries.
+
+import {
+  access,
+  defineFeature,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  ADMIN_SHELL_FEATURE,
+  DEFAULT_PLATFORM_WORKSPACE_ID,
+  DEFAULT_TENANT_WORKSPACE_ID,
+  PLATFORM_OVERVIEW_SCREEN_ID,
+  TENANT_OVERVIEW_SCREEN_ID,
+} from "./constants";
+import { ADMIN_SHELL_I18N } from "./i18n";
+
+export type CreateAdminShellOptions = {
+  /** Short workspace id for tenant operators (URL segment). Default `tenant-admin`. */
+  readonly workspaceIds?: {
+    readonly tenant?: string;
+    readonly platform?: string;
+  };
+  /** Platform nav → tier-engine:screen:tier-admin. Requires tier-engine mounted. Default true. */
+  readonly includeTierAdmin?: boolean;
+  /** When false, only overview screens + nav are registered — app owns r.workspace(). Default true. */
+  readonly registerWorkspaces?: boolean;
+};
+
+export function createAdminShellFeature(options: CreateAdminShellOptions = {}): FeatureDefinition {
+  const tenantWsId = options.workspaceIds?.tenant ?? DEFAULT_TENANT_WORKSPACE_ID;
+  const platformWsId = options.workspaceIds?.platform ?? DEFAULT_PLATFORM_WORKSPACE_ID;
+  const includeTierAdmin = options.includeTierAdmin ?? true;
+  const registerWorkspaces = options.registerWorkspaces ?? true;
+
+  return defineFeature(ADMIN_SHELL_FEATURE, (r) => {
+    r.describe(
+      "Registers tenant-admin and platform-admin workspaces with provider nav into owner-feature screens (`tenant:screen:members`, `audit:screen:audit-log`, `tenant:screen:tenant-list`, `jobs:screen:job-runs`, optional `tier-engine:screen:tier-admin`). Mount after tenant, audit, and jobs; pass `workspaceIds` to match app URL conventions (e.g. Studio `d`/`s`, PublicStatus `admin`/`sysadmin`). Client: `adminShellClient()`, `tenantClient()`, `auditClient()`, `jobsClient()`, optional `tierEngineClient()`.",
+    );
+    r.uiHints({
+      displayLabel: "Admin Shell",
+      category: "operations",
+      recommended: false,
+    });
+    r.requires("tenant");
+    r.requires("audit");
+    r.requires("jobs");
+    if (includeTierAdmin) r.requires("tier-engine");
+
+    r.translations({ keys: ADMIN_SHELL_I18N });
+
+    const tenantNav = [
+      "admin-shell:nav:tenant-overview",
+      "tenant:nav:members",
+      "audit:nav:audit-log",
+    ] as const;
+    const platformNav: string[] = [
+      "admin-shell:nav:platform-overview",
+      "admin-shell:nav:tenants",
+      "jobs:nav:job-runs",
+      ...(includeTierAdmin ? (["admin-shell:nav:tier-admin"] as const) : []),
+    ];
+
+    r.screen({
+      id: TENANT_OVERVIEW_SCREEN_ID,
+      type: "custom",
+      renderer: { react: { __component: "TenantOverviewScreen" } },
+      access: { roles: access.admin },
+    });
+    r.nav({
+      id: "tenant-overview",
+      label: "admin-shell:nav.tenantOverview",
+      icon: "home",
+      screen: "admin-shell:screen:tenant-overview",
+      order: 1,
+    });
+
+    r.screen({
+      id: PLATFORM_OVERVIEW_SCREEN_ID,
+      type: "custom",
+      renderer: { react: { __component: "PlatformOverviewScreen" } },
+      access: { roles: access.systemAdmin },
+    });
+    r.nav({
+      id: "platform-overview",
+      label: "admin-shell:nav.platformOverview",
+      icon: "dashboard",
+      screen: "admin-shell:screen:platform-overview",
+      order: 1,
+    });
+
+    r.nav({
+      id: "tenants",
+      label: "admin-shell:nav.tenants",
+      icon: "building",
+      screen: "tenant:screen:tenant-list",
+      access: { roles: access.systemAdmin },
+      order: 10,
+    });
+
+    if (includeTierAdmin) {
+      r.nav({
+        id: "tier-admin",
+        label: "admin-shell:nav.tierAdmin",
+        icon: "shield",
+        screen: "tier-engine:screen:tier-admin",
+        access: { roles: access.systemAdmin },
+        order: 30,
+      });
+    }
+
+    if (registerWorkspaces) {
+      r.workspace({
+        id: tenantWsId,
+        label: "admin-shell:workspace.tenant",
+        icon: "users",
+        order: 1,
+        access: { roles: access.admin },
+        nav: [...tenantNav],
+        default: true,
+      });
+
+      r.workspace({
+        id: platformWsId,
+        label: "admin-shell:workspace.platform",
+        icon: "shield",
+        order: 2,
+        access: { roles: access.systemAdmin },
+        nav: platformNav,
+      });
+    }
+  });
+}

package/src/admin-shell/i18n.ts

@@ -0,0 +1,35 @@
+// @runtime client
+// Pure-Data i18n keys for admin-shell (server r.translations + client pivot).
+// Without these keys nav labels and workspace tabs render raw QNs in the shell.
+
+type LocalizedString = { readonly de: string; readonly en: string };
+
+export const ADMIN_SHELL_I18N: Readonly<Record<string, LocalizedString>> = {
+  "screen:tenant-overview.title": { de: "Übersicht", en: "Overview" },
+  "screen:platform-overview.title": { de: "Übersicht", en: "Overview" },
+  "admin-shell:workspace.tenant": { de: "Administration", en: "Administration" },
+  "admin-shell:workspace.platform": { de: "Plattform", en: "Platform" },
+  "admin-shell:nav.tenantOverview": { de: "Übersicht", en: "Overview" },
+  "admin-shell:nav.platformOverview": { de: "Übersicht", en: "Overview" },
+  "admin-shell:nav.tenants": { de: "Mandanten", en: "Tenants" },
+  "admin-shell:nav.tierAdmin": { de: "Tier zuweisen", en: "Assign tier" },
+  "admin-shell:overview.tenantTitle": { de: "Administration", en: "Administration" },
+  "admin-shell:overview.platformTitle": { de: "Plattform", en: "Platform" },
+  "admin-shell:overview.loading": { de: "Lade…", en: "Loading…" },
+  "admin-shell:overview.pendingInvitations": {
+    de: "Ausstehende Einladungen",
+    en: "Pending invitations",
+  },
+  "admin-shell:overview.members": { de: "Mitglieder", en: "Members" },
+  "admin-shell:overview.missingConfig": {
+    de: "Fehlende Konfiguration",
+    en: "Missing configuration",
+  },
+  "admin-shell:overview.missingConfigHint": {
+    de: "Pflichtfelder in den Einstellungen prüfen",
+    en: "Check required settings",
+  },
+  "admin-shell:overview.tenants": { de: "Mandanten", en: "Tenants" },
+  "admin-shell:overview.failedJobs": { de: "Fehlgeschlagene Jobs", en: "Failed jobs" },
+  "admin-shell:overview.failedJobsHint": { de: "Job-Runs prüfen", en: "Review job runs" },
+};

package/src/admin-shell/index.ts

@@ -0,0 +1,17 @@
+export {
+  ADMIN_SHELL_FEATURE,
+  DEFAULT_PLATFORM_WORKSPACE_ID,
+  DEFAULT_TENANT_WORKSPACE_ID,
+  PLATFORM_OVERVIEW_SCREEN_ID,
+  TENANT_OVERVIEW_SCREEN_ID,
+} from "./constants";
+export { type CreateAdminShellOptions, createAdminShellFeature } from "./feature";
+export { ADMIN_SHELL_I18N } from "./i18n";
+export {
+  isOverviewQueryAllowed,
+  type OverviewWorkspaceKind,
+  overviewAllowedQueries,
+  PLATFORM_OVERVIEW_ALLOWED_QUERIES,
+  TENANT_OVERVIEW_ALLOWED_QUERIES,
+  TENANT_OVERVIEW_FORBIDDEN_QUERIES,
+} from "./overview-allowlist";