knowless 1.1.4 → 1.1.5

package/CHANGELOG.md

@@ -30,6 +30,41 @@ v1.0.0 are:
 - Documentation corrections
 - Helper exports that pull existing mechanism back into the library
 
+## [1.1.5] — 2026-05-09
+
+Documentation-only release. plato (Mode A adopter) hit a real seam
+under `bodyOverride`: they want to reorder the body (expiry warning
+before URL) AND keep the "Last sign-in" security signal. The current
+contract drops the line under override — deliberately, since override
+is full-content replacement — and that read as a missing capability.
+It isn't: `auth.deriveHandle(email)` and a parallel `createStore`
+handle calling `getLastLogin(handle)` already give adopters everything
+they need to compose the signal themselves. The gap was discoverability,
+not surface area. Considered exporting a `formatLastLogin` helper to
+centralize the canonical wording across adopters; held off under the
+walk-away default-no, since the population that hits the
+override + reorder + want-signal intersection is narrow (most
+`bodyOverride` uses are per-call subject branding without a sign-in
+event), and the drift risk for the few who do is small and recoverable.
+Cross-product wording consistency for operators running multiple
+knowless adopters belongs in a shared module on the operator side, not
+in knowless. Revisit if a second independent adopter asks for the
+helper. No code changes.
+
+### Documented
+
+- `GUIDE.md` Mode A walkthrough — added a "Composing the 'Last
+  sign-in' security signal under `bodyOverride`" callout right after
+  the `auth.deriveHandle` paragraph. Explains why the line doesn't
+  auto-append on overridden bodies (override is full-content
+  replacement, AF-26), points at the existing recipe
+  (`auth.deriveHandle` + parallel `createStore` + `getLastLogin`),
+  notes that `upsertLastLogin` only fires on callback consumption so
+  a pre-call read matches what knowless reads internally, and
+  includes a worked example. Targeted at adopters who reorder the
+  body and want the signal back; default-path adopters (no override)
+  are unaffected.
+
 ## [1.1.4] — 2026-05-08
 
 Documentation + small bug fix. Adopters (plato, addypin, bareagent,

package/GUIDE.md

@@ -384,6 +384,39 @@ and `startLogin` would compute. The bare `deriveHandle` re-export
 takes pre-normalized input; use the instance method unless you
 have a specific reason to call the lower-level primitive.
 
+> **Composing the "Last sign-in" security signal under
+> `bodyOverride`.** The default last-sign-in line lives in
+> `composeBody` and does **not** auto-append on overridden bodies —
+> override is full-content replacement (handlers.js AF-26). If your
+> override needs the same signal, look up the timestamp before
+> calling `startLogin` and interpolate it yourself. Everything you
+> need is already exported: `auth.deriveHandle(email)` returns the
+> handle, and a parallel read-only `createStore(dbPath)` exposes
+> `getLastLogin(handle)` (Unix ms when the handle exists, `null` for
+> sham / new / opted-out). `upsertLastLogin` only fires on callback
+> consumption, so a pre-call read returns the same value knowless
+> reads internally. Wording stays your responsibility under override —
+> small drift cost for taking the wheel.
+>
+> ```js
+> import { createStore } from 'knowless';
+> const store = createStore(process.env.KNOWLESS_DB_PATH);
+> // ... in your request handler ...
+> const handle = auth.deriveHandle(email);
+> const lastLoginAt = store.getLastLogin(handle); // null for sham/new
+> await auth.startLogin({
+>   email,
+>   bodyOverride: ({ url }) =>
+>     `Click to sign in:\n\n${url}\n\n` +
+>     `This link expires in 15 minutes. If you didn't request this,\n` +
+>     `ignore this email.\n` +
+>     (lastLoginAt != null
+>       ? `\nLast sign-in: ${new Date(lastLoginAt).toISOString()}.\n` +
+>         `If that wasn't you, do not click the link above.\n`
+>       : ''),
+> });
+> ```
+
 > **Set `failureRedirect: '/'` — it's part of the silent-miss
 > contract, not just a UX knob.** The default falls back to
 > `loginPath` (typically `/login`). That's a partial enumeration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knowless",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "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",