dsh-secret-scrub

English | 中文

Irreversible secret-scrubbing guard plugin, extracted from the user-sensitive-information protection strategy of the kaya-ai-terminal project and open-sourced standalone (Mainland China site: https://www.yunhouai.com; international site: https://www.yunhou.ai). It rewrites text on its way to the session log and the model: when a configured rule matches a secret-shaped fragment — an access key, a bearer token, a private key block — the fragment is replaced irreversibly with a [REDACTED:<category>] placeholder, so the durable log and the model request carry only the placeholder at the covered points.

Install

npm install dsh-secret-scrub

Runtime dependencies are @deepseek-ai/cordis (peer) and @deepseek-ai/schemastery. The @deepseek-ai/dsh-* peer packages are type-only and optional.

Use with dsh

This package declares dsh.bundle.patch, so installation is a single command — the plugin activates with the default balanced scrub level and needs no credentials:

# 1. Install the dsh CLI
npm i -g @deepseek-ai/dsh

# 2. Install this plugin into the target profile (headless shown as an example)
dsh plugin --profile headless add dsh-secret-scrub
#    To test local changes before publishing, use the tarball from `npm pack`:
#    dsh plugin --profile headless add /path/to/dsh-secret-scrub-0.1.1.tgz

# 3. Restart the profile, then run a task that contains secrets — they will be redacted before reaching the model/session log
dsh --profile headless "echo AWS AKIAIOSFODNN7EXAMPLE"

dsh plugin add applies the cordis.patch.yml shipped inside this package (mounting the plugin at balanced level). To change the level or add custom rules, override the same id in the profile patch layer ~/.dsh/profiles/headless/cordis.patch.yml:

- id: secret-scrub
  config:
    level: aggressive
    extra:
      - category: internal-token
        pattern: 'internal-[0-9]{4}'

Use as a standalone Cordis plugin

If you are not using dsh, you can also mount the plugin directly on a Cordis context:

import { Context } from '@deepseek-ai/cordis'
import * as SecretScrub from 'dsh-secret-scrub'

const ctx = new Context()
await ctx.plugin(SecretScrub, {
  level: 'aggressive',               // scrub depth: minimal | balanced (default) | aggressive
  disabled: ['env-var-secret'],      // tier 1/2 built-in categories only — tier 0 cannot be disabled
  extra: [
    { category: 'internal-token', pattern: 'internal-[0-9]{4}' },
  ],
})

The plugin mounts three prepended waterfall listeners that delegate first and then scrub whatever the rest of the chain admitted:

• agent/pre-step rewrites each step's admitted user messages before they reach the session log and the model request.
• tools/post-execute rewrites an accepted tool result's plain content.
• tools/ptc-dispatch-log rewrites the durable tool/code-dispatch copy of a run_code sub-dispatch.

Field	Default	Meaning
level	balanced	Scrub depth: minimal runs tier 0 only, balanced adds tier 1, aggressive adds tier 2 — PII and the high-entropy fallback
disabled	[]	Built-in tier 1/2 categories to turn off; a tier-0 core rule cannot be disabled and fails the load
extra	[]	Deployment-added rules, active at every level: a unique lowercase-dashed category plus a pattern compiled with new RegExp(pattern, 'g')

Invalid configuration fails at startup with a clear error — an unknown or tier-0 disabled category, an extra pattern that does not compile, a category id that cannot appear in the placeholder, or a duplicate category — never a silent fall-back.

Built-in rule tiers

level selects the highest active tier. Tiers 0–1 are prefix-anchored and tier 2 matches shapes (the patterns live in src/rules.ts):

Tier	Active at	Categories
0 — core secrets	every level; cannot be disabled	private-key, aws-access-key, github-token, google-api-key, deepseek-key, openai-key, anthropic-key, gitlab-pat, stripe-key, slack-token, npm-token, pypi-token, sendgrid-key, twilio-key, digitalocean-token, shopify-token, telegram-bot-token, tavily-key, url-credentials (connection-URL authority), url-access-token (OAuth callback token), generic-bearer (bearer tokens and JWTs)
1 — assignment and cloud-provider keys	balanced and up	env-var-secret (uppercase assignments whose name carries KEY/SECRET/TOKEN/PASSWORD as a whole _-delimited segment), azure-storage-key, alibaba-access-key
2 — PII and the high-entropy fallback	aggressive only	email, phone-cn, phone-intl, id-cn, credit-card (Luhn-checked), ssn-us, high-entropy

Use the engine directly

The pure scrubbing engine is exported from dsh-secret-scrub/rules and has no Cordis dependency:

import { BUILTIN_RULES, scrubText } from 'dsh-secret-scrub/rules'

const { text, redactions } = scrubText('key: AKIAIOSFODNN7EXAMPLE', BUILTIN_RULES)
// text       → 'key: [REDACTED:aws-access-key]'
// redactions → { 'aws-access-key': 1 }

Known limitations

Redaction is one-way and regex-based. Unprefixed keys, secrets split across text blocks, and encoded forms (base64-wrapped, URL-escaped) evade the conservative rule shapes by design. The tier-2 rules match shapes, not proven secrets, so they trade false positives for coverage — an email address in a task instruction is redacted as if it were a secret, and hash-like text (git SHAs, SHA-256 digests) matches the high-entropy fallback at aggressive. Do not rely on this guard as the only control against credential leaks.

Development

npm install
npm run typecheck
npm test
npm run build

License

MIT — Copyright (c) 2026 jkt-check