Browser Control extension

1Introduction

Some steps on a Company's website are ones the Company wants the User to take themselves, such as checking in for a flight. With this extension, the Company marks those steps in its pages, to indicate to the Personal Agent that the User should take them:

1. The Personal Agent browses the website in a browser joined to a Session (spec 6). It reads a marked step and prepares what the mark allows, but leaves the step to the User (4).
2. It tells the User that the step is theirs and offers them control of the browser. While the User holds control, the Personal Agent's model doesn't use the browser (5).
3. The User takes the step. The page can read who controls the browser from navigator.poppy.controller and send it with the request (6).
4. The User hands control back, and the Personal Agent continues.

Marks signal what the Company wants, and a Personal Agent that follows this extension honors them. navigator.poppy.controller should be correct, but a Company shouldn't use it as a guarantee that the User took a step. The Company still enforces its own rules on its servers (8).

Where it fits, the Operations extension gives the User a better experience (2).

This page defines version 1 of the browser-control extension. It uses the terms and Sessions in the specification.

2Browser control and Operations

Both extensions let a Company involve the User in an action, in different ways:

Operations is the better experience for the User when it fits. The User approves in the place they already talk to their Personal Agent, such as with a tap on their phone, without finding a browser window and learning the Company's page, or doesn't need to be asked at all when an instruction they gave covers the terms (Operations 5). The Personal Agent finishes the action, so the task doesn't wait on the User any longer than the approval. The Company gets more, too: an approval of exact terms, tied to the Session and, when signed in, the access token, and an action performed at most once (Operations 1).

A Company SHOULD use Operations for an action that it can describe as terms to approve. Browser control fits steps that Operations doesn't:

• Steps that are the User's to perform, not to approve. The Company wants the User to make the choice on its page, such as picking from options the page shows, rather than approving a choice the Personal Agent made.
• Input the Personal Agent shouldn't handle. The User types something into the page, such as passport details at check-in, so the Personal Agent doesn't need to collect it.
• Requests the website can't repeat. Operations on a website needs the browser to make the request again after the approval, and an action guarded by a single-use form token, for example, can't be (Operations 4).
• Websites without Operations yet. Marking steps needs no endpoint and no change to how the website handles requests.

A Company MAY use both for the same action, such as browser control for the User to check in for a flight and Operations for the User to approve the price of a paid seat.

3Advertising support

A Company that supports this extension lists it in extensions in its poppy.json (spec 3.3), with web.browser_session_endpoint (spec 6):

"extensions": {
  "browser-control": [{ "version": "1" }]
}

A Personal Agent that supports this extension declares it in Poppy-Extensions (spec 3.4):

Poppy-Extensions: "browser-control";v="1"

A browser's requests declare the extensions that step 2 of its browser join declared. Support means that the Personal Agent leaves marked steps to the User (4), hands control to the User (5), and provides navigator.poppy.controller (6).

A Personal Agent that doesn't declare this version may not read the marks at all. For its browser, the Company handles the step as it would without the extension.

4Marking steps

The Company marks a step with the data-poppy-user-step attribute:

<label>
  Passport number
  <input name="passport_number" data-poppy-user-step="interaction" />
</label>

<form action="/bookings/bkg_4Rt9/check-in" method="post" data-poppy-user-step="submission">
  <label>Seat <select name="seat">…</select></label>
  <button type="submit">Check in</button>
</form>

• A form's controls are the ones it owns in HTML, including controls outside it that name it in their form attribute.
• Marks add up. A control inside a submission form can also be marked interaction. A marked control doesn't mark the rest of its form.
• A value other than interaction or submission, or submission on anything but a form, counts as interaction.

The Company SHOULD mark every control that performs the step, or the form it is in, and SHOULD mark them before they can be used. The Company SHOULD NOT let filling in a submission form perform the step itself. Whatever it marks, the Company's servers MUST check the action's conditions themselves, because marks don't stop anything (8.1).

5Handing control to the User

A Personal Agent that declares this extension SHOULD NOT take a marked step: change or activate a control that a mark covers, or submit a form that a mark covers, whether with a click, a key press, an accessibility action, a script, or a WebMCP tool. It SHOULD NOT remove or change marks to get around them.

When it reaches a marked step, the Personal Agent tells the User which step is theirs and offers them control of the browser. It MAY instead leave the step undone and continue with other work. What the page says about the step is content from the Company (spec 10.1).

While the User holds control:

• The Personal Agent's software MUST NOT carry out browser actions from its model. The website's own scripts keep running.
• Only the User ends their control, by handing it back or cancelling. A timeout, a change to the page's marks, or anything the Company sends MUST NOT end it.
• The Personal Agent MUST NOT keep its own requests, or its conversation with the User, waiting until the User acts.

When the User hands control back, the Personal Agent looks at the page again before it continues.

6Who controls the browser

On pages of the Company's website, in a browser joined to a Session that declared this version, the Personal Agent's software provides navigator.poppy.controller, a read-only string:

• "user" while the User holds control (5).
• "agent" otherwise.

The page reads it when it needs it, such as when a marked button is pressed, and MAY send it to the Company with the request:

form.elements.controller.value = navigator.poppy?.controller ?? "";

In a browser without the extension, navigator.poppy is undefined. The Personal Agent's software, not its model, sets the value, and changes it as soon as control changes. It provides navigator.poppy only on the Company's website, on the hosts of organization.domain and its subdomains (spec 3.1), so other websites can't tell that the browser is a Personal Agent's.

The value should be correct, but it isn't a guarantee (8.2). A Company MAY record it with the action, or use it to choose what its page does, such as showing "This step is for you to complete" when it reads "agent". It MUST NOT rely on "user" as a guarantee that the User took the step.

7Example

The User asks their Personal Agent to check them in for their flight tomorrow, in an aisle seat. The airline's check-in form is marked submission:

1. The Personal Agent's browser opens the booking and chooses an aisle seat, which the mark allows.
2. It doesn't press Check in. It tells the User that the airline asks them to check in themselves, and offers them control.
3. The User takes control and presses Check in. The page reads navigator.poppy.controller, which is "user", and posts the form with it in a hidden field.
4. The airline records the value with the check-in and checks the User in.
5. The User hands control back. The Personal Agent reads the confirmation page and tells the User their boarding pass is ready.

Had the Personal Agent pressed Check in itself, the page would have read "agent". The airline decides what to do then, such as asking the User to take the step.

8Security considerations

8.1 Marks are signals

A mark asks the Personal Agent to leave a step to the User. It doesn't stop a Personal Agent that doesn't support this extension, or one that ignores it. The Company's servers decide whether an action is allowed, whatever the page marks.

8.2 The controller isn't a guarantee

A Personal Agent that follows this extension sets navigator.poppy.controller correctly. But the value isn't signed, and anything that runs in the page can change what the page reads, including the website's own scripts, third-party ones, and a Personal Agent that doesn't follow this extension. A value sent to the Company passes through the page, so it can be changed on the way too. The value tells the Company what a Personal Agent that follows this extension says about who controlled the browser. It doesn't show that the User took a step, saw what the page showed, or caused a particular request.

8.3 The User in the Personal Agent's browser

The specification forbids joining the User's own browser to a Session, so that the Company doesn't treat the User's own visits as the Personal Agent's (spec 6). Handing control to the User doesn't do that. The browser stays the Personal Agent's, and the User uses it through the Personal Agent for the length of the step. Its requests still belong to the Session, and navigator.poppy.controller tells the page who was in control when it read it.

9References

This extension uses the HTML Standard for form owners.