spec-3nweb-server 1.8.5 → 1.8.7

package/ts-code/lib-server/middleware/body-parsers.ts

@@ -0,0 +1,248 @@
+/*
+ Copyright (C) 2015 - 2016, 2025 3NSoft Inc.
+ 
+ This program is free software: you can redistribute it and/or modify it under
+ the terms of the GNU General Public License as published by the Free Software
+ Foundation, either version 3 of the License, or (at your option) any later
+ version.
+ 
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ See the GNU General Public License for more details.
+ 
+ You should have received a copy of the GNU General Public License along with
+ this program. If not, see <http://www.gnu.org/licenses/>.
+*/
+
+import { Request, Response, NextFunction, RequestHandler } from 'express';
+import { stringToNumOfBytes } from '../conf-util';
+import { makeErr } from './error-handler';
+import { defer } from '../../lib-common/processes';
+import { BytesFIFOBuffer } from '../../lib-common/byte-streaming/common';
+import { EMPTY_BUFFER } from '../../lib-common/buffer-utils';
+
+const HTTP_HEADER = {
+	contentType: 'Content-Type',
+	contentLength: 'Content-Length'
+};
+
+const TYPES = {
+	plain: 'text/plain',
+	json: 'application/json',
+	bin: 'application/octet-stream'
+};
+
+export function attachByteDrainToRequest(req: Request): void {
+	req.on('data', noop);
+	req.on('end', noop);
+}
+
+function noop() {}
+
+/**
+ * Use this for empty-body POST and PUT routes, as it does sanitization, and
+ * prevents hanging requests, because nothing drains data.
+ * @return a middleware function that ensures empty body in requests.
+ */
+export function emptyBody(): RequestHandler {
+	return (req, _res, next) => {
+		attachByteDrainToRequest(req);
+		
+		// get and check Content-Length
+		const contentLength = parseInt(req.get(HTTP_HEADER.contentLength)!, 10);
+		if (isNaN(contentLength)) {
+			return next(makeErr(411,
+				"Content-Length header is required with proper number."));
+		}
+		if (contentLength !== 0) {
+			return next(makeErr(413, "Request body is too long."));
+		}
+		
+		next();
+	}	
+}
+
+/**
+ * @param req
+ * @param expectedLen is an expected non-zero length of a binary body.
+ * If body has different length, this function throws.
+ * @return a promise, resolvable to request's body bytes, parsed from a request
+ * object.
+ */
+export async function parseBinaryBodyWithExpectedSize(
+	req: Request, expectedLen: number
+): Promise<Uint8Array> {
+	try {
+		if (expectedLen < 1) { throw new Error(`Given illegal length value ${expectedLen}`); }
+
+		// check type
+		if (!req.is(TYPES.bin)) {
+			throw makeErr(415, `Content-Type must be ${TYPES.bin} for this call.`);
+		}
+
+		// check length declared in header
+		const contentLength = parseInt(req.get(HTTP_HEADER.contentLength)!, 10);
+		if (isNaN(contentLength)) {
+			throw makeErr(411,
+				"Content-Length header is required with proper number.");
+		}
+		if (contentLength !== expectedLen) {
+			throw makeErr(400, "Unexpected number of bytes.");
+		}
+
+	} catch (err) {
+		attachByteDrainToRequest(req);
+		throw err;
+	}
+
+	const deffered = defer<Uint8Array>();
+	const bytes = new BytesFIFOBuffer();
+
+	// collect body bytes
+	let erred = false;
+	req.on('data', (chunk: Buffer) => {
+		if (erred) { return; }
+		if ((bytes.length + chunk.length) <= expectedLen) {
+			bytes.push(chunk);
+		} else {
+			erred = true;
+			deffered.reject(makeErr(400, "Request body is longer than expected."));
+		}
+	});
+	req.on('end', () => {
+		if (erred) { return; }
+		if (bytes.length === expectedLen) {
+			deffered.resolve(bytes.getBytes(undefined)!);
+		} else {
+			deffered.reject(makeErr(400,
+				"Request body is shorter than expected."));
+		}
+	});
+
+	return deffered.promise;
+}
+
+function byteCollector(
+	maxSize: string|number, contentType: string, parser?: RequestHandler
+): RequestHandler {
+	const maxSizeNum = stringToNumOfBytes(maxSize);
+	if ('string' !== typeof contentType) {
+		throw new Error("Given 'contentType' argument must be a string.");
+	}
+
+	return (req, res, next) => {
+		// check Content-Type
+		if (!req.is(contentType)) {
+			attachByteDrainToRequest(req);
+			return next(makeErr(415, "Content-Type must be "+
+				contentType+" for this call."));
+		}
+
+		// get and check Content-Length
+		const contentLength = parseInt(req.get(HTTP_HEADER.contentLength)!, 10);
+		if (isNaN(contentLength)) {
+			attachByteDrainToRequest(req);
+			return next(makeErr(411,
+				"Content-Length header is required with proper number."));
+		}
+		
+		// enforce agreed limit on request size
+		if (contentLength > maxSizeNum) {
+			attachByteDrainToRequest(req);
+			return next(makeErr(413, "Request body is too long."));
+		}
+
+		// XXX we may use fifo here, postponing byte copying till moment, when
+		//		everything is downloaded
+
+		// set body to be buffer for all expected incoming bytes
+		req.body = (contentLength > 0) ?
+			Buffer.alloc(contentLength) : EMPTY_BUFFER;
+
+		// collect incoming bytes into body array
+		let bytesRead = 0;
+		let erred = false;
+		req.on('data', (chunk: Buffer) => {
+			if (erred) { return; }
+			if ((bytesRead + chunk.length) <= contentLength) {
+				chunk.copy(req.body, bytesRead);
+				bytesRead += chunk.length;
+			} else {
+				erred = true;
+				req.body = null;
+				next(makeErr(413, "Request body is too long."));
+			}
+		});
+
+		req.on('end', () => {
+			if (erred) { return; }
+			if (parser) {
+				parser(req, res, next);
+			} else {
+				next();
+			}
+		});
+	};
+}
+
+/**
+ * @param maxSize is a maximum allowed body length, given as number of bytes,
+ * or string parameter for kb/mb's.
+ * @return middleware function, that places all request bytes into Buffer,
+ * placed into usual body field of request object. 
+ */
+export function binary(maxSize: string|number): RequestHandler {
+	return byteCollector(maxSize, TYPES.bin);
+}
+
+/**
+ * @param maxSize is a maximum allowed body length, given as number of bytes,
+ * or string parameter for kb/mb's.
+ * @param allowNonObject is a boolean flag, which, when true, turns of a check
+ * that forces body to be an object.
+ * @return middleware function, that parses all request bytes as JSON, placing
+ * result into usual body field of request object.
+ */
+export function json(
+	maxSize: string|number, allowNonObject?: boolean
+): RequestHandler {
+	return byteCollector(maxSize, TYPES.json, (req, _res, next) => {
+		try {
+			const bodyAsStr = req.body.toString('utf8');
+			req.body = ((bodyAsStr === '') ?
+				undefined :
+				JSON.parse(bodyAsStr)
+			);
+		} catch (err) {
+			return next(
+				makeErr(400, "Request body cannot be interpreted as JSON.")
+			);
+		}
+		if (!allowNonObject
+		&& (!req.body || (typeof req.body !== 'object'))) {
+			return next(makeErr(400, "Request body is not a JSON object."));
+		}
+		next();
+	});
+}
+
+/**
+ * @param maxSize is a maximum allowed body length, given as number of bytes, or
+ * string parameter for kb/mb's.
+ * @return middleware function, that parses all request bytes as utf8 text,
+ * placing result into usual body field of request object.
+ */
+export function textPlain(maxSize: string|number): RequestHandler {
+	return byteCollector(maxSize, TYPES.plain, (req, _res, next) => {
+		try {
+			req.body = req.body.toString('utf8');
+		} catch (err) {
+			return next(makeErr(400,
+				"Request body cannot be interpreted as plain utf8 text."));
+		}
+		next();
+	});
+}
+
+Object.freeze(exports);

package/ts-code/lib-server/middleware/error-handler.ts

@@ -0,0 +1,79 @@
+/*
+ Copyright (C) 2016, 2020, 2023 3NSoft Inc.
+ 
+ This program is free software: you can redistribute it and/or modify it under
+ the terms of the GNU General Public License as published by the Free Software
+ Foundation, either version 3 of the License, or (at your option) any later
+ version.
+ 
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ See the GNU General Public License for more details.
+ 
+ You should have received a copy of the GNU General Public License along with
+ this program. If not, see <http://www.gnu.org/licenses/>.
+*/
+
+import { Request, ErrorRequestHandler } from 'express';
+import * as http from 'http';
+import { ErrorWithCause, errWithCause as makeErrWithCause } from '../../lib-common/exceptions/error';
+
+export interface HttpError extends ErrorWithCause {
+	status: number;
+}
+
+/**
+ * This creates an error object that should be given to next(), instead of
+ * throwing it.
+ * @param code is http status code to be attached to produced error object.
+ * @param msg goes into error message.
+ * @param cause
+ */
+export function makeErr(code: number, msg: string, cause?: any): HttpError {
+  const err = makeErrWithCause(cause, msg) as HttpError;
+  err.status = code;
+  return err;
+}
+
+export type ErrLogger = (err: any, req: Request) => void;
+
+export function makeErrHandler(log?: ErrLogger): ErrorRequestHandler {
+	// Note that when we don't have next, tons of errors show up.
+	// I guess, express checks how many arguments js function takes, and
+	// gives args respectively. Thus, since express is doing this introspection
+	// (magic?), we have to leave next argument, even though we ain't using it.
+	return async function (err: HttpError, req, res, next) {
+		let resStatus: number;
+		let resBody: string;
+		if (err && (typeof err.status === 'number')) {
+			resStatus = err.status;
+			if (resStatus === 500) {
+				resBody = http.STATUS_CODES[500]!;
+			} else if (err.message) {
+				resBody = err.message;
+			} else {
+				resBody = http.STATUS_CODES[err.status]!;
+			}
+		} else {
+			resStatus = 500;
+			resBody = http.STATUS_CODES[500]!;
+		}
+		res.status(resStatus).send(resBody);
+		if (log) {
+			log(err, req);
+		}
+	};
+}
+
+export function makeErrLoggerToConsole(srvName: string): ErrLogger {
+	return (err, req) => {
+		if (typeof err.status !== 'number') {
+			console.error(`\n --- Error occured in ${srvName}, when handling ${req.method} request to ${req.originalUrl}`);
+			console.error(err);
+		}
+	};
+}
+
+
+Object.freeze(exports);

package/ts-code/lib-server/pkl-access.ts

@@ -0,0 +1,46 @@
+/*
+ Copyright (C) 2024 3NSoft Inc.
+ 
+ This program is free software: you can redistribute it and/or modify it under
+ the terms of the GNU General Public License as published by the Free Software
+ Foundation, either version 3 of the License, or (at your option) any later
+ version.
+ 
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ See the GNU General Public License for more details.
+ 
+ You should have received a copy of the GNU General Public License along with
+ this program. If not, see <http://www.gnu.org/licenses/>.
+*/
+
+import { Express } from 'express';
+import { json as parseJSON, binary as parseBinary } from './middleware/body-parsers';
+import { Factory as SessionsFactory } from './resources/sessions';
+import { ComputeDHSharedKey, GetUserPKeyAndKeyGenParams, SessionParams, startPKLogin } from './routes/pub-key-login/start-exchange';
+import { completePKLogin } from './routes/pub-key-login/complete-exchange';
+import * as api from '../lib-common/service-api/pub-key-login';
+
+
+export function addPKLLoginRoutes(
+	app: Express, urlPrefix: string,
+	getUserParamsAndKey: GetUserPKeyAndKeyGenParams,
+	sessions: SessionsFactory<SessionParams>,
+	computeDHSharedKey: ComputeDHSharedKey
+): void {
+
+	app.post(urlPrefix + api.start.URL_END,
+		sessions.checkSession(),
+		parseJSON('1kb'),
+		startPKLogin(
+			getUserParamsAndKey, sessions.generate, computeDHSharedKey
+		)
+	);
+	app.post(urlPrefix + api.complete.URL_END,
+		sessions.ensureOpenedSession(),
+		parseBinary('1kb'),
+		completePKLogin()
+	);
+
+}

package/ts-code/lib-server/resources/dns.ts

@@ -0,0 +1,151 @@
+/*
+ Copyright (C) 2015 - 2016, 2023 3NSoft Inc.
+ 
+ This program is free software: you can redistribute it and/or modify it under
+ the terms of the GNU General Public License as published by the Free Software
+ Foundation, either version 3 of the License, or (at your option) any later
+ version.
+ 
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ See the GNU General Public License for more details.
+ 
+ You should have received a copy of the GNU General Public License along with
+ this program. If not, see <http://www.gnu.org/licenses/>.
+*/
+
+import * as dns from 'dns';
+
+export const SC = {
+	RECORDS_MISSING: 'records missing',
+	DOMAIN_NOT_FOUND: 'domain not found'
+};
+Object.freeze(SC);
+
+const DNS_ERR_CODE = {
+	NODATA: 'ENODATA',
+	NOTFOUND: 'ENOTFOUND'
+};
+Object.freeze(DNS_ERR_CODE);
+
+interface DnsError extends Error {
+	code: string;
+	hostname: string;
+}
+
+/**
+ * This implementation extracts exactly one string value for a given service.
+ * All other values are ignored, without raising error about misconfiguration.
+ * In time we may have several records for the same service type, yet, for now
+ * only one TXT per service per domain is considered valid.
+ * @param txtRecords are TXT records from dns.
+ * @param serviceLabel is a label of service, for which we want to get string
+ * value from TXT record.
+ * @return string value for a given service among given dns TXT records.  
+ */
+function extractPair(
+	txtRecords: string[][], serviceLabel: ServiceLabel
+): string|undefined {
+	for (const txtRecord of txtRecords) {
+		let joinedTXTstanzas = txtRecord.join('');
+		let record = getRecordAtStartOf(joinedTXTstanzas);
+		while (record) {
+			if (record.service === serviceLabel) {
+				const value = record.value.trim();
+				if (value.length > 0) {
+					return value;
+				}
+			}
+			if (record.txtTail) {
+				record = getRecordAtStartOf(record.txtTail);
+			} else {
+				break;
+			}
+		}
+	}
+	return;
+}
+
+const recordsStarts: { [key in ServiceLabel]: string; } = {
+	"3nstorage": '3nstorage=',
+	asmail: 'asmail=',
+	mailerid: 'mailerid='
+}
+
+function getRecordAtStartOf(txt: string): {
+	service: ServiceLabel; value: string; txtTail?: string;
+}|undefined {
+	let service: ServiceLabel|undefined = undefined;
+	for (const [ label, startSeq ] of Object.entries(recordsStarts)) {
+		if (txt.startsWith(startSeq)) {
+			service = label as ServiceLabel;
+			txt = txt.substring(startSeq.length);
+			break;
+		}
+	}
+	if (!service) { return; }
+	for (const delimiter of Object.values(recordsStarts)) {
+		const endPos = txt.indexOf(delimiter);
+		if (endPos >= 0) {
+			return {
+				service,
+				value: txt.substring(0, endPos),
+				txtTail: txt.substring(endPos)
+			};
+		}
+	}
+	return {
+		service,
+		value: txt
+	};
+}
+
+export type ServiceLabel = 'asmail' | 'mailerid' | '3nstorage';
+
+function resolveTxt(domain: string): Promise<string[][]> {
+	return new Promise<string[][]>((resolve, reject) => {
+		// As of March 2017, docs for node say that texts given in a callback
+		// are string[][], and node works this way, but definition is incorrect.
+		// Therefore, need to insert "as any" into resolve function.
+		dns.resolveTxt(domain, (err, texts) => {
+			if (err) {
+				reject(err);
+			} else {
+				resolve(texts as any);
+			}
+		});
+	});
+}
+
+/**
+ * @param address
+ * @return domain string, extracted from a given address
+ */
+function domainOfAddress(address: string): string {
+	address = address.trim();
+	const indOfAt = address.lastIndexOf('@');
+	const domain = ((indOfAt < 0) ? address : address.substring(indOfAt+1));
+	return domain;
+}
+
+export async function get3NWebRecords(address: string,
+		serviceLabel: ServiceLabel): Promise<string> {
+	try {
+		const domain = domainOfAddress(address);
+		const txtRecords = await resolveTxt(domain);
+		const recValue = extractPair(txtRecords, serviceLabel);
+		if (!recValue) { throw SC.RECORDS_MISSING; }
+		return recValue;
+	} catch (err) {
+		if ((<DnsError> err).code === DNS_ERR_CODE.NODATA) {
+			throw SC.RECORDS_MISSING;
+		} else if ((<DnsError> err).code === DNS_ERR_CODE.NOTFOUND) {
+			throw SC.DOMAIN_NOT_FOUND;
+		} else {
+			throw err;
+		}
+	}
+}
+
+Object.freeze(exports);

package/ts-code/lib-server/resources/mailerid-authorizer.ts

@@ -0,0 +1,115 @@
+/*
+ Copyright (C) 2015 - 2016, 2019, 2025 3NSoft Inc.
+ 
+ This program is free software: you can redistribute it and/or modify it under
+ the terms of the GNU General Public License as published by the Free Software
+ Foundation, either version 3 of the License, or (at your option) any later
+ version.
+ 
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ See the GNU General Public License for more details.
+ 
+ You should have received a copy of the GNU General Public License along with
+ this program. If not, see <http://www.gnu.org/licenses/>.
+*/
+
+import * as https from 'https';
+import { SignedLoad, getKeyCert, getPrincipalAddress } from '../../lib-common/jwkeys';
+import * as mid from '../../lib-common/mid-sigs-NaCl-Ed';
+import { get3NWebRecords } from './dns';
+import { MidAuthorizer } from '../routes/sessions/mid-auth';
+import { serviceRoot } from '../../lib-common/service-api/mailer-id/provisioning';
+
+/**
+ * @param serviceURL
+ * @return a promise, resolvable to MailerId provider's current root
+ * certificate.
+ */
+function getRootCert(serviceURL: string): Promise<SignedLoad> {
+	return new Promise<SignedLoad>((resolve, reject) => {
+		const req = https.request('https://'+serviceURL, (res) => {
+			if (res.statusCode === 200) {
+				res.setEncoding('utf8');
+				let collectedString = '';
+				res.on('data', (chunk) => {
+					collectedString += chunk;
+				});
+				res.on('end', () => {
+					const infoObj: serviceRoot.Reply = JSON.parse(collectedString);
+					const cert = infoObj['current-cert'];
+					if (cert) {
+						resolve(cert);
+					} else {
+						reject(new Error(
+							"Info file "+serviceURL+", is malformed."));
+					}
+				});
+				res.on('error', (err) => {
+					reject(err);
+				});
+			} else {
+				reject(new Error("Cannot get "+serviceURL+
+					", returned " +"status code is "+res.statusCode));
+			}
+		});
+		req.on('error', (err) => {
+			reject(err);
+		});
+		req.end();
+	});
+}
+
+// TODO need to add caching of certs using domain->(kid->cert)
+//		(this will speed things up)
+
+export function validator(ownMidService: OwnMidService|undefined): MidAuthorizer {
+	return (
+		rpDomain, sessionId, userId, assertion, userCert, provCert
+	) => validate(
+		rpDomain, sessionId, userId, assertion, userCert, provCert, ownMidService
+	);
+}
+
+export interface OwnMidService { domain: string; getRoot: () => SignedLoad; }
+
+async function validate(
+	rpDomain: string, sessionId: string, userId: string,
+	assertion: SignedLoad, userCert: SignedLoad, provCert: SignedLoad,
+	ownMidService: OwnMidService|undefined
+): Promise<boolean> {
+	const validAt = Date.now() / 1000;
+	try{
+		// check that certificate is for the user
+		const addressInCert = getPrincipalAddress(userCert);
+		if (userId !== addressInCert) { return false; }
+		
+		// check that issuer is the one that provides MailerId service for
+		// user's domain
+		const issuer = getKeyCert(provCert).issuer;
+		const serviceURL = await get3NWebRecords(addressInCert, 'mailerid');
+		const domainInRecord = serviceURL.split('/')[0].split(':')[0];
+		if (issuer !== domainInRecord) { return false; }
+
+		// get root certificate and check the whole chain
+		const rootCert = ((ownMidService && (issuer === ownMidService.domain)) ?
+			ownMidService.getRoot() : await getRootCert(serviceURL)
+		);
+		const assertInfo = mid.relyingParty.verifyAssertion(
+			assertion,
+			{ user: userCert, prov: provCert, root: rootCert },
+			issuer, validAt
+		);
+		if ((assertInfo.relyingPartyDomain === rpDomain)
+		&& (assertInfo.sessionId === sessionId)) {
+			return true;
+		} else {
+			return false;
+		}
+	} catch (e) {
+		return false;
+	}
+}
+
+Object.freeze(exports);