spec-3nweb-server 1.8.4 → 1.8.6

package/ts-code/cli/show-sample-config.ts

@@ -0,0 +1,78 @@
+/*
+ Copyright (C) 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 { CommandDef } from "./utils";
+
+
+export const showSampleConfigCmd: CommandDef<'show-sample-config'> = {
+	name: 'show-sample-config',
+	summary: 'prints out a template configuration yaml file with comments'
+};
+
+export const sampleConfig = `
+# This is a sample configuration yaml file.
+# Uncomment and set required values.
+# Default path of this file is /etc/3nweb/conf.yaml
+
+# Uncomment to enable service
+enabledServices:
+  # asmail: true
+  # storage: true
+  # mailerId: true
+
+# Data root folder. Set non-default value, if required.
+# rootFolder: /var/3nweb
+
+# Customize domain at which clients reach this server from an outside.
+# This value is used by users' MailerId-based login: assertion challenges
+# cryptographically imprint this domain to assure client that there is no
+# missuse.
+domain: service-for.example.com
+
+# If MailerId provider service is enabled, this is its configuration
+mailerId:
+  certs: /etc/3nweb/mailerid/certs
+
+# Customize servicesConnect before starting this server.
+servicesConnect:
+
+  port: 7070
+  # Hostname allows to restrict on which address service is listening for incoming connections
+  # hostname: "1.2.3.4"
+
+  # Uncomment path to Let's Encrypt folder, if it is used. This implicitly tells
+  # server to HTTPS with given certificates.
+  # letsencrypt: /etc/letsencrypt/live/service-for.example.com
+
+  # By default HTTPS service reloads when certificates change. Skip, if required.
+  # skipReloadOnCertsChange: false
+
+  # Set TLS cert and key to do HTTPS. Use either this, or letsencrypt, but not both.
+  # sslOpts: {
+  #   It is Node's https.ServerOptions. Follow https://nodejs.org/docs/latest/api/https.html
+  # }
+
+# Configuration for signup service that creates new accounts on this server.
+# Comment out to disable signup service completely.
+# Note that signup cli commands should be used to create token, without which
+# signup doesn't happen, unless a no-token configuration file is provided.
+signup: {
+  # noTokenFile: /some/path/to/json
+}
+`;
+
+Object.freeze(exports);

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

@@ -0,0 +1,229 @@
+/*
+ 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, HelpArg, OptionDef, UsageSection, helpOpt, parseArgv, toErrorUsage, toUsageDisplay } from "./utils";
+
+export const signupCmd: CommandDef<'signup'> = {
+	name: 'signup',
+	summary: 'controls adding new users to this instance'
+};
+
+function signupUsage(execName: string): UsageSection[] {
+	return [
+		{
+			content: `This command controls parameters of adding new users to this instance.`
+		},
+		{
+			header: 'Usage:',
+			content: `${execName} ${signupCmd.name} [command] [options] [config_file]`
+		},
+		{
+			header: 'Available commands:',
+			content: [
+				infoCmd,
+				listTokensCmd,
+				showTokenCmd,
+				createTokenCmd
+			]
+		},
+		{
+			header: `${infoCmd.name} options:`,
+			optionList: infoOpts
+		},
+		{
+			header: `${listTokensCmd.name} options:`,
+			optionList: listTokensOpts
+		},
+		{
+			header: `${showTokenCmd.name} options:`,
+			optionList: showTokenOpts
+		},
+		{
+			header: `${createTokenCmd.name} options:`,
+			optionList: createTokenOpts
+		}
+	];
+}
+
+const configOpt: OptionDef = {
+	name: 'config',
+	alias: 'c',
+	type: String,
+	typeLabel: '{underline <file>}',
+	description: `path of a configuration yaml file`
+};
+
+const infoCmd: CommandDef<'info'> = {
+	name: 'info',
+	summary: 'shows state of signup subsystem'
+};
+
+const infoOpts: OptionDef[] = [
+	configOpt
+];
+
+const listTokensCmd: CommandDef<'list-tokens'> = {
+	name: 'list-tokens',
+	summary: 'lists signup tokens'
+};
+
+const listTokensOpts: OptionDef[] = [
+	configOpt
+];
+
+const showTokenCmd: CommandDef<'show-token'> = {
+	name: 'show-token',
+	summary: 'shows signup token with complete value'
+};
+
+const showTokenOpts: OptionDef[] = [
+	configOpt,
+	{
+		name: 'token',
+		alias: 't',
+		type: String,
+		typeLabel: '{underline <token_id>}',
+		description: `token id`
+	}
+];
+
+const createTokenCmd: CommandDef<'create-token'> = {
+	name: 'create-token',
+	summary: 'creates signup token for single user, when user id is given, and for many users, when domain(s) are given'
+};
+
+const createTokenOpts: OptionDef[] = [
+	configOpt,
+	{
+		name: 'domain',
+		alias: 'd',
+		type: String,
+		typeLabel: '{underline <domain>}',
+		multiple: true,
+		description: `domain for new users. Several domain options will attach all domains to same token.`
+	},
+	{
+		name: 'user',
+		alias: 'u',
+		type: String,
+		typeLabel: '{underline <user_address>}',
+		description: `address of a single user`
+	}
+];
+
+export interface ParsedSignupArgs {
+	info?: boolean;
+	config?: string;
+	help?: boolean;
+	listTokens?: boolean;
+	showToken?: boolean;
+	token?: string;
+	createToken?: boolean;
+	domain?: string[];
+	user?: string;
+}
+
+function parseWithConfFile(
+	args: string[], optList: OptionDef[]
+): ParsedSignupArgs|undefined {
+	const opts = parseArgv<ParsedSignupArgs>(args, optList, { partial: true });
+	if (opts.config) {
+		return opts;
+	} else if (opts._unknown) {
+		opts.config = opts._unknown[0];
+		return opts;
+	} else {
+		return;
+	}
+}
+
+function cmdUsageErr(
+	execName: string, cmd: string, errTxt = `missing configuration file`
+): {
+	showUsage: CliUsageDisplay;
+} {
+	return toUsageDisplay(-1, toErrorUsage(
+		signupUsage(execName),
+		`Incorrect options for command '${signupCmd.name} ${cmd}': ${errTxt}`
+	));
+}
+
+export function parseSignupArgs(
+	args: string[], execName: string
+): {
+	signupCmd?: ParsedSignupArgs;
+	showUsage?: CliUsageDisplay;
+} {
+	if (args.length === 0) {
+		return toUsageDisplay(0, signupUsage(execName));
+	}
+	if (args[0] === infoCmd.name) {
+		const signupCmd = parseWithConfFile(args.slice(1), infoOpts);
+		if (signupCmd) {
+			signupCmd.info = true;
+			return { signupCmd };
+		} else {
+			return cmdUsageErr(execName, infoCmd.name);
+		}
+	} else if (args[0] === listTokensCmd.name) {
+		const signupCmd = parseWithConfFile(args.slice(1), listTokensOpts);
+		if (signupCmd) {
+			signupCmd.listTokens = true;
+			return { signupCmd };
+		} else {
+			return cmdUsageErr(execName, listTokensCmd.name);
+		}
+	} else if (args[0] === showTokenCmd.name) {
+		const signupCmd = parseWithConfFile(args.slice(1), showTokenOpts);
+		if (signupCmd) {
+			if (!signupCmd.token) {
+				return cmdUsageErr(
+					execName, showTokenCmd.name, `missing token`
+				);
+			}
+			signupCmd.showToken = true;
+			return { signupCmd };
+		} else {
+			return cmdUsageErr(execName, showTokenCmd.name);
+		}
+	} else if (args[0] === createTokenCmd.name) {
+		const signupCmd = parseWithConfFile(args.slice(1), createTokenOpts);
+		if (signupCmd) {
+			if (!signupCmd.domain && !signupCmd.user) {
+				return cmdUsageErr(
+					execName, createTokenCmd.name, `either user address, or domain(s) should be given`
+				);
+			}
+			signupCmd.createToken = true;
+			return { signupCmd };
+		} else {
+			return cmdUsageErr(execName, createTokenCmd.name);
+		}
+	} else {
+		const opts = parseArgv<HelpArg>(args, [ helpOpt ], { partial: true });
+		if (opts.help) {
+			return toUsageDisplay(0, signupUsage(execName));
+		}
+		return toUsageDisplay(-1, toErrorUsage(
+			signupUsage(execName),
+			`Unknown command '${args[0]}'`
+		));
+	}
+}
+
+
+Object.freeze(exports);

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

@@ -0,0 +1,68 @@
+/*
+ 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, UsageSection, toUsageDisplay } from "./utils";
+
+export const userCmd: CommandDef<'user'> = {
+	name: 'user',
+	summary: 'provides information about existing users'
+};
+
+const listCmd: CommandDef<'list'> = {
+	name: 'list',
+	summary: `lists users`
+}
+
+export interface ParsedUserArgs {
+	listAll?: true;
+}
+
+function userUsage(execName: string): UsageSection[] {
+	return [
+		{
+			header: execName,
+			content: `Server of all 3NWeb utilities: MailerId, ASMail, 3NStorage.`
+		},
+		{
+			header: `Usage:`,
+			content: `${execName} user [command]`
+		},
+		{
+			header: 'Available commands:',
+			content: []
+		},
+		{
+			content: `Use "${execName} user [command] --help" for more information about a command.`
+		}
+	];
+}
+
+export function parseSignupArgs(
+	args: string[], execName: string
+): {
+	userCmd?: ParsedUserArgs;
+	showUsage?: CliUsageDisplay;
+} {
+	if (args.length === 0) {
+		return toUsageDisplay(0, userUsage(execName));
+	}
+
+	// XXX
+
+
+	return {};
+}

package/ts-code/cli/utils.ts

@@ -0,0 +1,105 @@
+/*
+ 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 * as commandLineArgs from "command-line-args";
+import * as commandLineUsage from "command-line-usage";
+
+export interface CommandDef<T extends string> {
+	name: T;
+	summary: string;
+}
+
+export interface OptionDef {
+	name: string;
+	type: (typeof Boolean) | (typeof String) | (typeof Number) |
+	((value: string) => any);
+	alias?: string;
+	description?: string;
+	typeLabel?: string;
+	multiple?: boolean;
+	defaultOption?: boolean;
+}
+
+export interface UsageSection {
+	header?: string;
+	summary?: string;
+	optionList?: OptionDef[];
+	content?: string | UsageSectionContent | (string | UsageSection)[];
+}
+
+export interface UsageSectionContent {
+	options: any;
+	data: any
+}
+
+export interface ParseOptions {
+	argv?: string[];
+	partial?: boolean;
+	stopAtFirstUnknown?: boolean;
+	camelCase?: boolean;
+	caseInsensitive?: boolean;
+}
+
+export interface CliUsageDisplay {
+	txtToDisplay: string;
+	exitStatus: number;
+}
+
+export const helpOpt: OptionDef = {
+	name: 'help',
+	alias: 'h',
+	type: Boolean,
+	description: 'shows help'
+};
+
+export interface HelpArg {
+	help?: boolean;
+}
+
+export function toUsageDisplay(
+	exitStatus: number, usage: UsageSection[]
+): {
+	showUsage: CliUsageDisplay;
+} {
+	return {
+		showUsage: {
+			txtToDisplay: commandLineUsage(usage),
+			exitStatus
+		}
+	};
+}
+
+export function parseArgv<T>(
+	argv: string[], argOpts: OptionDef[], opts?: ParseOptions
+): T & { _unknown?: string[]; } {
+	if (opts) {
+		opts.argv = argv;
+	} else {
+		opts = { argv };
+	}
+	return commandLineArgs(argOpts, opts);
+}
+
+export function toErrorUsage(
+	usage: UsageSection[], errTxt: string
+): UsageSection[] {
+	usage[0] = { content: errTxt };
+	return usage;
+}
+
+
+Object.freeze(exports);

package/ts-code/config/default-confs.ts

@@ -0,0 +1,22 @@
+/*
+ Copyright (C) 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/>.
+*/
+
+export const EXECUTABLE_NAME = '3nweb';
+
+export const DEFAULT_DATA_ROOT_PATH = '/var/3nweb';
+
+export const DEFAULT_CONFIG_PATH = `/etc/3nweb/conf.yaml`;

package/ts-code/config/from-yaml.ts

@@ -0,0 +1,35 @@
+/*
+ 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 { readFileSync } from 'fs';
+import * as yaml from 'js-yaml';
+import { Configurations } from '../services';
+import { DEFAULT_DATA_ROOT_PATH } from './default-confs';
+
+export function readYamlConfFile(path: string): Configurations {
+	const txt = readFileSync(path, 'utf8');
+	const conf = yaml.load(txt) as Configurations;
+
+	if (conf.rootFolder) {
+		conf.rootFolder = DEFAULT_DATA_ROOT_PATH;
+	}
+
+	return conf;
+}
+
+
+Object.freeze(exports);

package/ts-code/config/letsencrypt.ts

@@ -0,0 +1,77 @@
+/*
+ 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 { readFileSync } from "fs";
+import { ServerOptions } from "https";
+import { join } from "path";
+
+export type CertsUpdateListener = (
+	newOpts: ServerOptions, originalOpts: ServerOptions
+) => Promise<void>;
+
+const LETSENCRYPT_CERT_FILE = 'fullchain.pem';
+const LETSENCRYPT_KEY_FILE = 'privkey.pem';
+
+export function sslOptsFromConfig(
+	letsencrypt: string|undefined, sslOpts: ServerOptions|undefined,
+	skipReloadOnCertsChange: boolean|undefined
+): {
+	sslOpts: ServerOptions;
+	onCertsUpdate?: (listener: CertsUpdateListener) => (() => void);
+}|undefined {
+	if (!sslOpts) {
+		sslOpts = {};
+	}
+	if (letsencrypt) {
+		sslOpts.cert = readFileSync(join(letsencrypt, LETSENCRYPT_CERT_FILE));
+		sslOpts.key = readFileSync(join(letsencrypt, LETSENCRYPT_KEY_FILE));
+		if (skipReloadOnCertsChange) {
+			return { sslOpts };
+		}
+		const onCertsUpdate = makeCertsUpdatesWatch();
+		return { sslOpts, onCertsUpdate };
+	} else if (sslOpts.cert && sslOpts.key) {
+		sslOpts.cert = readFileSync(sslOpts.cert as string);
+		sslOpts.key = readFileSync(sslOpts.key as string);
+		if (skipReloadOnCertsChange) {
+			return { sslOpts };
+		}
+		const onCertsUpdate = makeCertsUpdatesWatch();
+		return { sslOpts, onCertsUpdate };
+	} else if ((!sslOpts.cert && sslOpts.key)
+	|| (sslOpts.cert && !sslOpts.key)) {
+		throw new Error(`servicesConnect.sslOpts section must have both key and cert fields pointing to respective files.`);
+	} else {
+		return;
+	}
+}
+
+function makeCertsUpdatesWatch(
+	// XXX pass locations, or some fs watching object
+): (listener: CertsUpdateListener) => (() => void) {
+	return listener => {
+
+		// XXX start watching a signal
+
+		const stopWatching = () => {};
+		return stopWatching;
+	}
+}
+
+
+
+Object.freeze(exports);