sently 0.4.1 → 0.4.4

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## [0.4.4] — 2026-05-30
+
+### Security
+
+- Fixed SigV4 date format: slice(0,15) not slice(0,16) — all real
+  SES requests were producing malformed x-amz-date headers
+- Added requireTLS guard before SMTP AUTH (default: true when auth
+  is set) — prevents credential exposure on STARTTLS-stripping attacks
+- Hardened email address validation against header and SMTP command
+  injection, enforced centrally in `parseAddresses()` (and re-asserted
+  at render time in `toMIMEHeader()`):
+  - Rejects CR, LF, NUL, all other C0 control characters (0x00–0x1F),
+    DEL (0x7F), and the Unicode line/paragraph separators U+2028/U+2029
+  - Fails closed: hostile input throws a clear error with the offending
+    code point instead of being accepted
+  - No repair or normalization of malicious input — addresses are never
+    transformed (e.g. CR/LF stripped) and then accepted
+  - Protects the display name as well as the address; an ASCII display
+    name such as `"Foo\r\nBcc: ..."` can no longer inject a header
+  - Enforced consistently across every address field (From, To, Cc, Bcc,
+    Reply-To) and every transport (SMTP, SES, Mailgun, Postmark, Resend,
+    SendGrid, Brevo), since all of them route through `parseAddresses()`
+- Sanitized attachment filenames and custom attachment headers
+  against MIME header injection
+- Fixed basePath startsWith sibling-directory bypass in
+  resolve-attachments (now appends path separator before comparison)
+- Added CRLF guard on EHLO domain for consistency
+
+## [0.4.3] — 2026-05-30
+
+### Added
+
+- `llms.txt` for LLM/agent discovery (install, quick example, subpath
+  exports, and when-to-use guidance)
+- README: Nodemailer comparison table, 30-second tour, error handling,
+  and TypeScript sections
+- `CLAUDE.md` repository map for agents (core entry, adapters,
+  transports, tests, build)
+
+### Changed
+
+- README positioning, HTTP transport reference table, plugin docs
+  reorder, and tree-shaking callout
+- `package.json` description and npm keywords for discoverability
+
+## [0.4.2] — 2026-05-30
+
+### Fixed
+
+- CI: replaced node -e dynamic import with scripts/smoke.mjs
+  (top-level await ESM) for reliable Node.js smoke testing
+- CI: integration test now imports from dist/index.js directly
+  instead of relying on package self-reference resolution
+- CI: updated GitHub Actions to latest patch versions
+
 ## [0.4.1] — 2026-05-30
 
 ### Fixed

package/README.md

@@ -1,6 +1,11 @@
 # sently
 
-**Runtime-agnostic email library for Node.js, Bun, Deno, and Cloudflare Workers.**
+> Nodemailer hasn't been updated in years, doesn't run on Bun or Deno, and ships at 220KB.
+> sently is the modern replacement — same familiar API, runs everywhere, tree-shakes to ~6KB.
+
+```bash
+bun add sently
+```
 
 [![npm version](https://img.shields.io/npm/v/sently.svg)](https://www.npmjs.com/package/sently)
 [![JSR](https://jsr.io/badges/@alialnaghmoush/sently)](https://jsr.io/@alialnaghmoush/sently)
@@ -11,17 +16,62 @@
 
 ---
 
-## Why sently
+## Why not Nodemailer?
+
+| Feature | Nodemailer | sently |
+|---------|-----------|--------|
+| Bundle size | ~220 KB | ~6 KB core |
+| Runtimes | Node.js only | Node, Bun, Deno, CF Workers |
+| Module format | CommonJS | ESM only |
+| Dependencies | 3 | 0 |
+| DKIM signing | ✓ via `nodemailer-dkim` | ✓ built-in (Web Crypto) |
+| OAuth2 / XOAUTH2 | ✓ via plugin | ✓ built-in |
+| Connection pooling | ✓ | ✓ |
+| HTTP transports | ✓ via plugins | ✓ built-in (6 providers) |
+| Retry transport | ✗ | ✓ |
+| Preview transport | ✗ | ✓ |
+| Template engine | ✗ | ✓ |
+| `sendBulk()` | ✗ | ✓ |
+| TypeScript | via `@types/nodemailer` | ✓ built-in |
+| Last release | 2021 | 2026 |
+
+---
+
+## The 30-second tour
+
+```typescript
+import { createMailer, type MailOptions } from "sently";
+import { ResendTransport } from "sently/transports/resend";
+import { PreviewTransport } from "sently/transports/preview";
+
+const addFooter = (options: MailOptions): MailOptions => ({
+  ...options,
+  html: (options.html ?? "") + '<p style="color:#999">Unsubscribe</p>',
+});
+
+// Swap providers without changing send code
+const mailer = await createMailer({
+  transport: new ResendTransport({ apiKey: process.env.RESEND_API_KEY! }),
+  plugins: [addFooter],
+});
+
+await mailer.send({
+  from: "you@example.com",
+  to: "recipient@example.com",
+  subject: "Hello from sently",
+  html: "<p>Hello!</p>",
+});
+
+// Bulk send with concurrency control
+await mailer.sendBulk(recipients, { concurrency: 5 });
 
-- **Works everywhere** — Node.js, Bun, Deno, Cloudflare Workers, and any environment with Web APIs
-- **True tree-shaking** — import only what you need; unused adapters and transports stay out of your bundle
-- **Zero dependencies in core** — MIME, SMTP protocol, and encoding use pure Web APIs only
-- **Plugin system** — transform `MailOptions` before send with composable middleware
-- **HTTP transports** — Resend, SendGrid, Postmark, Mailgun, AWS SES, and Brevo
-- **DKIM signing** — RSA-SHA256 and Ed25519-SHA256 via Web Crypto
-- **OAuth2 / XOAUTH2** — Gmail and Microsoft 365 SMTP auth with automatic token refresh
-- **Connection pooling** — reuse SMTP sessions with optional rate limiting
-- **TypeScript-first** — strict types, subpath exports, and full IDE support
+// Local dev — write to disk instead of sending
+const devMailer = await createMailer({
+  transport: process.env.CI
+    ? new ResendTransport({ apiKey: process.env.RESEND_API_KEY! })
+    : new PreviewTransport({ outDir: ".emails", open: true }),
+});
+```
 
 ---
 
@@ -164,6 +214,8 @@ await mailer.verify(); // test connection + auth
 
 **AUTH methods:** XOAUTH2, CRAM-MD5, LOGIN, and PLAIN (auto-negotiated from EHLO unless `auth.type` is set).
 
+**`requireTLS` (default `true` when `auth` is set):** sently refuses to send credentials over an unencrypted connection. If the link is not secured by direct TLS (`secure: true`) or a successful `STARTTLS` upgrade, authentication throws an `SMTPError` instead of leaking credentials — this defends against STARTTLS-stripping MITM attacks. Set `requireTLS: false` only if you fully trust the network (not recommended).
+
 #### DKIM signing
 
 ```typescript
@@ -228,63 +280,19 @@ const pool = new SMTPPool({
 
 ### HTTP APIs
 
-#### Resend
-
-```typescript
-import { ResendTransport } from "sently/transports/resend";
-
-const transport = new ResendTransport({ apiKey: "re_..." });
-```
-
-#### SendGrid
+| Transport | Import path | Required config |
+|-----------|-------------|-----------------|
+| Resend | `sently/transports/resend` | `apiKey` |
+| SendGrid | `sently/transports/sendgrid` | `apiKey` |
+| Postmark | `sently/transports/postmark` | `serverToken` |
+| Mailgun | `sently/transports/mailgun` | `apiKey`, `domain` |
+| AWS SES | `sently/transports/ses` | `accessKeyId`, `secretAccessKey`, `region` |
+| Brevo | `sently/transports/brevo` | `apiKey` |
 
-```typescript
-import { SendGridTransport } from "sently/transports/sendgrid";
-
-const transport = new SendGridTransport({ apiKey: "SG...." });
-```
-
-#### Postmark
-
-```typescript
-import { PostmarkTransport } from "sently/transports/postmark";
-
-const transport = new PostmarkTransport({ serverToken: "..." });
-```
-
-#### Mailgun
-
-```typescript
-import { MailgunTransport } from "sently/transports/mailgun";
-
-const transport = new MailgunTransport({
-  apiKey: "key-...",
-  domain: "mg.example.com",
-});
-```
-
-#### AWS SES
-
-```typescript
-import { SESTransport } from "sently/transports/ses";
-
-const transport = new SESTransport({
-  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-  region: "us-east-1",
-});
-```
+All transports implement the same interface — swap without changing your send code.
 
 Messages with attachments are sent as raw MIME (`Content.Raw`); simple messages use `Content.Simple`.
 
-#### Brevo
-
-```typescript
-import { BrevoTransport } from "sently/transports/brevo";
-
-const transport = new BrevoTransport({ apiKey: "xkeysib-..." });
-```
-
 ### PreviewTransport
 
 Write emails to disk during local development instead of sending them:
@@ -346,6 +354,38 @@ const result = await mailer.sendBulk(
 console.log(result.sent, result.failed);
 ```
 
+---
+
+## Plugin system
+
+Plugins transform `MailOptions` before the transport builds and sends the message. They run sequentially — each receives the output of the previous plugin.
+
+```typescript
+import { createMailer, type MailOptions } from "sently";
+
+const addFooter = (options: MailOptions) => ({
+  ...options,
+  html: (options.html ?? "") + '<p style="color:#999">Unsubscribe</p>',
+});
+
+const mailer = await createMailer({
+  host: "smtp.resend.com",
+  port: 465,
+  secure: true,
+  auth: { user: "resend", pass: process.env.RESEND_API_KEY! },
+  plugins: [addFooter],
+});
+```
+
+Works with SMTP config or custom transports:
+
+```typescript
+const mailer = await createMailer({
+  transport: new ResendTransport({ apiKey: "re_..." }),
+  plugins: [addFooter],
+});
+```
+
 ### TemplatePlugin
 
 Render HTML from named templates with zero dependencies:
@@ -378,36 +418,6 @@ await mailer.send({
 
 Use a custom engine by passing any `(template, data) => string` function to `templatePlugin`.
 
-### Plugin system
-
-Plugins transform `MailOptions` before the transport builds and sends the message. They run sequentially — each receives the output of the previous plugin.
-
-```typescript
-import { createMailer, type MailOptions } from "sently";
-
-const addFooter = (options: MailOptions) => ({
-  ...options,
-  html: (options.html ?? "") + '<p style="color:#999">Unsubscribe</p>',
-});
-
-const mailer = await createMailer({
-  host: "smtp.resend.com",
-  port: 465,
-  secure: true,
-  auth: { user: "resend", pass: process.env.RESEND_API_KEY! },
-  plugins: [addFooter],
-});
-```
-
-Works with SMTP config or custom transports:
-
-```typescript
-const mailer = await createMailer({
-  transport: new ResendTransport({ apiKey: "re_..." }),
-  plugins: [addFooter],
-});
-```
-
 ---
 
 ## MailOptions Reference
@@ -469,6 +479,77 @@ On Cloudflare Workers and browsers, use `content: Uint8Array` — `attachment.pa
 
 ---
 
+## Error Handling
+
+```typescript
+import { SMTPError } from "sently";
+import { ResendError } from "sently/transports/resend";
+// Each HTTP transport exports its own error class:
+// SendGridError  → sently/transports/sendgrid
+// PostmarkError  → sently/transports/postmark
+// MailgunError   → sently/transports/mailgun
+// SESError       → sently/transports/ses
+// BrevoError     → sently/transports/brevo
+
+try {
+  await mailer.send({ ... });
+} catch (err) {
+  if (err instanceof SMTPError) {
+    console.error(err.code);     // SMTP response code, e.g. 550
+    console.error(err.command);  // failed command, e.g. "RCPT TO"
+  }
+  if (err instanceof ResendError) {
+    console.error(err.statusCode); // HTTP status code
+  }
+}
+```
+
+Import error classes from their transport subpath — not from `sently` core. Each exports a `statusCode` property on HTTP failures.
+
+---
+
+## Security
+
+sently is built to be secure by default — protections are enforced at the library's core chokepoints, so they apply to every transport and every address field without any extra configuration.
+
+### Email header & SMTP command injection
+
+All addresses **and** display names are validated centrally in `parseAddresses()` (and re-asserted when rendering headers), before any normalization:
+
+- Rejects CR, LF, NUL, every other C0 control (`0x00`–`0x1F`), DEL (`0x7F`), and the Unicode line/paragraph separators `U+2028`/`U+2029`.
+- **Fails closed:** hostile input throws a clear error (with the offending code point) — it is never stripped, repaired, and then accepted.
+- Protects the **display name** too, so an ASCII name like `"Foo\r\nBcc: attacker@evil.com"` can no longer inject a header.
+- Enforced consistently across **From, To, Cc, Bcc, and Reply-To**, and across **every transport** (SMTP, SES, Mailgun, Postmark, Resend, SendGrid, Brevo).
+
+```typescript
+await mailer.send({
+  from: "you@example.com",
+  to: { address: "victim@x.com\r\nBcc: attacker@evil.com" },
+  subject: "Hi",
+  text: "...",
+});
+// → throws: Email address contains a forbidden control character (0x0d)
+```
+
+MIME attachment filenames and custom attachment headers are likewise sanitized against header injection.
+
+### Credential protection
+
+- **`requireTLS`** (default `true` when `auth` is set) refuses to authenticate over a cleartext connection, defeating STARTTLS-stripping downgrade attacks.
+- **OAuth2 / XOAUTH2** and DKIM signing are built in via Web Crypto — no plaintext secrets in transit beyond what the protocol requires.
+
+### Attachments
+
+> ⚠️ `attachment.path` reads files from disk. Never pass user-controlled paths without validation.
+
+`resolveAttachments()` accepts an opt-in `basePath` that confines reads to an allowed directory and rejects path-traversal (including sibling-directory prefix tricks like `/var/data-secret` vs `/var/data`). Note: `basePath` does not dereference symlinks — use `fs.realpath()` first if symlink traversal is a concern.
+
+### Supply chain
+
+**Zero runtime dependencies** — there is no transitive dependency tree to audit or to be compromised.
+
+---
+
 ## Tree-Shaking
 
 Each import path is a separate build entry point:
@@ -518,6 +599,24 @@ Approximate gzip sizes per subpath export:
 | `sently/adapters/deno` | ~2 KB |
 | `sently/adapters/cf` | ~2 KB |
 
+> **Example:** Resend only = core (~6 KB) + transport (~2 KB) = **~8 KB total**. Nodemailer ships 220 KB regardless of which transport you use.
+
+---
+
+## TypeScript
+
+```typescript
+import type {
+  MailOptions,
+  MailPlugin,
+  SendResult,
+  Attachment,
+  SMTPConfig,
+} from "sently";
+```
+
+All types ship with the package — no separate `@types/` install needed.
+
 ---
 
 ## Links

package/dist/{chunk-z3eq2t1d.js → chunk-7fqv71z1.js}

@@ -1,6 +1,9 @@
+import {
+  OAuth2Client
+} from "./chunk-ym3zzv8b.js";
 import {
   buildMIME
-} from "./chunk-j6qw8ms6.js";
+} from "./chunk-x3szga4k.js";
 import {
   SMTPError,
   accumulateResponse,
@@ -13,13 +16,10 @@ import {
   parseEHLO,
   parseResponse,
   selectAuthMethod
-} from "./chunk-tjsgb3qb.js";
-import {
-  OAuth2Client
-} from "./chunk-ym3zzv8b.js";
+} from "./chunk-tymfm441.js";
 import {
   resolveAttachments
-} from "./chunk-bvxkmq94.js";
+} from "./chunk-f4c9ttmr.js";
 import {
   __require
 } from "./chunk-v0bahtg2.js";
@@ -87,6 +87,7 @@ function resolveSMTPConfig(config) {
     port: config.port ?? (secure ? 465 : 587),
     secure,
     ...config.auth !== undefined ? { auth: config.auth } : {},
+    ...config.requireTLS !== undefined ? { requireTLS: config.requireTLS } : {},
     ...config.dkim !== undefined ? { dkim: config.dkim } : {},
     ...config.tls !== undefined ? { tls: config.tls } : {},
     ...config.connectionTimeout !== undefined ? { connectionTimeout: config.connectionTimeout } : {},
@@ -100,7 +101,8 @@ async function openSMTPSession(adapter, config) {
   const greeting = await readSMTPResponse(adapter);
   assertResponse(greeting, [220], "greeting");
   let capabilities = await ehlo(adapter, config.host);
-  if (!config.secure && !adapter.secure) {
+  const supportsStartTls = capabilities.some((cap) => cap.toUpperCase() === "STARTTLS");
+  if (!config.secure && !adapter.secure && supportsStartTls) {
     await sendRaw(adapter, encodeCommand({ type: "STARTTLS" }));
     const starttlsResp = await readSMTPResponse(adapter);
     assertResponse(starttlsResp, [220], "STARTTLS");
@@ -108,6 +110,11 @@ async function openSMTPSession(adapter, config) {
     capabilities = await ehlo(adapter, config.host);
   }
   if (config.auth) {
+    const tlsRequired = config.requireTLS ?? true;
+    const encrypted = adapter.secure || config.secure;
+    if (tlsRequired && !encrypted) {
+      throw new SMTPError("Refusing to authenticate over unencrypted connection. " + "Set requireTLS: false to disable this check (not recommended).", 0, "AUTH", "");
+    }
     await authenticate(adapter, config.auth, capabilities);
   }
 }
@@ -241,4 +248,4 @@ async function resolveMX(domain) {
 }
 export { SMTPTransport, resolveSMTPConfig, openSMTPSession, deliverSMTPMessage, closeSMTPSession, readSMTPResponse };
 
-//# debugId=58BDA0CC5C272AF664756E2164756E21
+//# debugId=736A9106E3164FC464756E2164756E21

package/dist/chunk-7fqv71z1.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/transports/smtp.ts"],
+  "sourcesContent": [
+    "/**\n * @module\n * SMTP transport — orchestrates socket adapter, MIME builder, and protocol logic.\n *\n * @example\n * ```ts\n * import { SMTPTransport } from \"sently/transports/smtp\";\n * import { NodeAdapter } from \"sently/adapters/node\";\n * import { createMailer } from \"sently\";\n *\n * const mailer = await createMailer({\n *   transport: new SMTPTransport({\n *     host: \"smtp.example.com\",\n *     auth: { user: \"you@example.com\", pass: \"secret\" },\n *     adapter: new NodeAdapter(),\n *   }),\n * });\n * ```\n */\nimport { OAuth2Client } from \"../auth/oauth2.js\";\nimport { buildMIME, type MIMEBuildResult } from \"../core/mime.js\";\nimport type { SMTPResponse } from \"../core/smtp.js\";\nimport {\n  accumulateResponse,\n  assertResponse,\n  computeCRAMMD5,\n  encodeAuthLoginPass,\n  encodeAuthLoginUser,\n  encodeCommand,\n  encodeLine,\n  parseEHLO,\n  parseResponse,\n  SMTPError,\n  selectAuthMethod,\n} from \"../core/smtp.js\";\nimport type {\n  MailOptions,\n  SendResult,\n  SMTPConfig,\n  SocketAdapter,\n  Transport,\n  VerifyResult,\n} from \"../core/types.js\";\nimport { resolveAttachments } from \"./resolve-attachments.js\";\n\n/**\n * SMTP transport orchestrating adapter, MIME builder, and protocol logic.\n */\nexport class SMTPTransport implements Transport {\n  private readonly config: ResolvedSMTPConfig;\n  private adapter: SocketAdapter | null = null;\n\n  /** Creates an SMTP transport with the given configuration. */\n  constructor(config: SMTPConfig) {\n    this.config = resolveSMTPConfig(config);\n  }\n\n  /** Sends an email via SMTP using the configured adapter. */\n  async send(options: MailOptions): Promise<SendResult> {\n    const resolvedOptions = {\n      ...options,\n      attachments: await resolveAttachments(options.attachments),\n    };\n    const mime = await buildMIME(resolvedOptions, this.config.dkim);\n    const adapter = await this.getAdapter();\n\n    const host = this.config.direct\n      ? await resolveMX(mime.envelope.from.split(\"@\")[1] ?? this.config.host)\n      : this.config.host;\n\n    await adapter.connect(host, this.config.port);\n    this.adapter = adapter;\n\n    try {\n      await openSMTPSession(adapter, this.config);\n      return await deliverSMTPMessage(adapter, mime);\n    } finally {\n      await closeSMTPSession(adapter);\n      this.adapter = null;\n    }\n  }\n\n  /** Verifies SMTP connectivity and authentication without sending mail. */\n  async verify(): Promise<VerifyResult> {\n    try {\n      const adapter = await this.getAdapter();\n      await adapter.connect(this.config.host, this.config.port);\n\n      try {\n        await openSMTPSession(adapter, this.config);\n        return { ok: true, provider: \"smtp\" };\n      } finally {\n        await closeSMTPSession(adapter);\n      }\n    } catch (err) {\n      return {\n        ok: false,\n        provider: \"smtp\",\n        message: err instanceof Error ? err.message : String(err),\n      };\n    }\n  }\n\n  /** Closes the underlying socket adapter if connected. */\n  async close(): Promise<void> {\n    if (this.adapter) {\n      await this.adapter.close();\n      this.adapter = null;\n    }\n  }\n\n  private async getAdapter(): Promise<SocketAdapter> {\n    if (!this.config.adapter) {\n      throw new SMTPError(\"No socket adapter configured\", 0, \"CONNECT\", \"\");\n    }\n    return this.config.adapter;\n  }\n}\n\n/** Resolved SMTP transport configuration with defaults applied. */\nexport interface ResolvedSMTPConfig {\n  host: string;\n  port: number;\n  secure: boolean;\n  auth?: SMTPConfig[\"auth\"];\n  requireTLS?: boolean;\n  tls?: SMTPConfig[\"tls\"];\n  dkim?: SMTPConfig[\"dkim\"];\n  connectionTimeout?: number;\n  greetingTimeout?: number;\n  socketTimeout?: number;\n  direct?: boolean;\n  adapter?: SocketAdapter;\n}\n\n/** Apply defaults to SMTP configuration. */\nexport function resolveSMTPConfig(config: SMTPConfig): ResolvedSMTPConfig {\n  const secure = config.secure ?? false;\n  return {\n    host: config.host,\n    port: config.port ?? (secure ? 465 : 587),\n    secure,\n    ...(config.auth !== undefined ? { auth: config.auth } : {}),\n    ...(config.requireTLS !== undefined ? { requireTLS: config.requireTLS } : {}),\n    ...(config.dkim !== undefined ? { dkim: config.dkim } : {}),\n    ...(config.tls !== undefined ? { tls: config.tls } : {}),\n    ...(config.connectionTimeout !== undefined\n      ? { connectionTimeout: config.connectionTimeout }\n      : {}),\n    ...(config.greetingTimeout !== undefined ? { greetingTimeout: config.greetingTimeout } : {}),\n    ...(config.socketTimeout !== undefined ? { socketTimeout: config.socketTimeout } : {}),\n    ...(config.direct !== undefined ? { direct: config.direct } : {}),\n    ...(config.adapter !== undefined ? { adapter: config.adapter } : {}),\n  };\n}\n\n/**\n * Connect greeting, EHLO, optional STARTTLS, and AUTH on an open adapter.\n */\nexport async function openSMTPSession(\n  adapter: SocketAdapter,\n  config: ResolvedSMTPConfig,\n): Promise<void> {\n  const greeting = await readSMTPResponse(adapter);\n  assertResponse(greeting, [220], \"greeting\");\n\n  let capabilities = await ehlo(adapter, config.host);\n  const supportsStartTls = capabilities.some((cap) => cap.toUpperCase() === \"STARTTLS\");\n  if (!config.secure && !adapter.secure && supportsStartTls) {\n    await sendRaw(adapter, encodeCommand({ type: \"STARTTLS\" }));\n    const starttlsResp = await readSMTPResponse(adapter);\n    assertResponse(starttlsResp, [220], \"STARTTLS\");\n    await adapter.startTLS(config.tls);\n    capabilities = await ehlo(adapter, config.host);\n  }\n\n  if (config.auth) {\n    const tlsRequired = config.requireTLS ?? true;\n    const encrypted = adapter.secure || config.secure;\n    if (tlsRequired && !encrypted) {\n      throw new SMTPError(\n        \"Refusing to authenticate over unencrypted connection. \" +\n          \"Set requireTLS: false to disable this check (not recommended).\",\n        0,\n        \"AUTH\",\n        \"\",\n      );\n    }\n    await authenticate(adapter, config.auth, capabilities);\n  }\n}\n\n/**\n * MAIL FROM, RCPT TO, and DATA for a built MIME message on an authenticated session.\n */\nexport async function deliverSMTPMessage(\n  adapter: SocketAdapter,\n  mime: MIMEBuildResult,\n): Promise<SendResult> {\n  await sendCommand(adapter, { type: \"MAIL_FROM\", address: mime.envelope.from });\n  const mailResp = await readSMTPResponse(adapter);\n  assertResponse(mailResp, [250], \"MAIL FROM\");\n\n  const accepted: string[] = [];\n  const rejected: string[] = [];\n\n  for (const recipient of mime.envelope.to) {\n    await sendRaw(adapter, encodeCommand({ type: \"RCPT_TO\", address: recipient }));\n    const rcptResp = await readSMTPResponse(adapter);\n    if (rcptResp.isSuccess) {\n      accepted.push(recipient);\n    } else {\n      rejected.push(recipient);\n    }\n  }\n\n  await sendCommand(adapter, { type: \"DATA\" });\n  const dataResp = await readSMTPResponse(adapter);\n  assertResponse(dataResp, [354], \"DATA\");\n\n  let finalResp: SMTPResponse;\n  try {\n    await sendRaw(adapter, encodeCommand({ type: \"DATA_BODY\", content: mime.raw }));\n    finalResp = await readSMTPResponse(adapter);\n  } catch (err) {\n    await sendRaw(adapter, encodeCommand({ type: \"DATA_BODY\", content: mime.raw }));\n    finalResp = await readSMTPResponse(adapter);\n    if (finalResp.isError) {\n      throw err;\n    }\n  }\n  assertResponse(finalResp, [250], \"DATA end\");\n\n  return {\n    messageId: mime.messageId,\n    accepted,\n    rejected,\n    response: finalResp.message,\n    envelope: mime.envelope,\n  };\n}\n\n/**\n * QUIT and close an SMTP session adapter.\n */\nexport async function closeSMTPSession(adapter: SocketAdapter): Promise<void> {\n  try {\n    await sendCommand(adapter, { type: \"QUIT\" });\n    await readSMTPResponse(adapter);\n  } catch {\n    // ignore errors during shutdown\n  } finally {\n    await adapter.close();\n  }\n}\n\nasync function ehlo(adapter: SocketAdapter, host: string): Promise<string[]> {\n  await sendCommand(adapter, { type: \"EHLO\", domain: host });\n  const response = await readSMTPResponse(adapter);\n  assertResponse(response, [250], \"EHLO\");\n  return parseEHLO(response);\n}\n\nasync function authenticate(\n  adapter: SocketAdapter,\n  auth: NonNullable<SMTPConfig[\"auth\"]>,\n  capabilities: string[],\n): Promise<void> {\n  if (auth.type === \"OAUTH2\" && auth.oauth2) {\n    const client = new OAuth2Client(auth.oauth2);\n    const xoauth2 = await client.buildXOAUTH2();\n    await sendCommand(adapter, { type: \"AUTH_XOAUTH2\", xoauth2String: xoauth2 });\n    let resp = await readSMTPResponse(adapter);\n    if (resp.code === 334) {\n      await sendRaw(adapter, encodeLine(\"\"));\n      resp = await readSMTPResponse(adapter);\n    }\n    assertResponse(resp, [235], \"AUTH XOAUTH2\");\n    return;\n  }\n\n  const method = auth.type ?? selectAuthMethod(capabilities);\n\n  if (method === \"CRAM-MD5\") {\n    const pass = requirePassword(auth, \"CRAM-MD5\");\n    await sendCommand(adapter, { type: \"AUTH_CRAM_MD5_INIT\" });\n    let resp = await readSMTPResponse(adapter);\n    assertResponse(resp, [334], \"AUTH CRAM-MD5\");\n    const challenge = resp.message.trim();\n    const response = await computeCRAMMD5(challenge, auth.user, pass);\n    await sendCommand(adapter, { type: \"AUTH_CRAM_MD5_RESPONSE\", response });\n    resp = await readSMTPResponse(adapter);\n    assertResponse(resp, [235], \"AUTH CRAM-MD5 response\");\n    return;\n  }\n\n  if (method === \"PLAIN\") {\n    const pass = requirePassword(auth, \"PLAIN\");\n    await sendRaw(adapter, encodeCommand({ type: \"AUTH_PLAIN\", user: auth.user, pass }));\n    const resp = await readSMTPResponse(adapter);\n    assertResponse(resp, [235], \"AUTH PLAIN\");\n    return;\n  }\n\n  const pass = requirePassword(auth, \"LOGIN\");\n  await sendRaw(adapter, encodeCommand({ type: \"AUTH_LOGIN\", user: auth.user, pass }));\n  let resp = await readSMTPResponse(adapter);\n  assertResponse(resp, [334], \"AUTH LOGIN\");\n\n  await sendRaw(adapter, encodeAuthLoginUser(auth.user));\n  resp = await readSMTPResponse(adapter);\n  assertResponse(resp, [334], \"AUTH LOGIN user\");\n\n  await sendRaw(adapter, encodeAuthLoginPass(pass));\n  resp = await readSMTPResponse(adapter);\n  assertResponse(resp, [235], \"AUTH LOGIN pass\");\n}\n\nfunction requirePassword(auth: NonNullable<SMTPConfig[\"auth\"]>, method: string): string {\n  if (!auth.pass) {\n    throw new SMTPError(`Password required for ${method} authentication`, 0, `AUTH ${method}`, \"\");\n  }\n  return auth.pass;\n}\n\nasync function sendCommand(\n  adapter: SocketAdapter,\n  command: Parameters<typeof encodeCommand>[0],\n): Promise<void> {\n  await sendRaw(adapter, encodeCommand(command));\n}\n\nasync function sendRaw(adapter: SocketAdapter, data: Uint8Array): Promise<void> {\n  await adapter.write(data);\n}\n\n/** Reads and parses a complete SMTP response from the adapter. */\nasync function readSMTPResponse(adapter: SocketAdapter): Promise<SMTPResponse> {\n  const chunks: Uint8Array[] = [];\n  for await (const chunk of adapter.read()) {\n    chunks.push(chunk);\n    const complete = accumulateResponse(chunks);\n    if (complete) {\n      return parseResponse(complete);\n    }\n  }\n  throw new SMTPError(\"Connection closed while reading SMTP response\", 0, \"READ\", \"\");\n}\n\nasync function resolveMX(domain: string): Promise<string> {\n  const dns = await import(\"node:dns/promises\");\n  const records = await dns.resolveMx(domain);\n  if (records.length === 0) {\n    throw new SMTPError(`No MX records for ${domain}`, 0, \"MX\", \"\");\n  }\n  records.sort((a: { priority: number }, b: { priority: number }) => a.priority - b.priority);\n  return records[0]?.exchange ?? domain;\n}\n\n/** @internal Test helper for raw line writes. */\nexport { encodeLine, readSMTPResponse };\n"
+  ],
+  "mappings": "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",
+  "debugId": "736A9106E3164FC464756E2164756E21",
+  "names": []
+}

package/dist/{chunk-bvxkmq94.js → chunk-f4c9ttmr.js}

@@ -6,13 +6,34 @@ import {
 } from "./chunk-v0bahtg2.js";
 
 // src/core/address.ts
+function findForbiddenChar(value) {
+  for (let i = 0;i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code <= 31 || code === 127 || code === 8232 || code === 8233) {
+      return code;
+    }
+  }
+  return -1;
+}
+function assertSafeAddress(value, label = "address") {
+  const code = findForbiddenChar(value);
+  if (code !== -1) {
+    const hex = code.toString(16).padStart(2, "0");
+    throw new Error(`Email ${label} contains a forbidden control character (0x${hex}). ` + "CR, LF, NUL, and other control characters are not allowed.");
+  }
+}
 function parseAddresses(input) {
   if (Array.isArray(input)) {
     return input.flatMap((item) => parseAddresses(item));
   }
   if (typeof input === "object") {
+    assertSafeAddress(input.address, "address");
+    if (input.name !== undefined) {
+      assertSafeAddress(input.name, "display name");
+    }
     return [{ ...input }];
   }
+  assertSafeAddress(input, "address");
   const trimmed = input.trim();
   if (!trimmed) {
     return [];
@@ -20,7 +41,9 @@ function parseAddresses(input) {
   return splitAddressList(trimmed).map(parseSingleAddress);
 }
 function toMIMEHeader(address) {
+  assertSafeAddress(address.address, "address");
   if (address.name) {
+    assertSafeAddress(address.name, "display name");
     const name = encodeHeader(address.name);
     return `${name} <${address.address}>`;
   }
@@ -29,6 +52,11 @@ function toMIMEHeader(address) {
 function extractEmails(input) {
   return parseAddresses(input).map((addr) => addr.address);
 }
+function isValidEmail(email) {
+  if (findForbiddenChar(email) !== -1)
+    return false;
+  return /^[^\s@<>]+@[^\s@<>]+\.[^\s@<>]+$/.test(email);
+}
 function splitAddressList(input) {
   const parts = [];
   let current = "";
@@ -99,11 +127,12 @@ async function resolveAttachments(attachments, options) {
         throw new Error("attachment.path is not supported on this runtime — use attachment.content (Uint8Array) instead");
       }
       if (options?.basePath) {
-        const { resolve } = await import("node:path");
+        const { resolve, sep } = await import("node:path");
         const resolvedPath = resolve(attachment.path);
         const resolvedBase = resolve(options.basePath);
-        if (!resolvedPath.startsWith(resolvedBase)) {
-          throw new Error(`[sently] Attachment path "${resolvedPath}" escapes basePath "${options.basePath}". Use absolute paths within the allowed directory.`);
+        const isWithin = resolvedPath === resolvedBase || resolvedPath.startsWith(resolvedBase + sep);
+        if (!isWithin) {
+          throw new Error(`[sently] Attachment path "${resolvedPath}" escapes basePath "${resolvedBase}". Use absolute paths within the allowed directory.`);
         }
       }
       const data = await fs.readFile(attachment.path);
@@ -120,6 +149,6 @@ async function resolveAttachments(attachments, options) {
   return resolved;
 }
 
-export { parseAddresses, toMIMEHeader, extractEmails, resolveAttachments };
+export { assertSafeAddress, parseAddresses, toMIMEHeader, extractEmails, isValidEmail, resolveAttachments };
 
-//# debugId=7C59D40B68EA994E64756E2164756E21
+//# debugId=419CD2BE8A029CA164756E2164756E21

package/dist/chunk-f4c9ttmr.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["../src/core/address.ts", "../src/transports/resolve-attachments.ts"],
+  "sourcesContent": [
+    "// src/core/address.ts\nimport { encodeHeader } from \"./base64.js\";\nimport type { Address, AddressInput } from \"./types.js\";\n\n/**\n * Find the first forbidden control character in a string.\n *\n * Forbidden characters must never appear in an email address or display name,\n * because each enables a distinct attack:\n * - CR (0x0D) / LF (0x0A): email header injection and SMTP command injection\n * - NUL (0x00): C-string truncation / parser confusion in downstream agents\n * - other C0 controls (0x01–0x1F), DEL (0x7F): header/parser confusion\n * - U+2028 / U+2029: line separators that some parsers treat as newlines\n *\n * @returns The char code of the first forbidden character, or -1 if none.\n */\nfunction findForbiddenChar(value: string): number {\n  for (let i = 0; i < value.length; i++) {\n    const code = value.charCodeAt(i);\n    if (code <= 0x1f || code === 0x7f || code === 0x2028 || code === 0x2029) {\n      return code;\n    }\n  }\n  return -1;\n}\n\n/**\n * Assert that a raw address or display-name value contains no forbidden\n * control characters. Throws immediately (fail closed) — the library never\n * attempts to strip or rewrite hostile input into an accepted value.\n *\n * The check is intentionally performed on the RAW input, before any trimming\n * or normalization, so hostile values are rejected rather than repaired.\n *\n * @param value - The raw, untransformed string to validate.\n * @param label - Field label used in the error message (e.g. \"address\").\n * @throws {Error} If the value contains any forbidden control character.\n */\nexport function assertSafeAddress(value: string, label = \"address\"): void {\n  const code = findForbiddenChar(value);\n  if (code !== -1) {\n    const hex = code.toString(16).padStart(2, \"0\");\n    throw new Error(\n      `Email ${label} contains a forbidden control character (0x${hex}). ` +\n        \"CR, LF, NUL, and other control characters are not allowed.\",\n    );\n  }\n}\n\n/**\n * Normalize any AddressInput form into Address[].\n *\n * Every address and display name is validated against control-character\n * injection before any transformation. This is the single chokepoint shared\n * by all transports and address fields (From, To, Cc, Bcc, Reply-To), so the\n * protection is uniform and secure by default.\n *\n * @throws {Error} If any address or name contains a forbidden control character.\n */\nexport function parseAddresses(input: AddressInput): Address[] {\n  if (Array.isArray(input)) {\n    return input.flatMap((item) => parseAddresses(item));\n  }\n\n  if (typeof input === \"object\") {\n    assertSafeAddress(input.address, \"address\");\n    if (input.name !== undefined) {\n      assertSafeAddress(input.name, \"display name\");\n    }\n    return [{ ...input }];\n  }\n\n  // Validate the raw input string before splitting or trimming so injected\n  // newlines cannot hide inside a multi-address list.\n  assertSafeAddress(input, \"address\");\n\n  const trimmed = input.trim();\n  if (!trimmed) {\n    return [];\n  }\n\n  return splitAddressList(trimmed).map(parseSingleAddress);\n}\n\n/**\n * Format an Address for SMTP envelope commands (MAIL FROM / RCPT TO).\n */\nexport function toEnvelope(address: Address): string {\n  return address.address;\n}\n\n/**\n * Format an Address for use in a MIME header (From, To, CC, etc.).\n *\n * Re-validates the address and name at render time so a header can never be\n * emitted with an embedded control character, even if the {@link Address} was\n * constructed without going through {@link parseAddresses}.\n *\n * @throws {Error} If the address or name contains a forbidden control character.\n */\nexport function toMIMEHeader(address: Address): string {\n  assertSafeAddress(address.address, \"address\");\n  if (address.name) {\n    assertSafeAddress(address.name, \"display name\");\n    const name = encodeHeader(address.name);\n    return `${name} <${address.address}>`;\n  }\n  return address.address;\n}\n\n/**\n * Extract plain email strings from any AddressInput.\n */\nexport function extractEmails(input: AddressInput): string[] {\n  return parseAddresses(input).map((addr) => addr.address);\n}\n\n/**\n * Basic email format validation (format only, no DNS lookup).\n *\n * Rejects any control character (including CR, LF, tab, and NUL) before\n * applying the structural check, so a \"valid\" result is always safe to place\n * into a header or SMTP command.\n */\nexport function isValidEmail(email: string): boolean {\n  if (findForbiddenChar(email) !== -1) return false;\n  return /^[^\\s@<>]+@[^\\s@<>]+\\.[^\\s@<>]+$/.test(email);\n}\n\nfunction splitAddressList(input: string): string[] {\n  const parts: string[] = [];\n  let current = \"\";\n  let inQuotes = false;\n  let inAngle = false;\n\n  for (let i = 0; i < input.length; i++) {\n    const char = input[i] ?? \"\";\n    if (char === '\"' && input[i - 1] !== \"\\\\\") {\n      inQuotes = !inQuotes;\n      current += char;\n      continue;\n    }\n    if (char === \"<\" && !inQuotes) {\n      inAngle = true;\n      current += char;\n      continue;\n    }\n    if (char === \">\" && !inQuotes) {\n      inAngle = false;\n      current += char;\n      continue;\n    }\n    if (char === \",\" && !inQuotes && !inAngle) {\n      if (current.trim()) {\n        parts.push(current.trim());\n      }\n      current = \"\";\n      continue;\n    }\n    current += char;\n  }\n\n  if (current.trim()) {\n    parts.push(current.trim());\n  }\n\n  return parts;\n}\n\nfunction parseSingleAddress(input: string): Address {\n  const trimmed = input.trim();\n\n  const angleMatch = trimmed.match(/^(?:\"([^\"]*)\"|([^<]*?))\\s*<([^>]+)>$/);\n  if (angleMatch) {\n    const name = (angleMatch[1] ?? angleMatch[2] ?? \"\").trim();\n    const address = (angleMatch[3] ?? \"\").trim();\n    if (name) {\n      return { name, address };\n    }\n    return { address };\n  }\n\n  if (trimmed.startsWith('\"') && trimmed.endsWith('\"')) {\n    return { address: trimmed.slice(1, -1) };\n  }\n\n  return { address: trimmed };\n}\n",
+    "import type { Attachment } from \"../core/types.js\";\n\n/** Options for {@link resolveAttachments}. */\nexport interface ResolveAttachmentsOptions {\n  /**\n   * If set, attachment paths must resolve within this directory.\n   * Prevents path traversal via `..` segments and sibling-directory\n   * prefix matches. Opt-in only.\n   *\n   * Note: this check uses `node:path` `resolve()`, which does NOT\n   * dereference symlinks. A symlink located inside `basePath` that\n   * points outside of it will pass this check. If symlink traversal is\n   * a concern, resolve paths with `fs.realpath()` before passing them in.\n   */\n  basePath?: string;\n}\n\n/**\n * Resolve attachment.path to in-memory Uint8Array content.\n * @throws When attachment.path is used on runtimes without node:fs/promises\n */\nexport async function resolveAttachments(\n  attachments: Attachment[] | undefined,\n  options?: ResolveAttachmentsOptions,\n): Promise<Attachment[]> {\n  const list = attachments ?? [];\n  const resolved: Attachment[] = [];\n\n  for (const attachment of list) {\n    if (attachment.content instanceof Uint8Array) {\n      resolved.push(attachment);\n      continue;\n    }\n\n    if (attachment.path) {\n      let fs: typeof import(\"node:fs/promises\");\n      try {\n        fs = await import(\"node:fs/promises\");\n      } catch {\n        throw new Error(\n          \"attachment.path is not supported on this runtime — use attachment.content (Uint8Array) instead\",\n        );\n      }\n\n      if (options?.basePath) {\n        const { resolve, sep } = await import(\"node:path\");\n        const resolvedPath = resolve(attachment.path);\n        const resolvedBase = resolve(options.basePath);\n        // startsWith alone is vulnerable: \"/var/data-secret\" passes \"/var/data\".\n        // Require an exact match or a trailing path separator.\n        const isWithin =\n          resolvedPath === resolvedBase || resolvedPath.startsWith(resolvedBase + sep);\n        if (!isWithin) {\n          throw new Error(\n            `[sently] Attachment path \"${resolvedPath}\" escapes basePath \"${resolvedBase}\". ` +\n              \"Use absolute paths within the allowed directory.\",\n          );\n        }\n      }\n\n      const data = await fs.readFile(attachment.path);\n      const { path: _path, ...rest } = attachment;\n      resolved.push({ ...rest, content: new Uint8Array(data) });\n      continue;\n    }\n\n    if (typeof attachment.content === \"string\") {\n      resolved.push(attachment);\n      continue;\n    }\n\n    resolved.push(attachment);\n  }\n\n  return resolved;\n}\n"
+  ],
+  "mappings": ";;;;;;;;AAgBA,SAAS,iBAAiB,CAAC,OAAuB;AAAA,EAChD,SAAS,IAAI,EAAG,IAAI,MAAM,QAAQ,KAAK;AAAA,IACrC,MAAM,OAAO,MAAM,WAAW,CAAC;AAAA,IAC/B,IAAI,QAAQ,MAAQ,SAAS,OAAQ,SAAS,QAAU,SAAS,MAAQ;AAAA,MACvE,OAAO;AAAA,IACT;AAAA,EACF;AAAA,EACA,OAAO;AAAA;AAeF,SAAS,iBAAiB,CAAC,OAAe,QAAQ,WAAiB;AAAA,EACxE,MAAM,OAAO,kBAAkB,KAAK;AAAA,EACpC,IAAI,SAAS,IAAI;AAAA,IACf,MAAM,MAAM,KAAK,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG;AAAA,IAC7C,MAAM,IAAI,MACR,SAAS,mDAAmD,WAC1D,4DACJ;AAAA,EACF;AAAA;AAaK,SAAS,cAAc,CAAC,OAAgC;AAAA,EAC7D,IAAI,MAAM,QAAQ,KAAK,GAAG;AAAA,IACxB,OAAO,MAAM,QAAQ,CAAC,SAAS,eAAe,IAAI,CAAC;AAAA,EACrD;AAAA,EAEA,IAAI,OAAO,UAAU,UAAU;AAAA,IAC7B,kBAAkB,MAAM,SAAS,SAAS;AAAA,IAC1C,IAAI,MAAM,SAAS,WAAW;AAAA,MAC5B,kBAAkB,MAAM,MAAM,cAAc;AAAA,IAC9C;AAAA,IACA,OAAO,CAAC,KAAK,MAAM,CAAC;AAAA,EACtB;AAAA,EAIA,kBAAkB,OAAO,SAAS;AAAA,EAElC,MAAM,UAAU,MAAM,KAAK;AAAA,EAC3B,IAAI,CAAC,SAAS;AAAA,IACZ,OAAO,CAAC;AAAA,EACV;AAAA,EAEA,OAAO,iBAAiB,OAAO,EAAE,IAAI,kBAAkB;AAAA;AAmBlD,SAAS,YAAY,CAAC,SAA0B;AAAA,EACrD,kBAAkB,QAAQ,SAAS,SAAS;AAAA,EAC5C,IAAI,QAAQ,MAAM;AAAA,IAChB,kBAAkB,QAAQ,MAAM,cAAc;AAAA,IAC9C,MAAM,OAAO,aAAa,QAAQ,IAAI;AAAA,IACtC,OAAO,GAAG,SAAS,QAAQ;AAAA,EAC7B;AAAA,EACA,OAAO,QAAQ;AAAA;AAMV,SAAS,aAAa,CAAC,OAA+B;AAAA,EAC3D,OAAO,eAAe,KAAK,EAAE,IAAI,CAAC,SAAS,KAAK,OAAO;AAAA;AAUlD,SAAS,YAAY,CAAC,OAAwB;AAAA,EACnD,IAAI,kBAAkB,KAAK,MAAM;AAAA,IAAI,OAAO;AAAA,EAC5C,OAAO,mCAAmC,KAAK,KAAK;AAAA;AAGtD,SAAS,gBAAgB,CAAC,OAAyB;AAAA,EACjD,MAAM,QAAkB,CAAC;AAAA,EACzB,IAAI,UAAU;AAAA,EACd,IAAI,WAAW;AAAA,EACf,IAAI,UAAU;AAAA,EAEd,SAAS,IAAI,EAAG,IAAI,MAAM,QAAQ,KAAK;AAAA,IACrC,MAAM,OAAO,MAAM,MAAM;AAAA,IACzB,IAAI,SAAS,OAAO,MAAM,IAAI,OAAO,MAAM;AAAA,MACzC,WAAW,CAAC;AAAA,MACZ,WAAW;AAAA,MACX;AAAA,IACF;AAAA,IACA,IAAI,SAAS,OAAO,CAAC,UAAU;AAAA,MAC7B,UAAU;AAAA,MACV,WAAW;AAAA,MACX;AAAA,IACF;AAAA,IACA,IAAI,SAAS,OAAO,CAAC,UAAU;AAAA,MAC7B,UAAU;AAAA,MACV,WAAW;AAAA,MACX;AAAA,IACF;AAAA,IACA,IAAI,SAAS,OAAO,CAAC,YAAY,CAAC,SAAS;AAAA,MACzC,IAAI,QAAQ,KAAK,GAAG;AAAA,QAClB,MAAM,KAAK,QAAQ,KAAK,CAAC;AAAA,MAC3B;AAAA,MACA,UAAU;AAAA,MACV;AAAA,IACF;AAAA,IACA,WAAW;AAAA,EACb;AAAA,EAEA,IAAI,QAAQ,KAAK,GAAG;AAAA,IAClB,MAAM,KAAK,QAAQ,KAAK,CAAC;AAAA,EAC3B;AAAA,EAEA,OAAO;AAAA;AAGT,SAAS,kBAAkB,CAAC,OAAwB;AAAA,EAClD,MAAM,UAAU,MAAM,KAAK;AAAA,EAE3B,MAAM,aAAa,QAAQ,MAAM,sCAAsC;AAAA,EACvE,IAAI,YAAY;AAAA,IACd,MAAM,QAAQ,WAAW,MAAM,WAAW,MAAM,IAAI,KAAK;AAAA,IACzD,MAAM,WAAW,WAAW,MAAM,IAAI,KAAK;AAAA,IAC3C,IAAI,MAAM;AAAA,MACR,OAAO,EAAE,MAAM,QAAQ;AAAA,IACzB;AAAA,IACA,OAAO,EAAE,QAAQ;AAAA,EACnB;AAAA,EAEA,IAAI,QAAQ,WAAW,GAAG,KAAK,QAAQ,SAAS,GAAG,GAAG;AAAA,IACpD,OAAO,EAAE,SAAS,QAAQ,MAAM,GAAG,EAAE,EAAE;AAAA,EACzC;AAAA,EAEA,OAAO,EAAE,SAAS,QAAQ;AAAA;;;ACrK5B,eAAsB,kBAAkB,CACtC,aACA,SACuB;AAAA,EACvB,MAAM,OAAO,eAAe,CAAC;AAAA,EAC7B,MAAM,WAAyB,CAAC;AAAA,EAEhC,WAAW,cAAc,MAAM;AAAA,IAC7B,IAAI,WAAW,mBAAmB,YAAY;AAAA,MAC5C,SAAS,KAAK,UAAU;AAAA,MACxB;AAAA,IACF;AAAA,IAEA,IAAI,WAAW,MAAM;AAAA,MACnB,IAAI;AAAA,MACJ,IAAI;AAAA,QACF,KAAK,MAAa;AAAA,QAClB,MAAM;AAAA,QACN,MAAM,IAAI,MACR,gGACF;AAAA;AAAA,MAGF,IAAI,SAAS,UAAU;AAAA,QACrB,QAAQ,SAAS,QAAQ,MAAa;AAAA,QACtC,MAAM,eAAe,QAAQ,WAAW,IAAI;AAAA,QAC5C,MAAM,eAAe,QAAQ,QAAQ,QAAQ;AAAA,QAG7C,MAAM,WACJ,iBAAiB,gBAAgB,aAAa,WAAW,eAAe,GAAG;AAAA,QAC7E,IAAI,CAAC,UAAU;AAAA,UACb,MAAM,IAAI,MACR,6BAA6B,mCAAmC,iEAElE;AAAA,QACF;AAAA,MACF;AAAA,MAEA,MAAM,OAAO,MAAM,GAAG,SAAS,WAAW,IAAI;AAAA,MAC9C,QAAQ,MAAM,UAAU,SAAS;AAAA,MACjC,SAAS,KAAK,KAAK,MAAM,SAAS,IAAI,WAAW,IAAI,EAAE,CAAC;AAAA,MACxD;AAAA,IACF;AAAA,IAEA,IAAI,OAAO,WAAW,YAAY,UAAU;AAAA,MAC1C,SAAS,KAAK,UAAU;AAAA,MACxB;AAAA,IACF;AAAA,IAEA,SAAS,KAAK,UAAU;AAAA,EAC1B;AAAA,EAEA,OAAO;AAAA;",
+  "debugId": "419CD2BE8A029CA164756E2164756E21",
+  "names": []
+}