Network permissions

network makes your app declare who it may talk to, like a mobile app's permissions. Anything not on your list in main.yaml, or declared by a driver, is blocked and reported.

network:
  allow:
    - api.partner.com
    - "*.pinecart.dev"
  default: deny
  mode: enforce
  http:
    timeout: 10s
    connect: 3s
    retries: { attempts: 3, backoff: 200ms, max: 5s, deadline: 30s }
    breaker: { failures: 50%, window: 30s, min: 10, cooldown: 15s }
    hosts:
      api.partner.com: { timeout: 3s, retries: { attempts: 5 } }
exceptions:
  - { rule: net.default_deny, reason: "partner VPN", owner: "@pinecart/platform", expires: 2026-11-30 }

import { http } from "mainsdk";

// allowed only if api.partner.com is in network.allow
const res = await http.fetch("https://api.partner.com/v1/rates");

import assert from "node:assert/strict";
import { it } from "node:test";
import { createTestApp } from "@mainsdk/testing";
import { http } from "mainsdk";

it("network AC1 blocks an undeclared host", async () => {
  const app = createTestApp({
    yaml: "schema: 1\nproject: rates\nnetwork:\n  allow: [api.partner.com]\n",
    respond: () => Response.json({ price: 5 }),   // what an allowed host answers
  });
  await assert.rejects(http.fetch("https://evil.example"), { code: "MAIN-NET-0002" });
  assert.deepEqual(await http.json("https://api.partner.com/v1/rates"), { price: 5 });
  assert.equal(app.sent.length, 1);   // only the allowed call was sent
});

network:
  driver: builtin

Quick start

network:
  allow:
    - api.partner.com
  default: deny
  mode: enforce

import { http } from "mainsdk";

export async function loadRates() {
  // allowed: api.partner.com is in network.allow
  const res = await http.fetch("https://api.partner.com/v1/rates");
  return res.json();
}

use mainsdk::prelude::*;
let app = App::test();
let err = app.network().assert("https://example.com/x").unwrap_err();
assert_eq!(err.code, ErrorCode::MainNet0002);

A call to a host that is not on the list, and not declared by a driver you use, is blocked with MAIN-NET-0002.

Configuration

Every key below lives under network:.

network:
  allow:
    - 8.8.8.8            # one IP
    - 10.20.0.0/16       # a range (IPv4 or IPv6 CIDR)
    - google.com         # exactly this domain, not its subdomains
    - "*.pinecart.dev"   # subdomains of pinecart.dev only, not pinecart.dev itself
  default: deny          # everything else is blocked and reported
  mode: enforce          # observe | warn | enforce

The effective list is your allow list plus the hosts of the drivers in use. The Resend driver declares api.resend.com, so you never list provider hosts yourself.

Matching rules:

• An exact domain does not match its subdomains. google.com does not allow mail.google.com.
• *.domain matches subdomains only. *.pinecart.dev allows api.pinecart.dev but not pinecart.dev.
• Prefer domains; IPs behind CDNs change. IPs suit fixed services such as a partner's VPN gateway.
• A plain entry covers HTTP, HTTPS and WebSocket only. Raw TCP and UDP need an entry with the protocol and port, such as tcp://db.acme.dev:5432 or udp://8.8.8.8:53, and listening needs network.listen. See TCP and UDP sockets.

Inherited and overlay lists

main.org.yaml can set the list for every app. An app can remove hosts (tightening), but adding a host the org does not allow is weakening: it fails with MAIN-CONFIG-0010 unless an exception names the rule, a reason, an owner and an expiry:

exceptions:
  - { rule: net.default_deny, reason: "partner VPN", owner: "@pinecart/platform", expires: 2026-11-30 }

An expired exception fails like no exception. See main.yaml.

Helpers

http.fetch is the base. The helpers below cover the calls apps make most often. Each one goes through the same allow-list check, and the decision names the calling file and line.

import { http } from "mainsdk";

// allowed: api.partner.com is in network.allow
export async function quote(sku: string) {
  return http.json<{ price: number }>("https://api.partner.com/v1/quotes", { body: { sku } });
}

export async function watchPrices() {
  for await (const event of http.events("https://api.partner.com/v1/prices/stream")) {
    console.log(event.data);
  }
}

export async function openFeed() {
  return http.websocket("wss://feed.partner.com/live");
}

Use http.assert before a driver or library opens a connection the SDK cannot wrap, such as a database client. It throws MAIN-NET-0002 for a host that is not allowed, and returns the decision when it is:

import { http } from "mainsdk";

const url = process.env.DATABASE_URL ?? "";
await http.assert(url);   // throws MAIN-NET-0002 if the database host is not allowed

Server-side programs such as git or curl run through system.run (see Server facts and programs). Every URL in their arguments is checked against this list too.

Reliable calls

Every outbound call is bounded and retried when it is safe, and a host that keeps failing is cut off. You write http.get() and get the same behaviour as every driver, with no timeout or retry loop of your own.

network:
  http:
    timeout: 10s           # one attempt, until the body is read; "off" for none
    connect: 3s            # one attempt, until the response headers arrive
    retries: { attempts: 3, backoff: 200ms, max: 5s, deadline: 30s }   # or retries: off
    breaker: { failures: 50%, window: 30s, min: 10, cooldown: 15s }   # or breaker: off
    hosts:                 # an exact host or "*.domain", as in network.allow
      api.partner.com: { timeout: 3s, retries: { attempts: 5 } }

These are the defaults, except hosts. Settings resolve per field, most specific first: the call, then the host's entry in hosts, then the driver's defaults for that host, then network.http, then the built-in defaults.

Options on each call

import { http } from "mainsdk";

// a slow report: give it more time, and do not retry it
export function report(id: string) {
  return http.get(`https://api.partner.com/v1/reports/${id}`, { timeout: "30s", retries: false });
}

// a charge: the key makes the POST safe to retry
export function charge(orderId: string, body: { amount: number }) {
  return http.post("https://api.partner.com/v1/charges", body, { idempotencyKey: orderId });
}

Use one key per logical call and reuse it on every retry. A new key for a retry defeats the point.

What is retried

• Only GET, HEAD, PUT, DELETE and OPTIONS are retried, and a POST that carries an idempotencyKey. A request whose body is a stream is never retried.
• A retry happens after a network error, a timed-out attempt, or a 408, 429, 502, 503 or 504 answer. Any other answer is returned as it is.
• Waits use full jitter: a random wait up to backoff doubled each attempt, capped at max. A Retry-After header on a 429 or 503 replaces that wait, even above max.
• A call stops after attempts tries or when the next wait would pass deadline. It then returns the last answer, or fails with MAIN-NET-0009 (timed out) or MAIN-NET-0011 (network error).
• A call blocked by the allowlist (MAIN-NET-0002) is never retried and never counts against the breaker.

The circuit breaker

Each host has its own breaker in each app instance. When the share of failed attempts in the last window reaches failures, with at least min attempts in it, the breaker opens. A failure is a network error, a timeout, or a 500, 502, 503 or 504; a 429 or other 4xx is not.

While the breaker is open, a call to that host fails at once with MAIN-NET-0010 and sends nothing. After cooldown one probe call goes through; if it succeeds the breaker closes, and if it fails the breaker opens again. Calls to other hosts are unaffected. A breaker's state is per instance and starts closed on every start.

Every attempt and every breaker change is written to the decision log, with the attempt number, its wait and its outcome. Bodies, Authorization headers and Idempotency-Key values are never logged.

Find what your code calls

npx mainsdk discover

discover reads your source and main.yaml and lists every host the code connects to, with the file and line, the kind of connection and whether main.yaml declares it. It also lists the server folders, facts and programs the app uses, which are covered by Declare what your app uses. Each undeclared host is marked MISSING, and the output ends with the network.allow lines to add.

network
  declared http         https://api.partner.com  lib/partner.ts:5
  MISSING  websocket    wss://feed.partner.com  lib/partner.ts:15

Three more ways to use it:

• npx mainsdk discover --json prints the full manifest for scripts and agents.
• npx mainsdk discover --out build/manifest.json writes the manifest to a file at build time, so a review or a platform rule can read what the app uses without running it.
• npx mainsdk network export --to k8s --discovered adds the hosts the code uses that network.allow doesn't list yet.

mainsdk check fails with MAIN-NET-0007 for any host the code uses that network.allow doesn't declare. A URL that is only known when the app runs, such as one read from a variable, is listed as dynamic: discovery can't read its host, so the runtime check is what guards it.

Examples

Call a partner API from a route handler

import { auth, http } from "mainsdk";

export async function POST(req: Request) {
  await auth.require(req);
  const body = (await req.json()) as { sku: string; qty: number };

  const res = await http.fetch("https://api.partner.com/v1/quotes", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ sku: body.sku, qty: body.qty }),
  });
  return Response.json(await res.json(), { status: res.status });
}

http.fetch(url, init) is the client every driver and app call uses, so you write it like fetch.

Roll a new list out safely

Adopting network on an existing app: start in observe, read what would be blocked, add what is legitimate, then enforce.

network:
  mode: observe     # calls succeed; would-block decisions are logged

Every block or would-block is written to the decision log with the destination, the rule and the calling file and line, and shows in mainsdk info:

npx mainsdk info --json

Once the log is clean, switch the overlay to warn, then enforce.

Internal services from an Express worker

Private ranges are reachable only when you declare them. A DNS answer that points an allowed name at a private address you did not declare is refused as rebinding.

network:
  allow:
    - "*.pinecart.dev"
    - 10.20.0.0/16        # the internal billing service
  default: deny

import { createServer } from "node:http";
import { http } from "mainsdk";

createServer(async (req, res) => {
  const id = req.url?.split("/")[2] ?? "";   // /invoices/:id/sync
  const upstream = await http.fetch(`http://10.20.4.12/invoices/${id}`);   // inside 10.20.0.0/16
  res.writeHead(upstream.status, { "content-type": "application/json" });
  res.end(JSON.stringify(await upstream.json()));
}).listen(3000);

A second wall at the platform

Export the same list as platform egress rules, so the network blocks undeclared hosts even if code finds a way around the SDK.

npx mainsdk network export --to k8s

Targets are k8s (a NetworkPolicy) and aws-sg (security group egress rules). Exports for Vercel and Cloudflare are planned. Platform rules match IPs, so names are resolved when you export. For Kubernetes the policy holds your CIDR egress rules, such as 10.20.0.0/16 and 8.8.8.8/32. --discovered adds hosts the code uses that network.allow does not list yet.

Reference: the network layer

The Network instance behind http has calls of its own. They are for adapters, drivers, tests and tooling. Most apps use only the http helpers above.

Customer-chosen URLs

A URL a customer typed, such as a webhook endpoint, must never reach a private address, and no network.allow entry can change that. These two calls take no allow-list entry.

Helpers

These functions are exported for tooling and tests.

Both exports take { name?, resolve?, listen? }: a name for the policy, a function that resolves a host to addresses, and the network.listen entries from main.yaml. They are what npx mainsdk network export runs.

What you get

• Every outbound call goes through the SDK's network layer and is checked against the list in main.yaml, plus the hosts your drivers declare.
• A poisoned dependency that tries to send your secrets to a new domain fails in CI and is stopped in production.
• Reach for http.fetch whenever your own code calls an outside API.
• It runs inside your app and is free on every plan.

Errors and checks

The decision log names the destination, the rule and the calling file and line for every block. The check codes for this interface are listed above.

Swapping drivers

network has one driver, built in. Other interfaces' drivers feed it: each driver declares the hosts it calls, and those join the effective list. When you swap email from Resend to SES, api.resend.com leaves the list and the SES host joins it, with no change to network.allow. network.destinations() shows the result.

Driver calls go through the same layer. A driver that reaches a host it did not declare is blocked with MAIN-NET-0002 like any other call. A kit for writing your own drivers (defineDriver, spec cohesion) is planned.

Testing

Route tests run on the in-memory fakes, so they make no real network calls. Assert the guarantee itself with a test named by its criterion:

import assert from "node:assert/strict";
import { it } from "node:test";
import { createTestApp } from "@mainsdk/testing";
import { http } from "mainsdk";

it("network AC1 blocks an undeclared host", async () => {
  const app = createTestApp({
    yaml: "schema: 1\nproject: rates\nnetwork:\n  allow: [api.partner.com]\n",
    respond: () => Response.json({ price: 5 }),   // what an allowed host answers
  });
  await assert.rejects(http.fetch("https://evil.example"), { code: "MAIN-NET-0002" });
  assert.deepEqual(await http.json("https://api.partner.com/v1/rates"), { price: 5 });
  assert.equal(app.sent.length, 1);   // only the allowed call was sent
});

respond answers every call the list lets through; without it the fake answers 204. dns maps names to fake addresses for the rebinding check. See the Testing kit.

Security and privacy

• Deny by default. Undeclared hosts are blocked and reported.
• The decision runs in process, with no network round trip.
• DNS answers are checked against the list, so a name cannot be rebound to a private range you did not declare. Redirects to undeclared hosts are refused.
• Raw sockets and other HTTP clients fail the check at build time.
• Free on every plan: an app protecting itself is never a paid action.

What Cloud adds

Your allowlist and its enforcement are free in your app. On Fleet, a security team enforces egress allowlists, approved providers and approved models across every app in the estate. Fleet can tighten your list, never loosen it. See free in-app and Cloud.

FAQ

Do I list Stripe, Resend and my database host? No. Drivers declare their own hosts. You list only your own destinations.

Does *.pinecart.dev allow pinecart.dev? No. Wildcards match subdomains only. List pinecart.dev separately if you call it.

Does this cover inbound traffic or CORS? No. network is outbound only. Secure headers, CSRF and CORS are inbound protection; rate limits are in rate limits and quotas.

Can I try it without breaking production? Yes. Set mode: observe and read the would-block decisions first.

List the destinations

network.destinations() returns every destination the app may reach: your allow list plus the hosts your drivers declare. It is what mainsdk info prints.

import { network } from "mainsdk";

const hosts = network.destinations();   // ["api.partner.com", "api.resend.com", ...]

Next

• Declare what your app uses: hosts, folders, facts and programs in one place.
• Local files and Server facts and programs: the server's own disk and programs, under the same permission model.
• Policy decisions: the network list compiles into policy you can explain.
• Secrets: keep the keys a poisoned dependency would try to send out.
• The check: what mainsdk check runs before merge.