omdsh-dev/dsh-tool-encoding

dsh-tool-encoding

English

DSH 编码/哈希工具插件 —— UTF-8 文本的 base64/base64url/url/hex 编解码 + 哈希 + UUID。零依赖、零进程、纯函数。

包名：@deepseek-ai/dsh-tool-encoding（独立 bundle，非 monorepo 集成形态）；lib/ 产物由仓库内 npm run build（tsc）生成并随仓库提交。

动机

Agent 处理编码/哈希是日常高频操作：查看 API 响应里的 base64 字段（JWT payload）、构造 query 参数、校验文件完整性（sha256）、生成 UUID。当前做法 bash -c "echo ... | base64" 的问题：进程开销、引号转义地狱（base64 串嵌进 bash 命令再嵌进 JSON 参数，双层转义错误率极高）、跨平台工具命名不一致（md5 vs md5sum vs shasum -a 256）。

安全模型

无 eval、无 new Function。所有操作是 Buffer/node:crypto/TextDecoder/encodeURIComponent 的纯函数组合：

• UTF-8 完整性：解码用 fatal 模式（TextDecoder('utf-8', { fatal: true })），非法字节抛 encoding: invalid UTF-8 output；合法 U+FFFD/控制字符不误伤（00 NUL、0a 换行、efbfbd U+FFFD 均合法，ff 非法）
• base64 严格校验：无空白、= 仅末尾且 ≤2、长度必须为 4 的倍数、RFC 4648 canonical unused bits（Zh== 等非 canonical 编码拒绝，防多串映射同文本）
• 孤立 surrogate 统一拒绝：所有文本输入过 String.prototype.isWellFormed()，避免静默替换与 URIError 行为不一致
• 字节上限：输入 1 MB / 输出 4 MB（各 1,000,000 / 4,000,000 字节，Buffer.byteLength；输出上限为分配前预估 + 最终检查的保险丝）
• 哈希算法白名单：Object.hasOwn 查表（md5/sha1/sha256/sha512）
• 错误统一 encoding: 前缀，不透传底层 URIError/TypeError

架构

DSH Agent
    │ ctx.tools.register()
    ▼
src/index.ts（Cordis 插件入口 + action 分发 + 独立校验）
    │
    ▼
src/encoding.ts
    ├── b64Encode/b64Decode — 标准 base64（严格校验）
    ├── b64UrlEncode/b64UrlDecode — base64url（canonical 无 padding，解码兼容）
    ├── urlEncode/urlDecode — component 语义（URIError 包装）
    ├── hexEncode/hexDecode — UTF-8 字节 hex（fatal 解码）
    ├── digest — 白名单哈希
    ├── newUuid — crypto.randomUUID()
    └── validateUnicode/assertInputBytes/decodeUtf8Strict — 校验器

工具声明

ctx.tools.register(defineTool({
  name: 'encoding',
  parameters: {
    action: {
      type: 'string', required: true,
      enum: ['base64_encode','base64_decode','base64url_encode','base64url_decode',
             'url_encode','url_decode','hex_encode','hex_decode','hash','uuid'],
    },
    input:     { type: 'string', description: 'Input string for encode/decode/hash' },
    algorithm: { type: 'string', enum: ['md5','sha1','sha256','sha512'], description: 'For hash' },
  },
  output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
  execute: (args) => Promise.resolve(executeAction(args.action, args) as JsonValue),
  timeoutMs: 1000,
}))