From 3407f135689760cb0f9dc42dbf4f3f39e952fc1b Mon Sep 17 00:00:00 2001 From: David Ibia Date: Mon, 12 Jan 2026 13:30:57 +0100 Subject: [PATCH] docs: add README and MIT license --- LICENSE | 21 ++++++++ README.md | 154 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 175 insertions(+) create mode 100644 LICENSE create mode 100644 README.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..2c4c63d --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 BoxPositron + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..27e20fa --- /dev/null +++ b/README.md @@ -0,0 +1,154 @@ +# envsitter-guard + +OpenCode plugin that prevents agents/tools from reading or editing sensitive `.env*` files, while still allowing safe inspection via EnvSitter (keys + deterministic fingerprints; never values). + +## Why + +Accidentally printing `.env` contents is one of the easiest ways for an agentic workflow to leak secrets into: + +- chat transcripts +- logs/tool output +- commits/patches +- screenshots / shared sessions + +`envsitter-guard` blocks the risky operations and points users to safe alternatives. + +## What it does + +This plugin does two things: + +1. Adds safe tools: + - `envsitter_keys`: list keys in a dotenv file (no values) + - `envsitter_fingerprint`: hash/fingerprint one key’s value (no value) +2. Blocks sensitive file access via OpenCode tool hooks: + - blocks `read` of sensitive `.env*` paths + - blocks `edit` / `write` / `patch` of sensitive `.env*` paths + - blocks access to `.envsitter/pepper` + +`.env.example` is explicitly allowed. + +## Tools + +### `envsitter_keys` + +Lists keys in a dotenv file. + +- Input: `{ "filePath"?: string }` (defaults to `.env`) +- Output: JSON `{ file, keys }` + +Example (inside OpenCode): + +```json +{ "tool": "envsitter_keys", "args": { "filePath": ".env" } } +``` + +### `envsitter_fingerprint` + +Computes a deterministic fingerprint of a single key. + +- Input: `{ "filePath"?: string, "key": string }` (filePath defaults to `.env`) +- Output: JSON `{ file, key, result }` + +Example (inside OpenCode): + +```json +{ "tool": "envsitter_fingerprint", "args": { "filePath": ".env", "key": "DATABASE_URL" } } +``` + +## Install & enable in OpenCode + +OpenCode supports loading plugins either from local files or from npm. + +Reference docs: +- https://opencode.ai/docs/plugins/ +- https://opencode.ai/docs/config/#plugins + +### Option A (recommended): load from npm via `opencode.json` + +Add the plugin package to your OpenCode config. + +`opencode.json`: + +```json +{ + "$schema": "https://opencode.ai/config.json", + "plugin": ["envsitter-guard@latest"] +} +``` + +Notes: +- OpenCode installs npm plugins automatically using Bun at startup. +- If you prefer, you can omit `@latest` and you’ll still get the latest by default: `"plugin": ["envsitter-guard"]`. + +### Option B: local plugin file (project-level) + +If you want a local plugin file in-repo (or need local overrides), create `.opencode/plugin/envsitter-guard.ts`: + +```ts +import EnvSitterGuard from "envsitter-guard"; + +export default EnvSitterGuard; +export { EnvSitterGuard } from "envsitter-guard"; +``` + +Then create `.opencode/package.json` with the dependency so OpenCode can install it: + +```json +{ + "dependencies": { + "envsitter-guard": "latest" + } +} +``` + +Restart OpenCode; files in `.opencode/plugin/` are loaded automatically. + +### Option C: global plugin file + +Place a plugin file in `~/.config/opencode/plugin/` if you want it enabled for all projects. + +(You can use the same contents as Option B.) + +## Behavior details + +### What paths are considered sensitive? + +- Sensitive: `.env`, `.env.local`, `.env.production`, etc. (`.env*`) +- Allowed: `.env.example` +- Always blocked: `.envsitter/pepper` + +### What operations are blocked? + +- `read` on sensitive `.env*` paths +- `edit` / `write` / `patch` on sensitive `.env*` paths + +When blocked, the plugin shows a throttled warning toast and suggests using EnvSitter instead. + +## Development + +### Install + +```bash +npm ci +``` + +### Typecheck + +```bash +npm run typecheck +``` + +There are currently no lint or test scripts in this repo. + +## Publishing notes (npm) + +You said you plan to publish as `envsitter-guard@0.0.1`, but want installs to always use latest. + +- Publishing a version like `0.0.1` is normal. +- For end users, recommend installing/loading `envsitter-guard@latest` (or just `envsitter-guard`) so they get the newest published version. + +Before publishing, double-check that the package entrypoint is compatible with how OpenCode loads npm plugins (OpenCode installs via Bun and loads the package as a module). If you change packaging (build output, exports), keep `.opencode/plugin/envsitter-guard.ts` as a thin re-export only. + +## License + +MIT. See `LICENSE`.