@trynullsec/s1-zk 1.0.2 → 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nullsec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,85 +1,134 @@
 # Nullsec S1-ZK
 
-AI-native auditing for zero-knowledge circuits. Find underconstraints before they mint infinite money.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/trynullsec/nullsec-s1-zk/main/assets/nullsec-s1-zk-banner.png" width="100%" />
+</p>
 
-## What Nullsec S1-ZK Is
+<p align="center">
+  <a href="https://www.npmjs.com/package/@trynullsec/s1-zk"><img src="https://img.shields.io/npm/v/@trynullsec/s1-zk?color=111827&label=npm" alt="npm version" /></a>
+  <img src="https://img.shields.io/badge/TypeScript-5.x-3178c6" alt="TypeScript" />
+  <img src="https://img.shields.io/badge/Circom-supported-16a34a" alt="Circom supported" />
+  <img src="https://img.shields.io/badge/Halo2-supported-7c3aed" alt="Halo2 supported" />
+  <img src="https://img.shields.io/badge/status-active-16a34a" alt="status active" />
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license" />
+</p>
 
-Nullsec S1-ZK is a production-grade static analysis foundation for ZK circuit auditing. It scans Circom circuits and Rust-based Halo2 circuits for high-impact soundness risks such as unsafe witness hints, missing constraints, missing range checks, missing booleanity checks, unbound inputs, unsafe assertions, component output binding mistakes, unconstrained advice assignments, and unbound Halo2 instance values.
+**AI-native auditing for zero-knowledge circuits.**
 
-It detects high-signal underconstraint patterns, but it does not prove full circuit soundness and does not replace expert cryptographic audits.
+Nullsec S1-ZK is an open-source security engine for zero-knowledge circuits.
 
-## Why ZK Underconstraints Matter
+It analyzes Circom and Halo2 circuits, builds constraint graphs, infers proof obligations, and generates exploit hypotheses for underconstraint risks.
 
-Most catastrophic ZK bugs are not ordinary application bugs. They are proof-system semantic failures where the circuit does not actually constrain what the protocol thinks it constrains. Nullsec S1-ZK is built around the question: what does this circuit claim to prove, and what does it actually constrain?
+**Find underconstraints before they mint infinite money.**
 
-## What v1 Detects
+```bash
+npx @trynullsec/s1-zk scan ./circuits
+```
+
+## Why S1-ZK Exists
+
+Catastrophic ZK bugs are often not ordinary application bugs. They are proof-system semantic failures: a witness can satisfy the constraint system while violating the protocol statement developers believe is being proven.
+
+Nullsec S1-ZK is built around one question:
+
+> What does this circuit claim to prove, and what does it actually constrain?
 
-v1 implements deterministic static analysis for Circom and best-effort static analysis for Halo2-style Rust circuits.
+The tool is designed for ZK auditors, protocol engineers, security researchers, and crypto developers who need fast, deterministic signal on underconstraints, unsafe witness assignments, missing public bindings, selector mistakes, incomplete EC relations, and other soundness risks.
 
-Circom checks include:
+## Supported Frontends
 
-- Dangerous `<--` hint assignments.
-- Assigned but unconstrained signals.
-- Input signals that never bind into constraints.
-- Unconstrained outputs.
-- Missing booleanity checks.
-- Missing range checks and aliasing risks.
-- Unsafe `assert(...)` over signals.
-- Unsafe division and inverse patterns.
-- Unconstrained component outputs.
-- Unused signals and suspicious selectors.
+### Circom
 
-Halo2 checks include:
+The Circom frontend parses `.circom` files and builds a signal/constraint graph for high-signal soundness checks:
 
-- Advice assignments that do not appear connected to gates, equality constraints, instance constraints, or lookups.
-- Instance/public values queried without an obvious public binding.
-- Selector discipline risks.
-- Unsafe inverse or division patterns.
-- Suspicious partial elliptic-curve operation assignments.
-- Copy-constraint usage without obvious `enable_equality`.
+- Dangerous hint assignments with `<--`
+- Assigned-but-unconstrained signals
+- Unbound inputs
+- Unconstrained outputs
+- Missing booleanity checks
+- Missing range checks
+- Unsafe assertions
+- Unsafe division or inverse patterns
+- Alias and overflow risks
+- Suspicious selectors
 
-## Halo2 Constraint Graph
+### Halo2-Style Rust
 
-The Halo2 frontend builds a best-effort constraint graph from Rust source. It links `create_gate` expressions, advice/fixed/instance queries, selector-gated polynomials, `assign_region` assignments, selector enables, `constrain_equal`, `copy_advice`, lookups, and `constrain_instance` public bindings.
+The Halo2 frontend scans Rust source for Halo2 patterns and builds a best-effort constraint graph over gates, regions, selectors, equality edges, and public bindings:
 
-This graph lets Nullsec S1-ZK distinguish advice values that are connected through gates, equality edges, lookups, or public instance exposure from values that are merely assigned in a region. It improves high-signal findings for Orchard-style EC gadgets and other Halo2 circuits, but it is still static source analysis, not formal verification or complete Halo2 synthesis.
+- Assigned advice not constrained
+- Instance value not bound
+- Selector discipline risk
+- Unsafe inverse/division
+- Partial EC operation risk
+- Missing `enable_equality` assumptions
+- Gate extraction
+- Assignment connectivity
+- Equality/copy edges
+- Public instance bindings
 
-## Deep Relationship Analysis
+## Deep Analysis Mode
 
-Use `--deep` to enable proof obligation extraction, relation checking, taint/dataflow analysis, and deterministic exploit hypotheses.
+`--deep` enables relationship-aware analysis beyond individual rule hits:
+
+- Proof obligation extraction
+- Relation checking
+- Taint/witness flow analysis
+- Exploit hypothesis generation
 
 ```bash
-nullsec-zk scan ./circuits --deep
+npx @trynullsec/s1-zk scan ./circuits --deep
 ```
 
-Deep analysis infers likely obligations such as commitment binding, nullifier binding, Merkle path binding, selector booleanity, EC multiplication consistency, public input binding, and range constraints. It then checks whether parsed constraints, Halo2 graph edges, equality/copy edges, lookups, and public instance bindings appear to support those obligations.
+Example deep-analysis output:
 
-This is relationship-aware static analysis. It helps auditors find gaps faster, but inferred obligations may be wrong or incomplete and are not formal proof obligations in the mathematical verification sense.
+```text
+Proof obligations:
+Total      68
+Satisfied  59
+Missing    9
+
+Exploit hypothesis:
+A malicious prover may choose EC point coordinates independently of the claimed scalar multiplication relation. If the verifier accepts those values as part of the EC output, the circuit may verify an invalid group operation.
+```
+
+Deep mode is still static analysis. It infers likely proof obligations from naming, graph relationships, and source structure, then checks whether parsed constraints appear to support those obligations.
 
 ## Installation
 
+Run without installing:
+
+```bash
+npx @trynullsec/s1-zk scan ./circuits
+```
+
+Install globally:
+
 ```bash
-npm install
-npm run build
-npm link
+npm install -g @trynullsec/s1-zk
 ```
 
 ## Usage
 
 ```bash
-nullsec-zk scan ./examples
-nullsec-zk scan ./examples/halo2
-nullsec-zk scan ./benchmarks/historical/orchard-inspired --deep
-nullsec-zk scan ./examples --format json
-nullsec-zk scan ./examples --format sarif
-nullsec-zk scan ./examples --report markdown
-nullsec-zk scan ./examples --out report.json
-nullsec-zk scan ./examples --fail-on HIGH
+nullsec-zk scan ./circuits
+nullsec-zk scan ./circuits --deep
+nullsec-zk scan ./circuits --format json
+nullsec-zk scan ./circuits --report markdown
 nullsec-zk rules
-nullsec-zk explain NS-ZK-001
+nullsec-zk explain NS-H2-005
+nullsec-zk init
 ```
 
-## Example Terminal Output
+The same commands work through `npx`:
+
+```bash
+npx @trynullsec/s1-zk scan ./circuits --deep
+npx @trynullsec/s1-zk rules
+npx @trynullsec/s1-zk explain NS-H2-005
+```
+
+## Example Output
 
 ```text
 Nullsec S1-ZK
@@ -90,73 +139,122 @@ Frontend: Mixed
 Files scanned: 24
 Rules executed: 18
 Issues found: 33
+
+Severity summary:
+CRITICAL  2
+HIGH      12
+MEDIUM    15
+LOW       4
+INFO      0
 ```
 
-## JSON Output
+## Rule Coverage
+
+Rules are documented in [`RULES.md`](./RULES.md). The current rule families include:
+
+- `NS-ZK-*` rules for Circom underconstraints, unsafe hints, missing booleanity/range checks, unsafe assertions, component-output binding, and selector risks.
+- `NS-H2-*` rules for Halo2 advice connectivity, public instance binding, selector discipline, inverse safety, EC operation completeness, and equality assumptions.
 
-JSON output includes the tool name, version, target, files scanned, rules executed, severity counts, issues, and parser warnings.
+List rules locally:
 
 ```bash
-nullsec-zk scan ./examples --format json
+nullsec-zk rules
 ```
 
-## Markdown Reports
+Explain a rule:
 
 ```bash
-nullsec-zk scan ./examples --report markdown
+nullsec-zk explain NS-H2-005
 ```
 
-By default this writes `nullsec-zk-report.md`. Use `--out` to choose another path.
+## Orchard-Inspired Benchmark
 
-## SARIF / CI Usage
+The repository includes synthetic Orchard-inspired Halo2 benchmarks under:
 
-```bash
-nullsec-zk scan ./circuits --format sarif --out nullsec-zk.sarif --fail-on HIGH
+```text
+benchmarks/historical/orchard-inspired
 ```
 
-The SARIF renderer is structured for GitHub code scanning compatibility.
+These examples are not copied from Zcash source. They are synthetic benchmark cases modeling the class of partial elliptic-curve underconstraint issues discussed publicly after the Orchard vulnerability disclosure.
 
-## Rule List
+Nullsec S1-ZK does not claim to have found the real Zcash bug, and it does not prove Zcash or Orchard security. The benchmark exists to research the same family of underconstraint risk in a small, auditable fixture.
 
-Run:
+Run it with deep analysis:
 
 ```bash
-nullsec-zk rules
+npx @trynullsec/s1-zk scan ./benchmarks/historical/orchard-inspired --deep
 ```
 
-Detailed rule documentation is in `RULES.md`.
+## Reports
+
+Nullsec S1-ZK supports:
+
+- Terminal output
+- JSON output
+- Markdown reports
+- SARIF for code-scanning workflows
+
+Examples:
+
+```bash
+nullsec-zk scan ./circuits --format json
+nullsec-zk scan ./circuits --report markdown
+nullsec-zk scan ./circuits --format sarif --out nullsec-zk.sarif
+```
 
 ## Configuration
 
-Create a config:
+Create a config file:
 
 ```bash
 nullsec-zk init
 ```
 
-Example:
+Example `.nullsec-zk.json`:
 
 ```json
 {
   "rules": {
-    "NS-ZK-006": "off",
-    "NS-ZK-005": "high"
+    "NS-ZK-006": "off"
   },
-  "ignore": ["node_modules", "circomlib"],
-  "failOn": "HIGH",
-  "format": "terminal",
-  "field": "BN254"
+  "ignore": ["node_modules", "target"],
+  "failOn": "HIGH"
 }
 ```
 
 ## Limitations
 
-Static analysis is approximate. The Circom and Halo2 frontends are best-effort source analyzers, and `--deep` infers likely proof obligations from naming and graph relationships. Nullsec S1-ZK does not compile circuits, generate witnesses, or perform formal verification. See `LIMITATIONS.md`.
+Nullsec S1-ZK is a static analysis tool:
+
+- Parsing is best-effort.
+- It is not formal verification.
+- It does not prove full circuit soundness.
+- It does not replace expert ZK or cryptographic audits.
+- Macro-heavy Rust/Halo2 code can be missed.
+- Deep analysis infers likely proof obligations and can be wrong.
+
+See [`LIMITATIONS.md`](./LIMITATIONS.md) for more detail.
 
 ## Roadmap
 
-Future work includes deeper Halo2 analysis, Noir, gnark, Plonky2, R1CS extraction, witness counterexample generation, spec-to-circuit comparison, LLM-assisted exploit reasoning, CI integrations, and hosted reporting. See `ROADMAP.md`.
+- Real Rust AST parsing via `syn`
+- Noir frontend
+- gnark frontend
+- Plonky2 frontend
+- R1CS extraction
+- Circuit graph visualization
+- GitHub Action
+- Hosted dashboard
+- Witness counterexample generation
+- Spec-to-circuit comparison
+- Historical ZK bug benchmark suite
 
 ## Security Philosophy
 
-Nullsec S1-ZK treats ZK circuit bugs as proof semantics failures. It is designed to surface places where witness values, public claims, outputs, selectors, and integer domains are not bound by constraints in the way a protocol likely intends.
+Nullsec S1-ZK treats ZK circuit bugs as proof semantics failures. It prioritizes cases where witness values, public claims, outputs, selectors, integer domains, and EC intermediates are not bound by constraints in the way the protocol likely intends.
+
+The goal is not to replace human auditors. The goal is to give auditors sharper graph-aware evidence faster.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trynullsec/s1-zk",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Nullsec S1-ZK: AI-native auditing for zero-knowledge circuits.",
   "type": "module",
   "bin": {
@@ -17,12 +17,25 @@
   },
   "keywords": [
     "zk",
+    "zero-knowledge",
     "circom",
+    "halo2",
     "security",
     "static-analysis",
-    "auditing"
+    "circuits",
+    "audit",
+    "cryptography",
+    "proof-systems"
   ],
-  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/trynullsec/nullsec-s1-zk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/trynullsec/nullsec-s1-zk/issues"
+  },
+  "homepage": "https://github.com/trynullsec/nullsec-s1-zk#readme",
+  "license": "MIT",
   "dependencies": {
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
@@ -37,9 +50,11 @@
   "files": [
     "dist",
     "README.md",
+    "LICENSE",
     "RULES.md",
     "LIMITATIONS.md",
     "ROADMAP.md",
+    "assets",
     "examples",
     "benchmarks"
   ]