@alineo-labs/opensandbox 0.1.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 +91 -1
- package/dist/index.mjs +131 -3
- package/package.json +1 -1
package/dist/index.d.mts
CHANGED
|
@@ -40,6 +40,36 @@ interface Sandbox {
|
|
|
40
40
|
metadata?: Record<string, string>;
|
|
41
41
|
platform?: unknown;
|
|
42
42
|
}
|
|
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
|
+
*/
|
|
52
|
+
interface NetworkRule {
|
|
53
|
+
action: "allow" | "deny";
|
|
54
|
+
target: string;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Outbound network policy for a sandbox, enforced by its egress sidecar. Requires the
|
|
58
|
+
* OpenSandbox server to have `egress.image` configured — see `alineo init`'s generated
|
|
59
|
+
* `server.toml`. `defaultAction` defaults server-side to `"deny"` if omitted.
|
|
60
|
+
*/
|
|
61
|
+
interface NetworkPolicy {
|
|
62
|
+
defaultAction?: "allow" | "deny";
|
|
63
|
+
egress: NetworkRule[];
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* Opts a sandbox into transparent MITM credential injection via the egress sidecar's
|
|
67
|
+
* Credential Vault (OSEP-0012). Requires `networkPolicy` to also be set and the server to be
|
|
68
|
+
* running `egress.mode = "dns+nft"` — see `@alineo-labs/vault`.
|
|
69
|
+
*/
|
|
70
|
+
interface CredentialProxyConfig {
|
|
71
|
+
enabled: boolean;
|
|
72
|
+
}
|
|
43
73
|
interface CreateSandboxOptions {
|
|
44
74
|
image?: ImageSpec;
|
|
45
75
|
snapshotId?: string;
|
|
@@ -49,6 +79,8 @@ interface CreateSandboxOptions {
|
|
|
49
79
|
env?: Record<string, string>;
|
|
50
80
|
metadata?: Record<string, string>;
|
|
51
81
|
secureAccess?: boolean;
|
|
82
|
+
networkPolicy?: NetworkPolicy;
|
|
83
|
+
credentialProxy?: CredentialProxyConfig;
|
|
52
84
|
}
|
|
53
85
|
interface ListSandboxesOptions {
|
|
54
86
|
state?: SandboxState;
|
|
@@ -241,6 +273,64 @@ declare class ControlClient {
|
|
|
241
273
|
deleteSnapshot(id: string): Promise<void>;
|
|
242
274
|
}
|
|
243
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
|
|
244
334
|
//#region src/exec.d.ts
|
|
245
335
|
declare class ExecClient {
|
|
246
336
|
private baseUrl;
|
|
@@ -334,4 +424,4 @@ declare class PtyClient {
|
|
|
334
424
|
close(): void;
|
|
335
425
|
}
|
|
336
426
|
//#endregion
|
|
337
|
-
export { type CodeContext, CodeLanguage, type CommandStatus, ControlClient, type CreatePtyOptions, type CreatePtyResponse, type CreateSandboxOptions, type CreateSessionRequest, type CreateSessionResponse, type DiagnosticEvent, type DiagnosticLog, ExecClient, type ExecuteCodeOptions, type ExecuteCommandOptions, type FileInfo, type FileReplacement, type ImageAuth, type ImageSpec, type ListSandboxesOptions, type ListSnapshotsOptions, type Metrics, 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";
|
|
@@ -445,8 +569,12 @@ var PtyClient = class {
|
|
|
445
569
|
const decoder = new TextDecoder();
|
|
446
570
|
let gotExitFrame = false;
|
|
447
571
|
return new Promise((resolve, reject) => {
|
|
448
|
-
ws.onopen = () =>
|
|
449
|
-
|
|
572
|
+
ws.onopen = () => {
|
|
573
|
+
resolve();
|
|
574
|
+
};
|
|
575
|
+
ws.onerror = (ev) => {
|
|
576
|
+
reject(/* @__PURE__ */ new Error(`pty websocket error: ${ev.type}`));
|
|
577
|
+
};
|
|
450
578
|
ws.onclose = () => {
|
|
451
579
|
if (!gotExitFrame) onExit(-1);
|
|
452
580
|
};
|
|
@@ -489,4 +617,4 @@ var PtyClient = class {
|
|
|
489
617
|
}
|
|
490
618
|
};
|
|
491
619
|
//#endregion
|
|
492
|
-
export { CodeLanguage, ControlClient, ExecClient, OpenSandboxError, PtyClient, SSEEventType, SandboxState, SnapshotState };
|
|
620
|
+
export { CodeLanguage, ControlClient, EgressClient, EgressClientError, ExecClient, OpenSandboxError, PtyClient, SSEEventType, SandboxState, SnapshotState, isValidEgressTarget };
|