Add OpenTimestamps workflow and documentation for cryptographic commit proofs

[Copilot]

Adds automated blockchain-anchored timestamping for commits and releases via OpenTimestamps, providing tamper-evident proof-of-existence independent of GitHub's internal timestamps.

Changes

• .github/workflows/ots-stamp.yml: GitHub Actions workflow that stamps commit SHA on push to main/master and release events, uploads .ots proof as artifact
• TIMESTAMPING-HOWTO.md: Documents GPG signing practices, manual OTS stamping, proof verification, and workflow usage

Workflow behavior

on:
  push:
    branches: [main, master]
  release:
    types: [published]

The workflow creates commit-sha.txt containing the commit SHA, stamps it with ots stamp, and uploads both the SHA file and .ots proof as downloadable artifacts named ots-proof-<commit-sha>.

Proofs can be verified after Bitcoin blockchain anchoring with:

ots verify commit-sha.txt

Original prompt

Add an OpenTimestamps proof workflow and a TIMESTAMPING-HOWTO.md to the repository

Summary

• Add a GitHub Actions workflow that stamps each pushed commit or published release with OpenTimestamps and uploads the .ots proof as an artifact.
• Add a documentation HOWTO (TIMESTAMPING-HOWTO.md) describing GPG-signed commits/tags, using Releases, and the OpenTimestamps workflow.

Files to add

1. .github/workflows/ots-stamp.yml

Contents (create this file exactly):

name: Create OpenTimestamps proof

on:
  push:
    branches:
      - main
      - master
  release:
    types: [published]

jobs:
  stamp:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4

      - name: Install OpenTimestamps client
        run: |
          python -m pip install --upgrade pip
          pip install opentimestamps-client

      - name: Create commit SHA file
        env:
          SHA: ${{ github.sha }}
        run: |
          echo -n "${SHA}" > commit-sha.txt
          ls -l commit-sha.txt
          echo "commit: ${SHA}"

      - name: Stamp with OpenTimestamps
        run: |
          # create an ots proof for the commit-sha file
          ots stamp commit-sha.txt
          ls -l commit-sha.txt*

      - name: Upload OTS proof artifact
        uses: actions/upload-artifact@v4
        with:
          name: ots-proof-${{ github.sha }}
          path: |
            commit-sha.txt
            commit-sha.txt.ots

Notes on the workflow

• The workflow runs on pushes to main and master and whenever a release is published.
• It stamps the commit SHA using the OpenTimestamps client and uploads commit-sha.txt and commit-sha.txt.ots as build artifacts.
• If you prefer to run only on tags/releases, we can change the triggers accordingly.

2. TIMESTAMPING-HOWTO.md (placed at repo root)

Contents (create this file exactly):

# Public timestamping and proof of existence

This repository includes an automated workflow that creates OpenTimestamps proofs for commits and releases. Below are recommended steps and background to create stronger, verifiable timestamps for your work.

## Why GitHub timestamps alone are not always sufficient
- Git commit metadata includes author and committer dates, which can be changed locally before pushing.
- GitHub release publish times are recorded by GitHub servers and are more trustworthy than local commit dates.
- For cryptographic, tamper-evident proof, combine signed commits/tags with an external timestamping system such as OpenTimestamps or a commercial TSA (RFC3161).

## Recommended practice
1. Create GPG-signed commits or tags
   - Configure GPG and git (example):
     - `git config user.signingkey <YOUR_KEY_ID>`
     - `git commit -S -m "..."`      # for signed commit
     - `git tag -s v1.0 -m "release"`    # for signed tag
   - Push commits and tags:
     - `git push origin main`
     - `git push origin --tags`

2. Create a GitHub Release from a signed tag
   - Releases show the published time recorded by GitHub servers.

3. Use OpenTimestamps for an external, tamper-evident proof
   - This repository includes a GitHub Action that automatically creates an OpenTimestamps proof for each pushed commit or published release and uploads the `.ots` proof as an artifact.
   - To create proofs locally:
     - `echo -n <commit-sha> > sha.txt`
     - `ots stamp sha.txt`
     - Keep `sha.txt` and `sha.txt.ots` together as your proof.

4. Verifying an OTS proof
   - Install the OpenTimestamps client and run:
     - `ots verify sha.txt`
   - The proof will show that the SHA existed at or before the anchored blockchain time.

## Automation in this repo
- The workflow `.github/workflows/ots-stamp.yml` stamps the commit SHA on push and publishes the proof as an artifact named `ots-proof-<sha>`.
- If you prefer proofs only for releases/tags, edit the workflow triggers to `push: tags: - 'v*'` and/or limit to `release` events.

## Notes and limitations
- OpenTimestamps anchors proofs to Bitcoin; the OTS workflow uses the public OTS servers to request anchoring. If you require an RFC3161 TSA (commercial), you will need a different workflow and possibly paid service.
- Signed commits and signed tags are recommended for stronger attribution: signatures prove authorship, and OTS proves existence at a given time.

If you want, I can also:
- Modify the workflow to attach the `.ots` proof as a release asset automatically when a release is published.
- Configure stamping only for tags/releases.
- Add an example GitHub Action that runs both OpenTimestamps and an RFC3161 TSA client (if you provide TSA credentials).

PR title

• Add OpenTimestamps GitHub Action and TIMESTAMPING-HOWTO.md

Repository

• Ada40/fractal-harmonic-framework

This pull request was created as a result of the following prompt from Copilot chat.

Add an OpenTimestamps proof workflow and a TIMESTAMPING-HOWTO.md to the repository

Summary

• Add a GitHub Actions workflow that stamps each pushed commit or published release with OpenTimestamps and uploads the .ots proof as an artifact.
• Add a documentation HOWTO (TIMESTAMPING-HOWTO.md) describing GPG-signed commits/tags, using Releases, and the OpenTimestamps workflow.

Files to add

1. .github/workflows/ots-stamp.yml

Contents (create this file exactly):

name: Create OpenTimestamps proof

on:
  push:
    branches:
      - main
      - master
  release:
    types: [published]

jobs:
  stamp:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4

      - name: Install OpenTimestamps client
        run: |
          python -m pip install --upgrade pip
          pip install opentimestamps-client

      - name: Create commit SHA file
        env:
          SHA: ${{ github.sha }}
        run: |
          echo -n "${SHA}" > commit-sha.txt
          ls -l commit-sha.txt
          echo "commit: ${SHA}"

      - name: Stamp with OpenTimestamps
        run: |
          # create an ots proof for the commit-sha file
          ots stamp commit-sha.txt
          ls -l commit-sha.txt*

      - name: Upload OTS proof artifact
        uses: actions/upload-artifact@v4
        with:
          name: ots-proof-${{ github.sha }}
          path: |
            commit-sha.txt
            commit-sha.txt.ots

Notes on the workflow

• The workflow runs on pushes to main and master and whenever a release is published.
• It stamps the commit SHA using the OpenTimestamps client and uploads commit-sha.txt and commit-sha.txt.ots as build artifacts.
• If you prefer to run only on tags/releases, we can change the triggers accordingly.

2. TIMESTAMPING-HOWTO.md (placed at repo root)

Contents (create this file exactly):

# Public timestamping and proof of existence

This repository includes an automated workflow that creates OpenTimestamps proofs for commits and releases. Below are recommended steps and background to create stronger, verifiable timestamps for your work.

## Why GitHub timestamps alone are not always sufficient
- Git commit metadata includes author and committer dates, which can be changed locally before pushing.
- GitHub release publish times are recorded by GitHub servers and are more trustworthy than local commit dates.
- For cryptographic, tamper-evident proof, combine signed commits/tags with an external timestamping system such as OpenTimestamps or a commercial TSA (RFC3161).

## Recommended practice
1. Create GPG-signed commits or tags
   - Configure GPG and git (example):
     - `git config user.signingkey <YOUR_KEY_ID>`
     - `git commit -S -m "..."`      # for signed commit
     - `git tag -s v1.0 -m "release"`    # for signed tag
   - Push commits and tags:
     - `git push origin main`
     - `git push origin --tags`

2. Create a GitHub Release from a signed tag
   - Releases show the published time recorded by GitHub servers.

3. Use OpenTimestamps for an external, tamper-evident proof
   - This repository includes a GitHub Action that automatically creates an OpenTimestamps proof for each pushed commit or published release and uploads the `.ots` proof as an artifact.
   - To create proofs locally:
     - `echo -n <commit-sha> > sha.txt`
     - `ots stamp sha.txt`
     - Keep `sha.txt` and `sha.txt.ots` together as your proof.

4. Verifying an OTS proof
   - Install the OpenTimestamps client and run:
     - `ots verify sha.txt`
   - The proof will show that the SHA existed at or before the anchored blockchain time.

## Automation in this repo
- The workflow `.github/workflows/ots-stamp.yml` stamps the commit SHA on push and publishes the proof as an artifact named `ots-proof-<sha>`.
- If you prefer proofs only for releases/tags, edit the workflow triggers to `push: tags: - 'v*'` and/or limit to `release` events.

## Notes and limitations
- OpenTimestamps anchors proofs to Bitcoin; the OTS workflow uses the public OTS servers to request anchoring. If you require an RFC3161 TSA (commercial), you will need a different workflow and possibly paid service.
- Signed commits and signed tags are recommended for stronger attribution: signatures prove authorship, and OTS proves existence at a given time.

If you want, I can also:
- Modify the workflow to attach the `.ots` proof as a release asset automatically when a release is published.
- Configure stamping only for tags/releases.
- Add an example GitHub Action that runs both OpenTimestamps and an RFC3161 TSA client (if you provide TSA credentials).

PR title

• Add OpenTimestamps GitHub Action and TIMESTAMPING-HOWTO.md

Repository

• Ada40/fractal-harmonic-framework

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.