dsh-plugin-auth 0.1.2

package/src/policy.js

@@ -0,0 +1,103 @@
+// @ts-check
+/**
+ * Auth policy: enterprise defaults merged with an optional
+ * $DSH_HOME/auth/config.json override object. Pure module — it performs no I/O
+ * (the caller reads the file and passes the parsed object) and imports no peer
+ * packages, so it runs under `node --test` standalone.
+ */
+
+/**
+ * @typedef {object} ScryptParams
+ * @property {number} N       CPU/memory cost (power of two).
+ * @property {number} r       Block size.
+ * @property {number} p       Parallelization.
+ * @property {number} keylen  Derived key length in bytes.
+ * @property {number} maxmem  scrypt memory ceiling in bytes.
+ */
+
+/**
+ * @typedef {object} AuthPolicy
+ * @property {number} sessionAbsoluteTtlMs Hard session lifetime cap.
+ * @property {number} sessionIdleTtlMs     Sliding idle window.
+ * @property {number} sweepIntervalMs      Background expired-session sweep cadence.
+ * @property {number} lockoutThreshold     Consecutive failures before lockout.
+ * @property {number} lockoutBaseMs        First lockout duration.
+ * @property {number} lockoutMaxMs         Cap for exponential backoff.
+ * @property {number} lockoutWindowMs      Idle time after which the counter resets.
+ * @property {number} minPasswordLength    Minimum acceptable password length.
+ * @property {boolean} secure              true behind TLS: sets Secure + __Host- cookie.
+ * @property {'Strict'|'Lax'} sameSite     Cookie SameSite attribute.
+ * @property {string} cookiePath           Cookie Path attribute.
+ * @property {string[]} trustedOrigins     Extra allowed Origin values for POST.
+ * @property {ScryptParams} scrypt         Password hashing cost parameters.
+ */
+
+/** @type {AuthPolicy} */
+export const DEFAULT_POLICY = {
+  sessionAbsoluteTtlMs: 12 * 60 * 60 * 1000,
+  sessionIdleTtlMs: 2 * 60 * 60 * 1000,
+  sweepIntervalMs: 5 * 60 * 1000,
+  lockoutThreshold: 5,
+  lockoutBaseMs: 30 * 1000,
+  lockoutMaxMs: 15 * 60 * 1000,
+  lockoutWindowMs: 15 * 60 * 1000,
+  minPasswordLength: 12,
+  secure: false,
+  sameSite: 'Strict',
+  cookiePath: '/',
+  trustedOrigins: [],
+  scrypt: { N: 16384, r: 8, p: 1, keylen: 64, maxmem: 64 * 1024 * 1024 },
+}
+
+/**
+ * Merge a partial override object onto the defaults with light validation.
+ * Unknown keys are ignored; out-of-range values fall back to the default so a
+ * malformed config file can never weaken the gate silently past sane bounds.
+ * @param {Partial<AuthPolicy>} [overrides]
+ * @returns {AuthPolicy}
+ */
+export function resolvePolicy(overrides = {}) {
+  const src = overrides && typeof overrides === 'object' ? overrides : {}
+  /** @type {AuthPolicy} */
+  const out = { ...DEFAULT_POLICY, scrypt: { ...DEFAULT_POLICY.scrypt }, trustedOrigins: [...DEFAULT_POLICY.trustedOrigins] }
+  /** @type {(v: unknown, d: number, opts?: {min?: number}) => number} */
+  const num = (v, d, { min = 1 } = {}) => (typeof v === 'number' && Number.isFinite(v) && v >= min ? v : d)
+
+  out.sessionAbsoluteTtlMs = num(src.sessionAbsoluteTtlMs, out.sessionAbsoluteTtlMs)
+  out.sessionIdleTtlMs = num(src.sessionIdleTtlMs, out.sessionIdleTtlMs)
+  out.sweepIntervalMs = num(src.sweepIntervalMs, out.sweepIntervalMs)
+  out.lockoutThreshold = num(src.lockoutThreshold, out.lockoutThreshold)
+  out.lockoutBaseMs = num(src.lockoutBaseMs, out.lockoutBaseMs)
+  out.lockoutMaxMs = num(src.lockoutMaxMs, out.lockoutMaxMs)
+  out.lockoutWindowMs = num(src.lockoutWindowMs, out.lockoutWindowMs)
+  out.minPasswordLength = num(src.minPasswordLength, out.minPasswordLength, { min: 8 })
+  out.secure = typeof src.secure === 'boolean' ? src.secure : out.secure
+  out.sameSite = src.sameSite === 'Lax' ? 'Lax' : 'Strict'
+  out.cookiePath = typeof src.cookiePath === 'string' && src.cookiePath.startsWith('/') ? src.cookiePath : out.cookiePath
+  out.trustedOrigins = Array.isArray(src.trustedOrigins)
+    ? src.trustedOrigins.filter((o) => typeof o === 'string')
+    : out.trustedOrigins
+
+  if (src.scrypt && typeof src.scrypt === 'object') {
+    out.scrypt.N = num(src.scrypt.N, out.scrypt.N, { min: 2 })
+    out.scrypt.r = num(src.scrypt.r, out.scrypt.r)
+    out.scrypt.p = num(src.scrypt.p, out.scrypt.p)
+    out.scrypt.keylen = num(src.scrypt.keylen, out.scrypt.keylen, { min: 16 })
+    out.scrypt.maxmem = num(src.scrypt.maxmem, out.scrypt.maxmem, { min: 1024 * 1024 })
+  }
+
+  // A __Host- prefixed cookie is only valid with Secure and Path=/; keep the
+  // policy self-consistent so cookieName() can key off `secure` alone.
+  if (out.secure) out.cookiePath = '/'
+  return out
+}
+
+/**
+ * Session cookie name. The __Host- prefix (browser-enforced: requires Secure,
+ * Path=/, and no Domain) is only used when running behind TLS.
+ * @param {Pick<AuthPolicy,'secure'>} policy
+ * @returns {string}
+ */
+export function cookieName(policy) {
+  return policy.secure ? '__Host-dsh_auth' : 'dsh_auth'
+}

package/src/sessions.js

@@ -0,0 +1,130 @@
+// @ts-check
+/**
+ * In-memory session store: 256-bit crypto-random tokens, an absolute TTL plus a
+ * sliding idle window, login-time token rotation (anti-fixation), explicit
+ * revoke, and a sweep. The clock is injectable so expiry is testable without
+ * real time. Pure module — sessions live only in this process, so a restart
+ * requires every user to log in again (an accepted in-scope tradeoff).
+ */
+
+import { randomBytes } from 'node:crypto'
+
+/**
+ * @typedef {object} SessionRecord
+ * @property {string} username
+ * @property {number} createdAt
+ * @property {number} lastSeenAt
+ * @property {string} [ip]
+ */
+
+/**
+ * @param {object} opts
+ * @param {import('./policy.js').AuthPolicy} opts.policy
+ * @param {() => number} [opts.now] Injectable clock (defaults to Date.now).
+ */
+export function createSessionStore({ policy, now = Date.now } = /** @type {any} */ ({})) {
+  if (!policy) throw new Error('createSessionStore: policy required')
+  /** @type {Map<string, SessionRecord>} */
+  const store = new Map()
+
+  function newToken() {
+    let token
+    // 256 bits of entropy; the loop guards the astronomically unlikely clash.
+    do {
+      token = randomBytes(32).toString('base64url')
+    } while (store.has(token))
+    return token
+  }
+
+  /** @param {SessionRecord} rec @param {number} t */
+  function fresh(rec, t) {
+    return t - rec.createdAt < policy.sessionAbsoluteTtlMs && t - rec.lastSeenAt < policy.sessionIdleTtlMs
+  }
+
+  /**
+   * @param {string} username
+   * @param {{ip?: string}} [meta]
+   * @returns {string} the new session token.
+   */
+  function create(username, meta = {}) {
+    const t = now()
+    const token = newToken()
+    store.set(token, { username, createdAt: t, lastSeenAt: t, ip: meta.ip })
+    return token
+  }
+
+  /**
+   * Validate a token and, when valid, touch its idle timestamp (sliding window).
+   * Stale sessions are deleted eagerly. Returns a copy so callers cannot mutate
+   * the stored record.
+   * @param {string | undefined} token
+   * @returns {SessionRecord | undefined}
+   */
+  function validate(token) {
+    if (typeof token !== 'string' || token.length === 0) return undefined
+    const rec = store.get(token)
+    if (!rec) return undefined
+    const t = now()
+    if (!fresh(rec, t)) {
+      store.delete(token)
+      return undefined
+    }
+    rec.lastSeenAt = t
+    return { ...rec }
+  }
+
+  /**
+   * Login rotation: mint a fresh token and drop the presented one, so a token
+   * observed pre-login cannot be reused post-login (session fixation defense).
+   * @param {string | undefined} oldToken
+   * @param {string} username
+   * @param {{ip?: string}} [meta]
+   * @returns {string}
+   */
+  function rotate(oldToken, username, meta = {}) {
+    if (oldToken) store.delete(oldToken)
+    return create(username, meta)
+  }
+
+  /** @param {string} token @returns {boolean} */
+  function revoke(token) {
+    return store.delete(token)
+  }
+
+  /** Drop every session belonging to a user (e.g. after disable / password change). */
+  function revokeUser(username) {
+    let n = 0
+    for (const [tok, rec] of store) {
+      if (rec.username === username) {
+        store.delete(tok)
+        n++
+      }
+    }
+    return n
+  }
+
+  /** Remove all stale sessions; returns the count reaped. */
+  function sweep() {
+    const t = now()
+    let n = 0
+    for (const [tok, rec] of store) {
+      if (!fresh(rec, t)) {
+        store.delete(tok)
+        n++
+      }
+    }
+    return n
+  }
+
+  return {
+    create,
+    validate,
+    rotate,
+    revoke,
+    revokeUser,
+    sweep,
+    get size() {
+      return store.size
+    },
+  }
+}

package/src/users.js

@@ -0,0 +1,129 @@
+// @ts-check
+/**
+ * User credential store backed by a JSON file (default $DSH_HOME/auth/users.json).
+ * Writes are atomic (temp file + rename) and mode 0600. Pure of peer imports:
+ * the caller supplies the path, so tests point it at a temp file. The file is
+ * managed offline by the `dsh-auth` CLI, never through the Web settings UI.
+ */
+
+import { readFile, writeFile, rename, mkdir, chmod, unlink } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { randomBytes } from 'node:crypto'
+
+const FILE_VERSION = 1
+
+/**
+ * @typedef {object} UserRecord
+ * @property {string} username
+ * @property {boolean} [disabled]
+ * @property {import('./passwords.js').PasswordRecord} password
+ * @property {number} [createdAt]
+ * @property {number} [updatedAt]
+ */
+
+/**
+ * @param {{path: string}} opts Absolute path to the users JSON file.
+ */
+export function createUserStore({ path } = /** @type {any} */ ({})) {
+  if (!path) throw new Error('createUserStore: path required')
+
+  /** @returns {Promise<{version: number, users: Record<string, UserRecord>}>} */
+  async function load() {
+    let raw
+    try {
+      raw = await readFile(path, 'utf8')
+    } catch (err) {
+      if (err && /** @type {any} */ (err).code === 'ENOENT') return { version: FILE_VERSION, users: {} }
+      throw err
+    }
+    let data
+    try {
+      data = JSON.parse(raw)
+    } catch {
+      throw new Error(`auth: users file is not valid JSON: ${path}`)
+    }
+    if (!data || typeof data !== 'object' || typeof data.users !== 'object' || data.users === null) {
+      throw new Error(`auth: users file has an unexpected shape: ${path}`)
+    }
+    return { version: data.version ?? FILE_VERSION, users: data.users }
+  }
+
+  /** @param {{users: Record<string, UserRecord>}} db */
+  async function save(db) {
+    await mkdir(dirname(path), { recursive: true })
+    const tmp = join(dirname(path), `.users.${process.pid}.${randomBytes(6).toString('hex')}.tmp`)
+    const body = JSON.stringify({ version: FILE_VERSION, users: db.users }, null, 2)
+    await writeFile(tmp, body, { encoding: 'utf8', mode: 0o600 })
+    try {
+      await chmod(tmp, 0o600)
+    } catch {
+      /* best effort where full POSIX modes are unavailable (e.g. some Windows FS) */
+    }
+    try {
+      await rename(tmp, path)
+    } catch (err) {
+      try {
+        await unlink(tmp)
+      } catch {
+        /* ignore cleanup failure */
+      }
+      throw err
+    }
+    try {
+      await chmod(path, 0o600)
+    } catch {
+      /* best effort */
+    }
+  }
+
+  return {
+    load,
+    /** @param {string} username @returns {Promise<UserRecord | undefined>} */
+    async getUser(username) {
+      const db = await load()
+      return db.users[username]
+    },
+    /** @returns {Promise<UserRecord[]>} */
+    async listUsers() {
+      const db = await load()
+      return Object.values(db.users)
+    },
+    /**
+     * Create or update a user, merging over any existing record.
+     * @param {string} username
+     * @param {Partial<UserRecord>} record
+     * @returns {Promise<UserRecord>}
+     */
+    async upsertUser(username, record) {
+      const db = await load()
+      const now = Date.now()
+      const prev = db.users[username]
+      db.users[username] = {
+        ...prev,
+        ...record,
+        username,
+        createdAt: prev?.createdAt ?? now,
+        updatedAt: now,
+      }
+      await save(db)
+      return db.users[username]
+    },
+    /** @param {string} username @returns {Promise<boolean>} */
+    async removeUser(username) {
+      const db = await load()
+      if (!(username in db.users)) return false
+      delete db.users[username]
+      await save(db)
+      return true
+    },
+    /** @param {string} username @param {boolean} disabled @returns {Promise<boolean>} */
+    async setDisabled(username, disabled) {
+      const db = await load()
+      if (!(username in db.users)) return false
+      db.users[username].disabled = Boolean(disabled)
+      db.users[username].updatedAt = Date.now()
+      await save(db)
+      return true
+    },
+  }
+}