@yahyahammad/venastine 0.2.0 → 0.3.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.env.example +19 -14
- package/CONFIG_ARCHITECTURE.md +2002 -0
- package/NOTICE +1 -1
- package/README.md +233 -94
- package/agents/builtin/build.md +73 -0
- package/agents/builtin/general.md +80 -0
- package/agents/builtin/plan.md +23 -5
- package/agents/builtin/test.md +65 -0
- package/agents/builtin/writer.md +67 -0
- package/agents/manager.py +261 -195
- package/agents/subagent_tool.py +277 -43
- package/agents/tui_commands.py +7 -12
- package/bin/venastine.mjs +528 -382
- package/bin/venastine.py +71 -0
- package/cli_commands.py +835 -0
- package/config.py +95 -1198
- package/config.yaml +1090 -0
- package/config_edit.py +1301 -0
- package/config_schema.py +966 -0
- package/config_update.py +749 -0
- package/core/agent_activity.py +158 -20
- package/core/ansi.py +452 -0
- package/core/approval.py +27 -5
- package/core/call_view.py +364 -0
- package/core/cancel.py +121 -0
- package/core/chatgpt_auth.py +747 -0
- package/core/claims_view.py +107 -0
- package/core/client.py +1238 -82
- package/core/commands.py +454 -0
- package/core/compaction.py +830 -66
- package/core/config_loader.py +516 -97
- package/core/connect.py +686 -0
- package/core/events.py +68 -6
- package/core/file_mentions.py +280 -0
- package/core/interaction.py +87 -4
- package/core/line_pattern.py +128 -0
- package/core/loop.py +1516 -440
- package/core/memory.py +120 -8
- package/core/pipeline_models.py +23 -9
- package/core/provider_errors.py +234 -0
- package/core/reasoning/confidence_scoring.py +70 -54
- package/core/reasoning/json_retry.py +19 -1
- package/core/reasoning/orchestrator.py +232 -53
- package/core/reasoning/output_writer.py +90 -31
- package/core/reasoning/payload_validation.py +133 -7
- package/core/reasoning/pipeline_storage.py +427 -361
- package/core/reasoning/review.py +659 -615
- package/core/reasoning/scholar.py +38 -14
- package/core/reasoning/source_corpus.py +110 -4
- package/core/replay.py +158 -26
- package/core/session.py +36 -12
- package/core/session_view.py +259 -0
- package/core/session_wake.py +259 -0
- package/core/shell_sessions.py +1553 -0
- package/core/workspace_trust.py +1 -1
- package/credentials.py +308 -180
- package/database.py +82 -1
- package/{PRIVACY.md → docs/PRIVACY.md} +19 -7
- package/docs/SECURITY.md +108 -0
- package/docs/THIRD_PARTY_NOTICES.md +148 -0
- package/env_secrets.py +118 -77
- package/json_store.py +236 -16
- package/logging_setup.py +121 -11
- package/main.py +1671 -199
- package/mcp_client/client.py +257 -23
- package/mcp_client/config.py +484 -379
- package/mcp_client/registration.py +163 -2
- package/memories/manager.py +15 -0
- package/memories/tui_commands.py +7 -12
- package/package.json +234 -4
- package/project_init/config_files.py +4 -0
- package/project_init/generator.py +201 -37
- package/project_init/manifest.py +418 -406
- package/project_init/tui_commands.py +7 -4
- package/prompts/revalidate.md +1 -1
- package/prompts/revise.md +17 -15
- package/prompts/system_prompts.py +64 -10
- package/providers.json.example +94 -92
- package/pyproject.toml +51 -2
- package/requirements.txt +252 -29
- package/safety/policy_enforcement.py +353 -17
- package/security/askpass.py +419 -0
- package/security/capability.py +37 -7
- package/security/confine.py +484 -0
- package/security/hosted.py +182 -0
- package/security/permissions.py +54 -7
- package/security/posture.py +124 -12
- package/security/protected_paths.py +198 -6
- package/security/sandbox.py +3262 -139
- package/security/secrets.py +855 -0
- package/skills/tui_commands.py +3 -4
- package/storage.py +368 -35
- package/tools/base.py +465 -305
- package/tools/builtin/_math_common.py +306 -16
- package/tools/builtin/_net_common.py +267 -61
- package/tools/builtin/arxiv.py +681 -223
- package/tools/builtin/ask_user.py +231 -213
- package/tools/builtin/discrete_math.py +35 -4
- package/tools/builtin/fetch_url.py +239 -21
- package/tools/builtin/file_ops.py +341 -33
- package/tools/builtin/geometry.py +184 -148
- package/tools/builtin/get_time.py +2 -2
- package/tools/builtin/linear_algebra.py +66 -23
- package/tools/builtin/load_skill.py +10 -0
- package/tools/builtin/logic.py +171 -12
- package/tools/builtin/pin.py +46 -12
- package/tools/builtin/probability_stats.py +224 -228
- package/tools/builtin/project_docs.py +80 -21
- package/tools/builtin/remember.py +21 -4
- package/tools/builtin/shell.py +586 -67
- package/tools/builtin/shell_sessions.py +613 -0
- package/tools/builtin/symbolic_math.py +80 -10
- package/tools/builtin/todo.py +5 -3
- package/tools/builtin/web_search.py +329 -151
- package/tools/context.py +23 -0
- package/tools/isolation.py +387 -314
- package/tools/registry.py +347 -30
- package/tui/app.py +4645 -438
- package/tui/app.tcss +185 -2
- package/tui/commands.py +10 -154
- package/tui/diffs.py +286 -265
- package/tui/hosted_driver.py +102 -0
- package/tui/markdown.py +60 -10
- package/tui/meters.py +103 -7
- package/tui/screens.py +346 -92
- package/tui/themes.py +59 -19
- package/tui/widgets.py +1575 -111
- package/SECURITY.md +0 -88
- package/THIRD_PARTY_NOTICES.md +0 -100
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
**No telemetry. No analytics. No tracking.**
|
|
4
4
|
|
|
5
|
-
This harness runs entirely on your machine, from a checkout or from an npm install. It does not phone home, does not collect usage data, and
|
|
5
|
+
This harness runs entirely on your machine, from a checkout or from an npm install. It does not phone home, does not collect usage data, and needs no hosted backend. The optional hosted demo, which is a server, is described in its own section below.
|
|
6
6
|
|
|
7
7
|
## What is stored locally
|
|
8
8
|
|
|
@@ -13,12 +13,13 @@ State lives in files, in one of two places depending on how you installed it —
|
|
|
13
13
|
|
|
14
14
|
| File / directory | What it holds | Created when |
|
|
15
15
|
|---|---|---|
|
|
16
|
-
| `app.db` (`APP_DB_PATH`) — `~/.config/venastine/app.db` on an npm install | SQLite: `MessageLog`, `ConversationThread`, `CompactionCheckpoint`, `ThreadSummary`, `UserMemory` (`storage.py`) and `PipelineRunRecord` (`core/reasoning/pipeline_storage.py`) — every chat turn, every research pass, and any `remember` memories | First run creates it |
|
|
17
|
-
| `logs/app.log` (`AGENT_LOG_FILE`, 1 MB × 3 rotated) — under `~/.config/venastine/logs/` on an npm install | **INFO and above** by default (`AGENT_LOG_LEVEL` overrides), including provider/HTTP traces. Redacted via `safety/policy_enforcement.
|
|
16
|
+
| `app.db` (`APP_DB_PATH`) — `~/.config/venastine/app.db` on an npm install | SQLite: `MessageLog`, `ConversationThread`, `CompactionCheckpoint`, `ThreadSummary`, `UserMemory` (`storage.py`) and `PipelineRunRecord` (`core/reasoning/pipeline_storage.py`) — every chat turn, every research pass, and any `remember` memories. Since ROADMAP_v3 §81 it also holds a full copy of every image `view_image` attached, base64 in `MessageLog.images`, kept for as long as its thread is. It is a copy, not a reference to the file, so deleting the image from your workspace does not remove it from here. Since §83 a ChatGPT plan turn also keeps the model's encrypted reasoning and its summary, which go back only to the model that wrote them | First run creates it |
|
|
17
|
+
| `logs/app.log` (`AGENT_LOG_FILE`, 1 MB × 3 rotated) — under `~/.config/venastine/logs/` on an npm install | **INFO and above** by default (`AGENT_LOG_LEVEL` overrides), including provider/HTTP traces. Redacted via `safety/policy_enforcement.redact_diagnostic_text` -- the same vocabulary as tool output, which between 2026-08-23 and batch 144 it measurably was not: the log applied the seven vendor-token patterns and not the three credential SHAPES, so a password in a URL's userinfo reached this file in cleartext while the identical string was redacted on its way to the model. May still contain query text. Created **0600** since batch 144; it took the process umask (0644 at the common default) before that, and an app.log created by an older build keeps its mode until rotation ages it out | Every run appends |
|
|
18
18
|
| `output/<run_id>/` (`AGENT_OUTPUT_DIR`) | Per-run artifacts: `report.md`, `report.pdf` (if `weasyprint`), `00_plan.md` … `07_review.json`, `trace.md` | Every ` --mode research` run |
|
|
19
|
-
| `output/<run_id>/sources/` | **Since §45: the text of every page a run retrieved**, one `<sha256>.txt` per document, plus an `index.json` of urls, tools, timestamps, hashes and lengths. This is what makes a similarity score checkable rather than something you take on trust. Everything written here has been through the same redaction tool output gets. Set `
|
|
20
|
-
| `~/.config/venastine/pipeline_models.json` | The `/critic` and `/
|
|
21
|
-
| `providers.json` (`AGENT_PROVIDERS_FILE`) & `.env` (`AGENT_ENV_FILE`) | Your local secrets
|
|
19
|
+
| `output/<run_id>/sources/` | **Since §45: the text of every page a run retrieved**, one `<sha256>.txt` per document, plus an `index.json` of urls, tools, timestamps, hashes and lengths. This is what makes a similarity score checkable rather than something you take on trust. Everything written here has been through the same redaction tool output gets — and since ROADMAP_v3 §52 that is true of a PAGED document too, which it measurably was not between §51 and §52: `fetch_url` cut a page out of the body before the redactor saw it, so a credential straddling a page boundary matched nothing in either page and the corpus rejoined the halves into this directory. Files written by a run from that window are on disk as they were written. Set `persist_source_text: false` in `config.yaml` to keep the index and drop the text | Every research run that fetched anything |
|
|
20
|
+
| `~/.config/venastine/pipeline_models.json` | The `/critic`, `/embedder` and `/submodel` model choices — provider and model name only, no keys | You run one of those commands |
|
|
21
|
+
| `providers.json` (`AGENT_PROVIDERS_FILE`) & `.env` (`AGENT_ENV_FILE`) | Your local secrets: LLM provider keys in `providers.json`, and in `.env` the API keys a future tool will need. No shipped tool reads `.env` yet, so a key put there is stored for nothing until one does. Gitignored, `export-ignore`d, and excluded from the npm tarball by the `files` allowlist; never sent except as described below | You create via `cp *.example` |
|
|
22
|
+
| `chatgpt_auth.json` (beside `providers.json`) | The ChatGPT plan's sign-in (§83): a host id made once per install, the client id OpenAI registered for it, your ChatGPT account's id, and the current access and refresh tokens. 0600, gitignored, `export-ignore`d, kept out of the npm tarball and any deploy bundle. Sent only to auth.openai.com, to refresh or revoke it, and to api.openai.com as the bearer of each plan request, every one sent with `store: false` | `/connect chatgpt`; `/disconnect chatgpt` revokes and deletes the tokens, and `--forget` the registration too |
|
|
22
23
|
| `~/.config/venastine/providers.json` | Optional user-level provider keys. An npm install reads this **only** when the current directory has no `providers.json` of its own — a local one always wins | You create it, for a command you run from anywhere |
|
|
23
24
|
| `~/.config/venastine/runtime/<version>-<hash>/` | The Python virtual environment an npm install builds on first run, after asking. Holds the pinned dependencies, no data of yours | First `venastine` run, with your consent |
|
|
24
25
|
| `~/.config/venastine/settings.json` & `~/.config/venastine/mcp.json` | Your user-tier settings/MCP servers | On first trust / settings save |
|
|
@@ -26,7 +27,7 @@ State lives in files, in one of two places depending on how you installed it —
|
|
|
26
27
|
| `<project>/.venastine/` | Project-tier config — `settings.json`, `mcp.json`, plus any project `agents/` and `skills/`. Loaded only after you trust the workspace (`core/workspace_trust.py`) | You create it, or `/init` does |
|
|
27
28
|
| `<project>/AGENTS.md` | The project's hub document, injected into the system prompt of any agent that opts in. An ordinary committed file, but it is inside the same trust boundary as `.venastine/` and a change to it re-triggers the trust prompt | You write it, or `/init` does |
|
|
28
29
|
|
|
29
|
-
Everything above is **local-only** by default, and three separate mechanisms keep it out of the three ways this project is distributed: `.gitignore` for `git push`, `.gitattributes` `export-ignore` for `git archive` and "Download ZIP", and the `files` allowlist in `package.json` for the npm tarball. `app.db`, `logs/`, `output/`, `providers.json` and `.env` are excluded by all three.
|
|
30
|
+
Everything above is **local-only** by default, and three separate mechanisms keep it out of the three ways this project is distributed: `.gitignore` for `git push`, `.gitattributes` `export-ignore` for `git archive` and "Download ZIP", and the `files` allowlist in `package.json` for the npm tarball. `app.db`, `logs/`, `output/`, `providers.json` and `.env` are excluded by all three, and since batch 144 so is the `*.tmp` a failed atomic write can leave beside any of them -- which was excluded by one of the three, and only because `package.json`'s `files` is an allowlist that happened not to name it. The three channels read one list, `package.json`'s `neverDistribute` (batch 140).
|
|
30
31
|
|
|
31
32
|
## What leaves your machine
|
|
32
33
|
|
|
@@ -51,9 +52,20 @@ No automatic expiry — a thread lives until you delete it.
|
|
|
51
52
|
To remove the Python environment as well: `venastine --venastine-reinstall` deletes it, or `rm -rf ~/.config/venastine/runtime/`. Uninstalling the package (`npm rm -g @yahyahammad/venastine`) does **not** remove anything under `~/.config/venastine/` — that is your data and config, and it is left for you to delete.
|
|
52
53
|
* **One thread:** there is no single-thread delete command; wiping the DB is the intended granularity (threads are cheap and local).
|
|
53
54
|
* **Durable memories:** `python main.py --memories` to list, `python main.py --forget <id>` to delete one by id (never by substring, by design).
|
|
55
|
+
* **Tool keys:** delete `.env` (or the file `AGENT_ENV_FILE` names). No shipped tool reads it yet, so nothing is lost.
|
|
54
56
|
* **Settings/trust:** delete `~/.config/venastine/settings.json` or `trusted_projects.json` entries directly. The same folder holds `ui_preferences.json`, `model_windows.json` and `pipeline_models.json` — remembered UI and model choices, no keys and no content.
|
|
55
57
|
* **Fetched page text only:** `rm -rf output/*/sources/` removes the retrieved text while leaving each run's report, claims and scores in place. The scores stay, but nothing can re-derive them afterwards.
|
|
56
58
|
|
|
59
|
+
## The hosted demo (ROADMAP_v3 §79)
|
|
60
|
+
|
|
61
|
+
Everything above describes the harness on your machine. The hosted demo -- a Hugging Face Space or ModelScope Studio running the same harness, its terminal drawn in your browser -- is a server, and it changes three things.
|
|
62
|
+
|
|
63
|
+
* **Your session runs on the server.** Each browser tab gets its own harness process and session directory, deleted when the tab closes (or, if the server was stopped abruptly, when it next starts), and a tab left idle for 20 minutes is ended; nothing you type, and nothing the model answers, outlives the session in a shared demo. The platform that hosts it (Hugging Face, or ModelScope on Alibaba Cloud) carries the connection and can see what crosses it, as any host can.
|
|
64
|
+
* **A sign-in's key is held in that process's memory only**, never written, and dropped when the session ends. You can revoke it at any time at https://huggingface.co/settings/connected-applications, https://openrouter.ai/keys, https://www.modelscope.ai/my/settings/apps or https://www.modelscope.cn/my/settings/apps. A shared demo takes no pasted key (§79 HD12); a private copy of your own does, and keeps what you give it in that copy until it restarts.
|
|
65
|
+
* **A ModelScope sign-in passes through the bridge**, the one part of the deployment that holds the app's secret (§79 HD13): it trades the code ModelScope sends back for the token, hands the token to your session, and keeps neither. ModelScope records that you approved this app -- on the ModelScope Studio, the one ModelScope created for that Studio. The page ModelScope returns you to shows a one-time code to paste into your terminal; the address it arrives at carries ModelScope's own code, which is of no use without the app's secret. A sign-in on modelscope.cn, ModelScope's site in China and a separate account, works the same way through that site's own app, and its token and your requests then go to modelscope.cn.
|
|
66
|
+
* **The code it runs is a commit of `main` that passed every CI check**, named in the page's footer (`build` and the commit). The Space is redeployed automatically once every check on a new commit has passed, and the Studio by hand with the same checks; whoever can merge to `main` decides what runs beside your sign-in (§79 HD9). The deploy itself holds a token for the Space and nothing of yours.
|
|
67
|
+
* **Gradio's analytics are off.** The page is served by Gradio, which by default reports each start to huggingface.co and api.gradio.app; the demo sets `GRADIO_ANALYTICS_ENABLED=False` unless its operator turns them back on, and with it off none of those calls was made (measured 2026-10-22). ModelScope also mounts persistent storage into every Studio (`/mnt/workspace`, and `/tmp/gradio`); no session writes to either.
|
|
68
|
+
|
|
57
69
|
## If you publish a report
|
|
58
70
|
|
|
59
71
|
`output/<run_id>/report.md` may quote third-party pages. Before publishing, verify you have the right to share those excerpts (fair-use / citation) and redact any private data that entered via a tool result or a prompted memory.
|
package/docs/SECURITY.md
ADDED
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# Security Policy
|
|
2
|
+
|
|
3
|
+
## Supported Versions
|
|
4
|
+
|
|
5
|
+
| Version | Supported |
|
|
6
|
+
|---|---|
|
|
7
|
+
| `main` (0.1.x) | Yes — security fixes ship on `main` first |
|
|
8
|
+
|
|
9
|
+
No long-term support branches yet. If you are on a fork, rebase on `main` before reporting.
|
|
10
|
+
|
|
11
|
+
## Reporting a Vulnerability
|
|
12
|
+
|
|
13
|
+
**Do not open a public issue, discussion, or pull request for a security vulnerability.**
|
|
14
|
+
|
|
15
|
+
**Email the maintainer at YahyaHammad@proton.me**, with the subject `[SECURITY] Venastine — <title>`.
|
|
16
|
+
|
|
17
|
+
Send a high-level summary first. Do not include full exploit code in plaintext until a secure transfer method has been agreed.
|
|
18
|
+
|
|
19
|
+
**Or use GitHub Private Vulnerability Reporting, where it is enabled:** *Security* tab → *Report a vulnerability*. It is the better channel when available, because the report, the fix and the advisory stay in one place — but it is a public-repository feature, so email is the channel that always works. Use email if you do not see the button.
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
### What to include
|
|
23
|
+
|
|
24
|
+
* Affected file(s) and line(s) — e.g. `security/sandbox.py:134`, `tools/registry.py:187`
|
|
25
|
+
* The concrete trigger — not "could be a problem" — the exact call, config (`ToolPermissions.shell=True`, `providers.json` entry), and filesystem/network/model state that reaches it
|
|
26
|
+
* Whether you can reproduce it offline (`python -m pytest -q` or a minimal script) and the commit you tested against
|
|
27
|
+
* Impact — what an attacker gains (exfiltration, code execution, bypass of approval, etc.) and whether it needs a local `shell` opt-in or is reachable on a default install
|
|
28
|
+
|
|
29
|
+
A minimal reproduction is not required, but it makes triage much faster.
|
|
30
|
+
|
|
31
|
+
## What to expect
|
|
32
|
+
|
|
33
|
+
* **Acknowledgment** within **2 business days**.
|
|
34
|
+
* **Triage and initial assessment** within **7 days** — we will confirm severity (`S1`–`S4` per `#15` tracker), whether it is in scope, and whether we need more info.
|
|
35
|
+
* **Fix and disclosure** under **coordinated disclosure with a 90-day window**:
|
|
36
|
+
* We will develop and test a fix on a private branch.
|
|
37
|
+
* We will ship the fix to `main` and tag a release as soon as it is ready — often well before day 90.
|
|
38
|
+
* Public disclosure (advisory + `DEVLOG.md` entry + `tests/BREAKING_CHANGES.md` row) happens **7 days after a fix ships to main** (to allow users time to update), or **90 days after your initial report**, whichever comes first, unless extended by mutual agreement.
|
|
39
|
+
* If you prefer, you will be credited in the advisory and `DEVLOG.md`; if not, you will remain anonymous.
|
|
40
|
+
|
|
41
|
+
We will keep the private thread updated at least every 14 days until resolution.
|
|
42
|
+
|
|
43
|
+
## Scope
|
|
44
|
+
|
|
45
|
+
In scope (examples):
|
|
46
|
+
|
|
47
|
+
* Bypass of `security/permissions.py` / `safety/policy_enforcement.py` (approval, `is_tool_allowed`, `requires_approval`, `check_output_policy`, blocked domains, secret redaction)
|
|
48
|
+
* Sandbox escape or network egress from a tier that should not have it (`security/sandbox.py`, `security/capability.py`)
|
|
49
|
+
* Workspace trust boundary bypass (`core/workspace_trust.py`, `core/config_loader.py` tier precedence)
|
|
50
|
+
* Credential exfiltration via tool arguments/results, logs, or `param_digest` display
|
|
51
|
+
* MCP `autoApprove` / `mcp.json` trust bypass
|
|
52
|
+
|
|
53
|
+
Out of scope: social engineering, physical access, compromise of a provider's own API, vulnerabilities in upstream dependencies without a harness-specific trigger, or issues that require `tool_permissions.shell: true` together with `shell_approval_mode: never` *and* are already documented as deliberate. `README.md` § *"`shell` is classified, not just approved"* records that `never` "is the old unbounded behaviour, kept on purpose" — in that mode `cat ~/.aws/credentials` runs on the host unprompted, and reaching it takes writing the word `never` in `config.yaml`. We still want such a report, but it will be closed as documented risk. The same holds for `shell_approval_mode: contained` (§48, CE2), within its narrower scope: any command the container confines runs unprompted when it gets no network, code included, so what that code reads inside the workspace -- a `.venastine/` directory among it, when the workspace contains one -- and what it tries against the container boundary are documented risk. Network egress and reads outside the workspace still ask in that mode, and a report of either reaching a model unprompted is in scope.
|
|
54
|
+
|
|
55
|
+
The same applies to `allow_insecure_sandbox_fallback: true` **together with** `auto_approve_sandbox_fallback: true`. That pair is unprompted arbitrary code on the host, with your own file access, including writes into the harness's own source tree — and the harness ships as a folder of Python, so a run can edit the code the next run executes. It is not defended against, and the reason is that it cannot be: an uncontained host shell cannot be bounded from inside the same process. A path check stops `echo x > ../config.yaml` and a `python -c` payload walks straight past it, which is a control that reads as safety without being it. The container is the boundary, whether Docker or Podman runs it. `README.md` § *"`shell` is classified, not just approved"* states the same thing at the point of use.
|
|
56
|
+
|
|
57
|
+
**Since batch 40 these settings are read ONCE, at startup, into a frozen posture
|
|
58
|
+
(`security/posture.py`).** Before that they were read live at every decision, so
|
|
59
|
+
`config.SHELL_APPROVAL_MODE = "never"` -- a single attribute assignment -- turned the shell gate off
|
|
60
|
+
for the rest of the process from anywhere in it, and `os.environ["VENASTINE_REDACT_OFF"] = "1"` did
|
|
61
|
+
the same for credential redaction. The posture now cannot be changed by a tool call, a settings
|
|
62
|
+
file, an environment variable, model output, or a TUI command; each of those is pinned by a test in
|
|
63
|
+
`tests/test_posture.py`.
|
|
64
|
+
|
|
65
|
+
It **can** be changed by arbitrary in-process Python, which can also rebind the accessor itself. A
|
|
66
|
+
frozen dataclass raises where a bare assignment succeeded, which raises the bar without closing the
|
|
67
|
+
class. In scope: any route from model output or repository content to a changed posture. Out of
|
|
68
|
+
scope: "I achieved arbitrary code execution and then changed it", which is a report about the
|
|
69
|
+
execution.
|
|
70
|
+
|
|
71
|
+
Note that all of these settings live in `config.yaml` (`shell_approval_mode`, `tool_permissions`, and the two `*_sandbox_fallback` flags) — none has a `settings.json` key or an environment override, by design, and `config.yaml` itself has exactly one location and no override variable. Keys rather than line numbers because the three this sentence used to cite had all gone stale. What IS in scope, and was fixed rather than documented: a sandboxed command reaching the harness's install tree or `~/.config/venastine/` through the workspace mount (`security/protected_paths.py`), and any argument spelling that makes the classifier and the executor disagree about where a token ends. **That first claim is about the CONTAINER route, and it is stated narrowly on purpose:** a command running under the optional WSL backend (`allow_wsl_backend`, shipped off) reaches both -- measured, the harness's own `config.yaml` and `~/.config` are writable from the distribution -- which is why a WSL command naming a protected segment is refused outright rather than asked about, and why the backend is on the startup banner and the sidebar badge for as long as it is enabled.
|
|
72
|
+
|
|
73
|
+
**The project's `.venastine/` directory is guarded by `PROTECTED_SEGMENTS` (`security/protected_paths.py`), one list with three consumers.** The `read`/`write`/`edit` tools hard-refuse any path resolving into the segment — pre-approval via `refusal_check` and again in the handlers, whatever the approval booleans and the workspace boundary say. A shell command whose tokens name the segment always requires approval under `tiered` mode, before the fallback opt-in and the capability rule can answer for it; when approved it still runs contained, where the read-only bind of `.venastine/` (§28 G6) is the write backstop. What remains documented risk: the shell check is a token check and does not parse (G2), so a spelling carrying no literal segment — a glob prefix like `.ven*/settings.json`, or a variable assigned outside the checked tokens — is not caught by it; on the auto-approved INERT tier that cannot matter, because EP5 executes argv with no shell and the tokens are the arguments, and under the shipped `tiered` mode every tier that could expand one is asked about anyway. That last clause was false until §48 (CE1): a contained command was auto-approved, so `cat .ven*/settings.json; true`, or a `python -c` that opens the file, read it with no prompt. Under `contained` and `never` it is still not true -- such a command runs unasked, the read-only bind stops a write, and the read is documented risk. `SHELL_APPROVAL_MODE = "never"` remains the opt-out it always was, and MCP servers exposing their own file tools are a separate surface this list does not reach.
|
|
74
|
+
|
|
75
|
+
**WSL is an opt-in backend with no isolation, and is described as one (ROADMAP_v3 §49, slice 3).** With `allow_wsl_backend: true` the agent may ask for a command to run in a WSL distribution instead of the container, per call. It is not a weaker sandbox; it is the user's own machine with a Linux userland on it. Measured, and stated here rather than left to be discovered: the harness's own `config.yaml` is writable from there, `~/.config` is writable, there is no memory, CPU or process limit because those belong to the whole WSL VM, the network is always on, and Windows interop is a kernel feature that survives an emptied environment -- so a WSL command can start `cmd.exe` with the user's full Windows authority and no argv or environment choice prevents it. What the harness does hold: `containment_for` answers UNCONTAINED for every tier, so under `tiered` and `contained` only a read-only command whose every argument is inside the workspace runs without a prompt; a command naming a protected segment is REFUSED, not asked; the process is started with the scrubbed environment, which drops `WSLENV` and so stops the one mechanism that carries a named Windows variable's value into the distribution; and the workspace is translated by `wslpath` rather than by `wsl.exe --cd`, which answers an untranslatable path by exiting 0 and running somewhere else. In scope for a report: any route from model output to a WSL command that was not approved under these rules. Out of scope: that an approved WSL command can do what the user can do, which is what the backend is.
|
|
76
|
+
|
|
77
|
+
**SSH is an opt-in backend on a machine this harness cannot inspect, and NOTHING there runs without asking (ROADMAP_v3 §49, slice 4).** With `allow_ssh_backend: true` the agent may ask for a command to run on the one host configured in `config.yaml`, per call. The rule that makes it different from every other backend: no command is auto-approved on this route, not even a read-only one, and that is not caution but arithmetic -- the check that decides whether a command's arguments stay inside the workspace resolves them against the LOCAL filesystem, so on a remote it is answering a true question about the wrong machine. Slice 3 is the evidence for what such a check is worth: a path test that cannot resolve does not fail loudly, it approves confidently. What the harness holds: authentication is a key file or a running `ssh-agent` and **this harness never asks for, holds or stores a passphrase or password** (`BatchMode=yes` is passed for that reason -- measured, without it `ssh` waits indefinitely to prompt on a terminal this process does not own); the host key is PINNED in `config.yaml` and a key that CHANGES is refused rather than accepted; `-F none` stops the local `ssh` reading a per-user config that could carry `ProxyCommand` or `LocalCommand`, from a path this harness cannot redirect; the command crosses ONE quoting boundary and runs under `bash --norc --noprofile -c`; a command naming a protected segment is REFUSED, because `ssh localhost` is this machine and nothing here can tell that it is not; and the backend is on the startup banner and the sidebar badge for as long as it is enabled. Two behaviours are disclosed rather than fixed, both measured: **a kill does not reach the remote command** -- ending the local `ssh` leaves the far side running until its in-guest `timeout` fires, and the pty that would deliver a hangup also merges stderr into stdout and rewrites every line ending, so it is not used -- and **`write` saves locally while the shell runs remotely**, so a file the agent just wrote is not there. In scope for a report: any route from model output to an SSH command that ran without the approval these rules require. Out of scope: that an approved SSH command can do what the configured credentials can do, which is what the backend is. **Slice 5a amends one sentence of the above and nothing else:** the harness CAN now hold an SSH key passphrase and an account password, if you put them there -- see the paragraph below -- and when it does, `BatchMode=yes` is replaced by `SSH_ASKPASS_REQUIRE=force`, which keeps the same property by a different mechanism (every prompt goes to a helper that answers at once and cannot block). With nothing stored the connection is byte-for-byte what slice 4 shipped.
|
|
78
|
+
|
|
79
|
+
**The harness-held secret store is encrypted at rest and opened once per session (ROADMAP_v3 §49, slice 5a).** `/secrets` (or `--secrets` on the CLI) keeps named values -- an SSH key passphrase, an SSH account password, and from slice 5b a sudo password -- in `~/.config/venastine/secrets.json`, sealed with AES-256-GCM under a key derived from a master passphrase by scrypt. **What that defends against, precisely:** the AGENT reading the file. A shell command on WSL, on SSH or on the host fallback can `cat` it and gets ciphertext, which is the threat this harness actually has; it also survives a backup, a sync client or a stolen disk. An OS keystore was rejected for exactly the property that makes it convenient -- DPAPI and its siblings decrypt for any process running as you, and the agent's own shell is such a process. **What it does NOT defend against, stated because a half-understood control is worse than none:** arbitrary in-process Python, which this document already concedes defeats the frozen posture too; anything watching you type the passphrase; and a crash dump taken while the store is open -- the plaintext is held in a buffer that is zeroed on lock, but CPython hands out immutable copies nothing can reach, so that shortens a window rather than closing one, and it is measured rather than assumed. The plaintext is in process memory and nowhere else: never on disk, never in an environment variable, never in an argv, never in a log -- four properties with a test each. It is dropped on `/secrets lock`, on quit, when an exception escapes anything using a secret, when the askpass listener sees a token it did not mint or a prompt nobody measured, and when the file changes on disk underneath the process. A value the harness holds is stripped from tool output **whatever `redact_tool_outputs` says**, because that switch governs guesses about other people's credentials and this is the harness leaking its own. Reaching `ssh`, a secret crosses on a loopback connection authenticated by a single-use token rather than in `ssh`'s environment, which any process running as you can read; the honest limit is that someone able to read that environment gets the token and could then race the helper during one connection, which is narrower than a value sitting there at rest and is not a boundary. A stored credential the server REFUSES is quarantined for the rest of the run rather than retried, because one refused call makes two authentication attempts and retrying every command would walk a real account into a lockout. In scope for a report: any route by which a stored value reaches the model, the transcript, the database, a log or a subprocess environment. Out of scope: that someone who already runs code in this process can read what this process holds.
|
|
80
|
+
|
|
81
|
+
**The ChatGPT plan's sign-in holds bearer tokens on your own machine and nowhere else (ROADMAP_v3 §83).** OpenAI's page comes back to a one-shot listener on 127.0.0.1 that answers one path, only for the sign-in's own `state`, and never logs the request line the code arrives in. The code is traded with PKCE and no client secret, and the ID token is checked against OpenAI's published keys with the algorithm pinned to RS256 before any key is chosen. The tokens live in `chatgpt_auth.json` beside `providers.json`: 0600, written atomically, under an OS lock held across processes, because a refresh spends the token it replaces. `/disconnect chatgpt` revokes the refresh token at OpenAI, which ends the access token too (measured), and deletes both. No hosted deployment offers the sign-in. Since slice 2b the access token also goes to api.openai.com, as the bearer of each plan request, through the openai SDK pointed at that address alone -- never at the `API_URL` a hand edit could change -- and every request sends `store: false`.
|
|
82
|
+
|
|
83
|
+
**A command can be run as root, and every one of them asks you first (ROADMAP_v3 §49, slice 5b).** A tool call may set `needs_root`; the harness then prefixes `/usr/bin/sudo -k -S -p '' --` and supplies the password stored for that machine. **It runs on WSL and over SSH and nowhere else.** The container is refused because a command there ALREADY runs as root and the image ships no `sudo` at all, so a prompt would be about a privilege the command already has; the host fallback is refused because on Windows `sudo.exe` elevates through a UAC consent dialog that cannot take a password on stdin, which is a different mechanism and a separate measurement rather than an assumption. **A root command always meets a human**, above both opt-ins and in every approval mode but `never` -- and that is a correction rather than a restatement, because the gate was measured auto-approving `sudo apt-get install` on WSL whenever `auto_approve_sandbox_fallback` was on. The step fires on the declaration OR on the command naming `sudo`, `doas`, `pkexec` or `su`, since a model that types `sudo` itself never sets the flag; it is a token check and refuses to parse, so a command that merely mentions the word costs one prompt. **The password goes on stdin and nowhere else** -- not in an argv, not in an environment, not in a log, not in the result, each asserted against a real run -- and the command behind `sudo` cannot read it either, because its stdin is explicitly closed. That last control is there because of a measurement and not a theory: `sudo -S` reads stdin only when it must authenticate, so on a host with a passwordless rule it reads nothing and the password would be the command's own input. That was reproduced on two different `sudo` implementations, with the `-k` flag and without it, which is also why `-k` is documented as buying one authentication per approval and nothing more. **If no password is stored for that machine the call is refused outright**, naming the entry to create: the stored secret is what turns root on at all, and there is deliberately no separate config flag for it. A refused password is not retried for the rest of the run, because `sudo` allows three attempts a call and a retrying agent could walk a real account into a lockout on a host that counts them. In scope for a report: any route by which a root command runs without a human answering, or by which the sudo password reaches the model, a log, an argv or a command's input. Out of scope: what root can do on a machine once you have approved it -- that is the privilege you granted, and the prompt says so in those words.
|
|
84
|
+
|
|
85
|
+
**Background sessions (ROADMAP_v3 §49) run under the same gate and the same backends as `shell`.** A session is a shell command that outlives the call which started it, so it is classified, approved and routed by exactly the rules above: `shell_background` and `shell_monitor` are registered with `shell`'s own approval check, and `tool_approvals` has no key for either, for the reason it has none for `shell`. Three properties are worth stating because they are what a long-lived command adds. **Session output is kept in memory only** -- a first and a last span of characters, with the middle dropped and reported as a gap -- and never written to disk, because program output can carry secrets, redaction is pattern-based, and a file would be a durable copy of whatever the patterns miss. **A session's container carries a label naming the process that started it and an in-container `timeout`**, so it dies with its harness, or shortly after it when the harness dies first, and one instance's exit cleanup cannot reach another's containers. **And a session can only be started by a run something will wake when it reports** — a chat turn or a subagent — which is what stops an unattended research pass starting work that nothing would ever report, read or stop.
|
|
86
|
+
|
|
87
|
+
**The hosted demo runs every visitor in ONE container as ONE Unix user, and its defences are written against that (ROADMAP_v3 §79).** On a ZeroGPU Space that user is root -- measured in batch 165, with Docker's default capabilities less `NET_RAW` -- so the bridge gives each browser tab its own process, session directory, database, log, workspace and credential file, built from an allowlisted environment that never carries the deployment's own secrets, and deletes the directory when the tab closes -- or, when a bridge was killed before it could, the next bridge deletes it before it listens (batch 168). Three things then stand between one visitor and another's session. **No tool in a shared deployment can reach the container**: `read`, `write`, `edit`, `view_image` (batch 174) and every shell tool ship disabled, and with `VENASTINE_HOSTED=shared` `is_tool_allowed` refuses them a second time whatever `config.yaml` says, so a deployment configured wrongly is still not a shell; `/config`, which writes the one `config.yaml` every session reads, is refused too, and so is `/secrets`, whose SSH and sudo passwords serve only the tools refused above (batch 168). **A credential is held in memory, never on disk**: a shared deployment takes only a sign-in -- Hugging Face's, OpenRouter's, and ModelScope's where its bridge can complete it -- scoped and revocable at the provider, and refuses a pasted key -- not for want of a safe place to hold one, but because a pasted key is usually the account's own, unscoped and unexpiring, handed to a server its owner cannot inspect, on a page anyone can duplicate to look the same; the refusal names the installed harness and a private single-user duplicate as the places a key belongs (§79 HD12). **A session's memory is not readable by its neighbours**: every hosted session process calls `prctl(PR_SET_DUMPABLE, 0)` first, and measured under WSL, a sibling process of the same user that could read an ordinary process's `/proc/<pid>/environ` -- secret included -- was refused the same read once the target had made that call. `VENASTINE_HOSTED` is an environment variable that can only take capability AWAY -- unset is a local install, an unrecognised value is `shared` -- so the posture above still cannot be WEAKENED by one, and a `.env` cannot set it (A70). **A private single-user deployment is the opposite on purpose**: it enables `read`, `write`, `edit` and `shell` with the host fallback, because the container is that person's own sandbox, and it is honoured only while the app does not answer an anonymous request -- made public, it refuses every session. The privacy gate accepts only a 401/403/404 access denial without the public health marker; redirects, rate limits, startup/proxy errors and unmarked 200 pages are indeterminate and refuse, including while cached (batches 193 and 194). In scope: any route by which one visitor's session reaches another's files, memory, credentials or conversation; any route from model output or repository content to a container-reaching tool in a shared deployment; a single-user deployment that runs while publicly reachable. Out of scope: the operator of a deployment reading what it holds -- whoever controls the Space or Studio controls the code beside every live session, and §79 says so -- and anything that first requires code execution in the container, which is a report about the execution -- with the one exception the next paragraph is about.
|
|
88
|
+
|
|
89
|
+
**The math tools are the one place a shared deployment evaluates what a visitor sends, and they run walled in (ROADMAP_v3 §79, HD11).** SymPy's parser ends in `eval`, and in a shared demo the visitor connects and prompts their own model, so they choose every expression the six math tools are handed. `_validate_ast` admits only an allowlist of expression node types over a closed list of SymPy names, with attribute access refused outright, and that guard is the lock. Behind it, the child each call already ran in walls itself in after importing SymPy and before reading the expression (`security/confine.py`): no file may grow past the cap on the two output files the child is handed, and the process is non-dumpable; a child started as root becomes `nobody`, losing `DAC_OVERRIDE`, the capability that lets root read a 0700 directory it does not own; Landlock lets it read beneath the interpreter's import roots and nothing else -- no other session's directory, no `/tmp`, no `/proc`, no write anywhere, and on the Space's ABI 7 no TCP and no signal out; and a seccomp filter answers `fork`, `exec`, sockets, signals, `ptrace`, privilege changes, mounts and the kernel's control surfaces with `EPERM`. A wall that will not go up means the call does not run. The bridge proves the walls at every start with a self-test that computes an integral behind them and then tries every one of those escapes, and only a clean pass lets its sessions run the math tools; without one they are refused like the container tools. Measured on the Space before it was relied on, and the root measurement is also why HD6 still holds there: reading a non-dumpable process takes `CAP_SYS_PTRACE`, which the Space does not grant to root. **What this does not cover:** a kernel exploit from inside the child, and CPU or memory spent within the bounds every math call already has (H3: 20 s of CPU and 2 GB). On a ModelScope Studio there is no Landlock (Alibaba's 5.10 kernel, measured in batch 166), so the self-test fails and a shared Studio refuses the six tools. Two more things a shared server changes: session creation is rate-limited on the `X-Forwarded-For` entry each platform's proxy writes itself -- the last on Hugging Face, which appends to the client's header, and the first on ModelScope, which replaces it and adds its own hops after (both measured with a hand-written TEST-NET-2 entry); and `fetch_url`'s recorded DNS-rebinding limit (`is_url_permitted`'s docstring) reaches the container's own network there, where the bridge's routes still need a one-time ticket or a download key. In scope: any route by which a math call's child reads, writes, connects, signals or starts anything; a shared deployment that runs the math tools without a verified self-test; and any way to make the rate limit count a different address than the proxy's.
|
|
90
|
+
|
|
91
|
+
**The bridge holds the only secrets of its own -- a ModelScope OAuth app's, one for each ModelScope site -- and completes that site's sign-in with it (ROADMAP_v3 §79, HD13).** ModelScope's token endpoint accepts only a confidential client, so a local install never signs in to ModelScope (it takes a pasted key), and a deployment that sets `VENASTINE_MODELSCOPE_CLIENT_SECRET` (modelscope.ai) or `VENASTINE_MODELSCOPE_CN_CLIENT_SECRET` (modelscope.cn, a separate site with separate accounts, batch 176) signs in to that site through its bridge -- and on a ModelScope Studio whose OAuth settings are on, the app ModelScope creates for the Studio takes the modelscope.ai sign-in, its secret arriving as `OAUTH_CLIENT_SECRET` (batch 177). Each site's endpoints are read from its discovery document at start, always over https -- the Studio injects its provider as plain http (batch 178) -- and must be https on its issuer's host. Each sign-in has its own callback path, so a code reaches only the flows of the site that issued it, and a session waits on one site at a time. The bridge takes every such secret, the Studio's included, out of its environment before it starts anything, so no child inherits it -- not the session environment's build, not the isolation probes -- and then marks itself non-dumpable, so a session running as the same user cannot read the bridge's memory or the environment block it started with; a session's own environment is an allowlist that never carried it. A sign-in's state is 256 random bits bound to the session that asked, spent at its first use and void after ten minutes. ModelScope's redirect gets a page carrying only a one-time handle -- nothing the request carried is repeated, and the page is `no-store` and `no-referrer`, runs nothing, and may be framed only by the platform's own site, which frames every page of the app -- and the handle is redeemed only by the session that started the flow, five tries at most. That copy step is the defence against the attack an automatic delivery would invite: a sign-in someone else started and sent you gives you a handle for their session, which you have no way to paste into. The trade refuses an `error` even in an HTTP 200, and a token granted without the `api-inference` scope; the refresh and id tokens are dropped, and no log line names the state, the code, the handle, the token or the secret. **Noted, not changed:** Hugging Face's device code flow has the remote-phishing exposure RFC 8628 §5.4 describes -- someone can start a sign-in and send you its code -- and Hugging Face's own consent page, which names the app, is what stands against it. In scope: any route by which a client secret reaches a session, a log, a page or the other site; a code traded with a site other than the one that issued it; a handle redeemed by a session other than the one that started its flow; a token delivered for a state the bridge did not issue.
|
|
92
|
+
|
|
93
|
+
**What the hosted demo runs is a commit of `main` that passed every CI check, and the deploy holds one token (ROADMAP_v3 §79, HD9, amended in batch 169).** `.github/workflows/deploy-demo.yml` deploys the Hugging Face Space only after `scripts/deploy_gate.py` has read GitHub's record of the commit and found every check run on it success or skipped -- including a job its workflow lets fail and a scheduled run on the same commit -- every workflow a push to `main` runs passed, and the commit still `main`'s tip. The gate's job holds no secret; the deploy job is the only one in the `demo` environment, which holds `HF_TOKEN` (fine-grained, write access to the one Space) and releases it to `main` only. A `workflow_run` job's `github.ref` is always the default branch, so the gate itself refuses anything but a push to `main` in this repository -- a fork's pull request from a branch named `main` included -- and no event value is pasted into a shell line. Before anything is sent, the bundle is scanned by gitleaks from its own root and its locks audited by pip-audit; a finding is accepted only by ID, with its reason, while its version is pinned. The ModelScope Studio is deployed by the owner with the same script and gate, because ModelScope's tokens are account-wide and it offers no trusted CI. **Whoever can merge to `main` decides the code that runs beside every live visitor's sign-in.** And no code scanning alert of security severity high or critical may be open on `main` (batch 170): CodeQL on a push uploads its alerts and fails nothing -- the `CodeQL` check is posted on pull requests only -- so the gate reads the alerts itself, and an alert list it cannot read stops the deploy.
|
|
94
|
+
|
|
95
|
+
## No bounty
|
|
96
|
+
|
|
97
|
+
This is an independent research project with no funding — **we cannot offer monetary rewards, bounties, or swag.** We will credit you publicly if you want, and we will prioritize a fix. If you need a bounty, please use a third-party program that covers this repo, or treat the report as a voluntary disclosure.
|
|
98
|
+
|
|
99
|
+
## Disclosure and credit
|
|
100
|
+
|
|
101
|
+
* We will publish a GitHub Security Advisory (GHSA) 7 days after the fix ships to main (or at the 90-day mark), requesting a CVE if the severity warrants it.
|
|
102
|
+
* We will not disclose your identity without permission.
|
|
103
|
+
* Please do not disclose the issue publicly (including in a fork, gist, or write-up) before public disclosure or advisory publication — this protects users who have not yet updated.
|
|
104
|
+
|
|
105
|
+
## Questions
|
|
106
|
+
|
|
107
|
+
For non-sensitive questions about this policy, open a regular issue. For sensitive details, use the private channel above.
|
|
108
|
+
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
# Third-Party Notices
|
|
2
|
+
|
|
3
|
+
This project is licensed under the **Apache License 2.0** — see [LICENSE](./LICENSE) and [NOTICE](./NOTICE) (Copyright 2026 Yahya Hammad).
|
|
4
|
+
|
|
5
|
+
The dependencies listed below are **not** part of the project's own source but are required at install/runtime. All are permissive and **Apache-2.0 compatible**; the assessment was made on 2026-08-27, and re-read from each package's own metadata for batch 234's pins on 2026-11-04, when `anthropic` 2.0 moved from MIT to Apache-2.0. This file records it so a scanner or reviewer does not have to re-derive it.
|
|
6
|
+
|
|
7
|
+
> **Scope.** Two things are covered here: the project's **declared direct** dependencies — the pins in `requirements.txt` and the extras in `pyproject.toml` — and, under *Non-code third-party material* below, the third-party **text** the repository reproduces.
|
|
8
|
+
>
|
|
9
|
+
> The transitive dependency closure is *not* enumerated: `sympy` pulls `mpmath`, `sqlmodel` pulls SQLAlchemy, and `mcp==2.3.0` brings `httpx2` (BSD-3-Clause), as `anthropic` and `openai` do since batch 234 (see the note beside the `mcp` pin in `requirements.txt`). Until batch 212 `matplotlib` was here too, pulling numpy, kiwisolver, fonttools and pillow; the confidence chart is drawn as SVG with the standard library now, and none of them is installed. For the full closure, run `pip-licenses` against a resolved environment — see *How to regenerate* below.
|
|
10
|
+
|
|
11
|
+
> Versions shown are the pins from `requirements.txt` / `pyproject.toml` at the time this file was created. Where a range is used (e.g. `rich>=14.2,<16`) the exact resolved version will vary.
|
|
12
|
+
|
|
13
|
+
## Runtime / core dependencies
|
|
14
|
+
|
|
15
|
+
| Package | Version (as pinned) | Primary License | Apache 2.0 Compatible | Source |
|
|
16
|
+
|---|---|---|---|---|
|
|
17
|
+
| anthropic | `==2.1.0` | Apache-2.0 (MIT through 0.x; 2.0 relicensed) | Yes | https://pypi.org/project/anthropic/ |
|
|
18
|
+
| ddgs | `==9.16.0` | MIT | Yes | https://pypi.org/project/ddgs/ |
|
|
19
|
+
| httpx | `==0.28.1` | BSD-3-Clause | Yes | https://pypi.org/project/httpx/ |
|
|
20
|
+
| openai | `==3.36.0` | Apache-2.0 | Yes | https://pypi.org/project/openai/ |
|
|
21
|
+
| google-genai | `==2.32.0` | Apache-2.0 | Yes | https://pypi.org/project/google-genai/ |
|
|
22
|
+
| pydantic | `==2.14.1` | MIT | Yes | https://pypi.org/project/pydantic/ |
|
|
23
|
+
| sympy | `==1.14.0` | BSD-3-Clause | Yes | https://pypi.org/project/sympy/ |
|
|
24
|
+
| sqlmodel | `==0.0.48` | MIT | Yes | https://pypi.org/project/sqlmodel/ |
|
|
25
|
+
| python-dotenv | `==1.2.4` | BSD-3-Clause | Yes | https://pypi.org/project/python-dotenv/ |
|
|
26
|
+
| pyyaml | `==6.0.3` | MIT | Yes | https://pypi.org/project/PyYAML/ |
|
|
27
|
+
| ruamel.yaml | `==0.19.1` | MIT | Yes | https://pypi.org/project/ruamel.yaml/ |
|
|
28
|
+
| textual | `==8.2.8` | MIT | Yes | https://pypi.org/project/textual/ |
|
|
29
|
+
| rich | `>=14.2,<16` | MIT | Yes | https://pypi.org/project/rich/ |
|
|
30
|
+
| mcp | `==2.3.0` | MIT | Yes | https://pypi.org/project/mcp/ |
|
|
31
|
+
| google-re2 | `==1.1.20251105` | BSD-3-Clause | Yes | https://pypi.org/project/google-re2/ |
|
|
32
|
+
| cryptography | `>=50.0.0,<52` | Apache-2.0 OR BSD-3-Clause | Yes | https://pypi.org/project/cryptography/ |
|
|
33
|
+
| PyJWT | `>=2.15.0,<3` | MIT | Yes | https://pypi.org/project/PyJWT/ |
|
|
34
|
+
|
|
35
|
+
`google-re2` (added 2026-09-15, ROADMAP_v3 §49) and `cryptography` (added 2026-09-24, ROADMAP_v3 §49 slice 5a) are the dependencies above that ship **compiled native code**. Taking `google-re2` first: its wheels carry the RE2 C++ library (BSD-3-Clause) and, as RE2 depends on it, Abseil (Apache-2.0). The paragraph under *What this means* holds for it unchanged — pip fetches the wheel onto the user's machine and this project redistributes nothing — so no inbound `NOTICE` obligation arises. Where no wheel exists (musl/Alpine, glibc older than 2.28), pip builds the source distribution locally, which is the user's build rather than a distribution by this project.
|
|
36
|
+
|
|
37
|
+
`cryptography` was **already in the install closure** before it was declared — `google-genai==1.0.0` → `google-auth>=2.14.1` → `cryptography>=38.0.3`, with no extra marker (re-measured on the 2.29.0 pin in batch 172: `google-auth>=2.56.0` → `cryptography>=38.0.3`, still unmarked) — so declaring it added no package to an install and no licence surface that was not already present; it made an existing transitive dependency into a pinned direct one, because the harness-held secret store (ROADMAP_v3 §49 slice 5a, SS57) rests on it. Its wheels carry a **Rust** extension and a statically linked **OpenSSL** (Apache-2.0); the dual licence above is the project's own, and the paragraph under *What this means* holds for it unchanged — pip fetches the wheel onto the user's machine and this project redistributes nothing, so no inbound `NOTICE` obligation arises. Wheels exist for CPython 3.7+ on Windows (x64, x86), macOS (arm64, x86_64) and manylinux/musllinux (x86_64, aarch64); where none does, pip builds the sdist locally and needs a Rust toolchain, which is the user's build rather than a distribution by this project.
|
|
38
|
+
|
|
39
|
+
`pillow` was declared on 2026-10-28 (batch 201), as a floor under what `matplotlib` pulled in, and removed with `matplotlib` in batch 212: nothing the harness installs reaches it now. The hosted demo's Gradio bridge still installs it, in an environment of its own (`deploy/hosted/requirements.txt`).
|
|
40
|
+
|
|
41
|
+
## Test dependencies (not used by end users during runtime, only for CI and developer testing)
|
|
42
|
+
|
|
43
|
+
| Package | Version (as pinned) | Primary License | Apache 2.0 Compatible |
|
|
44
|
+
|---|---|---|---|
|
|
45
|
+
| pytest | `>=8.0` | MIT | Yes |
|
|
46
|
+
| pytest-mock | `>=3.14` | MIT | Yes |
|
|
47
|
+
| pytest-asyncio | `>=1.0` | Apache-2.0 | Yes |
|
|
48
|
+
| pytest-xdist | `>=3.6` | MIT | Yes |
|
|
49
|
+
| execnet | transitive (via `pytest-xdist`) | MIT | Yes |
|
|
50
|
+
|
|
51
|
+
`execnet` is listed although nothing declares it: it is `pytest-xdist`'s only dependency and the process that actually runs each worker, so a reader auditing what a `pip install -r requirements.txt` puts on the machine would otherwise have to go and find it. Both are permissive, so the no-copyleft claim under *What this means* is unchanged.
|
|
52
|
+
|
|
53
|
+
## Optional dependencies (`pyproject.toml` extras)
|
|
54
|
+
|
|
55
|
+
| Package | Version (as pinned) | Primary License | Apache 2.0 Compatible | Notes |
|
|
56
|
+
|---|---|---|---|---|
|
|
57
|
+
| markitdown | `==0.1.9` (extra `documents`) | MIT | Yes | Permissive; only reachable behind `read`/`write`/`edit` (globally denied). |
|
|
58
|
+
| protobuf | `==7.36.2` (extra `documents`) | BSD-3-Clause / Apache-2.0 | Yes | Permissive; transitive via `markitdown`→`onnxruntime`. |
|
|
59
|
+
| markdown | unpinned (extra `pdf`) | BSD-3-Clause | Yes | Permissive |
|
|
60
|
+
| weasyprint | unpinned (extra `pdf`) | BSD-3-Clause (package) | Yes (with caveats) | Package itself BSD-3-Clause; transitive deps include LGPL (e.g. `pango`/`cairo` via system libs). See weasyprint docs. |
|
|
61
|
+
|
|
62
|
+
`weasyprint` is BSD-3-Clause itself; the caveat is its **system** dependencies (`pango`, `cairo`, `harfbuzz`), which are LGPL and are linked at runtime rather than vendored into this project. If `markdown` or `weasyprint` is later pinned, update the version column above.
|
|
63
|
+
|
|
64
|
+
## Hosted demo (`deploy/`, ROADMAP_v3 §79)
|
|
65
|
+
|
|
66
|
+
What the bridge -- the process that serves a Space's or Studio's page and relays each session -- runs beside Gradio. None of it is installed by `pip install` or npm: `deploy/` ships in neither, and a deployment installs these from PyPI when the platform builds it, so nothing here is redistributed. Licences read from each version's PyPI metadata (2026-10-23).
|
|
67
|
+
|
|
68
|
+
| Package | Version (as pinned) | Primary License | Apache 2.0 Compatible | Where |
|
|
69
|
+
|---|---|---|---|---|
|
|
70
|
+
| textual-serve | `==1.1.3` | MIT | Yes | `deploy/hosted/requirements.txt`; its browser assets only, its server never runs |
|
|
71
|
+
| uv | `==0.13.4` | MIT OR Apache-2.0 | Yes | `deploy/hosted/requirements.txt`; builds the session environment |
|
|
72
|
+
| websockets | `==17.3` | BSD-3-Clause | Yes | `deploy/hosted/requirements.txt`; the websocket upgrade every session is |
|
|
73
|
+
| gradio | `==6.30.0` | Apache-2.0 | Yes | installed by the Space at the README's `sdk_version`; in the Studio's `bridge.lock` |
|
|
74
|
+
| spaces | `==0.51.3` | Apache-2.0 | Yes | installed by the Space itself; in the Studio's `bridge.lock` |
|
|
75
|
+
|
|
76
|
+
## Deploy tooling (CI only)
|
|
77
|
+
|
|
78
|
+
Installed by `.github/workflows/deploy-demo.yml` to build, audit and upload a bundle (batch 169), and by the owner to deploy the Studio by hand. Never part of any install or bundle.
|
|
79
|
+
|
|
80
|
+
| Package | Version (as pinned) | Primary License | Apache 2.0 Compatible |
|
|
81
|
+
|---|---|---|---|
|
|
82
|
+
| huggingface_hub | `==2.2.0` | Apache-2.0 | Yes |
|
|
83
|
+
| pip-audit | `==2.10.1` | Apache-2.0 | Yes |
|
|
84
|
+
|
|
85
|
+
## Non-code third-party material
|
|
86
|
+
|
|
87
|
+
**No third-party source code is included in this repository.** Measured, not assumed: all 277 tracked
|
|
88
|
+
Python files carry no foreign copyright header and no `SPDX-License-Identifier`; a sweep for
|
|
89
|
+
copied or adapted code ("adapted from", "copied from", "taken from", "vendored", "borrowed from")
|
|
90
|
+
returns only this project's own design prose; and the 45 tracked files that are neither `.py`
|
|
91
|
+
nor `.md` are first-party without exception — the licence texts, configuration and packaging
|
|
92
|
+
(`config.yaml`, `pyproject.toml`, the three requirements files, `package.json`, `pytest.ini`, the
|
|
93
|
+
`.github/` workflows, issue templates and scanner configuration, the dotfiles), the two prompt
|
|
94
|
+
texts, `bin/venastine.mjs` and `scripts/prepublish-check.mjs`, `docs/assets/research-mode-birds-eye.mermaid`,
|
|
95
|
+
`tui/app.tcss`, the two `.example` templates, the hosted demo's four page templates in
|
|
96
|
+
`deploy/hosted/`, one screenshot of this project's own interface, and its cover image with the
|
|
97
|
+
page it is rendered from. **No third-party fonts, images or data files are bundled.** The
|
|
98
|
+
cover's text is set in Cascadia Mono, Microsoft's font under the SIL Open Font License: the PNG
|
|
99
|
+
holds rendered glyphs, and its page names the font, and neither carries a copy of it.
|
|
100
|
+
|
|
101
|
+
*(Counts restated in batch 83. The figure had been 166 against 200, the enumeration named
|
|
102
|
+
five of the thirty-four, and the closing sentence said there were no images at all while the
|
|
103
|
+
screenshot was tracked. The claim itself held throughout; only its arithmetic had drifted.)*
|
|
104
|
+
|
|
105
|
+
*(Restated again in batch 198, when the cover joined: 200 and 34 had become 277 and 43 as the
|
|
106
|
+
project grew. Both sweeps were run again and found nothing new, and every file added since
|
|
107
|
+
batch 83 is first-party.)*
|
|
108
|
+
|
|
109
|
+
What the repository *does* reproduce is third-party **text**:
|
|
110
|
+
|
|
111
|
+
| Material | Where it lives | Origin | Licensing |
|
|
112
|
+
|---|---|---|---|
|
|
113
|
+
| **Contributor Covenant, v2.1** | `CODE_OF_CONDUCT.md` (adapted — contact details and enforcement channel are ours) | Authored 2014 by Coraline Ada Ehmke, with later collaborative contributions. https://www.contributor-covenant.org/version/2/1/code_of_conduct.html | **Not stated by upstream** for the document text — see the note below |
|
|
114
|
+
| **Mozilla's CoC enforcement ladder** | Inspiration for the *Enforcement Guidelines* section of `CODE_OF_CONDUCT.md`, credited there per the Covenant's own boilerplate | https://github.com/mozilla/diversity | GitHub reports the repository as **MPL-2.0** |
|
|
115
|
+
| **Apache License 2.0 text** | `LICENSE` | https://www.apache.org/licenses/LICENSE-2.0 | Reproduced verbatim, which is what the licence itself directs; the appendix boilerplate is filled in with this project's copyright |
|
|
116
|
+
|
|
117
|
+
> **On the Covenant's licence.** Upstream does not publish an explicit licence for the Code of
|
|
118
|
+
> Conduct *text*. Three sources were checked on 2026-08-27: the project's `LICENSE.md`
|
|
119
|
+
> (`EthicalSource/contributor_covenant`) states the **Hippocratic License 3.0**, which covers the
|
|
120
|
+
> site and its code; the contributor-covenant.org footer carries a copyright line and no licence
|
|
121
|
+
> statement; and the raw `content/version/2/1/code_of_conduct.md` carries none either.
|
|
122
|
+
>
|
|
123
|
+
> **No licence identifier is asserted here on the Covenant's behalf.** The attribution block kept
|
|
124
|
+
> in `CODE_OF_CONDUCT.md` — naming the work, its version, its source URL, and the fact that it is
|
|
125
|
+
> *adapted* — is verbatim the attribution upstream prescribes in its own boilerplate, and is the
|
|
126
|
+
> best available evidence of what they ask adopters to provide. If you need certainty for a
|
|
127
|
+
> compliance review, ask upstream rather than inferring from this file.
|
|
128
|
+
|
|
129
|
+
## What this means
|
|
130
|
+
|
|
131
|
+
* All licenses **listed above** are **permissive** (MIT / BSD-3-Clause / PSF / Apache-2.0). None are copyleft (GPL/AGPL) and none impose source-disclosure on this Apache-2.0 work. This is a statement about the direct dependencies in the tables, not about the full transitive closure — see *Scope* at the top.
|
|
132
|
+
* This project does not redistribute any of them. It is distributed as **source** — a `git` checkout or the npm package `@yahyahammad/venastine`, which is the same folder of first-party files — and `pip` fetches each dependency from PyPI, onto the user's machine, under its own license. **No inbound `NOTICE` obligation therefore arises** — nothing here carries an upstream NOTICE that this project must propagate. The trigger is **redistribution**, not source-vs-binary, and not which channel delivered the source; if a build that vendors these packages is ever distributed, ship their `LICENSE` and `NOTICE` files as received (Apache-2.0 §4(d) applies to `openai`, `google-genai` and `pytest-asyncio`). **The npm tarball must therefore never carry wheels** — that is the one change that would turn this paragraph false, and `CONTRIBUTING.md` records it as a rule.
|
|
133
|
+
* **The npm channel adds no third-party licence surface at all.** Its launcher (`bin/venastine.mjs`) is Node standard library only, with an empty `dependencies` block, so an install of this package fetches no JavaScript code from anyone. What the tarball contains is the first-party source listed under `files` in `package.json`, plus `LICENSE`, `NOTICE` and this file. Publishing *is* distribution of the Work under Apache-2.0 §4 where running from a checkout was not, which is why those three are in the allowlist rather than left to chance: npm auto-includes `LICENSE` and does **not** auto-include `NOTICE`.
|
|
134
|
+
* The [NOTICE](./NOTICE) file this project publishes is therefore **voluntary**, not required. Apache-2.0 §4(d) obliges you to propagate a NOTICE you *received*; it does not oblige a licensor to author one. It exists because scanners and reviewers look for it and because it gives the copyright assertion a canonical home — and it is kept minimal on purpose, since anyone who redistributes this work must carry its contents forward.
|
|
135
|
+
* Full license texts: `pip show <package>` or `pip-licenses --format plain --with-urls`, or the PyPI links above.
|
|
136
|
+
|
|
137
|
+
## How to regenerate
|
|
138
|
+
|
|
139
|
+
```bash
|
|
140
|
+
pip-licenses --format markdown --with-urls --with-license-file
|
|
141
|
+
# or
|
|
142
|
+
pip install pip-licenses && pip-licenses --format plain
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
When a dependency is added or re-pinned, add a row here with its SPDX identifier and re-check the `Apache 2.0 Compatible` column. CI does not enforce this file today — it is documentation for reviewers.
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
*Last updated: 2026-08-27. If any row's upstream re-licenses, this file must be updated.*
|
package/env_secrets.py
CHANGED
|
@@ -1,77 +1,118 @@
|
|
|
1
|
-
"""
|
|
2
|
-
env_secrets.py
|
|
3
|
-
|
|
4
|
-
Miscellaneous API keys for individual TOOLS (e.g. a GitHub token, an
|
|
5
|
-
NVD/NIST API key) -- NOT LLM provider keys. Loaded from a .env file via
|
|
6
|
-
python-dotenv.
|
|
7
|
-
|
|
8
|
-
This is deliberately separate from credentials.py. The distinction:
|
|
9
|
-
|
|
10
|
-
credentials.py -- LLM PROVIDER keys (OpenAI, Anthropic, ...). Structured
|
|
11
|
-
per-provider (URL + key + compatibility flag), stored
|
|
12
|
-
in providers.json, read/written through
|
|
13
|
-
load_provider_data()/save_credentials().
|
|
14
|
-
|
|
15
|
-
env_secrets.py -- Flat, single-value secrets that one specific TOOL
|
|
16
|
-
needs to call some third-party API. No structure
|
|
17
|
-
beyond name -> value, stored in .env (never committed
|
|
18
|
-
-- see .gitignore), read through get_env_secret().
|
|
19
|
-
|
|
20
|
-
If you're adding a new tool that needs its own API key (a weather API, a
|
|
21
|
-
GitHub token, an NVD key, etc.), it belongs here, not in credentials.py or
|
|
22
|
-
providers.json -- those are exclusively for the LLM provider abstraction
|
|
23
|
-
in core/client.py.
|
|
24
|
-
"""
|
|
25
|
-
|
|
26
|
-
import os
|
|
27
|
-
|
|
28
|
-
from dotenv import
|
|
29
|
-
|
|
30
|
-
# Batch 35. Resolved at IMPORT time like credentials.LLM_PROVIDERS_FILE and
|
|
31
|
-
# for the same reason -- a test can monkeypatch the attribute, and a user can
|
|
32
|
-
# point it anywhere before launch.
|
|
33
|
-
#
|
|
34
|
-
#
|
|
35
|
-
#
|
|
36
|
-
#
|
|
37
|
-
#
|
|
38
|
-
#
|
|
39
|
-
#
|
|
40
|
-
#
|
|
41
|
-
#
|
|
42
|
-
# the
|
|
43
|
-
#
|
|
44
|
-
#
|
|
45
|
-
#
|
|
46
|
-
#
|
|
47
|
-
#
|
|
48
|
-
#
|
|
49
|
-
#
|
|
50
|
-
#
|
|
51
|
-
#
|
|
52
|
-
#
|
|
53
|
-
#
|
|
54
|
-
#
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
1
|
+
"""
|
|
2
|
+
env_secrets.py
|
|
3
|
+
|
|
4
|
+
Miscellaneous API keys for individual TOOLS (e.g. a GitHub token, an
|
|
5
|
+
NVD/NIST API key) -- NOT LLM provider keys. Loaded from a .env file via
|
|
6
|
+
python-dotenv.
|
|
7
|
+
|
|
8
|
+
This is deliberately separate from credentials.py. The distinction:
|
|
9
|
+
|
|
10
|
+
credentials.py -- LLM PROVIDER keys (OpenAI, Anthropic, ...). Structured
|
|
11
|
+
per-provider (URL + key + compatibility flag), stored
|
|
12
|
+
in providers.json, read/written through
|
|
13
|
+
load_provider_data()/save_credentials().
|
|
14
|
+
|
|
15
|
+
env_secrets.py -- Flat, single-value secrets that one specific TOOL
|
|
16
|
+
needs to call some third-party API. No structure
|
|
17
|
+
beyond name -> value, stored in .env (never committed
|
|
18
|
+
-- see .gitignore), read through get_env_secret().
|
|
19
|
+
|
|
20
|
+
If you're adding a new tool that needs its own API key (a weather API, a
|
|
21
|
+
GitHub token, an NVD key, etc.), it belongs here, not in credentials.py or
|
|
22
|
+
providers.json -- those are exclusively for the LLM provider abstraction
|
|
23
|
+
in core/client.py.
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
import os
|
|
27
|
+
|
|
28
|
+
from dotenv import dotenv_values, find_dotenv
|
|
29
|
+
|
|
30
|
+
# Batch 35. Resolved at IMPORT time like credentials.LLM_PROVIDERS_FILE and
|
|
31
|
+
# for the same reason -- a test can monkeypatch the attribute, and a user can
|
|
32
|
+
# point it anywhere before launch. Reading the variable is all that happens
|
|
33
|
+
# at import; the FILE is read by `_file_values()`, at the point of use.
|
|
34
|
+
#
|
|
35
|
+
# THE usecwd=True IS LOAD-BEARING, not a style choice. A bare find_dotenv()
|
|
36
|
+
# is find_dotenv(usecwd=False), which walks up from THE CALLING FRAME'S
|
|
37
|
+
# FILE -- this module -- and not from the working directory. In a checkout
|
|
38
|
+
# those are the same directory, which is the only reason this has ever looked
|
|
39
|
+
# like cwd resolution. Install the harness anywhere else (npm puts it under
|
|
40
|
+
# node_modules/) and the walk starts in the wrong tree: it never reaches the
|
|
41
|
+
# user's .env, and it can pick up a stray one sitting above the install
|
|
42
|
+
# prefix. Measured before the fix, with a .env in the working directory and
|
|
43
|
+
# the harness imported from elsewhere: get_env_secret() saw None.
|
|
44
|
+
#
|
|
45
|
+
# Do not "simplify" this back to a bare call. The defect is invisible from
|
|
46
|
+
# a checkout and presents as a tool reporting a missing key that is sitting
|
|
47
|
+
# in the .env right next to you.
|
|
48
|
+
#
|
|
49
|
+
# AGENT_ENV_FILE is the escape hatch, named to match AGENT_PROVIDERS_FILE.
|
|
50
|
+
# There is deliberately NO user-level fallback to ~/.config/venastine/ here,
|
|
51
|
+
# though providers.json has one: a provider key is machine-wide by nature,
|
|
52
|
+
# while .env holds the per-project tool tokens described above, and the two
|
|
53
|
+
# stores are kept apart on purpose. find_dotenv returns "" when it finds
|
|
54
|
+
# nothing, and that reads as "no file", so the unconfigured case costs one
|
|
55
|
+
# directory walk and returns nothing.
|
|
56
|
+
ENV_FILE = os.environ.get("AGENT_ENV_FILE")
|
|
57
|
+
|
|
58
|
+
# A .env MAY NOT SUPPLY THE HARNESS'S OWN NAMES (TECHNICAL_DEBT 57, batch
|
|
59
|
+
# 160). Until then this module called `load_dotenv()` AT IMPORT, which wrote
|
|
60
|
+
# every name in the file into `os.environ` for the whole process -- and a
|
|
61
|
+
# .env is an ordinary file in a repository, inside no trust boundary. Five
|
|
62
|
+
# security-relevant knobs are read from `os.environ`, two of them at call
|
|
63
|
+
# time: `AGENT_SECRETS_FILE` moves the encrypted store, `AGENT_LOG_FILE`
|
|
64
|
+
# the log, and `VENASTINE_REDACT_OFF` turns pattern redaction off -- the
|
|
65
|
+
# switch kept out of settings.json precisely so a cloned repository cannot
|
|
66
|
+
# flip it (G7's reason). Nothing imported this module yet, so none of that
|
|
67
|
+
# had happened; the first tool to import it would have done all of it.
|
|
68
|
+
#
|
|
69
|
+
# So the file is now READ, never loaded: `dotenv_values()` returns a mapping
|
|
70
|
+
# and touches nothing, `get_env_secret` is the only reader, and the process
|
|
71
|
+
# environment still wins, as `load_dotenv`'s default `override=False` made
|
|
72
|
+
# it. The filter is the second half and the belt: no harness module reads a
|
|
73
|
+
# knob through `get_env_secret`, but a tool asking for one of these names
|
|
74
|
+
# must get the environment's answer or none, never the repository's.
|
|
75
|
+
_HARNESS_PREFIXES = ("AGENT_", "VENASTINE_")
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def _file_values() -> dict:
|
|
79
|
+
"""The tool keys the .env holds, minus every harness name.
|
|
80
|
+
|
|
81
|
+
Read at the call, from the file `AGENT_ENV_FILE` names or the nearest
|
|
82
|
+
.env walking up from the working directory. A name with no value (a
|
|
83
|
+
bare `KEY` line) is absent rather than None, so the caller's
|
|
84
|
+
"missing" message stays the one it gives.
|
|
85
|
+
"""
|
|
86
|
+
path = ENV_FILE or find_dotenv(usecwd=True)
|
|
87
|
+
if not path:
|
|
88
|
+
return {}
|
|
89
|
+
return {
|
|
90
|
+
name: value for name, value in dotenv_values(path).items()
|
|
91
|
+
if value is not None
|
|
92
|
+
and not name.upper().startswith(_HARNESS_PREFIXES)
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def get_env_secret(key: str, required: bool = True) -> str:
|
|
97
|
+
"""
|
|
98
|
+
Fetch a misc API key/secret from the environment or .env.
|
|
99
|
+
|
|
100
|
+
The process environment answers first, then the .env file; nothing is
|
|
101
|
+
written back to `os.environ` (TECHNICAL_DEBT 57).
|
|
102
|
+
|
|
103
|
+
Raises a clear, actionable error if a REQUIRED secret is missing,
|
|
104
|
+
rather than letting a tool proceed with an empty string and fail
|
|
105
|
+
later with a confusing 401 from some third-party API. Pass
|
|
106
|
+
required=False for genuinely optional keys (e.g. a key that only
|
|
107
|
+
unlocks a higher rate limit but isn't needed for the tool to work
|
|
108
|
+
at all).
|
|
109
|
+
"""
|
|
110
|
+
value = os.environ.get(key)
|
|
111
|
+
if value is None:
|
|
112
|
+
value = _file_values().get(key)
|
|
113
|
+
if required and not value:
|
|
114
|
+
raise ValueError(
|
|
115
|
+
f"Missing required environment variable '{key}'. "
|
|
116
|
+
f"Copy .env.example to .env and fill in {key}."
|
|
117
|
+
)
|
|
118
|
+
return value or ""
|