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 againstmonosurf 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
profile rm when the intended action is to delete a browser
identity.
Commands
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
- MonoSurf opens the selected managed profile at the site’s login page.
- A person completes authentication in the browser.
- MonoSurf labels the profile when it can detect the account.
- The browser keeps its live authenticated session.
- MonoSurf saves an encrypted session snapshot as a bootstrap backup.
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
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
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
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.