@jini-ai/platform 0.5.9 → 0.6.10

package/dist/http/guarded/client.js

@@ -1,43 +1,11 @@
 // Policy refusals use EgressRefusedError; DNS, connection and transport failures retain their
 // own errors because they are operational failures, not decisions that a different URL fixes.
-import { isPrivateAddress, expandIpv6 } from "../../net/address.js";
+import { classifyIpAddress } from "../../net/address.js";
 import { FetchTimeoutError } from "../../fetch-with-timeout.js";
 import { isIP } from "node:net";
 import { EgressRefusedError } from "./errors.js";
 /** Uses the canonical net address validator; labels preserve the guarded refusal contract. */
-export function classifyAddress({ ip }) {
-    if (!isPrivateAddress({ address: ip })) {
-        if (ip.toLowerCase().startsWith("::0."))
-            return "reserved";
-        return "public";
-    }
-    if (isIP(ip) === 6) {
-        const g = expandIpv6({ address: ip });
-        if (g.slice(0, 5).every(n => n === 0) && g[5] === 0xffff) {
-            return classifyAddress({ ip: [g[6] >> 8, g[6] & 255, g[7] >> 8, g[7] & 255].join(".") });
-        }
-        if (g.slice(0, 7).every(n => n === 0) && g[7] === 1)
-            return "loopback";
-        if ((g[0] & 0xffc0) === 0xfe80)
-            return "link-local";
-        if ((g[0] & 0xfe00) === 0xfc00)
-            return "private";
-        return "reserved";
-    }
-    if (isIP(ip) !== 4)
-        return "reserved";
-    const [a, b] = ip.split(".").map(Number);
-    if (a === 127)
-        return "loopback";
-    // This range includes the cloud metadata address 169.254.169.254.
-    if (a === 169 && b === 254)
-        return "link-local";
-    if (a === 0 || a >= 224)
-        return "reserved";
-    // The remaining blocked IPv4 ranges include RFC 6598 shared carrier space (100.64.0.0/10):
-    // it is not globally routable and belongs with RFC 1918 private ranges for egress decisions.
-    return "private";
-}
+export const classifyAddress = classifyIpAddress;
 const CROSS_ORIGIN_HEADERS = new Set(["accept", "accept-language", "user-agent"]);
 // HTTP header names are case-insensitive; preserve the caller's explicit User-Agent in any casing.
 function hasUserAgentHeader(headers) {
@@ -142,12 +110,16 @@ function capResponse(response, maxBytes) {
     };
 }
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
-async function sendWithPolicy(transport, policy, request, redirectsFollowed, dns, redirect) {
+async function sendWithPolicy({ hop, request, redirectsFollowed }, _options = {}) {
     const url = new URL(request.url);
-    request.signal?.throwIfAborted();
-    const peer = await resolveBeforeDeadline(resolvePinnedPeer(url, policy, dns), request.signal);
-    request.signal?.throwIfAborted();
-    const boundedRequest = {
+    const response = await sendOneHop({ hop, request, url });
+    const nextRequest = followableRedirect({ hop, request, url, response, redirectsFollowed });
+    if (!nextRequest)
+        return response;
+    return sendWithPolicy({ hop, request: nextRequest, redirectsFollowed: redirectsFollowed + 1 });
+}
+function boundRequest({ request, policy }, _options = {}) {
+    return {
         ...request,
         // The policy timeout is a ceiling: callers may choose a shorter idle budget, never a longer one.
         // Keep the legacy alias synchronized for host transport adapters. Activity resets
@@ -156,34 +128,60 @@ async function sendWithPolicy(transport, policy, request, redirectsFollowed, dns
         timeoutMs: Math.min(request.idleTimeoutMs ?? request.timeoutMs, policy.connectTimeoutMs),
         maxResponseBytes: Math.min(request.maxResponseBytes ?? Infinity, policy.maxResponseBytes, policy.maxDecompressedBytes),
     };
-    const response = await resolveBeforeDeadline(transport.requestPinned({ request: boundedRequest, peer }), request.signal);
-    const effectiveCap = Math.min(request.maxResponseBytes ?? Infinity, policy.maxResponseBytes, policy.maxDecompressedBytes);
+}
+async function sendOneHop({ hop, request, url }, _options = {}) {
+    request.signal?.throwIfAborted();
+    const peer = await resolveBeforeDeadline(resolvePinnedPeer(url, hop.policy, hop.dns), request.signal);
+    request.signal?.throwIfAborted();
+    const boundedRequest = boundRequest({ request, policy: hop.policy });
+    const response = await resolveBeforeDeadline(hop.transport.requestPinned({ request: boundedRequest, peer }), request.signal);
+    const effectiveCap = Math.min(request.maxResponseBytes ?? Infinity, hop.policy.maxResponseBytes, hop.policy.maxDecompressedBytes);
     // Record the normalized URL actually resolved and pinned, not the caller's original spelling.
     // A followed redirect returns the deeper hop's response, including that hop's finalUrl.
     const cappedResponse = { ...capResponse(response, effectiveCap), finalUrl: url.href };
     // A refused redirect is a policy decision like a refused address, so it carries the same type.
     // The text names no Location target, which may be private, so both messages can share it.
-    if (redirect === "error" && REDIRECT_STATUSES.has(cappedResponse.status)) {
+    if (hop.redirect === "error" && REDIRECT_STATUSES.has(cappedResponse.status)) {
         const message = "redirect response refused by the request's redirect policy";
         throw new EgressRefusedError({ message }, { callerSafeMessage: message });
     }
+    return cappedResponse;
+}
+/** The next hop's request when this response is a redirect the policy follows, else undefined. */
+function followableRedirect({ hop, request, url, response, redirectsFollowed }, _options = {}) {
     // Follow GET only even when the policy allows redirects: 307/308 preserve method and body,
     // so following a mutating request would replay a write and leak its body to an unchosen target.
     // With follow policy, a non-GET redirect stays a raw response rather than a target refusal.
-    const canFollowRedirect = redirect === "follow" && request.method === "GET" && REDIRECT_STATUSES.has(cappedResponse.status) && redirectsFollowed < policy.maxRedirects;
-    if (!canFollowRedirect) {
-        return cappedResponse;
-    }
-    const location = cappedResponse.headers.location ?? cappedResponse.headers.Location;
+    const canFollowRedirect = hop.redirect === "follow" && request.method === "GET" && REDIRECT_STATUSES.has(response.status) && redirectsFollowed < hop.policy.maxRedirects;
+    if (!canFollowRedirect)
+        return undefined;
+    const location = response.headers.location ?? response.headers.Location;
     if (!location)
-        return cappedResponse;
+        return undefined;
     const nextUrl = new URL(location, url);
     // Cross-origin hops must not inherit authorization or cookies entrusted to the original origin.
     // Custom headers can carry credentials too; forward only the explicit noncredential allowlist.
     const nextHeaders = isCrossOrigin(url, nextUrl)
         ? withCrossOriginHeaders(request.headers)
         : request.headers;
-    return sendWithPolicy(transport, policy, { ...request, url: nextUrl.toString(), headers: nextHeaders }, redirectsFollowed + 1, dns, redirect);
+    return { ...request, url: nextUrl.toString(), headers: nextHeaders };
+}
+function assertPositiveLimit({ value, name }, _options = {}) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new TypeError(`${name} must be a positive safe integer`);
+}
+function assertRequestLimits({ request }, _options = {}) {
+    assertPositiveLimit({
+        value: request.idleTimeoutMs ?? request.timeoutMs,
+        name: request.idleTimeoutMs === undefined ? "timeoutMs" : "idleTimeoutMs",
+    });
+    if (request.totalDeadlineMs !== undefined)
+        assertPositiveLimit({ value: request.totalDeadlineMs, name: "totalDeadlineMs" });
+    if (request.maxResponseBytes !== undefined)
+        assertPositiveLimit({ value: request.maxResponseBytes, name: "maxResponseBytes" });
+}
+function composeRequestSignal({ caller, deadline }, _options = {}) {
+    return caller && deadline ? AbortSignal.any([caller, deadline]) : caller ?? deadline;
 }
 /** Builds an adapter-friendly outbound port. Every hop is resolved, checked, and pinned before I/O.
  * Socket idle time is bounded on every hop. An optional totalDeadlineMs includes DNS,
@@ -200,19 +198,11 @@ export function createHttpClient(required) {
     if (!Number.isSafeInteger(policy.maxRedirects) || policy.maxRedirects < 0)
         throw new TypeError("maxRedirects must be a nonnegative safe integer");
     return { async send({ request }, { redirect = "follow" } = {}) {
-            const idleTimeoutMs = request.idleTimeoutMs ?? request.timeoutMs;
-            if (!Number.isSafeInteger(idleTimeoutMs) || idleTimeoutMs <= 0) {
-                const timeoutName = request.idleTimeoutMs === undefined ? "timeoutMs" : "idleTimeoutMs";
-                throw new TypeError(`${timeoutName} must be a positive safe integer`);
-            }
-            if (request.totalDeadlineMs !== undefined && (!Number.isSafeInteger(request.totalDeadlineMs) || request.totalDeadlineMs <= 0))
-                throw new TypeError("totalDeadlineMs must be a positive safe integer");
-            if (request.maxResponseBytes !== undefined && (!Number.isSafeInteger(request.maxResponseBytes) || request.maxResponseBytes <= 0))
-                throw new TypeError("maxResponseBytes must be a positive safe integer");
+            assertRequestLimits({ request });
             const deadline = request.totalDeadlineMs === undefined ? undefined : clock.timeoutSignal({ timeoutMs: request.totalDeadlineMs });
-            const signal = request.signal && deadline ? AbortSignal.any([request.signal, deadline]) : request.signal ?? deadline;
+            const signal = composeRequestSignal({ caller: request.signal, deadline });
             try {
-                return await sendWithPolicy(transport, policy, { ...request, ...(signal === undefined ? {} : { signal }), headers: withDefaultUserAgent(request.headers, userAgent) }, 0, dns, redirect);
+                return await sendWithPolicy({ hop: { transport, policy, dns, redirect }, request: { ...request, ...(signal === undefined ? {} : { signal }), headers: withDefaultUserAgent(request.headers, userAgent) }, redirectsFollowed: 0 });
             }
             catch (error) {
                 if (deadline?.aborted && !request.signal?.aborted)

package/dist/http/guarded/fetch-adapter.d.ts

@@ -1,5 +1,4 @@
-import type { HttpClientPort } from "@jini-ai/core/primitives";
-import type { HttpRequest, RequestRedirect } from "@jini-ai/core/primitives";
+import type { HttpClientPort, HttpRequest, RequestRedirect } from "@jini-ai/core/primitives";
 export interface GuardedFetchOptions {
     method?: HttpRequest["method"];
     headers?: ConstructorParameters<typeof Headers>[0];
@@ -19,5 +18,5 @@ export declare function guardedFetch({ client, url, timeoutMs }: {
     client: HttpClientPort;
     url: string;
     timeoutMs: number;
-}, { method, headers, body, signal, redirect, idleTimeoutMs, totalDeadlineMs }?: GuardedFetchOptions): Promise<Response>;
+}, { method, headers, redirect, ...rest }?: GuardedFetchOptions): Promise<Response>;
 //# sourceMappingURL=fetch-adapter.d.ts.map

package/dist/http/guarded/fetch-adapter.js

@@ -2,18 +2,29 @@
  * Defaults to redirect refusal. Hosts adapt their SDK's positional fetch signature to this object API.
  * Strings and form bodies are supported; streaming uploads need a different transport contract.
  */
-export async function guardedFetch({ client, url, timeoutMs }, { method = "GET", headers = {}, body, signal, redirect = "error", idleTimeoutMs, totalDeadlineMs } = {}) {
-    const response = await client.send({ request: {
-            method, url, timeoutMs, headers: Object.fromEntries(new Headers(headers).entries()),
-            ...(body === undefined ? {} : { body: String(body) }),
-            ...(signal === undefined ? {} : { signal }),
-            ...(idleTimeoutMs === undefined ? {} : { idleTimeoutMs }),
-            ...(totalDeadlineMs === undefined ? {} : { totalDeadlineMs }),
-        } }, { redirect });
-    const truncated = response.bodyBytes === undefined
-        ? response.bodyTruncated : response.bodyBytesTruncated ?? response.bodyTruncated;
-    if (truncated)
+export async function guardedFetch({ client, url, timeoutMs }, { method = "GET", headers = {}, redirect = "error", ...rest } = {}) {
+    const response = await client.send({ request: toHttpRequest({ method, url, timeoutMs, headers }, rest) }, { redirect });
+    if (isTruncated(response))
         throw new Error("guarded response was truncated by the byte policy");
+    // Fetch prohibits bodies for HEAD and these statuses, even when a transport supplies an empty buffer.
+    const bodyless = method === "HEAD" || [204, 205, 304].includes(response.status);
+    return new Response(bodyless ? null : responseBody(response), { status: response.status, headers: responseHeaders(response) });
+}
+function toHttpRequest({ method, url, timeoutMs, headers }, { body, signal, idleTimeoutMs, totalDeadlineMs }) {
+    return {
+        method, url, timeoutMs, headers: Object.fromEntries(new Headers(headers).entries()),
+        ...(body === undefined ? {} : { body: String(body) }),
+        ...(signal === undefined ? {} : { signal }),
+        ...(idleTimeoutMs === undefined ? {} : { idleTimeoutMs }),
+        ...(totalDeadlineMs === undefined ? {} : { totalDeadlineMs }),
+    };
+}
+// With bytes present, the byte-specific flag decides; the coarse flag only fills in when it is absent.
+function isTruncated(response) {
+    return response.bodyBytes === undefined
+        ? response.bodyTruncated : response.bodyBytesTruncated ?? response.bodyTruncated;
+}
+function responseHeaders(response) {
     const resultHeaders = new Headers(response.headers);
     resultHeaders.delete("content-encoding");
     resultHeaders.delete("content-length");
@@ -22,9 +33,9 @@ export async function guardedFetch({ client, url, timeoutMs }, { method = "GET",
         for (const cookie of response.setCookies)
             resultHeaders.append("set-cookie", cookie);
     }
-    const bytes = response.bodyBytes === undefined ? response.bodyText : Buffer.from(response.bodyBytes);
-    // Fetch prohibits bodies for HEAD and these statuses, even when a transport supplies an empty buffer.
-    const bodyless = method === "HEAD" || [204, 205, 304].includes(response.status);
-    return new Response(bodyless ? null : bytes, { status: response.status, headers: resultHeaders });
+    return resultHeaders;
+}
+function responseBody(response) {
+    return response.bodyBytes === undefined ? response.bodyText : Buffer.from(response.bodyBytes);
 }
 //# sourceMappingURL=fetch-adapter.js.map

package/dist/mail/builtin-providers.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @file The two built-in mail providers: `smtp` (any mailbox/relay) and `console` (local only).
+ *
+ * SMTP gets its transport from the host (nodemailer is never loaded by this package); console logs
+ * each message with its body (the local preview of sign-in/confirmation links) and reports
+ * `hosted: false`, so it can never make a site look configured.
+ */
+import { type Clock } from "@jini-ai/core/primitives";
+import type { MailProviderModule } from "./provider.js";
+import { type SmtpTransport } from "./smtp.js";
+/**
+ * SMTP endpoint packed into a credential `baseUrl` (`https://host:port`); 443/465 = implicit TLS.
+ * @complexity O(1).
+ */
+export declare function parseSmtpEndpoint({ baseUrl }: {
+    baseUrl: string;
+}): {
+    host: string;
+    port: number;
+    secure: boolean;
+};
+export declare function createSmtpMailProvider(required: {
+    createTransport: (required: {
+        host: string;
+        port: number;
+        secure: boolean;
+        auth: {
+            user: string;
+            pass: string;
+        };
+    }) => SmtpTransport;
+    clock: Clock;
+}): MailProviderModule;
+export declare function createConsoleMailProvider(required: {
+    clock: Clock;
+}, optional?: {
+    log?: (line: string) => void;
+}): MailProviderModule;
+//# sourceMappingURL=builtin-providers.d.ts.map

package/dist/mail/builtin-providers.js

@@ -0,0 +1,60 @@
+/**
+ * @file The two built-in mail providers: `smtp` (any mailbox/relay) and `console` (local only).
+ *
+ * SMTP gets its transport from the host (nodemailer is never loaded by this package); console logs
+ * each message with its body (the local preview of sign-in/confirmation links) and reports
+ * `hosted: false`, so it can never make a site look configured.
+ */
+import { nowIso } from "@jini-ai/core/primitives";
+import { SmtpMailerAdapter } from "./smtp.js";
+/**
+ * SMTP endpoint packed into a credential `baseUrl` (`https://host:port`); 443/465 = implicit TLS.
+ * @complexity O(1).
+ */
+export function parseSmtpEndpoint({ baseUrl }) {
+    const url = new URL(baseUrl);
+    const port = url.port ? Number(url.port) : url.protocol === "https:" ? 443 : 80;
+    return { host: url.hostname, port, secure: port === 443 || port === 465 };
+}
+export function createSmtpMailProvider(required) {
+    return {
+        id: "smtp",
+        label: "SMTP server",
+        credentialKeys: ["baseUrl", "username", "token"],
+        capabilities: { hosted: true, feedback: false, domainVerification: false },
+        create({ credential }) {
+            const endpoint = parseSmtpEndpoint({ baseUrl: credential.baseUrl ?? "" });
+            const transport = required.createTransport({ ...endpoint, auth: { user: credential.username ?? "", pass: credential.token } });
+            return new SmtpMailerAdapter({ transport, clock: required.clock });
+        },
+    };
+}
+export function createConsoleMailProvider(required, optional = {}) {
+    const log = optional.log ?? ((line) => console.log(line));
+    let counter = 0;
+    const mailer = {
+        capabilities: () => ({ driver: "console", supportsIdempotencyKey: false, supportsWebhookFeedback: false, maxBatchSize: 1, supportsAttachments: true }),
+        async send({ message }) {
+            counter += 1;
+            // The body is the point of a local mailer: a sign-in or confirmation link must be usable from the
+            // log, since nothing is delivered. Text is preferred (readable); an html-only message shows its html.
+            const body = message.text ?? message.html;
+            log(`[mail:console] to=${message.to.email} subject=${JSON.stringify(message.subject)}${body === undefined ? "" : `\n${body}`}`);
+            return { ok: true, providerMessageId: `console-${counter}`, acceptedAt: nowIso({ clock: required.clock }) };
+        },
+        async sendBatch({ messages, ...delivery }) {
+            const results = [];
+            for (const message of messages)
+                results.push(await mailer.send({ ...delivery, message }));
+            return results;
+        },
+    };
+    return {
+        id: "console",
+        label: "Console (local development, sends nothing)",
+        credentialKeys: [],
+        capabilities: { hosted: false, feedback: false, domainVerification: false },
+        create: () => mailer,
+    };
+}
+//# sourceMappingURL=builtin-providers.js.map

package/dist/mail/feedback.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @file Inbound delivery feedback (bounces, complaints) — one ingest, one suppression writer.
+ *
+ * The host mounts this behind `POST /hooks/mail/:providerId` with the RAW body. Hardening lives
+ * here so every host gets it: a body-size cap before parsing, a rate limit on unverified requests
+ * (signature guessing; a verified request is never throttled), vault-held secrets with rotation (any of several may verify), and an inbox
+ * keyed by (providerId, eventId) so provider replays are no-ops.
+ *
+ * The inbox row and the suppression write are separate statements with no enclosing transaction,
+ * so the row is only marked complete after suppression and the subscriber succeed: a crash or error
+ * in between leaves it incomplete, and the provider's replay re-applies it (suppression is an upsert).
+ */
+import type { MailFeedbackParser } from "./provider.js";
+import type { MailSuppressionRepoPort, MailSuppressionScope } from "./ports.js";
+import type { MailerFeedbackEvent } from "./types.js";
+export interface MailFeedbackInboxPort {
+    /**
+     * Insert-if-absent on (providerId, eventId). `duplicate` means this event was already applied
+     * (completed); `inserted` means it must be applied now: either new, or recorded earlier but never
+     * completed (the earlier attempt failed or stopped part-way).
+     */
+    record(required: {
+        providerId: string;
+        event: MailerFeedbackEvent & {
+            eventId: string;
+            recipient: string;
+        };
+    }): Promise<"inserted" | "duplicate">;
+    /** Marks (providerId, eventId) applied; later `record` calls for it return `duplicate`. */
+    complete(required: {
+        providerId: string;
+        eventId: string;
+    }): Promise<void>;
+}
+export interface MailFeedbackIngestDeps {
+    /** Only providers whose module ships a parser; others 404 so the route reveals nothing else. */
+    parserFor: (required: {
+        providerId: string;
+    }) => MailFeedbackParser | undefined;
+    /** Current + previous webhook secrets from the vault; empty = not configured. */
+    secretsFor: (required: {
+        providerId: string;
+    }) => Promise<readonly string[]>;
+    inbox: MailFeedbackInboxPort;
+    suppression: MailSuppressionRepoPort;
+}
+export interface MailFeedbackIngestOptions {
+    maxBodyBytes?: number;
+    /** Unverified requests allowed per provider per window before 429. */
+    maxUnverifiedPerWindow?: number;
+    windowMs?: number;
+    now?: () => number;
+    /** Extra subscriber after suppression (e.g. newsletter recipient status). Errors propagate. */
+    onEvent?: (required: {
+        providerId: string;
+        event: MailerFeedbackEvent;
+    }) => Promise<void>;
+}
+export interface MailFeedbackResponse {
+    status: 200 | 400 | 401 | 404 | 413 | 429 | 503;
+    body: {
+        ok: boolean;
+        applied?: number;
+        duplicates?: number;
+        error?: string;
+    };
+}
+/** Hard bounce → every lane; complaint → bulk only (never lock a member out of sign-in links). */
+export declare function suppressionScopeFor({ event }: {
+    event: MailerFeedbackEvent;
+}): MailSuppressionScope | null;
+/**
+ * @complexity O(events) inbox writes per request.
+ * @example createMailFeedbackIngest({ parserFor, secretsFor, inbox, suppression }).handle({...})
+ */
+export declare function createMailFeedbackIngest(required: MailFeedbackIngestDeps, optional?: MailFeedbackIngestOptions): {
+    handle(input: {
+        providerId: string;
+        workspaceId: string;
+        rawBody: Uint8Array;
+        headers: Readonly<Record<string, string>>;
+    }): Promise<MailFeedbackResponse>;
+};
+//# sourceMappingURL=feedback.d.ts.map

package/dist/mail/feedback.js

@@ -0,0 +1,90 @@
+/** Hard bounce → every lane; complaint → bulk only (never lock a member out of sign-in links). */
+export function suppressionScopeFor({ event }) {
+    if (event.kind === "bounced")
+        return event.hardBounce ? "all" : null;
+    if (event.kind === "complained")
+        return "bulk";
+    return null;
+}
+function isKeyed(event) {
+    return typeof event.eventId === "string" && event.eventId !== "" && typeof event.recipient === "string" && event.recipient !== "";
+}
+function createUnverifiedCounter(required) {
+    const windows = new Map();
+    return {
+        blocked({ providerId }) {
+            const entry = windows.get(providerId);
+            return entry !== undefined && required.now() - entry.start < required.windowMs && entry.count >= required.max;
+        },
+        note({ providerId }) {
+            const at = required.now();
+            const entry = windows.get(providerId);
+            if (entry === undefined || at - entry.start >= required.windowMs)
+                windows.set(providerId, { start: at, count: 1 });
+            else
+                entry.count += 1;
+        },
+    };
+}
+/**
+ * @complexity O(events) inbox writes per request.
+ * @example createMailFeedbackIngest({ parserFor, secretsFor, inbox, suppression }).handle({...})
+ */
+export function createMailFeedbackIngest(required, optional = {}) {
+    const now = optional.now ?? Date.now;
+    const maxBodyBytes = optional.maxBodyBytes ?? 256 * 1024;
+    const unverified = createUnverifiedCounter({ max: optional.maxUnverifiedPerWindow ?? 30, windowMs: optional.windowMs ?? 60_000, now });
+    const apply = async (input) => {
+        const outcome = await required.inbox.record(input);
+        if (outcome === "duplicate")
+            return outcome;
+        const scope = suppressionScopeFor({ event: input.event });
+        if (scope !== null) {
+            const reason = input.event.kind === "complained" ? "complained" : "bounced";
+            await required.suppression.suppress({ workspaceId: input.event.workspaceId, normalizedAddress: input.event.recipient.trim().toLowerCase(), scope, reason });
+        }
+        await optional.onEvent?.(input);
+        await required.inbox.complete({ providerId: input.providerId, eventId: input.event.eventId });
+        return outcome;
+    };
+    const authenticate = async (input) => {
+        const secrets = await required.secretsFor({ providerId: input.providerId });
+        if (secrets.length === 0)
+            return { status: 503, body: { ok: false, error: "webhook secret not configured" } };
+        if (input.parser.verify({ rawBody: input.rawBody, headers: input.headers, secrets, now: now() }))
+            return null;
+        // The throttle answers failed verifications only. Checked before verifying, it let anyone who can
+        // reach the route block a provider's genuinely signed bounces/complaints with 30 junk requests.
+        const throttled = unverified.blocked({ providerId: input.providerId });
+        unverified.note({ providerId: input.providerId });
+        if (throttled)
+            return { status: 429, body: { ok: false, error: "too many unverified requests" } };
+        return { status: 401, body: { ok: false, error: "signature rejected" } };
+    };
+    return {
+        async handle(input) {
+            const parser = required.parserFor({ providerId: input.providerId });
+            if (!parser)
+                return { status: 404, body: { ok: false, error: "unknown provider" } };
+            if (input.rawBody.byteLength > maxBodyBytes)
+                return { status: 413, body: { ok: false, error: "body too large" } };
+            const denied = await authenticate({ ...input, parser });
+            if (denied)
+                return denied;
+            const parsed = parser.parse({ rawBody: input.rawBody, workspaceId: input.workspaceId, headers: input.headers });
+            if ("error" in parsed)
+                return { status: 400, body: { ok: false, error: parsed.error } };
+            let applied = 0;
+            let duplicates = 0;
+            // Events without an id or recipient cannot be deduped or suppressed; they are dropped, not guessed.
+            for (const event of parsed.filter(isKeyed)) {
+                if ((await apply({ providerId: input.providerId, event })) === "inserted")
+                    applied += 1;
+                else
+                    duplicates += 1;
+            }
+            return { status: 200, body: { ok: true, applied, duplicates } };
+        },
+    };
+}
+//# sourceMappingURL=feedback.js.map

package/dist/mail/index.d.ts

@@ -4,4 +4,15 @@ export type * from "./adapter-module.js";
 export { wrapMailerWithPurposeGate } from "./purpose-scoped-mailer.js";
 export type { WrapMailerWithPurposeGateOptions } from "./purpose-scoped-mailer.js";
 export { isMailDeliveryAvailable } from "./delivery-availability.js";
+export { createMailSenderIdentityResolver, NON_DELIVERING_MAIL_DRIVERS, SenderIdentityNotConfiguredError } from "./sender-identity.js";
+export type { ConfiguredMailSender, CreateMailSenderIdentityResolverOptional, MailSenderIdentityPort } from "./sender-identity.js";
+export { createMailProviderRegistry, validateMailProvider, initialMailProviderSetting, computeMailStatus, MAIL_PROVIDER_SETTING_KEY } from "./provider.js";
+export type * from "./provider.js";
+export { createMailLaneLimiter } from "./rate-limit.js";
+export type { MailLaneLimiter } from "./rate-limit.js";
+export { createMailDeliveryPolicy, createPolicyMailer, laneForPurpose, hasOneClickUnsubscribe, mailPayloadHash, MAIL_RATE_LIMITED, isMailRateLimited } from "./policy.js";
+export type { MailDeliveryPolicy, MailDeliveryPolicyDeps, MailDeliveryPolicyOptions, MailResendPolicy, MailTestMode } from "./policy.js";
+export { createMailFeedbackIngest, suppressionScopeFor } from "./feedback.js";
+export type { MailFeedbackInboxPort, MailFeedbackIngestDeps, MailFeedbackIngestOptions, MailFeedbackResponse } from "./feedback.js";
+export { createSmtpMailProvider, createConsoleMailProvider, parseSmtpEndpoint } from "./builtin-providers.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/mail/index.js

@@ -1,3 +1,9 @@
 export { wrapMailerWithPurposeGate } from "./purpose-scoped-mailer.js";
 export { isMailDeliveryAvailable } from "./delivery-availability.js";
+export { createMailSenderIdentityResolver, NON_DELIVERING_MAIL_DRIVERS, SenderIdentityNotConfiguredError } from "./sender-identity.js";
+export { createMailProviderRegistry, validateMailProvider, initialMailProviderSetting, computeMailStatus, MAIL_PROVIDER_SETTING_KEY } from "./provider.js";
+export { createMailLaneLimiter } from "./rate-limit.js";
+export { createMailDeliveryPolicy, createPolicyMailer, laneForPurpose, hasOneClickUnsubscribe, mailPayloadHash, MAIL_RATE_LIMITED, isMailRateLimited } from "./policy.js";
+export { createMailFeedbackIngest, suppressionScopeFor } from "./feedback.js";
+export { createSmtpMailProvider, createConsoleMailProvider, parseSmtpEndpoint } from "./builtin-providers.js";
 //# sourceMappingURL=index.js.map

package/dist/mail/policy.d.ts

@@ -0,0 +1,77 @@
+import type { MailCapturePort, MailDeliveryLane, MailerPort, MailSendLedgerPort, MailSuppressionRepoPort } from "./ports.js";
+import type { MailLaneLimiter } from "./rate-limit.js";
+import type { EmailAddress, MailerSendOptions, MailerSendResult, OutboundEmail } from "./types.js";
+/**
+ * The one throttling code of the mail contract: the local token bucket's refusal and a provider's own
+ * throttling (e.g. an HTTP 429, which adapters normalize to it) are the same retryable back-pressure,
+ * with `retryAfterMs` as the hint. Callers defer such a recipient instead of recording a failure.
+ */
+export declare const MAIL_RATE_LIMITED = "MAIL_RATE_LIMITED";
+/** Whether a send result is the typed rate-limited refusal. @complexity O(1). */
+export declare function isMailRateLimited({ result }: {
+    result: MailerSendResult;
+}): boolean;
+/** `never`: login links — the user asks again; `on_unknown`: confirmations may be re-sent once unknown. */
+export type MailResendPolicy = "never" | "on_unknown";
+export type MailTestMode = {
+    kind: "redirect";
+    to: EmailAddress;
+} | {
+    kind: "capture";
+    sink: MailCapturePort;
+};
+export interface MailDeliveryPolicyDeps {
+    providerId: string;
+    ledger: MailSendLedgerPort;
+    suppression: MailSuppressionRepoPort;
+    supportsAttachments: boolean;
+}
+export interface MailDeliveryPolicyOptions {
+    limiter?: MailLaneLimiter;
+    testMode?: MailTestMode;
+    /** Per-purpose resend policy; unlisted purposes use `on_unknown`. */
+    resendPolicy?: (required: {
+        purpose: MailerSendOptions["purpose"];
+    }) => MailResendPolicy;
+    /** ISO clock for synthesized results (dedup replays, captures). */
+    nowIso?: () => string;
+}
+export interface MailDeliveryPolicy {
+    /** Applies the policy to one message; `send` is the provider call (any host call shape). */
+    deliver(required: {
+        message: OutboundEmail;
+        options: MailerSendOptions;
+        send: (required: {
+            message: OutboundEmail;
+        }) => Promise<MailerSendResult>;
+    }): Promise<MailerSendResult>;
+}
+/** Bulk lane only for `purpose: "bulk"`; everything else (incl. `feature:*`) is transactional. */
+export declare function laneForPurpose({ purpose }: {
+    purpose: MailerSendOptions["purpose"];
+}): MailDeliveryLane;
+/** RFC 8058 one-click needs both headers; header names are case-insensitive. */
+export declare function hasOneClickUnsubscribe({ headers }: {
+    headers: OutboundEmail["headers"];
+}): boolean;
+/**
+ * Stable per-recipient payload hash: a reused key with different content is a caller bug. It covers
+ * everything the provider delivers (addresses with display names, reply-to, subject, bodies, headers,
+ * attachment names, types and bytes), so a changed message under a sent key is a conflict rather than
+ * the earlier message's success. Attachment bytes enter as their own sha256 to keep the input small.
+ * @complexity O(message size).
+ */
+export declare function mailPayloadHash({ message }: {
+    message: OutboundEmail;
+}): string;
+/**
+ * Builds the policy. @complexity O(1) ledger round-trips per recipient.
+ * @example createMailDeliveryPolicy({ providerId: "smtp", ledger, suppression, supportsAttachments: true })
+ */
+export declare function createMailDeliveryPolicy(required: MailDeliveryPolicyDeps, optional?: MailDeliveryPolicyOptions): MailDeliveryPolicy;
+/** Jini-shaped `MailerPort` decorator over the policy; batches go recipient by recipient. */
+export declare function createPolicyMailer(required: {
+    inner: MailerPort;
+    policy: MailDeliveryPolicy;
+}): MailerPort;
+//# sourceMappingURL=policy.d.ts.map