Capture a page behind a login

A route names its necessary login. Fruitful tests the session before capture. If the session is missing, the user must sign in. The package never receives credentials or cookies. Before capture, follow the private evidence rules.

Declare the login

Define logins in capture.logins[]. Routes refer to them by ID:

"logins": [
  {
    "id": "linkedin",
    "name": "LinkedIn",
    "reason": "LinkedIn captures need a logged-in browser session.",
    "checkUrl": "https://www.linkedin.com/in/me/",
    "signInUrl": "https://www.linkedin.com/login",
    "signedIn": {
      "selectors": ["[data-testid=\"mainFeed\"]", "section[data-view-name=\"profile-card\"]"]
    },
    "signedOut": {
      "reason": "LinkedIn redirected to a sign-in or checkpoint page.",
      "urls": [{ "pattern": { "hostname": "*.linkedin.com", "pathname": "/login*" } }],
      "html": ["id=\"rememberme-div\""]
    }
  }
]

• Fruitful loads checkUrl to test the session.
• Fruitful opens signInUrl when the user must sign in.
• Any matching signedIn condition can identify a ready session.
• signedOut tests the final URL or HTML for a signed-out session.
• The user sees the signedOut.reason text when it matches.

A matcher can test urls, CSS selectors, or literal html substrings. Use different reliable conditions when the site has different sign-in paths.

Attach the login to a route

{ "id": "newsfeed", "kind": "collection", "login": "linkedin", "runsOn": ["desktop"], "binding": "newsfeed" }

This route uses the local signed-in browser. The registry rejects a reader or media route that has a login and lists cloud. Capture stops with LoginRequired if signedOut matches or signedIn does not match.

Complete the authentication checkpoint

The CLI and MCP share a capture service, but their session lifetimes differ:

A later CLI invocation cannot resume the previous command's pending session. Rerun capture interactively if authentication is necessary. --headless does not provide an interactive login window.

For an MCP checkpoint:

1. Keep the returned authSessionId.
2. Tell the user the target URL and the reason for the checkpoint.
3. Ask the user to sign in through the already-open Chrome window and leave that window open.
4. Keep the authoring task pending until the user says the session is ready.
5. Call resume_capture with the same session ID.
6. Use assess_capture to make sure the capture contains the expected page.

If login is still necessary, repeat the checkpoint. If the task ends, call cancel_auth_session. Do not author from a login page or silently substitute an old fixture. If the user cannot sign in, get agreement before you reduce the task to a repair with existing fixtures. Give that reduced evidence scope in the result.

Never request passwords or two-factor codes. Do not keep a capture tool call open while you wait for the user. Do not repeatedly poll the login page or start another browser against the same profile.

Import an existing browser session

Use this path only when the user explicitly chooses to reuse their normal browser session:

1. Use list_browser_sessions to find available profile and domain metadata.
2. Name the source profile and target domains before import.
3. Get explicit consent for that profile and those domains.
4. Use import_browser_session for the active authentication session.
5. Resume capture after import.

The listing does not expose cookie values or access Keychain. The import uses only the permitted domains. The user enters a laptop password only in the macOS Keychain prompt. Never request, read, repeat, or log that password or decrypted cookie values.

Profile contention

For ChromeProfileInUse, ask the user to close only the unrelated window named by the error. Keep an MCP-managed login window open. Resume that window through its authSessionId.

Reference: login, sessionMatcher.