@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

package/src/personal-access-tokens/resolver.ts

@@ -0,0 +1,58 @@
+import type { TokenVerifier } from "@cosmicdrift/kumiko-framework/api";
+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 { Temporal } from "temporal-polyfill";
+import { hashPatToken } from "./hash";
+import { resolvePatRoles } from "./roles";
+import { apiTokenTable } from "./schema/api-token";
+import { expandScopes, type PatScopeConfig } from "./scopes";
+
+// Hot-path resolver — raw-DB like session-callbacks (a dispatcher roundtrip on
+// every request buys nothing here). Hash the bearer token, point-read the row,
+// reject revoked/expired, resolve LIVE roles, expand granted scopes into
+// allowedQns. Any failure returns null so the middleware answers a uniform 401
+// with no oracle about which check failed.
+export function createPatResolver(opts: {
+  readonly db: DbConnection;
+  readonly scopes: PatScopeConfig;
+}): TokenVerifier {
+  const { db, scopes } = opts;
+  return async (rawToken: string): Promise<SessionUser | null> => {
+    const row = await fetchOne<{
+      id: string;
+      userId: string;
+      tenantId: string;
+      scopes: string;
+      revokedAt: unknown;
+      expiresAt: { epochMilliseconds: number } | null;
+    }>(db, apiTokenTable, { tokenHash: hashPatToken(rawToken) });
+    if (!row) return null;
+    if (row.revokedAt !== null) return null;
+    if (
+      row.expiresAt &&
+      row.expiresAt.epochMilliseconds <= Temporal.Now.instant().epochMilliseconds
+    ) {
+      return null;
+    }
+    const roles = await resolvePatRoles(db, row.userId, row.tenantId);
+    if (!roles) return null;
+    const granted = parseScopeNames(row.scopes);
+    return {
+      id: row.userId,
+      // @cast-boundary db-row → branded id: stored from a valid SessionUser.tenantId at create
+      tenantId: row.tenantId as TenantId,
+      roles,
+      pat: { tokenId: row.id, scopes: granted, allowedQns: expandScopes(scopes, granted) },
+    };
+  };
+}
+
+function parseScopeNames(raw: string): string[] {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter((s): s is string => typeof s === "string") : [];
+  } catch {
+    return [];
+  }
+}

package/src/personal-access-tokens/roles.ts

@@ -0,0 +1,29 @@
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { buildSessionRoles } from "@cosmicdrift/kumiko-framework/engine";
+import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
+import { tenantMembershipsTable } from "../tenant";
+import { userTable } from "../user";
+
+// Live role resolution for a (userId, tenantId), mirroring login.write.ts:
+// global roles (users.roles) ∪ tenant-membership roles (forbidden roles
+// stripped via stripForbiddenMembershipRoles, see engine/membership-roles).
+// Resolved fresh on every PAT request — a snapshot baked at mint
+// time would keep a since-revoked admin role for the token's whole (months-long)
+// life. Returns null when the user has no membership in that tenant: removed
+// from the tenant → the PAT stops authenticating there.
+export async function resolvePatRoles(
+  db: DbConnection,
+  userId: string,
+  tenantId: string,
+): Promise<readonly string[] | null> {
+  const memberships = await selectMany<{ roles: string }>(db, tenantMembershipsTable, {
+    userId,
+    tenantId,
+  });
+  const membership = memberships[0];
+  if (!membership) return null;
+  const userRow = await fetchOne<{ roles: string | null }>(db, userTable, { id: userId });
+  const globalRoles = parseRoles(userRow?.roles ?? null);
+  return buildSessionRoles(globalRoles, parseRoles(membership.roles));
+}

package/src/personal-access-tokens/schema/api-token.ts

@@ -0,0 +1,63 @@
+import { buildEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  createEntity,
+  createTextField,
+  createTimestampField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// One row per Personal Access Token. Like store_user_sessions this is a
+// direct-write store (r.unmanagedTable): the create/revoke handlers write it and
+// the resolver point-reads it on the hot auth path. `tokenHash` is the SHA-256
+// of the plaintext (never the plaintext); the unique index on it makes the
+// resolver a single point-read. All columns are privileged-write so no user
+// request can forge ownership/scope/hash by poking a field directly — the
+// handlers mutate them via ctx.db inside the pipeline.
+export const apiTokenEntity = createEntity({
+  table: "store_api_tokens",
+  // No softDelete: revocation is its own lifecycle (revokedAt timestamp), and
+  // we keep revoked rows for the "your tokens" audit list.
+  softDelete: false,
+  fields: {
+    userId: createTextField({
+      required: true,
+      maxLength: 36,
+      access: { write: access.privileged },
+    }),
+    tenantId: createTextField({
+      required: true,
+      maxLength: 36,
+      access: { write: access.privileged },
+    }),
+    name: createTextField({
+      required: true,
+      maxLength: 120,
+      access: { write: access.privileged },
+      userOwned: { ownerField: "userId" },
+    }),
+    tokenHash: createTextField({
+      required: true,
+      maxLength: 64,
+      access: { write: access.privileged },
+    }),
+    prefix: createTextField({
+      required: true,
+      maxLength: 16,
+      access: { write: access.privileged },
+    }),
+    // JSON-encoded string[] of granted scope names — mirrors the roles-column
+    // convention (parseRoles-style text); the resolver JSON.parses it.
+    scopes: createTextField({ required: true, access: { write: access.privileged } }),
+    createdAt: createTimestampField({ required: true, access: { write: access.privileged } }),
+    expiresAt: createTimestampField({ access: { write: access.privileged } }),
+    revokedAt: createTimestampField({ access: { write: access.privileged } }),
+  },
+  indexes: [{ unique: true, columns: ["tokenHash"], name: "store_api_tokens_hash_unique" }],
+});
+
+// buildEntityTableMeta (not buildEntityTable): this is a direct-write store, so
+// the table must be a WritableTable (post ES-write-brand #742) — same as
+// sessions' userSessionTable. buildEntityTable is branded executor-only.
+export const apiTokenTable = buildEntityTableMeta("api-token", apiTokenEntity, {
+  source: "unmanaged",
+});

package/src/personal-access-tokens/scopes.ts

@@ -0,0 +1,43 @@
+// @runtime client
+// Pure scope helpers + types — client-marked so the web screen (web/) may import
+// parseGrant without pulling the feature's server runtime barrel.
+//
+// App-declared scopes — two axes, like GitHub fine-grained PATs: WHICH API
+// (the domain, keyed here) × the permission LEVEL (read vs read+write). Each
+// domain declares its read-QN globs and (optionally) its write-QN globs. A
+// domain may span features (e.g. a "miete" domain granting ledger + folders).
+export type PatScopeDef = {
+  readonly label: string;
+  readonly read: readonly string[];
+  // Omit for a read-only domain — the UI then offers only "no access" / "read".
+  readonly write?: readonly string[];
+};
+
+export type PatScopeConfig = Readonly<Record<string, PatScopeDef>>;
+
+export type PatLevel = "read" | "write";
+
+// A granted scope is the string "<domain>:<level>" (e.g. "credit:write"). The
+// domain key never contains a colon, so split on the LAST one.
+export function parseGrant(grant: string): { domain: string; level: string } | null {
+  const idx = grant.lastIndexOf(":");
+  if (idx <= 0) return null;
+  return { domain: grant.slice(0, idx), level: grant.slice(idx + 1) };
+}
+
+// Expand granted "<domain>:<level>" entries into the union of QN globs: read
+// always grants the read QNs; write additionally grants the write QNs. Unknown
+// domains contribute nothing (fail-closed — a scope dropped from config after a
+// token was minted silently loses that capability).
+export function expandScopes(config: PatScopeConfig, granted: readonly string[]): string[] {
+  const out = new Set<string>();
+  for (const grant of granted) {
+    const parsed = parseGrant(grant);
+    if (!parsed) continue;
+    const def = config[parsed.domain];
+    if (!def) continue;
+    for (const q of def.read) out.add(q);
+    if (parsed.level === "write") for (const q of def.write ?? []) out.add(q);
+  }
+  return [...out];
+}

package/src/personal-access-tokens/web/client-plugin.tsx

@@ -0,0 +1,29 @@
+// @runtime client
+// Client-feature factory for personal-access-tokens. Ships the PatTokensScreen
+// (mapped to the "api-tokens" screen id) + default translations. Apps mount it
+// in createKumikoApp({ clientFeatures: [personalAccessTokensClient()] }); the
+// server registers the screen dormant (r.screen) and the app places it via
+// r.nav.
+
+import { mergeTranslations, type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import { PAT_FEATURE, PAT_SCREEN_ID } from "../constants";
+import { defaultTranslations } from "./i18n";
+import { PatTokensScreen } from "./pat-tokens-screen";
+
+export type PersonalAccessTokensClientOptions = {
+  /** Key-wise overrides over the default bundles (de/en). */
+  readonly translations?: TranslationsByLocale;
+};
+
+export function personalAccessTokensClient(
+  options?: PersonalAccessTokensClientOptions,
+): ClientFeatureDefinition {
+  return {
+    name: PAT_FEATURE,
+    translations: mergeTranslations(defaultTranslations, options?.translations ?? {}),
+    components: {
+      [PAT_SCREEN_ID]: PatTokensScreen,
+    },
+  };
+}

package/src/personal-access-tokens/web/i18n.ts

@@ -0,0 +1,69 @@
+// @runtime client
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+
+export const defaultTranslations: TranslationsByLocale = {
+  de: {
+    "pat.title": "Personal Access Tokens",
+    "pat.create.title": "Neuen Token erstellen",
+    "pat.create.subtitle":
+      "Wähle Berechtigungen und eine Gültigkeit. Der Token wird nur einmal angezeigt.",
+    "pat.create.name": "Name",
+    "pat.create.namePlaceholder": "z. B. CLI-Automatisierung",
+    "pat.create.scopes": "Zugriff pro Bereich",
+    "pat.level.none": "Kein Zugriff",
+    "pat.level.read": "Lesen",
+    "pat.level.write": "Lesen & Schreiben",
+    "pat.create.expiry": "Gültig bis",
+    "pat.create.submit": "Token erstellen",
+    "pat.create.needName": "Bitte einen Namen vergeben.",
+    "pat.create.needScope": "Bitte mindestens eine Berechtigung wählen.",
+    "pat.expiry.30d": "30 Tage",
+    "pat.expiry.90d": "90 Tage",
+    "pat.expiry.1y": "1 Jahr",
+    "pat.expiry.never": "Unbegrenzt",
+    "pat.created.hint":
+      "Kopiere diesen Token jetzt — er wird aus Sicherheitsgründen nur dieses eine Mal angezeigt.",
+    "pat.created.copy": "Kopieren",
+    "pat.created.copied": "Kopiert ✓",
+    "pat.created.dismiss": "Fertig",
+    "pat.list.title": "Deine Tokens",
+    "pat.list.empty": "Noch keine Tokens.",
+    "pat.list.revoke": "Widerrufen",
+    "pat.list.revoked": "Widerrufen",
+    "pat.list.validUntil": "Gültig bis {date}",
+    "pat.list.neverExpires": "Unbegrenzt gültig",
+    "pat.list.created": "Erstellt {date}",
+    "pat.error.generic": "Aktion fehlgeschlagen.",
+  },
+  en: {
+    "pat.title": "Personal Access Tokens",
+    "pat.create.title": "Create a new token",
+    "pat.create.subtitle": "Pick permissions and an expiration. The token is shown only once.",
+    "pat.create.name": "Name",
+    "pat.create.namePlaceholder": "e.g. CLI automation",
+    "pat.create.scopes": "Per-API access",
+    "pat.level.none": "No access",
+    "pat.level.read": "Read",
+    "pat.level.write": "Read & write",
+    "pat.create.expiry": "Expiration",
+    "pat.create.submit": "Create token",
+    "pat.create.needName": "Please enter a name.",
+    "pat.create.needScope": "Please select at least one permission.",
+    "pat.expiry.30d": "30 days",
+    "pat.expiry.90d": "90 days",
+    "pat.expiry.1y": "1 year",
+    "pat.expiry.never": "No expiration",
+    "pat.created.hint": "Copy this token now — for security it is shown only this once.",
+    "pat.created.copy": "Copy",
+    "pat.created.copied": "Copied ✓",
+    "pat.created.dismiss": "Done",
+    "pat.list.title": "Your tokens",
+    "pat.list.empty": "No tokens yet.",
+    "pat.list.revoke": "Revoke",
+    "pat.list.revoked": "Revoked",
+    "pat.list.validUntil": "Valid until {date}",
+    "pat.list.neverExpires": "Never expires",
+    "pat.list.created": "Created {date}",
+    "pat.error.generic": "Action failed.",
+  },
+};

package/src/personal-access-tokens/web/index.ts

@@ -0,0 +1,7 @@
+// @runtime client
+export {
+  type PersonalAccessTokensClientOptions,
+  personalAccessTokensClient,
+} from "./client-plugin";
+export { defaultTranslations } from "./i18n";
+export { PatTokensScreen } from "./pat-tokens-screen";

package/src/personal-access-tokens/web/pat-tokens-screen.tsx

@@ -0,0 +1,265 @@
+// @runtime client
+// PatTokensScreen — logged-in self-service for Personal Access Tokens. Two-axis
+// scopes (like GitHub fine-grained PATs): per API domain pick a permission LEVEL
+// (no access / read / read & write). Mint → copy the plaintext ONCE → it's never
+// re-displayed. Layout follows the framework's polished-screen convention (Form
+// primitive + Tailwind), cards match the mh style. The feature registers this
+// dormant (r.screen); the app places it via r.nav.
+
+import {
+  useDispatcher,
+  usePrimitives,
+  useQuery,
+  useTranslation,
+} from "@cosmicdrift/kumiko-renderer";
+import { FormScreenShell } from "@cosmicdrift/kumiko-renderer-web";
+import { type ReactNode, useState } from "react";
+import { PatHandlers, PatQueries } from "../constants";
+import { parseGrant } from "../scopes";
+
+type ScopeDomain = { readonly name: string; readonly label: string; readonly canWrite: boolean };
+type TokenRow = {
+  readonly id: string;
+  readonly name: string;
+  readonly scopes: readonly string[];
+  readonly createdAt: string | null;
+  readonly expiresAt: string | null;
+  readonly revokedAt: string | null;
+};
+
+type Level = "none" | "read" | "write";
+type ExpiryKey = "30d" | "90d" | "1y" | "never";
+const EXPIRY_DAYS: Record<ExpiryKey, number | undefined> = {
+  "30d": 30,
+  "90d": 90,
+  "1y": 365,
+  never: undefined,
+};
+
+// Timestamps arrive as ISO strings over the JSON API — slice the date part
+// without touching the banned Date API.
+function isoDate(value: string | null): string | null {
+  return typeof value === "string" && value.length >= 10 ? value.slice(0, 10) : null;
+}
+
+export function PatTokensScreen({
+  embedded = false,
+}: {
+  readonly embedded?: boolean;
+} = {}): ReactNode {
+  const t = useTranslation();
+  const { Form, Field, Input, Button, Banner, Card, Heading } = usePrimitives();
+  const dispatcher = useDispatcher();
+
+  const scopesQuery = useQuery<readonly ScopeDomain[]>(PatQueries.availableScopes, {});
+  const listQuery = useQuery<readonly TokenRow[]>(PatQueries.mine, {});
+
+  const [name, setName] = useState("");
+  const [levels, setLevels] = useState<Readonly<Record<string, Level>>>({});
+  const [expiry, setExpiry] = useState<ExpiryKey>("90d");
+  const [minted, setMinted] = useState<{ token: string } | null>(null);
+  const [copied, setCopied] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  const domains = scopesQuery.data ?? [];
+  const tokens = listQuery.data ?? [];
+  const labelOf = (domain: string): string =>
+    domains.find((d) => d.name === domain)?.label ?? domain;
+
+  // Granted scopes = "<domain>:<level>" for every domain not set to "none".
+  const grants = (): string[] =>
+    Object.entries(levels)
+      .filter(([, l]) => l !== "none")
+      .map(([domain, l]) => `${domain}:${l}`);
+
+  const setLevel = (domain: string, level: Level): void =>
+    setLevels((cur) => ({ ...cur, [domain]: level }));
+
+  const create = async (): Promise<void> => {
+    if (name.trim() === "") return setError(t("pat.create.needName"));
+    const scopes = grants();
+    if (scopes.length === 0) return setError(t("pat.create.needScope"));
+    setBusy(true);
+    setError(null);
+    const days = EXPIRY_DAYS[expiry];
+    const res = await dispatcher.write(PatHandlers.create, {
+      name: name.trim(),
+      scopes,
+      ...(days !== undefined ? { expiresInDays: days } : {}),
+    });
+    setBusy(false);
+    if (!res.isSuccess) return setError(t("pat.error.generic"));
+    setMinted({ token: (res.data as { token: string }).token });
+    setCopied(false);
+    setName("");
+    setLevels({});
+    setExpiry("90d");
+    void listQuery.refetch?.();
+  };
+
+  const copy = async (): Promise<void> => {
+    if (!minted) return;
+    try {
+      await navigator.clipboard.writeText(minted.token);
+      setCopied(true);
+    } catch {
+      // clipboard blocked (non-secure context) — the token stays selectable in place
+    }
+  };
+
+  const revoke = async (id: string): Promise<void> => {
+    const res = await dispatcher.write(PatHandlers.revoke, { id });
+    if (!res.isSuccess) return setError(t("pat.error.generic"));
+    void listQuery.refetch?.();
+  };
+
+  // "Pages (read & write) · Tags (read) · Valid until … · Created …"
+  const meta = (row: TokenRow): string => {
+    const scopeText = row.scopes
+      .map((g) => {
+        const p = parseGrant(g);
+        if (!p) return g;
+        const lvl = p.level === "write" ? t("pat.level.write") : t("pat.level.read");
+        return `${labelOf(p.domain)} (${lvl})`;
+      })
+      .join(" · ");
+    const d = isoDate(row.expiresAt);
+    const parts = [
+      scopeText,
+      d ? t("pat.list.validUntil", { date: d }) : t("pat.list.neverExpires"),
+    ];
+    const created = isoDate(row.createdAt);
+    if (created) parts.push(t("pat.list.created", { date: created }));
+    return parts.join("  ·  ");
+  };
+
+  const content = (
+    <>
+      <Heading>{t("pat.title")}</Heading>
+
+      {minted && (
+        <Banner
+          variant="info"
+          actions={
+            <>
+              <Button variant="primary" onClick={copy}>
+                {copied ? t("pat.created.copied") : t("pat.created.copy")}
+              </Button>
+              <Button variant="secondary" onClick={() => setMinted(null)}>
+                {t("pat.created.dismiss")}
+              </Button>
+            </>
+          }
+        >
+          <div className="flex flex-col gap-2">
+            <span className="text-sm">{t("pat.created.hint")}</span>
+            <code className="block break-all rounded bg-muted px-3 py-2 font-mono text-sm">
+              {minted.token}
+            </code>
+          </div>
+        </Banner>
+      )}
+
+      {error && <Banner variant="error">{error}</Banner>}
+
+      <Form
+        title={t("pat.create.title")}
+        subtitle={t("pat.create.subtitle")}
+        onSubmit={create}
+        actions={
+          <Button type="submit" variant="primary" onClick={create} loading={busy} disabled={busy}>
+            {t("pat.create.submit")}
+          </Button>
+        }
+      >
+        <Field id="pat-name" label={t("pat.create.name")} required>
+          <Input
+            kind="text"
+            id="pat-name"
+            name="name"
+            value={name}
+            onChange={setName}
+            placeholder={t("pat.create.namePlaceholder")}
+            disabled={busy}
+          />
+        </Field>
+
+        {domains.map((d) => (
+          <Field key={d.name} id={`pat-scope-${d.name}`} label={d.label}>
+            <Input
+              kind="select"
+              id={`pat-scope-${d.name}`}
+              name={d.name}
+              value={levels[d.name] ?? "none"}
+              onChange={(v) => setLevel(d.name, v as Level)}
+              options={[
+                { value: "none", label: t("pat.level.none") },
+                { value: "read", label: t("pat.level.read") },
+                ...(d.canWrite ? [{ value: "write", label: t("pat.level.write") }] : []),
+              ]}
+              disabled={busy}
+            />
+          </Field>
+        ))}
+
+        <Field id="pat-expiry" label={t("pat.create.expiry")}>
+          <Input
+            kind="select"
+            id="pat-expiry"
+            name="expiry"
+            value={expiry}
+            onChange={(v) => setExpiry(v as ExpiryKey)}
+            options={[
+              { value: "30d", label: t("pat.expiry.30d") },
+              { value: "90d", label: t("pat.expiry.90d") },
+              { value: "1y", label: t("pat.expiry.1y") },
+              { value: "never", label: t("pat.expiry.never") },
+            ]}
+            disabled={busy}
+          />
+        </Field>
+      </Form>
+
+      <div className="flex flex-col gap-3">
+        <Heading>{t("pat.list.title")}</Heading>
+        {tokens.length === 0 && (
+          <span className="text-sm text-muted-foreground">{t("pat.list.empty")}</span>
+        )}
+        {tokens.map((row) => {
+          const revoked = row.revokedAt !== null;
+          return (
+            <Card
+              key={row.id}
+              options={{ padded: false }}
+              className={`p-4 ${revoked ? "opacity-60" : ""}`}
+            >
+              <div className="flex items-center justify-between gap-3">
+                <div className="flex min-w-0 flex-col gap-0.5">
+                  <span className="truncate text-sm font-semibold">{row.name}</span>
+                  <span className="whitespace-normal text-xs text-muted-foreground">
+                    {revoked ? t("pat.list.revoked") : meta(row)}
+                  </span>
+                </div>
+                {!revoked && (
+                  <Button variant="danger" onClick={() => revoke(row.id)}>
+                    {t("pat.list.revoke")}
+                  </Button>
+                )}
+              </div>
+            </Card>
+          );
+        })}
+      </div>
+    </>
+  );
+
+  if (embedded) {
+    return <div className="flex flex-col gap-6">{content}</div>;
+  }
+  return (
+    <FormScreenShell testId="pat-tokens-screen" maxWidth="3xl" className="flex flex-col gap-6">
+      {content}
+    </FormScreenShell>
+  );
+}

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

@@ -6,7 +6,7 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
 import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEncryptionProvider, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { access, createTenantConfig, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { createEnvMasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
@@ -18,6 +18,7 @@ import {
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
 import { createConfigFeature } from "../../config";
 import { createConfigAccessorFactory } from "../../config/feature";
 import { createConfigResolver } from "../../config/resolver";
@@ -133,8 +134,8 @@ let stack: TestStack;
 let db: DbConnection;
 
 beforeAll(async () => {
-  const encryption = createEncryptionProvider(randomBytes(32).toString("base64"));
-  const resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(randomBytes(32).toString("base64"));
+  const resolver = createConfigResolver({ cipher: encryption });
   const masterKeyProvider = createEnvMasterKeyProvider({
     env: {
       KUMIKO_SECRETS_MASTER_KEY_V1: randomBytes(32).toString("base64"),

package/src/renderer-simple/__tests__/resolve-variables.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { RendererContext } from "../../renderer-foundation";
+import { resolveNotificationVariables } from "../resolve-variables";
+
+describe("resolveNotificationVariables :: template-resolver not mounted", () => {
+  test("template slug set but template-resolver isn't mounted → falls back to variables, never touches ctx.db", async () => {
+    // Truthy-but-poisoned db: if the guard ever regresses to only checking
+    // `!ctx.db`, calling anything on this throws instead of silently
+    // succeeding — the test fails loud, not by accident.
+    const poisonedDb = new Proxy(
+      {},
+      {
+        get(): never {
+          throw new Error(
+            "resolveNotificationVariables must not touch ctx.db when template-resolver isn't mounted",
+          );
+        },
+      },
+    );
+    const ctx: RendererContext = {
+      db: poisonedDb as never,
+      registry: { features: new Map() } as never,
+      tenantId: "11111111-1111-4111-8111-111111111111" as TenantId,
+    };
+
+    const result = await resolveNotificationVariables(
+      {
+        kind: "notification",
+        payload: { template: "welcome-email", variables: { name: "Ada" } },
+      },
+      ctx,
+    );
+
+    expect(result).toEqual({ name: "Ada" });
+  });
+});

package/src/renderer-simple/resolve-variables.ts

@@ -14,7 +14,7 @@ export async function resolveNotificationVariables(
 ): Promise<Readonly<Record<string, unknown>>> {
   const variables = req.payload.variables ?? {};
   const slug = req.payload.template?.trim();
-  if (!slug || req.payload.content || !ctx.db) {
+  if (!slug || req.payload.content || !ctx.db || !ctx.registry.features.has("template-resolver")) {
     return variables;
   }
 
@@ -31,6 +31,8 @@ export async function resolveNotificationVariables(
       const base = parsePlainTemplateContent(resolved.content);
       return { ...base, ...variables };
     }
+    // body always wins from the resolved template for rendered formats — a runtime
+    // "variables.body" override would clobber the actual rendered content.
     return { ...variables, body: resolved.content };
   } catch (err) {
     if (err instanceof TemplateNotFoundError) {