@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 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 = () => resolve();
449
- ws.onerror = (ev) => reject(/* @__PURE__ */ new Error(`pty websocket error: ${String(ev)}`));
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 };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alineo-labs/opensandbox",
3
- "version": "0.1.0",
3
+ "version": "0.3.0",
4
4
  "license": "Apache-2.0",
5
5
  "repository": {
6
6
  "type": "git",