@cosmicdrift/kumiko-bundled-features 0.392.2 → 0.394.0

package/dist/file-foundation/read-file-ref-content.js

@@ -27,7 +27,6 @@ export class FileStorageUnavailableError extends Error {
         super("readFileRefContent: no file storage is available for the file's tenant");
     }
 }
-// fileName of the row is never used: it is personal data and may be a PII ciphertext.
 export async function readFileRefContent(args) {
     if (!isUuid(args.fileRefId))
         return null;
@@ -44,7 +43,8 @@ export async function readFileRefContent(args) {
     if (row === undefined)
         return null;
     const size = Number(row.size);
-    if (args.maxBytes !== undefined && size > args.maxBytes) {
+    // A size that is not a number counts as too large, so the limit cannot be skipped.
+    if (args.maxBytes !== undefined && !(size <= args.maxBytes)) {
         throw new FileRefTooLargeError(size);
     }
     const files = args.filesForTenant(row.tenantId);
@@ -52,5 +52,11 @@ export async function readFileRefContent(args) {
         throw new FileStorageUnavailableError();
     }
     const content = await files.refFromFileRef(row).read();
-    return { content, contentType: row.mimeType, tenantId: row.tenantId, size };
+    return {
+        content,
+        contentType: row.mimeType,
+        tenantId: row.tenantId,
+        size,
+        fileName: row.fileName,
+    };
 }

package/dist/form-draft/handlers/discard.write.d.ts

@@ -3,4 +3,4 @@ export declare const discardDraftWrite: import("@cosmicdrift/kumiko-types/define
     releaseFiles: import("zod").ZodOptional<import("zod").ZodBoolean>;
 }, import("zod/v4/core").$strip>, {
     discarded: boolean;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined, undefined>;

package/dist/form-draft/handlers/save.write.d.ts

@@ -2,4 +2,4 @@ export declare const saveDraftWrite: import("@cosmicdrift/kumiko-types/define-ha
     draftKey: import("zod").ZodString;
     values: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>;
     stepIndex: import("zod").ZodNumber;
-}, import("zod/v4/core").$strip>, import("@cosmicdrift/kumiko-types/hooks").SaveContext, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;
+}, import("zod/v4/core").$strip>, import("@cosmicdrift/kumiko-types/hooks").SaveContext, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined, undefined>;

package/dist/inbound-mail-foundation/account-health.d.ts

@@ -0,0 +1,17 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { DispatchWrite, IngestBatchOutcome, IngestBlockedReason } from "./supervisor-ingest.ts";
+import type { AccountHealthRef, SyncableAccount } from "./syncable-accounts.ts";
+export type PollFailureKind = "transient" | "rate_limited";
+export type AccountHealth = {
+    readonly onPollSuccess: (account: SyncableAccount, outcome: Pick<IngestBatchOutcome, "storageUnavailable" | "storageHealthy">) => Promise<void>;
+    readonly onPollFailure: (account: SyncableAccount, kind: PollFailureKind) => Promise<void>;
+    /** The cursor stayed before a failing mail: either the mail waits for its count or the ingest is down. */
+    readonly onIngestBlocked: (account: SyncableAccount, blocked: IngestBlockedReason, outcome: Pick<IngestBatchOutcome, "storageHealthy">) => Promise<void>;
+    /** The address did not decrypt because the key store is down, so the account could not be polled. */
+    readonly onKeyStoreUnavailable: (account: AccountHealthRef) => Promise<void>;
+};
+export declare function createAccountHealth(deps: {
+    readonly db: DbConnection;
+    readonly dispatchWrite: DispatchWrite;
+    readonly log: (line: string) => void;
+}): AccountHealth;

package/dist/inbound-mail-foundation/account-health.js

@@ -0,0 +1,101 @@
+// Account health: maps what the supervisor observes (repeated poll failures, quarantined mails, file
+// storage, KMS or ingest outage) onto the account status "degraded" plus a lastError code, and back to "active" once
+// nothing is wrong any more. Auth errors and disconnects are never touched here. An update is
+// dispatched only when status or lastError really changes, so a healthy mailbox causes no events.
+import { InboundMailAccountStatuses, InboundMailFoundationHandlers, InboundMailLastErrors, } from "./constants.js";
+import { hasOpenQuarantine } from "./quarantine.js";
+const FAILURES_BEFORE_DEGRADED = 3;
+const OUTAGE_LAST_ERRORS = new Set([
+    InboundMailLastErrors.encryptionUnavailable,
+    InboundMailLastErrors.ingestUnavailable,
+    InboundMailLastErrors.fileStorageUnavailable,
+]);
+const SUPERVISOR_AUDIT_REASON = "watch_supervisor";
+export function createAccountHealth(deps) {
+    const consecutiveFailures = new Map();
+    const storageUnavailable = new Set();
+    // The account snapshot of a tick is stale after our own update; this keeps the "real change" check honest.
+    // Per process: a drift between workers costs at most one redundant update-account.
+    const applied = new Map();
+    async function apply(account, lastError) {
+        const known = applied.get(account.id) ?? {
+            status: account.status,
+            lastError: account.lastError,
+        };
+        const status = lastError === null ? InboundMailAccountStatuses.active : InboundMailAccountStatuses.degraded;
+        // skip: the stored health already matches, nothing to write.
+        if (known.status === status && known.lastError === lastError)
+            return;
+        const result = await deps.dispatchWrite({
+            handlerQn: InboundMailFoundationHandlers.updateAccount,
+            tenantId: account.tenantId,
+            payload: { accountId: account.id, status, lastError, reason: SUPERVISOR_AUDIT_REASON },
+        });
+        if (!result.isSuccess) {
+            deps.log(`inbound-mail: account ${account.id} health update was rejected (${rejectionCode(result.error)})`);
+            // skip: not recorded as applied, so the next tick retries the update.
+            return;
+        }
+        applied.set(account.id, { status, lastError });
+    }
+    async function lastErrorWithoutOutage(account) {
+        if (await hasOpenQuarantine(deps.db, account.id)) {
+            return InboundMailLastErrors.messageQuarantined;
+        }
+        if (storageUnavailable.has(account.id))
+            return InboundMailLastErrors.fileStorageUnavailable;
+        return null;
+    }
+    return {
+        async onPollSuccess(account, outcome) {
+            consecutiveFailures.delete(account.id);
+            if (outcome.storageUnavailable)
+                storageUnavailable.add(account.id);
+            else if (outcome.storageHealthy)
+                storageUnavailable.delete(account.id);
+            return apply(account, await lastErrorWithoutOutage(account));
+        },
+        async onIngestBlocked(account, blocked, outcome) {
+            consecutiveFailures.delete(account.id);
+            if (blocked === "message_failing") {
+                deps.log(`inbound-mail: account ${account.id} waits for a failing message to be counted`);
+                if (outcome.storageHealthy)
+                    storageUnavailable.delete(account.id);
+                // A counted failure proves the ingest works again, so a shown outage is over; anything else stays.
+                const shown = (applied.get(account.id) ?? account).lastError;
+                // skip: no outage is shown, the status stays as it is
+                if (shown === null || !OUTAGE_LAST_ERRORS.has(shown))
+                    return;
+                return apply(account, await lastErrorWithoutOutage(account));
+            }
+            // KMS and ingest outages need no memory like storage: the next unblocked poll proves they are over.
+            if (blocked === "encryption_unavailable") {
+                return apply(account, InboundMailLastErrors.encryptionUnavailable);
+            }
+            if (blocked === "ingest_unavailable") {
+                return apply(account, InboundMailLastErrors.ingestUnavailable);
+            }
+            storageUnavailable.add(account.id);
+            return apply(account, InboundMailLastErrors.fileStorageUnavailable);
+        },
+        async onKeyStoreUnavailable(account) {
+            consecutiveFailures.delete(account.id);
+            return apply(account, InboundMailLastErrors.encryptionUnavailable);
+        },
+        async onPollFailure(account, kind) {
+            const count = (consecutiveFailures.get(account.id) ?? 0) + 1;
+            consecutiveFailures.set(account.id, count);
+            // skip: below the failure threshold the mailbox stays as it is.
+            if (count < FAILURES_BEFORE_DEGRADED)
+                return;
+            return apply(account, kind === "rate_limited"
+                ? InboundMailLastErrors.rateLimited
+                : InboundMailLastErrors.connectionFailed);
+        },
+    };
+}
+function rejectionCode(error) {
+    if (typeof error === "object" && error !== null && "code" in error)
+        return String(error.code);
+    return "unknown";
+}

package/dist/inbound-mail-foundation/account-poll-schedule.d.ts

@@ -0,0 +1,19 @@
+import type { PollAccountOptions, PollAccountResult } from "./sync-account-now.ts";
+import type { SyncableAccount } from "./syncable-accounts.ts";
+import type { InboundMailProviderPlugin } from "./types.ts";
+export declare const DEFAULT_POLL_CONCURRENCY = 4;
+export declare const DEFAULT_ACCOUNT_POLL_DEADLINE_MS: number;
+export declare function pollScheduleOf(options: {
+    readonly pollConcurrency?: number;
+    readonly accountPollDeadlineMs?: number;
+}): {
+    readonly pollConcurrency: number;
+    readonly accountPollDeadlineMs: number;
+};
+type PollAccount = (account: SyncableAccount, plugin: InboundMailProviderPlugin, options: PollAccountOptions) => Promise<PollAccountResult>;
+/** A sync past the deadline counts as one failed poll and its in-flight slot is freed. */
+export declare function withPollDeadline(pollAccount: PollAccount, deadline: {
+    readonly ms: number;
+    readonly onDeadline: (account: SyncableAccount) => Promise<void>;
+}): PollAccount;
+export {};

package/dist/inbound-mail-foundation/account-poll-schedule.js

@@ -0,0 +1,44 @@
+// How the supervisor tick spreads its accounts: a bounded number of syncs side by side, and a
+// deadline after which a sync that never answers is abandoned instead of holding the tick.
+export const DEFAULT_POLL_CONCURRENCY = 4;
+export const DEFAULT_ACCOUNT_POLL_DEADLINE_MS = 10 * 60 * 1000;
+export function pollScheduleOf(options) {
+    return {
+        pollConcurrency: options.pollConcurrency ?? DEFAULT_POLL_CONCURRENCY,
+        accountPollDeadlineMs: options.accountPollDeadlineMs ?? DEFAULT_ACCOUNT_POLL_DEADLINE_MS,
+    };
+}
+/** Aborts the signal when the deadline passes. The abandoned work may still settle later; its
+ *  outcome is dropped and a late rejection is swallowed. */
+async function runWithDeadline(deadlineMs, run) {
+    const controller = new AbortController();
+    const work = run(controller.signal);
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({ timedOut: true }), deadlineMs);
+    });
+    try {
+        const outcome = await Promise.race([
+            work.then((value) => ({ timedOut: false, value })),
+            deadline,
+        ]);
+        if (outcome.timedOut) {
+            controller.abort();
+            work.catch(() => { });
+        }
+        return outcome;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** A sync past the deadline counts as one failed poll and its in-flight slot is freed. */
+export function withPollDeadline(pollAccount, deadline) {
+    return async (account, plugin, options) => {
+        const outcome = await runWithDeadline(deadline.ms, (signal) => pollAccount(account, plugin, { ...options, signal }));
+        if (!outcome.timedOut)
+            return outcome.value;
+        await deadline.onDeadline(account);
+        return "done";
+    };
+}

package/dist/inbound-mail-foundation/account-poll.d.ts

@@ -0,0 +1,24 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { AccountHealth } from "./account-health.ts";
+import type { DispatchWrite, MessageIngester } from "./supervisor-ingest.ts";
+import type { PollAccountOptions, PollAccountResult } from "./sync-account-now.ts";
+import type { SyncCursorStore } from "./sync-cursor-store.ts";
+import type { SyncableAccount } from "./syncable-accounts.ts";
+import type { InboundMailContext, InboundMailProviderPlugin, MailAccountRecord } from "./types.ts";
+export type AccountPollerDeps = {
+    readonly systemDb: DbConnection;
+    readonly cursors: SyncCursorStore;
+    readonly ingester: MessageIngester;
+    readonly health: AccountHealth;
+    readonly providerCtx: InboundMailContext;
+    readonly dispatchWrite: DispatchWrite;
+    readonly backfillWindowDays: number;
+    readonly maxMessagesPerPoll: number;
+    readonly resolveAccessToken: (account: MailAccountRecord, plugin: InboundMailProviderPlugin) => Promise<string | undefined>;
+    /** Returns true when the account may keep running. */
+    readonly handleSyncError: (account: MailAccountRecord, err: unknown) => Promise<boolean>;
+    readonly log: (line: string) => void;
+};
+export declare function createAccountPoller(deps: AccountPollerDeps): {
+    readonly pollAccount: (account: SyncableAccount, plugin: InboundMailProviderPlugin, options?: PollAccountOptions) => Promise<PollAccountResult>;
+};

package/dist/inbound-mail-foundation/account-poll.js

@@ -0,0 +1,157 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
+import { refetchSnippetOnlyMessages } from "./content-refetch.js";
+import { describeError } from "./describe-error.js";
+import { seenMessageTable } from "./entities.js";
+import { isInboundAuthError, isInboundCredentialNotStoredError, isInboundCursorInvalidError, isInboundRateLimitError, } from "./provider-errors.js";
+import { quarantinedMessageIds } from "./quarantine.js";
+import { retryQuarantinedMessages } from "./quarantine-retry.js";
+const SEEN_LOOKUP_CHUNK_SIZE = 1000;
+export function createAccountPoller(deps) {
+    const { systemDb, cursors, ingester, health, providerCtx, backfillWindowDays, maxMessagesPerPoll, resolveAccessToken, handleSyncError, log, } = deps;
+    function unknownMessageIdsFilterFor(account) {
+        return async (providerMessageIds) => {
+            if (providerMessageIds.length === 0)
+                return new Set();
+            // One bind parameter per id: a full-mailbox listing would exceed Postgres' 65535 limit.
+            const seenIds = new Set();
+            for (let start = 0; start < providerMessageIds.length; start += SEEN_LOOKUP_CHUNK_SIZE) {
+                const seen = await selectMany(systemDb, seenMessageTable, {
+                    tenantId: account.tenantId,
+                    accountId: account.id,
+                    providerMessageId: {
+                        in: providerMessageIds.slice(start, start + SEEN_LOOKUP_CHUNK_SIZE),
+                    },
+                }, { fields: ["providerMessageId"] });
+                for (const row of seen)
+                    seenIds.add(row.providerMessageId);
+            }
+            // A quarantined message counts as seen: re-fetching it would only fail the same way again.
+            for (const id of await quarantinedMessageIds(systemDb, account.id, providerMessageIds)) {
+                seenIds.add(id);
+            }
+            return new Set(providerMessageIds.filter((id) => !seenIds.has(id)));
+        };
+    }
+    function pollFailureKindOf(err) {
+        if (isInboundAuthError(err) || isInboundCursorInvalidError(err))
+            return null;
+        return isInboundRateLimitError(err) ? "rate_limited" : "transient";
+    }
+    async function refetchContentSafely(account, plugin, signal) {
+        // skip: the provider cannot reload content.
+        if (!plugin.fetchContent)
+            return;
+        try {
+            const accessToken = await resolveAccessToken(account, plugin);
+            await refetchSnippetOnlyMessages({
+                db: systemDb,
+                dispatchWrite: deps.dispatchWrite,
+                providerCtx,
+                account,
+                plugin,
+                windowDays: backfillWindowDays,
+                accessToken,
+                signal,
+            });
+        }
+        catch (err) {
+            // Best effort: the sync itself succeeded, the next tick retries the reload.
+            log(`inbound-mail: content reload for account ${account.id} failed: ${describeError(err)}`);
+        }
+    }
+    async function retryQuarantineSafely(account, plugin, signal) {
+        try {
+            const accessToken = await resolveAccessToken(account, plugin);
+            await retryQuarantinedMessages({
+                db: systemDb,
+                dispatchWrite: deps.dispatchWrite,
+                providerCtx,
+                account,
+                plugin,
+                accessToken,
+                signal,
+                log,
+            });
+        }
+        catch (err) {
+            // Best effort: the sync itself succeeded, the flag stays and the next tick retries.
+            log(`inbound-mail: quarantine retry for account ${account.id} failed: ${describeError(err)}`);
+        }
+    }
+    // Fetches and ingests batch after batch until the provider has no more or the message budget of
+    // this tick is used up. An abandoned sync (deadline) throws out of the loop.
+    async function ingestBatches(account, plugin, options) {
+        const { signal } = options;
+        let cursor = await cursors.load(account.id);
+        let budget = maxMessagesPerPoll;
+        const totals = { storageUnavailable: false, storageHealthy: false, ingested: false };
+        for (;;) {
+            const accessToken = await resolveAccessToken(account, plugin);
+            const result = await plugin.fetch(providerCtx, account, cursor, {
+                backfillWindowDays,
+                maxMessages: budget,
+                filterUnknownMessageIds: unknownMessageIdsFilterFor(account),
+                ...(accessToken !== undefined && { accessToken }),
+                ...(signal && { signal }),
+            });
+            // The sync was abandoned while the provider was busy; its late result is dropped.
+            signal?.throwIfAborted();
+            const outcome = await ingester.ingestBatch(account, result.messages, result.rejected ?? [], JSON.stringify(result.nextCursor), {
+                ...(options.countBucket !== undefined && { countBucket: options.countBucket }),
+                ...(signal && { signal }),
+                proof: { ingested: totals.ingested, storageHealthy: totals.storageHealthy },
+            });
+            totals.storageUnavailable ||= outcome.storageUnavailable;
+            totals.storageHealthy ||= outcome.storageHealthy;
+            totals.ingested ||= outcome.ingested;
+            // Blocked: the cursor stays before the stuck mail, the next tick fetches it again.
+            if (outcome.blocked)
+                return { ...totals, blocked: outcome.blocked };
+            // A newer poll may already own the account; an abandoned one must not move its cursor back.
+            signal?.throwIfAborted();
+            await cursors.save(account, result.nextCursor);
+            cursor = result.nextCursor;
+            budget -= result.messages.length;
+            if (!result.hasMore || budget <= 0)
+                return totals;
+        }
+    }
+    async function pollAccount(account, plugin, options = {}) {
+        let totals;
+        try {
+            totals = await ingestBatches(account, plugin, options);
+        }
+        catch (err) {
+            // skip: an error caused by abandoning the sync is already counted as the deadline failure.
+            if (options.signal?.aborted)
+                return "done";
+            if (options.fromWake && isInboundCredentialNotStoredError(err)) {
+                // The secret is written after the account is created; the next tick picks it up.
+                log(`inbound-mail: account ${account.id} credential not stored yet, wake sync skipped`);
+                return "credential_pending";
+            }
+            const stillRunning = await handleSyncError(account, err);
+            const failureKind = pollFailureKindOf(err);
+            if (stillRunning && failureKind)
+                await health.onPollFailure(account, failureKind);
+            return "done";
+        }
+        // skip: abandoned during the last batch; the deadline already counted this poll as failed.
+        if (options.signal?.aborted)
+            return "done";
+        if (totals.blocked) {
+            await health.onIngestBlocked(account, totals.blocked, totals);
+            // A retry asked for by an admin does not depend on the cursor, so a stuck mail must not hold it.
+            // During an outage it would fail the same way; the flag stays and runs after the recovery.
+            if (totals.blocked === "message_failing") {
+                await retryQuarantineSafely(account, plugin, options.signal);
+            }
+            return "done";
+        }
+        await health.onPollSuccess(account, totals);
+        await retryQuarantineSafely(account, plugin, options.signal);
+        await refetchContentSafely(account, plugin, options.signal);
+        return "done";
+    }
+    return { pollAccount };
+}

package/dist/inbound-mail-foundation/account-record.d.ts

@@ -9,5 +9,6 @@ export type MailAccountRow = {
     readonly displayName?: string | null;
     readonly status?: string | null;
     readonly watchState?: string | null;
+    readonly trustedAuthservId?: string | null;
 };
 export declare function toMailAccountRecord(row: MailAccountRow, tenantId: string, requestId: string): Promise<MailAccountRecord>;

package/dist/inbound-mail-foundation/account-record.js

@@ -23,5 +23,6 @@ export async function toMailAccountRecord(row, tenantId, requestId) {
         displayName: row.displayName ?? "",
         status: isAccountStatus(row.status) ? row.status : InboundMailAccountStatuses.active,
         watchState: row.watchState ?? "idle",
+        trustedAuthservId: row.trustedAuthservId ?? null,
     };
 }

package/dist/inbound-mail-foundation/account-wake.d.ts

@@ -0,0 +1,3 @@
+export type MailAccountWakeListener = (tenantId: string, accountId: string) => void;
+export declare function registerMailAccountWakeListener(listener: MailAccountWakeListener): () => void;
+export declare function wakeMailAccount(tenantId: string, accountId: string): void;

package/dist/inbound-mail-foundation/account-wake.js

@@ -0,0 +1,17 @@
+// Process-local wake channel between the account-event consumer (feature.ts) and the sync supervisor.
+// A freshly connected, reconnected or re-activated mailbox is synced right away instead of waiting
+// for the next poll tick. The consumer runs "per-instance", so every process wakes its own supervisor.
+//
+// Without a running event dispatcher in the process (or without a supervisor) nothing wakes anyone;
+// the regular poll tick then picks the account up, so this is purely a latency optimisation.
+const listeners = new Set();
+export function registerMailAccountWakeListener(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+export function wakeMailAccount(tenantId, accountId) {
+    for (const listener of listeners)
+        listener(tenantId, accountId);
+}

package/dist/inbound-mail-foundation/connect-callback-verify.d.ts

@@ -0,0 +1,10 @@
+import type { SignatureExtraRouteVerifyRequest } from "@cosmicdrift/kumiko-framework/api";
+import type { Context } from "hono";
+import type { OAuthCodeExchange } from "./inbound-oauth-flow.ts";
+import { type OAuthStatePayload } from "./oauth-state.ts";
+export type VerifiedCallback = {
+    readonly code: string;
+    readonly state: OAuthStatePayload;
+};
+export declare function verifyCallbackRequest(request: SignatureExtraRouteVerifyRequest, stateSecret: string): VerifiedCallback;
+export declare function refreshTokenOrRefusal(c: Context, state: OAuthStatePayload, tokens: OAuthCodeExchange): string | Response;

package/dist/inbound-mail-foundation/connect-callback-verify.js

@@ -0,0 +1,31 @@
+import { ExtraRouteRejection } from "@cosmicdrift/kumiko-framework/api";
+import { errorJson } from "./connect-route-responses.js";
+import { normalizeMailAddress } from "./handlers/account-address.js";
+import { verifyOAuthState } from "./oauth-state.js";
+export function verifyCallbackRequest(request, stateSecret) {
+    const code = request.query["code"] ?? "";
+    const rawState = request.query["state"] ?? "";
+    if (!code || !rawState) {
+        throw new ExtraRouteRejection(400, { error: { code: "invalid_callback", message: "missing code or state" } }, "inbound-mail oauth callback missing code or state");
+    }
+    const verified = verifyOAuthState(rawState, stateSecret);
+    if (!verified.ok) {
+        throw new ExtraRouteRejection(400, { error: { code: "invalid_state", message: `state rejected: ${verified.reason}` } }, `inbound-mail oauth callback state rejected: ${verified.reason}`);
+    }
+    return { code, state: verified.payload };
+}
+// The refresh token the account needs, or the response that refuses the exchange result.
+export function refreshTokenOrRefusal(c, state, tokens) {
+    // Personal only: a shared mailbox is often an M365 shared mailbox the admin opens with their own
+    // login (delegated access). A token without access to it shows up as auth_error on the first sync.
+    if (state.ownerUserId &&
+        normalizeMailAddress(tokens.accountAddress) !== normalizeMailAddress(state.mailbox)) {
+        return errorJson(c, 403, "mailbox_address_mismatch", `the account you signed in with is not ${state.mailbox}; sign in with that mailbox's account`);
+    }
+    // No refresh token, no server-side sync. Consent must request offline_access (or
+    // access_type=offline); the provider's oauth block owns the scopes.
+    if (!tokens.refreshToken) {
+        return errorJson(c, 502, "no_refresh_token", `provider "${state.providerKey}" returned no refresh token — check the offline-access scope in the provider's oauth.scopes`);
+    }
+    return tokens.refreshToken;
+}

package/dist/inbound-mail-foundation/connect-route-responses.d.ts

@@ -0,0 +1,13 @@
+import type { Context } from "hono";
+export declare function connectFailureResponse(c: Context, error: unknown): Response & import("hono").TypedResponse<{
+    error: {
+        code: string;
+        message: string;
+    };
+}, 400 | 401 | 403 | 404 | 409 | 500 | 502, "json">;
+export declare function errorJson(c: Context, status: 400 | 401 | 403 | 404 | 409 | 500 | 502, code: string, message: string): Response & import("hono").TypedResponse<{
+    error: {
+        code: string;
+        message: string;
+    };
+}, 400 | 401 | 403 | 404 | 409 | 500 | 502, "json">;

package/dist/inbound-mail-foundation/connect-route-responses.js

@@ -0,0 +1,16 @@
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { InboundMailConnectErrors } from "./constants.js";
+const CONNECT_CONFLICT_MESSAGES = {
+    [InboundMailConnectErrors.addressAlreadyConnected.reason]: "this mailbox address is already connected",
+    [InboundMailConnectErrors.addressDisconnected.reason]: "this mailbox was disconnected before; reconnect it from the mailbox list instead",
+};
+export function connectFailureResponse(c, error) {
+    const reason = propertyOf(propertyOf(error, "details"), "reason");
+    const conflict = typeof reason === "string" ? CONNECT_CONFLICT_MESSAGES[reason] : undefined;
+    if (typeof reason === "string" && conflict)
+        return errorJson(c, 409, reason, conflict);
+    return errorJson(c, 502, "account_create_failed", JSON.stringify(error ?? {}));
+}
+export function errorJson(c, status, code, message) {
+    return c.json({ error: { code, message } }, status);
+}