Skip to content

Commit d937a71

Browse files
committed
🧪 Fail stop when the helper cannot work, and prove what it answers
Step 4 of the refreeze, plus the two corrections that came with it. **A13 was unmet, not merely unproven.** Three places quietly turned a broken host into a clean refusal, and each is fixed: - acquisition no longer catches its own failure to run `git credential fill`, so a machine that cannot start one fails stop rather than reporting that it holds no credential; - only an absent marker means "not rejected" — a marker that cannot be read is raised, where before every read error meant nothing was refused; - the helper's lifecycle is structured and awaited. Its stdin errors are raised rather than read as an empty request, and the marker write is part of what the program does rather than a detached promise that could fail after it answered. **The module contract was describing the design it replaced.** Its opening said the adapter never receives a credential and only forwards ambient helper names. It now says what is true: the trusted adapter holds one credential for one invocation, narrowly, and the two failure classes that must not be confused. `subprocess.ts` no longer mentions a credential broker. **`credential-helper.test.ts`** covers the exact-locator answer and every redirected refusal; `store` and `approve` doing nothing; an exact `erase` writing one fixed nonsecret byte and a mismatched one writing none; the four incomplete or mismatched acquisition answers, each refusing before transport; that the complete locator reaches the helper with `useHttpPath` forced by acquisition rather than by the fixture; and the injected faults at the acquisition, launcher and marker boundaries, with no credential in any cause. Remaining: ambient-authentication extensions for redirect refusal, hostile transport arguments and real cancellation; A14 in workflow-host.test.ts; A10 in git-push-crash.test.ts. Refs #522
1 parent ce02e81 commit d937a71

8 files changed

Lines changed: 499 additions & 85 deletions

File tree

‎packages/cli/src/compiled.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ import { API, useHostFiles } from "@executablemd/runtime";
1111
import { compileDataUri } from "@executablemd/core";
1212
import { runXmd } from "./cli.ts";
1313
import { useDenoWorkflowHost } from "./deno-workflow.ts";
14-
import { runCredentialHelperMode } from "@executablemd/workflow/deno";
14+
import { isCredentialHelperMode, runCredentialHelper } from "@executablemd/workflow/deno";
1515
import type { HelperAssembly } from "@executablemd/workflow/deno";
1616
import { useCompiledService } from "./compiled-service.ts";
1717

@@ -28,7 +28,9 @@ const HELPER: HelperAssembly = {
2828
};
2929

3030
// Before anything public is parsed, and absent from every public surface.
31-
if (!runCredentialHelperMode(process.argv.slice(2))) {
31+
if (isCredentialHelperMode(process.argv.slice(2))) {
32+
await main(() => runCredentialHelper(process.argv.slice(2)));
33+
} else {
3234
await main(function* (args) {
3335
// The base providers for this host. `at: "min"` puts them beneath ordinary
3436
// middleware, so middleware installed later can wrap either one.

‎packages/cli/src/credential-helper-entry.ts‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,14 @@
1212
*/
1313

1414
import process from "node:process";
15-
import { runCredentialHelperMode } from "@executablemd/workflow/deno";
15+
import { main } from "effection";
16+
import { isCredentialHelperMode, runCredentialHelper } from "@executablemd/workflow/deno";
1617

17-
// The launcher already names the mode; what follows it is Git's operation.
18-
runCredentialHelperMode(process.argv.slice(2));
18+
// The launcher already names the mode; what follows it is Git's operation. The
19+
// whole of what this program does is awaited, so a failure to read the request
20+
// or to record a rejection is this helper failing rather than something that
21+
// happened quietly after it answered.
22+
const invocation = process.argv.slice(2);
23+
if (isCredentialHelperMode(invocation)) {
24+
await main(() => runCredentialHelper(invocation));
25+
}

‎packages/cli/src/deno.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ import { API, useHostFiles } from "@executablemd/runtime";
1414
import { compileDataUri } from "@executablemd/core";
1515
import { runXmd } from "./cli.ts";
1616
import { useDenoWorkflowHost } from "./deno-workflow.ts";
17-
import { runCredentialHelperMode } from "@executablemd/workflow/deno";
17+
import { isCredentialHelperMode, runCredentialHelper } from "@executablemd/workflow/deno";
1818
import type { HelperAssembly } from "@executablemd/workflow/deno";
1919
import { useDenoService } from "./deno-service.ts";
2020

@@ -42,7 +42,9 @@ const HELPER: HelperAssembly = {
4242
// The internal helper mode runs before anything public is parsed. It is not a
4343
// command: it appears in no help and in no public grammar, and a caller who did
4444
// not select it gets the ordinary command line unchanged.
45-
if (!runCredentialHelperMode(process.argv.slice(2))) {
45+
if (isCredentialHelperMode(process.argv.slice(2))) {
46+
await main(() => runCredentialHelper(process.argv.slice(2)));
47+
} else {
4648
await main(function* (args) {
4749
// The base providers for this host. `at: "min"` puts them beneath ordinary
4850
// middleware, so middleware installed later can wrap either one.

‎packages/workflow/deno.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,8 @@ export {
8989
helperCommand,
9090
launcherName,
9191
launcherProgram,
92-
runCredentialHelperMode,
92+
isCredentialHelperMode,
93+
runCredentialHelper,
9394
} from "./src/deno/composition/credential-helper.ts";
9495
export type {
9596
HelperAssembly,

‎packages/workflow/src/deno/composition/authentication.ts‎

Lines changed: 45 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -9,55 +9,54 @@
99
* observations and its mutation, and disposed with it — a completed replay
1010
* restores its retained result without reaching this module at all.
1111
*
12-
* ## XMD is not the credential carrier
12+
* ## The adapter owns the credential, and owns it narrowly
1313
*
14-
* No credential value crosses this boundary, and none is written anywhere. What
15-
* a session holds is the host's *decision* about which authentication Git may
16-
* use for one exact locator: a socket path, a known-hosts file, and the names of
17-
* the credential helpers the invoking user already configured. Git and the
18-
* helper exchange the secret between themselves, over Git's own credential
19-
* protocol, and this module never sees it.
14+
* This is the trusted host adapter, so it may hold one HTTP credential in
15+
* memory — for one invocation, released when that invocation ends. What it may
16+
* not do is let one out. The value reaches nothing but the private environment
17+
* of this invocation's own Git children, through a helper this provider wrote,
18+
* and it is not in an argument, a URL, a configuration file, a launcher, the
19+
* ambient environment, a context, the Workspace, a journal, retained identity,
20+
* rendered output, a diagnostic or a failure cause.
2021
*
21-
* That is why there is no `{ username, password }` here and no file for one to
22-
* be written into. XMD acquires nothing to hand on: it says which mechanism is
23-
* in force for one locator, and Git does the asking. Approving, rejecting,
24-
* erasing, copying and persisting a credential are therefore things this
25-
* provider cannot do rather than things it declines to do.
22+
* Acquisition asks the invoking user's ordinary helper chain once, about one
23+
* exact repository. That is where a platform keychain, a cached token or a
24+
* credential manager lives, and asking it is the whole point: a workflow reaches
25+
* a private clone wherever the equivalent local Git command reaches one.
26+
*
27+
* ## Two failures that must not be confused
28+
*
29+
* A host that holds no credential, an answer that is incomplete and an answer
30+
* about somewhere else are all *authentication unavailability* — ordinary live
31+
* conditions this run reports and continues past. A helper that could not be
32+
* installed, a `git credential fill` that could not be run, a marker that could
33+
* not be read: those are the machine failing to provide a mechanism, and they
34+
* fail the run stop. Reporting infrastructure as "no credential" would turn a
35+
* broken host into a clean refusal.
2636
*
2737
* ## Why the host decides, and the checkout cannot
2838
*
2939
* `host.ts` builds Git's environment from nothing precisely so a workflow's
3040
* behavior does not depend on whose machine created it. Configuration is still
31-
* built from nothing: `GIT_CONFIG_GLOBAL`, `GIT_CONFIG_SYSTEM` and
32-
* `GIT_CONFIG_NOSYSTEM` stay as they were, so no `~/.gitconfig` URL rewrite,
33-
* `core.hooksPath` or `init.templateDir` is read. What a session adds is the
34-
* narrow set of things a standard credential helper needs in order to reach the
35-
* user's own keychain or store, and the helper names themselves, re-stated on
36-
* the command line where this provider chose them rather than inherited them.
37-
*
38-
* The retained checkout has no say at all. A `.git/config` a document wrote is
41+
* built from nothing, and the transport's arguments reset ambient credential
42+
* helpers and install only the provider-owned one — no ambient `credential.*`
43+
* definition or value is copied there. A `.git/config` a document wrote is
3944
* inside the Workspace and restored by replay, so a `credential.helper` or a
40-
* `core.sshCommand` in one would be document-authored data naming a program.
41-
* Both are fixed on the command line — where they outrank every configuration
42-
* file — for every invocation that transports to a remote, and the
43-
* `credential.helper` list is reset before the host's own choice is stated.
45+
* `core.sshCommand` in one would be document-authored data naming a program;
46+
* both are fixed on the command line, where they outrank every configuration
47+
* file, for every invocation that transports to a remote.
4448
*
4549
* ## What each transport borrows
4650
*
4751
* **SSH** borrows the agent, and only the agent. `HOME` stays the disposable
4852
* materialization, so no key file on the machine is reachable and no
49-
* `~/.ssh/config` is read; `IdentityAgent` names the ambient socket outright, so
50-
* the keys this run can offer are exactly the ones the invoking user has
51-
* unlocked. Host verification stays on and its material is the invoking user's
53+
* `~/.ssh/config` is read; `IdentityAgent` names the ambient socket outright.
54+
* Host verification stays on and its material is the invoking user's
5255
* `known_hosts`, selected here rather than found: an unknown host is a refusal,
5356
* never a key accepted on this run's behalf.
5457
*
55-
* **HTTP** borrows the credential helpers the invoking user configured, and the
56-
* environment those helpers need to answer. Git queries them for the exact URL
57-
* it is transporting to, which is a more exact question than this module could
58-
* ask on its behalf. `core.excludesFile` and `core.attributesFile` are pinned
59-
* alongside, because with configuration itself off they are the only remaining
60-
* things a passed-through `HOME` would decide.
58+
* **HTTP** borrows one answer from the user's helper chain, and hands it onward
59+
* only through the provider-owned helper described in `credential-helper.ts`.
6160
*/
6261

6362
import { ensure, type Operation, resource, until } from "effection";
@@ -373,21 +372,19 @@ export function denoCredentialBroker(
373372
env["SSH_ASKPASS"] = "";
374373
env["LC_ALL"] = "C";
375374

376-
let outcome: { code: number; stdout: string };
377-
try {
378-
outcome = yield* runProcess({
379-
command: "git",
380-
args: ["-c", "credential.useHttpPath=true", "credential", "fill"],
381-
cwd: directory,
382-
env,
383-
input:
384-
`protocol=${request.protocol}\nhost=${request.host}\n` +
385-
`${request.path === undefined ? "" : `path=${request.path}\n`}\n`,
386-
});
387-
} catch {
388-
yield* provide(unacquired());
389-
return;
390-
}
375+
// No `try` around this. A `git credential fill` that could not be
376+
// started, or that failed in a way this host cannot run past, is the
377+
// machine failing to provide a mechanism rather than a machine that
378+
// holds no credential — and the two must not report the same thing.
379+
const outcome = yield* runProcess({
380+
command: "git",
381+
args: ["-c", "credential.useHttpPath=true", "credential", "fill"],
382+
cwd: directory,
383+
env,
384+
input:
385+
`protocol=${request.protocol}\nhost=${request.host}\n` +
386+
`${request.path === undefined ? "" : `path=${request.path}\n`}\n`,
387+
});
391388
if (outcome.code !== 0) {
392389
yield* provide(unacquired());
393390
return;

‎packages/workflow/src/deno/composition/credential-helper.ts‎

Lines changed: 39 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,8 @@
3434
* credential is needed.
3535
*/
3636

37+
import { type Operation, until } from "effection";
38+
import { writeFile } from "node:fs/promises";
3739
import process from "node:process";
3840

3941
/** The private variables a helper is given, and nothing else. */
@@ -174,46 +176,57 @@ export function answerCredentialRequest(
174176
: `username=${username}\npassword=${password}\n`;
175177
}
176178

177-
/** Read everything on standard input, which Git closes when it has finished. */
179+
/**
180+
* Everything on standard input, which Git closes when it has finished.
181+
*
182+
* A stream error is raised rather than read as an empty request. Empty is a
183+
* question about nothing, which this helper answers by declining — and a helper
184+
* that declined because its input broke would be reporting "no credential" for
185+
* an infrastructure failure.
186+
*/
178187
function readAll(): Promise<string> {
179-
return new Promise((resolve) => {
188+
return new Promise((resolve, reject) => {
180189
let buffered = "";
181190
process.stdin.setEncoding("utf8");
182191
process.stdin.on("data", (chunk: string) => {
183192
buffered += chunk;
184193
});
185194
process.stdin.on("end", () => resolve(buffered));
186-
process.stdin.on("error", () => resolve(buffered));
195+
process.stdin.on("error", (error: Error) => reject(error));
187196
});
188197
}
189198

199+
/** Whether these arguments select the internal helper mode. */
200+
export function isCredentialHelperMode(argv: readonly string[]): boolean {
201+
return argv[0] === HELPER_MODE;
202+
}
203+
190204
/**
191-
* Run the internal helper mode when these arguments select it.
205+
* Run the internal helper mode, to completion.
206+
*
207+
* An operation rather than a detached promise: reading the request, writing the
208+
* marker and writing the answer are the whole of what this program does, and a
209+
* failure in any of them is a helper that did not do its job. A marker write
210+
* that failed in the background would leave a rejection unrecorded and the run
211+
* reporting that nothing was refused.
192212
*
193213
* An internal execution mode, not a command: it appears in no help and in no
194-
* public grammar, it is dispatched before anything public is parsed, and it can
195-
* acquire nothing — without the private environment its invocation built, it has
196-
* nothing to answer with.
214+
* public grammar, it is dispatched before anything public is parsed, and without
215+
* the private environment its invocation built it has nothing to answer with.
197216
*/
198-
export function runCredentialHelperMode(argv: readonly string[]): boolean {
199-
if (argv[0] !== HELPER_MODE) {
200-
return false;
201-
}
217+
export function* runCredentialHelper(argv: readonly string[]): Operation<void> {
202218
const operation = argv[1] ?? "";
203-
void readAll().then(async (input) => {
204-
const { writeFile } = await import("node:fs/promises");
205-
let marked: string | undefined;
206-
const answer = answerCredentialRequest(operation, input, process.env, (path) => {
207-
marked = path;
208-
});
209-
if (marked !== undefined) {
210-
// A fixed, nonsecret byte. What it records is that a rejection happened,
211-
// never what was rejected.
212-
await writeFile(marked, "rejected\n", { mode: 0o600 });
213-
}
214-
if (answer !== "") {
215-
process.stdout.write(answer);
216-
}
219+
const input = yield* until(readAll());
220+
let marked: string | undefined;
221+
const answer = answerCredentialRequest(operation, input, process.env, (path) => {
222+
marked = path;
217223
});
218-
return true;
224+
if (marked !== undefined) {
225+
// A fixed, nonsecret byte. What it records is that a rejection happened,
226+
// never what was rejected. A failure to record it is this helper failing.
227+
yield* until(writeFile(marked, "rejected\n", { mode: 0o600 }));
228+
}
229+
if (answer !== "") {
230+
process.stdout.write(answer);
231+
}
219232
}

0 commit comments

Comments
 (0)