knowless 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -9,6 +9,31 @@ Versioning is [SemVer](https://semver.org/).
 
 - 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)

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

@@ -147,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) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knowless",
-  "version": "0.1.6",
+  "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/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 {
@@ -322,8 +322,14 @@ export function createHandlers({ store, mailer, config }) {
       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);
@@ -393,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) {
@@ -405,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