@7h3/protocol-pq 0.5.0

package/dist/src/protocol.js

@@ -0,0 +1,294 @@
+const textEncoder = new TextEncoder();
+const HMAC_KEY_CACHE_LIMIT = 256;
+const hmacKeyCache = new Map();
+const ED25519_KEY_CACHE_LIMIT = 256;
+const ed25519PrivateKeyCache = new Map();
+const ed25519PublicKeyCache = new Map();
+function getBufferLike() {
+    const candidate = globalThis;
+    return candidate.Buffer ?? null;
+}
+function serializeHeaderCanonical(header) {
+    const parts = [
+        `"messageId":${JSON.stringify(header.messageId)}`,
+        `"nonce":${JSON.stringify(header.nonce)}`,
+    ];
+    if (header.recipient !== undefined) {
+        parts.push(`"recipient":${JSON.stringify(header.recipient)}`);
+    }
+    parts.push(`"sender":${JSON.stringify(header.sender)}`);
+    parts.push(`"timestampMs":${header.timestampMs}`);
+    parts.push(`"ttlMs":${header.ttlMs}`);
+    parts.push(`"version":${JSON.stringify(header.version)}`);
+    return `{${parts.join(',')}}`;
+}
+function serializeBodyCanonical(body) {
+    const parts = [];
+    if (body.capability !== undefined) {
+        parts.push(`"capability":${JSON.stringify(body.capability)}`);
+    }
+    parts.push(`"content":${JSON.stringify(body.content)}`);
+    if (body.correlationId !== undefined) {
+        parts.push(`"correlationId":${JSON.stringify(body.correlationId)}`);
+    }
+    parts.push(`"intent":${JSON.stringify(body.intent)}`);
+    return `{${parts.join(',')}}`;
+}
+function getCachedHmacKey(secret) {
+    const cacheKey = `hs256:${secret}`;
+    const cached = hmacKeyCache.get(cacheKey);
+    if (cached)
+        return cached;
+    if (hmacKeyCache.size >= HMAC_KEY_CACHE_LIMIT) {
+        hmacKeyCache.clear();
+    }
+    const subtle = requireCryptoSubtle();
+    const imported = subtle
+        .importKey('raw', textEncoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign', 'verify'])
+        .catch((error) => {
+        hmacKeyCache.delete(cacheKey);
+        throw error;
+    });
+    hmacKeyCache.set(cacheKey, imported);
+    return imported;
+}
+function getCachedEd25519PrivateKey(privateKeyPkcs8Base64Url) {
+    const cacheKey = `ed25519:pkcs8:${privateKeyPkcs8Base64Url}`;
+    const cached = ed25519PrivateKeyCache.get(cacheKey);
+    if (cached)
+        return cached;
+    if (ed25519PrivateKeyCache.size >= ED25519_KEY_CACHE_LIMIT) {
+        ed25519PrivateKeyCache.clear();
+    }
+    const subtle = requireCryptoSubtle();
+    const imported = subtle
+        .importKey('pkcs8', toArrayBuffer(fromBase64Url(privateKeyPkcs8Base64Url)), { name: 'Ed25519' }, false, ['sign'])
+        .catch((error) => {
+        ed25519PrivateKeyCache.delete(cacheKey);
+        throw error;
+    });
+    ed25519PrivateKeyCache.set(cacheKey, imported);
+    return imported;
+}
+function getCachedEd25519PublicKey(publicKeySpkiBase64Url) {
+    const cacheKey = `ed25519:spki:${publicKeySpkiBase64Url}`;
+    const cached = ed25519PublicKeyCache.get(cacheKey);
+    if (cached)
+        return cached;
+    if (ed25519PublicKeyCache.size >= ED25519_KEY_CACHE_LIMIT) {
+        ed25519PublicKeyCache.clear();
+    }
+    const subtle = requireCryptoSubtle();
+    const imported = subtle
+        .importKey('spki', toArrayBuffer(fromBase64Url(publicKeySpkiBase64Url)), { name: 'Ed25519' }, false, ['verify'])
+        .catch((error) => {
+        ed25519PublicKeyCache.delete(cacheKey);
+        throw error;
+    });
+    ed25519PublicKeyCache.set(cacheKey, imported);
+    return imported;
+}
+function toBase64Url(bytes) {
+    const bufferLike = getBufferLike();
+    const base64 = bufferLike ? bufferLike.from(bytes).toString('base64') : btoa(String.fromCharCode(...bytes));
+    return base64
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/g, '');
+}
+function fromBase64Url(value) {
+    const padded = value
+        .replace(/-/g, '+')
+        .replace(/_/g, '/')
+        .padEnd(Math.ceil(value.length / 4) * 4, '=');
+    const bufferLike = getBufferLike();
+    if (bufferLike) {
+        return new Uint8Array(bufferLike.from(padded, 'base64'));
+    }
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+function toArrayBuffer(bytes) {
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+export function canonicalizeEnvelope(envelope) {
+    return `{"body":${serializeBodyCanonical(envelope.body)},"header":${serializeHeaderCanonical(envelope.header)}}`;
+}
+function requireCryptoSubtle() {
+    if (typeof crypto === 'undefined' || !crypto.subtle) {
+        throw new Error('Web Crypto API is not available in this runtime');
+    }
+    return crypto.subtle;
+}
+async function hmacSign(payload, secret) {
+    const subtle = requireCryptoSubtle();
+    const key = await getCachedHmacKey(secret);
+    const signature = await subtle.sign('HMAC', key, textEncoder.encode(payload));
+    return toBase64Url(new Uint8Array(signature));
+}
+async function hmacVerify(payload, signature, secret) {
+    const subtle = requireCryptoSubtle();
+    const key = await getCachedHmacKey(secret);
+    const signatureBytes = fromBase64Url(signature);
+    return subtle.verify('HMAC', key, signatureBytes.buffer, textEncoder.encode(payload));
+}
+async function ed25519Sign(payload, privateKeyPkcs8Base64Url) {
+    const subtle = requireCryptoSubtle();
+    const key = await getCachedEd25519PrivateKey(privateKeyPkcs8Base64Url);
+    const signature = await subtle.sign('Ed25519', key, textEncoder.encode(payload));
+    return toBase64Url(new Uint8Array(signature));
+}
+async function ed25519Verify(payload, signature, publicKeySpkiBase64Url) {
+    const subtle = requireCryptoSubtle();
+    const key = await getCachedEd25519PublicKey(publicKeySpkiBase64Url);
+    const signatureBytes = fromBase64Url(signature);
+    return subtle.verify('Ed25519', key, signatureBytes.buffer, textEncoder.encode(payload));
+}
+export async function signCanonicalPayloadHmac(payload, secret) {
+    return hmacSign(payload, secret);
+}
+export async function verifyCanonicalPayloadHmac(payload, signature, secret) {
+    return hmacVerify(payload, signature, secret);
+}
+export async function generateEd25519KeypairBase64Url() {
+    const subtle = requireCryptoSubtle();
+    const pair = await subtle.generateKey({ name: 'Ed25519' }, true, ['sign', 'verify']);
+    const privateKeyRaw = await subtle.exportKey('pkcs8', pair.privateKey);
+    const publicKeyRaw = await subtle.exportKey('spki', pair.publicKey);
+    return {
+        privateKey: toBase64Url(new Uint8Array(privateKeyRaw)),
+        publicKey: toBase64Url(new Uint8Array(publicKeyRaw)),
+    };
+}
+export async function signCanonicalPayloadEd25519(payload, privateKeyPkcs8Base64Url) {
+    return ed25519Sign(payload, privateKeyPkcs8Base64Url);
+}
+export async function verifyCanonicalPayloadEd25519(payload, signature, publicKeySpkiBase64Url) {
+    return ed25519Verify(payload, signature, publicKeySpkiBase64Url);
+}
+export async function signEnvelopeHmac(envelope, secret, keyId = 'local-dev-key') {
+    const payload = canonicalizeEnvelope(envelope);
+    const signature = await hmacSign(payload, secret);
+    return {
+        ...envelope,
+        signature: {
+            alg: 'HS256',
+            keyId,
+            value: signature,
+        },
+    };
+}
+export async function verifyEnvelopeHmac(envelope, secret) {
+    if (!envelope.signature)
+        return false;
+    if (envelope.signature.alg !== 'HS256')
+        return false;
+    const unsigned = {
+        header: envelope.header,
+        body: envelope.body,
+    };
+    const payload = canonicalizeEnvelope(unsigned);
+    return hmacVerify(payload, envelope.signature.value, secret);
+}
+export async function signEnvelopeEd25519(envelope, privateKeyPkcs8Base64Url, keyId = 'local-ed25519-key') {
+    const payload = canonicalizeEnvelope(envelope);
+    const signature = await ed25519Sign(payload, privateKeyPkcs8Base64Url);
+    return {
+        ...envelope,
+        signature: {
+            alg: 'ED25519',
+            keyId,
+            value: signature,
+        },
+    };
+}
+export async function verifyEnvelopeEd25519(envelope, publicKeySpkiBase64Url) {
+    if (!envelope.signature)
+        return false;
+    if (envelope.signature.alg !== 'ED25519')
+        return false;
+    const unsigned = {
+        header: envelope.header,
+        body: envelope.body,
+    };
+    const payload = canonicalizeEnvelope(unsigned);
+    return ed25519Verify(payload, envelope.signature.value, publicKeySpkiBase64Url);
+}
+export async function verifyEnvelopeSignature(envelope, material) {
+    if (!envelope.signature)
+        return false;
+    if (envelope.signature.alg !== material.alg)
+        return false;
+    if (material.alg === 'HS256') {
+        return verifyEnvelopeHmac(envelope, material.secret);
+    }
+    return verifyEnvelopeEd25519(envelope, material.publicKey);
+}
+export async function verifyCanonicalPayloadSignature(payload, signature, material) {
+    if (!signature)
+        return false;
+    if (signature.alg !== material.alg)
+        return false;
+    if (material.alg === 'HS256') {
+        return verifyCanonicalPayloadHmac(payload, signature.value, material.secret);
+    }
+    return verifyCanonicalPayloadEd25519(payload, signature.value, material.publicKey);
+}
+export function validateEnvelope(envelope, nowMs = Date.now()) {
+    const diagnostics = [];
+    const header = envelope.header ?? {};
+    const body = envelope.body ?? {};
+    const version = typeof header.version === 'string' ? header.version : '';
+    const messageId = typeof header.messageId === 'string' ? header.messageId : '';
+    const sender = typeof header.sender === 'string' ? header.sender : '';
+    const nonce = typeof header.nonce === 'string' ? header.nonce : '';
+    const timestampMs = typeof header.timestampMs === 'number' ? header.timestampMs : 0;
+    const ttlMs = typeof header.ttlMs === 'number' ? header.ttlMs : 0;
+    const content = typeof body.content === 'string' ? body.content : '';
+    if (version !== '7h3/0.1') {
+        diagnostics.push({ level: 'error', message: `Unsupported protocol version '${version}'` });
+    }
+    if (!messageId.trim()) {
+        diagnostics.push({ level: 'error', message: 'Missing messageId' });
+    }
+    if (!sender.trim()) {
+        diagnostics.push({ level: 'error', message: 'Missing sender identity' });
+    }
+    if (!nonce.trim()) {
+        diagnostics.push({ level: 'error', message: 'Missing nonce — replay protection requires a unique nonce per message' });
+    }
+    if (ttlMs <= 0) {
+        diagnostics.push({ level: 'error', message: 'ttlMs must be greater than zero' });
+    }
+    if (timestampMs + ttlMs < nowMs) {
+        diagnostics.push({ level: 'error', message: 'Message TTL expired' });
+    }
+    if (!content.trim()) {
+        diagnostics.push({ level: 'warning', message: 'Empty content payload' });
+    }
+    return diagnostics;
+}
+export function createEnvelope(input) {
+    const nowMs = input.nowMs ?? Date.now();
+    return {
+        header: {
+            version: '7h3/0.1',
+            messageId: input.messageId ?? `msg-${nowMs}-${Math.random().toString(36).slice(2, 10)}`,
+            timestampMs: nowMs,
+            ttlMs: input.ttlMs ?? 60_000,
+            sender: input.sender,
+            recipient: input.recipient,
+            nonce: input.nonce ?? Math.random().toString(36).slice(2, 12),
+        },
+        body: {
+            intent: input.intent,
+            content: input.content,
+            capability: input.capability,
+            correlationId: input.correlationId,
+        },
+    };
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@7h3/protocol-pq",
+  "version": "0.5.0",
+  "description": "7h3 Protocol — Post-quantum signatures (ML-DSA-65, ML-DSA-87) via @noble/post-quantum",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "dependencies": {
+    "@noble/post-quantum": "^0.2.0"
+  },
+  "peerDependencies": {
+    "@7h3/protocol": "^0.5.0"
+  },
+  "license": "MIT",
+  "keywords": [
+    "7h3",
+    "protocol",
+    "post-quantum",
+    "ml-dsa",
+    "dilithium",
+    "signing"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/IceMasterT/7h3-protocol.git"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run src/index.test.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "~6.0.3",
+    "vitest": "^4.1.8"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,143 @@
+import { describe, it, expect } from 'vitest'
+import {
+  generatePqKeyPair,
+  signEnvelopePq,
+  verifyEnvelopePq,
+  signEnvelopeMlDsa65,
+  signEnvelopeMlDsa87,
+  verifyEnvelopeMlDsa65,
+  verifyEnvelopeMlDsa87,
+  createEnvelope,
+} from './index.js'
+
+// Conformance vector envelope (deterministic for tests)
+const baseEnvelope = {
+  header: {
+    version: '7h3/0.1' as const,
+    messageId: 'test-msg-001',
+    timestampMs: 1_700_000_000_000,
+    ttlMs: 60_000,
+    sender: 'agent-alpha',
+    recipient: 'agent-beta',
+    nonce: 'abc123xyz',
+  },
+  body: {
+    intent: 'TASK' as const,
+    content: 'Hello, post-quantum world!',
+  },
+}
+
+describe('generatePqKeyPair', () => {
+  it('1. ML-DSA-65 returns keypair with correct algorithm field', () => {
+    const kp = generatePqKeyPair('ML-DSA-65')
+    expect(kp.algorithm).toBe('ML-DSA-65')
+    expect(typeof kp.publicKey).toBe('string')
+    expect(typeof kp.privateKey).toBe('string')
+    expect(typeof kp.createdAt).toBe('number')
+    expect(kp.publicKey.length).toBeGreaterThan(0)
+    expect(kp.privateKey.length).toBeGreaterThan(0)
+  })
+
+  it('2. ML-DSA-87 returns keypair', () => {
+    const kp = generatePqKeyPair('ML-DSA-87')
+    expect(kp.algorithm).toBe('ML-DSA-87')
+    expect(typeof kp.publicKey).toBe('string')
+    expect(typeof kp.privateKey).toBe('string')
+  })
+
+  it('7. ML-DSA-65 public key is correct size (1952 bytes → ~2603 base64url chars)', () => {
+    const kp = generatePqKeyPair('ML-DSA-65')
+    // base64url: ceil(1952 / 3) * 4 = 2604 chars, minus up to 2 padding = 2603 or 2604
+    const decoded = Buffer.from(
+      kp.publicKey.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(kp.publicKey.length / 4) * 4, '='),
+      'base64'
+    )
+    expect(decoded.length).toBe(1952)
+  })
+
+  it('8. ML-DSA-65 private key is correct size (4032 bytes secretKey)', () => {
+    const kp = generatePqKeyPair('ML-DSA-65')
+    const decoded = Buffer.from(
+      kp.privateKey.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(kp.privateKey.length / 4) * 4, '='),
+      'base64'
+    )
+    expect(decoded.length).toBe(4032)
+  })
+})
+
+describe('ML-DSA-65 sign/verify', () => {
+  it('3. ML-DSA-65 sign + verify round trip', async () => {
+    const kp = generatePqKeyPair('ML-DSA-65')
+    const signed = await signEnvelopePq(baseEnvelope, kp.privateKey, 'ML-DSA-65')
+    expect(signed.signature?.alg).toBe('ML-DSA-65')
+    expect(typeof signed.signature?.value).toBe('string')
+    expect(signed.signature!.value.length).toBeGreaterThan(0)
+    const valid = await verifyEnvelopePq(signed, kp.publicKey)
+    expect(valid).toBe(true)
+  })
+
+  it('4. ML-DSA-65 verify fails on tampered envelope', async () => {
+    const kp = generatePqKeyPair('ML-DSA-65')
+    const signed = await signEnvelopePq(baseEnvelope, kp.privateKey, 'ML-DSA-65')
+    const tampered = {
+      ...signed,
+      body: { ...signed.body, content: 'TAMPERED content' },
+    }
+    const valid = await verifyEnvelopePq(tampered, kp.publicKey)
+    expect(valid).toBe(false)
+  })
+})
+
+describe('ML-DSA-87 sign/verify', () => {
+  it('5. ML-DSA-87 sign + verify round trip', async () => {
+    const kp = generatePqKeyPair('ML-DSA-87')
+    const signed = await signEnvelopePq(baseEnvelope, kp.privateKey, 'ML-DSA-87')
+    expect(signed.signature?.alg).toBe('ML-DSA-87')
+    const valid = await verifyEnvelopePq(signed, kp.publicKey)
+    expect(valid).toBe(true)
+  })
+
+  it('6. ML-DSA-87 verify fails with wrong public key', async () => {
+    const kp = generatePqKeyPair('ML-DSA-87')
+    const wrongKp = generatePqKeyPair('ML-DSA-87')
+    const signed = await signEnvelopePq(baseEnvelope, kp.privateKey, 'ML-DSA-87')
+    const valid = await verifyEnvelopePq(signed, wrongKp.publicKey)
+    expect(valid).toBe(false)
+  })
+})
+
+describe('algorithm-specific aliases', () => {
+  it('signEnvelopeMlDsa65 / verifyEnvelopeMlDsa65 round trip', async () => {
+    const kp = generatePqKeyPair('ML-DSA-65')
+    const envelope = createEnvelope({
+      sender: 'agent-a',
+      recipient: 'agent-b',
+      intent: 'PING',
+      content: 'alias test',
+    })
+    const signed = await signEnvelopeMlDsa65(envelope, kp.privateKey)
+    expect(signed.signature?.alg).toBe('ML-DSA-65')
+    const valid = await verifyEnvelopeMlDsa65(signed, kp.publicKey)
+    expect(valid).toBe(true)
+  })
+
+  it('signEnvelopeMlDsa87 / verifyEnvelopeMlDsa87 round trip', async () => {
+    const kp = generatePqKeyPair('ML-DSA-87')
+    const envelope = createEnvelope({
+      sender: 'agent-a',
+      recipient: 'agent-b',
+      intent: 'PONG',
+      content: 'ml-dsa-87 alias test',
+    })
+    const signed = await signEnvelopeMlDsa87(envelope, kp.privateKey)
+    expect(signed.signature?.alg).toBe('ML-DSA-87')
+    const valid = await verifyEnvelopeMlDsa87(signed, kp.publicKey)
+    expect(valid).toBe(true)
+  })
+
+  it('verifyEnvelopePq returns false when no signature', async () => {
+    const unsigned = { ...baseEnvelope }
+    const valid = await verifyEnvelopePq(unsigned, 'fakepublickey')
+    expect(valid).toBe(false)
+  })
+})

package/src/index.ts

@@ -0,0 +1,166 @@
+import { ml_dsa65, ml_dsa87 } from '@noble/post-quantum/ml-dsa'
+
+// Re-export from @7h3/protocol
+export type { ProtocolEnvelope, ProtocolHeader, ProtocolBody } from '../../../src/protocol.js'
+export { canonicalizeEnvelope, createEnvelope } from '../../../src/protocol.js'
+
+import type { ProtocolEnvelope, ProtocolHeader, ProtocolBody } from '../../../src/protocol.js'
+import { canonicalizeEnvelope } from '../../../src/protocol.js'
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export type PqAlgorithm = 'ML-DSA-65' | 'ML-DSA-87'
+
+export interface PqKeyPair {
+  algorithm: PqAlgorithm
+  publicKey: string  // base64url, no padding
+  privateKey: string // base64url, no padding (secretKey bytes from noble)
+  createdAt: number
+}
+
+/**
+ * Extended envelope type that carries a PQ signature.
+ * Structurally identical to ProtocolEnvelope but alg is widened.
+ */
+export interface PqProtocolEnvelope {
+  header: ProtocolHeader
+  body: ProtocolBody
+  signature?: {
+    alg: PqAlgorithm
+    keyId: string
+    value: string
+  }
+}
+
+// ─── Base64url helpers ───────────────────────────────────────────────────────
+
+function toBase64Url(bytes: Uint8Array): string {
+  const g = globalThis as unknown as {
+    Buffer?: { from: (b: Uint8Array) => { toString: (enc: string) => string } }
+  }
+  if (g.Buffer) {
+    return g.Buffer.from(bytes)
+      .toString('base64')
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_')
+      .replace(/=+$/g, '')
+  }
+  let binary = ''
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i])
+  return btoa(binary)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/g, '')
+}
+
+function fromBase64Url(value: string): Uint8Array {
+  const padded = value
+    .replace(/-/g, '+')
+    .replace(/_/g, '/')
+    .padEnd(Math.ceil(value.length / 4) * 4, '=')
+
+  const g = globalThis as unknown as {
+    Buffer?: { from: (s: string, enc: string) => Uint8Array }
+  }
+  if (g.Buffer) {
+    return new Uint8Array(g.Buffer.from(padded, 'base64'))
+  }
+  const binary = atob(padded)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i)
+  return bytes
+}
+
+// ─── Key generation ──────────────────────────────────────────────────────────
+
+export function generatePqKeyPair(algorithm: PqAlgorithm = 'ML-DSA-65'): PqKeyPair {
+  const impl = algorithm === 'ML-DSA-65' ? ml_dsa65 : ml_dsa87
+  const seed = crypto.getRandomValues(new Uint8Array(32))
+  const { publicKey, secretKey } = impl.keygen(seed)
+  return {
+    algorithm,
+    publicKey: toBase64Url(publicKey),
+    privateKey: toBase64Url(secretKey),
+    createdAt: Date.now(),
+  }
+}
+
+// ─── Sign ────────────────────────────────────────────────────────────────────
+
+export async function signEnvelopePq(
+  envelope: Omit<ProtocolEnvelope, 'signature'>,
+  privateKeyBase64Url: string,
+  algorithm: PqAlgorithm = 'ML-DSA-65',
+): Promise<PqProtocolEnvelope> {
+  const impl = algorithm === 'ML-DSA-65' ? ml_dsa65 : ml_dsa87
+  const canonical = canonicalizeEnvelope(envelope)
+  const message = new TextEncoder().encode(canonical)
+  const secretKey = fromBase64Url(privateKeyBase64Url)
+  const sigBytes = impl.sign(secretKey, message)
+  // keyId derived from first 16 chars of the secretKey base64url
+  const keyId = privateKeyBase64Url.slice(0, 16)
+
+  return {
+    header: envelope.header,
+    body: envelope.body,
+    signature: {
+      alg: algorithm,
+      keyId,
+      value: toBase64Url(sigBytes),
+    },
+  }
+}
+
+// ─── Verify ──────────────────────────────────────────────────────────────────
+
+export async function verifyEnvelopePq(
+  envelope: PqProtocolEnvelope,
+  publicKeyBase64Url: string,
+): Promise<boolean> {
+  if (!envelope.signature) return false
+  const alg = envelope.signature.alg
+  if (alg !== 'ML-DSA-65' && alg !== 'ML-DSA-87') return false
+
+  const impl = alg === 'ML-DSA-65' ? ml_dsa65 : ml_dsa87
+  const unsigned = { header: envelope.header, body: envelope.body }
+  const canonical = canonicalizeEnvelope(unsigned)
+  const message = new TextEncoder().encode(canonical)
+  const publicKey = fromBase64Url(publicKeyBase64Url)
+  const sigBytes = fromBase64Url(envelope.signature.value)
+
+  try {
+    return impl.verify(publicKey, message, sigBytes)
+  } catch {
+    return false
+  }
+}
+
+// ─── Algorithm-specific aliases ──────────────────────────────────────────────
+
+export async function signEnvelopeMlDsa65(
+  envelope: Omit<ProtocolEnvelope, 'signature'>,
+  privateKeyBase64Url: string,
+): Promise<PqProtocolEnvelope> {
+  return signEnvelopePq(envelope, privateKeyBase64Url, 'ML-DSA-65')
+}
+
+export async function signEnvelopeMlDsa87(
+  envelope: Omit<ProtocolEnvelope, 'signature'>,
+  privateKeyBase64Url: string,
+): Promise<PqProtocolEnvelope> {
+  return signEnvelopePq(envelope, privateKeyBase64Url, 'ML-DSA-87')
+}
+
+export async function verifyEnvelopeMlDsa65(
+  envelope: PqProtocolEnvelope,
+  publicKeyBase64Url: string,
+): Promise<boolean> {
+  return verifyEnvelopePq(envelope, publicKeyBase64Url)
+}
+
+export async function verifyEnvelopeMlDsa87(
+  envelope: PqProtocolEnvelope,
+  publicKeyBase64Url: string,
+): Promise<boolean> {
+  return verifyEnvelopePq(envelope, publicKeyBase64Url)
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "../../../",
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src/index.ts", "../../../src/protocol.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: false,
+  },
+})