knowless 0.1.0

package/src/mailer.js

@@ -0,0 +1,156 @@
+import crypto from 'node:crypto';
+import nodemailer from 'nodemailer';
+
+const ASCII_RE = /^[\x00-\x7f]*$/;
+
+/**
+ * Compose a fully-formed RFC822 message per SPEC §12.1. Nodemailer's
+ * own MimeNode disagreed with our SPEC on Content-Transfer-Encoding
+ * (insisted on QP or base64 even for ASCII bodies, breaking the URL
+ * with QP soft-breaks per the v0.11 POC finding). We sidestep its
+ * encoding by providing the raw message and using nodemailer only as
+ * the SMTP submission transport.
+ *
+ * @param {object} args
+ * @param {string} args.from
+ * @param {string} args.to
+ * @param {string} args.subject
+ * @param {string} args.body  ASCII-only plain text
+ * @returns {string} RFC822 message with CRLF line endings
+ */
+function composeRaw({ from, to, subject, body }) {
+  const fromDomain = from.includes('@') ? from.split('@').pop() : 'localhost';
+  const messageId = `<${crypto.randomUUID()}@${fromDomain}>`;
+  const date = new Date().toUTCString();
+  const headers = [
+    `From: ${from}`,
+    `To: ${to}`,
+    `Subject: ${subject}`,
+    `Date: ${date}`,
+    `Message-ID: ${messageId}`,
+    'MIME-Version: 1.0',
+    'Content-Type: text/plain; charset=utf-8',
+    'Content-Transfer-Encoding: 7bit',
+  ].join('\r\n');
+  const normalized = body.replace(/\r\n/g, '\n').replace(/\n/g, '\r\n');
+  return `${headers}\r\n\r\n${normalized}`;
+}
+
+/**
+ * Compose the plain-text body of the magic-link email per SPEC §12.2.
+ *
+ * Body shape (default):
+ *   Click to sign in:
+ *
+ *   <magic link URL>
+ *
+ *   This link expires in 15 minutes. If you didn't request this,
+ *   ignore this email.
+ *
+ * Plus, when lastLoginAt is provided:
+ *
+ *   Last sign-in: <ISO 8601 UTC timestamp>.
+ *   If that wasn't you, do not click the link above.
+ *
+ * The URL appears on its own line. Body is ASCII-only.
+ *
+ * @param {object} args
+ * @param {string} args.tokenRaw  43-char base64url token
+ * @param {string} args.baseUrl   e.g. 'https://app.example.com'
+ * @param {string} args.linkPath  e.g. '/auth/callback'
+ * @param {number|null} [args.lastLoginAt] Unix ms; null/undefined to omit
+ * @returns {string} the body text (ASCII)
+ */
+export function composeBody({ tokenRaw, baseUrl, linkPath, lastLoginAt }) {
+  const url = `${baseUrl}${linkPath}?t=${tokenRaw}`;
+  let body =
+    'Click to sign in:\n\n' +
+    `${url}\n\n` +
+    "This link expires in 15 minutes. If you didn't request this,\n" +
+    'ignore this email.\n';
+  if (lastLoginAt != null) {
+    const iso = new Date(lastLoginAt).toISOString();
+    body +=
+      `\nLast sign-in: ${iso}.\n` + 'If that wasn\'t you, do not click the link above.\n';
+  }
+  if (!ASCII_RE.test(body)) {
+    throw new Error('mail body contains non-ASCII');
+  }
+  return body;
+}
+
+/**
+ * Validate operator-overridden subject per SPEC §12.5.
+ * Throws on invalid; warns (returns warnings array) on suspicious-but-allowed.
+ *
+ * @param {string} subject
+ * @returns {string[]} warnings, possibly empty
+ */
+export function validateSubject(subject) {
+  if (typeof subject !== 'string' || subject.length === 0) {
+    throw new Error('subject must be a non-empty string');
+  }
+  if (subject.length > 60) throw new Error('subject longer than 60 chars');
+  if (!ASCII_RE.test(subject)) throw new Error('subject contains non-ASCII');
+  const warnings = [];
+  const triggers = ['!!', '$$', 'FREE', 'URGENT', 'WINNER'];
+  for (const t of triggers) {
+    if (subject.includes(t)) warnings.push(`subject contains likely spam trigger: "${t}"`);
+  }
+  return warnings;
+}
+
+/**
+ * Create a knowless mailer per SPEC §12.
+ *
+ * Submits to a localhost MTA over plain SMTP. Forces 7bit encoding,
+ * strips X-Mailer, refuses non-ASCII bodies. The submit() method is
+ * the only public surface.
+ *
+ * For tests: pass `transportOverride` (e.g. nodemailer.createTransport
+ * with streamTransport:true) to capture the raw bytes without an MTA.
+ *
+ * @param {object} cfg
+ * @param {string} cfg.from           sender, e.g. 'auth@app.example.com'
+ * @param {string} [cfg.smtpHost='localhost']
+ * @param {number} [cfg.smtpPort=25]
+ * @param {object} [cfg.transportOverride] for tests
+ * @returns {{ submit(args: {to:string, subject:string, body:string}): Promise<any>, close(): void }}
+ */
+export function createMailer(cfg) {
+  const { from, smtpHost = 'localhost', smtpPort = 25, transportOverride } = cfg;
+  if (typeof from !== 'string' || from.length === 0) {
+    throw new Error('mailer: from is required');
+  }
+  if (!ASCII_RE.test(from)) throw new Error('mailer: from must be ASCII');
+
+  const transport =
+    transportOverride ??
+    nodemailer.createTransport({
+      host: smtpHost,
+      port: smtpPort,
+      secure: false,
+      ignoreTLS: true, // localhost only; SPEC §10.4 / FR-15
+      // Safety: refuse SMTP auth — this transport must not carry credentials.
+      auth: undefined,
+    });
+
+  return {
+    async submit({ to, subject, body }) {
+      if (typeof to !== 'string' || !ASCII_RE.test(to)) {
+        throw new Error('mailer: recipient must be ASCII');
+      }
+      if (!ASCII_RE.test(body)) {
+        throw new Error('mailer: body must be ASCII');
+      }
+      const raw = composeRaw({ from, to, subject, body });
+      return transport.sendMail({
+        envelope: { from, to: [to] },
+        raw,
+      });
+    },
+    close() {
+      if (typeof transport.close === 'function') transport.close();
+    },
+  };
+}

package/src/session.js

@@ -0,0 +1,75 @@
+import crypto from 'node:crypto';
+
+/**
+ * Domain-separation tag for session signatures. See SPEC §3.4 / §5.2.
+ * The trailing 0x00 prevents prefix-collision with future HMAC uses
+ * of the same secret.
+ */
+const SESS_TAG = Buffer.from('sess\x00');
+
+/**
+ * Generate a new session id: 32 random bytes, base64url-encoded.
+ * @returns {string} 43-char base64url
+ */
+export function newSid() {
+  return crypto.randomBytes(32).toString('base64url');
+}
+
+/**
+ * @param {string} sidB64u
+ * @param {Buffer|string} secret
+ * @returns {string} 64-char lowercase hex
+ */
+function signature(sidB64u, secret) {
+  return crypto
+    .createHmac('sha256', secret)
+    .update(SESS_TAG)
+    .update(sidB64u, 'utf8')
+    .digest('hex');
+}
+
+/**
+ * Sign a sid into a session cookie value per SPEC §5.1.
+ * Cookie format: <sid_b64u>.<sig_hex> (108 chars total).
+ *
+ * @param {string} sidB64u 43-char base64url sid (typically from newSid())
+ * @param {Buffer|string} secret operator HMAC secret
+ * @returns {string} cookie value
+ */
+export function signSession(sidB64u, secret) {
+  if (typeof sidB64u !== 'string' || !/^[A-Za-z0-9_-]+$/.test(sidB64u)) {
+    throw new Error('invalid sid');
+  }
+  if (!secret || (typeof secret !== 'string' && !Buffer.isBuffer(secret))) {
+    throw new Error('secret required');
+  }
+  return `${sidB64u}.${signature(sidB64u, secret)}`;
+}
+
+/**
+ * Verify a cookie value's signature per SPEC §5.5.
+ * Returns the sid_b64u string on success; null on any failure (bad
+ * format, signature mismatch, malformed inputs). Caller does the
+ * DB lookup that resolves sid → handle.
+ *
+ * Constant-time comparison via crypto.timingSafeEqual.
+ *
+ * @param {string} cookie cookie value: <sid>.<sig>
+ * @param {Buffer|string} secret operator HMAC secret
+ * @returns {string|null}
+ */
+export function verifySessionSignature(cookie, secret) {
+  if (typeof cookie !== 'string' || cookie.length === 0) return null;
+  const dot = cookie.indexOf('.');
+  if (dot < 0) return null;
+  const sidB64u = cookie.slice(0, dot);
+  const sigHex = cookie.slice(dot + 1);
+  if (sigHex.length !== 64) return null;
+  if (!/^[a-f0-9]{64}$/.test(sigHex)) return null;
+  if (sidB64u.length === 0 || !/^[A-Za-z0-9_-]+$/.test(sidB64u)) return null;
+  const expected = signature(sidB64u, secret);
+  const a = Buffer.from(sigHex, 'hex');
+  const b = Buffer.from(expected, 'hex');
+  if (!crypto.timingSafeEqual(a, b)) return null;
+  return sidB64u;
+}

package/src/store.js

@@ -0,0 +1,265 @@
+import Database from 'better-sqlite3';
+
+/**
+ * Default token-sweeper grace: keep used tokens for 24h after redemption
+ * to support audit correlation, then delete. SPEC §4.6.
+ */
+const DEFAULT_TOKEN_GRACE_MS = 24 * 60 * 60 * 1000;
+
+const SCHEMA_VERSION = '1';
+
+const DDL = `
+  CREATE TABLE IF NOT EXISTS handles (
+    handle         TEXT    PRIMARY KEY,
+    last_login_at  INTEGER
+  );
+
+  CREATE TABLE IF NOT EXISTS tokens (
+    token_hash   TEXT    PRIMARY KEY,
+    handle       TEXT    NOT NULL,
+    expires_at   INTEGER NOT NULL,
+    used_at      INTEGER,
+    next_url     TEXT,
+    is_sham      INTEGER NOT NULL DEFAULT 0
+  );
+  CREATE INDEX IF NOT EXISTS idx_tokens_expires ON tokens(expires_at);
+  CREATE INDEX IF NOT EXISTS idx_tokens_handle  ON tokens(handle);
+
+  CREATE TABLE IF NOT EXISTS sessions (
+    sid_hash    TEXT    PRIMARY KEY,
+    handle      TEXT    NOT NULL,
+    expires_at  INTEGER NOT NULL
+  );
+  CREATE INDEX IF NOT EXISTS idx_sessions_expires ON sessions(expires_at);
+
+  CREATE TABLE IF NOT EXISTS rate_limits (
+    scope         TEXT    NOT NULL,
+    key           TEXT    NOT NULL,
+    window_start  INTEGER NOT NULL,
+    count         INTEGER NOT NULL,
+    PRIMARY KEY (scope, key, window_start)
+  );
+  CREATE INDEX IF NOT EXISTS idx_rate_limits_window ON rate_limits(window_start);
+
+  CREATE TABLE IF NOT EXISTS meta (
+    key   TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+  );
+`;
+
+/**
+ * Create a knowless storage backend. SPEC §6 (schema), §13 (interface).
+ *
+ * @param {string} [dbPath=':memory:'] path to SQLite file, or ':memory:'
+ * @returns {Store}
+ */
+export function createStore(dbPath = ':memory:') {
+  const db = new Database(dbPath);
+  db.pragma('journal_mode = WAL');
+  db.pragma('synchronous = NORMAL');
+  db.pragma('foreign_keys = OFF');
+  db.pragma('temp_store = MEMORY');
+  db.exec(DDL);
+
+  const existing = db
+    .prepare("SELECT value FROM meta WHERE key = 'schema_version'")
+    .get();
+  if (!existing) {
+    db.prepare("INSERT INTO meta (key, value) VALUES ('schema_version', ?)").run(
+      SCHEMA_VERSION,
+    );
+  } else if (existing.value !== SCHEMA_VERSION) {
+    throw new Error(`unsupported schema_version: ${existing.value}`);
+  }
+
+  const stmt = {
+    handleExists: db.prepare('SELECT 1 AS one FROM handles WHERE handle = ?'),
+    upsertHandleNoLogin: db.prepare(
+      `INSERT INTO handles (handle, last_login_at) VALUES (?, NULL)
+       ON CONFLICT(handle) DO NOTHING`,
+    ),
+    upsertLastLogin: db.prepare(
+      `INSERT INTO handles (handle, last_login_at) VALUES (?, ?)
+       ON CONFLICT(handle) DO UPDATE SET last_login_at = excluded.last_login_at`,
+    ),
+    getLastLogin: db.prepare(
+      'SELECT last_login_at AS lastLoginAt FROM handles WHERE handle = ?',
+    ),
+    deleteHandleRow: db.prepare('DELETE FROM handles WHERE handle = ?'),
+    deleteHandleTokens: db.prepare('DELETE FROM tokens WHERE handle = ?'),
+    deleteHandleSessions: db.prepare('DELETE FROM sessions WHERE handle = ?'),
+
+    insertToken: db.prepare(
+      `INSERT INTO tokens (token_hash, handle, expires_at, used_at, next_url, is_sham)
+       VALUES (?, ?, ?, NULL, ?, ?)`,
+    ),
+    getToken: db.prepare(
+      `SELECT handle, expires_at AS expiresAt, used_at AS usedAt,
+              next_url AS nextUrl, is_sham AS isSham
+       FROM tokens WHERE token_hash = ?`,
+    ),
+    markTokenUsed: db.prepare(
+      `UPDATE tokens SET used_at = ?
+       WHERE token_hash = ? AND used_at IS NULL`,
+    ),
+    countActiveTokens: db.prepare(
+      `SELECT COUNT(*) AS n FROM tokens
+       WHERE handle = ? AND used_at IS NULL AND expires_at > ?`,
+    ),
+    evictOldestActive: db.prepare(
+      `DELETE FROM tokens
+       WHERE token_hash = (
+         SELECT token_hash FROM tokens
+         WHERE handle = ? AND used_at IS NULL AND expires_at > ?
+         ORDER BY expires_at ASC LIMIT 1
+       )`,
+    ),
+    sweepTokens: db.prepare(
+      `DELETE FROM tokens
+       WHERE expires_at <= ?
+          OR (used_at IS NOT NULL AND used_at <= ?)`,
+    ),
+
+    insertSession: db.prepare(
+      'INSERT INTO sessions (sid_hash, handle, expires_at) VALUES (?, ?, ?)',
+    ),
+    getSession: db.prepare(
+      'SELECT handle, expires_at AS expiresAt FROM sessions WHERE sid_hash = ?',
+    ),
+    deleteSession: db.prepare('DELETE FROM sessions WHERE sid_hash = ?'),
+    sweepSessions: db.prepare('DELETE FROM sessions WHERE expires_at <= ?'),
+
+    rateLimitIncrement: db.prepare(
+      `INSERT INTO rate_limits (scope, key, window_start, count)
+       VALUES (?, ?, ?, 1)
+       ON CONFLICT(scope, key, window_start)
+       DO UPDATE SET count = count + 1
+       RETURNING count`,
+    ),
+    rateLimitGet: db.prepare(
+      `SELECT count FROM rate_limits
+       WHERE scope = ? AND key = ? AND window_start = ?`,
+    ),
+    sweepRateLimits: db.prepare('DELETE FROM rate_limits WHERE window_start < ?'),
+  };
+
+  // Transactional cap-check + insert per SPEC §4.7.
+  const insertTokenAtomic = db.transaction(
+    (tokenHash, handle, expiresAt, nextUrl, isSham, maxActive, now) => {
+      if (maxActive > 0) {
+        const { n: count } = stmt.countActiveTokens.get(handle, now);
+        let toEvict = count - maxActive + 1;
+        while (toEvict > 0) {
+          stmt.evictOldestActive.run(handle, now);
+          toEvict--;
+        }
+      }
+      stmt.insertToken.run(tokenHash, handle, expiresAt, nextUrl, isSham);
+    },
+  );
+
+  // Transactional account deletion per FR-37a.
+  const deleteHandleAtomic = db.transaction((handle) => {
+    stmt.deleteHandleSessions.run(handle);
+    stmt.deleteHandleTokens.run(handle);
+    stmt.deleteHandleRow.run(handle);
+  });
+
+  return {
+    // --- Handle ---
+    handleExists(handle) {
+      return !!stmt.handleExists.get(handle);
+    },
+    upsertHandle(handle) {
+      stmt.upsertHandleNoLogin.run(handle);
+    },
+    deleteHandle(handle) {
+      deleteHandleAtomic(handle);
+    },
+
+    // --- Token ---
+    insertToken(args) {
+      const {
+        tokenHash,
+        handle,
+        expiresAt,
+        nextUrl = null,
+        isSham = false,
+        maxActive = 0,
+        now = Date.now(),
+      } = args;
+      insertTokenAtomic(
+        tokenHash,
+        handle,
+        expiresAt,
+        nextUrl,
+        isSham ? 1 : 0,
+        maxActive,
+        now,
+      );
+    },
+    getToken(tokenHash) {
+      const row = stmt.getToken.get(tokenHash);
+      if (!row) return null;
+      return {
+        handle: row.handle,
+        expiresAt: row.expiresAt,
+        usedAt: row.usedAt,
+        nextUrl: row.nextUrl,
+        isSham: row.isSham === 1,
+      };
+    },
+    markTokenUsed(tokenHash, usedAt) {
+      return stmt.markTokenUsed.run(usedAt, tokenHash).changes > 0;
+    },
+    countActiveTokens(handle, now = Date.now()) {
+      return stmt.countActiveTokens.get(handle, now).n;
+    },
+    evictOldestActiveToken(handle, now = Date.now()) {
+      return stmt.evictOldestActive.run(handle, now).changes;
+    },
+    sweepTokens(now = Date.now(), graceMs = DEFAULT_TOKEN_GRACE_MS) {
+      return stmt.sweepTokens.run(now, now - graceMs).changes;
+    },
+
+    // --- Last login ---
+    upsertLastLogin(handle, at) {
+      stmt.upsertLastLogin.run(handle, at);
+    },
+    getLastLogin(handle) {
+      const row = stmt.getLastLogin.get(handle);
+      return row ? row.lastLoginAt : null;
+    },
+
+    // --- Session ---
+    insertSession(sidHash, handle, expiresAt) {
+      stmt.insertSession.run(sidHash, handle, expiresAt);
+    },
+    getSession(sidHash) {
+      return stmt.getSession.get(sidHash) ?? null;
+    },
+    deleteSession(sidHash) {
+      return stmt.deleteSession.run(sidHash).changes > 0;
+    },
+    sweepSessions(now = Date.now()) {
+      return stmt.sweepSessions.run(now).changes;
+    },
+
+    // --- Rate limiting ---
+    rateLimitIncrement(scope, key, windowStart) {
+      return stmt.rateLimitIncrement.get(scope, key, windowStart).count;
+    },
+    rateLimitGet(scope, key, windowStart) {
+      const row = stmt.rateLimitGet.get(scope, key, windowStart);
+      return row ? row.count : 0;
+    },
+    sweepRateLimits(olderThan) {
+      return stmt.sweepRateLimits.run(olderThan).changes;
+    },
+
+    // --- Lifecycle ---
+    close() {
+      db.close();
+    },
+  };
+}

package/src/token.js

@@ -0,0 +1,38 @@
+import crypto from 'node:crypto';
+
+/**
+ * Issue a magic-link token per SPEC §4.1.
+ *
+ * Returns the raw token (for embedding in the email URL) and the hash
+ * (for storage). Raw bytes never touch persistent storage; only the
+ * hash does. See FR-13, FR-34.
+ *
+ * @returns {{ raw: string, hash: string }}
+ *   raw  — 43-char base64url (32 bytes, no padding)
+ *   hash — 64-char lowercase hex (SHA-256 of the 32 raw bytes)
+ */
+export function issueToken() {
+  const bytes = crypto.randomBytes(32);
+  return {
+    raw: bytes.toString('base64url'),
+    hash: crypto.createHash('sha256').update(bytes).digest('hex'),
+  };
+}
+
+/**
+ * Hash a raw token for store lookup per SPEC §4.5.
+ *
+ * Returns null on malformed input (wrong length, wrong alphabet, decode
+ * fail). Caller treats null exactly like "no row found" — the silent
+ * failure path of verifyToken.
+ *
+ * @param {string} raw 43-char base64url token from a magic link
+ * @returns {string|null} 64-char lowercase hex hash, or null
+ */
+export function hashToken(raw) {
+  if (typeof raw !== 'string' || raw.length === 0 || raw.length > 64) return null;
+  if (!/^[A-Za-z0-9_-]+$/.test(raw)) return null;
+  const bytes = Buffer.from(raw, 'base64url');
+  if (bytes.length !== 32) return null;
+  return crypto.createHash('sha256').update(bytes).digest('hex');
+}