@cosmicdrift/kumiko-samples 0.340.0 → 0.341.0

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-pages.ts

@@ -5,7 +5,13 @@ import type { AnonymousExtraRoute } from "@cosmicdrift/kumiko-framework/api";
 import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
 import type { Context } from "hono";
 import { getCookie } from "hono/cookie";
-import { securePageHeaders, wrapInLayout } from "../../page-render/index.js";
+import {
+  type PublicPageWrapLayout,
+  redirectToCanonicalPath,
+  securePageHeaders,
+  slashVariantOf,
+  wrapInLayout,
+} from "../../page-render/index.js";
 import { SubscriptionFoundationHandlers } from "../constants.js";
 import { CONTRACT_TERMINATION_DECLARATION_TYPES, CONTRACT_TERMINATION_KINDS } from "../events.js";
 import type { ConsentLocale } from "./consent-text.js";
@@ -15,6 +21,21 @@ import { type PageTexts, TERMINATION_TEXTS } from "./termination-texts.js";
 
 export type ContractTerminationRoutesOptions = {
   readonly paths?: Readonly<Partial<Record<ConsentLocale, string>>>;
+  /** Layout around every page (form, review, result, 429, error). Default:
+   *  the minimal `wrapInLayout` skeleton. The page headers (CSP with
+   *  `script-src 'none'`, framing, no-store) stay with the framework, so the
+   *  layout must work without JavaScript and only returns the HTML string. */
+  readonly wrapLayout?: PublicPageWrapLayout;
+};
+
+const PAGE_SLUG = "contract-termination";
+
+// Everything a page render needs besides its own content.
+type PageContext = {
+  readonly locale: ConsentLocale;
+  readonly path: string;
+  readonly wrapLayout: PublicPageWrapLayout;
+  readonly alternates: Readonly<Record<ConsentLocale, string>>;
 };
 
 const DEFAULT_PATHS: Readonly<Record<ConsentLocale, string>> = {
@@ -59,15 +80,22 @@ function pageHeaders(): Record<string, string> {
 }
 
 function htmlResponse(
-  locale: ConsentLocale,
+  ctx: PageContext,
   title: string,
   bodyHtml: string,
-  status: 200 | 400 | 429 | 500,
+  status: 200 | 400 | 429,
 ): Response {
-  return new Response(wrapInLayout({ title, bodyHtml, lang: locale }), {
-    status,
-    headers: pageHeaders(),
-  });
+  const root = `<div data-kumiko-page="${PAGE_SLUG}">\n${bodyHtml}\n</div>`;
+  return new Response(
+    ctx.wrapLayout({
+      title,
+      bodyHtml: root,
+      lang: ctx.locale,
+      slug: PAGE_SLUG,
+      alternates: ctx.alternates,
+    }),
+    { status, headers: pageHeaders() },
+  );
 }
 
 function isOneOf<T extends string>(options: readonly T[], value: string): value is T {
@@ -152,32 +180,32 @@ function textField(
   value: string,
   attributes: { readonly type?: string; readonly required?: boolean; readonly maxlength: number },
 ): string {
-  return `<p><label>${escapeHtml(label)}<br><input type="${escapeHtmlAttr(attributes.type ?? "text")}" name="${name}" value="${escapeHtmlAttr(value)}" maxlength="${attributes.maxlength}"${
+  return `<p data-kumiko-field-group="${name}"><label>${escapeHtml(label)}<br><input type="${escapeHtmlAttr(attributes.type ?? "text")}" name="${name}" value="${escapeHtmlAttr(value)}" maxlength="${attributes.maxlength}"${
     attributes.required ? " required" : ""
   }></label></p>`;
 }
 
 function formPage(
-  locale: ConsentLocale,
-  path: string,
+  ctx: PageContext,
   values: FormValues,
   messages: readonly string[],
   status: 200 | 400,
 ): Response {
+  const { locale, path } = ctx;
   const texts = TERMINATION_TEXTS[locale];
   const { page } = texts;
   const body = `<h1>${escapeHtml(page.title)}</h1>
 <p>${escapeHtml(page.lead)}</p>
 ${errorsHtml(messages, page)}
-<form method="post" action="${escapeHtmlAttr(path)}">
+<form method="post" action="${escapeHtmlAttr(path)}" data-kumiko-form="contract-termination">
 <input type="hidden" name="step" value="review">
-<fieldset><legend>${escapeHtml(page.declarationTypeHeading)}</legend>${radioGroup(
+<fieldset data-kumiko-field-group="declarationType"><legend>${escapeHtml(page.declarationTypeHeading)}</legend>${radioGroup(
     "declarationType",
     CONTRACT_TERMINATION_DECLARATION_TYPES,
     texts.declarationTypeLabel,
     values.declarationType,
   )}</fieldset>
-<fieldset><legend>${escapeHtml(page.kindHeading)}</legend>${radioGroup(
+<fieldset data-kumiko-field-group="terminationKind"><legend>${escapeHtml(page.kindHeading)}</legend>${radioGroup(
     "terminationKind",
     CONTRACT_TERMINATION_KINDS,
     texts.terminationKindLabel,
@@ -186,10 +214,10 @@ ${errorsHtml(messages, page)}
 ${textField("name", page.nameLabel, values.name, { required: true, maxlength: 200 })}
 ${textField("email", page.emailLabel, values.email, { type: "email", required: true, maxlength: 254 })}
 ${textField("customerReference", page.customerReferenceLabel, values.customerReference, { maxlength: 200 })}
-<p><label>${escapeHtml(page.reasonLabel)} (${escapeHtml(page.reasonHint)})<br><textarea name="reason" rows="5" maxlength="2000">${escapeHtml(values.reason)}</textarea></label></p>
-<p><button type="submit">${escapeHtml(page.reviewButton)}</button></p>
+<p data-kumiko-field-group="reason"><label>${escapeHtml(page.reasonLabel)} (${escapeHtml(page.reasonHint)})<br><textarea name="reason" rows="5" maxlength="2000">${escapeHtml(values.reason)}</textarea></label></p>
+<p><button type="submit" data-kumiko-button="review">${escapeHtml(page.reviewButton)}</button></p>
 </form>`;
-  return htmlResponse(locale, page.title, body, status);
+  return htmlResponse(ctx, page.title, body, status);
 }
 
 function hiddenInputs(values: FormValues): string {
@@ -198,7 +226,8 @@ function hiddenInputs(values: FormValues): string {
   ).join("\n");
 }
 
-function reviewPage(locale: ConsentLocale, path: string, values: FormValues): Response {
+function reviewPage(ctx: PageContext, values: FormValues): Response {
+  const { locale, path } = ctx;
   const texts = TERMINATION_TEXTS[locale];
   const { page } = texts;
   // validationMessages already proved the enum values.
@@ -214,7 +243,7 @@ function reviewPage(locale: ConsentLocale, path: string, values: FormValues): Re
       : `<tr><th scope="row">${escapeHtml(label)}</th><td>${escapeHtml(value)}</td></tr>`;
   const body = `<h1>${escapeHtml(page.reviewTitle)}</h1>
 <p>${escapeHtml(page.reviewLead)}</p>
-<table>
+<table data-kumiko-review-table>
 ${row(texts.declarationType, texts.declarationTypeLabel[declarationType])}
 ${row(texts.terminationKind, texts.terminationKindLabel[terminationKind])}
 ${row(texts.name, values.name)}
@@ -222,22 +251,23 @@ ${row(texts.email, values.email)}
 ${row(texts.customerReference, values.customerReference)}
 ${row(texts.reasonFieldLabel, values.reason)}
 </table>
-<form method="post" action="${escapeHtmlAttr(path)}">
+<form method="post" action="${escapeHtmlAttr(path)}" data-kumiko-form="contract-termination-review">
 ${hiddenInputs(values)}
-<button type="submit" name="step" value="confirm">${escapeHtml(page.confirmButton[declarationType])}</button>
-<button type="submit" name="step" value="edit">${escapeHtml(page.backButton)}</button>
+<button type="submit" name="step" value="confirm" data-kumiko-button="confirm">${escapeHtml(page.confirmButton[declarationType])}</button>
+<button type="submit" name="step" value="edit" data-kumiko-button="back">${escapeHtml(page.backButton)}</button>
 </form>`;
-  return htmlResponse(locale, page.reviewTitle, body, 200);
+  return htmlResponse(ctx, page.reviewTitle, body, 200);
 }
 
-function resultPage(locale: ConsentLocale, receivedAtIso: string, requestId: string): Response {
+function resultPage(ctx: PageContext, receivedAtIso: string, requestId: string): Response {
+  const { locale } = ctx;
   const { page } = TERMINATION_TEXTS[locale];
   const body = `<h1>${escapeHtml(page.resultTitle)}</h1>
 <p>${escapeHtml(page.resultLead)}</p>
 <p>${escapeHtml(page.resultReceivedAt)}: <strong>${escapeHtml(formatReceivedAt(receivedAtIso, locale))}</strong></p>
 <p>${escapeHtml(page.resultRequestId)}: <code>${escapeHtml(requestId)}</code></p>
 <p>${escapeHtml(page.resultMailNote)}</p>`;
-  return htmlResponse(locale, page.resultTitle, body, 200);
+  return htmlResponse(ctx, page.resultTitle, body, 200);
 }
 
 type WriteResponseBody = {
@@ -320,50 +350,69 @@ async function submitDeclaration(
   return { kind: "failed" };
 }
 
-function routesFor(locale: ConsentLocale, path: string): AnonymousExtraRoute[] {
+function routesFor(ctx: PageContext): AnonymousExtraRoute[] {
+  const { locale, path } = ctx;
+  const slashVariant = slashVariantOf(path);
   return [
     {
       method: "GET",
       path,
       entry: "anonymous",
-      handler: () => formPage(locale, path, EMPTY_FORM, [], 200),
+      handler: () => formPage(ctx, EMPTY_FORM, [], 200),
     },
+    // GET also serves HEAD; POST gets no alias (a redirect would drop the body).
+    ...(slashVariant === null
+      ? []
+      : [
+          {
+            method: "GET" as const,
+            path: slashVariant,
+            entry: "anonymous" as const,
+            handler: (c: Context) => redirectToCanonicalPath(c.req.url, path),
+          },
+        ]),
     {
       method: "POST",
       path,
       entry: "anonymous",
       handler: async (c, deps) => {
         const { step, values } = await readForm(c);
-        if (step === "edit") return formPage(locale, path, values, [], 200);
+        if (step === "edit") return formPage(ctx, values, [], 200);
         const messages = validationMessages(values, locale);
-        if (messages.length > 0) return formPage(locale, path, values, messages, 400);
-        if (step !== "confirm") return reviewPage(locale, path, values);
+        if (messages.length > 0) return formPage(ctx, values, messages, 400);
+        if (step !== "confirm") return reviewPage(ctx, values);
 
         const outcome = await submitDeclaration(c, deps.app, deps.clientIp, values, locale);
         const { page } = TERMINATION_TEXTS[locale];
         if (outcome.kind === "received") {
-          return resultPage(locale, outcome.receivedAtIso, outcome.requestId);
+          return resultPage(ctx, outcome.receivedAtIso, outcome.requestId);
         }
         if (outcome.kind === "rate-limited") {
           return htmlResponse(
-            locale,
+            ctx,
             page.rateLimitedTitle,
             `<h1>${escapeHtml(page.rateLimitedTitle)}</h1><p>${escapeHtml(page.rateLimitedBody)}</p>`,
             429,
           );
         }
-        return formPage(locale, path, values, [page.errorGeneric], 400);
+        return formPage(ctx, values, [page.errorGeneric], 400);
       },
     },
   ];
 }
 
 /** GET + POST pages for de (`/legal/kuendigen`) and en (`/legal/cancel`);
- *  mount via the app's `extraRoutes`. */
+ *  mount via the app's `extraRoutes`. The other trailing-slash form of each
+ *  path 301-redirects (GET/HEAD) to the configured path. */
 export function createContractTerminationRoutes(
   options: ContractTerminationRoutesOptions = {},
 ): AnonymousExtraRoute[] {
+  const alternates: Readonly<Record<ConsentLocale, string>> = {
+    de: options.paths?.de ?? DEFAULT_PATHS.de,
+    en: options.paths?.en ?? DEFAULT_PATHS.en,
+  };
+  const wrapLayout = options.wrapLayout ?? wrapInLayout;
   return (["de", "en"] as const).flatMap((locale) =>
-    routesFor(locale, options.paths?.[locale] ?? DEFAULT_PATHS[locale]),
+    routesFor({ locale, path: alternates[locale], wrapLayout, alternates }),
   );
 }

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-request.ts

@@ -118,6 +118,7 @@ async function sendTerminationMails(
       declaration: plan.declaration,
       operatorEmail: consumerProtection.operatorEmail,
     }),
+    locale: plan.locale,
     priority: "critical",
   });
   // skip: no operator notice needed for this declaration
@@ -179,6 +180,7 @@ export function createRequestContractTerminationHandler(
     schema: requestContractTerminationSchema,
     access: { roles: ["anonymous"] },
     rateLimit: { per: "ip+handler", limit: 5, windowSeconds: 600 },
+    additionalRateLimits: [{ per: { payloadField: "email" }, limit: 3, windowSeconds: 86400 }],
     ...(consumerProtection.terminationScope === "platform" && { tenantlessAnonymous: true }),
     escapeHatch: {
       reason:

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-texts.ts

@@ -15,6 +15,7 @@ export type TerminationTexts = {
   readonly customerReference: string;
   readonly reasonFieldLabel: string;
   readonly receiptSubject: Readonly<Record<ContractTerminationDeclarationType, string>>;
+  readonly receiptGreeting: string;
   readonly receiptIntro: string;
   readonly receiptNextSteps: string;
   readonly receiptRevoke: (operatorEmail: string) => string;
@@ -93,6 +94,7 @@ export const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>
       termination: "Eingangsbestätigung deiner Kündigung",
       withdrawal: "Eingangsbestätigung deines Widerrufs",
     },
+    receiptGreeting: "Hallo,",
     receiptIntro:
       "wir bestätigen den Eingang deiner Erklärung mit folgendem Inhalt. Diese E-Mail ist eine Eingangsbestätigung, keine Bestätigung der Wirksamkeit.",
     receiptNextSteps:
@@ -175,8 +177,9 @@ export const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>
       termination: "Receipt for your termination",
       withdrawal: "Receipt for your withdrawal",
     },
+    receiptGreeting: "Hello,",
     receiptIntro:
-      "we confirm receipt of your declaration with the following content. This email is a receipt, not a confirmation that the declaration is effective.",
+      "We confirm receipt of your declaration with the following content. This email is a receipt, not a confirmation that the declaration is effective.",
     receiptNextSteps:
       "We will review your declaration and get back to you once it is processed or if we have questions.",
     receiptRevoke: (operatorEmail) =>

package/packages/bundled-features/src/channel-discord/discord-channel.ts

@@ -8,6 +8,11 @@ import {
 
 export type DiscordChannelOptions = ChatWebhookChannelOptions;
 
+export const DISCORD_SECRET_KEYS = {
+  webhookPrefix: "channel-discord:webhooks.",
+  webhookKeyFor: (connection: string) => `channel-discord:webhooks.${connection}`,
+} as const;
+
 export const DISCORD_DEFAULT_ALLOWED_HOSTS = ["discord.com", "discordapp.com"] as const;
 export const DISCORD_WEBHOOK_PATH_PREFIX = "/api/webhooks/";
 export const DISCORD_CONTENT_MAX_CHARS = 2000;

package/packages/bundled-features/src/channel-discord/feature.ts

@@ -1,9 +1,16 @@
 import {
   chatConnectionNameSchema,
+  chatWebhookUrlSchema,
   DELIVERY_CHANNEL_EXTENSION,
+  resolveChatWebhookTarget,
 } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
-import { createDiscordChannel, type DiscordChannelOptions } from "./discord-channel.js";
+import {
+  createDiscordChannel,
+  DISCORD_DEFAULT_ALLOWED_HOSTS,
+  DISCORD_WEBHOOK_PATH_PREFIX,
+  type DiscordChannelOptions,
+} from "./discord-channel.js";
 
 export function createChannelDiscordFeature(
   options: DiscordChannelOptions = {},
@@ -20,6 +27,13 @@ export function createChannelDiscordFeature(
     r.requires("delivery");
     r.requires("secrets");
 
+    const webhookTarget = resolveChatWebhookTarget(
+      {
+        defaultAllowedHosts: DISCORD_DEFAULT_ALLOWED_HOSTS,
+        requiredPathPrefix: DISCORD_WEBHOOK_PATH_PREFIX,
+      },
+      options,
+    );
     const webhooks = r.secretNamespace("webhooks", {
       label: { en: "Discord webhooks", de: "Discord-Webhooks", es: "Webhooks de Discord" },
       hint: {
@@ -29,6 +43,7 @@ export function createChannelDiscordFeature(
       },
       scope: "tenant",
       nameSchema: chatConnectionNameSchema,
+      valueSchema: chatWebhookUrlSchema(webhookTarget),
     });
 
     const channel = createDiscordChannel(options, webhooks.keyFor);

package/packages/bundled-features/src/channel-discord/index.ts

@@ -1,2 +1,8 @@
-export { createDiscordChannel, type DiscordChannelOptions } from "./discord-channel.js";
+export {
+  createDiscordChannel,
+  DISCORD_DEFAULT_ALLOWED_HOSTS,
+  DISCORD_SECRET_KEYS,
+  DISCORD_WEBHOOK_PATH_PREFIX,
+  type DiscordChannelOptions,
+} from "./discord-channel.js";
 export { createChannelDiscordFeature } from "./feature.js";

package/packages/bundled-features/src/channel-email/email-channel.ts

@@ -100,6 +100,7 @@ export function createEmailChannel(options: EmailChannelOptions): DeliveryChanne
     const html = await renderer.render({
       template: message.notificationType,
       variables,
+      locale: message.locale,
     });
     const subject = (variables["subject"] as string) ?? message.title; // @cast-boundary dynamic-key
     return { html, subject };

package/packages/bundled-features/src/channel-slack/feature.ts

@@ -1,9 +1,15 @@
 import {
   chatConnectionNameSchema,
+  chatWebhookUrlSchema,
   DELIVERY_CHANNEL_EXTENSION,
+  resolveChatWebhookTarget,
 } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
-import { createSlackChannel, type SlackChannelOptions } from "./slack-channel.js";
+import {
+  createSlackChannel,
+  SLACK_DEFAULT_ALLOWED_HOSTS,
+  type SlackChannelOptions,
+} from "./slack-channel.js";
 
 export function createChannelSlackFeature(options: SlackChannelOptions = {}): FeatureDefinition {
   return defineFeature("channel-slack", (r) => {
@@ -18,6 +24,10 @@ export function createChannelSlackFeature(options: SlackChannelOptions = {}): Fe
     r.requires("delivery");
     r.requires("secrets");
 
+    const webhookTarget = resolveChatWebhookTarget(
+      { defaultAllowedHosts: SLACK_DEFAULT_ALLOWED_HOSTS },
+      options,
+    );
     const webhooks = r.secretNamespace("webhooks", {
       label: { en: "Slack webhooks", de: "Slack-Webhooks", es: "Webhooks de Slack" },
       hint: {
@@ -27,6 +37,7 @@ export function createChannelSlackFeature(options: SlackChannelOptions = {}): Fe
       },
       scope: "tenant",
       nameSchema: chatConnectionNameSchema,
+      valueSchema: chatWebhookUrlSchema(webhookTarget),
     });
 
     const channel = createSlackChannel(options, webhooks.keyFor);

package/packages/bundled-features/src/channel-slack/index.ts

@@ -1,2 +1,7 @@
 export { createChannelSlackFeature } from "./feature.js";
-export { createSlackChannel, type SlackChannelOptions } from "./slack-channel.js";
+export {
+  createSlackChannel,
+  SLACK_DEFAULT_ALLOWED_HOSTS,
+  SLACK_SECRET_KEYS,
+  type SlackChannelOptions,
+} from "./slack-channel.js";

package/packages/bundled-features/src/channel-slack/slack-channel.ts

@@ -7,6 +7,11 @@ import {
 
 export type SlackChannelOptions = ChatWebhookChannelOptions;
 
+export const SLACK_SECRET_KEYS = {
+  webhookPrefix: "channel-slack:webhooks.",
+  webhookKeyFor: (connection: string) => `channel-slack:webhooks.${connection}`,
+} as const;
+
 export const SLACK_DEFAULT_ALLOWED_HOSTS = ["hooks.slack.com"] as const;
 
 // Slack mrkdwn treats & < > as control characters (links, @-mentions via <!channel>).

package/packages/bundled-features/src/channel-teams/feature.ts

@@ -1,9 +1,15 @@
 import {
   chatConnectionNameSchema,
+  chatWebhookUrlSchema,
   DELIVERY_CHANNEL_EXTENSION,
+  resolveChatWebhookTarget,
 } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
-import { createTeamsChannel, type TeamsChannelOptions } from "./teams-channel.js";
+import {
+  createTeamsChannel,
+  TEAMS_DEFAULT_ALLOWED_HOSTS,
+  type TeamsChannelOptions,
+} from "./teams-channel.js";
 
 export function createChannelTeamsFeature(options: TeamsChannelOptions = {}): FeatureDefinition {
   return defineFeature("channel-teams", (r) => {
@@ -18,6 +24,10 @@ export function createChannelTeamsFeature(options: TeamsChannelOptions = {}): Fe
     r.requires("delivery");
     r.requires("secrets");
 
+    const webhookTarget = resolveChatWebhookTarget(
+      { defaultAllowedHosts: TEAMS_DEFAULT_ALLOWED_HOSTS },
+      options,
+    );
     const webhooks = r.secretNamespace("webhooks", {
       label: {
         en: "Microsoft Teams webhooks",
@@ -31,6 +41,7 @@ export function createChannelTeamsFeature(options: TeamsChannelOptions = {}): Fe
       },
       scope: "tenant",
       nameSchema: chatConnectionNameSchema,
+      valueSchema: chatWebhookUrlSchema(webhookTarget),
     });
 
     const channel = createTeamsChannel(options, webhooks.keyFor);

package/packages/bundled-features/src/channel-teams/index.ts

@@ -1,2 +1,7 @@
 export { createChannelTeamsFeature } from "./feature.js";
-export { createTeamsChannel, type TeamsChannelOptions } from "./teams-channel.js";
+export {
+  createTeamsChannel,
+  TEAMS_DEFAULT_ALLOWED_HOSTS,
+  TEAMS_SECRET_KEYS,
+  type TeamsChannelOptions,
+} from "./teams-channel.js";

package/packages/bundled-features/src/channel-teams/teams-channel.ts

@@ -6,6 +6,11 @@ import {
 
 export type TeamsChannelOptions = ChatWebhookChannelOptions;
 
+export const TEAMS_SECRET_KEYS = {
+  webhookPrefix: "channel-teams:webhooks.",
+  webhookKeyFor: (connection: string) => `channel-teams:webhooks.${connection}`,
+} as const;
+
 export const TEAMS_DEFAULT_ALLOWED_HOSTS = [
   ".webhook.office.com",
   ".logic.azure.com",

package/packages/bundled-features/src/channel-telegram/changes.json

@@ -0,0 +1,9 @@
+[
+  {
+    "version": "0.341.0",
+    "type": "breaking",
+    "title": "Telegram apiBaseUrl must match allowedHosts and use https",
+    "detail": "`ctx.secrets.set` now runs the same `valueSchema` check as `secrets:write:set` and throws the same validation error (`secrets.errors.invalidValue`, never carrying the value) before anything is encrypted or stored. `createSecretsContext` takes a required `registry` option that supplies the declared schemas; `runProdApp`, `runDevApp` and `setupTestStack` setups pass the booted registry.\n`createChannelTelegramFeature` takes `allowedHosts` (default `[\"api.telegram.org\"]`) and `requireHttps` (default `true`), like the other chat channels. Boot fails when the host of `apiBaseUrl` is not in `allowedHosts` or the URL is not https while `requireHttps` is on. Before, the host of `apiBaseUrl` was its own allowlist and https was only required when the URL already started with `https:`.",
+    "migration": "An app that sets a custom apiBaseUrl (self-hosted Bot API server, local test server) must also pass allowedHosts: [\"<host>\"], plus requireHttps: false for plain http. Without it the app fails at boot."
+  }
+]

package/packages/bundled-features/src/channel-telegram/feature.ts

@@ -1,13 +1,18 @@
 import { DELIVERY_CHANNEL_EXTENSION } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
-import { createTelegramChannel, type TelegramChannelOptions } from "./telegram-channel.js";
+import * as z from "zod";
+import {
+  createTelegramChannel,
+  isTelegramBotToken,
+  type TelegramChannelOptions,
+} from "./telegram-channel.js";
 
 export function createChannelTelegramFeature(
   options: TelegramChannelOptions = {},
 ): FeatureDefinition {
   return defineFeature("channel-telegram", (r) => {
     r.describe(
-      'Sends delivery notifications through the Telegram Bot API (`sendMessage`, plain text), registered as the `telegram` channel in the delivery system. Tenant-owned chat target: reach it only via `ctx.notify(type, { route: { telegram: "<chat id or @channel>" } })`. The bot token is the tenant secret `channel-telegram:secret:bot-token`; the token never reaches logs or delivery attempts. Requires `delivery` and `secrets`. The API base URL and request timeout are app options of `createChannelTelegramFeature(opts)`, never tenant config.',
+      'Sends delivery notifications through the Telegram Bot API (`sendMessage`, plain text), registered as the `telegram` channel in the delivery system. Tenant-owned chat target: reach it only via `ctx.notify(type, { route: { telegram: "<chat id or @channel>" } })`. The bot token is the tenant secret `channel-telegram:secret:bot-token`; the token never reaches logs or delivery attempts. Requires `delivery` and `secrets`. The API base URL, its host allowlist (`allowedHosts`, default `api.telegram.org`), `requireHttps` (default true; boot fails on a mismatch) and the request timeout are app options of `createChannelTelegramFeature(opts)`, never tenant config.',
     );
     r.uiHints({
       displayLabel: "Telegram Channel",
@@ -24,6 +29,7 @@ export function createChannelTelegramFeature(
       },
       redact: () => "••••••••",
       scope: "tenant",
+      valueSchema: z.string().refine(isTelegramBotToken, "invalid bot token"),
     });
 
     const channel = createTelegramChannel(options, botToken.name);

package/packages/bundled-features/src/channel-telegram/index.ts

@@ -1,2 +1,9 @@
 export { createChannelTelegramFeature } from "./feature.js";
-export { createTelegramChannel, type TelegramChannelOptions } from "./telegram-channel.js";
+export {
+  createTelegramChannel,
+  isTelegramBotToken,
+  isTelegramChatId,
+  TELEGRAM_DEFAULT_API_BASE_URL,
+  TELEGRAM_SECRET_KEYS,
+  type TelegramChannelOptions,
+} from "./telegram-channel.js";

package/packages/bundled-features/src/channel-telegram/telegram-channel.ts

@@ -10,30 +10,65 @@ import {
 
 export type TelegramChannelOptions = {
   // App-level override (tests, self-hosted Bot API server); never tenant config.
+  // Its host must be listed in `allowedHosts`, otherwise boot fails.
   readonly apiBaseUrl?: string;
+  // Replaces the default allowlist (`api.telegram.org`); required for a self-hosted Bot API server.
+  readonly allowedHosts?: readonly string[];
+  // Default true; `false` only for local http test servers.
+  readonly requireHttps?: boolean;
   readonly timeoutMs?: number;
 };
 
 export const TELEGRAM_DEFAULT_API_BASE_URL = "https://api.telegram.org";
+export const TELEGRAM_DEFAULT_ALLOWED_HOSTS: readonly string[] = ["api.telegram.org"];
 export const TELEGRAM_TEXT_MAX_CHARS = 4096;
+export const TELEGRAM_SECRET_KEYS = { botToken: "channel-telegram:secret:bot-token" } as const;
 
 // Numeric chat/group id (groups and channels are negative) or a public @channelname.
 const TELEGRAM_CHAT_ID_PATTERN = /^(-?\d{1,20}|@[A-Za-z][A-Za-z0-9_]{3,31})$/;
 // `<bot id>:<secret>`; the token is spliced into the URL path, so only the real shape passes.
 const TELEGRAM_BOT_TOKEN_PATTERN = /^\d{1,20}:[A-Za-z0-9_-]{10,}$/;
 
+export function isTelegramChatId(address: string): boolean {
+  return TELEGRAM_CHAT_ID_PATTERN.test(address);
+}
+
+export function isTelegramBotToken(token: string): boolean {
+  return TELEGRAM_BOT_TOKEN_PATTERN.test(token);
+}
+
 export function createTelegramChannel(
   options: TelegramChannelOptions,
   botTokenKey: string,
 ): DeliveryChannel {
   const apiBaseUrl = options.apiBaseUrl ?? TELEGRAM_DEFAULT_API_BASE_URL;
+  const allowedHosts = options.allowedHosts ?? TELEGRAM_DEFAULT_ALLOWED_HOSTS;
+  const requireHttps = options.requireHttps ?? true;
+
+  // Fail at boot: a misconfigured base URL must not surface as per-send failures.
+  let parsedBase: URL;
+  try {
+    parsedBase = new URL(apiBaseUrl);
+  } catch {
+    throw new Error("channel-telegram: apiBaseUrl is not a valid URL");
+  }
+  if (!allowedHosts.includes(parsedBase.hostname)) {
+    throw new Error(
+      `channel-telegram: apiBaseUrl host "${parsedBase.hostname}" is not in allowedHosts`,
+    );
+  }
+  if (requireHttps && parsedBase.protocol !== "https:") {
+    throw new Error(
+      "channel-telegram: apiBaseUrl must use https (set requireHttps: false to opt out)",
+    );
+  }
 
   return {
     name: "telegram",
     mode: "queued",
 
     async send(address, message, ctx) {
-      if (!TELEGRAM_CHAT_ID_PATTERN.test(address)) {
+      if (!isTelegramChatId(address)) {
         return toChannelResult(address, { ok: false, code: "invalid_address" });
       }
       let token: string | undefined;
@@ -46,21 +81,14 @@ export function createTelegramChannel(
       } catch {
         token = undefined;
       }
-      if (!token || !TELEGRAM_BOT_TOKEN_PATTERN.test(token)) {
+      if (!token || !isTelegramBotToken(token)) {
         return toChannelResult(address, { ok: false, code: "missing_credentials" });
       }
 
-      // The base URL is the allowlist: only its own host is reachable.
-      let baseHost: string;
-      try {
-        baseHost = new URL(apiBaseUrl).hostname;
-      } catch {
-        return toChannelResult(address, { ok: false, code: "host_not_allowed" });
-      }
       const result = await postChatWebhook({
         url: `${apiBaseUrl.replace(/\/+$/, "")}/bot${token}/sendMessage`,
-        allowedHosts: [baseHost],
-        requireHttps: apiBaseUrl.startsWith("https:"),
+        allowedHosts,
+        requireHttps,
         timeoutMs: options.timeoutMs ?? DEFAULT_CHAT_TIMEOUT_MS,
         // No parse_mode: Telegram renders the text literally.
         body: {

package/packages/bundled-features/src/delivery/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.341.0",
+    "type": "breaking",
+    "title": "Chat channels deliver in production boot, ctx.notify returns a NotifyResult",
+    "detail": "Chat channels (slack, discord, teams, telegram) now deliver in production boot. `runProdApp`, `runDevApp` and `runWorkerApp` pass the tenant secrets to the delivery service and hand queued channels to the `delivery.render`/`delivery.send` jobs of the calling context's job runner. `delivery.render` now receives `ctx.secrets` as well. Without a job runner, queued channels still deliver inline, now with secrets. `runBootstrap` is a one-shot process whose queue nobody drains after it exits, so it keeps delivering queued channels inline (the SystemAdmin invitation goes out before the process ends).\n`NotifyFn` returns a `NotifyResult` (`{ deliveries }` with channel, recipientId, status `queued | sent | failed | skipped`, error and `deliveryAttemptId` per delivery) instead of `void`. `NotifyOptions.immediate` delivers queued channels inline for one call and bypasses job retry, for \"send test message\" handlers. `NotifyFactory` takes an optional job dispatcher as third argument, and `DeliveryService.notify` an optional per-call dispatcher.\nConsumers: `NotifyFn` implementations in tests and mocks must now return a `NotifyResult`, e.g. `async () => ({ deliveries: [] })`. When running the API without a worker (`runSingleInstance: false`), a dedicated worker must process the delivery jobs.",
+    "migration": "NotifyFn implementations in tests and mocks must return a NotifyResult, e.g. async () => ({ deliveries: [] }). Queued channels now run through the delivery jobs in production; an API-only deployment (runSingleInstance: false) needs a worker that mounts delivery and the channel features."
+  },
   {
     "version": "0.339.0",
     "type": "improvement",