@oxygen-agent/cli 1.1014.1138 → 1.1014.1221

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

@@ -0,0 +1,42 @@
+import { type PlacementObservationSource } from "./deliverability-checks.js";
+/**
+ * One read contract for the stored deliverability evidence on every surface: the
+ * `/api/cli/deliverability/{checks,observations,evidence,compare,score-copy}` routes,
+ * `oxygen mailboxes deliverability …` and `oxygen_mailboxes_deliverability_*`. The
+ * enums and bounds here are the ones the routes enforce, so CLI help, MCP schemas
+ * and route validation cannot drift apart.
+ */
+export declare const DELIVERABILITY_SURFACE_DEFAULT_LIMIT = 25;
+export declare const DELIVERABILITY_SURFACE_MAX_LIMIT = 100;
+/** A check's stored raw evidence is capped at 64 KB; reads return it whole up to this size. */
+export declare const DELIVERABILITY_SURFACE_RAW_MAX_CHARS = 16000;
+export declare const DELIVERABILITY_SURFACE_EVIDENCE_DEFAULT_DAYS = 28;
+export declare const DELIVERABILITY_SURFACE_CHECK_KINDS: readonly ["dns_auth", "bimi", "tracking_cname", "blacklist", "content_score", "header_proof", "placement"];
+export declare const DELIVERABILITY_SURFACE_SUBJECT_TYPES: readonly ["domain", "mailbox", "copy", "placement_run"];
+export declare const DELIVERABILITY_SURFACE_RUN_STATUSES: readonly ["succeeded", "partial", "failed", "unknown"];
+export declare const DELIVERABILITY_SURFACE_FINDING_STATUSES: readonly ["pass", "warn", "fail", "unknown"];
+export declare const DELIVERABILITY_SURFACE_FOLDERS: readonly ["inbox", "spam", "other", "not_observed", "unknown"];
+export declare const DELIVERABILITY_SURFACE_BUCKETS: readonly ["day", "week"];
+export declare const DELIVERABILITY_SURFACE_RECEIVER_PROVIDERS: readonly ["google", "microsoft", "yahoo", "other", "unknown"];
+/**
+ * Placement sources by their public names. Managed vendor rails are branded on customer
+ * surfaces (OXYGEN_PRODUCT.md): stored `emailguard` reads as `oxygen_deliverability` and
+ * stored `sendkit` as `oxygen_placement`. Storage keeps the backend ids.
+ */
+export declare const DELIVERABILITY_SURFACE_SOURCES: readonly ["workspace", "network", "oxygen_deliverability", "zapmail", "oxygen_placement"];
+export type DeliverabilitySurfaceSource = (typeof DELIVERABILITY_SURFACE_SOURCES)[number];
+export declare function publicPlacementSource(source: PlacementObservationSource): DeliverabilitySurfaceSource;
+/** Public name to stored id; the backend ids stay accepted as hidden compatibility spellings. */
+export declare function storedPlacementSource(value: string): PlacementObservationSource | null;
+/** Query fields of each read, in the spelling all three surfaces send. */
+export declare const DELIVERABILITY_CHECK_LIST_FIELDS: readonly ["kind", "subject_type", "subject", "status", "finding_status", "since", "until", "limit", "cursor"];
+export declare const DELIVERABILITY_OBSERVATION_LIST_FIELDS: readonly ["source", "sender_domain", "sender_mailbox_id", "receiver_provider", "folder", "run_ref", "content_hash", "since", "until", "limit", "cursor"];
+export declare const DELIVERABILITY_EVIDENCE_FIELDS: readonly ["sender_domain", "sender_mailbox_id", "content_hash", "receiver_provider", "since", "until", "bucket"];
+export declare const DELIVERABILITY_SCORE_COPY_FIELDS: readonly ["subject", "body_text", "body_html", "from", "request_id"];
+/**
+ * Used as the From address when score-copy names no sender. RFC 2606 reserves the
+ * domain, so no real sender's reputation is implied; the content hash ignores From.
+ */
+export declare const DELIVERABILITY_SCORE_COPY_DEFAULT_FROM = "sender@example.com";
+/** Builds a query string from the declared fields, skipping absent and empty values. */
+export declare function deliverabilitySurfaceQuery(fields: readonly string[], values: Record<string, unknown>): string;

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

@@ -0,0 +1,66 @@
+import { DELIVERABILITY_CHECK_KINDS, DELIVERABILITY_FINDING_STATUSES, DELIVERABILITY_RUN_STATUSES, DELIVERABILITY_SUBJECT_TYPES, PLACEMENT_FOLDERS, } from "./deliverability-checks.js";
+import { DELIVERABILITY_EVIDENCE_BUCKETS } from "./deliverability-evidence.js";
+/**
+ * One read contract for the stored deliverability evidence on every surface: the
+ * `/api/cli/deliverability/{checks,observations,evidence,compare,score-copy}` routes,
+ * `oxygen mailboxes deliverability …` and `oxygen_mailboxes_deliverability_*`. The
+ * enums and bounds here are the ones the routes enforce, so CLI help, MCP schemas
+ * and route validation cannot drift apart.
+ */
+export const DELIVERABILITY_SURFACE_DEFAULT_LIMIT = 25;
+export const DELIVERABILITY_SURFACE_MAX_LIMIT = 100;
+/** A check's stored raw evidence is capped at 64 KB; reads return it whole up to this size. */
+export const DELIVERABILITY_SURFACE_RAW_MAX_CHARS = 16_000;
+export const DELIVERABILITY_SURFACE_EVIDENCE_DEFAULT_DAYS = 28;
+export const DELIVERABILITY_SURFACE_CHECK_KINDS = DELIVERABILITY_CHECK_KINDS;
+export const DELIVERABILITY_SURFACE_SUBJECT_TYPES = DELIVERABILITY_SUBJECT_TYPES;
+export const DELIVERABILITY_SURFACE_RUN_STATUSES = DELIVERABILITY_RUN_STATUSES;
+export const DELIVERABILITY_SURFACE_FINDING_STATUSES = DELIVERABILITY_FINDING_STATUSES;
+export const DELIVERABILITY_SURFACE_FOLDERS = PLACEMENT_FOLDERS;
+export const DELIVERABILITY_SURFACE_BUCKETS = DELIVERABILITY_EVIDENCE_BUCKETS;
+export const DELIVERABILITY_SURFACE_RECEIVER_PROVIDERS = ["google", "microsoft", "yahoo", "other", "unknown"];
+/**
+ * Placement sources by their public names. Managed vendor rails are branded on customer
+ * surfaces (OXYGEN_PRODUCT.md): stored `emailguard` reads as `oxygen_deliverability` and
+ * stored `sendkit` as `oxygen_placement`. Storage keeps the backend ids.
+ */
+export const DELIVERABILITY_SURFACE_SOURCES = ["workspace", "network", "oxygen_deliverability", "zapmail", "oxygen_placement"];
+const STORED_TO_PUBLIC = {
+    workspace: "workspace", network: "network", emailguard: "oxygen_deliverability", zapmail: "zapmail", sendkit: "oxygen_placement",
+};
+export function publicPlacementSource(source) {
+    return STORED_TO_PUBLIC[source] ?? source;
+}
+/** Public name to stored id; the backend ids stay accepted as hidden compatibility spellings. */
+export function storedPlacementSource(value) {
+    const normalized = value.trim().toLowerCase();
+    for (const [stored, publicName] of Object.entries(STORED_TO_PUBLIC)) {
+        if (normalized === publicName || normalized === stored)
+            return stored;
+    }
+    return null;
+}
+/** Query fields of each read, in the spelling all three surfaces send. */
+export const DELIVERABILITY_CHECK_LIST_FIELDS = ["kind", "subject_type", "subject", "status", "finding_status", "since", "until", "limit", "cursor"];
+export const DELIVERABILITY_OBSERVATION_LIST_FIELDS = [
+    "source", "sender_domain", "sender_mailbox_id", "receiver_provider", "folder", "run_ref", "content_hash", "since", "until", "limit", "cursor",
+];
+export const DELIVERABILITY_EVIDENCE_FIELDS = ["sender_domain", "sender_mailbox_id", "content_hash", "receiver_provider", "since", "until", "bucket"];
+export const DELIVERABILITY_SCORE_COPY_FIELDS = ["subject", "body_text", "body_html", "from", "request_id"];
+/**
+ * Used as the From address when score-copy names no sender. RFC 2606 reserves the
+ * domain, so no real sender's reputation is implied; the content hash ignores From.
+ */
+export const DELIVERABILITY_SCORE_COPY_DEFAULT_FROM = "sender@example.com";
+/** Builds a query string from the declared fields, skipping absent and empty values. */
+export function deliverabilitySurfaceQuery(fields, values) {
+    const params = new URLSearchParams();
+    for (const field of fields) {
+        const value = values[field];
+        if (value === undefined || value === null || value === "")
+            continue;
+        params.set(field, String(value));
+    }
+    const query = params.toString();
+    return query ? `?${query}` : "";
+}

package/node_modules/@oxygen/shared/dist/diagnostic-spool.js

@@ -135,12 +135,42 @@ async function writeDiagnosticSpool(directory, id, compressed) {
         }
     }
 }
+const uploadStripes = new Map();
 /** A fixed set of stripes bounds SQLite lock files while coordinating direct and retry owners. */
 export async function lockDiagnosticUpload(directory, id, waitMs = 0) {
-    const release = await storageStage("lock", () => acquireDiagnosticStorageLock(join(directory, `.upload-${id.slice(0, 2).toLowerCase()}.lock`), waitMs));
-    if (!release)
-        throw new StorageFailure("lock", { code: "lock_timeout" });
-    return release;
+    const path = join(directory, `.upload-${id.slice(0, 2).toLowerCase()}.lock`);
+    const deadline = performance.now() + waitMs;
+    while (true) {
+        // Unrelated records in this process share the stripe's kernel lock; only the
+        // same record or another process consumes the bounded wait. Holders keep the
+        // stripe across receipt admission, which can queue behind spool inspections.
+        let stripe = uploadStripes.get(path);
+        if (!stripe) {
+            const release = await storageStage("lock", () => acquireDiagnosticStorageLock(path));
+            if (release)
+                uploadStripes.set(path, stripe = { release, records: new Set() });
+            else
+                stripe = uploadStripes.get(path);
+        }
+        if (stripe && !stripe.records.has(id)) {
+            const held = stripe;
+            held.records.add(id);
+            let released = false;
+            return async () => {
+                if (released)
+                    return;
+                released = true;
+                held.records.delete(id);
+                if (held.records.size || uploadStripes.get(path) !== held)
+                    return;
+                uploadStripes.delete(path);
+                await held.release();
+            };
+        }
+        if (performance.now() >= deadline)
+            throw new StorageFailure("lock", { code: "lock_timeout" });
+        await new Promise(resolve => setTimeout(resolve, Math.min(20, Math.max(1, deadline - performance.now()))));
+    }
 }
 export async function readUploadProgress(directory, id, storeFingerprint) {
     const path = join(directory, `${id}.receipt.json`);

package/node_modules/@oxygen/shared/dist/domain-authentication.d.ts

@@ -13,6 +13,28 @@ export type DomainAuthenticationCheck = {
         content: string;
     }>;
 };
+/**
+ * The BIMI assertion record at `default._bimi.<domain>`. BIMI is optional: absence is the normal
+ * case and never makes a domain unhealthy. `unknown` means the lookup failed, not that it is absent.
+ */
+export type DomainBimiObservation = {
+    state: "present" | "absent" | "invalid" | "unknown";
+    /**
+     * The domain whose `default._bimi` answered last: the checked domain, or the organizational
+     * (DMARC policy) domain a receiver falls back to when the checked subdomain publishes none.
+     * Absent on observations recorded before the fallback was read.
+     */
+    domain?: string | null;
+    record: string | null;
+    /** `l=`: the SVG logo URL. */
+    logoUrl: string | null;
+    /** `a=`: the mark certificate (VMC/CMC) URL. */
+    authorityUrl: string | null;
+    /** `v=BIMI1; l=;` explicitly declines a logo. */
+    declined: boolean;
+};
+/** Parse the TXT strings at `default._bimi.<domain>`; null means the lookup failed. Non-BIMI strings are ignored. */
+export declare function parseBimiRecords(records: readonly string[] | null, domain?: string | null): DomainBimiObservation;
 export type DomainAuthenticationObservation = {
     domain: string;
     source: "public_dns";
@@ -26,6 +48,8 @@ export type DomainAuthenticationObservation = {
     spfLookupTerms: number | null;
     spfLookupComplete: boolean;
     messageAlignment: "unknown";
+    /** Absent on observations recorded before BIMI was read; never part of `state`. */
+    bimi?: DomainBimiObservation;
 };
 export type DomainAuthenticationSnapshot = {
     domain: string;

package/node_modules/@oxygen/shared/dist/domain-authentication.js

@@ -7,6 +7,26 @@ export const DOMAIN_AUTHENTICATION_CHECKS = [
     "mx",
     "nameservers",
 ];
+/** Parse the TXT strings at `default._bimi.<domain>`; null means the lookup failed. Non-BIMI strings are ignored. */
+export function parseBimiRecords(records, domain = null) {
+    const empty = { domain, record: null, logoUrl: null, authorityUrl: null, declined: false };
+    if (records === null)
+        return { state: "unknown", ...empty };
+    const bimi = records.map((record) => record.trim()).filter((record) => /^v\s*=\s*BIMI1\s*(;|$)/i.test(record));
+    if (bimi.length === 0)
+        return { state: "absent", ...empty };
+    if (bimi.length > 1)
+        return { state: "invalid", ...empty, record: bimi.join("\n") };
+    const tags = new Map();
+    for (const part of bimi[0].split(";")) {
+        const at = part.indexOf("=");
+        if (at > 0)
+            tags.set(part.slice(0, at).trim().toLowerCase(), part.slice(at + 1).trim());
+    }
+    const logoUrl = tags.get("l") || null;
+    const authorityUrl = tags.get("a") || null;
+    return { state: "present", domain, record: bimi[0], logoUrl, authorityUrl, declined: !logoUrl && !authorityUrl };
+}
 export function domainAuthenticationStale(snapshot, now = Date.now()) {
     return (!snapshot.observation ||
         now - Date.parse(snapshot.observation.checkedAt) >=

package/node_modules/@oxygen/shared/dist/file-import.js

@@ -304,17 +304,25 @@ export function createImportHeaderProjector(input) {
             keyByHeader.set(header, key);
             claimed.add(key);
         };
-        // Explicit choices and exact keys claim their columns before any alias can.
+        // Explicit choices, then exact keys, claim their columns before any alias can.
+        // A column takes one header: a later explicit choice or exact key for an
+        // already claimed column is left out, never written over the first value.
         for (const header of pending) {
             if (ignore.has(header)) {
                 skip(header, "not_selected");
                 continue;
             }
             const explicit = explicitMap[header];
-            if (explicit) {
+            if (!explicit)
+                continue;
+            if (claimed.has(explicit))
+                skip(header, "duplicate_target", explicit);
+            else
                 claim(header, explicit);
+        }
+        for (const header of pending) {
+            if (keyByHeader.has(header) || ignored.has(header))
                 continue;
-            }
             const key = exact.get(header) ?? exact.get(header.trim());
             if (key && !claimed.has(key))
                 claim(header, key);

package/node_modules/@oxygen/shared/dist/linkedin-connection-identity.d.ts

@@ -4,6 +4,22 @@ export type LinkedInConnectionIdentity = {
     profileUrl?: string | null | undefined;
     publicIdentifier?: string | null | undefined;
 };
+/**
+ * `linkedin_member_id_v1`: the people identity every LinkedIn event joins on.
+ *
+ * One namespace, the Classic profile id (`ACoAA…`), because it is the id
+ * Unipile reports for every chat attendee, relation, connection and sequence
+ * enrollment. It accepts that id bare, as a profile URN or inside a profile
+ * URL, and keeps its case: it is base64url, so a folded id names nobody.
+ *
+ * Cross-provider rule: Up2Data/Harvest numeric member ids (`urn:li:member:N`)
+ * and Sales Navigator ids (`ACwAA…`) are different values for the same person
+ * and cannot be translated without a profile read, so they normalize to "" and
+ * are never stored or matched here. A payload that carries both (a Harvest
+ * profile's `profile_urn` beside its numeric `linkedin_id`) contributes its
+ * `ACo` value — aliases only ever come from the same provider person.
+ */
+export declare function normalizeLinkedinMemberId(value: string): string;
 export declare function linkedinConnectionKeys(identity: LinkedInConnectionIdentity): string[];
 /** Return the original waiting IDs so frozen enrollment identity guards remain authoritative. */
 export declare function connectedLinkedInLeadIds(targets: LinkedInConnectionIdentity[], connections: LinkedInConnectionIdentity[]): string[];

package/node_modules/@oxygen/shared/dist/linkedin-connection-identity.js

@@ -1,7 +1,35 @@
 import { normalizeLinkedinProfileUrl, isLinkedinMemberIdHandle } from "./linkedin-url.js";
+const LINKEDIN_PROFILE_URN_PREFIX = /^urn:li:(?:fs_miniProfile|fsd_profile|member):/;
+const LINKEDIN_CLASSIC_MEMBER_ID = /^ACo[A-Za-z0-9_-]+$/;
+function stripLinkedinProfileUrn(value) {
+    return value.trim().replace(LINKEDIN_PROFILE_URN_PREFIX, "");
+}
+/**
+ * `linkedin_member_id_v1`: the people identity every LinkedIn event joins on.
+ *
+ * One namespace, the Classic profile id (`ACoAA…`), because it is the id
+ * Unipile reports for every chat attendee, relation, connection and sequence
+ * enrollment. It accepts that id bare, as a profile URN or inside a profile
+ * URL, and keeps its case: it is base64url, so a folded id names nobody.
+ *
+ * Cross-provider rule: Up2Data/Harvest numeric member ids (`urn:li:member:N`)
+ * and Sales Navigator ids (`ACwAA…`) are different values for the same person
+ * and cannot be translated without a profile read, so they normalize to "" and
+ * are never stored or matched here. A payload that carries both (a Harvest
+ * profile's `profile_urn` beside its numeric `linkedin_id`) contributes its
+ * `ACo` value — aliases only ever come from the same provider person.
+ */
+export function normalizeLinkedinMemberId(value) {
+    let id = stripLinkedinProfileUrn(value);
+    if (/linkedin\.com\//i.test(id)) {
+        const handle = normalizeLinkedinProfileUrl(id)?.dispatchHandle;
+        id = handle ? stripLinkedinProfileUrn(handle) : "";
+    }
+    return LINKEDIN_CLASSIC_MEMBER_ID.test(id) ? id : "";
+}
 export function linkedinConnectionKeys(identity) {
     const id = identity.providerId.trim();
-    const keys = id ? [`id:${id.replace(/^urn:li:(?:fs_miniProfile|fsd_profile|member):/, "")}`] : [];
+    const keys = id ? [`id:${stripLinkedinProfileUrn(id)}`] : [];
     const publicIdentifier = identity.publicIdentifier?.trim();
     const publicUrl = publicIdentifier && !/[\s/?#]/.test(publicIdentifier)
         ? `https://www.linkedin.com/in/${publicIdentifier}` : null;
@@ -29,7 +57,7 @@ export function connectedLinkedInLeadIds(targets, connections) {
     for (const connection of connections) {
         for (const key of linkedinConnectionKeys(connection)) {
             const ids = owners.get(key) ?? new Set();
-            ids.add(connection.providerId.trim().replace(/^urn:li:(?:fs_miniProfile|fsd_profile|member):/, ""));
+            ids.add(stripLinkedinProfileUrn(connection.providerId));
             owners.set(key, ids);
         }
     }

package/node_modules/@oxygen/shared/dist/network-mining.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Network Mining is DEV-only (Philipp, 2026-10-17). Unknown tiers and production-shaped data are always denied,
+ * independent of NODE_ENV; the staff flag is set in Doppler's dev config.
+ */
+export declare function networkMiningEnabled(env?: Record<string, string | undefined>): boolean;

package/node_modules/@oxygen/shared/dist/network-mining.js

@@ -0,0 +1,9 @@
+import { isProductionData } from "./deploy-env.js";
+/**
+ * Network Mining is DEV-only (Philipp, 2026-10-17). Unknown tiers and production-shaped data are always denied,
+ * independent of NODE_ENV; the staff flag is set in Doppler's dev config.
+ */
+export function networkMiningEnabled(env = process.env) {
+    return env.OXYGEN_DEPLOY_ENV === "selfhost-dev" && !isProductionData(env)
+        && env.OXYGEN_NETWORK_MINING_ENABLED === "staff";
+}

package/node_modules/@oxygen/shared/dist/received-authentication.d.ts

@@ -0,0 +1,74 @@
+import type { DeliverabilityFinding } from "./deliverability-checks.js";
+/**
+ * Receiver-side authentication proof from a received probe's headers. Only the receiving provider's
+ * own Authentication-Results row is trusted; rows from any other authserv-id (a sender, a forwarder or
+ * a forged header) are ignored. No raw header, receiver address or message id leaves this module.
+ */
+export declare const RECEIVED_AUTH_RESULTS: readonly ["pass", "fail", "softfail", "neutral", "none", "temperror", "permerror", "unknown"];
+export type ReceivedAuthResult = (typeof RECEIVED_AUTH_RESULTS)[number];
+export type ReceivedAuthProvider = "google" | "microsoft";
+export type ReceivedHeader = {
+    name: string;
+    value: string;
+};
+/** The provider header names a receiver read must request for the proof. */
+export declare const RECEIVED_AUTHENTICATION_HEADERS: readonly ["Authentication-Results", "ARC-Authentication-Results", "Received", "DKIM-Signature", "From"];
+/** PTR and forward-confirmed reverse DNS of the sending IP; `unknown` when the lookup could not be answered. */
+export type ReverseDnsProof = {
+    ip: string;
+    ptr: "pass" | "fail" | "unknown";
+    hostnames: string[];
+    fcrdns: "pass" | "fail" | "unknown";
+    confirmed_hostname: string | null;
+};
+export type ReceivedAuthentication = {
+    /** The trusted row's authserv-id; null for Exchange Online's id-less row or when nothing was trusted. */
+    authserv_id: string | null;
+    source: "authentication_results" | "arc_authentication_results" | "none";
+    spf: ReceivedAuthResult;
+    spf_domain: string | null;
+    dkim: ReceivedAuthResult;
+    dkim_domain: string | null;
+    dkim_selector: string | null;
+    dmarc: ReceivedAuthResult;
+    /** Microsoft composite authentication; null for other receivers. */
+    compauth: ReceivedAuthResult | null;
+    header_from_domain: string | null;
+    /** DMARC pass, or a DKIM pass whose d= aligns (relaxed) with the From domain; null when unproven. */
+    aligned: boolean | null;
+    /** First hop outside the receiving provider. */
+    sending_ip: string | null;
+    reverse_dns?: ReverseDnsProof;
+};
+/** Splits a raw header block (RFC 5322 section 2.2.3 folding) into ordered entries, top first. */
+export declare function parseRawHeaderBlock(raw: string): ReceivedHeader[];
+export declare function normalizeAuthDomain(value: string | null | undefined): string | null;
+/** Organizational-domain approximation without a public-suffix list (relaxed DMARC alignment). */
+export declare function organizationalDomain(domain: string): string;
+export declare const relaxedAligned: (a: string, b: string) => boolean;
+/** Lowercased IP text or null; rejects anything that is not one IPv4 or IPv6 address. */
+export declare function normalizeIp(value: string | null | undefined): string | null;
+/** Eight 16-bit groups, or null when the text is not an IPv6 address. */
+export declare function expandIpv6(value: string): number[] | null;
+/** Parses the receiving provider's verdict from an ordered (top-first) header list. */
+export declare function parseReceivedAuthentication(input: {
+    provider: ReceivedAuthProvider;
+    headers: ReadonlyArray<ReceivedHeader>;
+}): ReceivedAuthentication;
+/**
+ * The proof a cross-workspace (network) probe may keep. The receiving organization's own servers can
+ * surface as the authserv-id, an inbound gateway or forwarder (the SPF identity and connecting IP it
+ * relays from, its PTR names) or a gateway's added DKIM signature. So every domain survives only when it
+ * aligns with the probe's sender domain, and the sending IP (with its reverse DNS) only when the receiver
+ * reported SPF pass for that aligned identity: then the IP is the sender's, authorized by its own domain.
+ * Verdicts (SPF, DKIM, DMARC, compauth, alignment) describe only the sender and are kept.
+ */
+export declare function networkReceivedAuthentication(auth: ReceivedAuthentication, senderAddress: string): ReceivedAuthentication;
+/** Defensive read of a stored proof; malformed fields become null/unknown, a non-object becomes null. */
+export declare function readReceivedAuthentication(value: unknown): ReceivedAuthentication | null;
+/** Typed findings for one received probe; PTR/FCrDNS appear only when the reverse lookup ran. */
+export declare function headerProofFindings(auth: ReceivedAuthentication | null): DeliverabilityFinding[];
+/** The reverse-lookup name for an IP (in-addr.arpa / nibble ip6.arpa); null for anything else. */
+export declare function reverseDnsName(ip: string): string | null;
+/** Same address regardless of IPv6 spelling. */
+export declare function sameIp(a: string, b: string): boolean;