@cosmicdrift/kumiko-samples 0.390.1 → 0.391.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.390.1",
+  "version": "0.391.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.390.1",
+  "version": "0.391.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/src/audit/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.391.0",
+    "type": "improvement",
+    "title": "The audit log leaves readiness probe runs to SystemAdmins",
+    "detail": "A probe run's events carry system-probe and personal-mailbox results. audit:query:list and audit:query:details now leave the probe-run stream out for every caller below SystemAdmin, also when the caller filters by that aggregate type."
+  },
   {
     "version": "0.388.0",
     "type": "fix",

package/packages/bundled-features/src/audit/event-classification.ts

@@ -65,6 +65,11 @@ export const AUDIT_EVENT_STANCES: Readonly<Record<string, AuditEventStance>> = {
   "feature-toggles:event:toggle-set": label("feature-toggle-set"),
 };
 
+// Streams whose payload holds rows that only a SystemAdmin or a single owner may read: a
+// readiness probe run stores system-probe and personal-mailbox results next to the tenant's
+// own. Below SystemAdmin the audit log leaves these streams out entirely.
+export const SYSTEM_ADMIN_ONLY_AGGREGATE_TYPES: readonly string[] = ["probe-run"];
+
 // Framework system events (kumiko:system:*) are engine plumbing, never audit-worthy on their own.
 export const FRAMEWORK_SYSTEM_EVENT_TYPES: readonly string[] = [
   ...WORKFLOW_SYSTEM_EVENT_DEFS.keys(),

package/packages/bundled-features/src/audit/handlers/audit-events.ts

@@ -92,8 +92,18 @@ export type AuditListFilters = {
   cursor?: string | undefined;
   before?: string | undefined;
   includeTechnical?: boolean | undefined;
+  hiddenAggregateTypes?: readonly string[] | undefined;
 };
 
+/** The aggregateType condition: the requested type, minus the streams hidden from the caller. */
+export function aggregateTypeCondition(
+  aggregateType: string | undefined,
+  hidden: readonly string[] | undefined,
+): unknown {
+  if (hidden === undefined) return aggregateType;
+  return { ...(aggregateType !== undefined && { in: [aggregateType] }), notIn: hidden };
+}
+
 /** `tenantCondition` is a tenant id, or an operator object for reads across tenants. */
 export function buildAuditWhere(
   tenantCondition: unknown,
@@ -101,7 +111,11 @@ export function buildAuditWhere(
   direction: "asc" | "desc",
 ): WhereObject {
   const where: WhereObject = { tenantId: tenantCondition };
-  if (p.aggregateType) where["aggregateType"] = p.aggregateType;
+  const aggregateType = aggregateTypeCondition(
+    p.aggregateType || undefined,
+    p.hiddenAggregateTypes,
+  );
+  if (aggregateType !== undefined) where["aggregateType"] = aggregateType;
   if (p.aggregateId) where["aggregateId"] = p.aggregateId;
   if (p.eventType) where["type"] = p.eventType;
   else if (p.search || !p.includeTechnical) {

package/packages/bundled-features/src/audit/handlers/details.query.ts

@@ -6,7 +6,12 @@
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { AUDIT_SCOPE_VALUES } from "../web/constants.ts";
-import { auditEventIdSchema, createEntityNounKeyResolver, loadAuditEvent } from "./audit-events.ts";
+import {
+  aggregateTypeCondition,
+  auditEventIdSchema,
+  createEntityNounKeyResolver,
+  loadAuditEvent,
+} from "./audit-events.ts";
 import { requireAuditSystemDb } from "./audit-system-db.ts";
 import { resolveAuditScopeFilter } from "./resolve-audit-tenant.ts";
 
@@ -24,13 +29,15 @@ export const detailsQuery = defineQueryHandler({
     const db = requireAuditSystemDb(ctx.systemDb, "audit:query:details").assertTenantMatch(
       query.user.tenantId,
     );
+    const aggregateType = aggregateTypeCondition(
+      scopeFilter.aggregateType,
+      scopeFilter.hiddenAggregateTypes,
+    );
     return loadAuditEvent(
       db,
       {
         tenantId: scopeFilter.tenantId,
-        ...(scopeFilter.aggregateType !== undefined && {
-          aggregateType: scopeFilter.aggregateType,
-        }),
+        ...(aggregateType !== undefined && { aggregateType }),
         id: BigInt(query.payload.id),
       },
       createEntityNounKeyResolver(ctx.registry),

package/packages/bundled-features/src/audit/handlers/list.query.ts

@@ -45,6 +45,7 @@ export const listQuery = defineQueryHandler({
       {
         ...p,
         aggregateType: scopeFilter.aggregateType ?? p.aggregateType,
+        hiddenAggregateTypes: scopeFilter.hiddenAggregateTypes,
         includeTechnical: includesTechnicalEntries(p.filters),
       },
       direction,

package/packages/bundled-features/src/audit/handlers/resolve-audit-tenant.ts

@@ -2,9 +2,14 @@ import { mayOverrideTenant, type SessionUser } from "@cosmicdrift/kumiko-framewo
 import { AccessDeniedError, FrameworkReasons } from "@cosmicdrift/kumiko-framework/errors";
 import { APP_INSTANCE_STREAM_TYPE } from "@cosmicdrift/kumiko-framework/event-store";
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-types/identifiers";
+import { SYSTEM_ADMIN_ONLY_AGGREGATE_TYPES } from "../event-classification.ts";
 import { type AuditScope, AuditScopes } from "../web/constants.ts";
 
-export type AuditScopeFilter = { readonly tenantId: string; readonly aggregateType?: string };
+export type AuditScopeFilter = {
+  readonly tenantId: string;
+  readonly aggregateType?: string;
+  readonly hiddenAggregateTypes?: readonly string[];
+};
 
 function denySystemAdminOnlyRead(): never {
   throw new AccessDeniedError({
@@ -19,7 +24,11 @@ export function resolveAuditScopeFilter(
   user: SessionUser,
   scope: AuditScope | undefined,
 ): AuditScopeFilter {
-  if (scope !== AuditScopes.system) return { tenantId: user.tenantId };
+  if (scope !== AuditScopes.system) {
+    return mayOverrideTenant(user)
+      ? { tenantId: user.tenantId }
+      : { tenantId: user.tenantId, hiddenAggregateTypes: SYSTEM_ADMIN_ONLY_AGGREGATE_TYPES };
+  }
   if (!mayOverrideTenant(user)) denySystemAdminOnlyRead();
   return { tenantId: SYSTEM_TENANT_ID, aggregateType: APP_INSTANCE_STREAM_TYPE };
 }

package/packages/bundled-features/src/auth-mfa/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.391.0",
+    "type": "fix",
+    "title": "The disable-MFA form confirms success",
+    "detail": "After a successful disable the auth-mfa-disable screen shows \"Two-factor authentication is now turned off.\" and clears the spent code. Before, the form looked unchanged. New key mfa.disable.done in all locale packages."
+  },
   {
     "version": "0.389.0",
     "type": "improvement",

package/packages/bundled-features/src/auth-mfa/i18n.ts

@@ -35,6 +35,7 @@ export const AUTH_MFA_FEATURE_I18N: Readonly<Record<string, LocalizedString>> =
 
   "screen:auth-mfa-disable.title": { en: "Disable two-factor authentication" },
   "mfa.disable.submit": { en: "Disable" },
+  "mfa.disable.done": { en: "Two-factor authentication is now turned off." },
 
   "screen:auth-mfa-regenerate-recovery.title": { en: "Generate new recovery codes" },
   "mfa.regenerate.submit": { en: "Generate new codes" },

package/packages/bundled-features/src/auth-mfa/screens.ts

@@ -86,6 +86,9 @@ export const mfaDisableScreen: ActionFormScreenDefinition = {
   layout: { sections: [{ fields: ["code"] }] },
   submitLabel: i18nKey("mfa.disable.submit"),
   submitStyle: "danger",
+  successMessage: i18nKey("mfa.disable.done"),
+  // The used code is spent; clearing it keeps the form from looking like it still waits.
+  resetOnSuccess: true,
   cancelTarget: false,
   access: {
     openToAll: {

package/packages/bundled-features/src/file-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.391.0",
+    "type": "improvement",
+    "title": "File-storage probe",
+    "detail": "file-foundation registers a probe that writes, reads and deletes a probe object in the configured storage provider."
+  },
   {
     "version": "0.370.0",
     "type": "breaking",

package/packages/bundled-features/src/file-foundation/feature.ts

@@ -35,6 +35,9 @@ export {
   isFileProviderPlugin,
 } from "@cosmicdrift/kumiko-framework/files";
 
+import { FILE_FOUNDATION_I18N } from "./i18n.ts";
+import { registerStorageProbe } from "./probe.ts";
+
 const FEATURE_NAME = "file-foundation";
 
 export function createFileFoundationFeature() {
@@ -71,6 +74,9 @@ export function createFileFoundationFeature() {
       // while their plugin is the one this key selects.
       r.extensionSelector(EXT_FILE_PROVIDER, providerConfigKey);
 
+      r.translations({ keys: FILE_FOUNDATION_I18N });
+      registerStorageProbe(r);
+
       return { providerConfigKey };
     },
     { dedupeOptions: {} },

package/packages/bundled-features/src/file-foundation/i18n.ts

@@ -0,0 +1,13 @@
+export const FILE_PROBE_KEYS = {
+  area: "file-foundation.probe.area",
+  label: "file-foundation.probe.storage-roundtrip.label",
+  reachable: "file-foundation.probe.storage-roundtrip.reachable",
+  notConfigured: "file-foundation.probe.not-configured",
+} as const;
+
+export const FILE_FOUNDATION_I18N = {
+  [FILE_PROBE_KEYS.area]: { en: "File storage" },
+  [FILE_PROBE_KEYS.label]: { en: "Write, read and delete a test file" },
+  [FILE_PROBE_KEYS.reachable]: { en: "Storage reachable" },
+  [FILE_PROBE_KEYS.notConfigured]: { en: "No file storage set up" },
+} as const;

package/packages/bundled-features/src/file-foundation/index.ts

@@ -15,3 +15,7 @@ export {
   fileContextFromResolver,
   readFileRefContent,
 } from "./read-file-ref-content.ts";
+export {
+  makeTenantStorageProviderResolver,
+  type TenantStorageResolverCtx,
+} from "./storage-provider-resolver.ts";

package/packages/bundled-features/src/file-foundation/probe.ts

@@ -0,0 +1,68 @@
+import {
+  createSystemUser,
+  type FeatureRegistrar,
+  FILE_PROVIDER_CONFIG_KEY,
+  FILE_STORAGE_PROVIDER_BOOT_SENTINEL,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createConfigAccessor } from "../config/index.ts";
+import { FILE_PROBE_KEYS } from "./i18n.ts";
+import { makeTenantStorageProviderResolver } from "./storage-provider-resolver.ts";
+
+const PROBE_CONTENT = new TextEncoder().encode("kumiko-readiness-probe");
+
+function isSameBytes(left: Uint8Array, right: Uint8Array): boolean {
+  return left.length === right.length && left.every((byte, index) => byte === right[index]);
+}
+
+// Bypasses the file-ref entity on purpose: a probe leaves neither a ref nor events behind.
+export function registerStorageProbe(r: FeatureRegistrar<"file-foundation">): void {
+  r.probe({
+    name: "storage-roundtrip",
+    scope: "tenant",
+    cost: "free",
+    area: FILE_PROBE_KEYS.area,
+    label: FILE_PROBE_KEYS.label,
+    run: async (ctx) => {
+      const { configResolver, secrets } = ctx.services;
+      const userId = createSystemUser(ctx.tenantId).id;
+      const notConfigured = {
+        status: "skipped",
+        message: { key: FILE_PROBE_KEYS.notConfigured },
+      } as const;
+      if (!configResolver) return notConfigured;
+      const selected = await createConfigAccessor(
+        ctx.registry,
+        configResolver,
+        ctx.tenantId,
+        userId,
+        ctx.db,
+      )(FILE_PROVIDER_CONFIG_KEY);
+      if (
+        selected === undefined ||
+        selected === "" ||
+        selected === FILE_STORAGE_PROVIDER_BOOT_SENTINEL
+      ) {
+        return notConfigured;
+      }
+
+      const provider = await makeTenantStorageProviderResolver({
+        registry: ctx.registry,
+        configResolver,
+        secrets,
+        db: ctx.db,
+        userId,
+        handlerName: "file-foundation:probe",
+      })(ctx.tenantId);
+      const key = `${ctx.tenantId}/__readiness-probe/${ctx.probeRunId}.txt`;
+      try {
+        await provider.write(key, PROBE_CONTENT, "text/plain");
+        if (!isSameBytes(await provider.read(key), PROBE_CONTENT)) {
+          throw new Error("storage returned different bytes than were written");
+        }
+      } finally {
+        await provider.delete(key);
+      }
+      return { status: "ok", message: { key: FILE_PROBE_KEYS.reachable } };
+    },
+  });
+}

package/packages/bundled-features/src/{user-data-rights/lib → file-foundation}/storage-provider-resolver.ts

@@ -8,9 +8,9 @@ import type { DbConnection, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { ConfigResolver, Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import type { FileStorageProvider } from "@cosmicdrift/kumiko-framework/files";
+import { createFileProviderForTenant } from "@cosmicdrift/kumiko-framework/files";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
-import { createConfigAccessor } from "../../config/index.ts";
-import { createFileProviderForTenant } from "../../file-foundation/index.ts";
+import { createConfigAccessor } from "../config/index.ts";
 
 export interface TenantStorageResolverCtx {
   readonly registry: Registry;

package/packages/bundled-features/src/inbound-mail-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.391.0",
+    "type": "improvement",
+    "title": "Inbound-mailbox probes",
+    "detail": "inbound-mail-foundation registers a probe with one result per configured mailbox. A personal mailbox is probed only when its owner starts the run, and only its owner sees the result."
+  },
   {
     "version": "0.388.0",
     "type": "fix",

package/packages/bundled-features/src/inbound-mail-foundation/feature.ts

@@ -80,6 +80,7 @@ import { listAccountsQuery } from "./handlers/list-accounts.query.ts";
 import { listMessagesQuery } from "./handlers/list-messages.query.ts";
 import { updateAccountHandler } from "./handlers/update-account.write.ts";
 import { INBOUND_MAIL_FOUNDATION_I18N } from "./i18n.ts";
+import { registerMailboxProbe } from "./probe.ts";
 import {
   applyInboundMessageReceived,
   applyMailAccountConnected,
@@ -203,6 +204,7 @@ export function createInboundMailFoundationFeature() {
       r.screen(mailAccountListScreen);
       r.screen(mailAccountEditScreen);
       r.translations({ keys: INBOUND_MAIL_FOUNDATION_I18N });
+      registerMailboxProbe(r);
 
       // Entity-specific GDPR destroy hooks — the gdpr-storage boot validator
       // checks the EXT_TENANT_DATA registration for each tenant-subject entity.

package/packages/bundled-features/src/inbound-mail-foundation/i18n.ts

@@ -1,6 +1,7 @@
 import { ACTION_FORM_ENTITY } from "@cosmicdrift/kumiko-framework/ui-types";
 import { fieldLabelKey } from "@cosmicdrift/kumiko-renderer/headless";
 import { INBOUND_MAIL_FOUNDATION_FEATURE, InboundMailAccountStatuses } from "./constants.ts";
+import { INBOUND_PROBE_I18N } from "./probe-keys.ts";
 import {
   MAIL_ACCOUNT_EDIT_SCREEN_ID,
   MAIL_ACCOUNT_LIST_SCREEN_ID,
@@ -11,6 +12,7 @@ const formFieldKey = (field: string): string =>
   fieldLabelKey(INBOUND_MAIL_FOUNDATION_FEATURE, ACTION_FORM_ENTITY, field);
 
 export const INBOUND_MAIL_FOUNDATION_I18N: Readonly<Record<string, { readonly en: string }>> = {
+  ...INBOUND_PROBE_I18N,
   [`screen:${MAIL_ACCOUNT_LIST_SCREEN_ID}.title`]: { en: "Mailboxes" },
   [`screen:${MAIL_ACCOUNT_EDIT_SCREEN_ID}.title`]: { en: "Edit mailbox" },
   "inboundMail.accounts.col.name": { en: "Name" },

package/packages/bundled-features/src/inbound-mail-foundation/probe-keys.ts

@@ -0,0 +1,17 @@
+export const INBOUND_PROBE_KEYS = {
+  area: "inbound-mail-foundation.probe.area",
+  label: "inbound-mail-foundation.probe.mailboxes.label",
+  mailbox: "inbound-mail-foundation.probe.mailbox",
+  reachable: "inbound-mail-foundation.probe.mailbox.reachable",
+  authFailed: "inbound-mail-foundation.probe.mailbox.auth-failed",
+  gone: "inbound-mail-foundation.probe.mailbox.gone",
+} as const;
+
+export const INBOUND_PROBE_I18N = {
+  [INBOUND_PROBE_KEYS.area]: { en: "Inbound email" },
+  [INBOUND_PROBE_KEYS.label]: { en: "Connected mailboxes" },
+  [INBOUND_PROBE_KEYS.mailbox]: { en: "Mailbox {name}" },
+  [INBOUND_PROBE_KEYS.reachable]: { en: "Mailbox reachable" },
+  [INBOUND_PROBE_KEYS.authFailed]: { en: "The mailbox rejected the stored login" },
+  [INBOUND_PROBE_KEYS.gone]: { en: "Mailbox no longer exists" },
+} as const;

package/packages/bundled-features/src/inbound-mail-foundation/probe.ts

@@ -0,0 +1,109 @@
+import {
+  configuredPiiSubjectKms,
+  decryptPiiFieldValues,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import {
+  createSystemUser,
+  type FeatureRegistrar,
+  type ProbeContext,
+  ProbeFailure,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createConfigAccessor } from "../config/index.ts";
+import { INBOUND_MAIL_FOUNDATION_FEATURE, InboundMailAccountStatuses } from "./constants.ts";
+import { MAIL_ACCOUNT_PII_FIELDS } from "./entities.ts";
+import { INBOUND_PROBE_KEYS } from "./probe-keys.ts";
+import { mailAccountsProjectionTable } from "./projection.ts";
+import { resolveInboundProviderForAccount } from "./provider-factory.ts";
+import { type InboundMailContext, isInboundAuthError, type MailAccountRecord } from "./types.ts";
+
+const SHORT_ID_LENGTH = 8;
+
+type AccountRow = {
+  readonly id: string;
+  readonly tenantId: string;
+  readonly provider: string;
+  readonly authMethod: string;
+  readonly ownerUserId?: string | null;
+  readonly address: string;
+  readonly displayName?: string | null;
+  readonly watchState?: string | null;
+};
+
+function providerContext(ctx: ProbeContext): InboundMailContext {
+  const { configResolver, secrets } = ctx.services;
+  const auditUserId = createSystemUser(ctx.tenantId).id;
+  return {
+    registry: ctx.registry,
+    ...(secrets && { secrets }),
+    auditUserId,
+    ...(configResolver && {
+      config: createConfigAccessor(ctx.registry, configResolver, ctx.tenantId, auditUserId, ctx.db),
+    }),
+  };
+}
+
+// Providers never see ciphertext, so the address is decrypted before the call.
+async function toAccountRecord(row: AccountRow, tenantId: string): Promise<MailAccountRecord> {
+  const piiKms = configuredPiiSubjectKms();
+  const decrypted = piiKms
+    ? await decryptPiiFieldValues(row, MAIL_ACCOUNT_PII_FIELDS, piiKms, {
+        requestId: "inbound-mail-foundation:probe",
+      })
+    : row;
+  const address = decrypted["address"];
+  if (typeof address !== "string") throw new Error("mailbox address did not decrypt to text");
+  return {
+    id: row.id,
+    tenantId,
+    provider: row.provider,
+    authMethod: row.authMethod,
+    ownerUserId: row.ownerUserId ?? null,
+    address,
+    displayName: row.displayName ?? "",
+    status: InboundMailAccountStatuses.active,
+    watchState: row.watchState ?? "idle",
+  };
+}
+
+export function registerMailboxProbe(r: FeatureRegistrar<"inbound-mail-foundation">): void {
+  r.probe({
+    name: "mailboxes",
+    scope: "tenant",
+    cost: "free",
+    area: INBOUND_PROBE_KEYS.area,
+    label: INBOUND_PROBE_KEYS.label,
+    fixScreen: `${INBOUND_MAIL_FOUNDATION_FEATURE}:screen:mail-accounts`,
+    // The address is PII, so the target label carries only the tenant-authored display name.
+    targets: async (ctx) => {
+      const rows = await ctx.db.selectMany<AccountRow>(mailAccountsProjectionTable, {
+        status: InboundMailAccountStatuses.active,
+      });
+      return rows.map((row) => ({
+        id: row.id,
+        label: {
+          key: INBOUND_PROBE_KEYS.mailbox,
+          params: { name: row.displayName || row.id.slice(0, SHORT_ID_LENGTH) },
+        },
+        ...(row.ownerUserId != null && { ownerUserId: row.ownerUserId }),
+      }));
+    },
+    run: async (ctx, target) => {
+      const row = target
+        ? await ctx.db.fetchOne<AccountRow>(mailAccountsProjectionTable, { id: target.id })
+        : undefined;
+      if (!row) return { status: "skipped", message: { key: INBOUND_PROBE_KEYS.gone } };
+      const account = await toAccountRecord(row, ctx.tenantId);
+      const providerCtx = providerContext(ctx);
+      const plugin = resolveInboundProviderForAccount(providerCtx, account);
+      try {
+        await (plugin.probe ?? plugin.verify)(providerCtx, account);
+      } catch (error) {
+        if (isInboundAuthError(error)) {
+          throw new ProbeFailure({ key: INBOUND_PROBE_KEYS.authFailed });
+        }
+        throw error;
+      }
+      return { status: "ok", message: { key: INBOUND_PROBE_KEYS.reachable } };
+    },
+  });
+}

package/packages/bundled-features/src/inbound-mail-foundation/types.ts

@@ -159,6 +159,9 @@ export type InboundMailProviderPlugin = {
   /** Credential/reachability check during the connect flow — throws a
    *  typed error (InboundAuthError, etc.) and returns no value. */
   readonly verify: (ctx: InboundMailContext, account: MailAccountRecord) => Promise<void>;
+  /** Read-only liveness check for the system check; falls back to `verify`. Must not
+   *  change mailbox state (no flags, no new connection side effects). */
+  readonly probe?: (ctx: InboundMailContext, account: MailAccountRecord) => Promise<void>;
   /** Fetch since cursor. `cursor === null` means initial population,
    *  limited by backfillWindowDays. */
   readonly fetch: (

package/packages/bundled-features/src/inbound-provider-imap/feature.ts

@@ -43,6 +43,7 @@ import { type ImapCredentialDocument, parseImapCredentialDocument } from "./cred
 import {
   assertUidValidity,
   coerceDate,
+  connectOnce,
   createImapClient,
   IMAP_MAILBOX,
   imapMailHostGuard,
@@ -259,17 +260,8 @@ async function watchMailbox(
 /** Exported for the live test (imap-live.integration.test.ts) —
  *  applications use the feature, never the plugin directly. */
 export const imapInboundMailPlugin: InboundMailProviderPlugin = {
-  verify: async (ctx, account) => {
-    const doc = await readCredentialDocument(ctx, account);
-    const client = await createImapClient(doc, imapMailHostGuard());
-    try {
-      await client.connect();
-    } catch (err) {
-      throw mapImapError(err, doc.host);
-    } finally {
-      await client.logout().catch(() => {});
-    }
-  },
+  verify: async (ctx, account) => connectOnce(await readCredentialDocument(ctx, account), false),
+  probe: async (ctx, account) => connectOnce(await readCredentialDocument(ctx, account), true),
   fetch: fetchMessages,
   watch: watchMailbox,
   // No oauth block: password authentication runs through the credential

package/packages/bundled-features/src/inbound-provider-imap/imap-client.ts

@@ -94,6 +94,22 @@ export async function createImapClient(
 }
 
 /** Server-Fehler → typisierte Foundation-Fehlerklassen (Plan §2). */
+// examineInbox opens INBOX with EXAMINE instead of SELECT, so the system check never touches \Recent or flags.
+export async function connectOnce(
+  doc: ImapCredentialDocument,
+  examineInbox: boolean,
+): Promise<void> {
+  const client = await createImapClient(doc, imapMailHostGuard());
+  try {
+    await client.connect();
+    if (examineInbox) await client.mailboxOpen(IMAP_MAILBOX, { readOnly: true });
+  } catch (err) {
+    throw mapImapError(err, doc.host);
+  } finally {
+    await client.logout().catch(() => {});
+  }
+}
+
 export function mapImapError(err: unknown, host: string): Error {
   // imapflow errors carry the server response in responseText; the
   // message is only "Command failed", so both are included in the match;

package/packages/bundled-features/src/mail-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.391.0",
+    "type": "improvement",
+    "title": "Mail-sending probe",
+    "detail": "mail-foundation registers a probe that sends a short test mail through the tenant's mail transport to the user who started the check. The address is not stored in the result. A failed row names the reason (server not found, settings incomplete, mail not accepted) and links to the email sending settings; the raw error stays in the server log."
+  },
   {
     "version": "0.388.0",
     "type": "fix",

package/packages/bundled-features/src/mail-foundation/feature.ts

@@ -45,6 +45,7 @@ import {
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { MAIL_FOUNDATION_I18N } from "./i18n.ts";
+import { registerMailProbe } from "./probe.ts";
 
 const FEATURE_NAME = "mail-foundation";
 
@@ -173,6 +174,7 @@ export function createMailFoundationFeature() {
       r.extensionSelector(MAIL_TRANSPORT_EXTENSION, providerConfigKey);
 
       r.translations({ keys: MAIL_FOUNDATION_I18N });
+      registerMailProbe(r);
 
       return {
         /** Config-key-handle for the provider-selector. */

package/packages/bundled-features/src/mail-foundation/i18n.ts

@@ -1,3 +1,15 @@
+export const MAIL_PROBE_KEYS = {
+  area: "mail-foundation.probe.area",
+  label: "mail-foundation.probe.send-test-mail.label",
+  accepted: "mail-foundation.probe.send-test-mail.accepted",
+  notConfigured: "mail-foundation.probe.not-configured",
+  noRecipient: "mail-foundation.probe.no-recipient",
+  hostNotFound: "mail-foundation.probe.host-not-found",
+  setupIncomplete: "mail-foundation.probe.setup-incomplete",
+  setupFailed: "mail-foundation.probe.setup-failed",
+  sendRejected: "mail-foundation.probe.send-rejected",
+} as const;
+
 export const MAIL_FOUNDATION_I18N = {
   "screen:mail-foundation-tenant.title": { en: "Email sending" },
   "mail-foundation.settings": { en: "Email sending" },
@@ -6,4 +18,19 @@ export const MAIL_FOUNDATION_I18N = {
     en: "Choose who sends your emails. The platform default needs no settings of your own.",
   },
   "mail-foundation.provider.platformDefault": { en: "Platform sending (default)" },
+  [MAIL_PROBE_KEYS.area]: { en: "Email" },
+  [MAIL_PROBE_KEYS.label]: { en: "Test email to the person who started the check" },
+  [MAIL_PROBE_KEYS.accepted]: { en: "Accepted by the mail server" },
+  [MAIL_PROBE_KEYS.notConfigured]: { en: "No own email sending set up" },
+  [MAIL_PROBE_KEYS.noRecipient]: {
+    en: "No email address known for the person who started the check",
+  },
+  [MAIL_PROBE_KEYS.hostNotFound]: { en: "Mail server not found, check the server address" },
+  [MAIL_PROBE_KEYS.setupIncomplete]: {
+    en: "Email sending settings are incomplete or the server is not allowed",
+  },
+  [MAIL_PROBE_KEYS.setupFailed]: { en: "Email sending could not be set up with these settings" },
+  [MAIL_PROBE_KEYS.sendRejected]: {
+    en: "The mail server did not accept the test email, check address, port and login",
+  },
 } as const;

package/packages/bundled-features/src/mail-foundation/index.ts

@@ -18,3 +18,7 @@ export {
   type TenantMailTransportScope,
   tenantMailTransport,
 } from "./feature.ts";
+export {
+  makeTenantMailTransportResolver,
+  type TenantMailResolverCtx,
+} from "./mail-transport-resolver.ts";

package/packages/bundled-features/src/{user-data-rights/lib → mail-foundation}/mail-transport-resolver.ts

@@ -7,11 +7,11 @@
 // in the worker lane (the prod-bug class the file-provider resolver already fixed).
 
 import type { EmailTransport } from "@cosmicdrift/kumiko-bundled-features/channel-email";
-import { createTransportForTenant } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { ConfigResolver, Registry } from "@cosmicdrift/kumiko-framework/engine";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
-import { createConfigAccessor } from "../../config/index.ts";
+import { createConfigAccessor } from "../config/index.ts";
+import { createTransportForTenant } from "./feature.ts";
 
 export interface TenantMailResolverCtx {
   readonly registry: Registry;