Identity That Survives: Sessions, Cookies, and Human Handoff

For camofox-browser, a browser session becomes genuinely useful when it can carry the right identity beyond one page and one process lifetime. This chapter traces that identity from an isolated BrowserContext through cookie import, persistence, reset, and optional human-assisted login. The practical judgment is where durability helps and where it increases risk: readers should be able to choose a transient or persistent session and explain why hashed paths, allowlists, and passwords are useful controls without treating them as encryption or complete authorization.

A BrowserContext is the unit of identity

The browser process is shared machinery. The BrowserContext is the unit that gives a user or agent a separate browser world. In camofox-browser's model, a userId maps to a Playwright context, and that context contains tab groups and tabs. Cookies and storage belong to the context, so two users can work through the same browser process without automatically seeing one another's logged-in state.

That separation answers a concrete question: why does an agent need a user identity at all if it already has a tab ID? A tab identifies a page surface; it does not by itself say whose cookies, local storage, proxy session, or permissions produced that page. The context supplies that surrounding state. A page at the same URL can show different controls to an anonymous user, a user with a valid login, or a user whose session has expired. Camofox therefore looks up a tab under the requesting user rather than treating a tab ID as a universal capability.

Tabs remain the working surfaces inside the context. They can be grouped by a session key, and the service tracks their access and tool activity. This lets one user keep more than one related page open while keeping the identity boundary above them. It also creates a lifecycle trade-off. A tab can be recycled when limits are reached, or a whole context can be closed after inactivity or a recovery event. The service is preserving the identity boundary, not promising that every page arrangement lives forever.

That distinction matters after a failure. If one tab becomes stuck, replacing it may lose the page's transient state while leaving the user's other tabs and context intact. If the context is poisoned by a proxy failure or has died, Camofox may recreate the context, which protects other users but changes the affected user's in-memory browser world. Persistence can restore selected storage after that transition, but it cannot replay every unsaved page interaction. Cookies and local storage can carry identity; they are not a recording of the current DOM, scroll position, or in-flight action.

Isolation is also not the same as a security sandbox. The repository's code and tests support application-level routing and separate BrowserContexts. They do not make arbitrary userId values trustworthy, prevent an operator with filesystem access from reading a profile directory, or protect a shared host from every other process. The context is the right unit for browser state separation, but deployment authentication and filesystem protection still determine who can ask to use that state.

Persistence is a lifecycle, not a file copy

The persistence plugin turns selected context state into a durable profile. Before a new context is created, it looks for saved Playwright storage state for the user and adds that state to the context options. After a context exists, the plugin can checkpoint the state when cookies are imported, when the session is closed, when another plugin exports storage, and when the server shuts down. This ordering is important: restoration happens before the page begins its new work, while checkpointing on session destruction happens while the context is still alive.

The saved directory is derived from a SHA-256 hash of the user ID. This serves two practical purposes.