Metadata-Version: 2.4
Name: darkelf-cocoa
Version: 4.2.2
Summary: Darkelf Cocoa privacy browser for macOS
Author: Dr. Kevin Moore
License: LGPL-3.0-or-later
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pyobjc
Requires-Dist: tldextract

# 🧿 Darkelf Cocoa Browser v4.2.2

### Ephemeral, Privacy-Focused Web Browser (macOS / Cocoa Build)

**Author:** Dr. Kevin Moore (2025)
**License:** LGPL-3.0-or-later

---

## Post-Quantum Integrity Layer (PQ)

Darkelf implements a **post-quantum–aware integrity and behavioral verification system** using **SHA3-512 / SHA3-256** primitives.
This layer provides **tamper-evident, session-bound consistency signals** *without modifying network traffic* and is fully **deterministic per session/tab context**.

---

### ✅ What PQ is (in Darkelf)

* **Deterministic request fingerprinting** bound to:

  * canonicalized URL (normalized path + sorted query)
  * filtered headers
  * **per-tab session seed (`_pq_seed`)**
  * **hidden salt (`_pq_salt`) for secrecy**
  * optional TLS certificate summary
  * time bucket (~10s, anti-replay)

* Uses:

  * **SHA3-512** → high-entropy identity + integrity binding
  * **SHA3-256** → lightweight deterministic decision logic

* Designed to be:

  * stable within a session
  * non-replayable across time buckets
  * non-correlatable across tabs

---

### 🔁 PQ Chaining

* **Per-tab seeded chain progression**

  * `_pq_seed` → root identity
  * `_pq_counter` → monotonic progression
  * `_pq_prev_chain` → forward-linked state

* Properties:

  * deterministic evolution (no randomness)
  * no fallback behavior (prevents weak entropy states)
  * forward-linked continuity

* Purpose:

  * detect replay patterns
  * detect navigation inconsistencies
  * enforce session continuity

---

### 🎨 Canvas PQ Integration

* Canvas entropy is derived from `_pq_seed`

* Behavior:

  * deterministic per tab
  * stable within session
  * isolated across tabs

* Effect:

  * reduces cross-tab correlation
  * avoids global fingerprint reuse

---

### 🕵️ Deterministic Deception (Third-Party)

* Applies only in **third-party contexts**

* Activated only when PQ identity is present

* **Fully deterministic (no randomness)**

* Modes:

  * slight mutation
  * truncated identity
  * namespace shift

* Purpose:

  * reduce tracker confidence
  * degrade correlation accuracy
  * avoid detectable noise patterns

---

### 🧠 PQ Behavioral Intelligence

* Tracks:

  * `_pq_window` (recent activity)
  * `_pq_seen` (uniqueness)

* Detects:

  * excessive uniqueness → suspicious session behavior
  * high short-window entropy → automation / replay patterns

* Contributes to:

  * `suspicious_hits`
  * overall threat score
  * PQ-specific risk signal

---

### 🔐 TLS Trust Awareness (TOFU-Style)

* Tracks server certificate summaries per host

* Detects trust changes within a session

* Effect:

  * continuity break indicates possible interception
  * feeds UI trust indicators

---

### 🧩 Canonicalization

* Inputs normalized before hashing:

  * path normalization (`// → /`)
  * sorted query parameters
  * filtered headers

* Purpose:

  * eliminate attacker-controlled entropy
  * ensure stable identity across equivalent requests

---

### 🔁 Replay Detection

* Sliding window of recent chain values
* Detects:

  * repeated chains (replay)
  * duplicated navigation flows

---

### ⚙️ Adaptive Behavior

PQ influences handling:

| Risk   | Behavior                    |
| ------ | --------------------------- |
| low    | allow                       |
| medium | degrade identity signals    |
| high   | isolate (strip PQ identity) |

---

### 🔄 Identity Rotation

* Long sessions trigger deterministic rotation:

  * `_pq_seed → SHA3-256(_pq_seed)`

* Purpose:

  * limit long-term correlation
  * preserve short-term continuity

---

### 👁 Observable Effects

PQ operates internally, but effects may be visible:

* fingerprint tests may vary across tabs
* tracking sessions may reset or fail
* tabs behave as isolated identities
* high-risk activity may trigger degraded behavior
* TLS changes may surface warnings

---

### 🧠 PQ Summary Model

PQ combines:

* Integrity (request binding)
* Continuity (chain progression)
* Replay detection
* Anti-correlation (deterministic deception)
* Behavioral analysis
* Adaptive handling
* Rendering isolation (canvas)
* TLS trust awareness

---

## MiniAI Sentinel (On-Device IDS)

### Detects

* trackers & third-party correlation
* fingerprinting patterns
* scraping / automation behavior
* credential stuffing bursts
* scanner-like activity
* suspicious URL patterns

### Lockdown Mode

Triggered on critical thresholds:

* stops loading across tabs
* opens `darkelf://report`
* disables navigation temporarily
* auto-recovers after timeout

> Runs fully local. No telemetry.
