knowless 0.1.7 → 0.1.8

package/CHANGELOG.md

@@ -9,6 +9,37 @@ Versioning is [SemVer](https://semver.org/).
 
 - Caddy forward-auth Docker integration test (TASKS.md 6.8).
 
+## [0.1.8] — 2026-04-28
+
+addypin round 4 — one small API addition + documentation polish.
+
+### Added
+
+- **`bypassRateLimit: true` arg on `auth.startLogin` (AF-10).**
+  Trusted server-side callers (CLI workers, cron jobs, internal
+  services on the same host as the web process) opt out of IP-
+  based rate-limit accounting entirely — neither check nor
+  increment for the `login_ip` and `create_ip` buckets. The per-
+  handle token cap (`maxActiveTokensPerHandle`) is still enforced.
+  Solves the "web + CLI sharing 127.0.0.1" starvation problem
+  without requiring config divergence between processes. Throws
+  on non-boolean. Do NOT plumb this from unauthenticated user
+  input.
+
+### Documentation
+
+- **GUIDE Step 6 rewrite (AF-11).** `auth.handleFromRequest(req)`
+  is now front-and-centre as the load-bearing primitive for
+  adopter authorization. Worked Express-style examples for
+  `requireAuth` middleware and per-handle CRUD gating. Replaces
+  the previous "(coming in v0.2.0)" placeholder with the v0.1.1
+  reality.
+- **OPS.md §11a "Multi-process deployments" (AF-12).** Half-page
+  guide covering when sharing one DB across processes is safe
+  (WAL mode, default), sweeper redundancy semantics, rate-limit
+  enforcement-vs-accounting under sharing (and why AF-10
+  matters), `auth.close()` behavior, and the cross-machine no-go.
+
 ## [0.1.7] — 2026-04-28
 
 addypin integration round 3 — one small API addition.

package/GUIDE.md

@@ -335,25 +335,54 @@ const auth = knowless({ ..., openRegistration: true });
 Note that open registration adds a per-IP cap on new handles
 (default 3/hour) to mitigate signup spam.
 
-### Step 6: Use sessions in your app
+### Step 6: Use sessions in your app — `auth.handleFromRequest`
 
-After `/auth/callback` succeeds, the user has a session cookie.
-Read it on every protected request:
+After `/auth/callback` succeeds, the user has a session cookie. To
+gate your own protected endpoints, call `auth.handleFromRequest(req)`:
+it returns the requesting session's opaque handle (64-char hex), or
+`null` when the cookie is missing, malformed, or expired. **This is
+the load-bearing primitive for adopter authorization.** The five
+mounted handlers (`login`, `callback`, `verify`, `logout`, `loginForm`)
+own the auth round-trip; everything *else* in your app uses
+`handleFromRequest`.
 
 ```js
+// Express-shaped middleware. Same pattern works in Hono / Fastify /
+// node:http — handleFromRequest takes a node-shaped req and returns
+// a string or null synchronously. No async, no DB hop beyond the
+// session lookup.
 function requireAuth(req, res, next) {
-  // Use auth.verify() in a sub-request shape, or read the cookie
-  // and call into the store. Simplest pattern:
-  // Mount a middleware that calls the verify handler against the
-  // request and checks the result.
-  // (Cleaner pattern coming in v0.2.0 with a middleware factory.)
+  const handle = auth.handleFromRequest(req);
+  if (!handle) {
+    res.statusCode = 401;
+    return res.end('unauthorized');
+  }
+  req.handle = handle;
   next();
 }
+
+// Then on every protected endpoint:
+app.get('/api/pins', requireAuth, (req, res) => {
+  const pins = db.findPinsByOwner(req.handle); // owner_handle = req.handle
+  res.json(pins);
+});
+
+app.delete('/api/pins/:id', requireAuth, (req, res) => {
+  const pin = db.getPin(req.params.id);
+  if (pin.owner_handle !== req.handle) {
+    res.statusCode = 403;
+    return res.end('forbidden');
+  }
+  db.deletePin(req.params.id);
+  res.end();
+});
 ```
 
-For now, the friendliest pattern: route a dedicated `/me` endpoint
-through `auth.verify` and have the rest of your app fetch it on
-mount.
+The `verify` handler is for **forward-auth deployments** (your
+reverse proxy gates upstreams via `/verify` returning 200/401 +
+`X-User-Handle`). For in-process middleware, prefer
+`handleFromRequest` — same answer, no sub-request round-trip, no
+header parsing.
 
 ### Step 7: GDPR right-to-erasure
 

package/OPS.md

@@ -540,6 +540,55 @@ in that order — most spam-folder verdicts trace to one of those four.
 
 ---
 
+## 11a. Multi-process deployments (web + worker / CLI)
+
+Multiple processes can share one knowless SQLite file. This is a
+common adopter pattern: a long-running web server plus a per-message
+CLI invoked by Postfix's `pipe` transport, or a web server plus a
+cron worker handling 48h reminders. Each process instantiates
+`knowless({...})` against the same `dbPath`.
+
+**Why this works.** `better-sqlite3` opens the database in WAL mode
+by default (knowless explicitly sets `journal_mode=WAL` at startup).
+WAL allows multiple readers and one writer concurrently, with the
+OS-level locking semantics needed for cross-process safety. Every
+write goes through a prepared statement under a SQLite transaction,
+so two processes inserting tokens or sessions at the same time can't
+corrupt the table.
+
+**What to know about each subsystem under multi-process:**
+
+- **Sweeper redundancy is harmless.** Each process runs its own 5-
+  minute sweep tick. The DELETE statements are idempotent — once
+  one process has deleted a row, the others' DELETEs simply affect
+  zero rows. No coordination needed.
+- **Rate-limit rows are shared but enforcement is per-process.**
+  All processes read and write the same `rate_limits` table, so
+  counter values are consistent. But each process makes its own
+  *enforcement* decision against its own configured cap. This
+  matters: a CLI worker calling `auth.startLogin` from `127.0.0.1`
+  uses the same `login_ip` bucket as web traffic from `127.0.0.1`.
+  Trusted CLI callers should pass `bypassRateLimit: true` to
+  `startLogin` (AF-10) so they don't starve the shared bucket and
+  don't participate in accounting.
+- **`auth.close()` from one process doesn't affect the others.**
+  Each process holds its own connection. Closing one is the right
+  thing to do at that process's shutdown; the database remains
+  open for the others.
+- **Magic-link tokens and session IDs are globally unique.** The
+  random-byte primitives have enough entropy that two processes
+  minting tokens concurrently won't collide (43-char base64url =
+  256 bits).
+
+**Don't share the DB across machines.** SQLite WAL only protects
+processes on the same host (it relies on POSIX advisory locks).
+For a multi-host knowless deployment, run a single instance behind
+a load balancer or — better — run one knowless per host, each
+with its own DB. Sessions are per-host but that's usually what you
+want for forward-auth-style deployments anyway.
+
+---
+
 ## 12. Backup and recovery
 
 The only stateful file is the SQLite database (`KNOWLESS_DB_PATH`,

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.7 | Node.js >= 20 | 2 deps (nodemailer, better-sqlite3) | Apache-2.0
+> v0.1.8 | 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?, 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. |
+| `startLogin` | ({email, nextUrl?, sourceIp?, subjectOverride?, bypassRateLimit?}) | 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` per call. `bypassRateLimit: true` (AF-10) opts trusted server-side callers (CLI, cron, worker) out of IP-rate-limit accounting. 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.7",
+  "version": "0.1.8",
   "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

@@ -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, subject }) {
+  async function runSendLink({ emailRaw, nextRaw, sourceIp, subject, bypassRateLimit = false }) {
     // Step 1: parse + normalize
     let emailNorm;
     try {
@@ -252,8 +252,13 @@ export function createHandlers({ store, mailer, config }) {
       return { handle: null, isSham: false, emailNorm: emailRaw, nextValidated: null };
     }
 
-    // Step 3: per-IP rate limit on /login — exempt short-circuit
+    // Step 3: per-IP rate limit on /login — exempt short-circuit.
+    // AF-10: trusted server-side callers (CLI, cron, worker) opt out
+    // of IP-based rate-limit accounting entirely — neither check nor
+    // increment. Per-handle token cap (insertToken's maxActive) still
+    // applies; only the IP buckets are bypassed.
     if (
+      !bypassRateLimit &&
       rateLimitExceeded(
         store,
         'login_ip',
@@ -271,7 +276,7 @@ export function createHandlers({ store, mailer, config }) {
     const exists = store.handleExists(handle);
     let isCreating = !exists && cfg.openRegistration;
 
-    if (isCreating) {
+    if (isCreating && !bypassRateLimit) {
       if (
         rateLimitExceeded(
           store,
@@ -353,8 +358,10 @@ export function createHandlers({ store, mailer, config }) {
       }
     }
 
-    rateLimitIncrement(store, 'login_ip', sourceIp, HOUR_MS);
-    if (isCreating) rateLimitIncrement(store, 'create_ip', sourceIp, HOUR_MS);
+    if (!bypassRateLimit) {
+      rateLimitIncrement(store, 'login_ip', sourceIp, HOUR_MS);
+      if (isCreating) rateLimitIncrement(store, 'create_ip', sourceIp, HOUR_MS);
+    }
 
     return { handle, isSham, emailNorm, nextValidated };
   }
@@ -404,6 +411,7 @@ export function createHandlers({ store, mailer, config }) {
     nextUrl,
     sourceIp = '',
     subjectOverride,
+    bypassRateLimit = false,
   } = {}) {
     // Programmer-error guards (AF-7.3). These DO throw; they're not
     // silent-miss conditions, they're "you called the API wrong."
@@ -416,6 +424,9 @@ export function createHandlers({ store, mailer, config }) {
     if (typeof sourceIp !== 'string') {
       throw new Error('startLogin: sourceIp must be a string when provided');
     }
+    if (typeof bypassRateLimit !== 'boolean') {
+      throw new Error('startLogin: bypassRateLimit must be a boolean 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
@@ -431,6 +442,7 @@ export function createHandlers({ store, mailer, config }) {
       nextRaw: nextUrl ?? null,
       sourceIp,
       subject,
+      bypassRateLimit,
     });
     // Same-shape return: rate-limit / sham / real all collapse here.
     // `handle` is the HMAC of the normalized email (or null if email