@volter/twin-gmail 0.0.0-stage → 1.0.1

package/journeys/decisions.json

@@ -0,0 +1,77 @@
+{
+  "about": "Gmail's receiving server's command decisions: the World's senders (ctx.mail) and RFC 5321 Appendix D; command semantics are the byte-stream front, not HTTP CRUD.",
+  "decisions": [
+    {
+      "operation": "CONNECTION ESTABLISHMENT",
+      "demand": "ADR 0032 \u00a74: the World's senders hand gmail.com's mail to this server (world-core smtp.ts sendMail); RFC 5321 Appendix D",
+      "mechanism": "handler",
+      "why": "The connection front (semantics/around.ts) answers the open with mx.google.com's 220 greeting; the World's senders (ctx.mail from the smtp relay and resend) wait for it before EHLO."
+    },
+    {
+      "operation": "EHLO",
+      "demand": "ADR 0032 \u00a74: the World's senders hand gmail.com's mail to this server (world-core smtp.ts sendMail); RFC 5321 Appendix D",
+      "mechanism": "handler",
+      "why": "The front answers EHLO with the server's keywords (SIZE, 8BITMIME, ENHANCEDSTATUSCODES, PIPELINING, SMTPUTF8; no AUTH or STARTTLS: an MX asks none, and the side port has no certificate); ctx.mail greets with EHLO."
+    },
+    {
+      "operation": "HELO",
+      "demand": "ADR 0032 \u00a74: the World's senders hand gmail.com's mail to this server (world-core smtp.ts sendMail); RFC 5321 Appendix D",
+      "mechanism": "handler",
+      "why": "The front answers HELO as RFC 5321 requires of a server; ctx.mail sends EHLO, an older sender HELO."
+    },
+    {
+      "operation": "MAIL",
+      "demand": "ADR 0032 \u00a74: the World's senders hand gmail.com's mail to this server (world-core smtp.ts sendMail); RFC 5321 Appendix D",
+      "mechanism": "handler",
+      "why": "The front takes the sender (any, as an MX does) and its SIZE, BODY and SMTPUTF8 parameters, refusing a declared SIZE above the 157,286,400 bytes its EHLO advertises with 552 5.3.4, as Google's error page words it; ctx.mail sends MAIL FROM with BODY=8BITMIME for 8-bit messages.",
+      "sourceRules": [
+        {
+          "source": "https://knowledge.workspace.google.com/admin/support/troubleshooting/gmail-smtp-errors-and-codes",
+          "means": "552 5.3.4 \"Your message exceeded Google's message size limits.\""
+        }
+      ]
+    },
+    {
+      "operation": "RCPT",
+      "demand": "ADR 0032 \u00a74: the World's senders hand gmail.com's mail to this server (world-core smtp.ts sendMail); RFC 5321 Appendix D",
+      "mechanism": "handler",
+      "why": "The front accepts a gmail.com address that is a Google account (googleoauth's _person and account, read through ownerReads) and refuses any other at RCPT: 550 5.1.1 for no account, as Google's error page words it; an address at a domain Google does not receive for is refused with 550, unverified, no wording claimed (the page has no row for it, no published transcript of mx.google.com's reply was found, and a session to gmail-smtp-in.l.google.com:25 from themachine on 2026-11-11 timed out after 10 s); ctx.mail turns each reply into the sender's delivered or bounced.",
+      "sourceRules": [
+        {
+          "source": "https://knowledge.workspace.google.com/admin/support/troubleshooting/gmail-smtp-errors-and-codes",
+          "means": "550 5.1.1 \"The email account that you tried to reach does not exist.\", and gsmtp added to all errors"
+        }
+      ]
+    },
+    {
+      "operation": "DATA",
+      "demand": "ADR 0032 \u00a74: the World's senders hand gmail.com's mail to this server (world-core smtp.ts sendMail); RFC 5321 Appendix D",
+      "mechanism": "handler",
+      "why": "The front takes the message and keeps it in each accepted recipient's mailbox (semantics/shared.ts deliver), which the webmail (screens/mail.ts) lists."
+    },
+    {
+      "operation": "RSET",
+      "demand": "ADR 0032 \u00a74: the World's senders hand gmail.com's mail to this server (world-core smtp.ts sendMail); RFC 5321 Appendix D",
+      "mechanism": "handler",
+      "why": "The front clears the transaction as RFC 5321 says."
+    },
+    {
+      "operation": "VRFY",
+      "demand": "RFC 5321 Appendix D",
+      "mechanism": "handler",
+      "why": "The front answers 502 5.5.1, as Gmail's server answers a command it does not take: it verifies no address."
+    },
+    {
+      "operation": "NOOP",
+      "demand": "ADR 0032 \u00a74: the World's senders hand gmail.com's mail to this server (world-core smtp.ts sendMail); RFC 5321 Appendix D",
+      "mechanism": "handler",
+      "why": "The front answers 250 as RFC 5321 says."
+    },
+    {
+      "operation": "QUIT",
+      "demand": "ADR 0032 \u00a74: the World's senders hand gmail.com's mail to this server (world-core smtp.ts sendMail); RFC 5321 Appendix D",
+      "mechanism": "handler",
+      "why": "The front closes the session with 221; ctx.mail ends every transfer with QUIT."
+    }
+  ]
+}

package/journeys/demand.json

@@ -0,0 +1,43 @@
+{
+  "measured": "2026-11-07, from ADR 0032 (twin-world docs/adr/0032-mail-is-delivered-to-the-recipients-mailbox-provider.md) and browser-substrate df8efa7e's walks, which read the mail Rallly, Dub, Cal, Twenty and LibreChat send.",
+  "applications": [
+    {
+      "name": "The World's senders",
+      "repo": "volter-ai/twin-world",
+      "commit": "f242abae30b2",
+      "client": "world-core ctx.mail (smtp.ts sendMail): the smtp relay after a client's DATA, resend after an API send",
+      "backend": [
+        {
+          "call": "connect: the 220 greeting",
+          "operation": "CONNECTION ESTABLISHMENT",
+          "evidence": "packages/world-core/src/smtp.ts transfer"
+        },
+        {
+          "call": "EHLO <sender domain>",
+          "operation": "EHLO",
+          "evidence": "packages/world-core/src/smtp.ts transfer"
+        },
+        {
+          "call": "MAIL FROM:<sender>, BODY=8BITMIME for 8-bit bytes",
+          "operation": "MAIL",
+          "evidence": "packages/world-core/src/smtp.ts transfer"
+        },
+        {
+          "call": "RCPT TO:<recipient>, one per gmail.com recipient",
+          "operation": "RCPT",
+          "evidence": "packages/world-core/src/smtp.ts transfer"
+        },
+        {
+          "call": "DATA, then the sender's message bytes and the end-of-data dot",
+          "operation": "DATA",
+          "evidence": "packages/world-core/src/smtp.ts transfer"
+        },
+        {
+          "call": "QUIT",
+          "operation": "QUIT",
+          "evidence": "packages/world-core/src/smtp.ts transfer"
+        }
+      ]
+    }
+  ]
+}

package/journeys/first-use.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": 1,
+  "source": "https://www.npmjs.com/package/nodemailer/v/10.0.1",
+  "about": "Gmail is the recipient's mailbox, not a service an app integrates: an app reaches it through its sending provider. Maya Okafor makes her Google account at Google's sign-up (googleoauth, which Gmail requires: its accounts are Gmail's mailboxes); Harbourline's Rallly, through the unchanged nodemailer at Rallly's pin (^10.0.1, packages/emails/package.json at 3e63239dbdec), sends a finalized poll's notice through Harbourline's relay (the smtp twin the entry uses, named in twins: a Gmail customer may send this way and need not; the SMTP_HOST, SMTP_PORT and SMTP_SECURE the World injects, no authentication at boot) to the address Maya gave it, maya.okafor+rallly@gmail.com, asserting it accepted and none rejected. The relay hands it to Gmail (twin-world ADR 0032), which keeps it in the account the address tags. The MX host reached directly from an app (gmail-smtp-in.l.google.com) is not this entry: no application integrates it.",
+  "files": {
+    "package.json": "{\n  \"name\": \"gmail-rallly-recipient\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@volter/twin-smtp\": \"1.0.1\",\n    \"nodemailer\": \"10.0.1\"\n  }\n}\n",
+    ".env.example": "SMTP_HOST=\nSMTP_PORT=\nSMTP_SECURE=false\n",
+    "deliver.mjs": "import assert from 'node:assert/strict';\nimport { randomBytes } from 'node:crypto';\nimport { writeFileSync } from 'node:fs';\nimport nodemailer from 'nodemailer';\nif (!process.env.VOLTER_WORLD) throw new Error('Run this app through its World.');\n// Maya Okafor makes her Google account at Google's sign-up, as a person does (accounts.google.com/signup); her password\n// is her own, made here and kept in the app's folder for her later sign-in, never a literal\nconst email = 'maya.okafor@gmail.com', tagged = 'maya.okafor+rallly@gmail.com';\nconst password = randomBytes(18).toString('base64url');\nwriteFileSync('.maya-password', password, { mode: 0o600 });\nconst signup = await fetch('https://accounts.google.com/signup', {\n  method: 'POST', redirect: 'manual', headers: { 'content-type': 'application/x-www-form-urlencoded' },\n  body: new URLSearchParams({ email, password, given_name: 'Maya', family_name: 'Okafor', continue: 'https://mail.google.com/mail/u/0/' }),\n});\nassert.ok(/(?:^|[,;]\\s*)SID=[^;]+/.test(signup.headers.get('set-cookie') ?? ''), `sign-up left Maya signed in to Google (status ${signup.status})`);\n// Harbourline's Rallly sends through its own relay (the World's SMTP_HOST and SMTP_PORT) to the address Maya gave it,\n// her tagged one: the relay hands it to Gmail, which keeps it in the account the address tags\nconst transport = nodemailer.createTransport({ host: process.env.SMTP_HOST, port: Number(process.env.SMTP_PORT), secure: process.env.SMTP_SECURE === 'true' });\nconst sent = await transport.sendMail({\n  from: 'Rallly <polls@harbourline.be>', to: tagged, subject: 'Your poll has been finalized',\n  text: 'The workshop is on Thursday 22 January 2026 at 10:00. Add it to your calendar.',\n});\nassert.deepEqual(sent.accepted, [tagged]);\nassert.deepEqual(sent.rejected, []);\ntransport.close();\nconsole.log(JSON.stringify({ sent: sent.messageId }));\n",
+    "read-inbox.mjs": "import assert from 'node:assert/strict';\nimport { readFileSync } from 'node:fs';\nif (!process.env.VOLTER_WORLD) throw new Error('Run this app through its World.');\n// Maya, later, in a browser that holds no Google session: she signs in (accounts.google.com/ServiceLogin) with the\n// webmail as the page to return to, reads her inbox and opens the message Rallly sent her tagged address\nconst email = 'maya.okafor@gmail.com', tagged = 'maya.okafor+rallly@gmail.com';\nconst signin = await fetch('https://accounts.google.com/ServiceLogin', {\n  method: 'POST', redirect: 'manual', headers: { 'content-type': 'application/x-www-form-urlencoded' },\n  body: new URLSearchParams({ email, password: readFileSync('.maya-password', 'utf8'), continue: 'https://mail.google.com/mail/u/0/' }),\n});\nassert.equal(signin.status, 302, 'Google signs Maya in and returns her to her inbox');\nassert.equal(signin.headers.get('location'), 'https://mail.google.com/mail/u/0/');\nconst sid = /(?:^|[,;]\\s*)SID=([^;]+)/.exec(signin.headers.get('set-cookie') ?? '')?.[1];\nassert.ok(sid, 'the sign-in sets her Google session');\nconst cookie = `SID=${sid}`;\nconst inbox = await fetch('https://mail.google.com/mail/u/0/', { headers: { cookie } });\nassert.equal(inbox.status, 200);\nconst listed = await inbox.text();\nassert.match(listed, /Your poll has been finalized/, 'the inbox lists Rallly\\'s message');\nconst id = /href=\"https:\\/\\/mail\\.google\\.com\\/mail\\/u\\/0\\/inbox\\/([^\"]+)\"/.exec(listed)?.[1];\nassert.ok(id, 'the message opens from the inbox');\nconst opened = await fetch(`https://mail.google.com/mail/u/0/inbox/${id}`, { headers: { cookie } });\nassert.equal(opened.status, 200);\nconst page = await opened.text();\nassert.ok(page.includes(tagged), 'the message is the one sent to her tagged address, kept in her own mailbox');\nassert.match(page, /Thursday 22 January 2026 at 10:00/);\nconsole.log(JSON.stringify({ readback: decodeURIComponent(id) }));\n"
+  },
+  "twins": [
+    "smtp"
+  ],
+  "run": [
+    "node",
+    "deliver.mjs"
+  ],
+  "retention": {
+    "readback": [
+      "node",
+      "read-inbox.mjs"
+    ]
+  }
+}

package/journeys/vendor-examples.json

@@ -0,0 +1,7 @@
+{
+  "vendor": "gmail",
+  "author": "Claude (VO-3832)",
+  "host": "mail.google.com",
+  "about": "Google publishes no SMTP examples for Gmail's MX; the twin's behaviour is cited to its decision rows.",
+  "steps": []
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@volter/twin-gmail",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Gmail twin: gmail.com's receiving SMTP server for the World's Google accounts, and the mail.google.com webmail where the person reads their mail.",
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-gmail": "dist/src/cli.js"
+  },
+  "files": [
+    "src",
+    "dist",
+    "generated",
+    "spec",
+    "README.md",
+    "!**/*.test.ts",
+    "journeys/customer-life.json",
+    "journeys/vendor-examples.json",
+    "journeys/decisions.json",
+    "journeys/demand.json",
+    "journeys/first-use.json"
+  ],
+  "peerDependencies": {
+    "@volter/twin-googleoauth": "^1.1.2",
+    "@volter/world-core": "^3.0.185"
+  },
+  "engines": {
+    "node": ">=22.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin-packs-p3.git",
+    "directory": "gmail"
+  },
+  "homepage": "https://github.com/volter-ai/twin-packs-p3/tree/main/gmail#readme",
+  "packageManager": "pnpm@12.15.0",
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "12.15.0",
+      "onFail": "error"
+    }
+  },
+  "volterRelease": {
+    "commit": "200f949d661297e45c9ff51b6ae8398bc4acc313"
+  }
+}

package/spec/SOURCE.md

@@ -0,0 +1,13 @@
+# Gmail sources
+
+Read 2026-11-07.
+
+- `rfc5321.txt`: RFC 5321, Simple Mail Transfer Protocol, October 2008, immutable RFC edition, upstream
+  https://www.rfc-editor.org/rfc/rfc5321.txt (the same bytes as the smtp pack's). SHA256:
+  `7d560eddff1b213c17d4e1e5f95005728b2f05bc2b3947f0fcc91717c6707634`. It is the command-reply table of
+  Gmail's receiving server (`gmail-smtp-in.l.google.com`, the MX `gmail.com` answers), the surface this pack serves on its
+  SMTP side port. Gmail's API and IMAP are not served (ADR 0032, later cards).
+- `sources.json` records cited reference pages checked by check-sources; the pack cites the RFC alone.
+
+Gmail's replies on that server (`mx.google.com`, `- gsmtp`, `550 5.1.1 The email account that you tried to reach does
+not exist`) are recalled from Gmail's bounces, not read from a published page: the pack says so where it uses them.