Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/engine-app-origin.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"e2e": patch
---

Engines receive the app's origin as `EngineAppInfo.origin` in `prepare` and `init`, on the run's port when `app.url` asks for a free one (and left out until the run assigns it), so an engine can scope a credential it injects to the exact origin.
7 changes: 7 additions & 0 deletions .changeset/web-credential-origins.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
"@e2e-dev/web": minor
---

**Breaking:** `web({ headers })` and `web({ basicAuth })` go only to the app's origin, the scheme, host, and port of `app.url`. Before, `headers` went to every host on the app's site (another port on the same host, sibling subdomains, every host under a shared domain such as `vercel.app`), and `basicAuth` answered a `401` from any origin, so a third-party origin the app embeds could collect the credential.

To migrate, list each other origin that needs the credentials in `credentialOrigins: ['https://api.example.com']`; it covers both. An app whose `app.url` redirects to another origin (`http:` to `https:`, the apex to `www`) needs the origin it lands on listed, or set `app.url` to it. `headers` still ride a request's own redirects to any origin, as before. WebKit can't scope basic auth to an origin on a default port or an IPv6 host, so there it still answers any origin. Update `e2e` with this release: the engine needs the app's origin from the runner.
9 changes: 6 additions & 3 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,9 +76,12 @@ elsewhere as one the agent may follow there, with the secrets the step was
given. If a threat model ever calls for an origin allowlist again, it comes
back as an opt-in.

Two things still key on the site of the target's `url`, its registrable
domain: the browser engine's `headers` reach the site and no other host, and
child frames off the site are dropped from observations.
Child frames off the site of the target's `url`, its registrable domain, are
dropped from observations. The browser engine's `headers` and `basicAuth`
are scoped tighter, to the exact origin of `url` plus the origins
`credentialOrigins` lists. `headers` stay on a request's redirects to any
origin, and WebKit answers a basic-auth challenge from any origin when an
allowed origin is on a default port or an IPv6 host.

## Telemetry and outbound traffic

Expand Down
6 changes: 3 additions & 3 deletions docs/migrate/playwright.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -68,8 +68,8 @@ A Playwright key such as `testDir`, `baseURL`, `use`, `webServer`, or
| --- | --- | --- |
| `use.viewport`, `use.browserName` | `web({ viewport, browser })` | renamed |
| `use.testIdAttribute` | `web({ testIdAttribute })` | renamed |
| `use.httpCredentials` | `web({ basicAuth })` | renamed |
| `use.extraHTTPHeaders` | `web({ headers })`, sent to the app's site only | renamed |
| `use.httpCredentials` | `web({ basicAuth })`, answered for the app's origin only; `credentialOrigins` adds more | renamed |
| `use.extraHTTPHeaders` | `web({ headers })`, sent on requests that start at the app's origin; `credentialOrigins` adds more | renamed |
| `chromium.connectOverCDP(url)` | `web({ connect: { cdpEndpoint: () => url } })`, chromium only | renamed |
| `use.connectOptions` (`wsEndpoint`) | `web({ connect })` attaches over CDP only | missing |
| `retries`, `workers`, `timeout` | the same names at the top level. `workers` takes an integer from 1 to 1024, not `'50%'`; `retries` stops at 10. The defaults differ, see [below](#defaults-that-differ) | renamed |
Expand Down Expand Up @@ -256,7 +256,7 @@ uses it declares `requires: ['browser']` and other targets skip it. Calls on
| --- | --- | --- |
| `page.route(pattern, handler)` | `browser.route(pattern, handler)`; a string or `RegExp` pattern, no predicate function; the handler decides exactly once. A string is a glob on the full URL, never resolved against `app.url`. `?` matches any one character on purpose, where Playwright reads it literally; `{a,b}` is literal, and `**/` needs at least one segment | web only |
| `route.fulfill({ json, body, path, status, headers, contentType })` | the same; one of `json`, `body`, or `path`, and `path` is relative to the project root. `body` is a string, `Buffer`, or `Uint8Array`, and a `\n`-joined `set-cookie` sets each cookie | web only |
| `route.continue({ url, method, headers, postData })`, `route.fallback()` | the same; a `url` resolves against `app.url` and keeps the request's `http` or `https` scheme. A header set to `undefined` is dropped; configured site headers still apply. `fallback()` takes no overrides | web only |
| `route.continue({ url, method, headers, postData })`, `route.fallback()` | the same; a `url` resolves against `app.url` and keeps the request's `http` or `https` scheme. A header set to `undefined` is dropped; configured headers still apply to an allowed origin. `fallback()` takes no overrides | web only |
| `route.fetch()` | argument-free: no `timeout`, `headers`, or `maxRedirects` options, and redirects return unfollowed; returns `{ url, status, headers, body(), text(), json() }` without deciding the route | web only |
| `route.abort(code)`, `route.fallback(overrides)` | none yet; `abort()` takes no error code | missing |
| `page.unroute()` | `browser.unroute()` | web only |
Expand Down
17 changes: 10 additions & 7 deletions docs/reference/config.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -382,8 +382,8 @@ url: 'http://localhost:3000',
- A missing scheme becomes `https://`, or `http://` for a loopback host.
- Plain HTTP is accepted for loopback hosts only.
- Port `0` on `127.0.0.1` or `[::1]` asks for a [free port](#free-ports).
- Its site scopes engine headers and observed frames: see
[the app's site](#the-apps-site).
- Its origin scopes engine request credentials, and its site scopes observed
frames: see [the app's site](#the-apps-site).

| Throws | When |
| --- | --- |
Expand Down Expand Up @@ -564,11 +564,14 @@ readyUrl: 'http://localhost:3000/health', // default: url
A test or the agent may open any http(s) URL, and `about:blank`. Every other
scheme (`file:`, `data:`, `javascript:`, `view-source:`, `blob:`) is
`POLICY_DENIED`. The site of `url` is its registrable domain:
`app.example.com` and `auth.example.com` are one site. It scopes two things:

- The browser engine's [`headers`](/reference/web#options) reach the site and
no other host.
- Child frames off the site stay out of observations.
`app.example.com` and `auth.example.com` are one site. Child frames off the
site stay out of observations.

The browser engine's [`headers`](/reference/web#headers) and
[`basicAuth`](/reference/web#basicauth) are scoped tighter, to the origin of
`url` (scheme, host, and port, the run's free port included) plus the
origins you list. See
[request credentials](/reference/security#request-credentials).

#### Free ports

Expand Down
28 changes: 18 additions & 10 deletions docs/reference/engine.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -729,7 +729,7 @@ export interface EngineInitInfo {
* `process.cwd()`, which an in-process run does not change.
*/
readonly projectRoot: string;
/** The app the target declares: the site policy of its URL, and what a device launches. */
/** The app the target declares: the origin and site policy of its URL, and what a device launches. */
readonly app: EngineAppInfo;
/**
* This worker's environment: the run's, plus what this target's `prepare`
Expand Down Expand Up @@ -1291,6 +1291,7 @@ the declaration to [`validateApp`](#validateapp) at config load.
| Target field | Reaches the engine as |
| --- | --- |
| `url` | `validateApp` only. The harness opens it through `session.open`. |
| the origin of `url`, on the run's port | `info.app.origin` in `prepare` and `init` |
| the site of `url` | `info.app.site` in `prepare` and `init` |
| `bundleId`, `appPath`, `launchArguments`, `permissions` | `validateApp`, and `info.app` in `prepare` and `init`, as the target declared them |
| `command`, `readyUrl` | Never. The runner starts the app. |
Expand Down Expand Up @@ -1342,26 +1343,33 @@ export type AppPermissionState = 'grant' | 'deny' | 'reset';
#### `EngineAppInfo`

The resolved app, as `EnginePrepareInfo.app` and `EngineInitInfo.app`: the
site of the URL and the device fields as the target declared them. Apply the
site to a URL with [`sameSite`](#site-helpers).
origin and site of the URL, and the device fields as the target declared
them. Scope a credential the engine injects to the exact origin. Apply the
site to observed frames with [`sameSite`](#site-helpers).

```ts
if (sameSite(request.url, info.app.site ?? '')) request.headers.set('x-api-key', key);
if (new URL(request.url).origin === info.app.origin) request.headers.set('x-api-key', key);
```

```ts
/**
* The app the harness resolved from the target's declaration, handed to
* `prepare` and `init`: the site policy for the decisions only a surface can
* make (which nested documents enter an observation, which requests carry
* injected credentials), and what a device launches.
* `prepare` and `init`: the origin and site policy for the decisions only a
* surface can make (which requests carry injected credentials, which nested
* documents enter an observation), and what a device launches.
*/
export interface EngineAppInfo {
/**
* The app URL's origin on the run's port (`scheme://host:port`, as
* `URL.origin` serializes it): where injected request credentials go.
* Absent when the app has no URL, and for a free port the run has not
* assigned (`e2e doctor`).
*/
readonly origin?: string;
/**
* The app URL's registrable domain, as read by `siteOf`. Use `sameSite`
* to scope secret fills, injected headers, and observed child frames.
* Absent when the app has no URL. The runner passes navigation URLs
* separately through `session.open`.
* to scope observed child frames. Absent when the app has no URL. The
* runner passes navigation URLs separately through `session.open`.
*/
readonly site?: string;
/** The installed app to launch, as the target declared it. */
Expand Down
45 changes: 35 additions & 10 deletions docs/reference/security.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@ lists the rules behind it, as the code enforces them.
| [Tool calls](#tool-calls) | Built-in and project tools, node ids |
| [Policy denials](#policy-denials) | Calls that fail with `POLICY_DENIED` |
| [Navigation](#navigation) | URL schemes per entry point |
| [Site check](#site-check) | Headers, child frames, `basicAuth` |
| [Request credentials](#request-credentials) | `headers`, `basicAuth` |
| [Site check](#site-check) | Child frames |
| [Secret fills](#secret-fills) | `type_secret`, `fill(secret)` |
| [Screenshots after a secret fill](#screenshots-after-a-secret-fill) | What masking covers |
| [Secrets in engine options](#secrets-in-engine-options) | `basicAuth` and other engine options |
Expand Down Expand Up @@ -100,18 +101,42 @@ There is no origin allowlist. The agent can follow the app to other sites
and use the step's secrets there.
</Warning>

### Request credentials

The browser engine scopes configured request credentials to exact origins:
the scheme, host, and port of `app.url`, plus the extras `credentialOrigins`
lists.

| Option | Goes to |
| --- | --- |
| `headers` | Every request that starts at an allowed origin |
| `basicAuth` | The answer to a `401` challenge from an allowed origin |

- Another port on the same host, a subdomain, and a sibling host under a
shared domain such as `vercel.app` are other origins. A request that
starts there carries no `headers`, and a `401` from there gets no answer,
except as the next bullets note.
- `headers` follow the origin a request starts on. A request to an allowed
origin keeps them through every redirect, to any origin. A request that
starts elsewhere gets none, even when it redirects to an allowed origin.
- `basicAuth` answers the origin that sends the `401`. A redirect to another
origin, such as `http:` to `https:` or the apex to `www`, gets no answer
unless you list the origin it lands on.
- On WebKit, `basicAuth` answers a `401` from any origin when an allowed
origin is on its scheme's default port (`https://staging.example.com`) or
has an IPv6 host. WebKit can't scope a credential to such an origin.
- An extra is an `http:` or `https:` origin with no path, query, or
fragment, such as `https://api.example.com`. Anything else, a `*` in the
host, and port `0` are `INVALID_CONFIG` at config load.

### Site check

The browser engine compares hostnames to decide what counts as the target's
site.

- Configured `headers` go only on requests to the target's site.
- Observations leave out child frames from other sites, and `data:` frames.
- The check approximates the registrable domain without a public suffix
list. A shared hosting domain such as `vercel.app` counts as one site, so
headers can reach other hosts under it.
- `basicAuth` ignores the site check. It answers a `401` challenge from any
origin.
site. Observations leave out child frames from other sites, and `data:`
frames.

The check approximates the registrable domain without a public suffix list.
A shared hosting domain such as `vercel.app` counts as one site.

### Secret fills

Expand Down
67 changes: 54 additions & 13 deletions docs/reference/web.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ web({ viewport: { width: 390, height: 844 }, locale: 'de-DE' });
| [`connect`](#connect) | `WebConnectOptions` | launches locally |
| [`headers`](#headers) | `Record<string, string>` | - |
| [`basicAuth`](#basicauth) | `WebBasicAuth` | - |
| [`credentialOrigins`](#credentialorigins) | `string[]` | - |
| [`testIdAttribute`](#testidattribute) | `string` | `'data-testid'` |
| [`userAgent`](#useragent) | `string` | the browser's own |
| [`locale`](#locale) | `string` | the browser's own |
Expand Down Expand Up @@ -240,15 +241,20 @@ session state capture and restore. `app.clearState` fails with

#### `headers`

Headers added to requests within the app's site, including subdomains.
Headers added to every request that starts at the app's origin: the scheme,
host, and port of `app.url`. A request that starts at another port, a
subdomain, or any other host gets none. A redirect keeps the headers its
request started with, to any origin.

```ts
web({ headers: { 'x-preview-token': process.env.PREVIEW_TOKEN ?? '' } });
```

- A [continued](#route) request bound for the app's site still carries them.
- A [continued](#route) request bound for an allowed origin still carries
them.
- `headers` and `basicAuth` are how a test reaches a
[protected preview](/web#protected-previews).
- See [request credentials](/reference/security#request-credentials).

| Throws | When |
| --- | --- |
Expand All @@ -261,8 +267,9 @@ blocks service workers.

#### `basicAuth`

HTTP basic authentication. The browser answers a `401` challenge with these
credentials on any origin, matching Playwright's `httpCredentials`.
HTTP basic authentication. The browser answers a `401` challenge from the
app's origin with these credentials. A challenge from any other origin goes
unanswered unless [`credentialOrigins`](#credentialorigins) lists it.

```ts
import { secrets } from 'e2e';
Expand All @@ -275,7 +282,7 @@ redacted like any configured secret. So is the base64 credential of the
`Authorization` header it becomes.

```ts
/** HTTP basic authentication the browser answers a `401` challenge with. */
/** HTTP basic authentication the browser answers a `401` challenge from the app's origin with. */
export interface WebBasicAuth {
/** The user name; `:` is not allowed in one (RFC 7617). */
readonly username: string;
Expand All @@ -288,12 +295,38 @@ export interface WebBasicAuth {
| --- | --- |
| `INVALID_CONFIG` | A `:` in the user name, or an unknown key. |

<Note>
WebKit can't scope a credential to an origin on its scheme's default port
(`https://staging.example.com`) or with an IPv6 host. When the app's origin
or one in `credentialOrigins` is such an origin, WebKit answers a `401` from
any origin, as Playwright does by default.
</Note>

<Warning>
The secret protection is text only. A page that renders the password on
screen is not masked in screenshots or model pixels
([Security rules](/reference/security#secrets-in-engine-options)).
</Warning>

#### `credentialOrigins`

More origins that receive [`headers`](#headers) and
[`basicAuth`](#basicauth), beyond the app's own, such as an API on another
host behind the same gate.

```ts
web({
headers: { 'x-preview-token': process.env.PREVIEW_TOKEN ?? '' },
credentialOrigins: ['https://api.staging.example.com'],
});
```

List each origin exactly. A `*` in the host and port `0` match no request.

| Throws | When |
| --- | --- |
| `INVALID_CONFIG` | No `headers` or `basicAuth`, an entry that is not an `http:` or `https:` origin with no path, query, or fragment, a `*` in the host, or port `0`. |

#### `testIdAttribute`

The attribute that carries an element's test id: what the `testId` query
Expand Down Expand Up @@ -616,7 +649,8 @@ await browser.route('**/api/quote', async (route) => {
```

`route.fetch()` returns the upstream `{ url, status, headers, body(), text(), json() }`
with the site's headers, under the action timeout, without deciding the route.
with the configured headers when its origin gets them, under the action
timeout, without deciding the route.
It does not follow redirects, which could take it past the navigation rule.

- The pattern is a string or a `RegExp`, both tested against the full URL. In
Expand Down Expand Up @@ -672,7 +706,7 @@ export interface RouteContinueOverrides {
url?: string;
/** Request method. */
method?: string;
/** Replaces every request header; `undefined` drops one, and the configured `headers` for the app's site are added on top. */
/** Replaces every request header; `undefined` drops one, and the configured `headers` for an allowed origin are added on top. */
headers?: Record<string, string | undefined>;
/** Request body. */
postData?: string;
Expand Down Expand Up @@ -715,7 +749,7 @@ await browser.unroute('**/api/quote');
#### `unrouteAll`

Removes every route registered by the browser fixture, preserving configured
site headers.
headers.

```ts
await browser.unrouteAll();
Expand Down Expand Up @@ -1079,18 +1113,25 @@ export interface WebOptions {
*/
readonly connect?: WebConnectOptions;
/**
* Headers added to requests within the app's site, including subdomains.
* Useful for preview-protection tokens. Other sites never receive them.
* Headers added to every request that starts at the app's origin (the
* scheme, host, and port of `app.url`) or one in `credentialOrigins`.
* Useful for preview-protection tokens. A request that starts at another
* origin goes without them; a redirect keeps them, to any origin.
* Names are case-insensitive and replace existing headers of the same name.
* This enables request routing, disables the browser's HTTP cache, and
* blocks service workers.
*/
readonly headers?: Readonly<Record<string, string>>;
/**
* HTTP basic authentication. The browser answers a `401` challenge with
* these credentials on any origin, matching Playwright's `httpCredentials`.
* HTTP basic authentication. The browser answers a `401` challenge from the
* app's origin, or one in `credentialOrigins`, with these credentials.
*/
readonly basicAuth?: WebBasicAuth;
/**
* More origins that receive `headers` and `basicAuth`, such as
* `https://api.example.com`; requires `headers` or `basicAuth`.
*/
readonly credentialOrigins?: readonly string[];
/**
* The attribute that carries an element's test id: what the `testId` query
* (`screen.getByTestId`) resolves and what `SemanticNode.testId` reports.
Expand Down Expand Up @@ -1183,7 +1224,7 @@ export interface Browser extends Expectable<BrowserExpectation> {
): Promise<void>;
/** Removes matching attempt-scoped routes. */
unroute(pattern: string | RegExp): Promise<void>;
/** Removes all routes registered by this browser fixture, preserving configured site headers. */
/** Removes all routes registered by this browser fixture, preserving the configured headers. */
unrouteAll(): Promise<void>;
/** Waits for a matching response. */
waitForResponse(
Expand Down
Loading
Loading