@cosmicdrift/kumiko-bundled-features 0.392.2 → 0.394.0

package/dist/inbound-mail-foundation/handlers/reactivate-account.write.d.ts

@@ -0,0 +1,8 @@
+import { type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { type InboundMailRoles } from "../mail-roles.ts";
+export declare const RECONNECT_AUDIT_REASON = "reconnect";
+export declare const reactivateAccountSchema: z.ZodObject<{
+    accountId: z.ZodUUID;
+}, z.core.$strict>;
+export declare function createReactivateAccountHandler({ memberRoles, adminRoles, }: InboundMailRoles): WriteHandlerDef;

package/dist/inbound-mail-foundation/handlers/reactivate-account.write.js

@@ -0,0 +1,84 @@
+// 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 { SYSTEM_ROLE, SYSTEM_USER_ID, } 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.js";
+import { MAIL_ACCOUNT_AGGREGATE_TYPE, MAIL_ACCOUNT_UPDATED_EVENT_QN, } from "../events.js";
+import { accessRolesOf } from "../mail-roles.js";
+import { loadCurrentMailAccountPayload } from "./account-state.js";
+import { mayReactivateMailbox } from "./scope-visibility.js";
+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) {
+    return user.id === SYSTEM_USER_ID && user.roles.includes(SYSTEM_ROLE);
+}
+function isAlreadyHealthy(current) {
+    return (current.status === InboundMailAccountStatuses.active &&
+        current.watchState === "idle" &&
+        current.lastError === null);
+}
+// Returns false when nothing had to change.
+async function appendMailAccountReactivation(ctx, accountId, current) {
+    if (isAlreadyHealthy(current))
+        return false;
+    const eventPayload = {
+        ...current,
+        status: InboundMailAccountStatuses.active,
+        watchState: "idle",
+        lastError: null,
+    };
+    const headers = {
+        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, }) {
+    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, 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, data: { accountId: payload.accountId, changed } };
+        },
+    };
+}

package/dist/inbound-mail-foundation/handlers/retry-quarantined-message.write.d.ts

@@ -0,0 +1,8 @@
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import type { InboundMailRoles } from "../mail-roles.ts";
+export declare const retryQuarantinedMessageSchema: z.ZodObject<{
+    accountId: z.ZodUUID;
+    providerMessageId: z.ZodString;
+}, z.core.$strict>;
+export declare function createRetryQuarantinedMessageHandler({ memberRoles, adminRoles, }: InboundMailRoles): WriteHandlerDef;

package/dist/inbound-mail-foundation/handlers/retry-quarantined-message.write.js

@@ -0,0 +1,34 @@
+// 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 { AccessDeniedError, failNotFound, writeFailure, } from "@cosmicdrift/kumiko-framework/errors";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import * as z from "zod";
+import { quarantineTable } from "../quarantine-entities.js";
+import { loadCurrentMailAccountPayload } from "./account-state.js";
+import { mayManageQuarantine } from "./scope-visibility.js";
+export const retryQuarantinedMessageSchema = z
+    .object({ accountId: z.uuid(), providerMessageId: z.string().min(1).max(500) })
+    .strict();
+export function createRetryQuarantinedMessageHandler({ memberRoles, adminRoles, }) {
+    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, data: { requested: true } };
+        },
+    };
+}

package/dist/inbound-mail-foundation/handlers/scope-visibility.d.ts

@@ -1,4 +1,12 @@
-export declare function isVisibleToCaller(row: Readonly<Record<string, unknown>>, user: {
+type Caller = {
     readonly id: string;
     readonly roles: readonly string[];
-}): boolean;
+};
+export declare function isVisibleToCaller(row: Readonly<Record<string, unknown>>, user: Caller): boolean;
+export declare function isMailAdmin(user: {
+    readonly roles: readonly string[];
+}, adminRoles: readonly string[]): boolean;
+export declare function isAccountListableBy(row: Readonly<Record<string, unknown>>, user: Caller, adminRoles: readonly string[]): boolean;
+export declare function mayReactivateMailbox(ownerUserId: unknown, user: Caller, adminRoles: readonly string[]): boolean;
+export declare function mayManageQuarantine(ownerUserId: string | null, user: Caller, adminRoles: readonly string[]): boolean;
+export {};

package/dist/inbound-mail-foundation/handlers/scope-visibility.js

@@ -1,11 +1,30 @@
-// 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).
+function isShared(ownerUserId) {
+    return ownerUserId == null || ownerUserId === "";
+}
 export function isVisibleToCaller(row, user) {
     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 isShared(owner) || owner === user.id;
+}
+export function isMailAdmin(user, adminRoles) {
+    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, user, adminRoles) {
+    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, user, adminRoles) {
+    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, user, adminRoles) {
+    return isShared(ownerUserId) ? isMailAdmin(user, adminRoles) : ownerUserId === user.id;
 }

package/dist/inbound-mail-foundation/handlers/set-trusted-authserv-id.write.d.ts

@@ -0,0 +1,13 @@
+import * as z from "zod";
+import type { InboundMailRoles } from "../mail-roles.ts";
+export declare const setTrustedAuthservIdSchema: z.ZodObject<{
+    accountId: z.ZodUUID;
+    trustedAuthservId: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const createSetTrustedAuthservIdHandler: ({ adminRoles }: InboundMailRoles) => import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"set-trusted-authserv-id", z.ZodObject<{
+    accountId: z.ZodUUID;
+    trustedAuthservId: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>, {
+    accountId: string;
+    changed: boolean;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined, undefined>;

package/dist/inbound-mail-foundation/handlers/set-trusted-authserv-id.write.js

@@ -0,0 +1,54 @@
+// 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.js";
+import { MAIL_ACCOUNT_AGGREGATE_TYPE, MAIL_ACCOUNT_UPDATED_EVENT_QN, } from "../events.js";
+import { normalizeTrustedAuthservId } from "../sender-auth.js";
+import { loadCurrentMailAccountPayload } from "./account-state.js";
+import { trustedAuthservIdInputSchema } from "./trusted-authserv-id.js";
+import { auditReasonFor } from "./update-account.write.js";
+export const setTrustedAuthservIdSchema = z
+    .object({
+    accountId: z.uuid(),
+    trustedAuthservId: trustedAuthservIdInputSchema,
+})
+    .strict();
+export const createSetTrustedAuthservIdHandler = ({ adminRoles }) => 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, data: { accountId: payload.accountId, changed: false } };
+        }
+        const eventPayload = { ...current, trustedAuthservId };
+        const headers = {
+            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, data: { accountId: payload.accountId, changed: true } };
+    },
+});

package/dist/inbound-mail-foundation/handlers/thread-rollup.d.ts

@@ -0,0 +1,24 @@
+import { type configuredPiiSubjectKms } from "@cosmicdrift/kumiko-framework/crypto";
+import type { HandlerContext, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { type InboundMessageEventHeaders } from "../events.ts";
+import type { IngestMessagePayload } from "./ingest-message-schema.ts";
+/**
+ * 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 declare function buildThreadKey(p: IngestMessagePayload, effectiveMessageIdHeader: string): string;
+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>;
+};
+export declare function appendThreadRollup(ctx: HandlerContext, input: ThreadRollupInput): Promise<void>;

package/dist/inbound-mail-foundation/handlers/thread-rollup.js

@@ -0,0 +1,98 @@
+import { encryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
+import { acquireNamespacedAdvisoryLock, countWhere } from "@cosmicdrift/kumiko-framework/db";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { MAIL_THREAD_PII_FIELDS, mailThreadEntity } from "../entities.js";
+import { MAIL_THREAD_AGGREGATE_TYPE, MAIL_THREAD_UPDATED_EVENT_QN, } from "../events.js";
+import { inboundMessagesProjectionTable } from "../projection.js";
+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, effectiveMessageIdHeader) {
+    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);
+}
+// ---------------------------------------------------------------
+// 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, input) {
+    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;
+        const previousLastAt = previousThread?.lastMessageAtIso ?? "";
+        const newLastAt = receivedAtIso > previousLastAt ? receivedAtIso : previousLastAt;
+        const messageCount = await countWhere(threadRollupRunner, inboundMessagesProjectionTable, {
+            tenantId,
+            threadKey,
+        });
+        const threadEventPayload = {
+            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/dist/inbound-mail-foundation/handlers/trusted-authserv-id.d.ts

@@ -0,0 +1,3 @@
+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 declare const trustedAuthservIdInputSchema: z.ZodNullable<z.ZodString>;

package/dist/inbound-mail-foundation/handlers/trusted-authserv-id.js

@@ -0,0 +1,3 @@
+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/dist/inbound-mail-foundation/handlers/update-account.write.d.ts

@@ -1,5 +1,6 @@
-import { type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { type SessionUser, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import { type InboundMailRoles } from "../mail-roles.ts";
 export declare const updateAccountSchema: z.ZodObject<{
     accountId: z.ZodUUID;
     status: z.ZodOptional<z.ZodEnum<{
@@ -7,8 +8,17 @@ export declare const updateAccountSchema: z.ZodObject<{
         auth_error: "auth_error";
         degraded: "degraded";
     }>>;
+    lastError: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        connection_failed: "connection_failed";
+        encryption_unavailable: "encryption_unavailable";
+        file_storage_unavailable: "file_storage_unavailable";
+        ingest_unavailable: "ingest_unavailable";
+        message_quarantined: "message_quarantined";
+        rate_limited: "rate_limited";
+    }>>>;
     watchState: z.ZodOptional<z.ZodString>;
     displayName: z.ZodOptional<z.ZodString>;
     reason: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export declare const updateAccountHandler: WriteHandlerDef;
+}, z.core.$strict>;
+export declare function auditReasonFor(user: SessionUser, requestedReason: string | undefined): string;
+export declare function createUpdateAccountHandler({ adminRoles }: InboundMailRoles): WriteHandlerDef;

package/dist/inbound-mail-foundation/handlers/update-account.write.js

@@ -6,10 +6,12 @@ import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
 import { SYSTEM_USER_ID, } from "@cosmicdrift/kumiko-framework/engine";
 import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
-import { InboundMailAccountStatuses } from "../constants.js";
+import { InboundMailAccountStatuses, InboundMailFoundationHandlers, InboundMailLastErrors, } from "../constants.js";
 import { MAIL_ACCOUNT_AGGREGATE_TYPE, MAIL_ACCOUNT_UPDATED_EVENT_QN, } from "../events.js";
+import { accessRolesOf } from "../mail-roles.js";
 import { loadCurrentMailAccountPayload } from "./account-state.js";
-export const updateAccountSchema = z.object({
+export const updateAccountSchema = z
+    .object({
     accountId: z.uuid(),
     status: z
         .enum([
@@ -18,57 +20,71 @@ export const updateAccountSchema = z.object({
         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().max(200).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();
 const SYSTEM_FALLBACK_REASON = "system";
-function auditReasonFor(user, requestedReason) {
+export function auditReasonFor(user, requestedReason) {
     if (user.id === SYSTEM_USER_ID)
         return requestedReason ?? SYSTEM_FALLBACK_REASON;
     return user.roles.includes(ROLES.SystemAdmin) ? "system_admin" : "tenant_admin";
 }
-export const updateAccountHandler = {
-    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;
-        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 });
-        }
-        // address/provider/authMethod come unchanged from the latest snapshot
-        // (address remains ciphertext—never re-encrypt it).
-        const eventPayload = {
-            ...current,
-            ...(payload.status !== undefined ? { status: payload.status } : {}),
-            ...(payload.watchState !== undefined ? { watchState: payload.watchState } : {}),
-            ...(payload.displayName !== undefined ? { displayName: payload.displayName } : {}),
-        };
-        const headers = {
-            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, data: { accountId: payload.accountId } };
-    },
-};
+export function createUpdateAccountHandler({ adminRoles }) {
+    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;
+            // 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) {
+                // 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 = {
+                ...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 = {
+                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, data: { accountId: payload.accountId } };
+        },
+    };
+}