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": "alice@obinexuscomputing.com",
  "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

Ensure Node.js ≥ 16.0.0 (node --version)
Verify input files are correctly formatted (use npx zero info to check library state)
Check file permissions — .zid.key should be 600 (owner read/write only)
Use -v, --verbose on any command for detailed error output
If npx zero verify cannot find the .zid file, pass it explicitly with -d
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: okpalan@protonmail.com

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
MVP/phantom_decoder		MVP/phantom_decoder
__tests__		__tests__
bin		bin
docs		docs
examples		examples
scripts		scripts
src		src
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.gitkeep		.gitkeep
.npmignore		.npmignore
.npmrc		.npmrc
.prettierrc		.prettierrc
LICENSE		LICENSE
README.md		README.md
TODO.md		TODO.md
favicon.svg		favicon.svg
jest.config.mjs		jest.config.mjs
jest.setup.js		jest.setup.js
package-lock.json		package-lock.json
package.json		package.json
rollup.config.js		rollup.config.js
tsconfig.json		tsconfig.json
tsconfig.test.json		tsconfig.test.json
zero.config.json		zero.config.json

Folders and files

Latest commit

History

Repository files navigation

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

Overview

Prerequisites

Installation

Quick Start: End-to-End Workflow

Identity Management

1. Creating an Identity

Options

2. Verifying an Identity

Options

3. Deriving Specialized Identities

Options

4. Generating Challenges

Options

5. Creating Proofs

Options

6. Verifying Proofs

Options

Time Capsule

Sealing a Capsule

Options

Opening a Capsule

Options

Inspecting a Capsule

System Information

Programmatic API

Identity creation

Challenge / prove / verify round-trip

TimeCapsule

Parser — reading .zid and .zid.key separately

Deriving sub-identities programmatically

File Format Reference

Text format examples

Security Considerations

Troubleshooting

Contributing

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Parser — reading `.zid` and `.zid.key` separately

Packages