@qbix/q 1.0.5

package/dist/methods/Q/Data/decrypt.js

@@ -0,0 +1,55 @@
+Q.exports(function (Q) {
+
+	/**
+	 * Decrypts AES-256-GCM ciphertext.
+	 *
+	 * @module Q
+	 * @class Q.Data
+	 */
+
+	/**
+	 * @static
+	 * @method decrypt
+	 * @param {CryptoKey} key AES-GCM key
+	 * @param {String} ivBase64 Base64-encoded IV (12 bytes)
+	 * @param {String} ciphertextBase64 Base64-encoded ciphertext + tag
+	 * @param {Object} [options]
+	 * @param {Uint8Array} [options.additional] Additional authenticated data (AAD).
+	 *   Must match exactly what was passed to encrypt(), otherwise decryption fails.
+	 * @param {String} [options.tag] Base64-encoded authentication tag (16 bytes).
+	 *   If provided, the tag is appended to ciphertext before decryption,
+	 *   matching the WebCrypto AES-GCM expectation of ciphertext || tag.
+	 *   If omitted, ciphertextBase64 is assumed to already include the tag.
+	 * @return {Q.Promise} Resolves Uint8Array plaintext
+	 */
+	return function Q_Data_decrypt(key, ivBase64, ciphertextBase64, options) {
+		options = options || {};
+
+		var iv         = Q.Data.fromBase64(ivBase64);
+		var ciphertext = Q.Data.fromBase64(ciphertextBase64);
+
+		// If a separate tag is provided, concatenate ciphertext || tag
+		// to match the WebCrypto AES-GCM wire format
+		if (options.tag) {
+			var tag     = Q.Data.fromBase64(options.tag);
+			var combined = new Uint8Array(ciphertext.length + tag.length);
+			combined.set(ciphertext, 0);
+			combined.set(tag, ciphertext.length);
+			ciphertext = combined;
+		}
+
+		var params = {
+			name: 'AES-GCM',
+			iv:   iv
+		};
+		if (options.additional) {
+			params.additionalData = options.additional;
+		}
+
+		return crypto.subtle.decrypt(params, key, ciphertext)
+			.then(function (plaintext) {
+				return new Uint8Array(plaintext);
+			});
+	};
+
+});

package/dist/methods/Q/Data/derive.js

@@ -0,0 +1,76 @@
+Q.exports(function (Q) {
+
+	/**
+	 * Deterministically derives key material from a seed
+	 * using HKDF with explicit domain separation.
+	 *
+	 * PURE FUNCTION:
+	 * - no randomness
+	 * - no storage
+	 * - no side effects
+	 *
+	 * Seed must be binary — pass Uint8Array, ArrayBuffer, or a raw
+	 * binary-compatible type handled by Q.Data.toUint8Array().
+	 * If you have a hex or base64 string, decode it first with
+	 * Q.Data.fromHex() or Q.Data.fromBase64() before calling derive().
+	 *
+	 * @module Q
+	 * @class Q.Data
+	 */
+
+	/**
+	 * @static
+	 * @method derive
+	 *
+	 * @param {Uint8Array|ArrayBuffer} seed
+	 *   Raw binary seed material. Must be a typed binary type —
+	 *   not a string. Decode hex/base64 strings before calling.
+	 * @param {String} label
+	 *   Domain separation label (used as HKDF info). Must be non-empty UTF-8.
+	 * @param {Object} [options]
+	 * @param {Number} [options.size=32]  Output length in bytes.
+	 * @param {String} [options.context=""] Context string used to derive salt
+	 *   via SHA-256(context). Empty string is valid and produces a fixed salt.
+	 *
+	 * @return {Q.Promise<Uint8Array>} Resolves derived key material.
+	 */
+	return function Q_Data_derive(seed, label, options) {
+
+		options = options || {};
+		var size    = options.size    || 32;
+		var context = options.context || "";
+
+		// ---------------------------------------------
+		// Normalize seed — strict binary types only
+		// ---------------------------------------------
+		var seedBytes;
+		try {
+			seedBytes = Q.Data.toUint8Array(seed);
+		} catch (e) {
+			return Q.reject(new Error(
+				"derive: seed must be a binary type (Uint8Array, ArrayBuffer). " +
+				"Decode hex or base64 strings before calling derive(). " +
+				"Original error: " + e.message
+			));
+		}
+
+		if (!label || typeof label !== "string") {
+			return Q.reject(new Error("derive: label must be a non-empty string"));
+		}
+
+		// ---------------------------------------------
+		// salt = SHA-256(context)
+		// ---------------------------------------------
+		var contextBytes = new TextEncoder().encode(context);
+
+		return Q.Data.digest("SHA-256", contextBytes)
+		.then(function (salt) {
+			return Q.Data.hkdf(
+				seedBytes,  // IKM
+				salt,       // salt = SHA-256(context)
+				label,      // info = label
+				size
+			);
+		});
+	};
+});

package/dist/methods/Q/Data/digest.js

@@ -0,0 +1,29 @@
+Q.exports(function (Q) {
+    /**
+     * Q plugin's front end code
+     *
+     * @module Q
+     * @class Q.Data
+     */
+
+    /**
+     * Generate a digest
+     * @static
+     * @method digest
+     * @param {String} algorithm 
+     * @param {String} payload 
+     * @param {Function} callback receives (err, result)
+     * @return {Q.Promise} Returns a Uint8Array
+     */
+    return function Q_Data_digest(algorithm, payload, callback) {
+        var encoded = new TextEncoder().encode(payload);
+
+        return crypto.subtle.digest(algorithm, encoded)
+        .then(function (buffer) {
+            var result = new Uint8Array(buffer);
+            callback && callback(null, result);
+            return result;
+        });
+    };
+
+});

package/dist/methods/Q/Data/encrypt.js

@@ -0,0 +1,61 @@
+Q.exports(function (Q) {
+
+	/**
+	 * Encrypts plaintext using AES-256-GCM.
+	 *
+	 * @module Q
+	 * @class Q.Data
+	 */
+
+	/**
+	 * @static
+	 * @method encrypt
+	 * @param {CryptoKey} key AES-GCM key
+	 * @param {Uint8Array} plaintext
+	 * @param {Object} [options]
+	 * @param {Uint8Array|String} [options.iv] Optional IV (12 bytes).
+	 *   If omitted, a random IV is generated via crypto.getRandomValues.
+	 *   Pass a derived IV (e.g. from Q.Data.derive) for deterministic /
+	 *   convergent encryption, such as Safecloud chunk encryption where
+	 *   the same content should always produce the same ciphertext and CID.
+	 *   WARNING: never reuse the same (key, iv) pair for different plaintexts.
+	 * @param {Uint8Array} [options.additional] Additional authenticated data (AAD).
+	 *   Authenticated but not encrypted. Pass e.g. a chunk index or stream ID
+	 *   to bind the ciphertext to its position and prevent reordering attacks.
+	 * @return {Q.Promise} Resolves { iv: String, ciphertext: String, tag: String }
+	 *   All values are base64-encoded.
+	 */
+	return function Q_Data_encrypt(key, plaintext, options) {
+		options = options || {};
+
+		var iv;
+		if (options.iv) {
+			iv = (typeof options.iv === 'string')
+				? Q.Data.fromBase64(options.iv)
+				: Q.Data.toUint8Array(options.iv);
+		} else {
+			iv = crypto.getRandomValues(new Uint8Array(12));
+		}
+
+		var params = {
+			name: 'AES-GCM',
+			iv:   iv
+		};
+		if (options.additional) {
+			params.additionalData = options.additional;
+		}
+
+		return crypto.subtle.encrypt(params, key, plaintext)
+			.then(function (ciphertext) {
+				var ct  = new Uint8Array(ciphertext);
+				var tag = ct.slice(ct.length - 16);
+				var data = ct.slice(0, ct.length - 16);
+				return {
+					iv:         Q.Data.toBase64(iv),
+					ciphertext: Q.Data.toBase64(data),
+					tag:        Q.Data.toBase64(tag)
+				};
+			});
+	};
+
+});

package/dist/methods/Q/Data/generateKey.js

@@ -0,0 +1,40 @@
+Q.exports(function (Q) {
+    /**
+     * Generates a public/private key pair and exports them as base64 strings.
+     * Compatible with Q.Data.verify and Q.Data.sign using SubtleCrypto.
+     *
+     * @module Q
+     * @class Q.Data
+     */
+
+    /**
+     * @static
+     * @method generateKey
+     * @param {Object} [algo] optional algorithm override
+     * @param {String} [algo.name="ECDSA"]
+     * @param {String} [algo.namedCurve="P-256"]
+     * @param {String} [algo.hash="SHA-256"]
+     * @return {Q.Promise} Resolves with { publicKey, privateKey, algorithm },
+     * where each key is a base64 string and algorithm is the resolved object.
+     */
+    return function Q_Data_generateKey(algo) {
+        algo = Q.extend({
+            name: 'ECDSA',
+            namedCurve: 'P-256',
+            hash: { name: "SHA-256" }
+        }, algo);
+
+        return crypto.subtle.generateKey(algo, true, ['sign', 'verify']).then(function (keyPair) {
+            return Q.Promise.all([
+                crypto.subtle.exportKey('raw', keyPair.publicKey),
+                crypto.subtle.exportKey('pkcs8', keyPair.privateKey)
+            ]).then(function ([pubKeyBuf, privKeyBuf]) {
+                return {
+                    publicKey: Q.Data.toBase64(pubKeyBuf),
+                    privateKey: Q.Data.toBase64(privKeyBuf),
+                    algorithm: algo
+                };
+            });
+        });
+    };
+});

package/dist/methods/Q/Data/hkdf.js

@@ -0,0 +1,44 @@
+Q.exports(function (Q) {
+
+	/**
+	 * HKDF using SHA-256 (RFC 5869).
+	 *
+	 * @module Q
+	 * @class Q.Data
+	 */
+
+	/**
+	 * @static
+	 * @method hkdf
+	 * @param {Uint8Array} ikm Input key material
+	 * @param {Uint8Array} salt Salt
+	 * @param {String} info Context string
+	 * @param {Number} [length=32] Output length in bytes
+	 * @return {Q.Promise} Resolves Uint8Array
+	 */
+	return function Q_Data_hkdf(ikm, salt, info, length) {
+		length = length || 32;
+		info = info || "";
+
+		return crypto.subtle.importKey(
+			"raw",
+			ikm,
+			{ name: "HKDF" },
+			false,
+			["deriveBits"]
+		).then(function (key) {
+			return crypto.subtle.deriveBits(
+				{
+					name: "HKDF",
+					hash: "SHA-256",
+					salt: salt,
+					info: new TextEncoder().encode(info)
+				},
+				key,
+				length * 8
+			);
+		}).then(function (bits) {
+			return new Uint8Array(bits);
+		});
+	};
+});

package/dist/methods/Q/Data/importKey.js

@@ -0,0 +1,34 @@
+Q.exports(function (Q) {
+
+	/**
+	 * @module Q
+	 * @class Q.Data
+	 */
+
+	/**
+	 * Imports raw key bytes into a CryptoKey for use with SubtleCrypto.
+	 * @static
+	 * @method importKey
+	 * @param {Uint8Array} keyBytes Raw key material
+	 * @param {Object} [algo] optional algorithm override
+	 * @param {String} [algo.name="AES-GCM"]
+	 * @param {Number} [algo.length=256]
+	 * @param {Array} [algo.usages=["encrypt", "decrypt"]]
+	 * @return {Q.Promise} Resolves CryptoKey
+	 */
+	return function Q_Data_importKey(keyBytes, algo) {
+		algo = Q.extend({
+			name: "AES-GCM",
+			length: 256,
+			usages: ["encrypt", "decrypt"]
+		}, algo);
+
+		return crypto.subtle.importKey(
+			"raw",
+			keyBytes,
+			{ name: algo.name, length: algo.length },
+			false,
+			algo.usages
+		);
+	};
+});

package/dist/methods/Q/Data/sign.js

@@ -0,0 +1,42 @@
+Q.exports(function (Q) {
+    /**
+     * Q plugin's front end code
+     *
+     * @module Q
+     * @class Q.Data
+     */
+
+    /**
+     * Encodes text data with TextEncoder, then signs it with
+     * each of the private keys. Returns a promise that is rejected
+     * if any of the keys fail to be imported.
+     * @static
+     * @method sign
+     * @param {String} data the data to sign
+     * @param {Array} privateKeyPKCS8Strings array of strings containing
+     *   PKCS8 encodings of private keys
+     * @param {Object} [algo] you can specify a different algorithm
+     * @param {String} [algo.name="ECDSA"]
+     * @param {String} [algo.namedCurve="P-256"]
+     * @param {String} [algo.hash="SHA-256"]
+     * @param {Function} callback receives (err, result)
+     * @return {Q.Promise} Resolves an array of ArrayBuffers containing
+     *   data signed with each of the corresponding public keys.
+     *   (You can use Q.Data.toBase64 to convert them into strings).
+     *   Or rejects if any of the keys fail to be imported.
+     */
+    return function Q_Data_sign(data, privateKeyPKCS8Strings, algo) {
+        algo = Q.extend({
+            name: 'ECDSA',
+            namedCurve: 'P-256',
+            hash: { name: "SHA-256" }
+        }, algo);
+        return Q.Promise.all(
+            privateKeyPKCS8Strings.map(pks => 
+                crypto.subtle.importKey('pkcs8', Q.Data.fromBase64(pks), algo, false, ['sign'])
+                .then(privateKey => crypto.subtle.sign(algo, privateKey, new TextEncoder().encode(data)))
+            )
+        );
+    };
+
+});

package/dist/methods/Q/Data/verify.js

@@ -0,0 +1,45 @@
+Q.exports(function (Q) {
+    /**
+     * Q plugin's front end code
+     *
+     * @module Q
+     * @class Q.Data
+     */
+
+    /**
+     * Encodes text data with TextEncoder, then verifies it with
+     * each of the public keys.
+     * @static
+     * @method verify
+     * @param {String} data the signed payload to verify
+     * @param {Array} publicKeyRawStrings array of exported public keys
+     * @param {Array} signatures array of ArrayBuffer signatures
+     *   previously generated with the corresponding public keys.
+     * @param {Object} [algo] you can specify a different algorithm
+     * @param {String} [algo.name="ECDSA"]
+     * @param {String} [algo.namedCurve="P-256"]
+     * @param {String} [algo.hash="SHA-256"]
+     * @param {Function} callback receives (err, result)
+     * @return {Q.Promise} Resolves with array of booleans corresponding
+     *   to each public key, indicating whether the verifications succeeded.
+     *   Or rejects if any of the keys fail to be imported.
+     */
+    return function Q_Data_verify(data, publicKeyRawStrings, signatures, algo) {
+		const sigs = [];
+		for (var sig of signatures) {
+			sigs.push(typeof sig === 'string' ? Q.Data.fromBase64(sig) : sig);
+		}
+        algo = Q.extend({
+            name: 'ECDSA',
+            namedCurve: 'P-256',
+            hash: { name: "SHA-256" }
+        }, algo);
+        return Q.Promise.all(
+            publicKeyRawStrings.map((pks, i) => 
+                crypto.subtle.importKey('raw', Q.Data.fromBase64(pks), algo, false, ['verify']
+            ).then(publicKey => crypto.subtle.verify(algo, publicKey, sigs[i], new TextEncoder().encode(data)))
+			)
+		);
+	};
+
+});

package/dist/methods/Q/Onboarding/handle.js

@@ -0,0 +1,50 @@
+Q.exports(function (Q) {
+    /**
+     * Q plugin's front end code
+     *
+     * @module Q
+     * @class Q.Onboarding
+     */
+
+    /**
+     * Handles a specific hint event, if it hasn't already occurred.
+     * Ignores the "after" instruction of the event, if any.
+     * But checks whether elements are visible, otherwise returns false.
+     * @static
+     * @method handle
+     * @param {String} key
+     * @param {Function} [callback]
+     */
+    return function _Q_Onboarding_handle(key, callback) {
+        // Added: support returning a Promise in addition to callback
+        var promise = new Promise(function (resolve) {
+            var lsk = Q.Onboarding.prefix + key;
+            var event = Q.Onboarding.events[key];
+            if (!localStorage[lsk] || !event || event.occurred || event.stopped) {
+                if (callback) callback(false);
+                return resolve(false);
+            }
+            var appeared = [];
+            var visible = false;
+            var selectorToAppear = Q.Onboarding.selectors[key].appear;
+            var elementsToAppear = document.querySelectorAll(selectorToAppear);
+            for (var i=0; i<elementsToAppear.length; ++i) {
+                var r = elementsToAppear[i].getBoundingClientRect();
+                if (r.width && r.height) {
+                    visible = true;
+                    appeared.push(elementsToAppear[i]);
+                }
+            }
+            if (!visible) {
+                if (callback) callback(false);
+                return resolve(false);
+            }
+            Q.Onboarding.waitToDisappear[key] = false;
+            Q.handle(Q.Onboarding.events[key], {}, [appeared, key]);
+            if (callback) callback(true);
+            resolve(true);
+        });
+
+        return promise;
+    };
+});

package/dist/methods/Q/Onboarding/start.js

@@ -0,0 +1,165 @@
+Q.exports(function (Q) {
+    /**
+     * Q plugin's front end code
+     *
+     * @module Q
+     * @class Q.Onboarding
+     */
+
+    /**
+     * Starts an onboarding process. You can also trigger
+     * Q.Onboarding.event manually with Q.handle().
+     * @static
+     * @method start
+     * @param {Object} [instructions] An object of key: instructionObject pairs
+     *   where instructionObject has at least "appear" key, with value = CSS selector.
+     *   It can also have optional:
+     *   "targets" (selector to override what to hint),
+     *   "disappear" (selector to override what should disappear before hint event stops)
+     *   "after" (key of a hint event that has to stop before this hint starts)
+     *   "options" (for options passed to Q.Visual.hint, merged over Q.Onboarding.options.hint)
+     *
+     */
+    return function _Q_Onboarding_start(instructions) {
+        // Added: track whether onboarding actually started
+        var started = false;
+        var resolveStarted;
+        var startedPromise = new Promise(function (resolve) {
+            resolveStarted = resolve;
+        });
+
+        if (!instructions) {
+            resolveStarted(false);
+            return startedPromise;
+        }
+        if (typeof Q.Onboarding.textName === 'string') {
+            Q.Text.get(Q.Onboarding.textName).then(function (text) {
+                Q.Onboarding.text = text;
+                if (!Q.isEmpty(Q.Onboarding.textPath)) {
+                    Q.Onboarding.text = Q.getObject(
+                        Q.Onboarding.textPath, Q.Onboarding.text
+                    );
+                }
+            });
+        }
+        var selectors = Q.Onboarding.selectors;
+        var events = Q.Onboarding.events;
+        var waitToDisappear = Q.Onboarding.waitToDisappear = {};
+        Q.each(instructions, function (k) {
+            var instr = instructions[k];
+            events[k] = new Q.Event(function (targets, k) {
+                var hintTargets = (selectors[k].targets)
+                    ? document.querySelectorAll(selectors[k].targets)
+                    : targets;
+                var lsk = Q.Onboarding.prefix + k;
+                if (localStorage[lsk]) {
+                    events[k].stop(); // it already occurred before
+                } else {
+                    var o = Q.extend({}, Q.Onboarding.options.hint, instr.options);
+                    if (Q.Onboarding.text[k]) {
+                        o.tooltip = Q.extend({
+                            text: Q.Onboarding.text && Q.Onboarding.text[k]
+                        }, o.tooltip);
+                    }
+                    o.onHide = Q.extend(o.onHide, {
+                        'Q.Onboarding': function () {
+                            setTimeout(function () {
+                                if (!waitToDisappear[k]) {
+                                    // They never appeared, or weren't specified
+                                    // So go to the next hint.
+                                    localStorage[Q.Onboarding.prefix + k] = 'stopped';
+                                    events[k].stop();
+                                    return;
+                                }
+                            }, Q.Onboarding.interval.afterHintHide || 3000);
+                        }
+                    });
+                    Q.Visual.stopHints(); // stop previous hints
+                    Q.Visual.hint(hintTargets, o);
+                    localStorage[lsk] = 'occurred';
+                }
+            }, 'Q.hint');
+            selectors[k] = { appear: instr.appear };
+            Q.take(instr, ['targets', 'disappear'], selectors[k]);
+        });
+        Q.Onboarding.intervalId && clearInterval(Q.Onboarding.intervalId);
+        Q.Onboarding.intervalId = setInterval(function () {
+            for (var k in selectors) {
+                var selectorToAppear = selectors[k].appear;
+                var selectorToDisappear = selectors[k].disappear || selectors[k].appear;
+                var elementsToAppear = document.querySelectorAll(selectorToAppear);
+                var appeared = [];
+                var visible = false;
+                for (var i=0; i<elementsToAppear.length; ++i) {
+                    var r = elementsToAppear[i].getBoundingClientRect();
+                    var s = Q.Onboarding.treatAsVisible;
+                    var elements = Array.prototype.slice.call(document.querySelectorAll(s));
+                    var treatAsVisible = elements.includes(elementsToAppear[i]);
+                    if (treatAsVisible || (r.width && r.height)) {
+                        visible = true;
+                        appeared.push(elementsToAppear[i]);
+                    }
+                }
+                if (!events[k].occurred && visible) {
+                    var after = instructions[k]?.after;
+                    if (typeof after === 'string') {
+                        after = [after];
+                    }
+                    var proceed = false;
+                    Q.each(after, function (i, s) {
+                        if (Q.Onboarding.events[s]?.stopped
+                        || localStorage[Q.Onboarding.prefix + s] === 'stopped') {
+                            proceed = true;
+                            return false;
+                        }
+                    });
+                    if (!after || proceed) {
+                        Q.Onboarding.waitToDisappear[k] = false;
+                        Q.handle(events[k], instructions, [appeared, k]);
+                        // Added: resolve when onboarding first starts
+                        if (!started) {
+                            started = true;
+                            resolveStarted(true);
+                        }
+                    }
+                }
+                if (!events[k].occurred || events[k].stopped) {
+                    continue;
+                }
+                if (selectorToDisappear === selectorToAppear) {
+					// event will stop onHide of the hints
+                    continue; // nothing to wait for
+                }
+                visible = false;
+                var elementsToDisappear = document.querySelectorAll(selectorToDisappear);
+                for (var i=0; i<elementsToDisappear.length; ++i) {
+                    var r = elementsToDisappear[i].getBoundingClientRect();
+                    var s = Q.Onboarding.treatAsVisible;
+                    var elements = Array.prototype.slice.call(document.querySelectorAll(s));
+                    var treatAsVisible = elements.includes(elementsToDisappear[i]);
+                    if (treatAsVisible || (r.width && r.height)) {
+                        visible = true;
+                        break;
+                    }
+                }
+                if (visible) {
+                    waitToDisappear[k] = true;
+                }
+                if (waitToDisappear[k] && !visible) {
+                    localStorage[Q.Onboarding.prefix + k] = 'stopped';
+                    events[k].stop();
+                    waitToDisappear[k] = false;
+                }
+            }
+        }, 100);
+
+        // Added: if nothing ever started after a grace period, resolve false
+        setTimeout(function () {
+            if (!started) {
+                resolveStarted(false);
+            }
+        }, 1000);
+
+        return startedPromise;
+    };
+});

package/dist/methods/Q/Onboarding/stop.js

@@ -0,0 +1,21 @@
+Q.exports(function (Q) {
+    /**
+     * Q plugin's front end code
+     *
+     * @module Q
+     * @class Q.Onboarding
+     */
+
+    /**
+     * Starts an onboarding process
+     * @static
+     * @method start
+     * @param {Object} [options={}] Can be one of the following options
+     */
+    return function _Q_Onboarding_stop(key) {
+        var instructions = Q.Onboarding.processes[key];
+        if (instructions) {
+            clearInterval(instructions.intervalId);
+        }
+    };
+});