Requirements
- Node.js with built-in
crypto(PBKDF2, HMAC, SHA-256, random bytes, timing-safe compare) - TypeScript 5.x for building from source (included in dev dependencies)
Package contents
src/index.ts— core implementation and exports (HotkeyEncryption,HKeyPacket, constants)src/example.ts— example usagepackage.json,tsconfig.json— build configuration
Build
cd sdk/typescript
npm install
npm run build
Quick start
import { HotkeyEncryption } from '@hkey/sdk';
const hkey = new HotkeyEncryption('lab.freezer.alpha', [
'Ctrl+Alt+H', 'Shift+K', 'Meta+E', 'Y',
]);
const packetJson = hkey.encryptText('sensitive payload');
const plain = hkey.decryptText(packetJson);
console.log(hkey.digest); // sequence digest
console.log(plain); // "sensitive payload"
API overview
new HotkeyEncryption(gestureSalt: string, chords: string[], iterations = 210000)encrypt(plaintext: Uint8Array | string, nonce?: Buffer): HKeyPacketdecrypt(packet: HKeyPacket): Buffer— verifies withtimingSafeEqualbefore returning plaintextencryptText(text: string): string/decryptText(packetJson: string): stringsequenceEncoding(): stringanddigestpropertystatic normalizeChord(chord: string): string— canonical chord form
Interop notes
- Uses UTF-8 sequence encoding, PBKDF2-HMAC-SHA256 (210k, 32 bytes), HMAC-derived subkeys, 12-byte nonce, big-endian counters/length, and base64 packet fields—matching PHP/Python/Mojo HKEY v1 behavior.
- For browsers, port the same byte layouts to WebCrypto (PBKDF2 + HMAC-SHA256) to remain interoperable.
Good practices
- Bind a unique salt per app/tenant/environment; prefer 4+ mixed chords.
- Do not persist or log raw chord sequences.
- Treat tag verification failures as hard errors.
Reference implementation for education and prototyping. For regulated or high-risk use, perform independent review and consider audited standard AEAD cores in production deployments.