knowless 0.1.0

package/src/handle.js

@@ -0,0 +1,51 @@
+import crypto from 'node:crypto';
+
+/**
+ * Email syntax accepted by knowless. Strict ASCII-only; no quoted-locals,
+ * no IP-literal domains, no IDN. See SPEC §2.1.
+ */
+const EMAIL_REGEX = /^[a-z0-9._%+\-]+@[a-z0-9.\-]+\.[a-z]{2,}$/;
+
+/**
+ * Normalize an email address per SPEC §2.1. Trim, ASCII-lowercase, reject
+ * non-ASCII, validate against the strict regex.
+ *
+ * @param {string} input
+ * @returns {string} normalized, validated, lowercase ASCII email
+ * @throws {Error} on any invalid input — caller treats as silent miss
+ */
+export function normalize(input) {
+  if (typeof input !== 'string') throw new Error('invalid email');
+  const trimmed = input.replace(/^[\t\n\r ]+|[\t\n\r ]+$/g, '');
+  if (trimmed.length === 0 || trimmed.length > 254) throw new Error('invalid email');
+  for (let i = 0; i < trimmed.length; i++) {
+    if (trimmed.charCodeAt(i) > 0x7f) throw new Error('invalid email');
+  }
+  const lowered = trimmed.toLowerCase();
+  if (!EMAIL_REGEX.test(lowered)) throw new Error('invalid email');
+  return lowered;
+}
+
+/**
+ * Derive the opaque handle for a normalized email using the operator secret.
+ * HMAC-SHA256, lowercase hex output, 64 chars. See SPEC §3.
+ *
+ * The handle is grandfathered without a domain-separation tag. Any future
+ * HMAC use of `secret` MUST add a tag prefix (see SPEC §3.4).
+ *
+ * @param {string} emailNormalized output of normalize()
+ * @param {Buffer|string} secret operator HMAC secret
+ * @returns {string} 64-char lowercase hex handle
+ */
+export function deriveHandle(emailNormalized, secret) {
+  if (typeof emailNormalized !== 'string' || emailNormalized.length === 0) {
+    throw new Error('emailNormalized required');
+  }
+  if (!secret || (typeof secret !== 'string' && !Buffer.isBuffer(secret))) {
+    throw new Error('secret required');
+  }
+  return crypto
+    .createHmac('sha256', secret)
+    .update(emailNormalized, 'utf8')
+    .digest('hex');
+}

package/src/handlers.js

@@ -0,0 +1,383 @@
+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 { renderLoginForm } from './form.js';
+import {
+  determineSourceIp,
+  rateLimitExceeded,
+  rateLimitIncrement,
+} from './abuse.js';
+
+const HOUR_MS = 60 * 60 * 1000;
+
+const DEFAULTS = {
+  cookieName: 'knowless_session',
+  linkPath: '/auth/callback',
+  loginPath: '/login',
+  verifyPath: '/verify',
+  logoutPath: '/logout',
+  tokenTtlSeconds: 900,
+  sessionTtlSeconds: 30 * 24 * 60 * 60,
+  subject: 'Sign in',
+  confirmationMessage:
+    'Thanks. If <strong>{email}</strong> is registered, a sign-in link is on its way. Check your inbox in a few minutes.',
+  includeLastLoginInEmail: true,
+  openRegistration: false,
+  maxActiveTokensPerHandle: 5,
+  maxLoginRequestsPerIpPerHour: 30,
+  maxNewHandlesPerIpPerHour: 3,
+  honeypotFieldName: 'website',
+  shamRecipient: 'null@knowless.invalid',
+  trustedProxies: ['127.0.0.1', '::1', '::ffff:127.0.0.1'],
+  failureRedirect: null,
+};
+
+/**
+ * Read a request body up to maxBytes. Returns the UTF-8 string.
+ * Resolves with '' if the request never sent any data and ended.
+ */
+function readBody(req, maxBytes = 65_536) {
+  return new Promise((resolve, reject) => {
+    let total = 0;
+    const chunks = [];
+    req.on('data', (c) => {
+      total += c.length;
+      if (total > maxBytes) {
+        req.destroy(new Error('body too large'));
+        reject(new Error('body too large'));
+        return;
+      }
+      chunks.push(c);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    req.on('error', reject);
+  });
+}
+
+function parseBody(raw, contentType) {
+  const ct = (contentType || '').split(';')[0].trim().toLowerCase();
+  if (ct === 'application/json') {
+    try {
+      const parsed = JSON.parse(raw);
+      return parsed && typeof parsed === 'object' ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
+  if (ct === 'application/x-www-form-urlencoded') {
+    return Object.fromEntries(new URLSearchParams(raw));
+  }
+  return {};
+}
+
+function getCookie(req, name) {
+  const header = req.headers?.cookie;
+  if (!header) return null;
+  for (const part of header.split(';')) {
+    const trimmed = part.trim();
+    const eq = trimmed.indexOf('=');
+    if (eq < 0) continue;
+    if (trimmed.slice(0, eq) === name) return trimmed.slice(eq + 1);
+  }
+  return null;
+}
+
+/**
+ * Validate the `next` URL per SPEC §11.2.
+ * @param {string|null|undefined} rawNext
+ * @param {string} baseUrl
+ * @param {string} cookieDomain
+ * @returns {string|null} canonical URL string, or null
+ */
+export function validateNextUrl(rawNext, baseUrl, cookieDomain) {
+  if (typeof rawNext !== 'string' || rawNext.length === 0 || rawNext.length > 2048) {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = new URL(rawNext, baseUrl);
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') return null;
+  const host = parsed.hostname.toLowerCase();
+  const dom = cookieDomain.toLowerCase();
+  if (host === dom || host.endsWith('.' + dom)) return parsed.toString();
+  return null;
+}
+
+function sidHashOf(sid) {
+  return crypto.createHash('sha256').update(Buffer.from(sid, 'base64url')).digest('hex');
+}
+
+/**
+ * Build the knowless HTTP handlers. Each handler is framework-agnostic:
+ * (req, res) => Promise<void> | void, where req/res match node:http.
+ *
+ * @param {object} args
+ * @param {object} args.store    knowless store (from createStore)
+ * @param {object} args.mailer   knowless mailer (from createMailer)
+ * @param {object} args.config   merged config; see DEFAULTS for missing keys
+ * @returns {{
+ *   login: (req:any,res:any)=>Promise<void>,
+ *   callback: (req:any,res:any)=>Promise<void>,
+ *   verify: (req:any,res:any)=>void,
+ *   logout: (req:any,res:any)=>Promise<void>,
+ *   loginForm: (req:any,res:any)=>void,
+ *   validateNextUrl: (raw:string)=>string|null
+ * }}
+ */
+export function createHandlers({ store, mailer, config }) {
+  const cfg = { ...DEFAULTS, ...config };
+  if (!cfg.secret) throw new Error('config.secret required');
+  if (typeof cfg.secret !== 'string' || cfg.secret.length < 64) {
+    throw new Error('config.secret must be ≥64 hex chars (32 bytes)');
+  }
+  if (!cfg.baseUrl) throw new Error('config.baseUrl required');
+  if (!cfg.from) throw new Error('config.from required');
+  if (!cfg.cookieDomain) {
+    try {
+      cfg.cookieDomain = new URL(cfg.baseUrl).hostname;
+    } catch {
+      throw new Error('config.baseUrl invalid');
+    }
+  }
+
+  const trustedProxies = new Set(cfg.trustedProxies);
+
+  function sameResponse(res, echoedEmail, next) {
+    const html = renderLoginForm({
+      loginPath: cfg.loginPath,
+      honeypotName: cfg.honeypotFieldName,
+      confirmationMessage: cfg.confirmationMessage,
+      echoedEmail: echoedEmail ?? '',
+      next: typeof next === 'string' ? next : '',
+    });
+    res.statusCode = 200;
+    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+    res.setHeader('Cache-Control', 'no-store');
+    res.end(html);
+  }
+
+  function failureRedirect(res) {
+    res.statusCode = 302;
+    res.setHeader('Location', cfg.failureRedirect ?? cfg.loginPath);
+    res.end();
+  }
+
+  async function login(req, res) {
+    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;
+
+    // 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;
+    }
+
+    // Step 3: per-IP rate limit on /login — exempt short-circuit
+    const ip = determineSourceIp(req, trustedProxies);
+    if (
+      rateLimitExceeded(
+        store,
+        'login_ip',
+        ip,
+        cfg.maxLoginRequestsPerIpPerHour,
+        HOUR_MS,
+      )
+    ) {
+      sameResponse(res, emailNorm, nextRaw);
+      return;
+    }
+
+    // ---- Equivalent-work region begins (SPEC §7.3 step 4) ----
+    const handle = deriveHandle(emailNorm, cfg.secret);
+    const nextValidated = validateNextUrl(nextRaw, cfg.baseUrl, cfg.cookieDomain);
+    const exists = store.handleExists(handle);
+    let isCreating = !exists && cfg.openRegistration;
+
+    if (isCreating) {
+      if (
+        rateLimitExceeded(
+          store,
+          'create_ip',
+          ip,
+          cfg.maxNewHandlesPerIpPerHour,
+          HOUR_MS,
+        )
+      ) {
+        // Cap exceeded — fall through to sham, do NOT short-circuit.
+        isCreating = false;
+      }
+    }
+
+    const expiresAt = Date.now() + cfg.tokenTtlSeconds * 1000;
+    const token = issueToken();
+
+    let toAddress;
+    let lastLoginAt = null;
+    let isSham;
+
+    if (exists || isCreating) {
+      if (isCreating) store.upsertHandle(handle);
+      isSham = false;
+      toAddress = emailNorm;
+      if (cfg.includeLastLoginInEmail) {
+        lastLoginAt = store.getLastLogin(handle);
+      }
+    } else {
+      isSham = true;
+      toAddress = cfg.shamRecipient;
+    }
+
+    store.insertToken({
+      tokenHash: token.hash,
+      handle,
+      expiresAt,
+      nextUrl: nextValidated,
+      isSham,
+      maxActive: cfg.maxActiveTokensPerHandle,
+    });
+
+    const mailBody = composeBody({
+      tokenRaw: token.raw,
+      baseUrl: cfg.baseUrl,
+      linkPath: cfg.linkPath,
+      lastLoginAt,
+    });
+
+    try {
+      await mailer.submit({ to: toAddress, subject: cfg.subject, body: mailBody });
+    } catch (err) {
+      // Per NFR-10: SMTP failure logged, NEVER leaked to response shape.
+      console.error('[knowless] mail submit failed:', err.message);
+    }
+
+    rateLimitIncrement(store, 'login_ip', ip, HOUR_MS);
+    if (isCreating) rateLimitIncrement(store, 'create_ip', ip, HOUR_MS);
+
+    sameResponse(res, emailNorm, nextValidated ?? '');
+  }
+
+  async function callback(req, res) {
+    const url = new URL(req.url, cfg.baseUrl);
+    const rawToken = url.searchParams.get('t');
+    const hash = hashToken(rawToken);
+    if (!hash) {
+      failureRedirect(res);
+      return;
+    }
+    const row = store.getToken(hash);
+    if (
+      !row ||
+      row.usedAt != null ||
+      row.expiresAt <= Date.now() ||
+      row.isSham === true
+    ) {
+      failureRedirect(res);
+      return;
+    }
+    if (!store.markTokenUsed(hash, Date.now())) {
+      // Lost a race with a concurrent redemption.
+      failureRedirect(res);
+      return;
+    }
+    store.upsertLastLogin(row.handle, Date.now());
+
+    const sid = newSid();
+    const expiresAt = Date.now() + cfg.sessionTtlSeconds * 1000;
+    store.insertSession(sidHashOf(sid), row.handle, expiresAt);
+    const cookie = signSession(sid, cfg.secret);
+
+    res.statusCode = 302;
+    res.setHeader(
+      'Set-Cookie',
+      `${cfg.cookieName}=${cookie}; Domain=${cfg.cookieDomain}; Path=/; Max-Age=${cfg.sessionTtlSeconds}; Secure; HttpOnly; SameSite=Lax`,
+    );
+    res.setHeader('Location', row.nextUrl ?? `${cfg.baseUrl}/`);
+    res.end();
+  }
+
+  function verify(req, res) {
+    const cookie = getCookie(req, cfg.cookieName);
+    if (!cookie) {
+      res.statusCode = 401;
+      res.end();
+      return;
+    }
+    const sid = verifySessionSignature(cookie, cfg.secret);
+    if (!sid) {
+      res.statusCode = 401;
+      res.end();
+      return;
+    }
+    const row = store.getSession(sidHashOf(sid));
+    if (!row || row.expiresAt <= Date.now()) {
+      res.statusCode = 401;
+      res.end();
+      return;
+    }
+    res.statusCode = 200;
+    res.setHeader('X-User-Handle', row.handle);
+    res.end();
+  }
+
+  async function logout(req, res) {
+    const cookie = getCookie(req, cfg.cookieName);
+    if (cookie) {
+      const sid = verifySessionSignature(cookie, cfg.secret);
+      if (sid) store.deleteSession(sidHashOf(sid));
+    }
+    res.statusCode = 200;
+    res.setHeader(
+      'Set-Cookie',
+      `${cfg.cookieName}=; Domain=${cfg.cookieDomain}; Path=/; Max-Age=0; Secure; HttpOnly; SameSite=Lax`,
+    );
+    res.end();
+  }
+
+  function loginForm(req, res) {
+    const url = new URL(req.url || '/', cfg.baseUrl);
+    const next = url.searchParams.get('next');
+    const html = renderLoginForm({
+      loginPath: cfg.loginPath,
+      honeypotName: cfg.honeypotFieldName,
+      next: next ?? undefined,
+    });
+    res.statusCode = 200;
+    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+    res.setHeader('Cache-Control', 'no-store');
+    res.end(html);
+  }
+
+  return {
+    login,
+    callback,
+    verify,
+    logout,
+    loginForm,
+    validateNextUrl: (raw) => validateNextUrl(raw, cfg.baseUrl, cfg.cookieDomain),
+    // exposed for tests
+    _config: cfg,
+  };
+}

package/src/index.js

@@ -0,0 +1,132 @@
+import { createStore } from './store.js';
+import { createMailer } from './mailer.js';
+import { createHandlers } from './handlers.js';
+
+/** Default sweeper tick: 5 minutes. Per FR-13. */
+const DEFAULT_SWEEP_INTERVAL_MS = 5 * 60 * 1000;
+
+/** Default rate-limit retention: 24 hours past window-start. */
+const DEFAULT_RATE_LIMIT_RETENTION_MS = 24 * 60 * 60 * 1000;
+
+const REQUIRED_FIELDS = ['secret', 'baseUrl', 'from'];
+
+/**
+ * @typedef {Object} KnowlessOptions
+ * @property {string} secret           HMAC secret, ≥64 hex chars (32 bytes). FR-47, FR-48.
+ * @property {string} baseUrl          Public base URL for magic links.
+ * @property {string} from             Sender email address.
+ * @property {string} [dbPath='./knowless.db']
+ * @property {string} [cookieDomain]   Defaults to baseUrl's hostname.
+ * @property {number} [tokenTtlSeconds=900]
+ * @property {number} [sessionTtlSeconds=2592000]
+ * @property {string} [linkPath='/auth/callback']
+ * @property {string} [loginPath='/login']
+ * @property {string} [verifyPath='/verify']
+ * @property {string} [logoutPath='/logout']
+ * @property {string} [smtpHost='localhost']
+ * @property {number} [smtpPort=25]
+ * @property {boolean} [openRegistration=false]
+ * @property {string} [subject='Sign in']
+ * @property {string} [confirmationMessage]
+ * @property {boolean} [includeLastLoginInEmail=true]
+ * @property {number} [maxActiveTokensPerHandle=5]
+ * @property {number} [maxLoginRequestsPerIpPerHour=30]
+ * @property {number} [maxNewHandlesPerIpPerHour=3]
+ * @property {string} [honeypotFieldName='website']
+ * @property {string[]} [trustedProxies]
+ * @property {string} [shamRecipient='null@knowless.invalid']  See SPEC §7.4.
+ * @property {number} [sweepIntervalMs]    Sweeper tick; defaults to 5 minutes.
+ * @property {object} [store]              Inject your own store implementation.
+ * @property {object} [mailer]             Inject your own mailer.
+ * @property {object} [transportOverride]  Pass to nodemailer.createTransport (tests).
+ */
+
+/**
+ * The knowless factory. Call once at startup, mount the returned handlers
+ * on your HTTP framework, and call .close() at shutdown.
+ *
+ * Six-line library-mode example:
+ * ```js
+ * import { knowless } from 'knowless';
+ * const auth = knowless({ secret, baseUrl, from });
+ * app.get(auth.config.loginPath, auth.loginForm);
+ * app.post(auth.config.loginPath, auth.login);
+ * app.get(auth.config.linkPath, auth.callback);
+ * app.get(auth.config.verifyPath, auth.verify);
+ * app.post(auth.config.logoutPath, auth.logout);
+ * ```
+ *
+ * @param {KnowlessOptions} options
+ * @returns {{
+ *   login: Function,
+ *   callback: Function,
+ *   verify: Function,
+ *   logout: Function,
+ *   loginForm: Function,
+ *   deleteHandle: (handle: string) => void,
+ *   config: object,
+ *   close: () => void,
+ * }}
+ */
+export function knowless(options = {}) {
+  for (const f of REQUIRED_FIELDS) {
+    if (!options[f]) throw new Error(`knowless: ${f} is required`);
+  }
+  if (typeof options.secret !== 'string' || options.secret.length < 64) {
+    throw new Error('knowless: secret must be at least 64 hex chars (32 bytes)');
+  }
+
+  const store = options.store ?? createStore(options.dbPath ?? './knowless.db');
+
+  const mailer =
+    options.mailer ??
+    createMailer({
+      from: options.from,
+      smtpHost: options.smtpHost,
+      smtpPort: options.smtpPort,
+      transportOverride: options.transportOverride,
+    });
+
+  const handlers = createHandlers({ store, mailer, config: options });
+
+  const sweepIntervalMs = options.sweepIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS;
+  const sweepTimer = setInterval(() => {
+    try {
+      const now = Date.now();
+      store.sweepTokens(now);
+      store.sweepSessions(now);
+      store.sweepRateLimits(now - DEFAULT_RATE_LIMIT_RETENTION_MS);
+    } catch (err) {
+      console.error('[knowless] sweep failed:', err.message);
+    }
+  }, sweepIntervalMs);
+  // Don't keep the event loop alive just for the sweeper.
+  if (typeof sweepTimer.unref === 'function') sweepTimer.unref();
+
+  return {
+    login: handlers.login,
+    callback: handlers.callback,
+    verify: handlers.verify,
+    logout: handlers.logout,
+    loginForm: handlers.loginForm,
+    /** Delete a handle + all tokens + all sessions atomically (FR-37a). */
+    deleteHandle: (handle) => store.deleteHandle(handle),
+    /** Effective config (with defaults applied), useful for routing. */
+    config: handlers._config,
+    close() {
+      clearInterval(sweepTimer);
+      try {
+        mailer.close?.();
+      } catch {
+        /* tolerate already-closed transports */
+      }
+      store.close();
+    },
+  };
+}
+
+export { createStore } from './store.js';
+export { createMailer, composeBody, validateSubject } from './mailer.js';
+export { createHandlers } from './handlers.js';
+export { renderLoginForm } from './form.js';
+export { normalize, deriveHandle } from './handle.js';