Kinetic Keys Javascript SDK Documentation

Kinetic Keys SDK

Kinetic Keys (KK) is a novel cryptographic framework that enables secure, privacy-preserving digital transactions without exposing sensitive underlying data. Unlike traditional zero-knowledge proofs (ZKPs) that impose significant computational overhead, Kinetic Keys achieves comparable security guarantees through hierarchical key derivation, deterministic encryption, and structured hashing techniques. The system provides a deterministic yet tamper-resistant mechanism for issuing, transferring, and verifying digital assets with minimal computational requirements.

This SDK includes a set of utilities for generating secure keys, encrypting/decrypting payloads, managing unlock hashes, and reconstructing content using granular poem-based key derivation.

Whitepaper: https://emmanuels-organization-21.gitbook.io/kinetic/kinetic-keys-a-lightweight-zero-knowledge-framework-for-secure-digital-transactions

✨ Features

⚠️ Environment

This SDK is for use in Node.js environments only. Browser-based environments are currently unsupported.

🔐 Generate Unlock Hashes

The foundation of Kinetic Keys is the Unlock Hash (UH), a secure, non-reversible transformation of a user's secret passphrase. The UH serves as the cryptographic anchor for all subsequent operations.

Single Mode

const hash = generateUnlockHash('U&Z1I2$9');
console.log(hash);
// Example output: cb7dd3e80e275d58735d0f7991796bb6.KUcS91vx5Dm4Hzc

Dual Mode

The dual mode allows a voucher or transaction to be unlocked using two separate passphrases:

const dualHash = generateUnlockHash('1234', '8888', 'dual');
console.log(dualHash);
// Example output: dual.58d072cf8f27fdaafb2f22eca81dc851.x8w9tBS81QSTg1ftA2xzmAdT0bBtUW.QQhz.gCEB

✅ Verify Unlock Hashes

const result = verifyUnlockHash('U&Z1I2$9', '<storedUnlockHash>');
console.log(result); // true or false

📦 Create Kinetic Key Voucher

Encapsulate sensitive data within a voucher that can only be decrypted using the correct passphrase.

const voucherID = await generateUniqueID(32);

const voucher = createVoucher({
  id: voucherID,
  payload: "Sensitive asset metadata"
}, UnlockHash, SYSTEM_SECRET_KEY);

🔓 Decrypt Kinetic Key Voucher

const data = decryptVoucher(voucher, 'U&Z1I2$9', UnlockHash);
console.log(data); // Original payload object

Dual Unlock Example

const dualData = decryptVoucher(voucher, '1234', dualUnlockHash);
console.log(dualData); // Original payload object

📐 Key Derivation Using Poem Matrix

The poem-matrix-based approach generates encryption keys by selecting randomized segments from a matrix of strings, enabling secure transmission of sensitive data with only a reconstruction blueprint.

Generate Poem Matrix

const poemMatrix = generatePoemMatrix();
console.log(poemMatrix);
// Example output:
// ["I0RIIIhO", "zmTi04jX", "mLr$oS9T", "ZTHrgcUu", "#8tfPHkZ", ...]

Derive Key and Blueprint

const { key, indices, keyId } = generateKeyWithPoemMatrix(poemMatrix);
const blueprint = await deriveBlueprintGranular("Secret text", key);

Reconstruct Text

const original = await reconstructTextGranular(blueprint, key);
console.log(original); // "Secret text"

🔐 Unique ID Generation

The Kinetic Keys SDK includes a utility to generate unique identifiers using a cryptographically secure random generator based on nanoid. These IDs are useful for generating unique voucher IDs, session tokens, or user identifiers within the Kinetic Key system.

✨ Features

  • Generates cryptographically secure, non-sequential IDs

  • Customizable character set and length

  • Lightweight and efficient

📦 generateUniqueID

Generates a unique alphanumeric ID of the specified length. Internally, it uses a custom character set including special characters for added entropy.

Syntax

const { generateUniqueID } = require('@projekt-kinetic/kinetic-keys');

const id = await generateUniqueID(length);

Parameters

  • length (number): The desired length of the unique ID.

Returns

  • Promise<string>: A promise that resolves to the generated unique ID.

Example

const id = await generateUniqueID(32);
console.log(id);
// Example output: @8GcB#5dPx7zF1A&K0qLm!Z9sU#XYT3%

Under the Hood

This function wraps around the nanoid library using the customAlphabet method to create a secure, flexible ID generator with a rich character set:

const alphabet = '@#$%&!ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';

This makes the output suitable for high-entropy requirements in security-sensitive contexts.

❗ Environment

Requires Node.js. Not available for browser-based use.

Licensing: https://emmanuels-organization-21.gitbook.io/kinetic/kinetic-keys-a-lightweight-zero-knowledge-framework-for-secure-digital-transactions#license

© 2025 Projekt Kinetic. All rights reserved.

Initial Publish Date: 25-04-2025. Emmanuel Ayodele Bello

PreviousPage

Last updated