@awebai/oats 0.69.24 → 0.70.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.
@@ -0,0 +1,329 @@
1
+ /** Sandbox allowances (docs/capabilities.md "Sandbox allowances"): what a session provider may
2
+ * widen its harness's sandbox by, for one launch. The kernel builds the list; the provider writes
3
+ * it and nothing else. Two kinds of entry, and where each may come from:
4
+ *
5
+ * - `domains`: exact hosts. Only the capability that fills the instance's messaging, knowledge or
6
+ * tasks slot may contribute one, only by a manifest line `sandboxDomains: [{ "setting": "<key>" }]`
7
+ * that names one of its own settings. The setting's value is a URL (the kernel takes its host),
8
+ * a bare host, or a map from team id to one of those, of which only the entries of the
9
+ * instance's own teams are taken. A line on any other capability refuses the launch, never
10
+ * drops the line. A line may instead be `{ "settingFile": "<key>", "urls": "<JSON pointer>" }`:
11
+ * the setting's value is the path of a JSON file of the deployment, and the hosts are those
12
+ * of every string at the pointer (readSettingFileHosts, with its bounds). Nothing at run time
13
+ * (hook output, an environment variable, a task, a launch argument) can add a host.
14
+ * - `write`: exact absolute paths, the kernel's own, never a capability's: the deployment's events
15
+ * directory (sandboxEventsDir), which the kernel creates before the launch
16
+ * (ensureSandboxWritePaths): an allowance on a path that does not exist does not let a
17
+ * sandboxed agent create it.
18
+ *
19
+ * The values are the DEPLOYMENT'S: a resolution's `slots` and `payloads` (what a spawn preview
20
+ * shows), never a file inside an instance home, which a sandboxed agent can write. For an existing
21
+ * home, which deployment and which soul are resolved is the home's PATH'S to say
22
+ * (lib/instance-resolution.mjs homeSandboxSource), never its instance.json's; the one thing read
23
+ * from the home is the list of its modules, which can only leave a host out (homeSandboxAllowances).
24
+ *
25
+ * A leaf: no import of the kernel's heavy modules. Every refusal is E_BACKEND_SANDBOX_HOST, with
26
+ * `details: { capability, setting?, host? }`. */
27
+ import { closeSync, constants as fsConstants, fstatSync, lstatSync, mkdirSync, openSync, readSync, realpathSync } from "node:fs";
28
+ import { dirname, isAbsolute, join, relative, resolve } from "node:path";
29
+ import { parseStrictJson } from "./canonical-json.mjs";
30
+ import { oatsError } from "./errors.mjs";
31
+
32
+ /** The slots whose provider may declare `sandboxDomains`. */
33
+ export const SANDBOX_SLOTS = ["messaging", "knowledge", "tasks"];
34
+ /** At most this many lines in one manifest. */
35
+ export const MAX_SANDBOX_LINES = 16;
36
+ const SETTING_KEY_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/;
37
+ /** A host as an allowlist takes it: DNS labels (letters, digits, hyphens; no wildcard, no
38
+ * underscore), at most 253 characters, or a dotted IPv4 address, which the same pattern covers. */
39
+ const LABEL = "[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?";
40
+ const HOST_RE = new RegExp(`^${LABEL}(?:\\.${LABEL})*$`);
41
+ /** `scheme://[userinfo@]host[:port][/path][?query][#fragment]`, the authority kept as written: WHATWG
42
+ * URL drops a port that is the scheme's default, and the entry carries a port only when the URL names one. */
43
+ const URL_RE = /^([a-z][a-z0-9+.-]*):\/\/([^/?#]*)(?:[/?#].*)?$/i;
44
+
45
+ /** A `settingFile` line's file: at most this many bytes, and this many hosts. */
46
+ export const SETTING_FILE_MAX_BYTES = 64 * 1024, SETTING_FILE_MAX_HOSTS = 16;
47
+ /** A JSON pointer (RFC 6901) of at most 16 segments, of which at most one is `*`: every key of the
48
+ * object, or every element of the array, at that place. */
49
+ const pointerSegments = (pointer) => {
50
+ if (typeof pointer !== "string" || !pointer.startsWith("/") || pointer.length > 400) return null;
51
+ const segments = pointer.slice(1).split("/");
52
+ if (segments.length > 16 || segments.some((s) => s === "" || /~(?![01])/.test(s)) || segments.filter((s) => s === "*").length > 1) return null;
53
+ return segments.map((s) => (s === "*" ? { any: true } : { key: s.replace(/~1/g, "/").replace(/~0/g, "~") }));
54
+ };
55
+ /** A git remote in scp form, `user@host:path` or `host.name:path`: its host. Only a `settingFile`'s
56
+ * strings are read so. `host:<port number>` is a bare host with its port, never this; and without
57
+ * a user the host must have a dot, so that `C:/dir` or `name:path` is no remote. */
58
+ const SCP_REMOTE_RE = /^(?:[A-Za-z0-9._-]+@([A-Za-z0-9.-]+)|([A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+)):(?!\/\/)(?![0-9]{1,5}$)[^\s]+$/;
59
+
60
+ const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
61
+ const refuse = (message, details) => Object.assign(oatsError("E_BACKEND_SANDBOX_HOST", message), { details });
62
+
63
+ /** `manifest.sandboxDomains` as the kernel reads it → `{ lines: [{ setting, optional }], problems:
64
+ * [string] }`. A line is `{ "setting": "<key>" }`, with `"optional": true` when the session works
65
+ * without that host (its absence is then no reason for a provider to refuse a launch).
66
+ * Total: it never throws. A manifest without the key has no lines and no problems. A problem is a
67
+ * refusal wherever the lines are used (sandboxAllowances): a line is never dropped. */
68
+ export function sandboxDomainsOf(manifest) {
69
+ const declared = manifest?.sandboxDomains;
70
+ if (declared === undefined) return { lines: [], problems: [] };
71
+ if (!Array.isArray(declared) || declared.length < 1 || declared.length > MAX_SANDBOX_LINES) return { lines: [], problems: [`sandboxDomains must list 1 to ${MAX_SANDBOX_LINES} entries`] };
72
+ const lines = [], problems = [];
73
+ declared.forEach((line, i) => {
74
+ const keys = isObject(line) ? Object.keys(line) : [];
75
+ if (isObject(line) && Object.hasOwn(line, "settingFile")) {
76
+ if (typeof line.settingFile !== "string" || !SETTING_KEY_RE.test(line.settingFile) || keys.some((k) => k !== "settingFile" && k !== "urls") || !pointerSegments(line.urls)) problems.push(`sandboxDomains[${i}] must be { "settingFile": "<one of the capability's setting keys>", "urls": "<a JSON pointer, at most one * segment>" }`);
77
+ else if (lines.some((l) => (l.settingFile ?? l.setting) === line.settingFile)) problems.push(`sandboxDomains[${i}] names the setting ${line.settingFile} a second time`);
78
+ else lines.push({ settingFile: line.settingFile, urls: line.urls });
79
+ return;
80
+ }
81
+ if (!isObject(line) || typeof line.setting !== "string" || !SETTING_KEY_RE.test(line.setting) || keys.some((k) => k !== "setting" && k !== "optional") || (line.optional !== undefined && typeof line.optional !== "boolean")) problems.push(`sandboxDomains[${i}] must be { "setting": "<one of the capability's setting keys>", "optional"?: true }`);
82
+ else if (lines.some((l) => (l.settingFile ?? l.setting) === line.setting)) problems.push(`sandboxDomains[${i}] names the setting ${line.setting} a second time`);
83
+ else lines.push({ setting: line.setting, optional: line.optional === true });
84
+ });
85
+ if (!SANDBOX_SLOTS.includes(manifest?.layer)) problems.push(`sandboxDomains is for a capability whose layer is ${SANDBOX_SLOTS.join(", ")}: this one declares ${manifest?.layer === undefined ? "none" : JSON.stringify(manifest.layer)}`);
86
+ return { lines, problems };
87
+ }
88
+
89
+ /** The host of a setting's value, as an allowlist entry → `{ host }`, or `{ problem }` saying why
90
+ * the value gives none. The value is a URL (anything with `://`: its host is taken) or a bare host
91
+ * (`host` or `host:port`). The entry is a bare host: lower case, no wildcard, scheme or path; its
92
+ * port only when the value names one. A value that carries credentials is refused whole: nothing
93
+ * of it is quoted. */
94
+ export function sandboxHostOf(value, { userName = false } = {}) {
95
+ if (typeof value !== "string" || !value.trim()) return { problem: "is not a URL or a host" };
96
+ const text = value.trim();
97
+ const m = URL_RE.exec(text);
98
+ if (!m && /[/?#\s]/.test(text)) return { problem: "is neither a URL with a scheme and a host nor a bare host" };
99
+ const authority = m ? m[2] : text;
100
+ // A user name alone is no credential (a git remote carries one), where the caller reads such values.
101
+ const user = authority.includes("@") ? authority.slice(0, authority.lastIndexOf("@")) : null;
102
+ if (user !== null && !(userName && m && /^[A-Za-z0-9._-]+$/.test(user))) return { problem: "is a URL that carries credentials" };
103
+ const hostPort = user === null ? authority : authority.slice(user.length + 1);
104
+ const at = hostPort.lastIndexOf(":");
105
+ const [name, port] = at >= 0 && !hostPort.endsWith("]") ? [hostPort.slice(0, at), hostPort.slice(at + 1)] : [hostPort, null];
106
+ const host = name.toLowerCase();
107
+ if (!host) return { problem: "is a URL without a host" };
108
+ if (host.includes("*")) return { problem: `names a wildcard host (${host}): an allowance is one exact host` };
109
+ if (host.length > 253 || !HOST_RE.test(host)) return { problem: "names a host that is no plain DNS name or IPv4 address" };
110
+ if (port !== null && (!/^[0-9]{1,5}$/.test(port) || Number(port) < 1 || Number(port) > 65535)) return { problem: "names a port that is no port number" };
111
+ return { host: port === null ? host : `${host}:${Number(port)}` };
112
+ }
113
+
114
+ /** The hosts a `settingFile` line gives → `{ hosts: [host] }`, `{ unread: "<why>" }` when the file
115
+ * gives none this kernel will use (missing, not a regular file, too large, no strict JSON, more
116
+ * than SETTING_FILE_MAX_HOSTS hosts: the launch goes on without them, and readiness names it), or
117
+ * `{ refused: "<why>" }` when the path itself is one no allowance may be read from.
118
+ *
119
+ * `path`: the setting's value. `within`: the deployment's directory. `outside`: directories inside
120
+ * it that are never a source (its instance homes, the paths the allowances make writable). The
121
+ * path must be inside `within` and outside each of those, as its REAL path, with no symbolic link
122
+ * anywhere along it below the deployment: a link planted in a parent directory cannot move the
123
+ * read to a file a sandboxed agent can write. The file is opened without following a link, as a
124
+ * regular file, and read once, at most SETTING_FILE_MAX_BYTES.
125
+ *
126
+ * A string at the pointer gives a host when it is a URL with a plain host (a user name is allowed,
127
+ * as git remotes carry one; a password is not) or a git remote in scp form (`git@host:path`);
128
+ * another string is skipped and counted in `skippedValues`. */
129
+ export function readSettingFileHosts({ path, pointer, within, outside = [] }) {
130
+ if (typeof path !== "string" || !path.trim()) return { unread: "the setting names no file" };
131
+ let root;
132
+ try { root = realpathSync(within); } catch (e) { return { refused: `the deployment's directory cannot be resolved (${e.code ?? e.message})` }; }
133
+ // The path as written, under the deployment's real directory. An absolute path may spell the
134
+ // deployment through a link; it is re-rooted at the FIRST place it enters the deployment, the
135
+ // outermost of its ancestors whose real path is the deployment's, and from there down no link
136
+ // is allowed. Outermost, never nearest: a link below the deployment that leads back to it (one
137
+ // an agent makes in its home) is then part of what must be link-free, not a new root. And the
138
+ // same whichever spelling the caller knows the deployment by (a spawn's `--dir`, a start's real
139
+ // path): both read the same file, or both refuse.
140
+ const written = resolve(isAbsolute(path) ? path : resolve(within, path));
141
+ let entered = null;
142
+ for (let dir = dirname(written); ; dir = dirname(dir)) {
143
+ try { if (realpathSync(dir) === root) entered = dir; } catch { /* not there: the file is not either, said below */ }
144
+ if (dirname(dir) === dir) break;
145
+ }
146
+ const rel = entered === null ? null : relative(entered, written);
147
+ const below = rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel : null;
148
+ if (!below) return { refused: `${path} is not inside the deployment (${root}): a host is read only from the deployment's own files` };
149
+ const target = resolve(root, below);
150
+ const inside = (dir) => { const rel = relative(dir, target); return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel)); };
151
+ const forbidden = outside.map((dir) => { try { return realpathSync(dir); } catch { return resolve(dir); } }).find(inside);
152
+ if (forbidden) return { refused: `${path} is inside ${forbidden}, which a session's agent can write: a host is never read from there` };
153
+ let real;
154
+ try { real = realpathSync(target); } catch (e) { return e.code === "ENOENT" || e.code === "ENOTDIR" ? { unread: `${target} does not exist` } : { unread: `${target} cannot be read (${e.code ?? e.message})` }; }
155
+ if (real !== target) return { refused: `${path} reaches its file through a symbolic link (${target} is ${real}): a host is read only from a path with no link along it` };
156
+ let fd;
157
+ try { fd = openSync(target, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0)); } catch (e) { return { unread: `${target} cannot be opened (${e.code ?? e.message})` }; }
158
+ let doc;
159
+ try {
160
+ const st = fstatSync(fd);
161
+ if (!st.isFile()) return { unread: `${target} is not a regular file` };
162
+ // Another name of the same file could be in a place a session's agent can write. (What this
163
+ // sees is a second name that exists NOW: one made, written through and removed before this
164
+ // read is not seen. The file's own mode and place are what keep it from that.)
165
+ if (st.nlink > 1) return { unread: `${target} has more than one hard link` };
166
+ if (st.size > SETTING_FILE_MAX_BYTES) return { unread: `${target} is larger than ${SETTING_FILE_MAX_BYTES / 1024} KiB` };
167
+ const buffer = Buffer.alloc(SETTING_FILE_MAX_BYTES + 1);
168
+ let length = 0;
169
+ for (let n; length < buffer.length && (n = readSync(fd, buffer, length, buffer.length - length, null)) > 0;) length += n;
170
+ if (length > SETTING_FILE_MAX_BYTES) return { unread: `${target} is larger than ${SETTING_FILE_MAX_BYTES / 1024} KiB` };
171
+ try { doc = parseStrictJson(buffer.subarray(0, length), { maxBytes: SETTING_FILE_MAX_BYTES }); } catch { return { unread: `${target} is not strict JSON` }; }
172
+ } catch (e) { return { unread: `${target} cannot be read (${e.code ?? e.message})` }; }
173
+ finally { closeSync(fd); }
174
+ // Every value at the pointer.
175
+ let values = [doc];
176
+ for (const segment of pointerSegments(pointer) ?? []) {
177
+ values = values.flatMap((v) => {
178
+ if (segment.any) return Array.isArray(v) ? v : v !== null && typeof v === "object" ? Object.values(v) : [];
179
+ if (Array.isArray(v)) return /^(0|[1-9][0-9]*)$/.test(segment.key) && Number(segment.key) < v.length ? [v[Number(segment.key)]] : [];
180
+ return v !== null && typeof v === "object" && Object.hasOwn(v, segment.key) ? [v[segment.key]] : [];
181
+ });
182
+ }
183
+ const hosts = [];
184
+ let skippedValues = 0;
185
+ for (const value of values) {
186
+ const scp = typeof value === "string" ? SCP_REMOTE_RE.exec(value.trim()) : null;
187
+ const { host } = scp ? sandboxHostOf(scp[1] ?? scp[2]) : sandboxHostOf(value, { userName: true });
188
+ if (!host) skippedValues += 1;
189
+ else if (!hosts.includes(host)) hosts.push(host);
190
+ }
191
+ if (hosts.length > SETTING_FILE_MAX_HOSTS) return { unread: `${target} names ${hosts.length} hosts, more than the ${SETTING_FILE_MAX_HOSTS} one file may give` };
192
+ return { hosts, skippedValues };
193
+ }
194
+
195
+ /** The path the kernel itself allows a sandboxed session to write: the deployment's events
196
+ * directory (`<deployment>/.agents/events`, where lib/instance-events.mjs appends a home's events
197
+ * and `oats instance attention` its claim), under the deployment's REAL path. `deployment` is the
198
+ * caller's, established outside any instance home. */
199
+ export function sandboxEventsDir(deployment) {
200
+ let real;
201
+ try { real = realpathSync(deployment); } catch { real = resolve(deployment); }
202
+ return join(real, ".agents", "events");
203
+ }
204
+ /** What ensureSandboxWritePaths would refuse of `write`, without creating anything (a readiness
205
+ * read): a path that exists and is not a real directory at exactly that path, or whose nearest
206
+ * existing ancestor is reached through a link → the refusal, or null. */
207
+ export function sandboxWritePathsRefusal(write) {
208
+ for (const { path } of write ?? []) {
209
+ // The nearest ancestor that is THERE, a link that leads nowhere included (lstat, which does
210
+ // not follow one): a launch would refuse that link, so a read does.
211
+ const there = (at) => { try { lstatSync(at); return true; } catch { return false; } };
212
+ let ancestor = path;
213
+ while (!there(ancestor) && dirname(ancestor) !== ancestor) ancestor = dirname(ancestor);
214
+ let sound;
215
+ try { sound = realpathSync(ancestor) === ancestor && (ancestor !== path || lstatSync(path).isDirectory()); } catch { sound = false; }
216
+ if (!sound) return refuse(`the session's sandbox may not be allowed to write ${path}: it is reached through a symbolic link, or is no directory; nothing was created or launched`, { capability: null, setting: null, host: null, path });
217
+ }
218
+ return null;
219
+ }
220
+ /** Make the `write` paths of an allowance exist, right before the launch that is handed them, and
221
+ * hold each to what it must be: a real directory at exactly that path, reached through no symbolic
222
+ * link. A path that is anything else is refused (E_BACKEND_SANDBOX_HOST): an allowance on it would
223
+ * let the session write wherever the link leads. */
224
+ export function ensureSandboxWritePaths(write) {
225
+ for (const { path } of write ?? []) {
226
+ // Nothing is created through a link: what a read would refuse is refused before anything is made.
227
+ const refused = sandboxWritePathsRefusal([{ path }]);
228
+ if (refused) throw refused;
229
+ try {
230
+ mkdirSync(path, { recursive: true });
231
+ if (realpathSync(path) !== path || !lstatSync(path).isDirectory()) throw Object.assign(new Error("it is reached through a symbolic link, or is no directory"), { code: "ELOOP" });
232
+ } catch (e) {
233
+ throw refuse(`the session's sandbox may not be allowed to write ${path}: ${e.code === "ELOOP" ? e.message : `it cannot be made (${e.code ?? e.message})`}; nothing was created or launched`, { capability: null, setting: null, host: null, path });
234
+ }
235
+ }
236
+ }
237
+ /** The allowances of a launch of an EXISTING home (a start, a restart; readiness): the deployment's
238
+ * resolution for the home's soul (`source`: lib/instance-resolution.mjs homeSandboxSource, which
239
+ * takes the deployment and the soul from where the home is, never from what is in it), with hosts
240
+ * only for the capabilities that are also the home's modules (`moduleNames`, the home's own
241
+ * record: it can only leave a host of that resolution out, never add one). `home`: its real path. */
242
+ export function homeSandboxAllowances({ source, home, moduleNames }) {
243
+ const eventsDir = sandboxEventsDir(source.deployment);
244
+ return sandboxAllowances({ modules: source.modules, slots: source.slots, payloads: source.payloads, teams: source.teams, defaultTeam: source.defaultTeam ?? null, eventsDir, only: moduleNames, deployment: source.deployment, outside: [dirname(dirname(dirname(home))), eventsDir] });
245
+ }
246
+
247
+ /** What a provider's launch is handed of the allowances: the three lists, each host with the
248
+ * capability and the setting that asked for it, never the kernel's own notes (a host's `team`,
249
+ * `skipped`, `unread`), which are for the answer and for readiness. */
250
+ export const sandboxLaunchInput = ({ domains, write, missing }) => ({ domains: domains.map(({ host, capability, setting }) => ({ host, capability, setting })), write, missing });
251
+
252
+ /** The allowances of one launch → `{ domains: [{ host, capability, setting, team? }], write: [{ path, reason }],
253
+ * missing: [{ capability, setting, team, defaultTeam, optional? }] }` (`sandboxLaunchInput` is what a
254
+ * provider is handed of it). `missing`: what a line names and the deployment's configuration does
255
+ * not hold: a team of the instance with no entry in a map (`team`: its id), or a setting with no
256
+ * value at all (`team: null`). `defaultTeam` is true on the row of the soul's default team and on
257
+ * a row with `team: null`, false on another team's; `optional: true` on a row of a line declared
258
+ * so. The kernel adds no host for those and refuses nothing: a provider that would sandbox the
259
+ * session refuses on a row that is not optional and whose `defaultTeam` is true (without its
260
+ * default team's service the agent has no messaging at all), since only it knows its mode; the
261
+ * other rows are for readiness.
262
+ *
263
+ * `modules`: the instance's capabilities, `[{ name, manifest }]`. `slots`: `{ messaging, knowledge,
264
+ * tasks }`, each the name of the capability that fills it, or null. `payloads`: `{ <capability>:
265
+ * { <setting>: value } }`, the deployment's effective settings, and `origins` (`{ <capability>: {
266
+ * <JSON pointer>: { kind } } }`, a resolution's `payloadOrigins`) where each came from. `teams`: the instance's team ids
267
+ * (the `team` of each row of the resolution's `teams`) and `defaultTeam`, the id of the soul's
268
+ * default team there, or null. `eventsDir`: the deployment's events
269
+ * directory, absolute. `deployment` and `outside`: where a `settingFile` line's file may be (inside
270
+ * the first, outside each of the second: readSettingFileHosts); `unread: [{ capability, setting,
271
+ * reason }]`, in the answer only when there is one, names each such file that gave no host, or
272
+ * values in it that were skipped. `only`, when given (a start of an existing home): the names of the home's
273
+ * own modules; a slot's provider of the deployment that is not one of them contributes no host
274
+ * and is named in `skipped: [{ capability, reason }]`, which is in the answer only then.
275
+ *
276
+ * Refused (E_BACKEND_SANDBOX_HOST), naming the capability and what it asked for: a malformed
277
+ * declaration; a capability that declares the line and fills none of the three slots; a setting
278
+ * a line names whose value was given to this spawn alone (origin `spawn`); a setting whose value
279
+ * is set and gives no plain host. A setting with no value contributes no host and is
280
+ * listed in `missing`. Of a map (team id → URL or host) only the entries of the instance's teams
281
+ * are read: another team's entry is neither taken nor judged, and a team without an entry
282
+ * contributes no host and is listed in `missing`.
283
+ * Hosts are deduplicated: the first capability, in `modules` order, to ask for one is named. */
284
+ export function sandboxAllowances({ modules = [], slots = {}, payloads = {}, origins = {}, teams = [], defaultTeam = null, eventsDir, only, deployment, outside = [] }) {
285
+ const domains = [], skipped = [], missing = [], unread = [];
286
+ for (const { name, manifest } of modules) {
287
+ if (manifest?.sandboxDomains === undefined) continue;
288
+ const { lines, problems } = sandboxDomainsOf(manifest);
289
+ const slot = SANDBOX_SLOTS.find((s) => slots?.[s] === name);
290
+ // One entry per value a line names: the setting's own, or each of the instance's teams' in a map.
291
+ const asked = lines.filter((l) => l.setting !== undefined).flatMap(({ setting, optional }) => {
292
+ const value = isObject(payloads?.[name]) && Object.hasOwn(payloads[name], setting) ? payloads[name][setting] : undefined;
293
+ if (!isObject(value)) return [{ setting, optional, team: null, value }];
294
+ return teams.filter((team, i) => typeof team === "string" && teams.indexOf(team) === i).map((team) => ({ setting, optional, team, value: Object.hasOwn(value, team) ? value[team] : undefined }));
295
+ });
296
+ if (!slot) {
297
+ // Named with the host it asked for, where its setting gives one.
298
+ const first = asked.map((l) => ({ setting: l.setting, host: sandboxHostOf(l.value).host ?? null })).find((l) => l.host) ?? { setting: asked[0]?.setting ?? null, host: null };
299
+ throw refuse(`capability ${name} declares sandboxDomains${first.host ? ` (the host ${first.host}, from its setting ${first.setting})` : ""}, and it is not this instance's ${SANDBOX_SLOTS.join(", ")} provider: only the capability that fills one of those slots may add a host to a session's sandbox; nothing was launched`, { capability: name, setting: first.setting, host: first.host });
300
+ }
301
+ if (only && !only.includes(name)) { skipped.push({ capability: name, reason: `the deployment's ${slot} provider is ${name}, which is not one of this home's modules: its hosts are not allowed here (respawn the instance to take the deployment's composition)` }); continue; }
302
+ // A value given to one spawn (`--provider <capability> <setting>=…`) is a launch's own
303
+ // argument, never the deployment's configuration: no host comes from it, and it is not passed
304
+ // over in silence either (the next start would resolve another host without a word).
305
+ const pointer = (setting) => `/${String(setting).replace(/~/g, "~0").replace(/\//g, "~1")}`;
306
+ const perSpawn = lines.map((l) => l.setting ?? l.settingFile).find((setting) => Object.entries(isObject(origins?.[name]) ? origins[name] : {}).some(([at, origin]) => (at === pointer(setting) || at.startsWith(`${pointer(setting)}/`)) && origin?.kind === "spawn"));
307
+ if (perSpawn !== undefined) throw refuse(`capability ${name} asks to allow the host of its setting ${perSpawn}, and this spawn was given that setting itself (--provider ${name} ${perSpawn}=…): a host comes from the deployment's configuration (the soul, the workspace, oats-local.yaml), never from a launch's own arguments; set it there, or leave it out of this spawn; nothing was launched`, { capability: name, setting: perSpawn, host: null });
308
+ if (problems.length) throw refuse(`capability ${name} declares a sandboxDomains this kernel cannot use: ${problems.join("; ")}; nothing was launched`, { capability: name, setting: null, host: null });
309
+ for (const { setting, optional, team, value } of asked) {
310
+ if (value === undefined || value === null || value === "") { missing.push({ capability: name, setting, team, defaultTeam: team === null || team === defaultTeam, ...(optional ? { optional: true } : {}) }); continue; }
311
+ const { host, problem } = sandboxHostOf(value);
312
+ if (!host) throw refuse(`capability ${name} asks to allow the host of its setting ${setting}${team === null ? "" : ` for team ${team}`}, whose value ${problem}; nothing was launched`, { capability: name, setting, host: null, ...(team === null ? {} : { team }) });
313
+ // A host from a map says whose it is: the team's id. The team is one the instance MAY join
314
+ // (a row of the resolution's `teams`), which is not to say it has.
315
+ if (!domains.some((d) => d.host === host)) domains.push({ host, capability: name, setting, ...(team === null ? {} : { team }) });
316
+ }
317
+ // A `settingFile` line: the hosts of a file of the deployment. A path that may not be read
318
+ // from refuses; a file that gives nothing is named, and the launch goes on without its hosts.
319
+ for (const { settingFile: setting, urls } of lines.filter((l) => l.settingFile !== undefined)) {
320
+ const path = isObject(payloads?.[name]) ? payloads[name][setting] : undefined;
321
+ const read = readSettingFileHosts({ path, pointer: urls, within: deployment, outside });
322
+ if (read.refused) throw refuse(`capability ${name} asks to allow the hosts in the file its setting ${setting} names, and ${read.refused}; nothing was launched`, { capability: name, setting, host: null });
323
+ if (read.unread) { unread.push({ capability: name, setting, reason: read.unread }); continue; }
324
+ for (const host of read.hosts) if (!domains.some((d) => d.host === host)) domains.push({ host, capability: name, setting });
325
+ if (read.skippedValues) unread.push({ capability: name, setting, reason: `${read.skippedValues} ${read.skippedValues === 1 ? "value" : "values"} at ${urls} ${read.skippedValues === 1 ? "is" : "are"} no URL with a plain host, and ${read.skippedValues === 1 ? "was" : "were"} skipped` });
326
+ }
327
+ }
328
+ return { domains, write: [{ path: eventsDir, reason: "oats events" }], missing, ...(skipped.length ? { skipped } : {}), ...(unread.length ? { unread } : {}) };
329
+ }
package/lib/servers.mjs CHANGED
@@ -37,6 +37,7 @@ import { LOGIN_CAPTURE_MAX_BYTES, LOGIN_SHELLS, loginPathEmitter, quoteFor, read
37
37
  import { compareSemver } from "./semver.mjs";
38
38
  import { SESSION_PROVIDERS_FEATURE, SPAWN_TASK_STDIN_FEATURE } from "./kernel-features.mjs";
39
39
  import { relayedProviderRow, withoutRelayedEndpoint } from "./session-providers.mjs";
40
+ import { readModuleCopy } from "./home-integrity.mjs";
40
41
  import { sameRepo } from "./repo-moves.mjs";
41
42
  import { OATS_PACKAGE_NAME } from "./version.mjs";
42
43
  import { readRemoteBoard } from "./instance-board.mjs";
@@ -1149,6 +1150,14 @@ const rowBoard = (i) => (Object.hasOwn(i, "board") ? { board: readRemoteBoard(i.
1149
1150
  /** `retire` (feature status-retire-state) as `waitingOnYou` is, relayed ONLY when the host's row has the
1150
1151
  * key: a host whose kernel predates the feature omits it, and its rows say nothing. Absent is the
1151
1152
  * only reading of "no retire", so a value the kernel's own read refuses is dropped, never null. */
1153
+ /** `moduleCopy` (a provider home's: which copy of its modules its kernel runs, and whether the home's
1154
+ * record of them is the receipt's; lib/home-integrity.mjs) as `retire` is: relayed ONLY when the
1155
+ * host's row has the key and this kernel's own read takes its value. A tmux home's row, and a
1156
+ * host whose kernel predates it, say nothing. */
1157
+ const rowModuleCopy = (i) => {
1158
+ const moduleCopy = Object.hasOwn(i, "moduleCopy") ? readModuleCopy(i.moduleCopy) : undefined;
1159
+ return moduleCopy ? { moduleCopy } : {};
1160
+ };
1152
1161
  const rowRetire = (i) => {
1153
1162
  const retire = Object.hasOwn(i, "retire") ? readRetireState(i.retire) : undefined;
1154
1163
  return retire ? { retire } : {};
@@ -1271,7 +1280,7 @@ export async function rosterGroups({ server, workspaceKeys, io = {} } = {}) {
1271
1280
  harness: i.harness || i.runtime || null, backend: i.tmux ? "tmux" : null, ...(relayedProviderRow(i) ?? {}),
1272
1281
  ...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}), ...(i.tmux ? { tmux: i.tmux } : {}),
1273
1282
  running: typeof i.running === "boolean" ? i.running : null, ...(i.runtimeError ? { runtimeError: i.runtimeError } : {}),
1274
- ...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowBackground(i), ...rowPinned(i), ...rowBoard(i), ...rowRelatedWork(i, g.probe.features), ...rowSessionEnd(i),
1283
+ ...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowModuleCopy(i), ...rowBackground(i), ...rowPinned(i), ...rowBoard(i), ...rowRelatedWork(i, g.probe.features), ...rowSessionEnd(i),
1275
1284
  // Every row the host reports is addressed by its home, saved
1276
1285
  // route or not; savedRoute says only that it was spawned from here.
1277
1286
  retirePending: !!i.retirePending, rollbackIncomplete: !!i.rollbackIncomplete, savedRoute: !!snap, addressable: true, missingRemotely: false,
@@ -4,12 +4,13 @@
4
4
  * provider's own answer. A leaf (awebai/oats#1630): `oats session inspect` reads it without loading core.mjs, which
5
5
  * imports these helpers and re-exports what it exported. */
6
6
  import { realPathOrNearest, canonicalHomePath } from "./real-path.mjs";
7
- import { existsSync, readFileSync, lstatSync } from "node:fs";
8
- import { isAbsolute, join, resolve, dirname, basename } from "node:path";
9
- import { createHash } from "node:crypto";
7
+ import { existsSync, readFileSync } from "node:fs";
8
+ import { isAbsolute, join, resolve, basename } from "node:path";
9
+ import { RETIRE_BASELINE_VERSION, findRetirementBaseline, instancesRetirementRoot, isPlainObject, legacyRetirementBaselinePath, readJsonOrUndefined, receiptHomeIdentity, receiptRecordsHome, retirementBaselinePath } from "./session-receipt.mjs";
10
10
  import { inspectSessionTarget } from "./session-input.mjs";
11
11
  import { liveWaiting } from "./instance-events.mjs";
12
12
  import { oatsError, herdrInstanceRemoved } from "./errors.mjs";
13
+ import { receiptTrust, trustedRecord } from "./home-integrity.mjs";
13
14
  import { homeSessionProvider, isSessionProviderName, inspectProviderSession, launchSentOf, providerEndpointDifferences, providerRuntimeOf, unsettledLaunchSaid } from "./session-providers.mjs";
14
15
 
15
16
  /** A cleanup descriptor is usable only if it can DRIVE the retry, so it is checked
@@ -29,76 +30,6 @@ import { homeSessionProvider, isSessionProviderName, inspectProviderSession, lau
29
30
  *
30
31
  * Anything else reads as ABSENT — no more retryable than a missing marker — so the
31
32
  * home fails closed by default and `--force` can clear it. */
32
- function isPlainObject(v) { return !!v && typeof v === "object" && !Array.isArray(v); }
33
-
34
- // The stored digests are versioned apart (`digestVersion`, BASELINE_DIGEST_VERSION): this version
35
- // also gates runtime, directory-home and provider-exclusion authority, so a bump would refuse them all.
36
- const RETIRE_BASELINE_VERSION = 2;
37
-
38
- function retirementStateRoot(home) {
39
- // Independent of the bytes it authenticates, but colocated with the agent's
40
- // already instance-owned storage rather than the source repository or user
41
- // config home. Retiring <instances>/<name> never removes this sibling.
42
- return instancesRetirementRoot(dirname(home));
43
- }
44
- /** The retirement state of the homes in the instances directory `instances`. */
45
- function instancesRetirementRoot(instances) {
46
- return join(instances, ".oats-retirement");
47
- }
48
-
49
- /** A home's identity as a receipt records it: its on-disk spelling, own name included. A home that
50
- * is a symlink is not followed: its parent's on-disk spelling and its name as given (a home
51
- * exchanged for a symlink is not the home it points at). */
52
- function receiptHomeIdentity(home) {
53
- let st;
54
- try { st = lstatSync(home); } catch { /* not there: spelled as the nearest existing ancestor */ }
55
- return st && !st.isSymbolicLink() ? canonicalHomePath(home) : join(canonicalHomePath(dirname(home)), basename(home));
56
- }
57
-
58
- /** Whether a receipt's recorded home is this home, whatever spelling either was written in.
59
- * `current` is the home as the caller resolves it for the comparison. */
60
- function receiptRecordsHome(baseline, current) {
61
- return typeof baseline?.home === "string" && receiptHomeIdentity(baseline.home) === current;
62
- }
63
-
64
- function retirementBaselineFile(identity) {
65
- return join(retirementStateRoot(identity), "baselines", `${createHash("sha256").update(identity).digest("hex")}.json`);
66
- }
67
-
68
- /** Where a spawn writes a home's receipt: keyed by its canonical identity. */
69
- export function retirementBaselinePath(home) {
70
- return retirementBaselineFile(receiptHomeIdentity(home));
71
- }
72
-
73
- /** Where a kernel before 0.49.0 wrote it: keyed by the parent's realpath in the spawn's own
74
- * spelling, which on a case-insensitive filesystem need not be the on-disk one. */
75
- function legacyRetirementBaselinePath(home) {
76
- return retirementBaselineFile(join(realPathOrNearest(dirname(home)), basename(home)));
77
- }
78
-
79
- /** The receipt every reader uses: the canonical one if it exists, else one an earlier kernel left
80
- * under this caller's spelling, else the canonical path (absent). Read-only: a receipt found at the
81
- * legacy key is used where it is, never moved, copied or rewritten elsewhere.
82
- *
83
- * Limits. A legacy receipt written under spelling S is found only from S, or from the canonical
84
- * spelling when that is S: a third spelling of such a home misses it (address the home as
85
- * `oats status` prints it, the spawn's spelling). Receipts outlive retire, so a reused name can
86
- * leave an earlier incarnation's receipt behind; the canonical one wins, which is right for every
87
- * home spawned from 0.49.0 on. It is wrong in one case: two incarnations of the same name, both
88
- * spawned by a kernel before 0.49.0 under different spellings, the earlier one under the canonical
89
- * spelling. The later home then reads the earlier one's receipt. Its stale endpoint disagrees with
90
- * instance.json (E_RUNTIME_AUTHORITY_MISMATCH) unless the later incarnation sits at the same
91
- * endpoint, where session control already targets the right session. Retire finds the home
92
- * fingerprint changed and preserves the home, less the stale receipt's disposable roots; a
93
- * directory-work disagreement is E_WORK_INSPECTION_FAILED; and a start's record rewrites the stale
94
- * file, as a kernel before 0.49.0 already does when a caller's spelling matches an earlier
95
- * incarnation's. */
96
- export function findRetirementBaseline(home) {
97
- const canonical = retirementBaselinePath(home);
98
- if (existsSync(canonical)) return canonical;
99
- const legacy = legacyRetirementBaselinePath(home);
100
- return legacy !== canonical && existsSync(legacy) ? legacy : canonical;
101
- }
102
33
 
103
34
  /** Herdr (removed in 0.31.0) is recognised in a home only to refuse: its instance.json records a
104
35
  * Herdr session target or `backend: "herdr"`, or its independent receipt records a session target
@@ -107,7 +38,6 @@ function recordsHerdr(meta, baseline) {
107
38
  return (isPlainObject(meta) && (meta.sessionTarget !== undefined || meta.backend === "herdr"))
108
39
  || (isPlainObject(baseline?.runtime) && baseline.runtime.sessionTarget !== undefined);
109
40
  }
110
- function readJsonOrUndefined(path) { try { return JSON.parse(readFileSync(path, "utf8")); } catch { return undefined; } }
111
41
  /** Refuse any session operation on a home opened in Herdr, from its files as they are (either may be
112
42
  * missing or unreadable): before any receipt validation, so the refusal is never an endpoint error. */
113
43
  function refuseHerdrHome(home) {
@@ -241,10 +171,24 @@ function instanceSessionTarget(home, { absentMeta } = {}) {
241
171
  if (!isPlainObject(meta)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read ${recordPath}: it holds no JSON object`);
242
172
  const authority = baseline.version === RETIRE_BASELINE_VERSION && receiptRecordsHome(baseline, canonicalHomePath(home)) && runtimeAuthorityOf(baseline);
243
173
  if (!authority) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or invalid for ${home}`);
174
+ // A home that is being spawned: its receipt is there (a directory home's is written before the
175
+ // spawn's hooks run; planned, never launched) and its record is still the one its files were
176
+ // composed with (lib/materialize.mjs: its modules, and no agent, no launch, no backend yet).
177
+ // The spawn's hooks, and a provider's readiness check, run in between. Nothing contradicts
178
+ // anything: the session is not recorded yet, and a read says so (a presence read that a hook
179
+ // sets off lands here on every spawn).
180
+ const composedOnly = meta.agent === undefined && meta.launch === undefined && meta.backend === undefined && meta.tmux === undefined;
181
+ if (composedOnly && (authority.planned ? !authority.planned.launchSent : authority.launched !== true)) {
182
+ // (Whether that spawn still runs is not told here: one that ended before its record reads the same.)
183
+ throw oatsError("E_SESSION_UNAVAILABLE", `${basename(home)} is being spawned, or its spawn ended before its record was written: its session ${authority.planned ? `is planned on ${authority.planned.backend}` : "is planned"}, and its record is not there yet`);
184
+ }
244
185
  if (!launchStateAgrees(meta, authority) || !endpointAgrees(meta, authority)) throw authorityMismatch("instance metadata disagrees with independent session receipt", meta, authority);
245
186
  // `unsettled`: a launch that was sent to the home's provider and never recorded, whether the home
246
187
  // was launched before or not: `{ backend, provider, launchSent }`, or null. The one place that says so.
247
188
  const recorded = authority.session ?? authority.planned ?? null;
189
+ // A provider home's capability rows (settings, hook commands) are its receipt's, never its own
190
+ // record's, which its agent can write (lib/home-integrity.mjs): every verb reads them here.
191
+ meta = trustedRecord(meta, receiptTrust(baseline, home));
248
192
  return { home, target: authority.tmux ? { backend: "tmux", ...authority.tmux } : undefined, meta,
249
193
  ...(authority.session ? { session: authority.session } : {}), ...(authority.planned ? { planned: authority.planned } : {}),
250
194
  unsettled: recorded?.launchSent ? { backend: recorded.backend, provider: recorded.provider, launchSent: recorded.launchSent } : null };
@@ -317,4 +261,5 @@ export function inspectInstanceSession(home, { io, absentMeta } = {}) {
317
261
  * fallback shell nor a dead pane. Only such a session can be waiting on a human. */
318
262
  function harnessRunning(observed) { return observed?.present === true && observed.state !== "shell" && observed.state !== "stopped"; }
319
263
 
320
- export { RETIRE_BASELINE_VERSION, authorityMismatch, endpointAgrees, harnessRunning, providerHomeOf, providerMayWait, instanceSessionTarget, instancesRetirementRoot, isPlainObject, launchStateAgrees, missingSessionReceipt, readJsonOrUndefined, receiptHomeIdentity, receiptRecordsHome, recordsHerdr, refuseHerdrHome, runtimeAuthorityOf, tmuxEndpointAgrees };
264
+ // (The receipt's own primitives are lib/session-receipt.mjs's, exported here as they were.)
265
+ export { RETIRE_BASELINE_VERSION, findRetirementBaseline, retirementBaselinePath, authorityMismatch, endpointAgrees, harnessRunning, providerHomeOf, providerMayWait, instanceSessionTarget, instancesRetirementRoot, isPlainObject, launchStateAgrees, missingSessionReceipt, readJsonOrUndefined, receiptHomeIdentity, receiptRecordsHome, recordsHerdr, refuseHerdrHome, runtimeAuthorityOf, tmuxEndpointAgrees };