hop2 0.11.47 → 0.11.49

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Jian Zhou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README-MCP.md

@@ -221,8 +221,9 @@ Helper tools (`hopx_`): convenience wrappers built on top of core tools.
 - `hopx_agents_overview` — fleet status in one call: every agent-created/agent-permitted session with state (running/busy/idle), cwd, foreground program, Claude turn count, bell counters, last activity, and pending wait jobs; `include_user_sessions=false` narrows to agent-created only, `include_ports=true` adds proxy sessions
 - `hopx_wait_any` — race several background waits (wait_ids and/or terminal_ids, auto-starting `until_agent_done` waits); returns the first real completion(s) plus the still-pending set; expired watches are re-armed automatically (new wait_id in `pending`) rather than reported as completions
 - `hopx_spawn_agent` — one-call subagent bring-up: create terminal + launch agent CLI (claude/codex/gemini/custom) + wait until ready + optionally run a first task with an automatic completion contract; `isolation="worktree"` gives the worker its own git worktree + fleet/ branch for overlapping-file fleets
-  - the Claude preset uses the `sonnet` model alias and `bypassPermissions` mode by default, and removes inherited Claude Code process credentials before launch, so a delegated worker uses the host's durable `claude auth login` without parking on approval prompts; pass `permission_mode="manual"` for a restricted worker, `args="--model ..."` to choose another model, or an explicit `command` when inherited credentials are intentional
-  - the Codex preset runs autonomously and bypasses workspace-trust, approval, and self-update startup gates; Hop rejects detected login, trust, or update screens instead of dispatching a task into them
+  - the Claude preset uses the `opus` model alias and `bypassPermissions` mode by default, and removes inherited Claude Code process credentials before launch, so a delegated worker uses the host's durable `claude auth login` without parking on approval prompts; pass `permission_mode="manual"` for a restricted worker, `args="--model ..."` to choose another model, or an explicit `command` when inherited credentials are intentional
+  - the host operator can cap the mode with `hop config agent-ceiling <mode>` (or `HOP_AGENT_PERMISSION_CEILING`); a request above the cap is clamped, the applied mode is returned as `permission_mode`, and the clamp is explained in `permission_note`
+  - the Codex preset runs autonomously and bypasses workspace-trust, approval, and self-update startup gates when the ceiling is `bypassPermissions` (the default); under any lower ceiling it runs `--full-auto` (sandboxed, asks on request). Hop rejects detected login, trust, or update screens instead of dispatching a task into them
   - MCP and `hopa spawn --task` wait by default and return the transcript-backed `assistant_reply`; `async=true` is for fleet dispatch through a long-lived MCP connection, while the short-lived `hopa` CLI rejects async waits
 - `hopx_task_ledger` — the durable orchestration ledger (~/.hop2/orchestration): async dispatches with contracts survive manager/MCP restarts; pending entries reconcile lazily from turn counters + transcripts; acknowledge to consume
 

package/README.md

@@ -290,6 +290,8 @@ Paths:
 - workspace-backed sessions: `~/.hop2/workspaces/<workspace>/history/<internal-session>.history`
 - workspace-backed audit logs: `~/.hop2/workspaces/<workspace>/logs/<internal-session>/audit.ndjson`
 
+Retention: a session's live `audit.ndjson` rotates at 64 MB (`HOP_SESSION_AUDIT_MAX_MB`, keep `HOP_SESSION_AUDIT_KEEP`=5 rotations), and a *dead* session's whole log directory is deleted 90 days after its last write (`HOP_SESSION_AUDIT_RETENTION_DAYS`; `0` disables). Live sessions are never swept.
+
 Key tunables:
 
 - `HOP_SESSION_HISTORY_SIZE`
@@ -298,6 +300,8 @@ Key tunables:
 - `HOP_AGENT_POST_START_HISTORY_INIT`
 - `HOP_POST_START_HISTORY_INIT`
 - `HOP_SESSION_AUDIT_INLINE_MAX_BYTES`
+- `HOP_SESSION_AUDIT_MAX_MB`, `HOP_SESSION_AUDIT_KEEP`, `HOP_SESSION_AUDIT_RETENTION_DAYS`
+- `HOP_SESSION_TTL_DAYS` (login session lifetime, default 30)
 - `HOP_SESSION_TUI_KEYFRAME_INTERVAL_MS`
 - `HOP_SESSION_TUI_KEYFRAME_TAIL_CHARS`
 - `HOP_SESSION_TUI_KEYFRAME_MAX_LINES`
@@ -360,13 +364,15 @@ Notes:
 
 ### Security
 
-- Password + TOTP is supported; password is required for custom domains
-- Login cookies are `httpOnly`, `secure`, and `sameSite=lax`
-- Browser sessions persist across `hop stop/start` by default through a stable session secret
-- The local server binds only to `127.0.0.1`
-- Cloudflare Tunnel provides end-to-end TLS
+- Login is password + TOTP, or a passkey (Touch ID / Face ID / security key). **A password is required before the public tunnel opens**; `hop config totp-only on` opts out.
+- Every login gets its **own per-device session** (random token, stored hashed), valid for 30 days (`HOP_SESSION_TTL_DAYS`). `hop auth` lists logged-in devices, `hop auth revoke <id>` logs one out, `hop auth revoke --all` logs everyone out, `hop auth token` mints a revocable token for an app or script.
+- Login cookies are `httpOnly`, `secure`, `sameSite=lax`, and host-scoped; they survive `hop stop/start`.
+- The daemon's own secret is only for local processes (CLI, MCP, hay) as a Bearer header; it is never a cookie.
+- The local server binds only to `127.0.0.1`; Cloudflare Tunnel provides end-to-end TLS.
+- Audit logs rotate at 64 MB and dead sessions' logs are removed after 90 days (see Logging).
+- `hop config agent-ceiling <mode>` caps the permission mode spawned agents may run with.
 
-Secrets are stored in `~/.hop2/`. Set `HOP_PERSIST_SESSION_SECRET=0` if you want login cookies invalidated on every daemon restart.
+Secrets are stored in `~/.hop2/`. Full threat model, what an authenticated user can do, and how to report a hole: [SECURITY.md](SECURITY.md).
 
 ### Runtime and Recovery
 

package/SECURITY.md

@@ -0,0 +1,102 @@
+# Security
+
+Hop puts a shell on the public internet on purpose. This page says exactly what
+stands between the internet and that shell, what an attacker who gets past it
+can do, and how to report a hole.
+
+## Reporting
+
+Email **jianzhou@uchicago.edu** with "hop security" in the subject. Please do
+not open a public issue for anything exploitable. You will get an
+acknowledgement within a few days and a fix or a plan within two weeks for
+anything confirmed.
+
+## Threat model
+
+- **In scope:** an attacker on the internet reaching your tunnel URL; a
+  stranger who obtained a device's cookie; a lab member on a shared landing
+  host trying to reach another member's instance; an agent (yours or a
+  prompt-injected one) doing more than you meant through the MCP surface.
+- **Out of scope:** an attacker who already has your local user account, your
+  Cloudflare account, or root on the machine. Hop runs as you; it cannot
+  protect you from you.
+
+## How a request gets in
+
+1. **TLS and the tunnel.** The daemon binds `127.0.0.1` only. Cloudflare
+   Tunnel terminates TLS at Cloudflare and connects to the daemon over
+   loopback. Nothing listens on a public port.
+2. **Login.** One of:
+   - password (scrypt, salted) **plus** a TOTP code (`otplib`, 30-second
+     steps), or
+   - a passkey (WebAuthn; Touch ID, Face ID, security key), enrolled from an
+     already-authenticated session and bound to the hostname.
+   Failed attempts back off per IP: 5 failures → 30 s, doubling.
+3. **Per-device sessions.** A successful login mints a random 256-bit token
+   for *that device* (stored only as a SHA-256 hash in
+   `~/.hop2/.auth-sessions.json`, mode 0600), set as an `httpOnly`, `Secure`,
+   `SameSite=Lax`, host-scoped cookie valid for **30 days**
+   (`HOP_SESSION_TTL_DAYS`). `hop auth` lists devices; `hop auth revoke <id>`
+   logs one out; `hop auth revoke --all` logs everyone out. Logging out
+   revokes the session server-side.
+4. **Local processes.** The hop CLI, MCP server and hay talk to the daemon
+   with a per-install secret (`~/.hop2/.session_secret`, 0600) as an
+   `Authorization: Bearer` header. That secret is **never** accepted as a
+   cookie, and in a WebSocket `?token=` query only on a direct loopback
+   connection (never through the tunnel). `hop auth token` mints a
+   revocable device token for apps and scripts instead.
+
+## Password is required for remote access
+
+TOTP alone is one factor. Hop will not open the public tunnel until a
+password is set (`hop password set`). If you genuinely want
+authenticator-only login — say, behind Cloudflare Access — opt out with
+`hop config totp-only on`; `hop status` shows the policy in force.
+
+## What an authenticated user can do
+
+Everything you can do in a terminal on that machine, as your user. There is
+no sandbox between the browser and the PTY. Treat the login page as the only
+boundary, and treat MCP access the same way: an MCP client that can reach the
+daemon can run `hopx_exec`.
+
+## Agents
+
+`hopx_spawn_agent` launches Claude Code with `--permission-mode
+bypassPermissions` by default so delegated work never parks on a prompt.
+Cap that on any host you do not fully trust with
+`hop config agent-ceiling <mode>` (for example `acceptEdits`); requests above
+the ceiling are clamped and the clamp is reported in the tool result. The
+Codex preset drops its approval bypass and runs `--full-auto` (sandboxed)
+under any ceiling below the top. This is a safety rail against agent
+accidents, not a security boundary: MCP access already means shell access.
+
+## Audit logs
+
+Every session's input and output is recorded to
+`~/.hop2/**/logs/<session>/audit.ndjson`. It is a plaintext record of
+everything typed, including anything pasted into the terminal. The daemon
+rotates each file at 64 MB (`HOP_SESSION_AUDIT_MAX_MB`), keeps 5 rotations
+(`HOP_SESSION_AUDIT_KEEP`), and deletes a *dead* session's log directory 90
+days after its last write (`HOP_SESSION_AUDIT_RETENTION_DAYS`; 0 disables).
+Live sessions are never swept. If you need shorter retention for compliance,
+lower the day count; if you need none, set it to 0 and manage the directory
+yourself.
+
+## Multi-user hosts and self-service signup
+
+Each lab member runs their own daemon on their own machine. The admin's
+daemon only issues subdomains and tunnels. Cookies are host-scoped (no
+`Domain=`), so one member's session never reaches another's host. Signup is
+off by default, requires an explicit allowed email domain
+(`hop registration domain <d>`), and gates identity through either a mailed
+confirmation link or a verified Cloudflare Access JWT. An approved user can
+serve anything they like at their subdomain; only approve people you would
+give a subdomain of your own domain to.
+
+## Files that are secrets
+
+Under `~/.hop2/` (all 0600): `.auth_secret` (TOTP seed), `.password_hash`,
+`.session_secret` (local IPC), `.auth-sessions.json` (session hashes),
+`.passkeys.json` (public keys only), tunnel credentials/tokens, and the
+`workspaces/**/logs` audit trail. Back them up like passwords.