kczx-user-management 1.0.0

package/src/totp.js

@@ -0,0 +1,136 @@
+'use strict'
+
+/**
+ * TOTP (RFC 6238) — time-based one-time passwords behind the login password.
+ *
+ * Zero-dependency by house rule: HMAC-SHA1 via node:crypto, base32 (RFC 4648)
+ * hand-rolled. The wire format matches every mainstream authenticator app
+ * (Google Authenticator, 1Password, Microsoft Authenticator, Aegis, …):
+ * 6 digits over a 30-second step, SHA-1, ±1 step of clock-drift tolerance.
+ *
+ * Verification is constant-time per candidate step and returns the matched
+ * step counter so callers can enforce single use (replay guard) by storing it
+ * on the user record and rejecting counters ≤ the last used one.
+ */
+
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+
+const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567'
+const OTP_STEP_SECONDS = 30
+const OTP_DIGITS = 6
+/** Accept the previous/next step so a slightly drifting clock still works. */
+const OTP_WINDOW = 1
+/** 160-bit secrets — the RFC 6238 recommendation and every app's minimum. */
+const SECRET_BYTES = 20
+
+function base32Encode(buf) {
+  let bits = 0
+  let value = 0
+  let out = ''
+  for (const byte of buf) {
+    value = (value << 8) | byte
+    bits += 8
+    while (bits >= 5) {
+      out += BASE32_ALPHABET[(value >>> (bits - 5)) & 31]
+      bits -= 5
+    }
+  }
+  if (bits > 0) out += BASE32_ALPHABET[(value << (5 - bits)) & 31]
+  return out
+}
+
+/** Tolerant decode: case-insensitive, ignores `=` padding and whitespace. */
+function base32Decode(str) {
+  const clean = String(str || '').toUpperCase().replace(/[=\s]/g, '')
+  const out = []
+  let bits = 0
+  let value = 0
+  for (const ch of clean) {
+    const idx = BASE32_ALPHABET.indexOf(ch)
+    if (idx === -1) return Buffer.alloc(0)
+    value = (value << 5) | idx
+    bits += 5
+    if (bits >= 8) {
+      out.push((value >>> (bits - 8)) & 0xff)
+      bits -= 8
+    }
+  }
+  return Buffer.from(out)
+}
+
+/** Fresh enrollment secret, base32 (authenticator manual-entry format). */
+function generateSecret() {
+  return base32Encode(randomBytes(SECRET_BYTES))
+}
+
+/** RFC 4226 HOTP — truncated HMAC over an 8-byte big-endian counter. */
+function hotp(secretBuf, counter, digits = OTP_DIGITS) {
+  const msg = Buffer.alloc(8)
+  msg.writeBigUInt64BE(BigInt(counter))
+  const digest = createHmac('sha1', secretBuf).update(msg).digest()
+  const offset = digest[digest.length - 1] & 0xf
+  const binary =
+    ((digest[offset] & 0x7f) << 24) |
+    (digest[offset + 1] << 16) |
+    (digest[offset + 2] << 8) |
+    digest[offset + 3]
+  return String(binary % 10 ** digits).padStart(digits, '0')
+}
+
+/** RFC 6238 TOTP — HOTP with the time step as counter. */
+function totpAt(secretBuf, unixSeconds, stepSeconds = OTP_STEP_SECONDS) {
+  return hotp(secretBuf, Math.floor(unixSeconds / stepSeconds))
+}
+
+/**
+ * Verify a user-supplied code. Tolerates surrounding whitespace, requires
+ * exactly `OTP_DIGITS` digits. Scans the ±OTP_WINDOW steps around `nowMs`,
+ * skipping any step ≤ `lastCounter` (replay / single-use guard). The
+ * constant-time comparison runs per candidate step; digit-length mismatch
+ * short-circuits before any HMAC work.
+ *
+ * @returns {{ ok: true, counter: number } | { ok: false }}
+ */
+function verifyTotp(secretBase32, code, { nowMs = Date.now(), lastCounter = 0 } = {}) {
+  const secret = base32Decode(secretBase32)
+  if (secret.length === 0) return { ok: false }
+  const normalized = String(code || '').replace(/\s+/g, '')
+  if (!new RegExp(`^\\d{${OTP_DIGITS}}$`).test(normalized)) return { ok: false }
+  const stepNow = Math.floor(nowMs / 1000 / OTP_STEP_SECONDS)
+  const given = Buffer.from(normalized, 'utf8')
+  for (let counter = stepNow + OTP_WINDOW; counter >= stepNow - OTP_WINDOW; counter -= 1) {
+    if (counter <= lastCounter) continue
+    const expected = Buffer.from(hotp(secret, counter), 'utf8')
+    if (given.length === expected.length && timingSafeEqual(given, expected)) {
+      return { ok: true, counter }
+    }
+  }
+  return { ok: false }
+}
+
+/** otpauth:// enrollment URI — the payload both QR codes and manual entry carry. */
+function otpauthUri({ username, secret, issuer = 'DSH' }) {
+  const label = encodeURIComponent(`${issuer}:${username}`)
+  const params = new URLSearchParams({
+    secret,
+    issuer,
+    algorithm: 'SHA1',
+    digits: String(OTP_DIGITS),
+    period: String(OTP_STEP_SECONDS),
+  })
+  return `otpauth://totp/${label}?${params.toString()}`
+}
+
+export {
+  OTP_STEP_SECONDS,
+  OTP_DIGITS,
+  OTP_WINDOW,
+  SECRET_BYTES,
+  base32Encode,
+  base32Decode,
+  generateSecret,
+  hotp,
+  totpAt,
+  verifyTotp,
+  otpauthUri,
+}

package/src/trusted-identity.js

@@ -0,0 +1,143 @@
+'use strict'
+
+/**
+ * Trusted upstream identity.
+ *
+ * In the merged deployment dsh-passwords is the ONLY login door: it
+ * authenticates the user, then signs that identity onto every request it
+ * proxies here. This layer therefore stops demanding a login of its own and
+ * instead trusts a signed header pair — while still observing every request,
+ * which is the whole reason user-management stays in the path: its gate feeds
+ * the access and operation ledgers.
+ *
+ * Trust conditions (all must hold):
+ *   - the TCP peer is loopback (the gateway listener binds 127.0.0.1, so only
+ *     the co-located dsh-passwords gateway can reach it at all);
+ *   - the timestamp is inside a narrow clock-skew window (replay guard);
+ *   - the HMAC over username/role/ip/timestamp matches, compared in constant
+ *     time.
+ *
+ * Cluster-free and cordis-free: pure functions over (req, secret) so the
+ * decision is testable without a listener — see test/trusted-identity.test.mjs.
+ */
+
+import { createHmac, timingSafeEqual } from 'node:crypto'
+
+/** Header names the signing gateway sets. Exported for tests and docs. */
+const TRUSTED_HEADERS = {
+  user: 'x-dsh-identity',
+  role: 'x-dsh-identity-role',
+  ip: 'x-dsh-identity-ip',
+  ts: 'x-dsh-identity-ts',
+  sig: 'x-dsh-identity-sig',
+}
+
+/** Canonical loopback peers (IPv4, IPv6, and the IPv4-mapped IPv6 form). */
+const LOOPBACK_PEERS = ['127.0.0.1', '::1', '::ffff:127.0.0.1']
+
+/** Reject signatures older/newer than this — a captured header must expire. */
+const MAX_SKEW_SECONDS = 60
+
+/** Strip an IPv4-mapped prefix so ::ffff:127.0.0.1 and 127.0.0.1 compare equal. */
+function normalizePeer(address) {
+  const value = String(address || '').trim().toLowerCase()
+  if (value.startsWith('::ffff:')) return value.slice('::ffff:'.length)
+  if (value.startsWith('[')) {
+    const end = value.indexOf(']')
+    return end === -1 ? value : value.slice(1, end)
+  }
+  return value
+}
+
+/**
+ * The signature both sides must agree on. One canonical string keeps the
+ * signing side (dsh-passwords) and this verifier in lockstep; the ip field is
+ * covered so a tampered ledger IP is a verification failure, not a silent
+ * rewrite of the audit trail.
+ *
+ * @param secret - shared HMAC key (dsh-passwords MCP_INTERNAL_SECRET).
+ * @param username - the authenticated user's name.
+ * @param role - 'admin' | 'user'.
+ * @param ip - client IP as seen by the signing gateway.
+ * @param ts - unix seconds, as a string.
+ * @returns hex HMAC-SHA256.
+ */
+function identitySignature(secret, username, role, ip, ts) {
+  return createHmac('sha256', String(secret))
+    .update(`${username}\n${role || ''}\n${ip || ''}\n${ts}`)
+    .digest('hex')
+}
+
+/** Constant-time hex compare; length mismatch short-circuits. */
+function signatureMatches(expected, given) {
+  const a = Buffer.from(String(expected), 'utf8')
+  const b = Buffer.from(String(given), 'utf8')
+  if (a.length !== b.length) return false
+  try { return timingSafeEqual(a, b) } catch { return false }
+}
+
+/**
+ * Build the verifier. Returns null when no secret is configured — an unsigned
+ * deployment (user-management standing alone) keeps its own login and this
+ * module stays completely inert.
+ *
+ * @param options.secret - shared HMAC key; empty disables trust entirely.
+ * @param options.peers - accepted peer addresses; defaults to loopback only.
+ * @param options.maxSkewSeconds - timestamp window; defaults to 60.
+ * @param options.now - clock injection for tests (ms).
+ * @returns {(req: object) => ({ user: object } | null)}
+ */
+function createTrustedIdentity(options = {}) {
+  const secret = String(options.secret || '')
+  const peers = new Set(
+    (Array.isArray(options.peers) && options.peers.length ? options.peers : LOOPBACK_PEERS)
+      .map((entry) => normalizePeer(entry)),
+  )
+  const maxSkew = Number.isFinite(options.maxSkewSeconds) ? options.maxSkewSeconds : MAX_SKEW_SECONDS
+  const now = typeof options.now === 'function' ? options.now : () => Date.now()
+
+  return function resolveTrusted(req) {
+    if (secret === '') return null
+    const peer = normalizePeer(req && req.socket && req.socket.remoteAddress)
+    if (!peers.has(peer)) return null
+
+    const headers = (req && req.headers) || {}
+    const username = headers[TRUSTED_HEADERS.user]
+    const role = headers[TRUSTED_HEADERS.role]
+    const ip = headers[TRUSTED_HEADERS.ip]
+    const ts = headers[TRUSTED_HEADERS.ts]
+    const sig = headers[TRUSTED_HEADERS.sig]
+    if (typeof username !== 'string' || username === '') return null
+    if (typeof ts !== 'string' || ts === '' || typeof sig !== 'string' || sig === '') return null
+
+    const seconds = Number(ts)
+    if (!Number.isFinite(seconds)) return null
+    const skew = Math.abs(now() / 1000 - seconds)
+    if (skew > maxSkew) return null
+
+    const expected = identitySignature(secret, username, typeof role === 'string' ? role : '', typeof ip === 'string' ? ip : '', ts)
+    if (!signatureMatches(expected, sig)) return null
+
+    return {
+      // Shape matches a store session so every downstream reader (gateway
+      // routing, handleApi, the ledger hooks, the client's /session call)
+      // works unchanged. The id is namespaced: it is NOT a store user id.
+      user: {
+        id: `upstream:${username}`,
+        username,
+        role: role === 'admin' ? 'admin' : 'user',
+      },
+      upstream: true,
+      clientIp: typeof ip === 'string' ? ip : '',
+    }
+  }
+}
+
+export {
+  TRUSTED_HEADERS,
+  LOOPBACK_PEERS,
+  MAX_SKEW_SECONDS,
+  normalizePeer,
+  identitySignature,
+  createTrustedIdentity,
+}