@cosmicdrift/kumiko-bundled-features 0.337.1 → 0.339.0

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

@@ -91,6 +91,7 @@ export const ingestMessageHandler = {
     access: { roles: ["SystemAdmin"] },
     agent: { expose: false },
     escapeHatch: {
+        grants: ["unsafeRaw"],
         reason: THREAD_ROLLUP_ADVISORY_LOCK_REASON,
     },
     handler: async (event, ctx) => {
@@ -229,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;

package/dist/inbound-mail-foundation/watch-supervisor.js

@@ -48,9 +48,15 @@ import { configuredPiiSubjectKms, decryptPiiFieldValues, } from "@cosmicdrift/ku
 import { Temporal } from "temporal-polyfill";
 import { InboundMailAccountStatuses, InboundMailFoundationHandlers } from "./constants.js";
 import { MAIL_ACCOUNT_PII_FIELDS, syncCursorTable } from "./entities.js";
+import { createOAuthAccessTokenManager, usesFoundationManagedOAuth, } from "./oauth-access-token.js";
 import { mailAccountsProjectionTable } from "./projection.js";
 import { resolveInboundProviderForAccount } from "./provider-factory.js";
 import { isInboundAuthError, isInboundCursorInvalidError, isInboundRateLimitError, } from "./types.js";
+// Provider errors can embed token or response data in `message`; logs carry
+// only the error class.
+function describeError(err) {
+    return err instanceof Error ? err.name : typeof err;
+}
 const DEFAULT_POLL_INTERVAL_MS = 5 * 60 * 1000;
 const DEFAULT_BACKFILL_WINDOW_DAYS = 30;
 const DEFAULT_MAX_MESSAGES_PER_POLL = 200;
@@ -72,6 +78,25 @@ export function createInboundMailSupervisor(deps) {
     // configured TTL — real deployments (default 90s) never hit it.
     const renewIntervalMs = Math.max(50, Math.floor((leaseTtlSeconds * 1000) / 3));
     const log = deps.log ?? (() => { });
+    const oauthTokens = deps.oauthTokens ??
+        (deps.providerCtx.secrets
+            ? createOAuthAccessTokenManager({
+                db: deps.db,
+                secrets: deps.providerCtx.secrets,
+                providerCtx: deps.providerCtx,
+            })
+            : undefined);
+    // Undefined for non-OAuth accounts. A refresh failure propagates into the
+    // caller's handleSyncError: InboundAuthError → auth_error, anything else
+    // → transient retry.
+    async function resolveAccessToken(account, plugin) {
+        if (!usesFoundationManagedOAuth(account, plugin))
+            return undefined;
+        if (!oauthTokens) {
+            throw new Error("oauth account needs a secrets context for token refresh");
+        }
+        return oauthTokens.getAccessToken(account, plugin);
+    }
     let running = false;
     let pollTimer = null;
     let pollInFlight = null;
@@ -213,7 +238,7 @@ export function createInboundMailSupervisor(deps) {
             return true;
         }
         // Transient/unbekannt: loggen, nächster Tick retried.
-        log(`inbound-mail: account ${account.id} sync error: ${err instanceof Error ? err.message : String(err)}`);
+        log(`inbound-mail: account ${account.id} sync error: ${describeError(err)}`);
         return true;
     }
     // ---------------------------------------------------------------
@@ -225,9 +250,11 @@ export function createInboundMailSupervisor(deps) {
         try {
             // hasMore-Schleife: Pagination innerhalb eines Ticks bis Budget.
             for (;;) {
+                const accessToken = await resolveAccessToken(account, plugin);
                 const result = await plugin.fetch(deps.providerCtx, account, cursor, {
                     backfillWindowDays,
                     maxMessages: budget,
+                    ...(accessToken !== undefined && { accessToken }),
                 });
                 await ingestBatch(account, result.messages, JSON.stringify(result.nextCursor));
                 await saveCursor(account, result.nextCursor);
@@ -249,7 +276,7 @@ export function createInboundMailSupervisor(deps) {
                 plugin = resolveInboundProviderForAccount(deps.providerCtx, account);
             }
             catch (err) {
-                log(`inbound-mail: ${err instanceof Error ? err.message : String(err)}`);
+                log(`inbound-mail: ${describeError(err)}`);
                 continue;
             }
             await pollAccount(account, plugin);
@@ -290,7 +317,7 @@ export function createInboundMailSupervisor(deps) {
             renewed = await deps.lock.renew(account.id, state.lockToken, leaseTtlSeconds);
         }
         catch (err) {
-            log(`inbound-mail: watch lease renew for account ${account.id} failed: ${err instanceof Error ? err.message : String(err)}`);
+            log(`inbound-mail: watch lease renew for account ${account.id} failed: ${describeError(err)}`);
             state.renewFailures += 1;
             // After failures spanning a full lease TTL, tear down — otherwise a
             // peer can acquire the expired key while we still hold an IDLE conn.
@@ -379,7 +406,7 @@ export function createInboundMailSupervisor(deps) {
             state.stop = null;
             const delay = state.backoffMs;
             state.backoffMs = Math.min(state.backoffMs * 2, backoffMaxMs);
-            log(`inbound-mail: watch for account ${account.id} died (${err instanceof Error ? err.message : String(err)}) — restart in ${delay}ms`);
+            log(`inbound-mail: watch for account ${account.id} died (${describeError(err)}) — restart in ${delay}ms`);
             void markAccount(account, { watchState: `backoff:${delay}ms` }, "watch_supervisor");
             state.restartTimer = setTimeout(() => {
                 state.restartTimer = null;
@@ -388,27 +415,28 @@ export function createInboundMailSupervisor(deps) {
         };
         state.starting = true;
         try {
+            const accessToken = await resolveAccessToken(account, plugin);
             const stop = await plugin.watch(deps.providerCtx, account, {
                 onMessages: async (msgs) => {
                     try {
                         await ingestBatch(account, msgs, "watch");
                     }
                     catch (err) {
-                        // Ingest-Fehler killt den Watcher nicht — der Poll holt die
-                        // Messages beim nächsten Tick (Dedup macht's idempotent).
-                        log(`inbound-mail: watch-ingest for account ${account.id} failed: ${err instanceof Error ? err.message : String(err)}`);
+                        // An ingest failure must not kill the watcher: the next poll
+                        // tick fetches the messages again and dedup keeps it idempotent.
+                        log(`inbound-mail: watch-ingest for account ${account.id} failed: ${describeError(err)}`);
                     }
                 },
                 onError: (err) => {
                     void (async () => {
                         const keepRunning = await handleSyncError(account, err);
-                        // auth_error → stopWatcher hat die generation gebumpt,
-                        // scheduleRestart no-op't; für alle anderen: Backoff-Restart.
+                        // On auth_error stopWatcher already bumped the generation, so
+                        // scheduleRestart is a no-op; every other error restarts with backoff.
                         if (keepRunning)
                             scheduleRestart(err);
                     })();
                 },
-            });
+            }, accessToken !== undefined ? { accessToken } : undefined);
             if (state.generation !== generation || !running) {
                 await stop();
                 // skip: stop() kam während des Connects — Watcher wurde sofort wieder abgebaut.
@@ -425,7 +453,7 @@ export function createInboundMailSupervisor(deps) {
                 await markAccount(account, { watchState: "watching" }, "watch_supervisor");
             }
             catch (err) {
-                log(`inbound-mail: markAccount(watching) for account ${account.id} failed: ${err instanceof Error ? err.message : String(err)}`);
+                log(`inbound-mail: markAccount(watching) for account ${account.id} failed: ${describeError(err)}`);
             }
         }
         catch (err) {
@@ -464,7 +492,7 @@ export function createInboundMailSupervisor(deps) {
                 await stop();
             }
             catch (err) {
-                log(`inbound-mail: stop watcher ${accountId} failed: ${err instanceof Error ? err.message : String(err)}`);
+                log(`inbound-mail: stop watcher ${accountId} failed: ${describeError(err)}`);
             }
         }
         if (deps.lock && lockToken) {
@@ -472,7 +500,7 @@ export function createInboundMailSupervisor(deps) {
                 await deps.lock.release(accountId, lockToken);
             }
             catch (err) {
-                log(`inbound-mail: watch lease release for account ${accountId} failed: ${err instanceof Error ? err.message : String(err)}`);
+                log(`inbound-mail: watch lease release for account ${accountId} failed: ${describeError(err)}`);
             }
         }
     }
@@ -486,7 +514,7 @@ export function createInboundMailSupervisor(deps) {
         pollTimer = setTimeout(() => {
             pollTimer = null;
             pollInFlight = pollOnce()
-                .catch((err) => log(`inbound-mail: poll tick failed: ${err instanceof Error ? err.message : String(err)}`))
+                .catch((err) => log(`inbound-mail: poll tick failed: ${describeError(err)}`))
                 .finally(() => {
                 pollInFlight = null;
                 scheduleNextPoll();

package/dist/managed-pages/handlers/set.write.js

@@ -38,6 +38,7 @@ export const setWrite = defineWriteHandler({
     access: { roles: ["TenantAdmin", "SystemAdmin"] },
     description: "Creates or overwrites one managed page addressed by slug and language, keeping the existing published flag, description and OG image when the payload omits them; use it for content edits and publish toggles, and as SystemAdmin to write another tenant's pages.",
     escapeHatch: {
+        grants: ["unsafeRaw"],
         reason: SET_PAGE_TENANT_OVERRIDE_REASON,
     },
     handler: async (event, ctx) => {
@@ -53,7 +54,7 @@ export const setWrite = defineWriteHandler({
         // on both the existing-check and the executor's stream reads; re-scope to the target.
         // Safe: the override branch is SystemAdmin-gated above.
         const scopedDb = override !== undefined
-            ? createTenantDb(db.unsafeRaw(SET_PAGE_TENANT_OVERRIDE_REASON), override, // @cast-boundary engine-bridge
+            ? createTenantDb(db.unsafeRaw(), override, // @cast-boundary engine-bridge
             "tenant")
             : db;
         const existing = await fetchOne(scopedDb, pagesTable, {

package/dist/notes-history/executor.d.ts

@@ -1,2 +1,4 @@
+import { type EntityDefinition } from "@cosmicdrift/kumiko-framework/engine";
 export declare const noteEntryExecutor: import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor, noteEntryTable: import("@cosmicdrift/kumiko-framework/db").EntityTable;
+export declare function createNoteEntryExecutor(ownership: EntityDefinition["access"] | undefined): typeof noteEntryExecutor;
 export declare const noteMentionExecutor: import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor, noteMentionTable: import("@cosmicdrift/kumiko-framework/db").EntityTable;

package/dist/notes-history/executor.js

@@ -1,4 +1,12 @@
 import { createEntityExecutor } from "@cosmicdrift/kumiko-framework/engine";
-import { noteEntryEntity, noteMentionEntity } from "./entity.js";
+import { createNoteEntryEntity, noteEntryEntity, noteMentionEntity } from "./entity.js";
 export const { executor: noteEntryExecutor, table: noteEntryTable } = createEntityExecutor("note-entry", noteEntryEntity);
+// Carries only `ownership.write`: the executor enforces entity.access.write on
+// create, while read ownership is applied by the list handler.
+export function createNoteEntryExecutor(ownership) {
+    if (ownership?.write === undefined)
+        return noteEntryExecutor;
+    return createEntityExecutor("note-entry", createNoteEntryEntity({ write: ownership.write }))
+        .executor;
+}
 export const { executor: noteMentionExecutor, table: noteMentionTable } = createEntityExecutor("note-mention", noteMentionEntity);

package/dist/notes-history/feature.d.ts

@@ -19,9 +19,8 @@ export type NotesHistoryFeatureOptions = {
      *  it is AND-ed with the host-visibility gate, never a replacement for it.
      *
      *  `ownership.write` is separate and does NOT affect list/read. It's
-     *  consulted by the framework's generic delete/forget/restore paths (not
-     *  by this feature's own add-note handler — see createNotesHistoryFeature's
-     *  boot-guard comment). A `from()` rule there also gates GDPR erasure
+     *  consulted on add-note (create) and the framework's generic
+     *  forget/restore paths. A `from()` rule there also gates GDPR erasure
      *  (`forget`): if the rule's role map doesn't cover whatever role the
      *  erasure/retention pipeline runs as, `forget` denies instead of
      *  crypto-shredding — a silent Art.17 failure, not a thrown error. Make

package/dist/notes-history/feature.js

@@ -16,6 +16,7 @@ import { defineEntityListHandler, defineFeature, } from "@cosmicdrift/kumiko-fra
 import { hasWhereRule } from "../shared/index.js";
 import { DEFAULT_NOTES_HISTORY_ACCESS, NOTES_HISTORY_FEATURE_NAME } from "./constants.js";
 import { createNoteEntryEntity, noteMentionEntity } from "./entity.js";
+import { createNoteEntryExecutor } from "./executor.js";
 import { createAddNoteHandler } from "./handlers/add-note.write.js";
 import { NOTES_HISTORY_FEATURE_I18N } from "./i18n.js";
 function registerNotesHistory(r, access, ownership, parents) {
@@ -33,7 +34,7 @@ function registerNotesHistory(r, access, ownership, parents) {
     // just building it inline in the handler) is what makes it visible to the
     // registry-wide GDPR boot guards and to executor.ts's table/projection setup.
     r.entity("note-mention", noteMentionEntity);
-    r.writeHandler(createAddNoteHandler(access));
+    r.writeHandler(createAddNoteHandler(access, createNoteEntryExecutor(ownership)));
     r.queryHandler(defineEntityListHandler("note-entry", entity, {
         access,
         description: "Lists note-history entries of the caller's tenant with their text, author and timestamp; filter on entityId to read the full note trail of one record.",

package/dist/notes-history/handlers/add-note.write.d.ts

@@ -1,3 +1,4 @@
 import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
-export declare function createAddNoteHandler(access?: AccessRule): WriteHandlerDef;
+import { noteEntryExecutor } from "../executor.js";
+export declare function createAddNoteHandler(access?: AccessRule, entryExecutor?: typeof noteEntryExecutor): WriteHandlerDef;
 export declare const addNoteHandler: WriteHandlerDef;