@cosmicdrift/kumiko-bundled-features 0.338.0 → 0.340.0

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;

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

@@ -0,0 +1,102 @@
+import { BlockedHostError, egress } from "@cosmicdrift/kumiko-framework/http";
+import * as z from "zod";
+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-]*$/);
+// 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, target) {
+    return request.requireHttps
+        ? { kind: "external" }
+        : { kind: "internal", allowHosts: [target.hostname] };
+}
+function hostMatches(hostname, allowedHost) {
+    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) {
+    let parsed;
+    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) {
+    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) {
+    return err instanceof Error && err.message.startsWith("egress(internal): redirect");
+}
+function classifyFailure(err) {
+    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) {
+    const target = checkTarget(request);
+    if (!target)
+        return { ok: false, code: "host_not_allowed" };
+    let 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, maxChars) {
+    const chars = Array.from(text);
+    return chars.length <= maxChars ? text : chars.slice(0, maxChars).join("");
+}

package/dist/delivery/delivery-service.js

@@ -229,6 +229,9 @@ export function createDeliveryService(options) {
     async function deliverToUser(userId, notificationType, data, tenantId, priority) {
         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
             if (isChannelKilled) {

package/dist/delivery/index.d.ts

@@ -1,4 +1,6 @@
 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, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobs, DeliveryQueries, DeliveryStatus, } from "./constants.js";
 export { collectChannels, createDeliveryService, type DeliveryServiceOptions, type KillSwitchResolver, type RateLimitConfig, } from "./delivery-service.js";

package/dist/delivery/index.js

@@ -1,4 +1,6 @@
 export { hashUnsubscribeAddress } from "./address-opt-out.js";
+export { chatMessageText, createChatWebhookChannel, toChannelResult, } from "./chat-webhook-channel.js";
+export { chatConnectionNameSchema, DEFAULT_CHAT_TIMEOUT_MS, postChatWebhook, truncateChars, } from "./chat-webhook-sender.js";
 export { DELIVERY_CHANNEL_EXTENSION, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobs, DeliveryQueries, DeliveryStatus, } from "./constants.js";
 export { collectChannels, createDeliveryService, } from "./delivery-service.js";
 export { createDeliveryFeature } from "./feature.js";

package/dist/delivery/jobs.js

@@ -103,7 +103,7 @@ export const deliverySendJob = async (payload, ctx) => {
     const tenantId = p.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);
         await appendAttemptEvent(db, registry, p.deliveryAttemptId, entryFor(p, result.status, result.error ?? null, result.address ?? p.address));

package/dist/delivery/testing.d.ts

@@ -1,6 +1,7 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { EscapeHatchAuditSink, Registry } 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";
@@ -11,6 +12,7 @@ export type CreateDeliveryTestContextOptions = {
     readonly isChannelKilled?: KillSwitchResolver;
     readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
     readonly log?: Logger;
+    readonly jobRunner?: JobRunner;
 };
 /**
  * Helper for setupTestStack: creates a DeliveryService + _notifyFactory for the test context.

package/dist/delivery/types.d.ts

@@ -1,12 +1,14 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { NotifyOptions, NotifyPriority, Registry, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import { DELIVERY_CHANNEL_EXTENSION } from "./constants.js";
 export type ChannelContext = {
     readonly db: TenantDb;
     readonly registry: Registry;
     readonly sseBroker: SseBroker | undefined;
     readonly tenantId: TenantId;
+    readonly secrets?: SecretsContext | undefined;
 };
 export type ChannelMessage = {
     readonly notificationType: string;
@@ -28,7 +30,7 @@ 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>;
+    resolve?(userId: string, ctx: ChannelContext): Promise<string | null>;
     render?(message: ChannelMessage, ctx: ChannelContext): Promise<RenderedMessage>;
     send(address: string, message: ChannelMessage, ctx: ChannelContext, rendered?: RenderedMessage): Promise<ChannelResult>;
 };

package/dist/delivery/types.js

@@ -10,8 +10,7 @@ export function isDeliveryChannelPlugin(o) {
         "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/dist/file-derivatives/handlers/public-variant-by-file-ref.query.js

@@ -16,7 +16,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(db, fileRefsTable, {
             id: query.payload.fileRefId,
             isDeleted: false,

package/dist/files-tenant-data/index.js

@@ -34,7 +34,7 @@ export function createFilesTenantDataFeature() {
             escapeHatch: {
                 reason: SWEEP_ORPHANED_DERIVATIVES_ESCAPE_HATCH_REASON,
             },
-            handler: (payload, ctx) => sweepOrphanedDerivativesJob(payload, ctx, ctx.db.unsafeRaw(SWEEP_ORPHANED_DERIVATIVES_ESCAPE_HATCH_REASON)),
+            handler: (payload, ctx) => sweepOrphanedDerivativesJob(payload, ctx, ctx.db.unsafeRaw()),
         });
     });
 }

package/dist/form-draft/feature.js

@@ -38,7 +38,7 @@ function registerFormDraft(r) {
         trigger: { cron: "0 3 * * *" },
         concurrency: "skip",
         escapeHatch: { reason: CLEANUP_ESCAPE_HATCH_REASON },
-        handler: (payload, ctx) => cleanupDraftsJob(payload, ctx, ctx.db.unsafeRaw(CLEANUP_ESCAPE_HATCH_REASON)),
+        handler: (payload, ctx) => cleanupDraftsJob(payload, ctx, ctx.db.unsafeRaw()),
     });
 }
 export const formDraftFeature = defineFeature(FORM_DRAFT_FEATURE_NAME, registerFormDraft);

package/dist/form-draft/handlers/discard.write.js

@@ -59,7 +59,7 @@ export const discardDraftWrite = defineWriteHandler({
             // lazily on the first step-change — a file uploaded before that exists
             // 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), event.user.tenantId, ownerId, candidateKeys, existing.insertedAt, isCreateMode);
+            const ownedRefs = await filterOwnedFileRefs(ctx.db.unsafeRaw(), event.user.tenantId, ownerId, candidateKeys, existing.insertedAt, isCreateMode);
             // Fail-closed erase of file_refs rows FIRST (outside the best-effort
             // storage-hygiene loop). releaseDraftFileRefs swallows per-key errors
             // by design — routing forget through it would report discarded:true

package/dist/form-draft/handlers/save.write.js

@@ -42,7 +42,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/dist/inbound-mail-foundation/connect-routes.d.ts

@@ -1,4 +1,5 @@
 import type { ExtraRouteDefinition } from "@cosmicdrift/kumiko-framework/api";
+import { type OAuthAccessTokenManager } from "./oauth-access-token.js";
 export type InboundMailConnectRoutesOptions = {
     /** HMAC-secret for the state param (deploy-time env — `scope:"system"`
      *  secrets don't exist in secrets-v1). */
@@ -14,6 +15,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;
 };
 /** Builds the `entry:"user"`/`entry:"signature"` extraRoute pair. Mount via
  *  `extraRoutes: createInboundMailConnectRoutes(options)`. */

package/dist/inbound-mail-foundation/connect-routes.js

@@ -11,6 +11,7 @@
 // HMAC-verified state (CSRF-/foreign-claiming lock, see oauth-state.ts).
 import { ExtraRouteRejection, signatureRoute } from "@cosmicdrift/kumiko-framework/api";
 import { INBOUND_MAIL_FOUNDATION_FEATURE, InboundMailAuthMethods, InboundMailFoundationHandlers, inboundCredentialSecretKey, } from "./constants.js";
+import { inboundRefreshTokenSecretOptions, } from "./oauth-access-token.js";
 import { signOAuthState, verifyOAuthState } from "./oauth-state.js";
 import { resolveInboundProviderForKey } from "./provider-factory.js";
 const DEFAULT_STATE_TTL_MINUTES = 15;
@@ -97,8 +98,9 @@ export function createInboundMailConnectRoutes(options) {
                     redirectUri: options.callbackUrl,
                 });
             }
-            catch (e) {
-                return errorJson(c, 502, "token_exchange_failed", e instanceof Error ? e.message : String(e));
+            catch {
+                // Provider error messages can carry token/response data — code only.
+                return errorJson(c, 502, "token_exchange_failed", "token exchange with the provider failed");
             }
             if (!tokens.refreshToken) {
                 // No refresh token → no server-side sync possible. Consent must
@@ -128,12 +130,15 @@ export function createInboundMailConnectRoutes(options) {
                 return errorJson(c, 502, "account_create_failed", "connect-account returned no accountId");
             }
             // 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);
                 target.searchParams.set("accountId", accountId);

package/dist/inbound-mail-foundation/feature.js

@@ -176,7 +176,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); // @cast-boundary db-operator — jobs never run inside a DbTx
+            const retentionDb = ctx.db.unsafeRaw(); // @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),
             // der Provider wird also nie gebaut. Sobald storeBody wired ist, raeumt

package/dist/inbound-mail-foundation/handlers/ingest-message.write.js

@@ -230,7 +230,7 @@ export const ingestMessageHandler = {
                 tenantId,
             }, { tenantId, entityName: MAIL_THREAD_AGGREGATE_TYPE })
             : threadPlainPii;
-        const threadRollupRunner = ctx.db.unsafeRaw(THREAD_ROLLUP_ADVISORY_LOCK_REASON);
+        const threadRollupRunner = ctx.db.unsafeRaw();
         await acquireNamespacedAdvisoryLock(threadRollupRunner, THREAD_ROLLUP_LOCK_NAMESPACE, threadAggId);
         let threadAppendOk = false;
         for (let attempt = 1; attempt <= THREAD_ROLLUP_MAX_ATTEMPTS && !threadAppendOk; attempt++) {

package/dist/inbound-mail-foundation/index.d.ts

@@ -4,6 +4,7 @@ export { INBOUND_MAIL_FOUNDATION_FEATURE, INBOUND_MAIL_PROVIDER_EXTENSION, type
 export { INBOUND_MESSAGE_PII_FIELDS, inboundMessageEntity, MAIL_ACCOUNT_PII_FIELDS, MAIL_THREAD_PII_FIELDS, mailAccountEntity, mailThreadEntity, seenMessageEntity, seenMessageTable, syncCursorEntity, syncCursorTable, } from "./entities.js";
 export { INBOUND_MESSAGE_AGGREGATE_TYPE, INBOUND_MESSAGE_RECEIVED_EVENT_QN, INBOUND_MESSAGE_RECEIVED_EVENT_SHORT, type InboundMessageEventHeaders, type InboundMessageEventPayload, inboundMessageEventPayloadSchema, MAIL_ACCOUNT_AGGREGATE_TYPE, MAIL_ACCOUNT_CONNECTED_EVENT_QN, MAIL_ACCOUNT_CONNECTED_EVENT_SHORT, MAIL_ACCOUNT_DISCONNECTED_EVENT_QN, MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT, MAIL_ACCOUNT_UPDATED_EVENT_QN, MAIL_ACCOUNT_UPDATED_EVENT_SHORT, MAIL_THREAD_AGGREGATE_TYPE, MAIL_THREAD_UPDATED_EVENT_QN, MAIL_THREAD_UPDATED_EVENT_SHORT, type MailAccountEventHeaders, type MailAccountEventPayload, type MailThreadEventPayload, mailAccountEventPayloadSchema, 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, type VerifyOAuthStateResult, verifyOAuthState, } from "./oauth-state.js";
 export { inboundMessagesProjectionTable, mailAccountsProjectionTable, mailThreadsProjectionTable, } from "./projection.js";
 export { resolveInboundProviderForAccount, resolveInboundProviderForKey, } from "./provider-factory.js";

package/dist/inbound-mail-foundation/index.js

@@ -5,6 +5,7 @@ export { INBOUND_MAIL_FOUNDATION_FEATURE, INBOUND_MAIL_PROVIDER_EXTENSION, Inbou
 export { INBOUND_MESSAGE_PII_FIELDS, inboundMessageEntity, MAIL_ACCOUNT_PII_FIELDS, MAIL_THREAD_PII_FIELDS, mailAccountEntity, mailThreadEntity, seenMessageEntity, seenMessageTable, syncCursorEntity, syncCursorTable, } from "./entities.js";
 export { INBOUND_MESSAGE_AGGREGATE_TYPE, INBOUND_MESSAGE_RECEIVED_EVENT_QN, INBOUND_MESSAGE_RECEIVED_EVENT_SHORT, inboundMessageEventPayloadSchema, MAIL_ACCOUNT_AGGREGATE_TYPE, MAIL_ACCOUNT_CONNECTED_EVENT_QN, MAIL_ACCOUNT_CONNECTED_EVENT_SHORT, MAIL_ACCOUNT_DISCONNECTED_EVENT_QN, MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT, MAIL_ACCOUNT_UPDATED_EVENT_QN, MAIL_ACCOUNT_UPDATED_EVENT_SHORT, MAIL_THREAD_AGGREGATE_TYPE, MAIL_THREAD_UPDATED_EVENT_QN, MAIL_THREAD_UPDATED_EVENT_SHORT, mailAccountEventPayloadSchema, mailThreadEventPayloadSchema, } from "./events.js";
 export { inboundMailFoundationFeature } from "./feature.js";
+export { createOAuthAccessTokenManager, inboundRefreshTokenSecretOptions, usesFoundationManagedOAuth, } from "./oauth-access-token.js";
 export { signOAuthState, verifyOAuthState, } from "./oauth-state.js";
 export { inboundMessagesProjectionTable, mailAccountsProjectionTable, mailThreadsProjectionTable, } from "./projection.js";
 export { resolveInboundProviderForAccount, resolveInboundProviderForKey, } from "./provider-factory.js";

package/dist/inbound-mail-foundation/oauth-access-token.d.ts

@@ -0,0 +1,28 @@
+import { type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import { Temporal } from "temporal-polyfill";
+import { type InboundMailContext, type InboundMailProviderPlugin, type MailAccountRecord, type OAuthTokenSet } from "./types.js";
+/** Shared by the OAuth callback and the refresh path so both write the slot identically. */
+export declare function inboundRefreshTokenSecretOptions(accountId: string): {
+    redact: (plaintext: string) => string;
+    hint: string;
+};
+/** True for accounts whose access token the foundation must supply. */
+export declare function usesFoundationManagedOAuth(account: MailAccountRecord, plugin: InboundMailProviderPlugin): boolean;
+export type OAuthAccessTokenManagerDeps = {
+    readonly db: DbConnection;
+    readonly secrets: SecretsContext;
+    readonly providerCtx?: InboundMailContext;
+    readonly now?: () => Temporal.Instant;
+    readonly refreshTimeoutMs?: number;
+};
+export type OAuthAccessTokenManager = {
+    /** Valid access token for the account; refreshes when missing or near expiry. */
+    readonly getAccessToken: (account: MailAccountRecord, plugin: InboundMailProviderPlugin) => Promise<string>;
+    /** Writes the refresh token under the account lock and drops any cached access token. */
+    readonly storeRefreshToken: (account: Pick<MailAccountRecord, "id" | "tenantId">, refreshToken: string) => Promise<void>;
+    /** Seeds the cache from a code-exchange result (access token only). */
+    readonly primeFromExchange: (account: Pick<MailAccountRecord, "id">, tokens: OAuthTokenSet) => void;
+    readonly invalidate: (accountId: string) => void;
+};
+export declare function createOAuthAccessTokenManager(deps: OAuthAccessTokenManagerDeps): OAuthAccessTokenManager;

package/dist/inbound-mail-foundation/oauth-access-token.js

@@ -0,0 +1,131 @@
+// OAuth access-token lifecycle for inbound-mail accounts. Access tokens
+// (~1h) are never persisted: they live in a per-process cache and are
+// re-minted from the refresh token in the account's secret slot.
+//
+// Serialization:
+//   - in-process: single-flight per account (concurrent callers share one
+//     refresh).
+//   - cross-worker: a pg advisory xact lock around "re-read refresh token →
+//     provider refresh → persist rotated refresh token". This serializes
+//     refreshes and secret writes so a rotating provider can't see two
+//     workers redeem the same refresh token concurrently. It does NOT make
+//     refresh exactly-once across workers: access tokens are per-process, so
+//     each worker still refreshes once itself.
+//
+// The refresh token is re-read inside the lock via `secrets.get` without an
+// audit context. SecretsContext does not cache values (only unwrapped DEKs),
+// so the read always reflects the latest committed write.
+import { transaction } from "@cosmicdrift/kumiko-framework/bun-db";
+import { acquireNamespacedAdvisoryLock } from "@cosmicdrift/kumiko-framework/db";
+import { Temporal } from "temporal-polyfill";
+import { InboundMailAuthMethods, inboundCredentialSecretKey } from "./constants.js";
+import { InboundAuthError, } from "./types.js";
+// 'inoa' as ASCII — disjoint from the other fixed advisory-lock namespaces.
+const OAUTH_REFRESH_LOCK_NAMESPACE = 0x696e6f61;
+const ACCESS_TOKEN_EXPIRY_MARGIN = Temporal.Duration.from({ minutes: 2 });
+// The provider call runs while the lock transaction holds a pool connection,
+// so it gets an abort signal with this upper bound.
+const DEFAULT_REFRESH_TIMEOUT_MS = 30_000;
+/** Shared by the OAuth callback and the refresh path so both write the slot identically. */
+export function inboundRefreshTokenSecretOptions(accountId) {
+    return {
+        redact: (plaintext) => `${plaintext.slice(0, 4)}…`,
+        hint: `OAuth refresh token for inbound mail account ${accountId}`,
+    };
+}
+/** True for accounts whose access token the foundation must supply. */
+export function usesFoundationManagedOAuth(account, plugin) {
+    return (plugin.oauth !== undefined &&
+        (account.authMethod === InboundMailAuthMethods.oauth ||
+            account.authMethod === InboundMailAuthMethods.xoauth2));
+}
+function lockKey(account) {
+    return `${account.tenantId}:${account.id}`;
+}
+export function createOAuthAccessTokenManager(deps) {
+    const now = deps.now ?? (() => Temporal.Now.instant());
+    const refreshTimeoutMs = deps.refreshTimeoutMs ?? DEFAULT_REFRESH_TIMEOUT_MS;
+    const providerCtx = { ...deps.providerCtx, secrets: deps.secrets };
+    const cache = new Map();
+    const inFlight = new Map();
+    function parseExpiry(iso) {
+        try {
+            return Temporal.Instant.from(iso);
+        }
+        catch {
+            // Unparseable expiry: treat as already expired so it is never cached.
+            return now();
+        }
+    }
+    function remember(accountId, tokens) {
+        cache.set(accountId, {
+            accessToken: tokens.accessToken,
+            expiresAt: parseExpiry(tokens.expiresAt),
+        });
+    }
+    function cachedValid(accountId) {
+        const hit = cache.get(accountId);
+        if (!hit)
+            return undefined;
+        const usableUntil = hit.expiresAt.subtract(ACCESS_TOKEN_EXPIRY_MARGIN);
+        return Temporal.Instant.compare(now(), usableUntil) < 0 ? hit.accessToken : undefined;
+    }
+    async function refreshWithTimeout(plugin, account, refreshToken) {
+        const oauth = plugin.oauth;
+        if (!oauth)
+            throw new InboundAuthError("provider has no oauth flow");
+        return oauth.refreshAccessToken(providerCtx, account, refreshToken, {
+            signal: AbortSignal.timeout(refreshTimeoutMs),
+        });
+    }
+    async function refresh(account, plugin) {
+        const secretKey = inboundCredentialSecretKey(account.id);
+        return transaction(deps.db, async (tx) => {
+            await acquireNamespacedAdvisoryLock(tx, OAUTH_REFRESH_LOCK_NAMESPACE, lockKey(account));
+            const stored = await deps.secrets.get(account.tenantId, secretKey);
+            if (!stored) {
+                throw new InboundAuthError("no refresh token stored for account");
+            }
+            const currentRefreshToken = stored.reveal();
+            const tokens = await refreshWithTimeout(plugin, account, currentRefreshToken);
+            if (tokens.refreshToken && tokens.refreshToken !== currentRefreshToken) {
+                await deps.secrets.set(account.tenantId, secretKey, tokens.refreshToken, inboundRefreshTokenSecretOptions(account.id));
+            }
+            remember(account.id, tokens);
+            return tokens.accessToken;
+        });
+    }
+    return {
+        async getAccessToken(account, plugin) {
+            const hit = cachedValid(account.id);
+            if (hit !== undefined)
+                return hit;
+            const running = inFlight.get(account.id);
+            if (running)
+                return running;
+            const started = refresh(account, plugin)
+                .catch((err) => {
+                cache.delete(account.id);
+                throw err;
+            })
+                .finally(() => {
+                inFlight.delete(account.id);
+            });
+            inFlight.set(account.id, started);
+            return started;
+        },
+        async storeRefreshToken(account, refreshToken) {
+            await transaction(deps.db, async (tx) => {
+                await acquireNamespacedAdvisoryLock(tx, OAUTH_REFRESH_LOCK_NAMESPACE, lockKey(account));
+                await deps.secrets.set(account.tenantId, inboundCredentialSecretKey(account.id), refreshToken, inboundRefreshTokenSecretOptions(account.id));
+            });
+            cache.delete(account.id);
+        },
+        primeFromExchange(account, tokens) {
+            remember(account.id, tokens);
+        },
+        invalidate(accountId) {
+            cache.delete(accountId);
+        },
+    };
+}