@sendmux/cli 1.5.0 → 1.7.0

package/dist/oauth-http.js

@@ -0,0 +1,113 @@
+export const OAUTH_RESOURCE = "https://sendmux.ai/api";
+export const DEFAULT_OAUTH_ISSUER = "https://app.sendmux.ai";
+export function oauthUrl(value, issuer) {
+    const url = new URL(value);
+    const loopback = url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+    if ((url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) ||
+        url.username ||
+        url.password ||
+        url.hash ||
+        url.search ||
+        (issuer && url.origin !== new URL(issuer).origin))
+        throw new Error("OAuth endpoints must use HTTPS and the configured issuer origin.");
+    return url;
+}
+export async function oauthRequest(endpoint, init = {}) {
+    oauthUrl(endpoint);
+    try {
+        const response = await fetch(endpoint, {
+            ...init,
+            redirect: "error",
+            signal: init.signal ?? AbortSignal.timeout(15_000),
+            headers: { Accept: "application/json", ...init.headers },
+        });
+        const reader = response.body?.getReader();
+        const chunks = [];
+        let bytes = 0;
+        if (reader) {
+            try {
+                while (true) {
+                    const chunk = await reader.read();
+                    if (chunk.done)
+                        break;
+                    bytes += chunk.value.byteLength;
+                    if (bytes > 256 * 1024)
+                        throw new Error("Response exceeds the OAuth size limit.");
+                    chunks.push(chunk.value);
+                }
+            }
+            finally {
+                await reader.cancel();
+            }
+        }
+        if (!response.ok)
+            throw new Error("OAuth request was rejected.");
+        if (bytes === 0)
+            return {};
+        if (!/^application\/json(?:;|$)/i.test(response.headers.get("content-type") ?? ""))
+            throw new Error("Invalid OAuth content type.");
+        const value = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error("Invalid OAuth response.");
+        return value;
+    }
+    catch {
+        throw new Error("OAuth request failed. Check the connection and try signing in again.");
+    }
+}
+export async function discoverOAuth(issuer, scopes) {
+    const url = oauthUrl(issuer);
+    const metadataUrl = `${url.origin}/.well-known/oauth-authorization-server${url.pathname === "/" ? "" : url.pathname}`;
+    const metadata = await oauthRequest(metadataUrl);
+    const supports = (field, value) => Array.isArray(metadata[field]) && metadata[field].includes(value);
+    if (metadata.issuer !== issuer ||
+        !supports("code_challenge_methods_supported", "S256") ||
+        !supports("token_endpoint_auth_methods_supported", "none") ||
+        metadata.authorization_response_iss_parameter_supported !== true ||
+        !supports("protected_resources", OAUTH_RESOURCE) ||
+        !scopes.every((scope) => supports("scopes_supported", scope)))
+        throw new Error("The issuer does not support the requested Sendmux OAuth connection.");
+    const endpoint = (name) => {
+        const value = metadata[name];
+        if (typeof value !== "string")
+            throw new Error("OAuth discovery is missing an endpoint.");
+        return oauthUrl(value, issuer).href;
+    };
+    return {
+        authorization: endpoint("authorization_endpoint"),
+        registration: endpoint("registration_endpoint"),
+        token: endpoint("token_endpoint"),
+        revocation: endpoint("revocation_endpoint"),
+    };
+}
+export function oauthTokenFields(value, allowedScopes) {
+    const validToken = (token) => typeof token === "string" && /^[A-Za-z0-9\-._~+/]+=*$/.test(token);
+    if (!validToken(value.access_token) ||
+        !validToken(value.refresh_token) ||
+        typeof value.token_type !== "string" ||
+        value.token_type.toLowerCase() !== "bearer" ||
+        typeof value.expires_in !== "number" ||
+        !Number.isSafeInteger(value.expires_in) ||
+        value.expires_in <= 0 ||
+        typeof value.scope !== "string")
+        throw new Error("The issuer returned invalid OAuth token metadata.");
+    const scopes = value.scope.split(" ").filter(Boolean);
+    if (!scopes.length || !scopes.every((scope) => allowedScopes.includes(scope)))
+        throw new Error("The issuer returned unexpected OAuth scopes.");
+    const expiresAt = Date.now() + value.expires_in * 1000;
+    if (!Number.isSafeInteger(expiresAt))
+        throw new Error("The issuer returned an invalid token lifetime.");
+    return {
+        accessToken: value.access_token,
+        refreshToken: value.refresh_token,
+        expiresAt,
+        scopes,
+    };
+}
+export function oauthForm(fields) {
+    return {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams(fields),
+    };
+}

package/dist/oauth-login.d.ts

@@ -0,0 +1,13 @@
+export declare function loginOAuth(input: {
+    configDir: string;
+    name: string;
+    issuer: string;
+    scopes: string[];
+    noBrowser: boolean;
+    report: (message: string) => void;
+}): Promise<{
+    profile: string;
+    type: string;
+    scopes: string[];
+}>;
+//# sourceMappingURL=oauth-login.d.ts.map

package/dist/oauth-login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-login.d.ts","sourceRoot":"","sources":["../src/oauth-login.ts"],"names":[],"mappings":"AAmBA,wBAAsB,UAAU,CAAC,KAAK,EAAE;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;;;;GAsJA"}

package/dist/oauth-login.js

@@ -0,0 +1,236 @@
+import { execFile } from "node:child_process";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { promisify } from "node:util";
+import { discoverOAuth, oauthForm, oauthRequest, oauthTokenFields, oauthUrl, OAUTH_RESOURCE, } from "./oauth-http.js";
+import { isOAuthProfile, updateCliConfig, } from "./profiles.js";
+export async function loginOAuth(input) {
+    const issuer = oauthUrl(input.issuer).href.replace(/\/$/, "");
+    const scopes = [
+        ...new Set(input.scopes.flatMap((scope) => scope.split(/\s+/)).filter(Boolean)),
+    ];
+    if (!scopes.length)
+        throw new Error("Choose at least one OAuth scope.");
+    const sessionId = randomUUID();
+    await updateCliConfig(input.configDir, (config) => {
+        if (config.profiles[input.name])
+            throw new Error("That profile already exists. Choose another name or log out first.");
+        config.profiles[input.name] = {
+            type: "oauth",
+            state: "authorizing",
+            sessionId,
+            issuer,
+        };
+    });
+    const abort = new AbortController();
+    const cancel = () => abort.abort();
+    process.once("SIGINT", cancel);
+    process.once("SIGTERM", cancel);
+    const timeout = setTimeout(cancel, 120_000);
+    let callback;
+    let activated;
+    try {
+        const endpoints = await discoverOAuth(issuer, scopes);
+        const state = randomBytes(32).toString("base64url");
+        const verifier = randomBytes(32).toString("base64url");
+        callback = await loopbackCallback({ state, issuer, signal: abort.signal });
+        const client = await oauthRequest(endpoints.registration, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                client_name: "Sendmux CLI",
+                application_type: "native",
+                redirect_uris: [callback.redirectUri],
+                grant_types: ["authorization_code", "refresh_token"],
+                response_types: ["code"],
+                token_endpoint_auth_method: "none",
+                resource: OAUTH_RESOURCE,
+                scope: scopes.join(" "),
+            }),
+        });
+        if (typeof client.client_id !== "string" ||
+            !client.client_id ||
+            client.token_endpoint_auth_method !== "none" ||
+            client.resource !== OAUTH_RESOURCE ||
+            !Array.isArray(client.redirect_uris) ||
+            client.redirect_uris.length !== 1 ||
+            client.redirect_uris[0] !== callback.redirectUri)
+            throw new Error("The issuer returned invalid client registration metadata.");
+        const url = new URL(endpoints.authorization);
+        url.search = new URLSearchParams({
+            client_id: client.client_id,
+            response_type: "code",
+            redirect_uri: callback.redirectUri,
+            scope: scopes.join(" "),
+            state,
+            resource: OAUTH_RESOURCE,
+            code_challenge_method: "S256",
+            code_challenge: createHash("sha256").update(verifier).digest("base64url"),
+        }).toString();
+        input.report(`Open this URL to sign in:\n${url.href}`);
+        if (!input.noBrowser)
+            await openBrowser(url.href).catch(() => input.report("Could not open the browser. Open the URL above to continue."));
+        const code = await callback.code;
+        await callback.close();
+        const fields = oauthTokenFields(await oauthRequest(endpoints.token, oauthForm({
+            grant_type: "authorization_code",
+            code,
+            code_verifier: verifier,
+            redirect_uri: callback.redirectUri,
+            client_id: client.client_id,
+            resource: OAUTH_RESOURCE,
+        })), scopes);
+        activated = {
+            type: "oauth",
+            state: "active",
+            sessionId,
+            issuer,
+            clientId: client.client_id,
+            tokenEndpoint: endpoints.token,
+            revocationEndpoint: endpoints.revocation,
+            ...fields,
+        };
+        const profile = activated;
+        await updateCliConfig(input.configDir, (config) => {
+            const existing = config.profiles[input.name];
+            if (!existing ||
+                !isOAuthProfile(existing) ||
+                existing.sessionId !== sessionId ||
+                existing.state !== "authorizing")
+                throw new Error("The login profile changed during authorization.");
+            config.profiles[input.name] = profile;
+            if (!config.defaultProfile)
+                config.defaultProfile = input.name;
+        });
+        return { profile: input.name, type: "oauth", scopes: profile.scopes };
+    }
+    catch (error) {
+        if (activated) {
+            await oauthRequest(activated.revocationEndpoint, oauthForm({
+                token: activated.refreshToken,
+                token_type_hint: "refresh_token",
+                client_id: activated.clientId,
+            })).catch(() => input.report("Could not revoke the interrupted login. Revoke the connection in Sendmux settings."));
+        }
+        await updateCliConfig(input.configDir, (config) => {
+            const existing = config.profiles[input.name];
+            if (existing &&
+                isOAuthProfile(existing) &&
+                existing.sessionId === sessionId &&
+                existing.state === "authorizing")
+                delete config.profiles[input.name];
+        });
+        throw error;
+    }
+    finally {
+        clearTimeout(timeout);
+        process.removeListener("SIGINT", cancel);
+        process.removeListener("SIGTERM", cancel);
+        await callback?.close();
+    }
+}
+async function openBrowser(url) {
+    const command = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "rundll32.exe"
+            : "xdg-open";
+    await promisify(execFile)(command, process.platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url], { timeout: 5_000 });
+}
+async function loopbackCallback({ state, issuer, signal, }) {
+    let resolveCode;
+    let rejectCode;
+    const code = new Promise((resolve, reject) => {
+        resolveCode = resolve;
+        rejectCode = reject;
+    });
+    // Attach before registration/browser work so cancellation cannot become an unhandled rejection.
+    void code.catch(() => undefined);
+    let redirectUri = "";
+    let received = false;
+    const server = createServer((request, response) => {
+        response.setHeader("Cache-Control", "no-store");
+        response.setHeader("Content-Type", "text/plain; charset=utf-8");
+        let url;
+        try {
+            url = new URL(request.url ?? "/", redirectUri);
+        }
+        catch {
+            response.writeHead(400);
+            response.end("Invalid authorization response.");
+            return;
+        }
+        const one = (key) => url.searchParams.getAll(key).length === 1;
+        const valid = request.method === "GET" &&
+            url.pathname === "/callback" &&
+            request.headers.host === new URL(redirectUri).host &&
+            one("state") &&
+            url.searchParams.get("state") === state &&
+            one("iss") &&
+            url.searchParams.get("iss") === issuer &&
+            ((one("code") &&
+                !url.searchParams.has("error") &&
+                !!url.searchParams.get("code")) ||
+                (one("error") && !url.searchParams.has("code")));
+        if (!valid || received) {
+            response.writeHead(400);
+            response.end("Invalid authorization response.");
+            return;
+        }
+        received = true;
+        response.setHeader("Content-Type", "text/html; charset=utf-8");
+        response.end('<!doctype html><meta charset="utf-8"><link rel="icon" href="data:image/svg+xml,%3Csvg%20xmlns=%27http://www.w3.org/2000/svg%27/%3E"><pre>Authorization received. You can return to the terminal.</pre>', () => {
+            if (url.searchParams.has("error"))
+                rejectCode(new Error("OAuth authorization was declined."));
+            else
+                resolveCode(url.searchParams.get("code"));
+        });
+    });
+    server.headersTimeout = 5_000;
+    server.requestTimeout = 10_000;
+    let host = "127.0.0.1";
+    for (const candidate of ["127.0.0.1", "::1"]) {
+        try {
+            await new Promise((resolve, reject) => {
+                const failed = (error) => {
+                    server.removeListener("listening", bound);
+                    reject(error);
+                };
+                const bound = () => {
+                    server.removeListener("error", failed);
+                    resolve();
+                };
+                server.once("error", failed);
+                server.once("listening", bound);
+                server.listen(0, candidate);
+            });
+            host = candidate;
+            break;
+        }
+        catch {
+            if (candidate === "::1")
+                throw new Error("Could not bind the OAuth callback listener.");
+        }
+    }
+    const address = server.address();
+    if (!address || typeof address === "string")
+        throw new Error("Could not bind the OAuth callback listener.");
+    redirectUri = `http://${host === "::1" ? "[::1]" : host}:${address.port}/callback`;
+    const cancel = () => rejectCode(new Error("OAuth login was cancelled or timed out."));
+    signal.addEventListener("abort", cancel, { once: true });
+    if (signal.aborted)
+        cancel();
+    let closing;
+    return {
+        redirectUri,
+        code,
+        close: () => {
+            if (closing)
+                return closing;
+            signal.removeEventListener("abort", cancel);
+            closing = new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())));
+            server.closeAllConnections();
+            return closing;
+        },
+    };
+}

package/dist/oauth-profile.d.ts

@@ -0,0 +1,6 @@
+export declare function resolveOAuthToken(configDir: string, name: string): Promise<string>;
+export declare function logoutOAuth(configDir: string, name: string): Promise<{
+    profile: string;
+    revoked: boolean;
+}>;
+//# sourceMappingURL=oauth-profile.d.ts.map

package/dist/oauth-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-profile.d.ts","sourceRoot":"","sources":["../src/oauth-profile.ts"],"names":[],"mappings":"AAsBA,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,CA4CjB;AA0DD,wBAAsB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;;;GA4ChE"}

package/dist/oauth-profile.js

@@ -0,0 +1,123 @@
+import { oauthForm, oauthRequest, oauthTokenFields, oauthUrl, OAUTH_RESOURCE, } from "./oauth-http.js";
+import { isOAuthProfile, readCliConfig, updateCliConfig, } from "./profiles.js";
+function activeProfile(profile) {
+    if (!profile || !isOAuthProfile(profile) || profile.state === "authorizing") {
+        throw new Error("The OAuth profile is not ready. Complete login first.");
+    }
+    return profile;
+}
+export async function resolveOAuthToken(configDir, name) {
+    const deadline = Date.now() + 20_000;
+    while (true) {
+        const profile = activeProfile((await readCliConfig(configDir)).profiles[name]);
+        if (profile.state === "revoking" || profile.state === "reauthorize") {
+            throw new Error("This OAuth profile needs a new login. Run auth:logout, then auth:login.");
+        }
+        if (profile.state === "active" && profile.expiresAt > Date.now() + 30_000)
+            return profile.accessToken;
+        if (profile.state === "refreshing") {
+            if (Date.now() >= deadline ||
+                Date.now() - (profile.refreshStartedAt ?? 0) >= 20_000) {
+                throw new Error("OAuth refresh did not finish. Log out and sign in again; the old refresh token will not be replayed.");
+            }
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            continue;
+        }
+        const reserved = await updateCliConfig(configDir, (config) => {
+            const current = activeProfile(config.profiles[name]);
+            if (current.state !== "active" ||
+                current.sessionId !== profile.sessionId ||
+                current.expiresAt > Date.now() + 30_000)
+                return null;
+            const next = {
+                ...current,
+                state: "refreshing",
+                refreshStartedAt: Date.now(),
+            };
+            config.profiles[name] = next;
+            return next;
+        });
+        if (!reserved)
+            continue;
+        return refreshReservedProfile(configDir, name, reserved);
+    }
+}
+async function refreshReservedProfile(configDir, name, profile) {
+    try {
+        const endpoint = oauthUrl(profile.tokenEndpoint, profile.issuer).href;
+        const fields = oauthTokenFields(await oauthRequest(endpoint, oauthForm({
+            grant_type: "refresh_token",
+            refresh_token: profile.refreshToken,
+            client_id: profile.clientId,
+            resource: OAUTH_RESOURCE,
+        })), profile.scopes);
+        await updateCliConfig(configDir, (config) => {
+            const current = activeProfile(config.profiles[name]);
+            if (current.sessionId !== profile.sessionId ||
+                current.state !== "refreshing" ||
+                current.refreshStartedAt !== profile.refreshStartedAt) {
+                throw new Error("The OAuth profile changed during refresh.");
+            }
+            const next = {
+                ...profile,
+                ...fields,
+                state: "active",
+            };
+            delete next.refreshStartedAt;
+            config.profiles[name] = next;
+        });
+        return fields.accessToken;
+    }
+    catch {
+        await updateCliConfig(configDir, (config) => {
+            const current = config.profiles[name];
+            if (current &&
+                isOAuthProfile(current) &&
+                current.state === "refreshing" &&
+                current.sessionId === profile.sessionId &&
+                current.refreshStartedAt === profile.refreshStartedAt) {
+                current.state = "reauthorize";
+            }
+        });
+        throw new Error("OAuth refresh failed. Log out and sign in again; the old refresh token will not be replayed.");
+    }
+}
+export async function logoutOAuth(configDir, name) {
+    const profile = await updateCliConfig(configDir, (config) => {
+        const stored = config.profiles[name];
+        if (stored && isOAuthProfile(stored) && stored.state === "authorizing") {
+            delete config.profiles[name];
+            if (config.defaultProfile === name)
+                delete config.defaultProfile;
+            return null;
+        }
+        const current = activeProfile(stored);
+        if (current.state === "refreshing" &&
+            Date.now() - (current.refreshStartedAt ?? 0) < 20_000) {
+            throw new Error("OAuth refresh is in progress. Retry logout when it finishes.");
+        }
+        const next = { ...current, state: "revoking" };
+        config.profiles[name] = next;
+        return next;
+    });
+    if (!profile)
+        return { profile: name, revoked: false };
+    const endpoint = oauthUrl(profile.revocationEndpoint, profile.issuer).href;
+    await oauthRequest(endpoint, oauthForm({
+        token: profile.refreshToken,
+        token_type_hint: "refresh_token",
+        client_id: profile.clientId,
+    }));
+    await updateCliConfig(configDir, (config) => {
+        const current = config.profiles[name];
+        if (current &&
+            isOAuthProfile(current) &&
+            current.sessionId === profile.sessionId &&
+            current.state === "revoking") {
+            delete config.profiles[name];
+            if (config.defaultProfile === name)
+                delete config.defaultProfile;
+        }
+    });
+    return { profile: name, revoked: true };
+}

package/dist/operation-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operation-runner.d.ts","sourceRoot":"","sources":["../src/operation-runner.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAsBhE,wBAAsB,eAAe,CACnC,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,mBAAmB,EAC9B,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,OAAO,CAAC,CAwElB"}
+{"version":3,"file":"operation-runner.d.ts","sourceRoot":"","sources":["../src/operation-runner.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAuBhE,wBAAsB,eAAe,CACnC,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,mBAAmB,EAC9B,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,OAAO,CAAC,CAwElB"}

package/dist/operation-runner.js

@@ -1,7 +1,12 @@
 import * as sdk from "@sendmux/sdk";
+import { createHash } from "node:crypto";
+import { closeSync, createReadStream, fsyncSync, openSync, writeSync } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
 import { basename, extname } from "node:path";
 import { parseOperationOptions, } from "./operation-flags.js";
+const MAX_SENDING_ATTACHMENTS = 10;
+// Absolute Sending service ceiling; deployment policy may impose a lower limit.
+const MAX_SENDING_ATTACHMENT_BYTES = 18 * 1024 * 1024;
 const surfaceModules = {
     mailbox: sdk.mailbox,
     management: sdk.management,
@@ -23,7 +28,7 @@ export async function runSdkOperation(command, operation, flags) {
         const auth = await command.resolveAuth(flags, operation.requiredKeyKind);
         baseUrl = auth.baseUrl;
         client = clientFactories[operation.surface]({
-            apiKey: auth.apiKey,
+            ...(auth.apiKeyKind === "oauth" ? { accessToken: auth.accessToken } : { apiKey: auth.apiKey }),
             ...(baseUrl ? { baseUrl } : {}),
         });
     }
@@ -160,13 +165,18 @@ async function uploadMailboxAttachmentFromFile(command, client, operationOptions
 async function withAttachedFiles(command, operation, client, operationOptions, flags) {
     const body = jsonObjectBody(command, operationOptions.body);
     const existingAttachments = attachmentArray(command, body.attachments);
+    if (operation.operationId === "sendingSendEmail"
+        && existingAttachments.length + (flags.attach?.length ?? 0) > MAX_SENDING_ATTACHMENTS) {
+        command.error(`Sending email supports at most ${MAX_SENDING_ATTACHMENTS} attachments, including existing attachments and files.`, { exit: 2 });
+    }
     const files = [];
+    const maxBytes = operation.operationId === "sendingSendEmail" ? MAX_SENDING_ATTACHMENT_BYTES : undefined;
     for (const path of flags.attach ?? []) {
-        files.push(await readAttachmentFile(command, path, flags["content-type"]));
+        files.push(await readAttachmentFile(command, path, flags["content-type"], maxBytes));
     }
     if (operation.operationId === "mailboxSendMessage") {
         const uploaded = [];
-        for (const file of files) {
+        for (const [ordinal, file] of files.entries()) {
             const uploadResponse = await sdk.mailbox.mailboxUploadAttachment({
                 client: client,
                 body: blobFor(file),
@@ -179,8 +189,10 @@ async function withAttachedFiles(command, operation, client, operationOptions, f
                 },
             });
             const result = envelopeData(uploadResponse, "mailboxUploadAttachment");
+            const blobId = stringField(result, "blob_id", "mailboxUploadAttachment");
+            journalNestedAttachment({ file, id: blobId, nestedOperationId: "mailboxUploadAttachment", operationId: operation.operationId, ordinal });
             uploaded.push({
-                blob_id: stringField(result, "blob_id", "mailboxUploadAttachment"),
+                blob_id: blobId,
                 content_type: stringField(result, "content_type", "mailboxUploadAttachment"),
                 filename: stringField(result, "filename", "mailboxUploadAttachment"),
             });
@@ -195,11 +207,19 @@ async function withAttachedFiles(command, operation, client, operationOptions, f
     }
     if (operation.operationId === "sendingSendEmail") {
         const uploaded = [];
-        for (const file of files) {
+        const outerKey = operationOptions.headers?.["Idempotency-Key"];
+        const idempotencyKey = typeof outerKey === "string" ? outerKey.trim() : undefined;
+        for (const [index, file] of files.entries()) {
             const uploadResponse = await sdk.sending.sendingUploadAttachment({
                 client: client,
                 body: blobFor(file),
                 headers: {
+                    ...(idempotencyKey ? {
+                        // Match the TS/Python helpers; content must not change the key and evade conflict detection.
+                        "Idempotency-Key": createHash("sha256")
+                            .update(`sendmux:sending:attachment:${index}:${idempotencyKey}`)
+                            .digest("hex"),
+                    } : {}),
                     "Content-Length": file.sizeBytes,
                     "Content-Type": file.contentType,
                 },
@@ -209,8 +229,10 @@ async function withAttachedFiles(command, operation, client, operationOptions, f
                 },
             });
             const result = envelopeData(uploadResponse, "sendingUploadAttachment");
+            const attachmentId = stringField(result, "attachment_id", "sendingUploadAttachment");
+            journalNestedAttachment({ file, id: attachmentId, nestedOperationId: "sendingUploadAttachment", operationId: operation.operationId, ordinal: index });
             uploaded.push({
-                attachment_id: stringField(result, "attachment_id", "sendingUploadAttachment"),
+                attachment_id: attachmentId,
             });
         }
         return {
@@ -237,7 +259,30 @@ async function withAttachedFiles(command, operation, client, operationOptions, f
         },
     };
 }
-async function readAttachmentFile(command, filePath, contentTypeOverride) {
+function journalNestedAttachment({ file, id, nestedOperationId, operationId, ordinal }) {
+    const path = process.env.SENDMUX_LIVE_E2E_ATTACHMENT_JOURNAL;
+    if (!path)
+        return;
+    const record = {
+        adapter: "cli",
+        filename: file.filename,
+        id,
+        operationId,
+        nestedOperationId,
+        ordinal,
+        sha256: createHash("sha256").update(file.bytes).digest("hex"),
+        size_bytes: file.sizeBytes,
+    };
+    const descriptor = openSync(path, "a", 0o600);
+    try {
+        writeSync(descriptor, `${JSON.stringify(record)}\n`, undefined, "utf8");
+        fsyncSync(descriptor);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+async function readAttachmentFile(command, filePath, contentTypeOverride, maxBytes) {
     const info = await stat(filePath).catch((error) => {
         const message = error instanceof Error ? error.message : String(error);
         command.error(`Could not read attachment file ${filePath}: ${message}`, { exit: 2 });
@@ -248,7 +293,26 @@ async function readAttachmentFile(command, filePath, contentTypeOverride) {
     if (info.size === 0) {
         command.error(`Attachment file is empty: ${filePath}`, { exit: 2 });
     }
-    const bytes = await readFile(filePath);
+    if (maxBytes !== undefined && info.size > maxBytes) {
+        command.error(`Attachment file exceeds ${maxBytes} bytes: ${filePath}`, { exit: 2 });
+    }
+    let bytes;
+    if (maxBytes === undefined) {
+        bytes = await readFile(filePath);
+    }
+    else {
+        const chunks = [];
+        // Include one excess byte so a growing file is rejected instead of truncated and uploaded.
+        for await (const chunk of createReadStream(filePath, { end: maxBytes }))
+            chunks.push(chunk);
+        bytes = Buffer.concat(chunks);
+        if (bytes.length > maxBytes) {
+            command.error(`Attachment file exceeds ${maxBytes} bytes: ${filePath}`, { exit: 2 });
+        }
+    }
+    if (bytes.length === 0) {
+        command.error(`Attachment file is empty: ${filePath}`, { exit: 2 });
+    }
     return {
         bytes,
         contentType: contentTypeOverride ?? inferContentType(filePath),