@cofy-x/axern-sdk 0.5.0 → 0.6.2

package/README.md

@@ -68,6 +68,32 @@ try {
 }
 ```
 
+## Network Policies
+
+Omitting `networkPolicy` keeps unrestricted v0.5 behavior. Strict policies are
+fail-closed; `denyDns` only refuses matching traditional UDP/TCP DNS queries and
+does not block direct IP traffic, DoH, DoT, or already-resolved addresses.
+
+```ts
+import { NetworkPolicy, Sandbox } from "@cofy-x/axern-sdk";
+
+const sandbox = await new Sandbox({
+  client,
+  image: "docker.io/library/python:3.12-slim",
+  networkPolicy: NetworkPolicy.denyDns(
+    "github.com",
+    "*.github.com",
+    "githubusercontent.com",
+    "*.githubusercontent.com",
+  ),
+}).start();
+```
+
+`NetworkPolicy.allowDomains("example.com", "*.example.com")` allows only
+strict HTTP/HTTPS destinations validated by DNS plus HTTP Host or TLS SNI.
+`NetworkPolicy.strict({ cidrRules: [...] })` adds explicit TCP/UDP CIDR and port
+grants; `NetworkPolicy.denyAll()` allows no egress.
+
 Run a tool from a separate image with `execImage` or `processImage`. OCI and
 Nydus refs use the same image field. When `mounts` is omitted, the SDK requests
 `/workspace -> /workspace`; pass `mounts: []` for no shared paths. Use

package/dist/client/index.d.ts

@@ -6,6 +6,7 @@
 import * as grpc from "@grpc/grpc-js";
 import { NodeSandboxClient } from "../node/client.js";
 import type { ResourceQuantity } from "../resources.js";
+import type { NetworkPolicy } from "../network-policy.js";
 import { TunnelControlClient } from "../tunnel/control.js";
 import type { VolumeMount } from "../types.js";
 import type { GatewayTransportOptions } from "../tunnel/relay.js";
@@ -33,6 +34,7 @@ export interface CreateServiceOptions {
     env?: Record<string, string>;
     cwd?: string;
     runtimeClass?: string;
+    networkPolicy?: NetworkPolicy;
     extensionCapabilities?: readonly ExtensionCapability[];
     volumes?: readonly VolumeMount[];
     requestCpu?: ResourceQuantity;

package/dist/client/index.js

@@ -207,6 +207,9 @@ export class AxernClient {
                     env: options.env ?? {},
                     cwd: options.cwd ?? "",
                     runtime_class: options.runtimeClass ?? "",
+                    ...(options.networkPolicy === undefined
+                        ? {}
+                        : { network: { egress_policy: options.networkPolicy.toWire() } }),
                     extension_capability_requirements: (options.extensionCapabilities ?? []).map((capability) => ({
                         capability: { name: capability.name, value: capability.value ?? "" },
                     })),

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export { SandboxProcess } from "./node/process.js";
 export type { ResourceQuantity } from "./resources.js";
 export { Sandbox } from "./sandbox/index.js";
 export type { SandboxMetadata, SandboxOptions, SandboxState } from "./sandbox/index.js";
+export { NetworkPolicy, cidrRule, portRange } from "./network-policy.js";
+export type { CIDRRule, PortRange, StrictNetworkPolicyOptions } from "./network-policy.js";
 export type { ChmodOptions, CapabilityDependencyStatus, CapabilityProviderStatus, CapabilityProviderSummary, CapabilityStatus, Command, ComputerUseDependencyStatus, ComputerUseDisplay, ComputerUseKeyboardOptions, ComputerUseMouseOptions, ComputerUseRegion, ComputerUseScreenshot, ComputerUseScreenshotOptions, ComputerUseStatus, CopyOptions, DownloadArchiveOptions, DownloadDirOptions, ExecOptions, ExecResult, ImageExecOptions, ImageProcessMount, ImageProcessOptions, MkdirOptions, MoveOptions, NodeCallOptions, ProcessEvent, ProcessOptions, ProcessResult, RemoveOptions, SandboxFileInfo, SandboxFileKind, TouchOptions, TunnelConnectorOptions, TunnelMetadata, TunnelOptions, UploadArchiveOptions, UploadDirOptions, VolumeMount, WriteFileOptions, } from "./types.js";
 export { workspaceMount } from "./types.js";
 export { AXERN_VERSION, platformName } from "./version.js";

package/dist/index.js

@@ -9,5 +9,6 @@ export { AxernError, AxernRpcError, isNotFound, isCancelled, isUnavailable, erro
 export { NodeSandboxClient } from "./node/client.js";
 export { SandboxProcess } from "./node/process.js";
 export { Sandbox } from "./sandbox/index.js";
+export { NetworkPolicy, cidrRule, portRange } from "./network-policy.js";
 export { workspaceMount } from "./types.js";
 export { AXERN_VERSION, platformName } from "./version.js";

package/dist/network-policy.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export interface PortRange {
+    readonly start: number;
+    readonly end: number;
+}
+export interface CIDRRule {
+    readonly cidr: string;
+    readonly protocol: "tcp" | "udp";
+    readonly ports: readonly PortRange[];
+}
+export interface StrictNetworkPolicyOptions {
+    readonly domains?: readonly string[];
+    readonly cidrRules?: readonly CIDRRule[];
+}
+type NetworkPolicyWire = {
+    strict: {
+        allowed_domains: string[];
+        allowed_cidrs: Record<string, unknown>[];
+    };
+} | {
+    dns_deny: {
+        denied_domains: string[];
+    };
+};
+export declare class NetworkPolicy {
+    private readonly wire;
+    private constructor();
+    static strict(options?: StrictNetworkPolicyOptions): NetworkPolicy;
+    static allowDomains(...domains: string[]): NetworkPolicy;
+    static denyDns(...domains: string[]): NetworkPolicy;
+    static denyAll(): NetworkPolicy;
+    /** @internal */
+    toWire(): NetworkPolicyWire;
+}
+export declare function portRange(start: number, end?: number): PortRange;
+export declare function cidrRule(cidr: string, protocol: "tcp" | "udp", ...ports: PortRange[]): CIDRRule;
+export {};

package/dist/network-policy.js

@@ -0,0 +1,132 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { isIP } from "node:net";
+import { domainToASCII } from "node:url";
+const maxRules = 256;
+export class NetworkPolicy {
+    wire;
+    constructor(wire) {
+        this.wire = wire;
+    }
+    static strict(options = {}) {
+        const domains = normalizeDomains(options.domains ?? []);
+        const cidrRules = normalizeCIDRRules(options.cidrRules ?? []);
+        if (domains.length + cidrRules.length > maxRules) {
+            throw new RangeError(`network policy may contain at most ${maxRules} rules`);
+        }
+        return new NetworkPolicy({
+            strict: {
+                allowed_domains: domains,
+                allowed_cidrs: cidrRules.map((rule) => ({
+                    cidr: rule.cidr,
+                    protocol: rule.protocol === "tcp" ? 1 : 2,
+                    ports: rule.ports.map((port) => ({ start: port.start, end: port.end })),
+                })),
+            },
+        });
+    }
+    static allowDomains(...domains) {
+        return NetworkPolicy.strict({ domains });
+    }
+    static denyDns(...domains) {
+        const normalized = normalizeDomains(domains);
+        if (normalized.length === 0)
+            throw new RangeError("denyDns requires at least one domain");
+        return new NetworkPolicy({ dns_deny: { denied_domains: normalized } });
+    }
+    static denyAll() {
+        return NetworkPolicy.strict();
+    }
+    /** @internal */
+    toWire() {
+        return structuredClone(this.wire);
+    }
+}
+export function portRange(start, end = start) {
+    if (!Number.isInteger(start) || !Number.isInteger(end) || start < 1 || end < start || end > 65535) {
+        throw new RangeError("ports must be an inclusive range within 1..65535");
+    }
+    return Object.freeze({ start, end });
+}
+export function cidrRule(cidr, protocol, ...ports) {
+    return normalizeCIDRRule({ cidr, protocol, ports });
+}
+function normalizeDomains(values) {
+    const result = [];
+    const seen = new Set();
+    for (const value of values) {
+        let raw = value.trim().toLowerCase();
+        const wildcard = raw.startsWith("*.");
+        if (wildcard)
+            raw = raw.slice(2);
+        raw = raw.replace(/\.+$/, "");
+        if (raw === "" || /[/:@?#*]/u.test(raw) || isIP(raw) !== 0) {
+            throw new TypeError(`invalid domain rule ${JSON.stringify(value)}`);
+        }
+        const ascii = domainToASCII(raw).toLowerCase();
+        const labels = ascii.split(".");
+        if (ascii === "" || Buffer.byteLength(ascii, "ascii") > 253 || labels.some((label) => label === "" || label.length > 63)) {
+            throw new TypeError(`invalid domain rule ${JSON.stringify(value)}`);
+        }
+        const normalized = wildcard ? `*.${ascii}` : ascii;
+        if (!seen.has(normalized)) {
+            seen.add(normalized);
+            result.push(normalized);
+        }
+    }
+    return result;
+}
+function normalizeCIDRRules(values) {
+    const result = [];
+    const seen = new Set();
+    for (const value of values) {
+        const rule = normalizeCIDRRule(value);
+        const key = JSON.stringify(rule);
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(rule);
+        }
+    }
+    return result;
+}
+function normalizeCIDRRule(value) {
+    const cidr = value.cidr.trim();
+    const separator = cidr.lastIndexOf("/");
+    const address = separator < 0 ? "" : cidr.slice(0, separator);
+    const prefix = separator < 0 ? -1 : Number(cidr.slice(separator + 1));
+    const family = isIP(address);
+    if ((family !== 4 && family !== 6) || !Number.isInteger(prefix) || prefix < 0 || prefix > (family === 4 ? 32 : 128)) {
+        throw new TypeError(`invalid CIDR ${JSON.stringify(value.cidr)}`);
+    }
+    if (isProtectedCIDR(address, prefix, family)) {
+        throw new TypeError(`CIDR ${JSON.stringify(value.cidr)} targets a protected address range`);
+    }
+    if (value.protocol !== "tcp" && value.protocol !== "udp")
+        throw new TypeError("CIDR protocol must be tcp or udp");
+    if (value.ports.length === 0)
+        throw new RangeError("CIDR rule requires at least one port range");
+    const ports = value.ports.map((port) => portRange(port.start, port.end));
+    return Object.freeze({ cidr, protocol: value.protocol, ports: Object.freeze(ports) });
+}
+function isProtectedCIDR(address, prefix, family) {
+    if (family === 4) {
+        const value = address.split(".").reduce((result, octet) => (result << 8n) | BigInt(octet), 0n);
+        const protectedRanges = [
+            [0n, 32],
+            [1684301000n, 32], // 100.100.100.200
+            [2130706432n, 8], // 127.0.0.0
+            [2851995648n, 16], // 169.254.0.0
+            [3221225664n, 32], // 192.0.0.192
+            [3758096384n, 4], // 224.0.0.0
+        ];
+        return protectedRanges.some(([base, bits]) => prefix >= bits && (value >> BigInt(32 - bits)) === (base >> BigInt(32 - bits)));
+    }
+    const canonical = new URL(`http://[${address}]/`).hostname.slice(1, -1).toLowerCase();
+    if (prefix >= 128 && (canonical === "::" || canonical === "::1"))
+        return true;
+    const first = Number.parseInt(canonical.split(":", 1)[0] || "0", 16);
+    return (prefix >= 10 && first >= 0xfe80 && first <= 0xfebf) || (prefix >= 8 && first >= 0xff00 && first <= 0xffff);
+}

package/dist/proto/axern/control/capability/v1/capability.proto

@@ -28,6 +28,11 @@ enum PlatformCapability {
   PLATFORM_CAPABILITY_RUNSC_MEMORY_ENFORCEMENT_SELF_TEST = 13;
   PLATFORM_CAPABILITY_RUNC_EPHEMERAL_ENFORCEMENT_SELF_TEST = 14;
   PLATFORM_CAPABILITY_RUNSC_EPHEMERAL_ENFORCEMENT_SELF_TEST = 15;
+  PLATFORM_CAPABILITY_EGRESSD_DNS_POLICY_SELF_TEST = 16;
+  PLATFORM_CAPABILITY_EGRESSD_STRICT_EGRESS_SELF_TEST = 17;
+  // Workload-facing capabilities derived from the egressd self-test facts.
+  PLATFORM_CAPABILITY_DNS_POLICY_ENFORCEMENT = 18;
+  PLATFORM_CAPABILITY_STRICT_EGRESS_ENFORCEMENT = 19;
 }
 
 message ExtensionCapability {

package/dist/proto/axern/control/common/v1/common.proto

@@ -49,6 +49,49 @@ enum NetworkMode {
 
 message NetworkSpec {
   NetworkMode mode = 1;
+  NetworkEgressPolicy egress_policy = 2;
+}
+
+// NetworkEgressPolicy deliberately separates strict enforcement from the
+// DNS-only convenience policy. Callers must not treat dns_deny as an egress
+// security boundary: direct IP traffic, encrypted DNS, and already-known
+// addresses remain outside that policy.
+message NetworkEgressPolicy {
+  oneof policy {
+    StrictEgressPolicy strict = 1;
+    DnsDenyPolicy dns_deny = 2;
+  }
+}
+
+// StrictEgressPolicy is default-deny. Domain grants authorize HTTP and HTTPS
+// only, on TCP ports 80 and 443, and require controlled DNS plus matching HTTP
+// Host or TLS SNI. Other protocols require an explicit CIDR rule.
+message StrictEgressPolicy {
+  repeated string allowed_domains = 1;
+  repeated CIDREgressRule allowed_cidrs = 2;
+}
+
+// DnsDenyPolicy returns REFUSED for matching conventional UDP/TCP DNS queries.
+// It does not block direct IP traffic, DoH, DoT, or previously resolved IPs.
+message DnsDenyPolicy {
+  repeated string denied_domains = 1;
+}
+
+enum EgressProtocol {
+  EGRESS_PROTOCOL_UNSPECIFIED = 0;
+  EGRESS_PROTOCOL_TCP = 1;
+  EGRESS_PROTOCOL_UDP = 2;
+}
+
+message PortRange {
+  uint32 start = 1;
+  uint32 end = 2;
+}
+
+message CIDREgressRule {
+  string cidr = 1;
+  EgressProtocol protocol = 2;
+  repeated PortRange ports = 3;
 }
 
 message PlacementConstraints {

package/dist/sandbox/index.d.ts

@@ -7,6 +7,7 @@ import { AxernClient } from "../client/index.js";
 import type { ExtensionCapability } from "../client/index.js";
 import type { SandboxProcess } from "../node/process.js";
 import type { ResourceQuantity } from "../resources.js";
+import type { NetworkPolicy } from "../network-policy.js";
 import type { ChmodOptions, CapabilityStatus, Command, ComputerUseDisplay, ComputerUseKeyboardOptions, ComputerUseMouseOptions, ComputerUseScreenshot, ComputerUseScreenshotOptions, ComputerUseStatus, CopyOptions, DownloadDirOptions, ExecOptions, ExecResult, ImageExecOptions, ImageProcessOptions, MkdirOptions, MoveOptions, NodeCallOptions, ProcessOptions, RemoveOptions, SandboxFileInfo, TunnelMetadata, TunnelOptions, TouchOptions, UploadDirOptions, VolumeMount, WriteFileOptions } from "../types.js";
 export interface SandboxOptions {
     client: AxernClient;
@@ -18,6 +19,7 @@ export interface SandboxOptions {
     env?: Record<string, string>;
     cwd?: string;
     runtimeClass?: string;
+    networkPolicy?: NetworkPolicy;
     extensionCapabilities?: readonly ExtensionCapability[];
     volumes?: readonly VolumeMount[];
     requestCpu?: ResourceQuantity;

package/dist/sandbox/index.js

@@ -59,6 +59,7 @@ export class Sandbox {
                 env: this.options.env,
                 cwd: this.options.cwd,
                 runtimeClass: this.options.runtimeClass,
+                networkPolicy: this.options.networkPolicy,
                 extensionCapabilities: this.options.extensionCapabilities,
                 volumes: this.options.volumes,
                 requestCpu: this.options.requestCpu,

package/dist/version.d.ts

@@ -3,5 +3,5 @@
  * Copyright 2026 cofy-x
  * SPDX-License-Identifier: Apache-2.0
  */
-export declare const AXERN_VERSION = "0.5.0";
+export declare const AXERN_VERSION = "0.6.2";
 export declare function platformName(): string;

package/dist/version.js

@@ -3,7 +3,7 @@
  * Copyright 2026 cofy-x
  * SPDX-License-Identifier: Apache-2.0
  */
-export const AXERN_VERSION = "0.5.0";
+export const AXERN_VERSION = "0.6.2";
 export function platformName() {
     return "axern";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cofy-x/axern-sdk",
-  "version": "0.5.0",
+  "version": "0.6.2",
   "description": "TypeScript SDK for Axern agentic infrastructure and isolated sandboxes",
   "license": "Apache-2.0",
   "repository": {