🔍 RootIB Provenance Scanner

🔐 GitHub Authentication

Authenticate with GitHub via Device Flow to unlock authenticated API calls (60 → 5,000 req/hr), private repo scanning, and code search. Requires the Railway backend with ROOTIBAPP_CLIENT_ID / ROOTIBAPP_CLIENT_SECRET set in Railway Variables.

⚡ Live Lookup

Enter a GitHub username or owner/repo to scan for RootIB provenance markers. Results are powered by the GitHub API and Groq AI analysis — no local backend required.

⚙️ Backend URL

API calls are routed to githubBackend.html which acts as a virtual backend via a Service Worker (persists in the browser, no server required). If localhost:8000 is running it is used automatically instead. Override the URL below if you are running a real backend elsewhere.
💡 Tip: set window.__BACKEND_API_BASE__ = "https://your-backend.example.com" in the browser console to override globally at runtime.

🔎 Pending Match Queue

Matches identified by the backend scanner that await human approval before being written to the ledger. Powered by the Railway-hosted Scanner API. Each match can be Approved, Rejected, or Skipped.

🌐 Global Scan Status

Live counters from the autonomous backend worker. Powered by the Railway-hosted Scanner API. Override the URL in the ⚙️ Backend / Railway URL card above to point to a local instance if needed.

📅 Origin Timeline

Enter a RootIB origin ID to see its full timeline of external matches.

ℹ️ How it works

1. The GitHub REST API fetches all public repos for the target user via paginated requests (per_page=100), with no artificial cap — all repos are scanned.
2. A regex scanner searches each file for explicit RootIB: <ID> patterns — these are counted as exact matches.
3. A concept matcher runs token n-gram Jaccard similarity (structural) and bag-of-words cosine similarity (semantic) comparisons against every origin description in the local ledger.
4. Found IDs and concept matches are cross-referenced against the local RootIB ledger (rootib-ledger.json) — confirmed ledger entries are highlighted in purple.
5. Groq AI (llama-3.3-70b-versatile) provides an intelligent provenance assessment of the findings.
6. The Groq API key is pre-embedded via the RootIB Scanner Setup GitHub Actions workflow using the GROK repo secret.

To enable AI analysis: add your Groq API key as GROK in Settings → Secrets → Actions, then run the RootIB Scanner Setup workflow. Free keys at console.groq.com/keys.

🔌 APIs Used

🏗️ Full Pipeline Overview

The RootIB Global Provenance System is a multi-stage pipeline that ingests GitHub repositories, canonicalizes their contents, finds matches against the RootIB origin ledger, routes findings through a human approval gate, and then automatically updates the ledger and recalculates valuations.

1. Repository Ingestion — POST /scan — Discovers all public repos for a GitHub user or org and fetches the full file tree + raw content via the GitHub API. Commit timestamps (first and last) are stored per file.
2. Canonicalization — POST /canonicalize — Each file is normalized (whitespace, comments stripped), hashed with SHA-256, and split into function/class-level artifacts. Language-aware extractors handle Python, JavaScript, TypeScript, and more.
3. Matching Engine — POST /match — Compares every artifact against every RootIB origin using three match types: exact (hash), structural (token n-gram Jaccard), and semantic (bag-of-words cosine). All matches are written to pending_provenance_links with status = pending.
4. Evidence Bundle — Every pending match carries an evidence bundle — a JSON object containing the file path, GitHub URL, match type, similarity score, origin description snippet, and structural diff — giving the human reviewer all context needed to make a decision.
5. Human Review Gate — GET /review/pending + POST /review/pending/{id} — A reviewer sees each pending match and chooses Approve, Reject, or Skip. No ledger entry is ever created without explicit human approval.
6. Ledger Update Automation — On approval the system: (a) moves the row from pending_provenance_links → provenance_links; (b) rebuilds the RootIB ledger JSON entry for that origin; (c) commits the updated js/rootib-ledger.json to GitHub via the Contents API; (d) fires a repository_dispatch event to trigger a Pages site rebuild. Ledger entries are immutable once confirmed.
7. Auto-Valuation Engine — POST /valuation/recalculate — Runs automatically after every approved merge. Computes nine weighted factors (originality, reuse count, temporal precedence, cross-repo propagation, developer contribution weight, chain position, and more) and stores a current_value ∈ [0, 100] per origin in rootib_values.

📋 Evidence Bundle

Each pending provenance match includes a structured evidence bundle so reviewers can make informed decisions without looking at the raw code.

📈 Auto-Valuation Engine

After every approved ledger merge the engine recalculates a current_value score (0–100) for every RootIB origin using nine weighted factors:

Results are stored in rootib_values and are queryable via GET /valuation/{origin_id}. Valuation is triggered automatically on every approved provenance link; it can also be triggered manually via POST /valuation/recalculate.

Engine Results