Developer policy and security guidelines

Simon Hangl

Demián Renzulli

Isolated Web Apps (IWAs) provide a security model that allows web applications to access powerful capabilities—such as Direct Sockets and Controlled Frame—that are typically restricted in the standard "drive-by" web. Because IWAs operate in a high-trust environment, they must adhere to strict security and privacy policies. These guidelines are designed to ensure that as the web platform gains more power, users remain safe, and the integrity of the browser environment is maintained.

The IWA trust model

The core of the IWA platform is built around strict technical policies that force developers to maintain a high level of security. While standard web apps rely on a flexible permission model, IWAs are cryptographically signed and delivered using Web Bundles, which allows for the verification of their origin and integrity.

In exchange for this verified identity, IWAs gain access to privileged APIs. To maintain this trust, developers must follow a security-first approach by adhering to stricter policies—including robust Content Security Policy (CSP) and Trusted Types—that ensure user safety even when using powerful capabilities. This means:

• Transparency: Users should never be surprised by an application's use of privileged APIs.
• Least Privilege: Apps should only request and use the specific capabilities required for their stated purpose.
• Static Integrity: All executable logic must be self-contained within the app package to allow for security auditing and to prevent sideloading of malicious code.

While IWAs include robust built-in protections—such as a strict Content Security Policy (CSP) that prevents the execution of external scripts—technical constraints alone cannot mitigate every risk. Even within a high-trust environment, certain implementation patterns or developer choices can inadvertently compromise user safety or privacy. This guide outlines these restricted scenarios and the policies governing the use of privileged APIs.

Why these guidelines matter

Adhering to these policies is not just about compliance—it's about building a sustainable ecosystem for advanced web applications. By following these guidelines, you ensure that your application:

• Avoids security regressions: Prevents vulnerabilities like Cross-Site Scripting (XSS) and remote code execution by keeping logic self-contained.
• Protects user privacy: Ensures sensitive data and hardware access are handled only with explicit user intent and transparency.
• Ensures platform longevity: Helps maintain the high security standards required for the IWA platform to continue expanding its capability set.

Core principles

Transparency and user intent

The most fundamental rule is: don't surprise the user. Your application's behavior must align with its stated purpose and user expectations.

• Stay within scope: Do not implement functionality that extends beyond the clear purpose of your application.
• Minimal API footprint: Only request and use the specific set of IWA APIs necessary to achieve your app's core function.

No dynamic code sideloading

The IWA security model depends on the ability for administrators or the browser vendor to verify all executable logic. Consequently, your IWA package must be self-contained. The platform enforces this through a strict Content Security Policy (CSP) that blocks string-based execution like eval() and new Function():

script-src 'self' 'wasm-unsafe-eval';
require-trusted-types-for 'script';

While the CSP allows 'wasm-unsafe-eval' to support WebAssembly, you must not bypass the spirit of this security boundary.

Strictly forbidden practices

• Shipping interpreters for remote code: You may not include a code interpreter (for example, Python or Lua compiled to WASM) to download and execute external scripts using privileged network access like Direct Sockets.
• Remotely loaded logic: Do not use service workers to embed remotely loaded code into the IWA origin.
• Code versus data: While downloading data (such as JSON) is permitted, downloading any code intended to be interpreted or run is a direct policy violation.

The principle of least privilege

Always use the least powerful API capable of accomplishing a task. Privileged IWA-specific APIs should never be used as a shortcut to bypass the security constraints or user prompts of standard Web APIs. The following table outlines common use cases to help you decide when to use traditional Web APIs versus IWA-specific capabilities:

API-specific guidelines

IWA APIs provide powerful capabilities that are typically restricted in the browser. The general guidance is to never use these privileged features in a way that would surprise users or compromise their trust and data.

Direct Sockets API

The Direct Sockets API grants raw TCP and UDP access, including multicast and local network access.

Allowed

• Supporting custom protocols: Connecting to remote servers that use custom protocols for which no higher-level Web API currently exists.
• Maintaining backend services: Connecting to a predefined, hard-coded server used specifically for your application's backend services.
• Discovering essential hardware: Accessing the local network or using multicast to discover specific, related hardware essential to the app's function (for example, a video-editing app locating network-attached storage).

Not allowed

• Surprising the user: Implementing network access that is not clearly justified by the app's primary functionality, such as a text editor communicating with local network devices.
• Scanning networks arbitrarily: Performing broad scans of the user's local network (for example, port-scanning 192.168.1.0/24) to profile the user or discover unrelated devices.
• Targeting local devices: Attempting to probe, reconfigure, or attack other devices on the local network is strictly forbidden.

Controlled Frame API

The <controlledframe> element allows for embedding and modification of cross-origin content, including script injection and header alteration.

Allowed

• Streamlining user interfaces: Embedding a third-party service and injecting CSS to hide irrelevant UI elements or provide a more cohesive experience.
• Mediating secure communication: Acting as a gatekeeper by receiving requests from the embedded page with postMessage and returning only sanitized, necessary data fetched through privileged APIs.

Not allowed

• Stealing user credentials: Injecting scripts to capture passwords, session cookies, or other sensitive user data from the embedded content.
• Violating service terms: Altering embedded platforms in ways that violate their Terms of Service, such as programmatic ad-clicking or unauthorized scraping.
• Proxying privileged access: Creating a pass-through that gives untrusted, embedded content direct or uncontrolled access to a privileged IWA API.
• Implementing uncontrolled AI: Performing actions on behalf of a logged-in user through AI without specific, transparent use-case constraints.

Unrestricted screen recording

Allows for screen capture without the repeated user permission prompts found in the standard web.

Allowed

• Providing core functionality: Using screen capture as an obvious part of the app's service, such as in virtual meeting or tutorial recording features.
• Ensuring user awareness: Informing users clearly that recording may occur before they engage with the application.

Not allowed

• Recording surreptitiously: Capturing the user's screen without their explicit, upfront knowledge and consent.
• Violating privacy regulations: Engaging in any recording practices that breach local or international privacy laws.

Unrestricted WebUSB

Unrestricted WebUSB bypasses the standard WebUSB blocklist to allow for low-level interaction with devices.

Allowed

• Supporting proprietary hardware: Interacting with specialized or legacy hardware for which no high-level web API exists, such as industrial controllers.

Now allowed

• Bypassing dedicated APIs: Using WebUSB for devices that have a more specific, constrained API, such as smart cards (use Smart Card API) or external storage (use File System Access API).

Window management (window.open and window.focus)

IWAs can create popups and focus windows without the user gesture required by the standard web.

Allowed

• Notifying task completion: Focusing the app window when a critical, user-initiated background task, such as a video render, is finished.

Not allowed

• Spamming: Bombarding the user with multiple unsolicited windows.
• Phishing: Opening windows designed to mimic system dialogs or trick the user.
• Focus-stealing: Disrupting the user by stealing focus from other applications for non-critical events.

Conclusion

The security architecture of Isolated Web Apps is designed to empower developers while maintaining a high-trust environment for users. By adhering to these guidelines, you ensure your application remains a responsible citizen of the IWA ecosystem. The most important takeaways from this guide include:

• Prioritize Transparency: Your application's behavior should always align with its stated purpose; never implement functionality that would surprise or betray the user.
• Enforce Package Integrity: All executable logic must be self-contained within your IWA bundle to allow for static verification. Bypassing the security model through dynamic code sideloading or remote interpreters is strictly prohibited.
• Adhere to Least Privilege: Always select the most constrained API available for a given task. Privileged IWA APIs should only be used when standard Web APIs are insufficient for the application's core functionality.
• Act as a Gatekeeper: When using powerful tools like <controlledframe>, your IWA must act as a secure mediator rather than a transparent proxy for untrusted content.

Before publishing your IWA, perform a final audit of your implementation by asking:

1. Am I using the simplest, most-constrained API possible for this task?
2. Would a user be surprised or feel betrayed by what my app is doing?

If the answer to the first question is "No" or the second is "Yes" your application is likely in violation of the IWA security policies and may be subject to removal.