@objy/server 0.0.0-stage → 0.1.0

package/src/interfaces/ui.js

@@ -0,0 +1,38 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { text } from "../http-router.js";
+
+const UI_HTML = readFileSync(
+  join(dirname(fileURLToPath(import.meta.url)), "..", "..", "public", "index.html"),
+  "utf8",
+);
+const API_DOCS = readFileSync(
+  join(dirname(fileURLToPath(import.meta.url)), "..", "..", "API.md"),
+  "utf8",
+);
+const LOGO_PNG = readFileSync(
+  join(dirname(fileURLToPath(import.meta.url)), "..", "..", "public", "objy-db-logo.png"),
+);
+export function createUiInterface() {
+  return {
+    name: "ui",
+    register(router) {
+      const send = (req, res) => text(res, 200, UI_HTML, "text/html; charset=utf-8");
+      const sendApiDocs = (req, res) => text(res, 200, API_DOCS, "text/markdown; charset=utf-8");
+      const sendPng = (body) => (req, res) => {
+        res.writeHead(200, {
+          "content-type": "image/png",
+          "content-length": body.byteLength,
+          "cache-control": "public, max-age=86400",
+        });
+        res.end(body);
+      };
+      router.get("/", send);
+      router.get("/ui", send);
+      router.get("/index.html", send);
+      router.get("/objy-db-logo.png", sendPng(LOGO_PNG));
+      router.get("/API.md", sendApiDocs);
+    },
+  };
+}

package/src/lib/crypto.cjs

@@ -0,0 +1,54 @@
+const {
+  createHmac,
+  pbkdf2Sync,
+  randomBytes,
+  randomUUID,
+  timingSafeEqual,
+} = require('node:crypto')
+
+const DEFAULT_ITERATIONS = 10000
+const KEY_LENGTH = 32
+
+function hashPassword(password, options = {}) {
+  if (typeof password !== 'string') throw new TypeError('Password must be a string')
+
+  const iterations = options.iterations || DEFAULT_ITERATIONS
+  const salt = options.salt || randomBytes(16).toString('hex')
+  const hash = derivePassword(password, salt, iterations).toString('hex')
+  return `pbkdf2$sha256$${iterations}$${salt}$${hash}`
+}
+
+function verifyPassword(password, storedHash) {
+  if (typeof password !== 'string' || typeof storedHash !== 'string') return false
+
+  const parts = storedHash.split('$')
+  if (parts.length !== 5) return false
+  const [algorithm, digest, iterationsText, salt, expectedText] = parts
+  if (algorithm !== 'pbkdf2' || digest !== 'sha256') return false
+  if (!/^[0-9]+$/.test(iterationsText)) return false
+  if (!isEvenHex(salt) || !isEvenHex(expectedText)) return false
+
+  const iterations = Number(iterationsText)
+  if (!Number.isSafeInteger(iterations) || iterations < 1) return false
+
+  const expected = Buffer.from(expectedText, 'hex')
+  const actual = derivePassword(password, salt, iterations)
+  return actual.length === expected.length && timingSafeEqual(actual, expected)
+}
+
+function hmacSha256(key, data) {
+  return createHmac('sha256', key).update(data).digest()
+}
+
+function derivePassword(password, salt, iterations) {
+  return pbkdf2Sync(password, Buffer.from(salt, 'hex'), iterations, KEY_LENGTH, 'sha256')
+}
+
+function isEvenHex(value) {
+  return typeof value === 'string'
+    && value.length > 0
+    && value.length % 2 === 0
+    && /^[a-f0-9]+$/i.test(value)
+}
+
+module.exports = { hashPassword, hmacSha256, randomUUID, verifyPassword }

package/src/lib/jwt.cjs

@@ -0,0 +1,231 @@
+const { hmacSha256, randomUUID } = require('./crypto.cjs')
+
+function signAccessToken(user, secret, { expiresInSeconds = 3600, sessionId = null, extraClaims = {} } = {}) {
+  const data = user && user._data ? user._data : user
+  if (!data || typeof data !== 'object') throw new TypeError('JWT user payload must be an object')
+
+  const now = Math.floor(Date.now() / 1000)
+  const id = sessionId || data.sessionId || randomUUID()
+  return sign({
+    typ: 'access',
+    sub: data._id,
+    userFamily: data.role,
+    username: data.username,
+    applications: data.applications || [],
+    authorisations: data.authorisations || {},
+    sessionId: id,
+    tokenVersion: data.tokenVersion || 0,
+    ..._safeExtraClaims(extraClaims),
+    iat: now,
+    exp: now + expiresInSeconds
+  }, secret)
+}
+
+function signRefreshToken(user, secret, { expiresInSeconds = 1209600, sessionId = null, extraClaims = {} } = {}) {
+  const data = user && user._data ? user._data : user
+  if (!data || typeof data !== 'object') throw new TypeError('JWT user payload must be an object')
+
+  const now = Math.floor(Date.now() / 1000)
+  const id = sessionId || data.sessionId || randomUUID()
+  return sign({
+    typ: 'refresh',
+    sub: data._id,
+    userFamily: data.role,
+    username: data.username,
+    sessionId: id,
+    tokenVersion: data.tokenVersion || 0,
+    ..._safeExtraClaims(extraClaims),
+    iat: now,
+    exp: now + expiresInSeconds
+  }, secret)
+}
+
+function sign(payload, secret) {
+  _assertSecret(secret)
+  const header = { alg: 'HS256', typ: 'JWT' }
+  const unsigned = `${_encodeJson(header)}.${_encodeJson(payload)}`
+  return `${unsigned}.${_base64UrlEncodeBytes(hmacSha256(secret, unsigned))}`
+}
+
+function verifyAccessToken(token, secret, options = {}) {
+  const payload = verify(token, secret, options)
+  if (payload.typ !== 'access') {
+    const err = new Error('JWT is not an access token')
+    err.code = 'E_INVALID_TOKEN'
+    throw err
+  }
+  return payload
+}
+
+function verifyRefreshToken(token, secret, options = {}) {
+  const payload = verify(token, secret, options)
+  if (payload.typ !== 'refresh') {
+    const err = new Error('JWT is not a refresh token')
+    err.code = 'E_INVALID_TOKEN'
+    throw err
+  }
+  return payload
+}
+
+function verify(token, secret, { clockToleranceSeconds = 0 } = {}) {
+  _assertSecret(secret)
+  if (typeof token !== 'string') {
+    const err = new Error('JWT must be a string')
+    err.code = 'E_INVALID_TOKEN'
+    throw err
+  }
+
+  const parts = token.split('.')
+  if (parts.length !== 3) {
+    const err = new Error('JWT must have three parts')
+    err.code = 'E_INVALID_TOKEN'
+    throw err
+  }
+
+  const [headerPart, payloadPart, signaturePart] = parts
+  const header = _decodeJson(headerPart)
+  if (header.alg !== 'HS256' || header.typ !== 'JWT') {
+    const err = new Error('Unsupported JWT header')
+    err.code = 'E_INVALID_TOKEN'
+    throw err
+  }
+
+  const unsigned = `${headerPart}.${payloadPart}`
+  const expected = _base64UrlEncodeBytes(hmacSha256(secret, unsigned))
+  if (!_constantTimeStringEqual(signaturePart, expected)) {
+    const err = new Error('Invalid JWT signature')
+    err.code = 'E_INVALID_TOKEN'
+    throw err
+  }
+
+  const payload = _decodeJson(payloadPart)
+  const now = Math.floor(Date.now() / 1000)
+  if (typeof payload.exp !== 'number' || payload.exp + clockToleranceSeconds < now) {
+    const err = new Error('JWT expired')
+    err.code = 'E_TOKEN_EXPIRED'
+    throw err
+  }
+  if (payload.iat !== undefined && typeof payload.iat !== 'number') {
+    const err = new Error('Invalid JWT iat')
+    err.code = 'E_INVALID_TOKEN'
+    throw err
+  }
+
+  return payload
+}
+
+function _assertSecret(secret) {
+  if (typeof secret !== 'string' || secret.length === 0) {
+    throw new TypeError('JWT secret must be a non-empty string')
+  }
+}
+
+function _safeExtraClaims(extraClaims) {
+  if (!extraClaims || typeof extraClaims !== 'object' || Array.isArray(extraClaims)) return {}
+  const reserved = new Set([
+    'typ', 'sub', 'userFamily', 'username', 'applications', 'authorisations',
+    'sessionId', 'tokenVersion', 'iat', 'exp'
+  ])
+  return Object.fromEntries(
+    Object.entries(extraClaims).filter(([key]) => !reserved.has(key))
+  )
+}
+
+function _encodeJson(value) {
+  return _base64UrlEncodeBytes(_utf8(JSON.stringify(value)))
+}
+
+function _decodeJson(value) {
+  try {
+    return JSON.parse(_utf8Decode(_base64UrlDecodeBytes(value)))
+  } catch {
+    const err = new Error('Invalid JWT JSON')
+    err.code = 'E_INVALID_TOKEN'
+    throw err
+  }
+}
+
+function _base64UrlEncodeBytes(bytes) {
+  const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_'
+  let out = ''
+  for (let i = 0; i < bytes.length; i += 3) {
+    const a = bytes[i]
+    const b = bytes[i + 1] || 0
+    const c = bytes[i + 2] || 0
+    const triplet = (a << 16) | (b << 8) | c
+    out += alphabet[(triplet >>> 18) & 0x3f]
+    out += alphabet[(triplet >>> 12) & 0x3f]
+    if (i + 1 < bytes.length) out += alphabet[(triplet >>> 6) & 0x3f]
+    if (i + 2 < bytes.length) out += alphabet[triplet & 0x3f]
+  }
+  return out
+}
+
+function _base64UrlDecodeBytes(value) {
+  if (typeof value !== 'string') throw new TypeError('base64url value must be a string')
+  const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_'
+  const bytes = []
+  let buffer = 0
+  let bits = 0
+
+  for (const char of value) {
+    const idx = alphabet.indexOf(char)
+    if (idx < 0) throw new Error('Invalid base64url character')
+    buffer = (buffer << 6) | idx
+    bits += 6
+    if (bits >= 8) {
+      bits -= 8
+      bytes.push((buffer >>> bits) & 0xff)
+    }
+  }
+
+  return new Uint8Array(bytes)
+}
+
+function _constantTimeStringEqual(a, b) {
+  let diff = a.length ^ b.length
+  const length = Math.max(a.length, b.length)
+  for (let i = 0; i < length; i++) {
+    diff |= (a.charCodeAt(i % a.length) || 0) ^ (b.charCodeAt(i % b.length) || 0)
+  }
+  return diff === 0
+}
+
+function _utf8(value) {
+  if (typeof TextEncoder !== 'undefined') return new TextEncoder().encode(value)
+
+  const out = []
+  for (let i = 0; i < value.length; i++) {
+    let code = value.charCodeAt(i)
+    if (code < 0x80) out.push(code)
+    else if (code < 0x800) out.push(0xc0 | (code >> 6), 0x80 | (code & 0x3f))
+    else if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(++i)
+      code = 0x10000 + (((code & 0x3ff) << 10) | (next & 0x3ff))
+      out.push(0xf0 | (code >> 18), 0x80 | ((code >> 12) & 0x3f), 0x80 | ((code >> 6) & 0x3f), 0x80 | (code & 0x3f))
+    } else {
+      out.push(0xe0 | (code >> 12), 0x80 | ((code >> 6) & 0x3f), 0x80 | (code & 0x3f))
+    }
+  }
+  return new Uint8Array(out)
+}
+
+function _utf8Decode(bytes) {
+  if (typeof TextDecoder !== 'undefined') return new TextDecoder().decode(bytes)
+
+  let out = ''
+  for (let i = 0; i < bytes.length; i++) {
+    const byte = bytes[i]
+    if (byte < 0x80) out += String.fromCharCode(byte)
+    else if (byte < 0xe0) out += String.fromCharCode(((byte & 0x1f) << 6) | (bytes[++i] & 0x3f))
+    else if (byte < 0xf0) out += String.fromCharCode(((byte & 0x0f) << 12) | ((bytes[++i] & 0x3f) << 6) | (bytes[++i] & 0x3f))
+    else {
+      const code = ((byte & 0x07) << 18) | ((bytes[++i] & 0x3f) << 12) | ((bytes[++i] & 0x3f) << 6) | (bytes[++i] & 0x3f)
+      const pair = code - 0x10000
+      out += String.fromCharCode(0xd800 + (pair >> 10), 0xdc00 + (pair & 0x3ff))
+    }
+  }
+  return out
+}
+
+module.exports = { signAccessToken, signRefreshToken, sign, verifyAccessToken, verifyRefreshToken, verify }

package/src/local-wal.js

@@ -0,0 +1,122 @@
+import { createReadStream } from "node:fs";
+import { mkdir, open, stat } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { DEFAULT_LOCAL_WAL_DIR } from "./config.js";
+
+export class LocalWalStore {
+  constructor({ dir = DEFAULT_LOCAL_WAL_DIR, nodeId, fsync = true, flushMs = 0, maxRecordBytes = 4 * 1024 * 1024, maxOpsPerRecord = 1000 } = {}) {
+    if (!nodeId) throw new Error("local WAL node id is required");
+    this.dir = resolve(dir);
+    this.nodeId = String(nodeId);
+    this.fsync = fsync !== false;
+    this.flushMs = Math.max(0, Number(flushMs) || 0);
+    this.maxRecordBytes = Math.max(1024, Number(maxRecordBytes) || 4 * 1024 * 1024);
+    this.maxOpsPerRecord = Math.max(1, Number(maxOpsPerRecord) || 1000);
+    this.filePath = `${this.dir}/${safePathPart(this.nodeId)}/wal.jsonl`;
+  }
+
+  async append(records = []) {
+    if (!records.length) return { records: 0, bytes: 0 };
+    await mkdir(dirname(this.filePath), { recursive: true });
+    const handle = await open(this.filePath, "a");
+    let bytes = 0;
+    try {
+      for (const record of records) {
+        const line = `${JSON.stringify(record)}\n`;
+        bytes += Buffer.byteLength(line);
+        await handle.write(line, undefined, "utf8");
+      }
+      if (this.fsync) await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    return { records: records.length, bytes };
+  }
+
+  async readRecords() {
+    if (!await exists(this.filePath)) {
+      return { records: [], skippedPartialRecords: 0 };
+    }
+
+    const complete = await endsWithNewline(this.filePath);
+    const records = [];
+    let skippedPartialRecords = 0;
+    let previousLine = null;
+    let previousLineNo = 0;
+    let lineNo = 0;
+    const lines = createInterface({
+      input: createReadStream(this.filePath, { encoding: "utf8" }),
+      crlfDelay: Infinity,
+    });
+
+    for await (const line of lines) {
+      if (previousLine !== null) pushRecord(records, parseLine(previousLine, previousLineNo, false));
+      previousLine = line;
+      previousLineNo = ++lineNo;
+    }
+
+    if (previousLine !== null) {
+      try {
+        pushRecord(records, parseLine(previousLine, previousLineNo, !complete));
+      } catch (err) {
+        if (!complete) skippedPartialRecords++;
+        else throw err;
+      }
+    }
+
+    return { records, skippedPartialRecords };
+  }
+
+  async truncate() {
+    await mkdir(dirname(this.filePath), { recursive: true });
+    const handle = await open(this.filePath, "w");
+    try {
+      if (this.fsync) await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    return { records: 0 };
+  }
+}
+
+function parseLine(line, lineNo, allowPartial) {
+  if (!line.trim()) return null;
+  try {
+    return JSON.parse(line);
+  } catch (err) {
+    if (allowPartial) throw err;
+    throw new Error(`failed to parse local WAL record at line ${lineNo}: ${err.message}`);
+  }
+}
+
+function pushRecord(records, record) {
+  if (record) records.push(record);
+}
+
+async function exists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch (err) {
+    if (err.code === "ENOENT") return false;
+    throw err;
+  }
+}
+
+async function endsWithNewline(path) {
+  const info = await stat(path);
+  if (info.size === 0) return true;
+  const handle = await open(path, "r");
+  try {
+    const buffer = Buffer.alloc(1);
+    await handle.read(buffer, 0, 1, info.size - 1);
+    return buffer[0] === 10;
+  } finally {
+    await handle.close();
+  }
+}
+
+function safePathPart(value) {
+  return encodeURIComponent(String(value));
+}

package/src/memory-guard.js

@@ -0,0 +1,152 @@
+import { existsSync, readFileSync } from "node:fs";
+import { totalmem } from "node:os";
+
+const DEFAULT_REJECT_PERCENT = 85;
+const DEFAULT_RESUME_PERCENT = 78;
+const DEFAULT_CHECK_MS = 1000;
+const RETRY_AFTER_SECONDS = 5;
+
+export class MemoryGuard {
+  constructor(config = {}, deps = {}) {
+    this.enabled = config.enabled === true;
+    this.rejectWritesPercent = percent(
+      config.rejectWritesPercent ?? config.maxRssPercent,
+      DEFAULT_REJECT_PERCENT,
+    );
+    this.resumeWritesPercent = percent(config.resumeWritesPercent, Math.min(DEFAULT_RESUME_PERCENT, this.rejectWritesPercent));
+    if (this.resumeWritesPercent > this.rejectWritesPercent) {
+      throw new Error("memoryGuard.resumeWritesPercent must be <= memoryGuard.rejectWritesPercent");
+    }
+    this.checkMs = positiveInt(config.checkMs, DEFAULT_CHECK_MS);
+    this.getUsage = deps.getUsage || (() => process.memoryUsage());
+    this.now = deps.now || (() => Date.now());
+    const detected = deps.limitBytes
+      ? { bytes: deps.limitBytes, source: "injected" }
+      : memoryLimit(config);
+    this.limitBytes = detected.bytes;
+    this.limitSource = detected.source;
+    this.acceptingWrites = true;
+    this.lastSample = null;
+    this.lastSampleAt = 0;
+  }
+
+  status({ force = false } = {}) {
+    if (!this.enabled) {
+      const sample = this._sample(force);
+      return {
+        enabled: false,
+        acceptingWrites: true,
+        writeState: "accepting",
+        ...sample,
+      };
+    }
+
+    const sample = this._sample(force);
+    if (this.acceptingWrites && sample.rssPercent >= this.rejectWritesPercent) {
+      this.acceptingWrites = false;
+    } else if (!this.acceptingWrites && sample.rssPercent <= this.resumeWritesPercent) {
+      this.acceptingWrites = true;
+    }
+
+    return {
+      enabled: true,
+      acceptingWrites: this.acceptingWrites,
+      writeState: this.acceptingWrites ? "accepting" : "rejecting",
+      rejectWritesPercent: this.rejectWritesPercent,
+      resumeWritesPercent: this.resumeWritesPercent,
+      checkMs: this.checkMs,
+      ...sample,
+    };
+  }
+
+  writeRejection() {
+    const status = this.status({ force: true });
+    if (status.acceptingWrites) return null;
+    return {
+      status: 507,
+      headers: { "retry-after": String(RETRY_AFTER_SECONDS) },
+      body: {
+        error: "peer memory limit exceeded",
+        rssMb: status.rssMb,
+        limitMb: status.limitMb,
+        rssPercent: status.rssPercent,
+        writeState: status.writeState,
+      },
+    };
+  }
+
+  assertCanWrite() {
+    const rejection = this.writeRejection();
+    if (!rejection) return true;
+    const err = new Error(rejection.body.error);
+    err.status = rejection.status;
+    err.body = rejection.body;
+    err.headers = rejection.headers;
+    throw err;
+  }
+
+  _sample(force = false) {
+    const at = this.now();
+    if (!force && this.lastSample && at - this.lastSampleAt < this.checkMs) return this.lastSample;
+    const usage = this.getUsage();
+    const rss = Number(usage.rss) || 0;
+    const limit = this.limitBytes || 1;
+    this.lastSample = {
+      rss,
+      rssMb: mib(rss),
+      limitBytes: limit,
+      limitMb: mib(limit),
+      limitSource: this.limitSource,
+      rssPercent: Math.round((rss / limit) * 10_000) / 100,
+    };
+    this.lastSampleAt = at;
+    return this.lastSample;
+  }
+}
+
+export function createMemoryGuard(config = {}, deps = {}) {
+  if (config instanceof MemoryGuard) return config;
+  return new MemoryGuard(config || {}, deps);
+}
+
+function memoryLimit(config = {}) {
+  if (Number.isFinite(config.limitBytes) && config.limitBytes > 0) {
+    return { bytes: Math.floor(config.limitBytes), source: "config" };
+  }
+  if (Number.isFinite(config.limitMb) && config.limitMb > 0) {
+    return { bytes: Math.floor(config.limitMb * 1024 * 1024), source: "config" };
+  }
+  return detectedMemoryLimit();
+}
+
+function detectedMemoryLimit() {
+  const host = totalmem();
+  const cgroup = cgroupMemoryLimit();
+  if (cgroup && cgroup < host) return { bytes: cgroup, source: "cgroup" };
+  return { bytes: host, source: "os" };
+}
+
+function cgroupMemoryLimit() {
+  for (const file of ["/sys/fs/cgroup/memory.max", "/sys/fs/cgroup/memory/memory.limit_in_bytes"]) {
+    if (!existsSync(file)) continue;
+    const raw = readFileSync(file, "utf8").trim();
+    if (!raw || raw === "max") continue;
+    const value = Number(raw);
+    if (Number.isFinite(value) && value > 0 && value < Number.MAX_SAFE_INTEGER) return Math.floor(value);
+  }
+  return null;
+}
+
+function percent(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 0 && n <= 100 ? n : fallback;
+}
+
+function positiveInt(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
+}
+
+function mib(bytes) {
+  return Math.round((bytes / 1024 / 1024) * 10) / 10;
+}