nzcore 🔐

Personal autonomous Root of Trust — deterministic identity and cryptographic document chain based on RFC 8785 (Canonical JSON), Ed25519, BIP-39, logical time, and fork detection.

📋 Table of Contents

Project Overview
Key Features
Project Status
Quick Start
Installation
Documentation
Usage Examples
Security
Testing
Contributing
License
Support

📖 Project Overview

nzcore is a cryptographic library for creating a personal autonomous Root of Trust. It provides deterministic identity and maintains an immutable chain of signed documents without relying on external services or system time.

Core Purpose

Deterministic Identity: Your identity is derived solely from a BIP-39 mnemonic phrase
Cryptographic Document Chain: Each document is signed and linked to the previous one via hash
Logical Time: Monotonic counter instead of system time for security decisions
Fork Detection: Automatic detection of chain divergences

Trust Architecture

BIP-39 Mnemonic → Seed → Master Key → Identity
                       ↓
            Document Chain (Ed25519)
                       ↓
            RFC 8785 Canonical JSON
                       ↓
            Logical Time (monotonic)

✨ Key Features

Feature	Description
🔑 Deterministic Identity	Identity derived solely from 24-word BIP-39 mnemonic phrase
📝 Canonical JSON (RFC 8785)	Deterministic serialization for reproducible signatures
⏰ Logical Time	Monotonic counter without system clock dependencies
🔍 Fork Detection	Automatic detection of chain divergences
🛡️ Secure Memory	Zeroization of sensitive data after use
🔐 Multi-layer Trust	Structural → Cryptographic → Policy validation
🌐 Cross-platform	Works in Node.js and browsers
📦 Minimal Dependencies	Only audited cryptographic libraries

📊 Project Status

Parameter	Value
Version	1.0.0
Status	✅ Production Ready
Minimum Node.js	18.0.0+
TypeScript Types	✅ Included
License	MIT / Apache-2.0 (dual)

🚀 Quick Start

1. Installation

npm install nzcore

2. Create Identity

import { generateIdentity, NewZoneCore } from 'nzcore';

// Generate new identity (24-word BIP-39 mnemonic)
const { mnemonic, core } = await generateIdentity();
console.log('Mnemonic:', mnemonic); // ⚠️ Store securely!
console.log('Public Key:', core.getPublicKeyHex());
console.log('Chain ID:', core.getChainId());

3. Create and Sign Document

const doc = await core.createDocument('profile', {
  name: 'Alice Johnson',
  email: 'alice@example.com'
});

console.log('Document ID:', doc.id);
console.log('Signature:', doc.signature);

4. Verify Document

const result = await core.verifyDocument(doc);
console.log('Valid:', result.final); // true if valid

5. Export/Import State

// Export chain state
const state = core.exportState();

// Create new instance and import
const newCore = await NewZoneCore.create(mnemonic);
newCore.importState(state);

6. Detect Forks

const forks = core.detectFork();
if (forks.length > 0) {
  console.log('⚠️ Fork detected:', forks);
  // Core does NOT resolve forks automatically
}

7. Secure Cleanup

// Securely zeroize private key
core.destroy();

📦 Installation

From npm

npm install nzcore

From GitHub (Development)

git clone https://github.com/NewZoneProject/nzcore.git
cd nzcore
npm install
npm run build

System Requirements

Component	Requirement
Node.js	18.0.0 or higher
npm	7.0.0 or higher
Operating System	Linux, macOS, Windows
Memory	Minimum 256 MB RAM

📚 Documentation

Complete documentation is organized into the following sections:

Document	Description
ARCHITECTURE.md	System architecture, component and data flow diagrams
API.md	Complete API reference with examples
DEPLOYMENT.md	Deployment and integration guide
SECURITY.md	Security model and best practices
CONTRIBUTING.md	Contributor guidelines

Additional Specifications

The specs/ folder contains detailed specifications:

TRUST_MODEL.md — Trust model (three validation layers)
CRYPTO_SPEC.md — Cryptographic stack (nzcore-crypto-01)
IDENTITY_MODEL.md — Identity model
DOCUMENT_SYSTEM.md — Document system
TIME_MODEL.md — Logical time model
FORK_MODEL.md — Fork detection model
THREAT_MODEL.md — Threat model

💡 Usage Examples

Basic Example

npm run example:basic

Source: examples/basic-usage.ts

Advanced Example

npm run example:advanced

Source: examples/advanced-usage.ts

Usage Scenarios

1. Personal Data Store

// Create chain of personal data
const profile = await core.createDocument('profile', {
  name: 'Alice',
  publicKey: '...'
});

const settings = await core.createDocument('settings', {
  theme: 'dark',
  language: 'en'
});

const activity = await core.createDocument('activity', {
  action: 'login',
  timestamp: Date.now()
});

2. Audit Logging

// Immutable event log
const auditLog = await core.createDocument('audit', {
  event: 'data_access',
  userId: '123',
  resource: '/api/data'
});

3. External Data Verification

// Verify document through three trust layers
const result = await core.verifyDocument(document);
console.log('Structural validity:', result.structural_valid);
console.log('Cryptographic validity:', result.cryptographic_valid);
console.log('Policy validity:', result.policy_valid);
console.log('Final result:', result.final);

🛡️ Security

Cryptographic Stack (nzcore-crypto-01)

Component	Implementation
Digital Signatures	Ed25519 (@noble/ed25519)
Hashing	BLAKE2b-256 (@noble/hashes)
KDF	scrypt (N=32768, r=8, p=1)
Key Derivation	HKDF-SHA256
Mnemonic	BIP-39 (@scure/bip39)
Canonicalization	RFC 8785 Canonical JSON

Security Principles

Deterministic Identity: Identity is a function of mnemonic only
No External Dependencies: No system time dependencies for security decisions
Secure Memory: All sensitive data is zeroized before garbage collection
Constant-Time Operations: Comparison operations run in constant time
Manual Fork Resolution: Core detects but never resolves forks automatically

Best Practices

// ✅ GOOD: Store mnemonic in secure storage
const { mnemonic } = await generateIdentity();
await secureStorage.save('mnemonic', mnemonic);

// ✅ GOOD: Destroy instance after use
core.destroy();

// ❌ BAD: Store mnemonic in code or environment variables
const MNEMONIC = process.env.MNEMONIC; // Never do this!

🧪 Testing

Run All Tests

npm test

Run Individual Tests

# Integration tests
node --test dist/test/integration.test.js

# Debug tests
node --test dist/test/debug.test.js

# Mnemonic tests
node --test dist/test/mnemonic-debug.test.js

Test Structure

Test Type	Description
Unit Tests	Testing individual components
Integration Tests	Testing complete workflows
Security Tests	Verifying security properties

Code Coverage

npx c8 npm test

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md.

Development Setup

# Clone repository
git clone https://github.com/NewZoneProject/nzcore.git
cd nzcore

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

# Run linter
npm run lint

Pull Request Process

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Write tests for new features
Ensure all tests pass
Update documentation
Submit Pull Request

📄 License

Dual-licensed (your choice):

MIT License — see LICENSE-MIT file
Apache License 2.0 — see LICENSE-APACHE file

🙏 Acknowledgments

This library uses the following open-source projects:

@noble/ed25519 — Ed25519 implementation
@noble/hashes — Cryptographic hash functions
@scure/bip39 — BIP-39 implementation
canonicalize — JSON canonicalization (RFC 8785)

📞 Support

Channel	Link
GitHub Issues	Report an issue
npm	Package on npm
Repository	GitHub

Security Vulnerabilities

For reporting security vulnerabilities, please contact project maintainers privately. Do not disclose vulnerabilities publicly before they are resolved.

📖 Glossary

Term	Definition
Root of Trust	Source of truth for verification
Mnemonic	24-word phrase for identity recovery (BIP-39)
Chain ID	Unique identifier for document chain
Logical Time	Monotonic counter for document ordering
Fork	Situation where two documents reference the same parent hash
Canonical JSON	Deterministic JSON serialization (RFC 8785)

Last updated: February 20, 2026

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
dist		dist
docs		docs
examples		examples
node_modules		node_modules
specs		specs
src		src
test		test
.npmignore		.npmignore
API.md		API.md
ARCHITECTURE.md		ARCHITECTURE.md
CONTRIBUTING.md		CONTRIBUTING.md
DEPLOYMENT.md		DEPLOYMENT.md
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
eslint.config.js		eslint.config.js
nzcore-1.0.0.tgz		nzcore-1.0.0.tgz
package-lock.json		package-lock.json
package.json		package.json
promt_nzcore_docs.md		promt_nzcore_docs.md
tsconfig.cjs.json		tsconfig.cjs.json
tsconfig.esm.json		tsconfig.esm.json
tsconfig.json		tsconfig.json
tsconfig.types.json		tsconfig.types.json
typedoc.json		typedoc.json

NewZoneProject/nzcore

Folders and files

Latest commit

History

Repository files navigation