knowless 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -12,6 +12,12 @@ Versioning is [SemVer](https://semver.org/).
   auth+mail layer. ~1,150 LOC of bespoke auth/mail code removed,
   ~35 LOC of knowless wiring added (~33× reduction). Drove audit
   findings AF-7 → AF-17 across v0.1.5–v0.1.10.
+- **2026-05-02 — Three adopters in production.** plato (Mode B,
+  forum) and gitdone (Mode A, multi-party email workflows) joined
+  addypin (Mode A, location sharing). gitdone's pre-merge review
+  surfaced the "wrong-shape integration" failure mode (parallel
+  tokens table + manual session minting alongside knowless instead
+  of `auth.startLogin`). Patched docs in v1.1.1; no API change.
 
 ## [Unreleased]
 
@@ -24,6 +30,56 @@ v1.0.0 are:
 - Documentation corrections
 - Helper exports that pull existing mechanism back into the library
 
+## [1.1.2] — 2026-05-03
+
+Documentation-only release. Adopters were repeatedly missing that
+`auth.loginForm` is an unstyled contract-minimal fallback they
+should override, and that `/login` is also where every silent-miss
+failure (used / expired / sham / malformed token) redirects — so
+the page deserves first-class UI in the host app, not the bundled
+default. No code changes.
+
+### Documented
+
+- `GUIDE.md` FAQ — added section "Branding the GET /login page
+  (you almost certainly want to override it)" with the three
+  reasons (brand consistency, silent-miss redirect target, opt-in
+  fallback) and the override pattern. Extended the existing
+  custom-form contract with `next` validation against
+  `baseUrl` + `cookieDomain` and the optional honeypot field name
+  from `cfg.honeypotFieldName`.
+- `knowless.context.md` gotcha #10 — expanded the "operators
+  wanting branding fork the project" note to surface the more
+  common path (skip mounting `auth.loginForm`, serve your own
+  `GET /login`) and call out that `/login` is the silent-miss
+  redirect target.
+
+## [1.1.1] — 2026-05-02
+
+Documentation-only release. Adds the wrong-shape-integration
+anti-pattern callout that gitdone's pre-merge review surfaced, and
+records plato + gitdone as the second and third production adopters.
+No code changes.
+
+### Documented
+
+- `README.md` — replaced "Sibling projects" with an "Adopters"
+  section explicitly listing addypin (Mode A), plato (Mode B), and
+  gitdone (Mode A) with a pointer that addypin and gitdone are the
+  Mode A worked references.
+- `GUIDE.md` § "Two adoption modes" — added an anti-pattern callout
+  at the top: if you're considering writing pending rows to a
+  custom tokens table or minting your own confirmation links, that's
+  Mode A and `auth.startLogin({ subjectOverride, bodyOverride })`
+  already does it. Includes a side-by-side wrong-shape vs Mode A
+  sketch. Surfaced by gitdone's pre-merge review where a parallel
+  activation system was built before the existing Mode A flow was
+  noticed.
+- `GUIDE.md` Mode A/B sub-headings — appended the API entrypoint
+  (`auth.startLogin` for Mode A, `auth.login` for Mode B) so the
+  use-case leads and `startLogin` doesn't read as "login button
+  click."
+
 ## [1.1.0] — 2026-05-02
 
 Mailer-contract clarification release. Pulls FR-6 sham-routing

package/GUIDE.md

@@ -286,7 +286,31 @@ both out of the box; pick per-action, not per-app — they coexist.
 The Mode A/B labels are used here and in the CHANGELOG so
 discussions across the docs stay unambiguous.
 
-**Mode B — "sign in, then do the thing" (register-first, the default).**
+> ⚠ **Stop before you build a parallel activation system.** If
+> you're considering writing pending rows to a custom tokens table,
+> minting your own confirmation links, or calling into the sessions
+> table directly to mark an account "activated by email" — that is
+> Mode A, and it's already in this library. Use
+> `auth.startLogin({ email, subjectOverride, bodyOverride })` and
+> promote your pending resource in the callback handler. The
+> wrong-shape integration is what every adopter has tried first; the
+> right shape is the worked example below.
+
+The wrong shape vs Mode A, side by side:
+
+```
+WRONG SHAPE                         MODE A (use auth.startLogin)
+─────────────────────────────       ─────────────────────────────
+your_tokens table                   (none — knowless owns the token)
+your custom email composer          subjectOverride + bodyOverride
+your /confirm/:token handler        auth.callback (already mounted)
+manual session insert               handled by callback
+your duplicate rate-limit code      knowless rate-limit applies
+                                    sham-work + timing equivalence
+                                    preserved automatically
+```
+
+**Mode B — "sign in, then do the thing" (register-first, the default, `auth.login`).**
 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
@@ -301,7 +325,7 @@ app.post('/api/comments', (req, res) => {
 });
 ```
 
-**Mode A — "do the thing, confirm by email" (use-first, claim-later).**
+**Mode A — "do the thing, confirm by email" (use-first, claim-later, `auth.startLogin`).**
 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
@@ -905,7 +929,48 @@ own form, provided it satisfies the handler contract:
   stream itself. A body-parser middleware mounted before `auth.login`
   will silently steal the data (see gotcha #15 in
   [`knowless.context.md`](knowless.context.md)).
-- Optional: include a `next` field for the post-callback redirect URL.
+- Optional: include a `next` field for the post-callback redirect URL
+  (knowless validates `next` against `baseUrl` + `cookieDomain`).
+- Optional but recommended: include the honeypot field using the name
+  from `cfg.honeypotFieldName`.
+
+### Branding the GET /login page (you almost certainly want to override it)
+
+Knowless ships `auth.loginForm(req, res)` as a turnkey fallback so
+adopters can wire `GET /login` in one line and have a working magic-link
+form. The page is intentionally unstyled — it's the contract-minimal
+renderer needed to make the flow demonstrable, not a UI you ship to
+end users. Three reasons most adopters override it:
+
+1. **Brand consistency.** The fallback page has no header, footer, nav,
+   or styling, so users redirected here from elsewhere in your app land
+   on what looks like a different site. That's especially jarring after
+   a sham-token failure (a deliberate part of the silent-miss design —
+   see "Silent miss" in [`knowless.context.md`](knowless.context.md)),
+   where a user clicked a magic link and ended up on a "Sign in" page
+   that looks unrelated to where they started.
+2. **`/login` is load-bearing in the silent-miss contract.** Knowless
+   redirects to `loginPath` on every failure mode that must be
+   indistinguishable from success — used token, expired token, sham
+   token, malformed token. That redirect is correct and required. But
+   it means `/login` is the page users actually land on during
+   anti-enumeration failures, not just the page they navigate to
+   deliberately. It deserves first-class UI in your app.
+3. **`auth.loginForm` is opt-in, not opt-out.** Adopters who never wire
+   the GET route still get a working app — just without a friendly
+   `/login` page. Override it whenever you want your app's chrome on
+   the page. The POST handler can stay as-is (or also be wrapped — for
+   example, plato wraps it for the "we sent a link" confirmation).
+
+Override pattern (mount your own handler instead of `auth.loginForm`):
+
+```js
+app.get('/login', (req, res) => renderMyOwnLogin(req, res));
+app.post('/login', auth.login);  // unchanged
+```
+
+The form just needs to satisfy the contract listed in the previous
+question.
 
 ### How do I add 2FA / WebAuthn / TOTP?
 

package/README.md

@@ -148,12 +148,21 @@ rate-limits) belong above the library — patterns in
 Full detail in [`knowless.context.md`](knowless.context.md) §
 "Threat model summary."
 
-## Sibling projects
+## Adopters
 
-- [`addypin`](https://github.com/hamr0/addypin) — location sharing,
-  first knowless adopter
-- [`gitdone`](https://github.com/hamr0/gitdone) — verified email
-  actions via DKIM/SPF inbound
+Production users of knowless, in adoption order:
+
+- [`addypin`](https://github.com/hamr0/addypin) — pin-drop location
+  sharing. First knowless adopter; Mode A (drop-pin-then-confirm).
+- [`plato`](https://github.com/hamr0/plato) — forum (Reddit-shaped,
+  one fingerprint per site). Mode B (sign-in-then-do).
+- [`gitdone`](https://github.com/hamr0/gitdone) — multi-party email
+  workflows verified via DKIM/SPF inbound. Mode A
+  (start-workflow-then-confirm).
+
+If you're picking knowless up: the addypin and gitdone callsites are
+both Mode A and good worked references for the use-first / claim-later
+shape.
 
 ## License
 

package/knowless.context.md

@@ -699,7 +699,13 @@ rate-limits) belongs above the library.
 10. **No JavaScript in any HTML page.** The login form, the
     confirmation page, error pages — all static HTML5. Works in
     text-mode browsers (Lynx, w3m). Operators wanting branding
-    fork the project.
+    fork the project — **or, more commonly, skip mounting
+    `auth.loginForm` and serve their own `GET /login`**. The
+    fallback is intentionally a contract-minimal renderer, not a
+    UI to ship. `/login` is also where every silent-miss failure
+    redirects (used / expired / sham / malformed token), so it
+    deserves first-class chrome in the host app. See GUIDE.md
+    § "Branding the GET /login page".
 
 11. **Process cleanup matters.** `auth.close()` stops the
     sweeper and closes the SQLite handle. Without it, your

package/package.json

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