Auth Doctor

A Chrome browser extension (Manifest V3) and desktop companion app for inspecting and debugging authentication & authorization artifacts during web development. Think of it as browser DevTools, but specialized for auth.

Features

Browser Extension

• Cookie Inspector — view all cookies for the current page with domain, path, flags, and expiration
• Storage Viewer — browse localStorage and sessionStorage entries with sizes
• HTTP Header Capture — live stream of auth-related headers (Authorization, Cookie, Set-Cookie, CSRF tokens, API keys, CORS credentials)
• WebAuthn Observer — intercepts navigator.credentials.create/get calls to show passkey and WebAuthn activity metadata
• Recording Sessions — capture multi-step auth flows as a timeline of headers, cookies, navigations, and WebAuthn events
• Export — save recorded sessions as JSON (full data) or HAR 1.2 (HTTP headers)
• Per-domain Config — ignore domains, add custom header names, auto-record on specific domains
• Service Worker Resilient — recordings survive Chrome killing the background service worker
• Programmatic API — window.AuthDoctor global on api.html for Playwright and headless automation

Desktop Companion App (Planned)

• Log Collection — receives captured data from the extension via a local HTTP server
• Token Analysis — classifies auth tokens (JWT, session cookies, CSRF, API keys, OAuth) and assesses security posture
• Visualization — filterable dashboards for cookies, headers, storage, WebAuthn, and auth flow timelines
• Security Assessment — checks cookie flags, token expiry, algorithm strength, missing protections
• Forwarding — export findings for retention and shared analysis

This is a read-only inspection tool. It never modifies cookies, storage, or credentials.

Prerequisites

• Bun (package manager and runtime)
• Google Chrome (or Chromium-based browser)
• Rust (for the desktop companion app)

Quick Start

# Install dependencies
bun install

# Build the extension
bun run build:extension

# Run the desktop companion app (dev mode)
bun run tauri dev

Installing the Dev Extension

1. Run the build:

   bun run build:extension

   This produces a loadable unpacked extension in the extension/ directory.

2. Open Chrome and navigate to chrome://extensions

3. Enable Developer mode using the toggle in the top-right corner

4. Click Load unpacked and select the extension/ directory from this project

5. Pin Auth Doctor to the toolbar — click the puzzle piece icon in Chrome's toolbar, then click the pin icon next to "Auth Doctor"

The extension icon should now appear in your Chrome toolbar.

Using Auth Doctor

Opening the Panel

Click the Auth Doctor icon in the Chrome toolbar while on any website. A popup panel opens with four tabs:

Cookies Tab

Displays all cookies accessible for the current page URL. Click a cookie row to expand and see all attributes (domain, path, secure, httpOnly, sameSite, expiration).

Storage Tab

Shows localStorage and sessionStorage entries for the current page. Each entry displays the key, value, and size in bytes.

Headers Tab

Captures auth-related HTTP headers in real time. On first use, you will be prompted to grant the webRequest permission — this is required for header interception and only activates when you approve.

Captured header names include: Authorization, Cookie, Set-Cookie, WWW-Authenticate, X-CSRF-Token, X-XSRF-Token, X-API-Key, Access-Control-Allow-Credentials, Access-Control-Allow-Origin, and any custom headers you add in Settings.

Recording Tab

Record an auth flow across multiple page navigations:

1. Click Start Recording — the extension captures all auth events for the current tab
2. Browse normally — log in, follow redirects, complete SAML/OAuth flows
3. The popup can close during navigation; the recording continues in the background
4. Reopen the popup and click Stop Recording
5. The session is saved and appears in the session list

Viewing a session: Click a saved session to load its timeline. Events are displayed with relative timestamps and colored dots:

• Blue = HTTP headers
• Green = cookie changes
• Orange = navigations
• Purple = WebAuthn calls

Use the filter checkboxes to show/hide event types. Click any event row to expand its details.

Exporting: When viewing a loaded session, use the export buttons:

• Export JSON — full session data (all event types)
• Export HAR — HTTP Archive 1.2 format (header events only, compatible with Chrome DevTools and other tools)

Settings (Gear Icon)

Click the gear icon in the header to open the settings panel:

• Ignored Domains — headers from these domains will not be captured (e.g., analytics domains)
• Custom Headers — additional header names to capture beyond the defaults
• Auto-Record Domains — automatically start recording when navigating to these domains

Settings persist across browser restarts.

Playwright / Headless Automation

Auth Doctor exposes a programmatic API for automated testing via api.html:

// Load the extension in Playwright
const context = await chromium.launchPersistentContext('', {
  headless: false,
  args: [
    `--disable-extensions-except=${extensionPath}`,
    `--load-extension=${extensionPath}`,
  ],
});

// Get the extension ID from the service worker
const sw = await context.waitForEvent('serviceworker');
const extensionId = sw.url().split('/')[2];

// Navigate to the API page
const apiPage = await context.newPage();
await apiPage.goto(`chrome-extension://${extensionId}/api.html`);
await apiPage.waitForFunction(() => 'AuthDoctor' in window);

// Use the API
const cookies = await apiPage.evaluate(
  () => window.AuthDoctor.getCookies('https://example.com')
);

Available methods: getCookies, getStorage, getHeaders, getTabInfo, requestHeaderPermission, startRecording, stopRecording, getRecordingState, getSessions, getSession, deleteSession, getConfig, saveConfig, connectLive.

Run the e2e test suite:

bun run test:e2e

Development

Build Commands

Command	Description
bun install	Install dependencies
bun run build:extension	Full extension build (panel + scripts + static assets)
bun run build:panel	Build only the SvelteKit panel UI
bun run build:scripts	Build only the extension scripts (background, content, devtools, api)
bun run check	TypeScript type checking
bun run check:watch	Type checking in watch mode
bun run test:e2e	Build extension and run Playwright e2e tests
bun run tauri dev	Run desktop companion app in dev mode
bun run tauri build	Production build of desktop app

Rebuild After Code Changes

bun run build:extension

Then go to chrome://extensions and click the refresh icon on the Auth Doctor card. If the popup is open, close and reopen it.

Architecture

The extension runs across four execution contexts:

Context	File	Role
Service Worker	background.js	Cookie/header capture, recording state machine, message routing, config
Content Script (ISOLATED)	webauthn-relay.js	Relays WebAuthn events from page to service worker
Content Script (MAIN)	webauthn-observer.js	Proxies navigator.credentials to capture WebAuthn metadata
Popup / DevTools Panel	index.html	SvelteKit SPA with artifact viewer, timeline, config, and export
Programmatic API	api.html	window.AuthDoctor global for Playwright automation

Communication flow:

Page JS (MAIN world)  -->  webauthn-relay (ISOLATED)  -->  Service Worker
                                                               |
Popup UI  <-- chrome.runtime ports (live streaming) --+--------+
          <-- chrome.runtime messages (request/response) ------+
                                                               |
api.html  <-- chrome.runtime messages (programmatic access) ---+

The desktop companion app adds a Tauri (Rust) backend that receives extension data over a local HTTP server:

Extension Service Worker  --POST /api/v1/-->  Tauri (Axum HTTP server)
                                                |
                                                +--> In-memory state
                                                +--> Disk persistence
                                                +--> Analysis engine
                                                +--> SvelteKit desktop UI

Build System

Two separate Vite builds assembled into a single extension/ output:

1. Panel build (vite build) — SvelteKit with adapter-static produces the popup HTML/JS/CSS
2. Script build (vite build --config vite.extension.config.ts) — Rollup compiles background.ts, devtools.ts, api.ts, webauthn-observer.ts, and webauthn-relay.ts into standalone JS files
3. Post-processing (scripts/fix-inline-script.js) — extracts SvelteKit's inline script to comply with MV3 CSP

Project Structure

src/
  extension/
    background.ts          Service worker
    recording.ts           Recording engine (imported by background)
    api.ts                 Programmatic API (window.AuthDoctor)
    webauthn-observer.ts   MAIN world content script
    webauthn-relay.ts      ISOLATED world content script
    devtools.ts            DevTools page bootstrap
    static/                manifest.json, api.html, devtools.html, icons
  lib/
    types.ts               Shared types and message constants
    messages.ts            Chrome messaging helpers
    stores/                Svelte 5 reactive stores
    components/            UI components
    export/                JSON and HAR export logic
  routes/
    +page.svelte           Main popup UI
extension/                 Built output (load this in Chrome)
src-tauri/                 Rust backend (desktop companion app)
  src/
    lib.rs                 Tauri app setup and command registration
    commands.rs            Tauri IPC commands
    state.rs               Application state (in-memory site data)
    models/                Data models (artifacts, analysis types)
    server/                Axum HTTP server (receives extension data)
tests/
  e2e/                     Playwright e2e tests

License

MIT