@stream44.studio/dco 0.3.0-rc.2

package/.o/GordianOpenIntegrity.yaml

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "envelope": "ur:envelope/lrtpsotanshdhdcxdkchoebkgohkmyahwnmevtvtrhmytpjsztzemdfdtkvydsjecwpetyimmwfljpksoyaylftpsohdgltansgylftanshfhdcxdthsctfzbdihfmueaygdlpsfrtoeswaxlkeoaobyhpiofsindtfymylosaeofneotansgrhdcxchweztoevyckleryrdsslaiawdgtperyckfplbtkbbwytljotkfnesiycmfhspeeoycsfncsfgoycsfztpsohdjktngdgmgwhflfaxhdimyawzaxjtlddndnlecyqzvdclkskotksafsskdmlgwpbgdszmrerncmuofpaxmkkeahluwnmoidbsiypedmaozsneykjpplurloolghesjedwjtbzstimswwladghiartaxjptaeemewdesehahvybtfleowsjsvavwmtvarfsbwkhestknprpywncycmfpsbssfristkahtniectuofgoytpsojyfljljpieinhsjtgwjoihjtgajtjyihiojpinjykktpsokshnjkjkisdpihieeyececehescxfpfpfpfpfxeoglknhsfxehjzhtfygaehglghfeecfpfpfpfpgagdjtgoknhkfxgokpkkgmflgmgleogsdniofdemksksghgaidhdethfjnjegtecfxfphfeeflkphdkkjzkogwfecxjyeeeedpjkiniojtinjtiodpjeihkkutztrteh",
+  "mark": "0fbc3988",
+  "$defs": {
+    "envelope": {
+      "$ref": "https://datatracker.ietf.org/doc/draft-mcnally-envelope/"
+    },
+    "mark": {
+      "$ref": "https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2025-001-provenance-mark.md"
+    }
+  }
+}
+---
+# Repository DID: did:repo:d241cef226ebb7495bcbe8422c889ffc088c2b50
+# Current Mark: 0fbc3988 (🅑 BIAS ROOF EYES LOGO)
+# Inception Mark: 1275c22f (🅑 BRAG KEEP SAGA DULL)
+# XID(2417a20a) [
+#     'key': Bytes(78) [
+#         'allow': 'All'
+#     ]
+#     'provenance': Bytes(115)
+#     "GordianOpenIntegrity": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPnUzYCUuyRGRN3L+gH7xxTIbX8VmkM5CAV4GuXylvOE t44-signing-key"
+# ]
+# Trust established using https://github.com/Stream44/t44-BlockchainCommons.com

package/DCO.md

@@ -0,0 +1,34 @@
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.

package/README.md

@@ -0,0 +1,122 @@
+⚠️ **WARNING:** This repository may get squashed and force-pushed if the [GordianOpenIntegrity](https://github.com/Stream44/t44-blockchaincommons.com) implementation must change in incompatible ways. Keep your diffs until the **GordianOpenIntegrity** system is stable.
+
+🔷 **Open Development Project:** The implementation is a preview release for community feedback.
+
+⚠️ **Disclaimer:** Under active development. Code has not been audited, APIs and interfaces are subject to change.
+
+Developer Certificate of Origin (DCO) Tools
+===
+
+DCOs are a simple way to have contributors agree to terms present in a `DCO.md` file whenever they commit to your repository.
+
+It is assurance for you that every commit adheres to the terms present in git at the time of the commit.
+
+This project contains tools to facilitate a DCO process for any project.
+
+**No outside service is required. Use github actions for signature verification on pull requests.**
+
+
+Usage
+---
+
+### Setup
+
+Create a `DCO.md` file and sign.
+
+A great template for open source projects is: [https://developercertificate.org](https://developercertificate.org)
+
+
+### Signing
+
+```
+bunx @stream44.studio/dco commit [--signing-key ~/.ssh/key] <git arguments>
+```
+
+### Verifying
+
+```
+bunx @stream44.studio/dco validate
+```
+
+Also see [Github Actions](#github-action) below.
+
+
+Tools
+---
+
+### Git Commit Script
+
+The script provides a nice experience for contributors of your project. 
+
+Instead of running `git commit ...`, run `commit.sh ...`.
+
+The **first time** you run the script you will see the DCO terms of the repository you are comitting to so you can agree.
+
+It will add an entry in `.dco-signatures` to record the signature and commit the change.
+
+It will then always add `--signoff` to every `git commit` invocation in order to **sign off** on the commit.
+
+These are the details from `git commit --help`:
+
+```
+-s, --signoff, --no-signoff
+    Add a Signed-off-by trailer by the committer at the end of the commit log message.
+    The meaning of a signoff depends on the project to which you’re committing.
+    For example, it may certify that the committer has the rights to submit the work under the project’s license
+    or agrees to some contributor representation, such as a Developer Certificate of Origin.
+    (See https://developercertificate.org for the one used by the Linux kernel and Git projects.)
+    Consult the documentation or leadership of the project to which you’re contributing to understand how
+    the signoffs are used in that project.
+```
+
+Optionally a signing key can be supplied to cryptographically sign commits as well. The fingreprint of the signing
+key will be sored in the `.dco-signatures` file.
+
+A project can choose to require signing keys or not by setting `enforceSignatureFingerprints` for the github action.
+
+
+### Verification Script
+
+Ensures all commits were signed off my signatures recorded in `.dco-signatures`.
+
+
+### Github Actions
+
+The github action enforces DCO sign-offs by ensuring all commits have a `Signed-off-by: Jane Doe <jane@example.com>`
+line in the respective commit messages and the same is found in `.dco-signatures`.
+
+
+Add to `.github/workflows/dco.yml` in your repository:
+
+```yaml
+name: Validate DCO Signatures
+on: [push, pull_request]
+jobs:
+  dco:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: Stream44/dco@main
+        with:
+          enforceSignatureFingerprints: true
+```
+
+
+Provenance
+===
+
+Repository DID: `did:repo:d241cef226ebb7495bcbe8422c889ffc088c2b50`
+
+<table>
+  <tr>
+    <td><strong>Inception Mark</strong></td>
+    <td><img src=".o/GordianOpenIntegrity-InceptionLifehash.svg" width="64" height="64"></td>
+    <td><strong>Current Mark</strong></td>
+    <td><img src=".o/GordianOpenIntegrity-CurrentLifehash.svg" width="64" height="64"></td>
+    <td>Trust established using<br/><a href="https://github.com/Stream44/t44-blockchaincommons.com">Stream44/t44-BlockchainCommons.com</a></td>
+  </tr>
+</table>
+
+(c) 2026 [Christoph.diy](https://christoph.diy) • Code: `Apache 2.0` • Text: `CC-BY` • Created with [Stream44.Studio](https://Stream44.Studio)

package/action.yml

@@ -0,0 +1,32 @@
+name: 'DCO Check'
+description: 'Validate Developer Certificate of Origin (DCO) signatures on all commits'
+author: 'Stream44'
+
+inputs:
+  enforceSignatureFingerprints:
+    description: 'Enforce that SSH signature fingerprints on commits match those recorded in .dco-signatures'
+    required: false
+    default: 'false'
+
+branding:
+  icon: 'check-circle'
+  color: 'green'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Validate DCO
+      shell: bash
+      run: |
+        chmod +x ${{ github.action_path }}/validate.sh
+        ENFORCE_FLAG=""
+        if [[ "${{ inputs.enforceSignatureFingerprints }}" == "true" ]]; then
+          ENFORCE_FLAG="--enforce-signature-fingerprints"
+        fi
+        ${{ github.action_path }}/validate.sh $ENFORCE_FLAG
+      env:
+        GITHUB_EVENT_NAME: ${{ github.event_name }}
+        GITHUB_BASE_REF: ${{ github.base_ref }}
+        GITHUB_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        GITHUB_BEFORE: ${{ github.event.before }}
+        GITHUB_SHA: ${{ github.sha }}

package/caps/Dco.test.ts

@@ -0,0 +1,288 @@
+#!/usr/bin/env bun test
+
+import * as bunTest from 'bun:test'
+import { run } from 't44/workspace-rt'
+import { join } from 'path'
+import { rm, mkdir, writeFile, readFile, copyFile, access } from 'fs/promises'
+import { constants, existsSync } from 'fs'
+import { $ } from 'bun'
+
+const WORK_DIR = join(import.meta.dir, '.~dco')
+
+const {
+    test: { describe, it, expect },
+    dco,
+} = await run(async ({ encapsulate, CapsulePropertyTypes, makeImportStack }: any) => {
+    const spine = await encapsulate({
+        '#@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0': {
+            '#@stream44.studio/encapsulate/structs/Capsule': {},
+            '#': {
+                test: {
+                    type: CapsulePropertyTypes.Mapping,
+                    value: 't44/caps/WorkspaceTest',
+                    options: {
+                        '#': {
+                            bunTest,
+                            env: {}
+                        }
+                    }
+                },
+                dco: {
+                    type: CapsulePropertyTypes.Mapping,
+                    value: './Dco'
+                },
+            }
+        }
+    }, {
+        importMeta: import.meta,
+        importStack: makeImportStack(),
+        capsuleName: '@stream44.studio/dco/caps/Dco.test'
+    })
+    return { spine }
+}, async ({ spine, apis }: any) => {
+    return apis[spine.capsuleSourceLineRef]
+}, {
+    importMeta: import.meta
+})
+
+await rm(WORK_DIR, { recursive: true, force: true })
+await mkdir(WORK_DIR, { recursive: true })
+
+// ════════════════════════════════════════════════════════════════════════
+//
+//  DCO — Developer Certificate of Origin Capsule Tests
+//
+// ════════════════════════════════════════════════════════════════════════
+
+// Helper: create a fresh git repo with DCO.md
+async function createTestRepo(name: string): Promise<string> {
+    const repoDir = join(WORK_DIR, name)
+    await mkdir(repoDir, { recursive: true })
+    await $`git init`.cwd(repoDir).quiet()
+    await $`git config user.name "Test User"`.cwd(repoDir).quiet()
+    await $`git config user.email "test@example.com"`.cwd(repoDir).quiet()
+    await $`git checkout -b main`.cwd(repoDir).quiet().nothrow()
+
+    // Copy DCO.md from the package
+    const packageDir = join(import.meta.dir, '..')
+    await copyFile(join(packageDir, 'DCO.md'), join(repoDir, 'DCO.md'))
+
+    return repoDir
+}
+
+describe('Dco', function () {
+
+    // ──────────────────────────────────────────────────────────────
+    // 1. hasDco
+    // ──────────────────────────────────────────────────────────────
+
+    describe('1. hasDco', function () {
+
+        it('should return true when DCO.md exists', async function () {
+            const repoDir = await createTestRepo('has-dco-true')
+            const result = await dco.hasDco({ repoDir })
+            expect(result).toBe(true)
+        })
+
+        it('should return false when DCO.md does not exist', async function () {
+            const repoDir = join(WORK_DIR, 'has-dco-false')
+            await mkdir(repoDir, { recursive: true })
+            const result = await dco.hasDco({ repoDir })
+            expect(result).toBe(false)
+        })
+    })
+
+    // ──────────────────────────────────────────────────────────────
+    // 2. sign
+    // ──────────────────────────────────────────────────────────────
+
+    describe('2. sign', function () {
+
+        it('should sign the DCO with --yes-signoff', async function () {
+            const repoDir = await createTestRepo('sign-auto')
+
+            await dco.sign({ repoDir, autoAgree: true })
+
+            // Verify marker file was created
+            const markerPath = join(repoDir, '.git/.dco-agreed')
+            expect(existsSync(markerPath)).toBe(true)
+
+            // Verify .dco-signatures was created
+            const sigPath = join(repoDir, '.dco-signatures')
+            expect(existsSync(sigPath)).toBe(true)
+        })
+
+        it('should throw when DCO.md is missing', async function () {
+            const repoDir = join(WORK_DIR, 'sign-no-dco')
+            await mkdir(repoDir, { recursive: true })
+
+            let threw = false
+            try {
+                await dco.sign({ repoDir, autoAgree: true })
+            } catch (e: any) {
+                threw = true
+                expect(e.message).toContain('DCO.md not found')
+            }
+            expect(threw).toBe(true)
+        })
+    })
+
+    // ──────────────────────────────────────────────────────────────
+    // 3. isSigned
+    // ──────────────────────────────────────────────────────────────
+
+    describe('3. isSigned', function () {
+
+        it('should return signed: false for a fresh repo', async function () {
+            const repoDir = await createTestRepo('is-signed-false')
+            const result = await dco.isSigned({ repoDir })
+            expect(result.signed).toBe(false)
+        })
+
+        it('should return signed: true after signing', async function () {
+            const repoDir = await createTestRepo('is-signed-true')
+            await dco.sign({ repoDir, autoAgree: true })
+
+            const result = await dco.isSigned({ repoDir })
+            expect(result.signed).toBe(true)
+            expect(result.name).toBe('Test User')
+            expect(result.email).toBe('test@example.com')
+            expect(result.date).toBeDefined()
+            expect(result.agreementCommit).toBeDefined()
+        })
+    })
+
+    // ──────────────────────────────────────────────────────────────
+    // 4. getSignatures
+    // ──────────────────────────────────────────────────────────────
+
+    describe('4. getSignatures', function () {
+
+        it('should return found: false when no signatures file', async function () {
+            const repoDir = await createTestRepo('sigs-none')
+            const result = await dco.getSignatures({ repoDir })
+            expect(result.found).toBe(false)
+            expect(result.signatures).toEqual([])
+        })
+
+        it('should parse signatures after signing', async function () {
+            const repoDir = await createTestRepo('sigs-parse')
+            await dco.sign({ repoDir, autoAgree: true })
+
+            const result = await dco.getSignatures({ repoDir })
+            expect(result.found).toBe(true)
+            expect(result.signatures.length).toBe(1)
+            expect(result.signatures[0].name).toBe('Test User')
+            expect(result.signatures[0].email).toBe('test@example.com')
+            expect(result.signatures[0].signedDate).toBeDefined()
+            expect(result.signatures[0].agreementCommit.length).toBeGreaterThan(0)
+        })
+    })
+
+    // ──────────────────────────────────────────────────────────────
+    // 5. signAndCommit
+    // ──────────────────────────────────────────────────────────────
+
+    describe('5. signAndCommit', function () {
+
+        it('should sign DCO and commit changes with --signoff', async function () {
+            const repoDir = await createTestRepo('sign-commit')
+
+            // Create a test file to commit
+            await writeFile(join(repoDir, 'README.md'), '# Test Project\n')
+
+            await dco.signAndCommit({
+                repoDir,
+                message: 'Initial commit',
+                autoAgree: true,
+            })
+
+            // Verify commits exist
+            const logResult = await $`git log --oneline`.cwd(repoDir).quiet()
+            const commits = logResult.text().trim().split('\n').filter(Boolean)
+            // Should have: DCO.md commit + DCO signature commit + user commit
+            expect(commits.length).toBe(3)
+
+            // Verify the user commit has Signed-off-by
+            const lastBody = await $`git log -1 --format=%b`.cwd(repoDir).quiet()
+            expect(lastBody.text()).toContain('Signed-off-by:')
+        })
+
+        it('should copy .dco-signatures to projectSourceDir', async function () {
+            const repoDir = await createTestRepo('sign-commit-copy')
+            const projectDir = join(WORK_DIR, 'sign-commit-copy-source')
+            await mkdir(projectDir, { recursive: true })
+
+            await writeFile(join(repoDir, 'README.md'), '# Test\n')
+
+            await dco.signAndCommit({
+                repoDir,
+                message: 'Test commit',
+                autoAgree: true,
+                projectSourceDir: projectDir,
+            })
+
+            // Verify .dco-signatures was copied to project source
+            const copiedSigPath = join(projectDir, '.dco-signatures')
+            expect(existsSync(copiedSigPath)).toBe(true)
+
+            const content = await readFile(copiedSigPath, 'utf-8')
+            expect(content).toContain('Test User')
+        })
+    })
+
+    // ──────────────────────────────────────────────────────────────
+    // 6. validate
+    // ──────────────────────────────────────────────────────────────
+
+    describe('6. validate', function () {
+
+        it('should validate a properly signed repository', async function () {
+            const repoDir = await createTestRepo('validate-pass')
+
+            await writeFile(join(repoDir, 'README.md'), '# Test\n')
+
+            await dco.signAndCommit({
+                repoDir,
+                message: 'Signed commit',
+                autoAgree: true,
+            })
+
+            const result = await dco.validate({ repoDir })
+            expect(result.valid).toBe(true)
+        })
+
+        it('should fail validation for unsigned commits', async function () {
+            const repoDir = await createTestRepo('validate-fail')
+
+            // Create a commit WITHOUT --signoff
+            await writeFile(join(repoDir, 'README.md'), '# Test\n')
+            await $`git add -A`.cwd(repoDir).quiet()
+            await $`git commit -m "Unsigned commit"`.cwd(repoDir).quiet()
+
+            const result = await dco.validate({ repoDir })
+            expect(result.valid).toBe(false)
+        })
+    })
+
+    // ──────────────────────────────────────────────────────────────
+    // 7. Re-sign (idempotent)
+    // ──────────────────────────────────────────────────────────────
+
+    describe('7. Re-sign idempotent', function () {
+
+        it('should not create additional commits on re-sign', async function () {
+            const repoDir = await createTestRepo('re-sign')
+
+            // First sign
+            await dco.sign({ repoDir, autoAgree: true })
+            const countAfterFirst = await $`git rev-list --count HEAD`.cwd(repoDir).quiet()
+
+            // Second sign (should be idempotent)
+            await dco.sign({ repoDir, autoAgree: true })
+            const countAfterSecond = await $`git rev-list --count HEAD`.cwd(repoDir).quiet()
+
+            expect(countAfterSecond.text().trim()).toBe(countAfterFirst.text().trim())
+        })
+    })
+})