@cosmicdrift/kumiko-bundled-features 0.338.0 → 0.339.0

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);
+        },
+    };
+}

package/dist/inbound-mail-foundation/tenant-destroy-hook.js

@@ -29,7 +29,7 @@ async function archiveAndDeleteRows(ctx, table, aggregateType) {
     declareEscapeHatch({ reason: INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON });
     const rows = await ctx.db.selectMany(table, { tenantId: ctx.tenantId });
     for (const row of rows) {
-        await archiveStream(ctx.db.unsafeRaw(INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON), {
+        await archiveStream(ctx.db.unsafeRaw(), {
             tenantId: ctx.tenantId,
             aggregateId: row.id,
             aggregateType,

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

@@ -112,7 +112,15 @@ export type InboundOAuthFlow = {
         readonly code: string;
         readonly redirectUri: string;
     }) => Promise<OAuthTokenSet>;
-    readonly refreshAccessToken: (ctx: InboundMailContext, account: MailAccountRecord, refreshToken: string) => Promise<OAuthTokenSet>;
+    readonly refreshAccessToken: (ctx: InboundMailContext, account: MailAccountRecord, refreshToken: string, 
+    /** The foundation aborts `signal` after a hard timeout while holding a
+     *  per-account lock (a pool connection is pinned meanwhile). Providers
+     *  MUST pass it to their token-endpoint fetch; the foundation awaits the
+     *  provider's result and never drops a late one, because that could lose
+     *  a rotated refresh token. */
+    opts?: {
+        readonly signal?: AbortSignal;
+    }) => Promise<OAuthTokenSet>;
 };
 /**
  * Inbound-Mail-Provider-Plugin contract. Jedes Provider-Feature
@@ -129,6 +137,10 @@ export type InboundMailProviderPlugin = {
     readonly fetch: (ctx: InboundMailContext, account: MailAccountRecord, cursor: SyncCursorPayload | null, opts: {
         readonly backfillWindowDays: number;
         readonly maxMessages: number;
+        /** Valid OAuth access token, minted by the foundation for accounts
+         *  whose provider declares `oauth` (authMethod oauth/xoauth2). Absent
+         *  for password accounts and providers without an oauth flow. */
+        readonly accessToken?: string;
     }) => Promise<InboundFetchResult>;
     /** Nur OAuth-Provider. */
     readonly oauth?: InboundOAuthFlow;
@@ -140,6 +152,11 @@ export type InboundMailProviderPlugin = {
     readonly watch?: (ctx: InboundMailContext, account: MailAccountRecord, handlers: {
         readonly onMessages: (msgs: readonly RawInboundMessage[]) => Promise<void>;
         readonly onError: (err: unknown) => void;
+    }, 
+    /** Same `accessToken` semantics as `fetch` opts; re-minted on every
+     *  supervisor (re)start of the watch. */
+    opts?: {
+        readonly accessToken?: string;
     }) => Promise<() => Promise<void>>;
 };
 export declare function isInboundMailProviderPlugin(o: unknown): o is InboundMailProviderPlugin;

package/dist/inbound-mail-foundation/watch-supervisor.d.ts

@@ -1,5 +1,6 @@
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { DistributedLock } from "@cosmicdrift/kumiko-framework/pipeline";
+import { type OAuthAccessTokenManager } from "./oauth-access-token.js";
 import { type InboundMailContext, type MailAccountRecord, type RawInboundMessage } from "./types.js";
 export type InboundMailSupervisorDeps = {
     /** Slim-Context für Provider-Calls (registry Pflicht, secrets für
@@ -34,6 +35,10 @@ export type InboundMailSupervisorDeps = {
      *  watcher lives. Omit for single-process deployments — every active
      *  account is watched locally, same as before #1719. */
     readonly lock?: DistributedLock;
+    /** Access-token lifecycle for OAuth accounts. Defaults to a manager built
+     *  from `db` + `providerCtx.secrets`; pass the instance shared with
+     *  `createInboundMailConnectRoutes` so a fresh connect primes this cache. */
+    readonly oauthTokens?: OAuthAccessTokenManager;
     /** TTL (seconds) for the per-account watch lease. Default 90s, renewed
      *  every ttl/3. Only used when `lock` is set. */
     readonly watchLeaseTtlSeconds?: number;