@aglyn/shared-util-email 1.0.0-beta.200 → 1.0.0-beta.202

package/src/lib/outbound-phishing-screen.d.ts

@@ -0,0 +1,248 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** One brand the screen recognizes. */
+export interface PhishingScreenBrand {
+    /** Stable id, as stored on a hold. */
+    id: string;
+    /** How staff read it. */
+    label: string;
+    /** Copy that names the brand — subject, body, sender. Case-insensitive. */
+    mention: RegExp;
+    /**
+     * Host labels that name the brand. Matched against each dot-separated
+     * label of a link's host, whole or hyphen-joined, after leetspeak is
+     * folded — never as a bare substring, which is how `amazonaws` or
+     * `bookingengine` would read as a brand.
+     */
+    hostTokens: readonly string[];
+    /**
+     * Registrable domains the brand genuinely links from. The FIRST is its
+     * primary domain, the one a kit embeds in a longer host.
+     */
+    officialDomains: readonly string[];
+    /**
+     * The brand's name is an ordinary word (`apple`, `amazon`), so a host
+     * label names the brand only when it IS the word — `apple.example.top` —
+     * and never hyphen-joined or leet-folded, which `apple-orchard-farm.com`
+     * would otherwise be.
+     */
+    wordToken?: boolean;
+    /**
+     * Whether `<brand>.<country code>` (and `<brand>.co.<cc>`) is the brand's
+     * too — true for the marketplaces that run a site per country.
+     */
+    countryDomains?: boolean;
+    /**
+     * Registrable domains the brand runs but where OTHER people's content lives —
+     * the platform's own tenant apex, where every site is `<name>.<apex>`. A
+     * host there never wears the brand as a disguise, so the lookalike rule
+     * skips it; but it is not the brand's own domain either, so a link to a
+     * neighbor's site still counts as "somewhere else" to the lure rules, and a
+     * workspace hosted there does not own the brand by being hosted there.
+     */
+    hostedDomains?: readonly string[];
+}
+export declare const PHISHING_SCREEN_BRANDS: readonly PhishingScreenBrand[];
+/**
+ * Account-action and credential phrasing — the half of a lure that asks the
+ * reader to DO something with an account. Only ever counted beside a brand
+ * AND a foreign link; alone, several of these are ordinary transactional copy.
+ */
+export declare const PHISHING_LURE_PATTERNS: readonly RegExp[];
+/** A signal the screen found. */
+export type PhishingScreenSignal = {
+    code: 'lookalike-link';
+    brand: string;
+    host: string;
+} | {
+    code: 'brand-sender';
+    brand: string;
+    fromName: string;
+} | {
+    code: 'brand-lure-link';
+    brand: string;
+    lure: string;
+    host: string;
+}
+/**
+ * A published page asks for a password, a card number or a one-time code
+ * in a field that is not one of the platform's own sign-in or checkout
+ * elements (`hosted-page-screen.ts`). Strong.
+ */
+ | {
+    code: 'credential-field';
+    field: 'password' | 'card' | 'otp';
+    label: string;
+}
+/**
+ * A published page names a brand that is not the workspace's beside a
+ * sign-in, verify or payment call to action (`hosted-page-screen.ts`).
+ * Soft.
+ */
+ | {
+    code: 'brand-action-page';
+    brand: string;
+    action: string;
+};
+export interface PhishingScreenInput {
+    subject?: string | null;
+    /** The display name in front of the sending address. */
+    fromName?: string | null;
+    /**
+     * The ADDRESS the message leaves from (AGL-3362) — a `From:` domain is a
+     * link the recipient never has to click, so its host is read by the
+     * lookalike rule exactly like a link's: mail from `support@paypa1.com` is
+     * the disguise whoever sends it. Not an own domain for the lure's "is this
+     * elsewhere" test either way; it only ever adds a lookalike signal.
+     */
+    fromAddress?: string | null;
+    replyTo?: string | readonly string[] | null;
+    preheader?: string | null;
+    /**
+     * Everything else the recipient reads or clicks: the body, the plain-text
+     * part, a design's nodes serialized — any string. Links are found by
+     * shape, so a JSON-encoded design is as readable here as HTML.
+     */
+    bodies?: readonly (string | null | undefined)[];
+    /**
+     * The workspace's own names — org, site, subdomain. A brand in one of them
+     * is the workspace's own, and `brand-sender` / `brand-lure-link` do not
+     * fire for it. The lookalike check does not consult names: a workspace
+     * NAMED "Poshmark" linking to `poshmark.id63835663.shop` is the incident.
+     */
+    ownNames?: readonly (string | null | undefined)[];
+    /**
+     * The workspace's own hosts — its subdomain on the tenant apex, custom
+     * domain, sending domain. A link to one of them, or below one, is never
+     * the "somewhere else" of a lure. Matched by host, never by registrable
+     * domain: every site's subdomain shares the tenant apex, and a link to a
+     * NEIGHBOR's site is somewhere else.
+     *
+     * Not an exemption from the lookalike check. A host shaped like
+     * `paypal-secure.com` is a lookalike whoever attached it, and a workspace
+     * that attached it has attached the disguise.
+     */
+    ownDomains?: readonly (string | null | undefined)[];
+}
+export interface PhishingScreenVerdict {
+    /** True when the message should be held for staff review. */
+    hold: boolean;
+    signals: PhishingScreenSignal[];
+}
+/** The registrable domain of a host: `a.b.evil.co.uk` → `evil.co.uk`. */
+export declare function registrableDomain(host: string): string;
+/** Every brand's real domains, for "is this link just the brand itself". */
+declare function isAnyOfficialDomain(registrable: string): boolean;
+/** The brand a host impersonates, or null. */
+export declare function lookalikeBrandForHost(host: string): PhishingScreenBrand | null;
+/** The hosts every link in the text points at, lowercased. */
+export declare function linkHostsIn(text: string): string[];
+/** Lowercased alphanumerics only, so "Wells-Fargo Advisors" contains `wellsfargo`. */
+declare function squash(text: string): string;
+/** Is this brand the workspace's own, by name or by a domain it holds? */
+declare function isOwnBrand(brand: PhishingScreenBrand, ownNames: string, ownRegistrables: ReadonlySet<string>): boolean;
+/** `squash`: lowercased alphanumerics, the form own-name matching reads. */
+export declare const squashScreenText: typeof squash;
+/** Is this brand the workspace's own, by name (squashed) or by a domain it holds? */
+export declare const isWorkspaceOwnBrand: typeof isOwnBrand;
+/** Is this registrable domain one of any listed brand's own? */
+export declare const isAnyOfficialBrandDomain: typeof isAnyOfficialDomain;
+/** Is this registrable domain a social, maps or review link merchants ordinarily carry? */
+export declare function isCommonLinkDomain(registrable: string): boolean;
+/**
+ * Screen one outbound message. See the module header for what holds and why.
+ */
+export declare function screenOutboundEmail(input: PhishingScreenInput): PhishingScreenVerdict;
+/** The brand's label for a stored id, for the staff surface. */
+export declare function phishingScreenBrandLabel(id: string): string;
+/** One line per signal, in words staff read on the review row. */
+export declare function describePhishingScreenSignals(signals: readonly PhishingScreenSignal[]): string[];
+/** A workspace younger than this many days has the soft rules applied. */
+export declare const OUTBOUND_REVIEW_YOUNG_DAYS = 14;
+/** Which tier a signal belongs to. */
+export type PhishingSignalTier = 'strong' | 'soft';
+/** The signal codes that hold for every workspace. */
+export declare const STRONG_PHISHING_SIGNAL_CODES: ReadonlySet<string>;
+export declare function phishingSignalTier(signal: {
+    code: string;
+}): PhishingSignalTier;
+/** Is a workspace of this age (days, `null` = unreadable) screened by the soft rules? */
+export declare function isYoungWorkspaceAge(ageDays: number | null | undefined): boolean;
+export interface OutboundScreenPolicy {
+    /**
+     * The workspace's age in days, or `null` when its creation date cannot be
+     * read — an org that predates the field, which is an EXISTING customer and
+     * is not young.
+     */
+    ageDays: number | null;
+    /**
+     * The recipient's own act made this message owed: a receipt for their
+     * order, a confirmation of their booking, a reset of their password. The
+     * soft rules never hold it. The lookalike rule still does — a receipt that
+     * links to a Poshmark lookalike is the disguise, not the receipt.
+     */
+    owed?: boolean;
+}
+/** The signals that HOLD under the tiers, for this workspace and message. */
+export declare function signalsThatHold<T extends {
+    code: string;
+}>(signals: readonly T[], policy: OutboundScreenPolicy): T[];
+/**
+ * The same brand, lookalike and tier logic applied to a HOST NAME a workspace
+ * asks for — a subdomain on the tenant apex, or a custom domain it attaches.
+ *
+ * Words a brand's impersonator hyphen-joins to its name. A subdomain that
+ * joins a brand's word to one of these (`booking-review`, `apple-support`,
+ * `amazon-account`) is the incident's shape even where the brand's word is
+ * an ordinary one — which the lookalike rule alone deliberately lets pass,
+ * so a salon can be `tanyas-booking` and a bakery `apple-pie-co`.
+ */
+export declare const BRAND_IMPERSONATION_WORDS: ReadonlySet<string>;
+/**
+ * The brand a requested subdomain label wears, or null.
+ *
+ * Refused for EVERY workspace, at creation and at rename — the tier is
+ * strong, because nothing is lost by asking a real bakery to pick
+ * `apple-pie-co` instead of `apple-support`, and a brand's name on our apex
+ * is a disguise that outlives every later screen. Two shapes:
+ *
+ * 1. the label is a lookalike host label ({@link lookalikeBrandForHost} on
+ *    `<label>.<apex>`): `poshmark`, `paypal-secure`, `paypa1`, `appleid`;
+ * 2. a brand's word hyphen-joined to an impersonation word
+ *    ({@link BRAND_IMPERSONATION_WORDS}): `booking-review`, `apple-support`.
+ */
+export declare function brandForSubdomainLabel(label: string, apex?: string): PhishingScreenBrand | null;
+/**
+ * The platform's own entry in {@link PHISHING_SCREEN_BRANDS} (AGL-3365). A
+ * workspace owns every other brand by carrying its name or domain; the
+ * platform's is owned only by the platform's staff, because a workspace NAMED
+ * for the platform is the cheapest disguise there is.
+ */
+export declare const PLATFORM_PHISHING_BRAND_ID = "aglyn";
+/** The platform's brand entry. */
+export declare function platformPhishingBrand(): PhishingScreenBrand;
+/**
+ * The brand a display NAME claims to speak for (AGL-3365), or null.
+ *
+ * For names a stranger reads as an identity — a marketplace publisher, a
+ * listing's title — rather than copy. A name that merely mentions a brand
+ * ("Sync for PayPal", "Bookings for Airbnb hosts") passes: that is how an
+ * integration is named. A name that pairs the brand with a claim of
+ * officialness ("PayPal Support", "Aglyn Official Plugins") is the disguise.
+ */
+export declare function brandClaimedByName(name: string): PhishingScreenBrand | null;
+export {};