knowless 0.1.9 → 0.1.10

package/CHANGELOG.md

@@ -17,6 +17,32 @@ Versioning is [SemVer](https://semver.org/).
   test message to `shamRecipient` and confirms the local MTA
   discarded it. Targeted for v0.2.0.
 
+## [0.1.10] — 2026-04-28
+
+addypin manual smoke continued. Two DX docs improvements; no code
+changes.
+
+### Documentation
+
+- **GUIDE: "Local development setup" section (AF-16).** Covers the
+  five flags that turn knowless from "production-tuned, defensive"
+  to "developer-friendly, get-out-of-my-way" — `cookieSecure: false`,
+  `devLogMagicLinks: true`, `maxLoginRequestsPerIpPerHour: 0`,
+  `maxNewHandlesPerIpPerHour: 0`, `openRegistration: true`. Each
+  flag explained with what it solves and a sharp warning about
+  shipping it. Considered auto-disabling rate limits whenever
+  `devLogMagicLinks: true` to save typing, but rejected the
+  coupling — operators turning on `devLogMagicLinks` briefly to
+  debug a single email in prod should NOT have rate limits silently
+  dropped at the same time.
+- **GUIDE: silent-miss debug line is now promoted as a feature
+  (AF-17).** The `[knowless dev:<from>] silent-miss: handle for
+  "X" does not exist (openRegistration=false)` stderr hint
+  introduced in AF-7.2 was buried in the CHANGELOG; it now leads
+  the dev-setup section. First-time closed-reg friction was costing
+  every adopter the same ~30 min; the hint cuts that to seconds
+  but only if you know it exists.
+
 ## [0.1.9] — 2026-04-28
 
 addypin manual smoke turned up one real bug, one defaults footgun,

package/GUIDE.md

@@ -398,6 +398,59 @@ reverse proxy gates upstreams via `/verify` returning 200/401 +
 `handleFromRequest` — same answer, no sub-request round-trip, no
 header parsing.
 
+### Local development setup
+
+Production defaults are tuned to bite bots, not to be friendly to a
+developer hammering the same address from `127.0.0.1` for the
+hundredth time. Use a dedicated dev config:
+
+```js
+const auth = knowless({
+  // ...required fields
+  cookieSecure: false,             // localhost-only HTTP origins (AF-4.4)
+  devLogMagicLinks: true,          // print magic links to stderr when SMTP fails (AF-6.2)
+  maxLoginRequestsPerIpPerHour: 0, // disable per-IP login cap
+  maxNewHandlesPerIpPerHour: 0,    // disable per-IP create cap
+  openRegistration: true,          // skip the pre-seeding step in dev
+});
+```
+
+Why each flag matters in dev:
+
+- **`cookieSecure: false`** — without it, `http://localhost` browsers
+  reject the session cookie silently. The library logs a stderr
+  warning at startup so you can't accidentally ship this to prod.
+- **`devLogMagicLinks: true`** — when SMTP is unreachable (no local
+  Postfix yet), magic-link URLs print to stderr tagged
+  `[knowless dev:<from>] magic link: ...`. Click straight from the
+  terminal. **Bonus diagnostic** (AF-7.2): on a sham/silent-miss
+  path, you get `[knowless dev:<from>] silent-miss: handle for
+  "X" does not exist (openRegistration=false)` instead — surfaces
+  the closed-reg gotcha that costs everyone the same 30 minutes
+  the first time.
+- **`maxLoginRequestsPerIpPerHour: 0` and `maxNewHandlesPerIpPerHour:
+  0`** — disable per-IP rate caps. The defaults (30 / 3 per hour)
+  are sane for prod but shoot you in the foot during repeated test
+  runs. The counters **persist in the SQLite file** across process
+  restarts, so even rebooting the dev server doesn't clear them —
+  you'd have to delete the DB or wait an hour. Setting both to 0
+  in dev avoids the surprise.
+- **`openRegistration: true`** — saves you from manually pre-seeding
+  every test email via `auth.deriveHandle` + your own store insert.
+
+> **Don't ship this config.** Each of these flags weakens a specific
+> defense. They are coupled to your environment, not to each other —
+> intentionally. (We considered auto-disabling rate limits whenever
+> `devLogMagicLinks` is true, but rejected: an operator turning on
+> `devLogMagicLinks` to debug a single email in production should
+> NOT have rate limits silently dropped at the same time.)
+
+For end-to-end mail rendering checks (verify the `bodyFooter`,
+inspect the magic-link line for QP soft-breaks, confirm the
+right `subjectOverride` shipped), point dev knowless at MailHog
+on `localhost:1025`. Setup walkthrough lives in
+[`OPS.md` §11b](OPS.md).
+
 ### Step 7: GDPR right-to-erasure
 
 The store interface exposes `deleteHandle(handle)` — atomic delete

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

package/knowless.context.md

@@ -1,7 +1,7 @@
 # knowless -- Integration Guide
 
 > For AI assistants and developers wiring knowless into a project.
-> v0.1.9 | Node.js >= 20 | 2 deps (nodemailer, better-sqlite3) | Apache-2.0
+> v0.1.10 | Node.js >= 20 | 2 deps (nodemailer, better-sqlite3) | Apache-2.0
 
 ## What this is
 

package/package.json

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