@volter/twin-gmail 0.0.0-stage → 1.0.0

package/dist/src/semantics/shared.js

@@ -0,0 +1,97 @@
+// What Gmail's receiving server, its byte-stream door and its webmail share: the server's replies, a session's shape, the
+// key the stream proves itself with, the mailboxes (Google's accounts, read from googleoauth: architecture A3) and the
+// delivery of a message into them.
+import { browserSessionToken, privateTransportKey } from '@volter/world-core';
+import { parse } from "../engine/mail.js";
+export 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 const MAIL_DOMAIN = 'gmail.com';
+// Gmail's receiving server's replies. Google publishes its refusals in "Gmail SMTP errors and codes", each ending
+// `gsmtp`; where the documentation stops: the page lists no successes and no refusal of a recipient at a domain Google
+// does not receive for, so those replies' words are unverified (each is said so below), and the queue ids Gmail adds
+// are left out.
+// source: https://knowledge.workspace.google.com/admin/support/troubleshooting/gmail-smtp-errors-and-codes "gsmtp (Google SMTP) is added to all errors"
+export const HOST = 'mx.google.com';
+export const GREETING = `220 ${HOST} ESMTP - gsmtp`;
+// the largest message the server takes, as its EHLO advertises SIZE (recalled, as above)
+export const MAX_SIZE = 157_286_400;
+export const OK_MAIL = '250 2.1.0 OK - gsmtp';
+export const OK_RCPT = '250 2.1.5 OK - gsmtp';
+export const OK = '250 2.0.0 OK - gsmtp';
+export const GO_AHEAD = '354 Go ahead - gsmtp';
+export const BYE = '221 2.0.0 closing connection - gsmtp';
+export const UNRECOGNIZED = '502 5.5.1 Unrecognized command. - gsmtp';
+// an address at gmail.com that is no account
+// source: https://knowledge.workspace.google.com/admin/support/troubleshooting/gmail-smtp-errors-and-codes "The email account that you tried to reach does not exist."
+export const NO_ACCOUNT = '550 5.1.1 The email account that you tried to reach does not exist. - gsmtp';
+// an address at a domain this server does not receive for: an MX relays for no one. Unverified: Google's error page has
+// no row for it, no published transcript of mx.google.com's reply to it was found, and a session to its MX from a
+// residential connection could not be made (port 25 closed); no wording is claimed for it, the words below only stand in
+export const NOT_OURS = '550 5.7.1 Relaying denied. - gsmtp';
+// source: https://knowledge.workspace.google.com/admin/support/troubleshooting/gmail-smtp-errors-and-codes "Your message exceeded Google's message size limits."
+export const TOO_BIG = '552 5.3.4 Your message exceeded Google\'s message size limits. - gsmtp';
+// no certificate on the World's side port (ADR 0032 §4: IMAP and submission, which need TLS, are later cards)
+export const NO_TLS = '454 4.7.0 TLS not available - gsmtp';
+// source: spec:4.1.1.11 "command, it will return code 555."
+export const unsupported = (arg) => `555 5.5.4 Unsupported option: ${arg} - gsmtp`;
+export const SYNTAX = '501 5.5.2 Syntax error. - gsmtp';
+// The host cannot persist a message: a temporary failure, as RFC 5321 names it.
+// source: spec:4.2.3 "451 Requested action aborted: local error in processing"
+const queueFailure = (session) => ({ replies: ['451 4.3.0 Local error in processing - gsmtp'], session, mode: 'command', close: true });
+/** 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 const BRIDGE = { header: 'x-volter-gmail-wire', key: () => privateTransportKey('gmail'), fresh: () => ({ stage: 'fresh', rcpt: [] }), failure: queueFailure };
+/** 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 function accountOf(ctx, address) {
+    const lower = address.toLowerCase();
+    const plain = lower.replace(/\+[^@]*@/, '@');
+    for (const email of lower === plain ? [lower] : [lower, plain]) {
+        const person = ctx.ownerRow('googleoauth', '_person', `person:${email}`);
+        const sub = typeof person?.sub === 'string' && person.deleted !== true ? person.sub : undefined;
+        const account = sub ? ctx.ownerRow('googleoauth', 'account', sub) : undefined;
+        if (sub && account && account.deleted !== true)
+            return email;
+    }
+    return undefined;
+}
+/** A message accepted: kept once in each recipient's mailbox, with its envelope, its bytes and what they parse to. */
+export async function deliver(ctx, e) {
+    const p = parse(e.data);
+    for (const rcpt of e.to) {
+        const mailbox = accountOf(ctx, rcpt);
+        if (!mailbox)
+            continue;
+        const id = ctx.mint(MESSAGE);
+        const rawKey = `${id}/raw`;
+        await ctx.blobs.put(rawKey, Uint8Array.from(e.data, (c) => c.charCodeAt(0) & 0xff));
+        const attachmentKeys = [];
+        for (let i = 0; i < p.attachments.length; i++) {
+            const key = `${id}/attachments/${i}`;
+            await ctx.blobs.put(key, Uint8Array.from(atob(p.attachments[i].base64), (c) => c.charCodeAt(0)));
+            attachmentKeys.push(key);
+        }
+        await ctx.write(MESSAGE, id, {
+            id, mailbox, envelope: { from: e.from, to: rcpt, smtputf8: e.smtputf8 }, size: e.data.length, receivedAt: ctx.occurredAt,
+            headers: p.headers, subject: p.subject, from: p.from, to: p.to, cc: p.cc, text: p.text, html: p.html,
+            attachments: p.attachments.map(({ base64: _b, ...a }) => a), labelIds: ['INBOX', 'UNREAD'], _raw: rawKey, _attachments: attachmentKeys,
+        }, 'message.deliver');
+    }
+}
+/** The SID cookie Google's sign-in sets on .google.com (googleoauth's contract). */
+const SESSION_COOKIE = 'SID';
+/** 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 function signedInAccount(ctx) {
+    const token = browserSessionToken(ctx.call.request, SESSION_COOKIE);
+    if (!token)
+        return undefined;
+    const session = ctx.ownerRow('googleoauth', '_web_session', `websession:${token}`);
+    if (!session || session.token !== token || typeof session.email !== 'string')
+        return undefined;
+    return accountOf(ctx, session.email);
+}

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

@@ -0,0 +1,4 @@
+import type { StateField } from '@volter/world-core';
+export declare const states: Record<string, {
+    state: Record<string, StateField>;
+}>;

package/dist/src/semantics/states.js

@@ -0,0 +1,33 @@
+const RFC5321 = (section, quote) => `spec:${section} "${quote}"`;
+// Where the documentation stops: Gmail's words for a command out of order, recalled from its server's replies
+const badSequence = (message) => ({ status: 503, code: '5.5.1', message });
+const ORDER = 'Once started, a mail transaction consists of a transaction beginning command, one or more RCPT commands, and a DATA command, in that order.';
+// fresh (nothing yet), helo or ehlo (greeted), mail (a sender), rcpt (recipients), data (the message's lines), closed
+const stage = [
+    { operation: 'EHLO', from: '*', to: 'ehlo', source: RFC5321('4.1.4', 'If it is issued after the session begins and the EHLO command is acceptable to the SMTP server, the SMTP server MUST clear all buffers and reset the state exactly as if a RSET command had been issued.') },
+    { operation: 'HELO', from: '*', to: 'helo', source: RFC5321('4.1.1.1', 'These commands are used to identify the SMTP client to the SMTP server.') },
+    {
+        operation: 'MAIL', from: ['helo', 'ehlo'], to: 'mail',
+        refusals: { fresh: badSequence('EHLO/HELO first. - gsmtp'), mail: badSequence('Nested MAIL command. - gsmtp'), rcpt: badSequence('Nested MAIL command. - gsmtp') },
+        source: RFC5321('4.1.4', 'MAIL (or SEND, SOML, or SAML) MUST NOT be sent if a mail transaction is already open'),
+    },
+    {
+        operation: 'RCPT', from: ['mail', 'rcpt'], to: 'rcpt',
+        refusals: { fresh: badSequence('MAIL first. - gsmtp'), helo: badSequence('MAIL first. - gsmtp'), ehlo: badSequence('MAIL first. - gsmtp') },
+        source: RFC5321('4.1.4', ORDER),
+    },
+    {
+        operation: 'DATA', from: ['rcpt'], to: 'data',
+        refusals: { fresh: badSequence('MAIL first. - gsmtp'), helo: badSequence('MAIL first. - gsmtp'), ehlo: badSequence('MAIL first. - gsmtp'), mail: badSequence('RCPT first. - gsmtp') },
+        source: RFC5321('4.1.4', ORDER),
+    },
+    // the end-of-data dot closes the transaction, back to the greeting the session had
+    { operation: 'DATA', from: ['data'], to: 'ehlo', source: RFC5321('4.1.4', 'or if the previous one successfully concluded with a successful DATA command') },
+    { operation: 'DATA', from: ['data'], to: 'helo', source: RFC5321('4.1.4', 'or if the previous one successfully concluded with a successful DATA command') },
+    { operation: 'RSET', from: ['mail', 'rcpt'], to: 'ehlo', source: RFC5321('4.1.1.5', 'This command specifies that the current mail transaction will be aborted.') },
+    { operation: 'RSET', from: ['mail', 'rcpt'], to: 'helo', source: RFC5321('4.1.1.5', 'This command specifies that the current mail transaction will be aborted.') },
+    { operation: 'QUIT', from: '*', to: 'closed', source: RFC5321('4.1.1.10', 'The QUIT command may be issued at any time.') },
+];
+export const states = {
+    Session: { state: { stage: { initial: 'fresh', transitions: stage } } },
+};

package/dist/src/server.d.ts

@@ -0,0 +1,9 @@
+import { type PackFetchOptions } from '@volter/world-core';
+export declare function createGmailTwinServer(options?: PackFetchOptions & {
+    port?: number;
+    smtpPort?: number;
+}): Promise<{
+    port: number;
+    smtpPort: number;
+    stop: () => Promise<void>;
+}>;

package/dist/src/server.js

@@ -0,0 +1,23 @@
+// FETCH-FIRST (runtime contract R12b) with a wire of the pack's own: the webmail on the main port (the pack's fetch) and
+// Gmail's receiving SMTP server on its side port (`smtpPort`, the manifest's sidePorts: the kernel's `serveStream`
+// carrying the byte-stream door's connections), where the World's senders hand gmail.com's mail (ctx.mail). A listener
+// that fails to open releases the one already open; stop closes both and settles once both have.
+import { serveHttp, serveStream } from '@volter/world-core';
+import { createGmailFetch } from "./fetch.js";
+import { createGmailTwinStream } from "./stream.js";
+export async function createGmailTwinServer(options = {}) {
+    const server = await serveHttp({ port: options.port ?? 0, idleTimeout: 60, fetch: createGmailFetch(options) });
+    let smtp;
+    try {
+        smtp = await serveStream({ port: options.smtpPort ?? 0, stream: createGmailTwinStream(options) });
+    }
+    catch (error) {
+        await server.stop(true);
+        throw error;
+    }
+    return {
+        port: server.port ?? options.port ?? 0,
+        smtpPort: smtp.port,
+        stop: async () => { await Promise.all([smtp.stop(), server.stop(true)]); },
+    };
+}

package/dist/src/stream.d.ts

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

package/dist/src/stream.js

@@ -0,0 +1,10 @@
+// GMAIL'S RECEIVING SERVER'S BYTE-STREAM DOOR (world-core's TwinStream): a connection's bytes framed and carried to the
+// server's front (./semantics/around.ts) by the kernel's SMTP server machine (`smtpServer.smtpStream`, RFC 5321
+// §4.1.1.4 and §4.5.2). The host carries the bytes: a local listener's socket on the pack's SMTP side port (./server.ts),
+// or the World's sender in process (a journey walk's companion).
+import { smtpServer } from '@volter/world-core';
+import { createGmailFetch } from "./fetch.js";
+import { BRIDGE } from "./semantics/shared.js";
+export function createGmailTwinStream(options = {}) {
+    return smtpServer.smtpStream(createGmailFetch(options), BRIDGE);
+}

package/generated/pack-facts.json

@@ -0,0 +1,47 @@
+{
+  "//": "GENERATED by twin-standard facts from the pack descriptor; no prior-artifact entries are retained.",
+  "packs": {
+    "gmail": {
+      "adoption": {
+        "sdks": [],
+        "envStems": []
+      },
+      "hosts": [
+        {
+          "host": "mail.google.com"
+        },
+        {
+          "host": "gmail.com"
+        }
+      ],
+      "archetype": "crud",
+      "protocol": {
+        "declared": "3",
+        "major": 3,
+        "standing": "current"
+      },
+      "transport": "rest",
+      "resources": [
+        "message"
+      ],
+      "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",
+      "requires": [
+        "googleoauth"
+      ],
+      "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"
+        }
+      ],
+      "seed": {
+        "signUp": "https://accounts.google.com/signup"
+      },
+      "serveExport": "createGmailTwinServer"
+    }
+  },
+  "undeclared": []
+}