Extension account and guided walks
The extension adds an account session and a guided Walks experience to the browser. The account session gives the extension access to personas and Walks services without exposing tokens to pages. A Walk then moves a selected persona through a web page under user-visible controls, safety checks, and a shared side-panel view. See Browser extension product, Extension page integration, and DevTools and popup interfaces for the surrounding product and browser surfaces.
Account lifecycle
Account session
The extension signs in as a public OAuth client. It uses a code flow with PKCE and asks only for account and persona access until the account server offers extra Walks or persona-create scopes. Production is always allowed; staging and local servers are limited to development builds. The account server must describe endpoints on its own origin or its paired app origin before the extension uses them. References: extension/…/flow.js• L1-18, extension/…/flow.js• L20-26, extension/…/flow.js• L50-75
The session keeps the long-lived refresh grant in extension-owned IndexedDB. Short-lived access tokens stay in the background worker. A sign-in callback is accepted only when its callback URL, state, issuer, and code match the request. Sign-out removes local access at once and retries remote grant removal when the server is reachable. References: extension/…/session.js• L1-14, extension/…/session.js• L20-47, extension/…/session.js• L55-64, extension/…/session.js• L452-483
Account capabilities
The background account service is the only account boundary for the popup and Walks side panel. It reports account facts, personas, apps, journey history, Pro access, and service errors. It never returns an access or refresh token to a UI surface, content script, page, or other extension. References: extension/…/worker.js• L1-7, extension/…/worker.js• L21-31, extension/…/worker.js• L55-72, extension/…/worker.js• L262-275
The account server remains the source of truth for Pro access and supported request fields. The extension remembers server capability results per server so an older server can still receive a valid request. It also keeps an in-progress persona creation request in session storage and reuses its request ID after a worker restart, so a retry does not create a duplicate persona. References: extension/…/session.js• L317-344, extension/…/session.js• L391-413, extension/…/worker.js• L134-145, extension/…/worker.js• L178-209
Agent check-ins
When a signed-in Pro account is active, the extension checks in with the account server at startup and on a short alarm. The server can return journeys that an external agent is waiting for. Each new journey becomes a browser notice with Start and Not now. Start opens only a valid Impeccable outing page; Not now is sent back to the server and is retried until acknowledged. References: extension/…/waiting.js• L1-19, extension/…/waiting.js• L21-75, extension/…/waiting.js• L78-116
Walk entry
Walk preparation
The Walk side panel is the main preparation surface. The user selects a persona, writes a task, chooses a screen width and optional way of seeing the page, then reviews a short plan before starting. An approved plan lets the Walk run without asking again for the steps already approved. References: extension/…/panel.js• L229-287, extension/…/panel.js• L639-652, extension/…/panel.js• L725-772, extension/…/worker.js• L117-123
The account worker turns that choice into a server request tied to the active web tab. It accepts only an HTTP or HTTPS tab, trims and bounds the task, rejects a second live Walk, and passes the server’s handoff to the Walk runtime. If the server creates a Walk but the extension cannot adopt it, the worker cancels that Walk so an abandoned server journey does not block the next one. References: extension/…/worker.js• L99-115, extension/…/worker.js• L148-175, extension/…/session.js• L415-438
Walk handoff
The Walk handoff is a short, checked block that identifies the outing, its socket, a one-use ticket, the persona, the task, the starting page, and allowed origins. A handoff from an Impeccable outing page is accepted only from the top frame of that page. A Walk started from the extension is accepted only when its socket belongs to the chosen account server and its starting site is not an Impeccable page. References: extension/…/handoff.js• L1-6, extension/…/handoff.js• L70-75, extension/…/handoff.js• L115-179, extension/…/link.js• L139-198
The handoff opens one browser connection for the server’s Walk engine. The ticket is kept in extension session storage and is spent when the connection opens. Before a tab is attached, a lost connection may request a fresh ticket by reloading the outing page. Once the debugger controls a tab, a lost connection ends the Walk because the engine cannot resume that tab safely. References: extension/…/link.js• L1-19, extension/…/link.js• L59-137
This diagram shows the two supported routes into a guided Walk.
flowchart LR
U[User chooses persona and task] --> P[Side panel plan]
P --> S[Account worker]
S --> A[Walk service]
A --> H[Checked handoff]
H --> W[Walk worker and browser tab]
G[External agent request] --> N[Account check-in]
N --> O[Start notice]
O --> H
W --> V[Side panel and tab controls]
Page instrumentation
Outing page instrumentation
The extension instruments only Impeccable’s own Walk start pages. A small marker tells the web app that the extension is present and gives its version. On an outing page, a content script reads one JSON handoff block and sends its text to the background worker; it does not accept page events or window messages as a handoff source. References: extension/…/present.js• L1-8, extension/…/handoff-content.js• L1-19
The outing content script watches for a block added later by the app and keeps a connection to the worker while a Walk waits for its tab. A trusted click on a page control marked for the extension can open the side panel. These hooks let a web app start or expose a Walk without giving the web page authority over the Walk’s validation or controls. References: extension/…/handoff-content.js• L22-45, extension/…/link.js• L201-223
Walk page instrumentation
Once a Walk owns a tab, it uses an isolated browser control layer to inspect the page, take screenshots, read accessibility information, and perform allowed actions. Generated page helpers provide the page reads and actions used by the Walk service. The extension also carries consent rules that can run in the page’s own world when an older service needs to read consent state. References: extension/…/driver.js• L1-9, extension/…/driver.js• L1424-1445, extension/…/page-helpers.js• L1860-1875
The inspection layer avoids sending secret field values and keeps extension controls out of the persona’s screenshots. The page is read through fixed helpers rather than arbitrary page code. The browser badge and glow are hidden while the Walk takes a picture or reads the page, then return for the user’s control. References: extension/…/signin.js• L1-19, extension/…/inspect.js• L1-4, extension/…/badge.js• L1-15, extension/…/badge.js• L255-290
Consent boundaries
Page consent
A consent page is a page that grants an app or account access, such as a supported OAuth or app-install page. The guided agent does not open or operate those pages. Instead, the extension leaves the action to the person in the browser and tells the agent to wait. This boundary applies even when the site would otherwise be on the Walk allow-list. References: extension/…/guard.js• L99-115, extension/…/agent.js• L55-65, extension/…/agent.js• L156-171
Consent handling also covers common cookie and privacy prompts. The bundled consent rules detect and handle supported consent managers for the Walk’s inspection needs, while the bridge reports only bounded status back to the worker. This is separate from the user’s approval of a destructive action or a new site. References: extension/…/consent-rules.js• L1-35, extension/…/driver.js• L653-657, extension/…/page-helpers.js• L1860-1865
User approval
The Walk pauses before a server-marked deed such as delete, pay, or send. A Walk of the user’s own tab also asks before a move to another site. The side panel and the in-page badge show the same question, and the action does not continue until the person answers. A timeout is treated as a refusal. References: extension/…/control.js• L119-153, extension/…/control.js• L155-217, extension/…/panel.js• L779-793
The safety guard limits the Walk to one tab and approved origins. It blocks top-level navigation away from the allowed sites, rejects requests that name another tab, and holds writes until the server or the person opens them. A user-approved move to another site is read-only for the Walk. References: extension/…/guard.js• L127-164, extension/…/guard.js• L197-223, extension/…/guard.js• L231-265, extension/…/net-hold.js• L1-25
Control surfaces
Side panel controls
The side panel presents the account, persona selection, plan approval, live Walk, history, and result view. During a Walk it shows the current persona, task steps, questions, pauses, and outcome. Its controls are Stop, Continue after a normal pause, I’ve signed in, Hand back after a takeover, and answers to approval questions. Only the side panel may send Walk control commands. References: extension/…/panel.js• L1-5, extension/…/panel.js• L775-821, extension/…/control.js• L246-344
Tab controls
The tab badge gives the user a control surface even when the side panel is closed. It shows who is active, the current step, Stop, and any pending approval. A gold edge glow marks active Walk control. The toolbar icon opens the side panel in Chrome and changes its browser-provided title for sign-in pauses or server shutdowns. References: extension/…/badge.js• L180-215, extension/…/toolbar.js• L1-20, extension/manifest.json• L39-48
Agent controls
The extension can also host the user’s local browser agent through native messaging. The agent uses the same Walk guard, pause rules, tab controls, and panel log as a server persona, but its first site requires the user’s Allow once, Always allow, or Not now choice. Always-allowed sites are kept in local browser storage and can end a session when removed. References: extension/…/agent.js• L1-14, extension/…/agent.js• L68-90, extension/…/agent.js• L335-455
State and presentation
Account state
Account state is split by lifetime and sensitivity. IndexedDB holds durable refresh grants. Local storage holds the selected account server and user preferences such as server capability results. Session storage holds temporary Walk handoffs, the current Walk view, persona creation recovery data, and the one-time connected or waiting markers. Tokens remain in the account worker. References: extension/…/session.js• L20-47, extension/…/session.js• L107-114, extension/…/worker.js• L28-45, extension/…/worker.js• L252-259
Walk state
The Walk state is one shared view with states such as waiting, walking, paused, takeover, done, stopped, and failed. The worker reduces events into that view and writes it to session storage. The side panel reads the same view, so socket events, user controls, badge text, and final results do not form separate state machines. A worker restart marks a Walk that was controlling a tab as failed because the debugger connection is gone. References: extension/…/view.js• L1-24, extension/…/view.js• L58-160, extension/…/store.js• L1-35
Walk presentation
The panel changes its presentation from account entry to persona selection, planning, live progress, and results. It keeps the live step list and shows the result link only when it belongs to the Walk’s paired app and socket host. History lists completed journeys and opens only validated Impeccable journey pages. References: extension/…/panel.js• L870-941, extension/…/panel.js• L944-1035, extension/…/panel.js• L1187-1240, extension/…/handoff.js• L58-75
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the OAuth issuer, paired app origin, resource name, redirect checks, and server capability flags aligned across flow.js, session.js, and account/worker.js.
- Keep token records and recovery states compatible with worker restart points. A refresh token must be saved before its replacement is used.
- Keep the handoff schema, socket pairing, selected account server, and tab-origin checks aligned for both outing-page and extension-started Walks.
- Keep the side-panel control names aligned with control.js, the badge actions, and the state reducer so a visible control always has one valid owner.
- Keep page helper and consent-rule copies synchronized with the service’s helper contract and reported helper hash.
- Keep consent-page checks separate from user approval checks. A page the agent must not operate cannot become safe only because its origin is allowed.
- Keep session-stored Walk recovery data consistent with the debugger lifecycle. A worker restart must not leave a Walk shown as active when no tab is controlled.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| OAuth callback state, issuer, or callback URL does not match | The code is not exchanged and no grant is saved | PKCE, exact callback checks, and issuer checks reject the callback |
| Account worker restarts during sign-in or token refresh | The UI could lose the account or reuse a rotated token | Durable step states and committed IndexedDB writes let the next worker recover safely |
| The account server creates a Walk but the extension rejects its socket or tab | The server keeps a journey that no browser can run | The worker cancels the created Walk on the same server |
| An outing page sends malformed or cross-origin handoff data | An untrusted page could start a Walk or redirect its socket | Only the top frame of a valid outing page is accepted and every handoff field is checked |
| A Walk tries to leave its allowed site or write to another origin | The tab may navigate away or change an unrelated site | The guard blocks top-level navigation and network rules hold disallowed writes |
| A Walk reaches a consent page or a filled secret field | The agent could grant access or expose a secret | The agent pauses or refuses the page and the page reader omits secret values |
| The user closes or takes over the tab during an operation | A delayed action could run against a changed page | Control fences invalidate in-flight actions and the state view records the pause or end |
| The side panel or badge answers after a Walk ended | A late answer could change a new Walk | The reducer accepts controls only in the matching live state |
Key files
| File | Why to read it |
|---|---|
| extension/…/flow.js | Defines the extension OAuth client, trusted servers, scopes, and callback checks. |
| extension/…/session.js | Defines durable grants, token refresh, account reads, personas, plans, and Walk service calls. |
| extension/…/worker.js | Connects account actions to the popup, side panel, Walk handoff, and server capability checks. |
| extension/…/waiting.js | Connects agent check-ins to browser notices and outing pages. |
| extension/manifest.json | Shows the account, outing-page, side-panel, and permission boundaries. |
| extension/…/handoff.js | Defines which pages and handoff blocks can enter a Walk. |
| extension/…/link.js | Owns the handoff-to-socket lifecycle and reconnect rules. |
| extension/…/guard.js | Defines tab, origin, consent-page, navigation, and write boundaries. |
| extension/…/control.js | Coordinates user approval, pauses, takeovers, and Walk commands. |
| extension/…/view.js and extension/…/store.js | Define the shared Walk state and its session-storage lifetime. |
| extension/…/panel.js | Shows account entry, plan approval, live progress, history, and results. |
| extension/…/badge.js and extension/…/toolbar.js | Show the in-tab control surface and toolbar state. |
| extension/…/agent.js | Shows the local agent handoff and its shared browser controls. |
| extension/…/present.js and extension/…/handoff-content.js | Show how Impeccable outing pages detect and hand off to the extension. |
| extension/…/page-helpers.js, extension/…/signin.js, and extension/…/consent-rules.js | Show the bounded page reads, sign-in detection, and consent handling used during inspection. |