@7h3/protocol-pq 0.5.0

package/dist/index.test.js

@@ -0,0 +1,116 @@
+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',
+        messageId: 'test-msg-001',
+        timestampMs: 1_700_000_000_000,
+        ttlMs: 60_000,
+        sender: 'agent-alpha',
+        recipient: 'agent-beta',
+        nonce: 'abc123xyz',
+    },
+    body: {
+        intent: 'TASK',
+        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/dist/sdk/pq/src/index.d.ts

@@ -0,0 +1,30 @@
+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';
+export type PqAlgorithm = 'ML-DSA-65' | 'ML-DSA-87';
+export interface PqKeyPair {
+    algorithm: PqAlgorithm;
+    publicKey: string;
+    privateKey: string;
+    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;
+    };
+}
+export declare function generatePqKeyPair(algorithm?: PqAlgorithm): PqKeyPair;
+export declare function signEnvelopePq(envelope: Omit<ProtocolEnvelope, 'signature'>, privateKeyBase64Url: string, algorithm?: PqAlgorithm): Promise<PqProtocolEnvelope>;
+export declare function verifyEnvelopePq(envelope: PqProtocolEnvelope, publicKeyBase64Url: string): Promise<boolean>;
+export declare function signEnvelopeMlDsa65(envelope: Omit<ProtocolEnvelope, 'signature'>, privateKeyBase64Url: string): Promise<PqProtocolEnvelope>;
+export declare function signEnvelopeMlDsa87(envelope: Omit<ProtocolEnvelope, 'signature'>, privateKeyBase64Url: string): Promise<PqProtocolEnvelope>;
+export declare function verifyEnvelopeMlDsa65(envelope: PqProtocolEnvelope, publicKeyBase64Url: string): Promise<boolean>;
+export declare function verifyEnvelopeMlDsa87(envelope: PqProtocolEnvelope, publicKeyBase64Url: string): Promise<boolean>;

package/dist/sdk/pq/src/index.js

@@ -0,0 +1,100 @@
+import { ml_dsa65, ml_dsa87 } from '@noble/post-quantum/ml-dsa';
+export { canonicalizeEnvelope, createEnvelope } from '../../src/protocol.js';
+import { canonicalizeEnvelope } from '../../src/protocol.js';
+// ─── Base64url helpers ───────────────────────────────────────────────────────
+function toBase64Url(bytes) {
+    const g = globalThis;
+    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) {
+    const padded = value
+        .replace(/-/g, '+')
+        .replace(/_/g, '/')
+        .padEnd(Math.ceil(value.length / 4) * 4, '=');
+    const g = globalThis;
+    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 = 'ML-DSA-65') {
+    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, privateKeyBase64Url, algorithm = 'ML-DSA-65') {
+    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, publicKeyBase64Url) {
+    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, privateKeyBase64Url) {
+    return signEnvelopePq(envelope, privateKeyBase64Url, 'ML-DSA-65');
+}
+export async function signEnvelopeMlDsa87(envelope, privateKeyBase64Url) {
+    return signEnvelopePq(envelope, privateKeyBase64Url, 'ML-DSA-87');
+}
+export async function verifyEnvelopeMlDsa65(envelope, publicKeyBase64Url) {
+    return verifyEnvelopePq(envelope, publicKeyBase64Url);
+}
+export async function verifyEnvelopeMlDsa87(envelope, publicKeyBase64Url) {
+    return verifyEnvelopePq(envelope, publicKeyBase64Url);
+}

package/dist/src/index.d.ts

@@ -0,0 +1,30 @@
+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';
+export type PqAlgorithm = 'ML-DSA-65' | 'ML-DSA-87';
+export interface PqKeyPair {
+    algorithm: PqAlgorithm;
+    publicKey: string;
+    privateKey: string;
+    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;
+    };
+}
+export declare function generatePqKeyPair(algorithm?: PqAlgorithm): PqKeyPair;
+export declare function signEnvelopePq(envelope: Omit<ProtocolEnvelope, 'signature'>, privateKeyBase64Url: string, algorithm?: PqAlgorithm): Promise<PqProtocolEnvelope>;
+export declare function verifyEnvelopePq(envelope: PqProtocolEnvelope, publicKeyBase64Url: string): Promise<boolean>;
+export declare function signEnvelopeMlDsa65(envelope: Omit<ProtocolEnvelope, 'signature'>, privateKeyBase64Url: string): Promise<PqProtocolEnvelope>;
+export declare function signEnvelopeMlDsa87(envelope: Omit<ProtocolEnvelope, 'signature'>, privateKeyBase64Url: string): Promise<PqProtocolEnvelope>;
+export declare function verifyEnvelopeMlDsa65(envelope: PqProtocolEnvelope, publicKeyBase64Url: string): Promise<boolean>;
+export declare function verifyEnvelopeMlDsa87(envelope: PqProtocolEnvelope, publicKeyBase64Url: string): Promise<boolean>;

package/dist/src/index.js

@@ -0,0 +1,100 @@
+import { ml_dsa65, ml_dsa87 } from '@noble/post-quantum/ml-dsa';
+export { canonicalizeEnvelope, createEnvelope } from '../../src/protocol.js';
+import { canonicalizeEnvelope } from '../../src/protocol.js';
+// ─── Base64url helpers ───────────────────────────────────────────────────────
+function toBase64Url(bytes) {
+    const g = globalThis;
+    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) {
+    const padded = value
+        .replace(/-/g, '+')
+        .replace(/_/g, '/')
+        .padEnd(Math.ceil(value.length / 4) * 4, '=');
+    const g = globalThis;
+    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 = 'ML-DSA-65') {
+    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, privateKeyBase64Url, algorithm = 'ML-DSA-65') {
+    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, publicKeyBase64Url) {
+    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, privateKeyBase64Url) {
+    return signEnvelopePq(envelope, privateKeyBase64Url, 'ML-DSA-65');
+}
+export async function signEnvelopeMlDsa87(envelope, privateKeyBase64Url) {
+    return signEnvelopePq(envelope, privateKeyBase64Url, 'ML-DSA-87');
+}
+export async function verifyEnvelopeMlDsa65(envelope, publicKeyBase64Url) {
+    return verifyEnvelopePq(envelope, publicKeyBase64Url);
+}
+export async function verifyEnvelopeMlDsa87(envelope, publicKeyBase64Url) {
+    return verifyEnvelopePq(envelope, publicKeyBase64Url);
+}

package/dist/src/protocol.d.ts

@@ -0,0 +1,66 @@
+export type ProtocolVersion = '7h3/0.1';
+export type IntentKind = 'PING' | 'PONG' | 'CAPS' | 'TASK' | 'RESULT' | 'ERROR';
+export interface ProtocolHeader {
+    version: ProtocolVersion;
+    messageId: string;
+    timestampMs: number;
+    ttlMs: number;
+    sender: string;
+    recipient?: string;
+    nonce: string;
+}
+export interface ProtocolBody {
+    intent: IntentKind;
+    content: string;
+    capability?: string;
+    correlationId?: string;
+}
+export interface ProtocolSignature {
+    alg: 'HS256' | 'ED25519';
+    keyId: string;
+    value: string;
+}
+export interface ProtocolEnvelope {
+    header: ProtocolHeader;
+    body: ProtocolBody;
+    signature?: ProtocolSignature;
+}
+export interface ProtocolDiagnostic {
+    level: 'error' | 'warning';
+    message: string;
+}
+export type SignatureVerificationMaterial = {
+    alg: 'HS256';
+    secret: string;
+} | {
+    alg: 'ED25519';
+    publicKey: string;
+};
+export declare function canonicalizeEnvelope(envelope: Omit<ProtocolEnvelope, 'signature'>): string;
+export declare function signCanonicalPayloadHmac(payload: string, secret: string): Promise<string>;
+export declare function verifyCanonicalPayloadHmac(payload: string, signature: string, secret: string): Promise<boolean>;
+export declare function generateEd25519KeypairBase64Url(): Promise<{
+    publicKey: string;
+    privateKey: string;
+}>;
+export declare function signCanonicalPayloadEd25519(payload: string, privateKeyPkcs8Base64Url: string): Promise<string>;
+export declare function verifyCanonicalPayloadEd25519(payload: string, signature: string, publicKeySpkiBase64Url: string): Promise<boolean>;
+export declare function signEnvelopeHmac(envelope: Omit<ProtocolEnvelope, 'signature'>, secret: string, keyId?: string): Promise<ProtocolEnvelope>;
+export declare function verifyEnvelopeHmac(envelope: ProtocolEnvelope, secret: string): Promise<boolean>;
+export declare function signEnvelopeEd25519(envelope: Omit<ProtocolEnvelope, 'signature'>, privateKeyPkcs8Base64Url: string, keyId?: string): Promise<ProtocolEnvelope>;
+export declare function verifyEnvelopeEd25519(envelope: ProtocolEnvelope, publicKeySpkiBase64Url: string): Promise<boolean>;
+export declare function verifyEnvelopeSignature(envelope: ProtocolEnvelope, material: SignatureVerificationMaterial): Promise<boolean>;
+export declare function verifyCanonicalPayloadSignature(payload: string, signature: ProtocolSignature | undefined, material: SignatureVerificationMaterial): Promise<boolean>;
+export declare function validateEnvelope(envelope: ProtocolEnvelope, nowMs?: number): ProtocolDiagnostic[];
+export declare function createEnvelope(input: {
+    sender: string;
+    recipient?: string;
+    intent: IntentKind;
+    content: string;
+    capability?: string;
+    correlationId?: string;
+    ttlMs?: number;
+    messageId?: string;
+    nonce?: string;
+    nowMs?: number;
+}): Omit<ProtocolEnvelope, 'signature'>;