knowless 0.2.2 → 1.0.0

package/CHANGELOG.md

@@ -15,8 +15,148 @@ Versioning is [SemVer](https://semver.org/).
 
 ## [Unreleased]
 
-**v0.2.2 is feature-complete.** v1.0.0 is the planned next release —
-walk-away promotion, no API changes.
+Walk-away is active. Per PRD §6.3, the only changes that ship after
+v1.0.0 are:
+
+- Security fixes (CVEs in `nodemailer` or `node:sqlite` with
+  user-visible impact)
+- Bug fixes that don't change the API surface
+- Documentation corrections
+
+Feature requests are deflected to PRD §14 NO-GO, to sibling projects,
+or to forking. The library being "done" is a feature.
+
+## [1.0.0] — 2026-04-29
+
+**Walk-away release.** No new API surface vs v0.2.3 — v1.0.0 is the
+*promotion* tag, marking the library as feature-complete and the
+maintenance mode (security + bug fixes only) as active.
+
+This is the terminal feature release by intent (PRD §6.3). The
+discipline that produced it: every proposed addition during the
+v0.1.x → v0.2.x cycle was stress-tested against two questions —
+*is this identity layer or behavior layer?* and *does the mechanism
+live with the policy?* Items that failed either test were cut to
+adopter / perimeter / operator code. The result is a library small
+enough to audit in an afternoon, with one production dep, and a
+closed feature list.
+
+### Why v1.0.0 now
+
+All PRD §6.1 graduation criteria are met (12/12 after the 2026-04-29
+scope cull). The library is production-validated end-to-end:
+
+- **One real adopter shipped on it.** addypin merged its
+  `try/knowless` branch and runs knowless as its auth+mail layer in
+  production. ~1,150 LOC of bespoke auth/mail removed; ~35 LOC of
+  knowless wiring added; ~33× reduction.
+- **The full v0.2.x hardening cycle was driven by adopter signal.**
+  Eleven audit findings (AF-7 through AF-25) shipped or were
+  recorded as deliberate cuts. Final cycle (AF-19/20/21 operator
+  visibility, AF-26 body override, AF-27 From: display name) all
+  validated by addypin in production:
+  - v0.2.2 + AF-26: bodyOverride wired into pin-confirmation,
+    login, and resend@ flows; subject and body agree end-to-end.
+  - v0.2.3 + AF-27: fromName wired in both factories (web +
+    inbound CLI); inbox preview shows the brand name, not the
+    local-part. Validated by use, not by spec.
+- **Test count: 235** (192 in v0.2.0 → 207 in v0.2.1 → 223 in
+  v0.2.2 → 235 in v0.2.3 → 235 in v1.0.0).
+- **One production dep** (`nodemailer`). Storage uses `node:sqlite`
+  from the Node stdlib. No native compile, no toolchain.
+- **`Δ_mean` for the FR-6 timing test: 0.002ms locally** — 500× under
+  the 1ms practical-effect bar.
+
+### What walk-away means in practice
+
+- **Pin and forget.** v1.0.0 will work the same way three years
+  later. Security patches will land in v1.x.
+- **No v2.0.** No sessions+, no plugin system, no second mailer, no
+  SaaS counterpart. The API closes here.
+- **No additive v1.x.** v1.1.0, v1.2.0, etc. are reserved for
+  security and bug fixes only. Feature requests are deflected.
+  This is the discipline the AF-23/24/25 cuts and the
+  AF-26/AF-27-as-v0.2.x decisions both protect: walk-away has to
+  *mean* walk-away, otherwise the promise is empty.
+- **Procurement signal.** A library that has explicitly committed
+  to *not growing* is a different risk profile from a typical OSS
+  package. Most reviews read "still actively developed" as good —
+  but for an auth dependency, "still actively developed" is also
+  "still changing in ways you'll have to track." knowless inverts
+  that.
+
+### Migration from v0.2.3
+
+None. v1.0.0 is byte-equivalent to v0.2.3 source. `npm install
+knowless@1.0.0` is a drop-in.
+
+## [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
 

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
+> v1.0.0 (walk-away release) | 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
+> v1.0.0 (walk-away release) | 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": "1.0.0",
   "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,