spec-3nweb-server 1.8.5 → 1.8.6

package/ts-code/lib-common/service-api/asmail/delivery.ts

@@ -0,0 +1,250 @@
+/*
+ Copyright (C) 2015, 2017, 2019 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/>.
+*/
+
+/**
+ * This defines interfaces for mail delivery requests.
+ */
+
+import * as jwk from '../../jwkeys';
+import * as config from './config';
+import { stringify as stringifyOpts } from 'querystring';
+
+export const HTTP_HEADER = {
+	contentType: 'Content-Type',
+	contentLength: 'Content-Length',
+}
+Object.freeze(HTTP_HEADER);
+
+export const ERR_SC = {
+	duplicateReq: 475,
+	earlyReq: 476,
+	malformed: 400,
+	needSession: 401,
+	server: 500,
+	contentTooLong: 413,
+	contentLenMissing: 411,
+	wrongContentType: 415,
+	objIncomplete: 479
+};
+Object.freeze(ERR_SC);
+
+export namespace preFlight {
+	
+	export const URL_END = 'pre-flight';
+	
+	export interface Request extends sessionStart.Request { }
+	
+	export interface Reply {
+		maxMsgLength: number;
+	}
+	
+	export interface RedirectReply {
+		redirect: string;
+	}
+	
+	export const SC = {
+		ok: 200,
+		unknownRecipient: 474,
+		senderNotAllowed: 403,
+		inboxFull: 480,
+		redirect: 373
+	};
+	Object.freeze(SC);
+	
+}
+Object.freeze(preFlight);
+
+export namespace sessionStart {
+	
+	export const URL_END = 'start-session';
+	
+	export interface Request {
+		sender?: string;
+		recipient: string;
+		invitation?: string;
+	}
+	
+	export interface Reply extends preFlight.Reply {
+		sessionId: string;
+	}
+	
+	export interface RedirectReply extends preFlight.RedirectReply {}
+	
+	export const SC = preFlight.SC;
+	
+}
+Object.freeze(sessionStart);
+
+export namespace sessionRestart {
+
+	export const URL_END = 'restart-session';
+
+	export interface Request {
+		recipient: string;
+		msgId: string;
+	}
+	
+	export interface Reply extends preFlight.Reply {
+		sessionId: string;
+		maxChunkSize? : number;
+	}
+
+	export interface RedirectReply extends preFlight.RedirectReply {}
+
+	export const SC = {
+		ok: 200,
+		unknownRecipient: 474,
+		unknownMsg: 473,
+		redirect: 373
+	};
+	Object.freeze(SC);
+
+}
+Object.freeze(sessionRestart);
+
+export namespace authSender {
+	
+	export const URL_END = 'authorize-sender';
+	
+	export interface Request {
+		assertion: jwk.SignedLoad;
+		userCert: jwk.SignedLoad;
+		provCert: jwk.SignedLoad;
+	}
+	
+	export const SC = {
+		ok: 200,
+		authFailed: 403
+	};
+	Object.freeze(SC);
+	
+}
+Object.freeze(authSender);
+
+export namespace initPubKey {
+	
+	export const URL_END = 'init-pub-key';
+	
+	export interface Reply extends config.p.initPubKey.Certs {}
+	
+	export const SC = {
+		ok: 200,
+		pkeyNotRegistered: 474
+	};
+	Object.freeze(SC);
+	
+}
+Object.freeze(initPubKey);
+
+export namespace msgMeta {
+	
+	export const URL_END = 'msg/meta';
+	
+	export interface CryptoInfo {
+		pid?: string;
+		recipientKid?: string;
+		senderPKey?: string;
+	}
+	
+	export interface Request extends CryptoInfo {
+		objIds: string[];
+	}
+	
+	export interface Reply {
+		msgId: string;
+		maxChunkSize? : number;
+	}
+	
+	export const SC = {
+		ok: 201
+	};
+	
+}
+Object.freeze(msgMeta);
+
+export interface PutObjFirstQueryOpts {
+
+	/**
+	 * This is a length of header, when it is sent in a request.
+	 * Header must be sent with the first request, located in http body start.
+	 */
+	header: number;
+
+	/**
+	 * This is a boolean flag, which true value indicates that this is the last
+	 * request in sending the object.
+	 */
+	last?: boolean;
+
+}
+
+export interface PutObjSecondQueryOpts {
+
+	/**
+	 * This is an offset into segments.
+	 */
+	ofs: number;
+
+	/**
+	 * This is a boolean flag, which true value indicates that this is the last
+	 * request in sending the object.
+	 */
+	last?: boolean;
+
+}
+
+export namespace msgObj {
+	
+	export const EXPRESS_URL_END = 'msg/obj/:objId';
+	
+	export function firstPutReqUrlEnd(objId: string,
+			opts: PutObjFirstQueryOpts): string {
+		return `msg/obj/${objId}?${stringifyOpts(opts as any)}`;
+	}
+	
+	export function secondPutReqUrlEnd(objId: string,
+			opts: PutObjSecondQueryOpts): string {
+		return `msg/obj/${objId}?${stringifyOpts(opts as any)}`;
+	}
+	
+	export const SC = {
+		ok: 201,
+		objAlreadyExists: 473,
+		unknownObj: 474
+	};
+	Object.freeze(SC);
+	
+}
+Object.freeze(msgObj);
+
+export namespace completion {
+	
+	export const URL_END = 'msg-complete';
+	
+	export const SC = {
+		ok: 200,
+	};
+	Object.freeze(SC);
+	
+}
+Object.freeze(completion);
+
+export interface ErrorReply {
+	error: string;
+}
+
+Object.freeze(exports);

package/ts-code/lib-common/service-api/asmail/retrieval.ts

@@ -0,0 +1,238 @@
+/*
+ Copyright (C) 2015, 2017, 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/>. */
+
+/**
+ * This defines interfaces for mail retrieval requests.
+ */
+
+import * as midApi from '../mailer-id/login';
+import * as deliveryApi from './delivery';
+import { stringify as stringifyOpts } from 'querystring';
+
+export const BIN_TYPE = 'application/octet-stream';
+
+export const HTTP_HEADER = {
+	contentType: 'Content-Type',
+	contentLength: 'Content-Length',
+	objHeaderLength: 'X-Obj-Header-Length',
+	objSegmentsLength: 'X-Obj-Segments-Length',
+}
+Object.freeze(HTTP_HEADER);
+export const ERR_SC = {
+	malformed: 400,
+	needAuth: midApi.ERR_SC.needAuth,
+	server: 500
+};
+Object.freeze(ERR_SC);
+
+export namespace midLogin {
+
+	export const MID_URL_PART = 'login/mailerid/';
+	export const START_URL_END = MID_URL_PART + midApi.startSession.URL_END;
+	export const AUTH_URL_END = MID_URL_PART + midApi.authSession.URL_END;
+
+}
+Object.freeze(midLogin);
+
+export namespace closeSession {
+
+	export const URL_END = 'close-session';
+
+}
+Object.freeze(closeSession);
+
+export interface ListMsgsOpts {
+	from?: number;
+	to?: number;
+}
+
+export namespace listMsgs {
+
+	export const EXPRESS_URL_END = 'msg/ids';
+
+	export function genUrlEnd(opts?: ListMsgsOpts): string {
+		let optStr = (opts ? '?'+stringifyOpts(opts as any) : '');
+		return `msg/ids${optStr}`;
+	}
+
+	export interface Reply extends Array<string> {}
+
+	export const SC = {
+		ok: 200,
+	};
+	Object.freeze(SC);
+
+}
+Object.freeze(listMsgs);
+
+export namespace rmMsg {
+
+	export const EXPRESS_URL_END = 'msg/:msgId';
+
+	export function genUrlEnd(msgId: string): string {
+		return 'msg/'+msgId;
+	}
+
+	export const SC = {
+		ok: 200,
+		unknownMsg: 474
+	};
+	Object.freeze(SC);
+
+}
+Object.freeze(rmMsg);
+
+export interface ObjSize {
+	header: number;
+	segments: number|undefined;
+}
+
+export interface ObjStatus {
+	completed?: boolean;
+	size: ObjSize;
+}
+
+export interface MsgMeta  {
+	recipient: string;
+	extMeta: deliveryApi.msgMeta.Request;
+	deliveryStart: number;
+	authSender: string|undefined;
+	invite: string|undefined;
+	maxMsgLength: number;
+	deliveryCompletion?: number;
+	objs: { [objId: string]: ObjStatus; };
+}
+
+export namespace msgMetadata {
+
+	export const EXPRESS_URL_END = 'msg/:msgId/meta';
+
+	export function genUrlEnd(msgId: string): string {
+		return 'msg/'+msgId+'/meta';
+	}
+
+	export interface Reply extends MsgMeta {}
+
+	export const SC = {
+		ok: 200,
+		unknownMsg: 474
+	};
+	Object.freeze(SC);
+
+}
+Object.freeze(msgMetadata);
+
+/**
+ * This function returns either a checked version of given meta object, if it
+ * passes as message meta, or undefined, otherwise.
+ * @param meta is an object that is expected to be message meta
+ */
+export function sanitizedMeta(meta: MsgMeta): MsgMeta|undefined {
+	if (typeof meta !== 'object') { return; }
+	if (typeof meta.objs !== 'object') { return; }
+	for (const objId of Object.keys(meta.objs)) {
+		const st = meta.objs[objId];
+		if (typeof st.size.header !== 'number') { return; }
+		if (st.completed &&
+				(st.size.segments === undefined)) { return; }
+	}
+	// TODO add more checks and return new object instead of a given one
+	return meta;
+}
+
+export interface GetObjQueryOpts {
+	/**
+	 * This is a boolean flag, which true value indicates that header should be
+	 * present in a response. If it is false, or is not present, header is not
+	 * included in a reply.
+	 */
+	header?: boolean;
+
+	/**
+	 * This is an offset into segments. If it is not present, zero is assumed.
+	 * This field must be zero or missing, when header is true.
+	 */
+	ofs?: number;
+
+	/**
+	 * This is a limit on number of segment bytes to be returned.
+	 */
+	limit?: number;
+}
+
+export namespace msgObj {
+
+	export const EXPRESS_URL_END = 'msg/:msgId/obj/:objId';
+
+	export function genUrlEnd(msgId: string, objId: string,
+			opts?: GetObjQueryOpts): string {
+		let optStr = (opts ? '?'+stringifyOpts(opts as any) : '');
+		return `msg/${msgId}/obj/${objId}${optStr}`;
+	}
+
+	export const SC = {
+		ok: 200,
+		unknownMsgOrObj: 474
+	};
+	Object.freeze(SC);
+
+}
+Object.freeze(msgObj);
+
+export interface ErrorReply {
+	error: string;
+}
+
+export namespace wsEventChannel {
+
+	export const URL_END = 'events';
+
+	export const SC = {
+		ok: 200,
+	};
+	Object.freeze(SC);
+
+}
+Object.freeze(wsEventChannel);
+
+export namespace msgRecievedCompletely {
+
+	export const EVENT_NAME = 'msg-received-completely';
+
+	export interface Event {
+		msgId: string;
+	}
+
+}
+Object.freeze(msgRecievedCompletely);
+
+// XXX this event should be triggered by big messages with more than one obj
+export namespace msgMainObjRecieved {
+
+	export const EVENT_NAME = 'msg-main-obj-received';
+
+	export interface Event {
+		msgId: string;
+	}
+
+}
+Object.freeze(msgMainObjRecieved);
+
+// XXX add event about message removal
+//   it is useful in multi-device case, pass implicit implicit signal that will
+//   have context-specific meaning.
+	
+Object.freeze(exports);

package/ts-code/lib-common/service-api/asmail/root-route.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 interface ASMailRootRoute {
+	delivery?: string;
+	retrieval?: string;
+	config?: string;
+}

package/ts-code/lib-common/service-api/ipc-api.ts

@@ -0,0 +1,44 @@
+/*
+ Copyright (C) 2016 - 2017 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 type Envelope = web3n.ipc.Envelope;
+export type EventEnvelope<T> = web3n.ipc.EventEnvelope<T>;
+export type EventEndEnvelope = web3n.ipc.EventEndEnvelope;
+export type EventException = web3n.ipc.EventException;
+export type RequestEnvelope<T> = web3n.ipc.RequestEnvelope<T>;
+export type ReplyEnvelope<T> = web3n.ipc.ReplyEnvelope<T>;
+
+export namespace events {
+
+	export namespace subscribe {
+
+		export const REQ_NAME = 'subscribe';
+
+	}
+	Object.freeze(subscribe);
+
+	export namespace unsubscribe {
+
+		export const REQ_NAME = 'unsubscribe';
+
+	}
+	Object.freeze(unsubscribe);
+
+}
+Object.freeze(events);
+
+Object.freeze(exports);

package/ts-code/lib-common/service-api/locker.ts

@@ -0,0 +1,44 @@
+/*
+ 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/>.
+*/
+
+
+export namespace createLocker {
+
+	export const URL_END = 'create';
+
+	export const method = 'PUT';
+
+	export interface Request {
+		token?: string;
+	}
+	
+	export interface Reply {
+		userId: string;
+		storageUri: string;
+		storageMBs: number;
+		willBeRemovedAt: number;
+	}
+
+	export const SC = {
+		ok: 200,
+		invalidToken: 403
+	};
+	Object.freeze(SC);
+
+};
+Object.freeze(createLocker);
+

package/ts-code/lib-common/service-api/mailer-id/login.ts

@@ -0,0 +1,80 @@
+/*
+ Copyright (C) 2015 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/>.
+*/
+
+/**
+ * This defines request interfaces for mailerId-based login.
+ */
+
+import * as jwk from '../../jwkeys';
+
+export const ERR_SC = {
+	duplicate: 475,
+	malformed: 400,
+	needAuth: 401
+};
+Object.freeze(ERR_SC);
+
+export namespace startSession {
+	
+	export const URL_END = 'start-session';
+
+	export interface Request {
+		userId: string;
+	}
+
+	export interface Reply {
+		sessionId: string;
+	}
+
+	export interface RedirectReply {
+		redirect: string;
+	}
+
+	export const SC = {
+		unknownUser: 474,
+		redirect: 373,
+		ok: 200
+	};
+	Object.freeze(SC);
+
+}
+Object.freeze(startSession);
+
+export namespace authSession {
+	
+	export const URL_END = 'authorize-session';
+
+	export interface Request {
+		assertion: jwk.SignedLoad;
+		userCert: jwk.SignedLoad;
+		provCert: jwk.SignedLoad;
+	}
+
+	export const SC = {
+		authFailed: 403,
+		ok: 200
+	};
+	Object.freeze(SC);
+
+}
+Object.freeze(authSession);
+
+export interface ErrorReply {
+	error: string;
+}
+
+Object.freeze(exports);