@alineo-labs/opensandbox 0.2.0 → 0.3.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/dist/index.d.mts +68 -2
- package/dist/index.mjs +125 -1
- package/package.json +1 -1
package/dist/index.d.mts
CHANGED
|
@@ -40,7 +40,15 @@ interface Sandbox {
|
|
|
40
40
|
metadata?: Record<string, string>;
|
|
41
41
|
platform?: unknown;
|
|
42
42
|
}
|
|
43
|
-
/**
|
|
43
|
+
/**
|
|
44
|
+
* A single ordered rule in a `NetworkPolicy`. `target` is one of:
|
|
45
|
+
* - an FQDN (`"api.github.com"`) or wildcard domain (`"*.openai.com"`) — matched against the
|
|
46
|
+
* DNS query name;
|
|
47
|
+
* - a bare IPv4/IPv6 address (`"10.0.0.5"`) or CIDR block (`"10.0.0.0/8"`) — enforced at the
|
|
48
|
+
* nftables layer, so it only takes effect when the server runs `egress.mode = "dns+nft"`,
|
|
49
|
+
* and it gates raw-IP egress only. It does **not** authorize resolving a *domain* that
|
|
50
|
+
* happens to resolve into that range — use a domain rule for reach-by-name.
|
|
51
|
+
*/
|
|
44
52
|
interface NetworkRule {
|
|
45
53
|
action: "allow" | "deny";
|
|
46
54
|
target: string;
|
|
@@ -265,6 +273,64 @@ declare class ControlClient {
|
|
|
265
273
|
deleteSnapshot(id: string): Promise<void>;
|
|
266
274
|
}
|
|
267
275
|
//#endregion
|
|
276
|
+
//#region src/egress.d.ts
|
|
277
|
+
/** Thrown for a non-2xx response from the egress sidecar's policy API. */
|
|
278
|
+
declare class EgressClientError extends Error {
|
|
279
|
+
readonly status: number;
|
|
280
|
+
constructor(message: string, status: number);
|
|
281
|
+
}
|
|
282
|
+
/** `GET /policy` response — the sidecar wraps the live policy in a status envelope. */
|
|
283
|
+
interface EgressPolicyStatus {
|
|
284
|
+
status?: string;
|
|
285
|
+
mode?: string;
|
|
286
|
+
enforcementMode?: string;
|
|
287
|
+
policy?: NetworkPolicy | null;
|
|
288
|
+
}
|
|
289
|
+
/**
|
|
290
|
+
* Talks directly to a sandbox's egress sidecar policy API (`PATCH`/`DELETE`/`GET /policy` on
|
|
291
|
+
* port `18080`), resolved the same way `VaultClient` resolves the Credential Vault — via
|
|
292
|
+
* `ControlClient.getEndpoint()`, against the sidecar's port instead of execd's `44772`.
|
|
293
|
+
*
|
|
294
|
+
* The policy API and the Credential Vault share one HTTP server and one auth check on the
|
|
295
|
+
* sidecar: an `alineo init` sidecar runs token-less, so the `getEndpoint()` headers are all
|
|
296
|
+
* that is needed. A hardened deployment that sets `OPENSANDBOX_EGRESS_TOKEN` would also need
|
|
297
|
+
* an `OPENSANDBOX-EGRESS-AUTH` header — not wired here yet.
|
|
298
|
+
*
|
|
299
|
+
* Wire shapes verified against `opensandbox-group/OpenSandbox`'s
|
|
300
|
+
* `components/egress/policy_server.go`:
|
|
301
|
+
* - `PATCH /policy` — body is a JSON **array** of `{ action, target }`; merge semantics
|
|
302
|
+
* (an incoming rule replaces a same-`target` rule, others untouched, `defaultAction` kept).
|
|
303
|
+
* - `DELETE /policy` — body is a JSON **array of target strings**; unmatched targets are
|
|
304
|
+
* silently ignored.
|
|
305
|
+
* - `GET /policy` — returns `{ status, mode, enforcementMode, policy }`.
|
|
306
|
+
*
|
|
307
|
+
* Egress policy is sidecar-local runtime state: it does not survive the sidecar restarting
|
|
308
|
+
* and is not restored by OpenSandbox's snapshot/checkpoint — `@alineo-labs/core` folds a
|
|
309
|
+
* `resume()`d sandbox's still-live changes back into its boot policy from the ledger. (A
|
|
310
|
+
* `fork()` does not carry them.)
|
|
311
|
+
*/
|
|
312
|
+
declare class EgressClient {
|
|
313
|
+
private readonly control;
|
|
314
|
+
private readonly useServerProxy?;
|
|
315
|
+
private static readonly PORT;
|
|
316
|
+
constructor(control: ControlClient, useServerProxy?: boolean | undefined);
|
|
317
|
+
private request;
|
|
318
|
+
/** Merge `rules` into the live policy — an incoming rule replaces any rule with the same `target`. */
|
|
319
|
+
patchRules(sandboxId: string, rules: NetworkRule[]): Promise<EgressPolicyStatus>;
|
|
320
|
+
/** Remove every rule whose `target` is in `targets`. Unknown targets are ignored. */
|
|
321
|
+
deleteRules(sandboxId: string, targets: string[]): Promise<EgressPolicyStatus>;
|
|
322
|
+
/** The live policy plus the sidecar's status envelope. */
|
|
323
|
+
getPolicy(sandboxId: string): Promise<EgressPolicyStatus>;
|
|
324
|
+
}
|
|
325
|
+
//#endregion
|
|
326
|
+
//#region src/egress-target.d.ts
|
|
327
|
+
/**
|
|
328
|
+
* Returns whether `target` is a plausible `NetworkRule.target`: an FQDN, a `*.`-prefixed
|
|
329
|
+
* wildcard domain, a bare IPv4/IPv6 address, or a CIDR block. Whitespace-only, URL-shaped
|
|
330
|
+
* (`http://…`), space-containing, or otherwise clearly-malformed strings return `false`.
|
|
331
|
+
*/
|
|
332
|
+
declare function isValidEgressTarget(target: string): boolean;
|
|
333
|
+
//#endregion
|
|
268
334
|
//#region src/exec.d.ts
|
|
269
335
|
declare class ExecClient {
|
|
270
336
|
private baseUrl;
|
|
@@ -358,4 +424,4 @@ declare class PtyClient {
|
|
|
358
424
|
close(): void;
|
|
359
425
|
}
|
|
360
426
|
//#endregion
|
|
361
|
-
export { type CodeContext, CodeLanguage, type CommandStatus, ControlClient, type CreatePtyOptions, type CreatePtyResponse, type CreateSandboxOptions, type CreateSessionRequest, type CreateSessionResponse, type CredentialProxyConfig, type DiagnosticEvent, type DiagnosticLog, ExecClient, type ExecuteCodeOptions, type ExecuteCommandOptions, type FileInfo, type FileReplacement, type ImageAuth, type ImageSpec, type ListSandboxesOptions, type ListSnapshotsOptions, type Metrics, type NetworkPolicy, type NetworkRule, OpenSandboxError, PtyClient, type PtyClientMessage, type PtyExitListener, type PtyOutputListener, type PtyServerMessage, type Resources, type RunInSessionRequest, type SSEEvent, SSEEventType, type Sandbox, type SandboxEndpoint, SandboxState, type SandboxStatus, type Snapshot, SnapshotState };
|
|
427
|
+
export { type CodeContext, CodeLanguage, type CommandStatus, ControlClient, type CreatePtyOptions, type CreatePtyResponse, type CreateSandboxOptions, type CreateSessionRequest, type CreateSessionResponse, type CredentialProxyConfig, type DiagnosticEvent, type DiagnosticLog, EgressClient, EgressClientError, type EgressPolicyStatus, ExecClient, type ExecuteCodeOptions, type ExecuteCommandOptions, type FileInfo, type FileReplacement, type ImageAuth, type ImageSpec, type ListSandboxesOptions, type ListSnapshotsOptions, type Metrics, type NetworkPolicy, type NetworkRule, OpenSandboxError, PtyClient, type PtyClientMessage, type PtyExitListener, type PtyOutputListener, type PtyServerMessage, type Resources, type RunInSessionRequest, type SSEEvent, SSEEventType, type Sandbox, type SandboxEndpoint, SandboxState, type SandboxStatus, type Snapshot, SnapshotState, isValidEgressTarget };
|
package/dist/index.mjs
CHANGED
|
@@ -101,6 +101,130 @@ var ControlClient = class ControlClient {
|
|
|
101
101
|
}
|
|
102
102
|
};
|
|
103
103
|
//#endregion
|
|
104
|
+
//#region src/egress.ts
|
|
105
|
+
/** Thrown for a non-2xx response from the egress sidecar's policy API. */
|
|
106
|
+
var EgressClientError = class extends Error {
|
|
107
|
+
status;
|
|
108
|
+
constructor(message, status) {
|
|
109
|
+
super(message);
|
|
110
|
+
this.status = status;
|
|
111
|
+
this.name = "EgressClientError";
|
|
112
|
+
}
|
|
113
|
+
};
|
|
114
|
+
/**
|
|
115
|
+
* Talks directly to a sandbox's egress sidecar policy API (`PATCH`/`DELETE`/`GET /policy` on
|
|
116
|
+
* port `18080`), resolved the same way `VaultClient` resolves the Credential Vault — via
|
|
117
|
+
* `ControlClient.getEndpoint()`, against the sidecar's port instead of execd's `44772`.
|
|
118
|
+
*
|
|
119
|
+
* The policy API and the Credential Vault share one HTTP server and one auth check on the
|
|
120
|
+
* sidecar: an `alineo init` sidecar runs token-less, so the `getEndpoint()` headers are all
|
|
121
|
+
* that is needed. A hardened deployment that sets `OPENSANDBOX_EGRESS_TOKEN` would also need
|
|
122
|
+
* an `OPENSANDBOX-EGRESS-AUTH` header — not wired here yet.
|
|
123
|
+
*
|
|
124
|
+
* Wire shapes verified against `opensandbox-group/OpenSandbox`'s
|
|
125
|
+
* `components/egress/policy_server.go`:
|
|
126
|
+
* - `PATCH /policy` — body is a JSON **array** of `{ action, target }`; merge semantics
|
|
127
|
+
* (an incoming rule replaces a same-`target` rule, others untouched, `defaultAction` kept).
|
|
128
|
+
* - `DELETE /policy` — body is a JSON **array of target strings**; unmatched targets are
|
|
129
|
+
* silently ignored.
|
|
130
|
+
* - `GET /policy` — returns `{ status, mode, enforcementMode, policy }`.
|
|
131
|
+
*
|
|
132
|
+
* Egress policy is sidecar-local runtime state: it does not survive the sidecar restarting
|
|
133
|
+
* and is not restored by OpenSandbox's snapshot/checkpoint — `@alineo-labs/core` folds a
|
|
134
|
+
* `resume()`d sandbox's still-live changes back into its boot policy from the ledger. (A
|
|
135
|
+
* `fork()` does not carry them.)
|
|
136
|
+
*/
|
|
137
|
+
var EgressClient = class EgressClient {
|
|
138
|
+
control;
|
|
139
|
+
useServerProxy;
|
|
140
|
+
static PORT = 18080;
|
|
141
|
+
constructor(control, useServerProxy) {
|
|
142
|
+
this.control = control;
|
|
143
|
+
this.useServerProxy = useServerProxy;
|
|
144
|
+
}
|
|
145
|
+
async request(sandboxId, method, body) {
|
|
146
|
+
const ep = await this.control.getEndpoint(sandboxId, EgressClient.PORT, this.useServerProxy);
|
|
147
|
+
const baseUrl = ep.endpoint.startsWith("http") ? ep.endpoint : `http://${ep.endpoint}`;
|
|
148
|
+
const init = {
|
|
149
|
+
method,
|
|
150
|
+
headers: {
|
|
151
|
+
...ep.headers,
|
|
152
|
+
...body !== void 0 ? { "Content-Type": "application/json" } : {}
|
|
153
|
+
},
|
|
154
|
+
...body !== void 0 ? { body: JSON.stringify(body) } : {}
|
|
155
|
+
};
|
|
156
|
+
const delaysMs = [
|
|
157
|
+
0,
|
|
158
|
+
300,
|
|
159
|
+
600,
|
|
160
|
+
1200,
|
|
161
|
+
2400
|
|
162
|
+
];
|
|
163
|
+
let lastErr;
|
|
164
|
+
for (const delay of delaysMs) {
|
|
165
|
+
if (delay > 0) await new Promise((r) => setTimeout(r, delay));
|
|
166
|
+
const res = await fetch(`${baseUrl}/policy`, init);
|
|
167
|
+
if (res.ok) {
|
|
168
|
+
if (res.status === 204) return void 0;
|
|
169
|
+
const text = await res.text();
|
|
170
|
+
return text ? JSON.parse(text) : void 0;
|
|
171
|
+
}
|
|
172
|
+
lastErr = new EgressClientError(await res.text().catch(() => "") || "egress policy API error", res.status);
|
|
173
|
+
if (res.status !== 500 && res.status !== 502 && res.status !== 412) throw lastErr;
|
|
174
|
+
}
|
|
175
|
+
throw lastErr ?? new EgressClientError("egress policy API error", 500);
|
|
176
|
+
}
|
|
177
|
+
/** Merge `rules` into the live policy — an incoming rule replaces any rule with the same `target`. */
|
|
178
|
+
patchRules(sandboxId, rules) {
|
|
179
|
+
return this.request(sandboxId, "PATCH", rules);
|
|
180
|
+
}
|
|
181
|
+
/** Remove every rule whose `target` is in `targets`. Unknown targets are ignored. */
|
|
182
|
+
deleteRules(sandboxId, targets) {
|
|
183
|
+
return this.request(sandboxId, "DELETE", targets);
|
|
184
|
+
}
|
|
185
|
+
/** The live policy plus the sidecar's status envelope. */
|
|
186
|
+
getPolicy(sandboxId) {
|
|
187
|
+
return this.request(sandboxId, "GET");
|
|
188
|
+
}
|
|
189
|
+
};
|
|
190
|
+
//#endregion
|
|
191
|
+
//#region src/egress-target.ts
|
|
192
|
+
const IPV4_OCTET = "(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)";
|
|
193
|
+
const ipv4Re = new RegExp(`^${IPV4_OCTET}(\\.${IPV4_OCTET}){3}$`);
|
|
194
|
+
const ipv6Re = /^(?=.*:)[0-9a-fA-F:]*(?::(25[0-5]|2[0-4]\d|1?\d?\d)(\.(25[0-5]|2[0-4]\d|1?\d?\d)){3})?$/;
|
|
195
|
+
/** A single DNS label: alphanumeric plus internal hyphens, 1–63 chars. */
|
|
196
|
+
const LABEL = "(?!-)[A-Za-z0-9-]{1,63}(?<!-)";
|
|
197
|
+
const domainRe = new RegExp(`^(\\*\\.)?(${LABEL}\\.)*${LABEL}\\.?$`);
|
|
198
|
+
function isIpv6(s) {
|
|
199
|
+
return (s.includes("::") || (s.match(/:/g)?.length ?? 0) >= 2) && ipv6Re.test(s);
|
|
200
|
+
}
|
|
201
|
+
function isIpAddress(s) {
|
|
202
|
+
return ipv4Re.test(s) || isIpv6(s);
|
|
203
|
+
}
|
|
204
|
+
function isCidr(s) {
|
|
205
|
+
const slash = s.lastIndexOf("/");
|
|
206
|
+
if (slash === -1) return false;
|
|
207
|
+
const addr = s.slice(0, slash);
|
|
208
|
+
const bits = s.slice(slash + 1);
|
|
209
|
+
if (!/^\d{1,3}$/.test(bits)) return false;
|
|
210
|
+
const n = Number(bits);
|
|
211
|
+
if (ipv4Re.test(addr)) return n <= 32;
|
|
212
|
+
if (isIpv6(addr)) return n <= 128;
|
|
213
|
+
return false;
|
|
214
|
+
}
|
|
215
|
+
/**
|
|
216
|
+
* Returns whether `target` is a plausible `NetworkRule.target`: an FQDN, a `*.`-prefixed
|
|
217
|
+
* wildcard domain, a bare IPv4/IPv6 address, or a CIDR block. Whitespace-only, URL-shaped
|
|
218
|
+
* (`http://…`), space-containing, or otherwise clearly-malformed strings return `false`.
|
|
219
|
+
*/
|
|
220
|
+
function isValidEgressTarget(target) {
|
|
221
|
+
const t = target.trim();
|
|
222
|
+
if (t === "" || /\s/.test(t) || t.includes("/") !== isCidr(t)) return false;
|
|
223
|
+
if (isIpAddress(t)) return true;
|
|
224
|
+
if (isCidr(t)) return true;
|
|
225
|
+
return domainRe.test(t);
|
|
226
|
+
}
|
|
227
|
+
//#endregion
|
|
104
228
|
//#region src/types.ts
|
|
105
229
|
let SandboxState = /* @__PURE__ */ function(SandboxState) {
|
|
106
230
|
SandboxState["Pending"] = "Pending";
|
|
@@ -493,4 +617,4 @@ var PtyClient = class {
|
|
|
493
617
|
}
|
|
494
618
|
};
|
|
495
619
|
//#endregion
|
|
496
|
-
export { CodeLanguage, ControlClient, ExecClient, OpenSandboxError, PtyClient, SSEEventType, SandboxState, SnapshotState };
|
|
620
|
+
export { CodeLanguage, ControlClient, EgressClient, EgressClientError, ExecClient, OpenSandboxError, PtyClient, SSEEventType, SandboxState, SnapshotState, isValidEgressTarget };
|