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/build-trust/ockam 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 4mo ago
• 8 active contributors
• Distributed ownership (top contributor 27% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 4mo ago

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

What it runs against: a local clone of build-trust/ockam — 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 build-trust/ockam | 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 develop exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 153 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "build-trust/ockam(\\.git)?\\b" \\
  && ok "origin remote is build-trust/ockam" \\
  || miss "origin remote is not build-trust/ockam (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 develop >/dev/null 2>&1 \\
  && ok "default branch develop exists" \\
  || miss "default branch develop no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "implementations/rust/ockam" \\
  && ok "implementations/rust/ockam" \\
  || miss "missing critical file: implementations/rust/ockam"
test -f ".github/workflows/rust.yml" \\
  && ok ".github/workflows/rust.yml" \\
  || miss "missing critical file: .github/workflows/rust.yml"
test -f "implementations/elixir/ockam/ockam/lib/ockam.ex" \\
  && ok "implementations/elixir/ockam/ockam/lib/ockam.ex" \\
  || miss "missing critical file: implementations/elixir/ockam/ockam/lib/ockam.ex"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"

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

Ockam is a distributed systems framework that orchestrates end-to-end encryption, cryptographic identities, mutual authentication, and authorization policies across distributed applications at scale. It provides a command-line tool and Rust/Elixir libraries to establish secure, mutually-authenticated connections between services without requiring a centralized certificate authority, solving the hard problem of identity and authorization in decentralized networks. Monorepo with three main branches: implementations/rust/ockam/* (20+ Rust crates containing core protocol engines), implementations/rust/examples/* (runnable demos like rendezvous, file_transfer, tcp_inlet_and_outlet), tools/* (CLI, docs, stress-test utilities). Workspace resolver v2 coordinates builds across members. CI matrix in .github/workflows/ runs separate rust.yml, elixir.yml, shell.yml, and distroless.yml pipelines. Dev environment uses Nix caching (.github/actions/cache_nix/) and devcontainer support.

Platform engineers and DevOps teams building zero-trust architectures in distributed systems; cryptography-aware developers implementing secure inter-service communication; infrastructure teams managing IoT, edge computing, or multi-cloud deployments where centralized PKI is infeasible.

Production-ready and actively developed. The codebase shows mature practices: extensive multi-language implementation (5.5M lines Rust, 1M Elixir), comprehensive CI/CD via GitHub Actions (.github/workflows/), dev container support (.devcontainer/), dependency management via Cargo.lock, and modular workspace structure (20+ crates under implementations/rust/ockam/). Regular releases visible in release workflows (release-publish-crates.yml, release-ockam-package.yml).

Moderate risk from complexity: the codebase is large (6.8M lines across Rust/Elixir/Shell) requiring expertise in cryptography, distributed systems, and multiple languages. The Rust build system uses workspace resolution v2 with optimizations for specific dependencies (syntect, adler2 in profile.dev.package), which can hide build surprises. No visible security audit trail in the file list; cryptographic code requires peer review. Risk of vendor lock-in to the Ockam tool ecosystem if relying heavily on their abstraction layer.

Active development across multiple dimensions: release automation (release-ockam-package.yml, release-publish-crates.yml suggest frequent shipping), security scanning (osv-scanner.yml, scorecards.yml), artifact building for multiple targets (ockam-artifact.yml), and health monitoring (ockam-healthcheck.yml). The existence of elixir.yml alongside rust.yml suggests ongoing polyglot development. Dependabot is configured, indicating active dependency management.

git clone https://github.com/build-trust/ockam.git
cd ockam
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. $HOME/.cargo/env
cargo build --workspace
cargo test --workspace
# Or install the CLI directly:
curl -sSfL install.command.ockam.io | bash && source "$HOME/.ockam/env"

Daily commands: For Rust development: cargo build --workspace builds all members; cargo test --workspace runs test suite; cargo run --example file_transfer runs specific example. For CLI: ./implementations/rust/ockam/ockam_command/ likely contains the binary target. Makefile present but not detailed in file list—check make help. Dev container available: open in VS Code with Remote Containers extension and .devcontainer/devcontainer.json will handle environment.

• Cargo.toml — Workspace root configuration defining all Rust crates, profiles (coverage, profiling), and resolver strategy—essential for understanding the mono-repo structure.
• implementations/rust/ockam — Core Rust implementation directory housing the primary cryptographic, transport, and worker abstractions that form Ockam's foundation.
• .github/workflows/rust.yml — Rust CI/CD pipeline defining test, lint, and build steps—critical for understanding code quality gates and deployment process.
• implementations/elixir/ockam/ockam/lib/ockam.ex — Elixir implementation entry point exposing the high-level Ockam API for worker orchestration and routing.
• README.md — Project overview documenting Ockam's mission (end-to-end encryption, identities, mutual auth) and installation—required context for all contributors.
• .github/CODEOWNERS — Ownership matrix defining code review responsibilities across Rust, Elixir, and tool components.
• Cross.toml — Cross-compilation configuration for building Rust binaries across multiple platforms and architectures.

Add a New Secure Channel Feature

1. Define the new secure channel abstraction in Rust core (e.g., encryption policy, routing rule). (implementations/rust/ockam/ockam_core/src/lib.rs)
2. Implement the feature in the Elixir binding, wrapping the Rust API. (implementations/elixir/ockam/ockam/lib/ockam.ex)
3. Create a new example demonstrating the feature, placed in the get_started or tcp_inlet_and_outlet directories. (implementations/elixir/examples/get_started/07-new-feature.exs)
4. Add integration tests to the Elixir test suite to verify the feature works end-to-end. (implementations/elixir/ockam/ockam/test)

Add a New Transport (e.g., QUIC)

1. Create a new Rust crate under implementations/rust/ockam/ for the transport implementation. (implementations/rust/ockam/ockam_transport_quic/src/lib.rs)
2. Register the transport in the Cargo.toml workspace members. (Cargo.toml)
3. Implement the transport's Elixir FFI bindings in the high-level runtime. (implementations/elixir/ockam/ockam/lib/ockam/api/client.ex)
4. Add an example demonstrating the new transport (e.g., 07-routing-over-quic-initiator.exs). (implementations/elixir/examples/get_started/07-routing-over-quic-initiator.exs)

Add a New Elixir Example

1. Create a new .exs file in examples/get_started or examples/tcp_inlet_and_outlet with a descriptive name. (implementations/elixir/examples/get_started/08-my-new-feature.exs)
2. Use the Ockam.* API from lib/ockam.ex to set up workers, routes, or secure channels. (implementations/elixir/ockam/ockam/lib/ockam.ex)
3. Reference setup.exs if the example requires initialization or cleanup. (implementations/elixir/examples/get_started/setup.exs)
4. Document the example's purpose in a comment block and run it locally with elixir to verify. (implementations/elixir/examples/get_started/08-my-new-feature.exs)

Add a New Cryptographic Vault Capability

1. Define the new vault operation in the Rust core abstraction (e.g., new signing algorithm). (implementations/rust/ockam/ockam_core/src/vault.rs)
2. Implement the operation in a specific vault backend crate (e.g., ockam_vault_core or ockam_vault_software). (implementations/rust/ockam/ockam_vault_core/src/lib.rs)
3. Add unit tests and integration tests for the new operation. (implementations/rust/ockam/ockam_vault_core/tests)
4. Expose the operation through the Elixir API if needed for higher-level use. (implementations/elixir/ockam/ockam/lib/ockam.ex)

• Rust — Provides memory safety, zero-cost abstractions, and fine-grained control for cryptographic primitives and low-level transport handling.
• Elixir/Erlang OTP — Enables lightweight distributed actor-based concurrency, hot-code reloading, and fault tolerance via supervisor trees for managing workers and connections.
• Cargo Workspace — Allows modular crate organization (transport, vault, core, identity) with shared dependencies and unified versioning.
• GitHub Actions — Provides CI/CD automation for cross-platform testing (via Cross), multi-language builds (Rust + Elixir), and artifact publishing.
• Nix — Enables reproducible builds and development environments across platforms, reducing 'works on my machine' issues.

• Dual Rust + Elixir implementation

  • Why: Rust provides performance and cryptographic safety; Elixir provides distribution and fault tolerance.
  • Consequence: Increased codebase complexity and FFI maintenance burden, but maximizes safety and scalability across different deployment scenarios.

• Async/non-blocking workers via GenServer

  • Why: Enables handling thousands of concurrent connections without OS-level thread overhead.
  • Consequence: Requires disciplined non-blocking I/O patterns; blocking operations can starve other workers.

• Identity-based routing instead of IP/port-based

  • Why: Decouples trust from network topology; enables zero-trust architectures.
  • Consequence: Adds overhead of identity lookup and validation per message; requires external identity registry for distributed deployments.

• Multiple transport backends (TCP, QUIC, etc.)

  • Why: Allows pluggable transports and adapts to different network conditions.
  • Consequence: Each transport requires separate implementation, testing, and maintenance; potential inconsistencies across transports.

• Provide a complete message queue or pub/sub broker (only point-to-point and routed messaging)
• Handle application-level data persistence or state management (Ockam manages transport/crypto state only)
• Offer high-level DSLs for policy definition (low-level

1. Workspace resolver v2: Cargo uses custom resolver that may behave unexpectedly with path dependencies; check .cargo/config.toml if you see linking or re-export issues. 2. Profile.dev optimizations: syntect and adler2 use opt-level > 0 in dev builds to avoid 5x slowdown on CLI bootstrap—disabling this breaks UX; don't simplify the profile config. 3. Polyglot testing: CI runs separate pipelines for Rust (rust.yml), Elixir (elixir.yml), and Shell (shell.yml)—a change in one language won't trigger tests in another unless explicitly gated in the workflow. 4. Cryptographic code: No explicit security audit date visible; assume sensitive code in ockam_core/ and transport layers requires peer review before shipping. 5. Dev container Dockerfile: Check .devcontainer/Dockerfile for required system dependencies (Rust, Elixir, Nix) before running locally; Nix caching assumes nix-installer is available.

• Secure Enclaves / Portals — Ockam's core abstraction for encrypting inter-process communication; understanding enclaves vs. secure channels is essential to using the library correctly.
• Decentralized Identity (DID) and Verifiable Credentials — Ockam avoids centralized PKI by using cryptographic identities; knowing how identities are created, verified, and revoked is prerequisite for authorization rules.
• Zero-Trust Architecture — The explicit design philosophy of Ockam; every connection requires mutual authentication and policy evaluation, no implicit trust.
• End-to-End Encryption (E2EE) with Perfect Forward Secrecy — Ockam encrypts every hop; understanding PFS (ephemeral key agreement) and per-message encryption is critical for threat model analysis.
• Message-Oriented Routing — Ockam routes encrypted messages between nodes using cryptographic identities, not IP addresses; this decoupling enables the distributed auth model.
• Elliptic Curve Diffie-Hellman (ECDH) Key Exchange — Likely the primary key agreement protocol in Ockam (efficient, forward-secret); needed to understand secure channel establishment.
• Attribute-Based Access Control (ABAC) — Ockam's policy engine likely uses ABAC (policies evaluate cryptographic proofs + attributes) rather than simple ACLs; understanding this unlocks authorization customization.

• tokio-rs/tokio — Rust async runtime likely used throughout Ockam's networking layer; understanding Tokio is prerequisite for modifying transport code.
• ockam-network/ockam-hub — Sister repo (if it exists) implementing cloud-hosted Ockam relay and orchestration; shows how Ockam libraries are deployed at scale.
• rustls/rustls — Pure-Rust TLS library; architectural parallel to Ockam's approach (eliminate OpenSSL dependency, control the crypto stack).
• cloudflare/tlsn — TLS notarization framework; shares zero-trust authentication goals with Ockam, offers different approach to proving identity/authorization.
• temporal-sdk-go/temporal — Distributed workflow orchestration; potential integration point for Ockam (securing workflows) and similar coordination patterns.

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 Elixir examples in CI/CD pipeline

The repo has Elixir examples in implementations/elixir/examples/get_started/ (01-05 routing examples) but there's no dedicated CI workflow to validate them. Currently, .github/workflows/elixir-ignored.yml suggests Elixir tests are skipped. Adding executable integration tests would catch regressions in the Elixir implementation and ensure examples stay current as the codebase evolves.

• [ ] Create a new .github/workflows/elixir-integration-tests.yml workflow
• [ ] Add test targets in implementations/elixir/Makefile to run examples sequentially
• [ ] Implement validation logic (e.g., check expected output or process exit codes) for each example file (01-worker.exs through 05-routing-over-transport-two-hops-initiator.exs)
• [ ] Reference the existing cache_elixir custom action in .github/actions/cache_elixir/action.yml for dependency caching
• [ ] Update .github/CODEOWNERS to assign Elixir example changes to maintainers

Add cross-compilation CI validation for TCP inlet/outlet example on ARM64

The repo uses Cross.toml for cross-compilation and has a tcp_inlet_and_outlet example in implementations/rust/examples/, but there's no CI workflow specifically validating ARM64/other architecture builds for examples. This would catch architecture-specific bugs early and validate that the cross-compilation setup actually works for distributed deployment scenarios.

• [ ] Create .github/workflows/cross-compile-examples.yml using the existing Cross.toml configuration
• [ ] Add build targets for aarch64-unknown-linux-gnu and x86_64-pc-windows-gnu for at least implementations/rust/examples/tcp_inlet_and_outlet
• [ ] Leverage the existing cache_rust action in .github/actions/cache_rust/action.yml
• [ ] Add a step to verify binary output with file command to confirm correct architecture
• [ ] Document expected architecture targets in implementations/rust/examples/tcp_inlet_and_outlet/README.md if missing

Add security audit workflow for Python dependencies (if Python code exists upstream)

The repo has .github/workflows/python-ignored.yml which suggests Python code exists but tests are skipped, and there's already .github/workflows/osv-scanner.yml for supply chain security. However, there's no dedicated Python security audit step. Adding a workflow to scan Python dependencies would fill a gap in the security posture, especially if Python is used in examples/tools not yet visible in the file listing.

• [ ] Create .github/workflows/python-security-audit.yml that runs pip audit or bandit on Python projects
• [ ] Identify all Python source locations (likely under tools/ or implementations/python/ if it exists)
• [ ] Configure the workflow to fail on high-severity vulnerabilities and warn on medium
• [ ] Integrate with existing osv-scanner workflow to avoid duplication
• [ ] Document findings in SECURITY.md or update DEVELOP.md with remediation steps for Python dependencies

• Add integration test for end-to-end file transfer with policy enforcement: currently examples/file_transfer/ exists but no automated test verifying authorization policies block unauthorized transfers. Create implementations/rust/ockam/ockam_core/tests/policy_enforcement_e2e.rs that chains rendezvous + file_transfer + policy evaluation.
• Document cryptographic algorithm choices: the ockam_core crate likely uses specific curves (X25519, etc.) and hash functions, but no design doc in tools/docs/ explains why. Add tools/docs/cryptography_design.md linking to code and citing NIST/IETF standards.
• Extend the mitm_node example to demonstrate policy denial: currently implementations/rust/examples/mitm_node/ likely shows a working MITM. Add a companion example or test showing how Ockam's mutual auth prevents the attack when policies are enforced.

The Ockam repository demonstrates a strong foundation with cryptographic and security-focused design, but has several moderate security concerns. The primary risk is the insecure installation script distribution pattern using curl|bash, which is vulnerable to supply chain attacks. Additional concerns include loose workspace member resolution, debug symbols in profiling builds, and missing security policy documentation. The codebase shows good practices with explicit build profile configurations and multi-language support, but needs hardening in deployment and distribution mechanisms. Dependencies appear well-managed through lock files and CI/CD workflows, but cache integrity could be strengthened.

• Medium · Insecure Installation Script Distribution — README.md - Install Ockam Command section. The README recommends installing Ockam via a curl piped to bash script from 'install.command.ockam.io'. This is a high-risk installation pattern vulnerable to MITM attacks, DNS hijacking, or compromised infrastructure. Users blindly execute remote scripts without verification. Fix: Provide checksum verification, GPG signature verification, or use package managers (apt, brew, cargo). If using script installation, require users to inspect the script first and provide SHA256 checksums for verification.
• Medium · Loose Workspace Member Resolution — Cargo.toml - workspace members configuration. The Cargo.toml uses wildcard patterns like 'implementations/rust/ockam/*' to include workspace members. This could inadvertently include unvetted or vulnerable crates if new directories are added without proper review. Fix: Explicitly list all workspace members instead of using wildcards. This ensures each added crate is intentionally reviewed and included.
• Medium · Debug Information in Production Profile — Cargo.toml - [profile.profiling] section. The 'profiling' profile inherits from 'release' but sets 'strip = "none"', which preserves debug symbols in release binaries. This could leak sensitive information like function names, variable names, and source code structure to attackers analyzing the binary. Fix: Ensure 'strip = "symbols"' is used in release builds to remove debug symbols. Keep 'strip = "none"' only for internal profiling builds that are never distributed.
• Low · Coverage Profile Disabled Security Features — Cargo.toml - [profile.coverage] section. The 'coverage' profile explicitly disables 'overflow-checks' and 'panic = "abort"' to minimize noise during coverage measurement. While acceptable for testing, this could mask integer overflows and other overflow-related security issues during coverage runs. Fix: Document that the coverage profile is for testing only and should not be used in production. Consider keeping overflow-checks enabled even for coverage builds, or at minimum document the security implications.
• Low · Missing Security Policy Documentation — Repository root. No visible SECURITY.md or security policy file in the repository structure provided. This makes it unclear how security vulnerabilities should be reported or handled. Fix: Create a SECURITY.md file documenting responsible disclosure procedures, security contact information, and vulnerability reporting guidelines per GitHub security best practices.
• Low · Dependency Caching Without Verification — .github/actions/cache_rust, cache_elixir, cache_nix. GitHub Actions for caching dependencies (.github/actions/cache_*) don't show explicit integrity verification mechanisms. Cached artifacts could be tampered with if cache is compromised. Fix: Implement cache integrity verification using checksums or signatures. Consider using GitHub's official cache actions with built-in security features.

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.