@reegaviljoen/eldlock 0.1.0

package/README.md

@@ -0,0 +1,285 @@
+# Eldlock
+
+Eldlock is a local-first secret broker for developer machines.
+
+It keeps developer secrets out of long-lived plaintext files, shell profiles,
+and extractable private-key paths while preserving the interfaces developers
+already use: `SSH_AUTH_SOCK`, shells, env vars, `.env` workflows, process
+launchers, and local credential helpers.
+
+Eldlock is not a hosted secrets manager. The vault lives on your machine,
+secrets are encrypted on your machine, and normal secret release does not need
+the internet.
+
+```text
+eldlock CLI / TUI
+        |
+        | local Unix socket
+        v
+eldlock-server local daemon
+        |
+        v
+local encrypted vault
+```
+
+## Install
+
+Eldlock currently builds from source on the target machine. The installer uses
+vendored Go and npm dependencies after it downloads the repository archive.
+
+Install prerequisites first:
+
+```bash
+# macOS
+brew install go node pkg-config keys-pub/tap/libfido2
+curl -fsSL https://bun.sh/install | bash
+
+# Ubuntu / Debian
+sudo apt update
+sudo apt install golang nodejs npm pkg-config libfido2-dev
+curl -fsSL https://bun.sh/install | bash
+
+# Red Hat / Fedora
+sudo dnf install golang nodejs npm pkgconf-pkg-config libfido2-devel
+curl -fsSL https://bun.sh/install | bash
+
+# Arch Linux
+sudo pacman -Syu go nodejs npm pkgconf libfido2
+curl -fsSL https://bun.sh/install | bash
+```
+
+Then run the installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/reeganviljoen/eldlock/main/install.sh | bash
+```
+
+Or install from npm after the package is published:
+
+```bash
+npm install -g @reegaviljoen/eldlock
+```
+
+If the repository is private, pass a GitHub token that can read it:
+
+```bash
+export GITHUB_TOKEN="github_pat_or_ghp_token_with_repo_read_access"
+curl -fsSL -H "Authorization: Bearer $GITHUB_TOKEN" \
+  https://raw.githubusercontent.com/reeganviljoen/eldlock/main/install.sh | bash
+```
+
+The default install writes:
+
+- `~/.local/bin/eldlock`
+- `~/.local/share/eldlock/bin/eldlock-server`
+- `~/.local/share/eldlock/lib/eldlock-cli`
+
+Add the command directory to your shell path if needed:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+Initialize and check the daemon:
+
+```bash
+eldlock start
+eldlock init
+eldlock status
+```
+
+`eldlock` uses `~/.eldlock` as its default state directory. Override it with
+`ELDLOCK_STATE_DIR` when you want isolated state for testing.
+
+## Use
+
+Store and read a secret:
+
+```bash
+eldlock secret add personal/openai/api_key=sk-test
+eldlock secret list
+eldlock secret read personal/openai/api_key
+eldlock secret read personal/openai/api_key --plain
+```
+
+Import env-style secrets and launch a process with injected env vars:
+
+```bash
+eldlock import .env
+eldlock exec -- rails s
+eldlock exec -- 'echo "$NODE_AUTH_TOKEN"'
+eldlock shell --vault eldlock_secrets
+```
+
+The enclosed command runs through your current shell and receives normal env
+vars. The difference is that the secret is released just in time by the daemon
+instead of living indefinitely in a parent shell or plaintext project file.
+Use `eldlock shell` when you want an interactive copy of your current shell
+with the vault env already present. Eldlock unlocks the vault through the
+daemon first, prints a success line, then starts a clean interactive instance
+of your shell from the CLI process with an `(eldlock:<vault>)` prompt marker.
+Type `exit` to leave it.
+
+Manual local test builds can use a stub passkey provider:
+
+```bash
+export ELDLOCK_STUB_PASSKEY="local-test-passkey-change-me"
+npm run build:dev
+source .eldlock/dev-env.sh
+eldlock init
+eldlock start
+```
+
+For YubiKey Bio / FIDO2 testing, install `libfido2`, then build and run with:
+
+```bash
+export GOFLAGS="-tags=fido2"
+export ELDLOCK_FIDO2_UV=true
+```
+
+If your key requires a PIN, the CLI prompts after the daemon reports that the
+PIN is required.
+
+## Philosophy
+
+Eldlock's hard product principle:
+
+> If adoption requires rewriting the app, changing every deploy process, or
+> teaching every tool about Eldlock, the design has failed.
+
+The daemon is the trust boundary. The CLI and TUI are frontends only: they may
+request actions, show state, and launch flows, but security-critical behavior
+belongs in `eldlock-server`.
+
+That means policy decisions, approval state, caller inspection, encryption,
+decryption, SSH signing, env injection, and audit logging must be enforced
+daemon-side. A raw local socket client should not be able to bypass the rules by
+skipping the CLI.
+
+For integrations, Eldlock proxies the smallest useful operation:
+
+| Secret type | Eldlock integration point |
+| --- | --- |
+| SSH keys | OpenSSH-compatible agent socket via `SSH_AUTH_SOCK` |
+| Env vars | `eldlock exec -- <command>` |
+| `.env` compatibility | ephemeral materialization first; stronger virtual-file approaches later |
+| API tokens used by CLIs | wrapper, credential helper, plugin, or env injection |
+
+Env vars cannot be intercepted after a process has already started. Eldlock can
+launch a process with the required env vars, but it cannot make arbitrary env
+reads magically lazy.
+
+## Threat Model
+
+Eldlock helps against passive or opportunistic secret theft:
+
+- dependency install scripts scraping `.env`, `~/.ssh`, and common token files
+- local token grabbers scanning developer directories
+- accidental commits of `.env` files
+- stolen laptops where the attacker only has disk access
+- silent SSH private-key exfiltration
+- tools that need standard env vars or normal OpenSSH agent behavior
+
+Eldlock does not fully protect against:
+
+- malware running as your user during an approved secret release
+- malware replacing shell hooks or common binaries like `git`, `ssh`, or `npm`
+- malware reading child process memory
+- malware scraping injected env vars after `eldlock exec`
+- malware using the SSH agent during an approval TTL window
+- root-level compromise
+
+Useful claim:
+
+> Eldlock prevents secrets from sitting around passively stealable and requires
+> local policy plus user presence before use.
+
+Avoid claims like "impossible to steal" or "fully secure on a compromised
+machine."
+
+## Develop
+
+Repository layout:
+
+```text
+eldlock-server/  Go daemon and security boundary
+eldlock-cli/     TypeScript CLI/TUI frontend
+docs/            architecture and threat model notes
+examples/        example project configuration
+```
+
+Common commands:
+
+```bash
+# Build production artifacts into ./dist/eldlock
+npm run build:prod
+
+# Install eldlock for the whole machine at ~/.local/bin/eldlock
+npm run install:local
+
+# Local-only release build; requires an enrolled release YubiKey
+npm run release
+
+# First-time release YubiKey enrollment
+npm run release -- --enroll
+
+# Dry-run npm publish through eldlock_secrets/NODE_AUTH_TOKEN
+npm run release -- --publish-dry-run
+
+# Publish to npm through eldlock_secrets/NODE_AUTH_TOKEN
+npm run release -- --publish
+
+# Choose production install locations
+node scripts/build-production.mjs \
+  --install-dir "$HOME/.local/share/eldlock" \
+  --bin-dir "$HOME/.local/bin"
+
+# Server checks
+cd eldlock-server
+go run ./cmd/eldlock-server version
+go test -mod=vendor ./...
+
+# CLI checks
+cd eldlock-cli
+npm run typecheck
+npm run build
+```
+
+Vendored dependencies keep normal local development off live package registries:
+
+- Go server dependencies live in `eldlock-server/vendor/`; server builds use
+  `-mod=vendor`.
+- The patched `go-libfido2` binding lives in `eldlock-server/internal/libfido2/`.
+- CLI npm tarballs live in `eldlock-cli/vendor/npm/`.
+- `eldlock-cli/.npmrc` keeps npm offline for this package.
+
+Npm releases are intentionally local-only. The package publishes as
+`@reegaviljoen/eldlock` because npm rejected the unscoped `eldlock` name as too
+similar to an existing package. Before publishing, install the
+machine-wide command with `npm run install:local`, enroll the release YubiKey
+with `npm run release -- --enroll`, then create an Eldlock vault named
+`eldlock_secrets` containing the standard npm env secret `NODE_AUTH_TOKEN`.
+The release script builds and verifies Eldlock locally, authenticates with the
+release YubiKey, then runs normal `npm publish --access public` through
+`eldlock exec --vault eldlock_secrets`. Use an npm automation token, or a
+granular token with package publish access and 2FA bypass enabled, as
+`NODE_AUTH_TOKEN`.
+
+To verify env injection without printing the token, run:
+
+```bash
+eldlock exec --vault eldlock_secrets -- 'test -n "$NODE_AUTH_TOKEN" && echo NODE_AUTH_TOKEN is set'
+```
+
+If the secret is not already set in your outer shell, quote shell variables in
+one command string, such as `eldlock exec -- 'echo "$NODE_AUTH_TOKEN"'`.
+Unquoted variables are expanded by your outer shell before Eldlock starts.
+
+Storage note: the 0.1 preview uses an encrypted JSON envelope. Eldlock should
+avoid SQL/SQLite for vault storage so SQL injection is not part of the storage
+threat model.
+
+The deeper docs are intentionally more detailed:
+
+- [Architecture](docs/architecture.md)
+- [Threat model](docs/threat-model.md)

package/bin/eldlock

@@ -0,0 +1,11 @@
+#!/usr/bin/env sh
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+if [ "${1:-}" = "" ] || [ "${1:-}" = "tui" ]; then
+  if [ -n "${ELDLOCK_TUI_RUNTIME:-}" ]; then
+    exec "$ELDLOCK_TUI_RUNTIME" "$SCRIPT_DIR/../eldlock-cli/dist/main.js" "$@"
+  fi
+  if command -v bun >/dev/null 2>&1; then
+    exec bun "$SCRIPT_DIR/../eldlock-cli/dist/main.js" "$@"
+  fi
+fi
+exec node "$SCRIPT_DIR/../eldlock-cli/dist/main.js" "$@"

package/docs/architecture.md

@@ -0,0 +1,164 @@
+# Eldlock Architecture
+
+Eldlock is a local daemon plus a bundled CLI/TUI frontend.
+
+The daemon owns all security-sensitive behavior:
+
+- secret storage
+- encryption and decryption
+- YubiKey unlock or wrapping
+- policy decisions
+- approvals
+- SSH signing
+- env injection
+- audit logging
+
+The CLI/TUI is intentionally thin. It asks the daemon to do things; it does not decide whether those things are allowed.
+
+## Components
+
+```text
+                    ┌────────────────────┐
+                    │ eldlock-cli / TUI   │
+                    │ frontend only       │
+                    └─────────┬──────────┘
+                              │
+                              │ Unix socket API
+                              v
+┌──────────────────────────────────────────────────────┐
+│ eldlock-server local daemon                           │
+│                                                      │
+│  ┌──────────────┐  ┌──────────────┐  ┌─────────────┐ │
+│  │ policy       │  │ approval     │  │ audit log   │ │
+│  └──────┬───────┘  └──────┬───────┘  └──────┬──────┘ │
+│         │                 │                 │        │
+│  ┌──────v───────┐  ┌──────v───────┐  ┌──────v──────┐ │
+│  │ crypto       │  │ YubiKey      │  │ caller ID   │ │
+│  └──────┬───────┘  └──────────────┘  └─────────────┘ │
+│         │                                            │
+│  ┌──────v─────────────────────────────────────────┐  │
+│  │ local encrypted vault                           │  │
+│  └────────────────────────────────────────────────┘  │
+│                                                      │
+│  Interfaces: SSH agent, exec launcher, shell hooks   │
+└──────────────────────────────────────────────────────┘
+```
+
+## Local API
+
+The daemon should listen on a local Unix domain socket, for example:
+
+```text
+$XDG_RUNTIME_DIR/eldlock/daemon.sock
+```
+
+or on macOS:
+
+```text
+$HOME/Library/Application Support/Eldlock/daemon.sock
+```
+
+The local API should never be treated as trusted just because it is local. The daemon must inspect the peer process and apply policy before releasing secrets or signing anything.
+
+Important caller signals:
+
+- UID/GID
+- PID
+- executable path
+- command line
+- cwd
+- parent process
+- attached TTY/session
+- requested secret
+- requested action
+- approval TTL state
+
+On Linux, the daemon can use Unix socket peer credentials such as `SO_PEERCRED`. macOS has different peer credential APIs and needs its own implementation path.
+
+## SSH Agent
+
+Eldlock should expose an OpenSSH-compatible agent socket:
+
+```bash
+export SSH_AUTH_SOCK="$HOME/.eldlock/ssh-agent.sock"
+```
+
+Normal tools should keep working:
+
+```bash
+ssh server
+git clone git@github.com:org/repo.git
+git pull
+```
+
+The private key should not be exposed to the SSH client. The client asks the agent to sign a challenge. Eldlock checks policy, requires approval when needed, decrypts the key in memory, signs, and clears plaintext material as quickly as possible.
+
+## Env Injection
+
+Env vars cannot be lazily fetched after a process starts. Eldlock should launch the process with the required env vars:
+
+```bash
+eldlock exec -- bin/dev
+```
+
+Later, shell hooks can make this feel natural:
+
+```bash
+bin/dev
+```
+
+The shell hook can detect project config and route the command through `eldlock exec`.
+
+## Storage
+
+The 0.1 preview uses an encrypted JSON envelope stored on the local machine.
+The envelope uses established primitives through the Go implementation, with
+key material requested from the configured passkey provider for vault create,
+read, add, list, and remove operations.
+
+Eldlock should avoid SQL/SQLite for vault storage so SQL injection is not part
+of the storage threat model. Do not invent custom crypto.
+
+Conceptual record model:
+
+```text
+secrets
+  id
+  name
+  type
+  encrypted_blob
+  metadata_json
+  created_at
+  updated_at
+
+policies
+  id
+  secret_id
+  allowed_cwd
+  allowed_process
+  approval_mode
+  ttl_seconds
+  require_touch
+
+audit_events
+  id
+  event_type
+  secret_id
+  caller_pid
+  caller_exe
+  caller_cwd
+  decision
+  created_at
+```
+
+Potential encryption model:
+
+```text
+YubiKey-backed wrapping provider
+        ↓ unwraps
+local master key
+        ↓ decrypts
+per-secret encryption keys or secret blobs
+```
+
+The YubiKey must be part of unwrapping key material, not just a cosmetic approval check.

package/docs/threat-model.md

@@ -0,0 +1,47 @@
+# Threat Model
+
+Eldlock is not a magic shield for compromised machines. It is designed to reduce passive secret theft and make secret use require local policy plus user presence.
+
+## Protects Against
+
+Eldlock should materially help against:
+
+- dependency install scripts scraping `~/.ssh`, `.env`, and common token files
+- local token grabbers scanning developer directories
+- accidental commits of `.env` files
+- stolen laptops where the attacker only has disk access
+- silent theft of SSH private keys
+- tools that need standard env vars or normal OpenSSH agent behavior
+
+## Does Not Fully Protect Against
+
+Eldlock cannot fully protect against:
+
+- malware running as the user during an approved secret release
+- malware modifying shell hooks
+- malware replacing binaries like `git`, `ssh`, `rails`, or `npm`
+- malware reading child process memory
+- malware scraping environment variables after `eldlock exec`
+- malware using the SSH agent during an approval TTL window
+- root-level compromise
+
+## Design Implication
+
+The daemon should assume local callers may be hostile. A command like this must not be automatically safe:
+
+```bash
+eldlock secret read personal/openai/api_key
+```
+
+Every request should go through policy checks, caller inspection, approval, and audit logging.
+
+## Useful Claim
+
+Good:
+
+> Eldlock prevents secrets from sitting around passively stealable and requires local policy plus user presence before use.
+
+Bad:
+
+> Eldlock makes secrets impossible to steal.
+

package/eldlock-cli/README.md

@@ -0,0 +1,56 @@
+# eldlock-cli
+
+`eldlock-cli` is the bundled command-line and TUI frontend for Eldlock.
+
+It is intentionally not the trust boundary. It talks to the local `eldlock-server` daemon over a Unix socket.
+
+Security-critical logic belongs in `eldlock-server`, including:
+
+- policy decisions
+- encryption and decryption
+- YubiKey unlock
+- SSH signing
+- env injection
+- audit logging
+
+## TUI Direction
+
+The intended TUI direction is OpenTUI-style: a rich terminal frontend similar in feel to OpenCode.
+
+The TUI should render state and collect user intent. The daemon decides what is allowed.
+
+## Prototype Secret Commands
+
+Initialize the vault:
+
+```bash
+export ELDLOCK_STUB_PASSKEY="local-test-passkey-change-me"
+npm run dev -- init
+```
+
+Start the daemon:
+
+```bash
+export ELDLOCK_SERVER_PATH="../eldlock-server/bin/eldlock-server-dev"
+npm run dev -- start
+npm run dev -- status
+```
+
+The public CLI does not require Go or mise at runtime. `eldlock start` launches the binary at `ELDLOCK_SERVER_PATH`, or finds `eldlock-server` on `PATH`.
+
+In another terminal, add and read an env secret:
+
+```bash
+npm run dev -- secret add demo/API_KEY=test-secret
+npm run dev -- secret read demo/API_KEY
+npm run dev -- secret read demo/API_KEY --plain
+npm run dev -- secret remove demo/API_KEY
+```
+
+Stop the daemon:
+
+```bash
+npm run dev -- stop
+```
+
+The CLI sends requests to the daemon over the Unix socket. Clipboard writes happen in the daemon, not in TypeScript.

package/eldlock-cli/bin/eldlock

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+exec node "$SCRIPT_DIR/../dist/main.js" "$@"