@cosmicdrift/kumiko-samples 0.377.0 → 0.378.0

package/packages/bundled-features/src/template-resolver/handlers/send-test.write.ts

@@ -1,23 +1,23 @@
-import { defineWriteHandler, type Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
-import {
-  collectChannels,
-  createEmailAttachmentReader,
-  EMAIL_CHANNEL_NAME,
-} from "../../delivery/index.ts";
-import { fileContextForTenant } from "../../file-foundation/index.ts";
 import { TEST_MAIL_SUBJECT_PREFIX } from "../constants.ts";
 import { TemplateResolverErrors } from "../qualified-names.ts";
+import {
+  refuseTemplateEdit,
+  type TemplateEditPolicy,
+  templateEditAccess,
+} from "../template-edit-policy.ts";
 import { renderTemplatePreview } from "../template-preview.ts";
+import {
+  emailChannelOf,
+  resolveTestMailAddress,
+  testMailChannelContext,
+} from "./send-test-shared.ts";
 import { localeSchema, templateSlugSchema } from "./shared.ts";
 
 const TEST_MAIL_RATE_LIMIT = { limit: 10, windowSeconds: 3600 } as const;
 
-function emailChannelOf(registry: Registry) {
-  return collectChannels(registry).find((channel) => channel.name === EMAIL_CHANNEL_NAME);
-}
-
 // Transport errors can carry provider responses or the address, so the client only gets a fixed code.
 function testMailFailed(code: "channel_error" | "not_sent") {
   return writeFailure(
@@ -34,105 +34,99 @@ function errorCodeOf(error: unknown): string | undefined {
 }
 
 // The only recipient is the caller's own address, resolved server-side, so the handler can never mail a third party.
-export const sendTestWrite = defineWriteHandler({
-  name: "send-test",
-  schema: z.object({
-    slug: templateSlugSchema,
-    locale: localeSchema,
-    content: z.string().max(200_000).optional(),
-    meta: z.unknown().optional(),
-    variableSchema: z.record(z.string(), z.unknown()).default({}),
-    variables: z.record(z.string(), z.unknown()).optional(),
-    includeAttachments: z.boolean().default(true),
-    prefixSubject: z.boolean().default(true),
-  }),
-  access: { roles: ["TenantAdmin", "SystemAdmin"] },
-  rateLimit: { per: "user+handler", ...TEST_MAIL_RATE_LIMIT },
-  description:
-    "Sends the rendered preview of a mail template draft, or of the stored template when no content is given, to the calling user's own address with the subject prefixed by [TEST] unless prefixSubject is false, carrying the inline images and, unless includeAttachments is false, the files attached to the template; there is no recipient input, the sample values come from the declared variable examples unless variables replaces them (checked against the variable schema), and a draft that fails the write rules is rejected without sending.",
-  handler: async (event, ctx) => {
-    const { includeAttachments, prefixSubject, ...previewPayload } = event.payload;
-    const outcome = await renderTemplatePreview(ctx, event.user, {
-      ...previewPayload,
-      kind: "mail",
-    });
-    if (!outcome.ok) return writeFailure(outcome.error);
-    const { preview, sender } = outcome;
-    const mailAttachments = includeAttachments
-      ? outcome.mailAttachments
-      : outcome.mailAttachments.filter((ref) => ref.kind === "inline");
-
-    const channel = emailChannelOf(ctx.registry);
-    if (channel === undefined) {
-      return writeFailure(
-        new UnprocessableError(TemplateResolverErrors.testMailNoChannel, {
-          i18nKey: "templateResolver.errors.testMail.noChannel",
-        }),
-      );
-    }
-    const channelContext = {
-      db: ctx.db,
-      registry: ctx.registry,
-      sseBroker: undefined,
-      tenantId: event.user.tenantId,
-      secrets: ctx.secrets,
-      config: ctx.config,
-      readAttachment: createEmailAttachmentReader(
-        ctx.db,
-        ctx.registry,
-        event.user.tenantId,
-        ctx.config,
-        (tenantId) => fileContextForTenant(ctx, ctx.user.tenantId, tenantId),
-      ),
-    };
-    const address = (await channel.resolve?.(event.user.id, channelContext)) ?? null;
-    if (address === null) {
-      return writeFailure(
-        new UnprocessableError(TemplateResolverErrors.testMailNoAddress, {
-          i18nKey: "templateResolver.errors.testMail.noAddress",
-        }),
-      );
-    }
-
-    const subject = `${prefixSubject ? TEST_MAIL_SUBJECT_PREFIX : ""}${preview.subject ?? ""}`;
-    let sentStatus: string;
-    try {
-      const result = await channel.send(
-        address,
-        {
-          // The template slug is the notification name, so the test mail takes the transport the real mail takes.
-          notificationType: event.payload.slug,
-          title: subject,
-          body: undefined,
-          data: undefined,
-          locale: event.payload.locale,
-        },
-        channelContext,
-        {
-          subject,
-          html: preview.html,
-          text: preview.text ?? "",
-          ...sender,
-          attachments: mailAttachments,
-        },
-      );
-      sentStatus = result.status;
-    } catch (error) {
-      // Class and code only: the message can carry the address or a provider response body.
-      ctx.log?.warn("template test mail: channel threw", {
-        tenantId: event.user.tenantId,
-        errorClass: error instanceof Error ? error.name : typeof error,
-        errorCode: errorCodeOf(error),
+export function makeSendTestWrite(policy: TemplateEditPolicy) {
+  return defineWriteHandler({
+    name: "send-test",
+    schema: z.object({
+      slug: templateSlugSchema,
+      locale: localeSchema,
+      content: z.string().max(200_000).optional(),
+      meta: z.unknown().optional(),
+      variableSchema: z.record(z.string(), z.unknown()).default({}),
+      variables: z.record(z.string(), z.unknown()).optional(),
+      includeAttachments: z.boolean().default(true),
+      prefixSubject: z.boolean().default(true),
+    }),
+    access: templateEditAccess(policy.tenantEditable),
+    rateLimit: { per: "user+handler", ...TEST_MAIL_RATE_LIMIT },
+    description:
+      "Sends the rendered preview of a mail template draft, or of the stored template when no content is given, to the calling user's own address with the subject prefixed by [TEST] unless prefixSubject is false, carrying the inline images and, unless includeAttachments is false, the files attached to the template; there is no recipient input, the sample values come from the declared variable examples unless variables replaces them (checked against the variable schema), and a draft that fails the write rules is rejected without sending.",
+    handler: async (event, ctx) => {
+      // Sending a test is part of editing, so it follows the same edit policy as the editor writes.
+      const refused = refuseTemplateEdit(policy, event.user, {
+        slug: event.payload.slug,
+        kind: "mail",
       });
-      return testMailFailed("channel_error");
-    }
-    if (sentStatus !== "sent") {
-      ctx.log?.warn("template test mail: channel did not send", {
-        tenantId: event.user.tenantId,
-        status: sentStatus,
+      if (refused !== null) return refused;
+      const { includeAttachments, prefixSubject, ...previewPayload } = event.payload;
+      const outcome = await renderTemplatePreview(ctx, event.user, {
+        ...previewPayload,
+        kind: "mail",
       });
-      return testMailFailed("not_sent");
-    }
-    return { isSuccess: true as const, data: { subject, checks: preview.checks } };
-  },
-});
+      if (!outcome.ok) return writeFailure(outcome.error);
+      const { preview, sender } = outcome;
+      const mailAttachments = includeAttachments
+        ? outcome.mailAttachments
+        : outcome.mailAttachments.filter((ref) => ref.kind === "inline");
+
+      const channel = emailChannelOf(ctx.registry);
+      if (channel === undefined) {
+        return writeFailure(
+          new UnprocessableError(TemplateResolverErrors.testMailNoChannel, {
+            i18nKey: "templateResolver.errors.testMail.noChannel",
+          }),
+        );
+      }
+      const channelContext = testMailChannelContext(ctx, event.user);
+      const address = await resolveTestMailAddress(channel, channelContext, event.user);
+      if (address === null) {
+        return writeFailure(
+          new UnprocessableError(TemplateResolverErrors.testMailNoAddress, {
+            i18nKey: "templateResolver.errors.testMail.noAddress",
+          }),
+        );
+      }
+
+      const subject = `${prefixSubject ? TEST_MAIL_SUBJECT_PREFIX : ""}${preview.subject ?? ""}`;
+      let sentStatus: string;
+      try {
+        const result = await channel.send(
+          address,
+          {
+            // The template slug is the notification name, so the test mail takes the transport the real mail takes.
+            notificationType: event.payload.slug,
+            title: subject,
+            body: undefined,
+            data: undefined,
+            locale: event.payload.locale,
+          },
+          channelContext,
+          {
+            subject,
+            html: preview.html,
+            text: preview.text ?? "",
+            ...sender,
+            attachments: mailAttachments,
+          },
+        );
+        sentStatus = result.status;
+      } catch (error) {
+        // Class and code only: the message can carry the address or a provider response body.
+        ctx.log?.warn("template test mail: channel threw", {
+          tenantId: event.user.tenantId,
+          errorClass: error instanceof Error ? error.name : typeof error,
+          errorCode: errorCodeOf(error),
+        });
+        return testMailFailed("channel_error");
+      }
+      if (sentStatus !== "sent") {
+        ctx.log?.warn("template test mail: channel did not send", {
+          tenantId: event.user.tenantId,
+          status: sentStatus,
+        });
+        return testMailFailed("not_sent");
+      }
+      return { isSuccess: true as const, data: { subject, checks: preview.checks } };
+    },
+  });
+}

package/packages/bundled-features/src/template-resolver/handlers/set.write.ts

@@ -9,6 +9,11 @@ import * as z from "zod";
 import { requireForTenant } from "../../shared/index.ts";
 import { TEMPLATE_KINDS, TEXT_BLOCK_KIND, UPSERT_KINDS } from "../constants.ts";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.ts";
+import {
+  refuseTemplateEdit,
+  type TemplateEditPolicy,
+  templateEditAccess,
+} from "../template-edit-policy.ts";
 import { resolveTemplateVariables } from "../template-validation.ts";
 import { contentFormatSchema, executor, folderSchema, localeSchema, slugSchema } from "./shared.ts";
 import { parseStoredJson, storedRecord } from "./template-gates.ts";
@@ -33,115 +38,117 @@ import { gateTemplateWrite } from "./template-write.ts";
 //
 // Kinds that upsertSystem/upsertTenant also write run the same validation
 // pipeline here, and because saving publishes, publish issues reject too.
-export const setWrite = defineWriteHandler({
-  name: "set",
-  schema: z.object({
-    slug: slugSchema,
-    locale: localeSchema,
-    /** Which kind to author. Defaults to text-block. */
-    kind: z.enum(TEMPLATE_KINDS).optional(),
-    title: z.string().min(1).max(200),
-    content: z.string().max(200_000).nullable(),
-    contentFormat: contentFormatSchema.default("markdown"),
-    /** Folder path for the content tree. Optional + null = root node. */
-    folder: folderSchema.nullable().optional(),
-    /** Optional cross-tenant write — SystemAdmin only. Typical use: the
-     *  editor lets a SystemAdmin write onto SYSTEM_TENANT_ID, otherwise the
-     *  text lands on their own platform tenant and the legal routes miss it. */
-    tenantIdOverride: z.string().min(1).optional(),
-  }),
-  // SystemAdmin is a global role, TenantAdmin is per tenant-membership — both
-  // paths are needed explicitly, otherwise nobody can set SYSTEM_TENANT texts.
-  access: { roles: ["TenantAdmin", "SystemAdmin"] },
-  description:
-    "Creates or overwrites one content-tree resource addressed by slug, kind and locale, carrying a title and folder and going live on save with no draft stage; a SystemAdmin may target the system tenant, where shared legal and marketing copy lives.",
-  handler: async (event, ctx) => {
-    const override = event.payload.tenantIdOverride;
-    // @cast-boundary engine-payload — override is a zod-validated string, the
-    // user's own tenantId is already TenantId-branded.
-    const tenantId = (override ?? event.user.tenantId) as TenantId;
-    const { db, streamTenantId } = requireForTenant(ctx, tenantId);
+export function makeSetWrite(policy: TemplateEditPolicy) {
+  return defineWriteHandler({
+    name: "set",
+    schema: z.object({
+      slug: slugSchema,
+      locale: localeSchema,
+      /** Which kind to author. Defaults to text-block. */
+      kind: z.enum(TEMPLATE_KINDS).optional(),
+      title: z.string().min(1).max(200),
+      content: z.string().max(200_000).nullable(),
+      contentFormat: contentFormatSchema.default("markdown"),
+      /** Folder path for the content tree. Optional + null = root node. */
+      folder: folderSchema.nullable().optional(),
+      /** Optional cross-tenant write — SystemAdmin only. Typical use: the
+       *  editor lets a SystemAdmin write onto SYSTEM_TENANT_ID, otherwise the
+       *  text lands on their own platform tenant and the legal routes miss it. */
+      tenantIdOverride: z.string().min(1).optional(),
+    }),
+    access: templateEditAccess(policy.tenantEditable),
+    description:
+      "Creates or overwrites one content-tree resource addressed by slug, kind and locale, carrying a title and folder and going live on save with no draft stage; a SystemAdmin may target the system tenant, where shared legal and marketing copy lives. A TenantAdmin may write only the slug and kind pairs the app lists in tenantEditable, otherwise SystemAdmin only.",
+    handler: async (event, ctx) => {
+      const kind = event.payload.kind ?? TEXT_BLOCK_KIND;
+      const refused = refuseTemplateEdit(policy, event.user, { slug: event.payload.slug, kind });
+      if (refused !== null) return refused;
+      const override = event.payload.tenantIdOverride;
+      // @cast-boundary engine-payload — override is a zod-validated string, the
+      // user's own tenantId is already TenantId-branded.
+      const tenantId = (override ?? event.user.tenantId) as TenantId;
+      const { db, streamTenantId } = requireForTenant(ctx, tenantId);
 
-    const kind = event.payload.kind ?? TEXT_BLOCK_KIND;
-    const existing = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
-      tenantId,
-      slug: event.payload.slug,
-      kind,
-      locale: event.payload.locale,
-    });
+      const existing = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
+        tenantId,
+        slug: event.payload.slug,
+        kind,
+        locale: event.payload.locale,
+      });
 
-    const scope = tenantId === SYSTEM_TENANT_ID ? ("system" as const) : ("tenant" as const);
-    let content = event.payload.content;
-    if (isOneOf(UPSERT_KINDS, kind)) {
-      const gated = gateTemplateWrite(
-        {
-          kind,
-          scope,
-          contentFormat: event.payload.contentFormat,
-          content,
-          rawMeta: parseStoredJson(existing?.meta ?? null),
-          variables: resolveTemplateVariables(
-            ctx.registry,
-            event.payload.slug,
-            storedRecord(existing?.variableSchema ?? null),
-          ),
-        },
-        "active",
-      );
-      if (!gated.ok) return gated.failure;
-      content = gated.evaluated.content;
-    }
+      const scope = tenantId === SYSTEM_TENANT_ID ? ("system" as const) : ("tenant" as const);
+      let content = event.payload.content;
+      if (isOneOf(UPSERT_KINDS, kind)) {
+        const gated = gateTemplateWrite(
+          {
+            kind,
+            scope,
+            contentFormat: event.payload.contentFormat,
+            content,
+            rawMeta: parseStoredJson(existing?.meta ?? null),
+            variables: resolveTemplateVariables(
+              ctx.registry,
+              event.payload.slug,
+              storedRecord(existing?.variableSchema ?? null),
+            ),
+          },
+          "active",
+        );
+        if (!gated.ok) return gated.failure;
+        content = gated.evaluated.content;
+      }
 
-    const fields = {
-      slug: event.payload.slug,
-      kind,
-      locale: event.payload.locale,
-      title: event.payload.title,
-      content,
-      contentFormat: event.payload.contentFormat,
-      folder: event.payload.folder ?? null,
-      variableSchema: "{}",
-      linkedResources: "{}",
-      scope,
-      parentTemplateId: null,
-      // Text blocks have no draft stage — saving publishes, so resolveTemplate
-      // (which only returns active rows) finds them.
-      status: "active" as const,
-    };
+      const fields = {
+        slug: event.payload.slug,
+        kind,
+        locale: event.payload.locale,
+        title: event.payload.title,
+        content,
+        contentFormat: event.payload.contentFormat,
+        folder: event.payload.folder ?? null,
+        variableSchema: "{}",
+        linkedResources: "{}",
+        scope,
+        parentTemplateId: null,
+        // Text blocks have no draft stage — saving publishes, so resolveTemplate
+        // (which only returns active rows) finds them.
+        status: "active" as const,
+      };
 
-    if (existing) {
-      const result = await executor.update(
-        {
-          id: existing.id,
-          version: existing.version,
-          // Only the editable columns — slug/kind/locale are the unique key,
-          // and rewriting scope/status/variableSchema here would reset whatever
-          // the template upserts put on the row.
-          changes: {
-            title: fields.title,
-            content: fields.content,
-            contentFormat: fields.contentFormat,
-            folder: fields.folder,
+      if (existing) {
+        const result = await executor.update(
+          {
+            id: existing.id,
+            version: existing.version,
+            // Only the editable columns — slug/kind/locale are the unique key,
+            // and rewriting scope/status/variableSchema here would reset whatever
+            // the template upserts put on the row.
+            changes: {
+              title: fields.title,
+              content: fields.content,
+              contentFormat: fields.contentFormat,
+              folder: fields.folder,
+            },
           },
-        },
-        event.user,
-        db,
-        { streamTenantId },
-      );
+          event.user,
+          db,
+          { streamTenantId },
+        );
+        if (!result.isSuccess) return result;
+        return {
+          isSuccess: true as const,
+          data: { slug: event.payload.slug, locale: event.payload.locale, isNew: false },
+        };
+      }
+
+      const result = await executor.create({ ...fields, tenantId }, event.user, db, {
+        streamTenantId,
+      });
       if (!result.isSuccess) return result;
       return {
         isSuccess: true as const,
-        data: { slug: event.payload.slug, locale: event.payload.locale, isNew: false },
+        data: { slug: event.payload.slug, locale: event.payload.locale, isNew: true },
       };
-    }
-
-    const result = await executor.create({ ...fields, tenantId }, event.user, db, {
-      streamTenantId,
-    });
-    if (!result.isSuccess) return result;
-    return {
-      isSuccess: true as const,
-      data: { slug: event.payload.slug, locale: event.payload.locale, isNew: true },
-    };
-  },
-});
+    },
+  });
+}

package/packages/bundled-features/src/template-resolver/handlers/toggle-status.write.ts

@@ -15,6 +15,12 @@ import { requireForTenant } from "../../shared/index.ts";
 import type { TemplateResourceRow } from "../table.ts";
 import { templateResourcesTable } from "../table.ts";
 import { activationChanges, parseTemplateDraft, toWorkingRow } from "../template-draft.ts";
+import {
+  refuseMissingTemplate,
+  refuseTemplateEdit,
+  type TemplateEditPolicy,
+  templateEditAccess,
+} from "../template-edit-policy.ts";
 import { executor } from "./shared.ts";
 import { publishGateIssues } from "./template-gates.ts";
 
@@ -27,8 +33,10 @@ function isRowOfTarget(row: TemplateResourceRow, target: StatusTarget, callerTen
     : row.tenantId === callerTenantId && row.scope === "tenant";
 }
 
-export function writeAccessFor(target: StatusTarget) {
-  return { roles: target === "system" ? ["SystemAdmin"] : ["TenantAdmin", "SystemAdmin"] };
+export function writeAccessFor(target: StatusTarget, policy: TemplateEditPolicy) {
+  return target === "system"
+    ? { roles: ["SystemAdmin"] }
+    : templateEditAccess(policy.tenantEditable);
 }
 
 // The tenant db also reads system rows; the row's own tenant must match the
@@ -65,6 +73,7 @@ function planStatusChange(
 }
 
 function createStatusUpdateHandler(
+  policy: TemplateEditPolicy,
   name: string,
   target: StatusTarget,
   status: TemplateStatus,
@@ -73,13 +82,20 @@ function createStatusUpdateHandler(
   return defineWriteHandler({
     name,
     schema: z.object({ id: z.string().min(1) }),
-    access: writeAccessFor(target),
+    access: writeAccessFor(target, policy),
     // A system template change reaches every tenant without an override.
     ...(target === "system" ? { agent: { risk: "high" as const } } : {}),
     description,
     handler: async (event, ctx) => {
       const { db, scoped, row } = await loadTargetRow(ctx, target, event.user, event.payload.id);
-      if (!row) return writeFailure(new NotFoundError("template-resource", event.payload.id));
+      if (!row) {
+        const refused = target === "own" ? refuseMissingTemplate(policy, event.user) : null;
+        return refused ?? writeFailure(new NotFoundError("template-resource", event.payload.id));
+      }
+      if (target === "own") {
+        const refused = refuseTemplateEdit(policy, event.user, row);
+        if (refused !== null) return refused;
+      }
       const plan = planStatusChange(ctx, row, status);
       if (!plan.ok) return plan.failure;
       const result = await executor.update(
@@ -94,27 +110,39 @@ function createStatusUpdateHandler(
   });
 }
 
-export const archiveWrite = createStatusUpdateHandler(
-  "archive",
-  "own",
-  "archived",
-  "Sets one template resource of the caller's tenant to archived so the resolver stops serving it while the row and its content survive; use it to retire a template reversibly instead of deleting it. An open draft stays.",
-);
-export const publishWrite = createStatusUpdateHandler(
-  "publish",
-  "own",
-  "active",
-  "Sets one template resource of the caller's tenant to active so the resolver starts serving it; use it to release a draft written by upsert-tenant (a draft saved beside an active version replaces it), or to bring an archived template back; a version with unknown placeholders or unused required variables is refused and the served version stays.",
-);
-export const archiveSystemWrite = createStatusUpdateHandler(
-  "archive-system",
-  "system",
-  "archived",
-  "Sets one system-default template to archived so the resolver stops serving it to every tenant that has no override; SystemAdmin only, reversible with publish-system.",
-);
-export const publishSystemWrite = createStatusUpdateHandler(
-  "publish-system",
-  "system",
-  "active",
-  "Sets one system-default template to active so the resolver serves it again to every tenant that has no override; an open draft beside the active version replaces it; SystemAdmin only, a version with unknown placeholders or unused required variables is refused.",
-);
+export function makeArchiveWrite(policy: TemplateEditPolicy) {
+  return createStatusUpdateHandler(
+    policy,
+    "archive",
+    "own",
+    "archived",
+    "Sets one template resource of the caller's tenant to archived so the resolver stops serving it while the row and its content survive; use it to retire a template reversibly instead of deleting it. An open draft stays. Outside the templates the app lists in tenantEditable only a SystemAdmin may use it.",
+  );
+}
+export function makePublishWrite(policy: TemplateEditPolicy) {
+  return createStatusUpdateHandler(
+    policy,
+    "publish",
+    "own",
+    "active",
+    "Sets one template resource of the caller's tenant to active so the resolver starts serving it; use it to release a draft written by upsert-tenant (a draft saved beside an active version replaces it), or to bring an archived template back; a version with unknown placeholders or unused required variables is refused and the served version stays. Outside the templates the app lists in tenantEditable only a SystemAdmin may use it.",
+  );
+}
+export function makeArchiveSystemWrite(policy: TemplateEditPolicy) {
+  return createStatusUpdateHandler(
+    policy,
+    "archive-system",
+    "system",
+    "archived",
+    "Sets one system-default template to archived so the resolver stops serving it to every tenant that has no override; SystemAdmin only, reversible with publish-system.",
+  );
+}
+export function makePublishSystemWrite(policy: TemplateEditPolicy) {
+  return createStatusUpdateHandler(
+    policy,
+    "publish-system",
+    "system",
+    "active",
+    "Sets one system-default template to active so the resolver serves it again to every tenant that has no override; an open draft beside the active version replaces it; SystemAdmin only, a version with unknown placeholders or unused required variables is refused.",
+  );
+}