feat(Auth): Support both HTTP Basic auth and form authentication (#1082)

Follow-up to #1053 

This PR does 5 things:
1. Ensures Jekyll includes the example post when building the
“site-with-errors”, by correcting its path:
github-community-projects/continuous-ai-for-accessibility-scanner@10fdd64
2. Updates the ‘Auth’ sub-action to support both HTTP Basic auth and
form authentication (automatically picking whichever is needed):
github-community-projects/continuous-ai-for-accessibility-scanner@42035f7
3. Replaces `session_state_path` with `playwright_context_options`, a
new input and output that includes the `session_state_path` string _and_
HTTP Basic auth credentials which are not persisted in the saved session
file:
github-community-projects/continuous-ai-for-accessibility-scanner@bdb5de9
4. Supports serving “site-with-errors” with Puma, behind HTTP Basic auth
(instead of just serving with Jekyll (WEBrick) directly):
github-community-projects/continuous-ai-for-accessibility-scanner@ad0ccb1
5. Updates the E2E test workflow so the ‘Auth’ sub-action is tested, by
scanning an HTTP Basic auth-protected “site-with-errors”:
github-community-projects/continuous-ai-for-accessibility-scanner@f319ee3

Author: smockle

.github/actions/auth/README.md

@@ -1,6 +1,6 @@
 # auth
 
-Log in using Playwright, then write authenticated session state to a file for reuse in other Playwright sessions.
+Authenticate with Playwright and save session state. Supports HTTP Basic and form authentication.
 
 ## Usage
 
@@ -23,6 +23,6 @@ Log in using Playwright, then write authenticated session state to a file for re
 
 ### Outputs
 
-#### `session_state_path`
+#### `auth_context`
 
-Path to a file containing authenticated session state.
+Stringified JSON object containing `username`, `password`, `cookies`, and/or `localStorage` from an authenticated session. For example: `{"username":"some-user","password":"correct-horse-battery-staple","cookies":[{"name":"theme-preference","value":"light","domain":"primer.style","path":"/"}],"localStorage":{"https://primer.style":{"theme-preference":"light"}}}`

.github/actions/auth/action.yml

@@ -1,5 +1,5 @@
 name: "Auth"
-description: "Log in using Playwright, then write authenticated session state to a file for reuse in other Playwright sessions."
+description: "Authenticate with Playwright and save session state. Supports HTTP Basic and form authentication."
 
 inputs:
   login_url:
@@ -13,13 +13,13 @@ inputs:
     required: true
 
 outputs:
-  session_state_path:
-    description: "Path to a file containing authenticated session state"
+  auth_context:
+    description: "Stringified JSON object containing 'username', 'password', 'cookies', and/or 'localStorage' from an authenticated session"
 
 runs:
   using: "node20"
   main: "bootstrap.js"
 
 branding:
   icon: "lock"
-  color: "blue"
+  color: "blue"

.github/actions/auth/package.json

@@ -1,7 +1,7 @@
 {
   "name": "auth",
   "version": "1.0.0",
-  "description": "Log in using Playwright, then write authenticated session state to a file for reuse in other Playwright sessions.",
+  "description": "Authenticate with Playwright and save session state. Supports HTTP Basic and form authentication.",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "scripts": {

.github/actions/auth/src/index.ts

@@ -1,3 +1,4 @@
+import type { AuthContextOutput } from "./types.d.js";
 import crypto from "node:crypto";
 import process from "node:process";
 import * as url from "node:url";
@@ -29,26 +30,62 @@ export default async function () {
       headless: true,
       executablePath: process.env.CI ? "/usr/bin/google-chrome" : undefined,
     });
-    context = await browser.newContext();
+    context = await browser.newContext({
+      // Try HTTP Basic authentication
+      httpCredentials: {
+        username,
+        password,
+      },
+    });
     page = await context.newPage();
 
-    // Log in
+    // Navigate to login page
     core.info("Navigating to login page");
     await page.goto(loginUrl);
-    core.info("Filling username");
-    await page.getByLabel(/username/i).fill(username);
-    core.info("Filling password");
-    await page.getByLabel(/password/i).fill(password);
-    core.info("Logging in");
-    await page
-      .getByLabel(/password/i)
-      .locator("xpath=ancestor::form")
-      .evaluate((form) => (form as HTMLFormElement).submit());
 
-    // Write authenticated session state to a file and output its path
-    await context.storageState({ path: sessionStatePath });
-    core.setOutput("session_state_path", sessionStatePath);
-    core.info(`Wrote authenticated session state to ${sessionStatePath}`);
+    // Check for a login form.
+    // If no login form is found, then either HTTP Basic auth succeeded, or the page does not require authentication.
+    core.info("Checking for login form");
+    const [usernameField, passwordField] = await Promise.all([
+      page.getByLabel(/username/i).first(),
+      page.getByLabel(/password/i).first(),
+    ]);
+    const [usernameFieldExists, passwordFieldExists] = await Promise.all([
+      usernameField.count(),
+      passwordField.count(),
+    ]);
+    if (usernameFieldExists && passwordFieldExists) {
+      // Try form authentication
+      core.info("Filling username");
+      await usernameField.fill(username);
+      core.info("Filling password");
+      await passwordField.fill(password);
+      core.info("Logging in");
+      await page
+        .getByLabel(/password/i)
+        .locator("xpath=ancestor::form")
+        .evaluate((form) => (form as HTMLFormElement).submit());
+    } else {
+      core.info("No login form detected");
+      // This occurs if HTTP Basic auth succeeded, or if the page does not require authentication.
+    }
+
+    // Output authenticated session state
+    const { cookies, origins } = await context.storageState();
+    const authContextOutput: AuthContextOutput = {
+      username,
+      password,
+      cookies,
+      localStorage: origins.reduce((acc, { origin, localStorage }) => {
+        acc[origin] = localStorage.reduce((acc, { name, value }) => {
+          acc[name] = value;
+          return acc;
+        }, {} as Record<string, string>);
+        return acc;
+      }, {} as Record<string, Record<string, string>>),
+    };
+    core.setOutput("auth_context", JSON.stringify(authContextOutput));
+    core.debug("Output: 'auth_context'");
   } catch (error) {
     if (page) {
       core.info(`Errored at page URL: ${page.url()}`);

.github/actions/auth/src/types.d.ts

@@ -0,0 +1,23 @@
+export type Cookie = {
+  name: string;
+  value: string;
+  domain: string;
+  path: string;
+  expires?: number;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: "Strict" | "Lax" | "None";
+};
+
+export type LocalStorage = {
+  [origin: string]: {
+    [key: string]: string;
+  };
+};
+
+export type AuthContextOutput = {
+  username?: string;
+  password?: string;
+  cookies?: Cookie[];
+  localStorage?: LocalStorage;
+};

.github/actions/find/README.md

@@ -15,9 +15,9 @@ https://primer.style
 https://primer.style/octicons/
 ```
 
-#### `session_state_path`
+#### `auth_context`
 
-**Optional** Path to a file containing authenticated session state.
+**Optional** Stringified JSON object containing `username`, `password`, `cookies`, and/or `localStorage` from an authenticated session. For example: `{"username":"some-user","password":"correct-horse-battery-staple","cookies":[{"name":"theme-preference","value":"light","domain":"primer.style","path":"/"}],"localStorage":{"https://primer.style":{"theme-preference":"light"}}}`
 
 ### Outputs
 

.github/actions/find/action.yml

@@ -6,8 +6,8 @@ inputs:
     description: "Newline-delimited list of URLs to check for accessibility issues"
     required: true
     multiline: true
-  session_state_path:
-    description: "Path to a file containing authenticated session state"
+  auth_context:
+    description: "Stringified JSON object containing 'username', 'password', 'cookies', and/or 'localStorage' from an authenticated session"
     required: false
 
 outputs:
@@ -20,4 +20,4 @@ runs:
 
 branding:
   icon: "compass"
-  color: "blue"
+  color: "blue"

.github/actions/find/src/AuthContext.ts

@@ -0,0 +1,50 @@
+import type playwright from "playwright";
+import type { Cookie, LocalStorage, AuthContextInput } from "./types.js";
+
+export class AuthContext implements AuthContextInput {
+  readonly username?: string;
+  readonly password?: string;
+  readonly cookies?: Cookie[];
+  readonly localStorage?: LocalStorage;
+
+  constructor({ username, password, cookies, localStorage }: AuthContextInput) {
+    this.username = username;
+    this.password = password;
+    this.cookies = cookies;
+    this.localStorage = localStorage;
+  }
+
+  toPlaywrightBrowserContextOptions(): playwright.BrowserContextOptions {
+    const playwrightBrowserContextOptions: playwright.BrowserContextOptions =
+      {};
+    if (this.username && this.password) {
+      playwrightBrowserContextOptions.httpCredentials = {
+        username: this.username,
+        password: this.password,
+      };
+    }
+    if (this.cookies || this.localStorage) {
+      playwrightBrowserContextOptions.storageState = {
+        // Add default values for fields Playwright requires which aren’t actually required by the Cookie API.
+        cookies:
+          this.cookies?.map((cookie) => ({
+            expires: -1,
+            httpOnly: false,
+            secure: false,
+            sameSite: "Lax",
+            ...cookie,
+          })) ?? [],
+        // Transform the localStorage object into the shape Playwright expects.
+        origins:
+          Object.entries(this.localStorage ?? {}).map(([origin, kv]) => ({
+            origin,
+            localStorage: Object.entries(kv).map(([name, value]) => ({
+              name,
+              value,
+            })),
+          })) ?? [],
+      };
+    }
+    return playwrightBrowserContextOptions;
+  }
+}

.github/actions/find/src/findForUrl.ts

@@ -1,10 +1,12 @@
 import type { Finding } from './types.d.js';
 import AxeBuilder from '@axe-core/playwright'
 import playwright from 'playwright';
+import { AuthContext } from './AuthContext.js';
 
-export async function findForUrl(url: string, sessionStatePath?: string): Promise<Finding[]> {
+export async function findForUrl(url: string, authContext?: AuthContext): Promise<Finding[]> {
   const browser = await playwright.chromium.launch({ headless: true, executablePath: process.env.CI ? '/usr/bin/google-chrome' : undefined });
-  const context = await browser.newContext({ storageState: !!sessionStatePath ? sessionStatePath : undefined });
+  const contextOptions = authContext?.toPlaywrightBrowserContextOptions() ?? {};
+  const context = await browser.newContext(contextOptions);
   const page = await context.newPage();
   await page.goto(url);
 

.github/actions/find/src/index.ts

@@ -1,17 +1,21 @@
+import type { AuthContextInput } from "./types.js";
 import core from "@actions/core";
+import { AuthContext } from "./AuthContext.js";
 import { findForUrl } from "./findForUrl.js";
 
 export default async function () {
   core.info("Starting 'find' action");
-  const urls = core.getMultilineInput('urls', { required: true });
+  const urls = core.getMultilineInput("urls", { required: true });
   core.debug(`Input: 'urls: ${JSON.stringify(urls)}'`);
-  const sessionStatePath = core.getInput('session_state_path', { required: false });
-  core.debug(`Input: 'session_state_path: ${sessionStatePath}'`);
+  const authContextInput: AuthContextInput = JSON.parse(
+    core.getInput("auth_context", { required: false }) ?? "{}"
+  );
+  const authContext = new AuthContext(authContextInput);
 
   let findings = [];
   for (const url of urls) {
-    core.info(`Scanning ${url}`)
-    const findingsForUrl = await findForUrl(url, sessionStatePath);
+    core.info(`Scanning ${url}`);
+    const findingsForUrl = await findForUrl(url, authContext);
     if (findingsForUrl.length === 0) {
       core.info(`No accessibility gaps were found on ${url}`);
       continue;