knowless 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -9,6 +9,62 @@ 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.
+
+### 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"
 });
@@ -332,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.6 | 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?}) | 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?, 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.6",
+  "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

@@ -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, 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,
@@ -322,8 +327,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);
@@ -347,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 };
   }
@@ -393,7 +406,13 @@ 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,
+    bypassRateLimit = false,
+  } = {}) {
     // 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 +424,25 @@ 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
+    // 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,
+      bypassRateLimit,
     });
     // Same-shape return: rate-limit / sham / real all collapse here.
     // `handle` is the HMAC of the normalized email (or null if email