@wildo-ai/saas-models 1.1.4 → 1.1.6

package/dist/esm/inbound/inbound-channels.shared.schemas.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Inbound channels — the vocabulary of HOW a message reached the application, how much is known about
+ * who sent it, and whether and how the handler answers (#1630).
+ *
+ * A CHANNEL is what the message arrived on, not who carried it. `EMAIL` is a channel an application
+ * declares a handler for; the provider that hosts the receiving domain is the application's
+ * `EMAIL_INBOUND` selection and is never named by a handler. `WEBHOOK` is the channel of every
+ * delivery #1596's endpoint sources receive, and is DERIVED for those rows, never declared.
+ *
+ * @see engine/saas-models/src/inbound/inbound-delivery.shared.schemas.ts — the durable delivery these
+ *   channels feed.
+ */
+import { type StandardInboundEmail_Authentication } from '@wildo-ai/external-connectors-models';
+/** @wildo_source:part:start saas.models.inbound-channels facet:layer:shared facet:family:inbound facet:audience:app-developer */
+/**
+ * What a message arrived on.
+ *
+ * SMS, chat and Slack join this vocabulary when a provider can fill them — a channel nothing can
+ * receive on is a slot no configuration can satisfy.
+ */
+export declare enum InboundChannelKind {
+    /** Email received through the application's `EMAIL_INBOUND` provider and routed to an organization. */
+    EMAIL = "email",
+    /**
+     * A signed HTTP delivery from another system (#1596). Derived for provider and application endpoint
+     * deliveries; a handler never declares it.
+     */
+    WEBHOOK = "webhook"
+}
+/**
+ * How much is known about who SENT a message.
+ *
+ * **Identification, never authentication.** An address, a domain or even a reply token identifies a
+ * sender to some degree; none of them authenticates a person. Assurance therefore GATES what a handler
+ * accepts (a handler declares the minimum it will act on) and grants NO authority: the handler acts
+ * with the roles it declares, whoever wrote.
+ *
+ * spec-cite: NIST SP 800-63B rev. 4 §3.1.3.1 ("Email SHALL NOT be used for out-of-band authentication");
+ * RFC 7489 §3.1 (DMARC authenticates the RFC5322.From DOMAIN by alignment with an authenticated
+ * identifier, not the person). Both as recorded in #1630's decisions log, 2026-09-25.
+ *
+ * **Ordered only within a channel.** Each channel has its own ladder ({@link INBOUND_SENDER_ASSURANCE_LADDERS});
+ * a signed webhook is not "more" or "less" than a domain-aligned email, so there is no total order and
+ * comparing across channels is refused.
+ */
+export declare enum InboundSenderAssurance {
+    /** Nothing about the sender verified. The floor of every ladder. */
+    UNVERIFIED = "unverified",
+    /** WEBHOOK: the delivery carried a valid signature under the source's secret. Identifies the SOURCE system. */
+    SOURCE_SIGNED = "source_signed",
+    /** EMAIL: DMARC passed and is aligned with the `From` domain — the domain, not the mailbox, is authenticated. */
+    DOMAIN_ALIGNED = "domain_aligned",
+    /**
+     * EMAIL: domain-aligned, and the address is known to the routed organization — a verified member, or a
+     * contact the application's resolver recognises.
+     */
+    KNOWN_CONTACT = "known_contact",
+    /**
+     * EMAIL: domain-aligned, arrived on an unrevoked reply token the application issued for this thread,
+     * and `From` is the address that token was issued to.
+     */
+    THREAD_TOKEN_BOUND = "thread_token_bound"
+}
+/** The assurance levels meaningful on each channel — the type a channel's ladder and minimum are drawn from. */
+export interface InboundSenderAssuranceByChannel {
+    [InboundChannelKind.EMAIL]: InboundSenderAssurance.UNVERIFIED | InboundSenderAssurance.DOMAIN_ALIGNED | InboundSenderAssurance.KNOWN_CONTACT | InboundSenderAssurance.THREAD_TOKEN_BOUND;
+    [InboundChannelKind.WEBHOOK]: InboundSenderAssurance.UNVERIFIED | InboundSenderAssurance.SOURCE_SIGNED;
+}
+/** An assurance level of channel `C`. `SenderAssuranceOf<EMAIL>` does not admit `SOURCE_SIGNED`. */
+export type SenderAssuranceOf<C extends InboundChannelKind> = InboundSenderAssuranceByChannel[C];
+/**
+ * Each channel's ladder, lowest first. Total over {@link InboundChannelKind}: a channel added without a
+ * ladder does not compile.
+ */
+export declare const INBOUND_SENDER_ASSURANCE_LADDERS: {
+    readonly [C in InboundChannelKind]: readonly SenderAssuranceOf<C>[];
+};
+/** Thrown when an assurance level is asked about on a channel whose ladder does not contain it. */
+export declare class InboundSenderAssuranceChannelError extends Error {
+    constructor(channel: InboundChannelKind, level: InboundSenderAssurance);
+}
+/**
+ * The rank of `level` on `channel`'s ladder, 0 for the floor.
+ *
+ * The type admits only that channel's levels, so `senderAssuranceRank(InboundChannelKind.WEBHOOK,
+ * InboundSenderAssurance.DOMAIN_ALIGNED)` does not compile; a value that reached here untyped (a stored
+ * row, a JSON payload) and is not on the ladder throws rather than ranking as anything.
+ */
+export declare function senderAssuranceRank<C extends InboundChannelKind>(channel: C, level: SenderAssuranceOf<C>): number;
+/** Whether `level` is at least `minimum`, both on `channel`'s ladder. */
+export declare function meetsMinimumSenderAssurance<C extends InboundChannelKind>(channel: C, level: SenderAssuranceOf<C>, minimum: SenderAssuranceOf<C>): boolean;
+/** Whether `level` is a level of `channel` — for narrowing a value read back from storage. */
+export declare function isSenderAssuranceOf<C extends InboundChannelKind>(channel: C, level: InboundSenderAssurance): level is SenderAssuranceOf<C>;
+/**
+ * Whether a channel handler answers, and how. Required on every handler, with no default: a handler
+ * that answers and one that does not are different programs, and the type system knows which one it
+ * is holding (`ctx.reply` exists only under {@link InboundReplyMode.THREAD}).
+ */
+export declare enum InboundReplyMode {
+    /** Replies go back on the thread the message arrived on, through the channel's outbound path. */
+    THREAD = "thread",
+    /** The handler never answers. Every endpoint handler (#1596) and billing declare this. */
+    NONE = "none"
+}
+/**
+ * What happened to a channel message whose sender assurance is below the selected handler's minimum
+ * (#1630). A below-minimum message never reaches the main handler (I11). What it causes instead is the
+ * application's binding: a declared below-minimum handler, or nothing but storage and an audit row.
+ */
+export declare enum InboundBelowMinimumDisposition {
+    /** The handler declared a below-minimum handler, and the message was dispatched to it instead. */
+    ROUTED_TO_BELOW_MINIMUM_HANDLER = "routed_to_below_minimum_handler",
+    /** No below-minimum handler: stored in its channel record and audited, and dispatched to nobody. */
+    STORED_NOT_DISPATCHED = "stored_not_dispatched"
+}
+/** What the routed organization knows about a sender's address. */
+export declare enum EmailSenderContactMatch {
+    /** Neither a member nor a contact the application recognises. */
+    NONE = "none",
+    /** A verified, active member of the routed organization (engine-known; sets `memberUserId`). */
+    ORGANIZATION_MEMBER = "organization_member",
+    /** The application's contact resolver answered true. The engine keeps no contacts of its own. */
+    APPLICATION_CONTACT = "application_contact"
+}
+/** How the reply token a message arrived on (if any) relates to its sender. */
+export declare enum EmailReplyTokenSenderMatch {
+    /** The message did not arrive on a live token of the routed organization. */
+    NO_TOKEN = "no_token",
+    /** A live token, and `From` is the address it was issued to. */
+    MATCHES_RECIPIENT = "matches_recipient",
+    /** A live token, `From` is on the recipient's domain but is another mailbox. */
+    OTHER_ADDRESS_SAME_DOMAIN = "other_address_same_domain",
+    /** A live token, `From` is on another domain than the address it was issued to. */
+    OTHER_DOMAIN = "other_domain"
+}
+/** Why a live reply token did not bind its message — recorded on `INBOUND_REPLY_TOKEN_DOWNGRADED`. */
+export declare enum ReplyTokenDowngradeReason {
+    /** `From` is not the address the token was issued to, though on its domain. */
+    SENDER_ADDRESS_MISMATCH = "sender_address_mismatch",
+    /** `From` is on another domain than the address the token was issued to — the case a leaked token looks like. */
+    SENDER_DOMAIN_MISMATCH = "sender_domain_mismatch",
+    /** The token is live but DMARC did not pass aligned, so the `From` domain itself is unauthenticated. */
+    DOMAIN_NOT_ALIGNED = "domain_not_aligned"
+}
+/** The inputs {@link deriveEmailSenderAssurance} reads. All of them are facts, never answers a sender gave. */
+export interface EmailSenderAssuranceInput {
+    readonly authentication: StandardInboundEmail_Authentication;
+    readonly contactMatch: EmailSenderContactMatch;
+    readonly tokenMatch: EmailReplyTokenSenderMatch;
+}
+export interface EmailSenderAssuranceDerivation {
+    readonly assurance: SenderAssuranceOf<InboundChannelKind.EMAIL>;
+    /** Set when a live token arrived and did not bind the message; the caller audits it. */
+    readonly tokenDowngrade?: ReplyTokenDowngradeReason;
+}
+/** DMARC passed AND aligned with the `From` domain — the one fact every level above the floor rests on. */
+export declare function isEmailDomainAligned(authentication: StandardInboundEmail_Authentication): boolean;
+/**
+ * Derive an email's sender assurance. PURE: every input is a fact the engine established (the
+ * provider's authentication results, a member or contact lookup, a token lookup).
+ *
+ * - `UNVERIFIED`: DMARC did not pass aligned with `From`. Nothing below is consulted: a token or a
+ *   known address on an unauthenticated domain proves nothing, since anyone can write that `From`.
+ * - `THREAD_TOKEN_BOUND`: aligned, and the message arrived on a live token issued to `From`.
+ * - `KNOWN_CONTACT`: aligned, and the address is a member or a recognised contact.
+ * - `DOMAIN_ALIGNED`: aligned, and nothing more is known.
+ *
+ * A live token that did not bind — `From` is someone else, or the domain did not align — falls back to
+ * the level the rest derives and reports why in `tokenDowngrade`, which the caller audits.
+ */
+export declare function deriveEmailSenderAssurance(input: EmailSenderAssuranceInput): EmailSenderAssuranceDerivation;
+/** The domain of an address, lower-cased; `undefined` when there is no `@`. */
+export declare function emailAddressDomain(address: string): string | undefined;
+/**
+ * Whether two addresses are on the same domain. An address with no domain shares a domain with nothing —
+ * not even another address with no domain — so a malformed `From` can never pass as a colleague's.
+ */
+export declare function emailAddressesShareDomain(first: string, second: string): boolean;
+/** How `from` relates to the address a reply token was issued to. Addresses compare case-insensitively. */
+export declare function matchReplyTokenSender(from: string, recipient: string): Exclude<EmailReplyTokenSenderMatch, EmailReplyTokenSenderMatch.NO_TOKEN>;
+/**
+ * One RFC 5322 `msg-id` — angle brackets, one `@`, no whitespace and no CR/LF. The one check for a
+ * Message-ID wherever the engine reads one from a sender (`In-Reply-To`, `References`) or writes one into
+ * a header, so a value that could inject a header or break threading is dropped where it arrives.
+ */
+export declare const EMAIL_MESSAGE_ID_PATTERN: RegExp;
+export declare function isEmailMessageId(value: unknown): value is string;
+/**
+ * What an inbound handler's `ref` looks like: lower-case, dot-separated segments of `[a-z0-9-]`
+ * (`todos.intake`, `matters.mail-intake`). One definition for the backend's `inboundHandlerRef()`, which
+ * refuses anything else at module load, and for a build plan naming the handler a task produces.
+ */
+export declare const INBOUND_HANDLER_REF_PATTERN: RegExp;
+/** @wildo_source:part:end saas.models.inbound-channels */
+//# sourceMappingURL=inbound-channels.shared.schemas.d.ts.map

package/dist/esm/inbound/inbound-channels.shared.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound-channels.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/inbound/inbound-channels.shared.schemas.ts"],"names":[],"mappings":"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"}

package/dist/esm/inbound/inbound-channels.shared.schemas.js

@@ -0,0 +1,244 @@
+/**
+ * Inbound channels — the vocabulary of HOW a message reached the application, how much is known about
+ * who sent it, and whether and how the handler answers (#1630).
+ *
+ * A CHANNEL is what the message arrived on, not who carried it. `EMAIL` is a channel an application
+ * declares a handler for; the provider that hosts the receiving domain is the application's
+ * `EMAIL_INBOUND` selection and is never named by a handler. `WEBHOOK` is the channel of every
+ * delivery #1596's endpoint sources receive, and is DERIVED for those rows, never declared.
+ *
+ * @see engine/saas-models/src/inbound/inbound-delivery.shared.schemas.ts — the durable delivery these
+ *   channels feed.
+ */
+import { EmailAuthenticationVerdict } from '@wildo-ai/external-connectors-models';
+/** @wildo_source:part:start saas.models.inbound-channels facet:layer:shared facet:family:inbound facet:audience:app-developer */
+/**
+ * What a message arrived on.
+ *
+ * SMS, chat and Slack join this vocabulary when a provider can fill them — a channel nothing can
+ * receive on is a slot no configuration can satisfy.
+ */
+export var InboundChannelKind;
+(function (InboundChannelKind) {
+    /** Email received through the application's `EMAIL_INBOUND` provider and routed to an organization. */
+    InboundChannelKind["EMAIL"] = "email";
+    /**
+     * A signed HTTP delivery from another system (#1596). Derived for provider and application endpoint
+     * deliveries; a handler never declares it.
+     */
+    InboundChannelKind["WEBHOOK"] = "webhook";
+})(InboundChannelKind || (InboundChannelKind = {}));
+/**
+ * How much is known about who SENT a message.
+ *
+ * **Identification, never authentication.** An address, a domain or even a reply token identifies a
+ * sender to some degree; none of them authenticates a person. Assurance therefore GATES what a handler
+ * accepts (a handler declares the minimum it will act on) and grants NO authority: the handler acts
+ * with the roles it declares, whoever wrote.
+ *
+ * spec-cite: NIST SP 800-63B rev. 4 §3.1.3.1 ("Email SHALL NOT be used for out-of-band authentication");
+ * RFC 7489 §3.1 (DMARC authenticates the RFC5322.From DOMAIN by alignment with an authenticated
+ * identifier, not the person). Both as recorded in #1630's decisions log, 2026-09-25.
+ *
+ * **Ordered only within a channel.** Each channel has its own ladder ({@link INBOUND_SENDER_ASSURANCE_LADDERS});
+ * a signed webhook is not "more" or "less" than a domain-aligned email, so there is no total order and
+ * comparing across channels is refused.
+ */
+export var InboundSenderAssurance;
+(function (InboundSenderAssurance) {
+    /** Nothing about the sender verified. The floor of every ladder. */
+    InboundSenderAssurance["UNVERIFIED"] = "unverified";
+    /** WEBHOOK: the delivery carried a valid signature under the source's secret. Identifies the SOURCE system. */
+    InboundSenderAssurance["SOURCE_SIGNED"] = "source_signed";
+    /** EMAIL: DMARC passed and is aligned with the `From` domain — the domain, not the mailbox, is authenticated. */
+    InboundSenderAssurance["DOMAIN_ALIGNED"] = "domain_aligned";
+    /**
+     * EMAIL: domain-aligned, and the address is known to the routed organization — a verified member, or a
+     * contact the application's resolver recognises.
+     */
+    InboundSenderAssurance["KNOWN_CONTACT"] = "known_contact";
+    /**
+     * EMAIL: domain-aligned, arrived on an unrevoked reply token the application issued for this thread,
+     * and `From` is the address that token was issued to.
+     */
+    InboundSenderAssurance["THREAD_TOKEN_BOUND"] = "thread_token_bound";
+})(InboundSenderAssurance || (InboundSenderAssurance = {}));
+/**
+ * Each channel's ladder, lowest first. Total over {@link InboundChannelKind}: a channel added without a
+ * ladder does not compile.
+ */
+export const INBOUND_SENDER_ASSURANCE_LADDERS = {
+    [InboundChannelKind.EMAIL]: [
+        InboundSenderAssurance.UNVERIFIED,
+        InboundSenderAssurance.DOMAIN_ALIGNED,
+        InboundSenderAssurance.KNOWN_CONTACT,
+        InboundSenderAssurance.THREAD_TOKEN_BOUND,
+    ],
+    [InboundChannelKind.WEBHOOK]: [InboundSenderAssurance.UNVERIFIED, InboundSenderAssurance.SOURCE_SIGNED],
+};
+/** Thrown when an assurance level is asked about on a channel whose ladder does not contain it. */
+export class InboundSenderAssuranceChannelError extends Error {
+    constructor(channel, level) {
+        super(`Sender assurance '${level}' is not on the ${channel} channel's ladder; assurance is compared only within one channel`);
+        this.name = 'InboundSenderAssuranceChannelError';
+    }
+}
+/**
+ * The rank of `level` on `channel`'s ladder, 0 for the floor.
+ *
+ * The type admits only that channel's levels, so `senderAssuranceRank(InboundChannelKind.WEBHOOK,
+ * InboundSenderAssurance.DOMAIN_ALIGNED)` does not compile; a value that reached here untyped (a stored
+ * row, a JSON payload) and is not on the ladder throws rather than ranking as anything.
+ */
+export function senderAssuranceRank(channel, level) {
+    const ladder = INBOUND_SENDER_ASSURANCE_LADDERS[channel];
+    const rank = ladder.indexOf(level);
+    if (rank < 0)
+        throw new InboundSenderAssuranceChannelError(channel, level);
+    return rank;
+}
+/** Whether `level` is at least `minimum`, both on `channel`'s ladder. */
+export function meetsMinimumSenderAssurance(channel, level, minimum) {
+    return senderAssuranceRank(channel, level) >= senderAssuranceRank(channel, minimum);
+}
+/** Whether `level` is a level of `channel` — for narrowing a value read back from storage. */
+export function isSenderAssuranceOf(channel, level) {
+    return INBOUND_SENDER_ASSURANCE_LADDERS[channel].includes(level);
+}
+/**
+ * Whether a channel handler answers, and how. Required on every handler, with no default: a handler
+ * that answers and one that does not are different programs, and the type system knows which one it
+ * is holding (`ctx.reply` exists only under {@link InboundReplyMode.THREAD}).
+ */
+export var InboundReplyMode;
+(function (InboundReplyMode) {
+    /** Replies go back on the thread the message arrived on, through the channel's outbound path. */
+    InboundReplyMode["THREAD"] = "thread";
+    /** The handler never answers. Every endpoint handler (#1596) and billing declare this. */
+    InboundReplyMode["NONE"] = "none";
+})(InboundReplyMode || (InboundReplyMode = {}));
+/**
+ * What happened to a channel message whose sender assurance is below the selected handler's minimum
+ * (#1630). A below-minimum message never reaches the main handler (I11). What it causes instead is the
+ * application's binding: a declared below-minimum handler, or nothing but storage and an audit row.
+ */
+export var InboundBelowMinimumDisposition;
+(function (InboundBelowMinimumDisposition) {
+    /** The handler declared a below-minimum handler, and the message was dispatched to it instead. */
+    InboundBelowMinimumDisposition["ROUTED_TO_BELOW_MINIMUM_HANDLER"] = "routed_to_below_minimum_handler";
+    /** No below-minimum handler: stored in its channel record and audited, and dispatched to nobody. */
+    InboundBelowMinimumDisposition["STORED_NOT_DISPATCHED"] = "stored_not_dispatched";
+})(InboundBelowMinimumDisposition || (InboundBelowMinimumDisposition = {}));
+// ─────────────────────────────────────────────────────────────────────────────
+// EMAIL: deriving sender assurance
+// ─────────────────────────────────────────────────────────────────────────────
+/** What the routed organization knows about a sender's address. */
+export var EmailSenderContactMatch;
+(function (EmailSenderContactMatch) {
+    /** Neither a member nor a contact the application recognises. */
+    EmailSenderContactMatch["NONE"] = "none";
+    /** A verified, active member of the routed organization (engine-known; sets `memberUserId`). */
+    EmailSenderContactMatch["ORGANIZATION_MEMBER"] = "organization_member";
+    /** The application's contact resolver answered true. The engine keeps no contacts of its own. */
+    EmailSenderContactMatch["APPLICATION_CONTACT"] = "application_contact";
+})(EmailSenderContactMatch || (EmailSenderContactMatch = {}));
+/** How the reply token a message arrived on (if any) relates to its sender. */
+export var EmailReplyTokenSenderMatch;
+(function (EmailReplyTokenSenderMatch) {
+    /** The message did not arrive on a live token of the routed organization. */
+    EmailReplyTokenSenderMatch["NO_TOKEN"] = "no_token";
+    /** A live token, and `From` is the address it was issued to. */
+    EmailReplyTokenSenderMatch["MATCHES_RECIPIENT"] = "matches_recipient";
+    /** A live token, `From` is on the recipient's domain but is another mailbox. */
+    EmailReplyTokenSenderMatch["OTHER_ADDRESS_SAME_DOMAIN"] = "other_address_same_domain";
+    /** A live token, `From` is on another domain than the address it was issued to. */
+    EmailReplyTokenSenderMatch["OTHER_DOMAIN"] = "other_domain";
+})(EmailReplyTokenSenderMatch || (EmailReplyTokenSenderMatch = {}));
+/** Why a live reply token did not bind its message — recorded on `INBOUND_REPLY_TOKEN_DOWNGRADED`. */
+export var ReplyTokenDowngradeReason;
+(function (ReplyTokenDowngradeReason) {
+    /** `From` is not the address the token was issued to, though on its domain. */
+    ReplyTokenDowngradeReason["SENDER_ADDRESS_MISMATCH"] = "sender_address_mismatch";
+    /** `From` is on another domain than the address the token was issued to — the case a leaked token looks like. */
+    ReplyTokenDowngradeReason["SENDER_DOMAIN_MISMATCH"] = "sender_domain_mismatch";
+    /** The token is live but DMARC did not pass aligned, so the `From` domain itself is unauthenticated. */
+    ReplyTokenDowngradeReason["DOMAIN_NOT_ALIGNED"] = "domain_not_aligned";
+})(ReplyTokenDowngradeReason || (ReplyTokenDowngradeReason = {}));
+/** DMARC passed AND aligned with the `From` domain — the one fact every level above the floor rests on. */
+export function isEmailDomainAligned(authentication) {
+    return authentication.dmarc === EmailAuthenticationVerdict.PASS && authentication.dmarcAligned;
+}
+/**
+ * Derive an email's sender assurance. PURE: every input is a fact the engine established (the
+ * provider's authentication results, a member or contact lookup, a token lookup).
+ *
+ * - `UNVERIFIED`: DMARC did not pass aligned with `From`. Nothing below is consulted: a token or a
+ *   known address on an unauthenticated domain proves nothing, since anyone can write that `From`.
+ * - `THREAD_TOKEN_BOUND`: aligned, and the message arrived on a live token issued to `From`.
+ * - `KNOWN_CONTACT`: aligned, and the address is a member or a recognised contact.
+ * - `DOMAIN_ALIGNED`: aligned, and nothing more is known.
+ *
+ * A live token that did not bind — `From` is someone else, or the domain did not align — falls back to
+ * the level the rest derives and reports why in `tokenDowngrade`, which the caller audits.
+ */
+export function deriveEmailSenderAssurance(input) {
+    const aligned = isEmailDomainAligned(input.authentication);
+    if (!aligned) {
+        return input.tokenMatch === EmailReplyTokenSenderMatch.NO_TOKEN
+            ? { assurance: InboundSenderAssurance.UNVERIFIED }
+            : { assurance: InboundSenderAssurance.UNVERIFIED, tokenDowngrade: ReplyTokenDowngradeReason.DOMAIN_NOT_ALIGNED };
+    }
+    if (input.tokenMatch === EmailReplyTokenSenderMatch.MATCHES_RECIPIENT) {
+        return { assurance: InboundSenderAssurance.THREAD_TOKEN_BOUND };
+    }
+    const assurance = input.contactMatch === EmailSenderContactMatch.NONE
+        ? InboundSenderAssurance.DOMAIN_ALIGNED
+        : InboundSenderAssurance.KNOWN_CONTACT;
+    switch (input.tokenMatch) {
+        case EmailReplyTokenSenderMatch.NO_TOKEN: return { assurance };
+        case EmailReplyTokenSenderMatch.OTHER_ADDRESS_SAME_DOMAIN: return { assurance, tokenDowngrade: ReplyTokenDowngradeReason.SENDER_ADDRESS_MISMATCH };
+        case EmailReplyTokenSenderMatch.OTHER_DOMAIN: return { assurance, tokenDowngrade: ReplyTokenDowngradeReason.SENDER_DOMAIN_MISMATCH };
+        default: {
+            const unhandled = input.tokenMatch;
+            return unhandled;
+        }
+    }
+}
+/** The domain of an address, lower-cased; `undefined` when there is no `@`. */
+export function emailAddressDomain(address) {
+    const at = address.lastIndexOf('@');
+    return at < 0 ? undefined : address.slice(at + 1).trim().toLowerCase();
+}
+/**
+ * Whether two addresses are on the same domain. An address with no domain shares a domain with nothing —
+ * not even another address with no domain — so a malformed `From` can never pass as a colleague's.
+ */
+export function emailAddressesShareDomain(first, second) {
+    const domain = emailAddressDomain(first);
+    return domain !== undefined && domain.length > 0 && domain === emailAddressDomain(second);
+}
+/** How `from` relates to the address a reply token was issued to. Addresses compare case-insensitively. */
+export function matchReplyTokenSender(from, recipient) {
+    if (from.trim().toLowerCase() === recipient.trim().toLowerCase())
+        return EmailReplyTokenSenderMatch.MATCHES_RECIPIENT;
+    return emailAddressesShareDomain(from, recipient)
+        ? EmailReplyTokenSenderMatch.OTHER_ADDRESS_SAME_DOMAIN
+        : EmailReplyTokenSenderMatch.OTHER_DOMAIN;
+}
+/**
+ * One RFC 5322 `msg-id` — angle brackets, one `@`, no whitespace and no CR/LF. The one check for a
+ * Message-ID wherever the engine reads one from a sender (`In-Reply-To`, `References`) or writes one into
+ * a header, so a value that could inject a header or break threading is dropped where it arrives.
+ */
+export const EMAIL_MESSAGE_ID_PATTERN = /^<[^<>\s@]+@[^<>\s@]+>$/;
+export function isEmailMessageId(value) {
+    return typeof value === 'string' && EMAIL_MESSAGE_ID_PATTERN.test(value);
+}
+/**
+ * What an inbound handler's `ref` looks like: lower-case, dot-separated segments of `[a-z0-9-]`
+ * (`todos.intake`, `matters.mail-intake`). One definition for the backend's `inboundHandlerRef()`, which
+ * refuses anything else at module load, and for a build plan naming the handler a task produces.
+ */
+export const INBOUND_HANDLER_REF_PATTERN = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*$/;
+/** @wildo_source:part:end saas.models.inbound-channels */
+//# sourceMappingURL=inbound-channels.shared.schemas.js.map

package/dist/esm/inbound/inbound-channels.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound-channels.shared.schemas.js","sourceRoot":"","sources":["../../../../src/inbound/inbound-channels.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Inbound channels — the vocabulary of HOW a message reached the application, how much is known about\n * who sent it, and whether and how the handler answers (#1630).\n *\n * A CHANNEL is what the message arrived on, not who carried it. `EMAIL` is a channel an application\n * declares a handler for; the provider that hosts the receiving domain is the application's\n * `EMAIL_INBOUND` selection and is never named by a handler. `WEBHOOK` is the channel of every\n * delivery #1596's endpoint sources receive, and is DERIVED for those rows, never declared.\n *\n * @see engine/saas-models/src/inbound/inbound-delivery.shared.schemas.ts — the durable delivery these\n *   channels feed.\n */\nimport { EmailAuthenticationVerdict, type StandardInboundEmail_Authentication } from '@wildo-ai/external-connectors-models';\n\n/** @wildo_source:part:start saas.models.inbound-channels facet:layer:shared facet:family:inbound facet:audience:app-developer */\n\n/**\n * What a message arrived on.\n *\n * SMS, chat and Slack join this vocabulary when a provider can fill them — a channel nothing can\n * receive on is a slot no configuration can satisfy.\n */\nexport enum InboundChannelKind {\n  /** Email received through the application's `EMAIL_INBOUND` provider and routed to an organization. */\n  EMAIL = 'email',\n  /**\n   * A signed HTTP delivery from another system (#1596). Derived for provider and application endpoint\n   * deliveries; a handler never declares it.\n   */\n  WEBHOOK = 'webhook',\n}\n\n/**\n * How much is known about who SENT a message.\n *\n * **Identification, never authentication.** An address, a domain or even a reply token identifies a\n * sender to some degree; none of them authenticates a person. Assurance therefore GATES what a handler\n * accepts (a handler declares the minimum it will act on) and grants NO authority: the handler acts\n * with the roles it declares, whoever wrote.\n *\n * spec-cite: NIST SP 800-63B rev. 4 §3.1.3.1 (\"Email SHALL NOT be used for out-of-band authentication\");\n * RFC 7489 §3.1 (DMARC authenticates the RFC5322.From DOMAIN by alignment with an authenticated\n * identifier, not the person). Both as recorded in #1630's decisions log, 2026-09-25.\n *\n * **Ordered only within a channel.** Each channel has its own ladder ({@link INBOUND_SENDER_ASSURANCE_LADDERS});\n * a signed webhook is not \"more\" or \"less\" than a domain-aligned email, so there is no total order and\n * comparing across channels is refused.\n */\nexport enum InboundSenderAssurance {\n  /** Nothing about the sender verified. The floor of every ladder. */\n  UNVERIFIED = 'unverified',\n  /** WEBHOOK: the delivery carried a valid signature under the source's secret. Identifies the SOURCE system. */\n  SOURCE_SIGNED = 'source_signed',\n  /** EMAIL: DMARC passed and is aligned with the `From` domain — the domain, not the mailbox, is authenticated. */\n  DOMAIN_ALIGNED = 'domain_aligned',\n  /**\n   * EMAIL: domain-aligned, and the address is known to the routed organization — a verified member, or a\n   * contact the application's resolver recognises.\n   */\n  KNOWN_CONTACT = 'known_contact',\n  /**\n   * EMAIL: domain-aligned, arrived on an unrevoked reply token the application issued for this thread,\n   * and `From` is the address that token was issued to.\n   */\n  THREAD_TOKEN_BOUND = 'thread_token_bound',\n}\n\n/** The assurance levels meaningful on each channel — the type a channel's ladder and minimum are drawn from. */\nexport interface InboundSenderAssuranceByChannel {\n  [InboundChannelKind.EMAIL]:\n    | InboundSenderAssurance.UNVERIFIED\n    | InboundSenderAssurance.DOMAIN_ALIGNED\n    | InboundSenderAssurance.KNOWN_CONTACT\n    | InboundSenderAssurance.THREAD_TOKEN_BOUND;\n  [InboundChannelKind.WEBHOOK]: InboundSenderAssurance.UNVERIFIED | InboundSenderAssurance.SOURCE_SIGNED;\n}\n\n/** An assurance level of channel `C`. `SenderAssuranceOf<EMAIL>` does not admit `SOURCE_SIGNED`. */\nexport type SenderAssuranceOf<C extends InboundChannelKind> = InboundSenderAssuranceByChannel[C];\n\n/**\n * Each channel's ladder, lowest first. Total over {@link InboundChannelKind}: a channel added without a\n * ladder does not compile.\n */\nexport const INBOUND_SENDER_ASSURANCE_LADDERS: { readonly [C in InboundChannelKind]: readonly SenderAssuranceOf<C>[] } = {\n  [InboundChannelKind.EMAIL]: [\n    InboundSenderAssurance.UNVERIFIED,\n    InboundSenderAssurance.DOMAIN_ALIGNED,\n    InboundSenderAssurance.KNOWN_CONTACT,\n    InboundSenderAssurance.THREAD_TOKEN_BOUND,\n  ],\n  [InboundChannelKind.WEBHOOK]: [InboundSenderAssurance.UNVERIFIED, InboundSenderAssurance.SOURCE_SIGNED],\n};\n\n/** Thrown when an assurance level is asked about on a channel whose ladder does not contain it. */\nexport class InboundSenderAssuranceChannelError extends Error {\n  constructor(channel: InboundChannelKind, level: InboundSenderAssurance) {\n    super(`Sender assurance '${level}' is not on the ${channel} channel's ladder; assurance is compared only within one channel`);\n    this.name = 'InboundSenderAssuranceChannelError';\n  }\n}\n\n/**\n * The rank of `level` on `channel`'s ladder, 0 for the floor.\n *\n * The type admits only that channel's levels, so `senderAssuranceRank(InboundChannelKind.WEBHOOK,\n * InboundSenderAssurance.DOMAIN_ALIGNED)` does not compile; a value that reached here untyped (a stored\n * row, a JSON payload) and is not on the ladder throws rather than ranking as anything.\n */\nexport function senderAssuranceRank<C extends InboundChannelKind>(channel: C, level: SenderAssuranceOf<C>): number {\n  const ladder = INBOUND_SENDER_ASSURANCE_LADDERS[channel] as readonly InboundSenderAssurance[];\n  const rank = ladder.indexOf(level);\n  if (rank < 0) throw new InboundSenderAssuranceChannelError(channel, level);\n  return rank;\n}\n\n/** Whether `level` is at least `minimum`, both on `channel`'s ladder. */\nexport function meetsMinimumSenderAssurance<C extends InboundChannelKind>(channel: C, level: SenderAssuranceOf<C>, minimum: SenderAssuranceOf<C>): boolean {\n  return senderAssuranceRank(channel, level) >= senderAssuranceRank(channel, minimum);\n}\n\n/** Whether `level` is a level of `channel` — for narrowing a value read back from storage. */\nexport function isSenderAssuranceOf<C extends InboundChannelKind>(channel: C, level: InboundSenderAssurance): level is SenderAssuranceOf<C> {\n  return (INBOUND_SENDER_ASSURANCE_LADDERS[channel] as readonly InboundSenderAssurance[]).includes(level);\n}\n\n/**\n * Whether a channel handler answers, and how. Required on every handler, with no default: a handler\n * that answers and one that does not are different programs, and the type system knows which one it\n * is holding (`ctx.reply` exists only under {@link InboundReplyMode.THREAD}).\n */\nexport enum InboundReplyMode {\n  /** Replies go back on the thread the message arrived on, through the channel's outbound path. */\n  THREAD = 'thread',\n  /** The handler never answers. Every endpoint handler (#1596) and billing declare this. */\n  NONE = 'none',\n}\n\n/**\n * What happened to a channel message whose sender assurance is below the selected handler's minimum\n * (#1630). A below-minimum message never reaches the main handler (I11). What it causes instead is the\n * application's binding: a declared below-minimum handler, or nothing but storage and an audit row.\n */\nexport enum InboundBelowMinimumDisposition {\n  /** The handler declared a below-minimum handler, and the message was dispatched to it instead. */\n  ROUTED_TO_BELOW_MINIMUM_HANDLER = 'routed_to_below_minimum_handler',\n  /** No below-minimum handler: stored in its channel record and audited, and dispatched to nobody. */\n  STORED_NOT_DISPATCHED = 'stored_not_dispatched',\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// EMAIL: deriving sender assurance\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** What the routed organization knows about a sender's address. */\nexport enum EmailSenderContactMatch {\n  /** Neither a member nor a contact the application recognises. */\n  NONE = 'none',\n  /** A verified, active member of the routed organization (engine-known; sets `memberUserId`). */\n  ORGANIZATION_MEMBER = 'organization_member',\n  /** The application's contact resolver answered true. The engine keeps no contacts of its own. */\n  APPLICATION_CONTACT = 'application_contact',\n}\n\n/** How the reply token a message arrived on (if any) relates to its sender. */\nexport enum EmailReplyTokenSenderMatch {\n  /** The message did not arrive on a live token of the routed organization. */\n  NO_TOKEN = 'no_token',\n  /** A live token, and `From` is the address it was issued to. */\n  MATCHES_RECIPIENT = 'matches_recipient',\n  /** A live token, `From` is on the recipient's domain but is another mailbox. */\n  OTHER_ADDRESS_SAME_DOMAIN = 'other_address_same_domain',\n  /** A live token, `From` is on another domain than the address it was issued to. */\n  OTHER_DOMAIN = 'other_domain',\n}\n\n/** Why a live reply token did not bind its message — recorded on `INBOUND_REPLY_TOKEN_DOWNGRADED`. */\nexport enum ReplyTokenDowngradeReason {\n  /** `From` is not the address the token was issued to, though on its domain. */\n  SENDER_ADDRESS_MISMATCH = 'sender_address_mismatch',\n  /** `From` is on another domain than the address the token was issued to — the case a leaked token looks like. */\n  SENDER_DOMAIN_MISMATCH = 'sender_domain_mismatch',\n  /** The token is live but DMARC did not pass aligned, so the `From` domain itself is unauthenticated. */\n  DOMAIN_NOT_ALIGNED = 'domain_not_aligned',\n}\n\n/** The inputs {@link deriveEmailSenderAssurance} reads. All of them are facts, never answers a sender gave. */\nexport interface EmailSenderAssuranceInput {\n  readonly authentication: StandardInboundEmail_Authentication;\n  readonly contactMatch: EmailSenderContactMatch;\n  readonly tokenMatch: EmailReplyTokenSenderMatch;\n}\n\nexport interface EmailSenderAssuranceDerivation {\n  readonly assurance: SenderAssuranceOf<InboundChannelKind.EMAIL>;\n  /** Set when a live token arrived and did not bind the message; the caller audits it. */\n  readonly tokenDowngrade?: ReplyTokenDowngradeReason;\n}\n\n/** DMARC passed AND aligned with the `From` domain — the one fact every level above the floor rests on. */\nexport function isEmailDomainAligned(authentication: StandardInboundEmail_Authentication): boolean {\n  return authentication.dmarc === EmailAuthenticationVerdict.PASS && authentication.dmarcAligned;\n}\n\n/**\n * Derive an email's sender assurance. PURE: every input is a fact the engine established (the\n * provider's authentication results, a member or contact lookup, a token lookup).\n *\n * - `UNVERIFIED`: DMARC did not pass aligned with `From`. Nothing below is consulted: a token or a\n *   known address on an unauthenticated domain proves nothing, since anyone can write that `From`.\n * - `THREAD_TOKEN_BOUND`: aligned, and the message arrived on a live token issued to `From`.\n * - `KNOWN_CONTACT`: aligned, and the address is a member or a recognised contact.\n * - `DOMAIN_ALIGNED`: aligned, and nothing more is known.\n *\n * A live token that did not bind — `From` is someone else, or the domain did not align — falls back to\n * the level the rest derives and reports why in `tokenDowngrade`, which the caller audits.\n */\nexport function deriveEmailSenderAssurance(input: EmailSenderAssuranceInput): EmailSenderAssuranceDerivation {\n  const aligned = isEmailDomainAligned(input.authentication);\n  if (!aligned) {\n    return input.tokenMatch === EmailReplyTokenSenderMatch.NO_TOKEN\n      ? { assurance: InboundSenderAssurance.UNVERIFIED }\n      : { assurance: InboundSenderAssurance.UNVERIFIED, tokenDowngrade: ReplyTokenDowngradeReason.DOMAIN_NOT_ALIGNED };\n  }\n  if (input.tokenMatch === EmailReplyTokenSenderMatch.MATCHES_RECIPIENT) {\n    return { assurance: InboundSenderAssurance.THREAD_TOKEN_BOUND };\n  }\n  const assurance = input.contactMatch === EmailSenderContactMatch.NONE\n    ? InboundSenderAssurance.DOMAIN_ALIGNED\n    : InboundSenderAssurance.KNOWN_CONTACT;\n  switch (input.tokenMatch) {\n    case EmailReplyTokenSenderMatch.NO_TOKEN: return { assurance };\n    case EmailReplyTokenSenderMatch.OTHER_ADDRESS_SAME_DOMAIN: return { assurance, tokenDowngrade: ReplyTokenDowngradeReason.SENDER_ADDRESS_MISMATCH };\n    case EmailReplyTokenSenderMatch.OTHER_DOMAIN: return { assurance, tokenDowngrade: ReplyTokenDowngradeReason.SENDER_DOMAIN_MISMATCH };\n    default: {\n      const unhandled: never = input.tokenMatch;\n      return unhandled;\n    }\n  }\n}\n\n/** The domain of an address, lower-cased; `undefined` when there is no `@`. */\nexport function emailAddressDomain(address: string): string | undefined {\n  const at = address.lastIndexOf('@');\n  return at < 0 ? undefined : address.slice(at + 1).trim().toLowerCase();\n}\n\n/**\n * Whether two addresses are on the same domain. An address with no domain shares a domain with nothing —\n * not even another address with no domain — so a malformed `From` can never pass as a colleague's.\n */\nexport function emailAddressesShareDomain(first: string, second: string): boolean {\n  const domain = emailAddressDomain(first);\n  return domain !== undefined && domain.length > 0 && domain === emailAddressDomain(second);\n}\n\n/** How `from` relates to the address a reply token was issued to. Addresses compare case-insensitively. */\nexport function matchReplyTokenSender(from: string, recipient: string): Exclude<EmailReplyTokenSenderMatch, EmailReplyTokenSenderMatch.NO_TOKEN> {\n  if (from.trim().toLowerCase() === recipient.trim().toLowerCase()) return EmailReplyTokenSenderMatch.MATCHES_RECIPIENT;\n  return emailAddressesShareDomain(from, recipient)\n    ? EmailReplyTokenSenderMatch.OTHER_ADDRESS_SAME_DOMAIN\n    : EmailReplyTokenSenderMatch.OTHER_DOMAIN;\n}\n\n/**\n * One RFC 5322 `msg-id` — angle brackets, one `@`, no whitespace and no CR/LF. The one check for a\n * Message-ID wherever the engine reads one from a sender (`In-Reply-To`, `References`) or writes one into\n * a header, so a value that could inject a header or break threading is dropped where it arrives.\n */\nexport const EMAIL_MESSAGE_ID_PATTERN = /^<[^<>\\s@]+@[^<>\\s@]+>$/;\n\nexport function isEmailMessageId(value: unknown): value is string {\n  return typeof value === 'string' && EMAIL_MESSAGE_ID_PATTERN.test(value);\n}\n\n/**\n * What an inbound handler's `ref` looks like: lower-case, dot-separated segments of `[a-z0-9-]`\n * (`todos.intake`, `matters.mail-intake`). One definition for the backend's `inboundHandlerRef()`, which\n * refuses anything else at module load, and for a build plan naming the handler a task produces.\n */\nexport const INBOUND_HANDLER_REF_PATTERN = /^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)*$/;\n\n/** @wildo_source:part:end saas.models.inbound-channels */\n"]}

package/dist/esm/inbound/inbound-delivery.shared.resources-config.schemas.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Inbound delivery resource configuration — polymorphic over ORGANIZATION and APPLICATION (#1596).
+ *
+ * Operation set:
+ *   - READ / LIST / SEARCH (API)      : an administrator of the scope browses deliveries, filters by status
+ *   - CREATE / UPDATE (REPOSITORY_ONLY): the inbound pipeline and its worker only — never an HTTP surface
+ *   - DELETE / DELETE_MANY (REPOSITORY_ONLY): the retention sweep's door (#1613); no API delete, so the
+ *                                        operator's log cannot be edited
+ *   - REPLAY (custom, API)             : move ONE `DEAD` delivery back to `RECEIVED`, with a written
+ *                                        justification that is stored on the row and on the audit trail
+ *
+ * Roles mirror the outbound delivery log: the organization's administrator for its own deliveries,
+ * the application's super-administrator for application-scope ones.
+ */
+import { z } from 'zod';
+import { CoreResourceOperation } from '../resources/resources.shared.core.definitions';
+export declare enum InboundDelivery_Operations {
+    /**
+     * Put a `DEAD` delivery back to `RECEIVED` so the worker runs its handler again. Refused for any
+     * other status (a processed delivery must not run twice; an unroutable one has no scope to run in).
+     */
+    REPLAY = "replay"
+}
+/**
+ * The only thing a replay needs from the operator is WHY. The row is addressed by the route, so the
+ * body cannot name a second one.
+ */
+export declare const InboundDelivery_ReplayRequestDto: z.ZodObject<{
+    justification: z.ZodString;
+}, z.core.$strict>;
+/** LIST's page: each operation keeps its own page ceiling, so request, repository and response agree. */
+export declare function inboundDeliveryListResponseDto(variantSchema: z.ZodTypeAny): z.ZodTypeAny;
+/** SEARCH's page, at SEARCH's ceiling. */
+export declare function inboundDeliverySearchResponseDto(variantSchema: z.ZodTypeAny): z.ZodTypeAny;
+export declare const inboundDeliveryPolymorphicFactories: Record<string, import("..").ResourceConfiguration_InitializationFactory<typeof InboundDelivery_Operations, CoreResourceOperation.READ | CoreResourceOperation.UPDATE | CoreResourceOperation.DELETE | CoreResourceOperation.DELETE_MANY | CoreResourceOperation.CREATE | CoreResourceOperation.LIST | CoreResourceOperation.SEARCH, any>>;
+//# sourceMappingURL=inbound-delivery.shared.resources-config.schemas.d.ts.map

package/dist/esm/inbound/inbound-delivery.shared.resources-config.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound-delivery.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../../src/inbound/inbound-delivery.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,qBAAqB,EAEtB,MAAM,gDAAgD,CAAC;AAexD,oBAAY,0BAA0B;IACpC;;;OAGG;IACH,MAAM,WAAW;CAClB;AAED;;;GAGG;AACH,eAAO,MAAM,gCAAgC;;kBAO3C,CAAC;AAiBH,yGAAyG;AACzG,wBAAgB,8BAA8B,CAAC,aAAa,EAAE,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAKxF;AAED,0CAA0C;AAC1C,wBAAgB,gCAAgC,CAAC,aAAa,EAAE,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAK1F;AAOD,eAAO,MAAM,mCAAmC,2UAgG/C,CAAC"}