LSH — Encrypted Secrets Manager

The simplest way to sync .env files across all your machines.

lsh is an encrypted secrets manager that syncs your environment files across development machines with AES-256 encryption over the IPFS network. Secrets are encrypted locally, addressed by content (CID), and published under a deterministic IPNS name derived from your shared key — so a teammate with the same key can pull the latest version with no account or server.

Durability note: by default the encrypted content is pinned only on the machine that pushed it and served peer-to-peer. Another machine can pull as long as a node that holds the content is online and the IPNS record is still live. For "pull anywhere, anytime" durability, configure a remote pinning service (see Durable sync).

What's New in v3.5.x

• Focused on secrets - Removed the dormant pre-pivot platform code (SaaS multi-tenant, job/cron daemon, Supabase/Postgres persistence). LSH is now purely an encrypted .env sync tool over IPFS.
• Dependency modernization - Express 5, TypeScript 6, ESLint 10, Jest 30.
• Hardening - Bounded network calls (no hangs), command-injection fix in the Kubo installer, reliable npm publishing.

See Release Notes for full details.

Quick Start

# Install
npm install -g lsh-framework

# Interactive setup (recommended)
lsh init

# Or quick start
cd ~/your-project
lsh sync

That's it! Your secrets are now encrypted and synced.

Why LSH?

| Feature | LSH | dotenv-vault | 1Password | Doppler | |---------|-----|--------------|-----------|---------| | Free | Yes | Limited | No | No | | Self-Hosted | Yes | No | No | No | | Auto Rotation | Built-in | No | No | No | | IPFS Storage | Yes | No | No | No | | Setup Time | 2 min | 5 min | 10 min | 10 min |

Core Commands

# Setup
lsh init              # Interactive setup wizard
lsh key               # Generate encryption key

# Daily use
lsh push              # Upload encrypted .env to cloud
lsh pull              # Download .env from cloud
lsh sync              # Smart sync (auto push/pull)
lsh list              # List local secrets
lsh env               # List cloud environments

# Get/Set individual secrets
lsh get API_KEY       # Get a secret value
lsh set API_KEY xxx   # Set a secret value
printenv | lsh set    # Batch import from stdin

# Multi-environment
lsh push --env prod
lsh pull --env staging

How It Works

Machine A (push)                Local Kubo (IPFS) node          IPFS DHT / swarm
┌─────────────┐   AES-256       ┌─────────────────────┐         ┌──────────────────┐
│   .env      │ ───encrypt───►  │ ipfs add (pin local)│ ──────► │ IPNS record:     │
│  (secrets)  │                 │  → CID              │ publish │  name → CID      │
└─────────────┘                 └─────────────────────┘         │ (key-derived)    │
                                                                 └──────────────────┘
                                                                          │ resolve
Machine B (pull)                                                          ▼
┌─────────────┐   AES-256       ┌─────────────────────┐  fetch   ┌──────────────────┐
│   .env      │ ◄──decrypt────  │ ipfs cat <CID>      │ ◄─────── │ a node holding   │
│  (secrets)  │                 └─────────────────────┘  swarm   │ the block (A or  │
└─────────────┘                                                  │ a pinning svc)   │
                                                                 └──────────────────┘

1. Your .env is encrypted locally with AES-256 (the key never leaves the machine).
2. The ciphertext is added to your local Kubo (IPFS) daemon and pinned there, producing a content ID (CID).
3. The CID is published to IPNS under a name derived deterministically from LSH_SECRETS_KEY + repo + environment (HMAC-SHA256), so teammates need only the shared key.
4. Another machine derives the same IPNS name, resolves it to the latest CID over the network, and fetches the ciphertext over the IPFS swarm.
5. Decryption happens locally with the shared key.

What this means: the encrypted block is only guaranteed to exist where it was pushed. Cross-machine pull works while a node holding the block is online (the publisher, a peer that cached it, or — recommended — a remote pinning service).

Durable sync (remote pinning)

Out of the box, lsh sync is zero-config but not durable: the encrypted content lives only on the machine that pushed it. If that machine sleeps or goes offline before a teammate pulls — and no peer has cached the block — the pull will stall. lsh sync push warns you when no durable pin is configured.

To make secrets available "anytime, anywhere", point lsh at any IPFS remote pinning service (Pinata, Filebase, 4EVERLAND, web3.storage, an IPFS Cluster, etc.). lsh uses your local Kubo daemon's remote-pinning support — no extra dependency, and your encryption key never leaves your machine (the service only ever stores ciphertext).

# 1. Register a pinning service with your local Kubo daemon (one-time)
ipfs pin remote service add pinata https://api.pinata.cloud/psa <YOUR_JWT>

# 2. Tell lsh which service to use (only needed if more than one is configured)
export LSH_SECRETS_KEY=<your-key>
export LSH_PIN_SERVICE=pinata

# 3. Push — content is now pinned remotely and survives this machine going offline
lsh sync push --env dev
# → "Pinned: pinata (durable)"

If exactly one remote service is configured, lsh uses it automatically and LSH_PIN_SERVICE is optional.

Quickest: bundled pinner (just a token)

Skip the manual ipfs pin remote service add. Set LSH_PIN_TOKEN and lsh auto-registers a remote pinning service for you on first push — defaulting to 4EVERLAND (free 5GB, standard Pinning Service API):

# Get a free accessToken from the 4EVERLAND "4EVER Pin" page (https://4everland.org)
export LSH_PIN_TOKEN=<your-4everland-accessToken>
lsh push --env dev        # auto-registers "lsh-pin" → https://api.4everland.dev, then pins

Use a different provider by overriding the endpoint: export LSH_PIN_ENDPOINT=<psa-endpoint>. (Note: Pinata's pin-by-CID PSA is paid-only; 4EVERLAND and Filebase offer it free.)

Installation

Prerequisites

• Node.js 20.18.0+
• npm 10.0.0+

Install from npm

npm install -g lsh-framework
lsh --version

First-Time Setup

# Interactive setup (handles everything)
lsh init

# Or manual setup:
lsh key                        # Generate encryption key
echo "LSH_SECRETS_KEY=..." >> .env
lsh push                       # Push to cloud

Multi-Host Sync

The killer feature. Sync secrets across all your machines:

# Machine 1: Push secrets
cd ~/repos/my-project
lsh push

# Machine 2: Pull secrets (same encryption key)
cd ~/repos/my-project
lsh pull

# That's it - your .env is synced!

First-Time on New Machine

# 1. Install LSH
npm install -g lsh-framework

# 2. Install + start a local IPFS (Kubo) daemon (one-time)
lsh sync init

# 3. Add your encryption key (shared with your other machines / team)
echo "LSH_SECRETS_KEY=your-shared-key" > .env

# 4. Pull secrets (resolves the latest version via IPNS)
lsh sync pull

Requires a local IPFS (Kubo) daemon — lsh sync init installs and starts one. The pushing machine must be online (or a pinning service configured) for others to fetch the content.

Multi-Environment Support

# Development
lsh push --env dev

# Staging
lsh push --file .env.staging --env staging

# Production
lsh push --file .env.prod --env prod

# Pull any environment
lsh pull --env prod

Team Collaboration

Setup (Team Lead):

lsh key                    # Generate team key
lsh push --env prod        # Push team secrets
# Share LSH_SECRETS_KEY via 1Password/LastPass

Team Members:

# Get key from 1Password
echo "LSH_SECRETS_KEY=shared-key" > .env
lsh pull --env prod
# Done!

Automatic Secret Rotation

Schedule rotation with any external scheduler (system cron, a CI job, etc.) that runs your rotation script and then pushes the updated secrets:

# Example: monthly rotation via crontab — `crontab -e`
0 0 1 * * cd /path/to/project && ./scripts/rotate.sh && lsh push

Or as a scheduled CI job (GitHub Actions, etc.) that runs the script and lsh push. LSH focuses on encrypting and syncing the .env; the rotation policy/schedule is yours.

Export Formats

Export secrets in multiple formats:

lsh list --format json    # JSON
lsh list --format yaml    # YAML
lsh list --format toml    # TOML
lsh list --format export  # Shell export statements

# Load into current shell
eval "$(lsh list --format export)"

Security

• AES-256 encryption for all secrets (the key never leaves your machine)
• Content-addressed storage - tamper-proof IPFS CIDs
• Zero-knowledge - the IPFS network (and any pinning service) only ever sees ciphertext
• Local-first - works offline with cached secrets

Best Practices

DO:

• Store LSH_SECRETS_KEY in shell profile (~/.zshrc)
• Share keys via password manager (1Password, etc.)
• Use different keys per project/team
• Rotate keys periodically

DON'T:

• Commit LSH_SECRETS_KEY to git
• Share keys in plain text (Slack, email)
• Store production secrets in dev environment

Troubleshooting

"No secrets found for environment"

# Check what environments exist
lsh env

# Push if missing
lsh push --env dev

"Decryption failed"

Wrong encryption key. Make sure LSH_SECRETS_KEY matches.

# Check current key
cat .env | grep LSH_SECRETS_KEY

# If lost, generate new key and re-push
lsh key
lsh push --force

Pull hangs or "Could not resolve secrets from network"

The IPNS name resolved but no online node is serving the content (or the IPNS record expired). Either:

# On the machine that pushed: make sure its daemon is running, then re-push
lsh sync status
lsh sync push --env dev

# Better: configure a remote pinning service so content stays available
# even when the pushing machine is offline (see "Durable sync" below)

"IPFS daemon not running"

lsh sync init     # install + start a local Kubo daemon
lsh sync status   # verify it is up

# If secrets were pushed before, pull should auto-recover
lsh pull

# If truly no secrets exist, push first
lsh push

Documentation

• Secrets Guide - Complete secrets management guide
• Smart Sync Guide - One-command sync guide
• Quick Reference - Daily use cheatsheet
• Installation - Detailed installation
• Developer Guide - Contributing to LSH

Configuration

Environment Variables

# Required
LSH_SECRETS_KEY=<your-encryption-key>

# Optional - name of a kubo remote pinning service for durable sync
# (configure once with: ipfs pin remote service add <name> <endpoint> <key>)
LSH_PIN_SERVICE=<service-name>

# Optional - pointer discovery backends, comma-separated in priority order.
# Default 'w3name,ipns': durable w3name (signed IPNS via name.web3.storage, no
# account, no DHT TTL) with IPNS-over-DHT fallback. Set 'ipns' for DHT-only.
LSH_DISCOVERY=w3name,ipns

# Optional - bundled pinner: with a token set, lsh auto-registers a remote pin
# service so pushed content is durable. Endpoint defaults to 4EVERLAND (free 5GB).
LSH_PIN_TOKEN=<psa-access-token>
LSH_PIN_ENDPOINT=https://api.4everland.dev   # override for another PSA provider

Configuration Files

~/.config/lsh/lshrc     # LSH configuration
~/.lsh/secrets-cache/   # Encrypted secrets cache
~/.lsh/secrets-metadata.json  # Metadata index

Contributing

git clone https://github.com/gwicho38/lsh.git
cd lsh
npm install
npm run build
npm test
npm link

See CLAUDE.md for development guidelines.

License

MIT

Support

• Issues: https://github.com/gwicho38/lsh/issues
• Discussions: https://github.com/gwicho38/lsh/discussions

Stop copying .env files. Start syncing.

npm install -g lsh-framework
lsh init