aere-proof-of-software/tools/proof-of-software/README.md

# Aere Proof of Software

An attestation of **what** was built, **from what**, **by whom** (the keys that signed, and who holds them when a developer credential
or `--signer` says so) and **when**, that anyone can verify without trusting
Aere: every artifact's SHA-256 and size, the SBOM's digest, the git commit and remote of the source tree, a **hybrid
signature** (classical + ML-DSA, both required) by the builder's own keys, and a **first-seen time on chain 2800**
covered by the validators' post-quantum certificate. It is the software-supply-chain shape of the Proof API: the
statement hash is notarized, and `GET /v1/proof/{statementHash}` returns the covering anchor and the finality.

```
node pos.mjs keygen --out keys.json                       # once, on the build machine; keep it secret
node pos.mjs attest --out attestation.json \
     --name myapp --version 1.4.2 --sbom sbom.json \
     --keys keys.json --cloud-key-file ~/.aere-cloud-key \
     dist/myapp-1.4.2.tgz dist/myapp-1.4.2.sha256
node pos.mjs verify attestation.json --cloud-key-file ~/.aere-cloud-key dist/myapp-1.4.2.tgz dist/myapp-1.4.2.sha256 sbom.json
```

`verify` recomputes every digest from the files it is handed, checks the statement text against `statementHash`,
verifies the hybrid signature, and asks the chain for the proof. It exits 0 only when everything present holds; what is
absent (no signature, no notarization, SBOM not handed over) is reported as absent, never as valid, and the verdict line
counts what was not judged. A missing artifact is a failure. Without a Cloud key the on-chain part is reported as unread,
not as valid.

**Who signed is yours to require (1.4.0).** A valid signature says that some keys signed, not which: anyone can attest their
own file under your package's name with their own keys, and until 1.4.0 that verified VALID without naming the signer. The
signature check now names the keys (`by keys 0x…`), `verify --signer <public keys>` requires the keys you expect (`node pos.mjs
pubkey --keys keys.json --out pub.json` writes the public part to hand out), and without `--signer` or a judged developer
credential the signer is reported as not judged.

## The statement

```json
{ "v": 1, "kind": "aere-proof-of-software", "tool": "aere-proof-of-software/1.0.0",
  "subject": { "name": "myapp", "version": "1.4.2" },
  "artifacts": [ { "name": "myapp-1.4.2.tgz", "sha256": "0x…", "bytes": 123456 } ],
  "sbom": { "name": "sbom.json", "sha256": "0x…", "bytes": 4321 },
  "source": { "commit": "…", "remote": "https://github.com/org/repo.git", "dirty": false },
  "builder": { "platform": "linux/x64", "node": "v22.0.0" },
  "createdAt": "2026-09-17T22:00:00.000Z" }
```

The canonical text is `JSON.stringify(statement)` exactly as written into the attestation; `statementHash` is its
SHA-256; the hybrid signature (see `@aere/pq-sign`) is over that text; the notarized digest is `statementHash`. The
SBOM is hashed, not interpreted: produce it with whatever you use (`npm sbom --sbom-format cyclonedx`, `syft`,
`cyclonedx-maven`) and hand the same file to `verify`.

## Rebuild: the artifact is what the source produces (1.1.0)

Digests prove the file is the file that was attested. They do not prove it came from the commit the statement names.
For npm packages the tool closes that gap:

```
node pos.mjs pack-npm --source-path sdk --out-dir dist                  # npm pack of the COMMITTED tree, not the working copy
node pos.mjs attest --out attestation.json --source-path sdk --build npm-pack dist/aere-cloud-1.2.1.tgz
node pos.mjs verify attestation.json --rebuild-from /path/to/any/clone dist/aere-cloud-1.2.1.tgz
```

`--source-path` adds to `source` the directory (`path`), its git **tree** hash at HEAD (`tree`) and whether that
directory had uncommitted changes (`pathDirty`); `--build npm-pack` records the build and the npm version.
`pack-npm` writes the committed bytes straight from the object store (no checkout conversion) and packs those, so the
artifact is a function of the tree alone: measured here, a working-copy pack of the same commit gave another digest
because a checkout with `core.autocrlf=true` had turned `LICENSE` into CRLF. `verify --rebuild-from` takes a clone the
**verifier** chose, requires `<commit>:<path>` to be the attested tree, packs it again and requires the attested digest
byte for byte. An artifact built from anything else passes on digests and fails the rebuild, which is the point.
Measured: same tree, same npm version, same machine. Not measured: another operating system or another npm major; the
npm version is in the statement so a mismatch can be told apart from tampering.

In the development repository a script runs this on our own packages (`@aere/cloud`, `@aere/pq-sign`), with a CycloneDX SBOM
and two negative controls. Those attestations are unsigned and not notarized until a release signing key exists, they say so
themselves, and they are not part of the public copy of this tool (they name the development repository as their source).

## AI models: provenance of the weights (1.2.0)

```
node pos.mjs model-bom --model-dir ./my-model --out mlbom.json --name my-model --version 1.0 \
                       --task text-generation --dataset train=./train.jsonl
node pos.mjs attest --base ./my-model --sbom mlbom.json --out attestation.json ./my-model/*  ./my-model/tokenizer/*
node pos.mjs verify attestation.json --base ./my-model mlbom.json ./my-model/*  ./my-model/tokenizer/*
```

`model-bom` writes a CycloneDX 1.6 ML-BOM: a `machine-learning-model` component (architecture and family read from
`config.json` when it exists, nothing guessed), every file of the directory with its SHA-256 and size (hidden folders
such as caches are left out), the datasets you name with theirs, and a manifest digest: the SHA-256 of the lines
`<relative path>\t<sha256>\t<bytes>` sorted by path, which changes when any file is added, removed or touched.
`--base` names artifacts by their path relative to the model directory, because a model often carries two
`config.json`; a verification without `--base` of such an attestation fails and says why. Files over 64 MiB are
hashed in a stream, so multi-gigabyte weights never have to fit in memory. A missing file fails the verification: an
incomplete model is not a verified model.

What it proves: these exact bytes are the model you attested, with the datasets and the time you recorded, and (with a
Cloud key) the statement was notarized on chain 2800 with post-quantum finality. What it does not prove: how the model
was trained, that the datasets are what their names say, or anything about its behaviour.

## GitHub Actions

```yaml
- run: npm ci && npm run build
- run: npm sbom --sbom-format cyclonedx > sbom.json
- run: |
    printf '%s' "${{ secrets.AERE_CLOUD_KEY }}" > .aere-key
    node tools/proof-of-software/pos.mjs attest --out attestation.json \
      --name ${{ github.event.repository.name }} --version ${{ github.ref_name }} \
      --sbom sbom.json --keys <(printf '%s' "${{ secrets.AERE_POS_KEYS }}") --cloud-key-file .aere-key dist/*
    rm -f .aere-key    
- uses: actions/upload-artifact@v4
  with: { name: attestation, path: attestation.json }
```

Publish `attestation.json` next to the release. A consumer runs `verify` with the downloaded files and, with any Aere
Cloud key, reads the chain's answer: notarized, first seen in block N, covered by anchor M with K post-quantum seals.

## Why this and not only Sigstore / SLSA provenance

Those bind a build to an identity with classical signatures and a transparency log operated by one party. This binds
it with a hybrid signature that stays valid if either scheme falls, and with a first-seen time whose rewriting would
require forging a post-quantum validator certificate. Use both: the attestation file is small enough to sit next to a
SLSA provenance.

## Builder identity: the developer credential (1.3.0)

A signature says "these keys signed"; it does not say who holds them. A **developer credential** is an organization's statement,
signed with the organization's own hybrid keys, that names a person and binds that name to the person's signing keys for a period.

```
node pos.mjs keygen --out org.json                           # the organization's keys (the issuer); keep them offline
node pos.mjs pubkey --keys org.json --out org.pub.json       # the trust root you hand to whoever verifies
node pos.mjs pubkey --keys dev.json --out dev.pub.json       # the developer's public keys
node pos.mjs credential issue --issuer-keys org.json --issuer-name "Example Org" \
     --subject-pub dev.pub.json --subject-name "Ana Dev" --valid-days 365 --out cred.json
node pos.mjs attest --keys dev.json --credential cred.json --out attestation.json dist/app.tgz
node pos.mjs verify attestation.json --trust-issuer org.pub.json [--revocations rev.json] dist/app.tgz
node pos.mjs credential revoke --issuer-keys org.json --credential cred.json --at 2026-10-01T00:00:00Z --out rev.json
```

`attest --credential` puts the credential's hash into the statement (`builder.credential`), so the statement signature also
covers "built under this credential"; it refuses a credential that names other keys than `--keys`. `verify` then checks that the
attestation carries that credential, that it is signed by the issuer it names, that the issuer is **the trust root you gave**
(never the one the attestation carries; without `--trust-issuer` the issuer is reported as not judged), that the credential names
exactly the keys that signed the statement, that the time falls in its validity, and that no revocation signed by the issuer covers
that time. The time is the chain's first-seen time when the on-chain proof was read, otherwise the builder's own `createdAt`, and
the check says which one it used: a builder who backdates `createdAt` under an expired credential is caught by the chain's time.
The declared `createdAt` can only accuse (1.4.0): outside the validity or after a revocation it fails the check, but inside them it
is reported as not judged, because whoever holds the keys chooses it. Until 1.4.0 an attestation signed with the keys of a revoked
credential and dated before the revocation passed "not revoked"; notarize attestations for the time to count.
A revocation you were not handed cannot be seen, and verification says so.

```
node test/credential.test.mjs               # 12/12: each check with its negative pair, the chain time over the declared one, a
                                            # backdated attestation under a revoked credential (not judged; caught on chain time), the CLI
node test/credential-control-negativ.mjs    # on a copy, each of 7 guards removed -> its own test turns red
node test/semnatar.test.mjs                 # 7/7: the signer named, --signer against another's keys -> INVALID, unsigned -> INVALID
node test/semnatar-control-negativ.mjs      # on a copy, each of 4 guards removed -> its own test turns red
# in the development repository all of the above also run as one suite, tied to its findings registry
```

## The SBOM is what the committed lockfile says (1.3.0)

`npm sbom --package-lock-only` writes a random serial number and a timestamp on every run, so the attested SBOM can never be
reproduced byte for byte, and until 1.3.0 an SBOM edited by hand (a component dropped, a version or an integrity hash changed) and
attested again passed on its digest. `verify --rebuild-from <clone>`, when you also hand it the attested SBOM, now re-derives the
SBOM from `<commit>:<path>/package-lock.json` in the clone YOU chose and compares what the two SAY: the root, every component by purl
with its hashes and scope, and the dependency graph. Same content with another serial number passes; different content fails. A
committed tree without `package-lock.json` cannot re-derive anything, and verification says so instead of passing it.

```
node test/sbom.test.mjs               # 8/8: two runs differ in bytes, not in content; a component dropped, a version changed, an
                                      # integrity hash changed -> caught; SBOM not handed / no committed lockfile -> reported, not passed
node test/sbom-control-negativ.mjs    # on a copy, 3 guards removed -> their own tests turn red
```

## A Go module's SBOM, from the committed go.sum (1.4.0)

```
node pos.mjs sbom-go --source-path ./mymod --version v1.4.2 --out sbom.cdx.json      # from the COMMITTED go.mod and go.sum
node pos.mjs attest --source-path ./mymod --sbom sbom.cdx.json --name mymod --version v1.4.2 --out attestation.json dist/*
node pos.mjs verify attestation.json --rebuild-from <a clone you chose> dist/* sbom.cdx.json
```

`sbom-go` writes a CycloneDX 1.6 SBOM from `<commit>:<path>/go.mod` and `go.sum`, with no Go toolchain and no network, and the same
files always give the same bytes (no timestamp; the serial number is derived from the content). Its components are the modules whose
content `go.sum` pins, each with its `pkg:golang` purl and Go's `h1:` hash as the property `aere:go-sum-h1`; the root is the module
named in `go.mod`. The `h1:` hash is a SHA-256 over a summary of the module's files, not over an archive, so it is not written as a
CycloneDX SHA-256 hash of the component. Modules pinned only by their `go.mod` line (consulted while resolving the module graph, their
code not downloaded) are counted in `aere:go-sum-go-mod-only`, not listed. What it does not say: `go.sum` can keep entries left over
from an older version until `go mod tidy`, so the SBOM says what is pinned, not what was compiled.

`verify --rebuild-from` re-derives it from the committed tree and compares what the two say (root, every module with its version and
`h1:`). An SBOM edited by hand and attested again passes on its digest and fails here. This tool rebuilds artifacts only with `npm
pack`; for a Go binary the rebuild of the artifacts is reported as not attempted (absent, not wrong), while the source tree and the
SBOM are still judged.

```
node test/sbom-go.test.mjs              # 13/13 on real go.mod/go.sum files (ours, and golang/mock v1.6.0 with 23 go.mod-only entries):
                                        # deterministic, h1 equal to what Go recorded when it downloaded the module (when the module is
                                        # in the local Go module cache; skipped otherwise), a module dropped, a version, an h1, the root
                                        # changed -> caught; no committed go.sum -> reported, not passed
node test/sbom-go-control-negativ.mjs   # on a copy, 7 guards removed -> their own tests turn red
```

Java (Maven, Gradle) and .NET lockfiles: not done; the machine these were built and measured on has neither toolchain to produce
real lockfiles to test against, and a parser tested only on files written by hand would test its own assumptions.