agent-recon 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to Agent Recon will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.1] - 2026-04-03
+
+### Changed
+
+- Server code bundled into single minified file for IP protection (esbuild)
+- npm tarball reduced from 84 to 44 files
+- Dynamic LLM provider loading replaced with static mapping for bundle compatibility
+
+### Fixed
+
+- npm publish step added to release workflow (was missing, caused E404 for users)
+- .npmignore gaps: excluded internal test procedures, hardware analysis, build tools, CLA
+
+## [1.0.0] - 2026-04-03
+
+### Added
+
+- Real-time event feed with WebSocket streaming from Claude Code hook scripts
+- Multi-environment support (Windows, macOS, Linux, WSL, VS Code, tmux)
+- Scrolling waveform timeline canvas with per-session swimlanes
+- Security classification engine (browser-side regex + server-side YARA-X rules)
+- LLM-powered security chain analysis with context-aware risk calibration
+- Token cost tracking with Usage API polling and per-session breakdowns
+- Per-session AI-generated insights and prompt quality coaching
+- Hallucination risk scoring (two-tier: direct evidence + circumstantial signals)
+- Environment recommendations based on 7-day rolling analysis
+- Session history narratives with LLM-generated title and detail summaries
+- Session labels with project-aware naming (<project>:<hex> format)
+- Multi-provider LLM abstraction (Anthropic fully implemented; OpenAI, Google stubs)
+- Per-pipeline provider and model configuration via settings
+- Cross-platform installer CLI (detect, install, upgrade, uninstall)
+- OS-native credential storage (DPAPI, Keychain, libsecret, PBKDF2 fallback)
+- AES-256-GCM encrypted settings for API keys at rest
+- AES-256 encrypted session archives
+- PII detection and automatic redaction before storage
+- Privacy-respecting telemetry with opt-out and self-service data deletion
+- OpenTelemetry export (OTLP/HTTP for logs, traces, metrics)
+- Browser-trusted TLS via mkcert (HTTP / mkcert / custom certificate modes)
+- Three-tier licensing (Community, Personal, Professional) via Lemonsqueezy
+- Feature gating with upgrade overlays for LLM-powered features
+- Landing page (agent-recon.net) and storefront integration
+- Azure telemetry backend with admin dashboard and compliance review workflow
+- In-app documentation modal with tabbed sections
+- Comprehensive developer documentation (API reference, architecture, database schema)
+- Cross-platform CI (Ubuntu, Windows, macOS Intel/ARM, Docker matrix)
+- Platform-aware setup scripts and service templates (launchd, systemd, NSSM)
+- Homebrew and Scoop package manager templates
+
+### Security
+
+- Server-side PII scanning with confidence-scored regex detection and redaction
+- YARA-X rule-based security classification of tool calls and events
+- Gitleaks-compatible secret detection configuration
+- IP allowlist restricting server connections to private network ranges (127.x, 10.x, 172.16-31.x, 192.168.x)
+- HMAC-SHA256 webhook signature verification for Lemonsqueezy events
+- Azure deployment with managed identity, Key Vault, VNet, and firewall hardening
+
+[1.0.1]: https://github.com/genxcoder1999/agent-recon/releases/tag/v1.0.1
+[1.0.0]: https://github.com/genxcoder1999/agent-recon/releases/tag/v1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing to Agent Recon™
+
+Thank you for your interest in contributing to Agent Recon™!
+
+## Contributor License Agreement (CLA)
+
+Before we can accept your contribution, you must sign our
+[Contributor License Agreement](CLA.md). When you open your first pull
+request, the CLA Assistant bot will prompt you to sign electronically.
+You only need to sign once.
+
+**Why a CLA?** Agent Recon™ uses an open-core model: core components are
+Apache 2.0, while some components are proprietary. The CLA ensures PNW Great
+Loop LLC can maintain both licenses. Your contributions to Apache 2.0 core
+remain Apache 2.0.
+
+## What Can I Contribute To?
+
+Contributions are welcome to **Apache 2.0-licensed core components** (see
+LICENSE for the full list). These include:
+
+- Event ingestion server and SQLite layer
+- Regex security engine
+- Dashboard UI (feed, waveform, stats, filters)
+- Token cost tracking
+- Build system and hook scripts
+- Setup scripts (all platforms)
+- Tests (all test suites)
+
+Contributions to proprietary components (LLM pipelines, telemetry, installer)
+are generally not accepted via open PRs. If you have ideas for those areas,
+please open an issue to discuss.
+
+## How to Contribute
+
+1. **Fork** the repository and create a feature branch from `main`
+2. **Make your changes** — follow the existing code style
+3. **Add tests** — every change must include tests (see CLAUDE.md > Testing Policy)
+4. **Run tests** before submitting:
+   ```bash
+   cd server
+   npm run test:unit && npm run test:fe
+   ```
+5. **Run the build** if you modified `src/` files:
+   ```bash
+   node build.js
+   ```
+6. **Open a pull request** against `main` with a clear description of the change
+
+## Code Style
+
+- No framework dependencies in the frontend (vanilla JS, single-file SPA)
+- Tests use `node:test` and `node:assert` (Node 22+ built-ins, no test framework)
+- LF line endings for `.py` and `.sh` files
+- See CLAUDE.md for the full developer guide
+
+## Reporting Issues
+
+Open a GitHub issue with:
+- Steps to reproduce
+- Expected vs. actual behavior
+- Platform info (OS, terminal, shell, Node.js version)
+
+## Code of Conduct
+
+Be respectful and constructive. We're building something useful together.
+
+---
+
+Questions? Email contribute@agent-recon.net

package/EULA.md

@@ -0,0 +1,223 @@
+# Agent Recon™ — End User License Agreement (EULA)
+
+**Effective Date:** March 2026
+**Licensor:** PNW Great Loop LLC
+**Product:** Agent Recon™
+
+---
+
+> Agent Recon™ is an independent product and is not affiliated with, endorsed
+> by, or sponsored by Anthropic PBC. Claude, Claude Code, and the Anthropic
+> name and logo are trademarks of Anthropic PBC. Agent Recon™ is a trademark
+> of PNW Great Loop LLC.
+
+---
+
+## 1. Agreement to Terms
+
+By installing, copying, or otherwise using Agent Recon™ ("Software"), you
+("User") agree to be bound by the terms of this End User License Agreement
+("EULA"). If you do not agree, do not install or use the Software.
+
+This EULA governs the entire Agent Recon™ distribution, which includes both
+open-source core components (licensed under Apache License 2.0 — see LICENSE)
+and proprietary components (licensed under a commercial license — see
+LICENSE-COMMERCIAL). The terms below apply to the Software as a whole, including
+the interaction between open-source and proprietary components.
+
+## 2. License Tiers
+
+Agent Recon™ is available under three license tiers:
+
+### 2.1 Community Tier (Free)
+
+- **Price:** Free forever
+- **Permitted use:** Individual developers for personal, non-commercial
+  development projects
+- **Features included:**
+  - Real-time event feed and WebSocket streaming
+  - Token cost tracking and Usage API integration
+  - Regex-based security classifications
+  - Dashboard UI (waveform timeline, statistics, filters, session management)
+  - Hook scripts for Claude Code event capture
+  - 7-day data retention
+- **Features not included (require paid license):**
+  - LLM-powered security chain analysis
+  - LLM-powered session insights and coaching
+  - LLM-powered hallucination scoring
+  - LLM-powered environment recommendations
+  - LLM-powered prompt quality analysis
+  - Session history narratives
+  - OTEL export
+  - Encrypted archives
+  - Multi-environment support
+  - Extended data retention (up to 90 days)
+- **Restrictions:** The Community tier may not be redistributed as part of a
+  commercial product or service.
+
+### 2.2 Personal Tier ($9.99/month or $84/year)
+
+- **Price:** $9.99 per month, or $84 per year (30% annual savings)
+- **Permitted use:** Individual developers purchasing with personal funds for
+  full-featured use
+- **Features:** All features, including all LLM-powered analysis, extended
+  retention, OTEL export, encrypted archives, and multi-environment support
+- **Purchase requirement:** Must be purchased with the User's own personal
+  funds. The Personal tier may NOT be purchased by, reimbursed by, or expensed
+  to an employer, client, or other business entity.
+- **License scope:** Single individual, any number of personal machines
+
+### 2.3 Professional Tier ($29/month or $279/year)
+
+- **Price:** $29 per month, or $279 per year (20% annual savings)
+- **Permitted use:** Developers whose use occurs in an employment, contractor,
+  or commercial context, OR whose license is purchased or reimbursed by a
+  business entity
+- **Features:** All features (identical to Personal tier), plus:
+  - Invoice billing
+  - Priority support
+- **Required when:**
+  - Use is in connection with employment or paid contracting
+  - Purchase is made by or reimbursed by an employer or client
+  - Use supports revenue-generating commercial activities
+- **License scope:** Single individual, any number of work machines
+
+## 3. LLM API Keys and Third-Party Services
+
+Agent Recon™ does not provide LLM API access. The User supplies their own API
+key(s) from any supported LLM provider (Anthropic, OpenAI, Google, or others).
+
+- The User is solely responsible for all costs associated with LLM API usage,
+  including costs incurred by both the AI coding agent being observed (e.g.,
+  Claude Code, Cursor) and Agent Recon™'s analysis pipelines.
+- The User is responsible for compliance with the terms of service of their
+  chosen LLM provider(s).
+- The Licensor is not responsible for the availability, pricing, terms, or
+  performance of any third-party LLM provider.
+
+## 4. License Key
+
+Access to Personal and Professional tier features requires a valid license key
+obtained through the authorized Agent Recon™ storefront.
+
+- License keys are non-transferable without written consent from the Licensor.
+- License keys are validated periodically via the Licensor's API and cached
+  locally for offline operation.
+- If the validation endpoint is unreachable, the most recently cached license
+  state is honored.
+- Tampering with, sharing, or circumventing license key validation is a
+  violation of this EULA.
+
+## 5. Telemetry
+
+Agent Recon™ includes an optional telemetry system that sends minimal,
+non-identifying data (install ID, software version, platform, and timestamp)
+to the Licensor's servers for product improvement and license compliance
+monitoring. See PRIVACY.md for full details.
+
+- Telemetry is **opt-out**: the User may disable telemetry at any time via
+  Settings > Telemetry or by setting `telemetry_enabled=false`.
+- The telemetry system must not be removed or disabled by any means other than
+  the provided opt-out mechanism.
+- No source code, prompts, API keys, file contents, or personally identifiable
+  information is collected by the telemetry system.
+
+## 6. Restrictions
+
+The User SHALL NOT:
+
+(a) Copy, redistribute, sublicense, sell, lease, or otherwise transfer the
+    Software or any portion thereof to any third party, except as expressly
+    permitted by the Apache License 2.0 for core components.
+
+(b) Reverse engineer, decompile, disassemble, or otherwise attempt to derive
+    the source code of the proprietary components, except to the extent
+    expressly permitted by applicable law.
+
+(c) Remove, alter, or obscure any proprietary notices, license headers, or
+    trademarks.
+
+(d) Use the Software to create a competing product or service that
+    substantially replicates the functionality of Agent Recon™.
+
+(e) Use the Software in any manner that violates applicable law or regulation.
+
+(f) Misrepresent the license tier under which the Software is used (e.g.,
+    using a Personal license in an employment context that requires
+    Professional).
+
+## 7. Intellectual Property
+
+The Software, including all proprietary components, modifications, and
+enhancements, is the exclusive property of PNW Great Loop LLC. Core components
+are licensed under Apache 2.0; proprietary components are licensed under
+LICENSE-COMMERCIAL. This EULA does not transfer ownership of any component.
+
+"Agent Recon" and the Agent Recon™ logo are trademarks of PNW Great Loop LLC.
+
+## 8. Disclaimer of Warranties
+
+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.
+
+THE LICENSOR DOES NOT WARRANT THAT THE SOFTWARE WILL BE UNINTERRUPTED,
+ERROR-FREE, OR SECURE. THE LICENSOR DOES NOT WARRANT THE ACCURACY,
+COMPLETENESS, OR RELIABILITY OF ANY LLM-GENERATED OUTPUT, INCLUDING
+SECURITY CLASSIFICATIONS, INSIGHTS, COACHING, HALLUCINATION SCORES,
+OR RECOMMENDATIONS. LLM-GENERATED OUTPUTS ARE PROVIDED FOR INFORMATIONAL
+PURPOSES ONLY AND SHOULD NOT BE RELIED UPON AS THE SOLE BASIS FOR SECURITY
+OR DEVELOPMENT DECISIONS.
+
+## 9. Limitation of Liability
+
+IN NO EVENT SHALL PNW GREAT LOOP LLC BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES ARISING OUT OF OR IN CONNECTION
+WITH THE USE OR INABILITY TO USE THE SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+THE LICENSOR'S TOTAL AGGREGATE LIABILITY SHALL NOT EXCEED THE AMOUNT PAID BY
+THE USER FOR THE SOFTWARE IN THE TWELVE (12) MONTHS PRECEDING THE CLAIM.
+
+FOR COMMUNITY TIER USERS, THE LICENSOR'S TOTAL LIABILITY SHALL NOT EXCEED
+TEN DOLLARS ($10.00 USD).
+
+## 10. Termination
+
+- The User may terminate this EULA at any time by uninstalling the Software
+  and destroying all copies.
+- The Licensor may terminate this EULA if the User breaches any term and fails
+  to cure the breach within thirty (30) days of written notice.
+- Upon termination of a paid subscription, the installation reverts to
+  Community tier functionality. No User data is deleted upon downgrade.
+- Sections 6, 7, 8, 9, and 11 survive termination.
+
+## 11. Governing Law
+
+This EULA shall be governed by and construed in accordance with the laws of
+the State of Washington, United States, without regard to its conflict of law
+provisions. Any dispute arising under this EULA shall be resolved in the state
+or federal courts located in Washington State.
+
+## 12. Changes to This EULA
+
+The Licensor may update this EULA from time to time. Material changes will be
+communicated through the Software's update mechanism or via the Licensor's
+website. Continued use of the Software after changes take effect constitutes
+acceptance of the revised EULA.
+
+## 13. Severability
+
+If any provision of this EULA is held to be unenforceable or invalid, that
+provision shall be modified to the minimum extent necessary to make it
+enforceable, and the remaining provisions shall continue in full force.
+
+## 14. Contact
+
+PNW Great Loop LLC
+Email: license@agent-recon.net
+Web: https://www.agent-recon.net
+
+---
+
+*Attorney review recommended before commercial distribution ($500-$1,500).*

package/INSTALL.md

@@ -0,0 +1,193 @@
+# Installing Agent Recon
+
+## Prerequisites
+
+- **Node.js >= 22** — [nodejs.org](https://nodejs.org/)
+- **Python 3** — Required for hook scripts ([python.org](https://www.python.org/))
+- **C/C++ build tools** — Required to compile the `better-sqlite3` native addon:
+  - **Windows:** `npm install -g windows-build-tools` or install Visual Studio Build Tools
+  - **macOS:** `xcode-select --install`
+  - **Linux (Debian/Ubuntu):** `sudo apt install build-essential python3`
+  - **Linux (Fedora/RHEL):** `sudo dnf groupinstall "Development Tools"`
+  - **Linux (Arch):** `sudo pacman -S base-devel`
+
+## npm (Recommended)
+
+```bash
+npm install -g agent-recon
+```
+
+Then run the guided installer:
+
+```bash
+agent-recon install
+```
+
+The installer will:
+1. Detect your platform and existing configuration
+2. Copy hook scripts to your Claude Code hooks directory
+3. Register 13 lifecycle events in Claude Code settings
+4. Optionally configure LLM API keys for analysis features
+5. Optionally set up an auto-start service (systemd / launchd / Windows Service)
+6. Verify the server starts and responds
+
+## From Source
+
+```bash
+git clone <repository-url>
+cd agent-recon
+
+# Install server dependencies
+cd server && npm install && cd ..
+
+# Install installer dependencies
+cd installer && npm install && cd ..
+
+# Run the guided installer
+node installer/cli.js install
+
+# Or start the server manually
+node server/start.js
+```
+
+## Upgrading
+
+```bash
+# If installed via npm
+npm update -g agent-recon
+agent-recon upgrade
+
+# If installed from source
+git pull
+agent-recon upgrade
+# or: node installer/cli.js upgrade
+```
+
+## Uninstalling
+
+```bash
+agent-recon uninstall
+```
+
+This removes hooks from Claude Code settings, stops any auto-start service, and optionally
+deletes the database and stored credentials. The source directory is never deleted.
+
+To also remove the npm package:
+
+```bash
+npm uninstall -g agent-recon
+```
+
+## CLI Commands
+
+```
+agent-recon install      # Guided installation (default)
+agent-recon upgrade      # Upgrade existing installation
+agent-recon uninstall    # Remove Agent Recon
+agent-recon detect       # Print environment detection report
+agent-recon --help       # Show help
+agent-recon --version    # Show version
+```
+
+## Platform Package Managers
+
+### Homebrew (macOS / Linux) — Coming Soon
+
+A Homebrew formula is planned for a future release. In the meantime, use npm.
+
+### Scoop (Windows) — Coming Soon
+
+A Scoop manifest is planned for a future release. In the meantime, use npm.
+
+## TLS / HTTPS Setup
+
+Agent Recon supports browser-trusted HTTPS via [mkcert](https://github.com/FiloSottile/mkcert), eliminating "Not Secure" browser warnings without self-signed certificate interstitials.
+
+### Prerequisites
+
+Install mkcert for your platform:
+
+| Platform | Command |
+|----------|---------|
+| macOS | `brew install mkcert` |
+| Windows | `choco install mkcert` |
+| Linux / WSL | `apt install mkcert` or `brew install mkcert` |
+
+Then run the one-time CA installation (requires admin/sudo):
+
+```bash
+mkcert -install
+```
+
+### Enable TLS during install
+
+```bash
+npx agent-recon install --tls
+```
+
+This pre-selects the mkcert option in the guided installer. You can also choose TLS interactively during a normal `npx agent-recon install`.
+
+### Enable TLS on an existing installation
+
+```bash
+npx agent-recon tls setup     # configure mkcert TLS via server API
+npx agent-recon tls status    # check current TLS status
+npx agent-recon upgrade --tls # add TLS during upgrade
+```
+
+After enabling TLS, restart the server. The dashboard will be available at `https://localhost:3132` with a green padlock.
+
+### WSL note
+
+On WSL2, mkcert installs the CA into the Windows trust store via interop. Both Windows browsers and WSL-side `curl` will trust the certificate. Ensure `mkcert -install` is run from WSL (it automatically uses the Windows `certutil` via `/mnt/c/`).
+
+### Custom certificates
+
+For CA-signed or enterprise certificates, choose "Custom certificate" during install or set the paths in Settings. Provide PEM-encoded cert and key file paths.
+
+## Verifying Installation
+
+```bash
+# Check environment detection
+agent-recon detect
+
+# Check server health (server must be running)
+curl http://localhost:3131/health
+```
+
+## Troubleshooting
+
+### `better-sqlite3` build failure
+
+This native addon must compile C++ code during installation. If it fails:
+
+1. Ensure C/C++ build tools are installed (see Prerequisites above)
+2. Try rebuilding manually: `cd server && npm rebuild better-sqlite3`
+3. On WSL, ensure you are on a native ext4 filesystem, not an NTFS mount (`/mnt/c/...`)
+
+### Python not found
+
+Hook scripts require Python 3. The installer checks for `python3` and `python` in your PATH.
+
+- **Windows:** Install from [python.org](https://www.python.org/) and ensure "Add to PATH" is checked
+- **macOS:** `brew install python` or use the system Python 3
+- **Linux:** `sudo apt install python3` (Debian/Ubuntu) or `sudo dnf install python3` (Fedora)
+
+### Permission errors on global install
+
+If `npm install -g` fails with permission errors:
+
+- **Recommended:** Configure npm to use a user directory:
+  ```bash
+  mkdir -p ~/.npm-global
+  npm config set prefix '~/.npm-global'
+  # Add to ~/.bashrc or ~/.zshrc:
+  export PATH="$HOME/.npm-global/bin:$PATH"
+  ```
+- **Not recommended:** `sudo npm install -g agent-recon` (avoid running npm as root)
+
+### Server won't start
+
+1. Check that port 3131 is available: `lsof -i :3131` (macOS/Linux) or `netstat -ano | findstr 3131` (Windows)
+2. Ensure the database directory is writable: `ls -la data/`
+3. Check logs: set `AGENT_RECON_DEBUG=1` before starting