@c9up/goldstone 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C9up
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,239 @@
-# Temporary Holding Version
+# @c9up/goldstone
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Reading mail for the Ream framework.
+
+Goldstone reads IMAP mailboxes — in real time with IDLE — and receives the
+inbound mail that providers post to a webhook. Every message it hands over has
+been parsed as the hostile input it is: HTML sanitized for display, attachments
+bounded, file names cleaned, and the sender's DKIM, SPF and DMARC verdict
+attached.
+
+Sending stays with `@c9up/rover`.
+
+## Status
+
+Here: reading IMAP mailboxes, receiving Mailgun's inbound mail, parsing what
+arrives, and checking who sent it (DKIM, SPF, DMARC, ARC).
+
+## Reading a mailbox
+
+```ts
+// config/inbox.ts
+import { defineConfig } from "@c9up/goldstone"
+
+export default defineConfig({
+  mailbox: "support",
+  mailboxes: {
+    support: {
+      host: "imap.example.com",
+      auth: { user: env.get("IMAP_USER"), pass: env.get("IMAP_PASSWORD") },
+    },
+    billing: {
+      host: "outlook.office365.com",
+      // XOAUTH2. Called on every connection, so an expired token is asked
+      // for again when the connection is made anew.
+      auth: { user: "billing@example.com", accessToken: () => tokens.for("billing") },
+    },
+  },
+})
+
+// reamrc.ts
+providers: [() => import("@c9up/goldstone/provider")]
+```
+
+```ts
+import inbox from "@c9up/goldstone/services/main"
+
+const support = inbox.mailbox() // the default; inbox.mailbox("billing")
+
+for (const uid of await support.search({ seen: false })) {
+  const message = await support.fetch(uid)   // parsed, see below
+  await support.markSeen(uid)
+}
+await support.move(uid, "Archive")
+
+const stop = support.watch(async (message, { uid }) => {
+  // every new message, as it arrives
+})
+```
+
+- **TLS is required**: implicit TLS by default (993), or `starttls: true`
+  (143, plaintext upgraded: `secure` need not be set), which refuses to go on
+  when the server does not offer STARTTLS. `secure: true` with
+  `starttls: true` is refused at `defineConfig`. Plaintext
+  or an unchecked certificate need `allowInsecure`, for a local test server.
+- A mailbox opens on first use. `watch()` keeps its own connection in IDLE;
+  when it is lost, it reconnects with a growing wait and delivers what
+  arrived meanwhile — messages are followed by UID, so none is skipped and
+  none delivered twice. A handler that throws is reported to `onError` and
+  the watch goes on.
+- A message's size is asked of the server before it is downloaded: one over
+  `limits.maxBytes` is refused without being fetched. The answer is only a
+  claim, so the connection also refuses any message literal over
+  `maxBytes` (and caps every response) before buffering it: a server that
+  lies about the size, or leaves it out, is cut off with
+  `E_GOLDSTONE_MESSAGE_TOO_LARGE` instead of pushing a gigabyte into memory.
+- The provider logs out of every mailbox on shutdown, so an IDLE connection
+  does not keep the process alive.
+
+## Receiving inbound mail (Mailgun)
+
+```ts
+import { createMailgunInboundHandler } from "@c9up/goldstone"
+
+router.post("/inbound/mailgun/mime", createMailgunInboundHandler({
+  signingKey: env.get("MAILGUN_SIGNING_KEY"),
+  async onMessage(message, { recipient, sender }) {
+    // parsed, checked (message.authenticity)
+  },
+}))
+```
+
+Point the Mailgun route's *forward* action at a URL ending in `mime`: that is
+what makes Mailgun send the message as received.
+
+The handler reads the fields from `request.body()`, which Ream fills only
+when its body parser has read the request: the route must run behind
+`BodyParserMiddleware` (registered globally in a scaffolded app). Mailgun
+posts `multipart/form-data`, or urlencoded; raise both limits above the
+largest message you accept (25 MiB by default; the parser's defaults are
+1 MB for a form and 20 MB for multipart), in `config/bodyparser.ts` so the
+server applies them too:
+
+```ts
+// config/bodyparser.ts
+export default {
+  form: { limit: "30mb" },
+  multipart: { limit: "30mb" },
+}
+```
+
+Without the parser, every delivery is answered 401, its fields missing.
+
+Mailgun signs a timestamp and a token — not the message. So the handler
+refuses a timestamp older than two minutes (`maxAgeSeconds`, an integer
+from 1 to 86 400 — anything else is refused when the handler is created,
+since a `NaN` read from an unset variable would turn the check off) and
+handles each token once,
+claimed before handling so two racing requests cannot both get through; a
+delivery whose handler throws gives its token back, and Mailgun's retry is
+handled. Fields are read from the request body only, never the query string.
+The tokens live in this process's memory; with several instances, pass a
+shared `replayGuard`. A message the parser refuses is answered 406, which
+stops Mailgun from retrying it.
+
+## Parsing a received message
+
+```ts
+import { parseMessage } from "@c9up/goldstone"
+
+const message = await parseMessage(raw) // raw RFC 5322 bytes
+
+message.subject
+message.from            // [{ name, address }]
+message.date            // Date
+message.text
+message.html            // sanitized: safe to render, loads nothing remote
+message.attachments     // [{ fileName, originalName, contentType, size, content, … }]
+message.header("List-Unsubscribe")
+```
+
+Parsing runs in Rust ([mail-parser](https://github.com/stalwartlabs/mail-parser)),
+in one call and off the JavaScript thread: the bytes go in, the message comes
+out, and the event loop keeps serving requests meanwhile. A received mail is
+input from whoever sent it, so:
+
+- **the size is checked before a byte is parsed**, then the structure is
+  bounded — parts, nesting depth, header fields and header size, number and
+  size of attachments. Parts and nesting count through the messages a message
+  carries (message/rfc822), encoded or not. Parts and headers are bounded
+  before the parse too: the message is first walked the way the parser walks
+  it, keeping only counts, so a message made of millions of tiny parts or
+  headers is refused before it costs any memory.
+  Each limit has a default and can be set per call
+  (`parseMessage(raw, { limits: { maxBytes } })`); over one, a `GoldstoneError` names it
+  (`E_GOLDSTONE_MESSAGE_TOO_LARGE`, `…_TOO_MANY_PARTS`, `…_TOO_DEEP`,
+  `…_TOO_MANY_HEADERS`, `…_HEADERS_TOO_LARGE`, `…_TOO_MANY_ATTACHMENTS`,
+  `…_ATTACHMENT_TOO_LARGE`). A part starts only at a delimiter of the
+  boundary its multipart declared, or after the header of a carried message:
+  a `-- ` signature, a pasted log or a large attachment is body, whatever it
+  says. The search for those delimiters is bounded too: a multipart whose
+  boundary never occurs is searched for up to the end of the message, so
+  past four such scans of a `maxBytes` message the message is refused
+  (`E_GOLDSTONE_MISSING_BOUNDARIES`), and so is a boundary over 256 bytes
+  (`E_GOLDSTONE_BOUNDARY_TOO_LONG`; RFC 2046 allows 70);
+- **`html` is sanitized** — no script, no event handler, no `javascript:` URL,
+  and nothing a browser would load by itself: remote images, backgrounds and
+  posters are removed, because loading one tells the sender the message was
+  opened, when and from where. `cid:` references to the message's own parts
+  stay, and so do links, which are only followed when clicked. An application
+  that shows remote content on purpose passes `remoteContent: "allow"` (to
+  `parseMessage`, `readMessage`, the inbox config or the Mailgun handler).
+  The HTML as received is only reachable through `unsanitizedHtml()`, for what
+  has to see the original; never render it;
+- **the HTML is bounded before it is sanitized**: over `maxHtmlBytes`
+  (512 KiB by default), nested deeper than 1 000 elements, or building a tree
+  out of proportion to its markup, it is not sanitized at all — the HTML
+  standard's tree building costs more than linear time on such markup.
+  `html` is then absent and `htmlError` says why
+  (`E_GOLDSTONE_HTML_TOO_LARGE`, `…_HTML_TOO_DEEP`, `…_HTML_TOO_COMPLEX`);
+  the message, its text and its attachments are read as usual;
+- **`fileName` is safe to save under**, on any system: the last path segment
+  of what the sender wrote, with control, invisible and bidi characters and
+  the characters Windows refuses (`< > : " | ? *` — a `:` would write into an
+  NTFS stream) replaced by `_`, without leading dots, trailing dots or
+  spaces, or a Windows device name (`CON`, `COM1`, `CONIN$`…). A right-to-left
+  override cannot dress `fdp.exe` up as `exe.pdf`. What the sender wrote stays in `originalName`, for display only.
+
+The engine is a native binary, prebuilt for Linux, macOS and Windows; there is
+no JavaScript fallback.
+
+## Who sent it
+
+The From header is whatever the sender typed. A message read from a mailbox
+carries the verdict on `message.authenticity`; for raw bytes, `readMessage()`
+parses and checks, `authenticate()` only checks:
+
+```ts
+import { authenticate, readMessage } from "@c9up/goldstone"
+
+const message = await readMessage(raw)
+message.authenticity.summary   // "pass" | "fail" | "none" | "temperror"
+message.authenticity.dkim      // [{ result, domain, selector, reason }]
+message.authenticity.dmarc     // and dmarcPolicy, dmarcDomain, spf, arc
+
+// SPF needs to know who delivered the message — a webhook usually says:
+await authenticate(raw, { ip: "203.0.113.7", helo: "mx.sender.test", mailFrom: "bounces@sender.test" })
+```
+
+- `summary` is `pass` only when the From domain's DMARC passes, through a
+  DKIM signature or an SPF result aligned with that domain. A message signed
+  by another domain than its From does not pass.
+- The verdict and the message come from one parse, and a pass speaks for the
+  From the message shows: exactly one From header, holding exactly one
+  address, whose domain is `authenticity.fromDomain`. A repeated From, a From
+  with several addresses, or a header allowed once (Subject, Date, To,
+  Message-ID…) that appears twice is a `fail`: an unsigned copy added to a
+  signed message is how a phisher rides on someone else's signature.
+- Only the address's domain is checked, never the display name:
+  `"ceo@bank.test" <a@evil.test>` can pass — for `evil.test`. Show
+  `fromDomain`, or the address, next to the verdict.
+- A repeated header is read from its first copy everywhere: `message.from`,
+  `message.subject` and `message.header("from")` agree, and every copy stays
+  in `message.headers`.
+- A DKIM signature made with rsa-sha1 (RFC 8301), or whose `h=` leaves out
+  From (RFC 6376 §6.1.1), is a `permerror` whatever its cryptography says,
+  and DMARC cannot pass on it: SHA-1 is broken, and a From the signature does
+  not cover can be rewritten at will.
+- A check that cannot complete — DNS down, too slow — is `temperror`,
+  never a pass. The whole check has a deadline (10 s by default), at most 5
+  DKIM signatures are verified (each is a lookup; the refused ones above are
+  not counted), and DNS answers are cached.
+- Read over IMAP, a message usually does not carry who delivered it
+  reliably, so SPF is `none` there and DMARC rests on DKIM.
+- Turn it off with `authenticate: false` in `config/inbox.ts`, or
+  `readMessage(raw, { authenticate: false })`; `parseMessage()` never checks.
+
+## License
+
+MIT

package/dist/GoldstoneProvider.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Wires `config/inbox.ts` into the container as `'inbox'`, and seats the
+ * manager on `@c9up/goldstone/services/main`.
+ *
+ *   // reamrc.ts
+ *   providers: [() => import('@c9up/goldstone/provider')]
+ *
+ * The host is duck-typed — this package stays publishable without importing
+ * `@c9up/ream`. `register` opens no connection: mailboxes open on first use.
+ */
+import "./augmentations.js";
+interface GoldstoneContainer {
+    singleton(token: unknown, factory: () => unknown): void;
+}
+interface GoldstoneConfigStore {
+    get(key: string): unknown;
+}
+export interface GoldstoneAppContext {
+    container: GoldstoneContainer;
+    config: GoldstoneConfigStore;
+}
+export default class GoldstoneProvider {
+    #private;
+    constructor(app: GoldstoneAppContext);
+    register(): void;
+    /**
+     * Log out of every mailbox and stop every watch. Without it, an IDLE
+     * connection keeps the process alive and the server looks hung on stop.
+     */
+    shutdown(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=GoldstoneProvider.d.ts.map

package/dist/GoldstoneProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GoldstoneProvider.d.ts","sourceRoot":"","sources":["../src/GoldstoneProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,oBAAoB,CAAC;AAK5B,UAAU,kBAAkB;IAC3B,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,GAAG,IAAI,CAAC;CACxD;AACD,UAAU,oBAAoB;IAC7B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AACD,MAAM,WAAW,mBAAmB;IACnC,SAAS,EAAE,kBAAkB,CAAC;IAC9B,MAAM,EAAE,oBAAoB,CAAC;CAC7B;AAcD,MAAM,CAAC,OAAO,OAAO,iBAAiB;;gBAIzB,GAAG,EAAE,mBAAmB;IAIpC,QAAQ,IAAI,IAAI;IAgBhB;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAO/B"}

package/dist/GoldstoneProvider.js

@@ -0,0 +1,55 @@
+/**
+ * Wires `config/inbox.ts` into the container as `'inbox'`, and seats the
+ * manager on `@c9up/goldstone/services/main`.
+ *
+ *   // reamrc.ts
+ *   providers: [() => import('@c9up/goldstone/provider')]
+ *
+ * The host is duck-typed — this package stays publishable without importing
+ * `@c9up/ream`. `register` opens no connection: mailboxes open on first use.
+ */
+import "./augmentations.js";
+import { InboxManager } from "./InboxManager.js";
+import { clearInbox, setInbox } from "./services/main.js";
+function isInboxConfig(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const mailboxes = Reflect.get(value, "mailboxes");
+    return (typeof Reflect.get(value, "mailbox") === "string" &&
+        typeof mailboxes === "object" &&
+        mailboxes !== null);
+}
+export default class GoldstoneProvider {
+    #app;
+    #manager;
+    constructor(app) {
+        this.#app = app;
+    }
+    register() {
+        const raw = this.#app.config.get("inbox");
+        if (raw === undefined)
+            throw new Error("[inbox] missing config/inbox.ts");
+        if (!isInboxConfig(raw)) {
+            throw new Error("[inbox] config/inbox.ts must export defineConfig({ mailbox, mailboxes }).");
+        }
+        const manager = new InboxManager(raw);
+        this.#manager = manager;
+        setInbox(manager);
+        this.#app.container.singleton(InboxManager, () => manager);
+        this.#app.container.singleton("goldstone.inbox", () => manager);
+        this.#app.container.singleton("inbox", () => manager);
+    }
+    /**
+     * Log out of every mailbox and stop every watch. Without it, an IDLE
+     * connection keeps the process alive and the server looks hung on stop.
+     */
+    async shutdown() {
+        const manager = this.#manager;
+        if (!manager)
+            return;
+        await manager.closeAll();
+        clearInbox(manager);
+        this.#manager = undefined;
+    }
+}
+//# sourceMappingURL=GoldstoneProvider.js.map

package/dist/GoldstoneProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GoldstoneProvider.js","sourceRoot":"","sources":["../src/GoldstoneProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,oBAAoB,CAAC;AAE5B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAa1D,SAAS,aAAa,CACrB,KAAc;IAEd,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;IAClD,OAAO,CACN,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,KAAK,QAAQ;QACjD,OAAO,SAAS,KAAK,QAAQ;QAC7B,SAAS,KAAK,IAAI,CAClB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,OAAO,OAAO,iBAAiB;IAC5B,IAAI,CAAsB;IACnC,QAAQ,CAA2B;IAEnC,YAAY,GAAwB;QACnC,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;IACjB,CAAC;IAED,QAAQ;QACP,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC1C,IAAI,GAAG,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;QAC1E,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CACd,2EAA2E,CAC3E,CAAC;QACH,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,QAAQ,CAAC,OAAO,CAAC,CAAC;QAClB,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,YAAY,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC;QAC3D,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,iBAAiB,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC;QAChE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC;IACvD,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,QAAQ;QACb,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;QACzB,UAAU,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC;IAC3B,CAAC;CACD"}

package/dist/InboxManager.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The configured mailboxes, each opened on first use.
+ *
+ *   inbox.mailbox()            // the default one
+ *   inbox.mailbox('billing')
+ */
+import type { InboxConfig, MailboxConfig } from "./config.js";
+import { Mailbox } from "./Mailbox.js";
+export declare class InboxManager<Mailboxes extends Record<string, MailboxConfig> = Record<string, MailboxConfig>> {
+    #private;
+    constructor(config: InboxConfig<Mailboxes>);
+    /** A mailbox by name; the default one without. Opens nothing yet. */
+    mailbox(name?: keyof Mailboxes & string): Mailbox;
+    /** Stop every watch and log out of every mailbox. */
+    closeAll(): Promise<void>;
+}
+//# sourceMappingURL=InboxManager.d.ts.map

package/dist/InboxManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InboxManager.d.ts","sourceRoot":"","sources":["../src/InboxManager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,qBAAa,YAAY,CACxB,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,MAAM,CACvD,MAAM,EACN,aAAa,CACb;;gBAKW,MAAM,EAAE,WAAW,CAAC,SAAS,CAAC;IAI1C,qEAAqE;IACrE,OAAO,CAAC,IAAI,GAAE,MAAM,SAAS,GAAG,MAA6B,GAAG,OAAO;IAmBvE,qDAAqD;IAC/C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAK/B"}

package/dist/InboxManager.js

@@ -0,0 +1,39 @@
+/**
+ * The configured mailboxes, each opened on first use.
+ *
+ *   inbox.mailbox()            // the default one
+ *   inbox.mailbox('billing')
+ */
+import { GoldstoneError } from "./errors.js";
+import { Mailbox } from "./Mailbox.js";
+export class InboxManager {
+    #config;
+    #open = new Map();
+    constructor(config) {
+        this.#config = config;
+    }
+    /** A mailbox by name; the default one without. Opens nothing yet. */
+    mailbox(name = this.#config.mailbox) {
+        const existing = this.#open.get(name);
+        if (existing)
+            return existing;
+        const config = this.#config.mailboxes[name];
+        if (config === undefined) {
+            throw new GoldstoneError("E_GOLDSTONE_UNKNOWN_MAILBOX", `[inbox] no mailbox "${name}" — got ${Object.keys(this.#config.mailboxes).join(", ")}`);
+        }
+        const mailbox = new Mailbox(name, config, {
+            limits: this.#config.limits,
+            authenticate: this.#config.authenticate,
+            remoteContent: this.#config.remoteContent,
+        });
+        this.#open.set(name, mailbox);
+        return mailbox;
+    }
+    /** Stop every watch and log out of every mailbox. */
+    async closeAll() {
+        const mailboxes = [...this.#open.values()];
+        this.#open.clear();
+        await Promise.all(mailboxes.map((mailbox) => mailbox.close()));
+    }
+}
+//# sourceMappingURL=InboxManager.js.map

package/dist/InboxManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InboxManager.js","sourceRoot":"","sources":["../src/InboxManager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,MAAM,OAAO,YAAY;IAMf,OAAO,CAAyB;IAChC,KAAK,GAAG,IAAI,GAAG,EAAmB,CAAC;IAE5C,YAAY,MAA8B;QACzC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,qEAAqE;IACrE,OAAO,CAAC,OAAiC,IAAI,CAAC,OAAO,CAAC,OAAO;QAC5D,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,IAAI,cAAc,CACvB,6BAA6B,EAC7B,uBAAuB,IAAI,WAAW,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACtF,CAAC;QACH,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE;YACzC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM;YAC3B,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,YAAY;YACvC,aAAa,EAAE,IAAI,CAAC,OAAO,CAAC,aAAa;SACzC,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC9B,OAAO,OAAO,CAAC;IAChB,CAAC;IAED,qDAAqD;IACrD,KAAK,CAAC,QAAQ;QACb,MAAM,SAAS,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,MAAM,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAChE,CAAC;CACD"}

package/dist/Mailbox.d.ts

@@ -0,0 +1,83 @@
+/**
+ * One IMAP mailbox: its connection, opened on first use, and what the
+ * application does with it.
+ *
+ *   const support = inbox.mailbox('support')
+ *   for (const uid of await support.search({ seen: false })) {
+ *     const message = await support.fetch(uid)
+ *   }
+ *   const stop = support.watch(async (message, { uid }) => { … })
+ *
+ * Every message read goes through {@link readMessage}: its size is asked of
+ * the server first, so one over the limit is refused without being
+ * downloaded; it is then parsed, and its sender checked (DKIM, SPF, DMARC)
+ * unless `authenticate: false`.
+ */
+import { type SearchObject } from "imapflow";
+import { type MailboxConfig } from "./config.js";
+import { type Limits, type ParseOptions, type ReceivedMessage } from "./ReceivedMessage.js";
+export type SearchCriteria = SearchObject;
+export interface WatchOptions {
+    /** Default `INBOX`. */
+    folder?: string;
+    /**
+     * Deliver messages after this UID. Default: none of those already there —
+     * only what arrives once watching started.
+     */
+    afterUid?: number;
+    /**
+     * Told about what does not stop the watch: a lost connection (it
+     * reconnects), a message refused by the limits, a handler that threw, a
+     * mailbox whose UIDs were reset. Default: `console.error`.
+     */
+    onError?: (error: unknown) => void;
+}
+/** Wait before reconnect attempt `n`: 0.5 s, 1 s, 2 s… up to 30 s. */
+export declare function reconnectDelay(attempt: number): number;
+export interface MailboxOptions {
+    /** Bounds on every message read. */
+    limits?: Limits;
+    /**
+     * Check DKIM, SPF and DMARC on every message read — the verdict lands on
+     * `message.authenticity`. Default `true`: it costs DNS lookups (cached),
+     * and a From nobody checked is the From a phisher wrote.
+     */
+    authenticate?: boolean;
+    /** Remote content in `message.html`; see {@link ParseOptions}. Default `"block"`. */
+    remoteContent?: ParseOptions["remoteContent"];
+}
+export declare class Mailbox {
+    #private;
+    readonly name: string;
+    constructor(name: string, config: MailboxConfig, options?: MailboxOptions);
+    /** Every folder's path, as the server names it. */
+    folders(): Promise<string[]>;
+    /** UIDs of the messages that match, in `folder` (default `INBOX`). */
+    search(criteria: SearchCriteria, folder?: string): Promise<number[]>;
+    /**
+     * One message, parsed — or `undefined` when no message has that UID.
+     * Refused with `E_GOLDSTONE_MESSAGE_TOO_LARGE` before download when the
+     * server says it is over the limit.
+     */
+    fetch(uid: number, folder?: string): Promise<ReceivedMessage | undefined>;
+    markSeen(uids: number | number[], folder?: string): Promise<void>;
+    markUnseen(uids: number | number[], folder?: string): Promise<void>;
+    move(uids: number | number[], to: string, folder?: string): Promise<void>;
+    delete(uids: number | number[], folder?: string): Promise<void>;
+    /**
+     * Call `handler` for every new message, as it arrives (IDLE), on a
+     * connection of its own. A lost connection is reopened with a growing
+     * wait, and what arrived meanwhile is delivered on return: messages are
+     * followed by UID, so none is skipped and none delivered twice.
+     *
+     * A handler that throws does not stop the watch, and the message is not
+     * offered again — a message that always fails would otherwise stall the
+     * mailbox. Resolves the returned function once the watch has stopped.
+     */
+    watch(handler: (message: ReceivedMessage, meta: {
+        uid: number;
+    }) => unknown, options?: WatchOptions): () => Promise<void>;
+    /** Stop every watch and log out. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=Mailbox.d.ts.map

package/dist/Mailbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Mailbox.d.ts","sourceRoot":"","sources":["../src/Mailbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAY,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EACN,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,KAAK,eAAe,EAEpB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,MAAM,cAAc,GAAG,YAAY,CAAC;AAE1C,MAAM,WAAW,YAAY;IAC5B,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACnC;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAyBD,MAAM,WAAW,cAAc;IAC9B,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qFAAqF;IACrF,aAAa,CAAC,EAAE,YAAY,CAAC,eAAe,CAAC,CAAC;CAC9C;AAED,qBAAa,OAAO;;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAUrB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,cAAmB;IAU7B,mDAAmD;IAC7C,OAAO,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAKlC,sEAAsE;IAChE,MAAM,CAAC,QAAQ,EAAE,cAAc,EAAE,MAAM,SAAU,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAO3E;;;;OAIG;IACG,KAAK,CACV,GAAG,EAAE,MAAM,EACX,MAAM,SAAU,GACd,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAIjC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,MAAM,SAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAOlE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,MAAM,SAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpE,IAAI,CACT,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EACvB,EAAE,EAAE,MAAM,EACV,MAAM,SAAU,GACd,OAAO,CAAC,IAAI,CAAC;IAOV,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,MAAM,SAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAOtE;;;;;;;;;OASG;IACH,KAAK,CACJ,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,EACrE,OAAO,GAAE,YAAiB,GACxB,MAAM,OAAO,CAAC,IAAI,CAAC;IA8GtB,oCAAoC;IAC9B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAqI5B"}