@7h3/protocol 0.4.0 → 0.5.0

package/sdk/pq/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/sdk/pq/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/sdk/pq/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/sdk/pq/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/sdk/pq/vitest.config.ts

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

package/sdk/python/protocol_7h3/encryption.py

@@ -0,0 +1,252 @@
+"""
+E2E Encryption for 7h3 Protocol — Python SDK
+
+Uses X25519 Diffie-Hellman key exchange + ChaCha20-Poly1305 AEAD.
+Requires: pip install cryptography
+
+EncryptedEnvelope = SignedEnvelope where body['content'] is a base64url-encoded
+EncryptedPayload JSON, body['intent'] = 'ENCRYPTED',
+body['capability'] = 'x25519-chacha20poly1305'
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+from typing import Any, Dict, Tuple
+
+try:
+    from cryptography.hazmat.primitives.asymmetric.x25519 import (
+        X25519PrivateKey,
+        X25519PublicKey,
+    )
+    from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305
+    from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+    from cryptography.hazmat.primitives import hashes
+    from cryptography.hazmat.primitives import serialization
+except ImportError as exc:
+    raise ImportError(
+        "7h3/encryption requires the 'cryptography' package. "
+        "Install it with: pip install cryptography"
+    ) from exc
+
+from .protocol import (
+    sign_envelope_ed25519,
+    verify_envelope_ed25519,
+)
+
+
+# ---------------------------------------------------------------------------
+# Utility
+# ---------------------------------------------------------------------------
+
+
+def _b64url_encode(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).decode("ascii").rstrip("=")
+
+
+def _b64url_decode(value: str) -> bytes:
+    padding = "=" * ((4 - (len(value) % 4)) % 4)
+    return base64.urlsafe_b64decode(value + padding)
+
+
+# ---------------------------------------------------------------------------
+# Types (documented shapes, not enforced at runtime)
+# ---------------------------------------------------------------------------
+# X25519KeyPair: tuple[str, str] = (publicKey_base64url, privateKey_base64url)
+# EncryptedPayload dict keys: ephemeralPublic, nonce, ciphertext, tag
+
+
+# ---------------------------------------------------------------------------
+# Key generation
+# ---------------------------------------------------------------------------
+
+
+def generate_x25519_keypair() -> Tuple[str, str]:
+    """
+    Generate a fresh X25519 keypair.
+
+    Returns:
+        (public_base64url, private_base64url) — both are raw 32 bytes, base64url-encoded
+    """
+    private_key = X25519PrivateKey.generate()
+    public_key = private_key.public_key()
+
+    priv_raw = private_key.private_bytes(
+        serialization.Encoding.Raw,
+        serialization.PrivateFormat.Raw,
+        serialization.NoEncryption(),
+    )
+    pub_raw = public_key.public_bytes(
+        serialization.Encoding.Raw,
+        serialization.PublicFormat.Raw,
+    )
+    return _b64url_encode(pub_raw), _b64url_encode(priv_raw)
+
+
+# ---------------------------------------------------------------------------
+# HKDF key derivation
+# ---------------------------------------------------------------------------
+
+
+def _derive_encryption_key(
+    private_key_b64: str,
+    peer_public_key_b64: str,
+    nonce_b64: str,
+) -> bytes:
+    """
+    X25519 DH + HKDF-SHA256 → 32 bytes for ChaCha20-Poly1305.
+
+    nonce_b64: base64url-encoded 12-byte ChaCha nonce; used as HKDF salt.
+    """
+    priv_bytes = _b64url_decode(private_key_b64)
+    pub_bytes = _b64url_decode(peer_public_key_b64)
+    nonce_bytes = _b64url_decode(nonce_b64)
+
+    private_key = X25519PrivateKey.from_private_bytes(priv_bytes)
+    public_key = X25519PublicKey.from_public_bytes(pub_bytes)
+
+    shared_secret = private_key.exchange(public_key)
+
+    hkdf = HKDF(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=nonce_bytes,
+        info=b"7h3-enc/1",
+    )
+    return hkdf.derive(shared_secret)
+
+
+# ---------------------------------------------------------------------------
+# Body encryption / decryption
+# ---------------------------------------------------------------------------
+
+
+def _encrypt_body(
+    body: Dict[str, Any],
+    recipient_x25519_public_b64: str,
+) -> Dict[str, str]:
+    """
+    Encrypt a protocol body dict.
+
+    Returns EncryptedPayload dict with: ephemeralPublic, nonce, ciphertext, tag
+    """
+    # Generate ephemeral keypair for forward secrecy
+    ephemeral_pub_b64, ephemeral_priv_b64 = generate_x25519_keypair()
+
+    # Random 12-byte ChaCha nonce (also used as HKDF salt)
+    nonce12 = os.urandom(12)
+    nonce_b64 = _b64url_encode(nonce12)
+
+    # Derive encryption key
+    key = _derive_encryption_key(ephemeral_priv_b64, recipient_x25519_public_b64, nonce_b64)
+
+    # Encrypt body as JSON
+    plaintext = json.dumps(body, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+    aead = ChaCha20Poly1305(key)
+    # ChaCha20Poly1305.encrypt returns ciphertext‖tag (tag is last 16 bytes)
+    ct_with_tag = aead.encrypt(nonce12, plaintext, None)
+    ciphertext = ct_with_tag[:-16]
+    tag = ct_with_tag[-16:]
+
+    return {
+        "ephemeralPublic": ephemeral_pub_b64,
+        "nonce": nonce_b64,
+        "ciphertext": _b64url_encode(ciphertext),
+        "tag": _b64url_encode(tag),
+    }
+
+
+def _decrypt_body(
+    encrypted_content_b64: str,
+    recipient_x25519_private_b64: str,
+) -> Dict[str, Any]:
+    """
+    Decrypt an EncryptedPayload back to a protocol body dict.
+
+    Raises ValueError if AEAD tag verification fails.
+    """
+    payload_json = _b64url_decode(encrypted_content_b64).decode("utf-8")
+    payload = json.loads(payload_json)
+
+    ephemeral_pub_b64 = payload["ephemeralPublic"]
+    nonce_b64 = payload["nonce"]
+    ciphertext_b64 = payload["ciphertext"]
+    tag_b64 = payload["tag"]
+
+    key = _derive_encryption_key(recipient_x25519_private_b64, ephemeral_pub_b64, nonce_b64)
+
+    nonce12 = _b64url_decode(nonce_b64)
+    ciphertext = _b64url_decode(ciphertext_b64)
+    tag = _b64url_decode(tag_b64)
+
+    aead = ChaCha20Poly1305(key)
+    # Re-concatenate ciphertext‖tag for decryption
+    ct_with_tag = ciphertext + tag
+    plaintext = aead.decrypt(nonce12, ct_with_tag, None)
+    return json.loads(plaintext.decode("utf-8"))
+
+
+# ---------------------------------------------------------------------------
+# Envelope-level seal / open
+# ---------------------------------------------------------------------------
+
+
+def seal_envelope(
+    envelope: Dict[str, Any],
+    recipient_x25519_public_b64: str,
+    sender_ed25519_private_b64: str,
+) -> Dict[str, Any]:
+    """
+    Encrypt the envelope body and sign the result with Ed25519.
+
+    The original body is encrypted; the envelope body is replaced with:
+      { intent: 'ENCRYPTED', content: <encrypted-payload>, capability: 'x25519-chacha20poly1305' }
+    The modified envelope is signed with Ed25519.
+    """
+    encrypted_payload = _encrypt_body(envelope["body"], recipient_x25519_public_b64)
+    encrypted_content = _b64url_encode(
+        json.dumps(encrypted_payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+    )
+
+    encrypted_body: Dict[str, Any] = {
+        "intent": "ENCRYPTED",
+        "content": encrypted_content,
+        "capability": "x25519-chacha20poly1305",
+    }
+    # Preserve correlationId if present
+    if "correlationId" in envelope["body"] and envelope["body"]["correlationId"] is not None:
+        encrypted_body["correlationId"] = envelope["body"]["correlationId"]
+
+    unsigned = {
+        "header": envelope["header"],
+        "body": encrypted_body,
+    }
+
+    return sign_envelope_ed25519(unsigned, sender_ed25519_private_b64)
+
+
+def open_envelope(
+    envelope: Dict[str, Any],
+    recipient_x25519_private_b64: str,
+    sender_ed25519_public_b64: str,
+) -> Dict[str, Any]:
+    """
+    Verify Ed25519 signature, then decrypt the body.
+
+    Signature is verified FIRST — decryption only proceeds if valid.
+
+    Returns a dict with:
+      'envelope': the signed envelope (with encrypted body)
+      'body': the decrypted original ProtocolBody dict
+
+    Raises ValueError if signature is invalid or AEAD tag fails.
+    """
+    # 1. Verify Ed25519 signature FIRST
+    if not verify_envelope_ed25519(envelope, sender_ed25519_public_b64):
+        raise ValueError("7h3/encryption: Ed25519 signature verification failed")
+
+    # 2. Decrypt
+    body = _decrypt_body(envelope["body"]["content"], recipient_x25519_private_b64)
+    return {"envelope": envelope, "body": body}