peardata

Production-oriented boilerplate for Holepunch / HyperDHT P2P apps.

Distilled from patterns used in peardock-class apps (MIT template — not a copy of peardock’s AGPL sources):

Plane	Stack
Transport	HyperDHT secret streams (Noise)
RPC	protomux-rpc + compact-encoding JSON
Identity	Ed25519 keypairs (server seed + client identity file)
AuthZ	Roles (viewer / operator / admin) + HMAC capabilities + admin seed proof
Desktop	Pear (pear-electron + pear-bridge + <pear-ctrl> titlebar)
Server	Node 20+ (systemd unit included)

The demo product is PearData: a multi-peer room with messages, presence, and invite minting. Swap server/handlers/demo.js + server/services/room.js for your domain.

---

Quick start

cd pear_app_template   # or your clone path
npm install

# Terminal A — server (prints public key)
npm run start:server

# Terminal B — mint an operator invite (optional)
npm run mint-invite -- operator

# Terminal C — Pear desktop UI
npm start
# or: pear run -d .

In the UI, paste the server public key (viewer) or a pd1. invite (elevated role).
Paste SERVER_SEED from .env into “Admin seed” for full admin without an invite.

Drag the titlebar to move the window; resize from the edges (pear.gui.resizable).

npm test
npm run healthcheck

---

Repository layout

pear_app_template/
├── app.js                 # Desktop UI logic
├── index.html / index.js  # Pear shell (titlebar + pear-ctrl + drag)
├── ui/styles.css          # Titlebar drag regions + layout
├── shared/                # Protocol, encodings, schema, crypto-auth
├── server/                # HyperDHT listener + RPC middleware + demo domain
│   ├── server.js
│   ├── core/              # keys, acl, audit, peer-policy, registry
│   ├── rpc/               # PeerSession + register
│   ├── handlers/          # Domain RPCs (replace demo.js)
│   ├── services/          # Domain state (replace room.js)
│   └── utils/
├── client/                # Connection, manager, identity
├── bin/                   # Server binary entry
├── scripts/               # healthcheck, soak, mint-invite, rename, release
├── test/                  # brittle unit + integration
├── docs/                  # Full documentation set
├── deploy/                # systemd unit
├── .github/workflows/     # GitHub CI + release
└── .gitea/workflows/      # Gitea CI + rolling release skeleton

---

npm scripts

Script	Purpose
npm start / npm run dev	Pear desktop UI
npm run start:server	HyperDHT server
npm test	brittle unit + integration
npm run mint-invite -- [role] [ttlMs]	Offline pd1. invite
npm run healthcheck	Liveness / remote ping
npm run soak	Load exercise (needs env keys)
npm run rename -- <slug> <Product>	Rebrand the tree
bash scripts/release.sh	Source tarball + checksum

Full env reference: docs/CONFIGURATION.md.

---

Rebrand for a new app

npm run rename -- my-app MyApp
# → package name, protocol id, env prefixes, invite prefix, product strings

Then implement your domain:

1. Extend shared/protocol.js (MethodRoles, Pushes, Methods)
2. Validate args in shared/schema.js
3. Add handlers under server/handlers/
4. Register them in server/rpc/register.js
5. Call from client/ + UI
6. Update docs/PROTOCOL.md and tests

See docs/EXTENDING.md.

---

Auth model (secure defaults)

Mode	How	Role
Viewer	Dial public key only	viewer (read)
Capability	pd1. invite or raw HMAC token	grant role
Admin seed	HMAC proof from SERVER_SEED	admin
Allowlist	PEARDATA_ADMIN_KEYS	admin for listed peers
Dev escape	PEARDATA_INSECURE_OPEN_ADMIN=1	everyone admin

See docs/SECURITY.md.

---

CI

• GitHub: .github/workflows/ci.yml (Node 20/22 matrix + docs presence), release.yml on v* tags
• Gitea: .gitea/workflows/ci.yml, release-rolling.yml (every push to main → rolling release; needs RELEASE_TOKEN)

---

Documentation

Doc	Contents
Getting started	Install, run, connect, systemd, troubleshooting
Desktop	Pear shell, pear-ctrl, drag/resize, identity
Architecture	Planes, boot, session pipeline, module map
Protocol	Methods, pushes, errors, versioning
Security	Threat model, secrets, hardening checklist
Configuration	Full environment + scripts reference
Testing	brittle suite, soak, manual checks
CI	Pipelines and required docs
Release	Version, tag, tarball, rollback
Extending	Grow past the demo room

---

License

MIT — use this as a starting point for proprietary or open apps.
(Peardock itself is AGPL; this template does not copy peardock source verbatim and is intentionally MIT.)