@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

package/src/inbound-mail-foundation/__tests__/watch-supervisor.integration.test.ts

@@ -0,0 +1,433 @@
+// Watch-supervisor integration — drives createInboundMailSupervisor against
+// a real setupTestStack + inbound-provider-inmemory (fetch/watch/error
+// injection). Proves poll ingest, IDLE watch push, auth_error quarantine,
+// and cursor-invalid resync — not existence checks.
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configurePiiSubjectKms,
+  InMemoryKmsAdapter,
+  resetPiiSubjectKmsForTests,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { createSystemUser, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { waitFor } from "@cosmicdrift/kumiko-framework/testing";
+import {
+  createComplianceProfilesFeature,
+  tenantComplianceProfileEntity,
+} from "../../compliance-profiles";
+import { createConfigFeature } from "../../config";
+import { inboundProviderInMemoryFeature } from "../../inbound-provider-inmemory";
+import {
+  emitWatchError,
+  failNextFetchWith,
+  isWatching,
+  resetInboundInMemory,
+  seedInboundMessage,
+} from "../../inbound-provider-inmemory/feature";
+import { createTenantFeature } from "../../tenant/feature";
+import { createTenantLifecycleFeature } from "../../tenant-lifecycle";
+import {
+  createInboundMailSupervisor,
+  InboundAuthError,
+  InboundCursorInvalidError,
+  InboundMailAccountStatuses,
+  InboundMailFoundationHandlers,
+  InboundRateLimitError,
+  inboundMailFoundationFeature,
+  inboundMessagesProjectionTable,
+  mailAccountsProjectionTable,
+  type RawInboundMessage,
+  seenMessageEntity,
+  syncCursorEntity,
+} from "../index";
+
+let stack: TestStack;
+let db: DbConnection;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createTenantFeature(),
+      createComplianceProfilesFeature(),
+      createTenantLifecycleFeature(),
+      inboundMailFoundationFeature,
+      inboundProviderInMemoryFeature,
+    ],
+  });
+  db = stack.db;
+  await createEventsTable(db);
+  await unsafeCreateEntityTable(db, tenantComplianceProfileEntity);
+  await unsafeCreateEntityTable(db, syncCursorEntity);
+  await unsafeCreateEntityTable(db, seenMessageEntity);
+  configurePiiSubjectKms(new InMemoryKmsAdapter());
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+  resetPiiSubjectKmsForTests();
+});
+
+beforeEach(() => {
+  resetInboundInMemory();
+});
+
+afterEach(() => {
+  resetInboundInMemory();
+});
+
+function adminFor(tenantNumber: number) {
+  return createTestUser({
+    id: tenantNumber,
+    tenantId: testTenantId(tenantNumber),
+    roles: ["TenantAdmin", "SystemAdmin"],
+  });
+}
+
+function rawMsg(
+  overrides: Partial<RawInboundMessage> & { providerMessageId: string },
+): RawInboundMessage {
+  return {
+    messageIdHeader: `${overrides.providerMessageId}@example.com`,
+    providerThreadId: null,
+    references: [],
+    from: "sender@example.com",
+    to: ["inbox@tenant.example"],
+    cc: [],
+    subject: `Subject ${overrides.providerMessageId}`,
+    snippet: "snippet",
+    receivedAtIso: "2026-07-15T10:00:00Z",
+    rawMime: null,
+    scope: "inbox",
+    ...overrides,
+  };
+}
+
+async function connectSharedAccount(admin: ReturnType<typeof adminFor>): Promise<string> {
+  const result = (await stack.http.writeOk(
+    InboundMailFoundationHandlers.connectAccount,
+    {
+      provider: "inmemory",
+      authMethod: "password",
+      displayName: "Team-Inbox",
+      address: "inbox@tenant.example",
+      scope: "shared",
+    },
+    admin,
+  )) as { accountId: string };
+  return result.accountId;
+}
+
+function createSupervisor() {
+  return createInboundMailSupervisor({
+    providerCtx: { registry: stack.registry },
+    db,
+    dispatchWrite: ({ handlerQn, payload, tenantId }) =>
+      stack.dispatcher.write(
+        handlerQn,
+        payload,
+        createSystemUser(tenantId as TenantId, [ROLES.SystemAdmin]),
+      ),
+    // Keep the periodic tick far away so tests only exercise explicit
+    // pollOnce / watch push — not a racing background timer.
+    pollIntervalMs: 60_000,
+    watchBackoffInitialMs: 50,
+    watchBackoffMaxMs: 200,
+  });
+}
+
+describe("watch-supervisor — poll reconciliation", () => {
+  test("pollOnce fetches seeded messages and persists them via ingest-message", async () => {
+    const admin = adminFor(4101);
+    const accountId = await connectSharedAccount(admin);
+    await seedInboundMessage(accountId, rawMsg({ providerMessageId: "poll-uid-1" }));
+    await seedInboundMessage(accountId, rawMsg({ providerMessageId: "poll-uid-2" }));
+
+    const supervisor = createSupervisor();
+    await supervisor.pollOnce();
+
+    const rows = await selectMany(db, inboundMessagesProjectionTable, { accountId });
+    expect(rows).toHaveLength(2);
+    const ids = rows.map((r) => r["messageIdHeader"]).sort();
+    expect(ids).toEqual(["poll-uid-1@example.com", "poll-uid-2@example.com"]);
+  });
+
+  test("second pollOnce is idempotent — Dedup keeps a single row per providerMessageId", async () => {
+    const admin = adminFor(4102);
+    const accountId = await connectSharedAccount(admin);
+    await seedInboundMessage(accountId, rawMsg({ providerMessageId: "poll-dedup-1" }));
+
+    const supervisor = createSupervisor();
+    await supervisor.pollOnce();
+    await supervisor.pollOnce();
+
+    const rows = await selectMany(db, inboundMessagesProjectionTable, { accountId });
+    expect(rows).toHaveLength(1);
+  });
+});
+
+describe("watch-supervisor — IDLE watch path", () => {
+  test("start() arms watch; seedInboundMessage pushes and ingest lands a row", async () => {
+    const admin = adminFor(4103);
+    const accountId = await connectSharedAccount(admin);
+    const supervisor = createSupervisor();
+    try {
+      await supervisor.start();
+
+      await waitFor(() => {
+        expect(isWatching(accountId)).toBe(true);
+      });
+
+      await seedInboundMessage(
+        accountId,
+        rawMsg({ providerMessageId: "watch-uid-1", subject: "via watch" }),
+      );
+
+      await waitFor(async () => {
+        const rows = await selectMany(db, inboundMessagesProjectionTable, { accountId });
+        expect(rows).toHaveLength(1);
+      });
+
+      const rows = await selectMany(db, inboundMessagesProjectionTable, { accountId });
+      expect(rows[0]?.["messageIdHeader"]).toBe("watch-uid-1@example.com");
+    } finally {
+      await supervisor.stop();
+    }
+    expect(isWatching(accountId)).toBe(false);
+  });
+});
+
+describe("watch-supervisor — error semantics", () => {
+  test("InboundAuthError on fetch marks the account auth_error", async () => {
+    const admin = adminFor(4104);
+    const accountId = await connectSharedAccount(admin);
+    failNextFetchWith(accountId, new InboundAuthError("credentials rejected"));
+
+    const supervisor = createSupervisor();
+    await supervisor.pollOnce();
+
+    const accounts = await selectMany(db, mailAccountsProjectionTable, { id: accountId });
+    expect(accounts).toHaveLength(1);
+    expect(accounts[0]?.["status"]).toBe(InboundMailAccountStatuses.authError);
+  });
+
+  test("InboundAuthError on live watch stops the watcher and marks auth_error", async () => {
+    const admin = adminFor(4106);
+    const accountId = await connectSharedAccount(admin);
+    const supervisor = createSupervisor();
+    try {
+      await supervisor.start();
+      await waitFor(() => {
+        expect(isWatching(accountId)).toBe(true);
+      });
+
+      emitWatchError(accountId, new InboundAuthError("token revoked"));
+
+      await waitFor(async () => {
+        expect(isWatching(accountId)).toBe(false);
+        const accounts = await selectMany(db, mailAccountsProjectionTable, { id: accountId });
+        expect(accounts[0]?.["status"]).toBe(InboundMailAccountStatuses.authError);
+      });
+    } finally {
+      await supervisor.stop();
+    }
+  });
+
+  test("InboundCursorInvalidError resets the cursor; a later poll still ingests", async () => {
+    const admin = adminFor(4105);
+    const accountId = await connectSharedAccount(admin);
+    await seedInboundMessage(accountId, rawMsg({ providerMessageId: "cursor-ok-1" }));
+
+    const supervisor = createSupervisor();
+    await supervisor.pollOnce();
+    expect(await selectMany(db, inboundMessagesProjectionTable, { accountId })).toHaveLength(1);
+
+    failNextFetchWith(accountId, new InboundCursorInvalidError("uidValidity changed"));
+    await supervisor.pollOnce();
+
+    // Account stays active (cursor invalid ≠ auth failure).
+    const accounts = await selectMany(db, mailAccountsProjectionTable, { id: accountId });
+    expect(accounts[0]?.["status"]).toBe(InboundMailAccountStatuses.active);
+
+    await seedInboundMessage(accountId, rawMsg({ providerMessageId: "cursor-ok-2" }));
+    await supervisor.pollOnce();
+
+    const rows = await selectMany(db, inboundMessagesProjectionTable, { accountId });
+    expect(rows.map((r) => r["messageIdHeader"]).sort()).toEqual([
+      "cursor-ok-1@example.com",
+      "cursor-ok-2@example.com",
+    ]);
+  });
+
+  test("InboundRateLimitError on fetch keeps the account active for the next tick", async () => {
+    const admin = adminFor(4107);
+    const accountId = await connectSharedAccount(admin);
+    failNextFetchWith(accountId, new InboundRateLimitError("slow down", 30_000));
+
+    const supervisor = createSupervisor();
+    await supervisor.pollOnce();
+
+    const accounts = await selectMany(db, mailAccountsProjectionTable, { id: accountId });
+    expect(accounts[0]?.["status"]).toBe(InboundMailAccountStatuses.active);
+  });
+});
+
+describe("watch-supervisor — watch restart + ingest resilience", () => {
+  test("transient watch error schedules backoff restart and re-arms watch", async () => {
+    const admin = adminFor(4108);
+    const accountId = await connectSharedAccount(admin);
+    const supervisor = createSupervisor();
+    try {
+      await supervisor.start();
+      await waitFor(() => {
+        expect(isWatching(accountId)).toBe(true);
+      });
+
+      emitWatchError(accountId, new Error("socket dropped"));
+      // No assertion here: isWatching(accountId) flips to false as a side
+      // effect of emitWatchError itself (inbound-provider-inmemory's
+      // feature.ts sets state.watch = null before handlers.onError runs),
+      // and the restart re-arms fast enough that the persisted `backoff:`
+      // projection state isn't reliably observable between the two either
+      // — asserting either one here pins test-helper bookkeeping, not
+      // production behavior. The real assertions are below: the watch
+      // recovers, and the account stays active with a valid watchState.
+
+      await waitFor(() => {
+        expect(isWatching(accountId)).toBe(true);
+      });
+
+      const accounts = await selectMany(db, mailAccountsProjectionTable, { id: accountId });
+      expect(accounts[0]?.["status"]).toBe(InboundMailAccountStatuses.active);
+      expect(String(accounts[0]?.["watchState"])).toMatch(/^(watching|backoff:)/);
+    } finally {
+      await supervisor.stop();
+    }
+  });
+
+  test("watch-ingest failure is logged; poll reconciliation still ingests", async () => {
+    const admin = adminFor(4109);
+    const accountId = await connectSharedAccount(admin);
+    let ingestCalls = 0;
+    const supervisor = createInboundMailSupervisor({
+      providerCtx: { registry: stack.registry },
+      db,
+      dispatchWrite: ({ handlerQn, payload, tenantId }) => {
+        if (handlerQn === InboundMailFoundationHandlers.ingestMessage) {
+          ingestCalls += 1;
+          if (ingestCalls === 1) {
+            return Promise.resolve({ isSuccess: false, error: { code: "simulated" } });
+          }
+        }
+        return stack.dispatcher.write(
+          handlerQn,
+          payload,
+          createSystemUser(tenantId as TenantId, [ROLES.SystemAdmin]),
+        );
+      },
+      pollIntervalMs: 60_000,
+      watchBackoffInitialMs: 50,
+      watchBackoffMaxMs: 200,
+    });
+    try {
+      await supervisor.start();
+      await waitFor(() => {
+        expect(isWatching(accountId)).toBe(true);
+      });
+
+      await seedInboundMessage(
+        accountId,
+        rawMsg({ providerMessageId: "watch-ingest-fail-1", subject: "via watch" }),
+      );
+
+      await supervisor.pollOnce();
+
+      const rows = await selectMany(db, inboundMessagesProjectionTable, { accountId });
+      expect(rows.some((r) => r["messageIdHeader"] === "watch-ingest-fail-1@example.com")).toBe(
+        true,
+      );
+    } finally {
+      await supervisor.stop();
+    }
+  });
+
+  test("storeBody hook persists raw MIME references on poll ingest", async () => {
+    const admin = adminFor(4110);
+    const accountId = await connectSharedAccount(admin);
+    const stored: string[] = [];
+    const supervisor = createInboundMailSupervisor({
+      providerCtx: { registry: stack.registry },
+      db,
+      dispatchWrite: ({ handlerQn, payload, tenantId }) =>
+        stack.dispatcher.write(
+          handlerQn,
+          payload,
+          createSystemUser(tenantId as TenantId, [ROLES.SystemAdmin]),
+        ),
+      storeBody: async (_account, msg) => {
+        stored.push(msg.providerMessageId);
+        return `body-ref:${msg.providerMessageId}`;
+      },
+      pollIntervalMs: 60_000,
+    });
+    await seedInboundMessage(
+      accountId,
+      rawMsg({
+        providerMessageId: "body-store-1",
+        rawMime: new TextEncoder().encode("raw-mime-bytes"),
+      }),
+    );
+    await supervisor.pollOnce();
+    expect(stored).toEqual(["body-store-1"]);
+  });
+
+  test("disconnecting an account tears down its watcher on the next pollOnce", async () => {
+    const admin = adminFor(4111);
+    const accountId = await connectSharedAccount(admin);
+    const supervisor = createSupervisor();
+    try {
+      await supervisor.start();
+      await waitFor(() => {
+        expect(isWatching(accountId)).toBe(true);
+      });
+
+      await stack.http.writeOk(
+        InboundMailFoundationHandlers.disconnectAccount,
+        { accountId, reason: "test" },
+        admin,
+      );
+      await supervisor.pollOnce();
+
+      expect(isWatching(accountId)).toBe(false);
+    } finally {
+      await supervisor.stop();
+    }
+  });
+
+  test("start() is idempotent — second start keeps the watcher armed", async () => {
+    const admin = adminFor(4112);
+    const accountId = await connectSharedAccount(admin);
+    const supervisor = createSupervisor();
+    try {
+      await supervisor.start();
+      await waitFor(() => {
+        expect(isWatching(accountId)).toBe(true);
+      });
+      await supervisor.start();
+      expect(isWatching(accountId)).toBe(true);
+    } finally {
+      await supervisor.stop();
+    }
+  });
+});

package/src/inbound-mail-foundation/aggregate-id.ts

@@ -0,0 +1,40 @@
+import { v5 as uuidv5 } from "uuid";
+
+// Fixed UUID-namespaces für deterministic aggregate-id-Ableitung.
+// Generiert einmalig (2026-07-12), in Stein gemeißelt: ein Wechsel würde
+// jeden existing aggregate-Stream re-keyen → kaputte Message-Historie,
+// kaputte Idempotency. Drift-Pins in __tests__/feature.test.ts.
+
+/** Namespace für inbound-message-Streams. */
+const INBOUND_MESSAGE_NAMESPACE = "7f2a9c41-3d6b-4e0f-9c58-2b1e7a4d8f63";
+
+/** Namespace für mail-thread-Streams. */
+const MAIL_THREAD_NAMESPACE = "b48d1e72-5c9a-4f36-8e0d-6a3f9b2c7e15";
+
+/**
+ * Deterministic aggregate-id für eine inbound-message. Key ist
+ * (accountId, providerMessageId): derselbe Provider-Fetch der zweimal
+ * dieselbe Message liefert (IDLE-Doppel-Notify, Cursor-Overlap,
+ * Watch-Restart-Replay) landet auf demselben Stream — der Idempotency-
+ * Check im ingest-handler sieht den bereits appendeten Event.
+ *
+ * accountId (nicht tenantId) im Key: zwei Accounts desselben Tenants
+ * können dieselbe Mail empfangen (CC an beide Postfächer) — das sind
+ * fachlich ZWEI inbound-messages.
+ */
+// @wrapper-known uuid-domain
+export function inboundMessageAggregateId(accountId: string, providerMessageId: string): string {
+  return uuidv5(`${accountId}:${providerMessageId}`, INBOUND_MESSAGE_NAMESPACE);
+}
+
+/**
+ * Deterministic aggregate-id für einen mail-thread. Key ist
+ * (tenantId, threadKey) — Threads sind tenant-weit, nicht account-weit:
+ * eine Konversation die über zwei verbundene Postfächer läuft ist EIN
+ * Thread. threadKey kommt normalisiert vom Provider (References/
+ * In-Reply-To-Chain bzw. Provider-Thread-ID).
+ */
+// @wrapper-known uuid-domain
+export function mailThreadAggregateId(tenantId: string, threadKey: string): string {
+  return uuidv5(`${tenantId}:${threadKey}`, MAIL_THREAD_NAMESPACE);
+}

package/src/inbound-mail-foundation/connect-routes.ts

@@ -0,0 +1,230 @@
+// createInboundMailConnectRoutes — Hono-Route-Factory die der App-Owner
+// via `extraRoutes` in seinem bin/server.ts mountet (Muster
+// billing-foundation/webhook-handler.ts).
+//
+//   GET /inbound-mail/connect          (auth-gated — im authed Bereich mounten)
+//   GET /inbound-mail/oauth/callback   (anonymous — MUSS außerhalb /api/*
+//                                       liegen, /api ist auth-gated;
+//                                       verifiziert user-data-rights §5)
+//
+// Beispiel bin/server.ts:
+//
+//   const routes = createInboundMailConnectRoutes({
+//     providerCtx: { registry: deps.registry, secrets, config: undefined },
+//     dispatchWrite: ({ handlerQn, payload, tenantId }) =>
+//       deps.dispatchSystemWrite({ handlerQn, payload, tenantId: tenantId as TenantId }),
+//     secrets,
+//     stateSecret: env.INBOUND_MAIL_STATE_SECRET,
+//     callbackUrl: `${env.PUBLIC_BASE_URL}/inbound-mail/oauth/callback`,
+//   });
+//   app.get("/api/inbound-mail/connect", routes.connect);      // auth-gated
+//   app.get("/inbound-mail/oauth/callback", routes.callback);  // anonymous
+//
+// Provider registrieren KEINE eigenen Routen — ihr oauth-Block wird über
+// resolveInboundProviderForKey aufgelöst. Der Callback vertraut NUR dem
+// HMAC-verifizierten state (CSRF-/Fremd-Claiming-Sperre, oauth-state.ts).
+
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import type { Context } from "hono";
+import {
+  INBOUND_MAIL_FOUNDATION_FEATURE,
+  InboundMailAuthMethods,
+  InboundMailFoundationHandlers,
+  inboundCredentialSecretKey,
+} from "./constants";
+import { signOAuthState, verifyOAuthState } from "./oauth-state";
+import { resolveInboundProviderForKey } from "./provider-factory";
+import type { InboundMailContext } from "./types";
+
+const DEFAULT_STATE_TTL_MINUTES = 15;
+
+export type InboundMailConnectRoutesDeps = {
+  /** Slim-Context für Provider-Lookups + oauth-Calls (registry Pflicht). */
+  readonly providerCtx: InboundMailContext;
+  /** Schreibt durch den Standard-Dispatcher mit auto-konstruiertem
+   *  SystemUser — muss connect-account als SystemAdmin durchlassen. */
+  readonly dispatchWrite: (args: {
+    readonly handlerQn: string;
+    readonly payload: unknown;
+    readonly tenantId: string;
+  }) => Promise<{
+    readonly isSuccess: boolean;
+    readonly data?: unknown;
+    readonly error?: unknown;
+  }>;
+  /** Tenant-Secret-Write für den Refresh-Token (Slot = accountId). */
+  readonly secrets: SecretsContext;
+  /** HMAC-Secret für den state-Parameter (Deploy-Config aus env —
+   *  `scope:"system"`-Secrets existieren in secrets-v1 nicht). */
+  readonly stateSecret: string;
+  /** Absolute Callback-URL — exakt so beim OAuth-Provider registriert. */
+  readonly callbackUrl: string;
+  /** Wohin der Browser nach erfolgreichem Connect redirected wird.
+   *  Fehlt sie, antwortet der Callback mit JSON (API-/Test-Modus). */
+  readonly successRedirectUrl?: string;
+  readonly stateTtlMinutes?: number;
+};
+
+function errorJson(c: Context, status: 400 | 401 | 404 | 502, code: string, message: string) {
+  return c.json({ error: { code, message } }, status);
+}
+
+/** Session-User aus dem Hono-Context — vom Auth-Middleware gesetzt. */
+function sessionUserOf(c: Context): { id: string; tenantId: string } | undefined {
+  const user = c.get("user") as { id?: unknown; tenantId?: unknown } | undefined;
+  if (!user || typeof user.id !== "string" || typeof user.tenantId !== "string") return undefined;
+  return { id: user.id, tenantId: user.tenantId };
+}
+
+export function createInboundMailConnectRoutes(deps: InboundMailConnectRoutesDeps) {
+  const ttl = deps.stateTtlMinutes ?? DEFAULT_STATE_TTL_MINUTES;
+
+  const connect = async (c: Context): Promise<Response> => {
+    const user = sessionUserOf(c);
+    if (!user) {
+      return errorJson(c, 401, "unauthenticated", "connect requires a signed-in user");
+    }
+    const providerKey = c.req.query("provider") ?? "";
+    const scope = c.req.query("scope") ?? "";
+    const mailbox = c.req.query("mailbox") ?? "";
+    if (!providerKey || (scope !== "user" && scope !== "shared") || !mailbox) {
+      return errorJson(
+        c,
+        400,
+        "invalid_connect_request",
+        `${INBOUND_MAIL_FOUNDATION_FEATURE}: expected ?provider=<key>&scope=user|shared&mailbox=<address>`,
+      );
+    }
+
+    let plugin: ReturnType<typeof resolveInboundProviderForKey>;
+    try {
+      plugin = resolveInboundProviderForKey(deps.providerCtx, providerKey);
+    } catch (e) {
+      return errorJson(
+        c,
+        404,
+        "provider_not_registered",
+        e instanceof Error ? e.message : String(e),
+      );
+    }
+    if (!plugin.oauth) {
+      return errorJson(
+        c,
+        400,
+        "provider_has_no_oauth_flow",
+        `provider "${providerKey}" connects via credentials form (connect-account write-handler), not OAuth`,
+      );
+    }
+
+    const state = signOAuthState(
+      {
+        tenantId: user.tenantId,
+        ownerUserId: scope === "user" ? user.id : null,
+        providerKey,
+        mailbox,
+      },
+      ttl,
+      deps.stateSecret,
+    );
+    const authorizeUrl = await plugin.oauth.buildAuthorizeUrl(deps.providerCtx, {
+      state,
+      redirectUri: deps.callbackUrl,
+    });
+    return c.redirect(authorizeUrl, 302);
+  };
+
+  const callback = async (c: Context): Promise<Response> => {
+    const code = c.req.query("code") ?? "";
+    const rawState = c.req.query("state") ?? "";
+    if (!code || !rawState) {
+      return errorJson(c, 400, "invalid_callback", "missing code or state");
+    }
+    const verified = verifyOAuthState(rawState, deps.stateSecret);
+    if (!verified.ok) {
+      return errorJson(c, 400, "invalid_state", `state rejected: ${verified.reason}`);
+    }
+    const state = verified.payload;
+
+    let plugin: ReturnType<typeof resolveInboundProviderForKey>;
+    try {
+      plugin = resolveInboundProviderForKey(deps.providerCtx, state.providerKey);
+    } catch (e) {
+      return errorJson(
+        c,
+        404,
+        "provider_not_registered",
+        e instanceof Error ? e.message : String(e),
+      );
+    }
+    if (!plugin.oauth) {
+      return errorJson(c, 400, "provider_has_no_oauth_flow", state.providerKey);
+    }
+
+    let tokens: Awaited<ReturnType<NonNullable<typeof plugin.oauth>["exchangeCode"]>>;
+    try {
+      tokens = await plugin.oauth.exchangeCode(deps.providerCtx, {
+        code,
+        redirectUri: deps.callbackUrl,
+      });
+    } catch (e) {
+      return errorJson(c, 502, "token_exchange_failed", e instanceof Error ? e.message : String(e));
+    }
+    if (!tokens.refreshToken) {
+      // Ohne Refresh-Token kein Server-Sync — Consent muss offline_access
+      // (bzw. access_type=offline) anfordern; der Provider-oauth-Block
+      // besitzt die Scopes.
+      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`,
+      );
+    }
+
+    // Account anlegen (programmatic SystemUser; echter Owner kommt aus
+    // dem HMAC-verifizierten state → ownerUserIdOverride).
+    const dispatched = await deps.dispatchWrite({
+      handlerQn: InboundMailFoundationHandlers.connectAccount,
+      tenantId: state.tenantId,
+      payload: {
+        provider: state.providerKey,
+        authMethod: InboundMailAuthMethods.oauth,
+        displayName: state.mailbox,
+        address: state.mailbox,
+        scope: state.ownerUserId ? "user" : "shared",
+        ownerUserIdOverride: state.ownerUserId,
+      },
+    });
+    if (!dispatched.isSuccess) {
+      return errorJson(c, 502, "account_create_failed", JSON.stringify(dispatched.error ?? {}));
+    }
+    const accountId = (dispatched.data as { accountId?: unknown } | undefined)?.accountId;
+    if (typeof accountId !== "string") {
+      return errorJson(c, 502, "account_create_failed", "connect-account returned no accountId");
+    }
+
+    // Refresh-Token in den per-Account-Secret-Slot (Request-Pfad =
+    // voller SecretsContext). Access-Tokens (~1h) werden NIE persistiert
+    // — refresh-before-poll im Sync-Pfad.
+    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}`,
+      },
+    );
+
+    if (deps.successRedirectUrl) {
+      const target = new URL(deps.successRedirectUrl);
+      target.searchParams.set("accountId", accountId);
+      return c.redirect(target.toString(), 302);
+    }
+    return c.json({ connected: true, accountId }, 200);
+  };
+
+  return { connect, callback };
+}
+
+export type InboundMailConnectRoutes = ReturnType<typeof createInboundMailConnectRoutes>;