@yahyahammad/venastine 0.3.8 → 0.3.10

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.
Files changed (130) hide show
  1. package/.env.example +19 -19
  2. package/CONFIG_ARCHITECTURE.md +2139 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1043 -1034
  5. package/agents/builtin/compactor.md +75 -75
  6. package/agents/builtin/explore.md +77 -77
  7. package/agents/builtin/pipeline-reviewer.md +100 -100
  8. package/agents/builtin/plan.md +106 -106
  9. package/agents/builtin/review.md +74 -74
  10. package/agents/manager.py +261 -261
  11. package/agents/subagent_tool.py +472 -472
  12. package/agents/tui_commands.py +238 -146
  13. package/bin/venastine.mjs +584 -528
  14. package/bin/venastine.py +73 -71
  15. package/cli_commands.py +848 -835
  16. package/config.yaml +64 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +987 -966
  19. package/config_update.py +749 -749
  20. package/core/agent_activity.py +256 -256
  21. package/core/ansi.py +452 -452
  22. package/core/approval.py +137 -137
  23. package/core/call_view.py +364 -364
  24. package/core/cancel.py +121 -121
  25. package/core/chatgpt_auth.py +747 -747
  26. package/core/claims_view.py +107 -107
  27. package/core/client.py +2756 -2715
  28. package/core/commands.py +464 -454
  29. package/core/compaction.py +1735 -1735
  30. package/core/config_loader.py +1982 -1982
  31. package/core/connect.py +686 -686
  32. package/core/events.py +123 -123
  33. package/core/file_mentions.py +280 -280
  34. package/core/interaction.py +411 -411
  35. package/core/loop.py +2566 -2566
  36. package/core/memory.py +482 -482
  37. package/core/pipeline_models.py +190 -190
  38. package/core/provider_errors.py +274 -234
  39. package/core/reasoning/authorization.py +130 -130
  40. package/core/reasoning/base.py +219 -219
  41. package/core/reasoning/confidence_scoring.py +484 -484
  42. package/core/reasoning/events.py +149 -149
  43. package/core/reasoning/orchestrator.py +1561 -1561
  44. package/core/reasoning/output_writer.py +345 -345
  45. package/core/reasoning/payload_validation.py +524 -524
  46. package/core/reasoning/pipeline_storage.py +427 -427
  47. package/core/reasoning/scholar.py +467 -458
  48. package/core/reasoning/source_corpus.py +433 -433
  49. package/core/reasoning/source_scoring.py +855 -855
  50. package/core/replay.py +315 -315
  51. package/core/shell_sessions.py +1553 -1553
  52. package/credentials.py +307 -307
  53. package/database.py +333 -333
  54. package/docs/PRIVACY.md +78 -78
  55. package/docs/SECURITY.md +114 -108
  56. package/docs/THIRD_PARTY_NOTICES.md +148 -148
  57. package/env_secrets.py +118 -118
  58. package/json_store.py +343 -343
  59. package/logging_setup.py +295 -295
  60. package/main.py +3433 -3433
  61. package/mcp_client/client.py +780 -733
  62. package/mcp_client/config.py +484 -484
  63. package/mcp_client/registration.py +343 -343
  64. package/memories/manager.py +147 -147
  65. package/memories/tui_commands.py +319 -239
  66. package/package.json +303 -303
  67. package/project_init/config_files.py +282 -282
  68. package/project_init/generator.py +728 -728
  69. package/project_init/manifest.py +418 -418
  70. package/project_init/tui_commands.py +147 -147
  71. package/prompts/critic_pass.md +24 -24
  72. package/prompts/revalidate.md +25 -25
  73. package/prompts/revise.md +17 -17
  74. package/prompts/source_grounding.md +66 -66
  75. package/prompts/system_prompts.py +316 -316
  76. package/providers.json.example +94 -94
  77. package/pyproject.toml +149 -149
  78. package/requirements.txt +314 -295
  79. package/safety/policy_enforcement.py +1082 -1082
  80. package/security/askpass.py +419 -419
  81. package/security/capability.py +207 -207
  82. package/security/confine.py +484 -484
  83. package/security/hosted.py +182 -182
  84. package/security/permissions.py +237 -237
  85. package/security/protected_paths.py +501 -501
  86. package/security/sandbox.py +4108 -4108
  87. package/skills/builtin/math/formal-specification.md +67 -67
  88. package/skills/builtin/math/numerical-methods.md +66 -66
  89. package/skills/builtin/research/experiment-design.md +62 -62
  90. package/skills/builtin/research/reproducibility.md +55 -55
  91. package/skills/builtin/research/source-evaluation.md +70 -70
  92. package/skills/builtin/research/statistical-inference.md +63 -63
  93. package/skills/builtin/research/technical-writing.md +59 -59
  94. package/skills/builtin/software/code-review.md +61 -61
  95. package/skills/builtin/software/debugging.md +61 -61
  96. package/skills/builtin/software/test-design.md +67 -67
  97. package/skills/tui_commands.py +110 -110
  98. package/storage.py +1338 -1338
  99. package/tools/base.py +465 -465
  100. package/tools/builtin/_math_common.py +667 -667
  101. package/tools/builtin/_net_common.py +1145 -267
  102. package/tools/builtin/_page_text.py +490 -0
  103. package/tools/builtin/_pdf_text.py +113 -0
  104. package/tools/builtin/arxiv.py +685 -681
  105. package/tools/builtin/fetch_url.py +639 -371
  106. package/tools/builtin/file_ops.py +720 -720
  107. package/tools/builtin/geometry.py +184 -184
  108. package/tools/builtin/load_skill.py +76 -76
  109. package/tools/builtin/pin.py +227 -227
  110. package/tools/builtin/probability_stats.py +224 -224
  111. package/tools/builtin/project_docs.py +464 -464
  112. package/tools/builtin/remember.py +175 -175
  113. package/tools/builtin/shell.py +980 -980
  114. package/tools/builtin/todo.py +149 -149
  115. package/tools/builtin/web_search.py +402 -328
  116. package/tools/context.py +159 -159
  117. package/tools/isolation.py +387 -387
  118. package/tools/registry.py +1252 -1242
  119. package/tui/app.py +8372 -8307
  120. package/tui/app.tcss +754 -739
  121. package/tui/commands.py +26 -26
  122. package/tui/diffs.py +286 -286
  123. package/tui/history.py +128 -128
  124. package/tui/hosted_driver.py +102 -102
  125. package/tui/markdown.py +1329 -1329
  126. package/tui/meters.py +364 -364
  127. package/tui/ravens.py +146 -146
  128. package/tui/screens.py +1255 -1197
  129. package/tui/themes.py +599 -599
  130. package/tui/widgets.py +3861 -3796
@@ -1,419 +1,419 @@
1
- """
2
- security/askpass.py
3
-
4
- ROADMAP_v3 §49 slice 5a (SS63, SS64). How a stored secret reaches `ssh`
5
- without ever being in `ssh`'s environment, its argv, or a file.
6
-
7
- THE PROPERTY THIS PRESERVES (SS63)
8
- ----------------------------------
9
- Slice 4's SS47 read as "BatchMode=yes", but `BatchMode` was never the
10
- property -- it was that **`ssh` can never prompt on a terminal this process
11
- does not own**. `BatchMode=yes` guaranteed that by refusing to prompt at
12
- all, which also meant an encrypted key or a password host simply could not
13
- be used. `SSH_ASKPASS_REQUIRE=force` guarantees the same thing the other
14
- way round: every prompt goes to a helper that answers immediately and
15
- cannot block.
16
-
17
- Measured, on this machine, against a real sshd (batch 103):
18
-
19
- * with `BatchMode=no` and NO askpass, Windows OpenSSH 9.5p2 HUNG -- 20 s
20
- and still waiting, trying to prompt on a terminal this process does not
21
- own. That is SS47's measurement reproduced, and it is what this module
22
- exists to prevent;
23
- * with `SSH_ASKPASS_REQUIRE=force` and a helper, the same call returned
24
- in 0.8 s, rc=0. Both binaries on this box agree;
25
- * the Git-for-Windows build did NOT hang under the same conditions
26
- (3.1 s, refused). So the hang is a property of the BUILD, which is
27
- exactly why the guarantee may not rest on "ssh will give up".
28
-
29
- **When no secret is stored for the host, `BatchMode=yes` is kept exactly as
30
- slice 4 shipped it** and none of this module runs. A user on key-and-agent
31
- auth sees an argv that has not moved by a single option.
32
-
33
- WHY A SOCKET AND NOT AN ENVIRONMENT VARIABLE (SS64)
34
- ---------------------------------------------------
35
- `ssh` passes its whole environment to the askpass child, so the obvious
36
- implementation puts the password in a variable and the helper echoes it.
37
- That environment is readable by any process running as this user --
38
- `/proc/<pid>/environ` on Linux, the PEB on Windows -- which is precisely
39
- the property that got an OS keystore rejected for the store itself.
40
-
41
- So the environment carries a single-use TOKEN and a port. The helper
42
- forwards `(token, prompt)` and is handed one answer.
43
-
44
- **What that buys, stated precisely rather than oversold:** an attacker who
45
- can read `ssh`'s environment gets a token, and must then be present during
46
- the connection window and win a race against the helper. An attacker who
47
- can do that could have read the password from the environment at the moment
48
- it mattered anyway. This is a real narrowing of the window -- from "at rest
49
- for the life of the process" to "during one connection" -- and it is not a
50
- boundary. The helper holds no secret and no policy, which is what makes it
51
- safe to leave on disk.
52
-
53
- THE CORRECTION THE PROBE FORCED
54
- -------------------------------
55
- This was designed as a ONE-SHOT listener: one connection, one secret, then
56
- closed. Measured, that is wrong. A WRONG password produced **two** askpass
57
- invocations despite `NumberOfPasswordPrompts=1`, because
58
- `keyboard-interactive` and `password` are separate authentication methods
59
- and each gets its own prompt budget. A stacked host
60
- (`AuthenticationMethods publickey,password`) legitimately makes two asks
61
- too -- the key passphrase and then the account password. So the listener
62
- serves a BOUNDED NUMBER of prompts within one connection window, and the
63
- bound is what stops a runaway rather than the count of one.
64
-
65
- THE PROMPT STRINGS ARE MEASURED, NOT GUESSED
66
- --------------------------------------------
67
- The harness decides which secret answers which prompt, so these are policy
68
- input. All three were captured from a real `ssh` (batch 103):
69
-
70
- Enter passphrase for key 'C:\\Users\\...\\19552cfb-c47c-4e1a-b':
71
- venprobe@127.0.0.1's password:
72
- (venprobe@127.0.0.1) Password:
73
-
74
- **The key prompt's path is TRUNCATED mid-string** -- OpenSSH cuts the
75
- prompt to a fixed width -- so matching it against the identity file's path
76
- would fail on any path longer than about sixty characters, which is most of
77
- them. The prefix is what is dependable. The two password forms are the two
78
- authentication methods: `password` produces the first, `keyboard-interactive`
79
- the second, and a server offering both serves keyboard-interactive.
80
-
81
- An unrecognised prompt is REFUSED and locks the store. An askpass that
82
- answers a question it did not understand is the wrong secret sent to the
83
- wrong prompt, and the one question `ssh` might ask that is not either of
84
- these is a trust decision -- which SS49 already answers by pinning the host
85
- key, and which must never be answered by a program.
86
- """
87
-
88
- import hmac
89
- import logging
90
- import os
91
- import shutil
92
- import socket
93
- import stat
94
- import sys
95
- import tempfile
96
- import threading
97
- import time
98
-
99
- from security import secrets
100
-
101
- logger = logging.getLogger(__name__)
102
-
103
- #: Logical names the caller supplies answers under.
104
- KEY_PASSPHRASE = "key_passphrase"
105
- LOGIN = "login"
106
-
107
- #: Measured (batch 103). PREFIX only: OpenSSH truncates this prompt, so the
108
- #: path in it is not the identity file's path and cannot be matched on.
109
- _KEY_PROMPT_PREFIX = "Enter passphrase for key "
110
- #: Measured: the `password` method and the `keyboard-interactive` method.
111
- _PASSWORD_SUFFIXES = ("'s password: ", ") Password: ")
112
-
113
- #: How many prompts one connection window may legitimately produce. A
114
- #: stacked host asks twice; a wrong password asks twice; the cap is above
115
- #: both and low enough that a loop is refused rather than served.
116
- MAX_SERVES = 6
117
- #: How long the listener stays open. Bounded by `ConnectTimeout` and the
118
- #: session in practice; this is the backstop for a connection that neither
119
- #: succeeds nor fails.
120
- DEADLINE_S = 120.0
121
- #: How long the helper may take between connecting and asking.
122
- _CLIENT_TIMEOUT_S = 10.0
123
- #: How often the accept loop wakes to check whether it has been stopped.
124
- _ACCEPT_POLL_S = 0.5
125
-
126
- #: The helper, as source. It imports nothing but the stdlib, holds no secret
127
- #: and makes no decision -- it is a pipe with a password on it, which is what
128
- #: makes it safe to write to a temp directory.
129
- _HELPER_SOURCE = '''\
130
- import os
131
- import socket
132
- import sys
133
-
134
- token = os.environ.get("VEN_ASKPASS_TOKEN", "")
135
- port = int(os.environ.get("VEN_ASKPASS_PORT", "0") or 0)
136
- prompt = sys.argv[1] if len(sys.argv) > 1 else ""
137
- if not token or not port:
138
- sys.exit(1)
139
- try:
140
- conn = socket.create_connection(("127.0.0.1", port), 10)
141
- except OSError:
142
- sys.exit(1)
143
- try:
144
- conn.sendall((token + "\\n" + prompt + "\\n\\n").encode("utf-8"))
145
- buf = b""
146
- while not buf.endswith(b"\\n") and len(buf) < 65536:
147
- chunk = conn.recv(4096)
148
- if not chunk:
149
- break
150
- buf += chunk
151
- finally:
152
- conn.close()
153
- if buf.strip() == b"":
154
- sys.exit(1)
155
- sys.stdout.write(buf.decode("utf-8", "replace"))
156
- '''
157
-
158
-
159
- def classify(prompt: str):
160
- """Which stored secret answers *prompt*, or None to refuse.
161
-
162
- The one place a prompt string becomes a decision. Returns a logical
163
- name rather than a value, so this function can be tested against the
164
- measured strings without a store existing at all.
165
- """
166
- if prompt.startswith(_KEY_PROMPT_PREFIX):
167
- return KEY_PASSPHRASE
168
- for suffix in _PASSWORD_SUFFIXES:
169
- if prompt.endswith(suffix):
170
- return LOGIN
171
- return None
172
-
173
-
174
- class _Listener:
175
- """One connection window's worth of answering."""
176
-
177
- def __init__(self, answers: dict) -> None:
178
- #: {logical name -> Secret}. Absent means "refuse that prompt",
179
- #: which is how a host with a passphrase but no password still gets
180
- #: a refusal rather than an empty string for the password ask.
181
- self._answers = answers
182
- self._token = os.urandom(32).hex()
183
- self._sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
184
- self._sock.bind(("127.0.0.1", 0))
185
- self._sock.listen(8)
186
- # HERE, not at the top of `_run`. The thread may not reach its
187
- # first statement before `close()` runs -- a `serving` block can be
188
- # that short -- and on Windows calling anything on a closed socket
189
- # raises WinError 10038, which as an unhandled thread exception
190
- # prints a traceback to stderr. Setting it while this object is
191
- # still the only thing holding the socket removes the race rather
192
- # than catching it.
193
- self._sock.settimeout(_ACCEPT_POLL_S)
194
- self.port = self._sock.getsockname()[1]
195
- self.served = []
196
- self.refusal = ""
197
- self._stop = threading.Event()
198
- self._thread = threading.Thread(
199
- target=self._run, name="venastine-askpass", daemon=True)
200
-
201
- # -- the answering loop -------------------------------------------------
202
-
203
- def _refuse(self, why: str) -> None:
204
- """Refuse, and LOCK (SS60).
205
-
206
- Every refusal here means something asked for a secret in a way the
207
- harness did not arrange: a token it should not have, a prompt
208
- nobody measured, or more asks than a connection can legitimately
209
- make. None of those is a condition to keep plaintext through.
210
-
211
- NAMES the cause, never the prompt's content or any value.
212
- """
213
- if not self.refusal:
214
- self.refusal = why
215
- logger.warning("askpass: refused (%s)", why)
216
- secrets.lock("askpass refused: %s" % why)
217
-
218
- def _run(self) -> None:
219
- try:
220
- self._loop()
221
- except OSError:
222
- # The socket was closed underneath us, which is what `close()`
223
- # does and is not a failure. Belt and braces over the
224
- # `settimeout` move above: this thread must never raise, because
225
- # an unhandled thread exception is a traceback on stderr and
226
- # nothing here is worth painting over a running TUI for.
227
- return
228
-
229
- def _loop(self) -> None:
230
- deadline = time.monotonic() + DEADLINE_S
231
- while not self._stop.is_set():
232
- if time.monotonic() > deadline:
233
- self._refuse("deadline")
234
- return
235
- try:
236
- conn, _ = self._sock.accept()
237
- except TimeoutError:
238
- continue
239
- except OSError:
240
- return
241
- try:
242
- self._answer(conn)
243
- except OSError as exc:
244
- self._refuse("connection error: %s" % type(exc).__name__)
245
- finally:
246
- try:
247
- conn.close()
248
- except OSError:
249
- pass # the connection is finished either way; a failed close says nothing
250
-
251
- def _answer(self, conn) -> None:
252
- conn.settimeout(_CLIENT_TIMEOUT_S)
253
- data = b""
254
- while b"\n\n" not in data and len(data) < 8192:
255
- chunk = conn.recv(4096)
256
- if not chunk:
257
- break
258
- data += chunk
259
- token, _, rest = data.partition(b"\n")
260
- prompt = rest.partition(b"\n")[0]
261
- # compare_digest, not ==. The token is a secret of its own for the
262
- # length of one connection, and a timing oracle on it is a timing
263
- # oracle on the password behind it.
264
- # REFUSE FIRST, REPLY SECOND, in all four branches. The reply is
265
- # an empty line, which makes the helper exit non-zero and ssh give
266
- # up -- but sending it before `_refuse` has locked the store leaves
267
- # a window in which the answer is already out and the plaintext is
268
- # still held. The window is small and it is not nothing, and
269
- # closing it costs the two lines being swapped.
270
- #
271
- # It also makes the refusal OBSERVABLE the moment the client's
272
- # `recv` returns, which is what lets the tests assert it without a
273
- # local wait helper -- and a local wait helper is what
274
- # `test_pilot_wait.py` forbids, for the reason five copies of one
275
- # taught this project.
276
- if not hmac.compare_digest(token.decode("utf-8", "replace"),
277
- self._token):
278
- self._refuse("bad token")
279
- conn.sendall(b"\n")
280
- return
281
- if len(self.served) >= MAX_SERVES:
282
- self._refuse("more prompts than a connection can make")
283
- conn.sendall(b"\n")
284
- return
285
- name = classify(prompt.decode("utf-8", "replace"))
286
- if name is None:
287
- self._refuse("unrecognised prompt")
288
- conn.sendall(b"\n")
289
- return
290
- secret = self._answers.get(name)
291
- if secret is None:
292
- self._refuse("no stored secret answers a %s prompt" % name)
293
- conn.sendall(b"\n")
294
- return
295
- conn.sendall(secret.reveal() + b"\n")
296
- self.served.append(name)
297
-
298
- # -- lifecycle ----------------------------------------------------------
299
-
300
- def start(self) -> None:
301
- self._thread.start()
302
-
303
- def close(self) -> None:
304
- self._stop.set()
305
- try:
306
- self._sock.close()
307
- except OSError:
308
- pass # already closed; shutting down goes on
309
- self._thread.join(timeout=3)
310
-
311
- @property
312
- def token(self) -> str:
313
- return self._token
314
-
315
-
316
- def _write_helper(directory: str) -> str:
317
- """Write the helper and return what `SSH_ASKPASS` should point at.
318
-
319
- On Windows `SSH_ASKPASS` has to name something `CreateProcess` can run
320
- and takes no arguments of its own, so the script cannot be named
321
- directly -- a `.cmd` shim carries the interpreter. Measured: both a
322
- `.cmd` and a `.bat` work, and the prompt reaches the script as
323
- `argv[1]` through either.
324
-
325
- On POSIX the script is executable with its own shebang and no shim.
326
- """
327
- script = os.path.join(directory, "venastine_askpass.py")
328
- with open(script, "w", encoding="utf-8", newline="\n") as handle:
329
- handle.write(_HELPER_SOURCE)
330
- if os.name == "nt":
331
- shim = os.path.join(directory, "venastine_askpass.cmd")
332
- with open(shim, "w", newline="") as handle:
333
- handle.write('@echo off\r\n"%s" "%s" %%*\r\n'
334
- % (sys.executable, script))
335
- return shim
336
- os.chmod(script, stat.S_IRWXU)
337
- launcher = os.path.join(directory, "venastine_askpass.sh")
338
- with open(launcher, "w", encoding="utf-8", newline="\n") as handle:
339
- handle.write('#!/bin/sh\nexec "%s" "%s" "$@"\n'
340
- % (sys.executable, script))
341
- os.chmod(launcher, stat.S_IRWXU)
342
- return launcher
343
-
344
-
345
- class Serving:
346
- """The live connection window: what the environment must carry, and
347
- what happened."""
348
-
349
- def __init__(self, listener: _Listener, env: dict) -> None:
350
- self._listener = listener
351
- self.env = env
352
-
353
- @property
354
- def served(self) -> list:
355
- return list(self._listener.served)
356
-
357
- @property
358
- def refusal(self) -> str:
359
- return self._listener.refusal
360
-
361
-
362
- class serving:
363
- """Context manager: stand up a listener and a helper for one connection.
364
-
365
- Yields a `Serving` whose `.env` is the fragment to merge into the
366
- subprocess environment. On exit the listener is closed and the helper
367
- directory removed, whatever happened -- and an exception escaping the
368
- block locks the store, because an unknown state is not a state to hold
369
- plaintext through (SS60).
370
-
371
- Not a `@contextlib.contextmanager` generator: the cleanup has to run on
372
- every path including the one where `__enter__` itself fails partway,
373
- and a class makes each half explicit.
374
- """
375
-
376
- def __init__(self, answers: dict) -> None:
377
- # No None-filter here, and that is a deliberate removal: one was
378
- # written, and the mutation pass showed it can never be observed,
379
- # because `_Listener._answer` checks for a missing answer anyway
380
- # and a None value reaches the same refusal. Two guards where one
381
- # fires is the shape that reads as protection without being any.
382
- self._answers = dict(answers)
383
- self._listener = None
384
- self._dir = ""
385
-
386
- def __enter__(self) -> Serving:
387
- self._dir = tempfile.mkdtemp(prefix="venastine-askpass-")
388
- try:
389
- helper = _write_helper(self._dir)
390
- self._listener = _Listener(self._answers)
391
- self._listener.start()
392
- except BaseException:
393
- self._cleanup()
394
- raise
395
- env = {
396
- "SSH_ASKPASS": helper,
397
- # The whole guarantee. Without `force`, ssh uses askpass only
398
- # when it has no terminal AND DISPLAY is set -- and with a
399
- # terminal it prompts, which is the 20-second hang measured
400
- # above.
401
- "SSH_ASKPASS_REQUIRE": "force",
402
- "VEN_ASKPASS_TOKEN": self._listener.token,
403
- "VEN_ASKPASS_PORT": str(self._listener.port),
404
- }
405
- return Serving(self._listener, env)
406
-
407
- def __exit__(self, exc_type, exc, tb) -> bool:
408
- self._cleanup()
409
- if exc_type is not None:
410
- secrets.lock("exception during an askpass connection")
411
- return False
412
-
413
- def _cleanup(self) -> None:
414
- if self._listener is not None:
415
- self._listener.close()
416
- self._listener = None
417
- if self._dir:
418
- shutil.rmtree(self._dir, ignore_errors=True)
419
- self._dir = ""
1
+ """
2
+ security/askpass.py
3
+
4
+ ROADMAP_v3 §49 slice 5a (SS63, SS64). How a stored secret reaches `ssh`
5
+ without ever being in `ssh`'s environment, its argv, or a file.
6
+
7
+ THE PROPERTY THIS PRESERVES (SS63)
8
+ ----------------------------------
9
+ Slice 4's SS47 read as "BatchMode=yes", but `BatchMode` was never the
10
+ property -- it was that **`ssh` can never prompt on a terminal this process
11
+ does not own**. `BatchMode=yes` guaranteed that by refusing to prompt at
12
+ all, which also meant an encrypted key or a password host simply could not
13
+ be used. `SSH_ASKPASS_REQUIRE=force` guarantees the same thing the other
14
+ way round: every prompt goes to a helper that answers immediately and
15
+ cannot block.
16
+
17
+ Measured, on this machine, against a real sshd (batch 103):
18
+
19
+ * with `BatchMode=no` and NO askpass, Windows OpenSSH 9.5p2 HUNG -- 20 s
20
+ and still waiting, trying to prompt on a terminal this process does not
21
+ own. That is SS47's measurement reproduced, and it is what this module
22
+ exists to prevent;
23
+ * with `SSH_ASKPASS_REQUIRE=force` and a helper, the same call returned
24
+ in 0.8 s, rc=0. Both binaries on this box agree;
25
+ * the Git-for-Windows build did NOT hang under the same conditions
26
+ (3.1 s, refused). So the hang is a property of the BUILD, which is
27
+ exactly why the guarantee may not rest on "ssh will give up".
28
+
29
+ **When no secret is stored for the host, `BatchMode=yes` is kept exactly as
30
+ slice 4 shipped it** and none of this module runs. A user on key-and-agent
31
+ auth sees an argv that has not moved by a single option.
32
+
33
+ WHY A SOCKET AND NOT AN ENVIRONMENT VARIABLE (SS64)
34
+ ---------------------------------------------------
35
+ `ssh` passes its whole environment to the askpass child, so the obvious
36
+ implementation puts the password in a variable and the helper echoes it.
37
+ That environment is readable by any process running as this user --
38
+ `/proc/<pid>/environ` on Linux, the PEB on Windows -- which is precisely
39
+ the property that got an OS keystore rejected for the store itself.
40
+
41
+ So the environment carries a single-use TOKEN and a port. The helper
42
+ forwards `(token, prompt)` and is handed one answer.
43
+
44
+ **What that buys, stated precisely rather than oversold:** an attacker who
45
+ can read `ssh`'s environment gets a token, and must then be present during
46
+ the connection window and win a race against the helper. An attacker who
47
+ can do that could have read the password from the environment at the moment
48
+ it mattered anyway. This is a real narrowing of the window -- from "at rest
49
+ for the life of the process" to "during one connection" -- and it is not a
50
+ boundary. The helper holds no secret and no policy, which is what makes it
51
+ safe to leave on disk.
52
+
53
+ THE CORRECTION THE PROBE FORCED
54
+ -------------------------------
55
+ This was designed as a ONE-SHOT listener: one connection, one secret, then
56
+ closed. Measured, that is wrong. A WRONG password produced **two** askpass
57
+ invocations despite `NumberOfPasswordPrompts=1`, because
58
+ `keyboard-interactive` and `password` are separate authentication methods
59
+ and each gets its own prompt budget. A stacked host
60
+ (`AuthenticationMethods publickey,password`) legitimately makes two asks
61
+ too -- the key passphrase and then the account password. So the listener
62
+ serves a BOUNDED NUMBER of prompts within one connection window, and the
63
+ bound is what stops a runaway rather than the count of one.
64
+
65
+ THE PROMPT STRINGS ARE MEASURED, NOT GUESSED
66
+ --------------------------------------------
67
+ The harness decides which secret answers which prompt, so these are policy
68
+ input. All three were captured from a real `ssh` (batch 103):
69
+
70
+ Enter passphrase for key 'C:\\Users\\...\\19552cfb-c47c-4e1a-b':
71
+ venprobe@127.0.0.1's password:
72
+ (venprobe@127.0.0.1) Password:
73
+
74
+ **The key prompt's path is TRUNCATED mid-string** -- OpenSSH cuts the
75
+ prompt to a fixed width -- so matching it against the identity file's path
76
+ would fail on any path longer than about sixty characters, which is most of
77
+ them. The prefix is what is dependable. The two password forms are the two
78
+ authentication methods: `password` produces the first, `keyboard-interactive`
79
+ the second, and a server offering both serves keyboard-interactive.
80
+
81
+ An unrecognised prompt is REFUSED and locks the store. An askpass that
82
+ answers a question it did not understand is the wrong secret sent to the
83
+ wrong prompt, and the one question `ssh` might ask that is not either of
84
+ these is a trust decision -- which SS49 already answers by pinning the host
85
+ key, and which must never be answered by a program.
86
+ """
87
+
88
+ import hmac
89
+ import logging
90
+ import os
91
+ import shutil
92
+ import socket
93
+ import stat
94
+ import sys
95
+ import tempfile
96
+ import threading
97
+ import time
98
+
99
+ from security import secrets
100
+
101
+ logger = logging.getLogger(__name__)
102
+
103
+ #: Logical names the caller supplies answers under.
104
+ KEY_PASSPHRASE = "key_passphrase"
105
+ LOGIN = "login"
106
+
107
+ #: Measured (batch 103). PREFIX only: OpenSSH truncates this prompt, so the
108
+ #: path in it is not the identity file's path and cannot be matched on.
109
+ _KEY_PROMPT_PREFIX = "Enter passphrase for key "
110
+ #: Measured: the `password` method and the `keyboard-interactive` method.
111
+ _PASSWORD_SUFFIXES = ("'s password: ", ") Password: ")
112
+
113
+ #: How many prompts one connection window may legitimately produce. A
114
+ #: stacked host asks twice; a wrong password asks twice; the cap is above
115
+ #: both and low enough that a loop is refused rather than served.
116
+ MAX_SERVES = 6
117
+ #: How long the listener stays open. Bounded by `ConnectTimeout` and the
118
+ #: session in practice; this is the backstop for a connection that neither
119
+ #: succeeds nor fails.
120
+ DEADLINE_S = 120.0
121
+ #: How long the helper may take between connecting and asking.
122
+ _CLIENT_TIMEOUT_S = 10.0
123
+ #: How often the accept loop wakes to check whether it has been stopped.
124
+ _ACCEPT_POLL_S = 0.5
125
+
126
+ #: The helper, as source. It imports nothing but the stdlib, holds no secret
127
+ #: and makes no decision -- it is a pipe with a password on it, which is what
128
+ #: makes it safe to write to a temp directory.
129
+ _HELPER_SOURCE = '''\
130
+ import os
131
+ import socket
132
+ import sys
133
+
134
+ token = os.environ.get("VEN_ASKPASS_TOKEN", "")
135
+ port = int(os.environ.get("VEN_ASKPASS_PORT", "0") or 0)
136
+ prompt = sys.argv[1] if len(sys.argv) > 1 else ""
137
+ if not token or not port:
138
+ sys.exit(1)
139
+ try:
140
+ conn = socket.create_connection(("127.0.0.1", port), 10)
141
+ except OSError:
142
+ sys.exit(1)
143
+ try:
144
+ conn.sendall((token + "\\n" + prompt + "\\n\\n").encode("utf-8"))
145
+ buf = b""
146
+ while not buf.endswith(b"\\n") and len(buf) < 65536:
147
+ chunk = conn.recv(4096)
148
+ if not chunk:
149
+ break
150
+ buf += chunk
151
+ finally:
152
+ conn.close()
153
+ if buf.strip() == b"":
154
+ sys.exit(1)
155
+ sys.stdout.write(buf.decode("utf-8", "replace"))
156
+ '''
157
+
158
+
159
+ def classify(prompt: str):
160
+ """Which stored secret answers *prompt*, or None to refuse.
161
+
162
+ The one place a prompt string becomes a decision. Returns a logical
163
+ name rather than a value, so this function can be tested against the
164
+ measured strings without a store existing at all.
165
+ """
166
+ if prompt.startswith(_KEY_PROMPT_PREFIX):
167
+ return KEY_PASSPHRASE
168
+ for suffix in _PASSWORD_SUFFIXES:
169
+ if prompt.endswith(suffix):
170
+ return LOGIN
171
+ return None
172
+
173
+
174
+ class _Listener:
175
+ """One connection window's worth of answering."""
176
+
177
+ def __init__(self, answers: dict) -> None:
178
+ #: {logical name -> Secret}. Absent means "refuse that prompt",
179
+ #: which is how a host with a passphrase but no password still gets
180
+ #: a refusal rather than an empty string for the password ask.
181
+ self._answers = answers
182
+ self._token = os.urandom(32).hex()
183
+ self._sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
184
+ self._sock.bind(("127.0.0.1", 0))
185
+ self._sock.listen(8)
186
+ # HERE, not at the top of `_run`. The thread may not reach its
187
+ # first statement before `close()` runs -- a `serving` block can be
188
+ # that short -- and on Windows calling anything on a closed socket
189
+ # raises WinError 10038, which as an unhandled thread exception
190
+ # prints a traceback to stderr. Setting it while this object is
191
+ # still the only thing holding the socket removes the race rather
192
+ # than catching it.
193
+ self._sock.settimeout(_ACCEPT_POLL_S)
194
+ self.port = self._sock.getsockname()[1]
195
+ self.served = []
196
+ self.refusal = ""
197
+ self._stop = threading.Event()
198
+ self._thread = threading.Thread(
199
+ target=self._run, name="venastine-askpass", daemon=True)
200
+
201
+ # -- the answering loop -------------------------------------------------
202
+
203
+ def _refuse(self, why: str) -> None:
204
+ """Refuse, and LOCK (SS60).
205
+
206
+ Every refusal here means something asked for a secret in a way the
207
+ harness did not arrange: a token it should not have, a prompt
208
+ nobody measured, or more asks than a connection can legitimately
209
+ make. None of those is a condition to keep plaintext through.
210
+
211
+ NAMES the cause, never the prompt's content or any value.
212
+ """
213
+ if not self.refusal:
214
+ self.refusal = why
215
+ logger.warning("askpass: refused (%s)", why)
216
+ secrets.lock("askpass refused: %s" % why)
217
+
218
+ def _run(self) -> None:
219
+ try:
220
+ self._loop()
221
+ except OSError:
222
+ # The socket was closed underneath us, which is what `close()`
223
+ # does and is not a failure. Belt and braces over the
224
+ # `settimeout` move above: this thread must never raise, because
225
+ # an unhandled thread exception is a traceback on stderr and
226
+ # nothing here is worth painting over a running TUI for.
227
+ return
228
+
229
+ def _loop(self) -> None:
230
+ deadline = time.monotonic() + DEADLINE_S
231
+ while not self._stop.is_set():
232
+ if time.monotonic() > deadline:
233
+ self._refuse("deadline")
234
+ return
235
+ try:
236
+ conn, _ = self._sock.accept()
237
+ except TimeoutError:
238
+ continue
239
+ except OSError:
240
+ return
241
+ try:
242
+ self._answer(conn)
243
+ except OSError as exc:
244
+ self._refuse("connection error: %s" % type(exc).__name__)
245
+ finally:
246
+ try:
247
+ conn.close()
248
+ except OSError:
249
+ pass # the connection is finished either way; a failed close says nothing
250
+
251
+ def _answer(self, conn) -> None:
252
+ conn.settimeout(_CLIENT_TIMEOUT_S)
253
+ data = b""
254
+ while b"\n\n" not in data and len(data) < 8192:
255
+ chunk = conn.recv(4096)
256
+ if not chunk:
257
+ break
258
+ data += chunk
259
+ token, _, rest = data.partition(b"\n")
260
+ prompt = rest.partition(b"\n")[0]
261
+ # compare_digest, not ==. The token is a secret of its own for the
262
+ # length of one connection, and a timing oracle on it is a timing
263
+ # oracle on the password behind it.
264
+ # REFUSE FIRST, REPLY SECOND, in all four branches. The reply is
265
+ # an empty line, which makes the helper exit non-zero and ssh give
266
+ # up -- but sending it before `_refuse` has locked the store leaves
267
+ # a window in which the answer is already out and the plaintext is
268
+ # still held. The window is small and it is not nothing, and
269
+ # closing it costs the two lines being swapped.
270
+ #
271
+ # It also makes the refusal OBSERVABLE the moment the client's
272
+ # `recv` returns, which is what lets the tests assert it without a
273
+ # local wait helper -- and a local wait helper is what
274
+ # `test_pilot_wait.py` forbids, for the reason five copies of one
275
+ # taught this project.
276
+ if not hmac.compare_digest(token.decode("utf-8", "replace"),
277
+ self._token):
278
+ self._refuse("bad token")
279
+ conn.sendall(b"\n")
280
+ return
281
+ if len(self.served) >= MAX_SERVES:
282
+ self._refuse("more prompts than a connection can make")
283
+ conn.sendall(b"\n")
284
+ return
285
+ name = classify(prompt.decode("utf-8", "replace"))
286
+ if name is None:
287
+ self._refuse("unrecognised prompt")
288
+ conn.sendall(b"\n")
289
+ return
290
+ secret = self._answers.get(name)
291
+ if secret is None:
292
+ self._refuse("no stored secret answers a %s prompt" % name)
293
+ conn.sendall(b"\n")
294
+ return
295
+ conn.sendall(secret.reveal() + b"\n")
296
+ self.served.append(name)
297
+
298
+ # -- lifecycle ----------------------------------------------------------
299
+
300
+ def start(self) -> None:
301
+ self._thread.start()
302
+
303
+ def close(self) -> None:
304
+ self._stop.set()
305
+ try:
306
+ self._sock.close()
307
+ except OSError:
308
+ pass # already closed; shutting down goes on
309
+ self._thread.join(timeout=3)
310
+
311
+ @property
312
+ def token(self) -> str:
313
+ return self._token
314
+
315
+
316
+ def _write_helper(directory: str) -> str:
317
+ """Write the helper and return what `SSH_ASKPASS` should point at.
318
+
319
+ On Windows `SSH_ASKPASS` has to name something `CreateProcess` can run
320
+ and takes no arguments of its own, so the script cannot be named
321
+ directly -- a `.cmd` shim carries the interpreter. Measured: both a
322
+ `.cmd` and a `.bat` work, and the prompt reaches the script as
323
+ `argv[1]` through either.
324
+
325
+ On POSIX the script is executable with its own shebang and no shim.
326
+ """
327
+ script = os.path.join(directory, "venastine_askpass.py")
328
+ with open(script, "w", encoding="utf-8", newline="\n") as handle:
329
+ handle.write(_HELPER_SOURCE)
330
+ if os.name == "nt":
331
+ shim = os.path.join(directory, "venastine_askpass.cmd")
332
+ with open(shim, "w", newline="") as handle:
333
+ handle.write('@echo off\r\n"%s" "%s" %%*\r\n'
334
+ % (sys.executable, script))
335
+ return shim
336
+ os.chmod(script, stat.S_IRWXU)
337
+ launcher = os.path.join(directory, "venastine_askpass.sh")
338
+ with open(launcher, "w", encoding="utf-8", newline="\n") as handle:
339
+ handle.write('#!/bin/sh\nexec "%s" "%s" "$@"\n'
340
+ % (sys.executable, script))
341
+ os.chmod(launcher, stat.S_IRWXU)
342
+ return launcher
343
+
344
+
345
+ class Serving:
346
+ """The live connection window: what the environment must carry, and
347
+ what happened."""
348
+
349
+ def __init__(self, listener: _Listener, env: dict) -> None:
350
+ self._listener = listener
351
+ self.env = env
352
+
353
+ @property
354
+ def served(self) -> list:
355
+ return list(self._listener.served)
356
+
357
+ @property
358
+ def refusal(self) -> str:
359
+ return self._listener.refusal
360
+
361
+
362
+ class serving:
363
+ """Context manager: stand up a listener and a helper for one connection.
364
+
365
+ Yields a `Serving` whose `.env` is the fragment to merge into the
366
+ subprocess environment. On exit the listener is closed and the helper
367
+ directory removed, whatever happened -- and an exception escaping the
368
+ block locks the store, because an unknown state is not a state to hold
369
+ plaintext through (SS60).
370
+
371
+ Not a `@contextlib.contextmanager` generator: the cleanup has to run on
372
+ every path including the one where `__enter__` itself fails partway,
373
+ and a class makes each half explicit.
374
+ """
375
+
376
+ def __init__(self, answers: dict) -> None:
377
+ # No None-filter here, and that is a deliberate removal: one was
378
+ # written, and the mutation pass showed it can never be observed,
379
+ # because `_Listener._answer` checks for a missing answer anyway
380
+ # and a None value reaches the same refusal. Two guards where one
381
+ # fires is the shape that reads as protection without being any.
382
+ self._answers = dict(answers)
383
+ self._listener = None
384
+ self._dir = ""
385
+
386
+ def __enter__(self) -> Serving:
387
+ self._dir = tempfile.mkdtemp(prefix="venastine-askpass-")
388
+ try:
389
+ helper = _write_helper(self._dir)
390
+ self._listener = _Listener(self._answers)
391
+ self._listener.start()
392
+ except BaseException:
393
+ self._cleanup()
394
+ raise
395
+ env = {
396
+ "SSH_ASKPASS": helper,
397
+ # The whole guarantee. Without `force`, ssh uses askpass only
398
+ # when it has no terminal AND DISPLAY is set -- and with a
399
+ # terminal it prompts, which is the 20-second hang measured
400
+ # above.
401
+ "SSH_ASKPASS_REQUIRE": "force",
402
+ "VEN_ASKPASS_TOKEN": self._listener.token,
403
+ "VEN_ASKPASS_PORT": str(self._listener.port),
404
+ }
405
+ return Serving(self._listener, env)
406
+
407
+ def __exit__(self, exc_type, exc, tb) -> bool:
408
+ self._cleanup()
409
+ if exc_type is not None:
410
+ secrets.lock("exception during an askpass connection")
411
+ return False
412
+
413
+ def _cleanup(self) -> None:
414
+ if self._listener is not None:
415
+ self._listener.close()
416
+ self._listener = None
417
+ if self._dir:
418
+ shutil.rmtree(self._dir, ignore_errors=True)
419
+ self._dir = ""