@huangjua

dsh-evidence

Name: dsh-evidence
Availability: InStock
Author: huangjua

🛡️ Verifiable, tamper-proof audit evidence bundles and hash-chained receipts for DSH agents

Stars: 0
Language: TypeScript
Created: Sep 1, 2026
Updated: Sep 1, 2026

Auth

GitHub repo

Introduction

🛡️ dsh-evidence

Verifiable, tamper-proof audit evidence bundles for DSH agent execution
SHA256 Manifests • Append-Only Hash-Chain Receipts • Temporal Validity (validUntil) • Zero Fluff

Features • Quick Start • DSH Power Suite • Tools • 简体中文

💡 Why dsh-evidence?

AI agents often hallucinate "tests passed" or succeed on commands that silently produce bad outputs. When delivering code or auditing tasks, there is no way to prove what really ran and whether outputs were modified afterwards.

dsh-evidence provides cryptographic proof of agent task execution:

⛓️ Append-Only Hash-Chained Receipts: Every snapshot or execution link appends a cryptographic hash to receipt.jsonl. Any post-hoc file modification immediately fails verification.
📦 Self-Contained Snapshots (copy=true): Bundle output directories, generated binaries, and validation scripts into portable, verifiable tarballs.
⏱️ Temporal Validity (validUntil): Explicitly tracks when evidence becomes stale (touched) or expired, preventing outdated logs from justifying new claims.
🤝 Honest Boundary Declarations: Clear definitions of what cryptographic hashing can and cannot prove.

🚀 Quick Start

Installation

# In your DSH plugin environment
dev_inject_plugin @dsh-external/dsh-evidence

Typical Usage Flow

Create evidence bundle: evidence_create name="bench-2026" description="Performance audit"
Add snapshots & assertions: evidence_add name="bench-2026" paths="bench.json|verify.py" claim="30% speedup verified" validUntil=2026-12-31
Audit and verify: evidence_verify name="bench-2026"

🧩 DSH Power Suite

This plugin is part of the DSH Agent Power Suite — 4 modular, zero-hard-dependency plugins forming a complete closed-loop developer workflow:

flowchart LR
    M["🧠 dsh-local-memory<br>(1. Remember rules & prefs)"] --> E["⚡ dsh-context-economy<br>(2. Save 80%+ tokens reading code)"]
    E --> A["🛡️ dsh-evidence<br>(3. Tamper-proof audit receipts)"]
    A --> S["🔍 dsh-session-index<br>(4. CJK search & bookmarks)"]
    S --> M

    style M fill:#e8f4fd,stroke:#2b7de9,stroke-width:2px
    style E fill:#eef9f2,stroke:#1e8e3e,stroke-width:2px
    style A fill:#fef7e0,stroke:#f29900,stroke-width:2px
    style S fill:#f3e8fd,stroke:#8430ce,stroke-width:2px

Plugin	Role in Suite	Synergy with Evidence
🛡️ dsh-evidence	Audit & Receipts (Current)	Creates cryptographic audit bundles and hash-chained receipts for agent execution.
🧠 dsh-local-memory	Memory Layer	Commits critical decisions into memory only after validating evidence receipts.
⚡ dsh-context-economy	Context Economy	Benchmarks (e.g. `savings-bench`) register evidence snapshots to prove real token savings.
🔍 dsh-session-index	Session Search	Search past session archives to pinpoint historical evidence receipts and jump back.

📖 Deep Dive & Reference

🛠️ Available Tools (5 Tools)

Tool	Purpose
`evidence_create`	Initialize evidence directory, `evidence.json` (v2), and `receipt.jsonl` chain.
`evidence_add`	Add files/directories (SHA256, size, mtime) with optional `claim`, `validUntil`, and `copy=true`.
`evidence_verify`	Recalculate SHA256 hashes, verify chain consistency, and audit against expiration/stale status.
`evidence_list`	List all local evidence packages with summary health counts.
`evidence_show`	Inspect complete manifest, claim assertions, timestamps, and receipt chains.

📁 Bundle Structure & Manifest Format

~/.dsh/evidence/<name>/
  evidence.json     # Manifest with top-level manifestHash self-integrity
  receipt.jsonl     # Append-only hash-chained receipts
  files/            # Self-contained copies when copy=true

⚖️ Honest Capability Declarations

Can Prove: Snapshot content matching, file alteration (corrupt/stale), manual edits to evidence.json, and receipt sequence tampering.
Cannot Prove: Command intention authenticity, author identity, or file system root access tampering (hashes are not digital signatures).

🧪 Building & Testing

node scripts/build.mjs                 # Compile src ➡️ lib
npm run typecheck
npm test                                # Run test suite
npm run pack:check                      # Packaging check

_{Part of the DSH Agent Power Suite. Licensed under BSD-3-Clause.}