knowless 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -8,6 +8,62 @@ Versioning is [SemVer](https://semver.org/).
 ## [Unreleased]
 
 - Caddy forward-auth Docker integration test (TASKS.md 6.8).
+
+## [0.1.6] — 2026-04-28
+
+addypin integration round 2 — one correctness fix (HMAC key handling)
+and one common-want feature (operator footer on auth mail).
+
+### Breaking
+
+- **The `secret` is now hex-decoded before being used as the HMAC
+  key.** Prior versions passed the 64-char hex string to
+  `crypto.createHmac` as ASCII bytes — same 256 bits of entropy, but
+  a different HMAC output than systems that hex-decode first. The
+  PRD already implied 32 bytes ("≥64 hex chars (32 bytes)"); the
+  implementation matched the spec on key length but used the wrong
+  key bytes. **Effect:** every handle and session signature changes
+  on upgrade. Existing sessions invalidate (users re-login); existing
+  pre-seeded handles must be re-derived. There are no production
+  knowless deployments yet (addypin and webrevival are both pre-prod),
+  so we lock the correct semantics in before v1.0 freezes. Closes
+  AF-8.1.
+- The startup secret check now also validates that the secret is
+  64-char lowercase hex (`/^[a-f0-9]{64,}$/i`). Mixed-case secrets
+  must be lowercased.
+- `deriveHandle()` and `signSession()` accept `Buffer` directly for
+  adopters who already hold raw 32-byte keys.
+
+### Added
+
+- **`bodyFooter: string`** config option — append a constant operator
+  footer to every magic-link email after the standard `"-- "` (RFC
+  3676) signature delimiter. Constraints (deliberately strict to
+  preserve the URL-line invariant and 7bit body encoding):
+  - ASCII only (no unicode middle-dot — use `|` or `-`)
+  - ≤ 240 chars, ≤ 4 lines
+  - No CR
+  - No `http://` / `https://` substrings (would conflict with the
+    magic-link line and trigger MTA URL-rewriting heuristics)
+  Validated at factory startup; fails fast on misconfiguration.
+  Closes AF-8.2.
+- `validateBodyFooter()` exported alongside `composeBody` for adopters
+  who want to validate operator-supplied footers themselves.
+- `secretBytes()` exported from `./handle.js` (and via the package
+  root) for adopters who want to coerce a hex string to raw 32-byte
+  HMAC key on their own boundaries.
+
+### Migration from 0.1.5
+
+- **Pre-seeded handles must be re-derived.** `deriveHandle('alice@x',
+  SECRET)` returns a different value in 0.1.6. If you stored handles
+  in any external system, recompute them. Closed-registration users
+  must re-seed.
+- **Active sessions invalidate.** Users will need to log in again
+  after the upgrade. Plan for a single-shot user-visible logout.
+- **Magic links in flight at upgrade time** become invalid (token
+  hashes are stored as HMAC outputs and the key changes). 15 min
+  TTL by default; a brief read-only window during deploy is enough.
 - `knowless-server --check-null-route`: CLI probe that submits a
   test message to `shamRecipient` and confirms the local MTA
   discarded it. Honest answer to "does the operator's null-route
@@ -15,6 +71,62 @@ Versioning is [SemVer](https://semver.org/).
   not what the MTA did, so this is the closest we can get.
   Targeted for v0.2.0.
 
+## [0.1.5] — 2026-04-28
+
+addypin POC findings round. Adds programmatic magic-link entry
+(unblocks "use first, claim later" UX patterns), one ergonomic
+helper, two safety/diagnostic fixes, and three doc updates.
+
+### Added
+
+- **`auth.startLogin({email, nextUrl?, sourceIp?})`** — programmatic
+  entry that runs the same 12-step sham-work flow as `POST /login`
+  but skips Origin/honeypot (no browser context). Returns
+  `{handle, submitted: true}` — same shape on rate-limit / sham /
+  real to preserve FR-6 timing equivalence. Throws only on
+  programmer error. SPEC §7.3a. Closes AF-7.3.
+- **`auth.deriveHandle(email)`** — instance method that uses the
+  configured secret. Lets adopters compute owner-handles outside
+  HTTP context without spreading the secret across modules. Closes
+  AF-7.4.
+- **GUIDE.md "Two adoption modes" section** — Mode B (register-
+  first, the form) and Mode A (use-first-claim-later, programmatic).
+  Both supported, pickable per-action.
+- **GUIDE.md "Constraints / install footprint" section** — direct
+  deps, transitive count, deprecation-warning context. Closes AF-7.7.
+
+### Changed
+
+- **`devLogMagicLinks` lines now tagged with `cfg.from`** —
+  `[knowless dev:auth@app.example.com] magic link: ...`. Disambiguates
+  multi-instance dev logs. Closes AF-7.6.
+- **`devLogMagicLinks` + sham + SMTP-fail now prints a one-line
+  silent-miss hint** instead of staying silent. Surfaces the
+  closed-registration-is-on case that previously cost adopters
+  ~30min of debugging. Strictly opt-in dev mode. Closes AF-7.2.
+
+### Safety / diagnostics
+
+- **`createMailer` validates `transportOverride` at startup.** A
+  malformed override (e.g. an options bag mistaken for a transport)
+  throws fast with a pointed error instead of failing at first
+  submission. Closes AF-7.5.
+- **`POST /login` warns once on stderr when `Content-Length > 0`
+  but body is empty.** Catches the common non-Express trap of
+  mounting `express.urlencoded()` or similar body parsers ahead of
+  `auth.login` (which consumes the stream itself). One warning per
+  handler instance. Closes AF-7.1.
+
+### Documentation
+
+- **SPEC §7.3a** specifies the programmatic entry's contract: which
+  steps it skips (Origin, honeypot), why FR-6 still holds, and
+  what programmer-error throws look like.
+- **GUIDE.md** adds two traps for non-Express integrators (body-
+  parser conflict, Origin requirement) and a worked Mode-A example.
+- **knowless.context.md** lists `startLogin` + `deriveHandle` in the
+  public API table and adds gotchas 15–16.
+
 ## [0.1.4] — 2026-04-28
 
 First real-world integration release. Bugs and ergonomics surfaced

package/GUIDE.md

@@ -205,6 +205,95 @@ Fastify, Hono, `node:http` — all work. Each handler is a plain
 `(req, res) => Promise<void>` function. No framework hooks, no
 middleware injection.
 
+#### Trap: do NOT pre-parse the body
+
+knowless reads `POST /login`'s body itself. If a body parser
+middleware runs ahead of `auth.login` and consumes the stream,
+knowless sees an empty body and silently null-routes the request
+(as if no email was submitted). Symptoms: form posts return 200,
+no magic link arrives, no error logged.
+
+Express works in the example above because `express.urlencoded()`
+is mounted as application middleware but doesn't intercept the
+specific path. **On Hono / Fastify-without-body-plugin / raw
+node:http, mount `auth.login` directly with no body parser in
+front.** Same goes for `auth.logout` (it doesn't read a body, but
+keep the symmetry).
+
+knowless will emit a one-time `console.warn(...)` if it sees an
+empty body where `Content-Length > 0` — that's the canary for this
+bug.
+
+#### Trap: non-browser callers need an Origin header
+
+`POST /login` runs an Origin/Referer whitelist (CSRF defense, see
+the FAQ below). Browsers always send `Origin` on cross-origin
+POSTs, so the form path is fine. **Curl / scripts / server-to-
+server callers must send no Origin header at all** (knowless
+allows browser-absent requests) **or** an Origin matching your
+`cookieDomain`. If you set a foreign Origin, the request silently
+falls through to a sham send. For programmatic callers, prefer
+[`auth.startLogin()`](#mode-a-use-first-claim-later) over POSTing
+the form.
+
+### Two adoption modes (Mode A vs Mode B)
+
+knowless supports two UX flows out of the box. Pick per-action,
+not per-app — both can coexist.
+
+**Mode B — register-first (the default).** User must log in before
+performing the action. Wire `auth.login` / `auth.callback` as
+above; gate your action with `auth.handleFromRequest(req)`. Use
+when the action requires a session (account settings, paid
+features, anything you want tied to an identity at the moment of
+the action).
+
+```js
+app.post('/api/comments', (req, res) => {
+  const handle = auth.handleFromRequest(req);
+  if (!handle) return res.status(401).end();
+  // create comment owned by `handle`
+});
+```
+
+**Mode A — use-first, claim-later.** User performs the action
+without logging in; you capture their email and trigger a magic
+link. Clicking it opens a session and your callback handler
+"promotes" the deferred resource. Use for "drop a pin," "post a
+share link," "submit a paste" — patterns where forcing a login
+*before* the action would harm the UX.
+
+```js
+app.post('/api/pins', async (req, res) => {
+  const { email, lat, lng } = await readJsonBody(req);
+  const owner = auth.deriveHandle(email);          // AF-7.4
+  await db.insertPendingPin({ owner, lat, lng });  // your code
+  await auth.startLogin({                          // AF-7.3
+    email,
+    nextUrl: 'https://app.example.com/manage',
+    sourceIp: req.socket.remoteAddress,
+  });
+  res.status(202).end();  // "we'll email you the link"
+});
+
+// On callback, promote pending pins owned by the now-logged-in handle.
+app.get('/manage', (req, res) => {
+  const owner = auth.handleFromRequest(req);
+  if (!owner) return res.redirect('/login');
+  // db.promotePendingPinsFor(owner)
+});
+```
+
+`startLogin` runs the same 12-step sham-work flow as the form
+handler, so unknown emails, rate-limit hits, and real sends all
+return identical shapes — the caller can't observe which happened.
+This preserves FR-6 timing equivalence even for programmatic
+callers. See SPEC §7.3a for the full contract.
+
+`auth.deriveHandle(email)` returns the same opaque HMAC handle
+that the form path uses, without you having to import the helper
+or pass the secret around.
+
 ### Step 5: Pre-seed users (closed-registration mode, default)
 
 By default, knowless is closed: a handle must already exist before
@@ -465,3 +554,18 @@ than weakening the bar — see SPEC §14.5.
 Yes: `tokenTtlSeconds`. Don't set it absurdly high. Magic links
 that linger in inboxes are a phishing-amplification risk if the
 mail account is later compromised.
+
+## Constraints / install footprint
+
+- **Two direct dependencies.** `nodemailer` (SMTP submission) and
+  `better-sqlite3` (storage). Both audited and pinned at major
+  versions in `package.json`.
+- **~40 transitive packages** in a typical install. The bulk are
+  `nodemailer`'s ecosystem deps (mostly idle in our usage) and
+  `better-sqlite3`'s build-time prebuild fetcher. You may see one
+  deprecation warning during install for `prebuild-install` —
+  build-chain noise, not runtime code.
+- **Node ≥ 20.** Uses `node:util parseArgs`, `node:net BlockList`
+  for CIDR support, and `--env-file=` for the standalone server.
+- **No optional deps, no postinstall scripts** beyond `better-
+  sqlite3`'s native binding fetch.

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.1.0 | Node.js >= 20 | 2 deps (nodemailer, better-sqlite3) | Apache-2.0
+> v0.1.6 | Node.js >= 20 | 2 deps (nodemailer, better-sqlite3) | Apache-2.0
 
 ## What this is
 
@@ -83,12 +83,12 @@ A short list (full table in [`docs/01-product/PRD.md`](docs/01-product/PRD.md)
 
 | Mode | Status | When |
 |---|---|---|
-| **Library mode** | v0.1.0 | Mount handlers in your existing Node app |
-| **Standalone server** (forward-auth) | v0.2.0 | Self-hosters gating Uptime Kuma / AdGuard / Pi-hole / Sonarr / etc. via Caddy or nginx |
+| **Library mode** | shipped (v0.1.0) | Mount handlers in your existing Node app |
+| **Standalone server** (forward-auth) | shipped (v0.1.3) | Self-hosters gating Uptime Kuma / AdGuard / Pi-hole / Sonarr / etc. via Caddy or nginx |
 
-This release ships library mode. Standalone server (`bin/knowless-server`)
-follows in 0.2.0 — see [`docs/03-tasks/TASKS.md`](docs/03-tasks/TASKS.md)
-Phase 6 for scope.
+Library mode is the six-line example above. Standalone server is
+`npx knowless-server` — see [`OPS.md`](OPS.md) for the full Postfix +
+DNS + reverse-proxy walkthrough.
 
 ## Operator commitments
 

package/knowless.context.md

@@ -76,6 +76,7 @@ const auth = knowless({
   // --- Cookie / session ---
   cookieDomain: 'app.example.com',    // default: hostname of baseUrl
   cookieName: 'knowless_session',     // default 'knowless_session'
+  cookieSecure: true,                 // default true; "false" only for localhost dev
   sessionTtlSeconds: 30 * 86400,      // 30 days
 
   // --- Token ---
@@ -97,17 +98,33 @@ const auth = knowless({
   // --- Behavior ---
   openRegistration: false,            // first-email-wins handle creation
   includeLastLoginInEmail: true,      // append "Last sign-in: <ISO ts>" line
-  confirmationMessage: 'Thanks. If <strong>{email}</strong>...',
+  confirmationMessage: 'Thanks. If {email} is registered, a link is on its way.',
+  // ^ NOTE: the message is HTML-escaped before render (AF-6.5).
+  //         {email} placeholder still works. For HTML, pre-render upstream.
+
+  // Operator footer on magic-link mail (AF-8.2). ASCII-only, ≤240
+  // chars, ≤4 lines, NO URLs (would conflict with the magic-link line).
+  // Validated at factory startup. Use | or - as separators (NOT · which
+  // is non-ASCII).
+  bodyFooter: 'feedback@example.com | privacy first',
 
   // --- Abuse defenses (FR-38..41) ---
   maxActiveTokensPerHandle: 5,        // 0 to disable
   maxLoginRequestsPerIpPerHour: 30,   // 0 to disable
   maxNewHandlesPerIpPerHour: 3,       // 0 to disable (open-reg only)
   honeypotFieldName: 'website',
-  trustedProxies: ['127.0.0.1', '::1'],
+  // Plain IPs and/or CIDR ranges (AF-6.3). Useful for k8s/docker/cgnat.
+  trustedProxies: ['127.0.0.1', '::1', '10.0.0.0/8'],
 
   // --- Lifecycle ---
   sweepIntervalMs: 5 * 60 * 1000,     // periodic sweeper tick
+  onSweepError: (err) => { /* alerting hook; errors are swallowed */ },
+
+  // --- Dev mode (AF-6.2) ---
+  // When SMTP submission fails AND this flag is true, the magic link
+  // is printed to stderr so a developer can click through. Off by
+  // default. Never fires for sham (silent-miss) submissions.
+  devLogMagicLinks: false,
 
   // --- Injection (tests / advanced) ---
   store: undefined,                   // bring your own store
@@ -127,7 +144,12 @@ const auth = knowless({
 | `verify` | (req, res) | void | GET handler (forward-auth): 200+`X-User-Handle` if cookie valid, else 401 |
 | `logout` | (req, res) | Promise\<void\> | POST handler: clears session row + cookie |
 | `loginForm` | (req, res) | void | GET handler: renders the hardcoded login HTML; preserves `?next=` |
+| `handleFromRequest` | (req) | string \| null | Programmatic session resolver for in-process middleware. Returns the handle if the cookie is valid, else null. SPEC §9.4. |
 | `deleteHandle` | (handle: string) | void | Atomic delete of handle + tokens + sessions (FR-37a, GDPR) |
+| `revokeSessions` | (handle: string) | number | Drops every session for `handle` without deleting the account ("log out everywhere"). Returns rows removed. AF-6.1. |
+| `startLogin` | ({email, nextUrl?, sourceIp?}) | Promise\<{handle, submitted: true}\> | Programmatic magic-link send for "use first, claim later" flows. Same 12-step sham-work as form. SPEC §7.3a. AF-7.3. |
+| `deriveHandle` | (email: string) | string | HMAC-SHA256(secret, normalize(email)) using the configured secret. Use to compute owner-handles outside HTTP context. AF-7.4. |
+| `_sweep` | -- | void | Trigger one sweep tick on demand (tests, operator scripts). AF-5.3. |
 | `config` | -- | object | Merged effective config; safe to read (do not mutate) |
 | `close` | -- | void | Stops sweeper, closes mailer + store. Call on shutdown. |
 
@@ -141,9 +163,11 @@ import {
   createHandlers,   // bring your own factory wiring
   composeBody,      // pure: build the mail body
   validateSubject,  // pure: validate operator-supplied subject
+  validateBodyFooter, // pure: validate operator-supplied footer (AF-8.2)
   renderLoginForm,  // pure: HTML5 page rendering
   normalize,        // pure: email normalization
-  deriveHandle,     // pure: HMAC-SHA256(secret, email)
+  deriveHandle,     // pure: HMAC-SHA256(hex-decoded secret, email)
+  secretBytes,      // pure: coerce hex string → 32-byte HMAC key
 } from 'knowless';
 ```
 
@@ -372,11 +396,10 @@ rate-limits) belongs above the library.
    The library does NOT compute eTLD+1 automatically (would
    require a public-suffix-list dep).
 
-5. **`Secure` cookie attribute is non-negotiable.** All session
-   cookies set `Secure`. HTTP-only origins won't receive them.
-   Use HTTPS in production. Localhost development: use
-   `--insecure-localhost-cookies` (not implemented yet — TASKS
-   open question; works in Chrome with `--unsafely-treat-insecure-origin-as-secure`).
+5. **`Secure` cookie attribute toggles via `cookieSecure`.** Default
+   is `true`. Set `cookieSecure: false` ONLY for `http://localhost`
+   development; the library logs a stderr warning at startup (AF-4.4).
+   Production deployments MUST use HTTPS and leave `cookieSecure: true`.
 
 6. **Forward-auth needs the parent-domain cookie.** If your auth
    subdomain is `auth.example.com` and protected service is
@@ -410,6 +433,53 @@ rate-limits) belongs above the library.
     so it won't *prevent* exit, but the SQLite handle held by
     `better-sqlite3` will leave a finalizer warning.
 
+12. **CSRF defense is the Origin/Referer whitelist, not a token.**
+    Modern browsers always emit `Origin` on cross-origin POSTs;
+    knowless validates host against `cookieDomain` on POST /login
+    AND POST /logout. Browser-absent (curl / programmatic) is
+    allowed. **Do NOT add a CSRF token upstream** — the Origin
+    check is the defense. SPEC §7.3 Step 0.
+
+13. **`confirmationMessage` is plain text + `{email}` placeholder.**
+    The whole message is HTML-escaped before render (AF-6.5). If
+    you want bold/italic/links in the confirmation copy, pre-render
+    the HTML upstream and pass the escaped string — but understand
+    you're then responsible for not interpolating user data.
+
+14. **`devLogMagicLinks` is opt-in and dev-only.** When set true
+    AND SMTP submission fails, the magic link is printed to stderr
+    tagged `[knowless dev:<from>]`. Sham (silent-miss) submissions
+    print a `silent-miss: ...` hint instead of a link — opt-in dev
+    only, since this leaks closed-reg state. Don't enable in
+    production.
+
+15. **POST /login: don't pre-parse the body.** knowless reads the
+    request stream itself. Any framework body parser mounted in
+    front of `auth.login` will silently steal the form data and
+    null-route the request. knowless emits a one-time
+    `console.warn` if it sees `Content-Length > 0` with an empty
+    body. AF-7.1.
+
+16. **Two adoption modes — Mode B (register-first) and Mode A
+    (use-first claim-later).** Mode B is the form (`auth.login`).
+    Mode A is `auth.startLogin({email, nextUrl, sourceIp})` for
+    "drop a pin, claim by email click" patterns. Both run the
+    identical 12-step sham-work flow; same FR-6 guarantee. Pick
+    per-action, not per-app.
+
+17. **Secret is hex-decoded (AF-8.1, since v0.1.6).** Pass a
+    64-char lowercase hex string; knowless decodes to 32 raw bytes
+    before HMAC. If you're upgrading from 0.1.5 or earlier, all
+    handles and session signatures change — re-seed handles, expect
+    one user-visible logout. `Buffer` accepted directly for adopters
+    who hold raw 32-byte keys.
+
+18. **`bodyFooter` constraints (AF-8.2).** ASCII only — `·` is NOT
+    ASCII, use `|` or `-`. ≤ 240 chars, ≤ 4 lines, no `http(s)://`
+    URLs (would conflict with the magic-link line). Validated at
+    factory startup; fails fast. Goes after RFC 3676 `"-- "`
+    delimiter so mail clients strip it from quoted replies.
+
 ## Constraints
 
 - **Node 20+** -- targeting LTS; tested on Node 22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knowless",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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/handle.js

@@ -26,6 +26,28 @@ export function normalize(input) {
   return lowered;
 }
 
+/**
+ * Coerce an operator-supplied secret to the raw bytes used as HMAC key.
+ *
+ * AF-8.1: knowless requires `secret` to be a 64-char lowercase hex
+ * string (32 bytes). Prior versions passed it to `createHmac` as an
+ * ASCII string — same 256 bits of entropy, but a different HMAC
+ * output than systems that hex-decode first. That meant adopters
+ * with existing HMAC-keyed identifiers couldn't interoperate. The
+ * fix is to hex-decode at the boundary so HMAC uses 32 raw bytes.
+ *
+ * @param {Buffer|string} secret
+ * @returns {Buffer} 32 raw bytes
+ */
+export function secretBytes(secret) {
+  if (Buffer.isBuffer(secret)) return secret;
+  if (typeof secret !== 'string') throw new Error('secret required');
+  if (!/^[a-f0-9]{64,}$/i.test(secret)) {
+    throw new Error('secret must be ≥64 hex chars (lowercase a-f, 0-9)');
+  }
+  return Buffer.from(secret, 'hex');
+}
+
 /**
  * Derive the opaque handle for a normalized email using the operator secret.
  * HMAC-SHA256, lowercase hex output, 64 chars. See SPEC §3.
@@ -34,18 +56,15 @@ export function normalize(input) {
  * HMAC use of `secret` MUST add a tag prefix (see SPEC §3.4).
  *
  * @param {string} emailNormalized output of normalize()
- * @param {Buffer|string} secret operator HMAC secret
+ * @param {Buffer|string} secret operator HMAC secret (32+ raw bytes or ≥64 hex chars)
  * @returns {string} 64-char lowercase hex handle
  */
 export function deriveHandle(emailNormalized, secret) {
   if (typeof emailNormalized !== 'string' || emailNormalized.length === 0) {
     throw new Error('emailNormalized required');
   }
-  if (!secret || (typeof secret !== 'string' && !Buffer.isBuffer(secret))) {
-    throw new Error('secret required');
-  }
   return crypto
-    .createHmac('sha256', secret)
+    .createHmac('sha256', secretBytes(secret))
     .update(emailNormalized, 'utf8')
     .digest('hex');
 }

package/src/handlers.js

@@ -182,6 +182,21 @@ export function createHandlers({ store, mailer, config }) {
   // Build once at handler creation; supports plain IPs and CIDRs (AF-6.3).
   const trustedProxies = buildTrustedPeers(cfg.trustedProxies);
 
+  // AF-7.1: emit at most one warning per handler instance about an
+  // upstream body parser swallowing the request body. Loud enough to
+  // notice in dev, quiet enough not to spam.
+  let emptyBodyWarned = false;
+  function warnEmptyBodyOnce() {
+    if (emptyBodyWarned) return;
+    emptyBodyWarned = true;
+    console.warn(
+      '[knowless] POST /login received an empty body but Content-Length > 0. ' +
+        'A body parser running ahead of this handler likely consumed the stream. ' +
+        'knowless reads req itself; do not mount express.urlencoded() / express.json() / ' +
+        'similar middleware in front of POST /login. (Warned once per instance.)',
+    );
+  }
+
   // SPEC §5.4 / FR-30: build the cookie-attribute suffix once. Secure is
   // emitted by default and omitted only when cookieSecure: false (localhost
   // dev). HttpOnly + SameSite=Lax are always set.
@@ -208,56 +223,46 @@ export function createHandlers({ store, mailer, config }) {
     res.end();
   }
 
-  async function login(req, res) {
-    // Step 0 — Origin / Referer validation (SPEC §7.3 Step 0, AF-4.3).
-    // CSRF defense: a malicious cross-origin page autosubmitting to /login
-    // would otherwise trigger magic-link sends to known emails. Exempt
-    // from FR-6 timing equivalence per SPEC §7.3.
-    if (!validateOrigin(req, cfg.cookieDomain)) {
-      sameResponse(res, '', '');
-      return;
-    }
-
-    let raw;
-    try {
-      raw = await readBody(req);
-    } catch {
-      sameResponse(res, '', '');
-      return;
-    }
-    const body = parseBody(raw, req.headers['content-type']);
-    const emailRaw = typeof body.email === 'string' ? body.email : '';
-    const honeypot = body[cfg.honeypotFieldName];
-    const nextRaw = body.next;
-
+  /**
+   * The 12-step sham-work flow, reusable by both POST /login and the
+   * programmatic auth.startLogin() entry. Returns {handle, isSham} so
+   * the form handler can drive its same-response and the programmatic
+   * caller can return the handle to its caller. See SPEC §7.3 (form)
+   * and §7.3a (programmatic). AF-7.3.
+   *
+   * Steps skipped depending on the entry point:
+   *   - Origin (§7.3 Step 0): form-only; programmatic callers are
+   *     trusted server-side code.
+   *   - Honeypot (§7.3 Step 2): form-only; no form context.
+   *
+   * Both entries run steps 1, 3, 4–12 identically — so the timing-
+   * equivalence guarantee (FR-6) holds for either.
+   *
+   * @returns {Promise<{handle: string|null, isSham: boolean,
+   *                    emailNorm: string, nextValidated: string|null}>}
+   *   handle is null only when the email failed to normalize (programmer
+   *   bug for startLogin; same-shape silent for /login).
+   */
+  async function runSendLink({ emailRaw, nextRaw, sourceIp }) {
     // Step 1: parse + normalize
     let emailNorm;
     try {
       emailNorm = normalize(emailRaw);
     } catch {
-      sameResponse(res, emailRaw, nextRaw);
-      return;
-    }
-
-    // Step 2: honeypot — exempt short-circuit (no sham work)
-    if (typeof honeypot === 'string' && honeypot.length > 0) {
-      sameResponse(res, emailNorm, nextRaw);
-      return;
+      return { handle: null, isSham: false, emailNorm: emailRaw, nextValidated: null };
     }
 
     // Step 3: per-IP rate limit on /login — exempt short-circuit
-    const ip = determineSourceIp(req, trustedProxies);
     if (
       rateLimitExceeded(
         store,
         'login_ip',
-        ip,
+        sourceIp,
         cfg.maxLoginRequestsPerIpPerHour,
         HOUR_MS,
       )
     ) {
-      sameResponse(res, emailNorm, nextRaw);
-      return;
+      return { handle: null, isSham: false, emailNorm, nextValidated: null };
     }
 
     // ---- Equivalent-work region begins (SPEC §7.3 step 4) ----
@@ -271,7 +276,7 @@ export function createHandlers({ store, mailer, config }) {
         rateLimitExceeded(
           store,
           'create_ip',
-          ip,
+          sourceIp,
           cfg.maxNewHandlesPerIpPerHour,
           HOUR_MS,
         )
@@ -314,6 +319,7 @@ export function createHandlers({ store, mailer, config }) {
       baseUrl: cfg.baseUrl,
       linkPath: cfg.linkPath,
       lastLoginAt,
+      bodyFooter: cfg.bodyFooter,
     });
 
     try {
@@ -323,18 +329,91 @@ export function createHandlers({ store, mailer, config }) {
       console.error('[knowless] mail submit failed:', err.message);
       // AF-6.2: dev-mode fallback. When SMTP is unreachable in local
       // development the operator otherwise has no way to obtain the magic
-      // link. Print it to stderr only when explicitly opted in. Sham
-      // submissions are NOT logged (would leak silent-miss outcome).
-      if (cfg.devLogMagicLinks && !isSham) {
-        const link = `${cfg.baseUrl}${cfg.linkPath}?t=${token.raw}`;
-        process.stderr.write(`[knowless dev] magic link: ${link}\n`);
+      // link. Print it to stderr only when explicitly opted in.
+      if (cfg.devLogMagicLinks) {
+        // AF-7.6: include `from` to disambiguate multi-instance logs.
+        const tag = `[knowless dev:${cfg.from}]`;
+        if (isSham) {
+          // AF-7.2 dev hint: silent-miss is by-design but in dev mode
+          // operators repeatedly debug "why no link?" — surface the
+          // reason. Only fires on opt-in dev mode + SMTP failure.
+          process.stderr.write(
+            `${tag} silent-miss: handle for "${emailNorm}" does not exist (openRegistration=${cfg.openRegistration})\n`,
+          );
+        } else {
+          const link = `${cfg.baseUrl}${cfg.linkPath}?t=${token.raw}`;
+          process.stderr.write(`${tag} magic link: ${link}\n`);
+        }
       }
     }
 
-    rateLimitIncrement(store, 'login_ip', ip, HOUR_MS);
-    if (isCreating) rateLimitIncrement(store, 'create_ip', ip, HOUR_MS);
+    rateLimitIncrement(store, 'login_ip', sourceIp, HOUR_MS);
+    if (isCreating) rateLimitIncrement(store, 'create_ip', sourceIp, HOUR_MS);
 
-    sameResponse(res, emailNorm, nextValidated ?? '');
+    return { handle, isSham, emailNorm, nextValidated };
+  }
+
+  async function login(req, res) {
+    // Step 0 — Origin / Referer validation (SPEC §7.3 Step 0, AF-4.3).
+    if (!validateOrigin(req, cfg.cookieDomain)) {
+      sameResponse(res, '', '');
+      return;
+    }
+
+    let raw;
+    try {
+      raw = await readBody(req);
+    } catch {
+      sameResponse(res, '', '');
+      return;
+    }
+    // AF-7.1: warn when a body parser ahead of us has consumed the stream.
+    // POST /login with Content-Length > 0 but empty raw body is the
+    // signature; without this, the request silently null-routes and the
+    // adopter loses 30 minutes wondering why magic links never arrive.
+    if (raw.length === 0) {
+      const cl = Number(req.headers?.['content-length']);
+      if (Number.isFinite(cl) && cl > 0) {
+        warnEmptyBodyOnce();
+      }
+    }
+    const body = parseBody(raw, req.headers['content-type']);
+    const emailRaw = typeof body.email === 'string' ? body.email : '';
+    const honeypot = body[cfg.honeypotFieldName];
+    const nextRaw = body.next;
+
+    // Step 2: honeypot — exempt short-circuit (no sham work)
+    if (typeof honeypot === 'string' && honeypot.length > 0) {
+      sameResponse(res, emailRaw, nextRaw);
+      return;
+    }
+
+    const sourceIp = determineSourceIp(req, trustedProxies);
+    const result = await runSendLink({ emailRaw, nextRaw, sourceIp });
+    sameResponse(res, result.emailNorm, result.nextValidated ?? '');
+  }
+
+  async function startLogin({ email, nextUrl, sourceIp = '' } = {}) {
+    // Programmer-error guards (AF-7.3). These DO throw; they're not
+    // silent-miss conditions, they're "you called the API wrong."
+    if (typeof email !== 'string' || email.length === 0) {
+      throw new Error('startLogin: email is required (string)');
+    }
+    if (nextUrl !== undefined && nextUrl !== null && typeof nextUrl !== 'string') {
+      throw new Error('startLogin: nextUrl must be a string when provided');
+    }
+    if (typeof sourceIp !== 'string') {
+      throw new Error('startLogin: sourceIp must be a string when provided');
+    }
+    const { handle } = await runSendLink({
+      emailRaw: email,
+      nextRaw: nextUrl ?? null,
+      sourceIp,
+    });
+    // Same-shape return: rate-limit / sham / real all collapse here.
+    // `handle` is the HMAC of the normalized email (or null if email
+    // was malformed). It leaks nothing about existence per FR-6.
+    return { handle, submitted: true };
   }
 
   async function callback(req, res) {
@@ -453,6 +532,7 @@ export function createHandlers({ store, mailer, config }) {
     logout,
     loginForm,
     handleFromRequest,
+    startLogin,
     validateNextUrl: (raw) => validateNextUrl(raw, cfg.baseUrl, cfg.cookieDomain),
     // exposed for tests
     _config: cfg,

package/src/index.js

@@ -1,6 +1,7 @@
 import { createStore } from './store.js';
-import { createMailer } from './mailer.js';
+import { createMailer, validateBodyFooter } from './mailer.js';
 import { createHandlers } from './handlers.js';
+import { deriveHandle as deriveHandleRaw } from './handle.js';
 
 /** Default sweeper tick: 5 minutes. Per FR-13. */
 const DEFAULT_SWEEP_INTERVAL_MS = 5 * 60 * 1000;
@@ -72,8 +73,12 @@ export function knowless(options = {}) {
   for (const f of REQUIRED_FIELDS) {
     if (!options[f]) throw new Error(`knowless: ${f} is required`);
   }
-  if (typeof options.secret !== 'string' || options.secret.length < 64) {
-    throw new Error('knowless: secret must be at least 64 hex chars (32 bytes)');
+  if (typeof options.secret !== 'string' || !/^[a-f0-9]{64,}$/i.test(options.secret)) {
+    throw new Error('knowless: secret must be at least 64 hex chars (32 bytes, lowercase a-f, 0-9)');
+  }
+  // Validate operator-supplied body footer at startup (AF-8.2).
+  if (options.bodyFooter !== undefined && options.bodyFooter !== null) {
+    validateBodyFooter(options.bodyFooter);
   }
 
   // SPEC §5.4: cookieSecure: false is allowed only for localhost dev.
@@ -141,6 +146,16 @@ export function knowless(options = {}) {
      *  "Log out everywhere." Returns the number of sessions removed.
      *  AF-6.1. */
     revokeSessions: (handle) => store.revokeSessions(handle),
+    /** Programmatic magic-link send. Use this for "use first, claim
+     *  later" UX flows (drop a pin, post a comment, then confirm via
+     *  email). Returns `{handle, submitted: true}` — same shape on
+     *  rate-limit / sham / real to preserve FR-6 timing equivalence.
+     *  See SPEC §7.3a. AF-7.3. */
+    startLogin: handlers.startLogin,
+    /** Derive the opaque handle for an email using the configured
+     *  secret. Lets adopters compute owner-handles outside HTTP context
+     *  without spreading the secret across modules. AF-7.4. */
+    deriveHandle: (email) => deriveHandleRaw(email, options.secret),
     /** Effective config (with defaults applied), useful for routing. */
     config: handlers._config,
     /** Run a sweep tick on demand. Useful for tests and operator scripts. */
@@ -158,7 +173,7 @@ export function knowless(options = {}) {
 }
 
 export { createStore } from './store.js';
-export { createMailer, composeBody, validateSubject } from './mailer.js';
+export { createMailer, composeBody, validateSubject, validateBodyFooter } from './mailer.js';
 export { createHandlers } from './handlers.js';
 export { renderLoginForm } from './form.js';
-export { normalize, deriveHandle } from './handle.js';
+export { normalize, deriveHandle, secretBytes } from './handle.js';

package/src/mailer.js

@@ -52,6 +52,39 @@ function composeRaw({ from, to, subject, body }) {
   return `${headers}\r\n\r\n${normalized}`;
 }
 
+/**
+ * Validate an operator-supplied body footer per AF-8.2.
+ *
+ * Constraints (deliberately strict to preserve the URL-line invariant
+ * and 7bit body encoding from the v0.11 POC finding):
+ *   - ASCII only
+ *   - ≤ 240 chars
+ *   - No CR (LF allowed; line count ≤ 4)
+ *   - No `http://` / `https://` substring (avoids URL-line confusion
+ *     and avoids triggering MTA URL-rewriting heuristics)
+ *
+ * Throws on any violation. Returns the (already-trimmed) footer.
+ *
+ * @param {unknown} footer
+ * @returns {string|null}
+ */
+export function validateBodyFooter(footer) {
+  if (footer == null || footer === '') return null;
+  if (typeof footer !== 'string') {
+    throw new Error('bodyFooter must be a string');
+  }
+  if (footer.length > 240) throw new Error('bodyFooter must be ≤ 240 chars');
+  if (!ASCII_RE.test(footer)) throw new Error('bodyFooter must be ASCII');
+  if (footer.includes('\r')) throw new Error('bodyFooter must not contain CR');
+  if (footer.split('\n').length > 4) {
+    throw new Error('bodyFooter must be ≤ 4 lines');
+  }
+  if (/https?:\/\//i.test(footer)) {
+    throw new Error('bodyFooter must not contain URLs (would conflict with the magic-link line)');
+  }
+  return footer;
+}
+
 /**
  * Compose the plain-text body of the magic-link email per SPEC §12.2.
  *
@@ -68,6 +101,11 @@ function composeRaw({ from, to, subject, body }) {
  *   Last sign-in: <ISO 8601 UTC timestamp>.
  *   If that wasn't you, do not click the link above.
  *
+ * Plus, when bodyFooter is provided (AF-8.2):
+ *
+ *   --
+ *   <footer text>
+ *
  * The URL appears on its own line. Body is ASCII-only.
  *
  * @param {object} args
@@ -75,9 +113,10 @@ function composeRaw({ from, to, subject, body }) {
  * @param {string} args.baseUrl   e.g. 'https://app.example.com'
  * @param {string} args.linkPath  e.g. '/auth/callback'
  * @param {number|null} [args.lastLoginAt] Unix ms; null/undefined to omit
+ * @param {string|null} [args.bodyFooter] operator footer; pre-validated
  * @returns {string} the body text (ASCII)
  */
-export function composeBody({ tokenRaw, baseUrl, linkPath, lastLoginAt }) {
+export function composeBody({ tokenRaw, baseUrl, linkPath, lastLoginAt, bodyFooter }) {
   const url = `${baseUrl}${linkPath}?t=${tokenRaw}`;
   let body =
     'Click to sign in:\n\n' +
@@ -89,6 +128,11 @@ export function composeBody({ tokenRaw, baseUrl, linkPath, lastLoginAt }) {
     body +=
       `\nLast sign-in: ${iso}.\n` + 'If that wasn\'t you, do not click the link above.\n';
   }
+  if (bodyFooter) {
+    // Standard email signature delimiter: "-- " (dash-dash-space) on
+    // its own line. Mail clients strip this section from quoted replies.
+    body += `\n-- \n${bodyFooter}\n`;
+  }
   if (!ASCII_RE.test(body)) {
     throw new Error('mail body contains non-ASCII');
   }
@@ -151,6 +195,18 @@ export function createMailer(cfg) {
       auth: undefined,
     });
 
+  // AF-7.5: validate the resolved transport at startup. Without this,
+  // a malformed transportOverride (or a bare options bag mistaken for a
+  // transport) silently constructs something that throws "sendMail is
+  // not a function" only at first submission — which in production may
+  // be hours later. Fail fast at factory time instead.
+  if (typeof transport.sendMail !== 'function') {
+    throw new Error(
+      'mailer: transport has no sendMail() — if you passed transportOverride, ' +
+        'pass the result of nodemailer.createTransport(opts), not an opts bag.',
+    );
+  }
+
   return {
     async submit({ to, subject, body }) {
       if (typeof to !== 'string' || !ASCII_RE.test(to)) {

package/src/session.js

@@ -1,4 +1,5 @@
 import crypto from 'node:crypto';
+import { secretBytes } from './handle.js';
 
 /**
  * Domain-separation tag for session signatures. See SPEC §3.4 / §5.2.
@@ -22,7 +23,7 @@ export function newSid() {
  */
 function signature(sidB64u, secret) {
   return crypto
-    .createHmac('sha256', secret)
+    .createHmac('sha256', secretBytes(secret))
     .update(SESS_TAG)
     .update(sidB64u, 'utf8')
     .digest('hex');
@@ -40,9 +41,6 @@ export function signSession(sidB64u, secret) {
   if (typeof sidB64u !== 'string' || !/^[A-Za-z0-9_-]+$/.test(sidB64u)) {
     throw new Error('invalid sid');
   }
-  if (!secret || (typeof secret !== 'string' && !Buffer.isBuffer(secret))) {
-    throw new Error('secret required');
-  }
   return `${sidB64u}.${signature(sidB64u, secret)}`;
 }