# Browser Profile Isolation

Implementation task: `180.C.11.09`

Bellona browser automation uses Bellona-managed isolated Chrome/Chromium
profiles only. Personal browser profiles remain blocked at this stage.

This document is the operator and agent-facing policy for the Browser CDP MVP.
It summarizes the behavior implemented by the remote protocol schemas and the
remote-host browser adapter through `180.C.11.08`.

## Current Policy

- Browser commands must use `adapter:browser-local`.
- Managed browser sessions must use `capability:browser-managed-session`.
- `browser.launch_managed` creates a new Bellona-managed profile directory.
- `browser.navigate`, `browser.snapshot`, and `browser.screenshot` operate only
  against a launched managed browser session.
- `browser.close` closes the managed browser context and removes the managed
  profile by default.
- Chrome/Chromium remote debugging is bound to `127.0.0.1`; CDP is not exposed
  directly to LAN or internet.
- Real profile access is represented as blocked in adapter metadata, capability
  metadata, discovery output, and command metadata.

The allowed profile mode is `isolated`. Protocol browser command schemas reject
real-profile assumptions and require localhost-only CDP metadata. Host
capabilities advertise `browser.profile.isolated`; the adapter does not grant
`browser.profile.real`.

## Managed Profile Shape

The host creates browser profiles under the Bellona-managed profile root, which
defaults to the host runtime's browser profile directory. A caller may provide a
different managed root for tests or controlled deployments, but the root must
not be a recognized Chrome/Chromium user-data directory.

Every created profile:

- lives under the configured managed profile root
- uses a `bellona-profile-` directory prefix
- receives a `bellona-profile.json` marker
- records `isolated: true`
- records `personalProfileAccess: false`
- records cleanup strategy `rm_recursive_managed_path`

The host rejects roots and profile paths that look like real browser profile
locations, including Chrome/Chromium user-data roots, `Default`, and `Profile N`
directories. Cleanup also validates that the path remains inside the managed
root before recursive removal.

## Why Personal Profiles Stay Blocked

Personal browser profiles are not just local files. They are an authority
boundary for signed-in accounts and private browsing state. A profile can
contain cookies, session tokens, local storage, autofill data, browser
extensions, password-manager integration state, history, downloads, and cached
page data. Exposing that profile to a remote agent would let malicious pages,
prompt-injected content, or a compromised control path access state that the
operator did not explicitly grant.

The current Phase 180 browser stack is intentionally read-only after launch
except for managed-profile lifecycle and screenshot artifact creation. It does
not yet have the full set of controls required for real profile access:

- explicit per-profile grants and revocation
- operator approval UX for sensitive browser state
- cookie, storage, download, upload, extension, and password-manager policy
  boundaries
- origin-scoped allowlists and prompt-injection containment
- redaction rules for account pages and authenticated screenshots
- durable evidence-retention and deletion policy for sensitive browser data
- distributed locks for shared browser profile access
- rollback and compensating-action rules for account mutations
- manual hardware evidence on a real host profile

Until those controls exist and an ADR accepts the remaining risk, real personal
profiles remain out of scope.

## Audit And Timeline Expectations

Browser command audit entries must preserve enough context for later replay and
incident review without exposing personal profile contents:

- command id, device id, adapter id, capability id, and command name
- actor chain and participant id
- profile mode `isolated`
- localhost CDP metadata
- current page URL after blocked-domain enforcement
- screenshot artifact ids and evidence ids when screenshots are captured
- redaction status and redaction hook metadata for screenshot artifacts

Gateway timeline events merge command-store, audit-log, and artifact-store
events. After `180.C.11.08`, browser screenshot command results expose artifact
and evidence IDs in `command.completed`, `artifact.registered`, and
`command.result` timeline entries.

## Future Unlock Criteria For Real Profiles

Real profile access requires a later Phase 180 task or ADR to explicitly change
this policy. At minimum, that work must add:

- protocol fields that distinguish real profile grants from isolated profile
  sessions
- host policy preflight that denies real profile commands without an active
  grant
- an approval request that names the exact profile path, profile kind, page
  origin, command risk, retention policy, and rollback limitations
- host tests that prove real profile access cannot be reached through managed
  profile arguments, cleanup paths, command metadata spoofing, or gateway
  routing
- manual hardware evidence on a controlled test profile, not an operator's
  personal daily-use profile

Until then, agents must launch isolated profiles, navigate within the blocked
domain policy, capture artifacts with redaction metadata, and close the managed
session when finished.
