[jplhomer]

Important

Needs server support before release. The platform rejects unknown keys in a theme app extension's deploy config today, so deploying an extension that declares [extensions.capabilities.network_access] fails until the server accepts capabilities.network_access.allowed_sources. Extensions that don't declare it send the same payload as before and aren't affected.

WHY are these changes introduced?

Theme app extensions load scripts and make requests on storefronts, but there's no way for them to say which origins they contact. Declaring them lets the platform build a storefront Content Security Policy for each extension, starting in report-only mode. Undeclared origins may be reported now and blocked later.

UI extensions (checkout, customer accounts) already use a boolean capabilities.network_access. They run sandboxed, so they keep the boolean. Theme app extensions use the same key as a table.

WHAT is this pull request doing?

Theme app extensions can declare the origins they contact in shopify.extension.toml:

[[extensions]]
type = "theme"
name = "My theme app extension"
handle = "my-theme-app-extension"

[extensions.capabilities.network_access]
allowed_sources = ["https://api.example.com", "https://*.cdn.example.com"]

• Theme-only schema. The theme specification gets its own capabilities schema in which network_access is a table with allowed_sources. The shared CapabilitiesSchema and UI dev payload remain unchanged. Extension model and factory generics use a common configuration constraint without capabilities, so each extension schema defines its own capability types without casting ThemeSchema. Their default configuration type remains BaseConfigType.
• Deploy config. The theme deployConfig adds capabilities: {network_access: {allowed_sources: [...]}} next to theme_extension only when the table is declared. Otherwise the payload stays {theme_extension: {files: {}}}, byte for byte.

Validation rules (each entry in allowed_sources):

• https:// only, with a host and an optional port. No path, query, fragment or credentials, so http://, scheme-less values, CSP keywords like 'self', and * are rejected.
• The host needs at least two labels made of letters, digits and hyphens (localhost is rejected). Labels can't start or end with a hyphen, and the host is at most 253 characters. URL parsing rejects invalid hosts, and an IP check rejects IP addresses after URL normalization, including hexadecimal forms. The same checks apply to wildcard base hosts.
• Only a leading *. wildcard is allowed, and it must cover at least two labels (https://*.cdn.example.com is fine, but https://*.com and https://api.*.example.com aren't). CSP host sources support this form, and extensions often load from CDN subdomains.
• Ports must be 1–65535. The default :443 is dropped, and other ports are kept.
• Entries are trimmed and lowercased (hosts are case-insensitive), a trailing / is dropped, and duplicates are removed after normalization. The normalized list is what gets deployed.
• Up to 20 origins (counted after duplicates are removed). This keeps the generated policy header small. It's a constant, so raising it later is cheap.
• One error lists every invalid entry, with an example of a valid one.

Omitted vs. empty:

TOML	Meaning	Sent on deploy
No [extensions.capabilities.network_access] table	Not declared. The extension's requests may be reported as undeclared.	Nothing (payload unchanged)
allowed_sources = []	Declared: the extension contacts no other origins	allowed_sources: []
Table without allowed_sources	Error: allowed_sources is required. Use an empty list if your extension contacts no other origins.	n/a
network_access = true / false (the UI extension boolean)	Error: theme app extensions require a table with an allowed_sources list. UI extensions still accept booleans.	n/a

app dev needs no separate change: dev sessions build the app manifest from the same deployConfig, so declared sources reach the server there too, and are subject to the same server-support caveat.

There's no generated JSON schema or docs for extension TOML in this repo. The field should be documented in the theme app extension configuration docs once the server supports it.

Tests (packages/app):

• pnpm vitest run src/cli/models/extensions/specifications/theme.test.ts: 46 tests pass. They cover valid origins and normalization, empty and omitted lists, rejected theme booleans, missing allowed_sources, wrong types, HTTP, paths, queries, fragments, credentials, wildcard placement, invalid hosts, decimal and hexadecimal IPs, ports, CSP keywords and injection, the 20-origin limit, deploy payloads, and UI extensions retaining boolean support.
• loader.test.ts: new test that loads a theme extension TOML with the table and checks the deploy config.
• Related suites: src/cli/models/extensions/, dev/extension/payload, app/loader, app/app and utilities/extensions/theme: 36 files, 664 tests pass.
• pnpm tsc --noEmit, pnpm eslint on changed files and prettier --check: clean.

How to manually test your changes?

1. Add the TOML above to a theme app extension and run shopify app build or shopify app deploy. The config loads, and the deploy payload includes the normalized allowed_sources. Deploy succeeds only once the server supports the field.
2. Change an entry to http://api.example.com or https://api.example.com/path. Loading fails with the invalid-entry error.
3. Remove the table. The deploy payload is {"theme_extension":{"files":{}}} as before.

Post-release steps

Document [extensions.capabilities.network_access] allowed_sources for theme app extensions once the server supports it.

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes
• I've considered analytics changes to measure impact
• The change is user-facing — I've identified the correct bump type (patch for bug fixes · minor for new features · major for breaking changes) and added a changeset with pnpm changeset add

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

[pt2pham]

I didn't give this a tophat but the proposed changes make sense to me to just include this as a field for theme extensions

[jplhomer]

/snapit

[github-actions]

🫰✨ Thanks @jplhomer! Your snapshot has been published to npm.

Built from a337cb92258dfa955c8ad9f3e3fb03c26afdcbc0. Workflow run.

Test the snapshot by installing your package globally:

pnpm i -g --@shopify:registry=https://registry.npmjs.org @shopify/cli@0.0.0-snapshot-20261025175303

Caution

After installing, validate the version by running shopify version in your terminal.
If the versions don't match, you might have multiple global instances installed.
Use which shopify to find out which one you are running and uninstall it.

[isaacroldan]

why extend CapabilitiesSchema if you are going to only need network_access and not even with the same type?.

Isn't it easier to just define ThemeCapabilitiesSchema without extending anything? it should simplify everything.

[isaacroldan]

(i went ahead and pushed a commit with this)

[isaacroldan]

The IP-validation fix is now separate from the schema changes.

---

🤖 Generated by the review-pr skill

[isaacroldan]

Fixed in 652c7903c7. The previous decimal-only last-label check accepted https://127.0.0x1 and https://0x7f.0x1. URL parsing converts both to https://127.0.0.1, so checking only the input spelling missed these IP addresses.

The isolated commit parses the hostname with safeParseURL and checks the normalized hostname with isIP. It also checks wildcard base hosts and rejects invalid URL hosts. Regression tests cover these cases.

---

🤖 Generated by the review-pr skill