dsh-inner-browser-use 0.38.0 → 0.39.0

package/README.md

@@ -21,7 +21,8 @@ live picture of that browser, and your own cursor keeps working on the picture.
 | `browser_scroll` | Scrolls the wheel at the centre of the page, or at `x`/`y`. `dy: 600` is about a screen down. |
 | `browser_shot` | Saves a full-size PNG into `~/.dsh-inner-browser-use/screenshots` and returns the path. |
 | `browser_media` | Lists the video and sound the page already fetched, with sizes, the one its own player shows first and marked `main`; `save: <row>`, `save: main` or part of the address keeps one. Ads and beacons stay out unless `all: true`; `watch: false` stops remembering the page. A stream is followed to its pieces and joined, so nothing has to be installed. |
-| `browser_state` | Reports whether the browser runs, which profile it uses, its address and title, and how many columns are showing it. |
+| `browser_login` | Keeps a sign-in by name: `save` stores this window's cookies and each site's local storage, `list` shows what is kept, `use` signs that account back in and reopens the page, `drop` forgets it. Names survive a restart and belong to the browser rather than to one chat, so two accounts on one site are two names. What sits on disk is encrypted, with the key in the system keychain. |
+| `browser_state` | Reports whether the browser runs, which profile it uses, its address and title, how many columns are showing it, how much memory it holds right now and when it would close on its own if left alone. |
 
 `browser_read` on the same page is the words only, in Markdown (measured: 4,520
 characters of an about page against 2,987 characters of snapshot — and the

package/README.zh.md

@@ -20,7 +20,8 @@ profile，不是产品自带的那个浏览页签：右栏放的是它的画面
 | `browser_scroll` | 在页面中心滚轮，也可以指定 `x`/`y`。`dy: 600` 约一屏。 |
 | `browser_shot` | 存一张 PNG 到 `~/.dsh/inner-browser-use/screenshots`，返回路径；`region: [x, y, w, h]` 只截一块（游戏、图表、看局部）。 |
 | `browser_media` | 列出页面已经请求过的视频和声音（带大小），页面自己播放器里那个排第一、标 `main`；`save: <行号>`、`save: main` 或地址片段存下来。广告和统计默认不出现（`all: true` 才看），`watch: false` 关掉这个页面的记录。流会顺着播放列表把片段取回拼好，不用装任何东西。 |
-| `browser_state` | 报浏览器在不在跑、用的哪个 profile、地址、标题，以及有几个右栏在看它。 |
+| `browser_login` | 按名字留住登录：`save` 存下当前窗口的 cookie 和各站的 localStorage，`list` 看有哪些，`use` 切回那个账号并重开页面，`drop` 忘掉。名字跟着浏览器走、不跟着一个会话走，重启也在；同一站点两个账号就存两个名字。磁盘上那一份是加密的，钥匙在系统钥匙串里。 |
+| `browser_state` | 报浏览器在不在跑、用的哪个 profile、地址、标题、有几个右栏在看它，以及它此刻占多少内存、没人用的话还有多久关闭。 |
 
 点、输入、按键之后的那一行会多一句结果：`· navigated to …`（换页了）、`· content changed`（页内有变化）、`· no visible change`（点了没动）、Flash 页则是 `· screen updated` / `· no frame change`；`read: true` 时不再多说。
 

package/docs/ARCHITECTURE.md

@@ -165,10 +165,49 @@ picture comes back on the mutation that satisfies it. A page that changes 137 ms
 starts answers at 138 ms, not at the next 100 ms tick — the same reason `idle` (a mutation-free
 window) costs one round trip on an animation-heavy page instead of one per frame.
 
+## Sign-ins and reclaim
+
 Sign-in state lives in the profile, and session cookies — the kind a sign-in usually sets,
 which Chrome would otherwise drop on exit — are saved next to it and restored on the next
 launch, so a restart of the app does not sign the person out.
 
+Three layers, each adding one thing the previous cannot do:
+
+- **The profile** keeps everything Chrome writes: dated cookies, origin storage, service
+  workers. It survives a restart of the app and a restart of the machine.
+- **The session jar** (`session-cookies.json`) covers the part Chrome throws away on exit.
+  Every cookie that comes back from `page.cookies()` without an expiry is written when the
+  browser closes, and put back on the next launch. A cookie the browser already holds is
+  never overwritten from the jar — a rotation happened in the live browser, and the jar is
+  the older truth.
+- **`browser_login`** (`vault.js`) turns that state into named snapshots a chat can call
+  back: cookies plus per-origin `localStorage`, saved under a name, listed, restored, or
+  dropped. `list` is a directory read, so it costs nothing while the browser is down.
+  Restoring writes cookies first, then navigates to each stored origin to write its local
+  storage (the API is origin-bound), then reopens the page that was saved.
+
+Everything written at rest is sealed with AES-256-GCM (`{v, alg, iv, tag, data}`, all
+base64). The key comes from `DSH_INNER_BROWSER_VAULT_KEY` when a test sets one, otherwise
+from the macOS keychain, otherwise from `vault.key` in the state root — 0600, and a fallback
+rather than the intended home, because an unattended `security add-generic-password` can
+block on a prompt. A tampered blob, a wrong key and a truncated file all come back empty;
+nothing trusts what it cannot verify. A plaintext jar from a version before this one is
+still read and re-sealed on the next write, so an upgrade does not sign anyone out.
+
+The reclaim ladder is three separate timers, because they answer three different questions:
+
+| Question | Timer | What happens |
+| --- | --- | --- |
+| Did the person close the column? | `REST_MS` = 60 s | The browser is put away a minute after the last pane lets go. |
+| Has nobody touched it at all? | `IDLE_MS` = 15 min | The whole process is reclaimed, but never while a pane is still watching a frame. |
+| Is this one tab stale? | `TAB_IDLE_MS` = 10 min, `MAX_TABS` = 6 | The tab is closed, not the browser; a returning chat gets a fresh page instead of a dead one (`expired`). |
+
+`browser_state` reports both what the process costs right now (`ps` over its process tree,
+which includes renderers, not just the parent) and `closesIn`, so the model can decide
+between keeping the page and letting it go instead of guessing. A freeze
+(`Page.setWebLifecycleState`) is deliberately not wired in: closing a stale tab is already
+cheap, and a frozen page that misses a mutation would make the event-driven wait lie.
+
 A system-prompt section (`browser-in-this-chat`) tells the model to reach for these tools
 without asking first when someone wants something done on a site.
 

package/docs/ARTIFACTS.md

@@ -22,12 +22,14 @@
 ~/.dsh-inner-browser-use/
   artifacts/<项目>/<会话>/<种类>/   给人看的产出，只在这里（见上）
   chrome/                          浏览器自己的数据：登录态、Cookie、缓存
+  logins/                          按名字留住的登录，一个名字一个文件，加密
+  vault.key                        钥匙串拿不到钥匙时的替代文件，只有本人可读
   flash/                           Flash 播放器运行时，第一次用 flash:true 才装
   browser.log                     最近一次浏览器启动和页面记录
   asks.log                        人问过什么、答了什么
   tabs.json / mirror.json / flash.json / watcher.json   上次开着哪些页
 ```
 
-`chrome/` 是浏览器进程自己在读写，不要手动改；要清登录态，用 `browser_open` 的档位或插件自己的入口，别删目录里的某个文件。上面这些都在一个根目录下，卸载插件前想留产出就拷 `artifacts/`。
+`chrome/session-cookies.json` 是 Chrome 退出时会丢的会话 cookie，加密后存在 profile 旁边；`logins/` 与 `vault.key` 由 `browser_login` 和启动时自动保存的登录备份共用，不要手动改或删，要清就用 `browser_login({action:"drop"})`。`chrome/` 其余部分是浏览器进程自己在读写，不要手动改；要清登录态，用 `browser_open` 的档位或插件自己的入口，别删目录里的某个文件。上面这些都在一个根目录下，卸载插件前想留产出就拷 `artifacts/`。
 
 测试里用 `DSH_INNER_BROWSER_ARTIFACTS` 指向临时目录，不写真实 home。

package/docs/BENCH.md

@@ -1,3 +1,17 @@
+## 登录能留、能切、关得掉（0.39.0）
+
+本地页签在加载时写一个会话 cookie 和一个 `localStorage` 令牌，然后用工具层实际走一遍：保存 → 清空浏览器里的一切 → 切回。磁盘上那一份同时用字符串搜一遍。
+
+| 项 | 结果 |
+| --- | --- |
+| `browser_login {action:"save"}` | 2 ms，8 个 cookie |
+| `browser_login {action:"use"}`（清空后切回、重开页面） | 105 ms |
+| 切回后 cookie 与 `localStorage` | 都在（`signedIn: true`） |
+| 密文里能否搜到 cookie 值 / 令牌 | 搜不到（`sealed: true`） |
+| 预算 | `login-vault: 1600 ms`，19 项全过 |
+
+`browser_state` 另外报两行：当前进程树占多少内存（含渲染进程），以及没人用的话还有多久关闭——两者都来自 `ps` 一次采样和已有的空闲计时器，不额外起进程。关闭策略没变：右栏关掉约 1 分钟、没人碰约 15 分钟回收整个浏览器，页签 10 分钟不动、最多 6 个。
+
 ## 等到变化，而不是去问（0.38.0）
 
 `browser_wait` 以前在宿主侧每 100 毫秒读一次页面判断条件，命中与否都被凑到下一个整拍上。

package/index.js

@@ -941,6 +941,8 @@ export function apply(ctx) {
         '不要用它：读公开文章、单个链接正文、文档、搜索结果摘要、GitHub 仓库或 PR 页面——这些能用 `web_fetch` / envoy 读就不用浏览器；一打开就是一个后台 Chrome 进程加一个页签，会话多了很占内存。',
         '也不要用它做连通性、可达性、服务是否起来的检查：那是一个 HTTP 请求的事，`web_fetch` 或 `curl` 就够，开浏览器只会多一个进程和一栏画面。只有「这一步必须在真实浏览器里点/填/登录」才轮到它。',
         '人点名之后不问、不另起外部 Chrome；画面留在本会话右栏，做完保留，不主动关。',
+        '登录态属于浏览器，不属于某个会话：`browser_login` 的 `save` 把当前登录按名字留存（`list` 看、`use` 切账号、`drop` 忘掉），换会话、重启都还在；同一站点要多个账号就存成不同名字。留存的登录凭据在磁盘上是加密的，密钥在系统钥匙串里。人让你登录时先 `browser_login` 的 `list` 看一眼有没有可复用的，再决定要不要重新登。',
+        '浏览器不用时自己让位：右栏关掉约一分钟后、没人碰约一刻钟后回收整个进程，页签十分钟不动、最多六个；`browser_state` 会给出它现在占多少内存和还有多久关闭。人还在看的时候不关。',
         '先接着用已有的页：`browser_view`（拿编号控件与可见文字）→ `browser_click` / `browser_type` → 再 `browser_view` 直到出现要的结果；页面要等就重复读，不 sleep。`browser_open` 只用于没有页、要换新地址、或要明确刷新；同一个地址不要反复重开。',
         '页面很长、只想确认某句话/按钮在哪时用 `browser_find`，别整页读。要读长文（文章、文档、issue、论坛帖）用 `browser_read`：它回 Markdown，只花几十分之一的 token，链接可点；要动手点、填表才用 `browser_view` 拿编号。',
         '要保存页面样子用 `browser_shot`，它会给出 PNG 绝对路径；要交给人看的文件，把绝对路径写进回复。',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-inner-browser-use",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "description": "An agent-owned Chromium sidecar mirrored into the DeepSeek Harness right column: the agent drives it, the person watches and can take the mouse, and logins survive restarts.",
   "type": "module",
   "main": "index.js",
@@ -18,6 +18,7 @@
     "read.js",
     "review.js",
     "media.js",
+    "vault.js",
     "client.js",
     "locale/*.json",
     "cordis.patch.yml",
@@ -49,7 +50,7 @@
     "dsh": ">=0.2.0"
   },
   "scripts": {
-    "test": "node --test test/artifacts.test.mjs test/client.test.mjs test/cookies.test.mjs test/diff.test.mjs test/fresh.test.mjs test/host.test.mjs test/input.test.mjs test/isolation.test.mjs test/keyboard.test.mjs test/leak.test.mjs test/login.test.mjs test/media.test.mjs test/no-duplicate.test.mjs test/package.test.mjs test/readfault.test.mjs test/refs.test.mjs test/review.test.mjs test/session.test.mjs test/settle.test.mjs test/sidecar.test.mjs test/swf.test.mjs test/tabs.test.mjs test/trouble.test.mjs",
+    "test": "node --test test/artifacts.test.mjs test/client.test.mjs test/cookies.test.mjs test/diff.test.mjs test/fresh.test.mjs test/host.test.mjs test/input.test.mjs test/isolation.test.mjs test/keyboard.test.mjs test/leak.test.mjs test/login.test.mjs test/media.test.mjs test/no-duplicate.test.mjs test/package.test.mjs test/readfault.test.mjs test/refs.test.mjs test/review.test.mjs test/session.test.mjs test/settle.test.mjs test/sidecar.test.mjs test/swf.test.mjs test/tabs.test.mjs test/trouble.test.mjs test/vault.test.mjs",
     "doctor": "node scripts/doctor.mjs",
     "breadth": "node scripts/breadth.mjs",
     "live": "node scripts/live.mjs",

package/sidecar.js

@@ -6,11 +6,12 @@
  * shows it as a screencast, so the tab is a viewer, not the browser.
  */
 import { execFileSync, spawn, spawnSync } from 'node:child_process'
-import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, appendFileSync } from 'node:fs'
+import { appendFileSync, chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { readyFlash } from './runtime/flash-setup.mjs'
+import { readSealed, tightenDir, writeSealed } from './vault.js'
 import { isMedia, kindOf } from './media.js?m=1'
 
 /**
@@ -113,6 +114,44 @@ const TAB_IDLE_MS = 10 * 60_000
 /** @param {number} ms - how long to wait. @returns {Promise<void>} resolves after it. */
 const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
 
+/** @param {number} root - a process id. @returns {number} bytes of RSS the process tree holds. */
+function treeBytes(root) {
+  if (!Number.isFinite(root) || root <= 0) return 0
+  try {
+    const rows = execFileSync('ps', ['-Ao', 'pid=,ppid=,rss='], { encoding: 'utf8', timeout: 3000 })
+      .trim()
+      .split('\n')
+      .map((line) => line.trim().split(/\s+/u))
+      .filter((cols) => cols.length >= 3)
+    /** @type {Map<number, number[]>} */
+    const byParent = new Map()
+    /** @type {Map<number, number>} */
+    const size = new Map()
+    for (const [pid, ppid, rss] of rows) {
+      const parent = Number(ppid)
+      const kids = byParent.get(parent) ?? []
+      kids.push(Number(pid))
+      byParent.set(parent, kids)
+      size.set(Number(pid), Number(rss) * 1024)
+    }
+    let total = size.get(root) ?? 0
+    const queue = [root]
+    const seen = new Set()
+    while (queue.length > 0) {
+      const pid = queue.shift()
+      if (seen.has(pid)) continue
+      seen.add(pid)
+      for (const kid of byParent.get(pid) ?? []) {
+        total += size.get(kid) ?? 0
+        queue.push(kid)
+      }
+    }
+    return total
+  } catch {
+    return 0
+  }
+}
+
 /** @param {string} path - candidate. @returns {string | undefined} the one that exists. */
 function firstBinary() {
   return CHROME_BINARIES.find((path) => existsSync(path))
@@ -348,9 +387,19 @@ export function snapshotLogin(dir) {
   const files = COOKIE_FILES.map((name) => ({ name, from: join(dir, name) })).filter((row) => existsSync(row.from))
   if (files.length === 0) return 0
   const to = loginBackupDir(dir)
-  mkdirSync(to, { recursive: true })
+  /* A copy of a cookie store is a copy of every sign-in in it: nobody else gets
+     to read the folder or the files, even on a shared machine. */
+  tightenDir(to)
   const stamp = String(Date.now())
-  for (const row of files) copyFileSync(row.from, join(to, `${stamp}-${row.name.replace(/\//g, '_')}`))
+  for (const row of files) {
+    const target = join(to, `${stamp}-${row.name.replace(/\//g, '_')}`)
+    copyFileSync(row.from, target)
+    try {
+      chmodSync(target, 0o600)
+    } catch {
+      /* best effort */
+    }
+  }
   const mine = readdirSync(to).filter((name) => name.startsWith(`${stamp}-`))
   const older = readdirSync(to).filter((name) => !mine.includes(name)).sort()
   const generations = 5
@@ -2996,6 +3045,7 @@ export class Sidecar {
    * @param {number} [ms] - how long a browser nobody watches may stay up.
    */
   touch(ms = IDLE_MS) {
+    this.idleAt = Date.now() + ms
     if (this.idle !== null) clearTimeout(this.idle)
     this.idle = setTimeout(() => {
       this.idle = null
@@ -3087,6 +3137,7 @@ export class Sidecar {
   }
 
   async shutdown() {
+    this.idleAt = 0
     /* A browser this process did not start belongs to somebody else — another
        app on the same profile, or a script that connected to it — and closing
        it would close the person's window. Let go of it instead: drop the socket
@@ -3158,7 +3209,7 @@ export class Sidecar {
         rmSync(file, { force: true })
         return
       }
-      writeFileSync(file, JSON.stringify(jar), { mode: 0o600 })
+      writeSealed(file, jar)
     } catch {
       /* a browser that is already gone has nothing to save */
     }
@@ -3166,12 +3217,9 @@ export class Sidecar {
 
   /** @returns {Promise<void>} puts back what saveSessionCookies kept. */
   async restoreSessionCookies() {
-    let jar = []
-    try {
-      jar = JSON.parse(String(readFileSync(sessionJar(profileDir(this.profile)), 'utf8')))
-    } catch {
-      return
-    }
+    /* Sealed by this version; plain JSON by one before it. Both are read, so an
+       update never signs anyone out. */
+    const jar = readSealed(sessionJar(profileDir(this.profile)))
     if (!Array.isArray(jar)) return
     /* A cookie the browser already holds is newer than the note: the site may
        have rotated its session id since the note was written, and putting the
@@ -3250,6 +3298,12 @@ export class Sidecar {
          screenshot is in this space, not in the window's. */
       viewport: this.page?.view ?? null,
       profiles,
+      /* What this browser costs right now: the whole process tree, renderers
+         included. Reported so a chat can decide whether to let it rest. */
+      memory: this.alive ? treeBytes(Number(this.child?.pid ?? 0)) : 0,
+      /* When it would close itself if nobody came back, and why: 0 means the
+         browser is either watched or not on a clock. */
+      closesIn: this.idle === null || this.stopping === true ? 0 : Math.max(0, Number(this.idleAt ?? 0) - Date.now()),
       error: this.alive ? '' : this.lastError,
     }
   }

package/tools.js

@@ -16,6 +16,7 @@ import { basename, join } from 'node:path'
 import { mkdir, readdir, stat, unlink, writeFile } from 'node:fs/promises'
 import { VIEW, DESKTOP_UA } from './sidecar.js?v=1'
 import { planOf, gather, sizeText, coreRows } from './media.js?m=2'
+import { dropLogin, listLogins, readLogin, saveLogin, vaultState } from './vault.js'
 import { readPage, renderPage, readArticle, readRelevant, findOnPage, locate, locateFirst, FRAME_BASE, covering, contextFor, identityOf, sameThing, differs, labelSpot, selectSpot, bounds, pictures, clickInDom, writeInDom, REF_GONE } from './read.js?v=1'
 import { brief as askBrief, recordRound, lastRoundNote, lastRound, markRound, MARK_STATUS } from './review.js?v=1'
 
@@ -965,6 +966,56 @@ async function evaluate(page, expression, route, raceMs = 2000) {
   return result?.value
 }
 
+/**
+ * The local storage a page is holding, per origin: some sites keep the sign-in
+ * itself there and cookies alone would come back signed out.
+ * @param {any} page - sidecar page.
+ * @returns {Promise<Array<{origin: string, items: Record<string, string>}>>} what it holds.
+ */
+async function storageOf(page) {
+  const raw = await evaluate(
+    page,
+    '(() => { try { const items = {}; for (let i = 0; i < localStorage.length; i += 1) { const key = localStorage.key(i); if (key !== null) items[key] = String(localStorage.getItem(key)).slice(0, 4000); } return JSON.stringify([{ origin: location.origin, items }]) } catch { return "[]" } })()',
+    null,
+    4000,
+  )
+  let rows = []
+  try {
+    rows = JSON.parse(String(raw ?? '[]'))
+  } catch {
+    return []
+  }
+  if (!Array.isArray(rows)) return []
+  return rows
+    .filter((row) => row !== null && typeof row === 'object' && typeof row.origin === 'string' && row.items !== null && typeof row.items === 'object')
+    .map((row) => ({ origin: String(row.origin), items: Object.fromEntries(Object.entries(row.items).slice(0, 200).map(([key, value]) => [key, String(value)])) }))
+}
+
+/**
+ * Puts one origin's local storage back. The page has to be on that origin to
+ * write to it, so this navigates there first — a sign-in that lives in local
+ * storage is worth the extra step.
+ * @param {any} page - sidecar page.
+ * @param {{origin: string, items: Record<string, string>}} row - what to put back.
+ * @returns {Promise<number>} how many entries went in.
+ */
+async function restoreStorage(page, row) {
+  if (String(row?.origin ?? '') === '' || page === null) return 0
+  try {
+    const here = String(page.url ?? '')
+    if (!here.startsWith(String(row.origin))) await page.navigate(String(row.origin))
+  } catch {
+    return 0
+  }
+  const written = await evaluate(
+    page,
+    `(() => { try { const items = ${JSON.stringify(row.items ?? {})}; for (const [key, value] of Object.entries(items)) localStorage.setItem(key, value); return Object.keys(items).length } catch { return 0 } })()`,
+    null,
+    4000,
+  )
+  return Number(written) || 0
+}
+
 /**
  * What the page looks like in one cheap string: address, title, how many
  * elements and how much text. Two of these equal says the click did nothing
@@ -3050,6 +3101,10 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
           `mirror owner ${owner === '' ? 'none' : owner}`, // ui-copy-ignore
           owner === '' ? 'no owner' : `owner ${owner}`,
           `refs followed ${String(follows.count)}`,
+          /* What it costs and when it would let go: the two facts that decide
+             whether to keep using it or let it rest. */
+          state.alive === true ? `memory ${Math.max(1, Math.round(Number(state.memory ?? 0) / 1048576))} MB` : 'memory 0 MB',
+          state.closesIn > 0 ? `closes in ${Math.max(1, Math.round(Number(state.closesIn) / 60_000))} min unless used` : 'no close scheduled',
           holdText(sidecar) === '' ? 'person free' : `person using it (${String(Math.ceil(Number(sidecar.holding()) / 1000))} s left)`,
         ]
         if (state.alive === true && viewerNote(state.viewers) !== '') rows.push(NO_VIEWER)
@@ -3057,6 +3112,86 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
       },
     },
 
+    {
+      name: 'browser_login', // ui-copy-ignore
+      description: 'Sign-ins belong to the browser, not to a chat: every chat uses them and they survive a restart. "save" keeps the sign-in showing right now under a name, "list" shows what is kept, "use" signs the browser back in as that account and reopens the page, "drop" forgets it. What is written is sealed, and the key is the one in the system keystore. One site can hold several accounts: save them under different names and switch with "use".',
+      parameters: { // ui-copy-ignore
+        type: 'object',
+        properties: {
+          action: { type: 'string', enum: ['list', 'save', 'use', 'drop'], description: 'list, save, use or drop.' },
+          name: { type: 'string', description: 'Account name, for example "work" or "personal". Needed by save, use and drop.' },
+        },
+        required: ['action'], // ui-copy-ignore
+        additionalProperties: false,
+      },
+      output: TEXT_OUTPUT, // ui-copy-ignore
+      timeoutMs: 25_000,
+      isConcurrencySafe: () => false,
+      /** @param {any} args - action and name. @returns {Promise<{text: string}>} what happened. */
+      execute: async (args) => {
+        const action = String(args?.action ?? '')
+        if (action === 'list') {
+          const rows = listLogins()
+          const shape = vaultState()
+          if (rows.length === 0) {
+            return { text: 'Nothing saved yet. Sign in on the site, then browser_login {action:"save", name:"work"}.' }
+          }
+          const head = `${rows.length} kept sign-in${rows.length === 1 ? '' : 's'}, ${Math.max(1, Math.round(shape.bytes / 1024))} KB sealed${shape.keyInKeychain ? ', key in the system keystore' : ''}`
+          const lines = rows.map((row) => {
+            const sites = row.origins.length === 0 ? '' : `, ${row.origins.join(' ')}`
+            return `${row.name} — ${row.cookieCount} cookies${sites}, saved ${new Date(row.savedAt).toLocaleString()}`
+          })
+          return { text: [head, ...lines].join('\n') }
+        }
+        const name = String(args?.name ?? '').trim()
+        if (name === '') return { text: 'Name the account: browser_login {action:"save", name:"work"}.' }
+        if (action === 'drop') {
+          return { text: dropLogin(name) ? `Forgot "${name}".` : `Nothing saved as "${name}".` }
+        }
+        if (action === 'save') {
+          const page = await sidecar.ensure({ session: currentSession() })
+          const cookies = await page.cookies()
+          const storage = await storageOf(page)
+          const kept = saveLogin(name, { cookies, storage, url: String(page.url ?? '') })
+          const sites = kept.origins.length === 0 ? '' : ` and ${kept.origins.length} site${kept.origins.length === 1 ? '' : 's'} of local storage`
+          return { text: `Saved "${kept.name}": ${kept.cookieCount} cookies${sites}, sealed on disk.` }
+        }
+        if (action === 'use') {
+          const held = readLogin(name)
+          if (held === null) return { text: `Nothing saved as "${name}". browser_login {action:"list"} shows what is kept.` }
+          const page = await sidecar.ensure({ session: currentSession() })
+          let put = 0
+          for (const cookie of (Array.isArray(held.cookies) ? held.cookies : []).slice(0, 400)) {
+            const domain = String(cookie?.domain ?? '').replace(/^\./u, '')
+            if (domain === '' || cookie?.name === undefined) continue
+            try {
+              await page.setCookie({
+                name: String(cookie.name),
+                value: String(cookie.value ?? ''),
+                domain,
+                path: String(cookie.path ?? '/'),
+                secure: cookie.secure === true,
+                httpOnly: cookie.httpOnly === true,
+                sameSite: cookie.sameSite,
+                expires: cookie.session === true ? undefined : Number(cookie.expires) || undefined,
+              })
+              put += 1
+            } catch {
+              /* one cookie a site refuses is not a reason to stop */
+            }
+          }
+          let stored = 0
+          for (const row of (Array.isArray(held.storage) ? held.storage : []).slice(0, 4)) stored += await restoreStorage(page, row)
+          const back = String(held.url ?? '')
+          if (back !== '') await page.navigate(back)
+          else await page.reload()
+          const said = stored === 0 ? '' : `, ${stored} local storage entries`
+          return { text: `Signed in as "${name}": ${put} cookies${said}, page reopened.` }
+        }
+        return { text: 'Pass action "list", "save", "use" or "drop".' }
+      },
+    },
+
     {
       name: 'browser_resume', // ui-copy-ignore
       description: 'Take the page back from the person at the mirror: clears the hold so the next action is sent at once, instead of waiting the few seconds out.',

package/vault.js

@@ -0,0 +1,333 @@
+/**
+ * Sign-in material at rest.
+ *
+ * A cookie jar is a password: whoever reads the file is signed in as the person.
+ * Chrome keeps its own store encrypted, but the copy this plugin makes when a
+ * session cookie would otherwise be dropped is a plain file, and a plain file in
+ * a home directory is one backup or one shared folder away from being someone
+ * else's session. Everything this plugin writes about a sign-in is therefore
+ * sealed with AES-256-GCM, and the key lives in the system Keychain — not next
+ * to the ciphertext, not in the profile, not in an environment variable by
+ * default.
+ *
+ * What stays unsealed is a name and a timestamp, so the list of accounts can be
+ * shown without opening the vault.
+ */
+import { createCipheriv, createDecipheriv, randomBytes, timingSafeEqual } from 'node:crypto'
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { execFileSync } from 'node:child_process'
+
+const KEYCHAIN_SERVICE = 'dsh-inner-browser-use-vault'
+const KEY_BYTES = 32
+const IV_BYTES = 12
+
+/** @returns {string} where the browser state, and so the vault, lives. */
+export function vaultRoot() {
+  return process.env.DSH_INNER_BROWSER_STATE_DIR || join(homedir(), '.dsh', 'inner-browser-use')
+}
+
+/**
+ * The key, in order of preference: the one this run was handed (tests, or a
+ * person who keeps it in their own secret store), the one in the Keychain, the
+ * one on disk with owner-only permissions. A missing key is created once and
+ * then never rotated silently, because rotating it would sign everyone out.
+ * @returns {Buffer} 32 bytes.
+ */
+export function vaultKey() {
+  const given = String(process.env.DSH_INNER_BROWSER_VAULT_KEY ?? '')
+  if (given !== '') {
+    const raw = Buffer.from(given, 'base64')
+    if (raw.length === KEY_BYTES) return raw
+  }
+  const fromKeychain = readKeychain()
+  if (fromKeychain !== null) return fromKeychain
+  const file = join(vaultRoot(), 'vault.key')
+  if (existsSync(file)) {
+    const raw = Buffer.from(String(readFileSync(file, 'utf8')).trim(), 'base64')
+    if (raw.length === KEY_BYTES) return raw
+  }
+  const made = randomBytes(KEY_BYTES)
+  const written = writeKeychain(made)
+  if (written === true) return made
+  mkdirSync(vaultRoot(), { recursive: true })
+  writeFileSync(file, `${made.toString('base64')}\n`, { mode: 0o600 })
+  chmodSync(file, 0o600)
+  return made
+}
+
+/** @returns {Buffer|null} the Keychain copy, if this platform has one. */
+function readKeychain() {
+  if (process.platform !== 'darwin') return null
+  try {
+    const out = execFileSync('security', ['find-generic-password', '-s', KEYCHAIN_SERVICE, '-a', 'vault', '-w'], {
+      encoding: 'utf8',
+      timeout: 4000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    const raw = Buffer.from(out.trim(), 'base64')
+    return raw.length === KEY_BYTES ? raw : null
+  } catch {
+    return null
+  }
+}
+
+/** @param {Buffer} key - the material. @returns {boolean} whether the Keychain took it. */
+function writeKeychain(key) {
+  if (process.platform !== 'darwin') return false
+  try {
+    execFileSync('security', ['add-generic-password', '-U', '-s', KEYCHAIN_SERVICE, '-a', 'vault', '-w', key.toString('base64')], {
+      timeout: 4000,
+      stdio: ['ignore', 'ignore', 'ignore'],
+    })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** @returns {'env'|'keychain'|'file'|'none'} which of the three the key in use came from. */
+function keySource() {
+  const given = String(process.env.DSH_INNER_BROWSER_VAULT_KEY ?? '')
+  if (given !== '' && Buffer.from(given, 'base64').length === KEY_BYTES) return 'env'
+  if (readKeychain() !== null) return 'keychain'
+  const file = join(vaultRoot(), 'vault.key')
+  if (existsSync(file)) {
+    const raw = Buffer.from(String(readFileSync(file, 'utf8')).trim(), 'base64')
+    if (raw.length === KEY_BYTES) return 'file'
+  }
+  return 'none'
+}
+
+/**
+ * @param {unknown} value - anything JSON can hold.
+ * @returns {{v: number, alg: string, iv: string, tag: string, data: string}} the sealed blob.
+ */
+export function seal(value) {
+  const key = vaultKey()
+  const iv = randomBytes(IV_BYTES)
+  const cipher = createCipheriv('aes-256-gcm', key, iv)
+  const data = Buffer.concat([cipher.update(Buffer.from(JSON.stringify(value), 'utf8')), cipher.final()])
+  return {
+    v: 1,
+    alg: 'aes-256-gcm',
+    iv: iv.toString('base64'),
+    tag: cipher.getAuthTag().toString('base64'),
+    data: data.toString('base64'),
+  }
+}
+
+/**
+ * Opens a sealed blob. A tampered blob, a different key, or a plain array all
+ * come back as `undefined` rather than as data that might be trusted.
+ * @param {unknown} blob - what `seal` returned, or its JSON text.
+ * @returns {any} the value, or undefined.
+ */
+export function unseal(blob) {
+  let held = blob
+  if (typeof held === 'string') {
+    try {
+      held = JSON.parse(held)
+    } catch {
+      return undefined
+    }
+  }
+  if (held === null || typeof held !== 'object') return undefined
+  const row = /** @type {any} */ (held)
+  if (row.v !== 1 || row.alg !== 'aes-256-gcm') return undefined
+  try {
+    const key = vaultKey()
+    const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(String(row.iv), 'base64'))
+    decipher.setAuthTag(Buffer.from(String(row.tag), 'base64'))
+    const text = Buffer.concat([decipher.update(Buffer.from(String(row.data), 'base64')), decipher.final()])
+    return JSON.parse(text.toString('utf8'))
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Reads a file that is either sealed or, from an older version, plain JSON.
+ * @param {string} path - the file.
+ * @returns {any} its value, or undefined.
+ */
+export function readSealed(path) {
+  let text = ''
+  try {
+    text = String(readFileSync(path, 'utf8'))
+  } catch {
+    return undefined
+  }
+  const opened = unseal(text)
+  if (opened !== undefined) return opened
+  try {
+    return JSON.parse(text)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Writes a sealed file and makes sure nobody but the owner can read it, even if
+ * it was created earlier with looser permissions.
+ * @param {string} path - where.
+ * @param {unknown} value - what.
+ * @returns {void}
+ */
+export function writeSealed(path, value) {
+  writeFileSync(path, `${JSON.stringify(seal(value))}\n`, { mode: 0o600 })
+  try {
+    chmodSync(path, 0o600)
+  } catch {
+    /* a file system without permissions is not a reason to fail the save */
+  }
+}
+
+/** @param {string} path - a directory. @returns {void} owner-only, best effort. */
+export function tightenDir(path) {
+  try {
+    mkdirSync(path, { recursive: true, mode: 0o700 })
+    chmodSync(path, 0o700)
+  } catch {
+    /* best effort */
+  }
+}
+
+/* ------------------------------------------------------------------ logins */
+
+/**
+ * A name becomes a file name. Anything that could climb out of the directory or
+ * collide on a case-insensitive file system is folded to a safe character.
+ * @param {string} name - what the person called the account.
+ * @returns {string} the file stem.
+ */
+export function loginSlug(name) {
+  const raw = String(name ?? '').trim()
+  if (raw === '') return ''
+  return raw
+    .replace(/[^\w. -]/gu, '_')
+    .replace(/\s+/gu, '-')
+    .replace(/^[.-]+/u, '')
+    .slice(0, 48)
+}
+
+/** @returns {string} where named accounts live. */
+export function loginDir() {
+  const dir = join(vaultRoot(), 'logins')
+  tightenDir(dir)
+  return dir
+}
+
+/**
+ * @param {string} name - account name.
+ * @returns {string} the file for it.
+ */
+function loginFile(name) {
+  const slug = loginSlug(name)
+  return slug === '' ? '' : join(loginDir(), `${slug}.json`)
+}
+
+/**
+ * Keeps one account: cookies plus the local storage of the sites it was saved
+ * on. Sealed as a whole, so even the list of sites is not readable off disk.
+ * @param {string} name - account name.
+ * @param {{cookies: object[], storage: Array<{origin: string, items: Record<string, string>}>, url?: string}} payload - what to keep.
+ * @returns {{name: string, savedAt: number, cookieCount: number, origins: string[]}} what was written.
+ */
+export function saveLogin(name, payload) {
+  const file = loginFile(name)
+  if (file === '') throw new Error('a login needs a name')
+  const cookies = Array.isArray(payload?.cookies) ? payload.cookies.slice(0, 400) : []
+  const storage = Array.isArray(payload?.storage) ? payload.storage.slice(0, 40) : []
+  const savedAt = Date.now()
+  writeSealed(file, {
+    name: String(name).trim().slice(0, 80),
+    savedAt,
+    url: String(payload?.url ?? ''),
+    cookies,
+    storage,
+  })
+  return {
+    name: String(name).trim().slice(0, 80),
+    savedAt,
+    cookieCount: cookies.length,
+    origins: storage.map((row) => String(row?.origin ?? '')).filter(Boolean),
+  }
+}
+
+/**
+ * @param {string} name - account name.
+ * @returns {any|null} the kept account, or null.
+ */
+export function readLogin(name) {
+  const file = loginFile(name)
+  if (file === '' || !existsSync(file)) return null
+  const held = readSealed(file)
+  return held === undefined ? null : held
+}
+
+/**
+ * Everything in the vault, newest first. Only the envelope is needed for the
+ * list, but the envelope is sealed too, so this opens each file.
+ * @returns {Array<{name: string, savedAt: number, cookieCount: number, origins: string[]}>} the accounts.
+ */
+export function listLogins() {
+  const dir = loginDir()
+  const rows = []
+  let names = []
+  try {
+    names = readdirSync(dir).filter((name) => name.endsWith('.json'))
+  } catch {
+    return rows
+  }
+  for (const name of names) {
+    const held = readSealed(join(dir, name))
+    if (held === null || typeof held !== 'object') continue
+    rows.push({
+      name: String(held.name ?? name.replace(/\.json$/u, '')),
+      savedAt: Number(held.savedAt ?? 0),
+      cookieCount: Array.isArray(held.cookies) ? held.cookies.length : 0,
+      origins: Array.isArray(held.storage) ? held.storage.map((row) => String(row?.origin ?? '')).filter(Boolean) : [],
+    })
+  }
+  return rows.sort((a, b) => b.savedAt - a.savedAt)
+}
+
+/**
+ * @param {string} name - account name.
+ * @returns {boolean} whether something was there to remove.
+ */
+export function dropLogin(name) {
+  const file = loginFile(name)
+  if (file === '' || !existsSync(file)) return false
+  rmSync(file, { force: true })
+  return true
+}
+
+/**
+ * How big the vault is, and whether the key is outside it: the two facts a
+ * person wants when deciding whether a sign-in is safe to leave here.
+ * @returns {{files: number, bytes: number, keyInKeychain: boolean, keySource: string}} the shape.
+ */
+export function vaultState() {
+  const dir = loginDir()
+  let files = 0
+  let bytes = 0
+  try {
+    for (const name of readdirSync(dir)) {
+      if (!name.endsWith('.json')) continue
+      files += 1
+      bytes += statSync(join(dir, name)).size
+    }
+  } catch {
+    /* an empty vault is a valid vault */
+  }
+  const source = keySource()
+  return { files, bytes, keyInKeychain: source === 'keychain', keySource: source }
+}
+
+/** @param {string} path - two files. @param {Buffer} a - one. @param {Buffer} b - the other. @returns {boolean} same bytes. */
+export function sameKey(a, b) {
+  return a.length === b.length && timingSafeEqual(a, b)
+}