@quantsafe/mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuantSafe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# @quantsafe/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Post-quantum encryption for AI agents. The same crypto core as [quantsafe.tech](https://quantsafe.tech), exposed as a Model Context Protocol server over stdio.
+
+- Hybrid KEM: ML-KEM-768 + X25519, combined with HKDF-SHA256
+- Signatures: ML-DSA-65, context-bound
+- Symmetric: AES-256-GCM, random nonces
+- Keyfiles wrapped with Argon2id
+
+Everything runs locally. No network calls, no telemetry.
+
+## Install
+
+Claude Desktop, Claude Code, Cursor or any MCP client:
+
+```json
+{
+  "mcpServers": {
+    "qsafe": {
+      "command": "npx",
+      "args": ["-y", "@quantsafe/mcp"]
+    }
+  }
+}
+```
+
+Requires Node.js 20 or later.
+
+## Tools
+
+| Tool                    | What it does                                                                                                                |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `qsafe_encrypt_file`    | Encrypt bytes under ML-KEM-768 + X25519, signed with ML-DSA-65                                                              |
+| `qsafe_decrypt_file`    | Decrypt a `.qsafe` blob with a keyfile or wallet signature                                                                  |
+| `qsafe_send_message`    | Wrap text in a shareable encrypted URL, optionally wallet-signed                                                            |
+| `qsafe_decrypt_message` | Read a message URL and return its text and the key that signed it                                                           |
+| `qsafe_verify_seal`     | Read the fields a Quantum Seal PNG carries, unsigned and unchecked; given the envelope, compare its sha256 with `file_hash` |
+| `qsafe_sign_x402`       | Sign an x402 payload with ML-DSA-65 under context `qsafe-v1-x402`                                                           |
+
+## Key sources
+
+A tool that signs or decrypts takes one key source: `keyfile_json` + `passphrase`, or a wallet signature given as `signature_hex` + `address`, with an optional `signature_hex_repeat`. `qsafe_encrypt_file` and `qsafe_send_message` name them `signer_keyfile_json`, `signer_passphrase`, `signer_signature_hex`, `signer_address` and `signer_signature_hex_repeat`.
+
+A keyfile without its passphrase, a passphrase without its keyfile, a signature without its address (or the reverse), or a keyfile together with any wallet field returns an error. `qsafe_encrypt_file` and `qsafe_send_message` sign with a fresh ephemeral identity only when every signer field is omitted.
+
+### Wallet signatures
+
+`signature_hex` is a 65-byte EOA signature (`0x` + 130 hex characters) made with `personal_sign` (EIP-191) over this exact message: six lines joined by `\n`, no trailing newline.
+
+```text
+QuantSafe keypair derivation v1
+
+This signature derives your personal post-quantum encryption keypair.
+It grants no permissions and costs no gas.
+
+Domain: quantsafe.tech
+```
+
+It is the message the browser app at [quantsafe.tech/app](https://quantsafe.tech/app) asks a wallet to sign, so the same wallet derives the same identity in both places. The tool descriptions quote it as a JSON string.
+
+Before any key is derived, the server recovers the signer of that message from `signature_hex` and refuses the call unless it equals `address`. A signature over other text (CRLF line endings, a missing line), a signature paired with another address, a high-s copy of a valid signature or a smart-contract wallet signature is refused instead of silently deriving an identity no browser session can reproduce.
+
+Keys are derived from all 65 bytes, the last one (`v`) included. viem, ethers and browser wallets such as MetaMask and Rabby return `v` as 27 or 28 (`1b` or `1c`). Some signers return 0 or 1 instead (raw ECDSA libraries, KMS wrappers, some hardware paths). Pass the signature exactly as your signer returned it: the identity comes from those exact bytes, as in the browser app, so rewriting `v` from 0/1 to 27/28 (or back) gives a different identity.
+
+MPC and threshold signers return a different valid signature every time, so the keys derived from them would change between sessions. Pass a second signature of the same message as `signature_hex_repeat` the first time you use a wallet: the call fails if the two differ.
+
+```js
+import { privateKeyToAccount } from 'viem/accounts'
+
+const QSAFE_DERIVATION_MESSAGE = [
+  'QuantSafe keypair derivation v1',
+  '',
+  'This signature derives your personal post-quantum encryption keypair.',
+  'It grants no permissions and costs no gas.',
+  '',
+  'Domain: quantsafe.tech',
+].join('\n')
+
+const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY)
+const signature_hex = await account.signMessage({ message: QSAFE_DERIVATION_MESSAGE })
+const signature_hex_repeat = await account.signMessage({ message: QSAFE_DERIVATION_MESSAGE })
+
+// signer_signature_hex, signer_address and signer_signature_hex_repeat on the encrypting tools
+await mcp.call('qsafe_decrypt_file', {
+  blob_base64,
+  signature_hex,
+  address: account.address,
+  signature_hex_repeat,
+  expected_signer_pubkey_base64,
+})
+```
+
+The signature is root key material. Pass it over the local stdio transport only.
+
+A wallet-derived identity is only as strong as the wallet key behind it: it rests on that key's elliptic curve. For files that must survive a break of elliptic curves, use a freshly generated key file, whose keys are random.
+
+## Inputs and outputs
+
+A trailing `?` marks an optional field. "Key source" is one of the forms above.
+
+| Tool                    | Inputs                                                                                           | Outputs                                                  |
+| ----------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
+| `qsafe_encrypt_file`    | `bytes_base64`, `recipient_pubkey_base64`, signer key source?                                    | `blob_base64`, `seal_png_base64`, `signer_pubkey_base64` |
+| `qsafe_decrypt_file`    | `blob_base64`, key source, `expected_signer_pubkey_base64`?                                      | `plaintext_base64`, `signer_pubkey_base64`, `filename`   |
+| `qsafe_send_message`    | `text`, `recipient_pubkey_base64`?, signer key source?                                           | `url`, `mode`                                            |
+| `qsafe_decrypt_message` | `url`, key source? (needed unless the URL carries its own key), `expected_signer_pubkey_base64`? | `text`, `signer_pubkey_base64`                           |
+| `qsafe_verify_seal`     | `png_base64`, `blob_base64`?                                                                     | `valid`, `metadata`, `file_hash_matches`?                |
+| `qsafe_sign_x402`       | `payload_json` (a JSON object), key source                                                       | `signature_base64`, `signer_pubkey_base64`               |
+
+Every `*_base64` input is standard base64: the alphabet `A-Z a-z 0-9 + /`, `=` padding, no whitespace or line breaks. Raw text, base64url or a string with stray characters is refused with an error that names the field; it is never decoded into other bytes. Encode the bytes first (`base64 -w0` on Linux, `base64 -i file` on macOS, `Buffer.from(bytes).toString('base64')` in Node).
+
+`seal_png_base64` is a 1x1 PNG whose text chunks carry the Quantum Seal fields (`file_hash` is sha256 of the envelope). It has no rendered card; `qsafe_verify_seal` and [/verify](https://quantsafe.tech/verify) read its fields.
+
+## Your public key
+
+`recipient_pubkey_base64` and `expected_signer_pubkey_base64` take the same kind of value: standard base64 of a 3168-byte hybrid public key, ML-KEM-768 (1184 bytes), then X25519 (32), then ML-DSA-65 (1952). It is the `signer_pubkey_base64` a tool returns when it signs with your key source; no tool returns it on its own.
+
+To get yours, call `qsafe_sign_x402` with your keyfile or wallet signature and any payload, for example `{}`, and keep `signer_pubkey_base64`. Give it to anyone who should encrypt to you, or who needs it to check your signature. The same key source always returns the same value. An anonymous ephemeral signer returns a new key on every call, and nothing can be encrypted to it later.
+
+## Reading a Seal
+
+No Seal field is signed: every one is a claim that anyone can write into a PNG. `qsafe_verify_seal` returns the fields it finds as `metadata`, and `valid` is `true` when at least one Seal field is present. `valid` checks nothing.
+
+Pass the envelope the Seal is for as `blob_base64` and the result adds `file_hash_matches`: `true` when sha256 of that envelope equals the Seal's `file_hash`. That is the only check the tool makes. It does not contact the chain, so anchor fields are returned as written. Who signed the envelope is checked when it is decrypted.
+
+## Decrypting a file from someone else
+
+`qsafe_decrypt_file` always verifies the ML-DSA-65 signature before it decrypts, and a `.qsafe` file does not carry its signer's public key. Pass the sender's `signer_pubkey_base64` (returned by `qsafe_encrypt_file`) as `expected_signer_pubkey_base64`. Leave it out only for a file you signed with the same key you decrypt with; any other file, including one encrypted with an anonymous ephemeral signer, fails with an error that names the field.
+
+A verified signature shows which key signed the envelope, not who wrote what is inside it. The signature covers the envelope bytes only, so anyone who holds a `.qsafe` file can strip its signature and sign the same envelope with their own key.
+
+## Messages
+
+`qsafe_send_message` returns the URL and its `mode`:
+
+- `recipient`: `recipient_pubkey_base64` was given, and only that key opens the message.
+- `anyone_with_link`: `recipient_pubkey_base64` was omitted. The URL carries its own decryption key, so anyone holding the URL can read the message.
+
+An empty or malformed `recipient_pubkey_base64` is refused, never treated as omitted.
+
+A message URL names the key that signed it, so a valid signature proves only that whoever built the URL holds that key. `qsafe_decrypt_message` returns that key as `signer_pubkey_base64`. Pass a key you already trust as `expected_signer_pubkey_base64` and a URL signed by any other key is refused.
+
+That pin confirms which key signed the envelope, not who wrote the text. Anyone who sees a URL can strip its signature, sign the same envelope with their own key and rebuild the URL around it: a recipient who pins that key reads the original text under the new signer. Do not take a signature as proof that the signer wrote the message.
+
+## Signing x402 payloads
+
+`payload_json` must be a JSON object. A JSON-encoded string, array or scalar is rejected, since a string would be signed as a quoted string literal rather than as the payload it encodes.
+
+The signed message is the UTF-8 encoding of the payload's canonical form, signed with ML-DSA-65 under context `qsafe-v1-x402`:
+
+- object keys sorted in JavaScript default string order (UTF-16 code units), at every level
+- no whitespace
+- arrays kept in order
+- strings, numbers, booleans and `null` written as `JSON.stringify` writes them
+
+For example, `{"b":1,"a":{"d":[true,null],"c":2.5}}` is signed as `{"a":{"c":2.5,"d":[true,null]},"b":1}`. A verifier rebuilds those bytes and checks the signature against the ML-DSA-65 part of `signer_pubkey_base64` (bytes 1216 to 3168 of the decoded key, after the ML-KEM-768 and X25519 parts).
+
+## Errors
+
+A failed call returns `isError: true` with a JSON body `{ "error": "..." }`. Arguments that do not match a tool's input schema are rejected before the tool runs, with `isError: true` and a plain-text message.
+
+A blob or message whose signature verifies but which is encrypted to another key returns "not encrypted to this key source". A message URL that does not decode returns "Malformed message URL" and names the broken segment.
+
+Docs: [quantsafe.tech/mcp](https://quantsafe.tech/mcp)

package/dist/lib/qsafe/aead.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aeadEncrypt = aeadEncrypt;
+exports.aeadDecrypt = aeadDecrypt;
+const constants_1 = require("./constants");
+function getSubtle() {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        throw new Error('WebCrypto SubtleCrypto is not available in this environment');
+    }
+    return subtle;
+}
+function toArrayBuffer(u8) {
+    const buf = new ArrayBuffer(u8.byteLength);
+    new Uint8Array(buf).set(u8);
+    return buf;
+}
+async function importAesKey(key, usage) {
+    if (key.length !== constants_1.AES_KEY_LEN) {
+        throw new Error(`AES key must be ${constants_1.AES_KEY_LEN} bytes, got ${key.length}`);
+    }
+    return getSubtle().importKey('raw', toArrayBuffer(key), { name: 'AES-GCM' }, false, [usage]);
+}
+async function aeadEncrypt(key, nonce, plaintext, aad) {
+    if (nonce.length !== constants_1.NONCE_LEN) {
+        throw new Error(`Nonce must be ${constants_1.NONCE_LEN} bytes, got ${nonce.length}`);
+    }
+    const cryptoKey = await importAesKey(key, 'encrypt');
+    const ct = await getSubtle().encrypt({ name: 'AES-GCM', iv: toArrayBuffer(nonce), additionalData: toArrayBuffer(aad) }, cryptoKey, toArrayBuffer(plaintext));
+    return new Uint8Array(ct);
+}
+async function aeadDecrypt(key, nonce, ciphertext, aad) {
+    if (nonce.length !== constants_1.NONCE_LEN) {
+        throw new Error(`Nonce must be ${constants_1.NONCE_LEN} bytes, got ${nonce.length}`);
+    }
+    const cryptoKey = await importAesKey(key, 'decrypt');
+    const pt = await getSubtle().decrypt({ name: 'AES-GCM', iv: toArrayBuffer(nonce), additionalData: toArrayBuffer(aad) }, cryptoKey, toArrayBuffer(ciphertext));
+    return new Uint8Array(pt);
+}

package/dist/lib/qsafe/codec.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildHeaderAad = buildHeaderAad;
+exports.encode = encode;
+exports.decode = decode;
+const constants_1 = require("./constants");
+const types_1 = require("./types");
+const HEADER_FIXED_LEN = constants_1.MAGIC_LEN + 2 + 2 + constants_1.ML_KEM_CT_LEN + constants_1.X25519_PK_LEN + constants_1.NONCE_LEN + 8;
+function writeU16LE(view, offset, value) {
+    view.setUint16(offset, value, true);
+}
+function writeU64LE(view, offset, value) {
+    view.setBigUint64(offset, value, true);
+}
+function readU16LE(view, offset) {
+    return view.getUint16(offset, true);
+}
+function readU64LE(view, offset) {
+    return view.getBigUint64(offset, true);
+}
+function buildHeaderAad(container) {
+    const out = new Uint8Array(HEADER_FIXED_LEN);
+    const view = new DataView(out.buffer, out.byteOffset, out.byteLength);
+    let o = 0;
+    out.set(constants_1.MAGIC, o);
+    o += constants_1.MAGIC_LEN;
+    writeU16LE(view, o, container.version);
+    o += 2;
+    writeU16LE(view, o, container.algoId);
+    o += 2;
+    out.set(container.kemCtPq, o);
+    o += constants_1.ML_KEM_CT_LEN;
+    out.set(container.kemCtCls, o);
+    o += constants_1.X25519_PK_LEN;
+    out.set(container.nonce, o);
+    o += constants_1.NONCE_LEN;
+    writeU64LE(view, o, container.aeadPayloadLen);
+    return out;
+}
+function encode(container) {
+    if (container.kemCtPq.length !== constants_1.ML_KEM_CT_LEN) {
+        throw new Error(`KEM PQ ciphertext must be ${constants_1.ML_KEM_CT_LEN} bytes`);
+    }
+    if (container.kemCtCls.length !== constants_1.X25519_PK_LEN) {
+        throw new Error(`KEM classical ciphertext must be ${constants_1.X25519_PK_LEN} bytes`);
+    }
+    if (container.nonce.length !== constants_1.NONCE_LEN) {
+        throw new Error(`Nonce must be ${constants_1.NONCE_LEN} bytes`);
+    }
+    if (container.signature.length > 0xffff) {
+        throw new Error('Signature too long (>64KB)');
+    }
+    const aeadLen = BigInt(container.aeadPayload.length);
+    const header = buildHeaderAad({
+        version: container.version,
+        algoId: container.algoId,
+        kemCtPq: container.kemCtPq,
+        kemCtCls: container.kemCtCls,
+        nonce: container.nonce,
+        aeadPayloadLen: aeadLen,
+    });
+    const total = header.length + container.aeadPayload.length + 2 + container.signature.length;
+    const out = new Uint8Array(total);
+    const view = new DataView(out.buffer, out.byteOffset, out.byteLength);
+    let o = 0;
+    out.set(header, o);
+    o += header.length;
+    out.set(container.aeadPayload, o);
+    o += container.aeadPayload.length;
+    writeU16LE(view, o, container.signature.length);
+    o += 2;
+    out.set(container.signature, o);
+    return out;
+}
+function decode(bytes) {
+    if (bytes.length < HEADER_FIXED_LEN + 2) {
+        throw new types_1.CorruptFileError('Input too short for .qsafe header');
+    }
+    for (let i = 0; i < constants_1.MAGIC_LEN; i++) {
+        if (bytes[i] !== constants_1.MAGIC[i]) {
+            throw new types_1.CorruptFileError('Bad magic bytes (not a .qsafe file)');
+        }
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let o = constants_1.MAGIC_LEN;
+    const version = readU16LE(view, o);
+    o += 2;
+    if (version !== constants_1.VERSION) {
+        throw new types_1.CorruptFileError(`Unsupported version ${version} (this build expects ${constants_1.VERSION})`);
+    }
+    const algoIdNum = readU16LE(view, o);
+    o += 2;
+    if (algoIdNum !== constants_1.ALGO_ID.HYBRID_V1) {
+        throw new types_1.CorruptFileError(`Unknown algorithm suite 0x${algoIdNum.toString(16)}`);
+    }
+    const kemCtPq = bytes.slice(o, o + constants_1.ML_KEM_CT_LEN);
+    o += constants_1.ML_KEM_CT_LEN;
+    const kemCtCls = bytes.slice(o, o + constants_1.X25519_PK_LEN);
+    o += constants_1.X25519_PK_LEN;
+    const nonce = bytes.slice(o, o + constants_1.NONCE_LEN);
+    o += constants_1.NONCE_LEN;
+    const aeadLenBig = readU64LE(view, o);
+    o += 8;
+    if (aeadLenBig > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new types_1.CorruptFileError('AEAD payload length exceeds safe range');
+    }
+    const aeadLen = Number(aeadLenBig);
+    if (bytes.length < o + aeadLen + 2) {
+        throw new types_1.CorruptFileError('Truncated AEAD payload');
+    }
+    const aeadPayload = bytes.slice(o, o + aeadLen);
+    o += aeadLen;
+    const sigLen = readU16LE(view, o);
+    o += 2;
+    if (bytes.length < o + sigLen) {
+        throw new types_1.CorruptFileError('Truncated signature');
+    }
+    const signature = bytes.slice(o, o + sigLen);
+    o += sigLen;
+    if (o !== bytes.length) {
+        throw new types_1.CorruptFileError(`Trailing bytes after signature (${bytes.length - o} bytes)`);
+    }
+    return {
+        version,
+        algoId: algoIdNum,
+        kemCtPq,
+        kemCtCls,
+        nonce,
+        aeadPayload,
+        signature,
+    };
+}

package/dist/lib/qsafe/constants.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_MESSAGE_PLAINTEXT = exports.ARGON2ID_SALT_LEN = exports.ARGON2ID_PARAMS_PROD = exports.AES_GCM_TAG_LEN = exports.NONCE_LEN = exports.AES_KEY_LEN = exports.ML_DSA_SIG_LEN = exports.ML_DSA_SK_LEN = exports.ML_DSA_PK_LEN = exports.ML_DSA_SEED_LEN = exports.X25519_SK_LEN = exports.X25519_PK_LEN = exports.ML_KEM_CT_LEN = exports.ML_KEM_SK_LEN = exports.ML_KEM_PK_LEN = exports.ML_KEM_SEED_LEN = exports.WALLET_KDF_MESSAGE = exports.KEYFILE_AAD = exports.HKDF_INFO_KEYFILE_WRAP = exports.HKDF_INFO_AES_KEY = exports.HKDF_INFO_MLDSA_SEED = exports.HKDF_INFO_X25519_SEED = exports.HKDF_INFO_MLKEM_SEED = exports.HKDF_SALT_HYBRID = exports.HKDF_SALT = exports.X402_CONTEXT = exports.MESSAGE_CONTEXT = exports.FILE_CONTEXT = exports.ALGO_ID = exports.VERSION = exports.MAGIC_LEN = exports.MAGIC = void 0;
+exports.MAGIC = new Uint8Array([0x51, 0x53, 0x41, 0x46, 0x45]);
+exports.MAGIC_LEN = 5;
+exports.VERSION = 1;
+exports.ALGO_ID = {
+    HYBRID_V1: 0x0001,
+};
+exports.FILE_CONTEXT = 'qsafe-v1-file';
+exports.MESSAGE_CONTEXT = 'qsafe-v1-message';
+exports.X402_CONTEXT = 'qsafe-v1-x402';
+exports.HKDF_SALT = 'qsafe-v1';
+exports.HKDF_SALT_HYBRID = 'qsafe-v1-hybrid';
+exports.HKDF_INFO_MLKEM_SEED = 'mlkem-seed';
+exports.HKDF_INFO_X25519_SEED = 'x25519-seed';
+exports.HKDF_INFO_MLDSA_SEED = 'mldsa-seed';
+exports.HKDF_INFO_AES_KEY = 'aes-256-gcm';
+exports.HKDF_INFO_KEYFILE_WRAP = 'keyfile-wrap-key';
+exports.KEYFILE_AAD = 'qsafe-keyfile-v1';
+exports.WALLET_KDF_MESSAGE = 'qsafe-key-derivation-v1';
+exports.ML_KEM_SEED_LEN = 64;
+exports.ML_KEM_PK_LEN = 1184;
+exports.ML_KEM_SK_LEN = 2400;
+exports.ML_KEM_CT_LEN = 1088;
+exports.X25519_PK_LEN = 32;
+exports.X25519_SK_LEN = 32;
+exports.ML_DSA_SEED_LEN = 32;
+exports.ML_DSA_PK_LEN = 1952;
+exports.ML_DSA_SK_LEN = 4032;
+exports.ML_DSA_SIG_LEN = 3309;
+exports.AES_KEY_LEN = 32;
+exports.NONCE_LEN = 12;
+exports.AES_GCM_TAG_LEN = 16;
+exports.ARGON2ID_PARAMS_PROD = { t: 3, m: 65536, p: 1 };
+exports.ARGON2ID_SALT_LEN = 16;
+exports.MAX_MESSAGE_PLAINTEXT = 64 * 1024;

package/dist/lib/qsafe/crypto.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hybridEncapsulate = hybridEncapsulate;
+exports.hybridDecapsulate = hybridDecapsulate;
+exports.sign = sign;
+exports.verify = verify;
+const ed25519_1 = require("@noble/curves/ed25519");
+const utils_1 = require("@noble/hashes/utils");
+const ml_dsa_1 = require("@noble/post-quantum/ml-dsa");
+const ml_kem_1 = require("@noble/post-quantum/ml-kem");
+const constants_1 = require("./constants");
+const hkdf_1 = require("./hkdf");
+const utf8 = new TextEncoder();
+function combineSharedSecrets(ssPq, ssCls) {
+    const ikm = new Uint8Array(ssPq.length + ssCls.length);
+    ikm.set(ssPq, 0);
+    ikm.set(ssCls, ssPq.length);
+    return (0, hkdf_1.hkdfDerive)(ikm, constants_1.HKDF_SALT_HYBRID, constants_1.HKDF_INFO_AES_KEY, constants_1.AES_KEY_LEN);
+}
+function hybridEncapsulate(recipient) {
+    const pq = ml_kem_1.ml_kem768.encapsulate(recipient.mlkem);
+    const ephSk = (0, utils_1.randomBytes)(constants_1.X25519_SK_LEN);
+    const ephPk = ed25519_1.x25519.getPublicKey(ephSk);
+    const ssCls = ed25519_1.x25519.getSharedSecret(ephSk, recipient.x25519);
+    const aesKey = combineSharedSecrets(pq.sharedSecret, ssCls);
+    return {
+        kemCtPq: pq.cipherText,
+        kemCtCls: ephPk,
+        aesKey,
+    };
+}
+function hybridDecapsulate(sk, kemCtPq, kemCtCls) {
+    const ssPq = ml_kem_1.ml_kem768.decapsulate(kemCtPq, sk.mlkem);
+    const ssCls = ed25519_1.x25519.getSharedSecret(sk.x25519, kemCtCls);
+    return combineSharedSecrets(ssPq, ssCls);
+}
+function sign(secretKey, msg, context) {
+    const signer = ml_dsa_1.ml_dsa65.sign;
+    return signer(secretKey, msg, utf8.encode(context));
+}
+function verify(publicKey, msg, signature, context) {
+    const verifier = ml_dsa_1.ml_dsa65.verify;
+    return verifier(publicKey, msg, signature, utf8.encode(context));
+}

package/dist/lib/qsafe/file.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encryptFile = encryptFile;
+exports.decryptFile = decryptFile;
+const utils_1 = require("@noble/hashes/utils");
+const aead_1 = require("./aead");
+const codec_1 = require("./codec");
+const constants_1 = require("./constants");
+const crypto_1 = require("./crypto");
+const types_1 = require("./types");
+const utf8Encoder = new TextEncoder();
+const utf8Decoder = new TextDecoder('utf-8', { fatal: true });
+function packAeadPlaintext(fileBytes, filename) {
+    const filenameBytes = utf8Encoder.encode(filename);
+    if (filenameBytes.length > 0xffff) {
+        throw new Error('Filename too long (>64KB UTF-8)');
+    }
+    const out = new Uint8Array(2 + filenameBytes.length + 8 + fileBytes.length);
+    const view = new DataView(out.buffer, out.byteOffset, out.byteLength);
+    let o = 0;
+    view.setUint16(o, filenameBytes.length, true);
+    o += 2;
+    out.set(filenameBytes, o);
+    o += filenameBytes.length;
+    view.setBigUint64(o, BigInt(fileBytes.length), true);
+    o += 8;
+    out.set(fileBytes, o);
+    return out;
+}
+function unpackAeadPlaintext(plaintext) {
+    if (plaintext.length < 10) {
+        throw new types_1.SignatureError();
+    }
+    const view = new DataView(plaintext.buffer, plaintext.byteOffset, plaintext.byteLength);
+    let o = 0;
+    const filenameLen = view.getUint16(o, true);
+    o += 2;
+    if (plaintext.length < o + filenameLen + 8) {
+        throw new types_1.SignatureError();
+    }
+    const filename = utf8Decoder.decode(plaintext.slice(o, o + filenameLen));
+    o += filenameLen;
+    const originalSize = view.getBigUint64(o, true);
+    o += 8;
+    const fileBytes = plaintext.slice(o);
+    if (BigInt(fileBytes.length) !== originalSize) {
+        throw new types_1.SignatureError();
+    }
+    return { fileBytes, filename, originalSize };
+}
+async function encryptFile(fileBytes, filename, recipient, signer) {
+    const { kemCtPq, kemCtCls, aesKey } = (0, crypto_1.hybridEncapsulate)(recipient);
+    const nonce = (0, utils_1.randomBytes)(constants_1.NONCE_LEN);
+    const aeadPlaintext = packAeadPlaintext(fileBytes, filename);
+    const header = (0, codec_1.buildHeaderAad)({
+        version: constants_1.VERSION,
+        algoId: constants_1.ALGO_ID.HYBRID_V1,
+        kemCtPq,
+        kemCtCls,
+        nonce,
+        aeadPayloadLen: BigInt(aeadPlaintext.length + 16),
+    });
+    const aeadPayload = await (0, aead_1.aeadEncrypt)(aesKey, nonce, aeadPlaintext, header);
+    const signedBytes = new Uint8Array(header.length + aeadPayload.length);
+    signedBytes.set(header, 0);
+    signedBytes.set(aeadPayload, header.length);
+    const signature = (0, crypto_1.sign)(signer.mldsa, signedBytes, constants_1.FILE_CONTEXT);
+    return (0, codec_1.encode)({
+        version: constants_1.VERSION,
+        algoId: constants_1.ALGO_ID.HYBRID_V1,
+        kemCtPq,
+        kemCtCls,
+        nonce,
+        aeadPayload,
+        signature,
+    });
+}
+async function decryptFile(qsafeBytes, recipient, expectedSigner) {
+    const container = (0, codec_1.decode)(qsafeBytes);
+    const header = (0, codec_1.buildHeaderAad)({
+        version: container.version,
+        algoId: container.algoId,
+        kemCtPq: container.kemCtPq,
+        kemCtCls: container.kemCtCls,
+        nonce: container.nonce,
+        aeadPayloadLen: BigInt(container.aeadPayload.length),
+    });
+    const signedBytes = new Uint8Array(header.length + container.aeadPayload.length);
+    signedBytes.set(header, 0);
+    signedBytes.set(container.aeadPayload, header.length);
+    if (!(0, crypto_1.verify)(expectedSigner.mldsa, signedBytes, container.signature, constants_1.FILE_CONTEXT)) {
+        throw new types_1.SignatureError();
+    }
+    const aesKey = (0, crypto_1.hybridDecapsulate)(recipient, container.kemCtPq, container.kemCtCls);
+    const plaintext = await (0, aead_1.aeadDecrypt)(aesKey, container.nonce, container.aeadPayload, header);
+    return unpackAeadPlaintext(plaintext);
+}

package/dist/lib/qsafe/hkdf.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hkdfDerive = hkdfDerive;
+const hkdf_1 = require("@noble/hashes/hkdf");
+const sha2_1 = require("@noble/hashes/sha2");
+const utf8 = new TextEncoder();
+function hkdfDerive(ikm, salt, info, length) {
+    return (0, hkdf_1.hkdf)(sha2_1.sha256, ikm, utf8.encode(salt), utf8.encode(info), length);
+}

package/dist/lib/qsafe/index.js

@@ -0,0 +1,44 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapKeyfile = exports.unwrapKeyfile = exports.encryptFile = exports.decryptFile = exports.encode = exports.decode = exports.buildHeaderAad = exports.verify = exports.sign = exports.hybridEncapsulate = exports.hybridDecapsulate = exports.aeadEncrypt = exports.aeadDecrypt = exports.keysFromSeeds = exports.deriveSeedsFromWalletSignature = exports.deriveSeedsFromRandomness = exports.deriveSeedsFromIkm = exports.assertEoaSignatureShape = void 0;
+__exportStar(require("./constants"), exports);
+__exportStar(require("./types"), exports);
+var kdf_1 = require("./kdf");
+Object.defineProperty(exports, "assertEoaSignatureShape", { enumerable: true, get: function () { return kdf_1.assertEoaSignatureShape; } });
+Object.defineProperty(exports, "deriveSeedsFromIkm", { enumerable: true, get: function () { return kdf_1.deriveSeedsFromIkm; } });
+Object.defineProperty(exports, "deriveSeedsFromRandomness", { enumerable: true, get: function () { return kdf_1.deriveSeedsFromRandomness; } });
+Object.defineProperty(exports, "deriveSeedsFromWalletSignature", { enumerable: true, get: function () { return kdf_1.deriveSeedsFromWalletSignature; } });
+var keys_1 = require("./keys");
+Object.defineProperty(exports, "keysFromSeeds", { enumerable: true, get: function () { return keys_1.keysFromSeeds; } });
+var aead_1 = require("./aead");
+Object.defineProperty(exports, "aeadDecrypt", { enumerable: true, get: function () { return aead_1.aeadDecrypt; } });
+Object.defineProperty(exports, "aeadEncrypt", { enumerable: true, get: function () { return aead_1.aeadEncrypt; } });
+var crypto_1 = require("./crypto");
+Object.defineProperty(exports, "hybridDecapsulate", { enumerable: true, get: function () { return crypto_1.hybridDecapsulate; } });
+Object.defineProperty(exports, "hybridEncapsulate", { enumerable: true, get: function () { return crypto_1.hybridEncapsulate; } });
+Object.defineProperty(exports, "sign", { enumerable: true, get: function () { return crypto_1.sign; } });
+Object.defineProperty(exports, "verify", { enumerable: true, get: function () { return crypto_1.verify; } });
+var codec_1 = require("./codec");
+Object.defineProperty(exports, "buildHeaderAad", { enumerable: true, get: function () { return codec_1.buildHeaderAad; } });
+Object.defineProperty(exports, "decode", { enumerable: true, get: function () { return codec_1.decode; } });
+Object.defineProperty(exports, "encode", { enumerable: true, get: function () { return codec_1.encode; } });
+var file_1 = require("./file");
+Object.defineProperty(exports, "decryptFile", { enumerable: true, get: function () { return file_1.decryptFile; } });
+Object.defineProperty(exports, "encryptFile", { enumerable: true, get: function () { return file_1.encryptFile; } });
+var keyfile_1 = require("./keyfile");
+Object.defineProperty(exports, "unwrapKeyfile", { enumerable: true, get: function () { return keyfile_1.unwrapKeyfile; } });
+Object.defineProperty(exports, "wrapKeyfile", { enumerable: true, get: function () { return keyfile_1.wrapKeyfile; } });

package/dist/lib/qsafe/kdf.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveSeedsFromIkm = deriveSeedsFromIkm;
+exports.assertEoaSignatureShape = assertEoaSignatureShape;
+exports.deriveSeedsFromWalletSignature = deriveSeedsFromWalletSignature;
+exports.deriveSeedsFromRandomness = deriveSeedsFromRandomness;
+const utils_1 = require("@noble/hashes/utils");
+const constants_1 = require("./constants");
+const hkdf_1 = require("./hkdf");
+function hexToBytes(hex) {
+    const clean = hex.startsWith('0x') || hex.startsWith('0X') ? hex.slice(2) : hex;
+    if (clean.length % 2 !== 0) {
+        throw new Error('Invalid hex string: odd length');
+    }
+    const out = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        const byte = Number.parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+        if (Number.isNaN(byte)) {
+            throw new Error('Invalid hex string');
+        }
+        out[i] = byte;
+    }
+    return out;
+}
+function deriveSeedsFromIkm(ikm) {
+    if (ikm.length === 0) {
+        throw new Error('IKM must be non-empty');
+    }
+    return {
+        mlkem: (0, hkdf_1.hkdfDerive)(ikm, constants_1.HKDF_SALT, constants_1.HKDF_INFO_MLKEM_SEED, constants_1.ML_KEM_SEED_LEN),
+        x25519: (0, hkdf_1.hkdfDerive)(ikm, constants_1.HKDF_SALT, constants_1.HKDF_INFO_X25519_SEED, constants_1.X25519_SK_LEN),
+        mldsa: (0, hkdf_1.hkdfDerive)(ikm, constants_1.HKDF_SALT, constants_1.HKDF_INFO_MLDSA_SEED, constants_1.ML_DSA_SEED_LEN),
+    };
+}
+const EOA_SIG_HEX_RE = /^0x[0-9a-fA-F]{130}$/;
+function assertEoaSignatureShape(signatureHex) {
+    if (!EOA_SIG_HEX_RE.test(signatureHex)) {
+        throw new Error('Wallet signature must be a 65-byte EOA signature (0x + 130 hex chars). ' +
+            'Smart-contract wallet signatures are not supported for key derivation.');
+    }
+}
+function deriveSeedsFromWalletSignature(signatureHex) {
+    assertEoaSignatureShape(signatureHex);
+    return deriveSeedsFromIkm(hexToBytes(signatureHex));
+}
+function deriveSeedsFromRandomness() {
+    return {
+        mlkem: (0, utils_1.randomBytes)(constants_1.ML_KEM_SEED_LEN),
+        x25519: (0, utils_1.randomBytes)(constants_1.X25519_SK_LEN),
+        mldsa: (0, utils_1.randomBytes)(constants_1.ML_DSA_SEED_LEN),
+    };
+}