owlrunkit 0.15.0 → 0.16.0
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/CHANGELOG.md +100 -0
- package/README.md +274 -66
- package/integrations/codex/skills/owlcoda-runkit/SKILL.md +223 -117
- package/integrations/codex/skills/owlcoda-runkit/assets/templates/config.json +3 -3
- package/integrations/codex/skills/owlcoda-runkit/assets/templates/ready-for-commit-request.json +2 -2
- package/package.json +2 -2
- package/packages/attest/distribution-manifest-v1.json +10 -0
- package/packages/attest/src/quick.mjs +10 -0
- package/registry-release-policy-v1.json +8 -2
- package/sbom.spdx.json +5 -5
- package/scripts/runkit-contract/assurance-router.mjs +119 -0
- package/scripts/runkit-contract/core-contract.mjs +250 -115
- package/scripts/runkit-contract/core-successor.mjs +2043 -0
- package/scripts/runkit-contract/deployment-workflow.mjs +2040 -0
- package/scripts/runkit-contract/finalize.mjs +242 -21
- package/scripts/runkit-contract/fleet-discovery.mjs +456 -0
- package/scripts/runkit-contract/formal-workflow.mjs +850 -0
- package/scripts/runkit-contract/human-status.mjs +553 -0
- package/scripts/runkit-contract/inspect-presentation.mjs +25 -8
- package/scripts/runkit-contract/install-codex-skill.mjs +73 -30
- package/scripts/runkit-contract/lease-lifecycle.mjs +8 -2
- package/scripts/runkit-contract/lifecycle-orchestration.mjs +135 -12
- package/scripts/runkit-contract/onboarding-doctor.mjs +43 -90
- package/scripts/runkit-contract/owner-authority-trust.mjs +230 -0
- package/scripts/runkit-contract/owner-deployment-decision.mjs +385 -0
- package/scripts/runkit-contract/profile-onboarding.mjs +841 -13
- package/scripts/runkit-contract/project-cli-resolver.mjs +701 -0
- package/scripts/runkit-contract/project-control-parser.mjs +830 -0
- package/scripts/runkit-contract/project-control-state.mjs +28 -0
- package/scripts/runkit-contract/provenance-common.mjs +19 -2
- package/scripts/runkit-contract/ready-for-commit.mjs +330 -18
- package/scripts/runkit-contract/remote-deployment.mjs +1596 -0
- package/scripts/runkit-contract/remote-process-adapter.mjs +177 -0
- package/scripts/runkit-contract/runkit-bootstrap.mjs +131 -0
- package/scripts/runkit-contract/runkit-cli.mjs +1097 -21
- package/scripts/runkit-contract/schemas/assurance-route-v1.schema.json +26 -0
- package/scripts/runkit-contract/schemas/core-successor-batch-receipt-v1.schema.json +126 -0
- package/scripts/runkit-contract/schemas/core-successor-plan-v1.schema.json +155 -0
- package/scripts/runkit-contract/schemas/core-successor-project-success-receipt-v1.schema.json +72 -0
- package/scripts/runkit-contract/schemas/deployment-execute-request-v1.schema.json +63 -0
- package/scripts/runkit-contract/schemas/deployment-lineage-v1.schema.json +292 -0
- package/scripts/runkit-contract/schemas/deployment-prepare-receipt-v1.schema.json +140 -0
- package/scripts/runkit-contract/schemas/fleet-discovery-v1.schema.json +31 -0
- package/scripts/runkit-contract/schemas/fleet-manifest-v1.schema.json +20 -0
- package/scripts/runkit-contract/schemas/fleet-root-registry-v1.schema.json +34 -0
- package/scripts/runkit-contract/schemas/human-status-v1.schema.json +102 -0
- package/scripts/runkit-contract/schemas/owner-authority-trust-v1.schema.json +66 -0
- package/scripts/runkit-contract/schemas/owner-deployment-authority-v1.schema.json +46 -0
- package/scripts/runkit-contract/schemas/owner-deployment-authority-v2.schema.json +94 -0
- package/scripts/runkit-contract/schemas/owner-deployment-decision-v1.schema.json +102 -0
- package/scripts/runkit-contract/schemas/owner-migration-authority-v1.schema.json +33 -0
- package/scripts/runkit-contract/schemas/owner-migration-authority-v2.schema.json +67 -0
- package/scripts/runkit-contract/schemas/profile-apply-receipt-v1.schema.json +32 -0
- package/scripts/runkit-contract/schemas/profile-detection-v2.schema.json +145 -0
- package/scripts/runkit-contract/schemas/ready-for-commit-v2.schema.json +37 -0
- package/scripts/runkit-contract/schemas/remote-deployment-manifest-v1.schema.json +379 -0
- package/scripts/runkit-contract/schemas/remote-deployment-result-v1.schema.json +153 -0
- package/scripts/runkit-contract/schemas/remote-deployment-stage-journal-v1.schema.json +183 -0
- package/scripts/runkit-contract/schemas/remote-target-v1.schema.json +32 -0
- package/scripts/runkit-contract/schemas/source-candidate-v2.schema.json +152 -0
- package/scripts/runkit-contract/schemas/verification-receipt-v2.schema.json +13 -0
- package/scripts/runkit-contract/snapshot.mjs +1 -1
- package/scripts/runkit-contract/source-candidate.mjs +1382 -0
- package/scripts/runkit-contract/ssh-remote-adapter.mjs +1184 -0
- package/scripts/runkit-contract/sync-core016-release-identity.mjs +161 -0
- package/scripts/runkit-contract/templates/assurance-request.json +13 -0
- package/scripts/runkit-contract/templates/core-successor-owner-authority.json +15 -0
- package/scripts/runkit-contract/templates/deployment-execute-request.json +39 -0
- package/scripts/runkit-contract/templates/deployment-owner-authority.json +23 -0
- package/scripts/runkit-contract/templates/deployment-owner-decision.json +26 -0
- package/scripts/runkit-contract/templates/fleet-manifest.json +8 -0
- package/scripts/runkit-contract/templates/fleet-root-registry.json +8 -0
- package/scripts/runkit-contract/templates/owner-authority-trust.json +16 -0
- package/scripts/runkit-contract/templates/ready-for-commit-request.json +2 -2
- package/scripts/runkit-contract/templates/remote-deployment-manifest.json +108 -0
- package/scripts/runkit-contract/verification-receipt-gate.mjs +28 -0
|
@@ -0,0 +1,1184 @@
|
|
|
1
|
+
import { execFileSync } from "node:child_process";
|
|
2
|
+
import { createHash } from "node:crypto";
|
|
3
|
+
import {
|
|
4
|
+
lstatSync,
|
|
5
|
+
readFileSync,
|
|
6
|
+
realpathSync,
|
|
7
|
+
} from "node:fs";
|
|
8
|
+
import path from "node:path";
|
|
9
|
+
import { fileURLToPath } from "node:url";
|
|
10
|
+
|
|
11
|
+
import {
|
|
12
|
+
REMOTE_DEPLOYMENT_STAGES,
|
|
13
|
+
SSH_REMOTE_HELPER_PROTOCOL_V1,
|
|
14
|
+
validateSshRemoteHelperBindingV1,
|
|
15
|
+
validateRemoteTarget,
|
|
16
|
+
} from "./remote-deployment.mjs";
|
|
17
|
+
|
|
18
|
+
const SHA256 = /^[a-f0-9]{64}$/u;
|
|
19
|
+
const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
|
|
20
|
+
const SERVICE_NAME = /^[A-Za-z0-9][A-Za-z0-9_.@-]*\.service$/u;
|
|
21
|
+
const SAFE_REMOTE_PATH =
|
|
22
|
+
/^\/(?:[A-Za-z0-9._@%+=,-]+\/)*[A-Za-z0-9._@%+=,-]+$/u;
|
|
23
|
+
const SAFE_RELATIVE_PATH =
|
|
24
|
+
/^(?:[A-Za-z0-9._@%+=,-]+\/)*[A-Za-z0-9._@%+=,-]+$/u;
|
|
25
|
+
const SAFE_ENV_KEYS = [
|
|
26
|
+
"HOME",
|
|
27
|
+
"LANG",
|
|
28
|
+
"LC_ALL",
|
|
29
|
+
"PATH",
|
|
30
|
+
"SSH_AUTH_SOCK",
|
|
31
|
+
"SystemRoot",
|
|
32
|
+
"TMPDIR",
|
|
33
|
+
"USER",
|
|
34
|
+
"WINDIR",
|
|
35
|
+
];
|
|
36
|
+
const MODULE_PATH = fileURLToPath(import.meta.url);
|
|
37
|
+
|
|
38
|
+
function sha256(value) {
|
|
39
|
+
return createHash("sha256").update(value).digest("hex");
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
function isRecord(value) {
|
|
43
|
+
return value !== null && typeof value === "object" && !Array.isArray(value);
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function assertExactKeys(value, allowed, label) {
|
|
47
|
+
if (!isRecord(value)) throw new Error(`${label} must be a structured object.`);
|
|
48
|
+
const unsupported = Object.keys(value).filter((key) => !allowed.includes(key));
|
|
49
|
+
if (unsupported.length > 0) {
|
|
50
|
+
throw new Error(`${label} contains unsupported field: ${unsupported.join(", ")}`);
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
function assertIdentifier(value, label) {
|
|
55
|
+
if (typeof value !== "string" || !IDENTIFIER.test(value)) {
|
|
56
|
+
throw new Error(`${label} is invalid.`);
|
|
57
|
+
}
|
|
58
|
+
return value;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
function assertHash(value, label) {
|
|
62
|
+
if (typeof value !== "string" || !SHA256.test(value)) {
|
|
63
|
+
throw new Error(`${label} must be a lowercase SHA-256 digest.`);
|
|
64
|
+
}
|
|
65
|
+
return value;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
function assertAbsoluteLocalPath(value, label) {
|
|
69
|
+
if (
|
|
70
|
+
typeof value !== "string"
|
|
71
|
+
|| !path.isAbsolute(value)
|
|
72
|
+
|| value.includes("\0")
|
|
73
|
+
|| /[\r\n]/u.test(value)
|
|
74
|
+
) {
|
|
75
|
+
throw new Error(`${label} must be an absolute local path.`);
|
|
76
|
+
}
|
|
77
|
+
return path.normalize(value);
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
function assertRemotePath(value, label) {
|
|
81
|
+
if (
|
|
82
|
+
typeof value !== "string"
|
|
83
|
+
|| value === "/"
|
|
84
|
+
|| !SAFE_REMOTE_PATH.test(value)
|
|
85
|
+
|| path.posix.normalize(value) !== value
|
|
86
|
+
) {
|
|
87
|
+
throw new Error(`${label} must be an exact remote path.`);
|
|
88
|
+
}
|
|
89
|
+
return value;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
function assertRelativePath(value, label) {
|
|
93
|
+
if (
|
|
94
|
+
typeof value !== "string"
|
|
95
|
+
|| !SAFE_RELATIVE_PATH.test(value)
|
|
96
|
+
|| path.posix.normalize(value) !== value
|
|
97
|
+
) {
|
|
98
|
+
throw new Error(`${label} must be an exact relative path.`);
|
|
99
|
+
}
|
|
100
|
+
return value;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
function canonical(value) {
|
|
104
|
+
if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
|
|
105
|
+
if (isRecord(value)) {
|
|
106
|
+
return `{${Object.entries(value)
|
|
107
|
+
.sort(([left], [right]) => left.localeCompare(right))
|
|
108
|
+
.map(([key, nested]) => `${JSON.stringify(key)}:${canonical(nested)}`)
|
|
109
|
+
.join(",")}}`;
|
|
110
|
+
}
|
|
111
|
+
const encoded = JSON.stringify(value);
|
|
112
|
+
if (encoded === undefined) throw new Error("SSH adapter value is not canonical JSON.");
|
|
113
|
+
return encoded;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
function sameValue(left, right) {
|
|
117
|
+
return canonical(left) === canonical(right);
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
function regularFile(filePath, label) {
|
|
121
|
+
const requested = assertAbsoluteLocalPath(filePath, label);
|
|
122
|
+
const requestedStat = lstatSync(requested);
|
|
123
|
+
if (requestedStat.isSymbolicLink() || !requestedStat.isFile()) {
|
|
124
|
+
throw new Error(`${label} must be a regular non-symlink file.`);
|
|
125
|
+
}
|
|
126
|
+
const resolved = realpathSync(requested);
|
|
127
|
+
const resolvedStat = lstatSync(resolved);
|
|
128
|
+
if (resolvedStat.isSymbolicLink() || !resolvedStat.isFile()) {
|
|
129
|
+
throw new Error(`${label} must resolve to a regular file.`);
|
|
130
|
+
}
|
|
131
|
+
return resolved;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
function realDirectory(directoryPath, label) {
|
|
135
|
+
const requested = assertAbsoluteLocalPath(directoryPath, label);
|
|
136
|
+
const stat = lstatSync(requested);
|
|
137
|
+
if (stat.isSymbolicLink() || !stat.isDirectory()) {
|
|
138
|
+
throw new Error(`${label} must be a real directory.`);
|
|
139
|
+
}
|
|
140
|
+
return realpathSync(requested);
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
function constrainedEnvironment() {
|
|
144
|
+
return Object.fromEntries(
|
|
145
|
+
SAFE_ENV_KEYS
|
|
146
|
+
.filter((key) => typeof process.env[key] === "string")
|
|
147
|
+
.map((key) => [key, process.env[key]]),
|
|
148
|
+
);
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
function failure(failureCode, evidence = failureCode) {
|
|
152
|
+
return {
|
|
153
|
+
status: "failed",
|
|
154
|
+
failureCode,
|
|
155
|
+
evidenceSha256: sha256(
|
|
156
|
+
typeof evidence === "string" ? evidence : canonical(evidence),
|
|
157
|
+
),
|
|
158
|
+
};
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
function indeterminate(failureCode, evidence = failureCode) {
|
|
162
|
+
return {
|
|
163
|
+
...failure(failureCode, evidence),
|
|
164
|
+
status: "indeterminate",
|
|
165
|
+
};
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
function validateCredential(credential) {
|
|
169
|
+
assertExactKeys(
|
|
170
|
+
credential,
|
|
171
|
+
["ref", "mode", "identityFile"],
|
|
172
|
+
"SSH credential binding",
|
|
173
|
+
);
|
|
174
|
+
if (
|
|
175
|
+
typeof credential.ref !== "string"
|
|
176
|
+
|| !/^(?:agent|keychain|vault):[A-Za-z0-9][A-Za-z0-9._/-]*$/u.test(
|
|
177
|
+
credential.ref,
|
|
178
|
+
)
|
|
179
|
+
) {
|
|
180
|
+
throw new Error("SSH credential ref must be an opaque credential reference.");
|
|
181
|
+
}
|
|
182
|
+
if (credential.mode === "agent") {
|
|
183
|
+
if (credential.identityFile !== undefined) {
|
|
184
|
+
throw new Error("Agent SSH credential cannot include an identity file.");
|
|
185
|
+
}
|
|
186
|
+
return {
|
|
187
|
+
ref: credential.ref,
|
|
188
|
+
mode: "agent",
|
|
189
|
+
identityFile: null,
|
|
190
|
+
};
|
|
191
|
+
}
|
|
192
|
+
if (credential.mode === "identity_file") {
|
|
193
|
+
const identityBinding = isRecord(credential.identityFile)
|
|
194
|
+
? credential.identityFile
|
|
195
|
+
: {
|
|
196
|
+
path: credential.identityFile,
|
|
197
|
+
sha256: null,
|
|
198
|
+
};
|
|
199
|
+
assertExactKeys(
|
|
200
|
+
identityBinding,
|
|
201
|
+
["path", "sha256"],
|
|
202
|
+
"SSH identity file binding",
|
|
203
|
+
);
|
|
204
|
+
const identityFile = regularFile(
|
|
205
|
+
identityBinding.path,
|
|
206
|
+
"SSH identity file",
|
|
207
|
+
);
|
|
208
|
+
const identityFileSha256 = sha256(readFileSync(identityFile));
|
|
209
|
+
if (
|
|
210
|
+
identityBinding.sha256 !== null
|
|
211
|
+
&& (
|
|
212
|
+
!SHA256.test(identityBinding.sha256)
|
|
213
|
+
|| identityBinding.sha256 !== identityFileSha256
|
|
214
|
+
)
|
|
215
|
+
) {
|
|
216
|
+
throw new Error("SSH identity file hash mismatch.");
|
|
217
|
+
}
|
|
218
|
+
return {
|
|
219
|
+
ref: credential.ref,
|
|
220
|
+
mode: "identity_file",
|
|
221
|
+
identityFile: {
|
|
222
|
+
path: identityFile,
|
|
223
|
+
sha256: identityFileSha256,
|
|
224
|
+
},
|
|
225
|
+
};
|
|
226
|
+
}
|
|
227
|
+
throw new Error("SSH credential mode must be agent or identity_file.");
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
function validateInstallContract(contract) {
|
|
231
|
+
assertExactKeys(
|
|
232
|
+
contract,
|
|
233
|
+
["archiveFormat", "releaseRoot", "currentSymlink"],
|
|
234
|
+
"Install contract",
|
|
235
|
+
);
|
|
236
|
+
if (contract.archiveFormat !== "tar_gzip") {
|
|
237
|
+
throw new Error("Install contract archiveFormat is unsupported.");
|
|
238
|
+
}
|
|
239
|
+
return {
|
|
240
|
+
archiveFormat: contract.archiveFormat,
|
|
241
|
+
releaseRoot: assertRemotePath(contract.releaseRoot, "Release root"),
|
|
242
|
+
currentSymlink: assertRemotePath(
|
|
243
|
+
contract.currentSymlink,
|
|
244
|
+
"Current release symlink",
|
|
245
|
+
),
|
|
246
|
+
};
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
function validateManagedFile(value, label) {
|
|
250
|
+
assertExactKeys(
|
|
251
|
+
value,
|
|
252
|
+
["sourcePath", "destinationPath", "sha256"],
|
|
253
|
+
label,
|
|
254
|
+
);
|
|
255
|
+
return {
|
|
256
|
+
sourcePath: assertRelativePath(value.sourcePath, `${label} sourcePath`),
|
|
257
|
+
destinationPath: assertRemotePath(
|
|
258
|
+
value.destinationPath,
|
|
259
|
+
`${label} destinationPath`,
|
|
260
|
+
),
|
|
261
|
+
sha256: assertHash(value.sha256, `${label} SHA-256`),
|
|
262
|
+
};
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
function validateSystemdContract(contract) {
|
|
266
|
+
assertExactKeys(
|
|
267
|
+
contract,
|
|
268
|
+
[
|
|
269
|
+
"unitName",
|
|
270
|
+
"unitFile",
|
|
271
|
+
"daemonReload",
|
|
272
|
+
"enable",
|
|
273
|
+
"restart",
|
|
274
|
+
],
|
|
275
|
+
"Systemd contract",
|
|
276
|
+
);
|
|
277
|
+
if (
|
|
278
|
+
typeof contract.unitName !== "string"
|
|
279
|
+
|| !SERVICE_NAME.test(contract.unitName)
|
|
280
|
+
) {
|
|
281
|
+
throw new Error("Systemd unitName is invalid.");
|
|
282
|
+
}
|
|
283
|
+
for (const key of ["daemonReload", "enable", "restart"]) {
|
|
284
|
+
if (typeof contract[key] !== "boolean") {
|
|
285
|
+
throw new Error(`Systemd ${key} must be boolean.`);
|
|
286
|
+
}
|
|
287
|
+
}
|
|
288
|
+
return {
|
|
289
|
+
unitName: contract.unitName,
|
|
290
|
+
unitFile: validateManagedFile(contract.unitFile, "Systemd unit file"),
|
|
291
|
+
daemonReload: contract.daemonReload,
|
|
292
|
+
enable: contract.enable,
|
|
293
|
+
restart: contract.restart,
|
|
294
|
+
};
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
function validateNginxContract(contract) {
|
|
298
|
+
assertExactKeys(
|
|
299
|
+
contract,
|
|
300
|
+
[
|
|
301
|
+
"siteName",
|
|
302
|
+
"configFile",
|
|
303
|
+
"enabledLinkPath",
|
|
304
|
+
"configTest",
|
|
305
|
+
"reload",
|
|
306
|
+
],
|
|
307
|
+
"Nginx contract",
|
|
308
|
+
);
|
|
309
|
+
assertIdentifier(contract.siteName, "Nginx siteName");
|
|
310
|
+
for (const key of ["configTest", "reload"]) {
|
|
311
|
+
if (typeof contract[key] !== "boolean") {
|
|
312
|
+
throw new Error(`Nginx ${key} must be boolean.`);
|
|
313
|
+
}
|
|
314
|
+
}
|
|
315
|
+
return {
|
|
316
|
+
siteName: contract.siteName,
|
|
317
|
+
configFile: validateManagedFile(contract.configFile, "Nginx config file"),
|
|
318
|
+
enabledLinkPath: assertRemotePath(
|
|
319
|
+
contract.enabledLinkPath,
|
|
320
|
+
"Nginx enabled link path",
|
|
321
|
+
),
|
|
322
|
+
configTest: contract.configTest,
|
|
323
|
+
reload: contract.reload,
|
|
324
|
+
};
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
function validateSmokeCheck(check) {
|
|
328
|
+
if (check?.kind === "systemd_active") {
|
|
329
|
+
assertExactKeys(
|
|
330
|
+
check,
|
|
331
|
+
["checkId", "kind", "unitName"],
|
|
332
|
+
"Systemd smoke check",
|
|
333
|
+
);
|
|
334
|
+
assertIdentifier(check.checkId, "Smoke checkId");
|
|
335
|
+
if (
|
|
336
|
+
typeof check.unitName !== "string"
|
|
337
|
+
|| !SERVICE_NAME.test(check.unitName)
|
|
338
|
+
) {
|
|
339
|
+
throw new Error("Systemd smoke unitName is invalid.");
|
|
340
|
+
}
|
|
341
|
+
return structuredClone(check);
|
|
342
|
+
}
|
|
343
|
+
if (check?.kind === "http") {
|
|
344
|
+
assertExactKeys(
|
|
345
|
+
check,
|
|
346
|
+
["checkId", "kind", "url", "expectedStatus"],
|
|
347
|
+
"HTTP smoke check",
|
|
348
|
+
);
|
|
349
|
+
assertIdentifier(check.checkId, "Smoke checkId");
|
|
350
|
+
let parsed;
|
|
351
|
+
try {
|
|
352
|
+
parsed = new URL(check.url);
|
|
353
|
+
} catch {
|
|
354
|
+
throw new Error("HTTP smoke URL is invalid.");
|
|
355
|
+
}
|
|
356
|
+
if (
|
|
357
|
+
parsed.protocol !== "http:"
|
|
358
|
+
|| !new Set(["127.0.0.1", "[::1]", "localhost"]).has(parsed.hostname)
|
|
359
|
+
|| parsed.username !== ""
|
|
360
|
+
|| parsed.password !== ""
|
|
361
|
+
|| parsed.search !== ""
|
|
362
|
+
|| parsed.hash !== ""
|
|
363
|
+
|| !/^\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]*$/u.test(parsed.pathname)
|
|
364
|
+
|| !Number.isInteger(check.expectedStatus)
|
|
365
|
+
|| check.expectedStatus < 100
|
|
366
|
+
|| check.expectedStatus > 599
|
|
367
|
+
) {
|
|
368
|
+
throw new Error("HTTP smoke check must use a safe loopback URL and status.");
|
|
369
|
+
}
|
|
370
|
+
return structuredClone(check);
|
|
371
|
+
}
|
|
372
|
+
throw new Error("Smoke checks must use a supported structured kind.");
|
|
373
|
+
}
|
|
374
|
+
|
|
375
|
+
function validateSmokeContract(contract) {
|
|
376
|
+
assertExactKeys(contract, ["checks"], "Smoke contract");
|
|
377
|
+
if (!Array.isArray(contract.checks) || contract.checks.length === 0) {
|
|
378
|
+
throw new Error("Smoke contract requires structured checks.");
|
|
379
|
+
}
|
|
380
|
+
const checks = contract.checks.map(validateSmokeCheck);
|
|
381
|
+
if (new Set(checks.map((check) => check.checkId)).size !== checks.length) {
|
|
382
|
+
throw new Error("Smoke checkId values must be unique.");
|
|
383
|
+
}
|
|
384
|
+
return { checks };
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
function validateStageContracts(contracts) {
|
|
388
|
+
assertExactKeys(
|
|
389
|
+
contracts,
|
|
390
|
+
["install", "systemd", "nginx", "smoke"],
|
|
391
|
+
"SSH stage contracts",
|
|
392
|
+
);
|
|
393
|
+
return {
|
|
394
|
+
install: validateInstallContract(contracts.install),
|
|
395
|
+
systemd: validateSystemdContract(contracts.systemd),
|
|
396
|
+
nginx: validateNginxContract(contracts.nginx),
|
|
397
|
+
smoke: validateSmokeContract(contracts.smoke),
|
|
398
|
+
};
|
|
399
|
+
}
|
|
400
|
+
|
|
401
|
+
function validateRemoteFiles(entries, label, hashKey) {
|
|
402
|
+
if (!Array.isArray(entries)) throw new Error(`${label} must be an array.`);
|
|
403
|
+
const seen = new Set();
|
|
404
|
+
return entries.map((entry) => {
|
|
405
|
+
const allowed = hashKey === "sha256"
|
|
406
|
+
? ["path", "sha256"]
|
|
407
|
+
: ["path", "priorSha256"];
|
|
408
|
+
assertExactKeys(entry, allowed, `${label} entry`);
|
|
409
|
+
const remotePath = assertRemotePath(entry.path, `${label} path`);
|
|
410
|
+
if (seen.has(remotePath)) throw new Error(`${label} paths must be unique.`);
|
|
411
|
+
seen.add(remotePath);
|
|
412
|
+
return {
|
|
413
|
+
path: remotePath,
|
|
414
|
+
[hashKey]: assertHash(entry[hashKey], `${label} hash`),
|
|
415
|
+
};
|
|
416
|
+
});
|
|
417
|
+
}
|
|
418
|
+
|
|
419
|
+
function validateStageInput(input, boundTarget, credentialRef) {
|
|
420
|
+
if (!isRecord(input) || !REMOTE_DEPLOYMENT_STAGES.includes(input.stage)) {
|
|
421
|
+
throw new Error("SSH adapter stage input is invalid.");
|
|
422
|
+
}
|
|
423
|
+
const normalizedTarget = validateRemoteTarget(input.target);
|
|
424
|
+
if (!sameValue(normalizedTarget, boundTarget)) {
|
|
425
|
+
throw new Error("SSH adapter target drift is forbidden.");
|
|
426
|
+
}
|
|
427
|
+
if (input.credentialRef !== credentialRef) {
|
|
428
|
+
throw new Error("SSH adapter credential binding drift is forbidden.");
|
|
429
|
+
}
|
|
430
|
+
assertIdentifier(input.deploymentId, "DeploymentId");
|
|
431
|
+
assertHash(input.deploymentLineageSha256, "Deployment lineage");
|
|
432
|
+
if (!new Set(["first", "update"]).has(input.mode)) {
|
|
433
|
+
throw new Error("SSH deployment mode is invalid.");
|
|
434
|
+
}
|
|
435
|
+
assertExactKeys(
|
|
436
|
+
input.artifact,
|
|
437
|
+
["path", "sha256", "size", "mediaType"],
|
|
438
|
+
"SSH artifact",
|
|
439
|
+
);
|
|
440
|
+
const artifact = {
|
|
441
|
+
path: assertRelativePath(input.artifact.path, "SSH artifact path"),
|
|
442
|
+
sha256: assertHash(input.artifact.sha256, "SSH artifact"),
|
|
443
|
+
size: input.artifact.size,
|
|
444
|
+
mediaType: input.artifact.mediaType,
|
|
445
|
+
};
|
|
446
|
+
if (!Number.isSafeInteger(artifact.size) || artifact.size < 0) {
|
|
447
|
+
throw new Error("SSH artifact size is invalid.");
|
|
448
|
+
}
|
|
449
|
+
if (
|
|
450
|
+
typeof artifact.mediaType !== "string"
|
|
451
|
+
|| !/^[A-Za-z0-9.+-]+\/[A-Za-z0-9.+-]+$/u.test(artifact.mediaType)
|
|
452
|
+
) {
|
|
453
|
+
throw new Error("SSH artifact media type is invalid.");
|
|
454
|
+
}
|
|
455
|
+
assertExactKeys(input.upload, ["remotePath", "createOnly"], "SSH upload");
|
|
456
|
+
const upload = {
|
|
457
|
+
remotePath: assertRemotePath(input.upload.remotePath, "SSH upload path"),
|
|
458
|
+
createOnly: input.upload.createOnly,
|
|
459
|
+
};
|
|
460
|
+
if (upload.createOnly !== true) {
|
|
461
|
+
throw new Error("SSH upload must be create-only.");
|
|
462
|
+
}
|
|
463
|
+
const expectedRemoteFiles = validateRemoteFiles(
|
|
464
|
+
input.expectedRemoteFiles,
|
|
465
|
+
"Expected remote files",
|
|
466
|
+
"sha256",
|
|
467
|
+
);
|
|
468
|
+
const deletionAllowlist = validateRemoteFiles(
|
|
469
|
+
input.deletionAllowlist,
|
|
470
|
+
"Deletion allowlist",
|
|
471
|
+
"priorSha256",
|
|
472
|
+
);
|
|
473
|
+
const expectedByPath = new Map(
|
|
474
|
+
expectedRemoteFiles.map((entry) => [entry.path, entry.sha256]),
|
|
475
|
+
);
|
|
476
|
+
for (const deletion of deletionAllowlist) {
|
|
477
|
+
if (expectedByPath.get(deletion.path) !== deletion.priorSha256) {
|
|
478
|
+
throw new Error("Deletion allowlist must match an exact expected prior hash.");
|
|
479
|
+
}
|
|
480
|
+
}
|
|
481
|
+
assertExactKeys(
|
|
482
|
+
input.permissions,
|
|
483
|
+
["deploy", "destructive"],
|
|
484
|
+
"SSH deployment permissions",
|
|
485
|
+
);
|
|
486
|
+
if (
|
|
487
|
+
input.permissions.deploy !== true
|
|
488
|
+
|| typeof input.permissions.destructive !== "boolean"
|
|
489
|
+
|| (
|
|
490
|
+
deletionAllowlist.length > 0
|
|
491
|
+
&& input.permissions.destructive !== true
|
|
492
|
+
)
|
|
493
|
+
) {
|
|
494
|
+
throw new Error("SSH deployment permissions do not authorize the stage input.");
|
|
495
|
+
}
|
|
496
|
+
let priorDeployment = null;
|
|
497
|
+
if (input.mode === "first") {
|
|
498
|
+
if (
|
|
499
|
+
input.priorDeployment !== null
|
|
500
|
+
|| expectedRemoteFiles.length > 0
|
|
501
|
+
|| deletionAllowlist.length > 0
|
|
502
|
+
) {
|
|
503
|
+
throw new Error("First SSH deployment cannot use prior state or deletions.");
|
|
504
|
+
}
|
|
505
|
+
} else {
|
|
506
|
+
assertExactKeys(
|
|
507
|
+
input.priorDeployment,
|
|
508
|
+
["receiptSha256", "artifactSha256"],
|
|
509
|
+
"Prior SSH deployment",
|
|
510
|
+
);
|
|
511
|
+
priorDeployment = {
|
|
512
|
+
receiptSha256: assertHash(
|
|
513
|
+
input.priorDeployment.receiptSha256,
|
|
514
|
+
"Prior deployment receipt",
|
|
515
|
+
),
|
|
516
|
+
artifactSha256: assertHash(
|
|
517
|
+
input.priorDeployment.artifactSha256,
|
|
518
|
+
"Prior deployment artifact",
|
|
519
|
+
),
|
|
520
|
+
};
|
|
521
|
+
if (expectedRemoteFiles.length === 0) {
|
|
522
|
+
throw new Error("Update SSH deployment requires expected prior files.");
|
|
523
|
+
}
|
|
524
|
+
}
|
|
525
|
+
return {
|
|
526
|
+
stage: input.stage,
|
|
527
|
+
deploymentId: input.deploymentId,
|
|
528
|
+
deploymentLineageSha256: input.deploymentLineageSha256,
|
|
529
|
+
mode: input.mode,
|
|
530
|
+
target: normalizedTarget,
|
|
531
|
+
artifact,
|
|
532
|
+
upload,
|
|
533
|
+
priorDeployment,
|
|
534
|
+
expectedRemoteFiles,
|
|
535
|
+
deletionAllowlist,
|
|
536
|
+
permissions: structuredClone(input.permissions),
|
|
537
|
+
};
|
|
538
|
+
}
|
|
539
|
+
|
|
540
|
+
function verifyKnownHosts(knownHostsPath, target) {
|
|
541
|
+
const bindingFailure = verifyBoundLocalFile({
|
|
542
|
+
filePath: knownHostsPath,
|
|
543
|
+
resolvedPath: knownHostsPath,
|
|
544
|
+
expectedSha256: target.hostKeySha256,
|
|
545
|
+
failurePrefix: "known_hosts",
|
|
546
|
+
});
|
|
547
|
+
if (bindingFailure) return bindingFailure;
|
|
548
|
+
const bytes = readFileSync(knownHostsPath);
|
|
549
|
+
const expectedHost = target.port === 22
|
|
550
|
+
? new Set([target.host, `[${target.host}]:22`])
|
|
551
|
+
: new Set([`[${target.host}]:${target.port}`]);
|
|
552
|
+
const containsTarget = bytes
|
|
553
|
+
.toString("utf8")
|
|
554
|
+
.split(/\r?\n/u)
|
|
555
|
+
.filter((line) => line !== "" && !line.startsWith("#"))
|
|
556
|
+
.some((line) => expectedHost.has(line.split(/\s+/u, 1)[0]));
|
|
557
|
+
if (!containsTarget) return failure("known_hosts_target_missing");
|
|
558
|
+
return null;
|
|
559
|
+
}
|
|
560
|
+
|
|
561
|
+
function verifyBoundLocalFile({
|
|
562
|
+
filePath,
|
|
563
|
+
resolvedPath,
|
|
564
|
+
expectedSha256,
|
|
565
|
+
failurePrefix,
|
|
566
|
+
}) {
|
|
567
|
+
let currentResolved;
|
|
568
|
+
let bytes;
|
|
569
|
+
try {
|
|
570
|
+
const requestedStat = lstatSync(filePath);
|
|
571
|
+
if (requestedStat.isSymbolicLink() || !requestedStat.isFile()) {
|
|
572
|
+
return failure(`${failurePrefix}_invalid`);
|
|
573
|
+
}
|
|
574
|
+
currentResolved = realpathSync(filePath);
|
|
575
|
+
const resolvedStat = lstatSync(currentResolved);
|
|
576
|
+
if (resolvedStat.isSymbolicLink() || !resolvedStat.isFile()) {
|
|
577
|
+
return failure(`${failurePrefix}_invalid`);
|
|
578
|
+
}
|
|
579
|
+
bytes = readFileSync(currentResolved);
|
|
580
|
+
} catch {
|
|
581
|
+
return failure(`${failurePrefix}_invalid`);
|
|
582
|
+
}
|
|
583
|
+
if (currentResolved !== resolvedPath) {
|
|
584
|
+
return failure(`${failurePrefix}_realpath_drift`);
|
|
585
|
+
}
|
|
586
|
+
if (sha256(bytes) !== expectedSha256) {
|
|
587
|
+
return failure(`${failurePrefix}_hash_mismatch`);
|
|
588
|
+
}
|
|
589
|
+
return null;
|
|
590
|
+
}
|
|
591
|
+
|
|
592
|
+
function resolveLocalArtifact(workspaceRoot, artifact) {
|
|
593
|
+
const requested = path.resolve(workspaceRoot, artifact.path);
|
|
594
|
+
const relative = path.relative(workspaceRoot, requested);
|
|
595
|
+
if (relative.startsWith("..") || path.isAbsolute(relative)) {
|
|
596
|
+
return { failed: failure("local_artifact_outside_workspace") };
|
|
597
|
+
}
|
|
598
|
+
let resolved;
|
|
599
|
+
try {
|
|
600
|
+
resolved = regularFile(requested, "Local deployment artifact");
|
|
601
|
+
} catch {
|
|
602
|
+
return { failed: failure("local_artifact_invalid") };
|
|
603
|
+
}
|
|
604
|
+
const resolvedRelative = path.relative(workspaceRoot, resolved);
|
|
605
|
+
if (resolvedRelative.startsWith("..") || path.isAbsolute(resolvedRelative)) {
|
|
606
|
+
return { failed: failure("local_artifact_outside_workspace") };
|
|
607
|
+
}
|
|
608
|
+
const bytes = readFileSync(resolved);
|
|
609
|
+
if (bytes.length !== artifact.size || sha256(bytes) !== artifact.sha256) {
|
|
610
|
+
return { failed: failure("local_artifact_hash_mismatch") };
|
|
611
|
+
}
|
|
612
|
+
return { bytes };
|
|
613
|
+
}
|
|
614
|
+
|
|
615
|
+
function exactArray(value, expected) {
|
|
616
|
+
return Array.isArray(value)
|
|
617
|
+
&& value.length === expected.length
|
|
618
|
+
&& value.every((entry, index) => sameValue(entry, expected[index]));
|
|
619
|
+
}
|
|
620
|
+
|
|
621
|
+
function normalizeRemoteFailure(output) {
|
|
622
|
+
try {
|
|
623
|
+
assertExactKeys(
|
|
624
|
+
output,
|
|
625
|
+
["status", "failureCode", "evidenceSha256"],
|
|
626
|
+
"Remote helper failure",
|
|
627
|
+
);
|
|
628
|
+
if (output.status !== "failed") throw new Error("not failed");
|
|
629
|
+
assertIdentifier(output.failureCode, "Remote helper failureCode");
|
|
630
|
+
assertHash(output.evidenceSha256, "Remote helper failure evidence");
|
|
631
|
+
return {
|
|
632
|
+
status: "failed",
|
|
633
|
+
failureCode: output.failureCode,
|
|
634
|
+
evidenceSha256: output.evidenceSha256,
|
|
635
|
+
};
|
|
636
|
+
} catch {
|
|
637
|
+
return failure("ssh_output_invalid");
|
|
638
|
+
}
|
|
639
|
+
}
|
|
640
|
+
|
|
641
|
+
function normalizeRemoteOutput(
|
|
642
|
+
stage,
|
|
643
|
+
output,
|
|
644
|
+
context,
|
|
645
|
+
hostKeySha256,
|
|
646
|
+
remoteHelper,
|
|
647
|
+
) {
|
|
648
|
+
if (!isRecord(output)) return failure("ssh_output_invalid");
|
|
649
|
+
if (output.status === "failed") return normalizeRemoteFailure(output);
|
|
650
|
+
try {
|
|
651
|
+
if (stage === "identity_preflight") {
|
|
652
|
+
assertExactKeys(
|
|
653
|
+
output,
|
|
654
|
+
["status", "machineIdentitySha256", "remoteHelper"],
|
|
655
|
+
"Remote identity output",
|
|
656
|
+
);
|
|
657
|
+
if (
|
|
658
|
+
output.status !== "passed"
|
|
659
|
+
|| output.machineIdentitySha256
|
|
660
|
+
!== context.target.machineIdentitySha256
|
|
661
|
+
) {
|
|
662
|
+
return failure("remote_machine_identity_mismatch");
|
|
663
|
+
}
|
|
664
|
+
if (!sameValue(output.remoteHelper, remoteHelper)) {
|
|
665
|
+
return failure("remote_helper_capability_mismatch");
|
|
666
|
+
}
|
|
667
|
+
return {
|
|
668
|
+
status: "passed",
|
|
669
|
+
hostKeySha256,
|
|
670
|
+
machineIdentitySha256: output.machineIdentitySha256,
|
|
671
|
+
remoteHelper: structuredClone(remoteHelper),
|
|
672
|
+
};
|
|
673
|
+
}
|
|
674
|
+
if (stage === "upload") {
|
|
675
|
+
assertExactKeys(
|
|
676
|
+
output,
|
|
677
|
+
["status", "remotePath", "sha256", "size"],
|
|
678
|
+
"Remote upload output",
|
|
679
|
+
);
|
|
680
|
+
if (
|
|
681
|
+
!new Set(["created", "already_present"]).has(output.status)
|
|
682
|
+
|| output.remotePath !== context.upload.remotePath
|
|
683
|
+
|| output.sha256 !== context.artifact.sha256
|
|
684
|
+
|| output.size !== context.artifact.size
|
|
685
|
+
) {
|
|
686
|
+
return failure("create_only_upload_conflict");
|
|
687
|
+
}
|
|
688
|
+
return structuredClone(output);
|
|
689
|
+
}
|
|
690
|
+
if (stage === "verify_remote_hashes") {
|
|
691
|
+
assertExactKeys(
|
|
692
|
+
output,
|
|
693
|
+
[
|
|
694
|
+
"status",
|
|
695
|
+
"remotePath",
|
|
696
|
+
"sha256",
|
|
697
|
+
"size",
|
|
698
|
+
"verifiedPriorFiles",
|
|
699
|
+
],
|
|
700
|
+
"Remote hash output",
|
|
701
|
+
);
|
|
702
|
+
if (
|
|
703
|
+
output.status !== "passed"
|
|
704
|
+
|| output.remotePath !== context.upload.remotePath
|
|
705
|
+
|| output.sha256 !== context.artifact.sha256
|
|
706
|
+
|| output.size !== context.artifact.size
|
|
707
|
+
|| !exactArray(
|
|
708
|
+
output.verifiedPriorFiles,
|
|
709
|
+
context.expectedRemoteFiles,
|
|
710
|
+
)
|
|
711
|
+
) {
|
|
712
|
+
return failure("remote_artifact_or_prior_hash_mismatch");
|
|
713
|
+
}
|
|
714
|
+
return {
|
|
715
|
+
status: "passed",
|
|
716
|
+
remotePath: output.remotePath,
|
|
717
|
+
sha256: output.sha256,
|
|
718
|
+
size: output.size,
|
|
719
|
+
};
|
|
720
|
+
}
|
|
721
|
+
if (stage === "install") {
|
|
722
|
+
assertExactKeys(
|
|
723
|
+
output,
|
|
724
|
+
[
|
|
725
|
+
"status",
|
|
726
|
+
"mode",
|
|
727
|
+
"installedArtifactSha256",
|
|
728
|
+
"deletedFiles",
|
|
729
|
+
"evidenceSha256",
|
|
730
|
+
],
|
|
731
|
+
"Remote install output",
|
|
732
|
+
);
|
|
733
|
+
if (!exactArray(output.deletedFiles, context.deletionAllowlist)) {
|
|
734
|
+
return failure("remote_deletion_set_mismatch");
|
|
735
|
+
}
|
|
736
|
+
if (
|
|
737
|
+
output.status !== "passed"
|
|
738
|
+
|| output.mode !== context.mode
|
|
739
|
+
|| output.installedArtifactSha256 !== context.artifact.sha256
|
|
740
|
+
) {
|
|
741
|
+
return failure("remote_install_mismatch");
|
|
742
|
+
}
|
|
743
|
+
return {
|
|
744
|
+
status: "passed",
|
|
745
|
+
evidenceSha256: assertHash(
|
|
746
|
+
output.evidenceSha256,
|
|
747
|
+
"Remote install evidence",
|
|
748
|
+
),
|
|
749
|
+
};
|
|
750
|
+
}
|
|
751
|
+
if (stage === "service") {
|
|
752
|
+
assertExactKeys(
|
|
753
|
+
output,
|
|
754
|
+
[
|
|
755
|
+
"status",
|
|
756
|
+
"unitName",
|
|
757
|
+
"unitFileSha256",
|
|
758
|
+
"evidenceSha256",
|
|
759
|
+
],
|
|
760
|
+
"Remote systemd output",
|
|
761
|
+
);
|
|
762
|
+
if (
|
|
763
|
+
output.status !== "passed"
|
|
764
|
+
|| output.unitName !== context.contract.unitName
|
|
765
|
+
|| output.unitFileSha256 !== context.contract.unitFile.sha256
|
|
766
|
+
) {
|
|
767
|
+
return failure("remote_systemd_contract_mismatch");
|
|
768
|
+
}
|
|
769
|
+
return {
|
|
770
|
+
status: "passed",
|
|
771
|
+
evidenceSha256: assertHash(
|
|
772
|
+
output.evidenceSha256,
|
|
773
|
+
"Remote systemd evidence",
|
|
774
|
+
),
|
|
775
|
+
};
|
|
776
|
+
}
|
|
777
|
+
if (stage === "proxy") {
|
|
778
|
+
assertExactKeys(
|
|
779
|
+
output,
|
|
780
|
+
[
|
|
781
|
+
"status",
|
|
782
|
+
"siteName",
|
|
783
|
+
"configFileSha256",
|
|
784
|
+
"evidenceSha256",
|
|
785
|
+
],
|
|
786
|
+
"Remote Nginx output",
|
|
787
|
+
);
|
|
788
|
+
if (
|
|
789
|
+
output.status !== "passed"
|
|
790
|
+
|| output.siteName !== context.contract.siteName
|
|
791
|
+
|| output.configFileSha256 !== context.contract.configFile.sha256
|
|
792
|
+
) {
|
|
793
|
+
return failure("remote_nginx_contract_mismatch");
|
|
794
|
+
}
|
|
795
|
+
return {
|
|
796
|
+
status: "passed",
|
|
797
|
+
evidenceSha256: assertHash(
|
|
798
|
+
output.evidenceSha256,
|
|
799
|
+
"Remote Nginx evidence",
|
|
800
|
+
),
|
|
801
|
+
};
|
|
802
|
+
}
|
|
803
|
+
assertExactKeys(
|
|
804
|
+
output,
|
|
805
|
+
["status", "checks", "evidenceSha256"],
|
|
806
|
+
"Remote smoke output",
|
|
807
|
+
);
|
|
808
|
+
const expectedIds = context.contract.checks.map((check) => check.checkId);
|
|
809
|
+
if (
|
|
810
|
+
output.status !== "passed"
|
|
811
|
+
|| !Array.isArray(output.checks)
|
|
812
|
+
|| output.checks.length !== expectedIds.length
|
|
813
|
+
|| output.checks.some((check, index) => {
|
|
814
|
+
try {
|
|
815
|
+
assertExactKeys(
|
|
816
|
+
check,
|
|
817
|
+
["checkId", "status", "evidenceSha256"],
|
|
818
|
+
"Remote smoke check output",
|
|
819
|
+
);
|
|
820
|
+
assertHash(check.evidenceSha256, "Remote smoke check evidence");
|
|
821
|
+
return check.checkId !== expectedIds[index]
|
|
822
|
+
|| check.status !== "passed";
|
|
823
|
+
} catch {
|
|
824
|
+
return true;
|
|
825
|
+
}
|
|
826
|
+
})
|
|
827
|
+
) {
|
|
828
|
+
return failure("remote_smoke_contract_mismatch");
|
|
829
|
+
}
|
|
830
|
+
return {
|
|
831
|
+
status: "passed",
|
|
832
|
+
evidenceSha256: assertHash(
|
|
833
|
+
output.evidenceSha256,
|
|
834
|
+
"Remote smoke evidence",
|
|
835
|
+
),
|
|
836
|
+
};
|
|
837
|
+
} catch {
|
|
838
|
+
return failure("ssh_output_invalid");
|
|
839
|
+
}
|
|
840
|
+
}
|
|
841
|
+
|
|
842
|
+
function buildPayload(
|
|
843
|
+
stage,
|
|
844
|
+
context,
|
|
845
|
+
contracts,
|
|
846
|
+
artifactBytes,
|
|
847
|
+
remoteHelper,
|
|
848
|
+
) {
|
|
849
|
+
const common = {
|
|
850
|
+
protocol: SSH_REMOTE_HELPER_PROTOCOL_V1,
|
|
851
|
+
expectedRemoteHelper: structuredClone(remoteHelper),
|
|
852
|
+
stage,
|
|
853
|
+
deploymentId: context.deploymentId,
|
|
854
|
+
deploymentLineageSha256: context.deploymentLineageSha256,
|
|
855
|
+
mode: context.mode,
|
|
856
|
+
target: {
|
|
857
|
+
targetId: context.target.targetId,
|
|
858
|
+
environment: context.target.environment,
|
|
859
|
+
},
|
|
860
|
+
};
|
|
861
|
+
if (stage === "identity_preflight") {
|
|
862
|
+
return {
|
|
863
|
+
...common,
|
|
864
|
+
expectedMachineIdentitySha256:
|
|
865
|
+
context.target.machineIdentitySha256,
|
|
866
|
+
};
|
|
867
|
+
}
|
|
868
|
+
if (stage === "upload") {
|
|
869
|
+
return {
|
|
870
|
+
...common,
|
|
871
|
+
remotePath: context.upload.remotePath,
|
|
872
|
+
createOnly: true,
|
|
873
|
+
artifact: context.artifact,
|
|
874
|
+
contentBase64: artifactBytes.toString("base64"),
|
|
875
|
+
};
|
|
876
|
+
}
|
|
877
|
+
if (stage === "verify_remote_hashes") {
|
|
878
|
+
return {
|
|
879
|
+
...common,
|
|
880
|
+
remotePath: context.upload.remotePath,
|
|
881
|
+
artifact: context.artifact,
|
|
882
|
+
expectedRemoteFiles: context.expectedRemoteFiles,
|
|
883
|
+
};
|
|
884
|
+
}
|
|
885
|
+
if (stage === "install") {
|
|
886
|
+
return {
|
|
887
|
+
...common,
|
|
888
|
+
remoteArtifactPath: context.upload.remotePath,
|
|
889
|
+
artifact: context.artifact,
|
|
890
|
+
priorDeployment: context.priorDeployment,
|
|
891
|
+
expectedRemoteFiles: context.expectedRemoteFiles,
|
|
892
|
+
deletionAllowlist: context.deletionAllowlist,
|
|
893
|
+
destructive: context.permissions.destructive,
|
|
894
|
+
contract: {
|
|
895
|
+
...contracts.install,
|
|
896
|
+
releasePath: `${contracts.install.releaseRoot}/${context.deploymentId}`,
|
|
897
|
+
},
|
|
898
|
+
};
|
|
899
|
+
}
|
|
900
|
+
if (stage === "service") {
|
|
901
|
+
return { ...common, contract: contracts.systemd };
|
|
902
|
+
}
|
|
903
|
+
if (stage === "proxy") {
|
|
904
|
+
return { ...common, contract: contracts.nginx };
|
|
905
|
+
}
|
|
906
|
+
return { ...common, contract: contracts.smoke };
|
|
907
|
+
}
|
|
908
|
+
|
|
909
|
+
function buildReconciliationPayload(
|
|
910
|
+
stage,
|
|
911
|
+
context,
|
|
912
|
+
contracts,
|
|
913
|
+
remoteHelper,
|
|
914
|
+
) {
|
|
915
|
+
const payload = buildPayload(
|
|
916
|
+
stage,
|
|
917
|
+
context,
|
|
918
|
+
contracts,
|
|
919
|
+
stage === "upload" ? Buffer.alloc(0) : null,
|
|
920
|
+
remoteHelper,
|
|
921
|
+
);
|
|
922
|
+
if (stage === "upload") delete payload.contentBase64;
|
|
923
|
+
return {
|
|
924
|
+
...payload,
|
|
925
|
+
operation: "reconcile",
|
|
926
|
+
};
|
|
927
|
+
}
|
|
928
|
+
|
|
929
|
+
function defaultExecFile(file, args, options) {
|
|
930
|
+
const stdout = execFileSync(file, args, options);
|
|
931
|
+
return {
|
|
932
|
+
status: 0,
|
|
933
|
+
stdout: typeof stdout === "string" ? stdout : stdout.toString("utf8"),
|
|
934
|
+
stderr: "",
|
|
935
|
+
};
|
|
936
|
+
}
|
|
937
|
+
|
|
938
|
+
function builtInIdentity() {
|
|
939
|
+
return {
|
|
940
|
+
adapterId: "builtin-ssh-v1",
|
|
941
|
+
version: "1.0.0",
|
|
942
|
+
executable: MODULE_PATH,
|
|
943
|
+
sha256: sha256(readFileSync(MODULE_PATH)),
|
|
944
|
+
};
|
|
945
|
+
}
|
|
946
|
+
|
|
947
|
+
export function builtInSshRemoteAdapterIdentityV1() {
|
|
948
|
+
return builtInIdentity();
|
|
949
|
+
}
|
|
950
|
+
|
|
951
|
+
export function createSshRemoteAdapterV1({
|
|
952
|
+
target,
|
|
953
|
+
credential,
|
|
954
|
+
knownHostsPath,
|
|
955
|
+
workspaceRoot,
|
|
956
|
+
remoteHelper,
|
|
957
|
+
stageContracts,
|
|
958
|
+
sshExecutable = "/usr/bin/ssh",
|
|
959
|
+
sshExecutableSha256 = null,
|
|
960
|
+
timeoutMs = 600_000,
|
|
961
|
+
maxOutputBytes = 1_048_576,
|
|
962
|
+
execFile = defaultExecFile,
|
|
963
|
+
} = {}) {
|
|
964
|
+
const normalizedTarget = validateRemoteTarget(target);
|
|
965
|
+
const normalizedCredential = validateCredential(credential);
|
|
966
|
+
const normalizedKnownHostsPath = regularFile(
|
|
967
|
+
knownHostsPath,
|
|
968
|
+
"SSH known_hosts file",
|
|
969
|
+
);
|
|
970
|
+
const normalizedWorkspaceRoot = realDirectory(
|
|
971
|
+
workspaceRoot,
|
|
972
|
+
"SSH adapter workspaceRoot",
|
|
973
|
+
);
|
|
974
|
+
const normalizedRemoteHelper = validateSshRemoteHelperBindingV1(
|
|
975
|
+
remoteHelper,
|
|
976
|
+
);
|
|
977
|
+
const normalizedSshExecutable = regularFile(
|
|
978
|
+
sshExecutable,
|
|
979
|
+
"SSH executable",
|
|
980
|
+
);
|
|
981
|
+
if (path.basename(normalizedSshExecutable) !== "ssh") {
|
|
982
|
+
throw new Error("SSH executable must resolve to the ssh binary.");
|
|
983
|
+
}
|
|
984
|
+
const boundSshExecutableSha256 = sha256(
|
|
985
|
+
readFileSync(normalizedSshExecutable),
|
|
986
|
+
);
|
|
987
|
+
if (
|
|
988
|
+
sshExecutableSha256 !== null
|
|
989
|
+
&& (
|
|
990
|
+
!SHA256.test(sshExecutableSha256)
|
|
991
|
+
|| sshExecutableSha256 !== boundSshExecutableSha256
|
|
992
|
+
)
|
|
993
|
+
) {
|
|
994
|
+
throw new Error("SSH executable hash mismatch.");
|
|
995
|
+
}
|
|
996
|
+
const normalizedContracts = validateStageContracts(stageContracts);
|
|
997
|
+
if (
|
|
998
|
+
!Number.isSafeInteger(timeoutMs)
|
|
999
|
+
|| timeoutMs < 1
|
|
1000
|
+
|| timeoutMs > 3_600_000
|
|
1001
|
+
) {
|
|
1002
|
+
throw new Error("SSH adapter timeoutMs is invalid.");
|
|
1003
|
+
}
|
|
1004
|
+
if (
|
|
1005
|
+
!Number.isSafeInteger(maxOutputBytes)
|
|
1006
|
+
|| maxOutputBytes < 1_024
|
|
1007
|
+
|| maxOutputBytes > 16_777_216
|
|
1008
|
+
) {
|
|
1009
|
+
throw new Error("SSH adapter maxOutputBytes is invalid.");
|
|
1010
|
+
}
|
|
1011
|
+
if (typeof execFile !== "function") {
|
|
1012
|
+
throw new Error("SSH adapter execFile runner is required.");
|
|
1013
|
+
}
|
|
1014
|
+
const identity = builtInIdentity();
|
|
1015
|
+
const connectionArgs = [
|
|
1016
|
+
"-F",
|
|
1017
|
+
"none",
|
|
1018
|
+
"-o",
|
|
1019
|
+
"BatchMode=yes",
|
|
1020
|
+
"-o",
|
|
1021
|
+
"IdentitiesOnly=yes",
|
|
1022
|
+
"-o",
|
|
1023
|
+
"PasswordAuthentication=no",
|
|
1024
|
+
"-o",
|
|
1025
|
+
"StrictHostKeyChecking=yes",
|
|
1026
|
+
"-o",
|
|
1027
|
+
`UserKnownHostsFile=${normalizedKnownHostsPath}`,
|
|
1028
|
+
...(normalizedCredential.mode === "identity_file"
|
|
1029
|
+
? ["-i", normalizedCredential.identityFile.path]
|
|
1030
|
+
: []),
|
|
1031
|
+
"-p",
|
|
1032
|
+
String(normalizedTarget.port),
|
|
1033
|
+
`${normalizedTarget.user}@${normalizedTarget.host}`,
|
|
1034
|
+
];
|
|
1035
|
+
async function invokeStage(input, operation) {
|
|
1036
|
+
let context;
|
|
1037
|
+
try {
|
|
1038
|
+
context = validateStageInput(
|
|
1039
|
+
input,
|
|
1040
|
+
normalizedTarget,
|
|
1041
|
+
normalizedCredential.ref,
|
|
1042
|
+
);
|
|
1043
|
+
} catch {
|
|
1044
|
+
return failure("ssh_stage_input_invalid");
|
|
1045
|
+
}
|
|
1046
|
+
const knownHostsFailure = verifyKnownHosts(
|
|
1047
|
+
normalizedKnownHostsPath,
|
|
1048
|
+
normalizedTarget,
|
|
1049
|
+
);
|
|
1050
|
+
if (knownHostsFailure) return knownHostsFailure;
|
|
1051
|
+
const sshExecutableFailure = verifyBoundLocalFile({
|
|
1052
|
+
filePath: normalizedSshExecutable,
|
|
1053
|
+
resolvedPath: normalizedSshExecutable,
|
|
1054
|
+
expectedSha256: boundSshExecutableSha256,
|
|
1055
|
+
failurePrefix: "ssh_executable",
|
|
1056
|
+
});
|
|
1057
|
+
if (sshExecutableFailure) return sshExecutableFailure;
|
|
1058
|
+
if (normalizedCredential.mode === "identity_file") {
|
|
1059
|
+
const identityFileFailure = verifyBoundLocalFile({
|
|
1060
|
+
filePath: normalizedCredential.identityFile.path,
|
|
1061
|
+
resolvedPath: normalizedCredential.identityFile.path,
|
|
1062
|
+
expectedSha256: normalizedCredential.identityFile.sha256,
|
|
1063
|
+
failurePrefix: "identity_file",
|
|
1064
|
+
});
|
|
1065
|
+
if (identityFileFailure) return identityFileFailure;
|
|
1066
|
+
}
|
|
1067
|
+
let artifactBytes = null;
|
|
1068
|
+
if (context.stage === "upload" && operation === "execute") {
|
|
1069
|
+
const artifact = resolveLocalArtifact(
|
|
1070
|
+
normalizedWorkspaceRoot,
|
|
1071
|
+
context.artifact,
|
|
1072
|
+
);
|
|
1073
|
+
if (artifact.failed) return artifact.failed;
|
|
1074
|
+
artifactBytes = artifact.bytes;
|
|
1075
|
+
}
|
|
1076
|
+
const payload = operation === "reconcile"
|
|
1077
|
+
? buildReconciliationPayload(
|
|
1078
|
+
context.stage,
|
|
1079
|
+
context,
|
|
1080
|
+
normalizedContracts,
|
|
1081
|
+
normalizedRemoteHelper,
|
|
1082
|
+
)
|
|
1083
|
+
: buildPayload(
|
|
1084
|
+
context.stage,
|
|
1085
|
+
context,
|
|
1086
|
+
normalizedContracts,
|
|
1087
|
+
artifactBytes,
|
|
1088
|
+
normalizedRemoteHelper,
|
|
1089
|
+
);
|
|
1090
|
+
let completed;
|
|
1091
|
+
try {
|
|
1092
|
+
completed = await execFile(
|
|
1093
|
+
normalizedSshExecutable,
|
|
1094
|
+
[
|
|
1095
|
+
...connectionArgs,
|
|
1096
|
+
normalizedRemoteHelper.path,
|
|
1097
|
+
"--protocol",
|
|
1098
|
+
SSH_REMOTE_HELPER_PROTOCOL_V1,
|
|
1099
|
+
"--stage",
|
|
1100
|
+
context.stage,
|
|
1101
|
+
...(operation === "reconcile"
|
|
1102
|
+
? ["--operation", "reconcile"]
|
|
1103
|
+
: []),
|
|
1104
|
+
],
|
|
1105
|
+
{
|
|
1106
|
+
encoding: "utf8",
|
|
1107
|
+
env: constrainedEnvironment(),
|
|
1108
|
+
input: `${JSON.stringify(payload)}\n`,
|
|
1109
|
+
maxBuffer: maxOutputBytes,
|
|
1110
|
+
shell: false,
|
|
1111
|
+
timeout: timeoutMs,
|
|
1112
|
+
windowsHide: true,
|
|
1113
|
+
},
|
|
1114
|
+
);
|
|
1115
|
+
} catch (error) {
|
|
1116
|
+
return indeterminate(
|
|
1117
|
+
error?.code === "ETIMEDOUT"
|
|
1118
|
+
? "ssh_process_timeout"
|
|
1119
|
+
: "ssh_process_failed",
|
|
1120
|
+
{
|
|
1121
|
+
code: typeof error?.code === "string" ? error.code : null,
|
|
1122
|
+
stdoutSha256: sha256(String(error?.stdout ?? "")),
|
|
1123
|
+
stderrSha256: sha256(String(error?.stderr ?? "")),
|
|
1124
|
+
},
|
|
1125
|
+
);
|
|
1126
|
+
}
|
|
1127
|
+
if (
|
|
1128
|
+
!isRecord(completed)
|
|
1129
|
+
|| (
|
|
1130
|
+
completed.status !== undefined
|
|
1131
|
+
&& completed.status !== 0
|
|
1132
|
+
)
|
|
1133
|
+
) {
|
|
1134
|
+
return indeterminate(
|
|
1135
|
+
Number.isInteger(completed?.status)
|
|
1136
|
+
? `ssh_process_exit_${completed.status}`
|
|
1137
|
+
: "ssh_process_failed",
|
|
1138
|
+
{
|
|
1139
|
+
status: completed?.status ?? null,
|
|
1140
|
+
stdoutSha256: sha256(String(completed?.stdout ?? "")),
|
|
1141
|
+
stderrSha256: sha256(String(completed?.stderr ?? "")),
|
|
1142
|
+
},
|
|
1143
|
+
);
|
|
1144
|
+
}
|
|
1145
|
+
const stdout = String(completed.stdout ?? "");
|
|
1146
|
+
if (Buffer.byteLength(stdout) > maxOutputBytes) {
|
|
1147
|
+
return indeterminate("ssh_output_too_large");
|
|
1148
|
+
}
|
|
1149
|
+
let output;
|
|
1150
|
+
try {
|
|
1151
|
+
output = JSON.parse(stdout);
|
|
1152
|
+
} catch {
|
|
1153
|
+
return indeterminate("ssh_output_invalid", {
|
|
1154
|
+
stdoutSha256: sha256(stdout),
|
|
1155
|
+
stderrSha256: sha256(String(completed.stderr ?? "")),
|
|
1156
|
+
});
|
|
1157
|
+
}
|
|
1158
|
+
return normalizeRemoteOutput(
|
|
1159
|
+
context.stage,
|
|
1160
|
+
output,
|
|
1161
|
+
{
|
|
1162
|
+
...context,
|
|
1163
|
+
contract: context.stage === "service"
|
|
1164
|
+
? normalizedContracts.systemd
|
|
1165
|
+
: context.stage === "proxy"
|
|
1166
|
+
? normalizedContracts.nginx
|
|
1167
|
+
: context.stage === "smoke"
|
|
1168
|
+
? normalizedContracts.smoke
|
|
1169
|
+
: null,
|
|
1170
|
+
},
|
|
1171
|
+
normalizedTarget.hostKeySha256,
|
|
1172
|
+
normalizedRemoteHelper,
|
|
1173
|
+
);
|
|
1174
|
+
}
|
|
1175
|
+
return {
|
|
1176
|
+
identity,
|
|
1177
|
+
async runStage(input) {
|
|
1178
|
+
return invokeStage(input, "execute");
|
|
1179
|
+
},
|
|
1180
|
+
async reconcileStage(input) {
|
|
1181
|
+
return invokeStage(input, "reconcile");
|
|
1182
|
+
},
|
|
1183
|
+
};
|
|
1184
|
+
}
|