Permissions and Secure Contexts

## Why the API vanished instead of failing Web platform features that expose the user's device, location, identity, or the ability to intercept a site's own network traffic are restricted to *secure contexts*. A secure context is not quite "a page served over HTTPS": it is a `Window` or a `WorkerGlobalScope` whose own origin is **potentially trustworthy** and whose entire chain of ancestor browsing contexts is potentially trustworthy as well. When the context is not secure, the browser does not attach the gated interface at all. `navigator.serviceWorker`, `navigator.clipboard`, `crypto.subtle` and `navigator.storage` are `undefined`, so the first symptom a developer sees is a language-level error such as `TypeError: Cannot read properties of undefined (reading 'writeText')`. That is a deliberate design: the feature is absent, not denied, so a feature-detection check naturally routes around it. A handful of older APIs predate the rule and keep their shape for compatibility. `navigator.geolocation` still exists on an insecure origin, but `getCurrentPosition()` invokes the error callback with a permission-denied error instead of prompting. So the same underlying rule produces two different-looking symptoms depending on the age of the API. ## What counts as potentially trustworthy The Secure Contexts specification defines the set. In practice: - Any origin whose scheme is `https:` or `wss:`. - Loopback hosts: `localhost` and `*.localhost`, the `127.0.0.0/8` IPv4 range, and `::1`. - `file:` URLs, though browsers differ on which APIs they actually enable there. - Browser-internal schemes a user agent registers as trustworthy, such as `chrome-extension:`. Just as important is what is *not* in the set. A private LAN address such as `http://192.168.1.10` or `http://10.0.0.5` is not trustworthy — it is reachable from other machines on the network, so there is a network attacker to defend against. Neither is an invented hostname like `http://staging.internal` or `http://myapp.local`, even if it only resolves inside a VPN. The browser has no way to know your intranet is friendly. ## Why localhost gets an exemption Traffic to a loopback address never leaves the machine, so no network position exists from which to tamper with it. Demanding a certificate for local development would be pure friction with no security gain, so the loopback exemption exists purely to keep the development loop cheap. The exemption is keyed on the **host**, not on "development mode". The classic trap follows directly: you test on your laptop at `http://localhost:3000`, then open the same dev server from your phone at `http://192.168.1.10:3000` and every gated feature disappears. Nothing about the code changed; the host did. ## The ancestor rule Secure-context status is inherited down the frame tree. An HTTPS document embedded in an iframe whose top-level page was loaded over plain HTTP is **not** a secure context, because an attacker who controls the outer page controls the inner one anyway. So an embedded widget can be served perfectly over HTTPS and still find its gated APIs missing — the embedder is the problem. ## Detecting it in code `window.isSecureContext` is a boolean available on both `Window` and `WorkerGlobalScope`. Use it for a clear diagnostic rather than letting a `TypeError` surface: ```js if (!window.isSecureContext) { console.warn('Insecure origin: clipboard, service workers and crypto.subtle are unavailable.'); } ``` For a specific feature, prefer detecting the feature itself, since secure context is a necessary but not sufficient condition — a browser may still lack the API, or a Permissions Policy may have disabled it: ```js if (navigator.clipboard?.writeText) { await navigator.clipboard.writeText(text); } else { showManualCopyFallback(text); } ``` ## Fixing the staging environment The only real fix is to make the origin trustworthy: issue a certificate for the staging hostname from a public CA or from an internal CA that the test machines already trust, and serve over HTTPS. Common shortcuts that developers reach for instead — a tunnelling service that gives you an HTTPS hostname, or forwarding the remote port to a local loopback port so the browser sees `http://localhost` — work because they change the origin the browser evaluates, not because they change the rule. What does not work is a polyfill. There is no user-land implementation of a service worker or of `crypto.subtle`'s primitives with the same guarantees, and the absence is the browser enforcing a security boundary rather than a gap in its feature set.