vos.net — Network

Why a proxy

VibeOS injects a strict Content-Security-Policy built from your declared origins, so a plain fetch(), XMLHttpRequest or WebSocket to anywhere else is blocked by the browser before it leaves the window. Even for allowed origins, most public APIs would then fail CORS.

• No CORS. The request is made server-side, so APIs without CORS headers work normally.
• Re-validated host-side. The allow-list is checked against the installed grant on every call — an app cannot widen its own reach at runtime.
• Hardened. Private networks are unreachable and unsafe headers are stripped in both directions.

Declaring origins

List each https:// origin — optionally with a path prefix — in permissions.network. An entry matches any URL on the same origin whose path begins with the given prefix.

{
  "permissions": {
    "network": [
      "https://api.openlibrary.org/",
      "https://covers.openlibrary.org/"
    ]
  }
}

• Wildcard hostnames and credentials in the URL are rejected.
• "network": [] declares the capability with no targets — every request is blocked. Omit the key entirely if your app is offline.
• Users approve the list at install time and can revoke individual origins later from Web Apps → app details → Permissions, so handle a permission failure gracefully at any time.

net.fetch

fetch(
  url: string,
  init?: { method?: string; headers?: Record<string, string>; body?: string },
): Promise<{
  status: number;
  statusText: string;
  headers: Record<string, string>;
  body?: string;        // text responses
  bodyBase64?: string;  // binary responses
}>

{
  status: 200,
  statusText: "OK",
  headers: { "content-type": "application/json; charset=utf-8" },
  body: "{\"docs\":[...]}"     // text responses
  // bodyBase64: "iVBORw0K..."  // binary responses instead of body
}

Examples

Fetch JSON

const res = await window.vos.net.fetch(
  "https://api.openlibrary.org/search.json?q=tolkien",
  { method: "GET", headers: { Accept: "application/json" } },
);

if (res.status >= 200 && res.status < 300) {
  const data = JSON.parse(res.body);
  render(data.docs.slice(0, 10));
} else {
  setStatus("Request failed with status " + res.status);
}

Send JSON

const res = await window.vos.net.fetch("https://api.example.com/v1/items", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ title: "New item" }),
});

// The proxy never throws on a non-2xx response — check the status yourself.
if (res.status === 201) setStatus("Created");

A fetch-like helper

Wrap the call once so the rest of your app reads like ordinary code.

// A small wrapper that behaves like the fetch you already know.
async function apiGet(url) {
  const res = await window.vos.net.fetch(url, {
    headers: { Accept: "application/json" },
  });
  if (res.status < 200 || res.status >= 300) {
    throw new Error("HTTP " + res.status + " " + res.statusText);
  }
  return JSON.parse(res.body);
}

Binary responses

The host decides text versus binary from the response content type. Binary bodies arrive as bodyBase64 instead of body — turn them into a data URI to display them, since the CSP blocks loading remote images directly.

const res = await window.vos.net.fetch("https://covers.openlibrary.org/b/id/240727-L.jpg");

if (res.bodyBase64) {
  const type = res.headers["content-type"] || "image/jpeg";
  img.src = "data:" + type + ";base64," + res.bodyBase64;
}

Limits & blocked hosts

Requests to private and internal networks are refused outright, whatever your manifest says: localhost, *.local, *.internal, loopback and link-local addresses, IPv6 link-local and unique-local ranges, and the private IPv4 blocks 10.x, 127.x, 169.254.x, 172.16–31.x, 192.168.x and multicast.

Failure modes