knowless 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,142 @@
+# Changelog
+
+All notable changes to `knowless` are recorded here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning is [SemVer](https://semver.org/).
+
+## [Unreleased]
+
+- Standalone server (`bin/knowless-server`): env-var-driven CLI with
+  `--print-config` and `--config-check`, forward-auth deployment shape
+  for self-hosters gating no-auth services. (Tracked in TASKS.md
+  Phase 6.)
+- `OPS.md`: full operator setup walkthrough (Postfix, null-route for
+  sham mail, SPF/DKIM/PTR, reverse-proxy configs for Caddy / nginx /
+  Traefik). (Tracked in TASKS.md Phase 7.)
+
+## [0.1.0] — 2026-04-28
+
+First public release. Library-mode auth flow is complete and
+production-grounded; standalone-server deployment shape ships in 0.2.0.
+
+### Added — library
+
+- `knowless({ secret, baseUrl, from, ... })` factory wires store,
+  mailer, handlers, and a periodic sweeper.
+- Five framework-agnostic HTTP handlers: `login`, `callback`, `verify`,
+  `logout`, `loginForm`. Each is `(req, res) => Promise<void>`,
+  mountable on Express / Fastify / Hono / `node:http`.
+- `deleteHandle(handle)` for GDPR right-to-erasure (FR-37a). Removes
+  the handle, all active tokens, all active sessions, and the
+  `last_login_at` row in one transaction.
+- `close()` stops the sweeper and the SQLite handle for graceful
+  shutdown.
+
+### Added — privacy / security
+
+- **Silent-on-miss with practical timing equivalence (FR-6).** The
+  registered-hit and silent-miss paths are practically
+  indistinguishable: the in-tree timing test (SPEC §14, 1ms
+  delta-mean bar) measures `Δ_mean = 0.002ms` on commodity hardware
+  — 500× under the bar. Achieved via the four-step sham-work
+  pattern in SPEC §7.3.
+- **Sham mail goes to a configurable null-route address** (default
+  `null@knowless.invalid`), not to the unregistered email. Real
+  users never receive unsolicited mail. Operator's MTA discards via
+  `transport_maps`. Documented in OPS.md (forthcoming) and SPEC §7.4.
+- **Plaintext email never persisted.** Handle is `HMAC-SHA256(secret,
+  normalized_email)` per SPEC §3. DB-only leak yields opaque hashes,
+  not a mailing list.
+- **Plain-text 7bit ASCII mail** with the magic-link URL on its own
+  line (FR-17). Sidesteps the v0.11 POC finding that nodemailer's
+  default quoted-printable encoding wraps the URL with `=\n` soft
+  breaks. Implemented by composing the RFC822 message ourselves and
+  using nodemailer only as the SMTP submission transport.
+- **Tokens stored as SHA-256 hashes** at rest (FR-13). 256-bit
+  entropy from `node:crypto.randomBytes`, base64url-encoded raw
+  (43 chars). Single-use; used / expired tokens are swept on a
+  schedule.
+- **Session cookies are signed** with HMAC-SHA256 (`sess\0`
+  domain-separated), `Secure; HttpOnly; SameSite=Lax`. Server-side
+  expiry enforced via stored row; cookie expiry is advisory.
+- **Replay protection** via atomic `markTokenUsed`. Replays return
+  the same response as expired or never-existed.
+- **Forward-auth return URL** via DB-bound `next_url` on the token
+  row (SPEC §11). Same security as URL-signing without bloating the
+  magic link. Cross-domain `next` is silently dropped per the
+  cookie-domain whitelist; `javascript:` and other schemes
+  rejected.
+- **Per-IP and per-handle rate limiting** with safe defaults
+  (FR-38, FR-39, FR-40). Per-IP login cap: 30/hour. Per-handle
+  active token cap: 5 (newest replaces oldest). Per-IP
+  account-creation cap (open-registration only): 3/hour.
+- **Honeypot field** in the login form (FR-41), `aria-hidden="true"`
+  and `tabindex="-1"` so screen-reader users aren't trapped.
+- **No JS, no external resources** in any HTML page (FR-22). Inline
+  CSS only. Login form works in text-mode browsers.
+
+### Added — storage
+
+- `better-sqlite3`-backed store implementing the SPEC §13 interface.
+  WAL journal mode, prepared-statement caching, transactional
+  token issuance with cap-eviction, transactional `deleteHandle`.
+- Periodic sweeper (default 5 min) deletes expired tokens (with
+  24h grace for redeemed ones), expired sessions, and rate-limit
+  rows older than 24h.
+
+### Added — docs
+
+- `docs/01-product/PRD.md` (v0.12) — product requirements.
+- `docs/02-design/SPEC.md` (v0.1) — wire formats, byte layouts,
+  algorithms.
+- `docs/03-tasks/TASKS.md` (v0.1) — 8-phase implementation plan.
+- `README.md`, `GUIDE.md`, `knowless.context.md`, `CHANGELOG.md`.
+
+### Tests
+
+- 102 tests passing on Node 20+ and Node 22+.
+- Testing Trophy: ~50 unit tests (handle, token, session, form,
+  abuse), ~50 integration tests (store, mailer, full-flow,
+  sham-work, forward-auth-next, library-mode), 1 timing test
+  (FR-6 acceptance gate).
+
+### Production deps
+
+- `nodemailer` ^8.0.7 — SMTP submission to localhost MTA.
+- `better-sqlite3` ^11.0.0 — synchronous SQLite via N-API.
+
+Two deps total. Both stable, MIT-licensed, well-maintained.
+
+### Audience
+
+Two primary audiences (PRD §4):
+
+1. **In-app services where auth is the only legitimate email need.**
+   Indie tools, side projects, internal dashboards, member areas,
+   self-hosted apps. Library mode.
+2. **Self-hosters gating services without good auth.** Uptime Kuma,
+   AdGuard Home, Pi-hole, Sonarr, Jellyfin admin, etc. Standalone
+   server mode (ships in 0.2.0).
+
+### Known limitations (deliberate)
+
+- **ASCII-only email addresses** in v0.1. IDN support deferred to
+  0.2 (SPEC §15 Q-5).
+- **Standalone server not yet shipped.** v0.1.0 is library-mode
+  only. Use as `import { knowless } from 'knowless'` and mount
+  the handlers on your existing HTTP framework.
+- **No standalone server `bin/knowless-server`** — that's 0.2.0.
+  Forward-auth deployments wait for 0.2.0 unless you write a small
+  `node:http` wrapper yourself; see GUIDE.md for the ~30-line
+  pattern.
+- **Postfix on localhost is the only outbound mail transport.**
+  No remote SMTP, no Mailgun / Postmark / SES (intentional, see
+  PRD §16.2).
+
+### License
+
+Apache 2.0 with NOTICE preservation. See `LICENSE` and `NOTICE`.
+
+[Unreleased]: https://github.com/hamr0/knowless/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/hamr0/knowless/releases/tag/v0.1.0

package/GUIDE.md

@@ -0,0 +1,441 @@
+# knowless — Adopter Guide
+
+> The "is this for me, and how do I wire it up" doc. For the dense
+> AI-agent reference, see [`knowless.context.md`](knowless.context.md).
+> For the product philosophy, see
+> [`docs/01-product/PRD.md`](docs/01-product/PRD.md).
+
+## Who this is for
+
+Three audiences, in order of fit:
+
+### 1. In-app services where auth is the only legitimate email need
+
+You're building something where users log in, do their work in the
+app, leave. Email is purely the door opener — once they're in, the
+app delivers value through its UI.
+
+Good fits:
+- Web apps and SaaS dashboards (occasional login, work in-app)
+- Indie tools and side projects with infrequent users
+- Small-business B2B internal tools (HR portals, ops dashboards)
+- Member areas, paywalled forums, community sites
+- Self-hosted apps your team uses
+
+The disqualifier isn't service type — it's **email needs**. If you
+genuinely need to send order confirmations, subscription renewals,
+billing notifications, calendar invites, or any digest /
+newsletter, knowless is the wrong choice. Use a vendor with
+deliverability as their core business (Postmark, SES, Mailgun).
+
+### 2. Self-hosters gating services without good native auth
+
+You're running Uptime Kuma, AdGuard Home, Pi-hole, Sonarr, Jellyfin,
+n8n, Homepage, Heimdall, Portainer, Paperless-ngx — and their
+built-in auth is either missing or weak. The existing alternatives
+(Authelia, Authentik, Keycloak, oauth2-proxy) are heavyweight for
+the job: "redirect to login if no cookie, otherwise let through."
+
+knowless's standalone server (v0.2.0, in development) sits behind
+Caddy / nginx / Traefik via forward-auth. One auth subdomain, one
+session cookie scoped to the parent eTLD+1, SSO across all your
+services for free.
+
+### 3. Privacy-skeptical developers building for clients
+
+Small businesses, non-profits, EU operators, healthcare-adjacent,
+legal, education. Where the privacy story is part of the sale.
+knowless gives you a clean, defensible answer to "what data do you
+store about your users?": *an opaque salted hash of their email,
+nothing else*.
+
+## Who this isn't for
+
+- Apps that need to send any email beyond the sign-in link (order
+  confirmations, billing, reminders, digests, newsletters,
+  calendar invites)
+- Apps that need OAuth / OIDC / SAML / federated identity
+- Apps that need integrated 2FA / WebAuthn / TOTP (compose
+  separately if needed)
+- Teams without VPS ops capability — running your own Postfix is
+  real work
+- Anything where email deliverability problems would be
+  catastrophic
+
+## What knowless commits to (so you know what you're getting)
+
+- **Plaintext email is never persisted.** It's salted-hashed
+  (`HMAC-SHA256(secret, normalized_email)`) on the way in and
+  discarded.
+- **Only the magic link is ever sent.** No welcome email. No
+  digest. No notification. The library has no API to send anything
+  else.
+- **All outbound mail goes via your localhost MTA.** No Postmark.
+  No SES. No vendor credentials.
+- **The login flow is timing-equivalent** between registered and
+  unregistered emails — practical-effect-size delta under 1ms,
+  measured by a CI test.
+- **The library is self-contained.** Two npm deps. No build step.
+  Plain ES modules with JSDoc.
+- **Walks away at v1.0.0.** Maintenance mode (security patches +
+  bug fixes) after that, by design.
+
+## Walkthrough: library mode (v0.1.0)
+
+The shape: import `knowless`, configure it, mount the handlers on
+your HTTP framework.
+
+### Step 1: Install
+
+```
+npm install knowless
+```
+
+Requires Node.js 20+ (LTS until April 2026).
+
+### Step 2: Generate the secret
+
+The HMAC secret is the keystone of the privacy model. It must be
+≥32 random bytes (≥64 hex chars).
+
+```
+node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"
+```
+
+Store it in your env vars / secret manager. **Never** commit it.
+Rotating the secret invalidates every existing handle and session
+— it's a one-way switch.
+
+### Step 3: Set up Postfix on localhost
+
+knowless submits SMTP to `localhost:25`. You need a localhost MTA.
+
+On Ubuntu / Debian:
+```
+sudo apt install postfix
+# Pick "Internet Site" when prompted
+# System mail name: your sending domain (e.g. app.example.com)
+```
+
+Add the **null-route** for sham mail (this is the destination
+knowless uses on silent-miss to keep timing equivalence without
+delivering unsolicited mail to unregistered addresses):
+
+```
+# /etc/postfix/transport
+knowless.invalid    discard:silently dropped by knowless null-route
+```
+
+```
+# /etc/postfix/main.cf — add this line
+transport_maps = hash:/etc/postfix/transport
+```
+
+```
+sudo postmap /etc/postfix/transport
+sudo systemctl reload postfix
+```
+
+Then the DNS records — set on your sending domain, **not** your
+app's primary domain (typical setup: `auth.example.com` is the
+sending domain):
+
+- **SPF**: `v=spf1 ip4:<your-server-ip> -all`
+- **DKIM**: generate via `opendkim-genkey` and publish the public
+  key as a TXT record
+- **PTR (reverse DNS)**: ask your VPS provider to set the PTR for
+  your IP to your sending hostname
+
+Without all three, Gmail / Outlook will silently drop your auth
+mail. This is the operator commitment knowless asks of you.
+
+> Full Postfix walkthrough lives in `OPS.md` (shipping with v0.2.0).
+
+### Step 4: Mount the handlers
+
+Express:
+```js
+import express from 'express';
+import { knowless } from 'knowless';
+
+const app = express();
+const auth = knowless({
+  secret: process.env.KNOWLESS_SECRET,
+  baseUrl: 'https://app.example.com',
+  from: 'auth@app.example.com',
+});
+
+app.use(express.urlencoded({ extended: false }));
+app.get('/login',          auth.loginForm);
+app.post('/login',         auth.login);
+app.get('/auth/callback',  auth.callback);
+app.get('/verify',         auth.verify);
+app.post('/logout',        auth.logout);
+
+app.listen(8080);
+```
+
+Fastify, Hono, `node:http` — all work. Each handler is a plain
+`(req, res) => Promise<void>` function. No framework hooks, no
+middleware injection.
+
+### Step 5: Pre-seed users (closed-registration mode, default)
+
+By default, knowless is closed: a handle must already exist before
+that email can request a magic link. To seed users:
+
+```js
+import { deriveHandle } from 'knowless';
+
+// At admin setup time:
+auth._handlers; // not the public path — use a custom admin script
+                // that calls into the underlying store.
+```
+
+Actually the cleanest pattern: write a tiny admin script using the
+re-exported primitives:
+
+```js
+import { knowless, deriveHandle, createStore } from 'knowless';
+
+const SECRET = process.env.KNOWLESS_SECRET;
+const store = createStore('./knowless.db');
+
+const teamEmails = ['alice@example.com', 'bob@example.com'];
+for (const email of teamEmails) {
+  store.upsertHandle(deriveHandle(email, SECRET));
+}
+store.close();
+```
+
+Or run with `openRegistration: true` if you want first-email-wins:
+
+```js
+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
+
+After `/auth/callback` succeeds, the user has a session cookie.
+Read it on every protected request:
+
+```js
+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.)
+  next();
+}
+```
+
+For now, the friendliest pattern: route a dedicated `/me` endpoint
+through `auth.verify` and have the rest of your app fetch it on
+mount.
+
+### Step 7: GDPR right-to-erasure
+
+The store interface exposes `deleteHandle(handle)` — atomic delete
+of the handle row, all active tokens, and all active sessions.
+Wire it to your "delete my account" UX:
+
+```js
+app.post('/account/delete', requireAuth, (req, res) => {
+  const handle = /* read from session via auth.verify or cookie */;
+  auth.deleteHandle(handle);
+  res.redirect('/goodbye');
+});
+```
+
+Library doesn't ship a built-in HTTP endpoint for this — operator
+chooses the UX (admin CLI, in-app self-service, ticket-driven
+support).
+
+## Walkthrough: standalone server mode (v0.2.0, coming)
+
+The shape: run `npx knowless-server`, point Caddy / nginx /
+Traefik at it for forward-auth, protect any HTTP service behind
+magic-link login.
+
+The deployment-shape pattern:
+```
+[browser] → [Caddy] → [knowless-server /verify]
+                     ↓ 200 OK + X-User-Handle
+                [Caddy proxies to Uptime Kuma]
+                     -OR-
+                     ↓ 401 Unauthorized
+                [Caddy redirects to auth.example.com/login?next=...]
+```
+
+Sample Caddyfile (forthcoming OPS.md will have the full setup):
+```caddy
+auth.example.com {
+    reverse_proxy localhost:8080
+}
+
+kuma.example.com {
+    forward_auth localhost:8080 {
+        uri /verify
+        copy_headers X-User-Handle
+    }
+    reverse_proxy localhost:3001  # Uptime Kuma
+}
+
+adguard.example.com {
+    forward_auth localhost:8080 {
+        uri /verify
+        copy_headers X-User-Handle
+    }
+    reverse_proxy localhost:3000  # AdGuard Home
+}
+```
+
+One auth subdomain, one cookie, SSO across all gated services
+because the cookie is scoped to the parent eTLD+1.
+
+Until v0.2.0, you can replicate this yourself with ~30 lines of
+`node:http` wrapping the library-mode handlers — see
+`knowless.context.md` for the pattern.
+
+## Configuration reference
+
+Full options table:
+
+| Option | Required | Default | Purpose |
+|---|---|---|---|
+| `secret` | yes | — | HMAC key, ≥64 hex chars (32 bytes). FR-47, FR-48. |
+| `baseUrl` | yes | — | Base URL for magic-link construction. |
+| `from` | yes | — | Sender email address. |
+| `dbPath` | no | `./knowless.db` | SQLite file path. |
+| `cookieDomain` | no | (eTLD+1 of `baseUrl`) | Session cookie scope. |
+| `cookieName` | no | `knowless_session` | Session cookie name. |
+| `tokenTtlSeconds` | no | `900` | Magic-link expiry (15 min). |
+| `sessionTtlSeconds` | no | `2592000` | Session lifetime (30 days). |
+| `linkPath` | no | `/auth/callback` | Magic-link URL path. |
+| `loginPath` | no | `/login` | Login form / submission path. |
+| `verifyPath` | no | `/verify` | Forward-auth check. |
+| `logoutPath` | no | `/logout` | Logout endpoint. |
+| `smtpHost` | no | `localhost` | MTA host. |
+| `smtpPort` | no | `25` | MTA port. |
+| `openRegistration` | no | `false` | Allow new-handle creation on first email. |
+| `subject` | no | `'Sign in'` | Mail subject. ASCII, ≤60 chars. |
+| `confirmationMessage` | no | (default with `{email}` placeholder) | Shown after submission. |
+| `includeLastLoginInEmail` | no | `true` | Append "Last sign-in" line for compromise hint. |
+| `maxActiveTokensPerHandle` | no | `5` | Per-handle cap; 0 disables. |
+| `maxLoginRequestsPerIpPerHour` | no | `30` | Per-IP login cap; 0 disables. |
+| `maxNewHandlesPerIpPerHour` | no | `3` | Per-IP creation cap (open-reg only); 0 disables. |
+| `honeypotFieldName` | no | `website` | Hidden form field name. |
+| `trustedProxies` | no | `['127.0.0.1', '::1']` | IPs allowed to set `X-Forwarded-For`. |
+| `shamRecipient` | no | `null@knowless.invalid` | Where sham mail goes (your MTA must discard it). |
+| `sweepIntervalMs` | no | `300000` | Sweeper tick (5 min default). |
+| `failureRedirect` | no | (= `loginPath`) | Where /auth/callback failures redirect. |
+| `store` | no | (built-in better-sqlite3) | Inject your own store implementation. |
+| `mailer` | no | (built-in nodemailer) | Inject your own mailer. |
+
+## FAQ
+
+### My users say magic links land in spam.
+
+This is operator infrastructure, not the library. The library
+sends RFC-clean plain-text mail with whitelisted headers; what
+mail providers do with it depends entirely on your sending
+domain's reputation. Verify SPF, DKIM, and PTR records are all
+set correctly. Test with [mail-tester.com](https://www.mail-tester.com/).
+
+### Can I use Mailgun / Postmark / SES instead of localhost Postfix?
+
+No, by design. The library refuses remote SMTP and vendor APIs.
+The reasoning is in [`docs/01-product/PRD.md`](docs/01-product/PRD.md) §16.2: a
+vendor relationship invites the operator to use the same mailer
+for non-auth mail (welcome emails, digests), which contradicts
+the philosophy. If you need a vendor mailer, you're not the
+audience for knowless.
+
+### How do I rotate the secret?
+
+You can't, in practice. Rotating invalidates every existing handle
+(they're salted by the secret) and every session (they're signed
+by it). Treat the secret like a database master key: generate it
+once, back it up safely, never expose it.
+
+### Can I customise the login HTML?
+
+No. The form is hardcoded. Operators wanting branding fork the
+project. Rationale in [`docs/01-product/PRD.md`](docs/01-product/PRD.md) §16.12: templating
+is a slope ("let me put my logo" → "let me theme the page" →
+"let me embed a JS framework"). The hardcoded form refuses to
+drift.
+
+### How do I add 2FA / WebAuthn / TOTP?
+
+Compose with a separate library. knowless does magic-link, full
+stop. WebAuthn after login is a different layer.
+
+### What about CSRF on POST /login?
+
+The login form is unauthenticated, so traditional CSRF
+mitigations (anti-CSRF tokens) don't apply directly. SameSite=Lax
+on the session cookie covers the post-login risk. CSRF on the
+unauthenticated /login endpoint is on the v0.2 open-questions
+list (SPEC §15 Q-4) — Origin-header validation is the likely
+answer.
+
+### Can I run multiple instances behind a load balancer?
+
+Yes — the SQLite store is shared across processes via the file
+system. Concurrent writes use SQLite's `BEGIN IMMEDIATE` for the
+token-issuance transaction (SPEC §4.7). For very high concurrency
+(>1000 logins/sec), implement the store interface against
+Postgres or Redis.
+
+### How do I see what's in the store?
+
+```
+sqlite3 knowless.db
+sqlite> .schema
+sqlite> SELECT count(*) FROM handles;
+sqlite> SELECT count(*) FROM sessions WHERE expires_at > unixepoch() * 1000;
+```
+
+The schema is documented in [`docs/02-design/SPEC.md`](docs/02-design/SPEC.md) §6.
+
+## Troubleshooting
+
+### "config.secret must be ≥64 hex chars (32 bytes)"
+
+You passed a secret shorter than 64 characters or not a string.
+Run `node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"`
+and use the output.
+
+### Magic link works but `/verify` returns 401
+
+Common causes:
+- Cookie domain mismatch. The cookie is set to the eTLD+1 of
+  `baseUrl` by default; if your protected service is on a
+  different parent domain, the browser won't send the cookie.
+  Set `cookieDomain` explicitly.
+- Cookie not surviving the redirect. The `Set-Cookie` from
+  `/auth/callback` must be `Secure`, so HTTP-only origins won't
+  receive it. Use HTTPS in production.
+
+### "ERR_UNKNOWN_ENCODING: 7bit" or "Content-Transfer-Encoding: base64" in mail
+
+Library bug — the mailer is supposed to compose 7bit raw RFC822.
+Open an issue with the captured wire output.
+
+### Tests fail intermittently in CI
+
+The FR-6 timing test has a 1ms `delta_mean` bar. On extremely
+noisy CI runners this can spuriously fail. Re-run; if persistent,
+your runner is anomalous. Document the policy locally rather
+than weakening the bar — see SPEC §14.5.
+
+### "The link expires in 15 minutes" — can I make it longer?
+
+Yes: `tokenTtlSeconds`. Don't set it absurdly high. Magic links
+that linger in inboxes are a phishing-amplification risk if the
+mail account is later compromised.