core-3nweb-client-lib 0.49.6 → 0.49.8

package/build/core/keyring/peer-keys/dataset/v1/json-files.d.ts

@@ -0,0 +1,105 @@
+import type { JWKeyPair } from '../../../common';
+import type { RecipientKeyPairDbEntry, SendingKeyPairDbEntry } from '../v2/peer-keys-db';
+type JsonKey = web3n.keys.JsonKey;
+type JsonKeyShort = web3n.keys.JsonKeyShort;
+type WritableFS = web3n.files.WritableFS;
+export interface ReceptionPair {
+    pids: string[];
+    recipientKey: JWKeyPair;
+    isSenderIntroKey?: boolean;
+    senderPKey: JsonKeyShort;
+    msgMasterKey: string;
+    receivedMsgs?: {
+        counts: number[][];
+        lastTS: number;
+    };
+    timestamp: number;
+}
+/**
+ * Introductory pair appears when the first message is sent to a new
+ * correspondent. By nature it is an introductory message that uses recipient's
+ * published introductory key. Hence, recipient's key material in this pair
+ * comes from recipient's publishing.
+ *
+ * Structurally, introductory pair is just a sending pair with an addition of
+ * a flag that allows to distinguish it from ratcheted pair with a clean
+ * if-statement.
+ */
+export interface IntroductorySendingPair {
+    type: 'intro';
+    /**
+     * This is recipients' public key, to which encryption is done.
+     * If this is an introductory pair, this key is recipient's published intro
+     * public key.
+     * Else, if this is an ratcheted pair, this key comes from crypto material
+     * that recipients suggests from time to time for further use.
+     */
+    recipientPKey: JsonKey;
+}
+/**
+ * Ratcheted sending pair is a sending pair with pair ids (pids), attached to
+ * it. These ids are used to identify correct key material.
+ */
+export interface RatchetedSendingPair {
+    type: 'ratcheted';
+    pids: string[];
+    timestamp: number;
+    /**
+     * This is sender's secret-public key pair, to which encryption is done.
+     * This sending side always generates this key.
+     * Key material of an introductory key is used right away.
+     * Key material of a ratcheted pair is first suggested to the other side,
+     * and is moved to the sending pair when it is used by the other side.
+     */
+    senderKey: JWKeyPair;
+    /**
+     * This is recipients' public key, to which encryption is done.
+     * If this is an introductory pair, this key is recipient's published intro
+     * public key.
+     * Else, if this is an ratcheted pair, this key comes from crypto material
+     * that recipients suggests from time to time for further use.
+     */
+    recipientPKey: JsonKeyShort;
+    /**
+     * This is a precomputed message master key that comes from a given pair.
+     * This exist only as a speedup measure, to save time of public key crypto
+     * calculation by using a bit of extra space.
+     */
+    msgMasterKey: string;
+    sentMsgs?: {
+        count: number;
+        lastTS: number;
+    };
+}
+export type SendingPair = IntroductorySendingPair | RatchetedSendingPair;
+export interface V1PeerKeysJSON {
+    /**
+     * This is correspondent's address.
+     */
+    correspondent: string;
+    /**
+     * Sending pair is used for sending messages to this recipient.
+     * It is set from suggestions that correspondent sends in her messages.
+     * When initiating an exchange, while this pair has not been set, it is
+     * generated, which is indicated by the flag.
+     */
+    sendingPair: SendingPair | null;
+    /**
+     * Reception key pairs are pairs which we suggest to this correspondent
+     * for sending messages to us.
+     * Suggested pair is the one that we have already suggested, or are
+     * suggesting now.
+     * When correspondent uses suggested pair, we move it to inUse, while
+     * previous inUse pair is moved to old.
+     */
+    receptionPairs: {
+        suggested: ReceptionPair | null;
+        inUse: ReceptionPair | null;
+        old: ReceptionPair | null;
+    };
+}
+export declare function checkIfV1AndReadPeerKeys(krFS: WritableFS): Promise<V1PeerKeysJSON[] | undefined>;
+export declare function removeV1FolderIn(krFS: WritableFS): Promise<void>;
+export declare function v1ReceptionPairToV2RecipientKeyPairDbEntry(pairV1: ReceptionPair, ratchetStage: RecipientKeyPairDbEntry['ratchetStage'], peerCAddr: string): RecipientKeyPairDbEntry;
+export declare function v1RatchetedSendingPairToV2SendingKeyPairDbEntry(pairV1: RatchetedSendingPair, peerCAddr: string): SendingKeyPairDbEntry;
+export {};

package/build/core/keyring/peer-keys/dataset/v1/json-files.js

@@ -0,0 +1,89 @@
+"use strict";
+/*
+ Copyright (C) 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/>.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkIfV1AndReadPeerKeys = checkIfV1AndReadPeerKeys;
+exports.removeV1FolderIn = removeV1FolderIn;
+exports.v1ReceptionPairToV2RecipientKeyPairDbEntry = v1ReceptionPairToV2RecipientKeyPairDbEntry;
+exports.v1RatchetedSendingPairToV2SendingKeyPairDbEntry = v1RatchetedSendingPairToV2SendingKeyPairDbEntry;
+const buffer_utils_1 = require("../../../../../lib-common/buffer-utils");
+const ecma_nacl_1 = require("ecma-nacl");
+const VERSION_1_FOLDER_NAME = 'v1';
+const KEYRING_FNAME = 'keyring.json';
+async function checkIfV1AndReadPeerKeys(krFS) {
+    if (!(await krFS.checkFolderPresence(VERSION_1_FOLDER_NAME))) {
+        return;
+    }
+    const peerKeys = [];
+    const ringJSON = await krFS.readJSONFile(`${VERSION_1_FOLDER_NAME}/${KEYRING_FNAME}`)
+        .catch(noop);
+    if (ringJSON) {
+        for (const peerKeysStr of ringJSON.corrKeys) {
+            try {
+                peerKeys.push(JSON.parse(peerKeysStr));
+            }
+            catch (_err) { }
+        }
+    }
+    return peerKeys;
+}
+async function removeV1FolderIn(krFS) {
+    await krFS.deleteFolder(VERSION_1_FOLDER_NAME, true).catch(noop);
+}
+function noop() { }
+function v1ReceptionPairToV2RecipientKeyPairDbEntry(pairV1, ratchetStage, peerCAddr) {
+    const { pids, msgMasterKey, recipientKey, senderPKey, timestamp, isSenderIntroKey, receivedMsgs } = pairV1;
+    return {
+        ratchetStage,
+        pids,
+        msgMasterKey: buffer_utils_1.base64.open(msgMasterKey),
+        // at version 1 we only had NaCl' box shared key here
+        msgMasterKeyAlg: ecma_nacl_1.secret_box.JWK_ALG_NAME,
+        pairAlg: recipientKey.pkey.alg,
+        pairTS: timestamp,
+        peerCAddr,
+        peerKId: senderPKey.kid,
+        peerPKey: buffer_utils_1.base64.open(senderPKey.k),
+        isPeerIntroKey: !!isSenderIntroKey,
+        recipientKId: recipientKey.pkey.kid,
+        recipientPKey: recipientKey.pkey.k,
+        recipientSKey: buffer_utils_1.base64.open(recipientKey.skey.k),
+        receivedMsgLastTS: receivedMsgs === null || receivedMsgs === void 0 ? void 0 : receivedMsgs.lastTS,
+        receivedMsgsCounts: receivedMsgs === null || receivedMsgs === void 0 ? void 0 : receivedMsgs.counts
+    };
+}
+function v1RatchetedSendingPairToV2SendingKeyPairDbEntry(pairV1, peerCAddr) {
+    var _a, _b;
+    const { pids, msgMasterKey, recipientPKey, senderKey, timestamp, sentMsgs, type } = pairV1;
+    return {
+        pids,
+        msgMasterKey: buffer_utils_1.base64.open(msgMasterKey),
+        // at version 1 we only had NaCl' box shared key here
+        msgMasterKeyAlg: ecma_nacl_1.secret_box.JWK_ALG_NAME,
+        pairAlg: senderKey.pkey.alg,
+        pairTS: timestamp,
+        peerCAddr,
+        peerKId: recipientPKey.kid,
+        peerPKey: buffer_utils_1.base64.open(recipientPKey.k),
+        senderKId: senderKey.pkey.kid,
+        senderPKey: senderKey.pkey.k,
+        senderSKey: buffer_utils_1.base64.open(senderKey.skey.k),
+        sentMsgLastTS: (_a = sentMsgs === null || sentMsgs === void 0 ? void 0 : sentMsgs.lastTS) !== null && _a !== void 0 ? _a : 0,
+        sentMsgsCount: (_b = sentMsgs === null || sentMsgs === void 0 ? void 0 : sentMsgs.count) !== null && _b !== void 0 ? _b : 0
+    };
+}
+Object.freeze(exports);

package/build/core/keyring/peer-keys/dataset/v2/logs.d.ts

@@ -0,0 +1,43 @@
+import { LogError } from "../../../../../lib-client/logging/log-to-file";
+import { SingleProc } from "../../../../../lib-common/processes/synced";
+import { RecipientKeyPairDbEntry, SendingKeyPairDbEntry } from "./peer-keys-db";
+type WritableFS = web3n.files.WritableFS;
+export interface PairFromPeerLog {
+    opType: 'pair-from-peer';
+    eventTS: number;
+    sendingPairRecord: Omit<SendingKeyPairDbEntry, 'msgMasterKey' | 'senderSKey' | 'peerPKey'> & {
+        msgMasterKey: string;
+        senderSKey: string;
+        peerPKey: string;
+    };
+    peerAddr: string;
+}
+export interface PairSuggestedToPeerLog {
+    opType: 'pair-suggested-to-peer';
+    eventTS: number;
+    receivingPairRecord: Omit<RecipientKeyPairDbEntry, 'msgMasterKey' | 'recipientSKey' | 'peerPKey'> & {
+        msgMasterKey: string;
+        recipientSKey: string;
+        peerPKey: string;
+    };
+    peerAddr: string;
+}
+export interface PeerStartedUsingPair {
+    opType: 'peer-started-using-pair';
+    eventTS: number;
+    peerCAddr: string;
+    peerKId: string;
+    recipientKId: string;
+}
+export type PairEvent = PairFromPeerLog | PairSuggestedToPeerLog | PeerStartedUsingPair;
+export declare function sendingPairEntryFromJSON(json: PairFromPeerLog['sendingPairRecord']): SendingKeyPairDbEntry;
+export declare function recipientPairEntryFromJSON(json: PairSuggestedToPeerLog['receivingPairRecord']): RecipientKeyPairDbEntry;
+export declare function makePeerKeysChangeLogs(logsFS: WritableFS, localLogsFS: WritableFS, logError: LogError): Promise<{
+    recordSuggestingCryptoToPeer: (receivingPair: RecipientKeyPairDbEntry, peerAddr: string) => Promise<void>;
+    recordPeerStartedUsingPair: (peerCAddr: string, peerKId: string, recipientKId: string) => Promise<void>;
+    recordGettingCryptoFromPeer: (sendingPair: SendingKeyPairDbEntry, peerAddr: string) => Promise<void>;
+    numOfLogs: () => number;
+    cutLogOnDatasetSyncAndUpload: (syncPointV: number, params?: any) => Promise<void> | undefined;
+    watchAndApplyOpsFromOtherDevices: (changeProc: SingleProc, sink: (ops: import("../../../../../lib-common/dataset-sync/per-device-json-array-logs").LogEntry<PairEvent>[]) => Promise<void>) => () => void;
+}>;
+export {};

package/build/core/keyring/peer-keys/dataset/v2/logs.js

@@ -0,0 +1,116 @@
+"use strict";
+/*
+ Copyright (C) 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/>.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendingPairEntryFromJSON = sendingPairEntryFromJSON;
+exports.recipientPairEntryFromJSON = recipientPairEntryFromJSON;
+exports.makePeerKeysChangeLogs = makePeerKeysChangeLogs;
+const buffer_utils_1 = require("../../../../../lib-common/buffer-utils");
+const per_device_json_array_logs_1 = require("../../../../../lib-common/dataset-sync/per-device-json-array-logs");
+function sendingPairEntryFromJSON(json) {
+    return {
+        ...json,
+        msgMasterKey: buffer_utils_1.base64.open(json.msgMasterKey),
+        senderSKey: buffer_utils_1.base64.open(json.senderSKey),
+        peerPKey: buffer_utils_1.base64.open(json.peerPKey),
+    };
+}
+function sendingPairEntryToJSON(entry) {
+    return {
+        ...entry,
+        msgMasterKey: buffer_utils_1.base64.pack(entry.msgMasterKey),
+        senderSKey: buffer_utils_1.base64.pack(entry.senderSKey),
+        peerPKey: buffer_utils_1.base64.pack(entry.peerPKey),
+    };
+}
+function recipientPairEntryFromJSON(json) {
+    return {
+        ...json,
+        msgMasterKey: buffer_utils_1.base64.open(json.msgMasterKey),
+        recipientSKey: buffer_utils_1.base64.open(json.recipientSKey),
+        peerPKey: buffer_utils_1.base64.open(json.peerPKey),
+    };
+}
+function recipientPairEntryToJSON(entry) {
+    return {
+        ...entry,
+        msgMasterKey: buffer_utils_1.base64.pack(entry.msgMasterKey),
+        recipientSKey: buffer_utils_1.base64.pack(entry.recipientSKey),
+        peerPKey: buffer_utils_1.base64.pack(entry.peerPKey),
+    };
+}
+function areEventsEqual(a, b) {
+    if (b.opType !== a.opType) {
+        return false;
+    }
+    if (a.opType === 'pair-from-peer') {
+        const aSP = a.sendingPairRecord;
+        const { peerCAddr, peerKId, senderKId } = b.sendingPairRecord;
+        if ((aSP.peerCAddr === peerCAddr) && (aSP.peerKId === peerKId) && (aSP.senderKId === senderKId)) {
+            return true;
+        }
+    }
+    else if (a.opType === 'pair-suggested-to-peer') {
+        const aRP = a.receivingPairRecord;
+        const { receivingPairRecord: { peerCAddr, peerKId, recipientKId } } = b;
+        if ((aRP.peerCAddr === peerCAddr) && (aRP.peerKId === peerKId) && (aRP.recipientKId === recipientKId)) {
+            return true;
+        }
+    }
+    else if (a.opType === 'peer-started-using-pair') {
+        const { peerCAddr, peerKId, recipientKId } = b;
+        if ((a.peerCAddr === peerCAddr) && (a.peerKId === peerKId) && (a.recipientKId === recipientKId)) {
+            return true;
+        }
+    }
+    return false;
+}
+async function makePeerKeysChangeLogs(logsFS, localLogsFS, logError) {
+    const { appendLogsAndUpload, watchAndApplyOpsFromOtherDevices, cutLogOnDatasetSyncAndUpload, numOfLogs } = await (0, per_device_json_array_logs_1.makeRecentChangesLogs)(logsFS, localLogsFS, areEventsEqual, logError);
+    async function recordSuggestingCryptoToPeer(receivingPair, peerAddr) {
+        await appendLogsAndUpload({
+            opType: 'pair-suggested-to-peer',
+            eventTS: Date.now(),
+            receivingPairRecord: recipientPairEntryToJSON(receivingPair),
+            peerAddr
+        });
+    }
+    async function recordPeerStartedUsingPair(peerCAddr, peerKId, recipientKId) {
+        await appendLogsAndUpload({
+            opType: 'peer-started-using-pair',
+            eventTS: Date.now(),
+            peerCAddr, peerKId, recipientKId
+        });
+    }
+    async function recordGettingCryptoFromPeer(sendingPair, peerAddr) {
+        await appendLogsAndUpload({
+            opType: 'pair-from-peer',
+            eventTS: Date.now(),
+            sendingPairRecord: sendingPairEntryToJSON(sendingPair),
+            peerAddr
+        });
+    }
+    return {
+        recordSuggestingCryptoToPeer,
+        recordPeerStartedUsingPair,
+        recordGettingCryptoFromPeer,
+        numOfLogs,
+        cutLogOnDatasetSyncAndUpload,
+        watchAndApplyOpsFromOtherDevices
+    };
+}
+Object.freeze(exports);

package/build/core/keyring/peer-keys/dataset/v2/peer-keys-db.d.ts

@@ -0,0 +1,73 @@
+import { SuggestedNextKeyPair } from "../../../../asmail/msg/common";
+import { AsyncRNG } from "../../../../../lib-common/rng-def";
+import { PairEvent } from "./logs";
+import { SingleProc } from "../../../../../lib-common/processes/synced";
+import { LogEntry } from "../../../../../lib-common/dataset-sync/per-device-json-array-logs";
+type WritableFS = web3n.files.WritableFS;
+type JsonKey = web3n.keys.JsonKey;
+type CorrespondentKeysInfo = web3n.keys.CorrespondentKeysInfo;
+export interface SendingKeyPairDbEntry {
+    peerCAddr: string;
+    pids: string[];
+    pairAlg: string;
+    pairTS: number;
+    sentMsgsCount: number;
+    sentMsgLastTS: number;
+    peerPKey: Uint8Array;
+    peerKId: string;
+    senderSKey: Uint8Array;
+    senderPKey: string;
+    senderKId: string;
+    msgMasterKeyAlg: string;
+    msgMasterKey: Uint8Array;
+}
+export interface RecipientKeyPairDbEntry {
+    peerCAddr: string;
+    ratchetStage: 'suggested' | 'in_use' | 'old';
+    pids: string[];
+    pairTS: number;
+    pairAlg: string;
+    receivedMsgsCounts?: number[][];
+    receivedMsgLastTS?: number;
+    peerPKey: Uint8Array;
+    peerKId: string;
+    isPeerIntroKey: boolean;
+    recipientSKey: Uint8Array;
+    recipientPKey: string;
+    recipientKId: string;
+    msgMasterKeyAlg: string;
+    msgMasterKey: Uint8Array;
+}
+export declare function makePeerKeysDB(peerKeysFS: WritableFS, random: AsyncRNG): Promise<{
+    saveIfNeeded: () => Promise<void>;
+    generateSuggestedPairOnPeerIntroKey: (peerCAddr: string, peerIntroPKey: JsonKey) => Promise<{
+        nextCrypto: SuggestedNextKeyPair;
+        entryToLog: RecipientKeyPairDbEntry;
+    }>;
+    getPairSuggestedToPeer: (peerCAddr: string) => SuggestedNextKeyPair | undefined;
+    generateRegularSuggestedPairIfNeeded: (peerCAddr: string) => Promise<{
+        nextCrypto: SuggestedNextKeyPair;
+        entryToLog: RecipientKeyPairDbEntry;
+    } | undefined>;
+    addPeer: (peerAddr: string) => void;
+    getSendingPair: (peerCAddr: string) => SendingKeyPairDbEntry | undefined;
+    updateSentMsgCountInSendingPair: (peerCAddr: string, sentMsgsCount: number) => void;
+    addSendingPairFromSuggested: (peerCAddr: string, pair: SuggestedNextKeyPair, cryptoMaterial: Pick<SendingKeyPairDbEntry, "msgMasterKey" | "msgMasterKeyAlg" | "senderKId" | "senderPKey" | "senderSKey" | "peerPKey" | "pairAlg">) => void;
+    updateSendingPairFromSuggested: (peerCAddr: string, pair: SuggestedNextKeyPair, cryptoMaterial: Pick<SendingKeyPairDbEntry, "msgMasterKey" | "msgMasterKeyAlg" | "senderKId" | "senderPKey" | "senderSKey" | "peerPKey">) => void;
+    findKeyToMatchSuggestedForSendingPair: (peerCAddr: string, thisSideKid: string) => {
+        skey: Uint8Array;
+        pkey: string;
+        pairAlg: string;
+    } | undefined;
+    addReceptionPair: (pair: RecipientKeyPairDbEntry) => void;
+    markPairAsInUse: (peerCAddr: string, peerKId: string, recipientKId: string) => boolean;
+    findReceptionPairsForPId: (pid: string) => Pick<RecipientKeyPairDbEntry, "peerCAddr" | "peerKId" | "recipientKId" | "msgMasterKey" | "ratchetStage" | "pairAlg">[] | undefined;
+    absorbV1DataIfPresent: (keyringFS: WritableFS) => Promise<void>;
+    getPeerAddressForCanonical: (peerCAddr: string) => string | undefined;
+    updateReceivedMsgCountIn: (peerCAddr: string, peerKId: string, recipientKId: string, msgCount: number, msgTS: number) => void;
+    absorbOpsFromOtherDevices: (changeProc: SingleProc, ops: LogEntry<PairEvent>[]) => Promise<void>;
+    watchAndApplyOpsFromOtherDevices: (changeProc: SingleProc, resetSyncInterval: () => void) => () => void;
+    saveAndSync: () => Promise<number>;
+    getPeerKeysInfo: (peerAddr: string) => CorrespondentKeysInfo | undefined;
+}>;
+export {};