Skip to content

Commit b1c33b3

Browse files
committed
🔐 Refuse a rejected credential, and tear a lease down in order
Continues e81561c. A6's correction, the ordering correction, and the evidence for exclusivity, teardown, infrastructure failure, Windows and host assembly. **`erase` is a signal, not an erasure.** Git sends it when a transport refused what the helper gave, and it is the only way this run can tell "the host proved nothing" from "the host proved something the remote would not accept". It is never forwarded, reaches no helper or keychain, and produces no output — it tells the broker, the broker tells its parent, and the refusal vocabulary reads it. Both cases are `authentication-unavailable`; neither is an invalid locator. A rejection belongs to the lease it happened on: the next invocation's lease knows nothing about it, and an erase about another repository is ignored. **Teardown order is observed, not assumed.** Invalidate the lease, terminate the group, close the IPC, await every child, then remove the endpoint and the launcher. Each step announces itself and a test asserts the sequence, because these same steps in another order would leave a live broker addressable by a path nobody owns. **Exclusivity is per lease.** One caller answered at a time — three at once cannot all be this invocation — while a reconciliation's sequential commands are all answered. **Infrastructure failure is a host condition.** A broker mode that is not there produces no lease, no credential and no completion, and still removes what it made. A socket spoken to badly is answered with nothing. **Windows is proved on this host**, because the platform is a parameter: a random invocation-local pipe name, different per lease, with no all-user access option — and the capability still validated before any credential byte, which is what makes the name enough. **Both entrypoints assemble the same two modes**: from source the executable is Deno and the module is named to it; compiled, the executable is the host and carries its own. Architecture and §13.1 now describe the broker child rather than the environment-bearing lease that preceded it. Refs #522
1 parent e81561c commit b1c33b3

8 files changed

Lines changed: 448 additions & 40 deletions

File tree

‎architecture.md‎

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1141,14 +1141,22 @@ the mutation it decided go out under one identity rather than two, and the
11411141
session is disposed with the invocation. A later attempt on an interrupted
11421142
request opens its own.
11431143

1144-
No credential value crosses that boundary and none is written anywhere. A
1145-
host-owned broker is queried once, for the complete locator, and owns whatever
1146-
it acquires; what the invocation holds is an opaque lease, which says whether an
1147-
identity was proved and can attach itself to a command. The value reaches native
1148-
Git through Git's own credential protocol and materializes nowhere but the
1149-
environment of the one subprocess it speaks for. Approving, rejecting, erasing,
1150-
copying and persisting a credential are therefore things the provider cannot do
1151-
rather than things it declines to do. A Git-host API is the same shape in a different
1144+
No credential value reaches the workflow process at all. Acquisition happens in
1145+
a broker child started for one live invocation, which asks the invoking user's
1146+
Git about one exact repository and holds what comes back; the provider holds a
1147+
capability and a private endpoint, and a provider-owned shim is what Git runs.
1148+
Approving, rejecting, erasing, copying and persisting a credential are therefore
1149+
things this process cannot do rather than things it declines to do — there is
1150+
nothing in it to do them with.
1151+
1152+
The broker answers one operation, for one capability, about one locator, so a
1153+
redirected transport is answered with nothing. `erase` is not forwarded: it
1154+
becomes an invocation-local signal that the remote refused what it was given,
1155+
which is why a rejected credential and an absent one report the same
1156+
unavailability. Teardown is ordered — invalidate, terminate the group, close the
1157+
IPC, await the children, then remove the endpoint and the launcher — because the
1158+
same steps in another sequence would leave a live broker addressable by a path
1159+
nobody owns. A Git-host API is the same shape in a different
11521160
protocol: `GH_TOKEN`, then `GITHUB_TOKEN`, then the machine's own login, read
11531161
once for the invocation that needs it.
11541162

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

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,14 @@ export interface GitAuthenticationSession {
102102
* locator was wrong.
103103
*/
104104
readonly mechanism: GitAuthenticationMechanism;
105+
/**
106+
* Whether the transport rejected the identity this session gave it.
107+
*
108+
* Read after a command fails, not before it runs. A host that proved an
109+
* identity the remote refused is in the same position as one that could prove
110+
* none, and the refusal vocabulary says so.
111+
*/
112+
readonly rejected: boolean;
105113
}
106114

107115
/**
@@ -134,6 +142,7 @@ const NOTHING: GitAttachment = Object.freeze({
134142
export const UNAUTHENTICATED: GitAuthenticationSession = Object.freeze({
135143
attachment: NOTHING,
136144
mechanism: "none",
145+
rejected: false,
137146
});
138147

139148
/**
@@ -310,6 +319,7 @@ export function denoGitAuthentication(options: GitAuthenticationOptions = {}): G
310319
configuration: pinned(ssh, []),
311320
},
312321
mechanism: present ? "ssh-agent" : "none",
322+
rejected: false,
313323
});
314324
return;
315325
}
@@ -324,6 +334,9 @@ export function denoGitAuthentication(options: GitAuthenticationOptions = {}): G
324334
environment: attached.environment,
325335
configuration: pinned(ssh, attached.configuration),
326336
},
337+
get rejected() {
338+
return lease?.rejected === true;
339+
},
327340
// Acquisition, not configuration. A helper that answered nothing
328341
// leaves this `none`, and a transport that then fails failed for want
329342
// of authentication rather than because the locator was wrong.
@@ -355,5 +368,12 @@ export function noGitAuthentication(): GitAuthentication {
355368
* and from a remote that holds nothing.
356369
*/
357370
export function unauthenticable(locator: string, session: GitAuthenticationSession): boolean {
358-
return gitTransport(locator) !== "none" && session.mechanism === "none";
371+
if (gitTransport(locator) === "none") {
372+
return false;
373+
}
374+
// Two ways to have no usable identity: none was proved, or one was proved and
375+
// the remote refused it. Git tells a helper the second by asking it to erase,
376+
// which this provider turns into a signal rather than an erasure. Neither is
377+
// a locator that names nothing.
378+
return session.mechanism === "none" || session.rejected;
359379
}

‎packages/workflow/src/deno/composition/broker/child.ts‎

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,16 @@ import { Buffer } from "node:buffer";
3030
import { createServer, type Socket } from "node:net";
3131
import process from "node:process";
3232
import { spawnSync } from "node:child_process";
33-
import { ACQUIRED, decodeQuestion, encodeLine, GET, READY, sameSecret } from "./protocol.ts";
33+
import {
34+
ACQUIRED,
35+
decodeQuestion,
36+
encodeLine,
37+
GET,
38+
READY,
39+
REFUSED,
40+
REJECTED,
41+
sameSecret,
42+
} from "./protocol.ts";
3443

3544
/** What one broker was started to be about. */
3645
export interface BrokerSubject {
@@ -132,7 +141,6 @@ function about(
132141
): boolean {
133142
return (
134143
sameSecret(question.capability, subject.capability) &&
135-
question.operation === GET &&
136144
question.protocol === subject.protocol &&
137145
question.host === subject.host &&
138146
question.path === subject.path
@@ -180,7 +188,20 @@ export function serveCredentialBroker(argv: readonly string[]): void {
180188
return;
181189
}
182190
const question = decodeQuestion(buffered.slice(0, end));
183-
if (question === undefined || !about(subject, question) || held === undefined) {
191+
if (question === undefined || !about(subject, question)) {
192+
answer({});
193+
return;
194+
}
195+
if (question.operation === REJECTED) {
196+
// Told, not obeyed. Nothing is forgotten, nothing is forwarded and
197+
// nothing is answered — the parent learns that this lease's identity
198+
// was refused by the remote, which is a live authentication condition
199+
// rather than a locator that names nothing.
200+
process.stdout.write(`${REFUSED}\n`);
201+
answer({});
202+
return;
203+
}
204+
if (question.operation !== GET || held === undefined) {
184205
answer({});
185206
return;
186207
}

‎packages/workflow/src/deno/composition/broker/host.ts‎

Lines changed: 63 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ import { chmod, mkdtemp, rm, writeFile } from "node:fs/promises";
3939
import { tmpdir } from "node:os";
4040
import { join } from "node:path";
4141
import process from "node:process";
42-
import { CAPABILITY_VARIABLE, ENDPOINT_VARIABLE, READY, ACQUIRED } from "./protocol.ts";
42+
import { ACQUIRED, CAPABILITY_VARIABLE, ENDPOINT_VARIABLE, READY, REFUSED } from "./protocol.ts";
4343

4444
/** What a lease hands the command it speaks for. */
4545
export interface GitAttachment {
@@ -63,6 +63,15 @@ export interface CredentialRequest {
6363
export interface CredentialLease {
6464
/** Whether the host proved an identity for this lease's exact locator. */
6565
readonly acquired: boolean;
66+
/**
67+
* Whether the transport rejected the identity this lease gave it.
68+
*
69+
* Git's `erase` reaches the shim when a remote refused what it was handed.
70+
* Nothing is erased; the signal comes here. A run that proved an identity and
71+
* had it refused is in the same position as one that could prove none —
72+
* authentication unavailability, never an invalid locator.
73+
*/
74+
readonly rejected: boolean;
6675
/** What one command attaches to speak for this lease. */
6776
attachment(): GitAttachment;
6877
}
@@ -74,8 +83,25 @@ export interface CredentialBroker {
7483
export interface BrokerObserver {
7584
opened?: (directory: string) => void;
7685
released?: (directory: string) => void;
86+
/**
87+
* Each step of teardown, as it happens.
88+
*
89+
* The order is the contract — a lease invalidated after its endpoint went
90+
* away, or an endpoint removed while a broker still answered on it, would be
91+
* the same steps in an unsafe sequence. A suite watches rather than infers.
92+
*/
93+
step?: (name: string) => void;
7794
}
7895

96+
/** The steps teardown takes, in the order it must take them. */
97+
export const TEARDOWN = Object.freeze({
98+
invalidated: "invalidated",
99+
terminated: "terminated",
100+
closed: "ipc-closed",
101+
awaited: "awaited",
102+
removed: "removed",
103+
});
104+
79105
/**
80106
* How this host starts one of its own unadvertised internal modes.
81107
*
@@ -101,15 +127,25 @@ const NOTHING: GitAttachment = Object.freeze({
101127

102128
const NO_LEASE: CredentialLease = Object.freeze({
103129
acquired: false,
130+
rejected: false,
104131
attachment: () => NOTHING,
105132
});
106133

107-
/** Where this lease's endpoint lives, by what the platform can protect. */
108-
function endpointFor(directory: string): string {
109-
return process.platform === "win32"
110-
? // A pipe has no directory to hide in, so its name is the secret it has:
111-
// random, invocation-local, and created with no all-user access.
112-
`\\\\.\\pipe\\xmd-credential-${randomBytes(24).toString("hex")}`
134+
/**
135+
* Where this lease's endpoint lives, by what the platform can protect.
136+
*
137+
* A Unix socket hides in a directory only this user may enter. A named pipe has
138+
* no directory to hide in, so what it has instead is a name nobody can guess:
139+
* random, invocation-local, and created with no all-user access option. Neither
140+
* is trusted on its own — the capability is checked before a credential byte is
141+
* emitted either way.
142+
*
143+
* The platform is a parameter so a suite can prove the Windows shape on a host
144+
* that is not Windows.
145+
*/
146+
export function endpointFor(directory: string, platform: string = process.platform): string {
147+
return platform === "win32"
148+
? `\\\\.\\pipe\\xmd-credential-${randomBytes(24).toString("hex")}`
113149
: join(directory, "endpoint");
114150
}
115151

@@ -158,23 +194,32 @@ export function denoCredentialBroker(options: BrokerOptions): CredentialBroker {
158194
const finished = withResolvers<void>();
159195

160196
yield* ensure(function* () {
161-
// Invalidate first: a shim that connects from here on is answered by
162-
// nothing, rather than racing a broker that is going away.
197+
// The order is the contract, and each step is announced as it is
198+
// taken. Invalidate first, so a shim that connects from here on is
199+
// answered by nothing rather than racing a broker that is going away.
163200
closed = true;
201+
observe.step?.(TEARDOWN.invalidated);
164202
if (child !== undefined) {
165-
child.stdin?.end();
203+
// The group, so a helper the broker started goes with it.
166204
try {
167205
if (child.pid !== undefined) {
168206
process.kill(-child.pid, "SIGKILL");
169207
}
170208
} catch {
171209
child.kill("SIGKILL");
172210
}
211+
observe.step?.(TEARDOWN.terminated);
212+
// Then the pipe that is the lease's lifetime: a broker that somehow
213+
// survived the signal reads end-of-file and exits on its own.
214+
child.stdin?.end();
215+
observe.step?.(TEARDOWN.closed);
173216
yield* finished.operation;
217+
observe.step?.(TEARDOWN.awaited);
174218
}
175-
// Only now: an endpoint removed while a broker still answered on it
219+
// Only now. An endpoint removed while a broker still answered on it
176220
// would be a live service nobody owns.
177221
yield* until(rm(directory, { recursive: true, force: true }));
222+
observe.step?.(TEARDOWN.removed);
178223
observe.released?.(directory);
179224
});
180225

@@ -206,12 +251,16 @@ export function denoCredentialBroker(options: BrokerOptions): CredentialBroker {
206251
const started = withResolvers<boolean>();
207252
let announced = "";
208253
let acquired = false;
254+
let rejected = false;
209255
child.stdout?.setEncoding("utf8");
210256
child.stdout?.on("data", (chunk: string) => {
211257
announced += chunk;
212258
if (announced.includes(ACQUIRED)) {
213259
acquired = true;
214260
}
261+
if (announced.includes(REFUSED)) {
262+
rejected = true;
263+
}
215264
if (announced.includes(READY)) {
216265
started.resolve(true);
217266
}
@@ -236,6 +285,9 @@ export function denoCredentialBroker(options: BrokerOptions): CredentialBroker {
236285
get acquired() {
237286
return acquired && !closed;
238287
},
288+
get rejected() {
289+
return rejected;
290+
},
239291
attachment: () =>
240292
closed
241293
? NOTHING

‎packages/workflow/src/deno/composition/broker/protocol.ts‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,21 @@
2121
export const ENDPOINT_VARIABLE = "XMD_CREDENTIAL_ENDPOINT";
2222
export const CAPABILITY_VARIABLE = "XMD_CREDENTIAL_CAPABILITY";
2323

24-
/** The only operation this service performs. */
24+
/** The only operation this service answers. */
2525
export const GET = "get";
2626

27+
/**
28+
* The operation a shim sends when Git tells it to forget a credential.
29+
*
30+
* Not a forwarding of Git's `erase`: nothing is forgotten anywhere, and no
31+
* helper, keychain or store is reached. It is a signal, local to this
32+
* invocation, that the transport rejected what it was given — which is the one
33+
* thing that distinguishes a credential this host could not prove from a
34+
* credential it proved and the remote refused. Both are authentication
35+
* unavailability; neither is an invalid locator.
36+
*/
37+
export const REJECTED = "rejected";
38+
2739
/**
2840
* One question the shim asks the broker.
2941
*
@@ -52,6 +64,9 @@ export const READY = "xmd-credential-broker-ready";
5264
/** The line a broker prints when it acquired an identity for its lease. */
5365
export const ACQUIRED = "xmd-credential-broker-acquired";
5466

67+
/** The line a broker prints when its lease's transport rejected what it gave. */
68+
export const REFUSED = "xmd-credential-broker-refused";
69+
5570
/** One record, as a line. A value can hold no newline, so a line holds one. */
5671
export function encodeLine(value: unknown): string {
5772
return `${JSON.stringify(value)}\n`;

‎packages/workflow/src/deno/composition/broker/shim.ts‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ import {
2626
encodeLine,
2727
ENDPOINT_VARIABLE,
2828
GET,
29+
REJECTED,
2930
} from "./protocol.ts";
3031

3132
/** The fields Git wrote, as far as they can be read. */
@@ -64,8 +65,9 @@ function readAll(): Promise<string> {
6465
export async function serveCredentialShim(argv: readonly string[]): Promise<void> {
6566
const operation = argv[0] ?? "";
6667
const input = await readAll();
67-
if (operation !== GET) {
68-
// `store` and `erase` are read to the end and answered with silence.
68+
if (operation !== GET && operation !== "erase") {
69+
// `store`, `approve` and anything else are read to the end and answered
70+
// with silence. Nothing is written, forwarded or remembered.
6971
return;
7072
}
7173

@@ -78,7 +80,11 @@ export async function serveCredentialShim(argv: readonly string[]): Promise<void
7880
const asked = readRequest(input);
7981
const question = encodeLine({
8082
capability,
81-
operation: GET,
83+
// `erase` becomes a rejection signal rather than an erasure. Git sends it
84+
// when the transport refused what this helper gave, which is the only way
85+
// this run can tell "the host proved nothing" from "the host proved
86+
// something the remote would not accept". Both are unavailability.
87+
operation: operation === GET ? GET : REJECTED,
8288
protocol: asked.get("protocol") ?? "",
8389
// Git writes the port into `host` when there is one, which is what makes an
8490
// explicit port part of what the broker compares.
@@ -99,6 +105,10 @@ export async function serveCredentialShim(argv: readonly string[]): Promise<void
99105
socket.on("connect", () => socket.write(question));
100106
});
101107

108+
if (operation !== GET) {
109+
// A rejection produces no output at all, whatever came back.
110+
return;
111+
}
102112
const { username, password } = decodeAnswer(answer.split("\n")[0] ?? "");
103113
if (username === undefined || password === undefined) {
104114
return;

0 commit comments

Comments
 (0)