knowless 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -15,9 +15,77 @@ Versioning is [SemVer](https://semver.org/).
 
 ## [Unreleased]
 
-**v0.2.2 is feature-complete.** v1.0.0 is the planned next release —
+**v0.2.3 is feature-complete.** v1.0.0 is the planned next release —
 walk-away promotion, no API changes.
 
+## [0.2.3] — 2026-04-29
+
+**Last cosmetic gap before walk-away: From: header display name
+(AF-27).** addypin's recipients saw `From: noreply@addypin.com`
+instead of `From: addypin <noreply@addypin.com>` — most clients
+render the local-part as the sender name in inbox previews, so the
+brand "addypin" was hidden behind "noreply." The library was
+conflating the bare RFC 5321 envelope sender (MAIL FROM, no display
+name allowed) with the RFC 5322 From: header (display name allowed),
+preventing adopters from working around without forking the mailer.
+
+Also: the `bodyOverride` JSDoc (AF-26) gets an extra paragraph
+calling out typographic-punctuation traps after addypin hit the
+em-dash on a live send. Pure documentation, no API change.
+
+### Added
+
+- **`fromName` factory option (AF-27).** Optional. When set, the
+  `From:` header is rendered as `${fromName} <${from}>`; envelope
+  sender stays bare. Validated at factory startup via the new
+  `validateFromName()` helper:
+  - ≤ 60 chars
+  - ASCII only (excludes em/en dashes, smart quotes, ellipses,
+    middle dots — same trap surface as `bodyOverride`)
+  - No CR / LF (header-injection defense, matches existing
+    composeRaw invariant)
+  - No `<` / `>` / `"` (would break `name <addr>` quoting)
+
+  ```js
+  knowless({
+    secret, baseUrl,
+    from: 'noreply@addypin.com',
+    fromName: 'addypin',  // recipient sees: From: addypin <noreply@addypin.com>
+  });
+  ```
+
+  Adopters who don't pass `fromName` get the existing behavior (bare
+  address in From:). No call-site changes required.
+
+- **`validateFromName(name)` re-export.** Pure validator alongside
+  the other `validate*` helpers, for ahead-of-time tests.
+
+### Changed
+
+- **`composeRaw` accepts `fromName` arg.** Internal mailer-interface
+  change: composeRaw now takes an optional `fromName` parameter
+  threaded through from `createMailer`. Adopters with a custom
+  `mailer` injection (rare) should plumb `fromName` accordingly if
+  they want the display-name behavior; otherwise the field is
+  ignored and bare-address behavior is preserved.
+
+### Documentation
+
+- **`bodyOverride` JSDoc (AF-26)** — added a typographic-punctuation
+  paragraph listing the four common traps (em/en dashes, smart
+  quotes, ellipses, middle dots) and their ASCII alternatives.
+  Adopters writing email copy reach for these out of habit; the
+  validator error message was clear, but a heads-up before the first
+  live send saves a debugging cycle. Same paragraph applies to the
+  `fromName` validator docstring (AF-27).
+
+### Internal
+
+- 12 new tests in `test/integration/from-name.test.js` covering
+  the happy path (real + sham branches), envelope stays bare,
+  whitespace passthrough, all five validation error paths, and the
+  re-exported `validateFromName` helper. Test count: 223 → 235.
+
 ## [0.2.2] — 2026-04-29
 
 **One feature add at the end of v0.2.x: per-call body customization

package/GUIDE.md

@@ -631,7 +631,8 @@ Full options table:
 |---|---|---|---|
 | `secret` | yes | — | HMAC key, ≥64 hex chars (32 bytes). FR-47, FR-48. |
 | `baseUrl` | yes | — | Base URL for magic-link construction. |
-| `from` | yes | — | Sender email address. |
+| `from` | yes | — | Bare RFC 5321 sender (envelope MAIL FROM AND default From: header). |
+| `fromName` | no | — | Optional RFC 5322 display name for the From: header (AF-27, v0.2.3+). When set, recipients see `addypin <noreply@addypin.com>` instead of bare `noreply@addypin.com` — most clients display the local-part as the sender name otherwise. ASCII, ≤60 chars, no CR/LF/<>". envelope.from stays bare always. |
 | `dbPath` | no | `./knowless.db` | SQLite file path. |
 | `cookieDomain` | no | (eTLD+1 of `baseUrl`) | Session cookie scope. |
 | `cookieName` | no | `knowless_session` | Session cookie name. |

package/README.md

@@ -7,7 +7,7 @@ that don't need to email their users for anything but the sign-in link.
 npm install knowless
 ```
 
-> v0.2.2 | Node.js >= 22.5 | **1 production dep (nodemailer)** | Apache-2.0
+> v0.2.3 | Node.js >= 22.5 | **1 production dep (nodemailer)** | Apache-2.0
 
 ## Where to go next
 

package/knowless.context.md

@@ -1,7 +1,7 @@
 # knowless -- Integration Guide
 
 > For AI assistants and developers wiring knowless into a project.
-> v0.2.2 | Node.js >= 22.5 | 1 dep (nodemailer) | Apache-2.0
+> v0.2.3 | Node.js >= 22.5 | 1 dep (nodemailer) | Apache-2.0
 
 ## What this is
 
@@ -70,7 +70,15 @@ const auth = knowless({
   // --- Required ---
   secret: '...',                      // 64-char hex; HMAC + cookie sig key
   baseUrl: 'https://app.example.com', // base for magic-link URL construction
-  from: 'auth@app.example.com',       // sender address
+  from: 'auth@app.example.com',       // bare RFC 5321 sender (envelope MAIL FROM
+                                      //   AND default From: header value)
+
+  // --- Optional sender display name (AF-27, v0.2.3) ---
+  fromName: 'addypin',                // optional. When set, From: header is
+                                      //   `<fromName> <from>` (e.g. `addypin
+                                      //   <noreply@addypin.com>`); envelope.from
+                                      //   stays bare. Validated at startup:
+                                      //   ASCII, ≤60 chars, no CR/LF, no <>".
 
   // --- Storage ---
   dbPath: './knowless.db',            // SQLite file; ':memory:' for tests
@@ -179,6 +187,7 @@ import {
   validateSubject,  // pure: validate operator-supplied subject
   validateBodyFooter, // pure: validate operator-supplied footer (AF-8.2)
   validateBodyOverride, // pure: validate per-call body override (AF-26)
+  validateFromName, // pure: validate operator-supplied From: display name (AF-27)
   renderLoginForm,  // pure: HTML5 page rendering
   normalize,        // pure: email normalization
   deriveHandle,     // pure: HMAC-SHA256(hex-decoded secret, email)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knowless",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Small, opinionated, full-stack passwordless auth for Node.js services that don't need to email their users for anything but the sign-in link.",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -34,7 +34,13 @@ function safeHook(fn, label) {
  * @typedef {Object} KnowlessOptions
  * @property {string} secret           HMAC secret, ≥64 hex chars (32 bytes). FR-47, FR-48.
  * @property {string} baseUrl          Public base URL for magic links.
- * @property {string} from             Sender email address.
+ * @property {string} from             Sender email address (bare RFC 5321
+ *   MAIL FROM and default From: header value).
+ * @property {string} [fromName]       Optional RFC 5322 display name for
+ *   the From: header (AF-27, v0.2.3). When set, recipients see
+ *   `<fromName> <from>` in the From: header (e.g. `addypin
+ *   <noreply@addypin.com>`); SMTP envelope sender stays bare.
+ *   Validated at factory startup (ASCII, ≤60 chars, no CR/LF/<>).
  * @property {string} [dbPath='./knowless.db']
  * @property {string} [cookieDomain]   Defaults to baseUrl's hostname.
  * @property {number} [tokenTtlSeconds=900]
@@ -136,6 +142,7 @@ export function knowless(options = {}) {
     options.mailer ??
     createMailer({
       from: options.from,
+      fromName: options.fromName,
       smtpHost: options.smtpHost,
       smtpPort: options.smtpPort,
       transportOverride: options.transportOverride,
@@ -279,6 +286,7 @@ export {
   validateSubject,
   validateBodyFooter,
   validateBodyOverride,
+  validateFromName,
 } from './mailer.js';
 export { createHandlers } from './handlers.js';
 export { renderLoginForm } from './form.js';

package/src/mailer.js

@@ -12,13 +12,17 @@ const ASCII_RE = /^[\x00-\x7f]*$/;
  * the SMTP submission transport.
  *
  * @param {object} args
- * @param {string} args.from
+ * @param {string} args.from               bare RFC 5321 MAIL FROM address
+ * @param {string} [args.fromName]         optional RFC 5322 display name
+ *   (AF-27). When set, the From: header is `name <addr>`; when null/
+ *   undefined, the From: header is the bare `addr`. envelope.from
+ *   (caller-side) always uses the bare address.
  * @param {string} args.to
  * @param {string} args.subject
  * @param {string} args.body  ASCII-only plain text
  * @returns {string} RFC822 message with CRLF line endings
  */
-function composeRaw({ from, to, subject, body }) {
+function composeRaw({ from, fromName, to, subject, body }) {
   // AF-2.1: header-injection defense in depth. normalize() upstream
   // already rejects \r and \n in email addresses, but the mailer
   // shouldn't trust its callers — this is the layer that emits the
@@ -35,11 +39,19 @@ function composeRaw({ from, to, subject, body }) {
       throw new Error(`mailer: ${name} contains CR/LF — header injection blocked`);
     }
   }
+  // AF-27: defensive re-check on fromName (createMailer already validated
+  // at startup, but composeRaw owns the wire-format invariant).
+  if (fromName != null && fromName !== '') {
+    if (typeof fromName !== 'string' || /[\r\n<>"]/.test(fromName)) {
+      throw new Error('mailer: fromName contains forbidden characters');
+    }
+  }
   const fromDomain = from.includes('@') ? from.split('@').pop() : 'localhost';
   const messageId = `<${crypto.randomUUID()}@${fromDomain}>`;
   const date = new Date().toUTCString();
+  const fromHeader = fromName ? `${fromName} <${from}>` : from;
   const headers = [
-    `From: ${from}`,
+    `From: ${fromHeader}`,
     `To: ${to}`,
     `Subject: ${subject}`,
     `Date: ${date}`,
@@ -149,7 +161,15 @@ export function composeBody({ tokenRaw, baseUrl, linkPath, lastLoginAt, bodyFoot
  * invariant — QP soft-breaks WILL break the magic link):
  *   - non-empty string
  *   - ≤ 2048 chars (operator-side overflow guard)
- *   - ASCII only
+ *   - ASCII only (0x00–0x7F). This excludes typographic punctuation
+ *     that adopters reach for out of habit:
+ *       em/en dashes (— –)        → use - or --
+ *       smart quotes (" " ' ')    → use " and '
+ *       ellipses (…)              → use ...
+ *       middle dots (·)           → use | or -
+ *     The constraint preserves 7bit transfer encoding; non-ASCII
+ *     would force quoted-printable, which can soft-break the URL
+ *     line and break the link.
  *   - no CR (LF allowed; defense-in-depth header-injection guard)
  *   - the magic-link URL appears EXACTLY ONCE
  *   - that occurrence is on its own line (no leading or trailing
@@ -193,6 +213,49 @@ export function validateBodyOverride(body, url) {
   }
 }
 
+/**
+ * Validate the operator-supplied display name for the `From:` header
+ * (AF-27, v0.2.3). knowless splits the bare envelope sender (RFC 5321
+ * MAIL FROM) from the RFC 5322 `From:` header, allowing operators to
+ * brand the inbox preview as `addypin <noreply@addypin.com>` rather
+ * than the bare `noreply@addypin.com` (which most clients display as
+ * the local-part "noreply").
+ *
+ * Constraints (deliberately strict — same trap as bodyOverride for
+ * typographic punctuation):
+ *   - ≤ 60 chars (same ballpark as Subject)
+ *   - ASCII only (0x00–0x7F). Excludes em/en dashes, smart quotes,
+ *     ellipses, middle dots. Use plain ASCII equivalents.
+ *   - No CR / LF (header-injection defense; same invariant as
+ *     composeRaw enforces on `from` / `to` / `subject`)
+ *   - No `<` / `>` / `"` (would break the `name <addr>` quoting)
+ *
+ * Returns the validated string (or `null` for null/empty input, so
+ * callers can pass through). Throws on violation.
+ *
+ * @param {unknown} name
+ * @returns {string|null}
+ */
+export function validateFromName(name) {
+  if (name == null || name === '') return null;
+  if (typeof name !== 'string') {
+    throw new Error('fromName must be a string when provided');
+  }
+  if (name.length > 60) {
+    throw new Error('fromName must be ≤ 60 chars');
+  }
+  if (!ASCII_RE.test(name)) {
+    throw new Error('fromName must be ASCII (no em-dashes, smart quotes, ellipses, etc.)');
+  }
+  if (/[\r\n]/.test(name)) {
+    throw new Error('fromName must not contain CR/LF (header-injection defense)');
+  }
+  if (/[<>"]/.test(name)) {
+    throw new Error('fromName must not contain < > or " (would break From: header quoting)');
+  }
+  return name;
+}
+
 /**
  * Validate operator-overridden subject per SPEC §12.5.
  * Throws on invalid; warns (returns warnings array) on suspicious-but-allowed.
@@ -225,18 +288,24 @@ export function validateSubject(subject) {
  * with streamTransport:true) to capture the raw bytes without an MTA.
  *
  * @param {object} cfg
- * @param {string} cfg.from           sender, e.g. 'auth@app.example.com'
+ * @param {string} cfg.from           bare RFC 5321 sender address (envelope
+ *   MAIL FROM AND default From: header value when fromName is unset)
+ * @param {string} [cfg.fromName]     AF-27 (v0.2.3). Optional RFC 5322
+ *   display name. When set, the From: header is `name <addr>`; envelope
+ *   sender stays bare. Validated by validateFromName() at startup.
  * @param {string} [cfg.smtpHost='localhost']
  * @param {number} [cfg.smtpPort=25]
  * @param {object} [cfg.transportOverride] for tests
- * @returns {{ submit(args: {to:string, subject:string, body:string}): Promise<any>, close(): void }}
+ * @returns {{ submit(args: {to:string, subject:string, body:string}): Promise<any>, verify(): Promise<true>, close(): void }}
  */
 export function createMailer(cfg) {
-  const { from, smtpHost = 'localhost', smtpPort = 25, transportOverride } = cfg;
+  const { from, fromName, smtpHost = 'localhost', smtpPort = 25, transportOverride } = cfg;
   if (typeof from !== 'string' || from.length === 0) {
     throw new Error('mailer: from is required');
   }
   if (!ASCII_RE.test(from)) throw new Error('mailer: from must be ASCII');
+  // AF-27: validate display name at startup; fail-fast.
+  const validatedFromName = validateFromName(fromName);
 
   const transport =
     transportOverride ??
@@ -269,7 +338,9 @@ export function createMailer(cfg) {
       if (!ASCII_RE.test(body)) {
         throw new Error('mailer: body must be ASCII');
       }
-      const raw = composeRaw({ from, to, subject, body });
+      // AF-27: From: header may include display name; envelope.from
+      // stays bare (RFC 5321 MAIL FROM doesn't allow display names).
+      const raw = composeRaw({ from, fromName: validatedFromName, to, subject, body });
       return transport.sendMail({
         envelope: { from, to: [to] },
         raw,