Skip to content

Commit 9bbb35d

Browse files
committed
v1.4: agent identity signing, structured error handling, timestamped-signature transport
1 parent 1801766 commit 9bbb35d

8 files changed

Lines changed: 471 additions & 55 deletions

File tree

‎README.md‎

Lines changed: 25 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ Works in Hermes CLI, Telegram, and Hermes Desktop.
3232
| `/code-search <repo> "query"` | Hybrid semantic + literal search |
3333
| `/code-context <repo> "query"` | Retrieve a compact context pack |
3434
| `/code-ask <repo> "question"` | Retrieve + answer with citations (add an optional `"query"` before the question to steer retrieval) |
35-
| `/code-history <repo> "question"` | Search indexed git commit history (SourceVault v1.8+; index every commit via the dashboard's Full git history setting) |
35+
| `/code-history <repo> "question"` | Search indexed git commit history (requires the SourceVault history index; enable *Full git history* in the dashboard to index every commit) |
3636

3737
Telegram uses underscore forms (`/code_ask`, …).
3838

@@ -75,8 +75,8 @@ If you have the SourceVault server repo, use its installer instead — it also
7575
configures Hermes and validates the env:
7676

7777
```bash
78-
cd ~/Development/sourcevault
79-
./scripts/install-hermes-integration.sh --configure-sourcevault --restart-hermes
78+
cd ~/DevOps/sourcevault
79+
./scripts/setup/install-hermes-integration.sh --configure-sourcevault --restart-hermes
8080
```
8181

8282
Enable in `~/.hermes/config.yaml`:
@@ -93,8 +93,10 @@ platform_toolsets:
9393
- sourcevault_code_tools
9494
```
9595
96-
Point the gateway at your SourceVault instance
97-
(`~/.config/systemd/user/hermes-gateway.env` or equivalent):
96+
Point the gateway at your SourceVault instance. On Linux that is
97+
`~/.config/systemd/user/hermes-gateway.env`; on macOS put the same variables in
98+
the environment of whatever launches the gateway (a launchd plist's
99+
`EnvironmentVariables`, or the shell profile that starts Hermes Desktop):
98100

99101
```env
100102
CODE_SEARCH_URL=http://127.0.0.1:9000/api/search-codebase
@@ -103,8 +105,16 @@ CODE_HISTORY_URL=http://127.0.0.1:9000/api/history-search
103105
CODE_SEARCH_HMAC_SECRET=<same value as the SourceVault server>
104106
```
105107

106-
Restart Hermes (`systemctl --user restart hermes-gateway` or relaunch the
107-
Desktop app) and run `/code-status`.
108+
To attribute requests to a named agent in SourceVault's audit chain (v1.47+),
109+
mint a token with `sourcevault agent mint <name> --surfaces http` and add both:
110+
111+
```env
112+
SOURCEVAULT_AGENT_NAME=<agent name>
113+
SOURCEVAULT_AGENT_TOKEN=<sva_... token printed at mint time>
114+
```
115+
116+
Restart Hermes (`systemctl --user restart hermes-gateway` on Linux, or
117+
relaunch the Desktop app on macOS) and run `/code-status`.
108118

109119
## Try it
110120

@@ -150,14 +160,20 @@ Usage notes:
150160
|---|---|---|
151161
| `CODE_SEARCH_URL` | `http://127.0.0.1:9000/api/search-codebase` | SourceVault search endpoint |
152162
| `CODE_READ_FILE_URL` | `http://127.0.0.1:9000/api/read-file` | SourceVault file-read endpoint |
153-
| `CODE_HISTORY_URL` | `http://127.0.0.1:9000/api/history-search` | SourceVault history-search endpoint (v1.8+) |
154-
| `CODE_SEARCH_HMAC_SECRET` | — | Request-signing secret (required) |
163+
| `CODE_HISTORY_URL` | `http://127.0.0.1:9000/api/history-search` | SourceVault history-search endpoint |
164+
| `CODE_SEARCH_HMAC_SECRET` | — | Shared request-signing secret (required unless an agent identity is set) |
165+
| `SOURCEVAULT_AGENT_NAME` | — | Named agent identity, sent as `X-Code-Search-Signature-Agent` (mint with `sourcevault agent mint <name> --surfaces http`) |
166+
| `SOURCEVAULT_AGENT_TOKEN` | — | The agent's plaintext token (`sva_…`); the plugin signs with a key derived from it instead of the shared secret. Both agent vars are required together |
155167
| `REPO_ROOT` | `~/.hermes/repos` | Local repo mirrors for `/code-repos`, `/code-sync` |
156168
| `SOURCEVAULT_CODE_TOOLS_DEBUG` | off | Log argument shapes (no secrets) |
157169

158170
## Security notes
159171

160172
- All requests are HMAC-signed and travel over localhost only.
173+
- Signatures are timestamped and nonce-protected (SourceVault v1.28+ requires
174+
this), so a captured request cannot be replayed. With an agent token
175+
configured, every request is attributed to that agent in the server's audit
176+
chain instead of the shared secret.
161177
- The plugin never executes retrieved code; `/code-sync` runs only
162178
`git pull --ff-only` inside the configured repo root.
163179
- Repo paths are confined to `REPO_ROOT`; traversal attempts are rejected.

‎__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
Package layout:
44
helpers.py parameter/naming helpers (pure)
55
formatting.py response parsing and output formatting (pure)
6-
http.py HMAC-signed transport to the SourceVault API
6+
transport.py HMAC-signed transport to the SourceVault API
77
tools.py LLM-callable tool schemas and handlers
88
commands.py deterministic slash-command handlers
99

‎commands.py‎

Lines changed: 17 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -331,15 +331,23 @@ def _handle_code_status_command(raw_args):
331331
return f"sourcevault: FAIL {error}\nsearch_url: {search_url}\nread_file_url: {read_url}"
332332

333333
secret_state = "set" if os.environ.get("CODE_SEARCH_HMAC_SECRET") else "missing"
334-
return "\n".join(
335-
[
336-
"sourcevault: OK",
337-
f"health: {body}",
338-
f"search_url: {search_url}",
339-
f"read_file_url: {read_url}",
340-
f"code_search_hmac_secret: {secret_state}",
341-
]
342-
)
334+
agent_name = os.environ.get("SOURCEVAULT_AGENT_NAME", "").strip()
335+
agent_token_set = bool(os.environ.get("SOURCEVAULT_AGENT_TOKEN", "").strip())
336+
lines = [
337+
"sourcevault: OK",
338+
f"health: {body}",
339+
f"search_url: {search_url}",
340+
f"read_file_url: {read_url}",
341+
f"code_search_hmac_secret: {secret_state}",
342+
f"agent_name: {agent_name or '(not set — signing as shared-secret)'}",
343+
f"agent_token: {'set' if agent_token_set else 'missing'}",
344+
]
345+
if bool(agent_name) != agent_token_set:
346+
lines.append(
347+
"warning: agent identity needs BOTH SOURCEVAULT_AGENT_NAME and "
348+
"SOURCEVAULT_AGENT_TOKEN; falling back to the shared secret"
349+
)
350+
return "\n".join(lines)
343351

344352

345353
def _handle_code_repos_command(raw_args):

‎formatting.py‎

Lines changed: 73 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,73 @@
33
import json
44

55

6+
# One-line actionable messages for the machine API's structured error codes
7+
# (services/security/hmac-guard.js, services/util/http.js sendError, and the
8+
# machine API rate limiter). Unknown codes stay unmapped so callers keep the
9+
# raw JSON envelope exactly as before.
10+
_ERROR_HINTS = {
11+
"timestamp_required": (
12+
"Server requires timestamped signatures (SourceVault v1.28+); "
13+
"update this plugin to v1.4 or newer."
14+
),
15+
"stale_timestamp": (
16+
"Signature timestamp outside the accepted window; "
17+
"check clock sync between the Hermes and SourceVault hosts."
18+
),
19+
"bad_timestamp": "Signature timestamp header is not a number; update this plugin.",
20+
"missing_nonce": "Signature nonce header missing; update this plugin.",
21+
"replayed_nonce": "Signature nonce already used; retry the request.",
22+
"bad_signature": (
23+
"Signature rejected: CODE_SEARCH_HMAC_SECRET (or the agent token) "
24+
"does not match the server."
25+
),
26+
"signature_secret_required": (
27+
"Server requires a signing secret; set CODE_SEARCH_HMAC_SECRET "
28+
"on the SourceVault server and in the Hermes environment."
29+
),
30+
"unknown_agent": (
31+
"Agent not recognized by the server (revoked, mistyped, or never minted); "
32+
"check SOURCEVAULT_AGENT_NAME/SOURCEVAULT_AGENT_TOKEN or re-mint with: "
33+
"sourcevault agent mint <name> --surfaces http"
34+
),
35+
"agent_scope": (
36+
"This agent token is not scoped to the http surface; "
37+
"re-mint it with --surfaces http."
38+
),
39+
"agent_repo_scope": (
40+
"This agent token is not scoped to that repository; check its --repos grant."
41+
),
42+
"rate_limited": "Rate limited by the server; retry shortly.",
43+
"missing_repo_name": "repo_name is required; run /code-repos to list exact names.",
44+
"invalid_repo_name": (
45+
"Invalid repo_name; run /code-repos to list exact (case-sensitive) names."
46+
),
47+
"repo_not_found": (
48+
"Repository not indexed under REPO_ROOT; run /code-repos to list repos."
49+
),
50+
"question_too_long": "Question exceeds the server's maximum length; shorten it.",
51+
"history_search_unsupported": (
52+
"This SourceVault does not serve /api/history-search; update SourceVault."
53+
),
54+
}
55+
56+
57+
def _error_hint(payload):
58+
code = str(payload.get("error") or "")
59+
if code == "rate_limited" and payload.get("retry_after"):
60+
return f"Rate limited by the server; retry after {payload['retry_after']}s."
61+
return _ERROR_HINTS.get(code, "")
62+
63+
64+
def _error_command_output(parsed, raw):
65+
"""One-line human message for a failed machine-API result, or raw passthrough."""
66+
hint = str(parsed.get("hint") or "") or _error_hint(parsed)
67+
if not hint:
68+
return raw
69+
code = parsed.get("error") or "error"
70+
return f"SourceVault error ({code}): {hint}"
71+
72+
673
def _extract_json_object(text):
774
if not text:
875
return {}
@@ -66,6 +133,9 @@ def _read_file_command_output(result):
66133
if parsed.get("ok") is True and isinstance(parsed.get("content"), str):
67134
return parsed["content"]
68135

136+
if parsed.get("ok") is False or parsed.get("success") is False:
137+
return _error_command_output(parsed, result)
138+
69139
return result
70140

71141

@@ -79,7 +149,7 @@ def _format_history_command_output(result):
79149
return result
80150

81151
if parsed.get("ok") is False or parsed.get("success") is False:
82-
return result
152+
return _error_command_output(parsed, result)
83153

84154
results = parsed.get("results") or []
85155
lines = [
@@ -117,7 +187,7 @@ def _format_search_command_output(result):
117187
return result
118188

119189
if parsed.get("ok") is False or parsed.get("success") is False:
120-
return result
190+
return _error_command_output(parsed, result)
121191

122192
results = parsed.get("results") or []
123193
lines = [
@@ -229,7 +299,7 @@ def _parse_successful_search_result(result):
229299
return result
230300

231301
if parsed.get("ok") is False or parsed.get("success") is False:
232-
return result
302+
return _error_command_output(parsed, result)
233303

234304
return parsed
235305

‎plugin.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
name: sourcevault-code-tools
2-
version: "1.3"
2+
version: "1.4"
33
description: Adds signed sourcevault code tools and slash commands.

0 commit comments

Comments
 (0)