@cosmicdrift/kumiko-samples 0.392.2 → 0.394.0

package/packages/bundled-features/src/inbound-mail-foundation/handlers/reactivate-account.write.ts

@@ -0,0 +1,129 @@
+// reactivate-account — the only way from disconnected back to active (it also clears auth_error
+// and degraded). update-account keeps rejecting disconnected accounts so a late supervisor tick
+// can never undo a disconnect; a deliberate reconnect goes through here instead, keeping the
+// accountId and with it cursor, seen anchors and threads.
+
+import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import {
+  type HandlerContext,
+  SYSTEM_ROLE,
+  SYSTEM_USER_ID,
+  type WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  AccessDeniedError,
+  failNotFound,
+  UnprocessableError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import {
+  InboundMailAccountStatuses,
+  InboundMailConnectErrors,
+  InboundMailFoundationHandlers,
+  inboundCredentialSecretKey,
+} from "../constants.ts";
+import {
+  MAIL_ACCOUNT_AGGREGATE_TYPE,
+  MAIL_ACCOUNT_UPDATED_EVENT_QN,
+  type MailAccountEventHeaders,
+  type MailAccountEventPayload,
+} from "../events.ts";
+import { accessRolesOf, type InboundMailRoles } from "../mail-roles.ts";
+import { loadCurrentMailAccountPayload } from "./account-state.ts";
+import { mayReactivateMailbox } from "./scope-visibility.ts";
+
+export const RECONNECT_AUDIT_REASON = "reconnect";
+
+// Strict: the trusted authserv-id only changes through set-trusted-authserv-id.
+export const reactivateAccountSchema = z.object({ accountId: z.uuid() }).strict();
+
+const CREDENTIAL_PRESENCE_REASON =
+  "the credential secret is checked on the request transaction because reconnect-mailbox writes it earlier in the same transaction, which a separate connection would not see";
+
+// The OAuth callback re-arms a personal mailbox for its owner after the owner signed in: the signed
+// state carries the owner, the dispatcher only sees the system user.
+function isSystemActor(user: { readonly id: string; readonly roles: readonly string[] }): boolean {
+  return user.id === SYSTEM_USER_ID && user.roles.includes(SYSTEM_ROLE);
+}
+
+function isAlreadyHealthy(current: MailAccountEventPayload): boolean {
+  return (
+    current.status === InboundMailAccountStatuses.active &&
+    current.watchState === "idle" &&
+    current.lastError === null
+  );
+}
+
+// Returns false when nothing had to change.
+async function appendMailAccountReactivation(
+  ctx: Pick<HandlerContext, "events">,
+  accountId: string,
+  current: MailAccountEventPayload,
+): Promise<boolean> {
+  if (isAlreadyHealthy(current)) return false;
+  const eventPayload: MailAccountEventPayload = {
+    ...current,
+    status: InboundMailAccountStatuses.active,
+    watchState: "idle",
+    lastError: null,
+  };
+  const headers: MailAccountEventHeaders = {
+    providerName: current.provider,
+    reason: RECONNECT_AUDIT_REASON,
+  };
+  await ctx.events.unsafeAppend({
+    aggregateId: accountId,
+    aggregateType: MAIL_ACCOUNT_AGGREGATE_TYPE,
+    type: MAIL_ACCOUNT_UPDATED_EVENT_QN,
+    payload: eventPayload,
+    headers,
+  });
+  return true;
+}
+
+export function createReactivateAccountHandler({
+  memberRoles,
+  adminRoles,
+}: InboundMailRoles): WriteHandlerDef {
+  return {
+    name: "reactivate-account",
+    schema: reactivateAccountSchema,
+    // Members: the owner re-arms a personal mailbox; mayReactivateMailbox keeps shared ones to admins.
+    access: { roles: accessRolesOf(InboundMailFoundationHandlers.reactivateAccount, memberRoles) },
+    agent: { expose: false },
+    escapeHatch: { grants: ["unsafeRaw"], reason: CREDENTIAL_PRESENCE_REASON },
+    description:
+      "Brings a disconnected, interrupted or sign-in-failed mailbox back to active under its existing accountId, so cursor, seen messages and threads survive; the caller replaces the credential in the same flow.",
+    handler: async (event, ctx) => {
+      const payload = reactivateAccountSchema.parse(event.payload);
+      const current = await loadCurrentMailAccountPayload(ctx, payload.accountId);
+      if (!current) return failNotFound("mail-account", payload.accountId);
+      if (
+        !isSystemActor(event.user) &&
+        !mayReactivateMailbox(current.ownerUserId, event.user, adminRoles)
+      ) {
+        return writeFailure(new AccessDeniedError({ details: { reason: "not_mailbox_owner" } }));
+      }
+      // Nothing to re-arm, so no credential is needed either.
+      if (isAlreadyHealthy(current)) {
+        return { isSuccess: true as const, data: { accountId: payload.accountId, changed: false } };
+      }
+      // Every other starting state: without a credential the supervisor would only fail again.
+      const secrets = requireSecretsContext(
+        { secrets: ctx.services.secrets, user: ctx.user },
+        "reactivate-account",
+      ).withRunner(ctx.db.unsafeRaw());
+      const hasCredential = await secrets.has(
+        event.user.tenantId,
+        inboundCredentialSecretKey(payload.accountId),
+      );
+      if (!hasCredential) {
+        const { reason, i18nKey } = InboundMailConnectErrors.credentialRequired;
+        return writeFailure(new UnprocessableError(reason, { i18nKey }));
+      }
+      const changed = await appendMailAccountReactivation(ctx, payload.accountId, current);
+      return { isSuccess: true as const, data: { accountId: payload.accountId, changed } };
+    },
+  };
+}

package/packages/bundled-features/src/inbound-mail-foundation/handlers/retry-quarantined-message.write.ts

@@ -0,0 +1,49 @@
+// retry-quarantined-message — marks one quarantined mail for a reload. The next successful sync of
+// the mailbox fetches it again and, when it now goes through, removes the quarantine row
+// (quarantine-retry.ts). The handler only flags; the supervisor owns the provider connection.
+
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  AccessDeniedError,
+  failNotFound,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import * as z from "zod";
+import type { InboundMailRoles } from "../mail-roles.ts";
+import { quarantineTable } from "../quarantine-entities.ts";
+import { loadCurrentMailAccountPayload } from "./account-state.ts";
+import { mayManageQuarantine } from "./scope-visibility.ts";
+
+export const retryQuarantinedMessageSchema = z
+  .object({ accountId: z.uuid(), providerMessageId: z.string().min(1).max(500) })
+  .strict();
+
+export function createRetryQuarantinedMessageHandler({
+  memberRoles,
+  adminRoles,
+}: InboundMailRoles): WriteHandlerDef {
+  return {
+    name: "retry-quarantined-message",
+    schema: retryQuarantinedMessageSchema,
+    access: { roles: [...memberRoles] },
+    agent: { expose: false },
+    description:
+      "Asks for a quarantined mail to be loaded again from the provider on the next sync of its mailbox; the owner of a personal mailbox or, for a shared one, an admin may call it, and the quarantine entry disappears once the mail went through.",
+    handler: async (event, ctx) => {
+      const payload = retryQuarantinedMessageSchema.parse(event.payload);
+      const account = await loadCurrentMailAccountPayload(ctx, payload.accountId);
+      if (!account) return failNotFound("mail-account", payload.accountId);
+      if (!mayManageQuarantine(account.ownerUserId, event.user, adminRoles)) {
+        return writeFailure(new AccessDeniedError({ details: { reason: "not_mailbox_owner" } }));
+      }
+      const updated = await ctx.db.updateMany(
+        quarantineTable,
+        { retryRequestedAt: Temporal.Now.instant().toString() },
+        { accountId: payload.accountId, providerMessageId: payload.providerMessageId },
+      );
+      if (updated.length === 0) return failNotFound("mail-quarantine", payload.providerMessageId);
+      return { isSuccess: true as const, data: { requested: true as const } };
+    },
+  };
+}

package/packages/bundled-features/src/inbound-mail-foundation/handlers/scope-visibility.ts

@@ -1,13 +1,52 @@
-// Scope visibility: shared rows (`ownerUserId=null`) are visible to any authorized caller;
-// personal rows are visible only to the owner, `TenantAdmin`, or `SystemAdmin` for compliance.
-// The same rule applies to `read_mail_accounts` and `read_inbound_messages`.
+// Scope visibility: shared rows (`ownerUserId=null`) are visible to any authorized caller.
+// A personal mailbox is private to its owner: its messages, bodies, attachments and quarantine are
+// never shown to admins, who see only the operational metadata of the account (address, status).
 
-export function isVisibleToCaller(
+type Caller = { readonly id: string; readonly roles: readonly string[] };
+
+function isShared(ownerUserId: unknown): boolean {
+  return ownerUserId == null || ownerUserId === "";
+}
+
+export function isVisibleToCaller(row: Readonly<Record<string, unknown>>, user: Caller): boolean {
+  const owner = row["ownerUserId"];
+  return isShared(owner) || owner === user.id;
+}
+
+export function isMailAdmin(
+  user: { readonly roles: readonly string[] },
+  adminRoles: readonly string[],
+): boolean {
+  return adminRoles.some((role) => user.roles.includes(role));
+}
+
+// Account metadata (not content) of a personal mailbox stays visible to admins for operations.
+export function isAccountListableBy(
   row: Readonly<Record<string, unknown>>,
-  user: { readonly id: string; readonly roles: readonly string[] },
+  user: Caller,
+  adminRoles: readonly string[],
 ): boolean {
-  const owner = row["ownerUserId"];
-  if (owner == null || owner === "") return true;
-  if (owner === user.id) return true;
-  return user.roles.includes("TenantAdmin") || user.roles.includes("SystemAdmin");
+  return isVisibleToCaller(row, user) || isMailAdmin(user, adminRoles);
+}
+
+// A personal mailbox is re-armed (and its sender check changed) by its owner only: a reconnect
+// re-reads the owner's mail with whatever credential the caller supplies, so an admin must not do
+// it. A shared mailbox belongs to the tenant: admins only.
+export function mayReactivateMailbox(
+  ownerUserId: unknown,
+  user: Caller,
+  adminRoles: readonly string[],
+): boolean {
+  if (isShared(ownerUserId)) return isMailAdmin(user, adminRoles);
+  return ownerUserId === user.id;
+}
+
+// Quarantine entries carry sender and subject of the mail, so those of a personal mailbox are the
+// owner's alone; shared mailboxes are administered by admins.
+export function mayManageQuarantine(
+  ownerUserId: string | null,
+  user: Caller,
+  adminRoles: readonly string[],
+): boolean {
+  return isShared(ownerUserId) ? isMailAdmin(user, adminRoles) : ownerUserId === user.id;
 }

package/packages/bundled-features/src/inbound-mail-foundation/handlers/set-trusted-authserv-id.write.ts

@@ -0,0 +1,66 @@
+// set-trusted-authserv-id — the one place that changes which Authentication-Results header the
+// sender check believes. It is separate from connect/update/reactivate on purpose: a payload that
+// can smuggle this value in through a generic update would let any caller mark forged headers as
+// trusted, and it must never be a model-callable tool.
+
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { InboundMailAccountStatuses } from "../constants.ts";
+import {
+  MAIL_ACCOUNT_AGGREGATE_TYPE,
+  MAIL_ACCOUNT_UPDATED_EVENT_QN,
+  type MailAccountEventHeaders,
+  type MailAccountEventPayload,
+} from "../events.ts";
+import type { InboundMailRoles } from "../mail-roles.ts";
+import { normalizeTrustedAuthservId } from "../sender-auth.ts";
+import { loadCurrentMailAccountPayload } from "./account-state.ts";
+import { trustedAuthservIdInputSchema } from "./trusted-authserv-id.ts";
+import { auditReasonFor } from "./update-account.write.ts";
+
+export const setTrustedAuthservIdSchema = z
+  .object({
+    accountId: z.uuid(),
+    trustedAuthservId: trustedAuthservIdInputSchema,
+  })
+  .strict();
+
+export const createSetTrustedAuthservIdHandler = ({ adminRoles }: InboundMailRoles) =>
+  defineWriteHandler({
+    name: "set-trusted-authserv-id",
+    schema: setTrustedAuthservIdSchema,
+    // A tenant security policy, personal mailboxes included: a trusted authserv-id makes forged senders
+    // count as authenticated for the whole tenant (contact matching, auto replies), so owners never set it.
+    access: { roles: [...adminRoles] },
+    agent: { expose: false },
+    description:
+      "Sets or clears the authserv-id of the mailbox's own server, which decides whose Authentication-Results header the sender check trusts; null or empty clears it, a connected mailbox only.",
+    handler: async (event, ctx) => {
+      const payload = event.payload;
+      const current = await loadCurrentMailAccountPayload(ctx, payload.accountId);
+      if (!current) return failNotFound("mail-account", payload.accountId);
+      if (current.status === InboundMailAccountStatuses.disconnected) {
+        return failUnprocessable("account_disconnected", { accountId: payload.accountId });
+      }
+
+      const trustedAuthservId = normalizeTrustedAuthservId(payload.trustedAuthservId);
+      if (current.trustedAuthservId === trustedAuthservId) {
+        return { isSuccess: true as const, data: { accountId: payload.accountId, changed: false } };
+      }
+
+      const eventPayload: MailAccountEventPayload = { ...current, trustedAuthservId };
+      const headers: MailAccountEventHeaders = {
+        providerName: current.provider,
+        reason: auditReasonFor(event.user, undefined),
+      };
+      await ctx.events.unsafeAppend({
+        aggregateId: payload.accountId,
+        aggregateType: MAIL_ACCOUNT_AGGREGATE_TYPE,
+        type: MAIL_ACCOUNT_UPDATED_EVENT_QN,
+        payload: eventPayload,
+        headers,
+      });
+      return { isSuccess: true as const, data: { accountId: payload.accountId, changed: true } };
+    },
+  });

package/packages/bundled-features/src/inbound-mail-foundation/handlers/thread-rollup.ts

@@ -0,0 +1,136 @@
+import {
+  type configuredPiiSubjectKms,
+  encryptPiiFieldValues,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import { acquireNamespacedAdvisoryLock, countWhere } from "@cosmicdrift/kumiko-framework/db";
+import type { HandlerContext, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { MAIL_THREAD_PII_FIELDS, mailThreadEntity } from "../entities.ts";
+import {
+  type InboundMessageEventHeaders,
+  MAIL_THREAD_AGGREGATE_TYPE,
+  MAIL_THREAD_UPDATED_EVENT_QN,
+  type MailThreadEventPayload,
+} from "../events.ts";
+import { inboundMessagesProjectionTable } from "../projection.ts";
+import type { IngestMessagePayload } from "./ingest-message-schema.ts";
+
+const THREAD_ROLLUP_MAX_ATTEMPTS = 5;
+// pg_advisory_xact_lock namespace (int4) for the step-5 thread-rollup lock
+// — 'inbm' as ASCII, keeps it disjoint from the framework's other fixed
+// single-int advisory-lock keys (schema bootstrap, es-ops boot).
+const THREAD_ROLLUP_LOCK_NAMESPACE = 0x696e626d;
+
+/**
+ * Normalizes threadKey:
+ *   1. Use the provider thread ID when present — prefix it with the provider
+ *      so IMAP References keys and Graph conversationIds never collide.
+ *   2. Otherwise use the root of the References chain (the oldest Message-ID,
+ *      which is the thread anchor shared by all replies).
+ *   3. Otherwise use the own Message-ID → single-message thread; a later
+ *      reply carries it as the References root and joins the same thread.
+ */
+export function buildThreadKey(p: IngestMessagePayload, effectiveMessageIdHeader: string): string {
+  if (p.providerThreadId) return `${p.providerName}:${p.providerThreadId}`.slice(0, 500);
+  const referencesRoot = p.references[0];
+  if (referencesRoot) return `mid:${referencesRoot}`.slice(0, 500);
+  return `mid:${effectiveMessageIdHeader}`.slice(0, 500);
+}
+
+export type ThreadRollupInput = {
+  readonly tenantId: TenantId;
+  readonly threadAggId: string;
+  readonly threadKey: string;
+  readonly subject: string;
+  readonly receivedAtIso: string;
+  readonly headers: InboundMessageEventHeaders;
+  readonly piiKms: ReturnType<typeof configuredPiiSubjectKms>;
+};
+
+// ---------------------------------------------------------------
+// 5. Thread-Rollup. New snapshot (live COUNT + max(lastMessageAt)) via
+//    ctx.events.tryAppend in a bounded retry loop — the apply stays a
+//    dumb, replay-idempotent UPSERT. lastMessageAtIso is not PII (a
+//    timestamp), so it stays plaintext-comparable; subject is
+//    encrypted once up front (constant across retries, doesn't
+//    depend on the thread's prior state).
+//
+//    messageCount is a live COUNT, not previousCount+1, so two
+//    concurrent ingests on the same thread (Watch-Push vs.
+//    Poll-Reconciliation overlap, or two different messages of the
+//    same thread arriving at once) converge on the true count.
+//    acquireNamespacedAdvisoryLock below serializes this whole
+//    countWhere+append section per threadAggId — transaction-scoped,
+//    so it survives events.tryAppend's inner SAVEPOINT and releases at
+//    the enclosing TX's commit/rollback. Without it, a concurrent
+//    commit landing between countWhere and events.tryAppend's own fresh
+//    version-read makes the append succeed with a stale count instead
+//    of a VersionConflictError, so the retry loop below never sees it
+//    as a conflict to retry (the original gap). Unlike step 4, a
+//    lost version-conflict race here must NOT be treated as a no-op
+//    duplicate — skipping would leave this message's contribution to
+//    messageCount/lastMessageAt out of the thread forever. Exhausting
+//    all attempts throws, rolling back the whole TX (including the
+//    step-4 message append) for a clean re-ingest.
+// ---------------------------------------------------------------
+export async function appendThreadRollup(
+  ctx: HandlerContext,
+  input: ThreadRollupInput,
+): Promise<void> {
+  const { tenantId, threadAggId, threadKey, subject, receivedAtIso, headers, piiKms } = input;
+  const threadPlainPii = { tenantId, subject: subject };
+  const encryptedThreadFields = piiKms
+    ? await encryptPiiFieldValues(
+        threadPlainPii,
+        mailThreadEntity,
+        MAIL_THREAD_PII_FIELDS,
+        piiKms,
+        {
+          requestId: `inbound-mail-foundation:ingest-message:thread:${threadAggId}`,
+          tenantId,
+        },
+        { tenantId, entityName: MAIL_THREAD_AGGREGATE_TYPE },
+      )
+    : threadPlainPii;
+
+  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++) {
+    const threadEvents = await ctx.events.load(threadAggId);
+    const lastThreadEvent = threadEvents[threadEvents.length - 1];
+    // @cast-boundary engine-payload — eigene events, shape via defineEvent
+    const previousThread = lastThreadEvent?.payload as MailThreadEventPayload | undefined;
+    const previousLastAt = previousThread?.lastMessageAtIso ?? "";
+    const newLastAt = receivedAtIso > previousLastAt ? receivedAtIso : previousLastAt;
+    const messageCount = await countWhere(threadRollupRunner, inboundMessagesProjectionTable, {
+      tenantId,
+      threadKey,
+    });
+
+    const threadEventPayload: MailThreadEventPayload = {
+      threadKey,
+      subject: encryptedThreadFields.subject,
+      lastMessageAtIso: newLastAt,
+      messageCount,
+    };
+    const threadAppend = await ctx.events.tryAppend({
+      aggregateId: threadAggId,
+      aggregateType: MAIL_THREAD_AGGREGATE_TYPE,
+      type: MAIL_THREAD_UPDATED_EVENT_QN,
+      payload: threadEventPayload,
+      headers,
+    });
+    threadAppendOk = threadAppend.ok;
+  }
+  if (!threadAppendOk) {
+    throw new InternalError({
+      message: `ingest-message: thread-rollup append for "${threadAggId}" lost the version-conflict race ${THREAD_ROLLUP_MAX_ATTEMPTS} times in a row — aborting for a clean re-ingest instead of persisting a stale messageCount.`,
+    });
+  }
+}

package/packages/bundled-features/src/inbound-mail-foundation/handlers/trusted-authserv-id.ts

@@ -0,0 +1,4 @@
+import * as z from "zod";
+
+/** authserv-id of the mailbox's own server, set only through set-trusted-authserv-id; null or empty clears it. */
+export const trustedAuthservIdInputSchema = z.string().trim().max(255).nullable();

package/packages/bundled-features/src/inbound-mail-foundation/handlers/update-account.write.ts

@@ -11,82 +11,104 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
-import { InboundMailAccountStatuses } from "../constants.ts";
+import {
+  InboundMailAccountStatuses,
+  InboundMailFoundationHandlers,
+  InboundMailLastErrors,
+} from "../constants.ts";
 import {
   MAIL_ACCOUNT_AGGREGATE_TYPE,
   MAIL_ACCOUNT_UPDATED_EVENT_QN,
   type MailAccountEventHeaders,
   type MailAccountEventPayload,
 } from "../events.ts";
+import { accessRolesOf, type InboundMailRoles } from "../mail-roles.ts";
 import { loadCurrentMailAccountPayload } from "./account-state.ts";
 
-export const updateAccountSchema = z.object({
-  accountId: z.uuid(),
-  status: z
-    .enum([
-      InboundMailAccountStatuses.active,
-      InboundMailAccountStatuses.authError,
-      InboundMailAccountStatuses.degraded,
-    ])
-    .optional(),
-  /** Ops-Signal ("idle", "watching", "backoff:3", ...). */
-  watchState: z.string().max(100).optional(),
-  displayName: z.string().max(200).optional(),
-  /** Audit reason for metadata.headers, honored for the system identity only
-   *  ("watch_supervisor", "oauth_refresh"); user callers get a role-derived reason. */
-  reason: z.string().min(1).max(100).optional(),
-});
+export const updateAccountSchema = z
+  .object({
+    accountId: z.uuid(),
+    status: z
+      .enum([
+        InboundMailAccountStatuses.active,
+        InboundMailAccountStatuses.authError,
+        InboundMailAccountStatuses.degraded,
+      ])
+      .optional(),
+    /** Why the mailbox is degraded; null clears it. Codes only, never provider error text. */
+    lastError: z.enum(Object.values(InboundMailLastErrors)).nullable().optional(),
+    /** Ops-Signal ("idle", "watching", "backoff:3", ...). */
+    watchState: z.string().max(100).optional(),
+    displayName: z.string().trim().max(200).optional(),
+    /** Audit reason for metadata.headers, honored for the system identity only
+     *  ("watch_supervisor", "oauth_refresh"); user callers get a role-derived reason. */
+    reason: z.string().min(1).max(100).optional(),
+  })
+  .strict();
 type UpdateAccountPayload = z.infer<typeof updateAccountSchema>;
 
 const SYSTEM_FALLBACK_REASON = "system";
 
-function auditReasonFor(user: SessionUser, requestedReason: string | undefined): string {
+export function auditReasonFor(user: SessionUser, requestedReason: string | undefined): string {
   if (user.id === SYSTEM_USER_ID) return requestedReason ?? SYSTEM_FALLBACK_REASON;
   return user.roles.includes(ROLES.SystemAdmin) ? "system_admin" : "tenant_admin";
 }
 
-export const updateAccountHandler: WriteHandlerDef = {
-  name: "update-account",
-  schema: updateAccountSchema,
-  access: { roles: ["SystemAdmin", "TenantAdmin"] },
-  description:
-    "Records a status, watch-state or display-name change on a connected mailbox as a new snapshot with an audit reason, rejecting any change to an already disconnected mailbox; use it to flag an auth error or to re-activate a mailbox after fixing its credentials.",
-  handler: async (event, ctx) => {
-    // @cast-boundary engine-payload — dispatcher-zod-validated payload
-    const payload = event.payload as UpdateAccountPayload;
+export function createUpdateAccountHandler({ adminRoles }: InboundMailRoles): WriteHandlerDef {
+  return {
+    name: "update-account",
+    schema: updateAccountSchema,
+    access: { roles: accessRolesOf(InboundMailFoundationHandlers.updateAccount, adminRoles) },
+    description:
+      "Renames a connected mailbox (display name) as a new snapshot with an audit reason, rejecting any change to an already disconnected mailbox; status, error and watch state are reserved for the system identity.",
+    handler: async (event, ctx) => {
+      // @cast-boundary engine-payload — dispatcher-zod-validated payload
+      const payload = event.payload as UpdateAccountPayload;
+
+      // Status, error and watch state are machine signals of the supervisor and the OAuth refresh; an admin
+      // setting them could hide an auth error or fake an active mailbox.
+      const isSystemOnlyField =
+        payload.status !== undefined ||
+        payload.lastError !== undefined ||
+        payload.watchState !== undefined ||
+        payload.reason !== undefined;
+      if (isSystemOnlyField && event.user.id !== SYSTEM_USER_ID) {
+        return failUnprocessable("field_requires_system_identity");
+      }
 
-    const current = await loadCurrentMailAccountPayload(ctx, payload.accountId);
-    if (!current) {
-      return failNotFound("mail-account", payload.accountId);
-    }
-    if (current.status === InboundMailAccountStatuses.disconnected) {
-      // Disconnected accounts are final; re-enabling requires a fresh connect
-      // (new stream, new secret slot). This prevents a delayed supervisor tick
-      // from restoring a disconnected account to active (disconnect vs. poll
-      // race).
-      return failUnprocessable("account_disconnected", { accountId: payload.accountId });
-    }
+      const current = await loadCurrentMailAccountPayload(ctx, payload.accountId);
+      if (!current) {
+        return failNotFound("mail-account", payload.accountId);
+      }
+      if (current.status === InboundMailAccountStatuses.disconnected) {
+        // Only reactivate-account may leave disconnected. This prevents a delayed
+        // supervisor tick from restoring a disconnected account to active
+        // (disconnect vs. poll race).
+        return failUnprocessable("account_disconnected", { accountId: payload.accountId });
+      }
 
-    // address/provider/authMethod come unchanged from the latest snapshot
-    // (address remains ciphertext—never re-encrypt it).
-    const eventPayload: MailAccountEventPayload = {
-      ...current,
-      ...(payload.status !== undefined ? { status: payload.status } : {}),
-      ...(payload.watchState !== undefined ? { watchState: payload.watchState } : {}),
-      ...(payload.displayName !== undefined ? { displayName: payload.displayName } : {}),
-    };
-    const headers: MailAccountEventHeaders = {
-      providerName: current.provider,
-      reason: auditReasonFor(event.user, payload.reason),
-    };
-    await ctx.events.unsafeAppend({
-      aggregateId: payload.accountId,
-      aggregateType: MAIL_ACCOUNT_AGGREGATE_TYPE,
-      type: MAIL_ACCOUNT_UPDATED_EVENT_QN,
-      payload: eventPayload,
-      headers,
-    });
+      // address/provider/authMethod come unchanged from the latest snapshot
+      // (address remains ciphertext—never re-encrypt it).
+      const eventPayload: MailAccountEventPayload = {
+        ...current,
+        ...(payload.status !== undefined ? { status: payload.status } : {}),
+        ...(payload.watchState !== undefined ? { watchState: payload.watchState } : {}),
+        ...(payload.displayName !== undefined ? { displayName: payload.displayName } : {}),
+        ...(payload.lastError !== undefined ? { lastError: payload.lastError } : {}),
+      };
+      const headers: MailAccountEventHeaders = {
+        providerName: current.provider,
+        reason: auditReasonFor(event.user, payload.reason),
+      };
+      await ctx.events.unsafeAppend({
+        aggregateId: payload.accountId,
+        aggregateType: MAIL_ACCOUNT_AGGREGATE_TYPE,
+        type: MAIL_ACCOUNT_UPDATED_EVENT_QN,
+        payload: eventPayload,
+        headers,
+      });
 
-    return { isSuccess: true as const, data: { accountId: payload.accountId } };
-  },
-};
+      return { isSuccess: true as const, data: { accountId: payload.accountId } };
+    },
+  };
+}