Auth Setup for Testing

Get an authenticated session ready for testing. Work out how the project's auth is wired, locate any test credentials, bring in cookies from a real browser, and prove that an authenticated request goes through.

Gather context first

This skill ships standalone, so it can't assume your project's conventions, house style, or preferences the way it could for its author. Before doing the main work:

1. Auto-detect what you safely can from the repo — language/stack, base branch, build/test commands, existing config and docs. Never ask for something you can read for yourself.
2. Ask, don't assume, for the rest. Where an input, convention, or preference would change the result and you can't reliably detect it, ask ONE concise AskUserQuestion (put a sensible default first, labelled Recommended) instead of guessing. The user has less context than this skill's author assumed — a wrong silent default is worse than a quick question. Don't ask about things you can detect, and don't ask more than you need.

For this skill, confirm up front (only the items you can't already detect):

• Target / base URL to authenticate against — a local dev server (e.g. http://localhost:3000) or a staging/host URL. Detect a running dev server or take it from $ARGUMENTS; confirm only if more than one is plausible or none is detected.
• A protected route or API endpoint that should return 200 only when authenticated — this is what Step 5 hits to prove the session works. Auto-detect from auth middleware / route guards if you can; otherwise ask.
• Which browser to import cookies from (Option A) — auto-detect installed Chromium browsers (Chrome/Brave/Edge/Arc/Comet); ask only when more than one is installed and the user hasn't named one.
• Where to write the session config — default /tmp/test-auth-config.json, which the QA/design skills read. Confirm only if the user keeps test artifacts somewhere else.

How this runs

This skill is interactive and lives in the conversation. The CDP check, the Step 3 auth-options question, the manual-login walkthrough, the verification curls, and the final config export all need either a direct answer from the user or live filesystem / network access — so they always run inline here.

The only part that can theoretically be parallelized is the read-only codebase recon (auth detection + credential scan). Run that inline too by default. Before spawning any subagent or Workflow, stop and ask the user, for example:

This repo is large. The two recon passes (auth-system detection + credential scan) can run inline here (cheaper, slower) or as 2 parallel subagents (faster, more tokens). Which do you want?

Spawn subagents/workflows only after an explicit yes. If the user declines or doesn't answer, do the whole job inline. If the user opts in, you may push just those two passes into a Workflow — and even then the Workflow does nothing but headless reads and returns structured findings. Everything interactive and every file write stays inline, because background agents can neither talk to the user nor write files.

Arguments

Check $ARGUMENTS:

• A target URL / base URL / host (e.g. http://localhost:3000, a staging domain) → use it as the base for verification curls and the cookie-import domain.
• A mode hint — "cookie import" / "import from browser" → Option A; "use .env" / "dev creds" → Option B; "manual" → Option C; "api login" → Option D; "public only" / "skip auth" → Option E.
• A domain (e.g. github.com) → hand it straight to the direct cookie-import path ($B cookie-import-browser --domain <domain>).
• Empty → run the full flow starting at the CDP-mode check.

Step 0: CDP mode check

Before anything else, check whether the QA browser tool is already attached to a real browser over CDP (Chrome DevTools Protocol). If it is, cookies and sessions are already live and no setup is needed.

# If a browser cookie CLI is available, check its mode
$B status 2>/dev/null | grep -q "Mode: cdp" && echo "CDP_MODE=true" || echo "CDP_MODE=false"

If CDP_MODE=true: tell the user "Not needed — you're connected to your real browser via CDP. Your cookies and sessions are already available." and stop.

If $B is not available, continue to Step 1.

Steps 1–2: Codebase recon

Step 1 (detect the auth system) and Step 2 (scan for existing test credentials) are two independent, read-only passes over the repository. By default, run both inline in this context — a sequential grep/glob/read sweep is quick and cheap:

ls .env .env.local .env.development 2>/dev/null
# Check env files for test credentials (show key names only, NEVER values)
grep -l "TEST_USER\|STAFF_USER\|ADMIN_USER\|test_password\|dev_token" .env* 2>/dev/null

If the user opted into parallelism and the repo is large enough to be worth it, fan the two passes out as a Workflow — one agent per recon target — then present the consolidated findings inline. The Workflow only reads; it never writes files and never talks to the user.

export const meta = {
  name: 'auth-setup-auth-recon',
  description: 'Parallel codebase recon — auth-system detection and existing-credential scan',
  phases: [{ title: 'Recon' }],
}
const RECON_SCHEMA = {
  type: 'object',
  properties: {
    target: { type: 'string' },                 // auth-system | test-credentials
    authType: { type: 'string' },               // JWT | Session | OAuth | Cookie-based | unknown
    storage: { type: 'string' },                 // localStorage | cookies | httpOnly cookies | unknown
    loginEndpoint: { type: 'string' },
    tokenRefresh: { type: 'string' },            // yes/no + endpoint, or unknown
    sessionName: { type: 'string' },             // cookie/storage key name
    credentialLocations: {                       // WHERE creds exist — NEVER the values
      type: 'array',
      items: {
        type: 'object',
        properties: {
          file: { type: 'string' },
          keys: { type: 'array', items: { type: 'string' } },  // key names only, never values
        },
        required: ['file', 'keys'],
      },
    },
    notes: { type: 'string' },
  },
  required: ['target', 'notes'],
}
const TARGETS = [
  {
    key: 'auth-system',
    instruction:
      'Analyze the project to understand how authentication works. Search for: ' +
      'session storage (SessionName, sessionStorage, localStorage, cookies); ' +
      'auth headers (Authorization, Bearer, authHeader, token); ' +
      'auth libraries (next-auth, passport, jwt, oauth, lucia, clerk, supabase); ' +
      'login endpoints (/login, /signin, /auth, /api/auth); ' +
      'auth middleware (withAuth, requireAuth, isAuthenticated). ' +
      'Return the auth type, storage mechanism, login endpoint, token-refresh story, and session name. ' +
      'Leave credentialLocations empty for this target.',
  },
  {
    key: 'test-credentials',
    instruction:
      'Scan for existing test/dev credentials. Check env files (.env, .env.local, .env.development) for ' +
      'TEST_USER, STAFF_USER, ADMIN_USER, test_password, dev_token. Also search for: seed files with test users; ' +
      'test fixtures with login credentials; dev-environment config with default credentials; ' +
      'Postman/Insomnia collections with auth tokens. ' +
      'CRITICAL: report ONLY that credentials exist and WHERE (file + key names). ' +
      'NEVER read out, return, or echo any credential VALUE. Populate credentialLocations with file + key-name pairs only.',
  },
]
const recon = await parallel(TARGETS.map(t => () =>
  agent(
    `You are doing read-only auth recon on a codebase for "${t.key}". ${t.instruction}\n\n` +
    `Project root: ${args.root}. Do NOT write any files. Do NOT call the user. ` +
    `Return structured findings only.`,
    { label: `recon:${t.key}`, phase: 'Recon', model: 'opus', schema: RECON_SCHEMA }
  )
))
return recon.filter(Boolean)

When opting into the Workflow, mind these constraints: agent() calls run in the background — they cannot call AskUserQuestion, cannot talk to the user, and cannot write files, and they have no Date.now / Math.random / filesystem-write access. So timestamps, every option ceremony, the cookie import, the verification curls, and every file write (/tmp/test-auth-config.json, /tmp/test-cookies.txt) stay inline. The Workflow only greps/globs/reads the repo and returns structured results. Always set model: 'opus' on agent() calls so no lightweight tier leaks in, and pass the project root in via args: { root: "<project root path>" }.

When recon returns (inline or from the Workflow), report the findings inline.

Step 1 report: Detect Auth System

AUTH SYSTEM DETECTED
====================
Type: [JWT / Session / OAuth / Cookie-based]
Storage: [localStorage / cookies / httpOnly cookies]
Login endpoint: [path]
Token refresh: [yes/no, endpoint]
Session name: [cookie/storage key name]

Step 2 report: Check Existing Test Credentials

Look for existing test/dev credentials across env files, seed files, test fixtures, dev-environment config, and Postman/Insomnia collections.

NEVER display credential values. Report only that they exist and where.

Step 3: Auth Setup Options

Ask the user how to proceed, with the detected auth info in front of them (inline):

I detected [auth type] authentication in this project.

Current state:
- Login endpoint: [path]
- Session storage: [type]
- Test credentials: [found in .env / not found]
- Dev server: [running on :3000 / not detected]

How would you like to set up auth for testing?

A) Import cookies from a real browser
   (Use the cookie picker to grab your existing login session from Chrome/Brave/Edge/Arc/Comet)

B) Use existing dev credentials from .env
   (I'll extract the session token after an API login)

C) Manual login — I'll guide you through the login flow
   (You log in via browser, then give me the session token/cookie)

D) API login — I'll call the login endpoint directly
   (Requires username/password or API key)

E) Skip auth — test only public pages

RECOMMENDATION: Choose [X] because [reason]

Step 4: Execute Auth Setup

Option A: Import cookies from a real browser

The quickest path when the user is already signed in through a normal browser.

Find a cookie-import CLI:

# Check common locations for a cookie-import CLI
B=""
command -v browse >/dev/null 2>&1 && B=browse
[ -z "$B" ] && [ -x "./scripts/browse" ] && B="./scripts/browse"
[ -n "$B" ] && echo "BROWSE_READY: $B" || echo "BROWSE_NOT_AVAILABLE"

If BROWSE_NOT_AVAILABLE: fall back to manual cookie extraction (Option C).

Open the cookie picker:

$B cookie-import-browser

This auto-detects installed Chromium browsers and opens an interactive picker. If exactly one Chromium browser is installed, just use it; if several are and the user hasn't named one, confirm which to pull cookies from (see Gather context first) before importing. The user can:

• Switch between installed browsers
• Search domains
• Click "+" to import a domain's cookies
• Click trash to remove imported cookies

Tell the user: "Cookie picker opened — select the domains you want to import in your browser, then tell me when you're done."

Direct import (alternative):

If the user names a domain directly (e.g., "import cookies from github.com"), skip the UI:

$B cookie-import-browser --domain github.com
# Or specify a browser: $B cookie-import-browser comet --domain github.com

Platform notes:

• On macOS, the first import per browser may trigger a Keychain dialog — the user clicks "Allow" / "Always Allow"
• On Linux, v11 cookies may need secret-tool / libsecret access; v10 cookies use Chromium's standard fallback key
• Only domain names and cookie counts surface in the UI — no cookie values are ever shown
• The CLI session persists cookies between commands, so imported cookies work right away

Verify:

$B cookies

Show the user a summary of the imported cookies (domain counts).

Option B: Use existing dev credentials

1. Read the relevant env file for the credential keys
2. Identify the login API endpoint from the codebase
3. Attempt login via the API
4. Store the resulting token/session

Option C: Manual login guidance

1. Tell the user which URL to visit
2. Tell them what credentials to use (reference the env file; don't show values)
3. Tell them how to pull out the session token:
   • For cookies: "Open DevTools > Application > Cookies > copy the value of [session_name]"
   • For localStorage: "Open DevTools > Application > Local Storage > copy [token_key]"
   • For httpOnly cookies: "Open DevTools > Network > find any API request > copy the Cookie header"
4. Ask the user to paste the token/cookie value

Option D: API login

1. Read the login endpoint from the codebase
2. Ask the user for credentials (or reference the env file)
3. Call the login endpoint (use the login path detected in Step 1 and the confirmed base URL — the path below is a placeholder):

   curl -s -X POST <base-url>/<login-endpoint> \
     -H "Content-Type: application/json" \
     -d '{"username":"...","password":"..."}' \
     -c /tmp/test-cookies.txt

4. Extract and store the session token from the response

Option E: Skip auth

Note that only public pages will be reachable, and continue.

Step 5: Verify Auth

Once you have credentials, confirm they actually work. Use the base URL and protected route you confirmed in Gather context first (the http://localhost:3000/... paths below are placeholders — substitute the real ones):

# Test an authenticated endpoint (Bearer token)
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer <token>" \
  <base-url>/<protected-endpoint>

# Or with cookies
curl -s -o /dev/null -w "%{http_code}" \
  -b "session_name=<value>" \
  <base-url>/<protected-page>

Report:

AUTH VERIFICATION
=================
Status: SUCCESS / FAILED
Endpoint tested: [path]
Response code: [200/401/403]
Session valid until: [if detectable]

If it failed, suggest troubleshooting steps.

Step 6: Export for Other Skills

Save the auth config so other skills (/qa, /qa-fix, /ui-polish) can pick it up.

Write to /tmp/test-auth-config.json (the path those skills read by default — use it unless the user confirmed a different location in Gather context first):

{
  "type": "bearer|cookie|session|cdp|cookie-import",
  "header": "Authorization: Bearer <token>",
  "cookie": "session_name=<value>",
  "expires": "ISO-8601 or unknown",
  "verified": true,
  "endpoint_tested": "/api/protected"
}

Tell the user: "Auth session is ready. QA and design skills can use this session for testing authenticated pages."

Important Rules

1. NEVER display credential values. Show only that they exist and where they live.
2. NEVER commit credentials. Don't write tokens to tracked files.
3. NEVER hardcode tokens in source. Use environment variables or temp files.
4. Session tokens go to /tmp only. They should not survive a reboot.
5. Always verify auth works before telling QA skills the session is ready.
6. Handle expired sessions gracefully. If a token has expired, walk the user through re-authentication.
7. Prefer cookie-import over credential entry. If the user is already signed in through a real browser, Option A is faster and safer than re-typing passwords.
8. Interactive work and file writes stay inline. If you opt into the recon Workflow, it only reads the repo and returns findings — never put an option ceremony, a verification curl, a cookie import, or any file write (/tmp/test-auth-config.json, /tmp/test-cookies.txt) inside a Workflow agent(). Background agents can neither talk to the user nor write files.