> For the complete documentation index, see [llms.txt](https://emmanuels-organization-21.gitbook.io/projekt-kinetic/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://emmanuels-organization-21.gitbook.io/projekt-kinetic/kinetic-keys-javascript-sdk-documentation.md).

# 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](https://emmanuels-organization-21.gitbook.io/kinetic/kinetic-keys-a-lightweight-zero-knowledge-framework-for-secure-digital-transactions)

### ✨ Features

* 🔑[ Generate unique unlock hashes](#generate-unlock-hashes) ([single](#single-mode) or [dual ](#dual-mode)mode)
* 🔍 [Verify unlock hashes](#verify-unlock-hashes)
* 🧬[ Poem-matrix-based key generation and granular reconstruction](#key-derivation-using-poem-matrix)
* 📦 [Create and decrypt Kinetic Key vouchers](#create-kinetic-key-voucher)
* 🆔 [Generate unique IDs for users or sessions](#unique-id-generation)

### ⚠️ 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

```js
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:

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

***

### ✅ Verify Unlock Hashes

```js
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.

```js
const voucherID = await generateUniqueID(32);

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

***

### 🔓 Decrypt Kinetic Key Voucher

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

#### Dual Unlock Example

```js
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

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

#### Derive Key and Blueprint

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

#### Reconstruct Text

```js
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

```js
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

```js
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:

```js
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](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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://emmanuels-organization-21.gitbook.io/projekt-kinetic/kinetic-keys-javascript-sdk-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.