@aglyn/tenant-data-admin 1.0.0-beta.200 → 1.0.0-beta.202

package/src/lib/server/outbound-send-review.d.ts

@@ -0,0 +1,224 @@
+/**
+ * @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.
+ */
+import { OUTBOUND_REVIEW_YOUNG_DAYS, type PhishingScreenInput, type PhishingScreenSignal } from '@aglyn/shared-util-email/outbound-phishing-screen';
+import { type OutboundScreenGateRequest, type OutboundScreenGateVerdict, type SendingWorkspace } from '@aglyn/shared-util-email/outbound-screen-gate';
+/** A workspace younger than this many days has the soft rules applied. */
+export { OUTBOUND_REVIEW_YOUNG_DAYS };
+/**
+ * Where a held campaign is parked: a send time no processor run reaches.
+ * A release replaces it with "now"; nothing else ever does, so a hold that
+ * nobody decides stays a hold rather than lapsing into a send.
+ */
+export declare const HELD_SEND_AT_MS = 253402300799000;
+/**
+ * Which surface held it: a campaign, an automation step, any other tenant
+ * message at the send seam (`message`), a site publish (`page`), or a
+ * submission to a public catalog a plugin keeps — a marketplace listing, its
+ * publisher profile (`listing`, AGL-3365).
+ */
+export type HeldOutboundSendKind = 'campaign' | 'action' | 'workflow' | 'orgAutomation' | 'message' | 'page' | 'listing';
+/** The decision state a held send carries on its review row. */
+export type HeldOutboundSendState = 'held' | 'released' | 'rejected';
+/** What the review row records about the message it holds. */
+export interface HeldOutboundSend {
+    kind: HeldOutboundSendKind;
+    /** The document the message came from — a send, an action, a workflow. */
+    path: string;
+    hostId: string;
+    orgId: string | null;
+    contentHash: string;
+    subject: string;
+    fromName: string | null;
+    signals: PhishingScreenSignal[];
+    state: HeldOutboundSendState;
+    heldAtMs: number;
+    /** Workspace age in days when it was held, for the reviewer. */
+    ageDays: number | null;
+}
+/**
+ * Is this workspace young enough to screen?
+ *
+ * Age alone, deliberately. Payment history was the other candidate and the
+ * incident is the argument against it: the actor PAID, on a card that never
+ * met 3-D Secure, within days of signing up. A paid invoice proves a card
+ * worked, not that its holder is who they say.
+ */
+export declare function isYoungWorkspace(org: {
+    createdAt?: unknown;
+} | null | undefined, nowMs?: number): boolean;
+/**
+ * The workspace a host's mail belongs to, as the send seam's screen reads it
+ * — stamped on the sending identity by `hostSendingIdentity` from the host
+ * and org documents it has already read.
+ */
+export declare function sendingWorkspaceFor(input: {
+    hostId: string;
+    orgId: string | null;
+    org?: Record<string, unknown> | null;
+    host?: Record<string, unknown> | null;
+    nowMs?: number;
+}): SendingWorkspace;
+/**
+ * The workspace's own names and hosts, as the screen reads them: a brand in
+ * its own name is its own, and a link to its own site is not "elsewhere".
+ */
+export declare function workspaceScreenIdentity(input: {
+    org?: Record<string, unknown> | null;
+    host?: Record<string, unknown> | null;
+}): Pick<PhishingScreenInput, 'ownNames' | 'ownDomains'>;
+/**
+ * JSON with every object's keys sorted, so the same design serializes to the
+ * same string however it was read. Firestore hands back a map's keys in an
+ * order that differs by reader, and a release keyed on a hash of an unsorted
+ * serialization would not match the very content it released.
+ */
+export declare function canonicalJson(value: unknown): string;
+/** A stable hash of what a message says, so a release covers these words only. */
+export declare function outboundContentHash(parts: readonly unknown[]): string;
+/**
+ * The review row's id: one row per (source, content). Hex, so the admin
+ * route's report-id pattern addresses it like any intake row.
+ */
+export declare function heldOutboundReviewId(path: string, contentHash: string): string;
+/** The staff-facing reference, in the intake's `AR-` style. */
+export declare function heldOutboundReference(reviewId: string): string;
+export interface OutboundScreenRequest {
+    kind: HeldOutboundSendKind;
+    path: string;
+    hostId: string;
+    orgId: string | null;
+    org: Record<string, unknown> | null;
+    host: Record<string, unknown> | null;
+    subject: string;
+    fromName?: string | null;
+    /**
+     * The address it leaves from (AGL-3362). Read by the lookalike rule only,
+     * and kept out of the content hash so a release granted before this was
+     * read still names the same row.
+     */
+    fromAddress?: string | null;
+    replyTo?: string | readonly string[] | null;
+    preheader?: string | null;
+    bodies: readonly (string | null | undefined)[];
+    nowMs?: number;
+}
+/** What a screen answers for one piece of content. */
+export type OutboundScreenOutcome = {
+    outcome: 'send';
+    /** The review row staff released this content under, when there is one. */
+    releasedReviewId?: string;
+} | {
+    outcome: 'held' | 'rejected';
+    reviewId: string;
+    reference: string;
+    contentHash: string;
+};
+/** What a surface files when its screen holds, for {@link fileOutboundHold}. */
+export interface OutboundHoldFiling {
+    reviewId: string;
+    heldSend: HeldOutboundSend;
+    /** Extra fields a surface records beside `heldSend` (a page's version). */
+    extra?: Record<string, unknown>;
+    /** The first line of the row's details, naming what was held. */
+    headline: string;
+    /** The staff alert's title and body, the first time. */
+    alertTitle: string;
+    alertBody: string;
+    /** The URL the row reports: the flagged host, or the held page. */
+    url: string | null;
+    reportedHostname: string | null;
+}
+/**
+ * Write (or count) the review row for a hold, and tell staff the first time.
+ * Returns the row's decision state — a row staff already decided answers
+ * with that decision and is not written.
+ *
+ * One writer for every surface, so a campaign, a seam message and a page
+ * land in the queue in the one shape the admin route and page already read.
+ */
+export declare function fileOutboundHold(filing: OutboundHoldFiling): Promise<HeldOutboundSendState>;
+/** The first signal that names a host, for the row's reported URL. */
+export declare function flaggedHostOf(signals: readonly PhishingScreenSignal[]): string | null;
+/**
+ * The screen's answer for one message, and what to do with it.
+ *
+ * - `send` — clean under the tiers, or held earlier and RELEASED by staff
+ *   for exactly this content (then `releasedReviewId` names the row, and the
+ *   caller hands it to `sendEmail` so the seam's screen honors it too).
+ * - `held` — hold it. The review row is written (or its count bumped) and
+ *   staff are told the first time.
+ * - `rejected` — staff rejected exactly this content. Never sent.
+ *
+ * Every workspace is screened; `signalsThatHold` applies the tiers, so an
+ * established workspace is held only by a lookalike link.
+ *
+ * Fails OPEN on a store error, the posture of every other control on the
+ * send path: an outage on the review queue must not become an outage on
+ * every workspace's mail. The screen itself cannot fail.
+ */
+export declare function screenOutboundSend(request: OutboundScreenRequest): Promise<OutboundScreenOutcome>;
+/** Test seam: forget what this process learned about seam rows. */
+export declare function resetOutboundSeamMemoForTests(): void;
+/**
+ * The seam row's id for a site and the signals that held. Keyed on the
+ * SIGNALS rather than the words: a message at the seam is already
+ * personalized per recipient, so its words differ for every person while
+ * what makes it phishing — the lookalike host, the brand and the lure — does
+ * not. A release therefore covers this site's use of exactly these signals,
+ * and a message carrying any other signal is screened afresh.
+ */
+export declare function seamReviewId(hostId: string, signals: readonly PhishingScreenSignal[]): string;
+/**
+ * The send seam's gate: what `sendEmail` asks when a tenant message carries
+ * a signal that holds (see `outbound-screen-gate.ts`). Installed at module
+ * load by {@link installOutboundScreenGate}.
+ *
+ * A seam hold REFUSES that one message (`held-for-review`) — the sender's own
+ * failure handling reports it, the way it reports a suppression — and files
+ * one row per site and signal set. Once staff release it, the site's next
+ * message carrying those signals sends; reject it, and none does.
+ */
+export declare function screenSeamMessage(request: OutboundScreenGateRequest): Promise<OutboundScreenGateVerdict>;
+/**
+ * Puts the review store on `sendEmail`'s phishing screen.
+ *
+ * **Called at module load**, from the bottom of this file, for the reason
+ * `installEmailSendGovernor` is — and this module is also imported by
+ * `sending-domains.ts`, so any sender that resolved its identity through
+ * `hostSendingIdentity` (the only thing that stamps a workspace on it, and
+ * so the only thing the seam screens) has installed it.
+ */
+export declare function installOutboundScreenGate(): void;
+/**
+ * Apply a staff decision to a held send (the admin abuse route, in the same
+ * act as the row's status change).
+ *
+ * The row's `heldSend.state` is written first: it is what the screen reads,
+ * so an automation step released here sends on its next run whatever
+ * happens to the rest. A CAMPAIGN is also put back on the clock (released)
+ * or canceled (rejected) — but only while it is still the parked send this
+ * row held: a send that has since been edited, sent or canceled by the
+ * merchant is left alone, and the answer says so.
+ */
+export declare function decideHeldOutboundSend(input: {
+    reviewId: string;
+    decision: 'release' | 'reject';
+    actorUid: string;
+    actorEmail: string | null;
+    nowMs?: number;
+    firestore?: FirebaseFirestore.Firestore;
+}): Promise<'released' | 'rejected' | 'not-held' | 'campaign-moved'>;