gun - Moses Yebei

Repository: gun Clone URL: https://github.com/moses-y/gun

The Problem

GUN addresses the pain of building applications that require realtime, offline-first, end-to-end encrypted state synchronization without relying on a centralized server. It targets developers who need graph-structured data that syncs peer-to-peer, across browsers, mobile, and desktop, while surviving network partitions and offline use.

What This Does

This repository is a portfolio of 6 self-contained projects, not a single monolithic codebase. The directories and their responsibilities are:

lib (99 files, 96 code files) – Core runtime and graph management; contains gun.js, the hub module that 64 other modules depend on.
types (70 files) – Type definitions for the graph API and node types.
examples (205 files, 69 code files) – Drop-in demos for React, Angular, React-native, relay-sqlite, and vanilla usage; entry points include examples/Main.js, examples/angular/server.js, and examples/chat/index.html.
sea (26 files) – Secondary export layer; contains sea.js, sea/array.js, sea/buffer.js among others.
src (21 files) – Minimal source bundle; src/index is an entry point with 15 outgoing import edges and no dependents.
kit (2 files, 1 code file) – Utility scaffolding.

The codebase implements a decentralized graph protocol: nodes store key/value pairs, tables, or binary blobs; synchronization happens over WebRTC/DataChannels or REST fallbacks; encryption is handled locally before data leaves the client.

How It Is Wired

Execution starts at the example entry points (e.g., examples/Main.js). The central module gun.js is the hub: 64 modules import from it, and it imports from lib/store, lib/rfs, and sea/shim. The import graph contains 383 internal modules connected by 374 edges with zero circular dependencies. The most connected downstream modules are lib/server (14 imports, instability 0.88) and src/index (15 outgoing edges, instability 1). Files gun.js, test/expect.js, and test/panic/util/open.js exhibit deep nesting (max depth 9), oversized bodies (2298 lines in gun.js, sea.js), and duplicated 6-line blocks repeated across 125 files (3894 occurrences). Empty catch blocks appear in gun.js, lib/store.js, and sea/root.js, silently discarding errors.

How To Use It

Setup:

git clone https://github.com/moses-y/gun
cd gun
npm install

The repository uses npm as package manager; package-lock.json is committed. Build/configuration is example-driven; each example folder has its own package.json, tsconfig.json, or vite.config.ts.

Configuration: No global environment variables are required for basic use. Keys or node IDs are generated locally or passed via the GUN constructor options. For relay or server-mode deployments, configure a signaling server URL in the example’s server.js or angular/server.js.

Running it:

cd node_modules/gun && npm start

This starts the example server (usually examples/Main.js or the Angular dev server). An online demo is available at http://try.axe.eco/, and a playground exists at https://jsbin.com/kadobamevo/edit?js,console.

Real-World Use

A development team building a collaborative, offline-first wiki can embed gun as a local graph store. Data entered offline is encrypted, synced peer-to-peer when connectivity returns, and persists in IndexedDB or LevelDB. The same code runs in a Node.js backend (lib/server) or in the browser (browser.js). Use cases cited in the README include decentralized video conferencing, GPS tracking, IoT telemetry, and P2P social clients, all demonstrating terabytes of daily P2P traffic in production.

Code Health & Issues

Static analysis of 391 code files yielded 292 findings across 6 kinds:

HIGH cognitive_load – Deep nesting in gun.js, test/panic/util/open.js, test/expect.js; oversized files gun.js, sea.js, test/expect.js.
MEDIUM resilience – 17 empty catch blocks across gun.js, lib/store.js, sea/root.js that silently discard errors.
MEDIUM cognitive_load – High branching density (1767 branch points over 2298 lines) in gun.js, test/expect.js, lib/rfs.js.
HIGH clarity – Hub module gun.js with 64 dependents; duplicated 6-line blocks across 125 files.
MEDIUM/LOW – 292 total findings; 37 high, 227 medium, 28 low.

SDLC observations from the file structure: 163 test files, 9 doc files, Travis CI configured, Dockerfile present, license and lockfile committed, no secrets found in git history.

The Bottom Line

GUN is a functional, battle-tested protocol for decentralized graph sync, deployed at scale by dozens of production apps. Its architecture trades a steep learning curve and moderate code-maintenance burden (large, nested modules, duplicated logic) for genuine peer-to-peer resilience and offline capability. Teams that need realtime, encrypted, offline-first state sync without a central server will find it valuable; teams requiring a compact, modular codebase may need to extract or restructure the core modules.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

596 files

JavaScript265
TypeScript119
HTML78
JSON23
Markdown11
CSS10

ReactVueAngularExpressDocker

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["lib 95 modules"] g1["test 91 modules"] g2["types 70 modules"] g3["examples 67 modules"] g4["sea 26 modules"] g5["src 21 modules"] g6["(root) 12 modules"] g1 -->|57| g0 g0 -->|53| g6 g1 -->|28| g6 g6 -->|3| g0 g3 -->|1| g6 g3 -->|1| g0 g0 -->|1| g2

Module dependencies

The 10 most depended-upon modules of 383, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_gun["gun"] n1_test_panic_util_open["open"] n2_test_expect["expect"] n3_lib_store["store"] n4_lib_rfs["rfs"] n5_sea_shim["shim"] n6_lib_fsrm["fsrm"] n7_sea_root["root"] n8_sea["sea"] n9_src_root["root"] n4_lib_rfs --> n0_gun n3_lib_store --> n0_gun n5_sea_shim --> n7_sea_root

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium7

low1

Pin third-party GitHub Actions to a commit SHAhigh2 occurrences

.github/workflows

tcurdt/action-verify-version-npm@master, softprops/action-gh-release@v2

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/ci.yml

1 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

2 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Install from the lockfile in CImedium

.github/workflows

npm install with a committed package-lock.json

A fresh resolution in CI means the tested dependency set is not the locked one, so the failure only appears after merge.

Fix: Use npm ci, yarn install --immutable, or pnpm install --frozen-lockfile.

Pin the container base image by digestmedium2 occurrences

Dockerfile

node:lts-alpine, node:lts-alpine

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow

.github/workflows/ci.yml

1 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.