@quantsafe/mcp 0.0.0-stage → 0.1.0

package/dist/mcp/message-url.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MESSAGE_URL_PREFIX = exports.MESSAGE_URL_BASE = void 0;
+exports.buildMessageUrl = buildMessageUrl;
+exports.parseMessageUrl = parseMessageUrl;
+const base64_1 = require("./base64");
+const constants_1 = require("../lib/qsafe/constants");
+exports.MESSAGE_URL_BASE = 'https://quantsafe.tech/m/#';
+exports.MESSAGE_URL_PREFIX = 'v1.';
+const PUBLIC_KEY_LENGTHS = {
+    mlkem: constants_1.ML_KEM_PK_LEN,
+    x25519: constants_1.X25519_PK_LEN,
+    mldsa: constants_1.ML_DSA_PK_LEN,
+};
+const SECRET_KEY_LENGTHS = {
+    mlkem: constants_1.ML_KEM_SK_LEN,
+    x25519: constants_1.X25519_SK_LEN,
+    mldsa: constants_1.ML_DSA_SK_LEN,
+};
+function malformed(segment) {
+    return new Error(`Malformed message URL: the ${segment} segment does not decode.`);
+}
+function serializeKey(obj) {
+    const out = {};
+    for (const k of Object.keys(obj)) {
+        out[k] = (0, base64_1.base64urlEncode)(obj[k]);
+    }
+    return JSON.stringify(out);
+}
+function encodeKey(key) {
+    return (0, base64_1.base64urlEncode)(new TextEncoder().encode(serializeKey(key)));
+}
+// A segment that decodes to the wrong shape would otherwise surface later as a parser or
+// WebCrypto message that says nothing about the URL. Fields beyond the three are ignored.
+function decodeKey(s, segment, lengths) {
+    let obj;
+    try {
+        obj = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode((0, base64_1.base64urlDecode)(s, segment)));
+    }
+    catch {
+        throw malformed(segment);
+    }
+    if (typeof obj !== 'object' || obj === null || Array.isArray(obj))
+        throw malformed(segment);
+    const fields = obj;
+    const out = {};
+    for (const [name, length] of Object.entries(lengths)) {
+        const value = fields[name];
+        if (typeof value !== 'string')
+            throw malformed(segment);
+        let bytes;
+        try {
+            bytes = (0, base64_1.base64urlDecode)(value, segment);
+        }
+        catch {
+            throw malformed(segment);
+        }
+        if (bytes.length !== length)
+            throw malformed(segment);
+        out[name] = bytes;
+    }
+    return out;
+}
+function buildMessageUrl(blob, signerPublic, embed) {
+    const parts = [exports.MESSAGE_URL_PREFIX + (0, base64_1.base64urlEncode)(blob), encodeKey(signerPublic)];
+    if (embed) {
+        parts.push(encodeKey(embed.sk));
+        parts.push(encodeKey(embed.pk));
+    }
+    return exports.MESSAGE_URL_BASE + parts.join('.');
+}
+function parseMessageUrl(url) {
+    if (typeof url !== 'string')
+        throw new Error('Malformed message URL: url must be a string.');
+    const hashIdx = url.indexOf('#');
+    if (hashIdx === -1)
+        throw new Error('Message URL missing fragment');
+    const frag = url.slice(hashIdx + 1);
+    if (!frag.startsWith(exports.MESSAGE_URL_PREFIX)) {
+        throw new Error('Unsupported message URL version');
+    }
+    const rest = frag.slice(exports.MESSAGE_URL_PREFIX.length);
+    const segs = rest.split('.');
+    if (segs.length !== 2 && segs.length !== 4) {
+        throw new Error('Malformed message URL');
+    }
+    let blob;
+    try {
+        blob = (0, base64_1.base64urlDecode)(segs[0], 'envelope');
+    }
+    catch {
+        throw malformed('envelope');
+    }
+    const signerPublic = decodeKey(segs[1], 'signer key', PUBLIC_KEY_LENGTHS);
+    if (segs.length === 2) {
+        return { blob, signerPublic };
+    }
+    const sk = decodeKey(segs[2], 'embedded secret key', SECRET_KEY_LENGTHS);
+    const pk = decodeKey(segs[3], 'embedded public key', PUBLIC_KEY_LENGTHS);
+    return { blob, signerPublic, ephemeralSecret: sk, ephemeralPublic: pk };
+}

package/dist/mcp/server.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const zod_1 = require("zod");
+const tools_1 = require("./tools");
+const tool_result_1 = require("./tool-result");
+const KEYFILE_SCHEMA = zod_1.z.object({
+    v: zod_1.z.literal(1),
+    kdf: zod_1.z.literal('argon2id'),
+    kdfParams: zod_1.z.object({ t: zod_1.z.number(), m: zod_1.z.number(), p: zod_1.z.number() }),
+    salt: zod_1.z.string(),
+    nonce: zod_1.z.string(),
+    wrapped: zod_1.z.string(),
+});
+const SIG_HEX_RE = /^0x[0-9a-fA-F]{130}$/;
+// 65-byte EOA signature (r||s||v), 0x-prefixed. Smart-contract wallet
+// signatures are rejected: they are non-deterministic and cannot derive a
+// stable keypair. This is root key material, pass it over local stdio only.
+// The message is written as a JSON string so its line breaks are unambiguous: a signature over
+// any other text recovers to another address and is refused.
+const SIG_HEX = zod_1.z
+    .string()
+    .regex(SIG_HEX_RE, 'signature_hex must be a 65-byte EOA signature (0x + 130 hex chars)')
+    .describe(`65-byte EOA signature (0x + 130 hex chars) made with personal_sign (EIP-191) over this exact message, written here as a JSON string (lines joined by \\n, no trailing newline): ${JSON.stringify(tools_1.QSAFE_DERIVATION_MESSAGE)}. The browser app derives the same identity from the same signature. The signer is recovered and must equal the address passed with it. Pass the 65 bytes exactly as your wallet returned them: the identity is derived from those bytes, recovery byte (v) included, as in the browser app, so a signature rewritten from 0/1 to 27/28 (or back) derives a different identity. Root key material: local stdio only.`);
+const ADDRESS = zod_1.z
+    .string()
+    .regex(/^0x[0-9a-fA-F]{40}$/, 'address must be an EVM address (0x + 40 hex chars)')
+    .describe('The EOA address that made the signature. Required with it.');
+const SIG_HEX_REPEAT = zod_1.z
+    .string()
+    .regex(SIG_HEX_RE, 'signature_hex_repeat must be a 65-byte EOA signature (0x + 130 hex chars)')
+    .describe('Optional second signature of the same message by the same wallet. It must equal the first: MPC and threshold signers produce a different valid signature each time, and keys derived from them change between sessions. Pass it the first time a wallet is used.');
+const KEY_SOURCE = {
+    keyfile_json: KEYFILE_SCHEMA.optional(),
+    passphrase: zod_1.z.string().optional(),
+    signature_hex: SIG_HEX.optional(),
+    address: ADDRESS.optional(),
+    signature_hex_repeat: SIG_HEX_REPEAT.optional(),
+};
+const SIGNER_KEY_SOURCE = {
+    signer_keyfile_json: KEYFILE_SCHEMA.optional(),
+    signer_passphrase: zod_1.z.string().optional(),
+    signer_signature_hex: SIG_HEX.optional(),
+    signer_address: ADDRESS.optional(),
+    signer_signature_hex_repeat: SIG_HEX_REPEAT.optional(),
+};
+const BASE64 = 'Standard base64 (A-Z, a-z, 0-9, +, / with = padding, no whitespace).';
+const RECIPIENT_PUBKEY = `The recipient's hybrid public key. ${BASE64} It decodes to 3168 bytes: ML-KEM-768 (1184) || X25519 (32) || ML-DSA-65 (1952). It is the signer_pubkey_base64 that qsafe_sign_x402 or qsafe_encrypt_file returns when the recipient signs with its own keyfile or wallet signature: ask the recipient for that value.`;
+// A signature over a v1 envelope covers only the envelope bytes: nothing about the signer is
+// bound into the AEAD or the KEM, so a signature can be stripped and replaced.
+const SIGNER_IS_NOT_AUTHOR = 'A verified signature shows which key signed this envelope, not who wrote its contents: anyone who sees an envelope can re-sign it with their own key.';
+async function main() {
+    const server = new mcp_js_1.McpServer({ name: 'qsafe-mcp', version: '0.1.0' }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    server.registerTool('qsafe_encrypt_file', {
+        description: 'Encrypt bytes with the QuantSafe v1 hybrid PQC suite (ML-KEM-768 + X25519 + ML-DSA-65) to recipient_pubkey_base64. bytes_base64 must be standard base64 of the raw bytes; text or any other encoding is rejected. Returns a .qsafe blob, a Quantum Seal PNG (a 1x1 image whose text chunks carry the Seal fields, file_hash included; no rendered card) and signer_pubkey_base64; share signer_pubkey_base64 with the recipient, who needs it to decrypt. Sign as your wallet identity with signer_signature_hex + signer_address (personal_sign of the QuantSafe derivation message, quoted in the signer_signature_hex field description), or with signer_keyfile_json + signer_passphrase; omit every signer field for an anonymous ephemeral signer. A partial or doubled key source is rejected. Local stdio only.',
+        inputSchema: {
+            bytes_base64: zod_1.z.string().describe(`The bytes to encrypt. ${BASE64}`),
+            recipient_pubkey_base64: zod_1.z.string().describe(RECIPIENT_PUBKEY),
+            ...SIGNER_KEY_SOURCE,
+        },
+    }, async (args) => (0, tool_result_1.toolResult)(await (0, tools_1.qsafeEncryptFile)(args)));
+    server.registerTool('qsafe_decrypt_file', {
+        description: `Decrypt a .qsafe blob. Provide the recipient identity as keyfile_json + passphrase, or as signature_hex + address (personal_sign of the QuantSafe derivation message by that EOA). The ML-DSA-65 signature is always verified before decryption, and the blob does not carry its signer's key: pass the sender's signer_pubkey_base64 as expected_signer_pubkey_base64. It may be omitted only for a file you signed with the same key you decrypt with. ${SIGNER_IS_NOT_AUTHOR}`,
+        inputSchema: {
+            blob_base64: zod_1.z.string().describe(`The .qsafe envelope. ${BASE64}`),
+            ...KEY_SOURCE,
+            expected_signer_pubkey_base64: zod_1.z
+                .string()
+                .optional()
+                .describe("The sender's signer_pubkey_base64, as returned by qsafe_encrypt_file. Required unless the file was signed with the recipient's own key."),
+        },
+    }, async (args) => (0, tool_result_1.toolResult)(await (0, tools_1.qsafeDecryptFile)(args)));
+    server.registerTool('qsafe_send_message', {
+        description: 'Encrypt a UTF-8 message into a shareable URL. Returns url and mode. With recipient_pubkey_base64, only that key opens it (mode "recipient"). Without it, the URL carries its own decryption key and anyone holding the URL can read the message (mode "anyone_with_link"); an empty or malformed recipient_pubkey_base64 is rejected, never treated as omitted. Sign as your wallet identity with signer_signature_hex + signer_address, or with a keyfile, so a recipient who already knows your signer_pubkey_base64 can pin it; omit every signer field for an anonymous ephemeral signer. A partial or doubled key source is rejected.',
+        inputSchema: {
+            text: zod_1.z.string(),
+            recipient_pubkey_base64: zod_1.z
+                .string()
+                .optional()
+                .describe(`${RECIPIENT_PUBKEY} Omit it only for a URL that anyone holding it can read.`),
+            ...SIGNER_KEY_SOURCE,
+        },
+    }, async (args) => (0, tool_result_1.toolResult)(await (0, tools_1.qsafeSendMessage)(args)));
+    server.registerTool('qsafe_decrypt_message', {
+        description: `Decrypt a QuantSafe message URL and return its text and the key that signed it. URLs that carry their own key need no key source; recipient-mode URLs require keyfile_json + passphrase, or signature_hex + address. The URL names its own signer key, so the returned signer_pubkey_base64 is only the key the URL claims. Pass a key you already trust as expected_signer_pubkey_base64 and a URL signed by any other key is refused. ${SIGNER_IS_NOT_AUTHOR}`,
+        inputSchema: {
+            url: zod_1.z.string(),
+            ...KEY_SOURCE,
+            expected_signer_pubkey_base64: zod_1.z
+                .string()
+                .optional()
+                .describe('The signer_pubkey_base64 you expect, known from outside this URL. When given, a URL signed by any other key is refused. It confirms the signing key, not who wrote the text.'),
+        },
+    }, async (args) => (0, tool_result_1.toolResult)(await (0, tools_1.qsafeDecryptMessage)(args)));
+    server.registerTool('qsafe_verify_seal', {
+        description: 'Parse a Quantum Seal PNG and return the fields it carries (version, timestamp, algo, file_hash, optional x402 receipt fields, optional on-chain anchor fields). No Seal field is signed: every one is a claim anyone can write into a PNG. valid only means at least one Seal field was found; it checks nothing. This tool does not contact the chain. Pass the .qsafe envelope as blob_base64 to get file_hash_matches, true when sha256 of that envelope equals the Seal file_hash: the only check this tool makes. Who signed the envelope is checked when it is decrypted.',
+        inputSchema: {
+            png_base64: zod_1.z.string().describe(`The Seal PNG. ${BASE64}`),
+            blob_base64: zod_1.z
+                .string()
+                .optional()
+                .describe(`The .qsafe envelope the Seal is for. ${BASE64} When given, the result adds file_hash_matches.`),
+        },
+    }, async (args) => (0, tool_result_1.toolResult)((0, tools_1.qsafeVerifySeal)(args)));
+    server.registerTool('qsafe_sign_x402', {
+        description: 'Sign an x402 payload with ML-DSA-65 under context "qsafe-v1-x402". payload_json is a JSON object, not a JSON-encoded string. The signed bytes are the UTF-8 encoding of its canonical form: object keys sorted in JavaScript default string order at every level, no whitespace, arrays in order, strings, numbers, booleans and null as JSON.stringify writes them. Sign as your wallet identity with signature_hex + address, or with a keyfile. Local stdio only.',
+        inputSchema: {
+            payload_json: zod_1.z
+                .record(zod_1.z.string(), zod_1.z.unknown())
+                .describe('The x402 payload as a JSON object. A JSON-encoded string is rejected.'),
+            ...KEY_SOURCE,
+        },
+    }, async (args) => (0, tool_result_1.toolResult)(await (0, tools_1.qsafeSignX402)(args)));
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`qsafe-mcp fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/mcp/tool-result.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolResult = toolResult;
+// Every tool catches its own failures into { error } so the agent still gets a
+// parseable message; isError is what tells the client the call failed.
+function toolResult(value) {
+    const failed = typeof value === 'object' && value !== null && 'error' in value;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(value),
+            },
+        ],
+        isError: failed,
+    };
+}

package/dist/mcp/tools.js

@@ -0,0 +1,381 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMinimalSealPng = exports.QSAFE_DERIVATION_MESSAGE = void 0;
+exports.encodeHybridPublicKey = encodeHybridPublicKey;
+exports.decodeHybridPublicKey = decodeHybridPublicKey;
+exports.qsafeEncryptFile = qsafeEncryptFile;
+exports.qsafeDecryptFile = qsafeDecryptFile;
+exports.qsafeSendMessage = qsafeSendMessage;
+exports.qsafeDecryptMessage = qsafeDecryptMessage;
+exports.qsafeVerifySeal = qsafeVerifySeal;
+exports.qsafeSignX402 = qsafeSignX402;
+const sha2_1 = require("@noble/hashes/sha2");
+const utils_1 = require("@noble/hashes/utils");
+const base64_1 = require("./base64");
+const canonical_json_1 = require("./canonical-json");
+const png_text_1 = require("../lib/seal/png-text");
+Object.defineProperty(exports, "buildMinimalSealPng", { enumerable: true, get: function () { return png_text_1.buildMinimalSealPng; } });
+const constants_1 = require("../lib/seal/constants");
+const message_url_1 = require("./message-url");
+const wallet_identity_1 = require("./wallet-identity");
+Object.defineProperty(exports, "QSAFE_DERIVATION_MESSAGE", { enumerable: true, get: function () { return wallet_identity_1.QSAFE_DERIVATION_MESSAGE; } });
+const signer_determinism_1 = require("../lib/wallet/signer-determinism");
+const file_1 = require("../lib/qsafe/file");
+const index_1 = require("../lib/qsafe/index");
+const constants_2 = require("../lib/qsafe/constants");
+const MCP_FILE_NAME = 'mcp-file.bin';
+const MCP_MESSAGE_FILENAME = 'mcp-message.txt';
+function errorMessage(e) {
+    if (e instanceof Error)
+        return e.message;
+    return String(e);
+}
+// WebCrypto reports a failed AES-GCM tag check as an OperationError with a generic message. It
+// only runs after the ML-DSA signature has verified, so the envelope is intact and the key
+// opening it is the wrong one.
+function isAeadFailure(e) {
+    return typeof e === 'object' && e !== null && e.name === 'OperationError';
+}
+const KEY_FIELD_NAMES = {
+    keyfile: 'keyfile_json',
+    passphrase: 'passphrase',
+    signature: 'signature_hex',
+    address: 'address',
+    repeat: 'signature_hex_repeat',
+};
+const SIGNER_FIELD_NAMES = {
+    keyfile: 'signer_keyfile_json',
+    passphrase: 'signer_passphrase',
+    signature: 'signer_signature_hex',
+    address: 'signer_address',
+    repeat: 'signer_signature_hex_repeat',
+};
+// A partial or doubled key source is a caller mistake, not a request for the
+// fallback: on the signing tools the fallback is a random identity, which would
+// hand back a valid-looking artifact signed by nobody the caller controls.
+function selectKeySource(f, names) {
+    const { keyfile_json, passphrase, signature_hex, address, signature_hex_repeat } = f;
+    const walletGiven = signature_hex !== undefined || address !== undefined || signature_hex_repeat !== undefined;
+    const keyfileGiven = keyfile_json !== undefined || passphrase !== undefined;
+    if (walletGiven && keyfileGiven) {
+        throw new Error(`Conflicting key sources: supply ${names.signature} + ${names.address}, or ${names.keyfile} + ${names.passphrase}, not both.`);
+    }
+    if (walletGiven) {
+        if (signature_hex === undefined) {
+            const given = address !== undefined ? names.address : names.repeat;
+            throw new Error(`Incomplete key source: ${given} needs ${names.signature}.`);
+        }
+        if (address === undefined) {
+            throw new Error(`Incomplete key source: ${names.signature} needs ${names.address}, the EOA address that signed it.`);
+        }
+        return { kind: 'signature', signature_hex, address, repeat: signature_hex_repeat, names };
+    }
+    if (keyfile_json !== undefined && passphrase !== undefined) {
+        return { kind: 'keyfile', keyfile_json, passphrase };
+    }
+    if (keyfile_json !== undefined) {
+        throw new Error(`Incomplete key source: ${names.keyfile} needs ${names.passphrase}.`);
+    }
+    if (passphrase !== undefined) {
+        throw new Error(`Incomplete key source: ${names.passphrase} needs ${names.keyfile}.`);
+    }
+    return { kind: 'none' };
+}
+// The same guards the browser runs before it derives (constitution I): the EOA shape, then
+// recovery of the signer of the fixed derivation message. Without recovery, any 65 bytes, a
+// signature over other text or a 1-of-1 Safe owner signature included, would derive keys no
+// browser session reproduces, and files from /app would later fail as if they were altered.
+function sameRecoveryForm(signatureHex) {
+    const v = Number.parseInt(signatureHex.slice(130), 16);
+    return v === 0 || v === 1 ? `${signatureHex.slice(0, 130)}${(v + 27).toString(16)}` : signatureHex;
+}
+// Returns the bytes to derive from: the signature exactly as signed, as the browser derives it.
+function walletDerivationSignature(source) {
+    const { names } = source;
+    try {
+        (0, index_1.assertEoaSignatureShape)(source.signature_hex);
+    }
+    catch {
+        throw new Error(`${names.signature} must be a 65-byte EOA signature (0x + 130 hex chars). Smart-contract wallet signatures are not supported.`);
+    }
+    if (!wallet_identity_1.EVM_ADDRESS_RE.test(source.address)) {
+        throw new Error(`${names.address} must be an EVM address (0x + 40 hex chars).`);
+    }
+    const signer = (0, wallet_identity_1.recoverPersonalSigner)(wallet_identity_1.QSAFE_DERIVATION_MESSAGE, source.signature_hex);
+    if (signer === null || signer !== source.address.toLowerCase()) {
+        throw new Error(`${names.signature} is not a personal_sign (EIP-191) signature by ${names.address} of the QuantSafe derivation message. Sign that exact text, given in the ${names.signature} field description, with the EOA at ${names.address}. Smart-contract wallet signatures are not supported.`);
+    }
+    const signature = (0, wallet_identity_1.canonicalRecoveryByte)(source.signature_hex);
+    // MPC and threshold signers draw a fresh nonce per signature: each one recovers to the
+    // address and still derives different keys, which would lock the owner out next session.
+    // The comparison ignores how v is written (0/1 or 27/28): that is an encoding, not a nonce.
+    if (source.repeat !== undefined &&
+        !(0, signer_determinism_1.signaturesMatch)(sameRecoveryForm(signature), sameRecoveryForm((0, wallet_identity_1.canonicalRecoveryByte)(source.repeat)))) {
+        throw new Error(`${names.signature} and ${names.repeat} differ: this signer does not sign deterministically (MPC and threshold signers often sign this way), so keys derived from it would change between sessions. Use an EOA with a local private key, or a key file.`);
+    }
+    return signature;
+}
+// The signature is root key material: only pass it across a local (stdio) MCP
+// transport, never a network.
+async function keypairFromSource(source) {
+    if (source.kind === 'signature') {
+        return (0, index_1.keysFromSeeds)((0, index_1.deriveSeedsFromWalletSignature)(walletDerivationSignature(source)));
+    }
+    return (0, index_1.unwrapKeyfile)(source.keyfile_json, source.passphrase);
+}
+async function requireKeypair(f) {
+    const source = selectKeySource(f, KEY_FIELD_NAMES);
+    if (source.kind === 'none') {
+        throw new Error('No key source: supply keyfile_json + passphrase, or signature_hex + address (an EOA signature of the QuantSafe derivation message).');
+    }
+    return keypairFromSource(source);
+}
+// Omitting every signer field is the only way to get an anonymous ephemeral signer.
+async function signerKeypair(f) {
+    const source = selectKeySource(f, SIGNER_FIELD_NAMES);
+    if (source.kind === 'none')
+        return (0, index_1.keysFromSeeds)((0, index_1.deriveSeedsFromRandomness)());
+    return keypairFromSource(source);
+}
+function packHybridPublicKey(pk) {
+    const out = new Uint8Array(pk.mlkem.length + pk.x25519.length + pk.mldsa.length);
+    out.set(pk.mlkem, 0);
+    out.set(pk.x25519, pk.mlkem.length);
+    out.set(pk.mldsa, pk.mlkem.length + pk.x25519.length);
+    return out;
+}
+function unpackHybridPublicKey(bytes, label) {
+    const mlkemLen = 1184;
+    const x25519Len = 32;
+    const mldsaLen = 1952;
+    if (bytes.length !== mlkemLen + x25519Len + mldsaLen) {
+        throw new Error(`${label}: unexpected length`);
+    }
+    return {
+        mlkem: bytes.slice(0, mlkemLen),
+        x25519: bytes.slice(mlkemLen, mlkemLen + x25519Len),
+        mldsa: bytes.slice(mlkemLen + x25519Len),
+    };
+}
+function samePublicKey(a, b) {
+    const left = packHybridPublicKey(a);
+    const right = packHybridPublicKey(b);
+    return left.length === right.length && left.every((byte, i) => byte === right[i]);
+}
+function encodeHybridPublicKey(pk) {
+    return (0, base64_1.base64Encode)(packHybridPublicKey(pk));
+}
+// label names the offending field in the error, so an agent can tell a bad
+// recipient key from a bad expected signer key.
+function decodeHybridPublicKey(s, label = 'Recipient pubkey') {
+    return unpackHybridPublicKey((0, base64_1.base64Decode)(s, label), label);
+}
+async function qsafeEncryptFile(input) {
+    try {
+        if (!input.recipient_pubkey_base64) {
+            throw new Error('recipient_pubkey_base64 is required to produce a decryptable file');
+        }
+        const bytes = (0, base64_1.base64Decode)(input.bytes_base64, 'bytes_base64');
+        const signer = await signerKeypair({
+            keyfile_json: input.signer_keyfile_json,
+            passphrase: input.signer_passphrase,
+            signature_hex: input.signer_signature_hex,
+            address: input.signer_address,
+            signature_hex_repeat: input.signer_signature_hex_repeat,
+        });
+        const pub = decodeHybridPublicKey(input.recipient_pubkey_base64, 'recipient_pubkey_base64');
+        const blob = await (0, file_1.encryptFile)(bytes, MCP_FILE_NAME, pub, signer.secretKey);
+        // Same digest the web Seal carries: the anchor and /verify both key on sha256 of the envelope.
+        const seal = (0, png_text_1.buildMinimalSealPng)({
+            version: constants_1.SEAL_VERSION,
+            timestamp: new Date().toISOString(),
+            algo: constants_1.SEAL_ALGO,
+            file_hash: (0, utils_1.bytesToHex)((0, sha2_1.sha256)(blob)),
+        });
+        return {
+            blob_base64: (0, base64_1.base64Encode)(blob),
+            seal_png_base64: (0, base64_1.base64Encode)(seal),
+            signer_pubkey_base64: encodeHybridPublicKey(signer.publicKey),
+        };
+    }
+    catch (e) {
+        return { error: errorMessage(e) };
+    }
+}
+async function qsafeDecryptFile(input) {
+    try {
+        const blob = (0, base64_1.base64Decode)(input.blob_base64, 'blob_base64');
+        const kp = await requireKeypair({
+            keyfile_json: input.keyfile_json,
+            passphrase: input.passphrase,
+            signature_hex: input.signature_hex,
+            address: input.address,
+            signature_hex_repeat: input.signature_hex_repeat,
+        });
+        // The .qsafe container does not carry its signer's key, so the signature can
+        // only be checked against a key the caller supplies. Without one, the only
+        // key on hand is the recipient's own, which fits self-signed files only.
+        const signerB64 = input.expected_signer_pubkey_base64;
+        const signerGiven = signerB64 !== undefined;
+        const expectedSigner = signerGiven
+            ? decodeHybridPublicKey(signerB64, 'expected_signer_pubkey_base64')
+            : kp.publicKey;
+        let decrypted;
+        try {
+            decrypted = await (0, file_1.decryptFile)(blob, kp.secretKey, expectedSigner);
+        }
+        catch (e) {
+            if (isAeadFailure(e)) {
+                throw new Error('The file is not encrypted to this key source (keyfile_json + passphrase, or signature_hex + address): its signature verified, but this key cannot open it.');
+            }
+            if (!(e instanceof index_1.SignatureError))
+                throw e;
+            throw new Error(signerGiven
+                ? 'Signature verification failed: the file was not signed by expected_signer_pubkey_base64, or it was altered.'
+                : "Signature verification failed against the recipient's own key: the file was signed by a different key, or altered. Pass the sender's signer_pubkey_base64 (returned by qsafe_encrypt_file) as expected_signer_pubkey_base64.");
+        }
+        return {
+            plaintext_base64: (0, base64_1.base64Encode)(decrypted.fileBytes),
+            signer_pubkey_base64: encodeHybridPublicKey(expectedSigner),
+            filename: decrypted.filename,
+        };
+    }
+    catch (e) {
+        return { error: errorMessage(e) };
+    }
+}
+async function qsafeSendMessage(input) {
+    try {
+        if (typeof input.text !== 'string') {
+            throw new Error('text must be a string');
+        }
+        const textBytes = new TextEncoder().encode(input.text);
+        const signer = await signerKeypair({
+            keyfile_json: input.signer_keyfile_json,
+            passphrase: input.signer_passphrase,
+            signature_hex: input.signer_signature_hex,
+            address: input.signer_address,
+            signature_hex_repeat: input.signer_signature_hex_repeat,
+        });
+        let recipientPub;
+        let embed;
+        // Only an omitted field selects the link mode. An empty or broken key is a caller mistake,
+        // and falling back would publish the text to anyone who sees the URL.
+        if (input.recipient_pubkey_base64 === undefined) {
+            const eph = (0, index_1.keysFromSeeds)((0, index_1.deriveSeedsFromRandomness)());
+            recipientPub = eph.publicKey;
+            embed = { sk: eph.secretKey, pk: eph.publicKey };
+        }
+        else {
+            if (input.recipient_pubkey_base64 === '') {
+                throw new Error('recipient_pubkey_base64 is empty. Pass the recipient key, or omit the field for a URL anyone holding it can read.');
+            }
+            recipientPub = decodeHybridPublicKey(input.recipient_pubkey_base64, 'recipient_pubkey_base64');
+        }
+        const blob = await (0, file_1.encryptFile)(textBytes, MCP_MESSAGE_FILENAME, recipientPub, signer.secretKey);
+        return {
+            url: (0, message_url_1.buildMessageUrl)(blob, signer.publicKey, embed),
+            mode: embed ? 'anyone_with_link' : 'recipient',
+        };
+    }
+    catch (e) {
+        return { error: errorMessage(e) };
+    }
+}
+async function qsafeDecryptMessage(input) {
+    try {
+        const source = selectKeySource({
+            keyfile_json: input.keyfile_json,
+            passphrase: input.passphrase,
+            signature_hex: input.signature_hex,
+            address: input.address,
+            signature_hex_repeat: input.signature_hex_repeat,
+        }, KEY_FIELD_NAMES);
+        const expectedSigner = input.expected_signer_pubkey_base64 === undefined
+            ? undefined
+            : decodeHybridPublicKey(input.expected_signer_pubkey_base64, 'expected_signer_pubkey_base64');
+        const parts = (0, message_url_1.parseMessageUrl)(input.url);
+        // The URL names its own signer key, so a valid signature alone proves only that whoever
+        // built the URL holds that key. A pin to a key known out of band confirms which key signed
+        // the envelope, not who wrote the text: v1 binds no signer into the AEAD or the KEM, so
+        // anyone who sees the URL can strip the signature and re-sign the same envelope.
+        if (expectedSigner && !samePublicKey(expectedSigner, parts.signerPublic)) {
+            throw new Error('The message URL is signed by a different key than expected_signer_pubkey_base64.');
+        }
+        let kp;
+        let linkMode = false;
+        if (parts.ephemeralSecret && parts.ephemeralPublic) {
+            kp = { secretKey: parts.ephemeralSecret, publicKey: parts.ephemeralPublic };
+            linkMode = true;
+        }
+        else {
+            if (source.kind === 'none') {
+                throw new Error('Recipient-mode URL requires keyfile_json + passphrase, or signature_hex + address');
+            }
+            kp = await keypairFromSource(source);
+        }
+        let decrypted;
+        try {
+            decrypted = await (0, file_1.decryptFile)(parts.blob, kp.secretKey, parts.signerPublic);
+        }
+        catch (e) {
+            if (e instanceof index_1.SignatureError) {
+                throw new Error('Signature verification failed: the message URL was altered.');
+            }
+            if (!isAeadFailure(e))
+                throw e;
+            throw new Error(linkMode
+                ? 'The key carried in the message URL does not open it: the URL was altered.'
+                : 'The message is not encrypted to this key source (keyfile_json + passphrase, or signature_hex + address).');
+        }
+        const text = new TextDecoder('utf-8', { fatal: true }).decode(decrypted.fileBytes);
+        return { text, signer_pubkey_base64: encodeHybridPublicKey(parts.signerPublic) };
+    }
+    catch (e) {
+        return { error: errorMessage(e) };
+    }
+}
+// No Seal field is signed, so valid can only mean a Seal field is present (the parser leaves
+// anchor-only images out; here they count). The envelope digest is the one claim checkable
+// offline, and only against the envelope itself.
+function qsafeVerifySeal(input) {
+    try {
+        const png = (0, base64_1.base64Decode)(input.png_base64, 'png_base64');
+        const blob = input.blob_base64 === undefined ? undefined : (0, base64_1.base64Decode)(input.blob_base64, 'blob_base64');
+        const { fields } = (0, png_text_1.parseSealTextChunks)(png);
+        const out = { valid: Object.keys(fields).length > 0, metadata: fields };
+        if (blob !== undefined) {
+            out.file_hash_matches = fields.file_hash?.toLowerCase() === (0, utils_1.bytesToHex)((0, sha2_1.sha256)(blob));
+        }
+        return out;
+    }
+    catch (e) {
+        return { error: errorMessage(e) };
+    }
+}
+async function qsafeSignX402(input) {
+    try {
+        const kp = await requireKeypair({
+            keyfile_json: input.keyfile_json,
+            passphrase: input.passphrase,
+            signature_hex: input.signature_hex,
+            address: input.address,
+            signature_hex_repeat: input.signature_hex_repeat,
+        });
+        // A JSON-encoded string would canonicalize to a quoted string literal, a
+        // different byte string from the object any verifier rebuilds.
+        if (!(0, canonical_json_1.isJsonObject)(input.payload_json)) {
+            throw new Error('payload_json must be a JSON object. Pass the parsed object, not a JSON-encoded string, array or scalar.');
+        }
+        const canonical = (0, canonical_json_1.canonicalize)(input.payload_json);
+        const msg = new TextEncoder().encode(canonical);
+        const sig = (0, index_1.sign)(kp.secretKey.mldsa, msg, constants_2.X402_CONTEXT);
+        return {
+            signature_base64: (0, base64_1.base64Encode)(sig),
+            signer_pubkey_base64: encodeHybridPublicKey(kp.publicKey),
+        };
+    }
+    catch (e) {
+        return { error: errorMessage(e) };
+    }
+}