spec-3nweb-server 1.8.5 → 1.8.7

package/ts-code/asmail/routes/delivery/sender-authorization.ts

@@ -0,0 +1,81 @@
+/*
+ Copyright (C) 2015 - 2016, 2026 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 { RequestHandler } from 'express';
+import { SignedLoad } from '../../../lib-common/jwkeys';
+import { authSender as api, ERR_SC } from '../../../lib-common/service-api/asmail/delivery';
+import { Request } from '../../resources/delivery-sessions';
+import { replyWithErr } from '../../resources/utils';
+
+export type IMidAuthorizer = (
+	rpDomain: string, sessionId: string, userId: string,
+	mailerIdAssertion: SignedLoad, userCert: SignedLoad, provCert: SignedLoad
+) => Promise<boolean>;
+
+
+/**
+ * This creates an authorize-sender route handler.
+ * @param relyingPartyDomain at which this service operates, as seen by client
+ * @param mailerIdAuthorizingFunc is a function returning promise, which
+ * resolves into boolean flag, with true value for authorization passing,
+ * and false for failed authorization. 
+ */
+export function authorize(relyingPartyDomain: string, midAuthorizingFunc: IMidAuthorizer): RequestHandler {
+	
+	return async (req: Request, res, next) => {
+
+		if (req.session.isAuthorized) {
+			return replyWithErr(ERR_SC.duplicateReq, "This protocol request has already been served.", res);
+		}
+
+		const rb: api.Request = req.body;
+		const sender = req.session.params.sender;
+		const sessionId = req.session.id;
+
+		if (!sender) {
+			// This case must be rejected, because place for authorizing
+			// anonymous connection is at the session start.
+			replyWithErr(api.SC.authFailed, "Server is not accepting provided credentials.", res);
+			req.session.close();
+			return;
+		}
+
+		if (!rb.assertion || !rb.userCert || !rb.provCert) {
+			replyWithErr(ERR_SC.malformed, "No credentials given.", res);
+			req.session.close();
+			return;
+		}
+
+		try {
+			const certsVerified = await midAuthorizingFunc(
+				relyingPartyDomain, sessionId, sender, rb.assertion, rb.userCert, rb.provCert
+			);
+			if (certsVerified) {
+				req.session.isAuthorized = true;
+				res.status(api.SC.ok).send();
+			} else {
+				replyWithErr(api.SC.authFailed, "Server is not accepting provided credentials.", res);
+				req.session.close();
+			}
+		} catch (err) {
+			next(err);
+		}
+
+	};
+}
+
+Object.freeze(exports);

package/ts-code/asmail/routes/delivery/start-session.ts

@@ -0,0 +1,136 @@
+/*
+ Copyright (C) 2015 - 2016, 2025 - 2026  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 { RequestHandler, Response } from 'express';
+import { GenerateSession, Request } from '../../resources/delivery-sessions';
+import { SC as recipSC, MsgDelivery } from '../../resources/recipients';
+import { sessionStart as api, ERR_SC } from '../../../lib-common/service-api/asmail/delivery';
+import { checkAndTransformAddress } from '../../../lib-common/canonical-address';
+import { replyWithErr } from '../../resources/utils';
+
+export type Redirect = (userId: string) => Promise<string>;
+
+/**
+ * This creates a start-session route handler.
+ * @param allowedMsgSizeFunc is a function returning promises, that
+ * may resolve to
+ * (1) undefined, if recipient is unknown,
+ * (2) zero (0), if leaving mail is forbidden,
+ * (3) greater than zero maximum message length, and
+ * (4) -1, if mail cannot be accepted due to full mail box.
+ * @param sessionGenFunc is a promise returning function that generates new
+ * session objects.
+ * @param redirectFunc is an optional function that returns a promise,
+ * resolvable to
+ * (1) string with URI for ASMail service, which is serving given recipient,
+ * (2) undefined, if it is this server should service given recipient. 
+ */
+export function startSession(
+	allowedMsgSizeFunc: MsgDelivery['allowedMaxMsgSize'],
+	sessionGenFunc: GenerateSession, redirectFunc?: Redirect
+): RequestHandler {
+
+	async function serveRequestHere(
+		recipient: string, sender: string|undefined,
+		invitation: string|undefined, res: Response
+	): Promise<void> {
+		const msgSize = await allowedMsgSizeFunc(recipient, sender, invitation);
+		if (msgSize > 0) {
+			const session = await sessionGenFunc();
+			session.params.recipient = recipient;
+			session.params.sender = sender;
+			session.params.invite = invitation;
+			session.params.maxMsgLength = msgSize;
+			if (!sender) {
+				// message delivery is allowed for anonymous
+				// sender, thus, we set isAuthorized flag here
+				session.isAuthorized = true;
+			}
+			res.status(api.SC.ok).json( <api.Reply> {
+				sessionId: session.id,
+				maxMsgLength: msgSize
+			});
+		} else if (msgSize === 0) {
+			replyWithErr(
+				api.SC.senderNotAllowed,
+				`${sender ? sender : "Anonymous sender "} is not allowed to leave mail for ${recipient}`, res
+			);
+		} else if (msgSize === -1) {
+			replyWithErr(api.SC.inboxFull, `Mail box for ${recipient} is full.`, res);
+		} else {
+			throw new Error(`Unrecognized code ${msgSize} for message size limits.`);
+		}
+	}
+
+	return async (req: Request, res, next) => {
+
+		const rb: api.Request = req.body;
+		const recipient = checkAndTransformAddress(rb.recipient);
+		let sender = rb.sender;
+		const invitation = rb.invitation;
+		const session = req.session;
+
+		// already existing session indicates repeated call, which should be bounced off
+		if (session) {
+			replyWithErr(ERR_SC.duplicateReq, "This protocol request has already been served.", res);
+			return;
+		}
+
+		// missing recipient makes a bad request
+		if (!recipient) {
+			replyWithErr(ERR_SC.malformed, "Recipient is either missing in the request, or is malformed", res);
+			return;
+		}
+
+		// if sender is given, we canonicalize the address
+		if (sender) {
+			sender = checkAndTransformAddress(sender);
+			if (!sender) {
+				return replyWithErr(ERR_SC.malformed, "Sender field is malformed", res);
+			}
+		}
+
+		// check invitation field
+		if ((invitation !== undefined) && (typeof invitation !== 'string')) {
+			return replyWithErr(ERR_SC.malformed, "Inviation field is malformed", res);
+		}
+
+		try {
+			if (redirectFunc) {
+				const redirectTo = await redirectFunc(recipient)
+				if (redirectTo) {
+					res.status(api.SC.redirect).json({
+						redirect: redirectTo
+					} as api.RedirectReply);
+				} else {
+					await serveRequestHere(recipient, sender, invitation, res);
+				}
+			} else {
+				await serveRequestHere(recipient, sender, invitation, res);
+			}
+		} catch (err) {
+			if (err === recipSC.USER_UNKNOWN) {
+				replyWithErr(api.SC.unknownRecipient, `Recipient ${recipient} is unknown.`, res);
+			} else {
+				next(err);
+			}
+		}
+
+	};
+}
+
+Object.freeze(exports);

package/ts-code/asmail/routes/retrieval/get-message-meta.ts

@@ -0,0 +1,50 @@
+/*
+ Copyright (C) 2015 - 2016, 2025 - 2026 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 { RequestHandler } from 'express';
+import { SC as recipSC, MsgRetrieval } from '../../resources/recipients';
+import { msgMetadata as api, ERR_SC } from '../../../lib-common/service-api/asmail/retrieval';
+import { Request } from '../../resources/sessions';
+import { replyWithErr } from '../../resources/utils';
+
+export function getMsgMeta(
+	getMsgMetaFunc: MsgRetrieval['getMsgMeta']
+): RequestHandler {
+	return async (req: Request, res, next) => {
+		const userId = req.session.params.userId;
+		const msgId: string = req.params.msgId;
+
+		try {
+			const meta = await getMsgMetaFunc(userId, msgId);
+			res.status(api.SC.ok).json(meta);
+		} catch (err) {
+			if ("string" !== typeof err) {
+				next(err);
+			} else if (err === recipSC.MSG_UNKNOWN) {
+				replyWithErr(api.SC.unknownMsg, "Message "+msgId+" is unknown.", res);
+			} else if (err === recipSC.USER_UNKNOWN) {
+				replyWithErr(ERR_SC.server, "Recipient disappeared from the system.", res);
+				req.session.close();
+			} else {
+				next(new Error("Unhandled storage error code: "+err));
+			}
+		}
+
+	};
+}
+
+Object.freeze(exports);

package/ts-code/asmail/routes/retrieval/get-message-obj.ts

@@ -0,0 +1,106 @@
+/*
+ Copyright (C) 2015 - 2017, 2025 - 2026 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 { RequestHandler } from 'express';
+import { SC as recipSC, MsgRetrieval, BIN_TYPE } from '../../resources/recipients';
+import { GetObjQueryOpts, ERR_SC, msgObj as api, HTTP_HEADER } from '../../../lib-common/service-api/asmail/retrieval';
+import { Request } from '../../resources/sessions';
+import { errWithCause } from '../../../lib-common/exceptions/error';
+import { EMPTY_BUFFER } from '../../../lib-common/buffer-utils';
+import { getObjIdFromParams, replyWithErr } from '../../resources/utils';
+
+function extractQueryOptions(req: Request): undefined|{
+	header: boolean; limit: number|undefined; ofs: number;
+} {
+	// query fields are string or undefined, yet, type info helps the show
+	const query: GetObjQueryOpts = req.query;
+
+	const header = ((query.header as any) === 'true');
+
+	const ofs = (query.ofs ? parseInt(query.ofs as any) : 0);
+	if (isNaN(ofs) || (ofs < 0) || (header && (ofs > 0))) {
+		return;
+	}
+
+	const limit = (query.limit ? parseInt(query.limit as any) : undefined);
+	if (limit !== undefined) {
+		if (isNaN(limit) || (limit < 0) || (!header && (limit === 0))) {
+			return;
+		}
+	}
+
+	return { header, limit, ofs };
+}
+
+export function getMsgObj(
+	getMsgObjFunc: MsgRetrieval['getObj']
+): RequestHandler {
+	return async (req: Request, res, next) => {
+
+		const userId = req.session.params.userId;
+		const msgId: string = req.params.msgId;
+
+		const { objId, objIdParseErr } = getObjIdFromParams(req);
+		if (objIdParseErr) {
+			return replyWithErr(ERR_SC.malformed, objIdParseErr, res);
+		}
+
+		const opts = extractQueryOptions(req);
+		if (!opts) {
+			return replyWithErr(ERR_SC.malformed, "Bad query parameters", res);
+		}
+
+		try{
+			const reader = await getMsgObjFunc(userId, msgId, objId, opts.header, opts.ofs, opts.limit);
+			res.status(api.SC.ok);
+			res.set(HTTP_HEADER.contentType, BIN_TYPE);
+			res.set(HTTP_HEADER.contentLength, `${reader.len}`);
+			if (opts.header) {
+				res.set(HTTP_HEADER.objHeaderLength, `${reader.headerLen}`);
+			}
+			res.set(HTTP_HEADER.objSegmentsLength, `${reader.segsLen}`);
+			if (reader.len > 0) {
+				try {
+					await reader.pipe!(res);
+				} catch (err) {
+					console.error(errWithCause(
+						err, `Wasn't able to complete sending segments due to error in piping`
+					));
+				} finally {
+					res.end();
+				}
+			} else {
+				res.send(EMPTY_BUFFER);
+			}
+		} catch (err) {
+			if ("string" !== typeof err) {
+				next(err);
+			} else if (err === recipSC.OBJ_UNKNOWN) {
+				replyWithErr(api.SC.unknownMsgOrObj, `Object ${objId} is unknown.`, res);
+			} else if (err === recipSC.MSG_UNKNOWN) {
+				replyWithErr(api.SC.unknownMsgOrObj, `Message ${msgId} is unknown.`, res);
+			} else if (err === recipSC.USER_UNKNOWN) {
+				replyWithErr(ERR_SC.server, `Recipient disappeared from the system.`, res);
+				req.session.close();
+			} else {
+				next(new Error(`Unhandled storage error code: ${err}`));
+			}
+		}
+	};
+}
+
+Object.freeze(exports);

package/ts-code/asmail/routes/retrieval/list-messages.ts

@@ -0,0 +1,68 @@
+/*
+ Copyright (C) 2015 - 2016, 2025 - 2026 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 { RequestHandler } from 'express';
+import { SC as recipSC, MsgRetrieval } from '../../resources/recipients';
+import { listMsgs as api, ERR_SC, ListMsgsOpts } from '../../../lib-common/service-api/asmail/retrieval';
+import { Request } from '../../resources/sessions';
+import { replyWithErr } from '../../resources/utils';
+
+export function listMsgIds(
+	listMsgIdsFunc: MsgRetrieval['getMsgIds']
+): RequestHandler {
+	return async (req: Request, res, next) => {
+		const userId = req.session.params.userId;
+
+		const opts = extractQueryOptions(req);
+		if (!opts) {
+			return replyWithErr(ERR_SC.malformed, "Bad query parameters", res);
+		}
+
+		try {
+			const { from, to } = opts;
+			const msgIds = await listMsgIdsFunc(userId, from, to);
+			res.status(api.SC.ok).json(msgIds);
+		} catch (err) {
+			if ("string" !== typeof err) {
+				next(err);
+			} else if (err === recipSC.USER_UNKNOWN) {
+				replyWithErr(ERR_SC.server, "Recipient disappeared from the system.", res);
+				req.session.close();
+			} else {
+				next(new Error("Unhandled storage error code: "+err));
+			}
+		}
+
+	};
+}
+
+function extractQueryOptions(req: Request): ListMsgsOpts|undefined {
+	const query: ListMsgsOpts = req.query;
+
+	const from = (query.from ? parseInt(query.from as any) : undefined);
+	if ((from !== undefined) && (isNaN(from) || (from <= 0))) {
+		return;
+	}
+	const to = (query.to ? parseInt(query.to as any) : undefined);
+	if ((to !== undefined) && (isNaN(to) || (to <= 0))) {
+		return;
+	}
+
+	return { from, to };
+}
+
+Object.freeze(exports);

package/ts-code/asmail/routes/retrieval/remove-message.ts

@@ -0,0 +1,48 @@
+/*
+ Copyright (C) 2015 - 2016, 2026 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 { RequestHandler } from 'express';
+import { SC as recipSC, MsgRetrieval } from '../../resources/recipients';
+import { rmMsg as api, ERR_SC } from '../../../lib-common/service-api/asmail/retrieval';
+import { Request } from '../../resources/sessions';
+import { replyWithErr } from '../../resources/utils';
+
+export function deleteMsg(delMsgFunc: MsgRetrieval['deleteMsg']): RequestHandler {
+	return async (req: Request, res, next) => {
+		const userId = req.session.params.userId;
+		const msgId: string = req.params.msgId;
+
+		try {
+			await delMsgFunc(userId, msgId);
+			res.status(api.SC.ok).send();
+		} catch (err) {
+			if ("string" !== typeof err) {
+				next(err);
+			} else if (err === recipSC.MSG_UNKNOWN) {
+				replyWithErr(api.SC.unknownMsg, "Message "+msgId+" is unknown.", res);
+			} else if (err === recipSC.USER_UNKNOWN) {
+				replyWithErr(ERR_SC.server, "Recipient disappeared from the system.", res);
+				req.session.close();
+			} else {
+				next(new Error("Unhandled storage error code: "+err));
+			}
+		}
+
+	};
+}
+
+Object.freeze(exports);

package/ts-code/cli/index.ts

@@ -0,0 +1,82 @@
+/*
+ Copyright (C) 2023, 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 { EXECUTABLE_NAME } from "../config/default-confs";
+import { ParsedRunArgs, parseRunArgs, runCmd } from "./run-cmd";
+import { sampleConfig, showSampleConfigCmd } from "./show-sample-config";
+import { ParsedSignupArgs, parseSignupArgs, signupCmd } from "./signup-cmd";
+import { CliUsageDisplay, HelpArg, UsageSection, helpOpt, parseArgv, toErrorUsage, toUsageDisplay } from "./utils";
+
+export { CliUsageDisplay } from "./utils";
+
+function mainUsage(execName: string): UsageSection[] {
+	return [
+		{
+			header: execName,
+			content: `Server of all 3NWeb utilities: MailerId, ASMail, 3NStorage.`
+		},
+		{
+			header: `Usage:`,
+			content: `${execName} [command]`
+		},
+		{
+			header: 'Available commands:',
+			content: [
+				runCmd,
+				signupCmd,
+				showSampleConfigCmd
+			]
+		},
+		{
+			header: '',
+			content: `Use "${execName} [command] --help" for more information about a command.`
+		}
+	];
+}
+
+export function parseProcessArgv(): {
+	runCmd?: ParsedRunArgs;
+	signupCmd?: ParsedSignupArgs;
+	showUsage?: CliUsageDisplay;
+	showSampleConfig?: CliUsageDisplay;
+} {
+	const args = process.argv.slice(2);
+	if (args.length === 0) {
+		return toUsageDisplay(0, mainUsage(EXECUTABLE_NAME));
+	}
+	if (args[0] === runCmd.name) {
+		return parseRunArgs(args.slice(1), EXECUTABLE_NAME);
+	} else if (args[0] === signupCmd.name) {
+		return parseSignupArgs(args.slice(1), EXECUTABLE_NAME);
+	} else if (args[0] === showSampleConfigCmd.name) {
+		return { showSampleConfig: {
+			txtToDisplay: sampleConfig, exitStatus: 0
+		}};
+	} else {
+		const opts = parseArgv<HelpArg>(args, [ helpOpt ], { partial: true });
+		if (opts.help) {
+			return toUsageDisplay(0, mainUsage(EXECUTABLE_NAME));
+		}
+		return toUsageDisplay(-1, toErrorUsage(
+			mainUsage(EXECUTABLE_NAME),
+			`Unknown command '${args[0]}'`
+		));
+	}
+}
+
+
+Object.freeze(exports);

package/ts-code/cli/run-cmd.ts

@@ -0,0 +1,81 @@
+/*
+ Copyright (C) 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 { CliUsageDisplay, CommandDef, OptionDef, UsageSection, helpOpt, parseArgv, toErrorUsage, toUsageDisplay } from "./utils";
+
+
+export const runCmd: CommandDef<'run'> = {
+	name: 'run',
+	summary: 'runs 3NWeb services'
+};
+
+function runUsage(execName: string): UsageSection[] {
+	return [
+		{
+			content: `This command runs some or all 3NWeb services. Configuration is read from a yaml file.`
+		},
+		{
+			header: 'Usage:',
+			content: `${execName} ${runCmd.name} [options] [config_file]`
+		},
+		{
+			header: 'Options:',
+			optionList: runOpts
+		}
+	];
+}
+
+const runOpts: OptionDef[] = [
+	{
+		name: 'config',
+		alias: 'c',
+		type: String,
+		typeLabel: '{underline <file>}',
+		description: `path of a configuration yaml file`
+	},
+	helpOpt
+];
+
+export interface ParsedRunArgs {
+	config?: string;
+	help?: boolean;
+}
+
+export function parseRunArgs(args: string[], execName: string): {
+	runCmd?: ParsedRunArgs;
+	showUsage?: CliUsageDisplay;
+} {
+	if (args.length === 0) {
+		return toUsageDisplay(0, runUsage(execName));
+	}
+	const runArgs = parseArgv<ParsedRunArgs>(args, runOpts, { partial: true });
+	if (runArgs.help) {
+		return toUsageDisplay(0, runUsage(execName));
+	} else if (runArgs.config) {
+		return { runCmd: runArgs };
+	} else if (runArgs._unknown) {
+		return { runCmd: { config: runArgs._unknown[0] } };
+	} else {
+		return toUsageDisplay(-1, toErrorUsage(
+			runUsage(execName),
+			`Missing configuration file path.`
+		));
+	}
+}
+
+
+Object.freeze(exports);