hfs 0.26.7 → 0.26.8

package/src/listen.ts

@@ -0,0 +1,220 @@
+// This file is part of HFS - Copyright 2021-2022, Massimo Melina <a@rejetto.com> - License https://www.gnu.org/licenses/gpl-3.0.txt
+
+import * as http from 'http'
+import { defineConfig } from './config'
+import { app } from './index'
+import * as https from 'https'
+import { watchLoad } from './watchLoad'
+import { networkInterfaces } from 'os';
+import { newConnection } from './connections'
+import open from 'open'
+import { debounceAsync, onlyTruthy, wait } from './misc'
+import { ADMIN_URI, DEV } from './const'
+import findProcess from 'find-process'
+import { anyAccountCanLoginAdmin } from './perm'
+import _ from 'lodash'
+
+interface ServerExtra { name: string, error?: string, busy?: Promise<string> }
+let httpSrv: http.Server & ServerExtra
+let httpsSrv: http.Server & ServerExtra
+
+const openBrowserAtStart = defineConfig('open_browser_at_start', !DEV)
+
+export const portCfg = defineConfig<number>('port', 80)
+portCfg.sub(async port => {
+    while (!app)
+        await wait(100)
+    stopServer(httpSrv).then()
+    httpSrv = Object.assign(http.createServer(app.callback()), { name: 'http' })
+    port = await startServer(httpSrv, { port })
+    if (!port) return
+    httpSrv.on('connection', newConnection)
+    printUrls(port, 'http')
+    if (openBrowserAtStart.get())
+        openAdmin()
+})
+
+export function openAdmin() {
+    for (const srv of [httpSrv, httpsSrv]) {
+        const a = srv.address()
+        if (!a || typeof a === 'string') continue
+        const baseUrl = srv.name + '://localhost:' + a.port
+        open(baseUrl + ADMIN_URI, { wait: true}).catch(e => {
+            console.debug(String(e))
+            console.warn("cannot launch browser on this machine >PLEASE< open your browser and reach one of these (you may need a different address)",
+                ...Object.values(getUrls()).flat().map(x => '\n - ' + x + ADMIN_URI))
+            if (! anyAccountCanLoginAdmin())
+                console.log(`HINT: you can enter command: create-admin YOUR_PASSWORD`)
+        })
+        return true
+    }
+    console.log("openAdmin failed")
+}
+
+const considerHttps = debounceAsync(async () => {
+    stopServer(httpsSrv).then()
+    let port = httpsPortCfg.get()
+    try {
+        while (!app)
+            await wait(100)
+        httpsSrv = Object.assign(
+            https.createServer(port < 0 ? {} : { key: httpsOptions.private_key, cert: httpsOptions.cert }, app.callback()),
+            { name: 'https', error: undefined }
+        )
+        if (port >= 0) {
+            const namesForOutput: any = { cert: 'certificate', private_key: 'private key' }
+            const missing = httpsNeeds.find(x => !x.get())?.key()
+            if (missing)
+                return httpsSrv.error = "missing " + namesForOutput[missing]
+            const cantRead = httpsNeeds.find(x => !httpsOptions[x.key() as HttpsKeys])?.key()
+            if (cantRead)
+                return httpsSrv.error = "cannot read " + namesForOutput[cantRead]
+        }
+    }
+    catch(e) {
+        httpsSrv.error = "bad private key or certificate"
+        console.log("failed to create https server: check your private key and certificate", String(e))
+        return
+    }
+    port = await startServer(httpsSrv, { port })
+    if (!port) return
+    httpsSrv.on('connection', newConnection)
+    printUrls(port, 'https')
+})
+
+
+const cert = defineConfig<string>('cert')
+const privateKey = defineConfig<string>('private_key')
+const httpsNeeds = [cert, privateKey]
+const httpsOptions = { cert: '', private_key: '' }
+type HttpsKeys = keyof typeof httpsOptions
+for (const cfg of httpsNeeds) {
+    let unwatch: ReturnType<typeof watchLoad>['unwatch']
+    cfg.sub(async v => {
+        unwatch?.()
+        const k = cfg.key() as HttpsKeys
+        httpsOptions[k] = v
+        if (!v || v.includes('\n'))
+            return considerHttps()
+        // v is a path
+        httpsOptions[k] = ''
+        unwatch = watchLoad(v, data => {
+            httpsOptions[k] = data
+            considerHttps()
+        }).unwatch
+        await considerHttps()
+    })
+}
+
+export const httpsPortCfg = defineConfig('https_port', -1)
+httpsPortCfg.sub(considerHttps)
+
+interface StartServer { port: number, host?:string }
+function startServer(srv: typeof httpSrv, { port, host }: StartServer) {
+    return new Promise<number>(async resolve => {
+        try {
+            if (port < 0 || !host && !await testIpV4()) // !host means ipV4+6, and if v4 port alone is busy we won't be notified of the failure, so we'll first test it on its own
+                return resolve(0)
+            port = await listen(host)
+            if (port)
+                console.log(srv.name, "serving on", host||"any network", ':', port)
+            resolve(port)
+        }
+        catch(e) {
+            srv.error = String(e)
+            console.error(srv.name, "couldn't listen on port", port, srv.error)
+            resolve(0)
+        }
+    })
+
+    async function testIpV4() {
+        const res = await listen('0.0.0.0')
+        await new Promise(res => srv.close(res))
+        return res > 0
+    }
+
+    function listen(host?: string) {
+        return new Promise<number>(async (resolve, reject) => {
+            srv.listen({ port, host }, () => {
+                const ad = srv.address()
+                if (!ad)
+                    return reject('no address')
+                if (typeof ad === 'string') {
+                    srv.close()
+                    return reject('type of socket not supported')
+                }
+                resolve(ad.port)
+            }).on('error', async e => {
+                srv.error = String(e)
+                srv.busy = undefined
+                const { code } = e as any
+                if (code === 'EADDRINUSE') {
+                    srv.busy = findProcess('port', port).then(res => res?.[0]?.name || '', () => '')
+                    srv.error = `port ${port} busy: ${await srv.busy || "unknown process"}`
+                }
+                console.error(srv.name, srv.error)
+                const k = (srv === httpSrv? portCfg : httpsPortCfg).key()
+                console.log(` >> try specifying a different port, enter this command: config ${k} 8011`)
+                resolve(0)
+            })
+        })
+    }
+}
+
+function stopServer(srv: http.Server) {
+    return new Promise(resolve => {
+        if (!srv?.listening)
+            return resolve(null)
+        const ad = srv.address()
+        if (ad && typeof ad !== 'string')
+            console.log("stopped port", ad.port)
+        srv.close(err => {
+            if (err && (err as any).code !== 'ERR_SERVER_NOT_RUNNING')
+                console.debug("failed to stop server", String(err))
+            resolve(err)
+        })
+    })
+}
+
+export function getStatus() {
+    return {
+        httpSrv,
+        httpsSrv,
+    }
+}
+
+const ignore = /^(lo|.*loopback.*|virtualbox.*|.*\(wsl\).*|llw\d|awdl\d|utun\d|anpi\d)$/i // avoid giving too much information
+
+export function getUrls() {
+    return Object.fromEntries(onlyTruthy([httpSrv, httpsSrv].map(srv => {
+        if (!srv?.listening)
+            return false
+        const port = (srv?.address() as any)?.port
+        const appendPort = port === (srv.name === 'https' ? 443 : 80) ? '' : ':' + port
+        const urls = onlyTruthy(Object.entries(networkInterfaces()).map(([name, nets]) =>
+                nets && !ignore.test(name) && nets.map(net => {
+                    if (net.internal) return
+                    let { address } = net
+                    if (address.includes(':'))
+                        address = '[' + address + ']'
+                    return srv.name + '://' + address + appendPort
+                })
+        ).flat())
+        return urls.length && [srv.name, urls]
+    })))
+}
+
+function printUrls(port: number, proto: string) {
+    if (!port) return
+    for (const [name, nets] of Object.entries(networkInterfaces())) {
+        if (!nets || ignore.test(name)) continue
+        _.remove(nets, 'internal')
+        if (!nets.length) continue
+        const best = _.find(nets, { family: 'IPv4' }) || nets[0]
+        const appendPort = port === (proto==='https' ? 443 : 80) ? '' : ':' + port
+        let { address } = best
+        if (address.includes(':'))
+            address = '['+address+']'
+        console.log('network', name, proto + '://' + address + appendPort)
+    }
+}

package/src/log.ts

@@ -0,0 +1,128 @@
+// This file is part of HFS - Copyright 2021-2022, Massimo Melina <a@rejetto.com> - License https://www.gnu.org/licenses/gpl-3.0.txt
+
+import Koa from 'koa'
+import { Writable } from 'stream'
+import { defineConfig } from './config'
+import { createWriteStream, renameSync } from 'fs'
+import * as util from 'util'
+import { mkdir, stat } from 'fs/promises'
+import { DAY } from './const'
+import events from './events'
+import _ from 'lodash'
+import { dirname } from 'path'
+import { getCurrentUsername } from './perm'
+
+class Logger {
+    stream?: Writable
+    last?: Date
+    path: string = ''
+
+    constructor(readonly name: string){
+    }
+
+    async setPath(path: string) {
+        this.path = path
+        this.stream?.end()
+        this.last = undefined
+        if (!path)
+            return this.stream = undefined
+        try {
+            const stats = await stat(path)
+            this.last = stats.mtime || stats.ctime
+        }
+        catch {
+            await mkdir(dirname(path), { recursive: true })
+                .catch(() => console.log("cannot create folder for", path))
+        }
+        this.reopen()
+    }
+
+    reopen() {
+        return this.stream = createWriteStream(this.path, { flags: 'a' })
+            .on('error', () => this.stream = undefined)
+    }
+}
+
+// we'll have names same as config keys. These are used also by the get_log api.
+const accessLogger = new Logger('log')
+const accessErrorLog = new Logger('error_log')
+export const loggers = [accessLogger, accessErrorLog]
+
+defineConfig('log', 'logs/access.log').sub(path => {
+    console.debug('access log file: ' + (path || 'disabled'))
+    accessLogger.setPath(path)
+})
+
+const errorLogFile = defineConfig(accessErrorLog.name, 'logs/access-error.log')
+errorLogFile.sub(path => {
+    console.debug('access error log: ' + (path || 'disabled'))
+    accessErrorLog.setPath(path)
+})
+
+const logRotation = defineConfig('log_rotation', 'weekly')
+
+export function log(): Koa.Middleware {
+    const debounce = _.debounce(cb => cb(), 1000)
+    return async (ctx, next) => {  // wrapping in a function will make it use current 'mw' value
+        await next()
+        const isError = ctx.status >= 400
+        const logger = isError && accessErrorLog || accessLogger
+        const rotate = logRotation.get()?.[0]
+        let { stream, last, path } = logger
+        if (!stream) return
+        const now = new Date()
+        const a = now.toString().split(' ')
+        logger.last = now
+        if (rotate && last) { // rotation enabled and a file exists?
+            const passed = Number(now) - Number(last)
+                - 3600_000 // be pessimistic and count a possible DST change
+            if (rotate === 'm' && (passed >= 31*DAY || now.getMonth() !== last.getMonth())
+            || rotate === 'd' && (passed >= DAY || now.getDate() !== last.getDate()) // checking passed will solve the case when the day of the month is the same but a month has passed
+            || rotate === 'w' && (passed >= 7*DAY || now.getDay() < last.getDay())) {
+                stream.end()
+                const postfix = last.getFullYear() + '-' + doubleDigit(last.getMonth() + 1) + '-' + doubleDigit(last.getDate())
+                try { // other logging requests shouldn't happen while we are renaming. Since this is very infrequent we can tolerate solving this by making it sync.
+                    renameSync(path, path + '-' + postfix)
+                }
+                catch(e) {  // ok, rename failed, but this doesn't mean we ain't gonna log
+                    console.error(e)
+                }
+                stream = logger.reopen() // keep variable updated
+                if (!stream) return
+            }
+        }
+        const format = '%s - %s [%s] "%s %s HTTP/%s" %d %s\n' // Apache's Common Log Format
+        const date = a[2]+'/'+a[1]+'/'+a[3]+':'+a[4]+' '+a[5].slice(3)
+        const user = getCurrentUsername(ctx)
+        events.emit(logger.name, Object.assign(_.pick(ctx, ['ip', 'method','status','length']), { user, ts: now, uri: ctx.path }))
+        console.debug(ctx.status, ctx.method, ctx.path)
+        debounce(() => // once in a while we check if the file is still good (not deleted, etc), or we'll reopen it
+            stat(logger.path).catch(() => logger.reopen())) // async = smoother but we may lose some entries
+        stream.write(util.format( format,
+            ctx.ip,
+            user || '-',
+            date,
+            ctx.method,
+            ctx.path,
+            ctx.req.httpVersion,
+            ctx.status,
+            ctx.length ? ctx.length.toString() : '-',
+        ))
+    }
+}
+
+function doubleDigit(n: number) {
+    return n > 9 ? n : '0'+n
+}
+
+// dump console.error to file
+const debugLogFile = createWriteStream('debug.log', { flags: 'a' })
+debugLogFile.on('open', () => {
+    const was = console.error
+    console.error = function(...args: any[]) {
+        was.apply(this, args)
+        const params = args.map(x =>
+            typeof x === 'string' ? x : JSON.stringify(x)).join(' ')
+        debugLogFile.write(new Date().toLocaleString() + ': ' + params + '\n')
+    }
+}).on('error', () => console.log("cannot create debug.log"))

package/src/middlewares.ts

@@ -0,0 +1,176 @@
+// This file is part of HFS - Copyright 2021-2022, Massimo Melina <a@rejetto.com> - License https://www.gnu.org/licenses/gpl-3.0.txt
+
+import compress from 'koa-compress'
+import Koa from 'koa'
+import session from 'koa-session'
+import { ADMIN_URI, BUILD_TIMESTAMP, DEV, FORBIDDEN, SESSION_DURATION } from './const'
+import Application from 'koa'
+import { FRONTEND_URI } from './const'
+import { cantReadStatusCode, hasPermission, nodeIsDirectory, urlToNode } from './vfs'
+import { dirTraversal, objSameKeys, tryJson } from './misc'
+import { zipStreamFromFolder } from './zip'
+import { serveFileNode } from './serveFile'
+import { serveGuiFiles } from './serveGuiFiles'
+import mount from 'koa-mount'
+import { Readable } from 'stream'
+import { applyBlock } from './block'
+import { getAccount, getCurrentUsername } from './perm'
+import { socket2connection, updateConnection, normalizeIp } from './connections'
+import basicAuth from 'basic-auth'
+import { SRPClientSession, SRPParameters, SRPRoutines } from 'tssrp6a'
+import { srpStep1 } from './api.auth'
+import { IncomingMessage } from 'http'
+
+export const gzipper = compress({
+    threshold: 2048,
+    gzip: { flush: require('zlib').constants.Z_SYNC_FLUSH },
+    deflate: { flush: require('zlib').constants.Z_SYNC_FLUSH },
+    br: false, // disable brotli
+    filter(type) {
+        return /text|javascript|style/i.test(type)
+    },
+})
+
+export const headRequests: Koa.Middleware = async (ctx, next) => {
+    const head = ctx.method === 'HEAD'
+    if (head)
+        ctx.method = 'GET' // let other middlewares work, so we can collect the size at the end
+    await next()
+    if (!head || ctx.body === undefined) return
+    const { length, status } = ctx.response
+    if (ctx.body)
+        ctx.body = Readable.from('') // empty the body for this is a HEAD request. Using Readable avoids koa from trying to set length to 0
+    ctx.status = status
+    if (length)
+        ctx.response.length = length
+}
+
+export const sessions = (app: Application) => session({
+    key: 'hfs_$id',
+    signed: true,
+    rolling: true,
+    maxAge: SESSION_DURATION,
+}, app)
+
+const serveFrontendFiles = serveGuiFiles(process.env.FRONTEND_PROXY, FRONTEND_URI)
+const serveFrontendPrefixed = mount(FRONTEND_URI.slice(0,-1), serveFrontendFiles)
+const serveAdminPrefixed = mount(ADMIN_URI.slice(0,-1), serveGuiFiles(process.env.ADMIN_PROXY, ADMIN_URI))
+
+export const serveGuiAndSharedFiles: Koa.Middleware = async (ctx, next) => {
+    const { path } = ctx
+    if (ctx.body)
+        return next()
+    if (path.startsWith(FRONTEND_URI))
+        return serveFrontendPrefixed(ctx,next)
+    if (path+'/' === ADMIN_URI)
+        return ctx.redirect(ADMIN_URI)
+    if (path.startsWith(ADMIN_URI))
+        return serveAdminPrefixed(ctx,next)
+    const node = await urlToNode(path, ctx)
+    if (!node)
+        return ctx.status = 404
+    const canRead = hasPermission(node, 'can_read', ctx)
+    const isFolder = await nodeIsDirectory(node)
+    if (isFolder && !path.endsWith('/'))
+        return ctx.redirect(path + '/')
+    if (canRead && !isFolder)
+        return node.source ? serveFileNode(node)(ctx,next)
+            : next()
+    if (!canRead) {
+        ctx.status = cantReadStatusCode(node)
+        if (ctx.status === FORBIDDEN)
+            return
+        const browserDetected = ctx.get('Upgrade-Insecure-Requests') || ctx.get('Sec-Fetch-Mode') // ugh, heuristics
+        if (!browserDetected) // we don't want to trigger basic authentication on browsers, it's meant for download managers only
+            ctx.set('WWW-Authenticate', 'Basic') // we support basic authentication
+        ctx.state.serveApp = true
+        return serveFrontendFiles(ctx, next)
+    }
+    ctx.set({ server:'HFS '+BUILD_TIMESTAMP })
+    const { get } = ctx.query
+    if (get === 'zip')
+        return await zipStreamFromFolder(node, ctx)
+    if (node.default) {
+        const def = await urlToNode(path + node.default, ctx)
+        return !def ? next()
+            : hasPermission(def, 'can_read', ctx) ? serveFileNode(def)(ctx, next)
+            : ctx.status = cantReadStatusCode(def)
+    }
+    return serveFrontendFiles(ctx, next)
+}
+
+let proxyDetected = false
+export const someSecurity: Koa.Middleware = async (ctx, next) => {
+    ctx.request.ip = normalizeIp(ctx.ip)
+    try {
+        let proxy = ctx.get('X-Forwarded-For')
+        // we have some dev-proxies to ignore
+        if (DEV && proxy && [process.env.FRONTEND_PROXY, process.env.ADMIN_PROXY].includes(ctx.get('X-Forwarded-port')))
+            proxy = ''
+        if (dirTraversal(decodeURI(ctx.path)))
+            return ctx.status = 418
+        if (applyBlock(ctx.socket, ctx.ip))
+            return
+        proxyDetected ||= proxy > ''
+        ctx.state.proxiedFor = proxy
+    }
+    catch {
+        return ctx.status = 418
+    }
+    return next()
+}
+
+// this is only about http proxies
+export function getProxyDetected() {
+    return proxyDetected
+}
+export const prepareState: Koa.Middleware = async (ctx, next) => {
+    // calculate these once and for all
+    ctx.state.account = await getHttpAccount(ctx) ?? getAccount(getCurrentUsername(ctx))
+    const conn = ctx.state.connection = socket2connection(ctx.socket)
+    await next()
+    if (conn)
+        updateConnection(conn, { ctx })
+}
+
+async function getHttpAccount(ctx: Koa.Context) {
+    const credentials = basicAuth(ctx.req)
+    const account = getAccount(credentials?.name||'')
+    if (account && await srpCheck(account.username, credentials!.pass))
+        return account
+}
+
+async function srpCheck(username: string, password: string) {
+    username = username.toLocaleLowerCase()
+    const account = getAccount(username)
+    if (!account?.srp || !password) return false
+    const { step1, salt, pubKey } = await srpStep1(account)
+    const client = new SRPClientSession(new SRPRoutines(new SRPParameters()))
+    const clientRes1 = await client.step1(username, password)
+    const clientRes2 = await clientRes1.step2(BigInt(salt), BigInt(pubKey))
+    return await step1.step2(clientRes2.A, clientRes2.M1).then(() => true, () => false)
+}
+
+// unify get/post parameters, with JSON decoding to not be limited to strings
+export const paramsDecoder: Koa.Middleware = async (ctx, next) => {
+    ctx.params = ctx.method === 'POST' ? tryJson(await getReqData(ctx.req))
+        : objSameKeys(ctx.query, x => Array.isArray(x) ? x : tryJson(x))
+    await next()
+}
+
+async function getReqData(req: IncomingMessage): Promise<any> {
+    return new Promise((resolve, reject) => {
+        let data = ''
+        req.on('data', chunk =>
+            data += chunk)
+        req.on('error', reject)
+        req.on('end', () => {
+            try {
+                resolve(data)
+            }
+            catch(e) {
+                reject(e)
+            }
+        })
+    })
+}

package/src/misc.ts

@@ -0,0 +1,149 @@
+// This file is part of HFS - Copyright 2021-2022, Massimo Melina <a@rejetto.com> - License https://www.gnu.org/licenses/gpl-3.0.txt
+
+import { EventEmitter } from 'events'
+import { basename } from 'path'
+import _ from 'lodash'
+import Koa from 'koa'
+import { Connection } from './connections'
+import assert from 'assert'
+export * from './util-http'
+export * from './util-generators'
+export * from './util-files'
+import debounceAsync from './debounceAsync'
+export { debounceAsync }
+
+export type Callback<IN=void, OUT=void> = (x:IN) => OUT
+export type Dict<T = any> = Record<string, T>
+
+export function enforceFinal(sub:string, s:string) {
+    return s.endsWith(sub) ? s : s+sub
+}
+
+export function prefix(pre:string, v:string|number, post:string='') {
+    return v ? pre+v+post : ''
+}
+
+export function setHidden<T, ADD>(dest: T, src: ADD) {
+    return Object.defineProperties(dest, objSameKeys(src as any, value => ({
+        enumerable: false,
+        writable: true,
+        value,
+    }))) as T & ADD
+}
+
+export function objSameKeys<S extends object,VR=any>(src: S, newValue:(value:Truthy<S[keyof S]>, key:keyof S)=>any) {
+    return Object.fromEntries(Object.entries(src).map(([k,v]) => [k, newValue(v,k as keyof S)])) as { [K in keyof S]:VR }
+}
+
+export function wait(ms: number) {
+    return new Promise(res=> setTimeout(res,ms))
+}
+
+export function wantArray<T>(x?: void | T | T[]) {
+    return x == null ? [] : Array.isArray(x) ? x : [x]
+}
+
+export function getOrSet<T>(o: Record<string,T>, k:string, creator:()=>T): T {
+    return k in o ? o[k]
+        : (o[k] = creator())
+}
+
+// 10 chars is 51+bits, 8 is 41+bits
+export function randomId(len = 10): string {
+    if (len > 10)
+        return randomId(10) + randomId(len - 10)
+    return Math.random()
+        .toString(36)
+        .substring(2, 2+len)
+        .replace(/l/g, 'L'); // avoid confusion reading l1
+}
+
+type ProcessExitHandler = (signal:string) => any
+const cbs = new Set<ProcessExitHandler>()
+export function onProcessExit(cb: ProcessExitHandler) {
+    cbs.add(cb)
+    return () => cbs.delete(cb)
+}
+onFirstEvent(process, ['exit', 'SIGQUIT', 'SIGTERM', 'SIGINT', 'SIGHUP'], signal =>
+    Promise.allSettled(Array.from(cbs).map(cb => cb(signal))).then(() =>
+        process.exit(0)))
+
+export function onFirstEvent(emitter:EventEmitter, events: string[], cb: (...args:any[])=> void) {
+    let already = false
+    for (const e of events)
+        emitter.on(e, (...args) => {
+            if (already) return
+            already = true
+            cb(...args)
+        })
+}
+
+export function pattern2filter(pattern: string){
+    const re = new RegExp(_.escapeRegExp(pattern), 'i')
+    return (s?:string) =>
+        !s || !pattern || re.test(basename(s))
+}
+
+type Truthy<T> = T extends false | '' | 0 | null | undefined ? never : T
+
+export function truthy<T>(value: T): value is Truthy<T> {
+    return Boolean(value)
+}
+
+export function onlyTruthy<T>(arr: T[]) {
+    return arr.filter(truthy)
+}
+
+type PendingPromise<T> = Promise<T> & { resolve: (value: T) => void, reject: (reason?: any) => void }
+export function pendingPromise<T>() {
+    let takeOut
+    const ret = new Promise<T>((resolve, reject) =>
+        takeOut = { resolve, reject })
+    return Object.assign(ret, takeOut) as PendingPromise<T>
+}
+
+// install multiple handlers and returns a handy 'uninstall' function which requires no parameter. Pass a map {event:handler}
+export function onOff(em: EventEmitter, events: { [eventName:string]: (...args: any[]) => void }) {
+    events = { ...events } // avoid later modifications, as we need this later for uninstallation
+    for (const [k,cb] of Object.entries(events))
+        for (const e of k.split(' '))
+            em.on(e, cb)
+    return () => {
+        for (const [k,cb] of Object.entries(events))
+            for (const e of k.split(' '))
+                em.off(e, cb)
+    }
+}
+
+export function objRenameKey(o: Dict | undefined, from: string, to: string) {
+    if (!o || !o.hasOwnProperty(from) || from === to) return
+    o[to] = o[from]
+    delete o[from]
+    return true
+}
+
+export function typedKeys<T extends {}>(o: T) {
+    return Object.keys(o) as (keyof T)[]
+}
+
+export function with_<T,RT>(par:T, cb: (par:T) => RT) {
+    return cb(par)
+}
+
+export function isLocalHost(c: Connection | Koa.Context) {
+    const ip = c.socket.remoteAddress // don't use Context.ip as it is subject to proxied ips, and that's no use for localhost detection
+    return ip && (ip === '::1' || ip.endsWith('127.0.0.1'))
+}
+
+export function same(a: any, b: any) {
+    try {
+        assert.deepStrictEqual(a, b)
+        return true
+    }
+    catch { return false }
+}
+
+export function tryJson(s?: string) {
+    try { return s && JSON.parse(s) }
+    catch {}
+}