knowless 0.1.5 → 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

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.6 | 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
@@ -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.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

@@ -319,6 +319,7 @@ export function createHandlers({ store, mailer, config }) {
       baseUrl: cfg.baseUrl,
       linkPath: cfg.linkPath,
       lastLoginAt,
+      bodyFooter: cfg.bodyFooter,
     });
 
     try {

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