Package Exports
- @qpher/sdk
Readme
@qpher/sdk
Official Node.js SDK for the Qpher Post-Quantum Cryptography API.
Installation
npm install @qpher/sdkRequirements
- Node.js 18+
Quick Start
import { Qpher } from '@qpher/sdk';
// Initialize the client
const client = new Qpher({ apiKey: 'qph_live_your_api_key' });
// Encrypt data using Kyber768 KEM
const encrypted = await client.kem.encrypt({
plaintext: Buffer.from('Hello, Quantum World!'),
keyVersion: 1,
});
console.log('Ciphertext:', encrypted.ciphertext.toString('hex'));
// Decrypt data
const decrypted = await client.kem.decrypt({
ciphertext: encrypted.ciphertext,
keyVersion: encrypted.keyVersion,
});
console.log('Plaintext:', decrypted.plaintext.toString());
// Sign a message using Dilithium3
const signed = await client.signatures.sign({
message: Buffer.from('Invoice #12345'),
keyVersion: 1,
});
console.log('Signature:', signed.signature.toString('hex'));
// Verify a signature
const verified = await client.signatures.verify({
message: Buffer.from('Invoice #12345'),
signature: signed.signature,
keyVersion: signed.keyVersion,
});
console.log('Valid:', verified.valid);API Reference
Client Initialization
import { Qpher } from '@qpher/sdk';
const client = new Qpher({
apiKey: 'qph_live_your_api_key', // Required
baseUrl: 'https://api.qpher.ai', // Optional, default
timeout: 30000, // Optional, milliseconds
maxRetries: 3, // Optional
});KEM Operations (Kyber768)
Encrypt
const result = await client.kem.encrypt({
plaintext: Buffer.from('secret data'),
keyVersion: 1,
mode: 'standard', // Optional: 'standard' | 'deterministic'
salt: Buffer.alloc(32), // Required if mode='deterministic'
});
// result.ciphertext: Buffer
// result.keyVersion: number
// result.algorithm: string ('Kyber768')
// result.requestId: stringDecrypt
const result = await client.kem.decrypt({
ciphertext: encryptedData,
keyVersion: 1,
});
// result.plaintext: Buffer
// result.keyVersion: number
// result.algorithm: string
// result.requestId: stringSignature Operations (Dilithium3)
Sign
const result = await client.signatures.sign({
message: Buffer.from('document to sign'),
keyVersion: 1,
});
// result.signature: Buffer (3,293 bytes)
// result.keyVersion: number
// result.algorithm: string ('Dilithium3')
// result.requestId: stringVerify
const result = await client.signatures.verify({
message: Buffer.from('document to sign'),
signature: signatureBuffer,
keyVersion: 1,
});
// result.valid: boolean
// result.keyVersion: number
// result.algorithm: string
// result.requestId: stringKey Management
Generate Key
const result = await client.keys.generate({ algorithm: 'Kyber768' });
// result.keyVersion: number
// result.algorithm: string
// result.status: string ('active')
// result.publicKey: Buffer
// result.createdAt: stringRotate Key
const result = await client.keys.rotate({ algorithm: 'Kyber768' });
// result.keyVersion: number (new)
// result.oldKeyVersion: number
// result.algorithm: string
// result.publicKey: BufferGet Active Key
const keyInfo = await client.keys.getActive({ algorithm: 'Kyber768' });
// keyInfo.keyVersion: number
// keyInfo.algorithm: string
// keyInfo.status: string
// keyInfo.publicKey: Buffer
// keyInfo.createdAt: stringList Keys
const result = await client.keys.list({
algorithm: 'Kyber768', // Optional filter
status: 'active', // Optional filter
});
// result.keys: KeyInfo[]
// result.total: numberRetire Key
const result = await client.keys.retire({
algorithm: 'Kyber768',
keyVersion: 1,
});
// result.keyVersion: number
// result.status: string ('retired')Error Handling
import {
Qpher,
QpherError,
AuthenticationError,
ValidationError,
NotFoundError,
RateLimitError,
} from '@qpher/sdk';
try {
const result = await client.kem.encrypt({
plaintext: Buffer.from('data'),
keyVersion: 99,
});
} catch (err) {
if (err instanceof NotFoundError) {
console.log(`Key not found: ${err.message}`);
console.log(`Error code: ${err.errorCode}`);
console.log(`Request ID: ${err.requestId}`);
} else if (err instanceof RateLimitError) {
console.log('Rate limit exceeded, please retry later');
} else if (err instanceof AuthenticationError) {
console.log('Invalid API key');
} else if (err instanceof ValidationError) {
console.log(`Invalid input: ${err.message}`);
} else if (err instanceof QpherError) {
console.log(`API error: ${err.message}`);
}
}Error Types
| Exception | HTTP Status | Description |
|---|---|---|
AuthenticationError |
401 | Invalid or missing API key |
ValidationError |
400 | Invalid request parameters |
ForbiddenError |
403 | Operation not allowed |
NotFoundError |
404 | Resource not found |
RateLimitError |
429 | Rate limit exceeded |
ServerError |
500+ | Server-side errors |
TimeoutError |
504 | Request timed out |
ConnectionError |
503 | Connection failed |
TypeScript Support
This SDK is written in TypeScript and provides full type definitions. All input and output types are exported:
import {
QpherOptions,
EncryptInput,
EncryptResult,
DecryptInput,
DecryptResult,
SignInput,
SignResult,
VerifyInput,
VerifyResult,
KeyInfo,
KeyListResult,
// ... and more
} from '@qpher/sdk';Supported Algorithms
| Algorithm | Type | Security Level |
|---|---|---|
| Kyber768 | KEM (Encryption) | NIST Level 3 |
| Dilithium3 | Digital Signatures | NIST Level 3 |
License
MIT License - see LICENSE for details.