dsh-permission-gate

dsh-permission-gate

A UI-level access gate and process-wide agent tool brake for DeepSeek Harness (dsh).

Log in once → every open DSH page unlocks. Nobody logged in → the agent itself can't run a single tool.

---

⚠️ Read this first: this is NOT authentication

DSH's /api surface has no authentication of its own — that is a deliberate property of the harness, not a bug this plugin fixes. The harness's own source describes its request fence like this:

trustedHosts is a DNS-rebinding fence, explicitly not authentication

Any client that can reach the DSH port can bypass this plugin entirely by calling the HTTP API directly. This plugin gates:

• ✅ the browser page (a full-screen lock page injected into every page load)
• ✅ the agent's tool calls (a process-wide tools.guard brake)

It does not gate the HTTP surface. It is not a reverse proxy, not a session layer, and not an authorization system.

Always pair it with a real boundary:

If you deploy this on a public port and believe you are protected, you are worse off than having nothing, because you will stop looking for the real problem.

---

What it does

• Full-screen lock page. Injected into every DSH page load via the documented webserver/index-inject channel — no client bundle, no module loader, nothing to keep in sync with the SPA.
• Global shared session. One session per process, one idle clock. Log in on your phone → your desktop page unlocks on its next poll. The clock expires → every page falls back to the login page.
• Strict 60-minute idle lock. No grace period, not even for a running task. This is intentional: the gate is a dead-man switch.
• Process-wide tool brake. While nobody is logged in, ctx.tools.guard denies every agent tool call. The agent cannot read files, run commands, open the network, or spawn subagents.
• Real credentials. scrypt + random salt, stored at ~/.dsh/permission-gate.json (mode 0600). The session lives in memory only, so a restart always requires a fresh login — but your password is never reset.
• Server-rendered escape hatch. /gate is plain HTML served by the host half. It works even if the injected script fails or is cached out.
• Native settings module. A 权限闸门 page inside DSH's own Settings, where the gate can be disabled — and disabling requires the password.
• Collapsible status chip. A countdown chip in the corner; collapse it to a slim tab on the right edge and click the tab to bring it back. The preference persists in localStorage.

Install

This package declares dsh.bundle, so it is a profile layer: installing it is one command, and DSH reconciles the composition for you. There is no patch file to edit.

dsh plugin --profile web add dsh-permission-gate

# restart DSH once — the client roster is scanned at startup

The bundle inserts this row on its own (see cordis.patch.yml):

- insert:
    - id: permission-gate
      name: dsh-permission-gate

Migrating from a manual install? Delete that same row from your own ~/.dsh/profiles/web/cordis.patch.yml first. The bundle now inserts it, and two entries sharing one id will collide.

On the next page load you get the lock page. The first visit asks you to set a password; every visit after that asks you to enter it.

Endpoints

All of them are served by the host half and sit behind the same origin as DSH.

state is one of setup · locked · unlocked · disabled.

Threat model

Deliberate exemption

Three tools stay callable while the gate is locked, because they touch no files, commands, session content, or credentials:

get_goal · update_goal · todo_write

They exist so a locked agent can still report state and close out its own bookkeeping. Remove the BOOKKEEPING_TOOLS line in lib/index.js if you want a zero-exemption gate.

Recovery

Design notes

Built while running DSH remotely from a phone. Three bugs are baked into the comments and the test suite, because each one is a trap anyone building injected UI for DSH will hit:

1. A silent render crash is worse than a visible error. The lock page used to throw on every render in the common path (appendChild(null) when the "confirm password" field is absent) — the host-side guard kept working while the UI showed nothing, i.e. "no permissions, but you can still chat." Fix: never append null, and wrap the whole render in a fallback that puts the error on screen.
2. Never re-render a form on a timer. A 5-second status poll rebuilt the login form and wiped whatever the password field contained. Fix: re-render only when the state actually changes, and carry typed values across renders.
3. A global session must not require a per-browser cookie. /gate/touch originally demanded a cookie matching the session token. After a restart only the browser that logged in held a valid cookie, so every other page's activity was rejected with 401 — the countdown only ever went down. Fix: touch grants nothing; it only requires that the shared session is unlocked.

Development

The smoke test runs the real lib/ui.js against a minimal DOM stub whose appendChild throws on null, exactly like a real DOM. No browser needed.

npm test

Compatibility

Developed against DSH 0.1.1-rc.2 / cordis 4.x, and depends on these harness capabilities:

• host: webServer.register · webserver/index-inject · tools.guard
• client: the settings.section slot · slots and timer services

These are internal-ish APIs; a DSH upgrade may require a matching update here.

License

MIT