@k2b/cloud 0.40.0 → 0.42.0

package/src/services/mandates/index.ts

@@ -5,6 +5,7 @@ import type { CapabilityActionPolicy } from "../../contracts/capabilities";
 import { CapabilityAppIdSchema } from "../../contracts/capabilities";
 import { isAccountCategoryAllowed } from "../account-category-policy";
 import { audit } from "../audit";
+import { requireRegisteredAppAccess, resolveIssuanceAuthority } from "../identity/issue-invocation";
 import { logger } from "../logging";
 import { parsePgJsonValue } from "../postgres";
 import { isMandatePolicyNarrowing, type MandatePolicyV1, MandatePolicyV1Schema, mandatePolicyAllows, parseMandatePolicy } from "./policy";
@@ -213,6 +214,33 @@ const validSubject = async (subject: MandateSubject, db: SQL): Promise<boolean>
   return row?.active === true;
 };
 
+const subjectAppAccess = async (
+  subject: MandateSubject,
+  appIds: readonly string[],
+  db: SQL,
+  groupsAdmin?: readonly string[],
+): Promise<boolean> => {
+  try {
+    const authority = await resolveIssuanceAuthority(
+      {
+        sub: subject.id,
+        principal_type: subject.type,
+        access_subject_type: subject.type,
+        access_subject_id: subject.id,
+        credential_kind: "mandate",
+        scopes: [],
+      },
+      "core",
+      db,
+      groupsAdmin,
+    );
+    for (const appId of new Set(appIds)) await requireRegisteredAppAccess(authority, appId, { db });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
 const canActForSubject = (authority: MandateInteractiveAuthority | MandateAdminAuthority, subject: MandateSubject): boolean =>
   authority.kind === "admin" || (subject.type === "user" && subject.id === authority.userId);
 
@@ -548,6 +576,12 @@ const setMandateState = async (
   return changedRow(input.mandateId, input.expectedRevision, input.authority, db, async (current) => {
     if (state === "active" && input.authority.kind === "workload") return fail(err.forbidden("Workloads cannot resume mandates"));
     if (state === "active" && !(await validSubject(current.subject, db))) return ok(null);
+    if (
+      state === "active" &&
+      !(await subjectAppAccess(current.subject, [current.ownerAppId, ...(current.policy.apps === "*" ? [] : current.policy.apps)], db))
+    ) {
+      return fail(err.forbidden("App access was denied. Ask someone who manages access before resuming this mandate."));
+    }
     if (current.state === state) return ok(current);
     if (state === "paused" && current.state !== "active") return ok(null);
     if (state === "active" && current.state !== "paused") return ok(null);
@@ -632,7 +666,7 @@ export const validateMandateIssueAuthority = async (
     expectedRevision?: number;
     requestId?: string;
   },
-  options: { db?: SQL } = {},
+  options: { db?: SQL; groupsAdmin?: readonly string[] } = {},
 ): Promise<Result<MandateIssueAuthority>> => {
   if (!UUID.safeParse(input.mandateId).success) {
     return denyMandateIssue(err.forbidden("Mandate identifier is invalid"));
@@ -695,6 +729,9 @@ export const validateMandateIssueAuthority = async (
     return denyMandateIssue(err.forbidden(MANDATE_POLICY_DENIED_MESSAGE));
   }
   const mandate = mapMandate(row);
+  if (!(await subjectAppAccess(mandate.subject, [mandate.ownerAppId, target.data], db, options.groupsAdmin))) {
+    return denyMandateIssue(err.forbidden("App access was denied. Ask someone who manages access before running this mandate."));
+  }
   return ok({
     mandateId: mandate.id,
     mandateRevision: mandate.revision,
@@ -759,10 +796,10 @@ const issueAuditParams = <T>(
 export const withMandateIssueAuthority = <T>(
   input: Parameters<typeof validateMandateIssueAuthority>[0],
   use: (authority: MandateIssueAuthority) => Promise<T>,
-  options: { db?: SQL } = {},
+  options: { db?: SQL; groupsAdmin?: readonly string[] } = {},
 ): Promise<Result<T>> => {
   const run = async (db: SQL): Promise<Result<T>> => {
-    const authority = await validateMandateIssueAuthority(input, { db });
+    const authority = await validateMandateIssueAuthority(input, { db, groupsAdmin: options.groupsAdmin });
     if (!authority.ok) {
       mandateMetrics.increment(metricForIssueDenial(authority.error));
       return audit.recordResult(issueAuditParams(input, authority, input.expectedRevision ?? null, db));

package/src/services/network-security.ts

@@ -27,9 +27,10 @@ export const resolveAllowedNetworkAddresses = async (
   rawHostname: string,
   allowlist: NetworkAllowlist,
   lookup: NetworkLookup = (hostname) => dnsLookup(hostname, { all: true, verbatim: true }),
+  port?: number,
 ): Promise<PublicNetworkAddress[]> => {
   const hostname = normalizeNetworkHostname(rawHostname);
-  const trustedHost = allowlist.hosts.has(hostname);
+  const trustedHost = allowlist.hosts.has(hostname) || (port !== undefined && allowlist.hostPorts?.get(hostname)?.has(port) === true);
   if (!trustedHost && isUnsafeNetworkHostname(rawHostname)) throw new NetworkTargetBlockedError("Network target host is not allowed");
 
   const literal = parseNetworkAddress(rawHostname);
@@ -45,7 +46,7 @@ export const resolveAllowedNetworkAddresses = async (
   });
   if (
     !trustedHost &&
-    normalized.some((entry) => isUnsafeNetworkAddress(entry.address) && !isAllowlistedNetworkAddress(allowlist, entry.address))
+    normalized.some((entry) => isUnsafeNetworkAddress(entry.address) && !isAllowlistedNetworkAddress(allowlist, entry.address, port))
   ) {
     throw new NetworkTargetBlockedError("Network target resolved to a private or reserved address");
   }
@@ -59,15 +60,17 @@ export const isNetworkTargetBlocked = async (
   {
     resolve = resolveAllowedNetworkAddresses,
     timeoutMs = 5000,
+    port,
   }: {
     resolve?: typeof resolveAllowedNetworkAddresses;
     timeoutMs?: number;
+    port?: number;
   } = {},
 ): Promise<boolean> => {
   let timer: ReturnType<typeof setTimeout> | undefined;
   try {
     await Promise.race([
-      resolve(hostname, allowlist),
+      resolve(hostname, allowlist, undefined, port),
       new Promise<void>((resolve) => {
         timer = setTimeout(resolve, timeoutMs);
       }),

package/src/services/network-transport.ts

@@ -0,0 +1,99 @@
+import type { ClientRequest, IncomingMessage } from "node:http";
+import type { RequestOptions } from "node:https";
+
+/** Stop waiting even when a resolver cannot cancel its underlying DNS work. */
+export const awaitNetworkOperation = <T>(work: Promise<T>, signal: AbortSignal): Promise<T> =>
+  new Promise<T>((resolve, reject) => {
+    const cleanup = () => signal.removeEventListener("abort", abort);
+    const abort = () => {
+      cleanup();
+      reject(signal.reason);
+    };
+    signal.addEventListener("abort", abort, { once: true });
+    work.then(
+      (value) => {
+        cleanup();
+        if (signal.aborted) reject(signal.reason);
+        else resolve(value);
+      },
+      (error) => {
+        cleanup();
+        reject(error);
+      },
+    );
+    if (signal.aborted) abort();
+  });
+
+/** One caller-owned budget, shared by lookup, address attempts, redirects and body reads. */
+export const withNetworkDeadline = async <T>(
+  timeoutMs: number,
+  callerSignal: AbortSignal | undefined,
+  timeoutError: Error,
+  work: (signal: AbortSignal) => Promise<T>,
+): Promise<T> => {
+  const controller = new AbortController();
+  const abort = () => controller.abort(callerSignal?.reason);
+  callerSignal?.addEventListener("abort", abort, { once: true });
+  if (callerSignal?.aborted) abort();
+  const timer = setTimeout(() => controller.abort(timeoutError), timeoutMs);
+  try {
+    controller.signal.throwIfAborted();
+    return await awaitNetworkOperation(work(controller.signal), controller.signal);
+  } finally {
+    clearTimeout(timer);
+    callerSignal?.removeEventListener("abort", abort);
+  }
+};
+
+export type NetworkRequestFactory = (options: RequestOptions, callback: (response: IncomingMessage) => void) => ClientRequest;
+
+/** Lifecycle for already validated/pinned request options. Does not resolve or authorize targets. */
+export const readNetworkResponse = <T>(input: {
+  request: NetworkRequestFactory;
+  options: RequestOptions;
+  signal: AbortSignal;
+  body?: Uint8Array;
+  read: (response: IncomingMessage, resolve: (value: T) => void, reject: (error: Error) => void) => void;
+}): Promise<T> =>
+  new Promise<T>((resolve, reject) => {
+    input.signal.throwIfAborted();
+    let settled = false;
+    let outgoing: ClientRequest | undefined;
+    let incoming: IncomingMessage | undefined;
+    const finish = (result: { value: T } | { error: Error }) => {
+      if (settled) return;
+      settled = true;
+      input.signal.removeEventListener("abort", abort);
+      // Discarded bodies must never be drained after the operation has settled.
+      incoming?.destroy();
+      outgoing?.destroy();
+      if ("error" in result) reject(result.error);
+      else resolve(result.value);
+    };
+    const fail = (error: Error) => finish({ error });
+    const abort = () => fail(input.signal.reason);
+    input.signal.addEventListener("abort", abort, { once: true });
+    try {
+      outgoing = input.request(input.options, (response) => {
+        incoming = response;
+        response.on("error", fail);
+        response.once("aborted", () => fail(new Error("Network response was aborted")));
+        if (settled) {
+          response.destroy();
+          return;
+        }
+        try {
+          input.read(response, (value) => finish({ value }), fail);
+        } catch (error) {
+          fail(error instanceof Error ? error : new Error(String(error)));
+        }
+      });
+      outgoing.on("error", fail);
+      if (settled || input.signal.aborted) {
+        if (input.signal.aborted) abort();
+        outgoing.destroy();
+      } else outgoing.end(input.body);
+    } catch (error) {
+      fail(error instanceof Error ? error : new Error(String(error)));
+    }
+  });

package/src/services/notifications/catalog.ts

@@ -9,8 +9,9 @@ const RETRY_MS = 5_000;
 const log = logger("notifications:catalog");
 
 const isSchemaUnavailable = (error: unknown): boolean => {
-  if (!error || typeof error !== "object" || !("code" in error)) return false;
-  return error.code === "42P01" || error.code === "42703" || error.code === "3F000";
+  if (!error || typeof error !== "object") return false;
+  const code = ("errno" in error ? error.errno : undefined) ?? ("code" in error ? error.code : undefined);
+  return code === "42P01" || code === "42703" || code === "3F000";
 };
 
 const upsertDefinition = async (definition: AnyBoundNotificationDefinition, db: typeof sql = sql): Promise<void> => {

package/src/services/notifications/runtime.ts

@@ -95,6 +95,7 @@ const recover = (): Promise<void> => {
 const lifecycle = createRuntimeLifecycle({
   start: async () => {
     recoveryTasks.open();
+    // Local delivery orchestration; email enters the shared SMTP budget.
     const concurrency = Math.min(Math.max(Math.floor(runtimeOptions.concurrency ?? 4), 1), 16);
     const recoveryIntervalMs = Math.max(runtimeOptions.recoveryIntervalMs ?? 30_000, 5_000);
     worker = await deliveryJob().process(

package/src/services/notifications/web-push-transport.ts

@@ -4,6 +4,7 @@ import webpush, { type RequestDetails as WebPushRequestDetails, type RequestOpti
 import { type BrowserPushSubscription, BrowserPushSubscriptionSchema } from "../../contracts/user-notifications";
 import { normalizeNetworkHostname } from "../../shared/network-address";
 import { type PublicNetworkAddress, resolvePublicNetworkAddresses } from "../network-security";
+import { awaitNetworkOperation, readNetworkResponse, withNetworkDeadline } from "../network-transport";
 
 const RESPONSE_LIMIT_BYTES = 64 * 1_024;
 const REQUEST_TIMEOUT_MS = 15_000;
@@ -19,6 +20,7 @@ type RequestDetailsFactory = (
 type WebPushTransportDeps = {
   generateRequestDetails?: RequestDetailsFactory;
   request?: RequestFactory;
+  signal?: AbortSignal;
   resolve?: (hostname: string) => Promise<PublicNetworkAddress[]>;
 };
 
@@ -31,7 +33,9 @@ export const buildPinnedWebPushRequests = async (
   const validatedSubscription = BrowserPushSubscriptionSchema.parse(subscription);
   const endpoint = new URL(validatedSubscription.endpoint);
   const hostname = normalizeNetworkHostname(endpoint.hostname);
-  const resolvedAddresses = await (deps.resolve ?? resolvePublicNetworkAddresses)(hostname);
+  deps.signal?.throwIfAborted();
+  const resolving = (deps.resolve ?? resolvePublicNetworkAddresses)(hostname);
+  const resolvedAddresses = deps.signal ? await awaitNetworkOperation(resolving, deps.signal) : await resolving;
   const uniqueAddresses = resolvedAddresses.filter(
     (target, index) => resolvedAddresses.findIndex((candidate) => candidate.address === target.address) === index,
   );
@@ -61,32 +65,30 @@ export const buildPinnedWebPushRequests = async (
       headers: { ...details.headers, host: endpoint.host },
       servername: hostname,
       rejectUnauthorized: true,
-      timeout: REQUEST_TIMEOUT_MS,
     })),
   };
 };
 
-const sendPreparedWebPushRequest = async (request: RequestFactory, options: HttpsRequestOptions, body: Buffer | null): Promise<void> =>
-  new Promise<void>((resolve, reject) => {
-    let settled = false;
-    let responseReceived = false;
-    const finish = (result: { error?: Error }) => {
-      if (settled) return;
-      settled = true;
-      if (result.error) {
-        reject(responseReceived ? Object.assign(result.error, { providerResponse: true }) : result.error);
-      } else {
-        resolve();
-      }
-    };
-    const outgoing = request(options, (response) => {
+const sendPreparedWebPushRequest = (
+  request: RequestFactory,
+  options: HttpsRequestOptions,
+  body: Buffer | null,
+  signal: AbortSignal,
+): Promise<void> => {
+  let responseReceived = false;
+  return readNetworkResponse<void>({
+    request,
+    options,
+    body: body ?? undefined,
+    signal,
+    read: (response, resolve, reject) => {
       responseReceived = true;
+      const finish = (result: { error?: Error }) => (result.error ? reject(result.error) : resolve());
       let responseBody = "";
       let bytes = 0;
       response.on("data", (chunk: Buffer | string) => {
         bytes += Buffer.byteLength(chunk);
         if (bytes > RESPONSE_LIMIT_BYTES) {
-          response.destroy();
           finish({ error: new Error("Web Push provider response is too large") });
           return;
         }
@@ -105,31 +107,36 @@ const sendPreparedWebPushRequest = async (request: RequestFactory, options: Http
           }),
         });
       });
-      response.on("error", (error) => finish({ error }));
-    });
-    outgoing.on("timeout", () => outgoing.destroy(new Error("Web Push provider request timed out")));
-    outgoing.on("error", (error) => finish({ error }));
-    if (body) outgoing.write(body);
-    outgoing.end();
+    },
+  }).catch((error) => {
+    throw responseReceived ? Object.assign(error, { providerResponse: true }) : error;
   });
+};
 
 export const sendPinnedWebPush = async (
   subscription: BrowserPushSubscription,
   payload: string,
   options: WebPushRequestOptions,
   deps: WebPushTransportDeps = {},
-): Promise<void> => {
-  const request = deps.request ?? httpsRequest;
-  const prepared = await buildPinnedWebPushRequests(subscription, payload, options, deps);
-  let lastError: unknown;
-  for (const attempt of prepared.attempts) {
-    try {
-      await sendPreparedWebPushRequest(request, attempt, prepared.body);
-      return;
-    } catch (error) {
-      if (error && typeof error === "object" && "providerResponse" in error) throw error;
-      lastError = error;
-    }
-  }
-  throw lastError instanceof Error ? lastError : new Error("Web Push provider request failed");
-};
+): Promise<void> =>
+  withNetworkDeadline(
+    options.timeout ?? REQUEST_TIMEOUT_MS,
+    deps.signal,
+    new Error("Web Push provider request timed out"),
+    async (signal) => {
+      const request = deps.request ?? httpsRequest;
+      const prepared = await buildPinnedWebPushRequests(subscription, payload, options, { ...deps, signal });
+      let lastError: unknown;
+      for (const attempt of prepared.attempts) {
+        try {
+          await sendPreparedWebPushRequest(request, attempt, prepared.body, signal);
+          return;
+        } catch (error) {
+          signal.throwIfAborted();
+          if (error && typeof error === "object" && "providerResponse" in error) throw error;
+          lastError = error;
+        }
+      }
+      throw lastError instanceof Error ? lastError : new Error("Web Push provider request failed");
+    },
+  );

package/src/services/outgoing-mail/dispatcher.ts

@@ -4,6 +4,7 @@ import { Readable } from "node:stream";
 import { sql } from "bun";
 import { z } from "zod";
 import { listApps } from "../../_internal/registry";
+import { DownstreamBusyError, downstreamBudget } from "../downstream-budget";
 import { parsePgJsonValue } from "../postgres";
 import { get } from "../settings";
 import { deleteMailObjects, verifyMailAttachment } from "./attachments";
@@ -97,6 +98,7 @@ export const attemptOutgoingMail = async (row: MessageRow, signal?: AbortSignal)
     if (signal?.aborted) abort();
     const timer = setTimeout(abort, 60_000);
     const streams: Readable[] = [];
+    let releaseSmtp: (() => void) | undefined;
     try {
       for (const [index, ref] of refs.entries()) await verifyMailAttachment(ref, metadata[index]!, attempt.signal);
       const attachments = [];
@@ -131,6 +133,8 @@ export const attemptOutgoingMail = async (row: MessageRow, signal?: AbortSignal)
       }
       // Load the checked profile by ID: a profile deleted (or recreated under its key) since the check is profile_removed.
       credentials = await resolveMailCredentials({ id: row.profile_id });
+      releaseSmtp = await downstreamBudget.acquire({ downstream: "smtp", timeoutMs: 60_000, signal: attempt.signal });
+      attempt.signal.throwIfAborted();
       const socket = new Socket();
       // DNS can complete after cancellation; tear down a late connection too.
       socket.once("connect", () => {
@@ -182,6 +186,7 @@ export const attemptOutgoingMail = async (row: MessageRow, signal?: AbortSignal)
       signal?.removeEventListener("abort", abort);
       attempt.abort();
       for (const stream of streams) stream.destroy();
+      releaseSmtp?.();
     }
   } catch (error) {
     if (error instanceof OutgoingMailError && ["profile_unknown", "profile_removed"].includes(error.code)) {
@@ -196,7 +201,7 @@ export const attemptOutgoingMail = async (row: MessageRow, signal?: AbortSignal)
         ]
       : [];
     const message =
-      credentials || error instanceof OutgoingMailError
+      credentials || error instanceof OutgoingMailError || error instanceof DownstreamBusyError
         ? smtpFailureMessage(error, secrets)
         : "Outgoing mail delivery is temporarily unavailable.";
     const lost = error instanceof OutgoingMailError && error.code === "attachment_lost";

package/src/services/outgoing-mail/index.ts

@@ -1,7 +1,10 @@
 import { fail, ok, type Result } from "@k2b/stdlib";
+import { z } from "zod";
 import { getProcessApplicationId, getProcessPlatformPermissions } from "../../_internal/process-identity";
 import {
   MailBatchSchema,
+  type MailContent,
+  type MailContentContext,
   type MailFilter,
   MailFilterSchema,
   type MailMessage,
@@ -13,6 +16,7 @@ import {
   type MailRecord,
   type MailServiceError,
 } from "../../contracts/outgoing-mail";
+import { ServiceAccountSchema, UserSchema } from "../../contracts/shared";
 import { cancelMailStreams } from "./attachments";
 import { enqueueMail } from "./enqueue";
 import { outgoingMailMessages, recordMailBatch, recordMailSend } from "./messages";
@@ -36,13 +40,63 @@ const failure = (error: unknown): MailServiceError => {
   return {
     code: error.code,
     message: error.message,
-    status: error.code === "mail_unavailable" || error.status === 502 ? 500 : error.status,
+    status: error.code === "mail_unavailable" || error.status === 502 || error.status === 503 ? 500 : error.status,
     ...("limit" in error && typeof error.limit === "number" ? { limit: error.limit } : {}),
     ...("used" in error && typeof error.used === "number" ? { used: error.used } : {}),
     ...("requested" in error && typeof error.requested === "number" ? { requested: error.requested } : {}),
   };
 };
+// Runtime validation protects the transport boundary; authentication is owned by the caller's
+// trusted server context. Unknown actor fields never reach the read audit.
+const delegation = z.object({
+  kind: z.literal("invocation"),
+  callingAppId: z.string().min(1),
+  credentialKind: z.enum(["session", "oauth", "api_key", "mandate"]),
+  invocationId: z.string().min(1),
+  requestId: z.string().nullable().optional(),
+  mandateId: z.string().optional(),
+  mandateRevision: z.int().positive().optional(),
+  workloadType: z.string().optional(),
+  workloadId: z.string().optional(),
+});
+const contentContext = z.object({
+  actor: z.discriminatedUnion("kind", [
+    z.object({
+      kind: z.literal("user"),
+      user: UserSchema.refine((user) => z.uuid().safeParse(user.id).success && !!user.uid),
+      delegation: delegation.optional(),
+    }),
+    z.object({
+      kind: z.literal("service_account"),
+      serviceAccount: ServiceAccountSchema.refine((account) => account.status === "active"),
+      delegatedUser: UserSchema.nullable(),
+      scopes: z.array(z.string()),
+      delegation: delegation.optional(),
+    }),
+  ]),
+  requestId: z.string().optional(),
+});
 export const mail = {
+  async content(id: string, context: MailContentContext): Promise<Result<MailContent, MailServiceError>> {
+    const caller = identity(true);
+    if (!caller.ok) return caller;
+    const parsedId = z.uuid().safeParse(id);
+    const parsedContext = contentContext.safeParse(context);
+    if (!parsedId.success || !parsedContext.success)
+      return fail({ code: "bad_input", message: "Provide a valid mail ID and authenticated actor context.", status: 400 });
+    try {
+      return ok(
+        await outgoingMailMessages.appContent(
+          parsedId.data,
+          caller.data,
+          getProcessPlatformPermissions().includes("mail:read"),
+          parsedContext.data,
+        ),
+      );
+    } catch (error) {
+      return fail(failure(error));
+    }
+  },
   async readableApps(): Promise<Result<string[], MailServiceError>> {
     const caller = identity(true);
     if (!caller.ok) return caller;

package/src/services/outgoing-mail/messages.ts

@@ -4,6 +4,8 @@ import { z } from "zod";
 import {
   type AdminMailFilter,
   type AdminMailRecord,
+  type MailContent,
+  type MailContentContext,
   type MailFilter,
   type MailMessage,
   type MailPage,
@@ -17,7 +19,7 @@ import { audit } from "../audit";
 import { escapeLikePattern, parsePgJsonValue, toPgTextArray, toPgUuidArray } from "../postgres";
 import type { UploadedAttachments } from "./attachments";
 import { mailActorSnapshot, mailMessageId } from "./message";
-import { type MailAuditContext, OutgoingMailError } from "./store";
+import { type MailAuditContext, mailAppIdSha256, OutgoingMailError } from "./store";
 
 export type MessageRow = {
   id: string;
@@ -109,7 +111,7 @@ export const messageRecord = (row: LogRow): MailRecord => ({
   ...(row.error_message ? { error: row.error_message } : {}),
   failures: MailRecordSchema.shape.failures.parse(parsePgJsonValue(row.failures)),
   attempts: row.attempt_count,
-  ...(row.actor_id ? { actor: { id: row.actor_id, name: row.actor_name ?? row.actor_id } } : {}),
+  ...(row.actor_id ? { actor: { id: row.actor_id, name: row.actor_name ?? "" } } : {}),
   createdAt: date(row.created_at),
   ...(row.sent_at ? { sentAt: date(row.sent_at) } : {}),
   ...(row.content_purged_at ? { contentPurgedAt: date(row.content_purged_at) } : {}),
@@ -433,7 +435,84 @@ const content = async (id: string, context: MailAuditContext) =>
           headers: z.record(z.string(), z.string()).nullable().parse(parsePgJsonValue(row.headers)),
         };
   });
-export const outgoingMailMessages = { read, metadata, known, accept, list, content };
+/** One budget for database work, from transaction start through audit. Pool acquisition and commit are outside it. */
+const CONTENT_BUDGET_MS = 5_000;
+const appContent = async (id: string, readingAppId: string, canReadOtherApps: boolean, context: MailContentContext): Promise<MailContent> =>
+  sql.begin(async (tx) => {
+    const deadline = Date.now() + CONTENT_BUDGET_MS;
+    const limit = async () => {
+      const remaining = Math.floor(deadline - Date.now());
+      if (remaining < 1) throw new Error("Outgoing mail content DB budget exhausted.");
+      await tx`SELECT set_config('statement_timeout', ${`${remaining}ms`}, true)`;
+    };
+    await limit();
+    // Writers take this same key exclusively. Check grants in a fresh statement after acquiring it.
+    await tx`SELECT pg_advisory_xact_lock_shared(hashtextextended('outgoing_mail.policy', 0))`;
+    await limit();
+    const [row] = await tx<{ app_id: string; content_purged_at: Date | string | null; level: string | null }[]>`
+      SELECT m.app_id, m.content_purged_at, g.level FROM outgoing_mail.messages m
+      LEFT JOIN outgoing_mail.app_log_access g ON g.app_id = ${readingAppId} AND g.source_app_id = m.app_id
+      WHERE m.id = ${id}::uuid AND (m.app_id = ${readingAppId} OR
+        (${canReadOtherApps} AND ${readingAppId} <> 'core' AND m.app_id <> 'core' AND g.app_id IS NOT NULL))
+      FOR SHARE OF m`;
+    if (!row) throw new OutgoingMailError("message_unknown", "Outgoing mail message does not exist.", 404);
+    if (row.app_id !== readingAppId && row.level !== "content")
+      throw new OutgoingMailError("app_not_allowed", "This application may not read this mail content.", 403);
+    let result: MailContent;
+    if (row.content_purged_at !== null) result = { purged: true, contentPurgedAt: date(row.content_purged_at) };
+    else {
+      await limit();
+      // No body fetch before authorization. Never fetch HTML, headers, object refs or attachment digests.
+      const [body] = await tx<{ text_body: string | null; attachment_names: unknown }[]>`
+        SELECT text_body, ARRAY(SELECT item->>'filename' FROM jsonb_array_elements(attachments) AS item) AS attachment_names
+        FROM outgoing_mail.messages WHERE id = ${id}::uuid`;
+      if (!body) throw new Error("Locked outgoing mail disappeared.");
+      result = { purged: false, text: body.text_body, attachmentNames: z.array(z.string()).parse(body.attachment_names) };
+    }
+    const actor = context.actor;
+    const user = actor.kind === "user" ? actor.user : undefined;
+    const provenance = actor.delegation;
+    await limit();
+    await audit.record(
+      {
+        action: "outgoing_mail.message.read",
+        outcome: "allowed",
+        target: { type: "outgoing_mail_message", id },
+        actor: user ? { userId: user.id, uid: user.uid, provider: user.provider, roles: user.roles } : undefined,
+        requestId: context.requestId ?? provenance?.requestId,
+        metadata: {
+          appId: row.app_id,
+          appIdSha256: mailAppIdSha256(row.app_id),
+          readingAppId,
+          readingAppIdSha256: mailAppIdSha256(readingAppId),
+          actorKind: actor.kind,
+          ...(actor.kind === "service_account"
+            ? {
+                serviceAccountId: actor.serviceAccount.id,
+                ...(actor.delegatedUser ? { delegatedUserId: actor.delegatedUser.id } : {}),
+              }
+            : {}),
+          ...(provenance
+            ? {
+                delegation: {
+                  kind: provenance.kind,
+                  callingAppId: provenance.callingAppId,
+                  credentialKind: provenance.credentialKind,
+                  invocationId: provenance.invocationId,
+                  mandateId: provenance.mandateId,
+                  mandateRevision: provenance.mandateRevision,
+                  workloadType: provenance.workloadType,
+                  workloadId: provenance.workloadId,
+                },
+              }
+            : {}),
+        },
+      },
+      tx,
+    );
+    return result;
+  });
+export const outgoingMailMessages = { read, metadata, known, accept, list, content, appContent };
 
 /** Serialize updates to preserve failures from overlapping reports and replicas. */
 export const applyOutgoingMailBounce = async (

package/src/services/outgoing-mail/resolve-host.ts

@@ -5,7 +5,7 @@ import { NetworkTargetBlockedError, resolveAllowedNetworkAddresses } from "../ne
 export const outgoingMailAllowlist = () => parseNetworkAllowlistEnv("OUTGOING_MAIL_ALLOWED_TARGETS", env.OUTGOING_MAIL_ALLOWED_TARGETS);
 
 /** One bounded lookup shared by SMTP and bounce IMAP; clients use only the checked addresses. */
-export const resolveMailHost = async (host: string, signal?: AbortSignal, resolve = resolveAllowedNetworkAddresses) => {
+export const resolveMailHost = async (host: string, signal?: AbortSignal, resolve = resolveAllowedNetworkAddresses, port?: number) => {
   const hostname = normalizeNetworkHostname(host);
   const deadline = new AbortController();
   const timer = setTimeout(() => deadline.abort(new Error("Outgoing mail DNS lookup timed out.")), 5000);
@@ -14,7 +14,7 @@ export const resolveMailHost = async (host: string, signal?: AbortSignal, resolv
   try {
     cancellation.throwIfAborted();
     const addresses = await Promise.race([
-      resolve(hostname, outgoingMailAllowlist()),
+      resolve(hostname, outgoingMailAllowlist(), undefined, port),
       new Promise<never>((_, reject) => {
         abort = () => reject(cancellation.reason);
         cancellation.addEventListener("abort", abort, { once: true });

package/src/services/outgoing-mail/retention.ts

@@ -1,7 +1,7 @@
 import { sql } from "bun";
 import type { MailRetention } from "../../contracts/outgoing-mail";
 import { toPgUuidArray } from "../postgres";
-import { get } from "../settings";
+import { get, read } from "../settings";
 import { deleteMailObjects } from "./attachments";
 import { messageAttachmentRefs } from "./messages";
 
@@ -38,6 +38,18 @@ export const readMailRetention = async (): Promise<MailRetention> => ({
   contentDays: await get<number>(MAIL_RETENTION_KEYS[0]),
   recordDays: await get<number>(MAIL_RETENTION_KEYS[1]),
 });
+export const readMailRetentionSettings = async (db?: typeof sql) => {
+  const content = await read(MAIL_RETENTION_KEYS[0], db);
+  const record = await read(MAIL_RETENTION_KEYS[1], db);
+  return {
+    contentDays: Number(content.value),
+    recordDays: Number(record.value),
+    unreadable: {
+      [MAIL_RETENTION_KEYS[0]]: content.stored === "unreadable",
+      [MAIL_RETENTION_KEYS[1]]: record.stored === "unreadable",
+    },
+  };
+};
 export const retainOutgoingMail = async (signal?: AbortSignal): Promise<void> => {
   const { contentDays, recordDays } = await readMailRetention();
   const deadline = Date.now() + 5 * 60_000;