Preface

In DSH agent workflows, handling encoding, hashing, and UUIDs is a common operation: reading base64 fields from API responses, constructing query parameters, validating sha256 digests, and generating UUIDs. Putting these operations into shell external commands introduces process scheduling and command concatenation overhead.

omdsh-dev/dsh-tool-encoding is a DSH encoding/hashing tool plugin that provides base64/base64url/url/hex encoding/decoding, hashing, and UUID operations for UTF-8 text. It is positioned as zero-dependency, zero-process, and pure functions.

What is this

  • Repository: omdsh-dev/dsh-tool-encoding
  • Maintainer: omdsh-dev
  • License: MIT
  • Compatible Version: DSH 0.1.2-alpha.2 (npm)
  • Core Positioning: Provide a set of text encoding, hashing, and UUID tools for the DSH Agent, covering common base64/base64url/url/hex scenarios.

Core Features

The following describes verified operations. All actions process UTF-8 text, outputting strings; input limit is 1 MB, output limit is 4 MB (bytes).

action Capability Example
base64_encode / base64_decode RFC 4648 standard base64, strict validation foobar → Zm9vYmFy
base64url_encode / base64url_decode JWT-style base64url, output without padding; decoding compatible with +/ and optional padding U+FEFF → 77u_
url_encode / url_decode Component semantics: spaces encoded as %20, not +; !'()* not escaped a b → a%20b
hex_encode / hex_decode UTF-8 byte hex; decoded result must be valid UTF-8 AB → 4142
hash md5/sha1/sha256/sha512 hex digests sha256 empty string → e3b0c442...
uuid UUID v4 string, using crypto.randomUUID() 550e8400-...

Validation behaviors include:

  • base64 input performs RFC 4648 canonical validation
  • UTF-8 decoding uses fatal mode
  • Isolated surrogates are uniformly rejected
  • hex_decode result must be valid UTF-8
  • hash algorithm whitelist is md5, sha1, sha256, sha512

Installation and Enablement

First, install to the web profile:

dsh plugin --profile web add github:omdsh-dev/dsh-tool-encoding

After the above steps, you can perform a configuration check:

dsh --profile web --dump-config | grep tool-encoding

If verifying in dsh run, note that web and headless are different profiles. dsh run defaults to the headless profile, so that profile also needs to be installed separately. The installation command example provided in the verified materials for this time is for the web profile; the verification command is as follows:

dsh run "使用 encoding 工具把 hello 做 base64 编码"

Typical Usage

You can select the corresponding action within a DSH session:

  1. Base64: Select base64_encode, input foobar, get Zm9vYmFy.

  2. Base64URL: Select base64url_encode, input U+FEFF, get 77u_.

  3. URL component: Select url_encode, input a b, get a%20b.

  4. Hex: Select hex_encode, input AB, get 4142.

  5. Hash: Select hash, use sha256, input empty string, get e3b0c442....

  6. UUID: Select uuid, returns a UUID v4 string like 550e8400-....

Suitable Scenarios and Notes

Suitable for processing UTF-8 text encoding, digest validation, and UUID generation. Precautions before use:

  • Do not use this tool for sensitive materials: tool parameters are logged into session logs
  • The plugin runs with the current dsh process permissions; check source code and license before installing
  • hash is only for digests, no HMAC/salting/key derivation; MD5/SHA-1 are for compatibility/non-secure integrity checks only
  • Decoding/encoding arbitrary binary (non-printable bytes) requires v2’s output: "utf8" | "hex" mode
  • URL is component semantics; form encoding (space → +) requires a separate action (v2)
  • web and headless are different profiles; installing to web does not automatically override headless

Conclusion

dsh-tool-encoding collects the frequently occurring text encoding, hashing, and UUID operations in DSH into a set of tools, reducing external commands and escape concatenation. The materials for this time do not provide a directory page address; the GitHub repository is:

https://github.com/omdsh-dev/dsh-tool-encoding