@wildo-ai/saas-models 1.1.4 → 1.1.6

package/dist/esm/notifications/inbound-email/inbound-email.shared.schemas.js

@@ -0,0 +1,530 @@
+/**
+ * Receiving email (#1600) — the email channel's own records.
+ *
+ * #1630 built the channel mechanism (handlers, sender assurance, threads, replies). This file holds what
+ * only EMAIL has: where a message is addressed, the domains an organization receives and sends on, the
+ * mailboxes a firm keeps for its clients, and the message itself as it was received.
+ *
+ * | resource | scope | one row per | what it is for |
+ * |---|---|---|---|
+ * | `inboundEmails` | organization | message routed to that organization | the channel record: bodies, headers, attachments, raw MIME, and the message's disposition |
+ * | `organizationEmailDomains` | organization | domain the organization claimed | proving ownership, provisioning it at the provider, receiving and sending on it |
+ * | `clientMailboxes` | organization (the CLIENT) | address on a firm's domain | mail to `acme@inbox.firm.com` lands in the client organization, where the case lives |
+ * | `inboundAddressTombstones` | application | slug of a deleted organization | a reused slug never receives an old organization's mail |
+ *
+ * ## Addresses, and the order they are tried in (fail closed)
+ *
+ * {@link InboundRouteKind}: a reply token first (it names a thread, and its organization must be the one the
+ * address reaches), then an exact client mailbox, then a verified organization domain, then the shared
+ * domain's `{slug}` address. Anything else is UNROUTABLE and audited. The SENDER never decides where a
+ * message goes: a `From` domain is spoofable, and routing on it would let anyone write into any tenant.
+ *
+ * ## One state per row
+ *
+ * `inboundEmails.status` is the MESSAGE's disposition. Whether its handler ran is the inbound delivery's
+ * status (#1596) — there is no second "processed" state here, and no "quarantined" one anywhere: a message
+ * below its handler's minimum is `STORED_BELOW_MINIMUM`, an infected attachment is listed in
+ * `withheldAttachments`.
+ */
+import { z } from 'zod';
+import { addImpersonalizeWith, z_file } from '@wildo-ai/zod-decorators';
+import { PersonalDataCategory } from '../../compliance/privacy/personal-data-category.shared.schemas.js';
+import { RedactionType } from '../../compliance/privacy/redaction.shared.schemas.js';
+import { InboundSenderAssurance } from '../../inbound/inbound-channels.shared.schemas.js';
+/** @wildo_source:part:start saas.models.inbound-email facet:layer:shared facet:family:inbound facet:audience:app-developer */
+/**
+ * What became of a received message. The message's disposition only; the handler's run is the delivery's.
+ */
+export var InboundEmailStatus;
+(function (InboundEmailStatus) {
+    /** Stored; at least one attachment has no scan verdict yet. Nothing reaches a handler before every one has one. */
+    InboundEmailStatus["AWAITING_ATTACHMENT_SCAN"] = "awaiting_attachment_scan";
+    /** Handed to its channel handler through a stored delivery. */
+    InboundEmailStatus["DISPATCHED"] = "dispatched";
+    /**
+     * The sender is below the selected handler's minimum assurance and no below-minimum handler is declared.
+     * Kept — it is correspondence — audited, and dispatched to nobody. Who sees it is the application's choice.
+     */
+    InboundEmailStatus["STORED_BELOW_MINIMUM"] = "stored_below_minimum";
+    /** Over a limit (see {@link InboundEmailLimit}). Only the envelope is kept: no bodies, no attachments. */
+    InboundEmailStatus["REJECTED_LIMIT"] = "rejected_limit";
+})(InboundEmailStatus || (InboundEmailStatus = {}));
+/** How an address reached its organization, in the order routing tries them. */
+export var InboundRouteKind;
+(function (InboundRouteKind) {
+    /** `{local}+r-{token}@{domain}` — a reply to a thread. The token's organization must be the routed one. */
+    InboundRouteKind["REPLY_TOKEN"] = "reply_token";
+    /** An exact client mailbox on a firm's verified domain, under an ACTIVE service-provider relationship. */
+    InboundRouteKind["CLIENT_MAILBOX"] = "client_mailbox";
+    /** Any address on a VERIFIED receiving domain of the organization; `local+tag` passes `tag`. */
+    InboundRouteKind["ORGANIZATION_DOMAIN"] = "organization_domain";
+    /** `{slug}[+tag]@{sharedDomain}` — the zero-configuration default every organization has. */
+    InboundRouteKind["SHARED_DOMAIN"] = "shared_domain";
+})(InboundRouteKind || (InboundRouteKind = {}));
+/** Where an organization's claimed domain stands. Only VERIFIED routes and sends. */
+export var OrganizationEmailDomainStatus;
+(function (OrganizationEmailDomainStatus) {
+    /** Claimed; the DNS TXT ownership challenge is not answered yet. Blocks nobody — several organizations may be here at once. */
+    OrganizationEmailDomainStatus["OWNERSHIP_PENDING"] = "ownership_pending";
+    /** Ownership proven, the domain exists at the provider, and its DNS records are not verified there yet. */
+    OrganizationEmailDomainStatus["PROVIDER_PENDING"] = "provider_pending";
+    /** Ownership proven and the provider verified its records: the domain routes (receiving) and sends (sending). */
+    OrganizationEmailDomainStatus["VERIFIED"] = "verified";
+    /** The provider could not verify the records. Fix the DNS and verify again. */
+    OrganizationEmailDomainStatus["FAILED"] = "failed";
+    /** Was verified; the ownership record or the provider's records disappeared. Routing and sending stop. */
+    OrganizationEmailDomainStatus["SUSPENDED"] = "suspended";
+})(OrganizationEmailDomainStatus || (OrganizationEmailDomainStatus = {}));
+/**
+ * Whether an organization's verified SENDING domain is used beyond thread replies. Applies application-wide.
+ * The default keeps the application's own sender on every message the application did not route through a thread.
+ */
+export var OrganizationSendingDomainUse;
+(function (OrganizationSendingDomainUse) {
+    /** Only replies on a thread go out from the organization's domain. */
+    OrganizationSendingDomainUse["THREAD_REPLIES"] = "thread_replies";
+    /** Every email sent on behalf of the organization goes out from its verified sending domain. */
+    OrganizationSendingDomainUse["ALL_ORGANIZATION_MAIL"] = "all_organization_mail";
+})(OrganizationSendingDomainUse || (OrganizationSendingDomainUse = {}));
+/**
+ * Whether the original bytes of a received message are kept. Default `KEEP`: DKIM verifies over the original
+ * bytes only (RFC 6376 §3.7), so parsed text can never be re-verified, and commercial law asks for received
+ * letters to be reproducible as received.
+ *
+ * spec-cite: RFC 6376 §3.7 (the body hash and signature are computed over the canonicalized ORIGINAL message).
+ */
+export var InboundEmailRawRetention;
+(function (InboundEmailRawRetention) {
+    InboundEmailRawRetention["KEEP"] = "keep";
+    InboundEmailRawRetention["DISCARD"] = "discard";
+})(InboundEmailRawRetention || (InboundEmailRawRetention = {}));
+/** Which limit a `REJECTED_LIMIT` message exceeded. */
+export var InboundEmailLimit;
+(function (InboundEmailLimit) {
+    /** The whole message is larger than the application's configured maximum. */
+    InboundEmailLimit["MESSAGE_SIZE"] = "message_size";
+    /** More attachments than {@link INBOUND_EMAIL_MAX_ATTACHMENTS}. */
+    InboundEmailLimit["ATTACHMENT_COUNT"] = "attachment_count";
+    /** One attachment is larger than the application's maximum file size. */
+    InboundEmailLimit["ATTACHMENT_SIZE"] = "attachment_size";
+})(InboundEmailLimit || (InboundEmailLimit = {}));
+/** Why an attachment was not made available to the handler. The message itself still reaches it. */
+export var InboundEmailWithheldReason;
+(function (InboundEmailWithheldReason) {
+    /** The scanner found malware. The file is quarantined and never served. */
+    InboundEmailWithheldReason["INFECTED"] = "infected";
+    /** The scan could not run or did not conclude. Not proven clean, so not exposed. */
+    InboundEmailWithheldReason["SCAN_FAILED"] = "scan_failed";
+})(InboundEmailWithheldReason || (InboundEmailWithheldReason = {}));
+/** Why a verified domain stopped routing and sending. */
+export var OrganizationEmailDomainSuspensionReason;
+(function (OrganizationEmailDomainSuspensionReason) {
+    /** The organization's ownership TXT record is no longer published. */
+    OrganizationEmailDomainSuspensionReason["OWNERSHIP_RECORD_MISSING"] = "ownership_record_missing";
+    /** The provider no longer finds the domain's records (or the domain itself). */
+    OrganizationEmailDomainSuspensionReason["PROVIDER_RECORDS_MISSING"] = "provider_records_missing";
+})(OrganizationEmailDomainSuspensionReason || (OrganizationEmailDomainSuspensionReason = {}));
+/** What removed a domain — both delete the provider's domain (E9). */
+export var OrganizationEmailDomainRemovalTrigger;
+(function (OrganizationEmailDomainRemovalTrigger) {
+    /** An organization administrator removed it. */
+    OrganizationEmailDomainRemovalTrigger["REMOVE"] = "remove";
+    /** The organization was deleted. */
+    OrganizationEmailDomainRemovalTrigger["ORGANIZATION_DELETED"] = "organization_deleted";
+})(OrganizationEmailDomainRemovalTrigger || (OrganizationEmailDomainRemovalTrigger = {}));
+/** @wildo_source:part:end saas.models.inbound-email */
+/** The largest notification body the `inbound-email` endpoint accepts. A notification is small JSON; the message is FETCHED. */
+export const INBOUND_EMAIL_NOTIFICATION_MAX_BODY_BYTES = 256 * 1024;
+/** The default ceiling on a whole message (the application may lower or raise it). */
+export const INBOUND_EMAIL_DEFAULT_MAX_MESSAGE_BYTES = 25 * 1024 * 1024;
+/** The most attachments one message may carry. */
+export const INBOUND_EMAIL_MAX_ATTACHMENTS = 20;
+/** The most text a stored message keeps per body; the rest is cut and `textTruncated` is set. */
+export const INBOUND_EMAIL_MAX_STORED_TEXT_BYTES = 1024 * 1024;
+/**
+ * The headers an `inboundEmails` row keeps. An ALLOW-list, not a deny-list: a header is correspondence metadata
+ * that can carry personal data, and one not named here is not stored. Threading and authentication headers are
+ * kept in their own fields.
+ */
+export const INBOUND_EMAIL_KEPT_HEADERS = [
+    'date',
+    'from',
+    'to',
+    'cc',
+    'reply-to',
+    'subject',
+    'message-id',
+    'in-reply-to',
+    'references',
+    'return-path',
+    'authentication-results',
+    'content-type',
+    'mime-version',
+    'auto-submitted',
+    'list-id',
+    'precedence',
+];
+/** Placeholder written over free text an erasure scrubs. */
+export const ERASED_INBOUND_EMAIL_TEXT = '[erased]';
+const addressText = (maximum = 320) => addImpersonalizeWith(z.string().max(maximum).dataCategories(PersonalDataCategory.CONTACT_DETAILS), RedactionType.MASK, { maskValue: ERASED_INBOUND_EMAIL_TEXT });
+/** One address as a message named it. */
+export const InboundEmailAddressSchema = z.strictObject({
+    address: z.string().max(320).describe('The address.'),
+    name: z.string().max(320).optional().describe('The display name the message gave it, when it gave one.'),
+});
+/** One attachment that was stored and made available. `fileId` names a `files` row. */
+export const InboundEmailAttachmentSchema = z.strictObject({
+    fileId: z.string().min(1).describe('The stored file. Served only once its scan verdict is clean.'),
+    filename: z.string().max(255).describe('The filename the sender gave.'),
+    contentType: z.string().max(255).describe('The content type the sender declared.'),
+    size: z.number().int().nonnegative().describe('The size in bytes.'),
+    contentId: z.string().max(998).optional().describe('The Content-ID of an inline part, without angle brackets.'),
+    disposition: z.string().max(20).optional().describe('`attachment` or `inline`, as the sender declared it.'),
+});
+/** An attachment that was NOT made available, and why. */
+export const InboundEmailWithheldAttachmentSchema = z.strictObject({
+    filename: z.string().max(255).describe('The filename the sender gave.'),
+    reason: z.enum(InboundEmailWithheldReason).systemEnum('InboundEmailWithheldReason').describe('Why it was withheld.'),
+});
+/**
+ * The original bytes, copied at ingest (a provider's download link is signed and expires). `sha256` is of the
+ * bytes AS CAPTURED; the stored file must hash to it (E5). Nothing updates this field: `inboundEmails` has no
+ * update route and the field is excluded from every write after creation.
+ */
+export const InboundEmailRawMimeSchema = z.strictObject({
+    fileId: z.string().min(1).describe('The stored file holding the original message bytes.'),
+    sha256: z.string().length(64).describe('The SHA-256 (hex) of the bytes as captured.'),
+    sizeBytes: z.number().int().nonnegative().describe('The size of the original message in bytes.'),
+});
+/** What the receiving provider concluded about the message's origin (RFC 8601 result names). */
+export const InboundEmailAuthenticationSchema = z.strictObject({
+    spf: z.string().max(20).describe('The SPF result.'),
+    dkim: z.string().max(20).describe('The DKIM result.'),
+    dmarc: z.string().max(20).describe('The DMARC result.'),
+    dmarcAligned: z.boolean().describe('Whether the From domain aligned with an authenticated identifier.'),
+});
+/**
+ * One received message, in the organization it was routed to.
+ *
+ * A message addressed to two organizations is one row in EACH: routing decides the organization, and a row
+ * never names another tenant.
+ */
+export const InboundEmailSchema = z.object({
+    _id: z.string().min(1).isPrimaryKey().isSummaryField(),
+    organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),
+    // IDENTITY ────────────────────────────────────────────────────────────────
+    /** The stage-1 delivery that carried the provider's notification (#1596). */
+    inboundDeliveryId: z.string().min(1).isDBIndexed().excludeFromUpdate()
+        .describe('The stored delivery of the provider\'s notification that announced this message.'),
+    providerRef: z.string().min(1).max(100).excludeFromUpdate().describe('The provider that received the message.'),
+    providerMessageId: z.string().min(1).max(200).isDBIndexed().excludeFromUpdate()
+        .describe('The provider\'s id for the message.'),
+    messageId: z.string().max(998).nullable().default(null).excludeFromUpdate()
+        .describe('The Message-ID the message carried, angle brackets included, when it carried a well-formed one.'),
+    // THREADING ───────────────────────────────────────────────────────────────
+    inReplyTo: z.string().max(998).nullable().default(null).excludeFromUpdate().describe('The Message-ID this message answers.'),
+    references: z.array(z.string().max(998)).max(100).default([]).excludeFromUpdate().describe('The Message-IDs of the thread before it, oldest first.'),
+    threadId: z.string().isDBIndexed().nullable().default(null).excludeFromUpdate()
+        .describe('The conversation thread the message was recorded in, once it was dispatched.'),
+    // ADDRESSING ──────────────────────────────────────────────────────────────
+    /** The sender's address, lower-cased. Indexed: a data subject's erasure finds their letters by it. */
+    fromAddress: addressText().isDBIndexed().isSummaryField().excludeFromUpdate()
+        .describe('The sender\'s address.'),
+    fromName: addImpersonalizeWith(z.string().max(320).nullable().default(null).dataCategories(PersonalDataCategory.CONTACT_DETAILS), RedactionType.RESET).excludeFromUpdate().describe('The sender\'s display name.'),
+    to: addImpersonalizeWith(z.array(InboundEmailAddressSchema).default([]).dataCategories(PersonalDataCategory.CONTACT_DETAILS), RedactionType.RESET).excludeFromUpdate().describe('The addresses in To.'),
+    cc: addImpersonalizeWith(z.array(InboundEmailAddressSchema).default([]).dataCategories(PersonalDataCategory.CONTACT_DETAILS), RedactionType.RESET).excludeFromUpdate().describe('The addresses in Cc.'),
+    replyTo: addImpersonalizeWith(z.string().max(320).nullable().default(null).dataCategories(PersonalDataCategory.CONTACT_DETAILS), RedactionType.RESET).excludeFromUpdate().describe('The Reply-To address, when the message named one.'),
+    /** The recipient the message was routed on — one of the envelope recipients, on this organization's route. */
+    receivedFor: z.string().min(1).max(320).isDBIndexed().isSummaryField().excludeFromUpdate()
+        .describe('The address the message was delivered for, which routing read.'),
+    routeKind: z.enum(InboundRouteKind).systemEnum('InboundRouteKind').isSummaryField().excludeFromUpdate()
+        .describe('How that address reached this organization.'),
+    routeTag: z.string().max(64).nullable().default(null).excludeFromUpdate()
+        .describe('The tag the address carried (`cases+tag@…`), which selects the handler.'),
+    // CONTENT ─────────────────────────────────────────────────────────────────
+    subject: addImpersonalizeWith(z.string().max(998).default('').isSummaryField().dataCategories(PersonalDataCategory.USER_CONTENT), RedactionType.MASK, { maskValue: ERASED_INBOUND_EMAIL_TEXT }).excludeFromUpdate().describe('The subject.'),
+    textBody: addImpersonalizeWith(z.string().nullable().default(null).dataCategories(PersonalDataCategory.USER_CONTENT), RedactionType.RESET).excludeFromUpdate().describe('The plain-text body, cut at 1 MB.'),
+    /** RAW as received. Never trusted as markup: rendered only in a sandboxed frame that runs nothing and loads nothing remote. */
+    htmlBody: addImpersonalizeWith(z.string().nullable().default(null).dataCategories(PersonalDataCategory.USER_CONTENT), RedactionType.RESET).excludeFromUpdate().describe('The HTML body as received, cut at 1 MB; shown only in a sandboxed frame that runs nothing and loads nothing remote.'),
+    strippedReply: addImpersonalizeWith(z.string().nullable().default(null).dataCategories(PersonalDataCategory.USER_CONTENT), RedactionType.RESET).excludeFromUpdate().describe('The new part of a reply, without the quoted history, when it could be separated.'),
+    headers: addImpersonalizeWith(z.record(z.string(), z.string()).default({}).dataCategories(PersonalDataCategory.CONTACT_DETAILS), RedactionType.RESET).excludeFromUpdate().describe('The allow-listed headers the message carried.'),
+    textTruncated: z.boolean().default(false).excludeFromUpdate().describe('Whether a body was cut at the stored-text limit.'),
+    // AUTHENTICATION ──────────────────────────────────────────────────────────
+    authentication: InboundEmailAuthenticationSchema.excludeFromUpdate()
+        .describe('The SPF, DKIM and DMARC results the receiving provider reported.'),
+    senderAssurance: z.enum(InboundSenderAssurance).systemEnum('InboundSenderAssurance').nullable().default(null).excludeFromUpdate()
+        .describe('How well the sender is known, as the channel derived it; null until the message was admitted.'),
+    // ATTACHMENTS AND RAW ─────────────────────────────────────────────────────
+    // What the sender attached, as stored — filenames are the sender's words, so they are reset on erasure.
+    attachments: addImpersonalizeWith(z.array(InboundEmailAttachmentSchema).default([]).dataCategories(PersonalDataCategory.USER_CONTENT), RedactionType.RESET).excludeFromUpdate().describe('The attachments that were stored, each with the verdict-independent metadata the sender declared.'),
+    withheldAttachments: addImpersonalizeWith(z.array(InboundEmailWithheldAttachmentSchema).default([]).dataCategories(PersonalDataCategory.USER_CONTENT), RedactionType.RESET).excludeFromUpdate().describe('The attachments that were not made available, and why.'),
+    /**
+     * The CLEAN attachments, as files LINKED to this row. Linking is what keeps them: an unlinked file is swept by
+     * the files cleanup a day after its scan, so a message's attachments would otherwise outlive it by one day. It is
+     * also what serves them: the file routes authorize a linked file through this row's READ. Set only once every
+     * verdict is known; an infected or unscannable file is never linked, so it is never served and is swept.
+     * Removed — and its files erased — when the message is impersonalized.
+     */
+    attachmentFiles: addImpersonalizeWith(z_file({ multiple: true, maxFiles: INBOUND_EMAIL_MAX_ATTACHMENTS }).optional().dataCategories(PersonalDataCategory.USER_CONTENT), RedactionType.REMOVE).excludeFromCreate().excludeFromUpdate().describe('The clean attachments, as files readable wherever the message is.'),
+    rawMime: InboundEmailRawMimeSchema.nullable().default(null).excludeFromUpdate()
+        .describe('The original message\'s digest and size, as captured.'),
+    /**
+     * The original message bytes as a file LINKED to this row — for the same two reasons as `attachmentFiles`. Set
+     * only when its scan is clean (the raw message contains every attachment). Removed, and the file erased, when the
+     * message is impersonalized: the raw bytes hold everything the reset text fields held.
+     */
+    rawMimeFile: addImpersonalizeWith(z_file().optional().dataCategories(PersonalDataCategory.USER_CONTENT), RedactionType.REMOVE).excludeFromCreate().excludeFromUpdate().describe('The original message, as a file readable wherever the message is.'),
+    sizeBytes: z.number().int().nonnegative().excludeFromUpdate().describe('The size of the message in bytes.'),
+    receivedAt: z.date().isDBIndexed().isSummaryField().excludeFromUpdate().describe('When the provider received the message.'),
+    // DISPOSITION ─────────────────────────────────────────────────────────────
+    status: z.enum(InboundEmailStatus).systemEnum('InboundEmailStatus').isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate()
+        .describe('What became of the message.'),
+    limitExceeded: z.enum(InboundEmailLimit).systemEnum('InboundEmailLimit').nullable().default(null).excludeFromCreate().excludeFromUpdate()
+        .describe('For a message rejected over a limit, which one.'),
+    createdAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),
+    updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),
+}).businessKeySet(['organizationId', 'providerRef', 'providerMessageId']);
+/** The DNS ownership challenge an organization answers before its domain is created anywhere. */
+export const EmailDomainOwnershipChallengeSchema = z.strictObject({
+    txtName: z.string().min(1).max(253).describe('The DNS name the TXT record is published on.'),
+    /** SHA-256 of the challenge value. The value itself is shown once, when the domain is claimed. */
+    nonceHash: z.string().length(64).describe('The SHA-256 of the challenge value.'),
+});
+/** One DNS record the provider asks the organization to publish, copied as the provider reported it. */
+export const EmailDomainDnsRecordSchema = z.strictObject({
+    purpose: z.string().max(40).describe('What the record is for, as the provider named it (DKIM, SPF, MX…).'),
+    type: z.string().max(10).describe('The record type.'),
+    name: z.string().max(253).describe('The name to publish it on.'),
+    value: z.string().max(4096).describe('The value to publish.'),
+    priority: z.number().int().optional().describe('For an MX record, its priority.'),
+    status: z.string().max(40).optional().describe('Whether the provider has seen it yet.'),
+});
+/** What an organization uses a domain for. */
+export const EmailDomainCapabilitiesSchema = z.strictObject({
+    sending: z.boolean().describe('Replies and organization mail may be sent from it.'),
+    receiving: z.boolean().describe('Mail addressed to it is routed to the organization.'),
+});
+/**
+ * A domain an organization claimed, from the ownership challenge to a verified sending and receiving domain.
+ *
+ * Ownership is proven PER ORGANIZATION before anything is created at the provider (review H1): every tenant
+ * shares one provider account, so the provider's own verification would accept a squatter's claim the moment
+ * the real owner published its records. Pending claims block nobody; the first organization to prove
+ * ownership wins, and from then on the domain is refused to everyone else.
+ */
+export const OrganizationEmailDomainSchema = z.object({
+    _id: z.string().min(1).isPrimaryKey().isSummaryField(),
+    organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),
+    /** Lower-case DNS hostname. Not unique: several organizations may hold PENDING claims on one domain. */
+    domain: z.string().min(4).max(253).isDBIndexed().isSummaryField().excludeFromUpdate()
+        .describe('The domain, e.g. `inbox.firm.com`. A subdomain keeps the organization\'s existing mailbox untouched.'),
+    capabilities: EmailDomainCapabilitiesSchema.excludeFromUpdate()
+        .describe('Whether the organization sends from it, receives on it, or both.'),
+    providerRef: z.string().max(100).nullable().default(null).excludeFromCreate().excludeFromUpdate()
+        .describe('The provider the domain was created at, once ownership was proven.'),
+    providerDomainId: z.string().max(200).isDBIndexed().nullable().default(null).excludeFromCreate().excludeFromUpdate()
+        .describe('The provider\'s id for the domain, once created there.'),
+    /**
+     * Where to publish the ownership TXT record, and the SHA-256 of the value to publish. The value itself is
+     * answered once, by `claim`; claiming again mints a fresh one and invalidates the old.
+     */
+    ownershipChallenge: EmailDomainOwnershipChallengeSchema.excludeFromCreate().excludeFromUpdate()
+        .describe('The DNS TXT ownership challenge: the name to publish it on, and a hash of the value.'),
+    status: z.enum(OrganizationEmailDomainStatus).systemEnum('OrganizationEmailDomainStatus').isDBIndexed().isSummaryField()
+        .excludeFromCreate().excludeFromUpdate()
+        .describe('Where the domain stands. Only a verified domain routes and sends.'),
+    dnsRecords: z.array(EmailDomainDnsRecordSchema).default([]).excludeFromCreate().excludeFromUpdate()
+        .describe('The records the provider asks to be published, as it reported them.'),
+    ownershipVerifiedAt: z.date().nullable().default(null).excludeFromCreate().excludeFromUpdate()
+        .describe('When the organization proved it owns the domain.'),
+    lastVerifiedAt: z.date().nullable().default(null).excludeFromCreate().excludeFromUpdate()
+        .describe('When the domain was last found verified.'),
+    createdAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),
+    updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),
+}).businessKeySet(['organizationId', 'domain']);
+/**
+ * A mailbox a firm keeps for one of its clients on the firm's own domain (S1): `acme@inbox.firm.com` → the
+ * client organization Acme, so the work lands where the case lives.
+ *
+ * OWNED BY THE FIRM — scoped to the organization that owns the domain, and created and deleted only by it. The
+ * domain owner decides what each of its addresses does, as every mail host does (a Google Workspace or Microsoft 365
+ * administrator creates the addresses on their domain; no one else can). The first design let the CLIENT create the
+ * row in its own organization, which let a client take any address on the firm's domain — the firm's own intake
+ * address included — and route the firm's mail into itself, with no way for the firm to remove it.
+ *
+ * It routes only while its domain is VERIFIED for receiving and still the firm's, and the service-provider
+ * relationship (#1597) is ACTIVE — re-checked for every message. The client ends it by ending the relationship.
+ */
+export const ClientMailboxSchema = z.object({
+    _id: z.string().min(1).isPrimaryKey().isSummaryField(),
+    /** The FIRM — the organization that owns the domain and the mailbox. */
+    organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),
+    /** Lower-case, unique across the application: one address routes to one organization. */
+    address: z.string().min(3).max(320).isUnique({ scope: 'global', sparse: false }).isSummaryField().excludeFromUpdate()
+        .describe('The mailbox address, on the firm\'s verified domain.'),
+    /** The firm's domain. A plain id: it names a row of ANOTHER tenant, and a navigable edge across tenants is refused. */
+    emailDomainId: z.string().min(1).isDBIndexed().isSummaryField().excludeFromUpdate()
+        .describe('The firm\'s email domain the address is on.'),
+    serviceProviderRelationshipId: z.string().min(1).isDBIndexed().isSummaryField().excludeFromUpdate()
+        .describe('The relationship between the client and the firm that authorizes this mailbox.'),
+    /** A plain id, not a navigable edge: it names ANOTHER tenant. */
+    clientOrganizationId: z.string().min(1).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate()
+        .describe('The client organization the mail lands in, as the relationship names it.'),
+    createdAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),
+    updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),
+});
+/**
+ * The slug of a deleted organization, which the shared domain never routes again (L3). Kept for as long as
+ * the application exists: a tombstone that expired would hand an old organization's correspondents to
+ * whoever took the slug next.
+ */
+export const InboundAddressTombstoneSchema = z.object({
+    _id: z.string().min(1).isPrimaryKey().isSummaryField(),
+    applicationId: z.string().min(1).isDBIndexed().isForeignKey().excludeFromUpdate(),
+    slug: z.string().min(1).max(50).isUnique({ scope: 'global', sparse: false }).isSummaryField().excludeFromUpdate()
+        .describe('The slug of the deleted organization.'),
+    tombstonedAt: z.date().isSummaryField().excludeFromUpdate().describe('When the organization was deleted.'),
+    createdAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),
+    updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),
+});
+/** @wildo_source:part:start saas.models.inbound-email-domains facet:layer:shared facet:family:inbound facet:audience:app-developer */
+/** The verbs of `organizationEmailDomains`, each audited. */
+export var OrganizationEmailDomains_Operations;
+(function (OrganizationEmailDomains_Operations) {
+    /** Mint the organization's DNS TXT ownership challenge. Creates nothing at the provider. */
+    OrganizationEmailDomains_Operations["CLAIM"] = "claim";
+    /** Resolve the TXT record; the first organization to prove ownership wins, and only then is the domain created at the provider. */
+    OrganizationEmailDomains_Operations["VERIFY_OWNERSHIP"] = "verify_ownership";
+    /** Ask the provider to verify the domain's records. */
+    OrganizationEmailDomains_Operations["VERIFY"] = "verify";
+    /** Delete the domain at the provider, and the row. */
+    OrganizationEmailDomains_Operations["REMOVE"] = "remove";
+})(OrganizationEmailDomains_Operations || (OrganizationEmailDomains_Operations = {}));
+/** A claim: the domain and what it will be used for. */
+export const OrganizationEmailDomainClaimRequestSchema = z.object({
+    domain: z.string()
+        .min(4)
+        .max(253)
+        .regex(/^(?!-)[A-Za-z0-9-]{1,63}(?<!-)(\.(?!-)[A-Za-z0-9-]{1,63}(?<!-))+$/, 'Provide a DNS hostname with at least two labels, e.g. "inbox.firm.com".')
+        .describe('The domain to claim, e.g. `inbox.firm.com`.'),
+    capabilities: EmailDomainCapabilitiesSchema.default({ sending: true, receiving: true })
+        .describe('Whether the organization will send from it, receive on it, or both.'),
+});
+/**
+ * What `claim` answers: the claim, and the ONE time the ownership record's value is shown. Only its hash is
+ * stored, so claiming again is how a lost value is recovered — and it replaces the old one.
+ */
+export const OrganizationEmailDomainClaimResponseSchema = z.object({
+    organizationEmailDomainId: z.string().describe('The claim.'),
+    domain: z.string().describe('The domain claimed.'),
+    status: z.enum(OrganizationEmailDomainStatus).describe('OWNERSHIP_PENDING until the record is found.'),
+    txtName: z.string().describe('The DNS name to publish the TXT record on.'),
+    // `.isEphemeral()`: the frontend reveals it once, in the dialog that must be acknowledged (the SSO domain claim's contract).
+    txtValue: z.string().isEphemeral().describe('The TXT record value to publish. Shown once.'),
+});
+/** What `remove` answers: which domain went, and whether the provider still held it and deleted it. */
+export const OrganizationEmailDomainRemoveResponseSchema = z.object({
+    organizationEmailDomainId: z.string().describe('The removed domain.'),
+    domain: z.string().describe('The domain name.'),
+    providerDomainDeleted: z.boolean().describe('Whether the domain existed at the email provider and was deleted there.'),
+});
+/** The prefix of an email domain ownership record's value; the nonce follows it. */
+export const EMAIL_DOMAIN_OWNERSHIP_TXT_PREFIX = 'wildo-email-domain-verification=';
+/** The label the ownership record is published under: `_wildo-verification.{domain}` (the SSO challenge's name). */
+export const EMAIL_DOMAIN_OWNERSHIP_TXT_LABEL = '_wildo-verification';
+/** A client mailbox, as a firm or a client administrator asks for it. */
+export const ClientMailboxCreateRequestSchema = z.object({
+    address: z.string().min(3).max(320).describe('The mailbox address, e.g. `acme@inbox.firm.com`.'),
+    emailDomainId: z.string().min(1).describe('This organization\'s verified receiving domain the address is on.'),
+    serviceProviderRelationshipId: z.string().min(1).describe('The ACTIVE relationship in which this organization serves the client.'),
+});
+/**
+ * An application's receiving-email settings (`email.inbound` in the backend configuration). Every field has a
+ * safe default, and the section is optional: an application that receives no email declares nothing.
+ */
+export const InboundEmailConfigSchema = z.object({
+    /**
+     * The application's SHARED receiving domain — every organization's zero-configuration address is
+     * `{slug}@{sharedDomain}`. Its MX points at the receiving provider. Absent, the shared address does not exist
+     * and only organization domains and client mailboxes route.
+     */
+    sharedDomain: z.string()
+        .min(4)
+        .max(253)
+        .regex(/^(?!-)[a-z0-9-]{1,63}(?<!-)(\.(?!-)[a-z0-9-]{1,63}(?<!-))+$/, 'A lower-case DNS hostname, e.g. "in.example.com".')
+        .optional()
+        .describe('The shared receiving domain: every organization is reachable at {slug}@{sharedDomain}.'),
+    /** Keep the original bytes of every received message (default), or discard them. */
+    rawMimeRetention: z.enum(InboundEmailRawRetention).default(InboundEmailRawRetention.KEEP)
+        .describe('Whether the original message bytes are kept; kept by default, because only they can be re-verified.'),
+    /** Whether an organization's verified sending domain is used for all its mail, or for thread replies only (default). */
+    organizationSendingDomainUse: z.enum(OrganizationSendingDomainUse).default(OrganizationSendingDomainUse.THREAD_REPLIES)
+        .describe('Where an organization\'s verified sending domain is used as the sender.'),
+    /** The largest message accepted whole; a larger one is kept as its envelope only (REJECTED_LIMIT). */
+    maxMessageSizeBytes: z.number().int().positive().max(100 * 1024 * 1024).default(INBOUND_EMAIL_DEFAULT_MAX_MESSAGE_BYTES)
+        .describe('The largest message accepted whole, in bytes.'),
+});
+/** @wildo_source:part:end saas.models.inbound-email-domains */
+// ─────────────────────────────────────────────────────────────────────────────
+// Addresses — pure functions every consumer shares, so routing and reply composition cannot disagree.
+// ─────────────────────────────────────────────────────────────────────────────
+/** The prefix of a reply-token sub-address: `{local}+r-{token}@{domain}`. */
+export const REPLY_TOKEN_SUBADDRESS_PREFIX = 'r-';
+/** A reply token as it appears in an address: base64url, at least 128 bits (22 characters). */
+const REPLY_TOKEN_PATTERN = /^[A-Za-z0-9_-]{22,128}$/;
+/** A route tag: the same shape as `INBOUND_ROUTE_TAG_PATTERN` on the backend. */
+const ROUTE_TAG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+ * Take an envelope recipient apart. Returns `undefined` for anything that is not `local@domain` with a
+ * non-empty local part — such an address routes nowhere.
+ *
+ * The local part is compared lower-cased (mailboxes here are case-insensitive, and the provider lower-cases
+ * nothing); the reply token alone keeps its case.
+ */
+export function parseInboundAddress(raw) {
+    const trimmed = raw.trim().replace(/^<|>$/g, '');
+    const at = trimmed.lastIndexOf('@');
+    if (at <= 0 || at === trimmed.length - 1)
+        return undefined;
+    const localRaw = trimmed.slice(0, at);
+    const domain = trimmed.slice(at + 1).toLowerCase();
+    if (!/^[a-z0-9.-]+$/.test(domain) || !domain.includes('.'))
+        return undefined;
+    const plus = localRaw.indexOf('+');
+    const local = (plus >= 0 ? localRaw.slice(0, plus) : localRaw).toLowerCase();
+    if (local.length === 0)
+        return undefined;
+    const address = `${localRaw.toLowerCase()}@${domain}`;
+    if (plus < 0)
+        return { address, local, domain };
+    const sub = localRaw.slice(plus + 1);
+    if (sub.toLowerCase().startsWith(REPLY_TOKEN_SUBADDRESS_PREFIX) && REPLY_TOKEN_PATTERN.test(sub.slice(REPLY_TOKEN_SUBADDRESS_PREFIX.length))) {
+        return { address, local, domain, replyToken: sub.slice(REPLY_TOKEN_SUBADDRESS_PREFIX.length) };
+    }
+    const tag = sub.toLowerCase();
+    return ROUTE_TAG_PATTERN.test(tag) ? { address, local, domain, tag } : { address, local, domain };
+}
+/** `{local}+r-{token}@{domain}` — the address a reply on a thread carries in Reply-To. */
+export function composeReplyTokenAddress(local, token, domain) {
+    return `${local.toLowerCase()}+${REPLY_TOKEN_SUBADDRESS_PREFIX}${token}@${domain.toLowerCase()}`;
+}
+/** How many trailing characters of an organization id disambiguate a reused slug. */
+export const SHARED_DOMAIN_SHORT_ORGANIZATION_ID_LENGTH = 8;
+/** The trailing characters of an organization id that follow a reused slug: `{slug}.{shortOrgId}`. */
+export function shortOrganizationId(organizationId) {
+    return organizationId.toLowerCase().replace(/[^a-z0-9]/g, '').slice(-SHARED_DOMAIN_SHORT_ORGANIZATION_ID_LENGTH);
+}
+/**
+ * What separates a reused slug from its organization's short id. A DOT, because an organization slug cannot contain
+ * one (`^[a-z0-9]+(?:-[a-z0-9]+)*$`): with a hyphen, `{slug}-{shortOrgId}` was itself a valid slug, and an organization
+ * registering exactly that slug would have been routed its victim's mail. A dot is legal in an RFC 5321 local part.
+ */
+export const SHARED_DOMAIN_REUSED_SLUG_SEPARATOR = '.';
+/**
+ * An organization's local part on the shared domain: its slug, or `{slug}.{shortOrgId}` when its slug was
+ * once held by a DELETED organization — so mail written to the old organization never reaches the new one.
+ */
+export function sharedDomainLocalPartFor(slug, organizationId, slugTombstoned) {
+    return slugTombstoned ? `${slug}${SHARED_DOMAIN_REUSED_SLUG_SEPARATOR}${shortOrganizationId(organizationId)}` : slug;
+}
+//# sourceMappingURL=inbound-email.shared.schemas.js.map