@lanes-sh/link 0.1.0

package/src/connectivity/transports/imap/parse.ts

@@ -0,0 +1,130 @@
+import { quoted } from './client.ts';
+import { asText, itemValue, type ImapToken } from './parser.ts';
+import { SETTABLE_FLAGS } from './operations.ts';
+
+/**
+ * Turning IMAP's wire vocabulary into ordinary values.
+ *
+ * Dates in its own peculiar `DD-Mon-YYYY`, SEARCH criteria, flag lists, and the
+ * ENVELOPE structure — none of which any other transport has an opinion about.
+ */
+
+export const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+/** IMAP wants `1-Aug-2026`, and rejects anything else without explaining. */
+export function imapDate(value: string): string | undefined {
+  const match = value.match(/^(\d{4})-(\d{2})-(\d{2})/);
+  if (!match) return undefined;
+  return `${Number(match[3])}-${MONTHS[Number(match[2]) - 1]}-${match[1]}`;
+}
+
+export function searchCriteria(args: Readonly<Record<string, unknown>>): string {
+  const parts: string[] = [];
+
+  const term = (key: string, keyword: string): void => {
+    const value = args[key];
+    if (typeof value === 'string' && value) parts.push(`${keyword} ${quoted(value)}`);
+  };
+
+  term('from', 'FROM');
+  term('to', 'TO');
+  term('subject', 'SUBJECT');
+  term('text', 'TEXT');
+
+  for (const [key, keyword] of [
+    ['since', 'SINCE'],
+    ['before', 'BEFORE'],
+  ] as const) {
+    const value = args[key];
+    if (typeof value === 'string') {
+      const formatted = imapDate(value);
+      if (formatted) parts.push(`${keyword} ${formatted}`);
+    }
+  }
+
+  if (args['unseen'] === true) parts.push('UNSEEN');
+  if (args['flagged'] === true) parts.push('FLAGGED');
+
+  return parts.length > 0 ? parts.join(' ') : 'ALL';
+}
+
+export function uidList(value: unknown): number[] {
+  if (!Array.isArray(value)) return [];
+  return value.map((entry) => Number(entry)).filter((uid) => Number.isFinite(uid) && uid > 0);
+}
+
+/**
+ * Only flags on the allowlist, silently dropping the rest.
+ *
+ * `\Deleted` is the one that matters: accepting it would let an agent stage a
+ * mailbox for destruction through a capability whose name says "mark".
+ */
+export function allowedFlags(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  const allowed = new Set<string>(SETTABLE_FLAGS);
+  return value.map(String).filter((flag) => allowed.has(flag));
+}
+
+export function flagList(token: ImapToken | undefined): string[] {
+  if (!token || token.kind !== 'list') return [];
+  return token.items.map((item) => asText(item)).filter((flag): flag is string => Boolean(flag));
+}
+
+/**
+ * The parts of an ENVELOPE worth showing.
+ *
+ * Positional, per RFC 3501: date, subject, from, sender, reply-to, to, cc, bcc,
+ * in-reply-to, message-id. Addresses are `(name adl mailbox host)`.
+ */
+export function envelopeSummary(token: ImapToken | undefined): Record<string, unknown> {
+  if (!token || token.kind !== 'list') return {};
+  const fields = token.items;
+
+  return {
+    subject: asText(fields[1]) ?? null,
+    from: addressList(fields[2])[0] ?? null,
+    to: addressList(fields[5]),
+    message_id: asText(fields[9]) ?? null,
+  };
+}
+
+export function addressList(token: ImapToken | undefined): string[] {
+  if (!token || token.kind !== 'list') return [];
+
+  return token.items
+    .map((entry) => {
+      if (entry.kind !== 'list') return null;
+      const name = asText(entry.items[0]);
+      const local = asText(entry.items[2]);
+      const host = asText(entry.items[3]);
+      if (!local || !host) return null;
+      const address = `${local}@${host}`;
+      return name ? `${name} <${address}>` : address;
+    })
+    .filter((entry): entry is string => entry !== null);
+}
+
+export function formatAddress(address: {
+  name?: string | undefined;
+  address?: string | undefined;
+}): string {
+  // A group address (`undisclosed-recipients:;`) has a name and no address.
+  if (!address.address) return address.name ?? '';
+  return address.name ? `${address.name} <${address.address}>` : address.address;
+}
+
+/** A readable fallback when a message carries only HTML. */
+export function stripHtml(html: string): string {
+  return html
+    .replace(/<(script|style)[\s\S]*?<\/\1>/gi, '')
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<\/(p|div|tr|li|h[1-6])>/gi, '\n')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}

package/src/connectivity/transports/imap/parser.ts

@@ -0,0 +1,272 @@
+/**
+ * Reading IMAP responses.
+ *
+ * The one thing that must not be done line-wise. A response may announce a
+ * literal — `{1234}` at the end of a line — and the next 1234 bytes are then
+ * *arbitrary*: a message body containing CRLF, quotes, parentheses, and NUL. A
+ * reader that splits on CRLF tears those apart and produces garbage that looks
+ * like a protocol error, which is why this assembles by counting bytes and only
+ * then tokenises.
+ *
+ * Bytes rather than strings all the way through, because `BODY[]` is the raw
+ * RFC 822 message and decoding it as UTF-8 before the MIME layer has read its
+ * charset would corrupt every non-UTF-8 mail in the box.
+ */
+
+const CR = 0x0d;
+const LF = 0x0a;
+
+/** A parsed element of a response. */
+export type ImapToken =
+  | { readonly kind: 'atom'; readonly value: string }
+  | { readonly kind: 'quoted'; readonly value: string }
+  | { readonly kind: 'literal'; readonly bytes: Uint8Array }
+  | { readonly kind: 'list'; readonly items: readonly ImapToken[] };
+
+/**
+ * Accumulates bytes and hands back one complete logical response at a time.
+ *
+ * "Logical" is the important word: a single response can span several physical
+ * lines whenever a literal is involved, and it is not complete until every
+ * announced literal has arrived in full.
+ */
+export class ResponseAssembler {
+  #buffer = new Uint8Array(0);
+
+  push(chunk: Uint8Array): void {
+    const merged = new Uint8Array(this.#buffer.length + chunk.length);
+    merged.set(this.#buffer);
+    merged.set(chunk, this.#buffer.length);
+    this.#buffer = merged;
+  }
+
+  /** The next complete response, or undefined while more bytes are needed. */
+  next(): Uint8Array | undefined {
+    const end = completeResponseEnd(this.#buffer);
+    if (end === undefined) return undefined;
+
+    const response = this.#buffer.subarray(0, end);
+    this.#buffer = this.#buffer.slice(end);
+    return response;
+  }
+
+  /** Whatever has arrived but does not yet form a response. For diagnostics. */
+  get pending(): number {
+    return this.#buffer.length;
+  }
+}
+
+/** Where a complete response ends, counting past every literal it announces. */
+function completeResponseEnd(buffer: Uint8Array): number | undefined {
+  let cursor = 0;
+
+  for (;;) {
+    const crlf = indexOfCrlf(buffer, cursor);
+    if (crlf === -1) return undefined;
+
+    const announced = literalLength(buffer, cursor, crlf);
+    if (announced === undefined) return crlf + 2;
+
+    const afterLiteral = crlf + 2 + announced;
+    if (buffer.length < afterLiteral) return undefined;
+
+    // The literal is in hand; the response continues after it, and may announce
+    // another — `BODY[HEADER] {12} ... BODY[TEXT] {900} ...` in one FETCH.
+    cursor = afterLiteral;
+  }
+}
+
+function indexOfCrlf(buffer: Uint8Array, from: number): number {
+  for (let index = from; index + 1 < buffer.length; index++) {
+    if (buffer[index] === CR && buffer[index + 1] === LF) return index;
+  }
+  return -1;
+}
+
+/**
+ * The size a line announces, if it ends in a literal marker.
+ *
+ * `{123}` or `{123+}` — the `+` form is LITERAL+, which a server uses to say it
+ * is not waiting for a continuation.
+ */
+function literalLength(buffer: Uint8Array, from: number, crlf: number): number | undefined {
+  let index = crlf - 1;
+  if (index < from) return undefined;
+
+  // Read right to left: `}`, then an optional `+` *inside* the braces, then the
+  // digits, then `{`.
+  if (buffer[index] !== 0x7d /* } */) return undefined;
+  index--;
+  if (index >= from && buffer[index] === 0x2b /* + */) index--; // LITERAL+
+
+  let digits = '';
+  while (index >= from && buffer[index]! >= 0x30 && buffer[index]! <= 0x39) {
+    digits = String.fromCharCode(buffer[index]!) + digits;
+    index--;
+  }
+
+  if (digits === '' || index < from || buffer[index] !== 0x7b /* { */) return undefined;
+  return Number(digits);
+}
+
+/**
+ * Turn one complete response into tokens.
+ *
+ * Brackets are deliberately kept inside atoms: `BODY[HEADER.FIELDS (FROM DATE)]`
+ * is *one* item name, parentheses and all, and splitting it on the space would
+ * turn the FETCH item into two unrecognisable ones.
+ */
+export function tokenize(response: Uint8Array): ImapToken[] {
+  const state = { at: 0 };
+  const tokens = readTokens(response, state, null);
+  return tokens;
+}
+
+function readTokens(
+  buffer: Uint8Array,
+  state: { at: number },
+  closer: number | null,
+): ImapToken[] {
+  const tokens: ImapToken[] = [];
+
+  while (state.at < buffer.length) {
+    const byte = buffer[state.at]!;
+
+    if (byte === CR || byte === LF) {
+      // A bare CRLF ends the response; inside a list it is part of a literal's
+      // surroundings and simply skipped.
+      state.at++;
+      if (closer === null) break;
+      continue;
+    }
+
+    if (byte === 0x20 /* space */) {
+      state.at++;
+      continue;
+    }
+
+    if (closer !== null && byte === closer) {
+      state.at++;
+      break;
+    }
+
+    if (byte === 0x28 /* ( */) {
+      state.at++;
+      tokens.push({ kind: 'list', items: readTokens(buffer, state, 0x29 /* ) */) });
+      continue;
+    }
+
+    if (byte === 0x22 /* " */) {
+      tokens.push({ kind: 'quoted', value: readQuoted(buffer, state) });
+      continue;
+    }
+
+    if (byte === 0x7b /* { */) {
+      const literal = readLiteral(buffer, state);
+      if (literal) {
+        tokens.push({ kind: 'literal', bytes: literal });
+        continue;
+      }
+    }
+
+    tokens.push({ kind: 'atom', value: readAtom(buffer, state, closer) });
+  }
+
+  return tokens;
+}
+
+function readQuoted(buffer: Uint8Array, state: { at: number }): string {
+  state.at++; // opening quote
+  const bytes: number[] = [];
+
+  while (state.at < buffer.length) {
+    const byte = buffer[state.at]!;
+    if (byte === 0x5c /* \ */ && state.at + 1 < buffer.length) {
+      bytes.push(buffer[state.at + 1]!);
+      state.at += 2;
+      continue;
+    }
+    if (byte === 0x22) {
+      state.at++;
+      break;
+    }
+    bytes.push(byte);
+    state.at++;
+  }
+
+  return new TextDecoder().decode(new Uint8Array(bytes));
+}
+
+function readLiteral(buffer: Uint8Array, state: { at: number }): Uint8Array | undefined {
+  const close = buffer.indexOf(0x7d /* } */, state.at);
+  if (close === -1) return undefined;
+
+  const header = new TextDecoder().decode(buffer.subarray(state.at + 1, close));
+  const size = Number(header.replace('+', ''));
+  if (!Number.isFinite(size)) return undefined;
+
+  // The size is followed by CRLF, then exactly `size` bytes.
+  let start = close + 1;
+  if (buffer[start] === CR) start++;
+  if (buffer[start] === LF) start++;
+
+  const end = Math.min(start + size, buffer.length);
+  state.at = end;
+  return buffer.subarray(start, end);
+}
+
+function readAtom(buffer: Uint8Array, state: { at: number }, closer: number | null): string {
+  const start = state.at;
+  let brackets = 0;
+
+  while (state.at < buffer.length) {
+    const byte = buffer[state.at]!;
+
+    if (byte === 0x5b /* [ */) brackets++;
+    else if (byte === 0x5d /* ] */) brackets--;
+    else if (brackets === 0) {
+      if (byte === 0x20 || byte === CR || byte === LF) break;
+      if (byte === 0x28 || byte === 0x29) break;
+      if (closer !== null && byte === closer) break;
+    }
+
+    state.at++;
+  }
+
+  return new TextDecoder().decode(buffer.subarray(start, state.at));
+}
+
+// ---------------------------------------------------------------------------
+// Reading what was parsed
+// ---------------------------------------------------------------------------
+
+/** The text of any token that has one. `NIL` is an absent value, not the word. */
+export function asText(token: ImapToken | undefined): string | undefined {
+  if (!token) return undefined;
+  if (token.kind === 'atom') return token.value === 'NIL' ? undefined : token.value;
+  if (token.kind === 'quoted') return token.value;
+  if (token.kind === 'literal') return new TextDecoder().decode(token.bytes);
+  return undefined;
+}
+
+/**
+ * The value following a named item, as FETCH lays them out.
+ *
+ * A FETCH response is a flat alternation — `UID 5 FLAGS (\Seen) RFC822.SIZE 42`
+ * — so an item's value is simply the token after its name. Matching is prefix-
+ * based because `BODY[]` and `BODY[HEADER.FIELDS (DATE)]` are different names
+ * for the same request depending on what was asked for.
+ */
+export function itemValue(
+  items: readonly ImapToken[],
+  name: string,
+): ImapToken | undefined {
+  for (let index = 0; index < items.length; index++) {
+    const token = items[index]!;
+    if (token.kind !== 'atom') continue;
+    if (token.value === name || token.value.toUpperCase().startsWith(`${name.toUpperCase()}[`)) {
+      return items[index + 1];
+    }
+  }
+  return undefined;
+}

package/src/connectivity/transports/imap/result.ts

@@ -0,0 +1,15 @@
+import type { ToolResult } from '#connectivity';
+
+/** The two result shapes every operation returns. */
+
+export function error(message: string): ToolResult {
+  return { content: [{ type: 'text', text: message }], isError: true };
+}
+
+export function json(value: unknown): ToolResult {
+  return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+}
+
+// ---------------------------------------------------------------------------
+// Operations
+// ---------------------------------------------------------------------------

package/src/connectivity/transports/imap/send.ts

@@ -0,0 +1,92 @@
+import nodemailer from 'nodemailer';
+import { composeMime, type ComposedMessage, type OutgoingMessage } from '#connectivity/mail';
+import type { ImapCredential } from './client.ts';
+
+/**
+ * SMTP submission.
+ *
+ * Composition itself lives in `#connectivity/mail` — it grew a second caller
+ * once an HTTP mail API needed the same assembled bytes, and one MIME builder is
+ * the difference between one set of boundary bugs and two. What stays here is the
+ * part that is actually SMTP: the envelope, the TLS decision, and the socket.
+ *
+ * The message is composed once and then both sent *and* appended, so the copy in
+ * Sent is byte-identical to what the recipient got rather than a re-render of the
+ * same intent.
+ */
+
+export interface SmtpTarget {
+  readonly host: string;
+  readonly port: number;
+  readonly starttls: boolean;
+  /** Largest encoded message this host accepts. See the manifest field. */
+  readonly maxMessageBytes: number;
+}
+
+export type { OutgoingMessage };
+
+/** What went out, and the exact bytes of it, for appending to Sent. */
+export type SentMessage = ComposedMessage;
+
+export type Sender = (input: {
+  target: SmtpTarget;
+  credential: ImapCredential;
+  from: string;
+  /**
+   * The name shown beside the address.
+   *
+   * SMTP submits exactly what we compose — unlike an HTTP mail API, there is no
+   * server-side step that fills in the account's own name — so without this the
+   * `From` header is a bare address, which is what makes a sent message look
+   * machine-generated.
+   */
+  fromName?: string | undefined;
+  message: OutgoingMessage;
+}) => Promise<SentMessage>;
+
+export const sendOverSmtp: Sender = async ({
+  target,
+  credential,
+  from,
+  fromName,
+  message,
+}) => {
+  const envelope = {
+    from,
+    to: [...message.to, ...(message.cc ?? []), ...(message.bcc ?? [])],
+  };
+
+  // The envelope keeps the bare address: SMTP's MAIL FROM is a routing
+  // identity, not a display one, and a name there is a protocol error.
+  const built = await composeMime({ from, fromName, message });
+
+  // Checked here rather than by the caller because this is the only point where
+  // the real number exists: base64 expansion, headers and boundaries are all
+  // decided by composition, so any earlier figure is an estimate. And it must be
+  // before submission — a message refused part-way through `DATA` has already
+  // cost the upload and reads like a dropped connection.
+  if (built.raw.byteLength > target.maxMessageBytes) {
+    throw new Error(
+      `The composed message is ${built.raw.byteLength} bytes and ${target.host} accepts ${target.maxMessageBytes}. Attachments are base64 in transit, so they weigh about a third more than on disk.`,
+    );
+  }
+
+  const transport = nodemailer.createTransport({
+    host: target.host,
+    port: target.port,
+    // 465 is implicit TLS; 587 upgrades. `requireTLS` makes the upgrade
+    // mandatory rather than best-effort — without it a downgrade would send the
+    // password in the clear.
+    secure: !target.starttls,
+    requireTLS: target.starttls,
+    auth: { user: credential.username, pass: credential.password },
+  });
+
+  try {
+    await transport.sendMail({ raw: built.raw, envelope });
+  } finally {
+    transport.close();
+  }
+
+  return built;
+};

package/src/connectivity/transports/imap/socket.ts

@@ -0,0 +1,111 @@
+/**
+ * The one place this connector touches a socket.
+ *
+ * Behind an interface for the same reason `HttpConnectorOptions.fetch` is: a
+ * test needs to drive the protocol without a server, and the protocol is where
+ * the bugs are. Everything above this file speaks in bytes and never learns
+ * whether they came from Bun, from Node, or from an array in a test.
+ */
+
+export interface ImapSocket {
+  write(data: Uint8Array): Promise<void>;
+  /** The next chunk, or null once the peer has gone away. */
+  read(): Promise<Uint8Array | null>;
+  close(): Promise<void>;
+}
+
+export interface SocketTarget {
+  readonly host: string;
+  readonly port: number;
+  readonly signal?: AbortSignal | undefined;
+}
+
+export type SocketFactory = (target: SocketTarget) => Promise<ImapSocket>;
+
+/**
+ * Connect over implicit TLS.
+ *
+ * There is no plaintext option, and the manifest schema has no flag for one.
+ * IMAP's `LOGIN` puts the password on the wire in the clear, so a cleartext
+ * session is not a degraded mode — it is a credential disclosure, and offering
+ * it as configuration invites someone to reach for it while debugging.
+ */
+export const connectTls: SocketFactory = async (target) => {
+  const incoming: Uint8Array[] = [];
+  let waiting: ((chunk: Uint8Array | null) => void) | null = null;
+  let draining: (() => void) | null = null;
+  let ended = false;
+  let failure: Error | null = null;
+
+  const deliver = (chunk: Uint8Array | null): void => {
+    if (waiting) {
+      const resolve = waiting;
+      waiting = null;
+      resolve(chunk);
+      return;
+    }
+    if (chunk) incoming.push(chunk);
+  };
+
+  const socket = await Bun.connect({
+    hostname: target.host,
+    port: target.port,
+    tls: true,
+    socket: {
+      data(_socket, data) {
+        deliver(new Uint8Array(data));
+      },
+      drain() {
+        const resume = draining;
+        draining = null;
+        resume?.();
+      },
+      close() {
+        ended = true;
+        deliver(null);
+      },
+      error(_socket, error) {
+        failure = error;
+        ended = true;
+        deliver(null);
+      },
+    },
+  });
+
+  return {
+    async write(data) {
+      // Written in a loop because a large APPEND — saving a sent message back
+      // to the mailbox — will not fit in the socket's buffer in one go, and a
+      // short write that goes unnoticed truncates the message.
+      let offset = 0;
+      while (offset < data.length) {
+        const written = socket.write(data.subarray(offset));
+        if (written > 0) {
+          offset += written;
+          continue;
+        }
+        if (ended) throw failure ?? new Error('The connection closed while sending.');
+        await new Promise<void>((resolve) => {
+          draining = resolve;
+        });
+      }
+    },
+
+    async read() {
+      if (incoming.length > 0) return incoming.shift()!;
+      if (ended) {
+        if (failure) throw failure;
+        return null;
+      }
+      return new Promise<Uint8Array | null>((resolve) => {
+        waiting = resolve;
+        target.signal?.addEventListener('abort', () => resolve(null), { once: true });
+      });
+    },
+
+    async close() {
+      ended = true;
+      socket.end();
+    },
+  };
+};