@veda-hq/kavach 0.0.0-stage → 0.5.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Veda Authors
+
+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.

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# @veda-hq/kavach
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+कवच, armour. Guards for coding agents: each tool call an agent makes is
+judged before it runs. Part of [Veda](https://github.com/veda-hq/veda).
+
+## v0.5: three guards and a rule-check engine
+
+| Guard | Refuses | Entry point |
+| --- | --- | --- |
+| Worktree boundary | Any write outside the agent's own git worktree: a Bash command, an Edit or a Write; and, while a push runs, any write into it (below). Read-only commands pass from any checkout. | `python3 python/kavach/worktree_guard.py` |
+| Command guard | Git-hook bypasses (`--no-verify`, `core.hooksPath`…), history-destroying pushes, and the project's own command rules (settings below). | `python3 python/kavach/command_guard.py` |
+| Rule checks | The project's own checks, written in TypeScript, refusing or warning with the rule's reason. | `kavach-rule-checks` (`dist/rule-checks/cli.js`) |
+
+The two Python guards read one Claude Code `PreToolUse` event on stdin. Exit
+0 allows; exit 2 refuses, with `BLOCKED: <reason>` on stderr. Every other end
+(a crash, a missing module, unreadable settings) refuses: Claude Code lets a
+hook's exit 1 through, so a guard that fails must not allow. The rule-check
+engine is the opposite by design: a check that crashes lets the call go
+ahead with a warning, so a broken rule never stops every session.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "Bash|Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [{ "type": "command", "command": "python3 node_modules/@veda-hq/kavach/python/kavach/worktree_guard.py" }] },
+      { "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": "python3 node_modules/@veda-hq/kavach/python/kavach/command_guard.py" }] }
+    ]
+  }
+}
+```
+
+Python 3.12 or later, standard library only. Node 24 or later. MIT.
+
+## What "read-only" means
+
+A Bash command passes from any checkout when the worktree boundary can prove
+every part of it writes nothing: pipes, `sort`, `uniq`, `awk` and `sed`
+without writing options or programs, input redirection, `2>/dev/null`,
+`tee /dev/null`, `$(...)` and `<(...)` whose bodies are themselves read-only,
+`for` loops over literal words, `xargs` running a read-only command, `[`,
+`test`, read subcommands of `git` and `gh` (`gh api` with GET only). When it
+cannot prove a command, it treats it as writing, and from outside an owned
+worktree that refuses. An expansion that could become an option (`git log
+$X`, where `X=--output=/elsewhere`) leaves the command unproven.
+
+`corpus/corpus.json` is the adversarial test set: commands that write outside
+the worktree, bypass hooks or force-push, each executed in real bash to prove
+it does what its row says, and near-miss commands that must pass. Each guard
+must refuse every attack row and pass every near-miss.
+
+## Settings
+
+`KAVACH_CONFIG` names a JSON file; unset, every project rule is off. A file
+that cannot be read, is not JSON, or has an unknown key refuses every call.
+
+```json
+{
+  "worktree": {
+    "trustedCommands": [
+      { "script": "scripts/worktree.py", "pattern": "python3 scripts/worktree\\.py (?:status|retire --pr [1-9][0-9]*)" }
+    ]
+  },
+  "command": {
+    "protectedVariables": ["AGENT_REMOTE"],
+    "protectedVariablesReason": "it marks a hosted session; leave it as the session set it",
+    "pairedChanges": [
+      { "changes": "schema.sql", "requires": "changesets/", "reason": "a schema change needs its changeset" }
+    ]
+  }
+}
+```
+
+- `trustedCommands`: a script in the repository that may run from the agent's
+  own worktree although its writes cannot be read off its command line. The
+  pattern must match the whole command; trust only command lines of plain
+  words (a whole line with any shell metacharacter is never trusted by its
+  pattern alone).
+- `protectedVariables`: environment variables a command may not assign, declare or
+  export.
+- `pairedChanges`: a commit that may record a path ending in `changes` must
+  also certainly record a path containing `requires`. With no entries the
+  rule is off, and a commit whose repository the guard cannot resolve is no
+  longer refused for that reason alone (`--no-verify` and the rest still are).
+  Keep a CI check behind it: the guard reads one command line, not the files
+  other programs change.
+
+## While a push runs
+
+A push's checks read the worktree it was started from, and an edit made
+while they run either fails the push at its end or leaves it checking what
+was not pushed. So while a push runs, the worktree boundary refuses writes
+into that worktree: any Bash command it cannot prove read-only, run there
+(a trusted command included), and any Edit, Write or NotebookEdit of a path
+git does not ignore. Reads still run, and the file tools can still write
+files git ignores (drafts, scratch); a Bash command that writes one is still
+refused. The refusal names the push's pid and start. Commands that only reach
+the network, such as `gh pr comment`, wait too: the guard cannot tell what an
+unproven command writes.
+
+It knows a push is running from the marker the project's pre-push hook
+writes. Write it when a real push starts and clear it on every exit:
+
+```sh
+kavach-rule-checks push-marker write "$(git rev-parse --absolute-git-dir)" "$$"
+trap 'kavach-rule-checks push-marker clear "$(git rev-parse --absolute-git-dir)" "$$"' EXIT
+```
+
+Each push gets its own marker, `kavach-push-in-progress.<pid>.json` in the
+worktree's own git folder, naming its pid and start. A marker whose pid has
+ended or now belongs to a later process blocks nothing, so a killed push
+leaves no lock behind, and a push in another worktree never blocks this one.
+Without the marker, nothing here changes.
+
+## Refusal log
+
+Each refusal of the two Python guards appends a row (time, guard, tool, first
+line of the reason, start of the command) to
+`<git common dir>/kavach/refusals.jsonl`. It is best effort and never changes
+a verdict; `KAVACH_REFUSAL_LOG_OFF=1` turns it off. The rule-check engine
+keeps its own fire log (`--fires-dir`).
+
+## Rule checks
+
+```sh
+kavach-rule-checks --checks rules/checks.ts --registry rules/registry.json   # the hook
+kavach-rule-checks count --registry rules/registry.json --json               # rules with no enforcer
+kavach-rule-checks latency --rounds 5                                        # time the Bash hooks
+```
+
+A checks module exports `CHECKS`, a list of `Check` (`@veda-hq/kavach/rule-checks`):
+an id, the events and tools it applies to, and a function returning a
+refusal, a warning or nothing. A Bash command passes one named check when it
+ends with `# rule-pass <id>: <reason>`; the pass is logged.