helix-cli icon indicating copy to clipboard operation
helix-cli copied to clipboard
verified publisher icon adobe

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

Open trieloff opened this issue 2 months ago • 8 comments

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

  • [x] Added test for plain text 401 transformation with Chrome-compatible structure
  • [x] Added test for plain text 403 transformation with Chrome-compatible structure
  • [x] Added test for URL escaping with special characters
  • [x] Verified existing HTML 401/403 tests still pass (from PR #2601)
  • [x] Verified autologin functionality still works
  • [x] 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 avatar Oct 07 '25 10:10 trieloff

This PR will trigger a patch release when merged.

github-actions[bot] avatar Oct 07 '25 11:10 github-actions[bot]

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.

trieloff avatar Oct 07 '25 12:10 trieloff

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.

rofe avatar Oct 07 '25 12:10 rofe

The sidekick has been updated to support localhost URLs with the authorization header injection. See https://github.com/adobe/aem-sidekick/pull/701

trieloff avatar Oct 08 '25 04:10 trieloff

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

trieloff avatar Oct 10 '25 11:10 trieloff

@trieloff sidekick v7.20.1 is published

rofe avatar Oct 10 '25 11:10 rofe

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

trieloff avatar Oct 17 '25 08:10 trieloff 

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

redirects me immediately to the Microsoft IDP, so I guess it's working as expected.

trieloff avatar Nov 24 '25 07:11 trieloff

:tada: This PR is included in version 16.16.7 :tada:

The release is available on:

Your semantic-release bot :package::rocket:

adobe-bot avatar Nov 28 '25 14:11 adobe-bot