knowless 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -15,6 +15,62 @@ Versioning is [SemVer](https://semver.org/).
   not what the MTA did, so this is the closest we can get.
   Targeted for v0.2.0.
 
+## [0.1.5] — 2026-04-28
+
+addypin POC findings round. Adds programmatic magic-link entry
+(unblocks "use first, claim later" UX patterns), one ergonomic
+helper, two safety/diagnostic fixes, and three doc updates.
+
+### Added
+
+- **`auth.startLogin({email, nextUrl?, sourceIp?})`** — programmatic
+  entry that runs the same 12-step sham-work flow as `POST /login`
+  but skips Origin/honeypot (no browser context). Returns
+  `{handle, submitted: true}` — same shape on rate-limit / sham /
+  real to preserve FR-6 timing equivalence. Throws only on
+  programmer error. SPEC §7.3a. Closes AF-7.3.
+- **`auth.deriveHandle(email)`** — instance method that uses the
+  configured secret. Lets adopters compute owner-handles outside
+  HTTP context without spreading the secret across modules. Closes
+  AF-7.4.
+- **GUIDE.md "Two adoption modes" section** — Mode B (register-
+  first, the form) and Mode A (use-first-claim-later, programmatic).
+  Both supported, pickable per-action.
+- **GUIDE.md "Constraints / install footprint" section** — direct
+  deps, transitive count, deprecation-warning context. Closes AF-7.7.
+
+### Changed
+
+- **`devLogMagicLinks` lines now tagged with `cfg.from`** —
+  `[knowless dev:auth@app.example.com] magic link: ...`. Disambiguates
+  multi-instance dev logs. Closes AF-7.6.
+- **`devLogMagicLinks` + sham + SMTP-fail now prints a one-line
+  silent-miss hint** instead of staying silent. Surfaces the
+  closed-registration-is-on case that previously cost adopters
+  ~30min of debugging. Strictly opt-in dev mode. Closes AF-7.2.
+
+### Safety / diagnostics
+
+- **`createMailer` validates `transportOverride` at startup.** A
+  malformed override (e.g. an options bag mistaken for a transport)
+  throws fast with a pointed error instead of failing at first
+  submission. Closes AF-7.5.
+- **`POST /login` warns once on stderr when `Content-Length > 0`
+  but body is empty.** Catches the common non-Express trap of
+  mounting `express.urlencoded()` or similar body parsers ahead of
+  `auth.login` (which consumes the stream itself). One warning per
+  handler instance. Closes AF-7.1.
+
+### Documentation
+
+- **SPEC §7.3a** specifies the programmatic entry's contract: which
+  steps it skips (Origin, honeypot), why FR-6 still holds, and
+  what programmer-error throws look like.
+- **GUIDE.md** adds two traps for non-Express integrators (body-
+  parser conflict, Origin requirement) and a worked Mode-A example.
+- **knowless.context.md** lists `startLogin` + `deriveHandle` in the
+  public API table and adds gotchas 15–16.
+
 ## [0.1.4] — 2026-04-28
 
 First real-world integration release. Bugs and ergonomics surfaced

package/GUIDE.md

@@ -205,6 +205,95 @@ Fastify, Hono, `node:http` — all work. Each handler is a plain
 `(req, res) => Promise<void>` function. No framework hooks, no
 middleware injection.
 
+#### Trap: do NOT pre-parse the body
+
+knowless reads `POST /login`'s body itself. If a body parser
+middleware runs ahead of `auth.login` and consumes the stream,
+knowless sees an empty body and silently null-routes the request
+(as if no email was submitted). Symptoms: form posts return 200,
+no magic link arrives, no error logged.
+
+Express works in the example above because `express.urlencoded()`
+is mounted as application middleware but doesn't intercept the
+specific path. **On Hono / Fastify-without-body-plugin / raw
+node:http, mount `auth.login` directly with no body parser in
+front.** Same goes for `auth.logout` (it doesn't read a body, but
+keep the symmetry).
+
+knowless will emit a one-time `console.warn(...)` if it sees an
+empty body where `Content-Length > 0` — that's the canary for this
+bug.
+
+#### Trap: non-browser callers need an Origin header
+
+`POST /login` runs an Origin/Referer whitelist (CSRF defense, see
+the FAQ below). Browsers always send `Origin` on cross-origin
+POSTs, so the form path is fine. **Curl / scripts / server-to-
+server callers must send no Origin header at all** (knowless
+allows browser-absent requests) **or** an Origin matching your
+`cookieDomain`. If you set a foreign Origin, the request silently
+falls through to a sham send. For programmatic callers, prefer
+[`auth.startLogin()`](#mode-a-use-first-claim-later) over POSTing
+the form.
+
+### Two adoption modes (Mode A vs Mode B)
+
+knowless supports two UX flows out of the box. Pick per-action,
+not per-app — both can coexist.
+
+**Mode B — register-first (the default).** 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 (account settings, paid
+features, anything you want tied to an identity at the moment of
+the action).
+
+```js
+app.post('/api/comments', (req, res) => {
+  const handle = auth.handleFromRequest(req);
+  if (!handle) return res.status(401).end();
+  // create comment owned by `handle`
+});
+```
+
+**Mode A — use-first, claim-later.** 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 pin," "post a
+share link," "submit a paste" — patterns where forcing a login
+*before* the action would harm the UX.
+
+```js
+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
+  await auth.startLogin({                          // AF-7.3
+    email,
+    nextUrl: 'https://app.example.com/manage',
+    sourceIp: req.socket.remoteAddress,
+  });
+  res.status(202).end();  // "we'll email you the link"
+});
+
+// On callback, promote pending pins owned by the now-logged-in handle.
+app.get('/manage', (req, res) => {
+  const owner = auth.handleFromRequest(req);
+  if (!owner) return res.redirect('/login');
+  // db.promotePendingPinsFor(owner)
+});
+```
+
+`startLogin` runs the same 12-step sham-work flow as the form
+handler, so unknown emails, rate-limit hits, and real sends all
+return identical shapes — the caller can't observe which happened.
+This preserves FR-6 timing equivalence even for programmatic
+callers. See SPEC §7.3a for the full contract.
+
+`auth.deriveHandle(email)` returns the same opaque HMAC handle
+that the form path uses, without you having to import the helper
+or pass the secret around.
+
 ### Step 5: Pre-seed users (closed-registration mode, default)
 
 By default, knowless is closed: a handle must already exist before
@@ -465,3 +554,18 @@ than weakening the bar — see SPEC §14.5.
 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.
+
+## Constraints / install footprint
+
+- **Two direct dependencies.** `nodemailer` (SMTP submission) and
+  `better-sqlite3` (storage). Both audited and pinned at major
+  versions in `package.json`.
+- **~40 transitive packages** in a typical install. The bulk are
+  `nodemailer`'s ecosystem deps (mostly idle in our usage) and
+  `better-sqlite3`'s build-time prebuild fetcher. You may see one
+  deprecation warning during install for `prebuild-install` —
+  build-chain noise, not runtime code.
+- **Node ≥ 20.** Uses `node:util parseArgs`, `node:net BlockList`
+  for CIDR support, and `--env-file=` for the standalone server.
+- **No optional deps, no postinstall scripts** beyond `better-
+  sqlite3`'s native binding fetch.

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.0 | Node.js >= 20 | 2 deps (nodemailer, better-sqlite3) | Apache-2.0
+> v0.1.4 | Node.js >= 20 | 2 deps (nodemailer, better-sqlite3) | Apache-2.0
 
 ## What this is
 
@@ -83,12 +83,12 @@ A short list (full table in [`docs/01-product/PRD.md`](docs/01-product/PRD.md)
 
 | Mode | Status | When |
 |---|---|---|
-| **Library mode** | v0.1.0 | Mount handlers in your existing Node app |
-| **Standalone server** (forward-auth) | v0.2.0 | Self-hosters gating Uptime Kuma / AdGuard / Pi-hole / Sonarr / etc. via Caddy or nginx |
+| **Library mode** | shipped (v0.1.0) | Mount handlers in your existing Node app |
+| **Standalone server** (forward-auth) | shipped (v0.1.3) | Self-hosters gating Uptime Kuma / AdGuard / Pi-hole / Sonarr / etc. via Caddy or nginx |
 
-This release ships library mode. Standalone server (`bin/knowless-server`)
-follows in 0.2.0 — see [`docs/03-tasks/TASKS.md`](docs/03-tasks/TASKS.md)
-Phase 6 for scope.
+Library mode is the six-line example above. Standalone server is
+`npx knowless-server` — see [`OPS.md`](OPS.md) for the full Postfix +
+DNS + reverse-proxy walkthrough.
 
 ## Operator commitments
 

package/knowless.context.md

@@ -76,6 +76,7 @@ const auth = knowless({
   // --- Cookie / session ---
   cookieDomain: 'app.example.com',    // default: hostname of baseUrl
   cookieName: 'knowless_session',     // default 'knowless_session'
+  cookieSecure: true,                 // default true; "false" only for localhost dev
   sessionTtlSeconds: 30 * 86400,      // 30 days
 
   // --- Token ---
@@ -97,17 +98,27 @@ const auth = knowless({
   // --- Behavior ---
   openRegistration: false,            // first-email-wins handle creation
   includeLastLoginInEmail: true,      // append "Last sign-in: <ISO ts>" line
-  confirmationMessage: 'Thanks. If <strong>{email}</strong>...',
+  confirmationMessage: 'Thanks. If {email} is registered, a link is on its way.',
+  // ^ NOTE: the message is HTML-escaped before render (AF-6.5).
+  //         {email} placeholder still works. For HTML, pre-render upstream.
 
   // --- Abuse defenses (FR-38..41) ---
   maxActiveTokensPerHandle: 5,        // 0 to disable
   maxLoginRequestsPerIpPerHour: 30,   // 0 to disable
   maxNewHandlesPerIpPerHour: 3,       // 0 to disable (open-reg only)
   honeypotFieldName: 'website',
-  trustedProxies: ['127.0.0.1', '::1'],
+  // Plain IPs and/or CIDR ranges (AF-6.3). Useful for k8s/docker/cgnat.
+  trustedProxies: ['127.0.0.1', '::1', '10.0.0.0/8'],
 
   // --- Lifecycle ---
   sweepIntervalMs: 5 * 60 * 1000,     // periodic sweeper tick
+  onSweepError: (err) => { /* alerting hook; errors are swallowed */ },
+
+  // --- Dev mode (AF-6.2) ---
+  // When SMTP submission fails AND this flag is true, the magic link
+  // is printed to stderr so a developer can click through. Off by
+  // default. Never fires for sham (silent-miss) submissions.
+  devLogMagicLinks: false,
 
   // --- Injection (tests / advanced) ---
   store: undefined,                   // bring your own store
@@ -127,7 +138,12 @@ const auth = knowless({
 | `verify` | (req, res) | void | GET handler (forward-auth): 200+`X-User-Handle` if cookie valid, else 401 |
 | `logout` | (req, res) | Promise\<void\> | POST handler: clears session row + cookie |
 | `loginForm` | (req, res) | void | GET handler: renders the hardcoded login HTML; preserves `?next=` |
+| `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. |
+| `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) |
 | `close` | -- | void | Stops sweeper, closes mailer + store. Call on shutdown. |
 
@@ -372,11 +388,10 @@ rate-limits) belongs above the library.
    The library does NOT compute eTLD+1 automatically (would
    require a public-suffix-list dep).
 
-5. **`Secure` cookie attribute is non-negotiable.** All session
-   cookies set `Secure`. HTTP-only origins won't receive them.
-   Use HTTPS in production. Localhost development: use
-   `--insecure-localhost-cookies` (not implemented yet — TASKS
-   open question; works in Chrome with `--unsafely-treat-insecure-origin-as-secure`).
+5. **`Secure` cookie attribute toggles via `cookieSecure`.** Default
+   is `true`. Set `cookieSecure: false` ONLY for `http://localhost`
+   development; the library logs a stderr warning at startup (AF-4.4).
+   Production deployments MUST use HTTPS and leave `cookieSecure: true`.
 
 6. **Forward-auth needs the parent-domain cookie.** If your auth
    subdomain is `auth.example.com` and protected service is
@@ -410,6 +425,40 @@ rate-limits) belongs above the library.
     so it won't *prevent* exit, but the SQLite handle held by
     `better-sqlite3` will leave a finalizer warning.
 
+12. **CSRF defense is the Origin/Referer whitelist, not a token.**
+    Modern browsers always emit `Origin` on cross-origin POSTs;
+    knowless validates host against `cookieDomain` on POST /login
+    AND POST /logout. Browser-absent (curl / programmatic) is
+    allowed. **Do NOT add a CSRF token upstream** — the Origin
+    check is the defense. SPEC §7.3 Step 0.
+
+13. **`confirmationMessage` is plain text + `{email}` placeholder.**
+    The whole message is HTML-escaped before render (AF-6.5). If
+    you want bold/italic/links in the confirmation copy, pre-render
+    the HTML upstream and pass the escaped string — but understand
+    you're then responsible for not interpolating user data.
+
+14. **`devLogMagicLinks` is opt-in and dev-only.** When set true
+    AND SMTP submission fails, the magic link is printed to stderr
+    tagged `[knowless dev:<from>]`. Sham (silent-miss) submissions
+    print a `silent-miss: ...` hint instead of a link — opt-in dev
+    only, since this leaks closed-reg state. Don't enable in
+    production.
+
+15. **POST /login: don't pre-parse the body.** knowless reads the
+    request stream itself. Any framework body parser mounted in
+    front of `auth.login` will silently steal the form data and
+    null-route the request. knowless emits a one-time
+    `console.warn` if it sees `Content-Length > 0` with an empty
+    body. AF-7.1.
+
+16. **Two adoption modes — Mode B (register-first) and Mode A
+    (use-first claim-later).** Mode B is the form (`auth.login`).
+    Mode A is `auth.startLogin({email, nextUrl, sourceIp})` for
+    "drop a pin, claim by email click" patterns. Both run the
+    identical 12-step sham-work flow; same FR-6 guarantee. Pick
+    per-action, not per-app.
+
 ## Constraints
 
 - **Node 20+** -- targeting LTS; tested on Node 22

package/package.json

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

@@ -182,6 +182,21 @@ export function createHandlers({ store, mailer, config }) {
   // Build once at handler creation; supports plain IPs and CIDRs (AF-6.3).
   const trustedProxies = buildTrustedPeers(cfg.trustedProxies);
 
+  // AF-7.1: emit at most one warning per handler instance about an
+  // upstream body parser swallowing the request body. Loud enough to
+  // notice in dev, quiet enough not to spam.
+  let emptyBodyWarned = false;
+  function warnEmptyBodyOnce() {
+    if (emptyBodyWarned) return;
+    emptyBodyWarned = true;
+    console.warn(
+      '[knowless] POST /login received an empty body but Content-Length > 0. ' +
+        'A body parser running ahead of this handler likely consumed the stream. ' +
+        'knowless reads req itself; do not mount express.urlencoded() / express.json() / ' +
+        'similar middleware in front of POST /login. (Warned once per instance.)',
+    );
+  }
+
   // SPEC §5.4 / FR-30: build the cookie-attribute suffix once. Secure is
   // emitted by default and omitted only when cookieSecure: false (localhost
   // dev). HttpOnly + SameSite=Lax are always set.
@@ -208,56 +223,46 @@ export function createHandlers({ store, mailer, config }) {
     res.end();
   }
 
-  async function login(req, res) {
-    // Step 0 — Origin / Referer validation (SPEC §7.3 Step 0, AF-4.3).
-    // CSRF defense: a malicious cross-origin page autosubmitting to /login
-    // would otherwise trigger magic-link sends to known emails. Exempt
-    // from FR-6 timing equivalence per SPEC §7.3.
-    if (!validateOrigin(req, cfg.cookieDomain)) {
-      sameResponse(res, '', '');
-      return;
-    }
-
-    let raw;
-    try {
-      raw = await readBody(req);
-    } catch {
-      sameResponse(res, '', '');
-      return;
-    }
-    const body = parseBody(raw, req.headers['content-type']);
-    const emailRaw = typeof body.email === 'string' ? body.email : '';
-    const honeypot = body[cfg.honeypotFieldName];
-    const nextRaw = body.next;
-
+  /**
+   * The 12-step sham-work flow, reusable by both POST /login and the
+   * programmatic auth.startLogin() entry. Returns {handle, isSham} so
+   * the form handler can drive its same-response and the programmatic
+   * caller can return the handle to its caller. See SPEC §7.3 (form)
+   * and §7.3a (programmatic). AF-7.3.
+   *
+   * Steps skipped depending on the entry point:
+   *   - Origin (§7.3 Step 0): form-only; programmatic callers are
+   *     trusted server-side code.
+   *   - Honeypot (§7.3 Step 2): form-only; no form context.
+   *
+   * Both entries run steps 1, 3, 4–12 identically — so the timing-
+   * equivalence guarantee (FR-6) holds for either.
+   *
+   * @returns {Promise<{handle: string|null, isSham: boolean,
+   *                    emailNorm: string, nextValidated: string|null}>}
+   *   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 }) {
     // Step 1: parse + normalize
     let emailNorm;
     try {
       emailNorm = normalize(emailRaw);
     } catch {
-      sameResponse(res, emailRaw, nextRaw);
-      return;
-    }
-
-    // Step 2: honeypot — exempt short-circuit (no sham work)
-    if (typeof honeypot === 'string' && honeypot.length > 0) {
-      sameResponse(res, emailNorm, nextRaw);
-      return;
+      return { handle: null, isSham: false, emailNorm: emailRaw, nextValidated: null };
     }
 
     // Step 3: per-IP rate limit on /login — exempt short-circuit
-    const ip = determineSourceIp(req, trustedProxies);
     if (
       rateLimitExceeded(
         store,
         'login_ip',
-        ip,
+        sourceIp,
         cfg.maxLoginRequestsPerIpPerHour,
         HOUR_MS,
       )
     ) {
-      sameResponse(res, emailNorm, nextRaw);
-      return;
+      return { handle: null, isSham: false, emailNorm, nextValidated: null };
     }
 
     // ---- Equivalent-work region begins (SPEC §7.3 step 4) ----
@@ -271,7 +276,7 @@ export function createHandlers({ store, mailer, config }) {
         rateLimitExceeded(
           store,
           'create_ip',
-          ip,
+          sourceIp,
           cfg.maxNewHandlesPerIpPerHour,
           HOUR_MS,
         )
@@ -323,18 +328,91 @@ export function createHandlers({ store, mailer, config }) {
       console.error('[knowless] mail submit failed:', err.message);
       // AF-6.2: dev-mode fallback. When SMTP is unreachable in local
       // development the operator otherwise has no way to obtain the magic
-      // link. Print it to stderr only when explicitly opted in. Sham
-      // submissions are NOT logged (would leak silent-miss outcome).
-      if (cfg.devLogMagicLinks && !isSham) {
-        const link = `${cfg.baseUrl}${cfg.linkPath}?t=${token.raw}`;
-        process.stderr.write(`[knowless dev] magic link: ${link}\n`);
+      // link. Print it to stderr only when explicitly opted in.
+      if (cfg.devLogMagicLinks) {
+        // AF-7.6: include `from` to disambiguate multi-instance logs.
+        const tag = `[knowless dev:${cfg.from}]`;
+        if (isSham) {
+          // AF-7.2 dev hint: silent-miss is by-design but in dev mode
+          // operators repeatedly debug "why no link?" — surface the
+          // reason. Only fires on opt-in dev mode + SMTP failure.
+          process.stderr.write(
+            `${tag} silent-miss: handle for "${emailNorm}" does not exist (openRegistration=${cfg.openRegistration})\n`,
+          );
+        } else {
+          const link = `${cfg.baseUrl}${cfg.linkPath}?t=${token.raw}`;
+          process.stderr.write(`${tag} magic link: ${link}\n`);
+        }
       }
     }
 
-    rateLimitIncrement(store, 'login_ip', ip, HOUR_MS);
-    if (isCreating) rateLimitIncrement(store, 'create_ip', ip, HOUR_MS);
+    rateLimitIncrement(store, 'login_ip', sourceIp, HOUR_MS);
+    if (isCreating) rateLimitIncrement(store, 'create_ip', sourceIp, HOUR_MS);
 
-    sameResponse(res, emailNorm, nextValidated ?? '');
+    return { handle, isSham, emailNorm, nextValidated };
+  }
+
+  async function login(req, res) {
+    // Step 0 — Origin / Referer validation (SPEC §7.3 Step 0, AF-4.3).
+    if (!validateOrigin(req, cfg.cookieDomain)) {
+      sameResponse(res, '', '');
+      return;
+    }
+
+    let raw;
+    try {
+      raw = await readBody(req);
+    } catch {
+      sameResponse(res, '', '');
+      return;
+    }
+    // AF-7.1: warn when a body parser ahead of us has consumed the stream.
+    // POST /login with Content-Length > 0 but empty raw body is the
+    // signature; without this, the request silently null-routes and the
+    // adopter loses 30 minutes wondering why magic links never arrive.
+    if (raw.length === 0) {
+      const cl = Number(req.headers?.['content-length']);
+      if (Number.isFinite(cl) && cl > 0) {
+        warnEmptyBodyOnce();
+      }
+    }
+    const body = parseBody(raw, req.headers['content-type']);
+    const emailRaw = typeof body.email === 'string' ? body.email : '';
+    const honeypot = body[cfg.honeypotFieldName];
+    const nextRaw = body.next;
+
+    // Step 2: honeypot — exempt short-circuit (no sham work)
+    if (typeof honeypot === 'string' && honeypot.length > 0) {
+      sameResponse(res, emailRaw, nextRaw);
+      return;
+    }
+
+    const sourceIp = determineSourceIp(req, trustedProxies);
+    const result = await runSendLink({ emailRaw, nextRaw, sourceIp });
+    sameResponse(res, result.emailNorm, result.nextValidated ?? '');
+  }
+
+  async function startLogin({ email, nextUrl, sourceIp = '' } = {}) {
+    // 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) {
+      throw new Error('startLogin: email is required (string)');
+    }
+    if (nextUrl !== undefined && nextUrl !== null && typeof nextUrl !== 'string') {
+      throw new Error('startLogin: nextUrl must be a string when provided');
+    }
+    if (typeof sourceIp !== 'string') {
+      throw new Error('startLogin: sourceIp must be a string when provided');
+    }
+    const { handle } = await runSendLink({
+      emailRaw: email,
+      nextRaw: nextUrl ?? null,
+      sourceIp,
+    });
+    // Same-shape return: rate-limit / sham / real all collapse here.
+    // `handle` is the HMAC of the normalized email (or null if email
+    // was malformed). It leaks nothing about existence per FR-6.
+    return { handle, submitted: true };
   }
 
   async function callback(req, res) {
@@ -453,6 +531,7 @@ export function createHandlers({ store, mailer, config }) {
     logout,
     loginForm,
     handleFromRequest,
+    startLogin,
     validateNextUrl: (raw) => validateNextUrl(raw, cfg.baseUrl, cfg.cookieDomain),
     // exposed for tests
     _config: cfg,

package/src/index.js

@@ -1,6 +1,7 @@
 import { createStore } from './store.js';
 import { createMailer } from './mailer.js';
 import { createHandlers } from './handlers.js';
+import { deriveHandle as deriveHandleRaw } from './handle.js';
 
 /** Default sweeper tick: 5 minutes. Per FR-13. */
 const DEFAULT_SWEEP_INTERVAL_MS = 5 * 60 * 1000;
@@ -141,6 +142,16 @@ export function knowless(options = {}) {
      *  "Log out everywhere." Returns the number of sessions removed.
      *  AF-6.1. */
     revokeSessions: (handle) => store.revokeSessions(handle),
+    /** Programmatic magic-link send. Use this for "use first, claim
+     *  later" UX flows (drop a pin, post a comment, then confirm via
+     *  email). Returns `{handle, submitted: true}` — same shape on
+     *  rate-limit / sham / real to preserve FR-6 timing equivalence.
+     *  See SPEC §7.3a. AF-7.3. */
+    startLogin: handlers.startLogin,
+    /** Derive the opaque handle for an email using the configured
+     *  secret. Lets adopters compute owner-handles outside HTTP context
+     *  without spreading the secret across modules. AF-7.4. */
+    deriveHandle: (email) => deriveHandleRaw(email, options.secret),
     /** Effective config (with defaults applied), useful for routing. */
     config: handlers._config,
     /** Run a sweep tick on demand. Useful for tests and operator scripts. */

package/src/mailer.js

@@ -151,6 +151,18 @@ export function createMailer(cfg) {
       auth: undefined,
     });
 
+  // AF-7.5: validate the resolved transport at startup. Without this,
+  // a malformed transportOverride (or a bare options bag mistaken for a
+  // transport) silently constructs something that throws "sendMail is
+  // not a function" only at first submission — which in production may
+  // be hours later. Fail fast at factory time instead.
+  if (typeof transport.sendMail !== 'function') {
+    throw new Error(
+      'mailer: transport has no sendMail() — if you passed transportOverride, ' +
+        'pass the result of nodemailer.createTransport(opts), not an opts bag.',
+    );
+  }
+
   return {
     async submit({ to, subject, body }) {
       if (typeof to !== 'string' || !ASCII_RE.test(to)) {