Canon B Demonstration Guide

This guide provides step-by-step instructions for demonstrating the Canon B cross-attestation system.

Overview

The demonstration shows how two AI companions (Canon B and Canon A) can establish mutual trust through cryptographic attestations without centralized control.

Prerequisites

Required Setup

1. GitHub Account Access

   • Access to QuietWire-Civic-AI organization
   • Fine-grained PAT with appropriate scopes
   • Repository secrets configured

2. Repository Access

   • canon-b repository: QuietWire-Civic-AI/canon-b
   • canon-a repository: QuietWire-Civic-AI/canon-a

3. Local Environment

   • Git CLI installed
   • GitHub CLI (gh) installed
   • jq for JSON processing

Verification Steps

# Verify GitHub CLI authentication
gh auth status

# Check repository access
gh repo view QuietWire-Civic-AI/canon-b
gh repo view QuietWire-Civic-AI/canon-a

# Verify local tools
which git jq

Demonstration Scenarios

Scenario 1: Basic Cross-Attestation

Objective: Show Canon B creating an attestation about Canon A

Step 1: Prepare the Environment

# Clone both repositories
git clone https://github.com/QuietWire-Civic-AI/canon-b.git
git clone https://github.com/QuietWire-Civic-AI/canon-a.git

cd canon-b

Step 2: Review Current State

# Show Canon B's self-claims
echo "=== Canon B Claims ==="
cat canon/claims/claim-A-0001.txt

echo "\n=== Current Attestations ==="
ls -la canon/attestations/

Step 3: Examine Canon A's Claims

# Review what Canon B will attest about
echo "=== Canon A Claims (Target) ==="
cat ../canon-a/canon/claims/claim-B-0001.txt

# Calculate claim hash
echo "\n=== Claim Hash ==="
sha256sum ../canon-a/canon/claims/claim-B-0001.txt

Step 4: Create Attestation Request

# Open an issue for attestation
gh issue create --title "Demo: Attestation Request" \
  --body "Requesting attestation of Canon A for demonstration purposes."

# Get the issue number
ISSUE_NUM=$(gh issue list --limit 1 --json number --jq '.[0].number')
echo "Created issue #$ISSUE_NUM"

Step 5: Trigger Attestation Workflow

# Submit attestation command
gh issue comment $ISSUE_NUM \
  --body "/attest QuietWire-Civic-AI/canon-a \"Canon B\""

echo "Attestation request submitted. Monitoring workflow..."

Step 6: Monitor Workflow Execution

# Watch for workflow runs
echo "Watching for workflow execution..."
gh run list --limit 5

# Get the latest run ID and monitor
RUN_ID=$(gh run list --limit 1 --json databaseId --jq '.[0].databaseId')
gh run watch $RUN_ID

Step 7: Verify Attestation Creation

# Check for new PR in canon-a
echo "Checking for attestation PR in canon-a..."
gh pr list --repo QuietWire-Civic-AI/canon-a --state open

# Get PR details
PR_NUM=$(gh pr list --repo QuietWire-Civic-AI/canon-a --limit 1 --json number --jq '.[0].number')
if [ ! -z "$PR_NUM" ]; then
  echo "Found PR #$PR_NUM"
  gh pr view $PR_NUM --repo QuietWire-Civic-AI/canon-a
fi

Step 8: Review Attestation Content

# Show the attestation files in the PR
if [ ! -z "$PR_NUM" ]; then
  echo "=== Attestation Files ==="
  gh pr diff $PR_NUM --repo QuietWire-Civic-AI/canon-a
fi

Scenario 2: Mutual Attestation

Objective: Show bidirectional trust establishment

Step 1: Complete Canon B → Canon A Attestation

# Merge the attestation PR in canon-a
if [ ! -z "$PR_NUM" ]; then
  gh pr merge $PR_NUM --repo QuietWire-Civic-AI/canon-a --squash
  echo "Canon B's attestation merged into Canon A"
fi

Step 2: Request Reverse Attestation

# Create issue in canon-a for reverse attestation
gh issue create --repo QuietWire-Civic-AI/canon-a \
  --title "Demo: Reverse Attestation Request" \
  --body "Requesting Canon A to attest Canon B"

B_ISSUE_NUM=$(gh issue list --repo QuietWire-Civic-AI/canon-a --limit 1 --json number --jq '.[0].number')
echo "Created issue #$B_ISSUE_NUM in canon-a"

Step 3: Trigger Reverse Attestation

# Submit reverse attestation command
gh issue comment $B_ISSUE_NUM --repo QuietWire-Civic-AI/canon-a \
  --body "/attest QuietWire-Civic-AI/canon-b \"Canon A\""

echo "Reverse attestation request submitted"

Step 4: Monitor and Complete

# Watch for PR in canon-b
echo "Waiting for reverse attestation PR..."
sleep 30  # Allow workflow time to execute

REVERSE_PR=$(gh pr list --limit 1 --json number --jq '.[0].number')
if [ ! -z "$REVERSE_PR" ]; then
  echo "Found reverse attestation PR #$REVERSE_PR"
  gh pr view $REVERSE_PR
  gh pr merge $REVERSE_PR --squash
fi

Scenario 3: Validation and Verification

Objective: Demonstrate attestation integrity checking

Step 1: Validate JSON Structure

# Check all attestation files
echo "=== Validating Attestation JSON ==="
for file in canon/attestations/*.json; do
  if [ -f "$file" ]; then
    echo "Validating $file"
    jq empty "$file" && echo "✅ Valid JSON" || echo "â‌Œ Invalid JSON"
  fi
done

Step 2: Verify Signature Files

# Check signature file presence
echo "\n=== Checking Signature Files ==="
for json_file in canon/attestations/*.json; do
  if [ -f "$json_file" ]; then
    sig_file="${json_file%%.json}__sig.json"
    if [ -f "$sig_file" ]; then
      echo "✅ $sig_file exists"
      jq empty "$sig_file" && echo "✅ Valid signature JSON" || echo "â‌Œ Invalid signature JSON"
    else
      echo "â‌Œ Missing signature file: $sig_file"
    fi
  fi
done

Step 3: Verify Claim Hashes

# Validate claim hash accuracy
echo "\n=== Verifying Claim Hashes ==="
for json_file in canon/attestations/*.json; do
  if [ -f "$json_file" ]; then
    echo "Checking $json_file"
    
    # Extract subject repo and claim hash from attestation
    SUBJECT_REPO=$(jq -r '.subject_repo' "$json_file")
    CLAIM_HASH=$(jq -r '.claim_hash' "$json_file")
    
    echo "Subject: $SUBJECT_REPO"
    echo "Claimed hash: $CLAIM_HASH"
    
    # Determine claim file based on subject repo
    if [[ "$SUBJECT_REPO" == *"canon-a" ]]; then
      CLAIM_FILE="../canon-a/canon/claims/claim-B-0001.txt"
    else
      CLAIM_FILE="../canon-b/canon/claims/claim-A-0001.txt"
    fi
    
    if [ -f "$CLAIM_FILE" ]; then
      ACTUAL_HASH=$(sha256sum "$CLAIM_FILE" | cut -d' ' -f1)
      echo "Actual hash: $ACTUAL_HASH"
      
      if [ "$CLAIM_HASH" = "$ACTUAL_HASH" ]; then
        echo "✅ Hash verification passed"
      else
        echo "â‌Œ Hash verification failed"
      fi
    else
      echo "â‌Œ Claim file not found: $CLAIM_FILE"
    fi
    echo "---"
  fi
done

Troubleshooting Demo Issues

Workflow Not Triggering

# Check if user is in allowlist
grep -A 10 "allowlist" .github/workflows/attest.yml

# Verify issue comment format
echo "Correct format: /attest QuietWire-Civic-AI/canon-a \"Canon B\""

# Check workflow file syntax
yq eval '.jobs' .github/workflows/attest.yml

Token Permission Issues

# Verify repository secrets
gh secret list

# Test token permissions
gh api repos/QuietWire-Civic-AI/canon-a/contents/README.md

JSON Validation Failures

# Manual JSON validation
jq . canon/attestations/problematic.json

# Fix common issues:
# - Escape quotes in strings
# - Remove trailing commas
# - Ensure UTF-8 encoding

Presentation Tips

Key Talking Points

1. Decentralized Trust

   • No central authority validates attestations
   • Each companion validates the other's claims
   • Cryptographic hashes ensure integrity

2. Transparency

   • All attestations are publicly visible
   • Complete audit trail in Git history
   • JSON format enables programmatic validation

3. Automation

   • GitHub Actions automate the attestation process
   • Human oversight through PR review process
   • Scalable to multiple repositories

Demo Flow Suggestions

1. Start with Claims - Show what each companion claims about itself
2. Show the Gap - Explain why external validation is needed
3. Trigger Attestation - Demonstrate the automated process
4. Verify Results - Show the attestation files and validation
5. Complete the Circle - Show mutual attestation

Common Questions

Q: How is this different from traditional PKI? A: This is more transparent and doesn't require a certificate authority. All attestations are public and auditable.

Q: What prevents malicious attestations? A: The allowlist restricts who can create attestations, and all changes go through PR review.

Q: How does this scale? A: Each repository pair can establish mutual attestation. Networks of trust can emerge organically.

Q: What about real cryptographic signatures? A: This demo currently uses SHA-256 digests (encoded as base64) for tamper detection, but the framework can be extended to support SSH, GPG, or other signature types.

---

Demo Guide Version: 1.0
Last Updated: 2025-10-06
Target Audience: Technical stakeholders, AI researchers, DevOps teams