create-rebe 1.0.0

package/template/core/common/crypt.js

@@ -0,0 +1,69 @@
+'use strict'
+
+const crypto = require('crypto')
+
+const ALGORITHM = 'aes-256-gcm'
+const IV_LENGTH = 12
+const SALT_LENGTH = 16
+const KEY_LENGTH = 32
+
+// Derive a stable 32-byte key from the application secret.
+function deriveKey(salt) {
+	const config = require('@config/index')
+	const secret = config.app.key || config.jwt.secret
+	return crypto.scryptSync(String(secret), salt, KEY_LENGTH)
+}
+
+// Authenticated symmetric encryption (AES-256-GCM) for at-rest secrets.
+class Crypt {
+	// Encrypt a value. Objects are JSON-encoded. Returns a compact base64 token.
+	static encrypt(value) {
+		const plaintext = typeof value === 'string' ? value : JSON.stringify(value)
+		const salt = crypto.randomBytes(SALT_LENGTH)
+		const iv = crypto.randomBytes(IV_LENGTH)
+		const key = deriveKey(salt)
+
+		const cipher = crypto.createCipheriv(ALGORITHM, key, iv)
+		const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()])
+		const tag = cipher.getAuthTag()
+
+		// Layout: salt | iv | authTag | ciphertext
+		return Buffer.concat([salt, iv, tag, encrypted]).toString('base64')
+	}
+
+	// Decrypt a token produced by encrypt(). Pass asJson to revive objects.
+	static decrypt(token, asJson = false) {
+		const data = Buffer.from(String(token), 'base64')
+		const salt = data.subarray(0, SALT_LENGTH)
+		const iv = data.subarray(SALT_LENGTH, SALT_LENGTH + IV_LENGTH)
+		const tag = data.subarray(SALT_LENGTH + IV_LENGTH, SALT_LENGTH + IV_LENGTH + 16)
+		const ciphertext = data.subarray(SALT_LENGTH + IV_LENGTH + 16)
+		const key = deriveKey(salt)
+
+		const decipher = crypto.createDecipheriv(ALGORITHM, key, iv)
+		decipher.setAuthTag(tag)
+		const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8')
+
+		return asJson ? JSON.parse(decrypted) : decrypted
+	}
+
+	// Plain base64 encode/decode helpers (encoding only, not encryption).
+	static base64Encode(value) {
+		return Buffer.from(String(value), 'utf8').toString('base64')
+	}
+
+	static base64Decode(value) {
+		return Buffer.from(String(value), 'base64').toString('utf8')
+	}
+
+	// URL-safe base64 variants.
+	static base64UrlEncode(value) {
+		return Buffer.from(String(value), 'utf8').toString('base64url')
+	}
+
+	static base64UrlDecode(value) {
+		return Buffer.from(String(value), 'base64url').toString('utf8')
+	}
+}
+
+module.exports = Crypt

package/template/core/common/date.js

@@ -0,0 +1,254 @@
+'use strict'
+
+const MS = {
+	second: 1000,
+	minute: 60 * 1000,
+	hour: 60 * 60 * 1000,
+	day: 24 * 60 * 60 * 1000,
+	week: 7 * 24 * 60 * 60 * 1000,
+}
+
+const MONTHS = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']
+const DAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
+
+const pad = (n, len = 2) => String(Math.abs(n)).padStart(len, '0')
+
+// A lightweight, chainable date wrapper in the spirit of Carbon / dayjs.
+// Instances are immutable: arithmetic methods return a fresh DateTime.
+class DateTime {
+	constructor(input = null) {
+		if (input instanceof DateTime) {
+			this._date = new Date(input._date.getTime())
+		} else if (input instanceof Date) {
+			this._date = new Date(input.getTime())
+		} else if (input === null || input === undefined) {
+			this._date = new Date()
+		} else {
+			this._date = new Date(input)
+		}
+	}
+
+	// ── Factories ────────────────────────────────────────────────────────────
+	static now() {
+		return new DateTime()
+	}
+
+	static parse(input) {
+		return new DateTime(input)
+	}
+
+	static create(year, month = 1, day = 1, hour = 0, minute = 0, second = 0) {
+		return new DateTime(new Date(year, month - 1, day, hour, minute, second))
+	}
+
+	static fromTimestamp(seconds) {
+		return new DateTime(new Date(seconds * 1000))
+	}
+
+	// ── Accessors ────────────────────────────────────────────────────────────
+	year() {
+		return this._date.getFullYear()
+	}
+	month() {
+		return this._date.getMonth() + 1
+	}
+	day() {
+		return this._date.getDate()
+	}
+	hour() {
+		return this._date.getHours()
+	}
+	minute() {
+		return this._date.getMinutes()
+	}
+	second() {
+		return this._date.getSeconds()
+	}
+	dayOfWeek() {
+		return this._date.getDay()
+	}
+	timestamp() {
+		return Math.floor(this._date.getTime() / 1000)
+	}
+	valueOf() {
+		return this._date.getTime()
+	}
+	toDate() {
+		return new Date(this._date.getTime())
+	}
+	clone() {
+		return new DateTime(this._date)
+	}
+
+	// ── Arithmetic (immutable) ───────────────────────────────────────────────
+	_add(ms) {
+		return new DateTime(new Date(this._date.getTime() + ms))
+	}
+
+	addSeconds(n) {
+		return this._add(n * MS.second)
+	}
+	subSeconds(n) {
+		return this._add(-n * MS.second)
+	}
+	addMinutes(n) {
+		return this._add(n * MS.minute)
+	}
+	subMinutes(n) {
+		return this._add(-n * MS.minute)
+	}
+	addHours(n) {
+		return this._add(n * MS.hour)
+	}
+	subHours(n) {
+		return this._add(-n * MS.hour)
+	}
+	addDays(n) {
+		return this._add(n * MS.day)
+	}
+	subDays(n) {
+		return this._add(-n * MS.day)
+	}
+	addWeeks(n) {
+		return this._add(n * MS.week)
+	}
+	subWeeks(n) {
+		return this._add(-n * MS.week)
+	}
+
+	addMonths(n) {
+		const d = new Date(this._date.getTime())
+		d.setMonth(d.getMonth() + n)
+		return new DateTime(d)
+	}
+
+	subMonths(n) {
+		return this.addMonths(-n)
+	}
+
+	addYears(n) {
+		const d = new Date(this._date.getTime())
+		d.setFullYear(d.getFullYear() + n)
+		return new DateTime(d)
+	}
+
+	subYears(n) {
+		return this.addYears(-n)
+	}
+
+	// ── Boundaries ───────────────────────────────────────────────────────────
+	startOfDay() {
+		const d = new Date(this._date.getTime())
+		d.setHours(0, 0, 0, 0)
+		return new DateTime(d)
+	}
+
+	endOfDay() {
+		const d = new Date(this._date.getTime())
+		d.setHours(23, 59, 59, 999)
+		return new DateTime(d)
+	}
+
+	// ── Comparisons ──────────────────────────────────────────────────────────
+	isBefore(other) {
+		return this.valueOf() < new DateTime(other).valueOf()
+	}
+	isAfter(other) {
+		return this.valueOf() > new DateTime(other).valueOf()
+	}
+	isSame(other) {
+		return this.valueOf() === new DateTime(other).valueOf()
+	}
+	isPast() {
+		return this.valueOf() < Date.now()
+	}
+	isFuture() {
+		return this.valueOf() > Date.now()
+	}
+
+	// Difference from another date, in the requested unit (signed).
+	diff(other, unit = 'seconds') {
+		const ms = this.valueOf() - new DateTime(other).valueOf()
+		switch (unit) {
+			case 'seconds':
+				return Math.trunc(ms / MS.second)
+			case 'minutes':
+				return Math.trunc(ms / MS.minute)
+			case 'hours':
+				return Math.trunc(ms / MS.hour)
+			case 'days':
+				return Math.trunc(ms / MS.day)
+			case 'weeks':
+				return Math.trunc(ms / MS.week)
+			default:
+				return ms
+		}
+	}
+
+	// Human friendly relative phrasing: "3 hours ago", "in 2 days".
+	diffForHumans(other = null) {
+		const ref = other ? new DateTime(other).valueOf() : Date.now()
+		const ms = this.valueOf() - ref
+		const abs = Math.abs(ms)
+		const units = [
+			['year', MS.day * 365],
+			['month', MS.day * 30],
+			['day', MS.day],
+			['hour', MS.hour],
+			['minute', MS.minute],
+			['second', MS.second],
+		]
+		for (const [name, size] of units) {
+			const value = Math.floor(abs / size)
+			if (value >= 1) {
+				const label = `${value} ${name}${value > 1 ? 's' : ''}`
+				return ms < 0 ? `${label} ago` : `in ${label}`
+			}
+		}
+		return 'just now'
+	}
+
+	// ── Formatting ───────────────────────────────────────────────────────────
+	// Token format: YYYY MM DD HH mm ss, plus MMMM/MMM/dddd/ddd/A/a.
+	format(pattern = 'YYYY-MM-DD HH:mm:ss') {
+		const d = this._date
+		const h12 = d.getHours() % 12 || 12
+		const map = {
+			YYYY: d.getFullYear(),
+			YY: pad(d.getFullYear() % 100),
+			MMMM: MONTHS[d.getMonth()],
+			MMM: MONTHS[d.getMonth()].slice(0, 3),
+			MM: pad(d.getMonth() + 1),
+			M: d.getMonth() + 1,
+			DD: pad(d.getDate()),
+			D: d.getDate(),
+			dddd: DAYS[d.getDay()],
+			ddd: DAYS[d.getDay()].slice(0, 3),
+			HH: pad(d.getHours()),
+			H: d.getHours(),
+			hh: pad(h12),
+			h: h12,
+			mm: pad(d.getMinutes()),
+			m: d.getMinutes(),
+			ss: pad(d.getSeconds()),
+			s: d.getSeconds(),
+			A: d.getHours() < 12 ? 'AM' : 'PM',
+			a: d.getHours() < 12 ? 'am' : 'pm',
+		}
+		return pattern.replace(/YYYY|YY|MMMM|MMM|MM|M|DD|D|dddd|ddd|HH|H|hh|h|mm|m|ss|s|A|a/g, (token) => map[token])
+	}
+
+	toISOString() {
+		return this._date.toISOString()
+	}
+
+	toString() {
+		return this.format('YYYY-MM-DD HH:mm:ss')
+	}
+
+	toJSON() {
+		return this._date.toISOString()
+	}
+}
+
+module.exports = DateTime

package/template/core/common/hash.js

@@ -0,0 +1,61 @@
+'use strict'
+
+const crypto = require('crypto')
+const bcrypt = require('bcrypt')
+
+// Hashing utilities: password hashing via bcrypt plus raw digest helpers.
+class Hash {
+	// Hash a plaintext value with bcrypt. Salt rounds come from config.
+	static async make(value, rounds = null) {
+		const config = require('@config/index')
+		const saltRounds = rounds ?? config.bcrypt.saltRounds
+		return bcrypt.hash(String(value), saltRounds)
+	}
+
+	// Verify a plaintext value against a bcrypt hash.
+	static async check(value, hashed) {
+		if (!hashed) return false
+		return bcrypt.compare(String(value), hashed)
+	}
+
+	// Detect whether a stored hash should be re-hashed at higher cost.
+	static needsRehash(hashed, rounds = null) {
+		const config = require('@config/index')
+		const target = rounds ?? config.bcrypt.saltRounds
+		const match = /^\$2[aby]\$(\d{2})\$/.exec(hashed || '')
+		if (!match) return true
+		return parseInt(match[1], 10) < target
+	}
+
+	// Generic digest (md5, sha1, sha256, sha512, ...).
+	static digest(value, algorithm = 'sha256', encoding = 'hex') {
+		return crypto.createHash(algorithm).update(String(value)).digest(encoding)
+	}
+
+	static md5(value) {
+		return Hash.digest(value, 'md5')
+	}
+
+	static sha256(value) {
+		return Hash.digest(value, 'sha256')
+	}
+
+	static sha512(value) {
+		return Hash.digest(value, 'sha512')
+	}
+
+	// Keyed HMAC digest.
+	static hmac(value, secret, algorithm = 'sha256') {
+		return crypto.createHmac(algorithm, secret).update(String(value)).digest('hex')
+	}
+
+	// Constant-time comparison to avoid timing attacks.
+	static equals(a, b) {
+		const bufA = Buffer.from(String(a))
+		const bufB = Buffer.from(String(b))
+		if (bufA.length !== bufB.length) return false
+		return crypto.timingSafeEqual(bufA, bufB)
+	}
+}
+
+module.exports = Hash

package/template/core/common/object.js

@@ -0,0 +1,155 @@
+'use strict'
+
+// Object helpers with dot-notation access and immutable-friendly merges.
+class Obj {
+	// Read a nested value by dot path: get(obj, 'a.b.c', fallback).
+	static get(obj, path, fallback = null) {
+		if (!obj || !path) return fallback
+		const keys = Array.isArray(path) ? path : String(path).split('.')
+		let current = obj
+		for (const key of keys) {
+			if (current === null || current === undefined || !(key in current)) {
+				return fallback
+			}
+			current = current[key]
+		}
+		return current === undefined ? fallback : current
+	}
+
+	// Write a nested value by dot path, creating intermediate objects.
+	static set(obj, path, value) {
+		const keys = Array.isArray(path) ? path : String(path).split('.')
+		let current = obj
+		for (let i = 0; i < keys.length - 1; i++) {
+			const key = keys[i]
+			if (typeof current[key] !== 'object' || current[key] === null) {
+				current[key] = {}
+			}
+			current = current[key]
+		}
+		current[keys[keys.length - 1]] = value
+		return obj
+	}
+
+	// True when the dot path exists.
+	static has(obj, path) {
+		const keys = Array.isArray(path) ? path : String(path).split('.')
+		let current = obj
+		for (const key of keys) {
+			if (current === null || current === undefined || !(key in current)) {
+				return false
+			}
+			current = current[key]
+		}
+		return true
+	}
+
+	// Delete a nested key by dot path.
+	static forget(obj, path) {
+		const keys = Array.isArray(path) ? path : String(path).split('.')
+		let current = obj
+		for (let i = 0; i < keys.length - 1; i++) {
+			if (typeof current[keys[i]] !== 'object' || current[keys[i]] === null) return obj
+			current = current[keys[i]]
+		}
+		delete current[keys[keys.length - 1]]
+		return obj
+	}
+
+	// New object containing only the listed keys.
+	static pick(obj, keys) {
+		const out = {}
+		for (const key of Arr(keys)) {
+			if (obj && key in obj) out[key] = obj[key]
+		}
+		return out
+	}
+
+	// New object without the listed keys.
+	static omit(obj, keys) {
+		const exclude = new Set(Arr(keys))
+		const out = {}
+		for (const key of Object.keys(obj || {})) {
+			if (!exclude.has(key)) out[key] = obj[key]
+		}
+		return out
+	}
+
+	// Recursive deep merge; later sources win.
+	static merge(target, ...sources) {
+		for (const source of sources) {
+			if (!source) continue
+			for (const key of Object.keys(source)) {
+				const sv = source[key]
+				const tv = target[key]
+				if (Obj.isPlain(sv) && Obj.isPlain(tv)) {
+					target[key] = Obj.merge({ ...tv }, sv)
+				} else {
+					target[key] = sv
+				}
+			}
+		}
+		return target
+	}
+
+	// Structured deep clone, with a JSON fallback for older runtimes.
+	static clone(obj) {
+		if (typeof structuredClone === 'function') {
+			try {
+				return structuredClone(obj)
+			} catch {
+				/* fall through to JSON clone */
+			}
+		}
+		return JSON.parse(JSON.stringify(obj))
+	}
+
+	static isPlain(value) {
+		if (typeof value !== 'object' || value === null) return false
+		const proto = Object.getPrototypeOf(value)
+		return proto === Object.prototype || proto === null
+	}
+
+	static isEmpty(value) {
+		if (value === null || value === undefined) return true
+		if (Array.isArray(value)) return value.length === 0
+		if (typeof value === 'object') return Object.keys(value).length === 0
+		return false
+	}
+
+	// Build an object from [key, value] entries.
+	static fromEntries(entries) {
+		return Object.fromEntries(entries)
+	}
+
+	// Map over values while keeping keys.
+	static mapValues(obj, fn) {
+		const out = {}
+		for (const [key, val] of Object.entries(obj || {})) {
+			out[key] = fn(val, key)
+		}
+		return out
+	}
+
+	// Flatten nested objects into dot-path keys.
+	static flatten(obj, prefix = '') {
+		const out = {}
+		for (const [key, val] of Object.entries(obj || {})) {
+			const path = prefix ? `${prefix}.${key}` : key
+			if (Obj.isPlain(val)) {
+				Object.assign(out, Obj.flatten(val, path))
+			} else {
+				out[path] = val
+			}
+		}
+		return out
+	}
+}
+
+// Local helper so pick/omit accept either a single key or an array.
+function Arr(value) {
+	if (value === null || value === undefined) return []
+	return Array.isArray(value) ? value : [value]
+}
+
+module.exports = Obj

package/template/core/common/path.js

@@ -0,0 +1,80 @@
+'use strict'
+
+const nodePath = require('path')
+const fs = require('fs')
+
+const ROOT = process.cwd()
+
+// Path helpers anchored at the project root, plus a few filesystem niceties.
+class Path {
+	// Absolute path from the project root.
+	static base(...segments) {
+		return nodePath.resolve(ROOT, ...segments)
+	}
+
+	static src(...segments) {
+		return Path.base('src', ...segments)
+	}
+
+	static core(...segments) {
+		return Path.base('core', ...segments)
+	}
+
+	static storage(...segments) {
+		return Path.base('storage', ...segments)
+	}
+
+	static public(...segments) {
+		return Path.base('public', ...segments)
+	}
+
+	static join(...segments) {
+		return nodePath.join(...segments)
+	}
+
+	static resolve(...segments) {
+		return nodePath.resolve(...segments)
+	}
+
+	static dirname(p) {
+		return nodePath.dirname(p)
+	}
+
+	static basename(p, ext) {
+		return nodePath.basename(p, ext)
+	}
+
+	// File extension without the leading dot.
+	static extension(p) {
+		return nodePath.extname(p).replace('.', '')
+	}
+
+	static filename(p) {
+		return nodePath.basename(p, nodePath.extname(p))
+	}
+
+	// Relative path from the project root, in posix form.
+	static relative(p) {
+		return nodePath.relative(ROOT, p).split(nodePath.sep).join('/')
+	}
+
+	static exists(p) {
+		return fs.existsSync(p)
+	}
+
+	static isFile(p) {
+		return fs.existsSync(p) && fs.statSync(p).isFile()
+	}
+
+	static isDir(p) {
+		return fs.existsSync(p) && fs.statSync(p).isDirectory()
+	}
+
+	// Create a directory (and parents) if it does not yet exist.
+	static ensureDir(p) {
+		if (!fs.existsSync(p)) fs.mkdirSync(p, { recursive: true })
+		return p
+	}
+}
+
+module.exports = Path

package/template/core/common/storage.js

@@ -0,0 +1,97 @@
+'use strict'
+
+const fs = require('fs')
+const fsp = require('fs/promises')
+const nodePath = require('path')
+
+// Resolve a path inside the configured storage root, guarding against escapes.
+function resolvePath(relative) {
+	const config = require('@config/index')
+	const root = nodePath.resolve(process.cwd(), config.storage.root)
+	const full = nodePath.resolve(root, relative || '')
+	if (full !== root && !full.startsWith(root + nodePath.sep)) {
+		throw new Error(`Storage path escapes the storage root: ${relative}`)
+	}
+	return { root, full }
+}
+
+// Filesystem storage abstraction rooted at config.storage.root. All paths are
+// relative to that root, so application code never deals in absolute paths.
+class Storage {
+	// Absolute path for a relative storage key.
+	static path(relative = '') {
+		return resolvePath(relative).full
+	}
+
+	static exists(relative) {
+		return fs.existsSync(resolvePath(relative).full)
+	}
+
+	// Write contents, creating parent directories as needed.
+	static async put(relative, contents) {
+		const { full } = resolvePath(relative)
+		await fsp.mkdir(nodePath.dirname(full), { recursive: true })
+		await fsp.writeFile(full, contents)
+		return relative
+	}
+
+	static async get(relative, encoding = 'utf8') {
+		return fsp.readFile(resolvePath(relative).full, encoding)
+	}
+
+	static async getBuffer(relative) {
+		return fsp.readFile(resolvePath(relative).full)
+	}
+
+	static async append(relative, contents) {
+		const { full } = resolvePath(relative)
+		await fsp.mkdir(nodePath.dirname(full), { recursive: true })
+		await fsp.appendFile(full, contents)
+		return relative
+	}
+
+	static async delete(relative) {
+		const { full } = resolvePath(relative)
+		if (!fs.existsSync(full)) return false
+		await fsp.rm(full, { recursive: true, force: true })
+		return true
+	}
+
+	static async copy(from, to) {
+		const src = resolvePath(from).full
+		const dest = resolvePath(to).full
+		await fsp.mkdir(nodePath.dirname(dest), { recursive: true })
+		await fsp.copyFile(src, dest)
+		return to
+	}
+
+	static async move(from, to) {
+		const src = resolvePath(from).full
+		const dest = resolvePath(to).full
+		await fsp.mkdir(nodePath.dirname(dest), { recursive: true })
+		await fsp.rename(src, dest)
+		return to
+	}
+
+	static async makeDir(relative) {
+		await fsp.mkdir(resolvePath(relative).full, { recursive: true })
+		return relative
+	}
+
+	// List entries in a directory (names only).
+	static async list(relative = '') {
+		const { full } = resolvePath(relative)
+		if (!fs.existsSync(full)) return []
+		return fsp.readdir(full)
+	}
+
+	// File size in bytes, or null when missing.
+	static async size(relative) {
+		const { full } = resolvePath(relative)
+		if (!fs.existsSync(full)) return null
+		const stat = await fsp.stat(full)
+		return stat.size
+	}
+}
+
+module.exports = Storage