4 4 Provider-bound secret redaction for Pi.
6 +`leaks` redacts secrets before provider requests.
7 +Local Pi behavior stays transparent when placeholders round-trip exactly.
8 -Loaded through the root [pi-ext package](../../README.md).
11 +Loaded through the root pi-ext package. See [../../README.md](../../README.md).
15 +Provider sees placeholders, not classified secret values.
16 +Pi keeps restore mappings in memory only.
17 +Mappings are lost on process exit, reload, new session, or `/leaks clear`.
19 +`leaks` does not stop tool exfiltration, malicious model behavior, prompt
20 +injection, or unsafe commands.
21 +Use Pi permissions, sandboxing, and tool policy for that.
25 +Provider text uses this shape:
28 +__LEAK_<TAG>[_<TAG>...]_<HMAC12>[_N]__
31 +Examples use fake metadata only:
34 +__LEAK_STRIPE_LIVE_SECRET_KEY_STRIPE_TOKEN_8f31aa77c901__
35 +__LEAK_DATABASE_URL_DB_PASSWORD_POSTGRES_URL_ba29d4ff8810__
38 +The digest is HMAC12 with a random in-memory key.
39 +Tags are safe metadata.
40 +Secret length, prefix, suffix, alphabet, and entropy are not encoded.
10 42 ##
Commands / tools / settings 16 -- `/leaks test <text>`
46 +- `/leaks status` reports safe counters and labels.
47 +- `/leaks reload` reloads settings and dotenv/env learning.
48 +- `/leaks test <text>` redacts local diagnostic text.
49 +- `/leaks clear` clears volatile placeholder mappings after confirmation.
23 -`beforeProviderRequest`, `context`, `toolCall`, `messageEnd`.
26 -`leaks` in Pi `settings.json`.
30 -- `enabled`: boolean, default `true`
31 -- `keywords`: string[], default `[]`
32 -- `regex`: string[] or `{ pattern, flags, label }[]`, default `[]`
33 -- `secretFiles`: string[], default `[".env", ".env.local", ".env.*.local"]`
34 -- `exclude`: string[], default `[]`
53 +Settings: only custom regex rules are accepted.
40 - "keywords": [
"acme-internal"],
41 - "regex": [{
"pattern":
"foo_[A-Za-z0-9]{32}",
"label":
"FOO_TOKEN" }],
42 - "secretFiles": [
".env",
".env.local",
".env.*.local"],
43 - "exclude": [
"localhost",
"127.0.0.1"]
58 + "regex": [{
"pattern":
"foo_[A-Za-z0-9]{32}",
"label":
"FOO_TOKEN" }]
63 +Labels must match `[A-Z0-9_]{1,64}`.
64 +Invalid or missing labels fall back to `CUSTOM_REGEX` and warn.
65 +Flags and unsupported fields are ignored with warnings.
66 +Unsafe patterns are rejected.
68 +Rejected settings: `enabled`, `keywords`, `exclude`, `secretFiles`.
69 +They are intentionally not compatibility features.
50 -Redacts provider-bound copies before model requests.
51 -Context-message copies are redacted without mutating originals.
52 -Local tool calls receive restored args before execution.
53 -Final assistant messages are restored locally.
73 +Built-ins are always active.
74 +They cover high-confidence AI, VCS, package, cloud, payment, messaging, webhook,
75 +mail, auth, OAuth, JWT, cookie, session, database, cache, private-key, and
76 +sensitive-assignment patterns.
55 -Secret values are loaded from configured files relative to Pi cwd.
56 -Settings are read from Pi settings, with `.pi/settings.json` fallback when the
57 -runtime settings API is absent.
78 +Dotenv learning reads only cwd files:
59 -Built-in rules cover common AI provider tokens, developer tokens, cloud keys,
60 -JWTs, private keys, and selected connection strings.
61 -Custom `keywords` use smart boundaries.
62 -Custom `regex` entries may be strings or objects with `pattern`, `flags`, and
64 -Generic assignment redaction requires sufficiently random values and skips
65 -common false positives.
67 -`/leaks status` reports enabled state, rule counts, secret-file values, provider
68 -redactions, and mapping counts.
69 -`/leaks reload` reloads settings and secret-file values.
70 -`/leaks clear` clears stored placeholder mappings.
71 -`/leaks test` is a dry run; its placeholders do not persist.
84 +Process environment values use the same classifier.
85 +Status collapses process env names to `ENV_KEY`.
73 -Placeholders are generic:
87 +URLs, query params, headers, cookies, and assignments preserve safe structure.
88 +Only secret components are redacted.
89 +JWTs and private-key material redact as whole logical values.
90 +Public keys and certificates stay visible.
92 +Provider-bound context and provider request payloads are redacted on copied
94 +Original local objects are not mutated.
95 +Provider authentication headers are preserved.
97 +Tool-call args and finalized assistant messages are restored locally when they
98 +contain exact placeholders.
99 +Restore only matches complete placeholders.
101 +Traversal is bounded.
102 +Cycles are preserved.
103 +Primitive and callable values pass through.
104 +Detector failures fail open and warn once.
106 +Mappings and learned values are capped at 8192 entries.
107 +Overflow placeholders may not be restorable.
109 +##
False-positive policy 111 +Metadata stays visible aggressively.
112 +No entropy-only redaction.
113 +Names, hosts, domains, ordinary URLs, refs, branch names, package names, IDs,
114 +codenames, env references, public keys, and certificates stay visible unless a
115 +custom regex explicitly matches them.
121 +- image, audio, binary, OCR redaction
122 +- semantic secret-byte editing
123 +- homomorphic encryption
124 +- symbolic secret transforms
125 +- arbitrary DLP/privacy redaction
127 +- permission enforcement
128 +- repository secret scanning
129 +- git history cleanup