If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/in3rsha/sha256-animation shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

AVOID — Looks unmaintained — solo project with stale commits

• MIT licensed
• ⚠ Stale — last commit 2y ago
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live in3rsha/sha256-animation repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/in3rsha/sha256-animation.

What it runs against: a local clone of in3rsha/sha256-animation — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in in3rsha/sha256-animation | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 825 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of in3rsha/sha256-animation. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/in3rsha/sha256-animation.git
#   cd sha256-animation
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of in3rsha/sha256-animation and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "in3rsha/sha256-animation(\\.git)?\\b" \\
  && ok "origin remote is in3rsha/sha256-animation" \\
  || miss "origin remote is not in3rsha/sha256-animation (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "sha256.rb" \\
  && ok "sha256.rb" \\
  || miss "missing critical file: sha256.rb"
test -f "hash256.rb" \\
  && ok "hash256.rb" \\
  || miss "missing critical file: hash256.rb"
test -f "compression.rb" \\
  && ok "compression.rb" \\
  || miss "missing critical file: compression.rb"
test -f "message.rb" \\
  && ok "message.rb" \\
  || miss "missing critical file: message.rb"
test -f "padding.rb" \\
  && ok "padding.rb" \\
  || miss "missing critical file: padding.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 825 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~795d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/in3rsha/sha256-animation"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

sha256-animation is a Ruby project that visualizes the SHA-256 cryptographic hash function step-by-step in the terminal. It animates each stage of the algorithm—message padding, block scheduling, compression rounds, and final hash output—with ASCII art and frame-by-frame visualization. It also includes a hash256.rb script for double-SHA256 hashing (used in Bitcoin) and individual scripts for testing SHA-256 primitives like ROTR, SHR, sigma functions, and bitwise operations. Single-file-per-function architecture: 40+ individual Ruby scripts (e.g., shr.rb, rotr.rb, sigma0.rb, ch.rb, maj.rb) implement specific SHA-256 operations; orchestration scripts (sha256.rb, hash256.rb) compose them with animation logic. No class-based structure, no external gem dependencies. The images/ directory holds GIFs demonstrating each operation visually. Entry point is sha256.rb which reads CLI arguments, processes message data, and renders terminal animation.

Cryptography students, security researchers, and developers learning how SHA-256 works internally. Bitcoin/blockchain developers who need to understand double-SHA256 hashing. Anyone who learns better by seeing algorithms animate rather than reading FIPS specifications.

This is a mature educational reference project. It is a single-author repository (in3rsha) with a focused scope and no automated test suite or CI pipeline visible in the file structure. The project is feature-complete for its stated goal (visualizing SHA-256) and unlikely to have active development, but remains a stable, self-contained teaching tool with no external runtime dependencies.

Low risk for educational use. The repo is pure Ruby with no external dependencies listed, so supply-chain compromise is not a concern. Single-maintainer status and lack of automated tests mean correctness relies on manual verification against the NIST FIPS 180-4 specification. No breaking changes are likely since the API is stable and the scope is narrow. Not suitable for production cryptography—use OpenSSL or other vetted libraries instead.

No active development visible. This is a completed educational project. The GitHub presence is stable with README, specification-accurate implementations, and visual documentation via GIFs. No open issues, PRs, or milestones are mentioned in the repo data.

git clone https://github.com/in3rsha/sha256-animation.git
cd sha256-animation
ruby sha256.rb abc

Daily commands:

# Basic SHA-256 animation
ruby sha256.rb abc

# With speed control
ruby sha256.rb abc fast
ruby sha256.rb abc enter  # step through

# Double-SHA256 (Bitcoin-style)
ruby hash256.rb 0100000000000000000000000000000000000000000000000000000000000000000000003ba3edfd7a7b12b27ac72c3e67768f617fc81bc3888a51323a9fb8aa4b1e5e4a29ab5f49ffff001d1dac2b7c

# Test individual primitives
ruby shr.rb 11111111111111110000000000000000 22
ruby rotr.rb 11111111111111110000000000000000 22
ruby sigma0.rb 11111111111111110000000000000000

• sha256.rb — Main entry point script that orchestrates the entire SHA-256 animation; all users start here.
• hash256.rb — Core SHA-256 algorithm implementation that coordinates all compression rounds and final hash computation.
• compression.rb — Implements the compression function loop that is the mathematical heart of SHA-256 processing.
• message.rb — Handles message input parsing from strings, binary, hex, and files—critical for data normalization.
• padding.rb — Implements SHA-256 padding algorithm that prepares messages for block processing.
• blocks.rb — Splits padded message into 512-bit blocks for processing by compression rounds.
• expansion.rb — Expands 16-word block into 64-word schedule used in compression function iterations.

• Message Parser (message.rb) (Ruby File I/O, regex for prefix detection) — Converts user input (string, binary 0b, hex 0x, file path) into a binary string.
  • Failure mode: Invalid input format → parsing error; file not found → error; binary/hex parse failure → error
• Padding (padding.rb) (Bit manipulation, binary string operations) — Applies SHA-256 padding (append '1', zeros, 64-bit length) to produce message length multiple of 512 bits.
  • Failure mode: Incorrect padding length → wrong hash output; off-by-one errors → invalid block boundaries
• Block Division (blocks.rb) (String slicing) — Splits padded message into 512-bit blocks for independent processing.
  • Failure mode: Uneven block split → corrupted block; overlapping slices → duplicate processing

Add a new standalone bitwise operation function

1. Create a new .rb file in the root (e.g., newop.rb) following the pattern: accept binary string arguments, perform the operation, and call animate() from sha256lib.rb to display each step. (newop.rb)
2. Import sha256lib.rb at the top and define the animate function calls with clear step descriptions. (sha256lib.rb)
3. Test by running: ruby newop.rb <binary_args> with the animate speed parameter (normal/fast/enter). (sha256.rb)

Add support for a new input format

1. Edit message.rb to detect the new input format (e.g., Base64, UTF-16) in the message parsing logic. (message.rb)
2. Add conversion logic to convert the new format into a binary string that the rest of the pipeline expects. (message.rb)
3. Update sha256.rb to handle the new format in ARGV parsing and document it in a usage comment. (sha256.rb)

Modify animation timing or visual presentation

1. Edit sha256lib.rb animate() function to adjust sleep duration, color codes, or terminal formatting. (sha256lib.rb)
2. Update sha256.rb to add new speed modes if desired (beyond normal/fast/enter). (sha256.rb)
3. Test the visual output with: ruby sha256.rb abc <speed_mode> (sha256.rb)

• Ruby — Interpreted language with concise syntax ideal for educational animations and terminal output manipulation; no compilation overhead.
• Terminal-based animation (ANSI codes) — Makes the algorithm visually interactive and step-by-step transparent; pedagogical value for understanding SHA-256 internals.
• Binary string representation — Direct representation of 32-bit and 256-bit values allows transparent bit manipulation and animation of each operation.

• Separate files for each bitwise operation (rotr.rb, shr.rb, etc.)

  • Why: Maximizes educational clarity and allows standalone testing/animation of individual functions.
  • Consequence: More file fragmentation and slightly higher overhead than combining into modules; trade-off favors learning over performance.

• Animation as first-class feature (integrated into every function)

  • Why: Makes the tool unique for education; users see every intermediate step.
  • Consequence: Execution is slow relative to optimized SHA-256 libraries; tool is unsuitable for production hashing.

• Binary string input/output throughout (not integer types)

  • Why: Simplifies animation and visualization; bit patterns are directly readable.
  • Consequence: Memory overhead and slower arithmetic than native 32-bit integers; performance is not a goal.

• Production-grade cryptographic hashing (use a native library instead)
• Performance optimization or benchmarking
• Support for SHA-1, SHA-512, or other hash variants
• Parallel processing or multi-threaded execution
• Web UI or graphical interface (terminal-only)

No hidden traps. Pure Ruby with no external dependencies, no environment variables, no services. Ensure your Ruby version supports bitwise operators (all modern Ruby 2.0+). File input via ruby sha256.rb file.txt will include the trailing newline character—this is by design but can surprise users expecting the raw file hash. Binary and hex input require 0b and 0x prefixes respectively, or they are treated as text.

• SHA-256 (Secure Hash Algorithm 256-bit) — Core algorithm this repo visualizes; understanding its structure (message schedule, compression rounds, final hash output) is essential for cryptocurrency, TLS, and digital signatures
• Merkle-Damgård Construction — SHA-256 is built on this design pattern (padding + block processing + finalization); understanding it explains why padding.rb and blocks.rb are separate steps
• Bitwise Operations (AND, OR, XOR, NOT, rotate, shift) — SHA-256 is 100% bitwise manipulation; this repo implements ROTR (rotate right), SHR (shift right), AND, XOR as separate visualizations—learning these is mandatory
• Message Schedule (W array) — expansion.rb expands 16 message words into 64 words using sigma functions; this is a non-obvious design choice that affects collision resistance
• Compression Function / Round Function — compression.rb implements 64 rounds of stateful transformations on A–H working variables; this is where the cryptographic strength comes from
• Double-SHA256 (Bitcoin standard) — hash256.rb applies SHA-256 twice; Bitcoin uses this for proof-of-work and transaction IDs, making it critical for blockchain understanding
• Difference between uppercase (Σ) and lowercase (σ) sigma functions — usigma0.rb and usigma1.rb (uppercase) differ from sigma0.rb and sigma1.rb (lowercase) in rotation amounts; swapping them breaks SHA-256 silently, so this repo's separation is pedagogically valuable

• openssl/openssl — Production-grade SHA-256 implementation in C; referenced as the correct behavior for verification and the standard for real cryptographic use
• bitcoin/bitcoin — Uses double-SHA256 (implemented in hash256.rb) for proof-of-work and transaction hashing; this repo can help Bitcoin developers understand the hashing pipeline
• jedisct1/libsodium — Secure cryptographic library with SHA-256; reference for how production crypto code handles edge cases and constant-time operations
• trezor/trezor-firmware — Hardware wallet firmware extensively uses SHA-256 and double-SHA256; this animation helps firmware engineers understand the algorithm they're implementing
• RubyBitcoin/bitcoin-ruby — Ruby Bitcoin library that likely calls hash256.rb or equivalent; users of this library benefit from understanding SHA-256 internals via the animation

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test suite for individual SHA-256 functions

The repo has 15+ individual function files (shr.rb, rotr.rb, sigma0.rb, etc.) but no visible test directory. Adding unit tests would catch regressions, verify correctness against NIST test vectors, and make the codebase more maintainable. This is especially critical for cryptographic functions where correctness is non-negotiable.

• [ ] Create test/ directory with test_helper.rb
• [ ] Add unit tests for bitwise operations: test_shr.rb, test_rotr.rb, test_xor.rb
• [ ] Add unit tests for sigma functions: test_sigma0.rb, test_sigma1.rb, test_usigma0.rb, test_usigma1.rb
• [ ] Add unit tests for CH and MAJ functions: test_ch.rb, test_maj.rb
• [ ] Add integration test for hash256.rb against known SHA-256 test vectors (empty string, 'abc', long messages)
• [ ] Set up test runner in README (e.g., 'rake test' or 'ruby -Ilib:test test/**/*_test.rb')

Extract shared animation utilities into a dedicated module

The 15+ individual function files (add.rb, ch.rb, compression.rb, etc.) likely contain repetitive animation/display logic. Creating a shared AnimationHelper or DisplayUtils module would reduce code duplication, make animations consistent, and simplify maintenance. This refactoring would be visible across all the function files.

• [ ] Analyze add.rb, ch.rb, compression.rb, and other function files to identify common animation patterns (clearing screen, printing steps, delays, formatting output)
• [ ] Create lib/animation_helper.rb with reusable methods like display_step(), animate_transition(), format_binary()
• [ ] Refactor each function file to use the new module instead of inline animation code
• [ ] Update sha256.rb and other entry points to use the centralized helper
• [ ] Add usage documentation to README under a 'Contributing' section

Add input validation and error handling with user-friendly messages

The repo supports multiple input formats (plain text, 0b binary, 0x hex, file paths) per the README, but there's no visible input validation. Adding proper error handling for invalid hex/binary, missing files, and malformed inputs would improve the user experience and prevent cryptic Ruby errors. This should be centralized in sha256.rb and exposed through helpful CLI messages.

• [ ] Review sha256.rb to identify all input parsing paths (binary, hex, file, plain text)
• [ ] Create lib/input_parser.rb with methods: parse_binary_input(), parse_hex_input(), parse_file_input(), validate_input_format()
• [ ] Add error cases: invalid hex characters, malformed 0b/0x prefix, file not found, file too large (optional size limit)
• [ ] Update sha256.rb to use input_parser.rb and catch errors with user-friendly messages (e.g., 'Error: File "x.txt" not found')
• [ ] Update README to document supported input formats and error scenarios

• Add RSpec test suite for all 40+ operation files (shr.rb, rotr.rb, sigma0.rb, etc.) with NIST test vectors from FIPS 180-4. Currently no automated tests exist; this would verify correctness.: Medium—requires learning RSpec and transcribing NIST test vectors for each primitive.
• Create visual GIFs for the 5 high-level SHA-256 stages (message.rb, padding.rb, blocks.rb, expansion.rb, compression.rb) in images/ and link them in README.md. Currently only primitive operations have GIFs.: Low—use existing shr.gif style as reference; requires terminal recording tool like Asciinema and ffmpeg.
• Add a --verify flag to sha256.rb that compares output against Ruby's Digest::SHA256 library to catch implementation bugs. Currently no self-check exists.: Low—one-liner comparison; useful for catching silent correctness regressions.

This is a SHA-256 animation/educational project with minimal security risks. It contains no dependencies, hardcoded credentials, SQL injection points, or XSS vulnerabilities. The main concerns are: (1) potential file path validation issues when reading files, (2) lack of input validation on cryptographic inputs, and (3) reliance on a custom SHA-256 implementation rather than a battle-tested library. For an educational tool, the security posture is good. However, this implementation should never be used for actual cryptographic purposes in production systems.

• Low · Potential Command Injection via File Input — sha256.rb. The sha256.rb script accepts file paths as command-line arguments without explicit validation. If user input is passed to file operations without proper sanitization, this could lead to command injection or arbitrary file access. Fix: Validate and sanitize file path inputs. Use Ruby's File class safely with explicit path validation. Consider restricting file access to a specific directory.
• Low · No Input Validation on Binary/Hex Input — sha256.rb. The script accepts binary (0b) and hex (0x) prefixes directly from command-line arguments. While Ruby's parser handles this, there's no explicit validation to ensure inputs are well-formed before processing. Fix: Add explicit input validation for binary and hexadecimal strings before processing them in cryptographic operations.
• Low · Use of Non-Standard Cryptography Implementation — hash256.rb, sha256lib.rb, and related function files. This is a SHA-256 animation/implementation created from scratch rather than using a well-tested, audited cryptographic library. Educational implementations may contain subtle bugs or performance issues that could lead to incorrect hash outputs. Fix: For production use, rely on Ruby's built-in OpenSSL bindings (Digest::SHA256) instead of custom implementations. This is acceptable only for educational/demonstration purposes.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.