Skip to content

Commit 941ef4e

Browse files
committed
one block message for both hosts, a generic fallback, and install-oc.sh
THE MESSAGE FIX DID NOT REACH OPENCODE. The previous commit routed the pi host's 11 hand-built block strings through blockMessage(). OpenCode never had that problem and never got the benefit: its guard calls core/path-guard.ts and core/egress.ts directly, and those two kept their original two-sentence wording. So the hosts disagreed about what a block says, and the weaker copy was the one running in the host that had silently failed to load for months. Both are now written to the same rule blockMessage follows: what was blocked, where, and what to do. pathGuardMessage additionally states "nothing was read, so no credential was exposed" and forbids the two retries that cannot work (different spelling, symlink), because the check resolves the real path. egressMessage's engine-unavailable branch now explains that it is a fail-closed gate rather than a verdict on the command, which is the distinction that decides whether the model should retry or escalate. GENERIC FALLBACK. remedyFor() returned a paragraph assuming the blocked thing was a credential in a fixture. For any pattern with no curated entry -- a rule id added by an engine update, a shape nobody wrote advice for -- that is a guess, and a wrong guess ("rotate it") sends the model after something that cannot succeed. The fallback now states the safe default without pretending to know the case. escapeHatches() became three concrete tiers instead of a list that mixed remedy and prohibition, and dropped the implication that only test fixtures get blocked. INSTALL-OC.SH. The pi host pulls from its git checkout on every start; the OpenCode host had no equivalent, which is how it drifted 135 lines of core/ behind the repo without saying anything. This script copies, then RE-RUNS ITSELF WITH --check and fails if the copy does not match -- a copy step alone reproduces the original bug, since a stale plugin that loads looks exactly like a current one. It also refuses to install when packages/oc-leakguard/core is stale, removes the legacy single-file plugin, and prints the log line that proves the plugin actually loaded (a load failure is only a WARN and never reaches the UI). ROOT package.json: main/exports now point at the OpenCode host. `opencode plugin add github:...` started working after dropping the root `workspaces` field (anomalyco/opencode#49704 -- any build/prepare/preinstall/ install/postinstall/prepack script OR workspaces makes the embedded npm fail the git-dependency prepare step; I confirmed workspaces alone was our trigger). But with `main` pointing at ./index.ts it would install the PI extension, which exports an ExtensionAPI factory and would fail the V2 plugin shape check. pi reads `pi.extensions` from the explicit manifest and ignores `main`, so `main`/`exports` now point at the OpenCode host with `./pi` kept as a named export. Verified by loading the installed package: keys are id/server/setup, id is leakguard. Verified: 151/151 tests, tsc clean, all four message shapes printed and read, install-oc.sh idempotent, --check catches stale copies, --uninstall leaves no leftovers, installed plugin loads from the npm-shaped package.
1 parent bfa5c7c commit 941ef4e

6 files changed

Lines changed: 258 additions & 47 deletions

File tree

‎core/egress.ts‎

Lines changed: 30 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -165,19 +165,38 @@ export function checkEgress(
165165
/** Message for a blocked command, phrased so a retrying model changes approach. */
166166
export function egressMessage(v: EgressVerdict): string {
167167
const what = v.found?.length ? ` (${v.found.join(", ")})` : "";
168+
168169
if (v.error) {
169-
return (
170-
`leakguard: cannot verify this command (${v.error}).\n` +
171-
`Refusing to run egress while secret detection is unavailable — a gate that ` +
172-
`passes when its scanner is broken is not a gate.`
173-
);
170+
return [
171+
`leakguard refused this command: secret detection is unavailable (${v.error}).`,
172+
"",
173+
"This is not a false positive and not about your command: the scanner that",
174+
"decides whether the payload carries a credential could not run, so the gate",
175+
"fails closed instead of waving everything through.",
176+
"",
177+
"What to do:",
178+
" 1. Run the command without the network part, if the two can be separated.",
179+
" 2. Install the engine (the human runs `~/.bin/betterleaks-update`, or",
180+
" `~/bin/betterleaks-update` on Linux) and try again.",
181+
" 3. If neither is possible, ask the human to run it themselves.",
182+
].join("\n");
174183
}
175-
return (
176-
`leakguard blocked an ${v.reason}${what}.\n` +
177-
`The VALUE tripped this, not the spelling — renaming a variable or re-quoting ` +
178-
`will not help. If this is a test, generate the value at runtime instead of ` +
179-
`writing it in the command.`
180-
);
184+
185+
return [
186+
`leakguard blocked this command: ${v.reason}${what}.`,
187+
"",
188+
"The VALUE tripped this, not the spelling — renaming a variable, re-quoting, or",
189+
"splitting the command will produce the same block. This rule fires when a",
190+
"command both leaves the machine AND carries a credential.",
191+
"",
192+
"What to do, cheapest first:",
193+
" 1. Drop the credential from the command. Almost every diagnostic works",
194+
" without it (a HEAD request, a status endpoint, `--dry-run`).",
195+
" 2. If the target is local (`localhost`, a unix socket), that is allowed —",
196+
" the rule is about sending secrets OFF the machine.",
197+
" 3. Need the real call? Ask the human to run it, so the secret never enters",
198+
" this transcript.",
199+
].join("\n");
181200
}
182201

183202
export { ENGINE_BIN, ENGINE_CFG };

‎core/path-guard.ts‎

Lines changed: 26 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -64,15 +64,31 @@ export function blockedPathReason(target: string): string | undefined {
6464
return undefined;
6565
}
6666

67-
/** A message a human, or a model that will retry, can act on. */
67+
/**
68+
* The message both hosts show when a path is refused.
69+
*
70+
* Structure is deliberate and matches llm-hints.ts: what was blocked, where, and
71+
* what to do about it. The earlier one-sentence version ("Read it by key name")
72+
* told the model a remedy but not what had matched, so the only move it could see
73+
* was retrying with a different spelling — which the message then had to forbid in
74+
* the same breath, without saying why.
75+
*
76+
* Kept here rather than in the pi host because the OpenCode host has no
77+
* llm-hints.ts and would otherwise keep the weaker wording.
78+
*/
6879
export function pathGuardMessage(tool: string, reason: string, target: string): string {
69-
return (
70-
`leakguard blocked ${tool} on ${reason}: ${target}\n` +
71-
`Read it by key name, or ask the human to allow this one call. ` +
72-
`Changing the path's spelling will not change the outcome — the check resolves ` +
73-
`symlinks and matches the real path.`
74-
);
80+
return [
81+
`leakguard blocked this ${tool}: ${reason}.`,
82+
` ${target}`,
83+
"",
84+
"Nothing was read, so no credential was exposed.",
85+
"What to do, cheapest first:",
86+
" 1. You probably do not need the contents. Reference the file by path if you",
87+
" only need to prove it exists, or ask the human whether it is set.",
88+
" 2. Need one non-secret value from it? Ask the human for that value.",
89+
" 3. Genuinely need the file? Ask the human to run `/leakguard allow-once`.",
90+
"",
91+
"Do not retry with different spelling, a relative path, or a symlink: the check",
92+
"resolves the real path, so the outcome will be identical.",
93+
].join("\n");
7594
}
76-
77-
/** Tools whose arguments name a file the agent intends to read or write. */
78-
export const PATH_TOOLS = new Set(["read", "write", "edit", "patch", "view"]);

‎llm-hints.ts‎

Lines changed: 19 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,15 @@ export function remedyFor(pattern?: string): string {
7070
if (p.includes("assignment")) {
7171
return "This looks like KEY=value where the value is secret. If you are writing a config or test fixture, use an obvious placeholder (`your-key-here`) or build the value at runtime.";
7272
}
73-
return "If this is a test fixture or a rule definition, build the string at runtime (string concatenation or character codes) instead of committing or echoing a literal. If it is a real credential, stop and ask the human to rotate it.";
73+
// Fallback for a pattern with no curated remedy: a rule id added by an engine
74+
// update, or a shape nobody wrote advice for yet. It must not guess, because a
75+
// wrong remedy (e.g. "rotate it" for a file that was never read) sends the model
76+
// down a path that cannot succeed.
77+
return (
78+
"Treat the value as live until proven otherwise: do not print it, copy it into another file, or send it anywhere. " +
79+
"If you are writing a test fixture or documentation, use an obvious placeholder or build the string at runtime. " +
80+
"If a task genuinely needs the value, stop and ask the human — they can allow this one call."
81+
);
7482
}
7583

7684
/**
@@ -82,10 +90,16 @@ export function remedyFor(pattern?: string): string {
8290
export function escapeHatches(): string {
8391
return [
8492
"Options, cheapest first:",
85-
" 1. Do not need the value — proceed without it (most tasks do).",
86-
" 2. Need to know it exists/shape only — ask for names, counts, or a yes/no check.",
87-
" 3. Need the actual value — ask the human to run `/leakguard allow-once`.",
88-
`Note: retrying with different quoting, variable indirection, or \`${REDACTION_PLACEHOLDER}\` will not help. The check is on the VALUE, not the syntax.`,
93+
" 1. Do not need the value — proceed without it. Most tasks do not need the",
94+
" secret itself, only proof that it exists or that the shape is right.",
95+
" 2. Need to know it exists or its shape — ask for a count, a yes/no, or the",
96+
" key NAMES only (e.g. `grep -o '^[A-Z_]*=' file` reads names, not values).",
97+
" 3. Need the actual value — stop and ask the human. They can run",
98+
" `/leakguard allow-once` for this single call.",
99+
"",
100+
"Note: retrying with different quoting, escapes, variable indirection, base64, or",
101+
`\`${REDACTION_PLACEHOLDER}\` will not help. The check is on the VALUE, not the`,
102+
"syntax, so every variant lands on the same block and costs a turn.",
89103
].join("\n");
90104
}
91105

‎packages/oc-leakguard/core/egress.ts‎

Lines changed: 30 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -165,19 +165,38 @@ export function checkEgress(
165165
/** Message for a blocked command, phrased so a retrying model changes approach. */
166166
export function egressMessage(v: EgressVerdict): string {
167167
const what = v.found?.length ? ` (${v.found.join(", ")})` : "";
168+
168169
if (v.error) {
169-
return (
170-
`leakguard: cannot verify this command (${v.error}).\n` +
171-
`Refusing to run egress while secret detection is unavailable — a gate that ` +
172-
`passes when its scanner is broken is not a gate.`
173-
);
170+
return [
171+
`leakguard refused this command: secret detection is unavailable (${v.error}).`,
172+
"",
173+
"This is not a false positive and not about your command: the scanner that",
174+
"decides whether the payload carries a credential could not run, so the gate",
175+
"fails closed instead of waving everything through.",
176+
"",
177+
"What to do:",
178+
" 1. Run the command without the network part, if the two can be separated.",
179+
" 2. Install the engine (the human runs `~/.bin/betterleaks-update`, or",
180+
" `~/bin/betterleaks-update` on Linux) and try again.",
181+
" 3. If neither is possible, ask the human to run it themselves.",
182+
].join("\n");
174183
}
175-
return (
176-
`leakguard blocked an ${v.reason}${what}.\n` +
177-
`The VALUE tripped this, not the spelling — renaming a variable or re-quoting ` +
178-
`will not help. If this is a test, generate the value at runtime instead of ` +
179-
`writing it in the command.`
180-
);
184+
185+
return [
186+
`leakguard blocked this command: ${v.reason}${what}.`,
187+
"",
188+
"The VALUE tripped this, not the spelling — renaming a variable, re-quoting, or",
189+
"splitting the command will produce the same block. This rule fires when a",
190+
"command both leaves the machine AND carries a credential.",
191+
"",
192+
"What to do, cheapest first:",
193+
" 1. Drop the credential from the command. Almost every diagnostic works",
194+
" without it (a HEAD request, a status endpoint, `--dry-run`).",
195+
" 2. If the target is local (`localhost`, a unix socket), that is allowed —",
196+
" the rule is about sending secrets OFF the machine.",
197+
" 3. Need the real call? Ask the human to run it, so the secret never enters",
198+
" this transcript.",
199+
].join("\n");
181200
}
182201

183202
export { ENGINE_BIN, ENGINE_CFG };

‎packages/oc-leakguard/core/path-guard.ts‎

Lines changed: 26 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -64,15 +64,31 @@ export function blockedPathReason(target: string): string | undefined {
6464
return undefined;
6565
}
6666

67-
/** A message a human, or a model that will retry, can act on. */
67+
/**
68+
* The message both hosts show when a path is refused.
69+
*
70+
* Structure is deliberate and matches llm-hints.ts: what was blocked, where, and
71+
* what to do about it. The earlier one-sentence version ("Read it by key name")
72+
* told the model a remedy but not what had matched, so the only move it could see
73+
* was retrying with a different spelling — which the message then had to forbid in
74+
* the same breath, without saying why.
75+
*
76+
* Kept here rather than in the pi host because the OpenCode host has no
77+
* llm-hints.ts and would otherwise keep the weaker wording.
78+
*/
6879
export function pathGuardMessage(tool: string, reason: string, target: string): string {
69-
return (
70-
`leakguard blocked ${tool} on ${reason}: ${target}\n` +
71-
`Read it by key name, or ask the human to allow this one call. ` +
72-
`Changing the path's spelling will not change the outcome — the check resolves ` +
73-
`symlinks and matches the real path.`
74-
);
80+
return [
81+
`leakguard blocked this ${tool}: ${reason}.`,
82+
` ${target}`,
83+
"",
84+
"Nothing was read, so no credential was exposed.",
85+
"What to do, cheapest first:",
86+
" 1. You probably do not need the contents. Reference the file by path if you",
87+
" only need to prove it exists, or ask the human whether it is set.",
88+
" 2. Need one non-secret value from it? Ask the human for that value.",
89+
" 3. Genuinely need the file? Ask the human to run `/leakguard allow-once`.",
90+
"",
91+
"Do not retry with different spelling, a relative path, or a symlink: the check",
92+
"resolves the real path, so the outcome will be identical.",
93+
].join("\n");
7594
}
76-
77-
/** Tools whose arguments name a file the agent intends to read or write. */
78-
export const PATH_TOOLS = new Set(["read", "write", "edit", "patch", "view"]);

‎scripts/install-oc.sh‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
#!/bin/sh
2+
# install-oc.sh — install / update the OpenCode host from this checkout.
3+
#
4+
# WHY THIS EXISTS
5+
#
6+
# `opencode plugin add github:calionauta/leakguard` works now (see the note at the
7+
# bottom), but it installs a PINNED snapshot and only refreshes when you re-run
8+
# it. The pi host pulls from its git checkout on every start; the OpenCode host
9+
# has no equivalent. That asymmetry is how the installed plugin drifted a full
10+
# refactor behind the repo: 240-line core/ against the repo's 375, so OpenCode
11+
# silently ran without line/column positions, without the curated rule names, and
12+
# without the shared residual table. Nothing reported it, because a stale plugin
13+
# that loads is indistinguishable from a current one.
14+
#
15+
# So: one command that copies, then VERIFIES the copy matches. The verification is
16+
# the point — a copy step alone fails the same way it did before, silently.
17+
#
18+
# Usage:
19+
# scripts/install-oc.sh install or update, then verify
20+
# scripts/install-oc.sh --check verify only; exit 1 if stale (use in CI/hooks)
21+
# scripts/install-oc.sh --uninstall remove the installed plugin
22+
#
23+
# Targets:
24+
# default ~/.config/opencode/plugins/leakguard/
25+
# OPENCODE_PLUGINS_DIR=/path/to/plugins explicit directory
26+
#
27+
# Safe to re-run. Removes the legacy single-file plugin (plugins/leakguard.ts) if
28+
# present, because OpenCode would otherwise load it as a SECOND plugin alongside
29+
# the directory.
30+
31+
set -eu
32+
33+
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
34+
PKG="$ROOT/packages/oc-leakguard"
35+
MODE="${1:-}"
36+
37+
PLUGINS_DIR="${OPENCODE_PLUGINS_DIR:-${HOME}/.config/opencode/plugins}"
38+
DEST="$PLUGINS_DIR/leakguard"
39+
LEGACY="$PLUGINS_DIR/leakguard.ts"
40+
41+
die() { printf '\033[31m%s\033[0m\n' "$*" >&2; exit 1; }
42+
note() { printf '%s\n' "$*" >&2; }
43+
ok() { printf '\033[32m%s\033[0m\n' "$*" >&2; }
44+
45+
[ -d "$PKG" ] || die "missing $PKG (run from a full checkout)"
46+
47+
# The shipped copy must match the repo's single source. If it does not, the
48+
# install would publish a stale core/ — exactly the drift this script exists to
49+
# catch, so refuse rather than copy the wrong thing.
50+
if ! sh "$ROOT/scripts/sync-core.sh" --check >/dev/null 2>&1; then
51+
die "packages/oc-leakguard/core is stale. Run: sh scripts/sync-core.sh"
52+
fi
53+
54+
if [ "$MODE" = "--uninstall" ]; then
55+
rm -rf "$DEST" "$LEGACY"
56+
ok "removed $DEST"
57+
[ -e "$LEGACY" ] || ok "no legacy single-file plugin present"
58+
exit 0
59+
fi
60+
61+
if [ "$MODE" = "--check" ]; then
62+
stale=0
63+
if [ ! -d "$DEST" ]; then
64+
note " MISSING $DEST"
65+
stale=$((stale + 1))
66+
else
67+
for f in index.ts package.json README.md; do
68+
if ! cmp -s "$PKG/$f" "$DEST/$f" 2>/dev/null; then
69+
note " STALE $f"
70+
stale=$((stale + 1))
71+
fi
72+
done
73+
for f in "$PKG"/core/*.ts; do
74+
base="$(basename "$f")"
75+
if ! cmp -s "$f" "$DEST/core/$base" 2>/dev/null; then
76+
note " STALE core/$base"
77+
stale=$((stale + 1))
78+
fi
79+
done
80+
fi
81+
if [ -e "$LEGACY" ]; then
82+
note " LEFTOVER $LEGACY (loads as a second plugin; run without --check to remove)"
83+
stale=$((stale + 1))
84+
fi
85+
if [ "$stale" -eq 0 ]; then
86+
ok "installed OpenCode plugin matches the repo"
87+
exit 0
88+
fi
89+
die "installed OpenCode plugin is out of date ($stale difference(s))"
90+
fi
91+
92+
[ -d "$PLUGINS_DIR" ] || die "no plugins directory at $PLUGINS_DIR — is OpenCode installed for this user?"
93+
94+
rm -rf "$DEST"
95+
mkdir -p "$DEST/core"
96+
cp "$PKG/index.ts" "$PKG/package.json" "$PKG/README.md" "$DEST"/
97+
cp "$PKG"/core/*.ts "$DEST/core"/
98+
99+
if [ -e "$LEGACY" ]; then
100+
rm -f "$LEGACY"
101+
note " removed $LEGACY (was loading as a second plugin)"
102+
fi
103+
104+
# Verify by re-running the check, so a partial copy cannot report success.
105+
if ! sh "$ROOT/scripts/install-oc.sh" --check >/dev/null 2>&1; then
106+
die "copy completed but verification failed — inspect $DEST"
107+
fi
108+
109+
ok "installed to $DEST"
110+
note ""
111+
note "OpenCode loads this directory at startup. Restart OpenCode to pick it up,"
112+
note "then confirm in its log that the plugin loaded:"
113+
note " grep -i leakguard ~/.local/share/opencode/log/opencode.log | tail -3"
114+
note ""
115+
note "A load failure is only a WARN and does not surface in the UI. If the last"
116+
note "line for leakguard is not a successful load, the guard is NOT running."
117+
118+
# NOTE on `opencode plugin add github:calionauta/leakguard`
119+
#
120+
# That path works as of the commit that dropped the root `workspaces` field
121+
# (anomalyco/opencode#49704: any build/prepare/preinstall/install/postinstall/
122+
# prepack script OR a `workspaces` field makes the embedded npm fail the git
123+
# dependency prepare step). It installs a pinned snapshot into the config's
124+
# `plugins` array and re-resolves only when re-run.
125+
#
126+
# This script remains the recommended path because it (a) tracks the checkout,
127+
# (b) verifies what it wrote, and (c) cleans up the legacy single-file plugin.

0 commit comments

Comments
 (0)