Skip to content

fix(server): transform plain text 401/403 to Chrome-compatible HTML for sidekick (#2414) #2613

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

fix(server): transform plain text 401/403 to Chrome-compatible HTML for sidekick (#2414) #2613

wants to merge 1 commit into from

Conversation

@trieloff
Copy link
Contributor

@trieloff trieloff commented Oct 7, 2025 •
edited
Loading

Summary

Completes the fix for #2414 by transforming plain text 401/403 responses into Chrome-compatible HTML that the AEM sidekick can recognize and act upon.

Background

Issue #2414 requested injection of the hlx:proxyUrl meta tag for 401/403 responses to enable sidekick login functionality.

PR #2601 partially addressed this by adding meta tag injection for HTML 401/403 responses. However, @rofe correctly identified that in real-world scenarios, the AEM pipeline returns plain text (not HTML) for these status codes, so the meta tag was never being injected in practice.

Solution

This PR transforms plain text 401/403 responses into Chrome-compatible HTML that:

  1. Matches the exact DOM structure Chrome generates for plain text responses
  2. Includes the hlx:proxyUrl meta tag the sidekick needs
  3. Uses the specific <body><pre>401 Unauthorized</pre></body> pattern the sidekick detects

Changes

  • Modified src/server/utils.js (lines 402-428) to generate Chrome-compatible HTML for plain text 401/403 responses
  • Removed old HTML wrapper (with login links) in favor of minimal Chrome-compatible structure
  • Standardized status text: "401 Unauthorized" or "403 Forbidden"
  • Added proper URL escaping for & and " characters
  • Changed content-type from text/plain to text/html
  • Added 3 comprehensive tests for plain text transformation scenarios

Test Plan

  • Added test for plain text 401 transformation with Chrome-compatible structure
  • Added test for plain text 403 transformation with Chrome-compatible structure
  • Added test for URL escaping with special characters
  • Verified existing HTML 401/403 tests still pass (from PR fix: inject hlx:proxyUrl meta tag for 401 and 403 HTML responses #2601)
  • Verified autologin functionality still works
  • All 34 server tests passing

Manual Testing Instructions

To test this fix manually with a real auth-enabled site:

  1. Clone and set up the adobe/helix-website repo (has auth enabled):

    git clone https://github.com/adobe/helix-website.git
cd helix-website

  2. Run the local dev server using this branch:

    npx --yes github:adobe/helix-cli#terragon/research-issue-2414-km0irh up --url https://main--helix-website--adobe.aem.page

  3. Test the 401/403 response transformation:

    • Open http://localhost:3000 in your browser
    • Navigate to an auth-protected page (you should see a 401/403 error)
    • Verify the response includes:
      • Chrome-compatible HTML structure with <pre>401 Unauthorized</pre> (or 403 Forbidden)
      • The hlx:proxyUrl meta tag in the <head>
      • The color-scheme meta tag for Chrome compatibility
    • With the AEM Sidekick extension installed:
      • The sidekick should recognize the auth error page
      • You should see the login option in the sidekick UI
      • Clicking login should redirect to the auth flow

  4. Inspect the HTML source to confirm structure:

    curl -i http://localhost:3000/some-protected-path

    Expected response headers:

    HTTP/1.1 401 Unauthorized
content-type: text/html

    Expected HTML body:

    <html><head><meta name="color-scheme" content="light dark"><meta property="hlx:proxyUrl" content="https://main--helix-website--adobe.aem.page/some-protected-path"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">401 Unauthorized</pre></body></html>

Fixes #2414

🤖 Generated with Claude Code

@trieloff trieloff force-pushed the terragon/research-issue-2414-km0irh branch from 42b5478 to a261c6d Compare October 7, 2025 11:59
@github-actions
Copy link

github-actions bot commented Oct 7, 2025

This PR will trigger a patch release when merged.

@trieloff trieloff changed the title Transform plain text 401/403 responses into Chrome-compatible HTML with meta tags fix(server): transform plain text 401/403 to Chrome-compatible HTML for sidekick (#2414) Oct 7, 2025
@trieloff @terragon-labs
fix(server): transform plain text 401/403 to Chrome-compatible HTML f…
a261c6d 
…or sidekick (#2414)

This completes the fix for issue #2414, addressing the real-world scenario
identified by @rofe where the AEM pipeline returns plain text (not HTML) for
401/403 responses.

PR #2601 previously added meta tag injection for 401/403 HTML responses, but
as noted in the issue comments, the actual pipeline returns plain text. This
change transforms those plain text responses into Chrome-compatible HTML that
the sidekick can recognize.

The generated HTML matches Chrome's structure for plain text responses:
- Includes <meta name="color-scheme"> for compatibility
- Includes <meta property="hlx:proxyUrl"> for sidekick functionality
- Uses <body><pre>401 Unauthorized</pre></body> structure that sidekick detects
- Properly escapes URLs containing special characters

This allows the AEM sidekick to detect auth errors and enable login functionality.

Fixes #2414

Co-authored-by: terragon-labs[bot] <terragon-labs[bot]@users.noreply.github.com>
@trieloff
Copy link
Contributor Author

trieloff commented Oct 7, 2025

Screenshot 2025-10-07 at 17 38 33

@rofe the PR will create the right HTML for the 401 to be intercepted, as you can see, Sidekick does decorate the HTML.

but: the login does not work, potentially due to something in sidekick itself or admin. I'd be grateful for pointers.

@rofe
Copy link
Contributor

rofe commented Oct 7, 2025 •
edited
Loading

I'd be grateful for pointers.

Here's a pointer: https://github.com/adobe/aem-sidekick/blob/main/src/extension/auth.js#L112

Currenty, the sidekick only injects the authorization header with the transient site token if the tab URL matches a aem.page or aem.live pattern.

@trieloff Terragon Labs
Copy link
Contributor Author

trieloff commented Oct 8, 2025

The sidekick has been updated to support localhost URLs with the authorization header injection. See adobe/aem-sidekick#701

@trieloff
Copy link
Contributor Author

trieloff commented Oct 10, 2025

@rofe do we need to wait for Google's approval for the sidekick extension to be released?

@rofe
Copy link
Contributor

rofe commented Oct 10, 2025

@trieloff sidekick v7.20.1 is published

@trieloff
Copy link
Contributor Author

trieloff commented Oct 17, 2025

Now I'd need a new example of an auth-protected site.

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

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

server: add hlx:proxyUrl meta tag also in case of 401 and 403 status

3 participants

@trieloff @rofe