Audit release licenses and provenance (#104)

docs/release-provenance.md

@@ -0,0 +1,99 @@
+# Release license, provenance, and asset audit
+
+MetaCrate treats every source-derived file, generated output, fixture, bundled
+asset, locked Rust package, and native component as release input. The
+canonical hand-reviewed policy is
+[`ci/provenance-policy.json`](../ci/provenance-policy.json); the native Rust
+`metacrate-ci-matrix` tool turns that policy and `Cargo.lock` into deterministic
+notices and distribution manifests.
+
+## Ownership model
+
+Files authored for MetaCrate are BSD-3-Clause under
+[`LICENSE.md`](../LICENSE.md). That license retains the BSD attribution for the
+pinned LibreMetaverse public API, behavior, translated tests, fixtures, and
+algorithms. The exact upstream repository and commit are recorded in the
+policy, source-generator inventory, API ledgers, parity ledgers, and
+distribution manifest. The pinned upstream BSD text is shipped verbatim as
+[`licenses/LibreMetaverse-BSD-3-Clause.txt`](../licenses/LibreMetaverse-BSD-3-Clause.txt)
+and verified against its recorded source hash.
+
+The audit requires three independently generated provenance ledgers—compiled
+public API, upstream program sources, and upstream tests/fixtures—to identify
+that same pinned commit. This binds rewritten code and documentation mappings
+to the BSD source attribution instead of relying on filename conventions.
+
+Exceptions to the default project-owned classification must be explicit
+materials in the policy. The audit recursively inventories every non-README
+file below `codegen/inputs`, `tests/fixtures`, and `fuzz/corpus`, rejects a
+missing or extra entry, validates its SHA-256, origin, license, and distribution
+class, and scans the complete release file list for binary/asset extensions.
+An image, mesh, audio file, native library, or viewer asset therefore cannot be
+added as an unreviewed opaque file.
+
+The seven required inputs copied from LibreMetaverse's `linden/` directory are
+CC-BY-SA-3.0, not BSD-3-Clause. They remain unmodified, are attributed to
+Linden Lab in [`NOTICE.md`](../NOTICE.md), and carry their exact hashes and
+license through the generated Rust headers. MetaCrate deliberately excludes
+the neighboring Linden textures, meshes, animations, gestures, clothing, body
+parts, and viewer binaries. The legal-code URI and hash of the upstream legal
+code are recorded in
+[`licenses/CC-BY-SA-3.0-NOTICE.md`](../licenses/CC-BY-SA-3.0-NOTICE.md).
+
+## Locked dependency notices
+
+`provenance-report` obtains the complete all-feature package graph from
+`cargo metadata --locked`, joins every registry package to its crates.io
+checksum in `Cargo.lock`, and reads license, copyright, copying, and notice
+files from the downloaded crate archives. Identical texts are stored once in
+the consolidated notice while every package records the filenames and hashes
+that apply to it. When a split package omits a repository-wide license file,
+the report uses a matching sibling package from the same repository. If an
+archive supplies no usable notice at all, the report emits a visible generated
+notice containing its declared SPDX expression, authors, repository, and SPDX
+legal-text links; packages are never silently omitted.
+
+The generated artifacts are:
+
+- [`release/DEPENDENCY-LICENSES.json`](../release/DEPENDENCY-LICENSES.json):
+  locked package, checksum, license-expression, repository, and notice hashes;
+- [`release/THIRD-PARTY-NOTICES.md`](../release/THIRD-PARTY-NOTICES.md): package
+  index and the complete deduplicated notice/license texts;
+- [`release/NATIVE-LICENSES.md`](../release/NATIVE-LICENSES.md): native version,
+  license, linkage, bundling, source, and downstream obligation review;
+- [`release/DISTRIBUTION-MANIFEST.json`](../release/DISTRIBUTION-MANIFEST.json):
+  every source file's byte length and SHA-256, all governed materials and
+  generated outputs, the hashes of generated notice artifacts, and the exact
+  notice set required beside source and binary distributions.
+
+OpenJPEG, Opus, and ALSA are system libraries and are not redistributed by
+MetaCrate. Skia and the optional aoTuV/Lancer Vorbis/libogg sources can enter a
+binary through feature builds, so their package notices are included in the
+locked third-party notice. A downstream distributor that supplies a system
+library must add the exact notice belonging to the native package it ships.
+
+## Reproduction and gate
+
+Fetch the immutable locked crate archives, regenerate, then audit:
+
+```sh
+cargo fetch --locked
+cargo run --locked -p metacrate-ci-matrix -- provenance-report
+cargo run --locked -p metacrate-ci-matrix -- \
+  provenance-audit --evidence /tmp/metacrate-provenance-audit.json
+```
+
+The audit regenerates every report in memory and requires byte-for-byte
+identity with the checked-in files. Its JSON evidence records the source,
+material, generated-output, dependency, unique-notice, and native-component
+counts plus every generated report hash. Evidence creation is exclusive and
+never overwrites an earlier run. A reviewed representative result is retained
+at [`ci/evidence/provenance-audit.json`](../ci/evidence/provenance-audit.json);
+CI writes a fresh result into its uploaded artifact directory.
+
+The Gitea supply-chain job runs only on `ubuntu-latest`, fetches the locked
+archives, runs this audit, then keeps the existing `cargo-deny` and
+`cargo-machete` gates. It runs for every source change because the distribution
+manifest intentionally covers the whole release source tree. Live-grid
+credentials, `.env`, network services, fuzz runners, and physical devices are
+not used by this deterministic issue gate.