Skip to main content

Auth Gate

MonoSurf’s auth gate controls authenticated site-plugin commands with time-limited scopes. It separates the browser capability from permission to use that capability through the CLI. Verified against monosurf 0.11.3, OpenCLIs build 2026-07-19-222928.
The gate applies to site-plugin read and write commands and protected session snapshot access. A public, ephemeral monosurf browse <url> does not require a site grant. A grant also does not delete, close, or log out an existing managed browser profile when it expires.

The Model

Expiry changes authorization state. It does not erase Chrome’s own encrypted profile data. Use profile rm when the intended action is to delete a browser identity.

Commands

With no arguments, monosurf auth reports status. auth grant defaults to a write grant for 24h, but explicit scope and duration are clearer for people and automation.

Scopes

Use the narrowest scope and shortest duration that fits the task.

Durations

The maximum grant duration is 28 days. Each grant stores its issue and expiry time; no background timer is required. Every command checks the current time against the active grants.

Login and Session Snapshot

Login follows the current Chrome-style model:
  1. MonoSurf opens the selected managed profile at the site’s login page.
  2. A person completes authentication in the browser.
  3. MonoSurf labels the profile when it can detect the account.
  4. The browser keeps its live authenticated session.
  5. MonoSurf saves an encrypted session snapshot as a bootstrap backup.
The snapshot is not replayed over a healthy live session. This matters because sites rotate tokens: the live browser jar can advance while a frozen snapshot ages. An explicit bridge snapshot uses the same priority without pretending to be a profile clone:
bridge install first requires the Monolex desktop-staged shared host at ~/.niia/bin/monolex-native-host (.exe on Windows). It copies that host under the MonoSurf routing name and writes the native-messaging manifest. The standalone 0.11.3 archive does not bundle the shared host; absence is a non-zero prerequisite failure, even if unpacked extension assets were materialized first. After the user clicks Sync in the active logged-in tab, only matching cookies are stored. Before navigation, an empty live jar may be hydrated after every scope is validated; each cookie receives an explicit HTTP(S) origin and retains domain/path/HttpOnly/Secure/SameSite/expiry. Any invalid scope or CDP error fails the whole command. LocalStorage, IndexedDB, service workers, passwords, the Chrome profile, and the Chrome process are outside this path.

Per-Command Resolution

If the profile has neither a valid live session nor a usable snapshot, the website remains logged out and the command reports the failure instead of claiming authenticated access. The exact-port listener check in 0.11.3 is separate from the read/write grant. A valid grant does not authorize MonoSurf to adopt a foreign process that happens to occupy the profile’s CDP port; profile-backed connection fails before cookies or plugin actions reach that process. Intentional attachment to an externally owned application remains an explicit browse --cdp-url <endpoint> operation. New profiles skip active unregistered ports, and temporarily unknown ownership metadata is retried only for a bounded settle interval before failing closed.

What Expiry and Revocation Do

After revocation, run auth status to confirm which scopes remain. Delete or rotate the underlying browser identity separately when that is the security goal.

Secret Ownership

The preferred protected backend is openclis-vault, whose stable signing identity avoids reauthorizing keychain access after every MonoSurf update. When only the legacy secure store has a value, the gated read path can migrate it to the vault. auth status reports the backend for known keys without triggering that migration. See OpenCLIs Vault for the stable protected storage boundary, MonoPass for passkeys/WebAuthn, and Monolex CLI / Agent Browser for the distinct same-profile handoff.

Status Is Read-Only

Status reports active or expired grants, whether the vault binary is present, and which backend owns each known session key. It does not grant access, read cookie values, or move data.

Browse and Plugin Boundaries

The distinction is deliberate: the grant is a MonoSurf site-command authorization layer, not a universal sandbox around every possible CDP call.

Relationship to Kernel CLI and NIIA

Both designs separate capability from authorization, but they do not share one token or imply that MonoSurf’s grant controls Kernel CLI’s OS commands. The embedded kernel-cli websurf namespace does use the same MonoSurf grants, profiles, plugins, and state as the standalone CLI because both call the same facade and core engine.

Usage and Command Reference

Run grants, login, profile, site, doctor, and self-test commands.

How It Works

Follow live-session priority and protected-snapshot fallback in context.

Site Plugins

See how commands declare read or write intent.

Kernel CLI Reference

Understand the separate native-control and NIIA harness boundary.