@cosmicdrift/kumiko-bundled-features 0.338.0 → 0.339.0

package/dist/billing-foundation/types.d.ts

@@ -2,7 +2,7 @@
 import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { HandlerContext, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
-import { type BillingEventKinds, type BillingPlanAction, SUBSCRIPTION_PROVIDER_EXTENSION, type SubscriptionCancelTiming, type SubscriptionEventType, type SubscriptionStatus } from "./constants.js";
+import { type BillingEventKinds, type BillingPlanAction, SUBSCRIPTION_PROVIDER_EXTENSION, type SubscriptionCancelTiming, type SubscriptionEventType, type SubscriptionStatus, type TerminationScope } from "./constants.js";
 export type SubscriptionEvent = {
     /** Discriminator against PaymentEvent. Optional (instead of required) so
      *  existing plugins like subscription-mollie, which don't set this field,
@@ -289,6 +289,11 @@ export type ConsumerProtectionOptions = {
     /** Per-locale VAT note; must carry at least `de` and `en`. */
     readonly vatNote: Readonly<Record<string, string>>;
     readonly operatorEmail: string;
+    /** Where the public § 312k declaration is reachable. `"tenant-host"`
+     *  (default): on a host that resolves a tenant. `"platform"`: also on a
+     *  host that resolves none (the platform apex) — the declaration then runs
+     *  without a request tenant and finds the contract by the declarant's email. */
+    readonly terminationScope?: TerminationScope;
     /** Root-relative paths or absolute https URLs. */
     readonly legalLinks: {
         readonly terms: string;

package/dist/billing-foundation/validate-options.js

@@ -3,6 +3,7 @@
 // concerns (app-feature-structure guard's 300-line budget). Internal — not
 // re-exported from index.ts.
 import * as z from "zod";
+import { isTerminationScope, TERMINATION_SCOPES } from "./constants.js";
 function isRootRelativePath(path) {
     return path.startsWith("/") && !path.startsWith("//");
 }
@@ -28,6 +29,9 @@ function validateConsumerProtection(cp) {
     if (!z.email().safeParse(cp.operatorEmail).success) {
         throw new Error(`createBillingFoundationFeature: consumerProtection.operatorEmail "${cp.operatorEmail}" is not a valid email address.`);
     }
+    if (cp.terminationScope !== undefined && !isTerminationScope(cp.terminationScope)) {
+        throw new Error(`createBillingFoundationFeature: consumerProtection.terminationScope "${String(cp.terminationScope)}" must be one of ${TERMINATION_SCOPES.map((scope) => `"${scope}"`).join(", ")}.`);
+    }
     for (const [key, link] of Object.entries(cp.legalLinks)) {
         if (!isRootRelativeOrHttpsUrl(link)) {
             throw new Error(`createBillingFoundationFeature: consumerProtection.legalLinks.${key} "${link}" must be a root-relative path ("/..." not "//") or an absolute https URL.`);

package/dist/channel-discord/discord-channel.d.ts

@@ -0,0 +1,6 @@
+import { type ChatWebhookChannelOptions, type DeliveryChannel } from "../delivery/index.js";
+export type DiscordChannelOptions = ChatWebhookChannelOptions;
+export declare const DISCORD_DEFAULT_ALLOWED_HOSTS: readonly ["discord.com", "discordapp.com"];
+export declare const DISCORD_WEBHOOK_PATH_PREFIX = "/api/webhooks/";
+export declare const DISCORD_CONTENT_MAX_CHARS = 2000;
+export declare function createDiscordChannel(options: DiscordChannelOptions, keyFor: (connection: string) => string): DeliveryChannel;

package/dist/channel-discord/discord-channel.js

@@ -0,0 +1,19 @@
+import { chatMessageText, createChatWebhookChannel, truncateChars, } from "../delivery/index.js";
+export const DISCORD_DEFAULT_ALLOWED_HOSTS = ["discord.com", "discordapp.com"];
+export const DISCORD_WEBHOOK_PATH_PREFIX = "/api/webhooks/";
+export const DISCORD_CONTENT_MAX_CHARS = 2000;
+export function createDiscordChannel(options, keyFor) {
+    return createChatWebhookChannel({
+        name: "discord",
+        featureName: "channel-discord",
+        defaultAllowedHosts: DISCORD_DEFAULT_ALLOWED_HOSTS,
+        requiredPathPrefix: DISCORD_WEBHOOK_PATH_PREFIX,
+        keyFor,
+        // parse: [] keeps @everyone / @here / role and user mentions in the text inert.
+        buildBody: (message) => ({
+            content: truncateChars(chatMessageText(message), DISCORD_CONTENT_MAX_CHARS),
+            allowed_mentions: { parse: [] },
+        }),
+        options,
+    });
+}

package/dist/channel-discord/feature.d.ts

@@ -0,0 +1,3 @@
+import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { type DiscordChannelOptions } from "./discord-channel.js";
+export declare function createChannelDiscordFeature(options?: DiscordChannelOptions): FeatureDefinition;

package/dist/channel-discord/feature.js

@@ -0,0 +1,30 @@
+import { chatConnectionNameSchema, DELIVERY_CHANNEL_EXTENSION, } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { createDiscordChannel } from "./discord-channel.js";
+export function createChannelDiscordFeature(options = {}) {
+    return defineFeature("channel-discord", (r) => {
+        r.describe('Posts delivery notifications to a Discord webhook, registered as the `discord` channel in the delivery system. Tenant-owned chat target: reach it only via `ctx.notify(type, { route: { discord: "<connection name>" } })`. The webhook URL is a tenant secret under `channel-discord:webhooks.<connection name>`; only the connection name is logged. Mentions are disabled and content is cut to 2000 characters. Requires `delivery` and `secrets`. Host allowlist (discord.com, discordapp.com, path /api/webhooks/), https-only and the request timeout are app options of `createChannelDiscordFeature(opts)`, never tenant config.');
+        r.uiHints({
+            displayLabel: "Discord Channel",
+            category: "notifications",
+            recommended: false,
+        });
+        r.requires("delivery");
+        r.requires("secrets");
+        const webhooks = r.secretNamespace("webhooks", {
+            label: { en: "Discord webhooks", de: "Discord-Webhooks", es: "Webhooks de Discord" },
+            hint: {
+                en: 'One secret per connection name; the value is the Discord webhook URL. Address it with route: { discord: "<connection name>" }.',
+                de: 'Ein Secret pro Verbindungsname; der Wert ist die Discord-Webhook-URL. Adressierung mit route: { discord: "<Verbindungsname>" }.',
+                es: 'Un secreto por nombre de conexión; el valor es la URL del webhook de Discord. Se usa con route: { discord: "<nombre de conexión>" }.',
+            },
+            scope: "tenant",
+            nameSchema: chatConnectionNameSchema,
+        });
+        const channel = createDiscordChannel(options, webhooks.keyFor);
+        r.useExtension(DELIVERY_CHANNEL_EXTENSION, "discord", {
+            mode: channel.mode,
+            send: channel.send,
+        });
+    });
+}

package/dist/channel-discord/index.d.ts

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

package/dist/channel-discord/index.js

@@ -0,0 +1,2 @@
+export { createDiscordChannel } from "./discord-channel.js";
+export { createChannelDiscordFeature } from "./feature.js";

package/dist/channel-slack/feature.d.ts

@@ -0,0 +1,3 @@
+import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { type SlackChannelOptions } from "./slack-channel.js";
+export declare function createChannelSlackFeature(options?: SlackChannelOptions): FeatureDefinition;

package/dist/channel-slack/feature.js

@@ -0,0 +1,30 @@
+import { chatConnectionNameSchema, DELIVERY_CHANNEL_EXTENSION, } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { createSlackChannel } from "./slack-channel.js";
+export function createChannelSlackFeature(options = {}) {
+    return defineFeature("channel-slack", (r) => {
+        r.describe('Posts delivery notifications to a Slack incoming webhook, registered as the `slack` channel in the delivery system. Tenant-owned chat target: reach it only via `ctx.notify(type, { route: { slack: "<connection name>" } })`. The webhook URL is a tenant secret under `channel-slack:webhooks.<connection name>`; only the connection name is logged. Requires `delivery` and `secrets`. Host allowlist (hooks.slack.com), https-only and the request timeout are app options of `createChannelSlackFeature(opts)`, never tenant config.');
+        r.uiHints({
+            displayLabel: "Slack Channel",
+            category: "notifications",
+            recommended: false,
+        });
+        r.requires("delivery");
+        r.requires("secrets");
+        const webhooks = r.secretNamespace("webhooks", {
+            label: { en: "Slack webhooks", de: "Slack-Webhooks", es: "Webhooks de Slack" },
+            hint: {
+                en: 'One secret per connection name; the value is the Slack webhook URL. Address it with route: { slack: "<connection name>" }.',
+                de: 'Ein Secret pro Verbindungsname; der Wert ist die Slack-Webhook-URL. Adressierung mit route: { slack: "<Verbindungsname>" }.',
+                es: 'Un secreto por nombre de conexión; el valor es la URL del webhook de Slack. Se usa con route: { slack: "<nombre de conexión>" }.',
+            },
+            scope: "tenant",
+            nameSchema: chatConnectionNameSchema,
+        });
+        const channel = createSlackChannel(options, webhooks.keyFor);
+        r.useExtension(DELIVERY_CHANNEL_EXTENSION, "slack", {
+            mode: channel.mode,
+            send: channel.send,
+        });
+    });
+}

package/dist/channel-slack/index.d.ts

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

package/dist/channel-slack/index.js

@@ -0,0 +1,2 @@
+export { createChannelSlackFeature } from "./feature.js";
+export { createSlackChannel } from "./slack-channel.js";

package/dist/channel-slack/slack-channel.d.ts

@@ -0,0 +1,5 @@
+import { type ChatWebhookChannelOptions, type DeliveryChannel } from "../delivery/index.js";
+export type SlackChannelOptions = ChatWebhookChannelOptions;
+export declare const SLACK_DEFAULT_ALLOWED_HOSTS: readonly ["hooks.slack.com"];
+export declare function escapeSlackText(text: string): string;
+export declare function createSlackChannel(options: SlackChannelOptions, keyFor: (connection: string) => string): DeliveryChannel;

package/dist/channel-slack/slack-channel.js

@@ -0,0 +1,16 @@
+import { chatMessageText, createChatWebhookChannel, } from "../delivery/index.js";
+export const SLACK_DEFAULT_ALLOWED_HOSTS = ["hooks.slack.com"];
+// Slack mrkdwn treats & < > as control characters (links, @-mentions via <!channel>).
+export function escapeSlackText(text) {
+    return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+export function createSlackChannel(options, keyFor) {
+    return createChatWebhookChannel({
+        name: "slack",
+        featureName: "channel-slack",
+        defaultAllowedHosts: SLACK_DEFAULT_ALLOWED_HOSTS,
+        keyFor,
+        buildBody: (message) => ({ text: escapeSlackText(chatMessageText(message)) }),
+        options,
+    });
+}

package/dist/channel-teams/feature.d.ts

@@ -0,0 +1,3 @@
+import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { type TeamsChannelOptions } from "./teams-channel.js";
+export declare function createChannelTeamsFeature(options?: TeamsChannelOptions): FeatureDefinition;

package/dist/channel-teams/feature.js

@@ -0,0 +1,34 @@
+import { chatConnectionNameSchema, DELIVERY_CHANNEL_EXTENSION, } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { createTeamsChannel } from "./teams-channel.js";
+export function createChannelTeamsFeature(options = {}) {
+    return defineFeature("channel-teams", (r) => {
+        r.describe('Posts delivery notifications to a Microsoft Teams webhook (Workflows or connector) as an Adaptive Card, registered as the `teams` channel in the delivery system. Tenant-owned chat target: reach it only via `ctx.notify(type, { route: { teams: "<connection name>" } })`. The webhook URL is a tenant secret under `channel-teams:webhooks.<connection name>`; only the connection name is logged. Requires `delivery` and `secrets`. Host allowlist (.webhook.office.com, .logic.azure.com, .powerplatform.com), https-only and the request timeout are app options of `createChannelTeamsFeature(opts)`, never tenant config.');
+        r.uiHints({
+            displayLabel: "Microsoft Teams Channel",
+            category: "notifications",
+            recommended: false,
+        });
+        r.requires("delivery");
+        r.requires("secrets");
+        const webhooks = r.secretNamespace("webhooks", {
+            label: {
+                en: "Microsoft Teams webhooks",
+                de: "Microsoft Teams-Webhooks",
+                es: "Webhooks de Microsoft Teams",
+            },
+            hint: {
+                en: 'One secret per connection name; the value is the Microsoft Teams webhook URL. Address it with route: { teams: "<connection name>" }.',
+                de: 'Ein Secret pro Verbindungsname; der Wert ist die Microsoft Teams-Webhook-URL. Adressierung mit route: { teams: "<Verbindungsname>" }.',
+                es: 'Un secreto por nombre de conexión; el valor es la URL del webhook de Microsoft Teams. Se usa con route: { teams: "<nombre de conexión>" }.',
+            },
+            scope: "tenant",
+            nameSchema: chatConnectionNameSchema,
+        });
+        const channel = createTeamsChannel(options, webhooks.keyFor);
+        r.useExtension(DELIVERY_CHANNEL_EXTENSION, "teams", {
+            mode: channel.mode,
+            send: channel.send,
+        });
+    });
+}

package/dist/channel-teams/index.d.ts

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

package/dist/channel-teams/index.js

@@ -0,0 +1,2 @@
+export { createChannelTeamsFeature } from "./feature.js";
+export { createTeamsChannel } from "./teams-channel.js";

package/dist/channel-teams/teams-channel.d.ts

@@ -0,0 +1,5 @@
+import { type ChatWebhookChannelOptions, type DeliveryChannel } from "../delivery/index.js";
+export type TeamsChannelOptions = ChatWebhookChannelOptions;
+export declare const TEAMS_DEFAULT_ALLOWED_HOSTS: readonly [".webhook.office.com", ".logic.azure.com", ".powerplatform.com"];
+export declare function buildTeamsAdaptiveCard(title: string, body: string | undefined): unknown;
+export declare function createTeamsChannel(options: TeamsChannelOptions, keyFor: (connection: string) => string): DeliveryChannel;

package/dist/channel-teams/teams-channel.js

@@ -0,0 +1,38 @@
+import { createChatWebhookChannel, } from "../delivery/index.js";
+export const TEAMS_DEFAULT_ALLOWED_HOSTS = [
+    ".webhook.office.com",
+    ".logic.azure.com",
+    ".powerplatform.com",
+];
+// Text only ever goes into TextBlocks (no markup interpretation of titles/bodies
+// beyond Adaptive Card's own text rendering).
+export function buildTeamsAdaptiveCard(title, body) {
+    return {
+        type: "message",
+        attachments: [
+            {
+                contentType: "application/vnd.microsoft.card.adaptive",
+                contentUrl: null,
+                content: {
+                    $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
+                    type: "AdaptiveCard",
+                    version: "1.4",
+                    body: [
+                        { type: "TextBlock", text: title, weight: "Bolder", wrap: true },
+                        ...(body ? [{ type: "TextBlock", text: body, wrap: true }] : []),
+                    ],
+                },
+            },
+        ],
+    };
+}
+export function createTeamsChannel(options, keyFor) {
+    return createChatWebhookChannel({
+        name: "teams",
+        featureName: "channel-teams",
+        defaultAllowedHosts: TEAMS_DEFAULT_ALLOWED_HOSTS,
+        keyFor,
+        buildBody: (message) => buildTeamsAdaptiveCard(message.title, message.body),
+        options,
+    });
+}

package/dist/channel-telegram/feature.d.ts

@@ -0,0 +1,3 @@
+import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { type TelegramChannelOptions } from "./telegram-channel.js";
+export declare function createChannelTelegramFeature(options?: TelegramChannelOptions): FeatureDefinition;

package/dist/channel-telegram/feature.js

@@ -0,0 +1,28 @@
+import { DELIVERY_CHANNEL_EXTENSION } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { createTelegramChannel } from "./telegram-channel.js";
+export function createChannelTelegramFeature(options = {}) {
+    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.');
+        r.uiHints({
+            displayLabel: "Telegram Channel",
+            category: "notifications",
+            recommended: false,
+        });
+        r.requires("delivery");
+        r.requires("secrets");
+        const botToken = r.secret("botToken", {
+            label: { en: "Telegram bot token" },
+            hint: {
+                en: 'Token from @BotFather. Used for every Telegram chat the tenant addresses via route: { telegram: "<chat id>" }.',
+            },
+            redact: () => "••••••••",
+            scope: "tenant",
+        });
+        const channel = createTelegramChannel(options, botToken.name);
+        r.useExtension(DELIVERY_CHANNEL_EXTENSION, "telegram", {
+            mode: channel.mode,
+            send: channel.send,
+        });
+    });
+}

package/dist/channel-telegram/index.d.ts

@@ -0,0 +1,2 @@
+export { createChannelTelegramFeature } from "./feature.js";
+export { createTelegramChannel, type TelegramChannelOptions } from "./telegram-channel.js";

package/dist/channel-telegram/index.js

@@ -0,0 +1,2 @@
+export { createChannelTelegramFeature } from "./feature.js";
+export { createTelegramChannel } from "./telegram-channel.js";

package/dist/channel-telegram/telegram-channel.d.ts

@@ -0,0 +1,8 @@
+import { type DeliveryChannel } from "../delivery/index.js";
+export type TelegramChannelOptions = {
+    readonly apiBaseUrl?: string;
+    readonly timeoutMs?: number;
+};
+export declare const TELEGRAM_DEFAULT_API_BASE_URL = "https://api.telegram.org";
+export declare const TELEGRAM_TEXT_MAX_CHARS = 4096;
+export declare function createTelegramChannel(options: TelegramChannelOptions, botTokenKey: string): DeliveryChannel;

package/dist/channel-telegram/telegram-channel.js

@@ -0,0 +1,54 @@
+import { SYSTEM_USER_ID } from "@cosmicdrift/kumiko-types/identifiers";
+import { chatMessageText, DEFAULT_CHAT_TIMEOUT_MS, postChatWebhook, toChannelResult, truncateChars, } from "../delivery/index.js";
+export const TELEGRAM_DEFAULT_API_BASE_URL = "https://api.telegram.org";
+export const TELEGRAM_TEXT_MAX_CHARS = 4096;
+// 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 createTelegramChannel(options, botTokenKey) {
+    const apiBaseUrl = options.apiBaseUrl ?? TELEGRAM_DEFAULT_API_BASE_URL;
+    return {
+        name: "telegram",
+        mode: "queued",
+        async send(address, message, ctx) {
+            if (!TELEGRAM_CHAT_ID_PATTERN.test(address)) {
+                return toChannelResult(address, { ok: false, code: "invalid_address" });
+            }
+            let token;
+            try {
+                const revealed = await ctx.secrets?.get(ctx.tenantId, botTokenKey, {
+                    userId: SYSTEM_USER_ID,
+                    handlerName: "channel-telegram:send",
+                });
+                token = revealed?.reveal();
+            }
+            catch {
+                token = undefined;
+            }
+            if (!token || !TELEGRAM_BOT_TOKEN_PATTERN.test(token)) {
+                return toChannelResult(address, { ok: false, code: "missing_credentials" });
+            }
+            // The base URL is the allowlist: only its own host is reachable.
+            let baseHost;
+            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:"),
+                timeoutMs: options.timeoutMs ?? DEFAULT_CHAT_TIMEOUT_MS,
+                // No parse_mode: Telegram renders the text literally.
+                body: {
+                    chat_id: address,
+                    text: truncateChars(chatMessageText(message), TELEGRAM_TEXT_MAX_CHARS),
+                },
+            });
+            return toChannelResult(address, result);
+        },
+    };
+}

package/dist/crypto-shredding/handlers/forget-subject.write.js

@@ -248,17 +248,17 @@ export const forgetSubjectWrite = defineWriteHandler({
                 ? { kind: "tenant", tenantId: raw.tenantId }
                 : { kind: "record", entity: raw.entity, id: raw.id };
         const subjectKey = subjectIdToKey(subject);
-        const tenantScopeDenial = await resolveTenantScopeDenial(ctx.db.unsafeRaw("tenant-scope check runs against the subject's tenant, not necessarily the caller's"), ctx.registry.features, event.user, raw);
+        const tenantScopeDenial = await resolveTenantScopeDenial(ctx.db.unsafeRaw(), ctx.registry.features, event.user, raw);
         if (tenantScopeDenial) {
-            const auditFailure = await appendDenialAuditEvent(ctx, event, subjectKey, raw.kind, denialReasonOf(tenantScopeDenial), ctx.dbOutsideTransaction?.unsafeRaw("denial audit append: names the prober's own tenant stream on the outside-transaction db"));
+            const auditFailure = await appendDenialAuditEvent(ctx, event, subjectKey, raw.kind, denialReasonOf(tenantScopeDenial), ctx.dbOutsideTransaction?.unsafeRaw());
             return auditFailure ?? tenantScopeDenial;
         }
         // Runs after the tenant gate but before any key is touched: a retention
         // check ahead of the tenant gate would leak a foreign entity's retention
         // posture to a cross-tenant prober.
-        const retentionDenial = await resolveRetentionDenial(ctx, raw, () => ctx.db.unsafeRaw("retention check reads the record row's owning tenant, not the caller's"));
+        const retentionDenial = await resolveRetentionDenial(ctx, raw, () => ctx.db.unsafeRaw());
         if (retentionDenial) {
-            const auditFailure = await appendDenialAuditEvent(ctx, event, subjectKey, raw.kind, TARGET_RECORD_RETENTION_BLOCK_DELETE, ctx.dbOutsideTransaction?.unsafeRaw("denial audit append: names the prober's own tenant stream on the outside-transaction db"));
+            const auditFailure = await appendDenialAuditEvent(ctx, event, subjectKey, raw.kind, TARGET_RECORD_RETENTION_BLOCK_DELETE, ctx.dbOutsideTransaction?.unsafeRaw());
             return auditFailure ?? retentionDenial;
         }
         // Erase BEFORE the audit append: if the append throws, the key is gone
@@ -272,7 +272,7 @@ export const forgetSubjectWrite = defineWriteHandler({
         });
         // Blind-index sweep (#818): nulls bidx columns now so the deterministic
         // HMAC doesn't stay equality-matchable; raw because the ciphertext prefix addresses the subject across tenants.
-        const crossTenantSubjectRunner = ctx.db.unsafeRaw("blind-index sweep and search purge address the subject across tenants");
+        const crossTenantSubjectRunner = ctx.db.unsafeRaw();
         await nullBlindIndexesForSubject(crossTenantSubjectRunner, ctx.registry.features, subjectKey);
         // Derived search index still holds plaintext (#1610) — purge next to the
         // blind-index sweep. No adapter → no-op (apps without search).
@@ -300,7 +300,7 @@ export const forgetSubjectWrite = defineWriteHandler({
         // update is best-effort for real users.
         if (raw.kind === "user" && ctx.registry.features.has("user")) {
             try {
-                const userLifecycleRunner = ctx.db.unsafeRaw("user lifecycle update and PAT revoke run on the SYSTEM user stream");
+                const userLifecycleRunner = ctx.db.unsafeRaw();
                 await updateUserLifecycle(userLifecycleRunner, raw.userId, { status: USER_STATUS.Deleted });
                 if (ctx.registry.features.has("personal-access-tokens")) {
                     await revokeAllPatTokensForUser(userLifecycleRunner, raw.userId);

package/dist/custom-fields/handlers/clear-custom-field.write.js

@@ -31,7 +31,7 @@ export const clearCustomFieldHandler = {
     },
     handler: async (event, ctx) => {
         const payload = event.payload; // @cast-boundary engine-payload
-        const accessCheck = await checkFieldAccessForWrite(ctx.db.unsafeRaw(CLEAR_CUSTOM_FIELD_REASON), event.user.tenantId, payload.entityName, payload.fieldKey, event.user.roles);
+        const accessCheck = await checkFieldAccessForWrite(ctx.db.unsafeRaw(), event.user.tenantId, payload.entityName, payload.fieldKey, event.user.roles);
         if (!accessCheck.ok) {
             if (accessCheck.reason === "field_definition_not_found") {
                 return failNotFound("fieldDefinition", payload.fieldKey);

package/dist/custom-fields/handlers/define-tenant-field.write.js

@@ -26,7 +26,7 @@ export function createDefineTenantFieldHandler(opts = {}) {
                 throw new Error("define-tenant-field: tenantId is SYSTEM_TENANT_ID — use define-system-field for system-scope definitions");
             }
             if (limit !== undefined) {
-                const current = await countTenantFieldDefinitions(ctx.db.unsafeRaw(DEFINE_TENANT_FIELD_REASON), tenantId);
+                const current = await countTenantFieldDefinitions(ctx.db.unsafeRaw(), tenantId);
                 if (current >= limit) {
                     return failUnprocessable("cap_exceeded", {
                         capName: "customFields.fieldDefinition.count",

package/dist/custom-fields/handlers/set-custom-field.write.js

@@ -54,7 +54,7 @@ export const setCustomFieldHandler = {
     },
     handler: async (event, ctx) => {
         const payload = event.payload; // @cast-boundary engine-payload
-        const loaded = await loadFieldDefinition(ctx.db.unsafeRaw(SET_CUSTOM_FIELD_REASON), event.user.tenantId, payload.entityName, payload.fieldKey);
+        const loaded = await loadFieldDefinition(ctx.db.unsafeRaw(), event.user.tenantId, payload.entityName, payload.fieldKey);
         if (!loaded.found) {
             return failNotFound("fieldDefinition", payload.fieldKey);
         }

package/dist/custom-fields/wire-user-data-rights.js

@@ -46,7 +46,7 @@ export function wireCustomFieldsUserDataRightsFor(r, opts) {
     const tableName = extractTableName(opts.entityTable, "custom-fields/wire-user-data-rights");
     // biome-ignore lint/correctness/useHookAtTopLevel: r.useExtension is a registrar API, not a React hook.
     r.useExtension(EXT_USER_DATA, opts.entityName, {
-        export: async (ctx) => exportCustomFields(ctx.db.unsafeRaw(CUSTOM_FIELDS_EXPORT_REASON), ctx, tableName, opts),
+        export: async (ctx) => exportCustomFields(ctx.db.unsafeRaw(), ctx, tableName, opts),
         escapeHatch: { reason: CUSTOM_FIELDS_EXPORT_REASON },
     });
 }

package/dist/data-retention/feature.js

@@ -64,7 +64,7 @@ export function createDataRetentionFeature() {
                     return;
                 }
                 const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
-                const cleanupDb = ctx.db.unsafeRaw("retention cleanup runs raw deletes and preset lookups; every statement filters by this run's tenantId"); // @cast-boundary db-operator — jobs never run inside a DbTx
+                const cleanupDb = ctx.db.unsafeRaw(); // @cast-boundary db-operator — jobs never run inside a DbTx
                 const tenantPreset = await resolveTenantRetentionPreset({
                     db: cleanupDb,
                     registry: ctx.registry,

package/dist/delivery/channel-context.d.ts

@@ -1,5 +1,6 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import { type DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import type { ChannelContext } from "./types.js";
-export declare function buildChannelContext(db: DbConnection, registry: Registry, sseBroker: SseBroker | undefined, tenantId: TenantId): ChannelContext;
+export declare function buildChannelContext(db: DbConnection, registry: Registry, sseBroker: SseBroker | undefined, tenantId: TenantId, secrets?: SecretsContext): ChannelContext;

package/dist/delivery/channel-context.js

@@ -3,6 +3,6 @@ import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 // Shared by the synchronous delivery-service path and the async job handlers
 // (which pass sseBroker=undefined — only the inline inApp channel uses SSE,
 // and it never runs through a job).
-export function buildChannelContext(db, registry, sseBroker, tenantId) {
-    return { db: createTenantDb(db, tenantId), registry, sseBroker, tenantId };
+export function buildChannelContext(db, registry, sseBroker, tenantId, secrets) {
+    return { db: createTenantDb(db, tenantId), registry, sseBroker, tenantId, secrets };
 }

package/dist/delivery/chat-webhook-channel.d.ts

@@ -0,0 +1,19 @@
+import { type ChatSendResult } from "./chat-webhook-sender.js";
+import type { ChannelMessage, ChannelResult, DeliveryChannel } from "./types.js";
+export type ChatWebhookChannelOptions = {
+    readonly allowedHosts?: readonly string[];
+    readonly requireHttps?: boolean;
+    readonly timeoutMs?: number;
+};
+export declare function toChannelResult(address: string, result: ChatSendResult): ChannelResult;
+export declare function chatMessageText(message: ChannelMessage): string;
+export type ChatWebhookChannelSpec = {
+    readonly name: string;
+    readonly featureName: string;
+    readonly defaultAllowedHosts: readonly string[];
+    readonly requiredPathPrefix?: string;
+    readonly keyFor: (connection: string) => string;
+    readonly buildBody: (message: ChannelMessage) => unknown;
+    readonly options: ChatWebhookChannelOptions;
+};
+export declare function createChatWebhookChannel(spec: ChatWebhookChannelSpec): DeliveryChannel;

package/dist/delivery/chat-webhook-channel.js

@@ -0,0 +1,48 @@
+import { SYSTEM_USER_ID } from "@cosmicdrift/kumiko-types/identifiers";
+import { chatConnectionNameSchema, DEFAULT_CHAT_TIMEOUT_MS, postChatWebhook, } from "./chat-webhook-sender.js";
+export function toChannelResult(address, result) {
+    return result.ok
+        ? { status: "sent", address }
+        : { status: "failed", error: result.code, address };
+}
+export function chatMessageText(message) {
+    return message.body ? `${message.title}\n${message.body}` : message.title;
+}
+// Slack/Discord/Teams: the route address is a tenant-chosen connection name, the
+// webhook URL lives in the secrets store under that name. Route-only (no resolve).
+export function createChatWebhookChannel(spec) {
+    const { options } = spec;
+    return {
+        name: spec.name,
+        mode: "queued",
+        async send(address, message, ctx) {
+            if (!chatConnectionNameSchema.safeParse(address).success) {
+                return toChannelResult(address, { ok: false, code: "invalid_address" });
+            }
+            let url;
+            try {
+                const revealed = await ctx.secrets?.get(ctx.tenantId, spec.keyFor(address), {
+                    userId: SYSTEM_USER_ID,
+                    handlerName: `${spec.featureName}:send`,
+                });
+                url = revealed?.reveal();
+            }
+            catch {
+                url = undefined;
+            }
+            if (!url)
+                return toChannelResult(address, { ok: false, code: "missing_credentials" });
+            const result = await postChatWebhook({
+                url,
+                allowedHosts: options.allowedHosts ?? spec.defaultAllowedHosts,
+                requireHttps: options.requireHttps ?? true,
+                ...(spec.requiredPathPrefix !== undefined && {
+                    requiredPathPrefix: spec.requiredPathPrefix,
+                }),
+                timeoutMs: options.timeoutMs ?? DEFAULT_CHAT_TIMEOUT_MS,
+                body: spec.buildBody(message),
+            });
+            return toChannelResult(address, result);
+        },
+    };
+}

package/dist/delivery/chat-webhook-sender.d.ts

@@ -0,0 +1,21 @@
+import * as z from "zod";
+export type ChatSendFailureCode = `http_${number}` | "timeout" | "network_error" | "redirect_blocked" | "host_not_allowed" | "missing_credentials" | "invalid_address";
+export type ChatSendResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly code: ChatSendFailureCode;
+};
+export declare const DEFAULT_CHAT_TIMEOUT_MS = 10000;
+export declare const chatConnectionNameSchema: z.ZodString;
+export type ChatWebhookRequest = {
+    readonly url: string;
+    readonly allowedHosts: readonly string[];
+    readonly requireHttps: boolean;
+    readonly requiredPathPrefix?: string;
+    readonly timeoutMs: number;
+    readonly body: unknown;
+    readonly send?: (url: string, init: RequestInit) => Promise<Response>;
+};
+export declare function postChatWebhook(request: ChatWebhookRequest): Promise<ChatSendResult>;
+export declare function truncateChars(text: string, maxChars: number): string;