Browser SDK (@qnsp/browser-sdk)

Browser-compatible PQC encryption SDK for the QNSP platform. Provides client-side encryption (CSE), digital signatures, and key management using NIST FIPS 203/204/205 standards via @noble/post-quantum.

No native dependencies. No node: imports. Works in browsers, Deno, Bun, and Node.js.

Install

pnpm add @qnsp/browser-sdk

Supported Algorithms

18 FIPS-standardized algorithms across 3 families:

Family	Standard	Algorithms	Use Case
ML-KEM	FIPS 203	kyber-512, kyber-768, kyber-1024	Key encapsulation (encryption)
ML-DSA	FIPS 204	dilithium-2, dilithium-3, dilithium-5	Digital signatures
SLH-DSA	FIPS 205	12 parameter sets (SHA2/SHAKE × 128/192/256 × f/s)	Hash-based signatures

Quick Start

import {
  initializePqcProvider,
  encryptBeforeUpload,
  decryptAfterDownload,
  generateEncryptionKeyPair,
} from "@qnsp/browser-sdk";

// Initialize the PQC provider (auto-detects runtime)
await initializePqcProvider();

// Generate ML-KEM key pair
const { publicKey, privateKey } = await generateEncryptionKeyPair("kyber-768");

// Encrypt data before upload (ML-KEM + AES-256-GCM)
const plaintext = new TextEncoder().encode("classified document");
const envelope = await encryptBeforeUpload(plaintext, publicKey, "kyber-768");

// Decrypt data after download
const decrypted = await decryptAfterDownload(envelope, privateKey);

Provider Setup

The SDK auto-detects the runtime environment and initializes the noble PQC provider.

import {
  initializePqcProvider,
  isProviderInitialized,
  getActiveProvider,
  detectRuntime,
  getSupportedAlgorithms,
  resetProvider,
} from "@qnsp/browser-sdk";

// Detect runtime environment
const runtime = detectRuntime(); // "browser" | "edge" | "node"

// Initialize provider
await initializePqcProvider();

// Check initialization status
console.log(isProviderInitialized()); // true

// Get the active provider instance
const provider = getActiveProvider();

// List supported algorithms
const algorithms = getSupportedAlgorithms(); // 18 algorithms

// Reset provider (for testing)
resetProvider();

Client-Side Encryption (CSE)

Encrypt data in the browser before uploading to QNSP storage. Uses ML-KEM for key encapsulation and AES-256-GCM for symmetric encryption.

import {
  encryptBeforeUpload,
  decryptAfterDownload,
  serializeCseEnvelope,
  deserializeCseEnvelope,
  type CseEnvelope,
} from "@qnsp/browser-sdk";

// Encrypt
const envelope: CseEnvelope = await encryptBeforeUpload(
  plaintext,
  recipientPublicKey,
  "kyber-768"
);
// envelope contains: { algorithm, kemCiphertext, iv, ciphertext }

// Serialize for transport (binary format)
const bytes: Uint8Array = serializeCseEnvelope(envelope);

// Deserialize after download
const restored: CseEnvelope = deserializeCseEnvelope(bytes);

// Decrypt
const decrypted: Uint8Array = await decryptAfterDownload(restored, privateKey);

CSE Envelope Format

Field	Type	Description
algorithm	PqcAlgorithm	KEM algorithm used (e.g., kyber-768)
kemCiphertext	Uint8Array	KEM ciphertext (encapsulated shared secret)
iv	Uint8Array	AES-256-GCM initialization vector (12 bytes)
ciphertext	Uint8Array	AES-256-GCM encrypted data

Digital Signatures

Sign and verify data using ML-DSA or SLH-DSA.

import {
  signData,
  verifySignature,
  generateSigningKeyPair,
  generateEncryptionKeyPair,
  type SignedEnvelope,
} from "@qnsp/browser-sdk";

// Generate ML-DSA signing key pair
const sigKeyPair = await generateSigningKeyPair("dilithium-3");

// Sign data
const signed: SignedEnvelope = await signData(
  data,
  sigKeyPair.privateKey,
  "dilithium-3"
);
// signed contains: { data, signature, algorithm }

// Verify signature
const valid: boolean = await verifySignature(
  signed.data,
  signed.signature,
  sigKeyPair.publicKey,
  "dilithium-3"
);

// Generate ML-KEM encryption key pair
const encKeyPair = await generateEncryptionKeyPair("kyber-768");

Runtime Environments

Environment	Detection	Provider
Browser	"window" in globalThis	noble (pure JS)
Edge (Cloudflare Workers, Vercel Edge)	"EdgeRuntime" in globalThis	noble (pure JS)
Node.js / Deno / Bun	Default	noble (pure JS)

The noble provider uses @noble/post-quantum which is a pure JavaScript implementation with no native dependencies, making it compatible with all JavaScript runtimes.

Integration with Storage SDK

import { initializePqcProvider, encryptBeforeUpload, generateEncryptionKeyPair } from "@qnsp/browser-sdk";
import { StorageClient } from "@qnsp/storage-sdk";

await initializePqcProvider();

// Generate keys
const { publicKey, privateKey } = await generateEncryptionKeyPair("kyber-768");

// Encrypt document in browser
const plaintext = await file.arrayBuffer();
const envelope = await encryptBeforeUpload(
  new Uint8Array(plaintext),
  publicKey,
  "kyber-768"
);

// Upload encrypted envelope to QNSP storage
const storage = new StorageClient({ baseUrl, apiKey, tenantId });
const upload = await storage.initiateUpload({
  name: file.name,
  mimeType: file.type,
  sizeBytes: envelope.ciphertext.length,
  classification: "confidential",
});

Key APIs

Provider Management

• initializePqcProvider() — Initialize the noble PQC provider
• isProviderInitialized() — Check if provider is ready
• getActiveProvider() — Get the active PqcProvider instance
• detectRuntime() — Detect current runtime environment
• getSupportedAlgorithms() — List all 18 supported algorithms
• resetProvider() — Reset provider state
• NOBLE_SUPPORTED_ALGORITHMS — Array of all supported algorithm names

Encryption

• encryptBeforeUpload(data, publicKey, algorithm) — Encrypt with ML-KEM + AES-256-GCM
• decryptAfterDownload(envelope, privateKey) — Decrypt CSE envelope
• serializeCseEnvelope(envelope) — Serialize to binary
• deserializeCseEnvelope(data) — Deserialize from binary

Signatures

• signData(data, privateKey, algorithm) — Sign data with ML-DSA or SLH-DSA
• verifySignature(data, signature, publicKey, algorithm) — Verify signature
• generateSigningKeyPair(algorithm) — Generate ML-DSA or SLH-DSA key pair
• generateEncryptionKeyPair(algorithm) — Generate ML-KEM key pair

Types

• CseEnvelope — Client-side encryption envelope
• SignedEnvelope — Signed data envelope
• RuntimeEnvironment — "browser" | "edge" | "node"
• PqcAlgorithm — Re-exported from @qnsp/cryptography
• PqcKeyPair — Re-exported from @qnsp/cryptography
• PqcProvider — Re-exported from @qnsp/cryptography