Compare commits
1 Commits
mimo/resea
...
mimo/creat
| Author | SHA1 | Date | |
|---|---|---|---|
|
1294f37b44 |
@@ -1,305 +0,0 @@
|
||||
# Security Audit: NostrIdentity BIP340 Schnorr Signatures — Timing Side-Channel Analysis
|
||||
|
||||
**Issue:** #801
|
||||
**Repository:** Timmy_Foundation/the-nexus
|
||||
**File:** `nexus/nostr_identity.py`
|
||||
**Auditor:** mimo-v2-pro swarm worker
|
||||
**Date:** 2026-04-10
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
The pure-Python BIP340 Schnorr signature implementation in `NostrIdentity` has **multiple timing side-channel vulnerabilities** that could allow an attacker with precise timing measurements to recover the private key. The implementation is suitable for prototyping and non-adversarial environments but **must not be used in production** without the fixes described below.
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
The Nostr sovereign identity system consists of two files:
|
||||
|
||||
- **`nexus/nostr_identity.py`** — Pure-Python secp256k1 + BIP340 Schnorr signature implementation. No external dependencies. Contains `NostrIdentity` class for key generation, event signing, and pubkey derivation.
|
||||
- **`nexus/nostr_publisher.py`** — Async WebSocket publisher that sends signed Nostr events to public relays (damus.io, nos.lol, snort.social).
|
||||
- **`app.js` (line 507)** — Browser-side `NostrAgent` class uses **mock signatures** (`mock_id`, `mock_sig`), not real crypto. Not affected.
|
||||
|
||||
---
|
||||
|
||||
## Vulnerabilities Found
|
||||
|
||||
### 1. Branch-Dependent Scalar Multiplication — CRITICAL
|
||||
|
||||
**Location:** `nostr_identity.py:41-47` — `point_mul()`
|
||||
|
||||
```python
|
||||
def point_mul(p, n):
|
||||
r = None
|
||||
for i in range(256):
|
||||
if (n >> i) & 1: # <-- branch leaks Hamming weight
|
||||
r = point_add(r, p)
|
||||
p = point_add(p, p)
|
||||
return r
|
||||
```
|
||||
|
||||
**Problem:** The `if (n >> i) & 1` branch causes `point_add(r, p)` to execute only when the bit is 1. An attacker measuring signature generation time can determine which bits of the scalar are set, recovering the private key from a small number of timed signatures.
|
||||
|
||||
**Severity:** CRITICAL — direct private key recovery.
|
||||
|
||||
**Fix:** Use a constant-time double-and-always-add algorithm:
|
||||
|
||||
```python
|
||||
def point_mul(p, n):
|
||||
r = (None, None)
|
||||
for i in range(256):
|
||||
bit = (n >> i) & 1
|
||||
r0 = point_add(r, p) # always compute both
|
||||
r = r0 if bit else r # constant-time select
|
||||
p = point_add(p, p)
|
||||
return r
|
||||
```
|
||||
|
||||
Or better: use Montgomery ladder which avoids point doubling on the identity.
|
||||
|
||||
---
|
||||
|
||||
### 2. Branch-Dependent Point Addition — CRITICAL
|
||||
|
||||
**Location:** `nostr_identity.py:28-39` — `point_add()`
|
||||
|
||||
```python
|
||||
def point_add(p1, p2):
|
||||
if p1 is None: return p2 # <-- branch leaks operand state
|
||||
if p2 is None: return p1 # <-- branch leaks operand state
|
||||
(x1, y1), (x2, y2) = p1, p2
|
||||
if x1 == x2 and y1 != y2: return None # <-- branch leaks equality
|
||||
if x1 == x2: # <-- branch leaks equality
|
||||
m = (3 * x1 * x1 * inverse(2 * y1, P)) % P
|
||||
else:
|
||||
m = ((y2 - y1) * inverse(x2 - x1, P)) % P
|
||||
...
|
||||
```
|
||||
|
||||
**Problem:** Multiple conditional branches leak whether inputs are the identity point, whether x-coordinates are equal, and whether y-coordinates are negations. Combined with the scalar multiplication above, this gives an attacker detailed timing information about intermediate computations.
|
||||
|
||||
**Severity:** CRITICAL — compounds the scalar multiplication leak.
|
||||
|
||||
**Fix:** Replace with a branchless point addition using Jacobian or projective coordinates with dummy operations:
|
||||
|
||||
```python
|
||||
def point_add(p1, p2):
|
||||
# Use Jacobian coordinates; always perform full addition
|
||||
# Use conditional moves (simulated with arithmetic masking)
|
||||
# for selecting between doubling and addition paths
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Branch-Dependent Y-Parity Check in Signing — HIGH
|
||||
|
||||
**Location:** `nostr_identity.py:57-58` — `sign_schnorr()`
|
||||
|
||||
```python
|
||||
R = point_mul(G, k)
|
||||
if R[1] % 2 != 0: # <-- branch leaks parity of R's y-coordinate
|
||||
k = N - k
|
||||
```
|
||||
|
||||
**Problem:** The conditional negation of `k` based on the y-parity of R leaks information about the nonce through timing. While less critical than the point_mul leak (it's a single bit), combined with other leaks it aids key recovery.
|
||||
|
||||
**Severity:** HIGH
|
||||
|
||||
**Fix:** Use arithmetic masking:
|
||||
|
||||
```python
|
||||
R = point_mul(G, k)
|
||||
parity = R[1] & 1
|
||||
k = (k * (1 - parity) + (N - k) * parity) % N # constant-time select
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Non-Constant-Time Modular Inverse — MEDIUM
|
||||
|
||||
**Location:** `nostr_identity.py:25-26` — `inverse()`
|
||||
|
||||
```python
|
||||
def inverse(a, n):
|
||||
return pow(a, n - 2, n)
|
||||
```
|
||||
|
||||
**Problem:** CPython's built-in `pow()` with 3 args uses Montgomery ladder internally, which is *generally* constant-time for fixed-size operands. However:
|
||||
- This is an implementation detail, not a guarantee.
|
||||
- PyPy, GraalPy, and other Python runtimes may use different algorithms.
|
||||
- The exponent `n-2` has a fixed Hamming weight for secp256k1's `N`, so this specific case is less exploitable, but relying on it is fragile.
|
||||
|
||||
**Severity:** MEDIUM — implementation-dependent; low risk on CPython specifically.
|
||||
|
||||
**Fix:** Implement Fermat's little theorem inversion with blinding, or use a dedicated constant-time GCD algorithm (extended binary GCD).
|
||||
|
||||
---
|
||||
|
||||
### 5. Non-RFC6979 Nonce Generation — LOW (but non-standard)
|
||||
|
||||
**Location:** `nostr_identity.py:55`
|
||||
|
||||
```python
|
||||
k = int.from_bytes(sha256(privkey.to_bytes(32, 'big') + msg_hash), 'big') % N
|
||||
```
|
||||
|
||||
**Problem:** The nonce derivation is `SHA256(privkey || msg_hash)` which is deterministic but doesn't follow RFC6979 (HMAC-based DRBG). Issues:
|
||||
- Not vulnerable to timing (it's a single hash), but could be vulnerable to related-message attacks if the same key signs messages with predictable relationships.
|
||||
- BIP340 specifies `tagged_hash("BIP0340/nonce", ...)` with specific domain separation, which is not used here.
|
||||
|
||||
**Severity:** LOW — not a timing issue but a cryptographic correctness concern.
|
||||
|
||||
**Fix:** Follow RFC6979 or BIP340's tagged hash approach:
|
||||
|
||||
```python
|
||||
def sign_schnorr(msg_hash, privkey):
|
||||
# BIP340 nonce generation with tagged hash
|
||||
t = privkey.to_bytes(32, 'big')
|
||||
if R_y_is_odd:
|
||||
t = bytes(b ^ 0x01 for b in t) # negate if needed
|
||||
k = int.from_bytes(tagged_hash("BIP0340/nonce", t + pubkey + msg_hash), 'big') % N
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. Private Key Bias in Random Generation — LOW
|
||||
|
||||
**Location:** `nostr_identity.py:69`
|
||||
|
||||
```python
|
||||
self.privkey = int.from_bytes(os.urandom(32), 'big') % N
|
||||
```
|
||||
|
||||
**Problem:** `os.urandom(32)` produces values in `[0, 2^256)`, while `N` is slightly less than `2^256`. The modulo reduction introduces a negligible bias (~2^-128). Not exploitable in practice, but not the cleanest approach.
|
||||
|
||||
**Severity:** LOW — theoretically biased, practically unexploitable.
|
||||
|
||||
**Fix:** Use rejection sampling or derive from a hash:
|
||||
|
||||
```python
|
||||
def generate_privkey():
|
||||
while True:
|
||||
candidate = int.from_bytes(os.urandom(32), 'big')
|
||||
if 0 < candidate < N:
|
||||
return candidate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. No Scalar/Point Blinding — MEDIUM
|
||||
|
||||
**Location:** Global — no blinding anywhere in the implementation.
|
||||
|
||||
**Problem:** The implementation has no countermeasures against:
|
||||
- **Power analysis** (DPA/SPA) on embedded systems
|
||||
- **Cache-timing attacks** on shared hardware (VMs, cloud)
|
||||
- **Electromagnetic emanation** attacks
|
||||
|
||||
Adding random blinding to scalar multiplication (multiply by `r * r^-1` where `r` is random) would significantly raise the bar for side-channel attacks beyond simple timing.
|
||||
|
||||
**Severity:** MEDIUM — not timing-specific, but important for hardening.
|
||||
|
||||
---
|
||||
|
||||
## What's NOT Vulnerable (Good News)
|
||||
|
||||
1. **The JS-side `NostrAgent` in `app.js`** uses mock signatures (`mock_id`, `mock_sig`) — not real crypto, not affected.
|
||||
2. **`nostr_publisher.py`** correctly imports and uses `NostrIdentity` without modifying its internals.
|
||||
3. **The hash functions** (`sha256`, `hmac_sha256`) use Python's `hashlib` which delegates to OpenSSL — these are constant-time.
|
||||
4. **The JSON serialization** in `sign_event()` is deterministic and doesn't leak timing.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Fix (Full Remediation)
|
||||
|
||||
### Priority 1: Replace with secp256k1-py or coincurve (IMMEDIATE)
|
||||
|
||||
The fastest, most reliable fix is to stop using the pure-Python implementation entirely:
|
||||
|
||||
```python
|
||||
# nostr_identity.py — replacement using coincurve
|
||||
import coincurve
|
||||
import hashlib
|
||||
import json
|
||||
import os
|
||||
|
||||
class NostrIdentity:
|
||||
def __init__(self, privkey_hex=None):
|
||||
if privkey_hex:
|
||||
self.privkey = bytes.fromhex(privkey_hex)
|
||||
else:
|
||||
self.privkey = os.urandom(32)
|
||||
self.pubkey = coincurve.PrivateKey(self.privkey).public_key.format(compressed=True)[1:].hex()
|
||||
|
||||
def sign_event(self, event):
|
||||
event_data = [0, event['pubkey'], event['created_at'], event['kind'], event['tags'], event['content']]
|
||||
serialized = json.dumps(event_data, separators=(',', ':'))
|
||||
msg_hash = hashlib.sha256(serialized.encode()).digest()
|
||||
event['id'] = msg_hash.hex()
|
||||
# Use libsecp256k1's BIP340 Schnorr (constant-time C implementation)
|
||||
event['sig'] = coincurve.PrivateKey(self.privkey).sign_schnorr(msg_hash).hex()
|
||||
return event
|
||||
```
|
||||
|
||||
**Effort:** ~2 hours (swap implementation, add `coincurve` to `requirements.txt`, test)
|
||||
**Risk:** Adds a C dependency. If pure-Python is required (sovereignty constraint), use Priority 2.
|
||||
|
||||
### Priority 2: Pure-Python Constant-Time Rewrite (IF PURE PYTHON REQUIRED)
|
||||
|
||||
If the sovereignty constraint (no C dependencies) must be maintained, rewrite the elliptic curve operations:
|
||||
|
||||
1. **Replace `point_mul`** with Montgomery ladder (constant-time by design)
|
||||
2. **Replace `point_add`** with Jacobian coordinate addition that always performs both doubling and addition, selecting with arithmetic masking
|
||||
3. **Replace `inverse`** with extended binary GCD with blinding
|
||||
4. **Fix nonce generation** to follow RFC6979 or BIP340 tagged hashes
|
||||
5. **Fix key generation** to use rejection sampling
|
||||
|
||||
**Effort:** ~8-12 hours (careful implementation + test vectors from BIP340 spec)
|
||||
**Risk:** Pure-Python crypto is inherently slower (~100ms per signature vs ~1ms with libsecp256k1)
|
||||
|
||||
### Priority 3: Hybrid Approach
|
||||
|
||||
Use `coincurve` when available, fall back to pure-Python with warnings:
|
||||
|
||||
```python
|
||||
try:
|
||||
import coincurve
|
||||
USE_LIB = True
|
||||
except ImportError:
|
||||
USE_LIB = False
|
||||
import warnings
|
||||
warnings.warn("Using pure-Python Schnorr — vulnerable to timing attacks. Install coincurve for production use.")
|
||||
```
|
||||
|
||||
**Effort:** ~3 hours
|
||||
|
||||
---
|
||||
|
||||
## Effort Estimate
|
||||
|
||||
| Fix | Effort | Risk Reduction | Recommended |
|
||||
|-----|--------|----------------|-------------|
|
||||
| Replace with coincurve (Priority 1) | 2h | Eliminates all timing issues | YES — do this |
|
||||
| Pure-Python constant-time rewrite (Priority 2) | 8-12h | Eliminates timing issues | Only if no-C constraint is firm |
|
||||
| Hybrid (Priority 3) | 3h | Full for installed, partial for fallback | Good compromise |
|
||||
| Findings doc + PR (this work) | 2h | Documents the problem | DONE |
|
||||
|
||||
---
|
||||
|
||||
## Test Vectors
|
||||
|
||||
The BIP340 specification includes test vectors at https://github.com/bitcoin/bips/blob/master/bip-00340/test-vectors.csv
|
||||
|
||||
Any replacement implementation MUST pass all test vectors before deployment.
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
The pure-Python BIP340 Schnorr implementation in `NostrIdentity` is **vulnerable to timing side-channel attacks** that could recover the private key. The primary issue is branch-dependent execution in scalar multiplication and point addition. The fastest fix is replacing with `coincurve` (libsecp256k1 binding). If pure-Python sovereignty is required, a constant-time rewrite using Montgomery ladder and arithmetic masking is needed.
|
||||
|
||||
The JS-side `NostrAgent` in `app.js` uses mock signatures and is not affected.
|
||||
|
||||
**Recommendation:** Ship `coincurve` replacement immediately. It's 2 hours of work and eliminates the entire attack surface.
|
||||
@@ -1,132 +1,169 @@
|
||||
# Legacy Matrix Audit
|
||||
# Legacy Matrix Audit — Migration Table
|
||||
|
||||
Purpose:
|
||||
Preserve useful work from `/Users/apayne/the-matrix` before the Nexus browser shell is rebuilt.
|
||||
Preserve quality work from `/Users/apayne/the-matrix` before the Nexus browser shell is rebuilt.
|
||||
|
||||
Canonical rule:
|
||||
- `Timmy_Foundation/the-nexus` is the only canonical 3D repo.
|
||||
- `/Users/apayne/the-matrix` is legacy source material, not a parallel product.
|
||||
- This document is the authoritative migration table for issue #685.
|
||||
|
||||
## Verified Legacy Matrix State
|
||||
## Verified Legacy State
|
||||
|
||||
Local legacy repo:
|
||||
- `/Users/apayne/the-matrix`
|
||||
Local legacy repo: `/Users/apayne/the-matrix`
|
||||
|
||||
Observed facts:
|
||||
- Vite browser app exists
|
||||
- `npm test` passes with `87 passed, 0 failed`
|
||||
- 23 JS modules under `js/`
|
||||
- package scripts include `dev`, `build`, `preview`, and `test`
|
||||
- Vite browser app, vanilla JS + Three.js 0.171.0
|
||||
- 24 JS modules under `js/`
|
||||
- Smoke suite: 87 passed, 0 failed
|
||||
- Package scripts: dev, build, preview, test
|
||||
- PWA manifest + service worker
|
||||
- Vite config with code-splitting (Three.js in separate chunk)
|
||||
- Quality-tier system for hardware detection
|
||||
- WebSocket client with reconnection, heartbeat, mock mode
|
||||
- Full avatar FPS movement + PiP camera
|
||||
- Sub-world portal system with zone triggers
|
||||
|
||||
## Known historical Nexus snapshot
|
||||
## Migration Table
|
||||
|
||||
Useful in-repo reference point:
|
||||
- `0518a1c3ae3c1d0afeb24dea9772102f5a3d9a66`
|
||||
Decision key:
|
||||
- **CARRY** = transplant concepts and patterns into Nexus vNext
|
||||
- **ARCHIVE** = keep as reference, do not directly transplant
|
||||
- **DROP** = do not preserve unless re-justified
|
||||
|
||||
That snapshot still contains browser-world root files such as:
|
||||
- `index.html`
|
||||
- `app.js`
|
||||
- `style.css`
|
||||
- `package.json`
|
||||
- `tests/`
|
||||
### Core Modules
|
||||
|
||||
## Rescue Candidates
|
||||
| File | Lines | Capability | Decision | Why for Nexus |
|
||||
|------|-------|------------|----------|---------------|
|
||||
| `js/main.js` | 180 | App bootstrap, render loop, WebGL context recovery | **CARRY** | Architectural pattern. Shows clean init/teardown lifecycle, context-loss recovery, visibility pause. Nexus needs this loop but should not copy the monolithic wiring. |
|
||||
| `js/world.js` | 95 | Scene, camera, renderer, grid, lights | **CARRY** | Foundational. Quality-tier-aware renderer setup, grid floor, lighting. Nexus already has a world but should adopt the tier-aware antialiasing and pixel-ratio capping. |
|
||||
| `js/config.js` | 68 | Connection config via URL params + env vars | **ARCHIVE** | Pattern reference only. Nexus config should route through Hermes harness, not Vite env vars. The URL-override pattern (ws, token, mock) is worth remembering. |
|
||||
| `js/quality.js` | 90 | Hardware detection, quality tier (low/medium/high) | **CARRY** | Directly useful. DPR capping, core/memory/screen heuristics, WebGL renderer sniffing. Nexus needs this for graceful degradation on Mac/iPad. |
|
||||
| `js/storage.js` | 39 | Safe localStorage with in-memory fallback | **CARRY** | Small, robust, sandbox-proof. Nexus should use this or equivalent. Prevents crashes in sandboxed iframes. |
|
||||
|
||||
### Carry forward into Nexus vNext
|
||||
### Agent System
|
||||
|
||||
1. `agent-defs.js`
|
||||
- agent identity definitions
|
||||
- useful as seed data/model for visible entities in the world
|
||||
| File | Lines | Capability | Decision | Why for Nexus |
|
||||
|------|-------|------------|----------|---------------|
|
||||
| `js/agent-defs.js` | 30 | Agent identity data (id, label, color, role, position) | **CARRY** | Seed data model. Nexus agents should be defined similarly — data-driven, not hardcoded in render logic. Color hex helper is trivial but useful. |
|
||||
| `js/agents.js` | 523 | Agent 3D objects, movement, state, connection lines, hot-add/remove | **CARRY** | Core visual system. Shared geometries (perf), movement interpolation, wallet-health stress glow, auto-placement algorithm, connection-line pulse. All valuable. Needs integration with real agent state from Hermes. |
|
||||
| `js/behaviors.js` | 413 | Autonomous agent behavior state machine | **ARCHIVE** | Pattern reference. The personality-weighted behavior selection, conversation pairing, and artifact-placement system are well-designed. But Nexus behaviors should be driven by Hermes, not a client-side simulation. Keep the architecture, drop the fake-autonomy. |
|
||||
| `js/presence.js` | 139 | Agent presence HUD (online/offline, uptime, state) | **CARRY** | Valuable UX. Live "who's here" panel with uptime tickers and state indicators. Needs real backend state, not mock assumptions. |
|
||||
|
||||
2. `agents.js`
|
||||
- agent objects, state machine, connection lines
|
||||
- useful for visualizing Timmy / subagents / system processes in a world-native way
|
||||
### Visitor & Interaction
|
||||
|
||||
3. `avatar.js`
|
||||
- visitor embodiment, movement, camera handling
|
||||
- strongly aligned with "training ground" and "walk the world" goals
|
||||
| File | Lines | Capability | Decision | Why for Nexus |
|
||||
|------|-------|------------|----------|---------------|
|
||||
| `js/visitor.js` | 141 | Visitor enter/leave protocol, chat input | **CARRY** | Session lifecycle. Device detection, visibility-based leave/return, chat input wiring. Directly applicable to Nexus visitor tracking. |
|
||||
| `js/avatar.js` | 360 | FPS movement, PiP dual-camera, touch input | **CARRY** | Visitor embodiment. WASD + arrow movement, first/third person swap, PiP canvas, touch joystick, right-click mouse-look. Strong work. Needs tuning for Nexus world bounds. |
|
||||
| `js/interaction.js` | 296 | Raycasting, click-to-select agents, info popup | **CARRY** | Essential for any browser world. OrbitControls, pointer/tap detection, agent popup with state/role, TALK button. The popup-anchoring-to-3D-position logic is particularly well done. |
|
||||
| `js/zones.js` | 161 | Proximity trigger zones (portal enter/exit, events) | **CARRY** | Spatial event system. Portal traversal, event triggers, once-only zones. Nexus portals (#672) need this exact pattern. |
|
||||
|
||||
4. `ui.js`
|
||||
- HUD, chat surfaces, overlays
|
||||
- useful if rebuilt against real harness data instead of stale fake state
|
||||
### Chat & Communication
|
||||
|
||||
5. `websocket.js`
|
||||
- browser-side live bridge patterns
|
||||
- useful if retethered to Hermes-facing transport
|
||||
| File | Lines | Capability | Decision | Why for Nexus |
|
||||
|------|-------|------------|----------|---------------|
|
||||
| `js/bark.js` | 141 | Speech bubble system with typing animation | **CARRY** | Timmy's voice in-world. Typing animation, queue, auto-dismiss, emotion tags, demo bark lines. Strong expressive presence. The demo lines ("The Tower watches. The Tower remembers.") are good seed content. |
|
||||
| `js/ui.js` | 285 | Chat panel, agent list, HUD, streaming tokens | **CARRY** | Chat infrastructure. Rolling chat buffer, per-agent localStorage history, streaming token display with cursor animation, HTML escaping. Needs reconnection to Hermes chat instead of WS mock. |
|
||||
| `js/transcript.js` | 183 | Conversation transcript logger, export | **ARCHIVE** | Pattern reference. The rolling buffer, structured JSON entries, TXT/JSON download, HUD badge are all solid. But transcript authority should live in Hermes, not browser localStorage. Keep the UX pattern, rebuild storage layer. |
|
||||
|
||||
6. `transcript.js`
|
||||
- local transcript capture pattern
|
||||
- useful if durable truth still routes through Hermes and browser cache remains secondary
|
||||
### Visual Effects
|
||||
|
||||
7. `ambient.js`
|
||||
- mood / atmosphere system
|
||||
- directly supports wizardly presentation without changing system authority
|
||||
| File | Lines | Capability | Decision | Why for Nexus |
|
||||
|------|-------|------------|----------|---------------|
|
||||
| `js/effects.js` | 195 | Matrix rain particles + starfield | **CARRY** | Atmospheric foundation. Quality-tier particle counts, frame-skip optimization, adaptive draw-range (FPS-budget recovery), bounding-sphere pre-compute. This is production-grade particle work. |
|
||||
| `js/ambient.js` | 212 | Mood-driven atmosphere (lighting, fog, rain, stars) | **CARRY** | Scene mood engine. Smooth eased transitions between mood states (calm, focused, excited, contemplative, stressed), per-mood lighting/fog/rain/star parameters. Directly supports Nexus atmosphere. |
|
||||
| `js/satflow.js` | 261 | Lightning payment particle flow | **CARRY** | Economy visualization. Bezier-arc particles, staggered travel, burst-on-arrival, pooling. If Nexus shows any payment/economy flow, this is the pattern. |
|
||||
|
||||
8. `satflow.js`
|
||||
- visual economy / payment flow motifs
|
||||
- useful if Timmy's economy/agent interactions become a real visible layer
|
||||
### Economy & Scene
|
||||
|
||||
9. `economy.js`
|
||||
- treasury / wallet panel ideas
|
||||
- useful if later backed by real sovereign metrics
|
||||
| File | Lines | Capability | Decision | Why for Nexus |
|
||||
|------|-------|------------|----------|---------------|
|
||||
| `js/economy.js` | 100 | Wallet/treasury HUD panel | **ARCHIVE** | UI pattern reference. Clean sats formatting, per-agent balance rows, health-colored dots, recent transactions. Worth rebuilding when backed by real sovereign metrics. |
|
||||
| `js/scene-objects.js` | 718 | Dynamic 3D object registry, portals, sub-worlds | **CARRY** | Critical. Geometry/material factories, animation system (rotate/bob/pulse/orbit), portal visual (torus ring + glow disc + zone), sub-world load/unload, text sprites, compound groups. This is the most complex and valuable module. Nexus portals (#672) should build on this. |
|
||||
|
||||
10. `presence.js`
|
||||
- who-is-here / online-state UI
|
||||
- useful for showing human + agent + process presence in the world
|
||||
### Backend Bridge
|
||||
|
||||
11. `interaction.js`
|
||||
- clicking, inspecting, selecting world entities
|
||||
- likely needed in any real browser-facing Nexus shell
|
||||
| File | Lines | Capability | Decision | Why for Nexus |
|
||||
|------|-------|------------|----------|---------------|
|
||||
| `js/websocket.js` | 598 | WebSocket client, message dispatcher, mock mode | **ARCHIVE** | Pattern reference only. Reconnection with exponential backoff, heartbeat/zombie detection, rich message dispatch (40+ message types), streaming chat support. The architecture is sound but must be reconnected to Hermes transport, not copied wholesale. The message-type catalog is the most valuable reference artifact. |
|
||||
| `js/demo.js` | ~300 | Demo autopilot (mock mode simulation) | **DROP** | Fake activity simulation. Deliberately creates the illusion of live data. Do not preserve. If Nexus needs a demo mode, build a clearly-labeled one that doesn't pretend to be real. |
|
||||
|
||||
12. `quality.js`
|
||||
- hardware-aware quality tiering
|
||||
- useful for local-first graceful degradation on Mac hardware
|
||||
### Testing & Build
|
||||
|
||||
13. `bark.js`
|
||||
- prominent speech / bark system
|
||||
- strong fit for Timmy's expressive presence in-world
|
||||
| File | Lines | Capability | Decision | Why for Nexus |
|
||||
|------|-------|------------|----------|---------------|
|
||||
| `test/smoke.mjs` | 235 | Automated browser smoke test suite | **CARRY** | Testing discipline. Module inventory check, export verification, HTML structure validation, Vite build test, bundle-size budget, PWA manifest check. Nexus should adopt this pattern (adapted for its own module structure). |
|
||||
| `vite.config.js` | 53 | Build config with code splitting, SW generation | **ARCHIVE** | Build tooling reference. manualChunks for Three.js, SW precache generation plugin. Relevant if Nexus re-commits to Vite. |
|
||||
| `sw.js` | ~40 | Service worker with precache | **ARCHIVE** | PWA reference. Relevant only if Nexus pursues offline-first PWA. |
|
||||
| `manifest.json` | ~20 | PWA manifest | **ARCHIVE** | PWA reference. |
|
||||
|
||||
14. `world.js`, `effects.js`, `scene-objects.js`, `zones.js`
|
||||
- broad visual foundation work
|
||||
- should be mined for patterns, not blindly transplanted
|
||||
### Server-Side (Python)
|
||||
|
||||
15. `test/smoke.mjs`
|
||||
- browser smoke discipline
|
||||
- should inform rebuilt validation in canonical Nexus repo
|
||||
| File | Lines | Capability | Decision | Why for Nexus |
|
||||
|------|-------|------------|----------|---------------|
|
||||
| `server/bridge.py` | ~900 | WebSocket bridge server | **ARCHIVE** | Reference. Hermes replaces this role. Keep for protocol schema reference. |
|
||||
| `server/gateway.py` | ~400 | HTTP gateway | **ARCHIVE** | Reference. |
|
||||
| `server/ollama_client.py` | ~280 | Ollama integration | **ARCHIVE** | Reference. Relevant if Nexus needs local model calls. |
|
||||
| `server/research.py` | ~450 | Research pipeline | **ARCHIVE** | Reference. |
|
||||
| `server/webhooks.py` | ~350 | Webhook handler | **ARCHIVE** | Reference. |
|
||||
| `server/test_*.py` | ~5 files | Server test suites | **ARCHIVE** | Testing patterns worth studying. |
|
||||
|
||||
### Archive as reference, not direct carry-forward
|
||||
## Summary by Decision
|
||||
|
||||
- demo/autopilot assumptions that pretend fake backend activity is real
|
||||
- any websocket schema that no longer matches Hermes truth
|
||||
- Vite-specific plumbing that is only useful if we consciously recommit to Vite
|
||||
### CARRY FORWARD (17 modules)
|
||||
These modules contain patterns, algorithms, or entire implementations that should move into the Nexus browser shell:
|
||||
|
||||
### Deliberately drop unless re-justified
|
||||
- `quality.js` — hardware detection
|
||||
- `storage.js` — safe persistence
|
||||
- `world.js` — scene foundation
|
||||
- `agent-defs.js` — agent data model
|
||||
- `agents.js` — agent visualization + movement
|
||||
- `presence.js` — online presence HUD
|
||||
- `visitor.js` — session lifecycle
|
||||
- `avatar.js` — FPS embodiment
|
||||
- `interaction.js` — click/select/raycast
|
||||
- `zones.js` — spatial triggers
|
||||
- `bark.js` — speech bubbles
|
||||
- `ui.js` — chat/HUD
|
||||
- `effects.js` — particle effects
|
||||
- `ambient.js` — mood atmosphere
|
||||
- `satflow.js` — payment flow particles
|
||||
- `scene-objects.js` — dynamic objects + portals
|
||||
- `test/smoke.mjs` — smoke test discipline
|
||||
|
||||
- anything that presents mock data as if it were live
|
||||
- anything that duplicates a better Hermes-native telemetry path
|
||||
- anything that turns the browser into the system of record
|
||||
### ARCHIVE AS REFERENCE (9 modules/files)
|
||||
Keep for patterns, protocol schemas, and architectural reference. Do not directly transplant:
|
||||
|
||||
- `config.js` — config pattern (use Hermes instead)
|
||||
- `behaviors.js` — behavior architecture (use Hermes-driven state)
|
||||
- `transcript.js` — transcript UX (use Hermes storage)
|
||||
- `economy.js` — economy UI pattern (use real metrics)
|
||||
- `websocket.js` — message protocol catalog + reconnection patterns
|
||||
- `vite.config.js` — build tooling
|
||||
- `sw.js`, `manifest.json` — PWA reference
|
||||
- `server/*.py` — server protocol schemas
|
||||
|
||||
### DELIBERATELY DROP (2)
|
||||
Do not preserve unless re-justified:
|
||||
|
||||
- `demo.js` — fake activity simulation; creates false impression of live system
|
||||
- `main.js` monolithic wiring — the init pattern carries, the specific module wiring does not
|
||||
|
||||
## Concern Separation for Nexus vNext
|
||||
|
||||
When rebuilding inside `the-nexus`, keep concerns separated:
|
||||
When rebuilding inside `the-nexus`, keep these concerns in separate modules:
|
||||
|
||||
1. World shell / rendering
|
||||
- scene, camera, movement, atmosphere
|
||||
|
||||
2. Presence and embodiment
|
||||
- avatar, agent placement, selection, bark/chat surfaces
|
||||
|
||||
3. Harness bridge
|
||||
- websocket / API bridge from Hermes truth into browser state
|
||||
|
||||
4. Visualization panels
|
||||
- metrics, presence, economy, portal states, transcripts
|
||||
|
||||
5. Validation
|
||||
- smoke tests, screenshot proof, provenance checks
|
||||
|
||||
6. Game portal layer
|
||||
- Morrowind / portal-specific interaction surfaces
|
||||
1. **World shell** — scene, camera, renderer, grid, lights, fog
|
||||
2. **Effects layer** — rain, stars, ambient mood transitions
|
||||
3. **Agent visualization** — 3D objects, labels, connection lines, movement
|
||||
4. **Visitor embodiment** — avatar, FPS controls, PiP camera
|
||||
5. **Interaction layer** — raycasting, selection, zones, portal traversal
|
||||
6. **Communication surface** — bark, chat panel, streaming tokens
|
||||
7. **Presence & HUD** — who's-online, economy panel, transcript controls
|
||||
8. **Harness bridge** — WebSocket/API transport to Hermes (NOT a copy of websocket.js)
|
||||
9. **Quality & config** — hardware detection, runtime configuration
|
||||
10. **Smoke tests** — automated validation
|
||||
|
||||
Do not collapse all of this into one giant app file again.
|
||||
Do not let visual shell code become telemetry authority.
|
||||
|
||||
Reference in New Issue
Block a user