---
robots: noindex, nofollow
---

# **Open Integrity Project - Git Inception Proof-of-Concepts (POCs)**

This repository demonstrates a Proof-of-Concept (POC) for how Git repositories can serve as cryptographic roots of trust. It showcases a platform-agnostic approach for establishing secure and verifiable repository histories, to establish transparency and trust from the initialization (inception) of a repository.

By using a tightly constrained, empty "Inception Commit" signed with an SSH key, this approach ensures all future changes and commits build on a secure and verified foundation. It does so by creating a robust, cryptographically verifiable identifier, enabling distributed and decentralized trust for code integrity and provenance.

The **Open Integrity Project** of Blockchain Commons is dedicated to advancing open, interoperable, and secure digital infrastructure guided by our Gordian principles of independence, resilience, privacy, and openness. It empowers developers and organizations to establish cryptographic roots of trust as a stepping stone in building verifiable distributed and decentralized trust systems.

Through initiatives like the Git Inception POC, Blockchain Commons aims to uphold human dignity by enabling individuals to securely and transparently manage their digital assets while fostering collaboration across distributed and fully decentralized platforms.

## **Purpose**

The purpose of this proof-of-concept is to explore a method for securing a Git repository’s history from its inception by:

1. Establishing a **cryptographic root of trust** using an empty, SSH-signed Inception Commit.
2. Mitigating the known weaknesses of Git’s default SHA-1 commit identifiers through the tight constraints on the commit details and cryptographic signatures.
3. Enabling repositories to be verified and trusted in decentralized environments, including platforms such as GitHub, GitLab, peer-to-peer networks, and local systems.

## **Key Concepts**

### **1. The Inception Commit**
The Inception Commit (commit 0) serves is:
- **Empty**: The repository begin with no data (`git commit --allow-empty`). No changes are introduced in the commit other than the Git metadata. An empty commit tree will always has the same deterministic SHA-1 root hash.
- **Signed**: The commit is cryptographically signed with the owner’s SSH key, ensuring authenticity and immutability.
- **Constrained**: The commit message and metadata are highly constrained to minimize the attack surface for SHA-1 collisions.

### **2. Distributed Verification**
This technique enables repositories to operate in a **platform-agnostic** manner, ensuring verification across diverse environments:
- The Inception Commit’s ID serves as a unique distibuted identifier for the repository across all platforms.
- Its cryptographic signature ensures that the repository can be **independently verified**:
- On GitHub, GitLab, or any other hosting service.
- In peer-to-peer networks.
- Locally, without requiring a hosting platform.
- The distributed nature of verification makes the repository robust against platform-specific failures or compromises.

### **3. Mitigating SHA-1 Weaknesses**
While SHA-1 is cryptographically weak, this approach compensates by:
- Using **highly constrained commit details** to reduce the likelihood of a successful collision.
- **Signing the commit** with a cryptographic SSH key, which provides 128-bit security.
- Requiring any potential forgery to produce not only a valid SHA-1 collision but also a valid SSH signature.

### **4. Cryptographic Signing**
The SSH signature embedded in the Inception Commit provides:
- **Proof of Authenticity**: Verifies the identity of the repository creator.
- **Tamper Resistance**: Detects unauthorized modifications to the commit.

## **Walkthrough**

[[NOTE: It could be more info is needed earlier, but this walkthrough is the main place where I felt like things needed more explanation]]

This repository demonstrates the creation of an Inception Commit, establishing a cryptographic root of trust for the Git repository. Use the following steps to explore and verify the Inception Commit. They require the `gh` app, which is [available through Homebrew and other installers](https://github.com/cli/cli#installation).

1. **Clone the Repository**:

   gh repo clone BlockchainCommons/open_integrity-git_inception_pocs
   cd open_integrity-git_inception_pocs

2. **Locate the Inception Commit (Commit 0) SHA-1 Identifier**:

Retrieve the SHA-1 hash of the Inception Commit (commit 0) with the following command:

   git rev-list --max-parents=0 HEAD

Expected Output:

   a3306efcb768baa6f414409b6b3575914986c8a6

2. **Inspect the Inception Commit's Details**:

You can inspect the full details of this Inception commit:

   % git cat-file -p $(git rev-list --max-parents=0 HEAD)

Expected Output:

   tree 4b825dc642cb6eb9a060e54bf8d69288fbee4904
   author ChristopherA <[e-mail]> 1735930944 -0800
   committer SHA256:a61TkTtLFGEYOmdRMbpYGkZwXw2QUrGkAWp3dok8jcw <[e-mail]> 1735930944 -0800
   gpgsig -----BEGIN SSH SIGNATURE-----
   U1NIU0lHAAAAAQAAADMAAAALc3NoLWVkMjU1MTkAAAAgIz5gy/oWhp2G15wVysRKmrlkiH
   FnNggqTLwL7deTRLIAAAADZ2l0AAAAAAAAAAZzaGE1MTIAAABTAAAAC3NzaC1lZDI1NTE5
   AAAAQLh/eQoRwX2QHcyLugKlCpGfHhCBrl7diUkbZg4llCnRjihy+OhE++Mm0NqTsUwdMj
   3v6+9LQslOd2Sm8b/lowY=
   -----END SSH SIGNATURE-----

   Initialize repository and establish a SHA-1 root of trust

   Signed-off-by: @ChristopherA <[e-mail]>

   This key certifies future commits' integrity and origin. Additional keys can be authorized to certify commits via the creation of a ./.repo/config/verification/allowed_commit_signers file. This file must added in a commit signed by the inception key, granting these keys the authority to certify commits, including the potential to remove the authority of the inception key. Once established, any changes to allowed_commit_signers must be certified by one of the previously approved signers.

Note that the "tree" is `4b825dc642cb6eb9a060e54bf8d69288fbee4904` - this hash proves that the repository is empty (and will be the same for all Inception Commits, as they are required to be empty).

3. **Verify the Inception Commit Locally**:

Run this command to confirm that the Inception Commit is signed with a valid SSH key:

   git verify-commit $(git rev-list --max-parents=0 HEAD)

Expected output:

   Good "git" signature for @ChristopherA with ED25519 key SHA256:a61TkTtLFGEYOmdRMbpYGkZwXw2QUrGkAWp3dok8jcw

4. **Inspect the Commit on GitHub**:

Open the following URL in your browser to view the Inception Commit on GitHub.

**Mac:**

   open https://github.com/BlockchainCommons/open_integrity-git_inception_pocs/commit/$(git rev-list --max-parents=0 HEAD)

**Windows:**

   open https://github.com/BlockchainCommons/open_integrity-git_inception_pocs/commit/$(git rev-list --max-parents=0 HEAD)

GitHub should display a green `Verified` badge, confirming that the signing key used for the commit is recognized as belonging to `@ChristopherA`.


5. **Confirm Signing Key via GitHub API**:

Use GitHub’s API to list the signing keys associated with `@ChristopherA`:

   curl https://api.github.com/users/ChristopherA/ssh_signing_keys

Confirm that the fingerprint (`SHA256:a61TkTtLFGEYOmdRMbpYGkZwXw2QUrGkAWp3dok8jcw`) used to sign the Inception Commit matches one of the signing keys for the user `@ChristopherA`.

6. **Verify Remaining Commits**

Subsequent commits must either be signed by the same SSH key used for the Inception Commit or by SSH keys explicitly authorized in a preceding commit’s `./.repo/config/verification/allowed_commit_signers` file.

For example:

   open https://github.com/BlockchainCommons/open_integrity-git_inception_pocs/commit/b7d0013e4a2770363e4f33290188c0890e51fa6e

...is a commit, signed by the Inception Key, that adds a initial `./.repo/config/verification/allowed_commit_signers` file.

_NOTE: Currently this example commit only authorizes the Inception Key, but could authorize other SSH keys, or even remove the authorization of the Inception Key to make commits._


## **How The Script Works**

This proof-of-concept is implemented in a single script that:
1. **Removes Old Git Metadata**: Ensures the repository is initialized from scratch.
2. **Initializes an Empty Git Repository**: Creates a new repository with no content.
3. **Creates and Signs the Inception Commit**:
- Generates an empty commit with constrained details.
- Signs the commit using the owner’s SSH key.
4. **Outputs a Cryptographic Identifier**:
- Displays the SHA-1 hash of the Inception Commit.
- Verifies the SSH signature to ensure authenticity.

Subsequent commits, such as adding governance files (e.g., `./.repo/config/verification/allowed_commit_signers`), build on this root of trust.

## **Script Setup Instructions**

### **1. Prerequisites**
1. **SSH Keys**: Even if you already have an SSH key for authentication, generate a new key specifically for signing using the following naming convention:
- Best practices are to use separate SSH keys for signing and authentication to enhance security and minimize risks:

     ssh-keygen -t ed25519 -C "# Signing key created on $(date -u +'%Y-%m-%d %H:%M:%S %Z')" -f ~/.ssh/sign_id_ed25519-${MY_LOCAL_DEVICE_NAME}-${MY_GITHUB_ID}

- **Explanation**:
- `-t ed25519`: Specifies the Ed25519 key type, which is highly secure and efficient.
- `-C "# Signing key created on $(date -u +'%Y-%m-%d %H:%M:%S %Z")"`: Sets the comment to include the creation date for better traceability.
- `-f ~/.ssh/sign_id_ed25519-${MY_LOCAL_DEVICE_NAME}-${MY_GITHUB_ID}.pub`: Sets the file name to match your preferred format (e.g., `sign_id_ed25519-athena.local-ChristopherA.pub`).

2. **Upload Public Keys to GitHub**:
- Copy the public authentication key to your clipboard:

     pbcopy < ~/.ssh/sign_id_ed25519-athena.local-ChristopherA.pub

- Upload the public key to GitHub:
1. Navigate to [GitHub SSH Settings](https://github.com/settings/keys).
2. Click **"New SSH Key"**.
3. Paste the public key from your clipboard into the **Key** field.
4. Add a meaningful title (e.g., "Signing Key for athena.local created 2025-01-03").
5. Change the **"Key Type"** to **"Signing Key"**.
6. Click **"Add SSH Key"**.

3. **Verify Keys**:
- Ensure that both authentication and signing keys are correctly configured in your local Git context and GitHub.
- LOCAL GIT CONTEXT:

   git config --global user.signingkey ~/.ssh/sign_id_ed25519-athena.local-ChristopherA.pub
   git config --global gpg.format ssh
   git config --global commit.gpgsign true
   git config --global tag.gpgsign true

- GITHUB: Verify that you've added your signing key via `https://api.github.com/users/{MY_GITHUB_ID}/ ssh_signing_keys`, e.g.:

   curl https://api.github.com/users/ChristopherA/ssh_signing_keys

4. **GitHub CLI (`gh`)**: Install and authenticate [the GitHub CLI](https://github.com/cli/cli):

    gh auth login

[[NOTE: NEEDS INSTALL INFO FOR GH]]

5. **Install `jq`**: Required for parsing `gh api` JSON output:

    sudo apt install jq  # or brew install jq

### **2. Preparing the Script**
1. Clone this repository:

    gh clone https://github.com/BlockchainCommons/open_integrity-inception_poc.git

2. Navigate to the folder where the script is located:

    cd open_integrity-inception_poc

3. Copy the script to an empty folder.
- WARNING: If the folder is already initialized for git, the git history will be deleted! But the rest of the contents will be left intact.
- `inception-test` is used as an example, but pick a repo name of your choice!

   mkdir ../inception-test
   cp init_repo_with_inception_commit-POC.sh ../inception-test

3. Ensure the script is executable:

    chmod +x init_repo_with_inception_commit-POC.sh

### **3. Running the Script**
1. **Navigate to Your Pre-Git-Init Repository Folder**:
- This script currently must be executed **inside the folder** where you want to initialize the Git repository.

   cd ../inception-test

2. **Run the Script**:

    ./init_repo_with_inception_commit-POC.sh

3. **Verify the Output**:
- The SHA-1 hash of the Inception Commit.
- A successful verification of the SSH signature.

[[NOTE: needs more instructions, maybe a reference to the earlier section on verifying the initial,, also not sure about the ordering of that initial verification]]

## **Roadmap: Advancing the Vision**

The following roadmap outlines the planned enhancements and vision for this proof-of-concept, focusing on validation, adoption, and integration into decentralized identity systems.

### **Short-Term Goals**

1. **Validation Scripts**:
- Develop scripts to validate additional commits against various `./.repo/config/verification/allowed_commit_signers` configurations, including:
- Adding new signers.
- Removing existing signers, including the Inception Signing Key.
- Verifying multi-signer governance policies.
- Test validation scripts against various platforms such as GitLab, GitHub, and peer-to-peer Git systems.

2. **Standardized `.repo` Folder**:
- Define a structured format for the `.repo` folder to organize:
- Configuration files.
- Governance rules (e.g., `allowed_commit_signers`).
- Validation scripts and Git hooks.
- DRAFT Reference: [Git Repo Directory Structure](./git_repo_directory_structure.md).

3. **Git Hooks**:
- Create platform-agnostic Git hooks to enforce governance policies:
- Pre-commit hooks for verifying SSH signatures.
- Pre-receive and update hooks for validating commit policies during pushes.
- Leverage additional capabilities of platform-specific functionality, such as GitHub Actions.

4. **Git Extensibility**:
- Recommend a standard list of useful Git aliases, such as `git config --global alias.inception.commit "!git rev-list --max-parents=0 HEAD"`
- Git supports a variety of features, in particular plugins, that allow additional functionality to be added, for instance `git inception` instead of `git init`, or `git inception --verify HEAD` that verifies all commits to the HEAD of the repo.

4. **Tag and Binary Release Signing**:
- Support different sets of SSH keys in `./.repo/config/verification/` that are authorized to tag commits (`allowed_tag_signers`), or sign using detached SSH signatures binary releases of files (`allowed_release_signers`), etc.

### **Medium-Term Goals**

1. **Personal Roots of Trust**:
- Extend the concept of Inception Commits to personal Git repositories as decentralized roots of trust for software developers.
- Leverage Bittorrent’s Mainline Distributed Hash Table (DHT) for distributing mutable identity controller documents securely and efficiently.
- Leverage Ed25519 keys for cryptographic signatures in DHT-based and SSH systems.

2. **W3C DID Standards**:
- Explore integrating **Decentralized Identifiers (DIDs)** with Git repositories:
- Investigate integrating SSH keys into the W3C DID 1.1 specification as an authentication method.
- Develop the `did:repo` method specification.
- Showcase how W3C DID Controller Documents can be derived from Git repository commit history, reinforcing the link between cryptographic roots of trust and decentralized identifiers (DIDs).
- Collaborate with DID resolvers to support `did:repo`-based indentifiers.

3. **Broader Adoption**:
- Publish educational resources and practical examples to encourage adoption by open-source projects and enterprises.
- Demonstrate how cryptographic roots of trust strengthen software provenance and integrity, reinforcing trust in open-source ecosystems and beyond.

4. **Trust Manifest Files**:
- Research cryptographic trust manifests (e.g., `repo-trust-manifest.env`) to support:
- Elidable privacy for developer privacy or sensitive operations, for instance commit to an authorization of a key without revealing it until later.
- Exploring governance models with privacy-preserving cryptographic techniques, such as MPC threshold protocols (e.g., FROST), to support multi-party authorization and distributed trust management.

## **Call for Contributions**

We invite the open-source community to collaborate. Share ideas for improvement, contribute tools or scripts, and help sustain this vision through financial support.
1. **Suggestions**:
- Share ideas for improving the proof-of-concept or extending its applications, here in the [issues](https://github.com/BlockchainCommons/open_integrity-git_inception_pocs/issues) for this repo, or by contacting us directly.
2. **Code Contributions**:
- Develop scripts, hooks, or tools that align with this vision.
3. **Financial Support**:
- Support Blockchain Commons in building open, interoperable, and secure digital infrastructure that empowers individuals to control their own data while fostering human dignity online. (More on supporting us in this way is below.)

## **License**

(c) 2025 By Blockchain Commons LLC.
This repository is licensed under the BSD-2-Clause Plus Patent License. Learn more at [LICENSE](https://spdx.org/licenses/BSD-2-Clause-Patent.html).

## **Support**

Blockchain Commons advocates for open, interoperable, secure, and compassionate digital infrastructure to enable individuals to control their digital destiny.

You can support us via the [GitHub Sponsor Page](https://github.com/sponsors/BlockchainCommons) or by making a one-time donation.

This is more than a transaction--supporting Blockchain Commons means joining a movement to advance digital civil liberties and human rights, foster the open web, and empower individuals with secure, human-centered digital tools. By joining us, you become part of a network advocating for the commons and can contribute to shaping the future.

- Christopher Allen, Blockchain Commons - Principal Architect & Executive Director
- Email: [[e-mail]](mailto:[e-mail])
- GitHub: [@ChristopherA](https://github.com/ChristopherA)
- Twitter: [@ChristopherA](https://twitter.com/ChristopherA)
- Bluesky: [@ChristopherA](https://bsky.app/profile/christophera.bsky.social)
- Professional Blog: [Life With Alacrity](https://www.LifeWithAlacrity.com)

- Blockchain Commons LLC
- [Main Website](https://www.BlockchainCommons.com)
- [Developer Website](https://developer.BlockchainCommons.com)
- [GitHub](https://github.com/BlockchainCommons)