feat: Post-Quantum Extended Diffie–Hellman (PQXDH) on the Mobile

common/package.json

@@ -661,7 +661,9 @@
   },
   "dependencies": {
     "@anon-aadhaar/core": "npm:@selfxyz/anon-aadhaar-core@^0.0.1",
+    "@noble/curves": "^2.0.1",
     "@noble/hashes": "^1.5.0",
+    "@noble/post-quantum": "^0.5.2",
     "@openpassport/zk-kit-imt": "^0.0.5",
     "@openpassport/zk-kit-lean-imt": "^0.0.6",
     "@openpassport/zk-kit-smt": "^0.0.1",

common/src/utils/proving.ts

@@ -3,6 +3,8 @@ import forge from 'node-forge';
 import { WS_DB_RELAYER, WS_DB_RELAYER_STAGING } from '../constants/index.js';
 import { initElliptic } from '../utils/certificate_parsing/elliptic.js';
 import type { EndpointType } from './appType.js';
+import { generateX25519Keypair } from './proving/pqxdh-crypto.js';
+import type { CryptoSuite, X25519Keypair } from './proving/pqxdh-types.js';
 
 const elliptic = initElliptic();
 const { ec: EC } = elliptic;
@@ -32,6 +34,9 @@ export const ec = new EC('p256');
 // eslint-disable-next-line -- clientKey is created from ec so must be second
 export const clientKey = ec.genKeyPair();
 
+/// Client's X25519 keypair for post-quantum key exchange.
+export const x25519Keys: X25519Keypair = generateX25519Keypair();
+
 type RegisterSuffixes = '' | '_id' | '_aadhaar';
 type DscSuffixes = '' | '_id';
 type DiscloseSuffixes = '' | '_id' | '_aadhaar';
@@ -106,3 +111,16 @@ export function getWSDbRelayerUrl(endpointType: EndpointType) {
     ? WS_DB_RELAYER
     : WS_DB_RELAYER_STAGING;
 }
+
+/// PQXDH types for post-quantum key exchange.
+export type { CryptoSuite, HelloParams, HelloResponse, KeyExchangeParams, SessionKeyMaterial, X25519Keypair } from './proving/pqxdh-types.js';
+
+/// PQXDH cryptographic functions.
+export {
+  generateX25519Keypair,
+  kyberEncapsulate,
+  computeX25519SharedSecret,
+  deriveSessionKey,
+  getSupportedSuites,
+  ml_kem768,
+} from './proving/pqxdh-crypto.js';

common/src/utils/proving/pqxdh-crypto.ts

@@ -0,0 +1,93 @@
+// SPDX-FileCopyrightText: 2025 Social Connect Labs, Inc.
+// SPDX-License-Identifier: BUSL-1.1
+
+import { randomBytes } from '@noble/hashes/utils';
+import { hkdf } from '@noble/hashes/hkdf';
+import { sha256 } from '@noble/hashes/sha2';
+import { x25519 } from '@noble/curves/ed25519.js';
+import { ml_kem768 } from '@noble/post-quantum/ml-kem.js';
+import type { X25519Keypair } from './pqxdh-types.js';
+
+/// Generates a fresh X25519 keypair for PQXDH.
+export function generateX25519Keypair(): X25519Keypair {
+  // generating 32 random bytes for the private key
+  const privateKey = randomBytes(32);
+
+  // deriving the public key from the private key using X25519
+  const publicKey = x25519.getPublicKey(privateKey);
+
+  return {
+    privateKey,
+    publicKey,
+  };
+}
+
+/// Performs Kyber ML-KEM-768 encapsulation to derive a shared secret.
+/// @param kyberPublicKey: TEE's Kyber public key (ML-KEM-768, 1184 bytes)
+/// @returns Object containing shared secret and ciphertext
+export function kyberEncapsulate(kyberPublicKey: Uint8Array): {
+  sharedSecret: Uint8Array;
+  ciphertext: Uint8Array;
+} {
+
+  // encapsulating with the server's Kyber public key to get shared secret and ciphertext
+  const { cipherText, sharedSecret } = ml_kem768.encapsulate(kyberPublicKey);
+
+  return {
+    sharedSecret,
+    ciphertext: cipherText,
+  };
+}
+
+/// Computes X25519 ECDH shared secret between client and server.
+/// @param privateKey: Client's X25519 private key (32 bytes)
+/// @param serverPublicKey: TEE's X25519 public key (32 bytes)
+/// @returns Shared secret (32 bytes)
+export function computeX25519SharedSecret(privateKey: Uint8Array, serverPublicKey: Uint8Array): Uint8Array {
+  // computing the X25519 shared secret using ECDH
+  return x25519.getSharedSecret(privateKey, serverPublicKey);
+}
+
+/// Derives the final session key using HKDF-SHA256 (following Signal PQXDH specification).
+/// @param x25519Shared: X25519 shared secret from ECDH (32 bytes)
+/// @param kyberShared: Kyber shared secret from KEM (32 bytes)
+/// @returns Derived 32-byte session key
+export function deriveSessionKey(
+  x25519Shared: Uint8Array,
+  kyberShared: Uint8Array,
+): Buffer {
+
+  // creating F prefix (32 0xFF bytes) per Signal PQXDH spec
+  // ensures the IKM is never a valid curve25519 scalar or point encoding
+  const F = new Uint8Array(32).fill(0xff);
+
+  // concatenating the two shared secrets (X25519 || Kyber) to form KM
+  const KM = new Uint8Array(x25519Shared.length + kyberShared.length);
+  KM.set(x25519Shared, 0);
+  KM.set(kyberShared, x25519Shared.length);
+
+  // combining F and KM to form the input key material (IKM = F || KM)
+  const ikm = new Uint8Array(F.length + KM.length);
+  ikm.set(F, 0);
+  ikm.set(KM, F.length);
+
+  // using zero-filled salt (32 bytes for SHA-256 output length) per Signal spec
+  const salt = new Uint8Array(32).fill(0);
+
+  // encoding the info string following the pattern "protocol_curve_hash_pqkem"
+  // per Signal spec: "MyProtocol_CURVE25519_SHA-512_CRYSTALS-KYBER-1024"
+  const info = new TextEncoder().encode('Self-PQXDH-1_X25519_SHA-256_ML-KEM-768');
+
+  // deriving the final 32-byte session key using HKDF-SHA256
+  const sessionKey = hkdf(sha256, ikm, salt, info, 32);
+
+  return Buffer.from(sessionKey);
+}
+
+/// Returns supported cryptographic suites in preference order (PQXDH first, then legacy P-256).
+export function getSupportedSuites(): ('Self-PQXDH-1' | 'legacy-p256')[] {
+  return ['Self-PQXDH-1', 'legacy-p256'];
+}
+
+/// ML-KEM-768 (Kyber) implementation for testing and advanced usage.
+export { ml_kem768 } from '@noble/post-quantum/ml-kem.js';

common/src/utils/proving/pqxdh-types.ts

@@ -0,0 +1,43 @@
+// SPDX-FileCopyrightText: 2025 Social Connect Labs, Inc.
+// SPDX-License-Identifier: BUSL-1.1
+
+/// Cryptographic suite identifier (legacy P-256 ECDH or post-quantum PQXDH).
+export type CryptoSuite = 'legacy-p256' | 'Self-PQXDH-1';
+
+/// Parameters for the initial hello message with suite negotiation.
+export interface HelloParams {
+  user_pubkey: number[];
+  uuid: string;
+  supported_suites: CryptoSuite[];
+}
+
+/// TEE's response to hello message with selected suite and public keys.
+/// For legacy-p256: attestation contains embedded server P-256 public key.
+/// For Self-PQXDH-1: separate X25519 and Kyber public keys are provided.
+export interface HelloResponse {
+  attestation: number[];
+  attestation_hash?: number[];
+  selected_suite: CryptoSuite;
+  // only present when selected_suite is 'Self-PQXDH-1'
+  x25519_pubkey?: number[];
+  kyber_pubkey?: number[];
+}
+
+/// Parameters for PQXDH key exchange completion message.
+export interface KeyExchangeParams {
+  uuid: string;
+  kyber_ciphertext: number[];
+}
+
+/// X25519 keypair for PQXDH key exchange.
+export interface X25519Keypair {
+  privateKey: Uint8Array;
+  publicKey: Uint8Array;
+}
+
+/// Derived session key material after key exchange.
+export interface SessionKeyMaterial {
+  sharedKey: Buffer;
+  x25519_shared?: Uint8Array;
+  kyber_shared?: Uint8Array;
+}