RepoMesh

See CHANGELOG.md for the full list.

What is this?

RepoMesh turns a collection of repos into a cooperative network. Each repo is a node with:

• A manifest (node.json) declaring what it provides and consumes
• Signed events broadcast to an append-only ledger
• A registry indexing all nodes and capabilities
• A profile defining what "done" means for trust

Today one GitHub organization, mcp-tool-shop-org, operates the log, the attestors, the policy check, and the XRPL anchor. Seven registered nodes do not make seven operators. An independent witness would be a party this organization does not operate.

The network enforces three invariants:

1. Deterministic outputs — same inputs, same artifacts
2. Verifiable provenance — every release is signed and attested
3. Composable contracts — interfaces are versioned and machine-readable

Quick Start (1 command + 2 secrets)

npx @mcptoolshop/repomesh init --repo your-org/your-repo --profile open-source
# JSON output for CI piping:
npx @mcptoolshop/repomesh init --repo your-org/your-repo --profile open-source --json

This generates everything you need:

• node.json — your node manifest
• repomesh.profile.json — your chosen profile
• .github/workflows/repomesh-broadcast.yml — release broadcast workflow
• Ed25519 signing keypair (private key stays local)

Then add two secrets to your repo:

1. REPOMESH_SIGNING_KEY — your private key PEM (printed by init)
2. REPOMESH_LEDGER_TOKEN — GitHub PAT with contents:write + pull-requests:write on this repo

Cut a release. Trust converges automatically.

CLI Flags

All commands accept: --quiet, --verbose, --debug, --no-color. The init command also supports --json for machine-readable output.

Shell completions are available:

repomesh completion bash >> ~/.bashrc
repomesh completion zsh >> ~/.zshrc

Environment Overrides

Profiles

Check Trust

node registry/scripts/verify-trust.mjs --repo your-org/your-repo

Shows integrity score, assurance score, profile-aware recommendations.

Overrides

Per-repo customization without forking verifiers:

// repomesh.overrides.json
{
  "license": { "allowlistAdd": ["WTFPL"] },
  "security": { "ignoreVulns": [{ "id": "GHSA-xxx", "justification": "Not reachable" }] }
}

Repo Structure

repomesh/
  profiles/                   # Trust profiles (baseline, open-source, regulated)
  schemas/                    # Source of truth for all schemas
  ledger/                     # Append-only signed event log
    events/events.jsonl       # The ledger itself
    nodes/                    # Registered node manifests + profiles
    scripts/                  # Validation + verification tooling
  attestor/                   # Universal attestor (sbom, provenance, sig chain)
  verifiers/                  # Independent verifier nodes, operated by the same organization today
    license/                  # License compliance scanner
    security/                 # Vulnerability scanner (OSV.dev)
  anchor/xrpl/               # XRPL anchoring (Merkle roots + testnet posting)
    manifests/                # Committed partition manifests (append-only)
    scripts/                  # compute-root, post-anchor, verify-anchor
  policy/                     # Network policy checks (semver, hash uniqueness)
  registry/                   # Network index (auto-generated from ledger)
    nodes.json                # All registered nodes
    trust.json                # Trust scores per release (integrity + assurance)
    anchors.json              # Anchor index (partitions + release anchoring)
    badges/                   # SVG trust badges per repo
    snippets/                 # Markdown verification snippets per repo
  pages/                      # Static site generator (GitHub Pages)
  docs/                       # Public verification docs
  tools/                      # Developer UX tools
    repomesh.mjs              # CLI entrypoint
  templates/                  # Workflow templates for joining

Manual Join (5 minutes)

1. Create your node manifest

Add node.json to your repo root:

{
  "id": "your-org/your-repo",
  "kind": "compute",
  "description": "What your repo does",
  "provides": ["your.capability.v1"],
  "consumes": [],
  "interfaces": [
    { "name": "your-interface", "version": "v1", "schemaPath": "./schemas/your.v1.json" }
  ],
  "invariants": {
    "deterministicBuild": true,
    "signedReleases": true,
    "semver": true,
    "changelog": true
  },
  "maintainers": [
    { "name": "your-name", "contact": "https://github.com/your-org", "keyId": "ci-yourrepo-2026", "publicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----" }
  ]
}

2. Generate a signing keypair

# Mint an ed25519 key and a paste-ready node.json maintainer block:
npx @mcptoolshop/repomesh keygen --repo <your-org>/<your-repo> --out repomesh-private.pem

keygen prints the public key + a keyId ready to drop into your node.json maintainers entry, and writes the private key (mode 0600) only where you point --out — never to a tracked path. Store it as a GitHub repo secret (REPOMESH_SIGNING_KEY). (Equivalent by hand: openssl genpkey -algorithm ED25519 ....)

Register ≥2 keys for a trust-critical node (TUF §6.1): a single key cannot sign its own revocation if compromised. repomesh init --second-key registers a distinct second maintainer so one key can revoke the other — init warns when a node has only one active key.

3. Register with the network

Open a PR to this repo adding your node manifest:

ledger/nodes/<your-org>/<your-repo>/node.json
ledger/nodes/<your-org>/<your-repo>/repomesh.profile.json

4. Add the broadcast workflow

Copy templates/repomesh-broadcast.yml to your repo's .github/workflows/. Set the REPOMESH_LEDGER_TOKEN secret (a fine-grained PAT with contents:write + pull-requests:write on this repo).

Every release will now automatically broadcast a signed ReleasePublished event to the ledger.

Ledger Rules

• Append-only — existing lines are immutable
• Schema-valid — every event validates against schemas/event.schema.json
• Signature-valid — every event is signed by a registered node maintainer
• Unique — no duplicate (repo, version, type) entries
• Timestamp-sane — not more than 1 hour in the future or 1 year in the past

Event Types

The ledger currently emits the live event types below. The rest are reserved / planned — the schema accepts them, but no node emits them yet. We list them so the roadmap is visible without implying coverage that does not exist (front-door honesty for a trust product).

Live (emitted today):

AttestationPublished also carries Cognate's run attestations (run.preregistered, run.outcome, cognate.root.anchored, since 2.4.0), signed only by its governance node.

Reserved / planned (not yet emitted):

Key Rotation & Revocation

Maintainer keys have a lifecycle. A key can be rotated to a successor or revoked, and verification is time-aware: a signature is trusted only if the key was valid at the signature's trusted time — the XRPL anchor close-time, the same trusted clock the ledger already uses.

# Rotate to a successor key (the retired key's past signatures stay valid)
npx @mcptoolshop/repomesh key rotate --repo your-org/your-repo \
  --retiring mike-2026-01 --new-key mike-2026-06 --public-key new.pem

# Revoke a compromised key (signatures at/after the invalidity date are rejected)
npx @mcptoolshop/repomesh key revoke --repo your-org/your-repo \
  --key mike-2026-01 --reason compromise --invalid-after 2026-06-18T00:00:00Z

• Routine rotation is prospective — the retired key's past signatures remain valid; it simply stops signing new releases.
• Compromise is retroactive (RFC 5280 §5.3.2) — any signature whose provable anchored time is at/after the invalidity date is rejected, and a signature that cannot be proven to predate it is rejected.
• A key with no lifecycle fields is grandfathered (always valid), so existing nodes verify unchanged.
• Revocations are signed KeyRevocation events; a single-key node whose only key is compromised is recovered by a governance (trustedPolicy) node signing the revocation. Trust-critical nodes should register ≥2 keys (TUF §6.1).
• Even against a tampered node.json, a revocation is re-imposed from the signed, XRPL-anchored events — a stripped manifest cannot revive a revoked key. See the threat model for the boundary (verify against the canonical ledger; use --anchored for revocation-sensitive checks).

Node Kinds

Extending the network — the verifier-plugin contract

New check kinds and verifier nodes are added by editing data, not code. The check-kinds registry, scoring weights, and node-kind permissions live in verifier.policy.json (schema-validated, fail-closed). Adding a check (e.g. sast.scan) is a ~6-line policy edit + a node.json, reviewed in a PR — no code change.

The one invariant: registered ≠ trusted. Registration lets a check participate; credit still requires a trusted-set consensus pass. Full guide: docs/verifier-plugin-contract.md.

Public Verification

Anyone can verify a release with one command — no clone required, the CLI fetches the public ledger for you:

npx @mcptoolshop/repomesh verify-release --repo mcp-tool-shop-org/shipcheck --version 1.0.4 --anchored

This checks:

1. The ReleasePublished event exists and is signed (Ed25519) by a key registered to that repo's own node.json — a key registered to a different repo cannot validate it.
2. The repo's trust profile is satisfied: every profile-required attestation (SBOM, provenance, license, security) is present, signed by a trusted attestor, and its latest result by ledger position is pass (per (check, signer), the event at the greater ledger index wins; the signer's timestamp is data only), with at least one independent attestor. A release with only a self-signature and no independent attestations reports UNVERIFIED, never PASS.
3. With --anchored: the partition's Merkle root is recomputed and matched to the manifest, and — when the network is reachable — the on-chain XRPL transaction is fetched and asserted (validated + tesSUCCESS, the signing account is in the trusted-anchor allowlist, and the on-chain memo binds to the local root/manifest-hash/count). Offline, it reports XRPL NOT verified rather than a fake transaction; strict --anchored then fails (use --anchored-or-local to accept a locally-verified manifest without the on-chain proof).

For CI gates, choose an output format with --format <text|json|sarif|markdown> (--json is an alias for --format json):

npx @mcptoolshop/repomesh verify-release --repo mcp-tool-shop-org/shipcheck --version 1.0.4 --anchored --format json

The exit code is derived from the tri-state verdict, so a CI step can gate on it directly:

Container

The same CLI is published as ghcr.io/mcp-tool-shop-org/repomesh, tagged with the npm version and the git sha. The image runs as a non-root user. It does not contain a wallet seed.

docker run --rm ghcr.io/mcp-tool-shop-org/repomesh verify-anchor --tx <TX_HASH>

Posting an anchor is a separate command. XRPL_SEED is passed at runtime:

docker run --rm -e XRPL_SEED --entrypoint node ghcr.io/mcp-tool-shop-org/repomesh \
  anchor/xrpl/scripts/post-anchor.mjs

The daily workflow builds this image from the checkout and posts with it.

XRPL Anchoring (Testnet Guard)

Anchoring in anchor/xrpl/config.json is testnet only ("network": "testnet"). anchor/xrpl/scripts/post-anchor.mjs enforces a fail-closed endpoint guard (assertPostingEndpoint) before validating XRPL_SEED or constructing an xrpl.Client:

• Default testnet check: posting is refused (non-zero exit, no socket opened) unless config.network === "testnet" and the resolved WebSocket URL (process.env.XRPL_WS_URL || config.rippledUrl) is in KNOWN_TESTNET_WS_URLS (wss://s.altnet.rippletest.net:51233, wss://clio.altnet.rippletest.net:51233, wss://testnet.xrpl-labs.com). Setting XRPL_WS_URL to a mainnet or unknown URL is refused immediately with a message naming both the resolved network and the resolved URL.
• Mainnet opt-in (disabled): an environment variable alone can never switch posting to mainnet. Opting into mainnet requires a reviewed commit in anchor/xrpl/config.json setting "network": "mainnet", "allowMainnetPosting": true, and "mainnetAllowedEndpoints": ["wss://..."] containing the target wss:// endpoint, after adding the funded mainnet classic address to the shipped allowlist ceiling (packages/repomesh-cli/src/trusted-anchor-accounts.mjs). That allowlist is a ceiling: a fetched config can drop an account and cannot add one.

--fail-on <fail\|unverified> sets strictness. Default unverified fails on both FAIL and UNVERIFIED; --fail-on=fail lets UNVERIFIED pass (exit 0, with a warning) for warn-mode adoption.

Verify a whole batch in one ledger load with verify-all, and verify offline against a local clone with --local:

# Every release in the trust index, warn-mode
npx @mcptoolshop/repomesh verify-all --from-registry --fail-on fail

# Offline against a local ledger checkout
npx @mcptoolshop/repomesh verify-release --repo org/repo --version 1.0.0 --local ./repomesh

Gate it in CI with the bundled composite action — see Using the GitHub Action:

- uses: mcp-tool-shop-org/repomesh/.github/actions/verify@v1
  with:
    repo: ${{ github.repository }}
    version: ${{ github.event.release.tag_name }}
    anchored: "true"

See docs/verification.md for the full verification guide, threat model, and key concepts.

Use it as a library

The verification engine is exported as a stable programmatic API — embed it in your own tooling instead of shelling out to the CLI:

import { verifyRelease, buildSarif, exitCodeForStatus } from "@mcptoolshop/repomesh";

const result = await verifyRelease({ repo: "org/repo", version: "1.0.0", local: "./repomesh" });
process.exitCode = exitCodeForStatus(result.status);

Network status endpoint

The dashboard publishes a machine-readable status.json for external polling — ledger freshness (with a frozen-ledger signal), trust-verdict counts, anchored vs. pending partitions, and an ok/degraded rollup with reasons.

Trust Badges

Repos can embed trust badges from the registry:

[![Integrity](https://raw.githubusercontent.com/mcp-tool-shop-org/repomesh/main/registry/badges/mcp-tool-shop-org/shipcheck/integrity.svg)](https://mcp-tool-shop-org.github.io/repomesh/repos/mcp-tool-shop-org/shipcheck/)
[![Assurance](https://raw.githubusercontent.com/mcp-tool-shop-org/repomesh/main/registry/badges/mcp-tool-shop-org/shipcheck/assurance.svg)](https://mcp-tool-shop-org.github.io/repomesh/repos/mcp-tool-shop-org/shipcheck/)
[![Anchored](https://raw.githubusercontent.com/mcp-tool-shop-org/repomesh/main/registry/badges/mcp-tool-shop-org/shipcheck/anchored.svg)](https://mcp-tool-shop-org.github.io/repomesh/repos/mcp-tool-shop-org/shipcheck/)

Trust & Verification

Verify a release

npx @mcptoolshop/repomesh verify-release --repo mcp-tool-shop-org/shipcheck --version 1.0.4 --anchored

Attest a release

Attesting and running verifiers are operator tasks that act on a clone of this ledger, so they run from a checkout. Verifying a release does not — use the npx command above.

node attestor/scripts/attest-release.mjs --scan-new  # process all unattested releases
node attestor/scripts/attest-release.mjs --scan-new --dry-run  # preview without writing

Checks: sbom.present, provenance.present, signature.chain

Run verifiers

node verifiers/license/scripts/verify-license.mjs --scan-new
node verifiers/security/scripts/verify-security.mjs --scan-new

Security verifier thresholds (max CVEs, allowed severities) are config-driven via verifiers/security/config.json.

Run policy checks

node policy/scripts/check-policy.mjs

Checks: semver monotonicity, artifact hash uniqueness, required capabilities.

Security & Threat Model

RepoMesh touches ledger events (signed JSON), node manifests (public keys + capabilities), registry indexes (auto-generated trust scores), and XRPL testnet (anchor transactions; posting refuses any endpoint that isn't a known testnet one). It does not touch member repo source code, private keys, user credentials, or browsing data. Private signing keys never leave the CI runner. Network access is limited to the GitHub API (PR creation), XRPL testnet (anchoring), and OSV.dev (vulnerability lookups). No telemetry is collected or sent — zero analytics, zero crash reports, zero phone-home. See SECURITY.md for the full scope, required permissions, and vulnerability reporting process, and the threat model for the key-lifecycle trust boundary (why node.json authenticity depends on its source, and why revocation-sensitive verification should use --anchored).

Hardening:

• Child-process calls that interpolate variable data use execFileSync with array arguments; the remaining execSync calls use static, constant command strings — no shell-injection vectors.
• Ledger and registry JSON is parsed inside try/catch with structured, line-numbered errors; a malformed line is skipped and surfaced, never crashes the tool with a raw stack.
• Path traversal is prevented on all file operations (resolve + boundary check).
• ReDoS-safe parsing throughout (no unbounded regex).
• PEM private keys are excluded via .gitignore, never printed to stdout or CI logs, and written with owner-only (0600) permissions.

Testing

The full node --test suite covers Ed25519 signatures, schema validation, Merkle tree integrity (v1 + RFC-6962 v2), append-only invariants, path traversal prevention, anchor verification, the trusted-attestor allowlist, and input validation across the CLI, ledger, anchor, verifier, and tools layers.

# Run every suite and read the exact pass/fail counts from the summary footer:
node --test $(git ls-files '*.test.mjs')

The test count grows as suites are added — run the command above for the current total rather than relying on a number that drifts out of date.

CI runs the same 9 suites on every pull request (ledger-ci.yml, the required test check), with --experimental-test-coverage and a line-coverage floor (--test-coverage-lines=57), then npm audit --audit-level=high --omit=dev for the root, anchor/xrpl and ledger.

License

MIT

Built by MCP Tool Shop