knowless 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -8,6 +8,87 @@ Versioning is [SemVer](https://semver.org/).
 ## [Unreleased]
 
 - Caddy forward-auth Docker integration test (TASKS.md 6.8).
+
+## [0.1.7] — 2026-04-28
+
+addypin integration round 3 — one small API addition.
+
+### Added
+
+- **`subjectOverride` arg on `auth.startLogin`.** Per-call subject
+  replaces the factory `subject` for that one mail. Validated by
+  the same rules (ASCII, ≤60 chars, no CR/LF) and throws on invalid
+  — programmer error, not silent miss. The subject is decided
+  before the hit/miss branch, so sham and real submissions carry
+  the same subject and no observer can distinguish outcomes by
+  subject. Spam-trigger warnings (`!!`, `FREE`, etc.) do not throw;
+  the caller has more context. Closes AF-9.1.
+
+  Example: addypin sends three magic-link variants with distinct
+  subjects:
+
+  ```js
+  await auth.startLogin({
+    email, nextUrl, sourceIp,
+    subjectOverride: `Confirm your pin: ${shortcode}`,
+  });
+  ```
+
+## [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

package/GUIDE.md

@@ -267,11 +267,14 @@ share link," "submit a paste" — patterns where forcing a login
 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
+  const shortcode = await db.insertPendingPin({ owner, lat, lng });
   await auth.startLogin({                          // AF-7.3
     email,
     nextUrl: 'https://app.example.com/manage',
     sourceIp: req.socket.remoteAddress,
+    // Per-call subject so the user can tell at a glance this is a
+    // pin-confirmation, not a routine login. AF-9.
+    subjectOverride: `Confirm your pin: ${shortcode}`,
   });
   res.status(202).end();  // "we'll email you the link"
 });

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.4 | Node.js >= 20 | 2 deps (nodemailer, better-sqlite3) | Apache-2.0
+> v0.1.7 | Node.js >= 20 | 2 deps (nodemailer, better-sqlite3) | Apache-2.0
 
 ## What this is
 

package/knowless.context.md

@@ -102,6 +102,12 @@ const auth = knowless({
   // ^ 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
@@ -141,7 +147,7 @@ const auth = knowless({
 | `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. |
+| `startLogin` | ({email, nextUrl?, sourceIp?, subjectOverride?}) | Promise\<{handle, submitted: true}\> | Programmatic magic-link send for "use first, claim later" flows. Same 12-step sham-work as form. `subjectOverride` (AF-9) replaces `cfg.subject` for this call. 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) |
@@ -157,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';
 ```
 
@@ -459,6 +467,19 @@ rate-limits) belongs above the library.
     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.5",
+  "version": "0.1.7",
   "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

@@ -2,7 +2,7 @@ import crypto from 'node:crypto';
 import { normalize, deriveHandle } from './handle.js';
 import { issueToken, hashToken } from './token.js';
 import { newSid, signSession, verifySessionSignature } from './session.js';
-import { composeBody } from './mailer.js';
+import { composeBody, validateSubject } from './mailer.js';
 import { renderLoginForm } from './form.js';
 import {
   buildTrustedPeers,
@@ -243,7 +243,7 @@ export function createHandlers({ store, mailer, config }) {
    *   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 }) {
+  async function runSendLink({ emailRaw, nextRaw, sourceIp, subject }) {
     // Step 1: parse + normalize
     let emailNorm;
     try {
@@ -319,10 +319,17 @@ export function createHandlers({ store, mailer, config }) {
       baseUrl: cfg.baseUrl,
       linkPath: cfg.linkPath,
       lastLoginAt,
+      bodyFooter: cfg.bodyFooter,
     });
 
+    // AF-9: programmatic callers may override the subject per call
+    // (addypin sends confirmation / login / expiry-warning all via
+    // magic links and needs distinct subjects). Decision happens
+    // BEFORE the hit/miss branch — same subject for sham and real,
+    // so timing equivalence is preserved.
+    const effectiveSubject = subject ?? cfg.subject;
     try {
-      await mailer.submit({ to: toAddress, subject: cfg.subject, body: mailBody });
+      await mailer.submit({ to: toAddress, subject: effectiveSubject, body: mailBody });
     } catch (err) {
       // Per NFR-10: SMTP failure logged, NEVER leaked to response shape.
       console.error('[knowless] mail submit failed:', err.message);
@@ -392,7 +399,12 @@ export function createHandlers({ store, mailer, config }) {
     sameResponse(res, result.emailNorm, result.nextValidated ?? '');
   }
 
-  async function startLogin({ email, nextUrl, sourceIp = '' } = {}) {
+  async function startLogin({
+    email,
+    nextUrl,
+    sourceIp = '',
+    subjectOverride,
+  } = {}) {
     // 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) {
@@ -404,10 +416,21 @@ export function createHandlers({ store, mailer, config }) {
     if (typeof sourceIp !== 'string') {
       throw new Error('startLogin: sourceIp must be a string when provided');
     }
+    // AF-9: per-call subject override. Validated with the same rules as
+    // the factory subject (ASCII, ≤60 chars, no CR/LF). Throws on
+    // invalid — same "programmer-error" treatment as other startLogin
+    // arg validation. Spam-trigger warnings are NOT thrown for; the
+    // caller has more context than knowless about what's appropriate.
+    let subject;
+    if (subjectOverride !== undefined && subjectOverride !== null) {
+      validateSubject(subjectOverride); // throws on invalid
+      subject = subjectOverride;
+    }
     const { handle } = await runSendLink({
       emailRaw: email,
       nextRaw: nextUrl ?? null,
       sourceIp,
+      subject,
     });
     // Same-shape return: rate-limit / sham / real all collapse here.
     // `handle` is the HMAC of the normalized email (or null if email

package/src/index.js

@@ -1,5 +1,5 @@
 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';
 
@@ -73,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.
@@ -169,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');
   }

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)}`;
 }