Whitelist network access in Sage

Whitelist every external host

Put hosts the app may use on every Chia network under permissions.network.whitelist. This includes your own API, RPC services, WebSocket servers, analytics, third-party SDK endpoints, and remote images requested at runtime.

From Sage 0.13.1, approved image origins are also included in the image security policy. For example, an image at https://images.example.com/banner.png needs https://images.example.com in the effective whitelist. A blocked image may report an img-src error rather than connect-src.

Declare an origin, not a complete URL: scheme, host, and an optional port. Do not include a path, query, or fragment. If a request redirects to a different host, that destination also needs to be allowed.

{
  "permissions": {
    "network": {
      "whitelist": {
        "required": [
          "https://api.example.com",
          "wss://events.example.com"
        ]
      }
    }
  }
}

Use secure origins, with a local HTTP exception

Use https for secure HTTP requests such as fetch() and wss for secure WebSocket connections. From Sage 0.13.1, an app installed from localhost, 127.0.0.1, or ::1 may also declare http network entries. Publicly installed apps and ZIP installations cannot request HTTP access, even for a local backend. Plain ws entries remain unsupported.

Granting wss access also grants https access for the same host. If an app uses both a secure WebSocket and HTTPS endpoints on that domain, declare the wss origin rather than listing both. The host includes an explicit port when one is present, so different ports are separate targets.

• Use https://api.example.com for HTTPS only
• Use wss://api.example.com when the same host needs WSS and HTTPS
• Include :port when the service does not use its protocol’s default port
• Use http://localhost:3000 for a development backend only when the app itself is installed from a supported local URL

Scope services to the selected Chia network

Use permissions.network.whitelistByNetwork when a host should be reachable only while a particular Chia network is selected. Sage currently accepts the network IDs mainnet and testnet11.

The effective whitelist combines the shared whitelist entries with the entries for the active network. In the example below, status.example.com is always reachable, while only the matching mainnet or testnet API is reachable at one time.

{
  "permissions": {
    "network": {
      "whitelist": {
        "required": ["https://status.example.com"]
      },
      "whitelistByNetwork": {
        "mainnet": {
          "required": ["https://mainnet-api.example.com"]
        },
        "testnet11": {
          "required": ["https://testnet-api.example.com"]
        }
      }
    }
  }
}

Choose required or optional access

Both shared and network-specific whitelist buckets support required and optional. Use required when the app cannot provide its core experience without the host. Use optional when the app can open without it and request access only after the user chooses the related feature.

An optional network target must still be declared in the manifest before the running app can request it. When requesting a whitelistByNetwork entry, include its networkId so Sage grants it in the correct bucket.

{
  "permissions": {
    "network": {
      "whitelistByNetwork": {
        "mainnet": {
          "optional": ["https://quotes.example.com"]
        }
      }
    }
  }
}

Rebuild and test the effective policy

Finalize and reinstall or update the app after changing its source manifest. Sage builds the app’s network policy from the granted entries and the currently selected Chia network.

Changing the selected Chia network or the effective network grants forces the app to reload so Sage can rebuild that policy. Test on both mainnet and testnet11, confirm the intended shared and network-specific hosts work, and confirm an undeclared host is blocked.

A browser console error mentioning connect-src means the destination is missing from the effective whitelist or the installed app still has an older manifest.