@volter/twin-gmail 0.0.0-stage → 1.0.1

package/dist/spec/sources.json

@@ -0,0 +1,25 @@
+{
+  "https://knowledge.workspace.google.com/admin/support/troubleshooting/gmail-smtp-errors-and-codes": {
+    "status": 200,
+    "checked": "2026-11-11",
+    "quotes": {
+      "gsmtp (Google SMTP) is added to all errors": true,
+      "The email account that you tried to reach does not exist.": true,
+      "Your message exceeded Google's message size limits.": true
+    }
+  },
+  "https://www.rfc-editor.org/rfc/rfc2047": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "encoded-word = \"=?\" charset \"?\" encoding \"?\" encoded-text \"?=\"": true
+    }
+  },
+  "https://www.rfc-editor.org/rfc/rfc5322": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "Unfolding is accomplished by simply removing any CRLF that is immediately followed by WSP": true
+    }
+  }
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// world-gmail: serve the gmail twin (its webmail, and its receiving SMTP server on the side port the World allocates).
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+import { createGmailTwinServer } from "./server.js";
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const smtpPort = Number(optionValue(rest, '--smtp-port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only');
+if (cmd === 'serve' || cmd === undefined) {
+    const s = await createGmailTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(smtpPort ? { smtpPort } : {}) });
+    process.stdout.write(`gmail twin${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`);
+    process.stdout.write(`gmail twin receiving mail on smtp://127.0.0.1:${s.smtpPort}\n`);
+    await keepProcessAlive();
+}
+else {
+    process.stdout.write('Usage: world-gmail serve [--port N] [--smtp-port N] [--root DIR] [--read-only]\n');
+}

package/dist/src/engine/mail.d.ts

@@ -0,0 +1,19 @@
+type Attachment = {
+    filename: string | null;
+    contentType: string;
+    size: number;
+    contentId: string | null;
+    base64: string;
+};
+type Parsed = {
+    headers: Record<string, string>;
+    subject: string;
+    from: string;
+    to: string[];
+    cc: string[];
+    text: string | null;
+    html: string | null;
+    attachments: Attachment[];
+};
+export declare function parse(data: string): Parsed;
+export {};

package/dist/src/engine/mail.js

@@ -0,0 +1,89 @@
+/** Headers and body split at the first empty line; folded headers unfolded, names lowercased (RFC 5322 §2.2.3). */
+// source: https://www.rfc-editor.org/rfc/rfc5322 "Unfolding is accomplished by simply removing any CRLF that is immediately followed by WSP"
+function split(raw) {
+    const at = raw.search(/\r?\n\r?\n/);
+    const head = at < 0 ? raw : raw.slice(0, at);
+    const body = at < 0 ? '' : raw.slice(at).replace(/^\r?\n\r?\n/, '');
+    const headers = {};
+    for (const line of head.replace(/\r?\n[ \t]+/g, ' ').split(/\r?\n/)) {
+        const i = line.indexOf(':');
+        if (i > 0)
+            headers[line.slice(0, i).trim().toLowerCase()] ??= utf8(bytesOf(line.slice(i + 1).trim()));
+    }
+    return { headers, body };
+}
+const param = (value, name) => {
+    const m = new RegExp(`;\\s*${name}\\*?=\\s*(?:"([^"]*)"|([^;\\s]+))`, 'i').exec(value);
+    const v = m?.[1] ?? m?.[2];
+    return v?.startsWith("utf-8''") || v?.startsWith("UTF-8''") ? decodeURIComponent(v.slice(7)) : v;
+};
+const bytesOf = (s) => Uint8Array.from(s, (c) => c.charCodeAt(0) & 0xff);
+const utf8 = (b) => new TextDecoder().decode(b);
+const textFor = (b, charset) => { try {
+    return new TextDecoder(charset ?? 'utf-8').decode(b);
+}
+catch {
+    return utf8(b);
+} };
+/** A part's body decoded by its Content-Transfer-Encoding: base64 and quoted-printable to bytes (RFC 2045 §6). */
+function decoded(part) {
+    const enc = (part.headers['content-transfer-encoding'] ?? '7bit').toLowerCase();
+    if (enc === 'base64') {
+        try {
+            return bytesOf(atob(part.body.replace(/\s+/g, '')));
+        }
+        catch {
+            return bytesOf(part.body);
+        }
+    }
+    if (enc === 'quoted-printable')
+        return bytesOf(part.body.replace(/=\r?\n/g, '').replace(/=([0-9A-Fa-f]{2})/g, (_, h) => String.fromCharCode(Number.parseInt(h, 16))).split('').map((c) => (c.charCodeAt(0) > 0xff ? '?' : c)).join(''));
+    return bytesOf(part.body);
+}
+/** Encoded words in a header (`=?UTF-8?B?…?=`, `=?UTF-8?Q?…?=`), decoded (RFC 2047). */
+// source: https://www.rfc-editor.org/rfc/rfc2047 "encoded-word = \"=?\" charset \"?\" encoding \"?\" encoded-text \"?=\""
+function words(value) {
+    return value.replace(/=\?([^?]+)\?([BbQq])\?([^?]*)\?=(\s+(?==\?))?/g, (_, _cs, e, t) => {
+        try {
+            return textFor(e.toUpperCase() === 'B' ? bytesOf(atob(t)) : bytesOf(t.replace(/_/g, ' ').replace(/=([0-9A-Fa-f]{2})/g, (_m, h) => String.fromCharCode(Number.parseInt(h, 16)))), _cs);
+        }
+        catch {
+            return t;
+        }
+    });
+}
+const addresses = (v) => (v ? words(v).split(/,(?=(?:[^"]*"[^"]*")*[^"]*$)/).map((a) => (/<([^>]+)>/.exec(a)?.[1] ?? a).trim()).filter(Boolean) : []);
+/** The message's parts: a multipart's each (recursively), else the one. */
+function leaves(part) {
+    const type = part.headers['content-type'] ?? 'text/plain';
+    const boundary = /^multipart\//i.test(type) ? param(type, 'boundary') : undefined;
+    if (!boundary)
+        return [part];
+    const pieces = part.body.split(new RegExp(`\\r?\\n?--${boundary.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:--)?[ \\t]*\\r?\\n?`));
+    return pieces.slice(1, -1).filter((p) => p.trim()).flatMap((p) => leaves(split(p)));
+}
+export function parse(data) {
+    const top = split(data);
+    let text = null;
+    let html = null;
+    const attachments = [];
+    for (const leaf of leaves(top)) {
+        const type = (leaf.headers['content-type'] ?? 'text/plain').split(';')[0].trim().toLowerCase();
+        const disposition = leaf.headers['content-disposition'] ?? '';
+        const filename = param(disposition, 'filename') ?? param(leaf.headers['content-type'] ?? '', 'name');
+        const bytes = decoded(leaf);
+        if (!/^attachment/i.test(disposition) && !filename && type === 'text/plain' && text === null) {
+            text = textFor(bytes, param(leaf.headers['content-type'] ?? '', 'charset'));
+            continue;
+        }
+        if (!/^attachment/i.test(disposition) && !filename && type === 'text/html' && html === null) {
+            html = textFor(bytes, param(leaf.headers['content-type'] ?? '', 'charset'));
+            continue;
+        }
+        let bin = '';
+        for (const b of bytes)
+            bin += String.fromCharCode(b);
+        attachments.push({ filename: filename ? words(filename) : null, contentType: type, size: bytes.length, contentId: leaf.headers['content-id']?.replace(/^<|>$/g, '') ?? null, base64: btoa(bin) });
+    }
+    return { headers: top.headers, subject: words(top.headers.subject ?? ''), from: addresses(top.headers.from)[0] ?? '', to: addresses(top.headers.to), cc: addresses(top.headers.cc), text, html, attachments };
+}

package/dist/src/fetch.d.ts

@@ -0,0 +1,2 @@
+import { type DerivedFetch, type PackFetchOptions } from '@volter/world-core';
+export declare function createGmailFetch(options?: PackFetchOptions): DerivedFetch;

package/dist/src/fetch.js

@@ -0,0 +1,18 @@
+// GENERATED by scripts/create-pack.ts (--init, --index): a fixed file. The kernel serves the discovery door, the clock,
+// the World's doors, the vendor's screens and the API from the pack's parts (architecture, "The pack contract").
+import { createPackFetch } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from "./manifest.js";
+import { around } from "./semantics/around.js";
+import { gmailSemantics } from "./semantics/index.js";
+import { screen as screen_home } from "./screens/home.js";
+import { screen as screen_mail } from "./screens/mail.js";
+export function createGmailFetch(options = {}) {
+    return createPackFetch({
+        manifest,
+        surface: surface,
+        handlers: gmailSemantics,
+        around,
+        screens: { "home": screen_home, "mail": screen_mail },
+    }, options);
+}

package/dist/src/generated/surface.gen.json

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","spec":"rfc5321.txt","format":"command-reply","version":"RFC 5321","anyCommand":[500,501,421],"commands":[{"id":"CONNECTION ESTABLISHMENT","intermediate":[],"success":[220],"error":[554]},{"id":"EHLO","intermediate":[],"success":[250],"error":[504,550,502]},{"id":"HELO","intermediate":[],"success":[250],"error":[504,550,502]},{"id":"MAIL","intermediate":[],"success":[250],"error":[552,451,452,550,553,503,455,555]},{"id":"RCPT","intermediate":[],"success":[250,251],"error":[550,551,552,553,450,451,452,503,455,555]},{"id":"DATA","intermediate":[354],"success":[],"error":[503,554],"then":{"intermediate":[],"success":[250],"error":[552,554,451,452,450,550]}},{"id":"RSET","intermediate":[],"success":[250],"error":[]},{"id":"VRFY","intermediate":[],"success":[250,251,252],"error":[550,551,553,502,504]},{"id":"EXPN","intermediate":[],"success":[250,252],"error":[550,500,502,504]},{"id":"HELP","intermediate":[],"success":[211,214],"error":[502,504]},{"id":"NOOP","intermediate":[],"success":[250],"error":[]},{"id":"QUIT","intermediate":[],"success":[221],"error":[]}]}

package/dist/src/index.d.ts

@@ -0,0 +1,6 @@
+import { manifest } from './manifest.js';
+export { createGmailFetch } from './fetch.js';
+export { createGmailTwinServer } from './server.js';
+export { createGmailTwinStream } from './stream.js';
+export { manifest };
+export declare const pack: import("@volter/world-core").PackDescriptor;

package/dist/src/index.js

@@ -0,0 +1,11 @@
+// @volter/twin-gmail — the gmail twin (Protocol 3). A fixed file (create-pack): the descriptor is the manifest's, and the
+// kernel derives the vendor-backed half from the generated surface, unless the manifest declares none (vendorBacked.none;
+// architecture, "The real-system adapters").
+import { packOf, registerPack } from '@volter/world-core';
+import { manifest } from "./manifest.js";
+import surface from './generated/surface.gen.json' with { type: 'json' };
+export { createGmailFetch } from "./fetch.js";
+export { createGmailTwinServer } from "./server.js";
+export { createGmailTwinStream } from "./stream.js";
+export { manifest };
+export const pack = registerPack(packOf(manifest, surface));

package/dist/src/manifest.d.ts

@@ -0,0 +1,2 @@
+import type { DerivedManifest } from '@volter/world-core';
+export declare const manifest: DerivedManifest;

package/dist/src/manifest.js

@@ -0,0 +1,68 @@
+import { states } from "./semantics/states.js";
+export const manifest = {
+    vendor: 'gmail',
+    service: 'gmail',
+    discovery: {
+        twinOf: "Gmail: its receiving SMTP server (gmail.com's MX) and its webmail at mail.google.com",
+        identity: "The SMTP side port takes mail from any sender, as an MX does, for gmail.com accounts Google holds. Webmail reads the person's Google session (googleoauth's SID cookie).",
+        stores: "each Google account's mailbox: the messages it received, with their envelope, bytes, headers, bodies and attachments",
+    },
+    body: { json: 'always' },
+    ids: { template: '{letters:16}' },
+    time: 'iso',
+    // the screens' and the wire's refusals; the wire answers in SMTP replies (./semantics/shared.ts)
+    error: { error: '{message}' },
+    readOnly: { status: 403, message: 'the twin is read-only' },
+    notFound: { status: 404, message: 'Not Found' },
+    list: { style: 'envelope', envelope: { messages: '{data}' }, limit: { param: 'limit', default: 50, max: 500 } },
+    deleted: {},
+    vendorBacked: { none: 'Mail reaches Gmail over SMTP from a sending twin inside the World; there is no derived HTTP perform or vendor resource refresh (the Gmail API is a later card).' },
+    unmodeled: ['EXPN', 'HELP'],
+    // who a message's records name (ADR 0036, "Replicating an issue"): its mailbox, the Google account it was kept for,
+    // and its envelope's addresses; the recipient as Gmail delivers it, where `local+tag@gmail.com` is the mailbox
+    // `local@gmail.com` labelled (shared.ts accountOf), so a pseudonymized pull keeps the tag on the mailbox's pseudonym (`email+`)
+    privacy: {
+        identifiers: {
+            message: { mailbox: 'email', 'envelope.to': 'email+', 'envelope.from': 'email', receivedAt: 'time' },
+        },
+    },
+    ownerReads: [
+        { owner: 'googleoauth', resource: '_person' },
+        { owner: 'googleoauth', resource: 'account' },
+        { owner: 'googleoauth', resource: '_web_session' },
+    ],
+    resources: {
+        Session: { storedAs: '_session', refresh: { none: 'Connection-local state, not a vendor resource.' }, idPrefix: 'session', ...states.Session },
+        message: { refresh: { none: 'The Gmail API, which would read a mailbox back, is a later card.' }, idPrefix: '', ids: '{letters:16}' },
+    },
+    screens: [{
+            // Gmail's webmail (screens/mail.ts): the signed-in person's inbox, a message with its links, and its attachments
+            id: 'mail', kind: 'workspace', host: 'mail.google.com', path: '/mail',
+            demand: "a person reads the mail an application sent them (Rallly's invitation with its invite.ics, Dub's links) and follows its link", status: 'done',
+            controls: ['Inbox', 'Download'], source: 'https://support.google.com/mail/answer/8494',
+        }, {
+            // gmail.com itself, which sends a visitor to the webmail
+            id: 'home', kind: 'flow', host: 'gmail.com', path: '/',
+            demand: 'a person who opens gmail.com reaches their inbox', status: 'done',
+            source: 'https://support.google.com/mail/answer/8494',
+        }],
+    descriptor: {
+        protocol: '3',
+        transport: 'rest',
+        archetype: 'crud',
+        bin: 'world-gmail',
+        resources: ['message'],
+        specSource: "spec/rfc5321.txt (RFC 5321): the command-reply table of Gmail's receiving server (spec/SOURCE.md)",
+        description: "Gmail twin — gmail.com's receiving SMTP server, which keeps mail for the World's Google accounts and refuses other addresses, and the webmail at mail.google.com where the signed-in person reads it and downloads its attachments.",
+        adoption: { sdks: [], envStems: [] },
+        // gmail.com: the domain whose mail this server receives (the kernel's ctx.mail routes by it), and its site; the
+        // webmail's host
+        hosts: [{ host: 'mail.google.com' }, { host: 'gmail.com' }],
+        endpointEnvNone: 'no application reads Gmail by a base URL: mail reaches it from the World\'s senders (ctx.mail), and a person opens its webmail',
+        // a gmail.com address is a Google account, made at Google's own sign-up (googleoauth's accounts.google.com/signup,
+        // which leaves the person signed in): the door the World's generated seed calls for each declared person whose
+        // address this pack's mail domain is (ADR 0033 §3)
+        seed: { signUp: 'https://accounts.google.com/signup' },
+        sidePorts: [{ name: 'smtp', option: 'smtpPort', flag: '--smtp-port', scheme: 'smtp', note: "Gmail's receiving SMTP server (gmail-smtp-in.l.google.com), without TLS: mail for gmail.com's accounts, handed on by the World's senders through ctx.mail" }],
+    },
+};

package/dist/src/screens/home.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerContext } from '@volter/world-core';
+export declare function screen(_ctx: HandlerContext): Promise<Response>;

package/dist/src/screens/home.js

@@ -0,0 +1,3 @@
+export async function screen(_ctx) {
+    return new Response(null, { status: 301, headers: { location: 'https://mail.google.com/mail/' } });
+}

package/dist/src/screens/mail.d.ts

@@ -0,0 +1,2 @@
+import { type HandlerContext } from '@volter/world-core';
+export declare function screen(ctx: HandlerContext): Promise<Response>;

package/dist/src/screens/mail.js

@@ -0,0 +1,142 @@
+// Gmail's webmail (mail.google.com/mail): the signed-in person's inbox, one message with its links, and its attachments,
+// under the person's Google session (googleoauth's SID cookie, read through the kernel's cross-pack read: ADR 0032 §2).
+// A browser with no Google session is sent to Google's sign-in, which returns it here.
+//
+//   GET /mail, /mail/u/0/                          the inbox, newest first
+//   GET /mail/u/0/inbox/<id>                       one message: its sender, recipients, subject and body, links followable
+//   GET /mail/u/0/inbox/<id>/attachments/<index>   one attachment's bytes, downloaded
+//
+// Where the documentation stops: Gmail draws its pages in the browser and names a message in the page's fragment
+// (`#inbox/<id>`); the twin renders each on the server at a path of its own, so a person (or a walk) opens and clicks it
+// as a page. A message's HTML is sanitized on the server by the kernel's HTML grammar and shown inline in the message
+// body, as Gmail shows it, its links opening a new tab; the body is the containing boundary of everything it draws.
+// Composing, replying, labels, search and the other folders are not built.
+import { html } from '@volter/world-core';
+import { MESSAGE, signedInAccount } from "../semantics/shared.js";
+const esc = (v) => String(v ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+// What Gmail keeps of a received message (ADR 0032 §4): these elements go with their content; these are kept; any other
+// element is unwrapped, its children kept. Only these attributes stay, so no received class or id poses as the
+// webmail's own element.
+const DROPPED = new Set(['script', 'style', 'link', 'meta', 'base', 'title', 'head', 'iframe', 'frame', 'frameset', 'object', 'embed', 'applet', 'form', 'input', 'button', 'select', 'textarea', 'option', 'template', 'noscript', 'svg', 'math', 'video', 'audio', 'source', 'track', 'canvas']);
+const KEPT = new Set(['a', 'abbr', 'address', 'b', 'bdi', 'bdo', 'big', 'blockquote', 'br', 'caption', 'center', 'cite', 'code', 'col', 'colgroup', 'dd', 'del', 'dfn', 'div', 'dl', 'dt', 'em', 'font', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'hr', 'i', 'img', 'ins', 'kbd', 'li', 'mark', 'ol', 'p', 'pre', 'q', 's', 'samp', 'small', 'span', 'strike', 'strong', 'sub', 'sup', 'table', 'tbody', 'td', 'tfoot', 'th', 'thead', 'tr', 'tt', 'u', 'ul', 'wbr']);
+const ATTRIBUTES = new Set(['href', 'src', 'alt', 'title', 'width', 'height', 'align', 'valign', 'colspan', 'rowspan', 'border', 'cellpadding', 'cellspacing', 'bgcolor', 'color', 'face', 'size', 'dir', 'lang', 'style']);
+/** A style attribute as Gmail keeps it (ADR 0032 §4): without a remote load, a script or positioning, for an ordinary
+ *  spelling. This is fidelity with Gmail, not the boundary: the message body contains whatever a style draws (BODY) and
+ *  the page's CSP refuses every load, so an escaped spelling this misses stays inside the body and loads nothing. */
+const style = (value) => value.split(';').map((declaration) => declaration.trim()).filter((declaration) => {
+    if (!declaration)
+        return false;
+    const lower = declaration.toLowerCase();
+    if (lower.includes('url(') || lower.includes('expression(') || lower.includes('@import'))
+        return false;
+    const property = lower.slice(0, lower.indexOf(':') === -1 ? lower.length : lower.indexOf(':')).trim();
+    return property !== 'position' && property !== 'behavior' && property !== '-moz-binding';
+}).join('; ');
+// The message body is the containing boundary of what the message draws: paint containment makes it the containing
+// block of every positioned descendant, `position: fixed` included, and clips what they paint to it (CSS Containment
+// Level 2 §3.3, https://www.w3.org/TR/css-contain-2/#containment-paint); its own stacking context keeps the message's
+// z-index inside it.
+const BODY = 'contain:paint;overflow:hidden;isolation:isolate;position:relative';
+const scheme = (value) => { try {
+    return new URL(value).protocol;
+}
+catch {
+    return '';
+} };
+function keep(nodes) {
+    const out = [];
+    for (const node of nodes) {
+        if (node.type === 'text') {
+            out.push(node);
+            continue;
+        }
+        if (DROPPED.has(node.name))
+            continue;
+        const children = keep(node.children);
+        if (!KEPT.has(node.name)) {
+            out.push(...children);
+            continue;
+        }
+        const attributes = [];
+        for (const { name, value, namespace } of node.attributes) {
+            // a namespaced attribute (xlink:href, xml:lang) is no attribute the message's HTML keeps
+            if (namespace || !ATTRIBUTES.has(name))
+                continue;
+            if (name === 'href' && !['http:', 'https:', 'mailto:'].includes(scheme(value)))
+                continue;
+            if (name === 'src' && !(node.name === 'img' && scheme(value) === 'data:'))
+                continue;
+            if (name === 'style') {
+                const kept = style(value);
+                if (kept)
+                    attributes.push({ name, value: kept });
+                continue;
+            }
+            attributes.push({ name, value });
+        }
+        if (node.name === 'a')
+            attributes.push({ name: 'target', value: '_blank' }, { name: 'rel', value: 'noreferrer noopener' });
+        out.push({ type: 'element', name: node.name, namespace: node.namespace, attributes, children });
+    }
+    return out;
+}
+/** A received message's HTML as Gmail shows it (ADR 0032 §4): sanitized on the server and shown inline in its body. */
+async function sanitized(source) {
+    return html.serialize(keep(await html.parseFragment(source)));
+}
+/** A plain-text body with its addresses followable, as Gmail links them. */
+const linked = (text) => esc(text).replace(/https?:\/\/[^\s<>"']+/g, (url) => `<a href="${url}" target="_blank" rel="noreferrer">${url}</a>`);
+const when = (iso) => {
+    const d = new Date(String(iso));
+    return Number.isNaN(d.getTime()) ? '' : d.toLocaleString('en-US', { month: 'short', day: 'numeric', year: 'numeric', hour: 'numeric', minute: '2-digit', timeZone: 'UTC' });
+};
+// the inbox is Gmail's, at its own host, however the request reached the twin: a person's browser reaches it there
+// through the World's DNS, so the links it writes carry that host (ADR 0036 §9)
+const MAIL = 'https://mail.google.com';
+function page(title, email, body, status = 200) {
+    return new Response(`<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(title)}</title><style>body{margin:0;font:14px/1.45 Roboto,Arial,sans-serif;background:#f6f8fc;color:#1f1f1f}header{display:flex;justify-content:space-between;align-items:center;padding:12px 20px}header .brand{font-size:22px;color:#444746}header .who{color:#444746}nav{position:absolute;width:220px;padding:8px 12px}nav a{display:block;padding:6px 16px;border-radius:16px;background:#d3e3fd;color:#001d35;font-weight:600;text-decoration:none}main{margin-left:244px;margin-right:16px;background:#fff;border-radius:16px;min-height:70vh;padding:8px 0}.row{display:grid;grid-template-columns:200px 1fr 120px;gap:12px;padding:10px 20px;border-bottom:1px solid #f1f3f4;color:inherit;text-decoration:none}.row.unread{font-weight:700}.row .date{text-align:right;color:#5e5e5e}.msg{padding:12px 24px}.msg h2.hP{font-size:22px;font-weight:400;margin:8px 0 16px}.meta{color:#5e5e5e;margin-bottom:16px}.body{border-top:1px solid #f1f3f4;padding-top:16px;overflow-wrap:anywhere;${BODY}}.body pre{white-space:pre-wrap;font:inherit}.files{margin-top:24px;display:flex;gap:12px;flex-wrap:wrap}.files a{border:1px solid #dadce0;border-radius:8px;padding:10px 14px;color:#1f1f1f;text-decoration:none}.empty{padding:24px}</style></head><body><header><span class="brand">Gmail</span><span class="who">${esc(email)}</span></header><nav><a href="${MAIL}/mail/u/0/" aria-current="page">Inbox</a></nav><main>${body}</main></body></html>`, { status, headers: { 'content-type': 'text/html; charset=utf-8', 'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'; img-src 'self' data:; script-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'" } });
+}
+export async function screen(ctx) {
+    const request = ctx.call.request;
+    if (!['GET', 'HEAD'].includes(request.method))
+        return new Response('Method Not Allowed', { status: 405, headers: { allow: 'GET, HEAD' } });
+    const url = new URL(request.url);
+    const who = signedInAccount(ctx);
+    if (!who) {
+        // to Google's sign-in, which returns the person to the page they asked for
+        const back = `${MAIL}${url.pathname}${url.search}`;
+        return new Response(null, { status: 302, headers: { location: `https://accounts.google.com/ServiceLogin?${new URLSearchParams({ service: 'mail', continue: back })}` } });
+    }
+    const mine = ctx.rowsRaw(MESSAGE).filter((m) => m.mailbox === who && m.deleted !== true)
+        .sort((a, b) => String(b.receivedAt).localeCompare(String(a.receivedAt)) || String(b.id).localeCompare(String(a.id)));
+    const path = url.pathname.replace(/\/+$/, '');
+    const opened = /^\/mail\/u\/0\/inbox\/([^/]+)(?:\/attachments\/(\d+))?$/.exec(path);
+    if (!opened) {
+        if (path !== '/mail' && path !== '/mail/u/0')
+            return page('Gmail', who, '<p class="empty" role="alert">Temporary Error (404)</p>', 404);
+        const rows = mine.map((m) => `<a class="row${m.labelIds?.includes('UNREAD') ? ' unread' : ''}" href="${MAIL}/mail/u/0/inbox/${encodeURIComponent(String(m.id))}"><span class="from">${esc(m.from || m.envelope?.from)}</span><span class="subject">${esc(m.subject || '(no subject)')}</span><span class="date">${esc(when(m.receivedAt))}</span></a>`).join('');
+        return page(`Inbox - ${who} - Gmail`, who, rows || '<p class="empty">Your Primary tab is empty.</p>');
+    }
+    let id = '';
+    try {
+        id = decodeURIComponent(opened[1]);
+    }
+    catch { /* no such message */ }
+    const m = mine.find((x) => x.id === id);
+    if (!m)
+        return page('Gmail', who, '<p class="empty" role="alert">That message could not be found.</p>', 404);
+    const files = m.attachments ?? [];
+    if (opened[2] !== undefined) {
+        const index = Number(opened[2]);
+        const key = m._attachments?.[index];
+        const meta = files[index];
+        const bytes = key === undefined ? undefined : await ctx.blobs.get(key);
+        if (!meta || !bytes)
+            return page('Gmail', who, '<p class="empty" role="alert">That attachment could not be found.</p>', 404);
+        const name = String(meta.filename ?? `attachment-${index}`).replace(/["\r\n\\]/g, '');
+        return new Response(new Uint8Array(bytes), { headers: { 'content-type': String(meta.contentType ?? 'application/octet-stream'), 'content-disposition': `attachment; filename="${name}"` } });
+    }
+    const body = typeof m.html === 'string' && m.html ? await sanitized(m.html) : `<pre>${linked(String(m.text ?? ''))}</pre>`;
+    const list = files.map((f, i) => `<a href="${MAIL}/mail/u/0/inbox/${encodeURIComponent(String(m.id))}/attachments/${i}" download="${esc(f.filename ?? '')}">${esc(f.filename ?? `attachment ${i + 1}`)} <small>Download</small></a>`).join('');
+    return page(`${String(m.subject ?? '(no subject)')} - ${who} - Gmail`, who, `<article class="msg"><h2 class="hP">${esc(m.subject || '(no subject)')}</h2><div class="meta"><strong>${esc(m.from)}</strong> to ${esc((m.to ?? []).join(', ') || who)} · ${esc(when(m.receivedAt))}</div><div class="body a3s">${body}</div>${list ? `<div class="files" aria-label="Attachments">${list}</div>` : ''}</article>`);
+}

package/dist/src/semantics/around.d.ts

@@ -0,0 +1,2 @@
+import { type HandlerContext } from '@volter/world-core';
+export declare function around(ctx: HandlerContext, next: (request?: Request) => Promise<Response>): Promise<Response>;

package/dist/src/semantics/around.js

@@ -0,0 +1,97 @@
+// GMAIL'S RECEIVING SERVER'S FRONT: each command a connection sends, run as RFC 5321 orders it and Gmail's MX answers
+// it. The byte-stream door (../stream.ts) frames a connection's bytes and posts each command (or a message's whole data)
+// here with the session it carries; the answer is the reply lines, the moved session, and what the stream reads next.
+// Every other request is the webmail's (the screens).
+//
+// The server takes mail from any sender, as an MX does, and refuses a recipient it does not hold: an address at another
+// domain (it relays for no one) or a gmail.com address that is no Google account (550 5.1.1). It asks no authentication
+// and has no certificate here, so it advertises neither AUTH nor STARTTLS (ADR 0032 §4).
+import { smtpServer } from '@volter/world-core';
+import { accountOf, BRIDGE, BYE, deliver, GO_AHEAD, GREETING, HOST, MAIL_DOMAIN, MAX_SIZE, NO_ACCOUNT, NO_TLS, NOT_OURS, OK, OK_MAIL, OK_RCPT, SYNTAX, TOO_BIG, UNRECOGNIZED, unsupported, } from "./shared.js";
+const { smtpCleared, smtpCommand, smtpDomain: domainOf, smtpEhlo, smtpFront, smtpMailFrom, smtpOrder, smtpRcptTo } = smtpServer;
+const cmd = (session, ...replies) => ({ replies, session, mode: 'command' });
+/** The machine's word on a command from where the session stands: a refusal's reply, or undefined to go on. */
+const order = (ctx, s, op, to) => smtpOrder(ctx, 'Session', s.stage, op, to);
+/** A transaction's state cleared, the greeting kept (RSET, a new EHLO, the end of DATA). */
+const cleared = (s, stage) => smtpCleared(s, stage, {});
+function command(ctx, s, line) {
+    const { verb, arg } = smtpCommand(line);
+    switch (verb) {
+        default: return cmd(s, UNRECOGNIZED);
+        case 'EHLO':
+        case 'HELO': {
+            if (!arg.trim())
+                return cmd(s, `501 5.5.4 Empty ${verb} argument not allowed, closing connection. - gsmtp`);
+            order(ctx, s, verb, verb.toLowerCase());
+            const next = cleared(s, verb.toLowerCase());
+            if (verb === 'HELO')
+                return cmd(next, `250 ${HOST} at your service`);
+            return { replies: smtpEhlo([`${HOST} at your service`, `SIZE ${MAX_SIZE}`, '8BITMIME', 'ENHANCEDSTATUSCODES', 'PIPELINING', 'SMTPUTF8']), session: next, mode: 'command' };
+        }
+        // source: spec:4.1.1.2 "This command clears the reverse-path buffer, the forward-path buffer, and the mail data buffer"
+        case 'MAIL': {
+            const refused = order(ctx, s, 'MAIL', 'mail');
+            if (refused)
+                return cmd(s, refused);
+            const mail = smtpMailFrom(arg);
+            if ('refused' in mail)
+                return cmd(s, 'parameter' in mail ? unsupported(mail.parameter) : SYNTAX);
+            if (mail.size !== undefined && mail.size > MAX_SIZE)
+                return cmd(s, TOO_BIG);
+            return cmd({ ...s, stage: 'mail', from: mail.from.toLowerCase(), rcpt: [], ...(mail.smtputf8 ? { smtputf8: true } : {}) }, OK_MAIL);
+        }
+        // source: spec:4.1.1.3 "This command is used to identify an individual recipient of the mail data; multiple recipients are specified by multiple uses of this command."
+        case 'RCPT': {
+            const refused = order(ctx, s, 'RCPT', 'rcpt');
+            if (refused)
+                return cmd(s, refused);
+            const rcpt = smtpRcptTo(arg);
+            if ('refused' in rcpt)
+                return cmd(s, 'parameter' in rcpt ? unsupported(rcpt.parameter) : SYNTAX);
+            const to = rcpt.to.toLowerCase();
+            if (domainOf(to) !== MAIL_DOMAIN)
+                return cmd(s, NOT_OURS);
+            if (!accountOf(ctx, to))
+                return cmd(s, NO_ACCOUNT);
+            return cmd({ ...s, stage: 'rcpt', rcpt: [...s.rcpt, to] }, OK_RCPT);
+        }
+        // source: spec:4.1.1.4 "The receiver normally sends a 354 response to DATA"
+        case 'DATA': {
+            const refused = order(ctx, s, 'DATA', 'data');
+            if (refused)
+                return cmd(s, refused);
+            return { replies: [GO_AHEAD], session: { ...s, stage: 'data' }, mode: 'data' };
+        }
+        // source: spec:4.1.1.5 "This command specifies that the current mail transaction will be aborted."
+        case 'RSET': {
+            const back = s.greeted ?? 'fresh';
+            if (s.stage === 'mail' || s.stage === 'rcpt')
+                order(ctx, s, 'RSET', back);
+            return cmd(cleared(s, s.stage === 'mail' || s.stage === 'rcpt' ? back : s.stage), OK);
+        }
+        // source: spec:4.1.1.9 "This command does not affect any parameters or previously entered commands."
+        case 'NOOP': return cmd(s, OK);
+        // source: spec:4.1.1.10 "The QUIT command may be issued at any time."
+        case 'QUIT':
+            order(ctx, s, 'QUIT', 'closed');
+            return { replies: [BYE], session: { ...s, stage: 'closed' }, mode: 'command', close: true };
+        case 'STARTTLS': return cmd(s, NO_TLS);
+    }
+}
+/** The end of a message's data: its size held against the limit, the message kept in each recipient's mailbox. */
+async function endOfData(ctx, s, data) {
+    const back = s.greeted ?? 'ehlo';
+    order(ctx, s, 'DATA', back);
+    const next = cleared(s, back);
+    if (data.length > MAX_SIZE)
+        return cmd(next, TOO_BIG);
+    await deliver(ctx, { from: s.from ?? '', to: s.rcpt, data, smtputf8: s.smtputf8 === true });
+    return cmd(next, OK);
+}
+export async function around(ctx, next) {
+    return smtpFront(ctx, next, BRIDGE, {
+        open: () => ({ replies: [GREETING], session: BRIDGE.fresh(), mode: 'command' }),
+        command: (s, line) => command(ctx, s, line),
+        data: (s, data) => endOfData(ctx, s, data),
+    });
+}

package/dist/src/semantics/index.d.ts

@@ -0,0 +1,2 @@
+import type { Handler } from '@volter/world-core';
+export declare const gmailSemantics: Record<string, Handler>;

package/dist/src/semantics/index.js

@@ -0,0 +1 @@
+export const gmailSemantics = {};

package/dist/src/semantics/shared.d.ts

@@ -0,0 +1,52 @@
+import { type HandlerContext, type smtpServer } from '@volter/world-core';
+export type Row = Record<string, unknown>;
+export declare const MESSAGE = "message";
+/** The domain whose accounts this server receives mail for: the descriptor's host rule names it, so the kernel's
+ *  ctx.mail hands its mail here. */
+export declare const MAIL_DOMAIN = "gmail.com";
+/** A session as its connection carries it between commands. */
+export type Session = {
+    stage: string;
+    from?: string;
+    rcpt: string[];
+    smtputf8?: boolean;
+    greeted?: 'helo' | 'ehlo';
+};
+/** What the front answers the stream: the reply lines, the session, and whether the stream reads a message next. */
+export type WireAnswer = smtpServer.SmtpAnswer<Session>;
+export declare const HOST = "mx.google.com";
+export declare const GREETING = "220 mx.google.com ESMTP - gsmtp";
+export declare const MAX_SIZE = 157286400;
+export declare const OK_MAIL = "250 2.1.0 OK - gsmtp";
+export declare const OK_RCPT = "250 2.1.5 OK - gsmtp";
+export declare const OK = "250 2.0.0 OK - gsmtp";
+export declare const GO_AHEAD = "354 Go ahead - gsmtp";
+export declare const BYE = "221 2.0.0 closing connection - gsmtp";
+export declare const UNRECOGNIZED = "502 5.5.1 Unrecognized command. - gsmtp";
+export declare const NO_ACCOUNT = "550 5.1.1 The email account that you tried to reach does not exist. - gsmtp";
+export declare const NOT_OURS = "550 5.7.1 Relaying denied. - gsmtp";
+export declare const TOO_BIG = "552 5.3.4 Your message exceeded Google's message size limits. - gsmtp";
+export declare const NO_TLS = "454 4.7.0 TLS not available - gsmtp";
+export declare const unsupported: (arg: string) => string;
+export declare const SYNTAX = "501 5.5.2 Syntax error. - gsmtp";
+/** The bridge between a connection and the server's front (world-core's SMTP server machine): the header the stream
+ *  signs its requests with, a key made once per process so a request from outside it (the webmail's port) cannot speak
+ *  for a connection, a fresh session, and the server's local-error reply. */
+export declare const BRIDGE: smtpServer.SmtpBridge<Session>;
+type Reader = Pick<HandlerContext, 'ownerRow'>;
+/** The mailbox an address names: the address of the Google account whose sign-up recorded its person (googleoauth's
+ *  `_person`, keyed `person:<email>`, with the account's `sub`, whose `account` stands); a `+tag` reaches the same
+ *  mailbox, as Gmail delivers it. Where the
+ *  documentation stops: Gmail also ignores dots in the local part; the twin matches the address as signed up. */
+export declare function accountOf(ctx: Reader, address: string): string | undefined;
+/** A message accepted: kept once in each recipient's mailbox, with its envelope, its bytes and what they parse to. */
+export declare function deliver(ctx: HandlerContext, e: {
+    from: string;
+    to: string[];
+    data: string;
+    smtputf8: boolean;
+}): Promise<void>;
+/** The mailbox of the Google account a request's browser is signed in to: its `SID` cookie names a session googleoauth
+ *  recorded (`_web_session`, keyed `websession:<token>`), whose person is the account's. */
+export declare function signedInAccount(ctx: HandlerContext): string | undefined;
+export {};