Skip to content

Commit 8e3ddc5

Browse files
committed
🔒 Publish a Workspace attachment a loaded package cannot subvert
The public-boundary correction. Everything else in this contract is arithmetic on a credential that has already been read if the surface around it hands one out. `@executablemd/workflow/deno` published `withWorkflowWorkspace` with its full options, `denoRepositoryHost`, `RepositoryHost`, `GitInvocation`, `GitOutcome` and the composition provider's own types. A host sees every Git invocation, and an authenticated one carries the attachment the credential travels in — so a package a document loaded could have installed a recorder and read what the adapter was holding. It would not have had to break anything to do it. The entrypoint now offers `withWorkflowHostWorkspace` and `WorkflowHostOptions`: which issue tracker this host authorizes, and how it assembles its own credential helper. Nothing that could observe or become a Git host crosses it. The broad options are unchanged and reachable from inside the package, which is where the suites that substitute a subprocess live and where nothing a loaded package writes can reach. `public-entrypoint.test.ts` asks from outside: it reads the module's own names rather than the source, looks for each seam by name, checks the attachment's arity for a positional way in, and builds the recording host an attacker would want to find nowhere to put it. Re-exporting `denoRepositoryHost` fails two of its five steps, so it is a question rather than a description. Refs #522
1 parent 2d48647 commit 8e3ddc5

6 files changed

Lines changed: 170 additions & 17 deletions

File tree

‎architecture.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1150,7 +1150,13 @@ redirect at all, since Git would otherwise carry a credential it already holds
11501150
to a destination this run never authorized. `store` and `approve` reach no ambient helper
11511151
or store; `erase` for the exact locator writes a fixed, nonsecret marker, which
11521152
is how a refused identity is told from an absent one. Both are authentication
1153-
unavailability, never an invalid locator. Infrastructure is only what the adapter
1153+
unavailability, never an invalid locator. The containment is only worth what the surface around it allows: a substituted
1154+
Git host sees every invocation, and an authenticated one carries the attachment
1155+
the credential travels in. So the published Deno entrypoint offers a Workspace
1156+
attachment that accepts what a host owns and nothing that could observe or
1157+
become that host; the broad options stay inside the package.
1158+
1159+
Infrastructure is only what the adapter
11541160
watched fail: starting acquisition, installing the launcher, reading the marker
11551161
for any reason but its absence, and removing what it made. The absence of a
11561162
signal from the helper proves nothing — there is no readiness, preflight or

‎packages/cli/src/deno-workflow.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ import {
2222
useWorkflowInputDelivery,
2323
useWorkflowLifecycle,
2424
useWorkflowRunHost,
25-
withWorkflowWorkspace,
25+
withWorkflowHostWorkspace,
2626
} from "@executablemd/workflow/deno";
2727
import type { WorkflowExecutionTransitions } from "@executablemd/workflow/deno";
2828
import type { WorkflowRunDatabase } from "@executablemd/workflow";
@@ -55,7 +55,7 @@ export function* useDenoWorkflowHost(helper: HelperAssembly): Operation<Workflow
5555
return useWorkflowInputDelivery({ root });
5656
},
5757
attach<T>(database: WorkflowRunDatabase, operation: Operation<T>): Operation<T> {
58-
return withWorkflowWorkspace(database, operation, {
58+
return withWorkflowHostWorkspace(database, operation, {
5959
...(gitHubIssues === undefined ? {} : { gitHubIssues }),
6060
helper,
6161
});

‎packages/workflow/deno.ts‎

Lines changed: 8 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -44,27 +44,21 @@ export {
4444
workflowRunPath,
4545
} from "./src/deno/path.ts";
4646
export { APPLICATION_ID, SCHEMA_VERSION } from "./src/deno/schema.ts";
47-
export { withWorkflowWorkspace } from "./src/deno/workspace/host.ts";
48-
export type { WorkflowWorkspaceOptions } from "./src/deno/workspace/host.ts";
49-
export {
50-
WORKSPACE_GIT_ADD,
51-
WORKSPACE_GIT_SWITCH,
52-
WORKSPACE_REPOSITORY,
53-
WORKSPACE_WORKTREE,
54-
} from "./src/deno/composition/provider.ts";
55-
export type {
56-
CompositionObserver,
57-
CompositionProviderOptions,
58-
} from "./src/deno/composition/provider.ts";
59-
export { denoRepositoryHost } from "./src/deno/composition/host.ts";
47+
// The narrow one. `withWorkflowWorkspace` and its options carry the leaf
48+
// substitutions a suite needs — the Git subprocess, the temporary directory, the
49+
// Git-host transport — and a `RepositoryHost` sees every `GitInvocation`,
50+
// attachment included. A package that could install one could read the
51+
// credential this adapter is holding, so none of that crosses this entrypoint;
52+
// the suites that need it import from source, inside the package.
53+
export { withWorkflowHostWorkspace } from "./src/deno/workspace/host.ts";
54+
export type { WorkflowHostOptions } from "./src/deno/workspace/host.ts";
6055
export {
6156
GITHUB,
6257
parseGitHubIssueTarget,
6358
recognizesGitHubUrl,
6459
useGitHubIssues,
6560
} from "./src/deno/issue/github.ts";
6661
export type { GitHubIssuesOptions } from "./src/deno/issue/github.ts";
67-
export type { GitInvocation, GitOutcome, RepositoryHost } from "./src/deno/composition/host.ts";
6862
export { WORKSPACE_FILE } from "./src/deno/workspace/files.ts";
6963
export { WORKSPACE_ROOT } from "./src/deno/workspace/logical-path.ts";
7064
export { useWorkflowInputDelivery } from "./src/deno/delivery.ts";

‎packages/workflow/src/deno/workspace/host.ts‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,44 @@ export interface WorkflowWorkspaceOptions {
9999
readonly helper?: HelperAssembly;
100100
}
101101

102+
/**
103+
* What a host may configure from outside this package.
104+
*
105+
* Deliberately not {@link WorkflowWorkspaceOptions}. That type carries the leaf
106+
* substitutions a suite needs — the Git subprocess, the temporary directory, the
107+
* Git-host transport — and any one of them is a seam through which a credential
108+
* this run acquires would become visible to whoever supplied it. A
109+
* `RepositoryHost` sees every `GitInvocation`, and an authenticated invocation
110+
* carries its attachment; a package that could install one could read what the
111+
* adapter is holding.
112+
*
113+
* So the public surface is what a *host* legitimately decides: which issue
114+
* tracker it authorizes, and how it assembles its own credential helper. The
115+
* broad options remain reachable from inside this package, where the suites that
116+
* need them live and where nothing a loaded package writes can reach.
117+
*/
118+
export interface WorkflowHostOptions {
119+
readonly gitHubIssues?: GitHubIssuesOptions;
120+
readonly helper?: HelperAssembly;
121+
}
122+
123+
/**
124+
* Run `operation` with this run's Workspace attached, as a host installs it.
125+
*
126+
* The one entrypoint outside this package. It accepts what a host owns and
127+
* nothing that could observe an authenticated Git invocation.
128+
*/
129+
export function withWorkflowHostWorkspace<T>(
130+
database: WorkflowRunDatabase,
131+
operation: Operation<T>,
132+
options: WorkflowHostOptions = {},
133+
): Operation<T> {
134+
return withWorkflowWorkspace(database, operation, {
135+
...(options.gitHubIssues === undefined ? {} : { gitHubIssues: options.gitHubIssues }),
136+
...(options.helper === undefined ? {} : { helper: options.helper }),
137+
});
138+
}
139+
102140
/** Run `operation` with this run's Workspace attached to the document. */
103141
export function withWorkflowWorkspace<T>(
104142
database: WorkflowRunDatabase,
Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
/**
2+
* Tier WA — what a loaded package can reach through the published entrypoint.
3+
*
4+
* The adapter holds a credential in memory for one invocation and hands it to
5+
* its own Git children. That containment is only worth as much as the surface
6+
* around it: a `RepositoryHost` sees every `GitInvocation`, and an authenticated
7+
* one carries the attachment the credential travels in. If a package that a
8+
* document loaded could install one — or reach the options that accept one —
9+
* then everything else in this contract is arithmetic on a value it has already
10+
* read.
11+
*
12+
* So this suite asks the question from outside. It imports the entrypoint the
13+
* way anybody else would, and looks for the seams rather than trusting that they
14+
* are absent.
15+
*/
16+
17+
import { describe, it } from "@executablemd/test-support/bdd";
18+
import { expect } from "@executablemd/test-support/expect";
19+
import * as published from "../deno.ts";
20+
import type { WorkflowHostOptions } from "../deno.ts";
21+
// Source-relative, and only resolvable for code that already lives here.
22+
import { withWorkflowWorkspace } from "../src/deno/workspace/host.ts";
23+
24+
/** The seams a host may configure, and the whole of them. */
25+
const HOST_OWNED = ["gitHubIssues", "helper"] as const;
26+
27+
/**
28+
* Every name a package that imported the entrypoint can see.
29+
*
30+
* Read from the module rather than from the source, so a re-export added
31+
* anywhere in the graph is caught here rather than by reading the file it was
32+
* added to.
33+
*/
34+
const REACHABLE = Object.keys(published);
35+
36+
describe("workflow published Deno entrypoint", () => {
37+
it("offers nothing that can observe a Git invocation", function* () {
38+
// Each of these is a way to see, or to become, the thing an authenticated
39+
// command runs through. None of them is a host's business, and none is
40+
// published.
41+
for (const seam of [
42+
"denoRepositoryHost",
43+
"withWorkflowWorkspace",
44+
"useRepositoryComposition",
45+
"useGitComposition",
46+
"denoGitAuthentication",
47+
"denoCredentialBroker",
48+
]) {
49+
expect(REACHABLE).not.toContain(seam);
50+
}
51+
});
52+
53+
it("publishes one Workspace attachment, and it is the narrow one", function* () {
54+
expect(REACHABLE).toContain("withWorkflowHostWorkspace");
55+
expect(REACHABLE).not.toContain("withWorkflowWorkspace");
56+
});
57+
58+
it("accepts only what a host owns", function* () {
59+
// A value, so the shape is checked by the compiler rather than described in
60+
// a comment. Adding `composition` here stops compiling, which is the point:
61+
// the option that carries a substituted host is not on this type.
62+
const options: WorkflowHostOptions = {};
63+
const named: readonly string[] = HOST_OWNED;
64+
expect(named).toEqual(["gitHubIssues", "helper"]);
65+
expect(Object.keys(options)).toEqual([]);
66+
});
67+
68+
it("hands a substituted host no route in, however it is spelled", function* () {
69+
// The exploit, attempted rather than reasoned about: a package that loaded
70+
// this entrypoint builds the recording host it would want and looks for
71+
// somewhere to put it.
72+
const recorded: unknown[] = [];
73+
const hostile = {
74+
git(invocation: unknown) {
75+
recorded.push(invocation);
76+
return { code: 0, stdout: "", stderr: "" };
77+
},
78+
useDirectory: () => "/tmp",
79+
};
80+
81+
const attempted = published as unknown as Record<string, unknown>;
82+
// Nothing published takes one. `withWorkflowHostWorkspace` is the only
83+
// attachment, and its third argument names two members, neither of which is
84+
// a host.
85+
const attach = attempted["withWorkflowHostWorkspace"];
86+
expect(typeof attach).toBe("function");
87+
// Its own arity: a database, an operation, and options. A fourth positional
88+
// seam would be another way in.
89+
expect((attach as (...args: unknown[]) => unknown).length).toBeLessThanOrEqual(3);
90+
91+
// And no published name is a host factory that would produce one either.
92+
for (const name of REACHABLE) {
93+
expect(name).not.toContain("RepositoryHost");
94+
expect(name).not.toContain("Composition");
95+
}
96+
expect(recorded).toEqual([]);
97+
expect(hostile.git({})).toEqual({ code: 0, stdout: "", stderr: "" });
98+
});
99+
100+
it("keeps the broad options reachable from inside the package", function* () {
101+
// Not a loophole: this import is source-relative and only resolves for code
102+
// that already lives here. The suites that substitute a Git subprocess need
103+
// it, and a loaded package cannot write it.
104+
expect(typeof withWorkflowWorkspace).toBe("function");
105+
});
106+
});

‎specs/workflow-workspace-spec.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2398,6 +2398,15 @@ transport would ordinarily have — a locator that could not be used stays that,
23982398
and a host that could not be reached stays unreachable. Missing or incomplete
23992399
credentials, and an exact rejection, remain authentication unavailability.
24002400

2401+
What the published entrypoint offers is what a *host* owns: which issue tracker
2402+
it authorizes, and how it assembles its own credential helper. The leaf
2403+
substitutions a suite needs — the Git subprocess, the temporary directory, the
2404+
Git-host transport — do not cross it. A `RepositoryHost` sees every Git
2405+
invocation and an authenticated one carries the credential's attachment, so a
2406+
package a document loaded must have no way to install one, and no way to reach
2407+
the options that would accept one. Those remain reachable only from inside the
2408+
package, where the suites that need them live.
2409+
24012410
The helper contract is assembled the same way for Deno source, compiled and
24022411
Windows hosts. Which one applies is stated by the runtime entrypoint rather than
24032412
inferred from an executable's name, and the mode it dispatches is internal: it

0 commit comments

Comments
 (0)