npm package: @obinexusmk2/zero
Description: A TypeScript implementation of Zero-Knowledge Proofs for Node.js — no trusted setup, clock-independent, fully deterministic
Author: OBINexus Computing
Latest version: 0.1.0

# Zero CLI: Zero-Knowledge Proof Command Line Interface

[![npm version](https://img.shields.io/npm/v/@obinexusmk2/zero)](https://www.npmjs.com/package/@obinexusmk2/zero)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![GitHub](https://img.shields.io/badge/GitHub-obinexusmk2-181717?logo=github)](https://www.github.com/obinexusmk2/)

## Overview

The Zero CLI provides a powerful, secure command-line interface for managing zero-knowledge proof identities, challenges, and verifications. Designed for developers and security professionals, it offers robust cryptographic operations with a simple, intuitive interface.

Built on the **OBINexus ZKP framework** — no trusted setup, no clock-dependent primitives, fully deterministic proofs.

## Prerequisites

- Node.js (version 16.0.0 or higher)
- npm (Node Package Manager)

## Installation

Install the Zero CLI globally to use it from any directory:

```bash
npm install -g @obinexusmk2/zero
```

Or add it to a specific project:

```bash
npm install @obinexusmk2/zero
```

---

## Quick Start: End-to-End Workflow

The fastest path to a signed, verified identity:

```bash
# 1. Create an identity — produces alice.zid (identity) + alice.zid.key (key, separate)
zero create -i identity.json -o alice.zid

# 2. Generate a 64-byte challenge
zero challenge -o challenge.bin -s 64

# 3. Produce a zero-knowledge proof
zero prove -i alice.zid -c challenge.bin -o proof.bin

# 4. Verify the proof
zero verify-proof -i proof.bin -c challenge.bin -d alice.zid

# 5. Seal a time capsule bound to the proof (clock-independent)
zero timecapsule seal -i proof.bin -c challenge.bin -d alice.zid -o alice.ztc

# 6. Open the capsule at abstract sequence 7
zero timecapsule open -i alice.ztc -d alice.zid -s 7
```

---

## Identity Management

### 1. Creating an Identity

Creates two separate, strictly scoped files:
- `alice.zid` — identity payload (`hash`, `salt`, `version`)
- `alice.zid.key` — verification key only (never bundled with identity)

```bash
zero create -i identity.json -o alice.zid
```

Example `identity.json`:
```json
{
  "name": "Alice Okpala",
  "email": "alice@obinexuscomputing.com",
  "role": "Developer"
}
```

With verbose output and a custom algorithm:
```bash
zero create -i identity.json -o alice.zid -a sha512 -s 64 -v
```

Output as JSON instead of the default text format:
```bash
zero create -i identity.json -o alice.zid -f json
```

Output as binary (compact, embed in binary protocols):
```bash
zero create -i identity.json -o alice.zid -f binary
```

#### Options
| Flag | Description | Default |
|------|-------------|---------|
| `-i, --input <file>` | Input JSON file with identity data | required |
| `-o, --output <file>` | Output `.zid` file | required |
| `-s, --salt <bytes>` | Salt length in bytes | `32` |
| `-a, --algorithm <algo>` | Hash algorithm (`sha256`, `sha384`, `sha512`) | `sha512` |
| `-f, --format <format>` | Output format (`text`, `json`, `binary`) | `text` |
| `-v, --verbose` | Display detailed identity information | — |

---

### 2. Verifying an Identity

Verifies that input data reproduces the hash stored in the key file. The `.zid` path is automatically derived from the `.zid.key` path (`alice.zid.key` → `alice.zid`).

```bash
zero verify -i identity.json -k alice.zid.key
```

Supply the identity file explicitly (useful when files are in different directories):
```bash
zero verify -i identity.json -k alice.zid.key -d /secure/store/alice.zid
```

Verify with verbose output (shows hash comparison details):
```bash
zero verify -i identity.json -k alice.zid.key -v
```

Verify a JSON-format identity file:
```bash
zero verify -i identity.json -k alice.zid.key -d alice.zid -v
```

#### Options
| Flag | Description | Default |
|------|-------------|---------|
| `-i, --input <file>` | Input JSON file to verify | required |
| `-k, --key <file>` | Key file (`.zid.key`) | required |
| `-d, --id <file>` | Identity file (`.zid`); auto-derived if omitted | — |
| `-v, --verbose` | Show detailed verification information | — |

---

### 3. Deriving Specialized Identities

Derive a purpose-scoped sub-identity from a base identity using PBKDF2. Derived identities are cryptographically bound to both the parent and the purpose string.

```bash
zero derive -i alice.zid -p "authentication" -o alice.auth.zid
```

Derive for different contexts:
```bash
# Signing context
zero derive -i alice.zid -p "signing" -o alice.signing.zid

# Monthly session token
zero derive -i alice.zid -p "session:2026-02" -o alice.session.zid

# Output as JSON
zero derive -i alice.zid -p "api-access" -o alice.api.zid -f json
```

#### Options
| Flag | Description | Default |
|------|-------------|---------|
| `-i, --input <file>` | Base identity file | required |
| `-p, --purpose <str>` | Purpose string for the derivation | required |
| `-o, --output <file>` | Output derived identity file | — |
| `-a, --algorithm <algo>` | KDF algorithm | `pbkdf2-sha512` |
| `-f, --format <format>` | Output format (`text`, `json`, `binary`) | `text` |

---

### 4. Generating Challenges

Create a cryptographically random challenge for a ZKP round. Challenges are one-time-use — generate a fresh one for each proof session.

```bash
zero challenge -o challenge.bin -s 64
```

Small challenge for testing (minimum recommended is 32 bytes):
```bash
zero challenge -o challenge.bin -s 32
```

Generate multiple challenges for a batch of sessions:
```bash
for i in 1 2 3; do
  zero challenge -o "challenge_${i}.bin" -s 64
done
```

#### Options
| Flag | Description | Default |
|------|-------------|---------|
| `-o, --output <file>` | Output challenge file | required |
| `-s, --size <bytes>` | Challenge size in bytes | `32` |

---

### 5. Creating Proofs

Generate a non-interactive zero-knowledge proof binding an identity to a challenge (Schnorr protocol via Fiat-Shamir transform).

```bash
zero prove -i alice.zid -c challenge.bin -o proof.bin
```

Output as Base64 (useful for embedding in HTTP headers or JSON payloads):
```bash
zero prove -i alice.zid -c challenge.bin -o proof.b64 -f base64
```

Prove with verbose logging (prints proof size, algorithm, timing):
```bash
zero prove -i alice.zid -c challenge.bin -o proof.bin -v
```

Prove using a derived identity:
```bash
zero prove -i alice.auth.zid -c challenge.bin -o proof.bin -v
```

#### Options
| Flag | Description | Default |
|------|-------------|---------|
| `-i, --input <file>` | Identity file | required |
| `-c, --challenge <file>` | Challenge file | required |
| `-o, --output <file>` | Proof output file | required |
| `-f, --format <format>` | Output format (`binary`, `base64`) | `binary` |
| `-v, --verbose` | Display proof details | — |

---

### 6. Verifying Proofs

Verify that a proof is valid for the given challenge and identity. Returns exit code `0` on success, non-zero on failure.

```bash
zero verify-proof -i proof.bin -c challenge.bin -d alice.zid
```

Verify a Base64-encoded proof:
```bash
zero verify-proof -i proof.b64 -c challenge.bin -d alice.zid
```

Verify against a derived identity:
```bash
zero verify-proof -i proof.bin -c challenge.bin -d alice.auth.zid
```

Use in CI pipelines (non-zero exit on failure):
```bash
zero verify-proof -i proof.bin -c challenge.bin -d alice.zid && echo "PASS" || echo "FAIL"
```

#### Options
| Flag | Description | Default |
|------|-------------|---------|
| `-i, --input <file>` | Proof file | required |
| `-c, --challenge <file>` | Challenge file | required |
| `-d, --id <file>` | Identity file | required |

---

## Time Capsule

The Time Capsule seals a proof against an **abstract sequence counter** — not a wall clock. Time is modelled as set membership (T_i ∈ T), with no timestamps and no epoch dependency. This makes capsules deterministic, audit-friendly, and immune to clock skew.

**Mathematical model**

| Concept | Formula |
|---------|---------|
| GCD quantum | `gcd(interval₁, interval₂, …)` |
| Poisson factor | `√(sealSequence² + quantum²)` |
| Window membership | `sealSeq ≤ openSeq ≤ sealSeq + max(intervals)` |

Default intervals `[5, 15, 30]` yield **GCD = 5**, **windowSize = 30** sequence units.

### Sealing a Capsule

Seal a proof at the current context sequence:
```bash
zero timecapsule seal -i proof.bin -c challenge.bin -d alice.zid -o alice.ztc
```

Custom intervals (abstract sequence units, comma-separated):
```bash
zero timecapsule seal \
  -i proof.bin \
  -c challenge.bin \
  -d alice.zid \
  -o alice.ztc \
  --intervals "10,20,40"
```

Seal at a specific sequence counter (useful for reproducible tests):
```bash
zero timecapsule seal \
  -i proof.bin \
  -c challenge.bin \
  -d alice.zid \
  -o alice.ztc \
  --sequence 42
```

#### Options
| Flag | Description | Default |
|------|-------------|---------|
| `-i, --input <file>` | Proof file | required |
| `-c, --challenge <file>` | Challenge file | required |
| `-d, --id <file>` | Identity file | required |
| `-o, --output <file>` | Output `.ztc` capsule file | required |
| `--intervals <list>` | Comma-separated interval values | `5,15,30` |
| `--sequence <n>` | Override seal sequence counter | context default |

### Opening a Capsule

Open and verify a capsule at a given sequence. Performs four checks: window membership, quantum alignment, identity binding, and embedded ZKP proof validity.

```bash
zero timecapsule open -i alice.ztc -d alice.zid -s 7
```

Open with verbose proof breakdown:
```bash
zero timecapsule open -i alice.ztc -d alice.zid -s 12 -v
```

Use in scripts (exit code reflects success/failure):
```bash
zero timecapsule open -i alice.ztc -d alice.zid -s 7 && echo "Capsule opened" || echo "Capsule rejected"
```

#### Options
| Flag | Description | Default |
|------|-------------|---------|
| `-i, --input <file>` | Capsule file (`.ztc`) | required |
| `-d, --id <file>` | Identity file (`.zid`) | required |
| `-s, --sequence <n>` | Sequence counter at open time | required |
| `-v, --verbose` | Print full capsule metadata | — |

### Inspecting a Capsule

Display capsule metadata without verifying:
```bash
zero timecapsule info -i alice.ztc
```

Check whether a specific sequence falls inside the window:
```bash
zero timecapsule info -i alice.ztc --sequence 10
```

Sample output:
```
Time Capsule: alice.ztc
  Version:        1
  Seal sequence:  0
  Window size:    30
  Quantum (GCD):  5
  Poisson factor: 5.0000
  Intervals:      short=5, medium=15, long=30
  Sequence 10:    IN WINDOW ✓
```

---

## System Information

View library version, supported algorithms, and runtime state:

```bash
zero info
```

Output includes CLI/library version, protocol version, supported algorithms, active identities, and current memory usage.

---

## Programmatic API

### Identity creation

```typescript
import { ZeroContext } from '@obinexusmk2/zero';

const ctx = new ZeroContext();
const id  = await ctx.createId({ name: 'Alice', role: 'admin' });
console.log('ID hash:', id.hash.toString('hex'));
```

### Challenge / prove / verify round-trip

```typescript
import { ZeroContext } from '@obinexusmk2/zero';

const ctx       = new ZeroContext();
const id        = await ctx.createId({ name: 'Alice' });
const challenge = await ctx.createChallenge(64);
const proof     = await ctx.prove(id, challenge);
const valid     = await ctx.verifyProof(proof, challenge, id);

console.log('Valid:', valid); // true
```

### TimeCapsule

```typescript
import {
  sealTimeCapsule,
  openTimeCapsule,
  isTimeCapsuleValid,
} from '@obinexusmk2/zero';

// Seal — no Date.now(), abstract sequence only
const capsule = await sealTimeCapsule(proof, challenge, id, {
  intervals: [
    { name: 'short',  value: 5  },
    { name: 'medium', value: 15 },
    { name: 'long',   value: 30 },
  ],
  sealSequence: 0,
});

// Window membership check (synchronous)
console.log('seq 7  in window:', isTimeCapsuleValid(capsule, 7));   // true
console.log('seq 99 in window:', isTimeCapsuleValid(capsule, 99));  // false

// Full open (runs all four verification checks)
const result = await openTimeCapsule(capsule, id, 7);
console.log('Opened:', result.success);
console.log('Quantum (GCD):', result.quantum);           // 5
console.log('Poisson factor:', result.poissonFactor.toFixed(4)); // 5.0000
```

### Parser — reading `.zid` and `.zid.key` separately

```typescript
import { ZeroParser, FileFormat } from '@obinexusmk2/zero';
import { readFileSync } from 'fs';

const parser = new ZeroParser();

// Read identity-only file
const idData  = parser.parseZidFile(readFileSync('alice.zid'));
console.log('ID hash:', idData.id!.hash.toString('hex'));

// Read key-only file (no id present — separation of concern enforced)
const keyData = parser.parseZidFile(readFileSync('alice.zid.key'));
console.log('Key hash:', keyData.key!.hash.toString('hex'));

// Serialise key-only OutputData — id is no longer required
const out = parser.serializeData({ key: keyData.key }, FileFormat.TEXT);
// # Zero Key File
// hash: <hex>
// timestamp: <ms>
console.log(out);
```

### Deriving sub-identities programmatically

```typescript
import { ZeroContext } from '@obinexusmk2/zero';

const ctx     = new ZeroContext();
const baseId  = await ctx.createId({ name: 'Alice' });

const authId  = await ctx.deriveId(baseId, 'authentication');
const signId  = await ctx.deriveId(baseId, 'signing');

// Each derived identity has a distinct hash bound to its purpose
console.log('auth hash ≠ sign hash:', authId.hash.toString('hex') !== signId.hash.toString('hex'));
```

---

## File Format Reference

| Extension | Contents | Notes |
|-----------|----------|-------|
| `.zid` | Identity only (`hash`, `salt`, `version`) | Never contains the key |
| `.zid.key` | Key only (`hash`, `timestamp`) | Never contains the identity |
| `.ztc` | Time Capsule (`proof`, `challenge`, `quantum`, `poissonFactor`, …) | Clock-independent |
| `.bin` | Raw binary challenge or proof | |
| `.b64` | Base64-encoded proof | Embed in JSON / HTTP headers |

### Text format examples

**`alice.zid`**
```
# Zero Identity File
version: 1
hash: a3f2c1...
salt: 9e4b12...
```

**`alice.zid.key`**
```
# Zero Key File
hash: 7d8a3f...
timestamp: 1700000000000
```

---

## Security Considerations

- Identities are cryptographically bound and cannot be reverse-engineered
- All comparisons use constant-time functions to prevent timing attacks
- `.zid` and `.zid.key` are **always separate files** — separation of concern enforced at the file-system level
- Supports SHA-256, SHA-384, SHA-512, and SHA3 variants
- Secure memory with canary-based overflow detection and multi-pass wipe patterns
- Time Capsule uses no wall-clock time — immune to clock skew, replay attacks, and NTP manipulation

---

## Troubleshooting

1. Ensure Node.js ≥ 16.0.0 (`node --version`)
2. Verify input files are correctly formatted (use `zero info` to check library state)
3. Check file permissions — `.zid.key` should be `600` (owner read/write only)
4. Use `-v, --verbose` on any command for detailed error output
5. If `zero verify` cannot find the `.zid` file, pass it explicitly with `-d`
6. If the build fails with `EPERM` on `dist/`, run `chmod -R u+w dist bin` before rebuilding

---

## Contributing

Contributions are welcome! Visit the repository, open an issue, or submit a pull request:

- **GitHub:** [https://www.github.com/obinexusmk2/](https://www.github.com/obinexusmk2/)
- **Repository:** [https://www.github.com/obinexusmk2/node-zero](https://www.github.com/obinexusmk2/node-zero)
- **Issues:** [https://www.github.com/obinexusmk2/node-zero/issues](https://www.github.com/obinexusmk2/node-zero/issues)
- **Discussions:** [https://www.github.com/obinexusmk2/node-zero/discussions](https://www.github.com/obinexusmk2/node-zero/discussions)

---

## Support

For additional support, file an issue on GitHub or contact:

- **GitHub:** [https://www.github.com/obinexusmk2/](https://www.github.com/obinexusmk2/)
- **Email:** support@obinexuscomputing.com