@yozz.app/imap 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fishball Ltd
+
+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

@@ -0,0 +1,37 @@
+# @yozz.app/imap
+
+Transport-agnostic IMAP4rev2/rev1 client core for YOZZ.
+
+```bash
+pnpm add @yozz.app/imap
+```
+
+## The seam
+
+`@yozz.app/imap` speaks IMAP over any `ByteDuplex` (`{ read(): Promise<Uint8Array | null>; write(bytes): Promise<void> }`)
+from `@yozz.app/tls`. It knows protocol lines, `{n}` literals, command state, and RFC 2047 header
+decoding. It **never knows** TLS records, certificates, session keys, or vault storage.
+
+In the browser, the duplex wraps `@yozz.app/tls` over the production WebSocket relay. In tests, it
+wraps in-memory transcript drivers without network. In the live harness, it connects through
+`@yozz.app/tls` over TCP sockets.
+
+## Running tests
+
+```bash
+pnpm -F @yozz.app/imap test
+```
+
+## Running the live harness
+
+Tests real IMAP servers across the nine host matrix:
+
+```bash
+pnpm -F @yozz.app/imap live
+```
+
+Or for a specific host with authentication:
+
+```bash
+YOZZ_IMAP_HOST=imap.example.com YOZZ_IMAP_USER=me@example.com YOZZ_IMAP_PASSWORD=secret pnpm -F @yozz.app/imap live imap.example.com
+```

package/dist/index.d.mts

@@ -0,0 +1,285 @@
+import { ByteDuplex } from "@yozz.app/tls";
+
+//#region src/tokenizer.d.ts
+/**
+ * Hand-written tokenizer over byte offsets for IMAP4rev2/rev1 stream.
+ *
+ * Implements total parsing over attacker-controlled bytes:
+ * - Line ends at CRLF; bare LF is a protocol failure.
+ * - Logical line frames `{n}` literals (and `{n+}` LITERAL+).
+ * - Enforces maxLiteralBytes (default 32 MiB).
+ * - A number above 2^32 - 1 is an atom of digits, not a failure: RFC 9051's `number` is
+ *   32-bit, but Gmail's X-GM-THRID is 64-bit and arrives as a bare number.
+ * - Never throws on malformed input; returns typed ImapResult.
+ */
+declare const DEFAULT_MAX_LITERAL_BYTES: number;
+type ImapToken = {
+  readonly kind: 'atom';
+  readonly value: string;
+} | {
+  readonly kind: 'number';
+  readonly value: number;
+} | {
+  readonly kind: 'quoted';
+  readonly value: string;
+} | {
+  readonly kind: 'literal';
+  readonly value: Uint8Array;
+} | {
+  readonly kind: 'lparen';
+} | {
+  readonly kind: 'rparen';
+} | {
+  readonly kind: 'lbracket';
+} | {
+  readonly kind: 'rbracket';
+} | {
+  readonly kind: 'plus';
+} | {
+  readonly kind: 'nil';
+};
+type ImapFailure = {
+  readonly kind: 'no';
+  readonly text: string;
+} | {
+  readonly kind: 'bad';
+  readonly text: string;
+} | {
+  readonly kind: 'bye';
+  readonly text: string;
+} | {
+  readonly kind: 'closed';
+} | {
+  readonly kind: 'protocol';
+  readonly detail: string;
+} | {
+  readonly kind: 'unsupported';
+  readonly detail: string;
+};
+type ImapResult<T> = {
+  readonly ok: true;
+  readonly value: T;
+} | {
+  readonly ok: false;
+  readonly reason: ImapFailure;
+};
+//#endregion
+//#region src/envelope.d.ts
+type ImapAddress = {
+  readonly name: string | null;
+  readonly mailbox: string | null;
+  readonly host: string | null;
+};
+type ImapEnvelope = {
+  readonly date: string | null;
+  readonly subject: string | null;
+  readonly subjectRaw: string | null;
+  readonly from: readonly ImapAddress[];
+  readonly sender: readonly ImapAddress[];
+  readonly replyTo: readonly ImapAddress[];
+  readonly to: readonly ImapAddress[];
+  readonly cc: readonly ImapAddress[];
+  readonly bcc: readonly ImapAddress[];
+  readonly inReplyTo: string | null;
+  readonly messageId: string | null;
+};
+type ImapFetchItem = {
+  readonly kind: 'flags';
+  readonly flags: readonly string[];
+} | {
+  readonly kind: 'envelope';
+  readonly envelope: ImapEnvelope;
+} | {
+  readonly kind: 'internalDate';
+  readonly date: string;
+} | {
+  readonly kind: 'size';
+  readonly size: number;
+} | {
+  readonly kind: 'uid';
+  readonly uid: number;
+} | {
+  readonly kind: 'body';
+  readonly section: string;
+  readonly bytes: Uint8Array | null;
+} | {
+  readonly kind: 'bodyStructure';
+  readonly parts: readonly string[];
+} /** Gmail's `X-GM-THRID`: 64-bit, so kept as its decimal digits. */ | {
+  readonly kind: 'gmailThreadId';
+  readonly id: string;
+} | {
+  readonly kind: 'other';
+  readonly name: string;
+};
+//#endregion
+//#region src/response.d.ts
+type ImapMailbox = {
+  readonly name: string;
+  readonly delimiter: string | null;
+  readonly attributes: readonly string[];
+};
+type ImapResponseCode = {
+  readonly kind: 'capability';
+  readonly capabilities: readonly string[];
+} | {
+  readonly kind: 'permanentFlags';
+  readonly flags: readonly string[];
+} | {
+  readonly kind: 'uidValidity';
+  readonly value: number;
+} | {
+  readonly kind: 'uidNext';
+  readonly value: number;
+} | {
+  readonly kind: 'readOnly';
+} | {
+  readonly kind: 'readWrite';
+} | {
+  readonly kind: 'alert';
+} | {
+  readonly kind: 'other';
+  readonly code: string;
+  readonly args: readonly string[];
+};
+type ImapUntagged = {
+  readonly kind: 'status';
+  readonly status: 'OK' | 'NO' | 'BAD' | 'BYE' | 'PREAUTH';
+  readonly code: ImapResponseCode | null;
+  readonly text: string;
+} | {
+  readonly kind: 'capability';
+  readonly capabilities: readonly string[];
+} | {
+  readonly kind: 'list';
+  readonly mailbox: ImapMailbox;
+} | {
+  readonly kind: 'flags';
+  readonly flags: readonly string[];
+} | {
+  readonly kind: 'exists';
+  readonly count: number;
+} | {
+  readonly kind: 'recent';
+  readonly count: number;
+} | {
+  readonly kind: 'expunge';
+  readonly seq: number;
+} | {
+  readonly kind: 'fetch';
+  readonly seq: number;
+  readonly items: readonly ImapFetchItem[];
+} | {
+  readonly kind: 'search';
+  readonly uids: readonly number[];
+} | {
+  readonly kind: 'unknown';
+  readonly name: string;
+  readonly rest: readonly string[];
+};
+type ImapTagged = {
+  readonly kind: 'tagged';
+  readonly tag: string;
+  readonly status: 'OK' | 'NO' | 'BAD';
+  readonly code: ImapResponseCode | null;
+  readonly text: string;
+};
+type ImapContinuation = {
+  readonly kind: 'continuation';
+  readonly text: string;
+};
+type ImapResponse = ImapTagged | {
+  readonly kind: 'untagged';
+  readonly untagged: ImapUntagged;
+} | ImapContinuation;
+declare const parseResponse: (tokens: readonly ImapToken[]) => ImapResult<ImapResponse>;
+//#endregion
+//#region src/client.d.ts
+type ImapMessageSummary = {
+  readonly seq: number;
+  readonly uid: number;
+  readonly flags: readonly string[];
+  readonly internalDate: string | null;
+  readonly size: number | null;
+  readonly envelope: ImapEnvelope | null; /** The msg-ids of the `References` header, in order; empty when the message carries none. */
+  readonly references: readonly string[]; /** Gmail's thread id (decimal digits), when the server was asked and answered. */
+  readonly gmailThreadId: string | null;
+};
+type ImapMessageFlags = {
+  readonly uid: number;
+  readonly flags: readonly string[];
+};
+type ImapSelected = {
+  readonly name: string;
+  readonly exists: number;
+  readonly uidValidity: number | null;
+  readonly uidNext: number | null;
+  readonly flags: readonly string[];
+  readonly permanentFlags: readonly string[];
+  readonly readOnly: boolean;
+};
+type ImapClientOptions = {
+  readonly onUntagged?: (response: ImapUntagged) => void; /** Max bytes of a single literal the client will buffer; default 32 MiB. Larger → protocol failure. */
+  readonly maxLiteralBytes?: number;
+};
+type ImapIdle = {
+  /** Sends DONE (once; later calls are no-ops) and resolves with the IDLE's outcome. */readonly done: () => Promise<ImapResult<void>>; /** The same outcome, for a caller that wants to observe an idle ending on its own (BYE, EOF). */
+  readonly ended: Promise<ImapResult<void>>;
+};
+type ImapClient = {
+  readonly greeting: () => Promise<ImapResult<{
+    readonly text: string;
+    readonly capabilities: readonly string[] | null;
+  }>>;
+  readonly capability: () => Promise<ImapResult<readonly string[]>>;
+  readonly capabilities: () => readonly string[]; /** Case-insensitive check against the last known capability list. */
+  readonly hasCapability: (name: string) => boolean;
+  readonly authenticate: (username: string, password: string) => Promise<ImapResult<void>>;
+  readonly list: (reference: string, pattern: string) => Promise<ImapResult<readonly ImapMailbox[]>>;
+  readonly select: (mailbox: string, options?: {
+    readonly readOnly?: boolean;
+  }) => Promise<ImapResult<ImapSelected>>;
+  /**
+   * UID FETCH with FLAGS ENVELOPE INTERNALDATE RFC822.SIZE, the `References` header and, on a
+   * server advertising `X-GM-EXT-1`, `X-GM-THRID`. `set` is an IMAP sequence-set string, e.g.
+   * "1:*" or "100:200".
+   */
+  readonly fetchSummaries: (uidSet: string) => Promise<ImapResult<readonly ImapMessageSummary[]>>;
+  /**
+   * The same FETCH read by message SEQUENCE number rather than uid. Sequence numbers are dense
+   * (1..EXISTS in the selected mailbox), so a fixed-width window is that many real messages —
+   * which uids, sparse wherever mail has been deleted, cannot promise.
+   */
+  readonly fetchSummariesBySeq: (seqSet: string) => Promise<ImapResult<readonly ImapMessageSummary[]>>; /** UID FETCH FLAGS only — what a resync of already-known messages asks for. */
+  readonly fetchFlags: (uidSet: string) => Promise<ImapResult<readonly ImapMessageFlags[]>>; /** UID FETCH BODY.PEEK[] — the whole raw message. */
+  readonly fetchRaw: (uid: number) => Promise<ImapResult<Uint8Array>>;
+  readonly storeFlags: (uidSet: string, mode: 'add' | 'remove' | 'set', flags: readonly string[]) => Promise<ImapResult<void>>; /** APPEND a whole RFC 5322 message to a mailbox, e.g. a Sent copy after SMTP accepted it. */
+  readonly append: (mailbox: string, message: Uint8Array, flags: readonly string[]) => Promise<ImapResult<void>>; /** RFC 6851 UID MOVE. Refuses without the MOVE capability (no COPY+EXPUNGE fallback). */
+  readonly move: (uidSet: string, mailbox: string) => Promise<ImapResult<void>>; /** CREATE a mailbox. */
+  readonly create: (mailbox: string) => Promise<ImapResult<void>>;
+  readonly noop: () => Promise<ImapResult<void>>;
+  /**
+   * RFC 2177 IDLE. Occupies the command queue until `done()`: every other command waits
+   * behind it, so the caller MUST call `done()` before awaiting anything else. Untagged
+   * responses that arrive while idling (EXISTS, EXPUNGE, FETCH) go to `onUntagged`.
+   * Resolves once the server's tagged completion of the IDLE arrives after DONE.
+   */
+  readonly idle: () => ImapIdle;
+  readonly logout: () => Promise<ImapResult<void>>;
+};
+declare const createImapClient: (transport: ByteDuplex, options?: ImapClientOptions) => ImapClient;
+//#endregion
+//#region src/rfc2047.d.ts
+/**
+ * RFC 2047 MIME Part Three: Message Header Extensions for Non-ASCII Text.
+ *
+ * Decodes encoded-words in header fields (Q and B encodings).
+ * Crucial invariants:
+ * 1. Adjacent encoded-words separated only by linear-white-space (LWS) are joined by their
+ *    raw decoded bytes before charset decoding.
+ * 2. The output is NEVER re-scanned.
+ * 3. Unknown charsets leave the raw word intact.
+ */
+declare const decodeRfc2047: (header: string) => string;
+//#endregion
+export { DEFAULT_MAX_LITERAL_BYTES, type ImapAddress, type ImapClient, type ImapClientOptions, type ImapContinuation, type ImapEnvelope, type ImapFailure, type ImapFetchItem, type ImapIdle, type ImapMailbox, type ImapMessageSummary, type ImapResponse, type ImapResponseCode, type ImapResult, type ImapSelected, type ImapTagged, type ImapToken, type ImapUntagged, createImapClient, decodeRfc2047, parseResponse };