Introduction¶

The installation philosophy of DSH is “everything is a plugin,” and plugins are the standard path for extending Harness. Below is an introduction to 07-dot/dsh-cookie-janitor, maintained by 07-dot, categorized as admin-security in the community directory, with a repository description of “Expire stale dsh-auth cookies before the 16 KiB header limit (HTTP 431).”

The problem it solves is specific: when opening dsh web in a browser, the login dsh-auth-* Cookies keep accumulating in the same jar. When the Cookie request header exceeds the Node HTTP parser’s limit, the server returns 431 directly. Requests cannot reach any route, handler, or plugin, and the page in the browser cannot recover on its own. This plugin clears these stale login Cookies before the header limit is exceeded.

Source of the Problem¶

@deepseek-ai/dsh-client-connection issues a browser Cookie for every request to an authority:

dsh-auth-<base64url(sha256("host:port"))> = v1.<payload>.<hmac>
  ; Max-Age=2592000; Path=/; HttpOnly; SameSite=Strict

The Cookie name includes the authority, valid for 30 days by default (corresponding to cookieMaxAgeDays), and this package never sends deletion commands and has no cleanup path. Cookies are scoped by host rather than port, so every dsh web port visited by the browser within 30 days leaves a dsh-auth-* in the same jar at 127.0.0.1.

One Cookie is about 226 bytes, and the parser limit is a 16 KiB request header. According to test data in the README, requests with a 16,400-byte Cookie header return 431, while 16,200 bytes still reach the application. This means accumulating about 69 Cookies is enough to lock the browser GUI. At this point, no button on the interface can recover, as every request fails before reaching the router.

What It Does¶

1. When the plugin activates, it prepends a request listener to the listening http.Server.

2. For each request carrying dsh-auth-* Cookies, measure the size of the Cookie header first.

3. Once the jar exceeds the budget, append deletion headers for all Cookies that are not the current request’s own authority, in order from oldest to newest:

Set-Cookie: <name>=; Path=/; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; HttpOnly; SameSite=Strict

The number retained is determined by retain. The browser clears the corresponding jar in this response.

It should be noted that the request itself is still processed by the normal pipeline: the hook only sets response headers and does not write a response body, so the behavior of routing, authentication, and SPA fallback remains unchanged.

Configuration¶

Set the budget in the plugin configuration:

- id: cookie-janitor
  name: dsh-cookie-janitor
  config:
    maxCookies: 8        # Trim dsh-auth Cookies exceeding this count
    maxHeaderBytes: 4096 # Trim Cookie header bytes exceeding this count
    retain: 2            # Number of Cookies to retain after trimming, including the current authority's
    dryRun: false        # Only log the trimming that will happen, do not send deletion commands

Trimming is only triggered after exceeding the budget. So, a jar containing only one Cookie per alive instance will not be touched; multiple alive authorities on the same host can also continue to work until the jar exceeds the budget. After that, the oldest entries are expired, and the instances cleaned up need to log in again from the URL they printed.

Installation and Enabling¶

dsh plugin add dsh-cookie-janitor

Or directly from this repository:

dsh plugin add github:07-dot/dsh-cookie-janitor

If the host does not support hot-loading plugins, restart dsh web (or the Desktop app) after installation.

Manual Rescue and Scope¶

When the jar is no longer usable, you can let the plugin clear it all at once. Open the following address in the same browser holding these Cookies; it will expire all dsh-auth-* carried by that request and print statistics (largest Cookie header, number of Cookies seen, cumulative trimming count):

GET /__dsh-cookie-janitor

Then, reopen the DSH URL.

Not all scenarios require it. The Desktop app does not accumulate this type of Cookie: the main window communicates with Host via the dsh-app://app/ protocol handler, forwarding only the single Cookie saved in shell memory, and does not allow set-cookie into the page jar (noted in README as checked against DSH 0.2.1-rc.5). The truly exposed scenario is the web profile in the browser, where the jar is shared by all used ports during the Cookie lifecycle. The plugin is harmless when there is nothing to clean and sends no headers when under budget.

It also cannot handle large Cookie headers caused by reasons other than dsh-auth-*; these are deliberately preserved.

Requirements¶

• DSH 0.2.1-rc.1 or newer 0.2.x versions (see engines.dsh).
• No runtime dependencies, no build steps, no installation scripts.

Use Cases and Notes¶

Suitable for developers using dsh web to develop and debug in a real browser, where ports change constantly over a period of time and may trigger login multiple times. It prevents the situation where the interface is locked by 431, forcing manual Cookie clearing.

The plugin runs with the permissions of the current dsh process and can be used to clean up expired login Cookies and compress request headers. Before installing, you should review the source code and license (MIT) to ensure the behavior matches your deployment environment before enabling it.

Conclusion¶

The value of dsh-cookie-janitor lies in turning the problem of “login Cookies accumulating infinitely until 431,” which can only be discovered and cleared manually, into an automatic trimming behavior within the budget. Directory page and source code:

• Community Directory: https://www.skillhub.cn/plugins/07-dot/dsh-cookie-janitor
• GitHub: https://github.com/07-dot/dsh-cookie-janitor