> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Auth Gate
> Time-limited read/write grants for MonoSurf site commands, with live-profile priority, protected session snapshots, explicit revocation, and clear boundaries.
# 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 ` 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
```text theme={null}
human grants a scope for a bounded duration
↓
site command declares read or write intent
↓
gate checks scope and expiry
├── denied or expired → stop before protected session use
└── allowed
↓
prefer the managed profile's live login session
├── live cookies present → continue with current browser state
└── empty jar → use the protected snapshot as bootstrap
↓
run the declared page command
```
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
```bash theme={null}
monosurf auth grant read 1h
monosurf auth grant write 30m
monosurf auth grant full 2h
monosurf auth revoke read
monosurf auth revoke all
monosurf auth status
```
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
| Scope | Allows | Relationship |
| ------- | ----------------------------------------------------------- | --------------------------------------- |
| `read` | Read-class site commands and their protected session access | Does not authorize write-class actions. |
| `write` | Write-class site commands | Also satisfies read checks. |
| `full` | Every gate scope | Covers both read and write. |
Use the narrowest scope and shortest duration that fits the task.
## Durations
| Suffix | Example | Meaning |
| ------ | ------- | ------- |
| `s` | `90s` | Seconds |
| `m` | `30m` | Minutes |
| `h` | `2h` | Hours |
| `d` | `7d` | Days |
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
```bash theme={null}
monosurf login x --profile work
```
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:
```bash theme={null}
monosurf bridge install
monosurf bridge example.com # add --keep for repeated Sync clicks
```
`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
```text theme={null}
plugin command
↓
check declared read/write scope
↓
connect to the selected profile
↓
verify that the managed CDP listener owns this profile's user-data directory
↓
query live cookies for the target domain
├── present → use them; skip snapshot
└── absent → read snapshot through the gate and hydrate the jar
↓
navigate and run the plugin command
```
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 ` 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
| State change | Stops | Does not do |
| -------------- | -------------------------------------------------- | ---------------------------------------------------------------- |
| Grant expires | New protected site-command access under that scope | Delete a managed profile, clear its live cookies, or stop Chrome |
| `revoke read` | The exact read grant | Remove an active write/full grant that also satisfies read |
| `revoke write` | The exact write grant | Remove an independent read or full grant |
| `revoke all` | Every stored grant | Delete browser or vault data |
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
```text theme={null}
managed Chromium profile
└── live cookies, local storage, saved browser state
OpenCLIs vault (preferred) or legacy secure fallback
└── login snapshots and other protected MonoSurf secret keys
auth gate state
└── scope, grant time, expiry time; no site cookie values
MonoPass companion
└── passkeys and WebAuthn/FIDO2 ceremonies outside the cookie-snapshot model
Monolex Agent Browser
└── same-profile managed login when complete browser state must stay together
```
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](/ai-clis/openclis-vault) for the stable protected storage
boundary, [MonoPass](/ai-clis/monopass) for passkeys/WebAuthn, and [Monolex CLI
/ Agent Browser](/ai-clis/monolex-cli) for the distinct same-profile handoff.
## Status Is Read-Only
```bash theme={null}
monosurf auth status
```
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
| Surface | Needs MonoSurf site grant? | Why |
| ------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------ |
| Public ephemeral browse | No | It has no stored login session by default. |
| Managed-profile browse | No site-plugin gate | It directly uses the selected browser profile; handle the profile as sensitive capability. |
| Site-plugin read command | Yes, `read`, `write`, or `full` | The plugin declares authenticated read intent. |
| Site-plugin write command | Yes, `write` or `full` | The plugin can change remote site state. |
| `login` | No pre-existing grant | A person is creating or refreshing the session; later use is gated. |
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
| Capability | Raw body | Authorization layer |
| ------------------------ | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Browser page/site plugin | Shared `lib-monosurf` facade and `lib-monosurf-core` through `monosurf` or `kernel-cli websurf` | MonoSurf read/write/full grant shared by both entry points |
| Native OS and desktop | [Kernel CLI](/kernel-cli) | Direct Kernel CLI is raw; NIIA can add OTP-gated control |
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.
Run grants, login, profile, site, doctor, and self-test commands.
Follow live-session priority and protected-snapshot fallback in context.
See how commands declare read or write intent.
Understand the separate native-control and NIIA harness boundary.