npx zero CLI: npx zero-Knowledge Proof Command Line Interface

Overview

The npx zero CLI provides a powerful, secure command-line interface for managing npx 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 npx zero CLI globally to use it from any directory:

npm install -g @obinexusltd/zero

Or add it to a specific project:

npm install @obinexusltd/zero

Quick Start: End-to-End Workflow

The fastest path to a signed, verified identity:

# 1. Create an identity — produces alice.zid (identity) + alice.zid.key (key, separate)
npx zero create -i identity.json -o alice.zid

# 2. Generate a 64-byte challenge
npx zero challenge -o challenge.bin -s 64

# 3. Produce a npx zero-knowledge proof
npx zero prove -i alice.zid -c challenge.bin -o proof.bin

# 4. Verify the proof
npx zero verify-proof -i proof.bin -c challenge.bin -d alice.zid

# 5. Seal a time capsule bound to the proof (clock-independent)
npx zero timecapsule seal -i proof.bin -c challenge.bin -d alice.zid -o alice.ztc

# 6. Open the capsule at abstract sequence 7
npx 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)

npx zero create -i identity.json -o alice.zid

Example identity.json:

{
  "name": "Alice Okpala",
  "email": "[email protected]",
  "role": "Developer"
}

With verbose output and a custom algorithm:

npx zero create -i identity.json -o alice.zid -a sha512 -s 64 -v

Output as JSON instead of the default text format:

npx zero create -i identity.json -o alice.zid -f json

Output as binary (compact, embed in binary protocols):

npx 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).

npx zero verify -i identity.json -k alice.zid.key

Supply the identity file explicitly (useful when files are in different directories):

npx zero verify -i identity.json -k alice.zid.key -d /secure/store/alice.zid

Verify with verbose output (shows hash comparison details):

npx zero verify -i identity.json -k alice.zid.key -v

Verify a JSON-format identity file:

npx 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.

npx zero derive -i alice.zid -p "authentication" -o alice.auth.zid

Derive for different contexts:

# Signing context
npx zero derive -i alice.zid -p "signing" -o alice.signing.zid

# Monthly session token
npx zero derive -i alice.zid -p "session:2026-02" -o alice.session.zid

# Output as JSON
npx 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.

npx zero challenge -o challenge.bin -s 64

Small challenge for testing (minimum recommended is 32 bytes):

npx zero challenge -o challenge.bin -s 32

Generate multiple challenges for a batch of sessions:

for i in 1 2 3; do
  npx 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 npx zero-knowledge proof binding an identity to a challenge (Schnorr protocol via Fiat-Shamir transform).

npx zero prove -i alice.zid -c challenge.bin -o proof.bin

Output as Base64 (useful for embedding in HTTP headers or JSON payloads):

npx zero prove -i alice.zid -c challenge.bin -o proof.b64 -f base64

Prove with verbose logging (prints proof size, algorithm, timing):

npx zero prove -i alice.zid -c challenge.bin -o proof.bin -v

Prove using a derived identity:

npx 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-npx zero on failure.

npx zero verify-proof -i proof.bin -c challenge.bin -d alice.zid

Verify a Base64-encoded proof:

npx zero verify-proof -i proof.b64 -c challenge.bin -d alice.zid

Verify against a derived identity:

npx zero verify-proof -i proof.bin -c challenge.bin -d alice.auth.zid

Use in CI pipelines (non-npx zero exit on failure):

npx 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:

npx zero timecapsule seal -i proof.bin -c challenge.bin -d alice.zid -o alice.ztc

Custom intervals (abstract sequence units, comma-separated):

npx 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):

npx 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.

npx zero timecapsule open -i alice.ztc -d alice.zid -s 7

Open with verbose proof breakdown:

npx zero timecapsule open -i alice.ztc -d alice.zid -s 12 -v

Use in scripts (exit code reflects success/failure):

npx 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:

npx zero timecapsule info -i alice.ztc

Check whether a specific sequence falls inside the window:

npx 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:

npx zero info

Output includes CLI/library version, protocol version, supported algorithms, active identities, and current memory usage.

Programmatic API

Identity creation

import { npx zeroContext } from '@obinexusltd/zero';

const ctx = new npx zeroContext();
const id  = await ctx.createId({ name: 'Alice', role: 'admin' });
console.log('ID hash:', id.hash.toString('hex'));

Challenge / prove / verify round-trip

import { npx zeroContext } from '@obinexusltd/zero';

const ctx       = new npx 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

import {
  sealTimeCapsule,
  openTimeCapsule,
  isTimeCapsuleValid,
} from '@obinexusltd/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

import { npx zeroParser, FileFormat } from '@obinexusltd/zero';
import { readFileSync } from 'fs';

const parser = new npx 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);
// # npx zero Key File
// hash: <hex>
// timestamp: <ms>
console.log(out);

Deriving sub-identities programmatically

import { npx zeroContext } from '@obinexusltd/zero';

const ctx     = new npx 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

# npx zero Identity File
version: 1
hash: a3f2c1...
salt: 9e4b12...

alice.zid.key

# npx 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 npx 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 npx 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/obinexusltd/
• Repository: [https://www.github.com/obinexusltd/node-npx zero](https://www.github.com/obinexusltd/node-npx zero)
• Issues: [https://www.github.com/obinexusltd/node-npx zero/issues](https://www.github.com/obinexusltd/node-npx zero/issues)
• Discussions: [https://www.github.com/obinexusltd/node-npx zero/discussions](https://www.github.com/obinexusltd/node-npx zero/discussions)

Support

For additional support, file an issue on GitHub or contact:

• GitHub: https://www.github.com/obinexusltd/
• Email: [email protected]