1

Witness Verification

ruv edited this page 2026-05-25 10:01:20 -04:00

Table of Contents

• Witness Verification
• What It Protects
• How It Works
• Verify an Installation
• Manifest Structure
• Regenerate Manifest
• Cross-Sign with External Auditor
• Temporal History (ADR-124)
• CI/CD Integration
• Commands
• Keys & Security
• Public Key
• Private Key
• Limitations
• ADR-103 & ADR-124

Witness Verification

Ruflo uses cryptographic artifact verification (ADR-103) to ensure installed code matches the audited baseline.

---

What It Protects

The witness manifest verifies:

• Source files — No code substitution
• Dist artifacts — Builds match source
• npm packages — Downloaded version is genuine
• Dependencies — No supply-chain attacks
• Configuration — Settings match baseline

---

How It Works

Source Code → Build → Dist Artifacts → Hash → Ed25519 Sign → Manifest
                                                              ↓
                                                      verification.md
                                                      verification.md.json

The manifest is:

• Signed with Ed25519 private key
• Timestamped (includes build date, commit hash)
• Witnessed by external auditor (when applicable)
• Published with each release

---

Verify an Installation

npx ruflo@latest verify

Output:

Verification Report
===================
Status: ✓ VERIFIED
Manifest: verification.md (v3.10.1)
Signature: Valid (Ed25519)
Build Date: 2026-05-24 15:32:10 UTC
Commit: 4a57be7b8 (main)

Artifacts Verified:
  ✓ v3/@claude-flow/cli/dist/cli.js (SHA-256: abc123...)
  ✓ v3/@claude-flow/codex/dist/index.js (SHA-256: def456...)
  ✓ ruflo/dist/index.js (SHA-256: ghi789...)
  ... 127 more artifacts

Result: All 130 artifacts verified ✓

---

Manifest Structure

verification.md (human-readable):

# Ruflo v3.10.1 Witness Manifest

Build: 2026-05-24 15:32:10 UTC
Commit: 4a57be7b8
Signed: Ed25519 public-key-123...

## Artifacts (130 total)

| Path | SHA-256 | Status |
|------|---------|--------|
| v3/@claude-flow/cli/dist/cli.js | abc123... | ✓ |
| v3/@claude-flow/cli/dist/mcp-tools.js | def456... | ✓ |
| ...

verification.md.json (machine-readable):

{
  "version": "3.10.1",
  "build_date": "2026-05-24T15:32:10Z",
  "commit": "4a57be7b8",
  "artifacts": [
    {
      "path": "v3/@claude-flow/cli/dist/cli.js",
      "sha256": "abc123...",
      "size": 1234567,
      "witness_id": "auditor-2026-05"
    }
  ],
  "signature": "sig_...",
  "public_key": "pk_..."
}

---

Regenerate Manifest

After a clean build:

# Build everything
npm run build

# Regenerate manifest
npx ruflo@latest witness sign \
  --manifest verification.md \
  --private-key ~/.ruflo/signing-key

# Verify it worked
npx ruflo@latest verify

---

Cross-Sign with External Auditor

For enterprise use, have a trusted auditor co-sign:

# Export manifest
npx ruflo@latest witness export \
  --output verification.md \
  --format json

# Send to auditor for review + signature
# Auditor runs their own verification and adds signature

# Merge auditor's signature
npx ruflo@latest witness merge \
  --manifest verification.md \
  --auditor-signature auditor-sig.json

# Result: dual-signed manifest
npx ruflo@latest verify --show-witnesses

Output:

Witnesses:
  ✓ Ruflo Team (2026-05-24)
  ✓ External Auditor A (2026-05-25)

---

Temporal History (ADR-124)

Each witness includes:

• Timestamp (when verified)
• Commitment (prior build hash this build depends on)
• Confidence (probability of correctness)

Query the chain:

npx ruflo@latest witness history

Output:

Witness Chain (5 releases):

v3.10.1
├─ Built: 2026-05-24 15:32:10
├─ Commit: 4a57be7b8
├─ Witnesses: Team (100% confidence), Auditor-A (95% confidence)
└─ Depends on: v3.10.0

v3.10.0
├─ Built: 2026-05-18 10:15:30
├─ Commit: 35708bd7e
├─ Witnesses: Team (100% confidence)
└─ Depends on: v3.9.5

---

CI/CD Integration

Verify in your GitHub Actions:

- name: Verify Ruflo Artifacts
  run: |
    npx ruflo@latest verify --source-mode  # Skip dist artifacts in source checkout
    if [ $? -ne 0 ]; then exit 1; fi

---

Commands

Command	Purpose
npx ruflo@latest verify	Verify installation
npx ruflo@latest witness sign	Create/update manifest
npx ruflo@latest witness history	Show witness chain
npx ruflo@latest witness export	Export manifest for sharing
npx ruflo@latest witness merge	Merge external signatures

---

Keys & Security

Public Key

Published in:

• v3/@claude-flow/cli/src/witness/public-key.ts
• NPM package metadata
• GitHub releases

Private Key

Stored in:

• ~/.ruflo/signing-key (locally, after init)
• GitHub Secrets (CI/CD)

Never share the private key.

---

Limitations

• Source-only verification — If checking out without build, use --source-mode
• Missing artifacts warning — Issue #2047 (95 artifacts marked missing in scheduled runs)
• Time drift — Timestamps are advisory; Git commit is the canonical reference

---

ADR-103 & ADR-124

For full architecture:

• ADR-103 — Witness temporal history (original design)
• ADR-124 — Extended with causality and confidence

---

Ruflo v3.10.1 · GitHub · Verification

Getting Started

• Home
• Installation
• Quick Start

Reference

• CLI Reference
• MCP Tools
• Agents

Architecture

• Memory & Graph
• Intelligence Pipeline
• Hooks & Workers
• Hive-Mind

Advanced

• Plugins
• ADR Index
• Benchmarks
• Witness Verification

Operations

• Troubleshooting
• Contributing
• Roadmap

Ruflo v3.10.1 · npm · GitHub · Benchmarks