Network

What a sandbox exposes to the network and what it may reach: its ports and how to reach them, the outbound network policy, and request transformations, which set headers on outbound requests after they leave the sandbox so that credentials never enter it.

Since v0.1.0

Schemas

Endpoint

How to reach a sandbox port from outside: the URL, and any headers the provider requires.

Details

A request to the URL with those headers reaches the server with the request’s other headers intact, Authorization included.

Signature

declare const Endpoint: Schema.Struct<{
  readonly url: Schema.String
  readonly headers: Schema.$Record<Schema.String, Schema.Redacted<Schema.String>>
}>

Source

Since v0.1.0

Endpoint (interface)

Signature

export interface Endpoint extends Schema.Schema.Type<typeof Endpoint> {}

Source

Since v0.1.0

EndpointProtocol

The kind of connection an endpoint is for; its URL uses the secure scheme when the provider serves one.

Signature

declare const EndpointProtocol: Schema.Literals<readonly ["http", "ws"]>

Source

Since v0.1.0

EndpointProtocol (type alias)

Signature

type EndpointProtocol = typeof EndpointProtocol.Type

Source

Since v0.1.0

NetworkPolicy

Which outbound destinations the sandbox may reach.

Details

AllowList allows the listed hosts and CIDR ranges, and deniedCidrs overrides both, for example to block a cloud metadata address inside an allowed range.

Example (Allowing one registry and a private network, except its metadata address)

import { Network } from "@amends-dev/sandbox"

const policy = Network.NetworkPolicy.cases.AllowList.make({
  allowedHosts: ["registry.npmjs.org"],
  allowedCidrs: ["10.0.0.0/8"],
  deniedCidrs: ["169.254.169.254/32"]
})

Signature

declare const NetworkPolicy: Schema.TaggedUnion<{
  readonly AllowAll: Schema.TaggedStruct<"AllowAll", {}>
  readonly DenyAll: Schema.TaggedStruct<"DenyAll", {}>
  readonly AllowList: Schema.TaggedStruct<
    "AllowList",
    {
      readonly allowedHosts: Schema.$Array<Schema.String>
      readonly allowedCidrs: Schema.$Array<Schema.String>
      readonly deniedCidrs: Schema.$Array<Schema.String>
    }
  >
}>

Source

Since v0.1.0

NetworkPolicy (type alias)

Signature

type NetworkPolicy = typeof NetworkPolicy.Type

Source

Since v0.1.0

Port

A TCP port a sandbox exposes, from 1 to 65535.

Signature

declare const Port: Schema.brand<Schema.Int, "Port">

Source

Since v0.1.0

Port (type alias)

Signature

type Port = typeof Port.Type

Source

Since v0.1.0

RequestTransformation

Sets setHeaders on outbound HTTPS requests to host whose path starts with pathPrefix and that carry every header in matchHeaders with exactly that value.

Details

The sandbox holds only a placeholder credential, matched here, and the real value is set outside it.

Example (Giving a sandbox an API key it never sees)

import { Network } from "@amends-dev/sandbox"
import type { Redacted } from "effect"

declare const apiKey: Redacted.Redacted<string>

const anthropicKey: Network.RequestTransformation = {
  host: "api.anthropic.com",
  matchHeaders: { "x-api-key": "placeholder" },
  setHeaders: { "x-api-key": apiKey }
}

Signature

declare const RequestTransformation: Schema.Struct<{
  readonly host: Schema.String
  readonly pathPrefix: Schema.optionalKey<Schema.String>
  readonly matchHeaders: Schema.$Record<Schema.String, Schema.String>
  readonly setHeaders: Schema.$Record<Schema.String, Schema.Redacted<Schema.String>>
}>

Source

Since v0.1.0

RequestTransformation (interface)

Signature

export interface RequestTransformation extends Schema.Schema.Type<typeof RequestTransformation> {}

Source

Since v0.1.0