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/str4d/rage 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.

GO — Healthy across all four use cases

• Last commit 2w ago
• 5 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 96% of recent commits

_{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 str4d/rage repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/str4d/rage.

What it runs against: a local clone of str4d/rage — 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 str4d/rage | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 46 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of str4d/rage. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/str4d/rage.git
#   cd rage
#
# 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 str4d/rage and re-run."
  exit 2
fi

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

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

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

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 46 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~16d)"
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/str4d/rage"
  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).

rage is a Rust implementation of the age file encryption format (filippo.io/age), providing a CLI tool and library for encrypting/decrypting files with small explicit keys, no configuration options, and UNIX pipe composability. It implements the formal age specification (age-encryption.org/v1) using modern cryptography primitives: X25519 for key exchange, ChaCha20-Poly1305 for authenticated encryption, and optional hardware PIV token support via plugins. Monorepo with 4 packages: age/ (CLI binary + i18n), age-core/ (cryptographic primitives and format parsing), age-plugin/ (plugin protocol), rage/ (aggregator binary crate). The core logic lives in age-core/src/ (format.rs, io.rs, primitives.rs); CLI logic in age/src/ with localization under age/i18n/ using Fluent (.ftl files). Plugin identity/recipient stubs in age-plugin/src/.

Systems administrators, DevOps engineers, and developers who need secure file encryption without complex configuration—users comfortable with CLI tools who value simplicity (like GPG users but with modern defaults), and maintainers of downstream tools/integrations that need an embedded encryption library.

Production-ready and actively maintained. The codebase implements a formally specified, interoperable standard with a reference Go implementation, comprehensive CI/CD (audit.yml, ci.yml, interop.yml, mutants.yml, criterion.yml), and structured testing. Rust MSRV is pinned to 1.74. Recent activity visible through GitHub workflows for continuous security auditing and benchmark comparisons.

Low risk for core encryption logic—relies on audited cryptographic crates (chacha20poly1305, x25519-dalek, hpke, ml-kem from FIPS/RFC specs). Single maintainer (@str4d) creates succession risk for the Rust reference implementation, though the format itself is multi-implementation stable. Dependencies on i18n-embed and pinentry add optional surface area; dependency count is moderate and well-curated (see workspace.dependencies in Cargo.toml).

Active maintenance with recent GitHub Actions workflows for mutation testing (mutants.yml), interoperability testing (interop.yml), and security auditing (audit.yml, audits.yml). The repo tracks against the formal age v1 spec; recent work likely involves ML-KEM integration (visible in workspace.dependencies with ml-kem = 0.2) and P-256 support (p256 crate pinned). Dependabot configured for automated dependency updates.

git clone https://github.com/str4d/rage.git
cd rage
cargo build --release
./target/release/rage --help

Or install via Cargo: cargo install rage (Rust 1.74+ required). For development: cargo build (debug), cargo test (run test suite).

Daily commands: Development: cargo build (outputs debug binary). Run tests: cargo test (workspace-wide). Run benchmarks: cargo bench (uses criterion, see benches/). CLI usage: ./target/debug/rage -e -r RECIPIENT_KEY [INPUT] or ./target/debug/rage -d -i IDENTITY_KEY [INPUT]. See age/README.md and rage --help for full CLI reference.

• age-core/src/format.rs: Implements the age file format specification (encryption/decryption stanza parsing, header layout)—core serialization logic for understanding how encrypted files are structured
• age-core/src/primitives.rs: Wraps cryptographic primitives (X25519, ChaCha20-Poly1305, HPKE, ML-KEM) with the age-specific key derivation and encryption logic
• age-core/src/lib.rs: Exports the public API (Encryptor, Decryptor, identity/recipient trait interfaces) that downstream crates and plugins depend on
• age/src/main.rs: CLI entry point; orchestrates argument parsing (via clap), input/output handling, and calls into age-core library functions
• age-plugin/src/lib.rs: Plugin protocol implementation—defines the interface for hardware tokens (YubiKey via age-plugin-yubikey) and custom recipients/identities
• age/i18n.toml: i18n configuration; controls which locales are embedded (en-US, es-AR, fr) and how Fluent bundles are built at compile-time
• Cargo.toml: Workspace root; pins MSRV (1.74), dependency versions (chacha20poly1305, x25519-dalek, hpke, ml-kem), and member crates

Adding encryption features: modify age-core/src/primitives.rs (crypto stubs) and age-core/src/format.rs (serialization). CLI changes: edit age/src/ (main binary crate). Plugin support: update age-plugin/src/identity.rs or recipient.rs. Localization: add strings to age/i18n/en-US/age.ftl and translate to other Fluent files in age/i18n/*/. Testing: add cases to **/tests/ or integrate with criterion benchmarks in age/benches/.

No environment variables required for basic use, but PINENTRY_USER_DATA may be set for pinentry integration (interactive passphrase prompts). MSRV strictly enforced: Rust 1.74+ required (check rust-version in Cargo.toml); newer features like #![expect(...)] unavailable. Binary names matter: package name is rage but conflicts in some distros use fallback rage-encryption—do not rename. Passphrase decryption has a --max-work-factor limit (KDF work factor negotiation) to prevent DoS; see age/src/ CLI parsing. Fluent i18n files (.ftl) are compile-time embedded; changes require rebuild.

• HPKE (Hybrid Public Key Encryption) — rage uses RFC 9180 HPKE (via the hpke crate) for key encapsulation in the age format; understanding how it combines DH key exchange with symmetric encryption is essential for modifying the cryptographic layer
• X25519 (Elliptic Curve Diffie-Hellman) — The primary key exchange mechanism in age; rage implements it via x25519-dalek with static_secrets feature for explicit key management
• ChaCha20-Poly1305 (AEAD cipher) — The symmetric encryption cipher used to encrypt file payloads after key exchange; understanding AEAD properties (authentication + confidentiality) is critical for security decisions
• ML-KEM (FIPS 203 Post-Quantum KEM) — rage v0.11+ includes ML-KEM for future post-quantum resistance; contributors should understand how hybrid KEM (classical + PQC) integration works in the format.rs layer
• scrypt key derivation function — Used for passphrase-based encryption (age --passphrase); scrypt's configurable work factor (tunable CPU/memory cost) is why rage has --max-work-factor flag for decryption safety
• Fluent localization format — All user-facing messages in rage are stored as .ftl files (age/i18n/*.ftl) and compiled at build-time via i18n-embed; essential for understanding how to add or modify CLI output strings
• Binary format parsing with nom — rage-core uses nom parser combinators in format.rs to deserialize age stanzas and encrypted payloads from bytes; critical for understanding how file format compliance is enforced

• filippo.io/age — The reference Go implementation of the age format specification; cross-compatibility is tested via the interop.yml workflow in this repo
• str4d/age-plugin-yubikey — Official hardware token plugin for rage; demonstrates how to extend age with PIV support and serves as the canonical plugin example
• FiloSottile/awesome-age — Community curated list of age tools, implementations, and integrations; points to ecosystem of tools built on or compatible with rage
• dani-garcia/vaultwarden — Potential downstream consumer; self-hosted vault platforms may use age/rage for encrypted secret storage backups
• mozilla/sops — Related tool for encrypted secrets management in CI/CD; competes in the same problem space (encrypted file handling) but with different design philosophy

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 integration tests for CLI file I/O edge cases in age/src/cli_common/file_io.rs

The file_io.rs module handles critical file operations (reading/writing encrypted files, permission handling, symlink safety). There are no dedicated integration tests visible in the repo structure for edge cases like concurrent file access, permission errors, disk full scenarios, or symlink attacks. This is a high-security area that deserves comprehensive test coverage beyond unit tests.

• [ ] Create age/tests/cli_file_io_integration.rs with tests for: reading from stdin/files, writing to stdout/files, permission preservation
• [ ] Add tests for edge cases: non-existent input files, unwritable output directories, symlink handling, TOCTOU race conditions
• [ ] Test interaction with identities.rs loader for encrypted identity files and error handling
• [ ] Verify cross-platform behavior (Windows/Unix permission differences)

Implement plugin protocol documentation and example in age-plugin/README.tpl with concrete workflow

The age-plugin crate exists with examples (age-plugin-unencrypted.rs) and a template README, but the plugin protocol workflow appears under-documented based on the file structure. Contributors building plugins (like age-plugin-yubikey mentioned in main README) need clearer step-by-step documentation on the handshake protocol, message formats, and error handling.

• [ ] Expand age-plugin/README.tpl with a 'Plugin Development Guide' section explaining the identity/recipient protocol flow
• [ ] Document the serialization format for plugin identity and recipient stanzas using examples from age-core/src/plugin.rs
• [ ] Add a complete walkthrough in age-plugin/examples/ showing a minimal working plugin with all required trait implementations (identity.rs, recipient.rs patterns)
• [ ] Include error handling best practices and versioning strategy for plugin compatibility

Add hermetic interoperability tests against hardcoded age v1 test vectors in age/tests/

The repo runs interop.yml GitHub workflow but there are no visible test fixtures/vectors in the file structure. For a cryptographic format standard (age-encryption.org/v1), having immutable golden test vectors ensures long-term compatibility across Rust versions and dependency updates without relying on external Go binary execution.

• [ ] Create age/tests/age_v1_vectors.rs with encrypted test files (or fetch from https://github.com/C2SP/age-vectors if public) covering: X25519 recipients, scrypt-encrypted identities, multiple stanzas
• [ ] Add test that decrypts known ciphertexts and verifies plaintext matches expected output
• [ ] Test both success cases and invalid format rejection (wrong MAC, truncated files, malformed stanzas)
• [ ] Document vector source/maintenance process in age/tests/README.md for future contributions

• Add missing CLI integration tests for piped stdin/stdout scenarios (e.g., echo 'data' | rage -e -r KEY | rage -d -i IDENTITY) in age/tests/ to match the UNIX composability promise.
• Expand age-core/src/io.rs documentation and add examples for the Read/Write trait implementations—currently sparse on explaining streaming encryption boundaries and buffering behavior for callers.
• Create a companion example in age-plugin/examples/ demonstrating a custom identity provider (like age-plugin-unencrypted.rs but for a real use case) with detailed comments for plugin authors.

The rage codebase demonstrates strong security practices. It uses well-maintained, standard cryptographic libraries (ChaCha20-Poly1305, HPKE, HKDF, SHA3, ML-KEM, X25519) that align with the age specification. No hardcoded secrets, credentials, or dangerous patterns (SQL injection, XSS) were identified in the visible file structure. The project includes automated security workflows (audit.yml, dependabot.yml, mutants.yml) indicating active security maintenance. The Rust language itself provides memory safety guarantees that mitigate many common vulnerabilities. Dependencies are minimal and well-chosen for cryptographic operations. The main recommendations are routine: maintain consistent security audits, ensure constant-time comparisons in sensitive operations, and keep the dependency audit workflow active. Overall security posture is excellent for a cryptographic tool.

• Low · Dependency Version Pinning Could Be More Restrictive — Cargo.toml (workspace.dependencies). Several dependencies use caret (^) version specifications which allow minor and patch version updates. While this is generally acceptable for security updates, it could theoretically allow unexpected behavior changes. Examples: base64 = "0.22", sha3 = "0.10", rand = "0.8". Fix: Consider using more restrictive version constraints (=) for security-critical dependencies, or ensure regular dependency audits are performed through the existing audit.yml workflow.
• Low · Console Dependency with Reduced Features — Cargo.toml (workspace.dependencies) - console dependency. The 'console' crate is included with default-features = false, which is good for minimizing attack surface. However, verify that this configuration doesn't disable important security features needed for terminal input/output handling. Fix: Explicitly document which console features are intentionally disabled and verify they don't relate to input sanitization or security features.
• Low · Potential Timing Attack Vector in Subtle Usage — age/src and age-core/src (implementation files not fully visible). While the codebase includes 'subtle = "2.6"' for constant-time comparisons, the actual usage patterns in cryptographic operations should be reviewed to ensure all sensitive comparisons use constant-time implementations. Fix: Audit all cryptographic key and authentication tag comparisons to ensure they use constant-time comparison functions from the 'subtle' crate throughout the codebase.

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.