@qbix/q 1.0.5

package/dist/methods/Q/Crypto/delegate.js

@@ -0,0 +1,186 @@
+Q.exports(function (Q) {
+
+	/**
+	 * Perform a cryptographic delegation ceremony.
+	 *
+	 * Delegation is capability-based:
+	 * - A child secret is deterministically derived from a parent secret
+	 * - The parent signs a typed delegation statement
+	 * - The result can be verified and chained
+	 *
+	 * SECURITY MODEL:
+	 * - rootSecret is never returned
+	 * - secret is the sole bearer of delegated capability
+	 * - Authority is proven by the parent's signature
+	 * - context is treated as an opaque, signed string
+	 *
+	 * SIGNING FORMATS:
+	 * - "ES256"  → P-256 + SHA-256. Digest = SHA-256(canonical JSON payload).
+	 * - "EIP712" → secp256k1 + keccak256 + full EIP-712 struct encoding.
+	 *   Domain: { name: "Q.Crypto", version: "1", salt: keccak256(label) }
+	 *   The label is in the domain salt, making cross-label signature
+	 *   replay structurally impossible at the cryptographic level.
+	 *
+	 * @static
+	 * @method delegate
+	 *
+	 * @param {Object}     options
+	 * @param {Uint8Array} options.rootSecret  Parent secret material.
+	 * @param {String}     options.label       Delegation label (domain-separated).
+	 * @param {String}     [options.context]   Opaque, signed context string.
+	 * @param {String}     [options.format='es256'] "ES256" or "EIP712".
+	 *
+	 * @return {Q.Promise<Object>}
+	 * @return {String}     return.label     Delegation label.
+	 * @return {String}     return.context   Signed context string.
+	 * @return {Uint8Array} return.secret    Delegated capability secret.
+	 * @return {Object}     return.statement The signed statement.
+	 * @return {Object}     return.proof     Signed delegation proof.
+	 */
+	return function Q_Crypto_delegate(options) {
+
+		return new Q.Promise(async function (resolve, reject) {
+
+			try {
+
+				if (!options) {
+					throw new Error("options required");
+				}
+
+				const rootSecret = options.rootSecret;
+				const label      = options.label;
+				const context    = options.context;
+				const format     = options.format || "ES256";
+
+				if (!(rootSecret instanceof Uint8Array)) {
+					throw new Error("rootSecret must be Uint8Array");
+				}
+				if (typeof label !== "string" || !label.length) {
+					throw new Error("label required");
+				}
+				if (context !== undefined && typeof context !== "string") {
+					throw new Error("context must be a string if provided");
+				}
+
+				const normalizedContext = context || "";
+
+				// -------------------------------------------------
+				// Derive delegated capability secret
+				// -------------------------------------------------
+				const derivedSecret = await Q.Data.derive(
+					rootSecret,
+					"q.crypto.delegate." + label,
+					{ size: 32 }
+				);
+
+				// -------------------------------------------------
+				// Derive parent keypair + identity
+				// -------------------------------------------------
+				const parentKp = await Q.Crypto.internalKeypair({
+					secret: rootSecret,
+					format: format
+				});
+
+				let parentIdentity;
+				let parentType;
+
+				if (format === "EIP712") {
+					// eip712: parent identity is the Ethereum address
+					parentIdentity = parentKp.address;
+					parentType     = "address";
+				} else {
+					// es256: parent identity is SHA-256 of the public key
+					const pubBytes  = Q.Data.toUint8Array(parentKp.publicKey);
+					const pubDigest = await Q.Data.digest("SHA-256", pubBytes);
+					parentIdentity  = Q.Data.toHex(pubDigest);
+					parentType      = "bytes32";
+				}
+
+				// -------------------------------------------------
+				// Compute secret hash
+				// eip712: keccak256(derivedSecret)
+				// es256:  SHA-256(derivedSecret)
+				// -------------------------------------------------
+				const { keccak_256 } = await import(
+					Q.url("{{Q}}/src/js/crypto/sha3.js")
+				);
+
+				let secretHashHex;
+
+				if (format === "EIP712") {
+					secretHashHex = Q.Data.toHex(keccak_256(derivedSecret));
+				} else {
+					secretHashHex = Q.Data.toHex(
+						await Q.Data.digest("SHA-256", derivedSecret)
+					);
+				}
+
+				// -------------------------------------------------
+				// Construct delegation statement (protocol-fixed)
+				// -------------------------------------------------
+				const statement = {
+					parent:     parentIdentity,
+					label:      label,
+					issuedTime: Math.floor(Date.now() / 1000),
+					context:    normalizedContext,
+					secretHash: secretHashHex
+				};
+
+				// -------------------------------------------------
+				// Build domain
+				// eip712: { name, version, salt } where
+				//   salt = keccak256(utf8(label)) as bytes32.
+				//   Placing the label in the domain salt makes
+				//   cross-label replay impossible at the digest level.
+				// es256: domain is unused (empty object).
+				// -------------------------------------------------
+				const domain = format === "EIP712"
+					? {
+						name:    "Q.Crypto",
+						version: "1",
+						salt:    Q.Data.toHex(keccak_256(new TextEncoder().encode(label)))
+					}
+					: {};
+
+				// -------------------------------------------------
+				// Sign via Q.Crypto.sign()
+				// eip712 path uses hashTypedData() from eip712.js.
+				// es256  path uses SHA-256(canonical JSON).
+				// -------------------------------------------------
+				const proof = await Q.Crypto.sign({
+					secret:      rootSecret,
+					domain:      domain,
+					message:     statement,
+					types: {
+						EIP712Domain: [
+							{ name: "name",    type: "string"  },
+							{ name: "version", type: "string"  },
+							{ name: "salt",    type: "bytes32" }
+						],
+						Delegation: [
+							{ name: "parent",     type: parentType },
+							{ name: "label",      type: "string"   },
+							{ name: "issuedTime", type: "uint64"   },
+							{ name: "context",    type: "string"   },
+							{ name: "secretHash", type: "bytes32"  }
+						]
+					},
+					primaryType: "Delegation",
+					format:      format
+				});
+
+				resolve({
+					label:     label,
+					context:   normalizedContext,
+					secret:    derivedSecret,
+					statement: statement,
+					proof:     proof
+				});
+
+			} catch (e) {
+				reject(e);
+			}
+		});
+	};
+
+});

package/dist/methods/Q/Crypto/internalKeypair.js

@@ -0,0 +1,170 @@
+Q.exports(function (Q) {
+
+	/**
+	 * Deterministically derive a signing keypair from a secret.
+	 *
+	 * SECURITY INVARIANTS:
+	 * - This is the ONLY place secrets become private keys
+	 * - No randomness
+	 * - No storage
+	 * - Deterministic & reproducible
+	 *
+	 * Supported formats:
+	 * - "eip712" → secp256k1 (noble-curves). Public key and Ethereum
+	 *              address derived entirely from noble, no ethers dependency.
+	 * - "es256"  → NIST P-256 (noble-curves).
+	 *
+	 * Derivation method:
+	 * - eip712: seed = keccak256("q.crypto.k256.private-key" || secret),
+	 *           scalar = seed mod curveOrder.
+	 * - es256:  scalar = HKDF-SHA256(secret, "q.crypto.p256.private-key")
+	 *           via Q.Data.derive().
+	 *
+	 * @static
+	 * @method internalKeypair
+	 *
+	 * @param {Object}     options
+	 * @param {Uint8Array} options.secret          Raw secret material (32 bytes recommended).
+	 * @param {String}     [options.format="es256"] Signing format: "eip712" or "es256".
+	 *
+	 * @return {Q.Promise<Object>} Resolves to an object with the following properties:
+	 *
+	 *   format     {String}     Normalized format: "eip712" or "es256".
+	 *   curve      {String}     Curve name: "secp256k1" or "p256".
+	 *   hashAlg    {String}     Hash algorithm: "keccak256" or "sha256".
+	 *   privateKey {Uint8Array} Raw private key scalar (32 bytes).
+	 *                           Never log, store, or transmit this value.
+	 *   publicKey  {Uint8Array} Raw uncompressed public key (65 bytes): 0x04 || X || Y.
+	 *
+	 *   The following property is only present for "eip712":
+	 *   address    {String}     Ethereum address: lowercase "0x" + last 20 bytes of
+	 *                           keccak256(publicKey[1..64]). Suitable for use
+	 *                           as an EVM signer identity.
+	 *
+	 * @throws {Error} If secret is missing or not a Uint8Array.
+	 * @throws {Error} If format is unsupported.
+	 * @throws {Error} If derived private key scalar is zero (astronomically unlikely).
+	 */
+	return function Q_Crypto_internalKeypair(options) {
+
+		return new Q.Promise(async function (resolve, reject) {
+
+			try {
+
+				if (!options || !(options.secret instanceof Uint8Array)) {
+					throw new Error("secret must be Uint8Array");
+				}
+
+				const secret = options.secret;
+				const format = options.format || "ES256";
+
+				// -------------------------------------------------
+				// EIP-712 / secp256k1 (noble-curves, no ethers)
+				// -------------------------------------------------
+				if (format === "EIP712") {
+
+					const [{ keccak_256 }, secp] = await Promise.all([
+						import(Q.url("{{Q}}/src/js/crypto/sha3.js")),
+						import(Q.url("{{Q}}/src/js/crypto/secp256k1.js"))
+					]);
+
+					// Domain-separated deterministic seed:
+					// keccak256("q.crypto.k256.private-key" || secret)
+					const info     = new TextEncoder().encode("q.crypto.k256.private-key");
+					const material = new Uint8Array(info.length + secret.length);
+					material.set(info, 0);
+					material.set(secret, info.length);
+
+					const digest = keccak_256(material); // Uint8Array(32)
+
+					// Reduce mod curve order — matches PHP implementation
+					const n = secp.secp256k1.CURVE.n;
+					const k = bytesToBigInt(digest) % n;
+
+					if (k === 0n) {
+						throw new Error("Derived invalid secp256k1 scalar");
+					}
+
+					// Private key as Uint8Array(32)
+					const privateKey = bigIntToBytes32(k);
+
+					// Uncompressed public key: 0x04 || X(32) || Y(32)
+					const publicKey = secp.secp256k1.getPublicKey(privateKey, false);
+
+					// Ethereum address: "0x" + last 20 bytes of keccak256(pubkey[1..])
+					const pubKeyBody  = publicKey.slice(1); // drop 0x04 prefix
+					const addrHash    = keccak_256(pubKeyBody); // Uint8Array(32)
+					const address     = "0x" + Q.Data.toHex(addrHash.slice(12)); // last 20 bytes
+
+					resolve({
+						format:     "eip712",
+						curve:      "secp256k1",
+						hashAlg:    "keccak256",
+						privateKey: privateKey, // Uint8Array(32)
+						publicKey:  publicKey,  // Uint8Array(65)
+						address:    address     // "0x..." lowercase
+					});
+
+					return;
+				}
+
+				// -------------------------------------------------
+				// es256 / P-256 (noble-curves)
+				// -------------------------------------------------
+				if (format === "ES256") {
+
+					const noble = await import(
+						Q.url("{{Q}}/src/js/crypto/nist.js")
+					);
+
+					// Deterministic scalar via HKDF-SHA256
+					const privateKey = await Q.Data.derive(
+						secret,
+						"q.crypto.p256.private-key",
+						{ size: 32 }
+					); // Uint8Array(32)
+
+					// Uncompressed public key: 0x04 || X(32) || Y(32)
+					const publicKey = noble.p256.getPublicKey(privateKey, false);
+
+					resolve({
+						format:     "es256",
+						curve:      "p256",
+						hashAlg:    "sha256",
+						privateKey: privateKey, // Uint8Array(32)
+						publicKey:  publicKey   // Uint8Array(65)
+					});
+
+					return;
+				}
+
+				throw new Error("Unsupported format: " + format);
+
+			} catch (e) {
+				reject(e);
+			}
+		});
+	};
+
+	// -------------------------------------------------
+	// Module-private helpers
+	// -------------------------------------------------
+
+	function bytesToBigInt(bytes) {
+		let result = 0n;
+		for (let i = 0; i < bytes.length; i++) {
+			result = (result << 8n) | BigInt(bytes[i]);
+		}
+		return result;
+	}
+
+	function bigIntToBytes32(n) {
+		const hex = n.toString(16).padStart(64, "0");
+		const out = new Uint8Array(32);
+		for (let i = 0; i < 32; i++) {
+			out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+		}
+		return out;
+	}
+
+});

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

@@ -0,0 +1,200 @@
+Q.exports(function (Q) {
+
+	/**
+	 * Sign a typed message using a deterministically derived keypair.
+	 *
+	 * This is the JS counterpart of Q_Crypto::sign() in PHP.
+	 * It performs protocol-level typed signing (not raw message signing).
+	 *
+	 * Supported formats:
+	 * - "ES256"  → NIST P-256 + SHA-256 (Q-native)
+	 * - "EIP712" → secp256k1 + keccak256 (Ethereum-style, full EIP-712 encoding)
+	 *
+	 * SECURITY PROPERTIES:
+	 * - Secret is never stored
+	 * - Keypair derivation is deterministic
+	 * - Exactly one hash + one signature
+	 * - Output is a verifiable proof object
+	 *
+	 * @static
+	 * @method sign
+	 *
+	 * @param {Object}     options
+	 * @param {Uint8Array} options.secret      Raw binary secret material.
+	 * @param {Object}     options.message     Typed message payload.
+	 * @param {Object}     options.types       Type definitions (EIP-712 style).
+	 * @param {String}     options.primaryType Root type name.
+	 * @param {Object}     [options.domain={}] Domain separator fields.
+	 * @param {String}     [options.format="ES256"] "ES256" or "EIP712".
+	 *
+	 * @return {Q.Promise<Object>} Resolves to an object with the following properties:
+	 *
+	 *   format       {String}     Resolved format: "eip712" or "es256".
+	 *   curve        {String}     Elliptic curve: "secp256k1" or "p256".
+	 *   hashAlg      {String}     Hash algorithm: "keccak256" or "sha256".
+	 *   domain       {Object}     Domain separator used.
+	 *   primaryType  {String}     Root type name.
+	 *   digest       {String}     Hex-encoded message digest.
+	 *   signature    {Uint8Array} Raw signature bytes.
+	 *                             EIP712: 65 bytes r||s||v (v = 27 + recovery).
+	 *                             ES256:  DER-encoded ECDSA signature.
+	 *   signatureHex {String}     Hex-encoded signature (no 0x prefix).
+	 *   publicKey    {Uint8Array} Raw uncompressed public key (65 bytes).
+	 *
+	 *   EIP712 only:
+	 *   address      {String}     Ethereum address of signer ("0x...").
+	 */
+	return function Q_Crypto_sign(options) {
+
+		return new Q.Promise(async function (resolve, reject) {
+
+			try {
+
+				if (!options || !(options.secret instanceof Uint8Array)) {
+					throw new Error("secret must be Uint8Array");
+				}
+				if (!options.message || typeof options.message !== "object") {
+					throw new Error("message required");
+				}
+				if (!options.types || typeof options.types !== "object") {
+					throw new Error("types required");
+				}
+				if (typeof options.primaryType !== "string") {
+					throw new Error("primaryType required");
+				}
+
+				const domain = options.domain || {};
+				const format = options.format || "ES256";
+
+				// -------------------------------------------------
+				// Derive keypair ONCE
+				// -------------------------------------------------
+				const kp = await Q.Crypto.internalKeypair({
+					secret: options.secret,
+					format: format
+				});
+
+				/* =================================================
+				 * EIP712 (secp256k1 + keccak256)
+				 * ================================================= */
+				if (format === "EIP712") {
+
+					const [{ hashTypedData }, secp] = await Promise.all([
+						import(Q.url("{{Q}}/src/js/crypto/eip712.js")),
+						import(Q.url("{{Q}}/src/js/crypto/secp256k1.js"))
+					]);
+
+					// Single source of truth for EIP-712 digest —
+					// byte-identical to Q_Crypto_EIP712::hashTypedData() in PHP
+					const digestBytes = hashTypedData(
+						domain,
+						options.primaryType,
+						options.message,
+						options.types
+					);
+
+					const sig = secp.secp256k1.sign(digestBytes, kp.privateKey, {
+						recovered: true,
+						der: false
+					});
+
+					let compact, recovery;
+
+					if (Array.isArray(sig)) {
+						compact  = sig[0];
+						recovery = sig[1];
+					} else {
+						compact  = sig.signature;
+						recovery = sig.recovery;
+					}
+
+					if (!(compact instanceof Uint8Array)) {
+						compact = new Uint8Array(compact);
+					}
+
+					// Ethereum-style: r||s||v  (v = 27 + recovery)
+					const signature = new Uint8Array(65);
+					signature.set(compact, 0);
+					signature[64] = 27 + recovery;
+
+					resolve({
+						format:       "eip712",
+						curve:        "secp256k1",
+						hashAlg:      "keccak256",
+						domain:       domain,
+						primaryType:  options.primaryType,
+						digest:       Q.Data.toHex(digestBytes),
+						signature:    signature,
+						signatureHex: Q.Data.toHex(signature),
+						publicKey:    kp.publicKey,
+						address:      kp.address
+					});
+
+					return;
+				}
+
+				/* =================================================
+				 * ES256 (P-256 + SHA-256)
+				 * ================================================= */
+
+				// Canonical JSON payload — must match Q_Crypto::sign() in PHP exactly
+				const payload = {
+					domain:      domain,
+					primaryType: options.primaryType,
+					types:       options.types,
+					message:     options.message
+				};
+
+				const canonical   = Q.serialize(payload);
+				const msgBytes    = new TextEncoder().encode(canonical);
+				const digestBytes = await Q.Data.digest("SHA-256", msgBytes);
+
+				const noble = await import(
+					Q.url("{{Q}}/src/js/crypto/nist.js")
+				);
+				const { encodeEcdsaDer } = await import(
+					Q.url("{{Q}}/src/js/crypto/encoder.js")
+				);
+
+				const sig = noble.p256
+					.sign(digestBytes, kp.privateKey)
+					.normalizeS();
+
+				const signatureDer = encodeEcdsaDer(
+					bigIntTo32Bytes(sig.r),
+					bigIntTo32Bytes(sig.s)
+				);
+
+				resolve({
+					format:       "es256",
+					curve:        "p256",
+					hashAlg:      "sha256",
+					domain:       domain,
+					primaryType:  options.primaryType,
+					digest:       Q.Data.toHex(digestBytes),
+					signature:    signatureDer,
+					signatureHex: Q.Data.toHex(signatureDer),
+					publicKey:    kp.publicKey
+				});
+
+			} catch (e) {
+				reject(e);
+			}
+		});
+	};
+
+	// -------------------------------------------------
+	// Module-private helper
+	// -------------------------------------------------
+
+	// BigInt → 32-byte Uint8Array (big-endian)
+	function bigIntTo32Bytes(n) {
+		const hex = n.toString(16).padStart(64, "0");
+		const out = new Uint8Array(32);
+		for (let i = 0; i < 32; i++) {
+			out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+		}
+		return out;
+	}
+
+});