snxraven/peardata
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
0f865348053798a2a38880fe6c40a3505c49319a
peardata/docs/SECURITY.md
T
Raven Scott 5521f2952a
CI / test (push) Successful in 1m1s
Details
Release rolling / release (push) Has been cancelled
Details
Update Docs
2026-07-19 13:35:19 -04:00

5.4 KiB
Raw Blame History

Security

Trust model

  • Server seed (SERVER_SEED) is the root of HMAC auth (capabilities + admin proofs). Compromise = full admin minting.
  • Client identity seed under ~/.config/peardata/identity.json identifies the peer across reconnects. Protect it if you bind capabilities to peerId.
  • HyperDHT provides mutual authentication of keypairs on the secret stream. RPC still needs application AuthZ (roles).
  • UI process can hold an admin seed in memory when the user pastes it — treat the desktop machine as trusted for that session.

Auth paths

  1. Admin proof — client proves knowledge of seed-derived MAC key without sending the seed (createAdminProof / verifyAdminProof).
  2. Capability — server-signed grant with role, optional expiry, optional peer binding, JTI spend tracking.
  3. Registered peer — after a successful grant, reconnects may use the stored role without replaying a spent JTI (see redeemCapability / peer policy).
  4. Admin keys env — PEARDATA_ADMIN_KEYS forces admin for listed peer public keys.
  5. Revocation — revokePeer drops live sessions and blocks future dials.
  6. Allowlist — when PEARDATA_ALLOWLIST is non-empty, unknown peers are rejected.

Secure defaults

Default Value
Unknown peer role viewer
Open admin off
Capability forever yes unless ttlMs set
Rate limit 120 RPC / minute / peer
Audit mutating methods + handshake failures
Identity file mode 0600
Data directory local ./data (not committed)

REST API exposure

  • Default bind is localhost only (127.0.0.1:18888).
  • REST is intentionally open on that bind (local-agent style) — do not set PEARDATA_REST_HOST=0.0.0.0 without a firewall, reverse proxy, or Holesail tunnel.
  • Prefer P2P + roles for remote multi-operator access; use REST for local scrapers/Grafana.

Production checklist

  • Never set PEARDATA_INSECURE_OPEN_ADMIN outside local demos
  • Keep PEARDATA_DEFAULT_ROLE=viewer
  • Prefer pd1. invites over sharing SERVER_SEED
  • Use short ttlMs for high-privilege invites when practical
  • Set PEARDATA_ALLOWLIST if only known operators should dial
  • Keep REST on localhost unless explicitly secured
  • Back up SERVER_SEED offline; rotate by redeploying a new keypair (clients must re-dial)
  • Persist data/ with mode 0700; audit.log may contain peer ids
  • Run under systemd with ProtectSystem / NoNewPrivileges (see deploy/)
  • Do not embed seed in frontend builds, CI logs, or crash reports
  • Review LOG_LEVEL=debug before production (avoid verbose auth noise)
  • Journal is on by default (admin-only over P2P); it can expose secrets from other units — set PEARDATA_JOURNAL=0 if you do not want host log access
  • If Docker is enabled, peardata ∈ docker can inspect all containers via the socket — treat that as host-equivalent visibility; disable with PEARDATA_DOCKER=0 and remove the group if unwanted
  • Keep Pear / dependency updates current (npm outdated)

Threat notes

Threat Mitigation
Stolen invite Short TTL; peer-bound capabilities; revoke JTI / peer
Stolen client identity Revoke peer id; re-issue invites
Stolen SERVER_SEED Rotate keypair; all grants invalid; re-onboard clients
RPC spam Rate limiter (PEARDATA_RATE_LIMIT_RPM)
Confused deputy role Server never trusts client-supplied role field
Log leakage Logger never prints seeds/tokens
Rogue desktop OS user access = ability to paste seed; use invites on shared machines
Supply chain Pin deps; review npm audit; CI from trusted runners

Crypto details

Item Algorithm / format
DHT identity Ed25519 via HyperDHT keyPair(seed)
MAC key HKDF-SHA256(seed, salt=peardata-hmac-v1, info=capability) → 32 bytes
Capability MAC HMAC-SHA256(macKey, canonical JSON payload)
Admin proof HMAC-SHA256(macKey, peardata-admin-v1 ‖ nonce ‖ peerId ‖ serverPk)
Invite envelope pd1. + base64url(JSON)

Implementation: shared/crypto-auth.js.

Canonical capability payload fields

v, role, peerId, exp, jti, iat — ordered JSON before MAC.

Operational security

Artifact Sensitivity Handling
.env Critical Never commit; backup offline
data/peer-policy.json High Contains roles & JTIs
data/audit.log Medium Peer activity metadata; readable via Logs/audit (admin)
Host journal (PEARDATA_JOURNAL) High May include secrets from other units; admin-only; on by default (disable with =0)
Docker socket (PEARDATA_DOCKER) High Container inventory/names/stats; installer adds peardata to docker when detected
data/retention.json Medium Retention / prune policy (admin-writable over P2P)
identity.json High for that user Per-machine client secret
Release tarballs Low Source only; no secrets

Incident response (seed leak)

  1. Stop accepting connections on the compromised key (shutdown / firewall).
  2. Generate new SERVER_SEED on a clean host (new public key).
  3. Deploy new server; do not reuse old seed.
  4. Re-issue invites to operators; notify clients of new public key.
  5. Review audit.log for abuse window.

Related

Reference in New Issue View Git Blame Copy Permalink