The DSH ecosystem embraces the “everything is a plugin” philosophy. In backend scenarios for agent development, developers often need to parse, forge, or verify JWTs: manually decoding the header/payload and calculating expiration time is inefficient; manually constructing signatures during integration testing is error-prone; manually verifying signatures and validity periods is unreliable. The dsh-tool-jwt plugin provides deterministic solutions for these scenarios.

Core Capabilities

dsh-tool-jwt is a DSH plugin maintained by chenxuhl, providing HS256 JWT decoding (without signature verification), signing, and full verification. This plugin does not depend on external runtime libraries and uses only the Node built-in crypto module.

1. Decoding (Decode)

Parses the header and payload into JSON and calculates the expiration status based on the current clock (valid / expired / no-exp-claim). This feature does not verify the signature; it only performs structural parsing and expiration status calculation, useful for quickly inspecting token contents.

2. Signing (Sign)

Issues a token. It automatically fills in iat (issued at) and exp (expiration time), and supports specifying the validity period via the expiresInSeconds parameter.

3. Verification (Verify)

Full verification flow:
* Algorithm check: only accepts alg=HS256, and rejects alg=none or other algorithms.
* Signature verification: uses constant-time signature comparison (crypto.timingSafeEqual) to prevent timing attacks.
* Expiration check: supports the leewaySeconds parameter to allow a certain level of clock skew tolerance.

Installation

Use DSH’s Profile Bundle installation method. The plugin is automatically added to the profile’s layer stack.

Interactive (web) Profile installation:

dsh plugin --profile web add github:chenxuhl/dsh-tool-jwt

One-shot task (headless) Profile installation:

dsh plugin --profile headless add github:chenxuhl/dsh-tool-jwt

Typical Usage

The following commands show the specific invocation for the three core actions.

Decode a Token

View the token contents and expiration status without signature verification.

dsh run "jwt { action: \"decode\", token: \"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1MSJ9.sig\" }"

Sign a Token

Construct a test token with timestamps automatically filled in.

dsh run "jwt { action: \"sign\", payload: {\"sub\":\"u1\",\"role\":\"admin\"}, secret: \"topsecret\", expiresInSeconds: 3600 }"

Verify a Token

Verify the signature and validity period, with configurable leeway.

dsh run "jwt { action: \"verify\", token: \"...\", secret: \"topsecret\", leewaySeconds: 30 }"

Applicable Scenarios and Precautions

This plugin is intended for development and integration testing scenarios (decoding inspection, generating test tokens, and signature verification). Do not paste production secrets into untrusted sessions in production environments.

Security Model

  • Algorithm enforcement: verify mode enforces alg=HS256 and rejects other algorithms (such as alg=none) to prevent algorithm downgrade attacks.
  • Input limits: The plugin imposes strict limits on input sizes. Inputs exceeding the limits are rejected directly without truncation:
    • Token length ≤ 16KB
    • Secret length ≤ 4KB
    • Serialized payload ≤ 8KB
  • Mutual exclusion check: The secret (string secret) and secretBase64url (binary secret) parameters are mutually exclusive; passing both at the same time causes an error.

Ecosystem Context

DSH is the abbreviation for DeepSeek Harness. Its plugin ecosystem and community directory (https://www.skillhub.cn/plugins/chenxuhl/dsh-tool-jwt) operate independently and have no official affiliation with DeepSeek or High-Flyer.

For more details and source code, visit the GitHub repository.