Skip to content

fix: serve the PWA offline stub as same-origin frameable - #25504

Merged
mcollovati merged 3 commits into
mainfrom
issues/25492-offline-stub-frame-options
Sep 8, 2026
Merged

mcollovati merged 3 commits into
mainfrom
issues/25492-offline-stub-frame-options

Conversation

@mcollovati

@mcollovati mcollovati commented Sep 7, 2026 •

Copy link
Copy Markdown
Collaborator

The Flow client renders the offline page inside a same-origin iframe pointing at offline-stub.html. What the browser gets for that navigation comes from the service worker, which replays the headers the origin server sent — including the X-Frame-Options: DENY that Spring Security, a servlet filter, a reverse proxy or a CDN adds to every response. The browser then refuses to render the stub and shows its own error page, so the offline page is never seen.

The service worker now rebuilds the response for the offline stub so that the same origin is allowed to frame it: X-Frame-Options becomes SAMEORIGIN, and 'self' is added to the source list of a frame-ancestors directive. Directive names are case-insensitive, so the directive is recognized however the deployment spells it.

The same origin is added to the source list rather than replacing it, which keeps the ancestors a deployment allows for the application itself. An application embedded in a partner portal sends frame-ancestors 'self' https://portal.example.com, and the directive is matched against every ancestor of the stub, so replacing the list would block the stub the same way the header it replaced did. A frame-ancestors 'none' gives way to 'self', being valid only as the single source of a list.

Scoping the rewrite to that single path leaves the app shell's own protection untouched. Both the pre-cached and the network response are rewritten, so the stub also renders when the server is reachable but the Flow client fails to start.

Fixes #25492

The Flow client renders the offline page inside a same-origin iframe
pointing at offline-stub.html. What the browser gets for that navigation
comes from the service worker, which replays the headers the origin
server sent — including the X-Frame-Options: DENY that Spring Security,
a servlet filter, a reverse proxy or a CDN adds to every response. The
browser then refuses to render the stub and shows its own error page, so
the offline page is never seen.

The service worker now rebuilds the response for the offline stub with
framing restricted to the same origin: X-Frame-Options becomes
SAMEORIGIN and a frame-ancestors directive becomes
frame-ancestors 'self'. Downgrading the headers rather than removing
them keeps a third party page from framing the stub, and scoping the
rewrite to that single path leaves the app shell's own protection
untouched. Both the pre-cached and the network response are rewritten,
so the stub also renders when the server is reachable but the Flow
client fails to start.

Fixes #25492
@github-actions

github-actions Bot commented Sep 7, 2026

Copy link
Copy Markdown
Contributor

The offline-stub response now passes through a header-downgrading step before the iframe renders it

flowchart LR
    subgraph Before
        direction TB
        B1["iframe to offline-stub.html"] -->|navigates| B2["NavigationRoute handler"]
        B2 -->|serves from cache| B3["precached response"]
        B3 -->|replays origin DENY header| B4["returned unchanged"]
        B4 -->|framing denied| B5["browser error page"]
    end
    subgraph After
        direction TB
        A1["iframe to offline-stub.html"] -->|navigates| A2["NavigationRoute handler"]
        A2 -->|serveNavigationRequest| A3["cache or network response"]
        A3 -->|only for offline-stub path| A4["allowSameOriginFraming (new)"]
        A4 -->|downgrades to SAMEORIGIN| A5["returned frameable"]
        A5 -->|framing allowed| A6["browser renders stub"]
    end
    Before ~~~ After
    A4:::changed
    classDef changed stroke:#c9a227,stroke-width:3px
Loading

The NavigationRoute handler in sw.ts builds the offline-stub response from the workbox precache (or network), which replays the origin server's X-Frame-Options: DENY, so the browser refuses to render it in the same-origin iframe. Per the PR description and #25492, the handler now routes that one path — context.url.pathname === offlineStubPath — through the new allowSameOriginFraming(), which rewrites X-Frame-Options to SAMEORIGIN and any CSP frame-ancestors to 'self' before returning. Scoping the rewrite to the stub path leaves the app shell's own protection untouched.

Diagram Bot draws the mechanism this pull request touches; it does not review the change. Verify it against the diff.

Generated by Diagram Bot for issue #25504 · ◷

@github-actions github-actions Bot added the +0.0.1 label Sep 7, 2026
@github-actions

github-actions Bot commented Sep 7, 2026 •

Copy link
Copy Markdown
Contributor

Test Results

 1 436 files  ±0   1 520 suites  ±0   1h 35m 11s ⏱️ -3s
11 912 tests +4  11 844 ✅ +4  68 💤 ±0  0 ❌ ±0 
12 230 runs  +4  12 162 ✅ +4  68 💤 ±0  0 ❌ ±0 

Results for commit ad4fe73. ± Comparison against base commit b07b661.

♻️ This comment has been updated with latest results.

Replacing the frame-ancestors directive of the offline stub with
frame-ancestors 'self' dropped every other origin a deployment allows.
An application embedded in a partner portal sends frame-ancestors
'self' https://portal.example.com, and the directive is matched against
every ancestor of the stub, so the portal stopped matching and the
browser blocked the stub — the very failure the rewrite is there to
prevent. The same origin is now added to the source list instead of
replacing it, and 'none' gives way to it, being valid only as the
single source of a list.

A frame-ancestors directive is also recognized however the deployment
spells it. Directive names are case-insensitive, but the guard that
returned the response untouched looked for a lower-case
frame-ancestors while the rewrite matched case-insensitively, so a
policy sending Frame-Ancestors 'none' took the early return and the
stub stayed blocked. The rewritten policy is now computed first, and
the response is served as it is only when that policy comes back
identical to the original one.

DenyFramingFilter picks the header that denies framing from a cookie,
so that ServiceWorkerIT covers a deployment denying framing with a
content security policy alongside one sending X-Frame-Options.
@sonarqubecloud

sonarqubecloud Bot commented Sep 8, 2026

Copy link
Copy Markdown

@mcollovati
mcollovati added this pull request to the merge queue Sep 8, 2026
Merged via the queue into main with commit bf9a04e Sep 8, 2026
36 checks passed
@mcollovati
mcollovati deleted the issues/25492-offline-stub-frame-options branch September 8, 2026 08:34
vaadin-bot added a commit that referenced this pull request Sep 8, 2026
…: 25.2) (#25531)

This PR cherry-picks changes from the original PR #25504 to branch 25.2.
---
#### Original PR description
> The Flow client renders the offline page inside a same-origin iframe
pointing at offline-stub.html. What the browser gets for that navigation
comes from the service worker, which replays the headers the origin
server sent — including the X-Frame-Options: DENY that Spring Security,
a servlet filter, a reverse proxy or a CDN adds to every response. The
browser then refuses to render the stub and shows its own error page, so
the offline page is never seen.
> 
> The service worker now rebuilds the response for the offline stub so
that the same origin is allowed to frame it: X-Frame-Options becomes
SAMEORIGIN, and 'self' is added to the source list of a frame-ancestors
directive. Directive names are case-insensitive, so the directive is
recognized however the deployment spells it.
> 
> The same origin is added to the source list rather than replacing it,
which keeps the ancestors a deployment allows for the application
itself. An application embedded in a partner portal sends
frame-ancestors 'self' https://portal.example.com, and the directive is
matched against every ancestor of the stub, so replacing the list would
block the stub the same way the header it replaced did. A
frame-ancestors 'none' gives way to 'self', being valid only as the
single source of a list.
> 
> Scoping the rewrite to that single path leaves the app shell's own
protection untouched. Both the pre-cached and the network response are
rewritten, so the stub also renders when the server is reachable but the
Flow client fails to start.
> 
> Fixes #25492
>

Co-authored-by: Marco Collovati <marco@vaadin.com>
vaadin-bot added a commit that referenced this pull request Sep 8, 2026
…: 25.3) (#25530)

This PR cherry-picks changes from the original PR #25504 to branch 25.3.
---
#### Original PR description
> The Flow client renders the offline page inside a same-origin iframe
pointing at offline-stub.html. What the browser gets for that navigation
comes from the service worker, which replays the headers the origin
server sent — including the X-Frame-Options: DENY that Spring Security,
a servlet filter, a reverse proxy or a CDN adds to every response. The
browser then refuses to render the stub and shows its own error page, so
the offline page is never seen.
> 
> The service worker now rebuilds the response for the offline stub so
that the same origin is allowed to frame it: X-Frame-Options becomes
SAMEORIGIN, and 'self' is added to the source list of a frame-ancestors
directive. Directive names are case-insensitive, so the directive is
recognized however the deployment spells it.
> 
> The same origin is added to the source list rather than replacing it,
which keeps the ancestors a deployment allows for the application
itself. An application embedded in a partner portal sends
frame-ancestors 'self' https://portal.example.com, and the directive is
matched against every ancestor of the stub, so replacing the list would
block the stub the same way the header it replaced did. A
frame-ancestors 'none' gives way to 'self', being valid only as the
single source of a list.
> 
> Scoping the rewrite to that single path leaves the app shell's own
protection untouched. Both the pre-cached and the network response are
rewritten, so the stub also renders when the server is reachable but the
Flow client fails to start.
> 
> Fixes #25492
>

Co-authored-by: Marco Collovati <marco@vaadin.com>
vaadin-bot added a commit that referenced this pull request Sep 8, 2026
…: 25.1) (#25532)

This PR cherry-picks changes from the original PR #25504 to branch 25.1.
---
#### Original PR description
> The Flow client renders the offline page inside a same-origin iframe
pointing at offline-stub.html. What the browser gets for that navigation
comes from the service worker, which replays the headers the origin
server sent — including the X-Frame-Options: DENY that Spring Security,
a servlet filter, a reverse proxy or a CDN adds to every response. The
browser then refuses to render the stub and shows its own error page, so
the offline page is never seen.
> 
> The service worker now rebuilds the response for the offline stub so
that the same origin is allowed to frame it: X-Frame-Options becomes
SAMEORIGIN, and 'self' is added to the source list of a frame-ancestors
directive. Directive names are case-insensitive, so the directive is
recognized however the deployment spells it.
> 
> The same origin is added to the source list rather than replacing it,
which keeps the ancestors a deployment allows for the application
itself. An application embedded in a partner portal sends
frame-ancestors 'self' https://portal.example.com, and the directive is
matched against every ancestor of the stub, so replacing the list would
block the stub the same way the header it replaced did. A
frame-ancestors 'none' gives way to 'self', being valid only as the
single source of a list.
> 
> Scoping the rewrite to that single path leaves the app shell's own
protection untouched. Both the pre-cached and the network response are
rewritten, so the stub also renders when the server is reachable but the
Flow client fails to start.
> 
> Fixes #25492
>

Co-authored-by: Marco Collovati <marco@vaadin.com>
@vaadin-bot

Copy link
Copy Markdown
Collaborator

This ticket/PR has been released with Vaadin 25.4.0-alpha1.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

PWA offline page is blank with Spring Security: X-Frame-Options: DENY blocks Vaadin's own offline-stub.html iframe

3 participants