@cosmicdrift/kumiko-samples 0.338.0 → 0.340.0

package/packages/bundled-features/src/crypto-shredding/handlers/forget-subject.write.ts

@@ -334,9 +334,7 @@ export const forgetSubjectWrite = defineWriteHandler({
     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.db.unsafeRaw(),
       ctx.registry.features,
       event.user,
       raw,
@@ -348,9 +346,7 @@ export const forgetSubjectWrite = defineWriteHandler({
         subjectKey,
         raw.kind,
         denialReasonOf(tenantScopeDenial),
-        ctx.dbOutsideTransaction?.unsafeRaw(
-          "denial audit append: names the prober's own tenant stream on the outside-transaction db",
-        ),
+        ctx.dbOutsideTransaction?.unsafeRaw(),
       );
       return auditFailure ?? tenantScopeDenial;
     }
@@ -358,9 +354,7 @@ export const forgetSubjectWrite = defineWriteHandler({
     // 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,
@@ -368,9 +362,7 @@ export const forgetSubjectWrite = defineWriteHandler({
         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",
-        ),
+        ctx.dbOutsideTransaction?.unsafeRaw(),
       );
       return auditFailure ?? retentionDenial;
     }
@@ -387,9 +379,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
@@ -425,9 +415,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/packages/bundled-features/src/custom-fields/handlers/clear-custom-field.write.ts

@@ -40,7 +40,7 @@ export const clearCustomFieldHandler: WriteHandlerDef = {
     const payload = event.payload as ClearCustomFieldPayload; // @cast-boundary engine-payload
 
     const accessCheck = await checkFieldAccessForWrite(
-      ctx.db.unsafeRaw(CLEAR_CUSTOM_FIELD_REASON),
+      ctx.db.unsafeRaw(),
       event.user.tenantId,
       payload.entityName,
       payload.fieldKey,

package/packages/bundled-features/src/custom-fields/handlers/define-tenant-field.write.ts

@@ -74,10 +74,7 @@ export function createDefineTenantFieldHandler(
       }
 
       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/packages/bundled-features/src/custom-fields/handlers/set-custom-field.write.ts

@@ -63,7 +63,7 @@ export const setCustomFieldHandler: WriteHandlerDef = {
     const payload = event.payload as SetCustomFieldPayload; // @cast-boundary engine-payload
 
     const loaded = await loadFieldDefinition(
-      ctx.db.unsafeRaw(SET_CUSTOM_FIELD_REASON),
+      ctx.db.unsafeRaw(),
       event.user.tenantId,
       payload.entityName,
       payload.fieldKey,

package/packages/bundled-features/src/custom-fields/wire-user-data-rights.ts

@@ -73,7 +73,7 @@ export function wireCustomFieldsUserDataRightsFor<TReg extends FeatureRegistrar<
   // 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: UserDataHookCtx) =>
-      exportCustomFields(ctx.db.unsafeRaw(CUSTOM_FIELDS_EXPORT_REASON), ctx, tableName, opts),
+      exportCustomFields(ctx.db.unsafeRaw(), ctx, tableName, opts),
     escapeHatch: { reason: CUSTOM_FIELDS_EXPORT_REASON },
   });
 }

package/packages/bundled-features/src/data-retention/feature.ts

@@ -95,9 +95,8 @@ export function createDataRetentionFeature(): FeatureDefinition {
           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",
-        ) as import("@cosmicdrift/kumiko-framework/db").DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
+        const cleanupDb =
+          ctx.db.unsafeRaw() as import("@cosmicdrift/kumiko-framework/db").DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
         const tenantPreset = await resolveTenantRetentionPreset({
           db: cleanupDb,
           registry: ctx.registry,

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

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.339.0",
+    "type": "improvement",
+    "title": "Slack, Discord, Microsoft Teams and Telegram delivery channels",
+    "detail": "`channel-slack`, `channel-discord`, `channel-teams` and `channel-telegram` register route-only delivery channels. Webhook URLs and the Telegram bot token live in the tenant's secrets; the send job reads them with an audit entry `<feature>:send`. `DeliveryChannel.resolve` is optional and `ChannelContext.secrets` is available on the send job path.",
+    "migration": "keine"
+  },
   {
     "version": "0.338.0",
     "type": "improvement",

package/packages/bundled-features/src/delivery/channel-context.ts

@@ -1,6 +1,7 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import { createTenantDb, 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";
 
 // Build the per-tenant context a channel's resolve/render/send receives.
@@ -12,6 +13,7 @@ export function buildChannelContext(
   registry: Registry,
   sseBroker: SseBroker | undefined,
   tenantId: TenantId,
+  secrets?: SecretsContext,
 ): ChannelContext {
-  return { db: createTenantDb(db, tenantId), registry, sseBroker, tenantId };
+  return { db: createTenantDb(db, tenantId), registry, sseBroker, tenantId, secrets };
 }

package/packages/bundled-features/src/delivery/chat-webhook-channel.ts

@@ -0,0 +1,76 @@
+import { SYSTEM_USER_ID } from "@cosmicdrift/kumiko-types/identifiers";
+import {
+  type ChatSendResult,
+  chatConnectionNameSchema,
+  DEFAULT_CHAT_TIMEOUT_MS,
+  postChatWebhook,
+} from "./chat-webhook-sender.js";
+import type { ChannelContext, ChannelMessage, ChannelResult, DeliveryChannel } from "./types.js";
+
+export type ChatWebhookChannelOptions = {
+  // Test/self-hosting override. Replaces the provider default allowlist; never
+  // reachable from tenant config or secrets.
+  readonly allowedHosts?: readonly string[];
+  readonly requireHttps?: boolean;
+  readonly timeoutMs?: number;
+};
+
+export function toChannelResult(address: string, result: ChatSendResult): ChannelResult {
+  return result.ok
+    ? { status: "sent", address }
+    : { status: "failed", error: result.code, address };
+}
+
+export function chatMessageText(message: ChannelMessage): string {
+  return message.body ? `${message.title}\n${message.body}` : message.title;
+}
+
+export type ChatWebhookChannelSpec = {
+  readonly name: string;
+  readonly featureName: string;
+  readonly defaultAllowedHosts: readonly string[];
+  readonly requiredPathPrefix?: string;
+  // Resolves the secret key for a validated connection name.
+  readonly keyFor: (connection: string) => string;
+  readonly buildBody: (message: ChannelMessage) => unknown;
+  readonly options: ChatWebhookChannelOptions;
+};
+
+// 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: ChatWebhookChannelSpec): DeliveryChannel {
+  const { options } = spec;
+  return {
+    name: spec.name,
+    mode: "queued",
+
+    async send(address, message, ctx: ChannelContext) {
+      if (!chatConnectionNameSchema.safeParse(address).success) {
+        return toChannelResult(address, { ok: false, code: "invalid_address" });
+      }
+      let url: string | undefined;
+      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/packages/bundled-features/src/delivery/chat-webhook-sender.ts

@@ -0,0 +1,135 @@
+import { BlockedHostError, type EgressPolicy, egress } from "@cosmicdrift/kumiko-framework/http";
+import * as z from "zod";
+
+// Closed vocabulary: these codes (and nothing else) land in delivery_attempts.error.
+// Never err.message and never a provider response body — a fetch error can carry
+// the request URL, and the Telegram URL embeds the bot token.
+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 const DEFAULT_CHAT_TIMEOUT_MS = 10_000;
+
+// Tenant-chosen connection name (the route address for webhook channels). Also
+// the suffix the secrets write gate accepts under the channel's namespace, so
+// the two cannot drift. Validated before it is used to build a secret key.
+export const chatConnectionNameSchema = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(/^[a-z0-9][a-z0-9-]*$/);
+
+export type ChatWebhookRequest = {
+  readonly url: string;
+  // Exact hostnames, or suffixes with a leading dot (".webhook.office.com").
+  readonly allowedHosts: readonly string[];
+  readonly requireHttps: boolean;
+  readonly requiredPathPrefix?: string;
+  readonly timeoutMs: number;
+  readonly body: unknown;
+  // Test seam; production always uses the policy-bound egress().
+  readonly send?: (url: string, init: RequestInit) => Promise<Response>;
+};
+
+// https targets are provider endpoints on public hosts: egress "external" adds
+// the private/reserved-range denial and DNS pinning on top of our allowlist. The
+// cleartext opt-out (requireHttps: false) exists for operator-trusted local
+// endpoints, which "external" would refuse; the allowlist already pins the host.
+function policyFor(request: ChatWebhookRequest, target: URL): EgressPolicy {
+  return request.requireHttps
+    ? { kind: "external" }
+    : { kind: "internal", allowHosts: [target.hostname] };
+}
+
+function hostMatches(hostname: string, allowedHost: string): boolean {
+  const allowed = allowedHost.toLowerCase();
+  if (allowed.startsWith(".")) {
+    return hostname.length > allowed.length && hostname.endsWith(allowed);
+  }
+  return hostname === allowed;
+}
+
+// Allowlist runs on the parsed URL, never on the raw string: userinfo
+// (`https://hooks.slack.com@evil.com`) and look-alike suffixes must not pass.
+function checkTarget(request: ChatWebhookRequest): URL | undefined {
+  let parsed: URL;
+  try {
+    parsed = new URL(request.url);
+  } catch {
+    return undefined;
+  }
+  const protocolAllowed =
+    parsed.protocol === "https:" || (!request.requireHttps && parsed.protocol === "http:");
+  if (!protocolAllowed) return undefined;
+  // egress() has no port rule; a provider webhook over https never needs a custom port.
+  if (request.requireHttps && parsed.port !== "") return undefined;
+  if (parsed.username !== "" || parsed.password !== "") return undefined;
+  const hostname = parsed.hostname.toLowerCase();
+  if (!request.allowedHosts.some((allowed) => hostMatches(hostname, allowed))) return undefined;
+  if (
+    request.requiredPathPrefix !== undefined &&
+    !parsed.pathname.startsWith(request.requiredPathPrefix)
+  ) {
+    return undefined;
+  }
+  return parsed;
+}
+
+function isTimeout(err: unknown): boolean {
+  return err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError");
+}
+
+// egress(internal) follows same-host redirects itself and throws on cross-host
+// ones; both are the "redirect" outcome here. Matched on the stable message
+// prefix only — the message is discarded, it can carry the Location header.
+function isEgressRedirectRefusal(err: unknown): boolean {
+  return err instanceof Error && err.message.startsWith("egress(internal): redirect");
+}
+
+function classifyFailure(err: unknown): ChatSendFailureCode {
+  if (err instanceof BlockedHostError) return "host_not_allowed";
+  if (isEgressRedirectRefusal(err)) return "redirect_blocked";
+  return isTimeout(err) ? "timeout" : "network_error";
+}
+
+// Never throws and never surfaces the URL: egress/Bun errors can carry it, so
+// every failure is reduced to a code here.
+export async function postChatWebhook(request: ChatWebhookRequest): Promise<ChatSendResult> {
+  const target = checkTarget(request);
+  if (!target) return { ok: false, code: "host_not_allowed" };
+
+  let response: Response;
+  try {
+    const send = request.send ?? egress(policyFor(request, target));
+    response = await send(target.toString(), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(request.body),
+      signal: AbortSignal.timeout(request.timeoutMs),
+    });
+  } catch (err) {
+    return { ok: false, code: classifyFailure(err) };
+  }
+
+  // Free the connection; the body is never read or stored.
+  await response.body?.cancel().catch(() => undefined);
+
+  const { status } = response;
+  if (status >= 300 && status < 400) return { ok: false, code: "redirect_blocked" };
+  if (status >= 200 && status < 300) return { ok: true };
+  return { ok: false, code: `http_${status}` };
+}
+
+export function truncateChars(text: string, maxChars: number): string {
+  const chars = Array.from(text);
+  return chars.length <= maxChars ? text : chars.slice(0, maxChars).join("");
+}

package/packages/bundled-features/src/delivery/delivery-service.ts

@@ -375,6 +375,9 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     const channelCtx = buildChannelContext(db, registry, sseBroker, tenantId);
 
     for (const channel of channels) {
+      // Route-only channel (no per-user address): not a user-notification target.
+      if (!channel.resolve) continue;
+
       const message = buildMessage(notificationType, data, channel.name);
 
       // Kill switch: tenant admin disabled this channel entirely

package/packages/bundled-features/src/delivery/index.ts

@@ -1,4 +1,19 @@
 export { hashUnsubscribeAddress } from "./address-opt-out.js";
+export {
+  type ChatWebhookChannelOptions,
+  chatMessageText,
+  createChatWebhookChannel,
+  toChannelResult,
+} from "./chat-webhook-channel.js";
+export {
+  type ChatSendFailureCode,
+  type ChatSendResult,
+  type ChatWebhookRequest,
+  chatConnectionNameSchema,
+  DEFAULT_CHAT_TIMEOUT_MS,
+  postChatWebhook,
+  truncateChars,
+} from "./chat-webhook-sender.js";
 export type { DeliveryStatusValue } from "./constants.js";
 export {
   DELIVERY_CHANNEL_EXTENSION,

package/packages/bundled-features/src/delivery/jobs.ts

@@ -147,7 +147,7 @@ export const deliverySendJob: JobHandlerFn = async (payload, ctx) => {
   const tenantId = p.tenantId as TenantId; // @cast-boundary engine-payload — stream tenant
   const { db, registry } = requireTenantScopedDeps(ctx, tenantId);
   const channel = resolveChannel(registry, p.channelName);
-  const channelCtx = buildChannelContext(db, registry, undefined, tenantId);
+  const channelCtx = buildChannelContext(db, registry, undefined, tenantId, ctx.secrets);
 
   try {
     const result = await channel.send(p.address, toMessage(p), channelCtx, p.rendered);

package/packages/bundled-features/src/delivery/testing.ts

@@ -5,6 +5,7 @@ import type {
   Registry,
   TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
+import type { JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
 import type { Logger } from "@cosmicdrift/kumiko-framework/logging";
 import type { Redis } from "ioredis";
 import type { KillSwitchResolver, RateLimitConfig } from "./delivery-service.js";
@@ -17,6 +18,7 @@ export type CreateDeliveryTestContextOptions = {
   readonly isChannelKilled?: KillSwitchResolver;
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
   readonly log?: Logger;
+  readonly jobRunner?: JobRunner;
 };
 
 /**

package/packages/bundled-features/src/delivery/types.ts

@@ -7,6 +7,7 @@ import type {
   SessionUser,
   TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import { DELIVERY_CHANNEL_EXTENSION } from "./constants.js";
 
 // --- Channel Interface ---
@@ -16,6 +17,9 @@ export type ChannelContext = {
   readonly registry: Registry;
   readonly sseBroker: SseBroker | undefined;
   readonly tenantId: TenantId;
+  // Only wired on the delivery.send job path. Chat channels read their
+  // per-tenant webhook URL / bot token from it; inline sends have none.
+  readonly secrets?: SecretsContext | undefined;
 };
 
 export type ChannelMessage = {
@@ -49,7 +53,9 @@ export type DeliveryChannelMode = (typeof DELIVERY_CHANNEL_MODES)[number];
 export type DeliveryChannel = {
   readonly name: string;
   readonly mode: DeliveryChannelMode;
-  resolve(userId: string, ctx: ChannelContext): Promise<string | null>;
+  // Absent for channels addressed only through `route` (tenant-owned chat
+  // targets): deliverToUser skips them without writing a no_address row.
+  resolve?(userId: string, ctx: ChannelContext): Promise<string | null>;
   render?(message: ChannelMessage, ctx: ChannelContext): Promise<RenderedMessage>;
   send(
     address: string,
@@ -106,8 +112,7 @@ export function isDeliveryChannelPlugin(o: unknown): o is DeliveryChannelPlugin
     "mode" in o &&
     DELIVERY_CHANNEL_MODES.some((mode) => mode === o.mode) &&
     (!("render" in o) || o.render === undefined || typeof o.render === "function") &&
-    "resolve" in o &&
-    typeof o.resolve === "function" &&
+    (!("resolve" in o) || o.resolve === undefined || typeof o.resolve === "function") &&
     "send" in o &&
     typeof o.send === "function"
   );

package/packages/bundled-features/src/file-derivatives/handlers/public-variant-by-file-ref.query.ts

@@ -38,7 +38,7 @@ export const publicVariantByFileRefQuery = defineQueryHandler({
     reason: BY_FILE_REF_ESCAPE_HATCH_REASON,
   },
   handler: async (query, ctx) => {
-    const db = ctx.db.unsafeRaw(BY_FILE_REF_ESCAPE_HATCH_REASON);
+    const db = ctx.db.unsafeRaw();
     const row = await fetchOne<FileRefTenantRow>(db, fileRefsTable, {
       id: query.payload.fileRefId,
       isDeleted: false,

package/packages/bundled-features/src/files-tenant-data/index.ts

@@ -55,7 +55,7 @@ export function createFilesTenantDataFeature(): FeatureDefinition {
         sweepOrphanedDerivativesJob(
           payload,
           ctx,
-          ctx.db.unsafeRaw(SWEEP_ORPHANED_DERIVATIVES_ESCAPE_HATCH_REASON) as DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
+          ctx.db.unsafeRaw() as DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
         ),
     });
   });

package/packages/bundled-features/src/form-draft/feature.ts

@@ -51,7 +51,7 @@ function registerFormDraft(r: FeatureRegistrar<typeof FORM_DRAFT_FEATURE_NAME>):
       cleanupDraftsJob(
         payload,
         ctx,
-        ctx.db.unsafeRaw(CLEANUP_ESCAPE_HATCH_REASON) as DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
+        ctx.db.unsafeRaw() as DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
       ),
   });
 }

package/packages/bundled-features/src/form-draft/handlers/discard.write.ts

@@ -69,7 +69,7 @@ export const discardDraftWrite = defineWriteHandler({
       // predates the draft row, so the insertedAt filter must not apply.
       const isCreateMode = event.payload.draftKey.includes(":new:");
       const ownedRefs = await filterOwnedFileRefs(
-        ctx.db.unsafeRaw(DISCARD_DRAFT_FILE_REFS_REASON),
+        ctx.db.unsafeRaw(),
         event.user.tenantId,
         ownerId,
         candidateKeys,

package/packages/bundled-features/src/form-draft/handlers/save.write.ts

@@ -62,11 +62,7 @@ export const saveDraftWrite = defineWriteHandler({
     // Cap check only on the create path — an update never grows the number
     // of drafts this owner has, so a user already at the limit can still
     // keep saving their existing drafts.
-    const draftCount = await countDraftsByOwner(
-      ctx.db.unsafeRaw(SAVE_DRAFT_COUNT_REASON),
-      event.user.tenantId,
-      ownerId,
-    );
+    const draftCount = await countDraftsByOwner(ctx.db.unsafeRaw(), event.user.tenantId, ownerId);
     if (draftCount >= FORM_DRAFT_MAX_PER_OWNER) {
       return failUnprocessable("draft_limit_reached", { limit: FORM_DRAFT_MAX_PER_OWNER });
     }

package/packages/bundled-features/src/inbound-mail-foundation/changes.json

@@ -1,4 +1,18 @@
 [
+  {
+    "version": "0.340.0",
+    "type": "improvement",
+    "title": "Inbound mail projections use typed bun-db helpers",
+    "detail": "Mail-account and mail-thread events upsert through `upsertOnConflict` (`connectedAt` is only written on insert), inbound messages insert through `insertOnConflictDoNothing`. The raw `db/queries/inbound-projections.ts` module is gone.",
+    "migration": "keine"
+  },
+  {
+    "version": "0.339.0",
+    "type": "improvement",
+    "title": "Inbound mail OAuth accounts refresh their access token",
+    "detail": "`createInboundMailSupervisor` obtains a valid access token via the new `createOAuthAccessTokenManager` before `plugin.fetch`/`plugin.watch` for accounts whose provider declares `oauth` and whose authMethod is `oauth`/`xoauth2`, and passes it as `opts.accessToken` (`fetch`) or `{ accessToken }` (`watch`, 4th argument). `refreshAccessToken` receives an optional 4th argument `{ signal }` (aborted after 30 s); providers must pass it to their token-endpoint fetch, since the foundation awaits the provider and never drops a late result. The foundation has no single construction point for routes and supervisor, so apps that want connect to prime the cache and write under the refresh lock create one manager with `createOAuthAccessTokenManager({ db, secrets })` and pass it to both `createInboundMailSupervisor({ oauthTokens })` and `createInboundMailConnectRoutes({ oauthTokens })`; without it the supervisor builds its own manager and the callback writes the secret without the lock. `InboundAuthError` from `refreshAccessToken` moves the account to `auth_error`; the generic sync-error log and the `token_exchange_failed` response body no longer contain provider error messages.",
+    "migration": "Apps with OAuth inbound accounts create one `createOAuthAccessTokenManager({ db, secrets })` and pass it as `oauthTokens` to both `createInboundMailSupervisor` and `createInboundMailConnectRoutes`. Provider plugins with a `refreshAccessToken` pass the `signal` from its fourth argument to their token-endpoint fetch."
+  },
   {
     "version": "0.335.0",
     "type": "fix",

package/packages/bundled-features/src/inbound-mail-foundation/connect-routes.ts

@@ -24,6 +24,10 @@ import {
   InboundMailFoundationHandlers,
   inboundCredentialSecretKey,
 } from "./constants.js";
+import {
+  inboundRefreshTokenSecretOptions,
+  type OAuthAccessTokenManager,
+} from "./oauth-access-token.js";
 import { type OAuthStatePayload, signOAuthState, verifyOAuthState } from "./oauth-state.js";
 import { resolveInboundProviderForKey } from "./provider-factory.js";
 
@@ -46,6 +50,12 @@ export type InboundMailConnectRoutesOptions = {
   readonly connectPath?: string;
   /** Default "/inbound-mail/oauth/callback". */
   readonly callbackPath?: string;
+  /** Apps wire the supervisor and these routes separately, so build ONE
+   *  manager (`createOAuthAccessTokenManager`) and share it with `createInboundMailSupervisor({ oauthTokens })`:
+   *  the callback then writes the refresh token under the account's refresh
+   *  lock and primes the access-token cache from the code exchange. Omitted
+   *  → plain secret write, no cache priming. */
+  readonly oauthTokens?: OAuthAccessTokenManager;
 };
 
 function errorJson(c: Context, status: 400 | 401 | 404 | 500 | 502, code: string, message: string) {
@@ -185,12 +195,13 @@ export function createInboundMailConnectRoutes(
           code,
           redirectUri: options.callbackUrl,
         });
-      } catch (e) {
+      } catch {
+        // Provider error messages can carry token/response data — code only.
         return errorJson(
           c,
           502,
           "token_exchange_failed",
-          e instanceof Error ? e.message : String(e),
+          "token exchange with the provider failed",
         );
       }
       if (!tokens.refreshToken) {
@@ -228,17 +239,22 @@ export function createInboundMailConnectRoutes(
       }
 
       // Refresh-token into the per-account secret slot (Slot = accountId).
-      // Access tokens (~1h) are NEVER persisted — refresh-before-poll in the
-      // sync path.
-      await deps.secrets.set(
-        state.tenantId,
-        inboundCredentialSecretKey(accountId),
-        tokens.refreshToken,
-        {
-          redact: (plaintext) => `${plaintext.slice(0, 4)}…`,
-          hint: `OAuth refresh token for inbound mail account ${accountId}`,
-        },
-      );
+      // Access tokens (~1h) are never persisted — the supervisor re-mints
+      // them from the refresh token (oauth-access-token.ts).
+      if (options.oauthTokens) {
+        await options.oauthTokens.storeRefreshToken(
+          { id: accountId, tenantId: state.tenantId },
+          tokens.refreshToken,
+        );
+        options.oauthTokens.primeFromExchange({ id: accountId }, tokens);
+      } else {
+        await deps.secrets.set(
+          state.tenantId,
+          inboundCredentialSecretKey(accountId),
+          tokens.refreshToken,
+          inboundRefreshTokenSecretOptions(accountId),
+        );
+      }
 
       if (options.successRedirectUrl) {
         const target = new URL(options.successRedirectUrl);

package/packages/bundled-features/src/inbound-mail-foundation/feature.ts

@@ -230,7 +230,7 @@ export const inboundMailFoundationFeature = defineFeature(INBOUND_MAIL_FOUNDATIO
         return;
       }
       const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
-      const retentionDb = ctx.db.unsafeRaw(INBOUND_MAIL_RETENTION_REASON) as DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
+      const retentionDb = ctx.db.unsafeRaw() as DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
 
       // Body-Objekte liegen in file-foundation. Provider lazy + memoized —
       // heute schreibt der Ingest kein bodyRef (storeBody-Hook ungebunden),

package/packages/bundled-features/src/inbound-mail-foundation/handlers/ingest-message.write.ts

@@ -273,7 +273,7 @@ export const ingestMessageHandler: WriteHandlerDef = {
         )
       : threadPlainPii;
 
-    const threadRollupRunner = ctx.db.unsafeRaw(THREAD_ROLLUP_ADVISORY_LOCK_REASON);
+    const threadRollupRunner = ctx.db.unsafeRaw();
     await acquireNamespacedAdvisoryLock(
       threadRollupRunner,
       THREAD_ROLLUP_LOCK_NAMESPACE,

package/packages/bundled-features/src/inbound-mail-foundation/index.ts

@@ -55,6 +55,13 @@ export {
   mailThreadEventPayloadSchema,
 } from "./events.js";
 export { inboundMailFoundationFeature } from "./feature.js";
+export {
+  createOAuthAccessTokenManager,
+  inboundRefreshTokenSecretOptions,
+  type OAuthAccessTokenManager,
+  type OAuthAccessTokenManagerDeps,
+  usesFoundationManagedOAuth,
+} from "./oauth-access-token.js";
 export {
   type OAuthStatePayload,
   signOAuthState,