@amalgm/browser 0.1.2-preview.35541635545 → 0.1.2-preview.37254096068

package/docs/COOKIES.md

@@ -1,61 +1,104 @@
 # Cookies
 
-Browser has three separate security domains:
-
-1. the Amalgm application renderer and account session;
-2. the visible Electron `persist:amalgm-browser` partition;
-3. each headless Chromium profile store.
-
-The application renderer is outside Browser. Electron and headless stores are
-physically isolated and never read one another.
-
-## Logical jar
-
-Cross-backend portability occurs through one encrypted Browser cookie jar.
-Each trusted `BrowserCookieAdapter` reports a normalized snapshot or mutation;
-the coordinator merges records and applies changes back to other adapters.
-
-The record identity includes domain, path, name, and partition key. Merges use
-timestamp then source ID for deterministic last-writer-wins ordering. Deletes
-are durable tombstones, so a stale physical snapshot cannot resurrect a logged
-out cookie. One adapter update cannot replace unrelated records.
-
-Adapter baselines suppress feedback generated while applying jar changes.
-Failed application is retried. Partitioned identity is preserved; an adapter
-that cannot represent partitioned cookies skips them rather than flattening
-them.
-
-## Filtering
-
-The central boundary rejects application/authentication hosts, Amalgm API
-hosts, Supabase hosts, loopback, and configured exclusions. Filtering happens
-before secret persistence or propagation. Automatic synchronization moves
-cookies only; it never copies localStorage or sessionStorage.
+The account's encrypted jar (`cookie-jar.sqlite`) is the store of record.
+Chrome uses one account profile; Electron uses one persistent partition per
+account. Application authentication in Electron's `defaultSession` is outside
+Browser. Physical browser storage follows the browser's own storage policy.
+
+## Events and consequences
+
+| Event | Consequence |
+| --- | --- |
+| Physical cookie added, changed, expired, evicted or deleted | Commit that record or tombstone to the jar. |
+| Jar transaction committed | Notify the new revision; deliver only records changed since the receiver's acknowledged revision. |
+| Adapter connected, or Chrome restarted the observer's stopped worker | Read one snapshot and reconcile that physical store. |
+| Live revision stream ended after delivering | Rejoin it once. A refused stream is not retried. |
+| Runtime binding published or native cookie changed while disconnected | Attempt the connection with the current credentials. |
+| Account closed | Drain admitted changes, unsubscribe and release resources. |
+
+Chrome's SDK-owned private extension listens to `chrome.cookies.onChanged`.
+It observes HttpOnly and partitioned cookies independently of websites and page
+activity. Electron's `cookies.changed` supplies the same record information.
+Neither adapter installs website listeners, enables network observation, scans
+on input/actions, or runs a synchronization timer. A replacement's intermediate
+`overwrite` removal is followed by its insertion event and is not a logout.
+
+Each adapter serializes its events. Pending changes to the same identity
+coalesce while existing work is in flight; there is no debounce delay. Applying
+a jar change records its expected echo before writing the physical store.
+That echo never becomes a new local edit, including after an interrupted apply.
+On first contact, physical cookies contribute only identities the jar has never
+known. Stale disk cookies cannot resurrect a deletion; an observed new edit can.
+An unavailable store retains pending changes and waits for another cookie or
+host readiness event. No timer guesses when the runtime will be ready.
+
+The private authenticated stream carries value-free revision notifications.
+Cookie values travel only through the private delta endpoint. A new database
+epoch requires a snapshot; normal revisions use an indexed delta query. Each
+identity occupies one encrypted row. A row is forgotten once its cookie can
+no longer exist in any browser: at its expiry, and never more than 400 days
+(Chrome's lifetime cap) after its last change. A tombstone keeps the expiry of
+the cookie it buries; deleting an unknown, already-expired cookie writes nothing.
+Automatic synchronization moves cookies only, never origin storage.
+
+Custom adapters implement `subscribe` with `{cookie, removed}` records;
+`undefined` means observation restarted and requires reconciliation.
+Custom stores implement `changes(version)` with upserts, deletions and the
+acknowledged revision; `reset` requests a new connection snapshot. These are
+trusted adapter ports, separate from the value-free public event stream.
+
+## Records
+
+A record's identity is domain (including its host-only or domain scope), path,
+name, and partition key. Merges keep the
+newest change, ordered by change time and then source ID. Deletes are durable
+tombstones. Partitioned cookies keep their partition; an adapter that cannot
+represent partitions skips those cookies rather than flattening them.
+
+## Protected hosts
+
+The jar never stores and sync never moves or removes cookies for `amalgm.ai`,
+`supabase.co`, `supabase.io`, `supabase.in`, loopback hosts, or their
+subdomains. A `BrowserCookieJar` built by hand may add more excluded hosts.
 
 ## Encryption and failure behavior
 
-The jar uses AES-256-GCM with an integrity tag, atomic replacement, private
-directories, and mode `0600`. The local key is stored separately but on the
-same device. This prevents accidental plaintext exposure; it does not defend
-against an attacker able to read both ciphertext and key.
+Each row uses AES-256-GCM; HMAC identifiers hide cookie identities in the
+index. The revision counter holds no cookie data and is stored plainly. SQLite
+write-ahead-log transactions commit only touched rows, using a bounded page
+cache and private `0700` directories / `0600` files. A committed change
+survives an application crash (`synchronous=NORMAL`); Chrome itself writes
+cookies to disk in batches. The previous encrypted whole-file jar is imported
+transactionally on first open and then removed, so it is never a second writer.
+The key (`browser.key`) sits beside the jar on the same device. This prevents accidental plaintext exposure; it does not
+defend against an attacker who can read both the jar and the key.
 
-A missing or corrupt jar reports value-free health metadata and ordinary
-browsing continues with backend-local state. An incorrect key never causes
-cookie values to enter an error.
+If the jar is corrupt or the key is wrong, the jar reports itself unhealthy,
+sync stops, and browsing continues with whatever cookies Chrome already has.
+Cookie values never enter an error message.
 
 ## Public versus trusted APIs
 
-Ordinary SDK, CLI, MCP, REST, events, and Toolbox projections return only
-sanitized metadata such as domains, names, expiry, partition presence, count,
-and version. Raw values are available only to trusted in-process adapters or
-the separately credentialed loopback internal REST transport.
-
-Named auth bundles are a separate explicit snapshot mechanism. They may carry
-filtered origin storage and do not become the automatic jar.
-
-## Reconciliation lifecycle
-
-Register physical adapters with `browser.cookieAdapters`, then initialize the
-coordinator. The first available physical store may seed an absent logical jar
-exactly once. Thereafter the jar is authoritative. Subscribe to sanitized
-`cookie-jar.changed` events or version tokens rather than secret data.
+`browser.cookies` is the jar. Its `inspect()` returns value-free metadata:
+key, name, domain, path, expiry, partition presence, change time, and a
+version token. Actions, MCP, REST, events, and Toolbox never return cookie
+values. Raw values are available only in process or through the separately
+credentialed internal REST routes (see [REST](./REST.md)). Subscribe to
+`cookie-jar.changed` events for version changes.
+
+`@amalgm/browser/cookies` exports the jar, the coordinator, the encrypted file
+store, and the cookie policy helpers for hosts that build their own cookie
+stores.
+
+Named auth bundles are a separate, explicit snapshot (see
+[authentication](./AUTHENTICATION.md)). They may carry origin storage and are
+not the jar.
+
+## Performance contract
+
+After connection, an idle adapter performs zero cookie reads or writes. A
+sequence of N independent cookie changes performs zero full-store scans and
+at most N durable mutations; encrypted work and delta payloads depend on the
+changed records, not on the total jar size. Functional and performance evidence
+are separate: native Chrome/Electron tests verify event delivery, while the
+bounded load examination counts physical reads, encrypted rows, and writes.

package/docs/ELECTRON_INTEGRATION.md

@@ -1,93 +1,100 @@
 # Electron integration
 
-Electron is an optional peer dependency and appears only behind
-`@amalgm/browser/electron`. Headless consumers do not load it.
+`@amalgm/browser/electron` is the desktop app's in-app browser: native tabs
+the user browses in, with Browser's navigation policy, downloads, permissions,
+context menus, and ad blocking. Agents do not drive these tabs; agent sessions
+run in the runtime's Chrome (see [Chrome runtime](./CHROME.md)).
 
-The published Electron entry has both ESM and generated CommonJS conditions.
-Desktop builds may copy `electron.cjs` and `electron-preload.cjs` into their
-own generated output so Electron ships the native adapter without the full
-headless dependency graph. Both files are build products of Browser's
-TypeScript source and must never be edited or reimplemented by a host app.
+Electron is an optional peer dependency and loads only through this entry
+point. It has ESM and generated CommonJS conditions. Desktop builds may copy
+`electron.cjs` and `electron-preload.cjs` into their own output. Both are
+build products of Browser's TypeScript source; a host app must not edit or
+reimplement them.
 
-## Composition
+## What it exports
 
-The package contains both sides of the visible boundary:
+- `createBrowserShell({ accountId, cookieStore?, isTrustedAppUrl, isDev, adBlockFetch? })`
+  installs the account's IPC handlers and returns asynchronous `dispose`.
+- `createHttpCookieStore` and `readCookieAdapter` connect a trusted native host
+  to the runtime's separately credentialed cookie port.
+- `BROWSER_IPC`, the IPC channel names, and the typed payloads for tabs,
+  context menus, permissions, downloads, ad blocking, and shortcuts.
 
-- `createBrowserShell` owns native page sites, policy, downloads, permissions,
-  context menus, popup conversion, ad blocking, and safe teardown.
-- `createBrowserSurfaceController` owns automation surfaces, bounds,
-  presentation, capture, focus, find, zoom, and surface state.
-- `ElectronBrowserDriver` presents those verified surfaces to the Browser SDK.
-- host advertisement helpers publish a private, atomic loopback CDP bridge.
+The renderer supplies presentation and IPC wiring. It is not a browser-state
+authority.
 
-The application renderer supplies presentation and IPC wiring; it is not a
-browser-state authority.
+## Partition
 
-## Partition isolation
-
-Always obtain the physical Browser session with `getBrowserSession` or
-`isolatedBrowserSession`. Both require the exact partition:
+Every account uses a separate persistent partition:
 
 ```text
-persist:amalgm-browser
+persist:amalgm-browser-<sha256 of the Amalgm account ID>
 ```
 
-Do not pass Electron `defaultSession` to the shell or cookie adapter. The
-Browser partition owns its cookies, cache, storage, service workers,
-permissions, zoom, and request policy without touching application auth.
-
-## Surface identity
-
-Protocol 6 uses native page targets; protocol 5 remains a rolling-compatibility
-reader for the prior webview bridge. A requested automation surface receives a
-neutral marker URL, surface ID, and session stamp. The driver binds this
-identity and verifies it before every action.
-
-It never selects a target by order, target count, active tab, or URL. Identical
-URLs in two sessions remain distinct. A destroyed target may be reattached
-once only to the same verified identity. Mismatch or ambiguity fails before
-input, capture, or recording.
-
-## Native shell policy
-
-The shell provides:
-
-- safe `http`, `https`, and controlled external-protocol navigation
-- popup-to-tab and child-window disposition
-- page state, favicon, navigation, and load-failure events
-- back, forward, reload, focus, location, find, and zoom commands
+Each tab runs sandboxed in that partition with context isolation and web
+security on and Node integration off. Application authentication stays in
+Electron's `defaultSession`, which Browser never uses.
+The host retires the old account's views and adapter before activating another
+account. Signing out disposes the shell; native cookies remain in that account's
+partition for the next authenticated activation.
+
+## Native tabs
+
+The shell hosts each tab as a native `WebContentsView` created through
+`BROWSER_IPC.surfaceCreate`. The renderer places it over the tab's box with
+`surfaceUpdate`, sending the box exactly as it measures it, in its own CSS
+pixels. The shell scales the box by the renderer's zoom and puts each edge on
+the nearest whole window point, the only positions a native view can take.
+The view paints its own white page background, so the box under it paints
+nothing. A hidden tab's view stays in its window, invisible. Only the
+renderer that created a tab can update, command, capture, or destroy it, and
+its tabs close when that renderer navigates away or is destroyed. Capture
+returns the tab's current frame as a JPEG, or `null` when the tab paints no
+frame within two seconds. The first frame after a move or resize takes a few
+hundred milliseconds; the renderer decides how long to wait for it. Commands are
+navigate, back, forward, reload, focus, find, stop-find, and zoom. The preload
+reports `capabilities.version` 2 for this contract.
+
+## Shell policy
+
+- navigation limited to `http`, `https`, and `about`, with `mailto:` and
+  `tel:` handed to the OS
+- popups become tabs; real child windows stay windows
+- page state, favicon, navigation, and load-failure updates
 - spellcheck-aware context menus
-- unique basename-only download destinations and lifecycle actions
-- requesting-frame permission origins with fail-closed defaults
-- browser-only shortcuts and renderer ownership checks
-- off-screen parking and fixed automation viewport behavior
-
-The host maps these typed contracts to its visible chrome; the renderer should
-not reproduce their policy.
-
-## Cookies and ad blocking
-
-Construct `ElectronCookieAdapter` with the isolated partition's `Cookies`
-object. Its stable adapter ID is `electron:default-session` for historical jar
-compatibility; the object itself is never Electron `defaultSession`.
-
-`NativeAdBlocker` uses Ghostery-compatible filtering, a compiled cache,
-seven-day refresh, a last-good-cache fallback, cosmetic rules, scriptlets,
-mutation observation, and per-site settings. `AMALGM_BROWSER_ADBLOCK=0`
-disables it explicitly. Filtering is attached only to Browser contents, not the
-application renderer, API, or auth traffic.
-
-## Host advertisement
-
-`writeHostAdvertisement` validates a loopback CDP URL, writes atomically with
-private permissions, and records PID/protocol/target types. The selector
-rejects stale, dead, remote, or incompatible advertisements. Call
-`removeHostAdvertisement` during owner teardown; it only removes an
-advertisement owned by the expected PID.
+- basename-only download paths that never overwrite, plus download actions
+- permission prompts keyed to the requesting frame's origin, failing closed
+- browser shortcuts: focus location, new or close tab, find, reload, zoom
+
+## Ad blocking
+
+`NativeAdBlocker` uses Ghostery-compatible filter lists, a compiled cache
+under Electron's `userData/browser/adblock`, a seven-day refresh, a
+last-good-cache fallback, cosmetic rules, scriptlets, and per-site settings.
+`AMALGM_BROWSER_ADBLOCK=0` turns it off. It applies only to Browser tabs, not
+to the application renderer, API, or auth traffic.
+
+## Cookies
+
+When supplied a `cookieStore`, the shell registers `ElectronCookieAdapter` as
+`electron:account`. Native cookie records and jar revision notifications
+converge through the account's jar; disposal drains pending work. Shell publishes the Browser state root
+in its private runtime discovery record and a separate private adapter token
+in that root. The UI's Electron main process rediscovers the exact runtime and
+account for each connection; cookies and credentials never enter renderer IPC.
+The host passes `subscribeReady` to `createHttpCookieStore`, using its runtime
+publication events to reopen the authenticated stream when the binding changes.
+A stream that ends after delivering rejoins at once; a refused stream waits for
+that event. There is no reconnect timer. Native edits can also attempt a disconnected port.
+Offline native browsing retains its physical cookies; uncommitted edits remain
+pending during the active account connection. Tombstones prevent stale partitions from undoing a sign-out.
 
 ## Verification
 
-`npm run test:electron` runs a real macOS Electron harness. It checks the exact
-partition, two simultaneous same-URL surfaces, action isolation, failure before
-identity mismatch, one remount, CSS-pixel capture, fixed off-screen viewport,
-and page-only WebM recording.
+`electron-policy`, `electron-surface`, `electron-adblock`, and
+`electron-cookies` tests cover URL, popup, permission, and download policy,
+where a tab's page goes in a zoomed window, the ad-block cache and kill
+switch, and the cookie adapter against an injected partition store.
+The UI's source examination additionally drives actual Electron views and the
+Shell/Browser runtime, proving bidirectional cookies, scope, deletion, account
+switching, sign-out and fractional native bounds on the examined platform.

package/docs/EVENTS.md

@@ -1,23 +1,19 @@
 # Events
 
 Browser emits version-1 state transitions through an injected
-`BrowserEventSink`. `BrowserEventBus` provides a bounded standalone history and
-subscription implementation; REST exposes it as SSE.
+`BrowserEventSink`. `BrowserEventBus` provides a standalone implementation with
+subscriptions and a history of the last 1,000 events; REST exposes it as SSE.
 
-Event families are:
+The event types are:
 
 - `session.created`, `session.ready`, `session.closed`, `session.failed`
-- `surface.requested`, `surface.bound`, `surface.updated`, `surface.lost`
-- `page.navigated`, `page.failed`
-- `profile.updated`
+- `page.navigated`
 - `recording.started`, `recording.stopped`
 - `login.updated`
 - `cookie-jar.changed`
-- `download.updated`
-- `permission.requested`
 
 Every event has a stable random ID, ISO timestamp, version, and only the
-resource identifiers/metadata required by that transition. Navigation uses a
+resource identifiers and metadata that transition needs. Navigation uses a
 sanitized origin rather than a sensitive full URL. Error text is redacted and
 bounded. Cookie values, auth payloads, login tokens, storage contents, keys,
 authorization headers, and captured pixels are forbidden.

package/docs/MCP.md

@@ -18,18 +18,22 @@ browser_auth_save         browser_auth_load
 ```
 
 Schemas derive from the same action descriptor array used by CLI, REST, and
-Toolbox. The optional `session` field selects the persistent session; otherwise
-the adapter uses `default`.
+Toolbox. The optional `session` field selects the session. Without it, a call
+uses the caller's session: the `callerId` the host passes to
+`handle(message, context)`, such as the calling chat (see
+[Shell integration](./SHELL_INTEGRATION.md)). The stdio server passes no
+caller, so it uses `default`. The session is created on first use.
 
 `notifications/cancelled` aborts the active SDK operation identified by the
 JSON-RPC request ID. Text results are bounded. Captures are emitted as MCP image
 content when the result is an image. Recording and resource results contain
 sanitized metadata.
 
-Raw cookie values, auth payloads, encryption keys, bearer headers, and stored
-login token hashes are not MCP tools or resource output. Login-link creation is
-the deliberate one-time credential-delivery operation; callers must treat its
-returned token-bearing URL as a secret.
+Every result is sanitized: keys naming cookies, tokens, secrets, ciphertext,
+authorization, or web storage are dropped, and `?token=` values in strings are
+redacted. `browser_auth_link_create` therefore returns the login's metadata but
+never a usable login token; a host delivers login links through the SDK or
+REST (see [authentication](./AUTHENTICATION.md)).
 
 Toolbox uses a different compatibility namespace,
 `toolbox__browser_<action>`, documented in

package/docs/MIGRATION.md

@@ -1,14 +1,15 @@
 # Migration
 
-Browser preserves existing user state through path reuse plus a versioned
-legacy import. Migration is read-only with respect to the legacy Engine DB and
-is recorded as `engine-browser-v1` metadata in the new registry.
+Browser keeps existing user state through a versioned, one-time import from
+the legacy Engine database. The import only reads that database and records
+itself as `engine-browser-v1` metadata in the new registry.
 
 ## Automatic path
 
-When `createBrowser()` uses its normal `$AMALGM_DIR/browser` root, it checks
-for `$AMALGM_DIR/amalgm.db`. An explicit root does not guess a database;
-provide `legacyDatabaseFile` to opt in, or `false` to disable import.
+When `createBrowser()` is not given `root`, it looks for `amalgm.db` in the
+directory above the resolved root (for example `$AMALGM_DIR/amalgm.db`). An
+explicit root does not guess a database; pass `legacyDatabaseFile` to opt in,
+or `false` to turn the import off.
 
 ```ts
 const browser = createBrowser({
@@ -17,48 +18,54 @@ const browser = createBrowser({
 });
 ```
 
-The importer opens the old DB read-only and imports inside one new-registry
-transaction:
+The importer opens the old database read-only and imports inside one
+new-registry transaction:
 
-- `browser_profiles` into durable/ephemeral profile metadata;
-- ordinary `browser_auth_bundles` after hash and AES-GCM verification;
-- the `browser-cookie-source` bundle into record-level cookies and tombstones;
-- `browser_login_sessions` plus stored token hashes.
+- ordinary `browser_auth_bundles`, after hash and AES-GCM verification;
+- the `browser-cookie-source` bundle, into the account's cookie jar as
+  records and tombstones;
+- `browser_login_sessions`, with the token hashes of pending and active ones.
 
-The source database path is recorded only after successful completion. A
-second start reports `already-migrated` and makes no changes. A failure rolls
-back SQLite metadata and leaves the source untouched.
+Legacy profiles are not imported. Everything imported belongs to the runtime's
+account, so a user signed in before the upgrade stays signed in after it.
+
+The legacy key comes from `AMALGM_BROWSER_AUTH_KEY` (64 hex characters) or
+`auth-bundles/keys/local-device.key`. The source database path is recorded
+only after success. A second start reports `already-migrated` and changes
+nothing. A failure rolls back SQLite metadata and leaves the source untouched.
+
+The registry also imports `registry-v1.json` once when present and never
+deletes that file.
 
 ## State reused in place
 
-- Electron partition `persist:amalgm-browser`
-- `$AMALGM_DIR/browser` root and headless profile directories
-- existing project `.amalgm/recordings`
-- native Electron `userData/browser/adblock` cache and settings
-- bridge protocol 5 advertisement readers during rolling upgrade
-- legacy key from `AMALGM_BROWSER_AUTH_KEY` or
-  `auth-bundles/keys/local-device.key`
+- the `$AMALGM_DIR/browser` root
+- project `.amalgm/recordings` directories
+- the Electron ad-block cache and settings under `userData/browser/adblock`
 
-The new registry also imports `registry-v1.json` transactionally once when
-present. It never deletes that source file automatically.
+Native browsing now selects `persist:amalgm-browser-<account hash>`. The old
+unscoped `persist:amalgm-browser` partition is retained but is not adopted into
+an account: it has no reliable account owner. Verified legacy cookies imported
+into the runtime's account jar reach the new native partition through its
+ordinary cookie adapter.
 
 ## Verification checklist
 
 1. Stop all legacy Browser writers.
-2. Back up the Engine DB and Browser directory.
-3. Run import against a copy first.
-4. Compare profile, bundle, login, cookie-record, and tombstone counts.
-5. Open a durable headless profile and the isolated Electron partition.
-6. Load a named auth bundle and verify only its declared domains.
-7. Confirm DB/key/encrypted files are private and the source is unchanged.
-8. Re-run and confirm an idempotent no-op.
+2. Back up the Engine database and the Browser directory.
+3. Run the import against a copy first.
+4. Compare bundle, login, cookie-record, and tombstone counts.
+5. Browse a site the user was signed in to and confirm the sign-in carried
+   over.
+6. Load a named auth bundle and confirm only its declared domains load.
+7. Confirm the database, key, and encrypted files are private and the source
+   is unchanged.
+8. Start again and confirm the import is a no-op.
 
-Representative encrypted legacy fixtures exercise this sequence in the test
-suite.
+Encrypted legacy fixtures exercise this sequence in the test suite.
 
 ## Non-destructive rollback
 
 Before cutover, discard the new Browser root and continue from the untouched
-legacy source. After cutover writes occur, restore the complete pre-cutover
-backup rather than mixing formats or replaying selected files. Never copy
-cookies into a different Electron partition merely to normalize names.
+legacy source. After cutover writes, restore the complete pre-cutover backup
+rather than mixing formats or replaying selected files.