@oxygen-agent/cli 1.1014.1138 → 1.1014.1219

package/node_modules/@oxygen/shared/dist/deliverability-blacklist.js

@@ -0,0 +1,118 @@
+/**
+ * `refused` (the operator answered with an error code) and `error` (no usable answer) are
+ * unknown evidence. Only NXDOMAIN from the operator's zone proves `not_listed`.
+ */
+export const DNSBL_VERDICTS = ["listed", "not_listed", "refused", "error"];
+export const BLACKLIST_CHECK_PREFIX = "blacklist.";
+const FINDING_STATUS = { listed: "fail", not_listed: "pass", refused: "unknown", error: "unknown" };
+/** One typed finding per queried zone. */
+export function blacklistFindings(results) {
+    return results.map((result) => ({
+        check: `${BLACKLIST_CHECK_PREFIX}${result.label}`,
+        status: FINDING_STATUS[result.verdict],
+        severity: "high",
+        summary: result.verdict === "listed" ? `Listed on ${result.zone}.`
+            : result.verdict === "not_listed" ? `Not listed on ${result.zone}.`
+                : `${result.zone} gave no usable answer; listing state unknown.`,
+        value: { zone: result.zone, verdict: result.verdict, codes: result.codes, error: result.error },
+    }));
+}
+/**
+ * Why a blacklist run queried no zone at all. Each is recorded as an `unknown` run, so
+ * "checked but nothing could answer" is never confused with "never checked" or "clean".
+ */
+export const BLACKLIST_UNAVAILABLE_REASONS = [
+    "dnsbl_no_queryable_zone",
+    "dnsbl_resolver_unconfigured",
+    "dnsbl_resolver_invalid",
+    "dnsbl_public_resolver_refused",
+];
+/**
+ * succeeded when every zone answered, partial when some did, failed when none did, and
+ * unknown when no zone was queried. A failure shared by every unanswered zone (for
+ * example dnsbl_resolver_unavailable) is reported as itself.
+ */
+export function blacklistRunOutcome(results, unavailable = "dnsbl_no_queryable_zone") {
+    if (!results.length)
+        return { status: "unknown", errorCode: unavailable };
+    const unanswered = results.filter((r) => r.verdict !== "listed" && r.verdict !== "not_listed");
+    if (!unanswered.length)
+        return { status: "succeeded", errorCode: null };
+    const causes = new Set(unanswered.map((r) => r.error));
+    const [cause] = causes;
+    return {
+        status: unanswered.length < results.length ? "partial" : "failed",
+        errorCode: causes.size === 1 && cause ? cause : "dnsbl_unanswered",
+    };
+}
+/**
+ * Listing starts and ends against the last KNOWN state per zone. An unknown answer
+ * changes nothing, so a refused query between two listed answers never re-fires.
+ * A listing seen on the first answered check of a subject is a start.
+ */
+export function blacklistListingTransitions(lastKnown, current) {
+    const transitions = [];
+    for (const finding of current) {
+        if (!finding.check.startsWith(BLACKLIST_CHECK_PREFIX))
+            continue;
+        const previous = lastKnown.get(finding.check);
+        const value = (finding.value ?? {});
+        const base = {
+            check: finding.check,
+            zone: typeof value.zone === "string" ? value.zone : finding.check.slice(BLACKLIST_CHECK_PREFIX.length),
+            codes: Array.isArray(value.codes) ? value.codes.filter((c) => typeof c === "string") : [],
+        };
+        if (finding.status === "fail" && previous !== "fail")
+            transitions.push({ ...base, transition: "listed" });
+        if (finding.status === "pass" && previous === "fail")
+            transitions.push({ ...base, transition: "delisted" });
+    }
+    return transitions;
+}
+/** Workflow-subscribable event for listing starts and ends (workspace-event-catalog). */
+export const DELIVERABILITY_WORKFLOW_EVENT_SOURCE = "deliverability";
+export const BLACKLIST_LISTING_CHANGED_EVENT = "blacklist_listing_changed";
+export const BLACKLIST_LISTING_CHANGED_PAYLOAD_FIELDS = [
+    "transition",
+    "subject_type",
+    "subject",
+    "zone",
+    "check",
+    "codes",
+    "run_id",
+    "occurred_at",
+];
+/**
+ * Link hosts recorded by a content-score finding (`content.links`). Accepts
+ * `{ domains: string[] }` or `{ links: Array<string | { url?, domain? }> }`; anything
+ * else yields nothing.
+ */
+export function linkDomainsFromFindingValue(value) {
+    if (!value || typeof value !== "object")
+        return [];
+    const record = value;
+    const raw = [
+        ...(Array.isArray(record.domains) ? record.domains : []),
+        ...(Array.isArray(record.links) ? record.links : []),
+    ];
+    const hosts = new Set();
+    for (const entry of raw) {
+        const candidate = typeof entry === "string" ? entry
+            : entry && typeof entry === "object" ? (entry.domain ?? entry.url) : null;
+        if (typeof candidate !== "string" || !candidate.trim())
+            continue;
+        let host = candidate.trim().toLowerCase();
+        if (/^[a-z][a-z0-9+.-]*:\/\//.test(host)) {
+            try {
+                host = new URL(host).hostname;
+            }
+            catch {
+                continue;
+            }
+        }
+        host = host.replace(/\.$/, "");
+        if (/^[a-z0-9-]+(\.[a-z0-9-]+)+$/.test(host) && !/^[0-9.]+$/.test(host))
+            hosts.add(host);
+    }
+    return [...hosts];
+}

package/node_modules/@oxygen/shared/dist/deliverability-checks.d.ts

@@ -0,0 +1,138 @@
+import type { DomainAuthenticationObservation, DomainBimiObservation } from "./domain-authentication.js";
+/** Append-only deliverability evidence: one run per check execution, typed findings, one observation per probe. */
+export declare const DELIVERABILITY_CHECK_KINDS: readonly ["dns_auth", "bimi", "tracking_cname", "blacklist", "content_score", "header_proof", "placement"];
+export type DeliverabilityCheckKind = (typeof DELIVERABILITY_CHECK_KINDS)[number];
+export declare const DELIVERABILITY_SUBJECT_TYPES: readonly ["domain", "mailbox", "copy", "placement_run"];
+export type DeliverabilitySubjectType = (typeof DELIVERABILITY_SUBJECT_TYPES)[number];
+export declare const DELIVERABILITY_TRIGGERS: readonly ["schedule", "preview", "manual", "workflow", "agent", "backfill"];
+export type DeliverabilityTrigger = (typeof DELIVERABILITY_TRIGGERS)[number];
+export declare const DELIVERABILITY_RUN_STATUSES: readonly ["succeeded", "partial", "failed", "unknown"];
+export type DeliverabilityRunStatus = (typeof DELIVERABILITY_RUN_STATUSES)[number];
+export declare const DELIVERABILITY_FINDING_STATUSES: readonly ["pass", "warn", "fail", "unknown"];
+export type DeliverabilityFindingStatus = (typeof DELIVERABILITY_FINDING_STATUSES)[number];
+export type DeliverabilityFindingSeverity = "info" | "low" | "medium" | "high";
+export declare const PLACEMENT_OBSERVATION_SOURCES: readonly ["workspace", "network", "emailguard", "zapmail", "sendkit"];
+export type PlacementObservationSource = (typeof PLACEMENT_OBSERVATION_SOURCES)[number];
+export declare const PLACEMENT_FOLDERS: readonly ["inbox", "spam", "other", "not_observed", "unknown"];
+export type PlacementFolder = (typeof PLACEMENT_FOLDERS)[number];
+export declare const PLACEMENT_TABS: readonly ["primary", "promotions", "social", "updates", "forums", "focused", "other", "unknown"];
+export type PlacementTab = (typeof PLACEMENT_TABS)[number];
+export type PlacementReceiverProvider = "google" | "microsoft" | "yahoo" | "other" | "unknown";
+/** Stable check codes: lowercase dotted segments; the last segment may name a zone, selector or rule. */
+export declare const DELIVERABILITY_CHECK_CODE: RegExp;
+export declare const DELIVERABILITY_RAW_MAX_BYTES = 65536;
+/** History older than this is pruned; the current-state projections are unaffected. */
+export declare const DELIVERABILITY_RETENTION_DAYS = 400;
+export type DeliverabilityFinding = {
+    check: string;
+    status: DeliverabilityFindingStatus;
+    severity: DeliverabilityFindingSeverity;
+    summary?: string | null;
+    value?: unknown;
+};
+export type DeliverabilityCheckRunInput = {
+    /** Retries of the same execution converge on one run. */
+    idempotencyKey: string;
+    kind: DeliverabilityCheckKind;
+    subjectType: DeliverabilitySubjectType;
+    subject: string;
+    trigger: DeliverabilityTrigger;
+    sourceRef?: string | null;
+    engine: string;
+    engineVersion?: string | null;
+    status: DeliverabilityRunStatus;
+    errorCode?: string | null;
+    credits?: number;
+    actorId?: string | null;
+    raw?: unknown;
+    startedAt: Date;
+    finishedAt?: Date | null;
+    findings: DeliverabilityFinding[];
+};
+export type DeliverabilityCheckRun = {
+    id: string;
+    kind: DeliverabilityCheckKind;
+    subjectType: DeliverabilitySubjectType;
+    subject: string;
+    trigger: DeliverabilityTrigger;
+    sourceRef: string | null;
+    engine: string;
+    engineVersion: string | null;
+    status: DeliverabilityRunStatus;
+    errorCode: string | null;
+    credits: number;
+    startedAt: string;
+    finishedAt: string | null;
+    findingCounts: Record<DeliverabilityFindingStatus, number>;
+    findings?: Array<DeliverabilityFinding & {
+        observedAt: string;
+    }>;
+    raw?: unknown;
+};
+export type PlacementObservation = {
+    id: string;
+    source: PlacementObservationSource;
+    runRef: string;
+    probeRef: string;
+    senderMailboxId: string | null;
+    senderAddress: string | null;
+    senderDomain: string | null;
+    receiverLabel: string;
+    receiverProvider: PlacementReceiverProvider;
+    receiverGateway: string | null;
+    outcome: "observed" | "not_observed" | "send_failed" | "send_unknown" | "read_blocked";
+    folder: PlacementFolder;
+    tab: PlacementTab;
+    spf: string | null;
+    dkim: string | null;
+    dmarc: string | null;
+    dkimDomain: string | null;
+    dkimSelector: string | null;
+    aligned: boolean | null;
+    sendingIp: string | null;
+    variantKey: string | null;
+    contentHash: string | null;
+    contentScore: number | null;
+    sentAt: string | null;
+    observedAt: string | null;
+    recordedAt: string;
+};
+/**
+ * One content identity for copy across tests and sources. The tenant migration backfill computes the same
+ * digest in SQL (`sha256(subject || E'\n\n' || body_text || E'\n\n' || coalesce(body_html,''))`).
+ */
+export declare function deliverabilityContentHash(copy: {
+    subject: string;
+    body_text: string;
+    body_html?: string | null;
+}): string;
+/** Typed findings from one public-DNS observation; a failed lookup yields one unknown finding. */
+export declare function domainAuthenticationFindings(observation: DomainAuthenticationObservation | null): DeliverabilityFinding[];
+/** BIMI is optional: absence warns, never fails; a published record is held to what receivers require. */
+export declare function bimiFindings(bimi: DomainBimiObservation): DeliverabilityFinding[];
+export declare const TRACKING_DOMAIN_STATUSES: readonly ["pending", "verified", "failed"];
+export type TrackingDomainVerificationStatus = (typeof TRACKING_DOMAIN_STATUSES)[number];
+/**
+ * One verification of a tracking host: its public CNAME, and whether the open-pixel endpoint answers
+ * through it. Link rewriting starts once a host is verified, so a host that resolves but does not
+ * serve the endpoint must never verify: every tracked link would break.
+ */
+export type TrackingCnameObservation = {
+    host: string;
+    expectedTarget: string;
+    /** The CNAME public DNS returned for the host; null when it has none. */
+    actualTarget: string | null;
+    cname: "match" | "mismatch" | "absent" | "unknown";
+    /** Probed only when the CNAME matches. */
+    https: {
+        state: "pass" | "fail" | "unknown" | "skipped";
+        httpStatus: number | null;
+        contentType: string | null;
+    };
+    checkedAt: string;
+};
+/** Null keeps the current status: a failed lookup or an unanswered probe is not evidence. */
+export declare function nextTrackingDomainStatus(current: TrackingDomainVerificationStatus, observation: TrackingCnameObservation): TrackingDomainVerificationStatus | null;
+export declare function trackingCnameFindings(observation: TrackingCnameObservation): DeliverabilityFinding[];
+/** Bounded raw evidence: oversized payloads keep a marker instead of failing the write. */
+export declare function boundedDeliverabilityRaw(raw: unknown): unknown;

package/node_modules/@oxygen/shared/dist/deliverability-checks.js

@@ -0,0 +1,124 @@
+import { createHash } from "node:crypto";
+/** Append-only deliverability evidence: one run per check execution, typed findings, one observation per probe. */
+export const DELIVERABILITY_CHECK_KINDS = ["dns_auth", "bimi", "tracking_cname", "blacklist", "content_score", "header_proof", "placement"];
+export const DELIVERABILITY_SUBJECT_TYPES = ["domain", "mailbox", "copy", "placement_run"];
+export const DELIVERABILITY_TRIGGERS = ["schedule", "preview", "manual", "workflow", "agent", "backfill"];
+export const DELIVERABILITY_RUN_STATUSES = ["succeeded", "partial", "failed", "unknown"];
+export const DELIVERABILITY_FINDING_STATUSES = ["pass", "warn", "fail", "unknown"];
+export const PLACEMENT_OBSERVATION_SOURCES = ["workspace", "network", "emailguard", "zapmail", "sendkit"];
+export const PLACEMENT_FOLDERS = ["inbox", "spam", "other", "not_observed", "unknown"];
+export const PLACEMENT_TABS = ["primary", "promotions", "social", "updates", "forums", "focused", "other", "unknown"];
+/** Stable check codes: lowercase dotted segments; the last segment may name a zone, selector or rule. */
+export const DELIVERABILITY_CHECK_CODE = /^[a-z0-9_]+(\.[A-Za-z0-9_-]+)*$/;
+export const DELIVERABILITY_RAW_MAX_BYTES = 65_536;
+/** History older than this is pruned; the current-state projections are unaffected. */
+export const DELIVERABILITY_RETENTION_DAYS = 400;
+/**
+ * One content identity for copy across tests and sources. The tenant migration backfill computes the same
+ * digest in SQL (`sha256(subject || E'\n\n' || body_text || E'\n\n' || coalesce(body_html,''))`).
+ */
+export function deliverabilityContentHash(copy) {
+    return createHash("sha256").update(`${copy.subject}\n\n${copy.body_text}\n\n${copy.body_html ?? ""}`, "utf8").digest("hex");
+}
+const DNS_STATUS = { configured: "pass", issues: "fail", unknown: "unknown" };
+const DNS_SEVERITY = { spf: "high", dkim: "high", dmarc: "high", mx: "medium", nameservers: "low" };
+/** Typed findings from one public-DNS observation; a failed lookup yields one unknown finding. */
+export function domainAuthenticationFindings(observation) {
+    if (!observation)
+        return [{ check: "dns_auth.lookup", status: "unknown", severity: "medium", summary: "Public DNS could not be read." }];
+    const findings = Object.entries(observation.checks ?? {}).map(([name, check]) => ({
+        check: `dns_auth.${name}`,
+        status: DNS_STATUS[check.state] ?? "unknown",
+        severity: DNS_SEVERITY[name] ?? "low",
+        summary: check.summary,
+        value: { records: check.records, next_action: check.nextAction },
+    }));
+    findings.push({ check: "dns_auth.dmarc_policy", status: observation.dmarcPolicy == null ? "unknown" : observation.dmarcPolicy === "none" ? "warn" : "pass",
+        severity: "medium", value: { policy: observation.dmarcPolicy ?? null, policy_domain: observation.dmarcPolicyDomain ?? null } });
+    findings.push({ check: "dns_auth.spf_lookup_budget",
+        status: !observation.spfLookupComplete || observation.spfLookupTerms == null ? "unknown" : observation.spfLookupTerms > 10 ? "fail" : observation.spfLookupTerms > 8 ? "warn" : "pass",
+        severity: "high", value: { lookup_terms: observation.spfLookupTerms ?? null, complete: observation.spfLookupComplete ?? false } });
+    for (const selector of observation.dkimSelectors ?? [])
+        findings.push({ check: `dns_auth.dkim_selector.${selector.replace(/[^A-Za-z0-9_-]/g, "_")}`, status: "pass", severity: "info", value: { selector } });
+    return findings;
+}
+const isHttps = (url) => {
+    try {
+        return new URL(url).protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+};
+/** BIMI is optional: absence warns, never fails; a published record is held to what receivers require. */
+export function bimiFindings(bimi) {
+    const value = { domain: bimi.domain ?? null, record: bimi.record, logo_url: bimi.logoUrl, authority_url: bimi.authorityUrl, declined: bimi.declined };
+    if (bimi.state === "unknown")
+        return [{ check: "bimi.record", status: "unknown", severity: "info", summary: "The BIMI record could not be read.", value }];
+    if (bimi.state === "absent") {
+        return [{ check: "bimi.record", status: "warn", severity: "info", summary: "No BIMI record is published for this domain or its organizational domain.", value }];
+    }
+    if (bimi.state === "invalid") {
+        return [{ check: "bimi.record", status: "fail", severity: "low", summary: "More than one BIMI record is published; receivers ignore them all.", value }];
+    }
+    if (bimi.declined)
+        return [{ check: "bimi.record", status: "pass", severity: "info", summary: "The BIMI record declines a logo.", value }];
+    const logo = bimi.logoUrl;
+    const authority = bimi.authorityUrl;
+    return [
+        { check: "bimi.record", status: "pass", severity: "info", summary: "A BIMI record is published.", value },
+        !logo
+            ? { check: "bimi.logo_url", status: "warn", severity: "low", summary: "The BIMI record names no logo.", value: { logo_url: null } }
+            : !isHttps(logo)
+                ? { check: "bimi.logo_url", status: "fail", severity: "low", summary: "The BIMI logo must be served over HTTPS.", value: { logo_url: logo } }
+                : !/\.svg$/i.test(new URL(logo).pathname)
+                    ? { check: "bimi.logo_url", status: "warn", severity: "low", summary: "The BIMI logo should be an SVG Tiny PS file.", value: { logo_url: logo } }
+                    : { check: "bimi.logo_url", status: "pass", severity: "low", summary: "The BIMI logo is an HTTPS SVG.", value: { logo_url: logo } },
+        !authority
+            ? { check: "bimi.vmc", status: "warn", severity: "low", summary: "No mark certificate is published; Gmail and Apple Mail show no logo without one.", value: { authority_url: null } }
+            : !isHttps(authority)
+                ? { check: "bimi.vmc", status: "fail", severity: "low", summary: "The mark certificate must be served over HTTPS.", value: { authority_url: authority } }
+                : { check: "bimi.vmc", status: "pass", severity: "low", summary: "A mark certificate is published; its validity is not checked.", value: { authority_url: authority } },
+    ];
+}
+export const TRACKING_DOMAIN_STATUSES = ["pending", "verified", "failed"];
+/** Null keeps the current status: a failed lookup or an unanswered probe is not evidence. */
+export function nextTrackingDomainStatus(current, observation) {
+    if (observation.cname === "unknown")
+        return null;
+    if (observation.cname !== "match")
+        return "failed";
+    if (observation.https.state === "pass")
+        return "verified";
+    if (observation.https.state === "fail")
+        return current === "verified" ? "failed" : "pending";
+    return current === "failed" ? "pending" : null;
+}
+export function trackingCnameFindings(observation) {
+    const target = { expected: observation.expectedTarget, actual: observation.actualTarget };
+    const findings = [
+        observation.cname === "unknown"
+            ? { check: "tracking_cname.target", status: "unknown", severity: "high", summary: "The tracking CNAME could not be read.", value: target }
+            : observation.cname === "match"
+                ? { check: "tracking_cname.target", status: "pass", severity: "high", summary: "The tracking CNAME points at the tracking service.", value: target }
+                : { check: "tracking_cname.target", status: "fail", severity: "high",
+                    summary: observation.cname === "absent" ? "The tracking host has no CNAME record." : "The tracking CNAME points somewhere else.", value: target },
+    ];
+    const https = observation.https;
+    if (https.state !== "skipped") {
+        const value = { http_status: https.httpStatus, content_type: https.contentType };
+        findings.push(https.state === "pass"
+            ? { check: "tracking_cname.https", status: "pass", severity: "high", summary: "The tracking endpoint answers over HTTPS on this host.", value }
+            : https.state === "fail"
+                ? { check: "tracking_cname.https", status: "fail", severity: "high", summary: "The tracking endpoint does not answer over HTTPS on this host yet.", value }
+                : { check: "tracking_cname.https", status: "unknown", severity: "high", summary: "The tracking endpoint gave no conclusive answer (no response, or a server error).", value });
+    }
+    return findings;
+}
+/** Bounded raw evidence: oversized payloads keep a marker instead of failing the write. */
+export function boundedDeliverabilityRaw(raw) {
+    if (raw === undefined || raw === null)
+        return null;
+    const text = JSON.stringify(raw);
+    return Buffer.byteLength(text, "utf8") <= DELIVERABILITY_RAW_MAX_BYTES ? raw : { truncated: true, bytes: Buffer.byteLength(text, "utf8") };
+}