signin-window 0.1.2__tar.gz

signin_window-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.11', '3.12', '3.13']
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          python-version: ${{ matrix.python }}
+      - run: make check
+
+  # The paste add-on in a real browser.
+  browser:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - run: uv sync --locked --group browser
+      - run: uv run --frozen playwright install --with-deps --only-shell chromium
+      - run: uv run --frozen pytest tests/test_paste_dom.py
+
+  # A link, its live view, paste and a hand-over, with Xvfb, x11vnc, noVNC and a real Chromium (scripts/e2e.py), on
+  # Debian trixie: the base a login service image normally uses (Ubuntu 24.04's x11vnc injects no input on Xvfb).
+  e2e:
+    runs-on: ubuntu-latest
+    container: python:3.12-slim-trixie
+    timeout-minutes: 15
+    env:
+      NOVNC_VERSION: 1.6.0
+      NOVNC_SHA256: 5066103959ef4e9b10f37e5a148627360dd8414e4cf8a7db92bdbd022e728aaa
+      UV_LINK_MODE: copy
+    steps:
+      - name: Xvfb, x11vnc, noVNC and uv
+        run: |
+          apt-get update -q && apt-get install -y -q --no-install-recommends ca-certificates curl git xvfb x11vnc
+          curl --fail --silent --show-error --location \
+            "https://github.com/novnc/noVNC/archive/refs/tags/v${NOVNC_VERSION}.tar.gz" -o /tmp/novnc.tar.gz
+          printf '%s  /tmp/novnc.tar.gz\n' "$NOVNC_SHA256" | sha256sum --check --status
+          mkdir -p /tmp/novnc && tar -xzf /tmp/novnc.tar.gz -C /tmp/novnc --strip-components=1
+          pip install --quiet uv
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - run: uv sync --locked --group browser
+      - run: uv run --frozen playwright install --with-deps chromium
+      - run: E2E_SHOTS=/tmp/e2e-shots NOVNC_DIR=/tmp/novnc timeout 600 uv run --frozen python scripts/e2e.py
+      - if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-screenshots
+          path: /tmp/e2e-shots
+          retention-days: 7

signin_window-0.1.2/.github/workflows/pypi.yml

@@ -0,0 +1,38 @@
+name: PyPI
+# A vX.Y.Z tag builds the wheel and sdist from the tagged tree and uploads them to PyPI as
+# `signin-window` with trusted publishing (OIDC through the `pypi` environment; no token is
+# stored). Tag pushes upload once the repository variable PYPI_PUBLISH is `true`; until then,
+# or to retry, run it by hand on the tag: `gh workflow run pypi.yml --ref vX.Y.Z`. Files that
+# are already on PyPI are skipped, so a repeated run is harmless.
+on:
+  push:
+    tags: ['v*.*.*']
+  workflow_dispatch: {}
+
+permissions: {}
+
+concurrency:
+  group: pypi-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    if: github.ref_type == 'tag' && (github.event_name == 'workflow_dispatch' || vars.PYPI_PUBLISH == 'true')
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - name: Build
+        run: |
+          version="$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          [ "${GITHUB_REF_NAME#v}" = "$version" ] || { echo "tag $GITHUB_REF_NAME is not version $version" >&2; exit 1; }
+          uv build
+      - name: Upload
+        run: uv publish --trusted-publishing always --check-url https://pypi.org/simple/

signin_window-0.1.2/.github/workflows/release.yml

@@ -0,0 +1,65 @@
+name: Release
+# A v1.2.3 tag: run the tests on the tagged commit, build the wheel and sdist, and publish a GitHub release with
+# them (pypi.yml uploads the same tag to PyPI). Only the built-in token is used.
+on:
+  push:
+    tags: ['v*.*.*']
+  workflow_dispatch: {}
+
+permissions: {}
+
+# GitHub can deliver one tag push twice: the runs of a ref queue one behind the other, and a
+# run whose tag already has a GitHub release (the last job) stops at `released`.
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  released:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    outputs:
+      done: ${{ steps.check.outputs.done }}
+    steps:
+      - id: check
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          done=false
+          if [ "$GITHUB_REF_TYPE" = tag ] && gh release view "$TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            done=true
+            echo "$TAG is already released: nothing to do"
+          fi
+          echo "done=$done" >> "$GITHUB_OUTPUT"
+
+  ci:
+    needs: released
+    if: needs.released.outputs.done != 'true'
+    uses: ./.github/workflows/ci.yml
+    permissions:
+      contents: read
+
+  github-release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - name: Build
+        run: |
+          version="$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          [ "${GITHUB_REF_NAME#v}" = "$version" ] || { echo "tag $GITHUB_REF_NAME is not version $version" >&2; exit 1; }
+          uv build
+      - env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: gh release create "$TAG" dist/* --repo "$GITHUB_REPOSITORY" --verify-tag --title "$TAG" --generate-notes

signin_window-0.1.2/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dist/
+.artifacts/

signin_window-0.1.2/.python-version

@@ -0,0 +1 @@
+3.12

signin_window-0.1.2/AGENTS.md

@@ -0,0 +1,27 @@
+# Working on signin-window
+
+Instructions for contributors and coding agents. `AGENTS.md` is the only agent instruction file.
+
+**This repository is public.** Never commit personal data or anything about a particular deployment: no names,
+email addresses, accounts, host names, networks or infrastructure of where it runs, and no anecdotes about who used
+it when. Tests and examples use `example.com` and invented values. This applies to code comments, docs, tests and
+commit messages alike.
+
+## Verify
+
+`make bootstrap`, then `make check`: ruff, the format check and pytest. The paste add-on's browser test runs with
+`uv sync --group browser`, `uv run playwright install chromium` and `uv run pytest tests/test_paste_dom.py` (CI runs
+it in a job of its own). Documentation-only changes need `git diff --check` and link checks.
+
+## Boundaries
+
+- `tests/test_safety.py` is the boundary: nothing in `src/` clicks, types or fills a page; only `client.py` opens
+  connections (to the login service); the VNC server listens on loopback; `static/paste.js` logs and keeps nothing.
+  Changing any of these is a design change: argue it in the pull request.
+- The login service's live view is open only while a window is `waiting` and only with its view token; a link's
+  live view only while its window is `waiting`. A session crosses from the service to the server once
+  (`POST /logins/{id}/result`) and is never part of a state, a page or a log line.
+- `static/paste.js` is noVNC-version-sensitive (it imports `app/ui.js` and the keysym tables): test it against the
+  noVNC release the README names.
+- The public API is what `README.md` documents. Within 0.x, a minor version may change it; say how in the release
+  notes.

signin_window-0.1.2/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing
+
+Thanks for helping. Issues and pull requests are welcome.
+
+## Setup
+
+```sh
+git clone https://github.com/benjamin-di/signin-window
+cd signin-window
+make bootstrap   # uv sync --locked
+make check       # lint, format, tests
+```
+
+The paste add-on's browser test needs Playwright's Chromium:
+`uv sync --group browser && uv run playwright install chromium && uv run pytest tests/test_paste_dom.py`.
+
+## Rules
+
+- **The person does every step of a sign-in.** Nothing in this package may click, type or fill a page
+  (`tests/test_safety.py`). A change that automates a sign-in will not be taken.
+- **Only `client.py` talks to the network**, and only to the login service.
+- **No personal data** in code, tests, fixtures, docs or commit messages: use `example.com` and invented values.
+- Keep the API stable within a minor version; say in the pull request what a change does to existing users.
+
+AGENTS.md has the same rules for coding agents.
+
+## How changes land
+
+Each release of this repository is exported from a private working repository as one
+`Release X.Y.Z` commit, so pull requests are not merged here: the next release would replace
+them. When a change fits, the maintainer applies it there, credits you in the release notes
+and closes the pull request with a link to the release that contains it. Issues are welcome;
+answers are best effort.

signin_window-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 benjamin-di
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

signin_window-0.1.2/Makefile

@@ -0,0 +1,7 @@
+.PHONY: bootstrap check lock
+bootstrap:
+	uv sync --locked
+check:
+	./scripts/test.sh
+lock:
+	uv lock

signin_window-0.1.2/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.5
+Name: signin-window
+Version: 0.1.2
+Summary: Let a person sign in to a website themselves, from their own browser, in a remote browser window your server runs (noVNC sign-in links for MCP servers and other headless services)
+Project-URL: Homepage, https://github.com/benjamin-di/signin-window
+Project-URL: Issues, https://github.com/benjamin-di/signin-window/issues
+Author: benjamin-di
+License-Expression: MIT
+License-File: LICENSE
+Keywords: login,mcp,model-context-protocol,novnc,playwright,remote-browser,sign-in
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: anyio>=4
+Requires-Dist: starlette<2,>=0.40
+Requires-Dist: websockets>=13
+Description-Content-Type: text/markdown
+
+# signin-window
+
+Let a person sign in to a website **themselves**, from their own browser or phone, in a browser window that runs on
+your server. Your server keeps the session afterwards; the password, the one-time code and the site's checks stay
+with the person.
+
+It is made for [MCP](https://modelcontextprotocol.io) servers and other headless services that act on a site for
+someone (shops, rides, photos, mail) but should never hold their password or automate a sign-in. Your assistant
+calls a tool, gets a one-time link, and gives it to the person. They open the site's own sign-in page through that
+link, and the page notices when they are in.
+
+```
+person's browser ──https──> your server (relay) ──private network──> login service
+  the link's page              /connect/<id>                          Xvfb + x11vnc + Chromium
+  noVNC viewer  <──────────── live view (WebSocket) ────────────────  on the site's sign-in page
+```
+
+- **The login service** (`signin_window.service`) runs sign-in windows: a virtual display, a remote-desktop server
+  on loopback, and your *runner*, which opens the site's sign-in page on that display (with Playwright, say) and
+  waits until the site has signed the person in. It stays on a private network, behind a bearer.
+- **The relay** (`signin_window.relay`) runs in your server: one-time links, their page, noVNC's files and the live
+  view, carried through to the login service. When the window ends, your hook stores the session.
+- **The paste add-on** lets the person paste into the remote page with Ctrl+V (Cmd+V), which noVNC alone does not.
+
+Nothing in the package clicks, types or fills anything: the person does every step of the sign-in.
+
+## Install
+
+```sh
+pip install signin-window
+```
+
+Python 3.11 or later. The login service runs on Linux with `Xvfb`, `x11vnc`, noVNC 1.5 or later (its static files)
+and a browser; [`examples/minimal/Dockerfile`](examples/minimal/Dockerfile) builds one. Use Debian trixie's Xvfb and
+x11vnc (CI runs the end-to-end check there): on Ubuntu 24.04's, the live view showed the window but no click or key
+reached it.
+
+## The login service
+
+A runner gets a `Window`. It opens the sign-in page on the window's display, calls `window.waiting(host)` once the
+page is up (the live view opens only then), and returns the session when the site has signed the person in:
+
+```python
+import asyncio
+
+from playwright.async_api import async_playwright
+from signin_window.hosts import allowed, host_resolver_rules
+from signin_window.service import Windows, build_app
+
+HOSTS = ("example.com",)
+
+async def sign_in(window):
+    async with async_playwright() as p:
+        context = await p.chromium.launch_persistent_context(
+            window.temp_profile(), headless=False, env=window.env(), no_viewport=True,
+            args=[f"--host-resolver-rules={host_resolver_rules(HOSTS)}", "--window-position=0,0"],
+        )
+        await context.route("**/*", lambda r: r.continue_() if allowed(r.request.url, HOSTS) else r.abort())
+        page = await context.new_page()
+        await page.goto("https://www.example.com/signin")
+        window.waiting("example.com")
+        while not window.cancelled.is_set():
+            cookies = await context.cookies()
+            if any(c["name"] == "session" for c in cookies):
+                return {"cookies": cookies}          # handed over to the server, once
+            await asyncio.sleep(1)
+
+app = build_app(Windows(sign_in), token=TOKEN, novnc_dir="/opt/novnc")
+```
+
+[`examples/minimal/login_service.py`](examples/minimal/login_service.py) is the complete version.
+
+A window ends in one of two ways:
+
+- **Hand-over**: the runner returns the session. It waits up to five minutes to be taken, once, by the server, then
+  it is dropped. The login service keeps nothing.
+- **Kept**: the runner keeps the session itself (a browser profile it refreshes, a snapshot it writes for the server
+  to read) and calls `window.finish("connected")`, or another final state of its own such as `"wrong_account"`.
+  `window.report(account=...)` adds public fields to the window's state. Pass a `lock` to `Windows` if a keeper
+  uses the same profile.
+
+A runner can be a plain function too (it runs in a thread and should watch `window.cancelled`), or a command:
+`signin_window.child.run_child(window, argv)` runs it on the window's display and follows its progress lines
+(`SIGNIN {"state": "waiting"}` ... `SIGNIN {"state": "signed_in", ...}`), which suits sign-in code that is
+synchronous or someone else's.
+
+`Windows` options: `slots` (windows at a time, each with its own display), `minutes` (time limit), `xvfb` and
+`x11vnc` (binaries), `lock` and `lock_wait`, `display_base` and `vnc_base` (window *n* uses display
+`display_base + n` and VNC port `vnc_base + n` on loopback). `build_app` options: `start_params(body)` turns a start
+request into the window's `params` (raise `ValueError` to refuse it; a `"key"` param makes a newer window for the
+same key cancel the older), `title` for the plain view page, and `routes` of your own behind the bearer.
+
+The service's API (`build_app`): `POST /logins`, `GET /logins/{id}`, `POST /logins/{id}/result` (the session, once),
+`DELETE /logins/{id}`, `WS /logins/{id}/vnc?t=` (the live view, with the window's view token), `GET /view/{id}?t=`
+(a plain page showing the window, for someone on the service's own network), `GET /novnc/...` and `GET /health`.
+
+## The relay, in your server
+
+```python
+from signin_window.client import LoginClient
+from signin_window.page import PageText
+from signin_window.relay import Relay
+
+def store(link, session):
+    save_session(link.key, session["cookies"])  # yours
+    return "connected"
+
+relay = Relay(
+    LoginClient("http://login:8080", TOKEN),
+    "https://mcp.example.com/connect",
+    text=PageText(service="Example", secure_host=r"(^|\.)example\.com$"),
+    on_signed_in=store,
+)
+app.routes.extend(relay.routes("/connect"))   # outside your server's bearer
+
+link = relay.create(account_id)               # in your connect tool
+return {"url": link.url, "expires_at": link.expires_at}
+```
+
+A link works for `link_ttl` (20 minutes) and one successful sign-in, up to `max_starts` windows (a reload or "try
+again" opens a new one); a newer link for the same key replaces it, and each key gets `links_per_hour` links. Its id
+has 192 random bits; requests for ids that do not exist are counted per client address (from `X-Forwarded-For`, or
+your `client_address`) and slowed long before guessing could matter, without ever locking a real link out.
+
+Hooks run one at a time, in a worker thread:
+
+- `on_signed_in(link, session) -> state`: check the session and store it for `link.key`. Return `"connected"`, or a
+  state of your own the page has a message for (`"wrong_account"`, say). Anything else, or an exception, is
+  `"failed"`.
+- `on_ended(link, window_state) -> state`: the window ended without a hand-over. By default its state is kept when
+  the page has a message for it (a kept session's `"connected"`), else `"failed"`.
+
+`link.show(name=...)` adds public fields to the link's state, which the page's messages can use (`{name}`).
+
+`PageText` holds everything the page says: `service`, `title`, `help_html`, `intro_html` (with `{service}` and
+`{label}`), `button`, `secure_host` (a host it matches gets a padlock), `starting`, `waiting`, `outcomes` (state ->
+message; `with_outcomes(...)` adds your own) and `script_extra` (it may define `window.signinBeforeStart`, an async
+function that must return true before a window opens, for an invite code the person enters first, say).
+
+The relay talks to the login service through `LoginClient`; any object with the same methods (`Backend`) works,
+for a login service of another shape.
+
+## Security
+
+- The login service never faces the internet: put it on a private network with your server. Every route but
+  `/health`, noVNC's files and the person's own view needs its bearer (32+ characters); a window's live view needs
+  that window's view token, which only the caller that started it gets, and it is open only while the sign-in page
+  is shown (`waiting`). The VNC server listens on loopback without a password; the service's WebSocket bridge is
+  the only way in.
+- A link's id is its credential. Pages are `no-store`, `no-referrer`, not framable, with a strict
+  Content-Security-Policy; nothing in the link's state or page is ever the session.
+- Keep the window on the site: `signin_window.hosts` checks every request against the site's hosts and makes every
+  other host unresolvable for the browser, so neither a link on the page nor a redirect turns the window into a
+  general browser. On a shared login service, also lock the browser down with Chromium's policies (no file
+  access, no extensions, no other profiles).
+- A hand-over session leaves the login service once, to your server's hook, and is dropped if nobody takes it.
+- Passkeys do not work in a remote window (they need the person's own device nearby): people sign in with a
+  password and a code.
+
+Report vulnerabilities privately ([SECURITY.md](SECURITY.md)).
+
+## Development
+
+```sh
+make bootstrap   # uv sync --locked
+make check       # lint, format, tests
+uv sync --group browser && uv run playwright install chromium && uv run pytest tests/test_paste_dom.py
+NOVNC_DIR=/opt/novnc uv run --group browser python scripts/e2e.py   # with Xvfb and x11vnc installed
+```
+
+`scripts/e2e.py` runs the whole path with real browsers and a stand-in site: a link, its live view, paste, a
+hand-over and closing the page; CI runs it on every change.
+
+## License
+
+MIT

signin_window-0.1.2/README.md

@@ -0,0 +1,176 @@
+# signin-window
+
+Let a person sign in to a website **themselves**, from their own browser or phone, in a browser window that runs on
+your server. Your server keeps the session afterwards; the password, the one-time code and the site's checks stay
+with the person.
+
+It is made for [MCP](https://modelcontextprotocol.io) servers and other headless services that act on a site for
+someone (shops, rides, photos, mail) but should never hold their password or automate a sign-in. Your assistant
+calls a tool, gets a one-time link, and gives it to the person. They open the site's own sign-in page through that
+link, and the page notices when they are in.
+
+```
+person's browser ──https──> your server (relay) ──private network──> login service
+  the link's page              /connect/<id>                          Xvfb + x11vnc + Chromium
+  noVNC viewer  <──────────── live view (WebSocket) ────────────────  on the site's sign-in page
+```
+
+- **The login service** (`signin_window.service`) runs sign-in windows: a virtual display, a remote-desktop server
+  on loopback, and your *runner*, which opens the site's sign-in page on that display (with Playwright, say) and
+  waits until the site has signed the person in. It stays on a private network, behind a bearer.
+- **The relay** (`signin_window.relay`) runs in your server: one-time links, their page, noVNC's files and the live
+  view, carried through to the login service. When the window ends, your hook stores the session.
+- **The paste add-on** lets the person paste into the remote page with Ctrl+V (Cmd+V), which noVNC alone does not.
+
+Nothing in the package clicks, types or fills anything: the person does every step of the sign-in.
+
+## Install
+
+```sh
+pip install signin-window
+```
+
+Python 3.11 or later. The login service runs on Linux with `Xvfb`, `x11vnc`, noVNC 1.5 or later (its static files)
+and a browser; [`examples/minimal/Dockerfile`](examples/minimal/Dockerfile) builds one. Use Debian trixie's Xvfb and
+x11vnc (CI runs the end-to-end check there): on Ubuntu 24.04's, the live view showed the window but no click or key
+reached it.
+
+## The login service
+
+A runner gets a `Window`. It opens the sign-in page on the window's display, calls `window.waiting(host)` once the
+page is up (the live view opens only then), and returns the session when the site has signed the person in:
+
+```python
+import asyncio
+
+from playwright.async_api import async_playwright
+from signin_window.hosts import allowed, host_resolver_rules
+from signin_window.service import Windows, build_app
+
+HOSTS = ("example.com",)
+
+async def sign_in(window):
+    async with async_playwright() as p:
+        context = await p.chromium.launch_persistent_context(
+            window.temp_profile(), headless=False, env=window.env(), no_viewport=True,
+            args=[f"--host-resolver-rules={host_resolver_rules(HOSTS)}", "--window-position=0,0"],
+        )
+        await context.route("**/*", lambda r: r.continue_() if allowed(r.request.url, HOSTS) else r.abort())
+        page = await context.new_page()
+        await page.goto("https://www.example.com/signin")
+        window.waiting("example.com")
+        while not window.cancelled.is_set():
+            cookies = await context.cookies()
+            if any(c["name"] == "session" for c in cookies):
+                return {"cookies": cookies}          # handed over to the server, once
+            await asyncio.sleep(1)
+
+app = build_app(Windows(sign_in), token=TOKEN, novnc_dir="/opt/novnc")
+```
+
+[`examples/minimal/login_service.py`](examples/minimal/login_service.py) is the complete version.
+
+A window ends in one of two ways:
+
+- **Hand-over**: the runner returns the session. It waits up to five minutes to be taken, once, by the server, then
+  it is dropped. The login service keeps nothing.
+- **Kept**: the runner keeps the session itself (a browser profile it refreshes, a snapshot it writes for the server
+  to read) and calls `window.finish("connected")`, or another final state of its own such as `"wrong_account"`.
+  `window.report(account=...)` adds public fields to the window's state. Pass a `lock` to `Windows` if a keeper
+  uses the same profile.
+
+A runner can be a plain function too (it runs in a thread and should watch `window.cancelled`), or a command:
+`signin_window.child.run_child(window, argv)` runs it on the window's display and follows its progress lines
+(`SIGNIN {"state": "waiting"}` ... `SIGNIN {"state": "signed_in", ...}`), which suits sign-in code that is
+synchronous or someone else's.
+
+`Windows` options: `slots` (windows at a time, each with its own display), `minutes` (time limit), `xvfb` and
+`x11vnc` (binaries), `lock` and `lock_wait`, `display_base` and `vnc_base` (window *n* uses display
+`display_base + n` and VNC port `vnc_base + n` on loopback). `build_app` options: `start_params(body)` turns a start
+request into the window's `params` (raise `ValueError` to refuse it; a `"key"` param makes a newer window for the
+same key cancel the older), `title` for the plain view page, and `routes` of your own behind the bearer.
+
+The service's API (`build_app`): `POST /logins`, `GET /logins/{id}`, `POST /logins/{id}/result` (the session, once),
+`DELETE /logins/{id}`, `WS /logins/{id}/vnc?t=` (the live view, with the window's view token), `GET /view/{id}?t=`
+(a plain page showing the window, for someone on the service's own network), `GET /novnc/...` and `GET /health`.
+
+## The relay, in your server
+
+```python
+from signin_window.client import LoginClient
+from signin_window.page import PageText
+from signin_window.relay import Relay
+
+def store(link, session):
+    save_session(link.key, session["cookies"])  # yours
+    return "connected"
+
+relay = Relay(
+    LoginClient("http://login:8080", TOKEN),
+    "https://mcp.example.com/connect",
+    text=PageText(service="Example", secure_host=r"(^|\.)example\.com$"),
+    on_signed_in=store,
+)
+app.routes.extend(relay.routes("/connect"))   # outside your server's bearer
+
+link = relay.create(account_id)               # in your connect tool
+return {"url": link.url, "expires_at": link.expires_at}
+```
+
+A link works for `link_ttl` (20 minutes) and one successful sign-in, up to `max_starts` windows (a reload or "try
+again" opens a new one); a newer link for the same key replaces it, and each key gets `links_per_hour` links. Its id
+has 192 random bits; requests for ids that do not exist are counted per client address (from `X-Forwarded-For`, or
+your `client_address`) and slowed long before guessing could matter, without ever locking a real link out.
+
+Hooks run one at a time, in a worker thread:
+
+- `on_signed_in(link, session) -> state`: check the session and store it for `link.key`. Return `"connected"`, or a
+  state of your own the page has a message for (`"wrong_account"`, say). Anything else, or an exception, is
+  `"failed"`.
+- `on_ended(link, window_state) -> state`: the window ended without a hand-over. By default its state is kept when
+  the page has a message for it (a kept session's `"connected"`), else `"failed"`.
+
+`link.show(name=...)` adds public fields to the link's state, which the page's messages can use (`{name}`).
+
+`PageText` holds everything the page says: `service`, `title`, `help_html`, `intro_html` (with `{service}` and
+`{label}`), `button`, `secure_host` (a host it matches gets a padlock), `starting`, `waiting`, `outcomes` (state ->
+message; `with_outcomes(...)` adds your own) and `script_extra` (it may define `window.signinBeforeStart`, an async
+function that must return true before a window opens, for an invite code the person enters first, say).
+
+The relay talks to the login service through `LoginClient`; any object with the same methods (`Backend`) works,
+for a login service of another shape.
+
+## Security
+
+- The login service never faces the internet: put it on a private network with your server. Every route but
+  `/health`, noVNC's files and the person's own view needs its bearer (32+ characters); a window's live view needs
+  that window's view token, which only the caller that started it gets, and it is open only while the sign-in page
+  is shown (`waiting`). The VNC server listens on loopback without a password; the service's WebSocket bridge is
+  the only way in.
+- A link's id is its credential. Pages are `no-store`, `no-referrer`, not framable, with a strict
+  Content-Security-Policy; nothing in the link's state or page is ever the session.
+- Keep the window on the site: `signin_window.hosts` checks every request against the site's hosts and makes every
+  other host unresolvable for the browser, so neither a link on the page nor a redirect turns the window into a
+  general browser. On a shared login service, also lock the browser down with Chromium's policies (no file
+  access, no extensions, no other profiles).
+- A hand-over session leaves the login service once, to your server's hook, and is dropped if nobody takes it.
+- Passkeys do not work in a remote window (they need the person's own device nearby): people sign in with a
+  password and a code.
+
+Report vulnerabilities privately ([SECURITY.md](SECURITY.md)).
+
+## Development
+
+```sh
+make bootstrap   # uv sync --locked
+make check       # lint, format, tests
+uv sync --group browser && uv run playwright install chromium && uv run pytest tests/test_paste_dom.py
+NOVNC_DIR=/opt/novnc uv run --group browser python scripts/e2e.py   # with Xvfb and x11vnc installed
+```
+
+`scripts/e2e.py` runs the whole path with real browsers and a stand-in site: a link, its live view, paste, a
+hand-over and closing the page; CI runs it on every change.
+
+## License
+
+MIT