{"_id":"@aaravmaloo/revera","_rev":"2-47d70f17c9b4d3f22f84468f1b4d37a5","name":"@aaravmaloo/revera","dist-tags":{"latest":"1.0.0"},"versions":{"0.1.0":{"name":"@aaravmaloo/revera","version":"0.1.0","keywords":["npm","package","reputation","security","audit","supply-chain","cli","trust","typosquatting","dependency"],"author":{"name":"Aarav Maloo"},"license":"MIT","_id":"@aaravmaloo/revera@0.1.0","maintainers":[{"name":"aaravmaloo","email":"aaravmaloo06@gmail.com"}],"homepage":"https://github.com/aaravmaloo/revera#readme","bugs":{"url":"https://github.com/aaravmaloo/revera/issues"},"bin":{"revera":"dist/cli.js"},"dist":{"shasum":"33e13daa09602bf4f69bfeee8c7634532e9f4c2a","tarball":"https://registry.npmjs.org/@aaravmaloo/revera/-/revera-0.1.0.tgz","fileCount":53,"integrity":"sha512-iFHlLWZHdcUUgiFkn6IPnNz0MRNhDTcR+pHM5oA372w7NZVhkKPwZOvEeqPJpliPCct7R7a0s0WWegYluFNdqA==","signatures":[{"sig":"MEUCIQCtn8gFzknMN+JNy7e1ol/+/9olBLA40WMz5PmzAWLU0QIgSw30F1I7uqEUxr9OryzY70y8Zjp9ThAH07LQJfi1vUQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":146862},"main":"./dist/cli.js","type":"module","types":"./dist/cli.d.ts","engines":{"node":">=20"},"gitHead":"9bae921dec336d9856b361230ae163b3ee766920","scripts":{"dev":"tsc -w","lint":"eslint src/**","test":"vitest run","build":"tsc","start":"node dist/cli.js","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"aaravmaloo","email":"aaravmaloo06@gmail.com"},"repository":{"url":"git+https://github.com/aaravmaloo/revera.git","type":"git"},"_npmVersion":"11.9.0","description":"The credit score for npm packages. Analyze package reputation, maintenance, security, publisher trust, and ecosystem health before you install any package.","directories":{},"_nodeVersion":"24.14.0","dependencies":{"ora":"^8.2.0","zod":"^3.24.1","axios":"^1.7.9","chalk":"^5.4.1","execa":"^9.5.2","listr2":"^8.2.5","semver":"^7.8.5","fuse.js":"^7.1.0","commander":"^13.1.0"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9.16.0","vitest":"^2.1.8","prettier":"^3.4.2","typescript":"^5.7.2","@types/node":"^20","@types/semver":"^7.7.1"},"_npmOperationalInternal":{"tmp":"tmp/revera_0.1.0_1783266469343_0.5163108869314745","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@aaravmaloo/revera","version":"1.0.0","description":"The credit score for npm packages. Analyze package reputation, maintenance, security, publisher trust, and ecosystem health before you install any package.","type":"module","main":"./dist/cli.js","bin":{"revera":"dist/cli.js"},"engines":{"node":">=22.0.0"},"keywords":["npm","package","reputation","security","audit","supply-chain","cli","trust","typosquatting","dependency"],"author":{"name":"Aarav Maloo"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/aaravmaloo/revera.git"},"homepage":"https://github.com/aaravmaloo/revera#readme","bugs":{"url":"https://github.com/aaravmaloo/revera/issues"},"scripts":{"build":"tsc","start":"node dist/cli.js","dev":"tsc -w","test":"vitest run","lint":"eslint src/**","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"","prepublishOnly":"npm run build && npm test"},"dependencies":{"axios":"^1.7.9","chalk":"^5.4.1","commander":"^13.1.0","execa":"^9.5.2","fuse.js":"^7.1.0","listr2":"^8.2.5","ora":"^8.2.0","semver":"^7.8.5","zod":"^3.24.1"},"devDependencies":{"@types/node":"^20","@types/semver":"^7.7.1","eslint":"^9.16.0","prettier":"^3.4.2","typescript":"^5.7.2","vitest":"^2.1.8"},"gitHead":"1702125673d735738631441ec20a2babfdf0ef4d","types":"./dist/cli.d.ts","_id":"@aaravmaloo/revera@1.0.0","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-iRiMXLvz+Hb4iD/cZ5dbmDTUNjrgzyj7GeO4luIdv1v85hpXyrHWaY7iW0pxN2YZJjsHvVUHQ8djabayUelg8w==","shasum":"e1eb4ac75dacded4e03bbb7148d644aed8c8bdc3","tarball":"https://registry.npmjs.org/@aaravmaloo/revera/-/revera-1.0.0.tgz","fileCount":59,"unpackedSize":182958,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD2bGYnJV41RrUwM1lS1lQVb9WCTQtbRvJJd/KD8QMLLAIhANWJCeFHwT5v8NIq2JhF804r6z6UjAEnZyY+vIHbOBS0"}]},"_npmUser":{"name":"aaravmaloo","email":"aaravmaloo06@gmail.com"},"directories":{},"maintainers":[{"name":"aaravmaloo","email":"aaravmaloo06@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/revera_1.0.0_1784362880676_0.30041331773398294"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-05T15:47:49.168Z","modified":"2026-07-18T08:21:20.982Z","0.1.0":"2026-07-05T15:47:49.489Z","1.0.0":"2026-07-18T08:21:20.827Z"},"bugs":{"url":"https://github.com/aaravmaloo/revera/issues"},"author":{"name":"Aarav Maloo"},"license":"MIT","homepage":"https://github.com/aaravmaloo/revera#readme","keywords":["npm","package","reputation","security","audit","supply-chain","cli","trust","typosquatting","dependency"],"repository":{"type":"git","url":"git+https://github.com/aaravmaloo/revera.git"},"description":"The credit score for npm packages. Analyze package reputation, maintenance, security, publisher trust, and ecosystem health before you install any package.","maintainers":[{"name":"aaravmaloo","email":"aaravmaloo06@gmail.com"}],"readme":"# Revera\n\n[![npm version](https://img.shields.io/npm/v/@aaravmaloo/revera.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/revera)\n[![build status](https://img.shields.io/github/actions/workflow/status/aaravmaloo/revera/ci.yml?branch=main&style=flat-square)](https://github.com/aaravmaloo/revera/actions)\n[![node version](https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square)](https://nodejs.org/)\n[![typescript](https://img.shields.io/badge/TypeScript-5.5-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)\n[![license](https://img.shields.io/npm/l/@aaravmaloo/revera.svg?style=flat-square&color=yellow)](LICENSE)\n[![coverage](https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square)](https://github.com/aaravmaloo/revera)\n\n> The credit score for npm packages.\n\nRevera helps you decide whether a package is worth installing before you run `npm install`. It analyzes package quality, maintenance, security, ecosystem health, and publisher trust — and now propagates risk transitively across your entire dependency graph — then produces an explainable, Bayesian reputation report.\n\n---\n\n## Demo\n\n![revera CLI Demo](assets/demo.gif)\n*Watch revera check and explain packages in real time.*\n\n---\n\n## Quick Start\n\nRun revera instantly without installation:\n\n```bash\nnpx revera check react\n```\n\n---\n\n## Example\n\nChecking a package like `request` (which was deprecated in 2020) immediately warns you with specific reasons:\n\n```bash\n$ revera why request\n```\n\n```text\n  ▲ revera EXPLAIN\n  ──────────────────────────────────────────────────\n  Package:   request@2.88.2\n  Overall:   38/100  Not Recommended\n\n  Score Breakdown\n\n    Maintenance             15/100  ███░░░░░░░░░░░░░░░░░\n                           Release cadence, commit activity, issue responsiveness, maintainer count\n\n    Stability               90/100  ██████████████████░░\n                           SemVer compliance, major version history, API volatility over time\n\n    Security               100/100  ████████████████████\n                           Known CVEs, install scripts, repository transparency\n\n    Package Quality         40/100  ████████░░░░░░░░░░░░\n                           README completeness, license, test coverage indicators, exports\n\n    Ecosystem              100/100  ████████████████████\n                           Weekly download volume, GitHub stars, community forks\n\n    Documentation           90/100  ██████████████████░░\n                           README length, code examples, API references, external docs presence\n\n    Developer Experience    40/100  ████████░░░░░░░░░░░░\n                           TypeScript support, ESM compatibility, CLI tooling\n\n    Publisher Trust        100/100  ████████████████████\n                           Known malicious releases, protestware history, supply-chain incidents\n\n  Why it scores well\n    +  Stable API (v1.0.0+)\n    +  Low API volatility\n    +  Zero known vulnerabilities\n    +  Permissive open-source license\n    +  Code examples in README\n    +  Structured API documentation\n    +  No known publisher trust incidents\n\n  Minor deductions\n    -  Last release was 59 months ago\n    -  Single maintainer (bus factor of 1)\n    -  Missing native type definitions\n    -  Legacy CommonJS only\n    -  No native typings (bad TypeScript DX)\n\n  Warnings\n    !  Last release: 59 months ago. No recent updates detected. This may be normal for mature, stable libraries.\n    !  Package has been officially marked as deprecated by the maintainer.\n\n  Verdict\n    Request has low confidence. revera recommends looking for alternatives due to security, activity, or stability concerns.\n```\n\n---\n\n## Installation\n\nInstall globally to access the executable from any directory:\n\n```bash\nnpm install -g @aaravmaloo/revera\n```\n\n---\n\n## Usage\n\n### 1. Check Package Reputation\nAnalyze a package and get a high-level summary report:\n```bash\nrevera check lodash\n```\n\nRun in offline mode using cached files:\n```bash\nrevera check express --offline\n```\n\n### 2. Explain Package Rating\nGet a deep-dive breakdown of the score, positive signals, and deductions:\n```bash\nrevera why node-ipc\n```\n\n### 3. Screen and Add Dependency\nScreens packages before installation and warns when reputation falls below your configured threshold:\n```bash\nrevera add express\n```\nYou can pass flags directly to your package manager:\n```bash\nrevera add typescript --save-dev\n```\n\n### 4. Audit Local Workspace\nAudit all packages in the current project (includes transitive dependencies) and calculate an overall project health score:\n```bash\nrevera audit\n```\n\nAudit production dependencies only:\n```bash\nrevera audit --prod\n```\n\nAudit direct dependencies only, skipping transitive dependencies:\n```bash\nrevera audit --direct\n```\n\n### 5. GitHub Authentication\nAuthenticate with GitHub to increase API rate limits (60/hour anonymous vs 5,000/hour authenticated). You can choose between browser-based OAuth2 or manually entering a Personal Access Token. Once authorized, revera securely encrypts and stores the token in your OS keyring (Windows DPAPI, macOS Keychain, or Linux Secret Service):\n```bash\nrevera login\n```\n\n### 6. CLI Settings\nManage local settings saved in `~/.revera/config.json`:\n```bash\nrevera config\nrevera config set minScoreThreshold 75\nrevera config get minScoreThreshold\n```\n\n### 7. System Doctor\nVerify environment settings, API status, and network connection latencies:\n```bash\nrevera doctor\n```\n\n### 8. Cache Control\nInspect or clear local metadata cache:\n```bash\nrevera cache\nrevera cache clear\n```\n\n### 9. Update Check\nVerify if you are running the latest version of the revera engine:\n```bash\nrevera update\n```\n\n---\n\n## Comparison\n\n| Feature | `npm audit` | `osv-scanner` | Socket | **revera** |\n| :--- | :---: | :---: | :---: | :---: |\n| **CVE Vulnerabilities** | ✔ | ✔ | ✔ | ✔ |\n| **Multiple Vuln DBs** | ✖ | Partial | ✔ | ✔ |\n| **Ecosystem Reputation** | ✖ | ✖ | Partial | ✔ |\n| **Explainable Scoring** | ✖ | ✖ | Partial | ✔ |\n| **Publisher Trust Check** | ✖ | ✖ | Partial | ✔ |\n| **Typosquat Detection** | ✖ | ✖ | Partial | ✔ |\n| **Transitive Risk Propagation** | ✖ | ✖ | ✖ | ✔ |\n| **Bayesian Confidence Intervals** | ✖ | ✖ | ✖ | ✔ |\n\n---\n\n## Scoring Engine (v2)\n\nRevera v2 replaced the legacy flat weighted-sum model with a four-stage Bayesian DAG pipeline.\n\n### Stage 1 — Dependency Graph (DAG)\n\nAll dependencies in the project are resolved into a directed acyclic graph. Each node tracks its full transitive dependent set so that later stages can compute accurate blast radii.\n\n```\nlodash ──► your-app\nexpress ──► your-app\naxios ──► some-lib ──► your-app   ← transitive\n```\n\n### Stage 2 — Per-Package Scoring (Bayesian Beta Posteriors)\n\nEach of the 8 scoring categories starts from an **archetype-specific prior** (`framework`, `cli`, `types-only`, `utility`) rather than a flat uninformed baseline. Observed signals update a Beta distribution posterior — meaning a timeout or missing data widens the credible interval rather than silently defaulting to \"clean\".\n\n| Category | Weight | Focus Areas |\n| :--- | :---: | :--- |\n| **Security** | 20% | Active CVEs (3 DBs), install scripts, repository transparency |\n| **Publisher Trust** | 15% | Protestware history, deliberate sabotage, account hijack incidents |\n| **Maintenance** | 13% | Publish cadence, recent commits, open issues response ratio |\n| **Stability** | 12% | SemVer compliance, major version frequency, pre-1.0 maturity |\n| **Package Quality** | 13% | Source file sizes, license, exports configuration |\n| **Ecosystem** | 13% | Weekly downloads (log-scaled), GitHub stars, contributor count |\n| **Documentation** | 9% | README completeness, code examples, API reference coverage |\n| **Developer Experience** | 5% | Native TS typings, ESM exports, tree-shaking support |\n\nThe final per-package score is a **confidence-weighted aggregate** of category posteriors (inverse-variance weighting), producing both a point estimate and a 95% credible interval.\n\n### Stage 3 — Veto Checks\n\nThree hard overrides bypass the Bayesian scoring entirely and immediately fail a package:\n\n| Veto | Trigger |\n| :--- | :--- |\n| **Critical Trust Incident** | Publisher has a confirmed supply-chain attack or protestware release |\n| **Typosquat** | Edit distance ≤ 1 from a top-N package (e.g. `lodahs`, `expres`) |\n| **Unpatched Critical CVE** | A `CRITICAL` severity vulnerability with no patched version available |\n\n### Stage 4 — Transitive Risk Propagation\n\nAfter per-package scores are computed, risk is propagated bottom-up through the DAG (topological order, leaves first):\n\n- If a dependency's `effectiveRisk` exceeds a threshold, its parent's risk is **floored at 0.8** (flagged as tainted).\n- The **blast radius** of each node = `effectiveRisk × transitive_dependent_count`.\n- The **worst subpath** is traced and surfaced in the audit output so you know exactly which chain of dependencies caused a flag.\n\n### Stage 5 — Report Synthesis\n\nThe final audit report merges intrinsic scores, inherited taint, credible intervals, and blast radii into a single ranked output. The overall workspace score is a weighted average by blast radius.\n\n---\n\n## Vulnerability Databases\n\nRevera queries **three independent vulnerability databases in parallel** on every check. Results are merged and deduplicated by CVE/GHSA alias before being used in scoring.\n\n| Database | Source | Auth Required | Notes |\n| :--- | :--- | :---: | :--- |\n| **OSV** (osv.dev) | Google Open Source Security | ✖ | Aggregates NVD, GitHub Advisory, RUSTSEC, and more |\n| **GitHub Advisory DB** | GitHub Security | ✖ | Rich CVSS scores + patched-version ranges |\n| **npm Advisory** | registry.npmjs.org | ✖ | Same data as `npm audit`; sometimes publishes before OSV |\n\nIf a source times out or errors, the others continue independently. The `VulnResult` exposes which sources responded (`sources`) and which failed (`failedSources`) so the Bayesian scorer can widen the uncertainty interval appropriately rather than assuming clean.\n\n---\n\n## Architecture & Structure\n\n```\n.github/              # CI configurations\ndocs/                 # Architecture specs and algorithm diagrams\nsrc/\n  ├── commands/       # CLI command handlers (check, why, add, audit, config, cache, update)\n  ├── engine/\n  │   ├── dag.ts          # DAG construction + topological sort + blast-radius computation\n  │   ├── propagation.ts  # Bottom-up transitive risk propagation\n  │   ├── scoring.ts      # Bayesian Beta posteriors, archetype priors, veto checks\n  │   ├── vuln.ts         # Multi-source vuln aggregator (OSV + GitHub + npm)\n  │   ├── trust.ts        # Publisher trust incident database\n  │   ├── typosquat.ts    # Edit-distance typosquat detection\n  │   ├── npm.ts          # npm registry + download stats fetcher\n  │   └── github.ts       # GitHub repo stats + README fetcher\n  ├── ui/             # Console view templates (reporter formatters, theme styles)\n  └── utils/          # Filesystem helpers (caching, configuration, package managers)\ntests/                # Unit test suites\nbenchmarker/          # Large-scale benchmark suite (100k+ packages)\n```\n\n---\n\n## Benchmarks\n\nRevera ships with a built-in large-scale benchmark suite in `benchmarker/` that tests against **100k+ npm packages** in parallel and produces a single, GitHub-readable report.\n\n### Running a benchmark\n\n```bash\ncd benchmarker\nnpm install\nnpm run fetch-dataset          # one-time: pulls ~100k packages into datasets/npm.jsonl\n./benchmark.sh --workers 16   # runs the full suite\n```\n\nEach run produces a self-contained output directory with:\n\n| File | Description |\n| :--- | :--- |\n| `BENCHMARK.md` | Single GitHub-readable report (accuracy, per-label detection, score distribution, latency) |\n| `report.html` | Interactive browser report with charts |\n| `summary.json` | Machine-readable aggregated stats |\n| `results.jsonl` | Per-package results for all tested packages |\n| `comparison.json` | Delta vs the previous run (regressions + improvements) |\n\n### Latest benchmark (v2 algorithm, seed dataset)\n\n| Label | Packages | Accuracy |\n| :--- | ---: | :--- |\n| `trusted` | 7,051 | 96.6% |\n| `malicious` | 9 | 22.2% _(v1 baseline — v2 veto checks fix this)_ |\n| `typosquat` | 20 | 35.0% _(v1 baseline — v2 edit-distance veto fixes this)_ |\n| **Overall (labeled)** | **7,085** | **96.5%** |\n\n> The v1 benchmark was run before the v2 veto checks were deployed. The per-label malicious/typosquat numbers reflect the legacy algorithm. A full v2 re-run will be published in the next release.\n\n---\n\n## Roadmap\n\n- [x] Package reputation scoring\n- [x] Explainable scoring reports\n- [x] Direct and transitive project auditing\n- [x] Publisher trust incident checks\n- [x] Typosquat Levenshtein warnings\n- [x] **Bayesian Beta posterior scoring (v2)**\n- [x] **Transitive DAG risk propagation (v2)**\n- [x] **Multi-source vulnerability aggregation (OSV + GitHub + npm)**\n- [x] **GitHub-readable benchmark reports (`BENCHMARK.md`)**\n- [ ] Multi-package comparison commands\n- [ ] Official GitHub Action for CI checks\n- [ ] Official VS Code extension\n- [ ] Native pnpm support\n- [ ] Native Yarn support\n\n---\n\n## FAQ\n\n#### How do I avoid GitHub API rate limits?\nWithout a token, anonymous queries are rate-limited to 60 requests per hour. You can set a Personal Access Token in your configuration:\n```bash\nrevera config set githubToken ghp_YOUR_TOKEN\n```\n\n#### What happens if I am offline?\nRevera falls back to using cache files. You can explicitly run commands in offline mode with the `--offline` flag. If a vulnerability source is unavailable, the Bayesian scorer widens the credible interval for that package rather than assuming clean.\n\n#### Does the add command modify my project?\nRevera acts as a shell wrapper. It runs the real package installer after screening.\n\n#### What is a \"tainted\" package in the audit output?\nA package is marked tainted when one of its transitive dependencies triggered a veto or scored critically low. The audit output shows the worst subpath so you can trace the exact chain of dependencies that caused the flag.\n\n#### How are vulnerabilities deduplicated across three databases?\nEach vulnerability is identified by its CVE ID, GHSA ID, or npm advisory ID. When the same vulnerability appears in multiple sources, it is merged into one canonical entry. OSV data takes priority for prose fields (summary, details); the highest severity rating and most complete patched-version range across all sources are preserved.\n\n---\n\n## Contributing\n\nPlease review the [Contributing Guide](CONTRIBUTING.md) to get started with setup, style rules, and PR guidelines.\n\n---\n\n## Disclaimer\n\nRevera provides a reputation score based on observable project signals and historical data. It is intended to assist engineering decisions and should not be treated as a definitive security audit.\n\n---\n\n## License\n\nRevera is distributed under the [MIT License](LICENSE).\n","readmeFilename":"README.md"}