tro-utils 0.5.2__tar.gz → 0.5.4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. {tro_utils-0.5.2 → tro_utils-0.5.4}/.github/workflows/release.yml +6 -6
  2. {tro_utils-0.5.2 → tro_utils-0.5.4}/.github/workflows/test.yml +21 -5
  3. tro_utils-0.5.4/MANIFEST.in +8 -0
  4. {tro_utils-0.5.2 → tro_utils-0.5.4}/Makefile +0 -4
  5. tro_utils-0.5.4/PKG-INFO +222 -0
  6. {tro_utils-0.5.2 → tro_utils-0.5.4}/README.md +7 -3
  7. {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/conf.py +35 -29
  8. {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/contributing.md +8 -10
  9. {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/installation.md +1 -1
  10. {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/usage.md +97 -2
  11. {tro_utils-0.5.2 → tro_utils-0.5.4}/pyproject.toml +15 -10
  12. {tro_utils-0.5.2 → tro_utils-0.5.4}/setup.cfg +0 -3
  13. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/conftest.py +3 -1
  14. tro_utils-0.5.4/tests/data/tsa/freetsa-2025.payload +4 -0
  15. tro_utils-0.5.4/tests/data/tsa/freetsa-2025.tsr +0 -0
  16. tro_utils-0.5.4/tests/data/tsa/freetsa-2026.payload +4 -0
  17. tro_utils-0.5.4/tests/data/tsa/freetsa-2026.tsr +0 -0
  18. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_cli.py +247 -0
  19. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_tro_performances.py +54 -0
  20. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_tro_reporting.py +90 -4
  21. tro_utils-0.5.4/tests/test_tro_signature_verification.py +871 -0
  22. tro_utils-0.5.4/tests/test_tro_timestamping.py +353 -0
  23. tro_utils-0.5.4/tests/test_trs_keys.py +207 -0
  24. tro_utils-0.5.4/tests/test_tsa.py +177 -0
  25. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/_version.py +3 -3
  26. tro_utils-0.5.4/tro_utils/certs/freetsa-root.pem +52 -0
  27. tro_utils-0.5.4/tro_utils/certs/freetsa-tsa.pem +100 -0
  28. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/cli.py +250 -25
  29. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/default.jinja2 +12 -1
  30. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/tro.py +3 -1
  31. tro_utils-0.5.4/tro_utils/static/trace-logo.png +0 -0
  32. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/tro_utils.py +320 -53
  33. tro_utils-0.5.4/tro_utils/trs_keys.py +251 -0
  34. tro_utils-0.5.4/tro_utils/tsa.py +149 -0
  35. tro_utils-0.5.4/tro_utils.egg-info/PKG-INFO +222 -0
  36. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils.egg-info/SOURCES.txt +13 -4
  37. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils.egg-info/requires.txt +3 -2
  38. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils.egg-info/scm_file_list.json +13 -4
  39. tro_utils-0.5.4/tro_utils.egg-info/scm_version.json +8 -0
  40. tro_utils-0.5.2/.travis.yml +0 -28
  41. tro_utils-0.5.2/MANIFEST.in +0 -11
  42. tro_utils-0.5.2/PKG-INFO +0 -75
  43. tro_utils-0.5.2/requirements_dev.txt +0 -13
  44. tro_utils-0.5.2/tests/test_tro_timestamping.py +0 -167
  45. tro_utils-0.5.2/tox.ini +0 -26
  46. tro_utils-0.5.2/tro_utils.egg-info/PKG-INFO +0 -75
  47. tro_utils-0.5.2/tro_utils.egg-info/scm_version.json +0 -8
  48. {tro_utils-0.5.2 → tro_utils-0.5.4}/.coveragerc +0 -0
  49. {tro_utils-0.5.2 → tro_utils-0.5.4}/.editorconfig +0 -0
  50. {tro_utils-0.5.2 → tro_utils-0.5.4}/.github/ISSUE_TEMPLATE.md +0 -0
  51. {tro_utils-0.5.2 → tro_utils-0.5.4}/.gitignore +0 -0
  52. {tro_utils-0.5.2 → tro_utils-0.5.4}/.readthedocs.yaml +0 -0
  53. {tro_utils-0.5.2 → tro_utils-0.5.4}/LICENSE +0 -0
  54. {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/Makefile +0 -0
  55. {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/authors.md +0 -0
  56. {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/history.md +0 -0
  57. {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/index.md +0 -0
  58. {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/make.bat +0 -0
  59. {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/readme.md +0 -0
  60. {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/requirements.txt +0 -0
  61. {tro_utils-0.5.2 → tro_utils-0.5.4}/pytest.ini +0 -0
  62. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/__init__.py +0 -0
  63. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/helpers.py +0 -0
  64. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_arrangement_determinism.py +0 -0
  65. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_extra_context.py +0 -0
  66. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_agent.py +0 -0
  67. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_artifact_arrangement.py +0 -0
  68. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_artifact_composition.py +0 -0
  69. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_artifact_location.py +0 -0
  70. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_composition_fingerprint.py +0 -0
  71. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_hash_value.py +0 -0
  72. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_performance.py +0 -0
  73. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_research_artifact.py +0 -0
  74. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_transparent_research_object.py +0 -0
  75. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_trs.py +0 -0
  76. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_tsa.py +0 -0
  77. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_replication_package_model.py +0 -0
  78. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_replication_package_verification.py +0 -0
  79. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_tro_arrangements.py +0 -0
  80. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_tro_creation.py +0 -0
  81. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_tro_hashing.py +0 -0
  82. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_tro_save_load.py +0 -0
  83. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_tro_signing.py +0 -0
  84. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_tro_utility_methods.py +0 -0
  85. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_tro_workflow.py +0 -0
  86. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_trs_identifier.py +0 -0
  87. {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_version.py +0 -0
  88. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/__init__.py +0 -0
  89. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/__init__.py +0 -0
  90. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/_base.py +0 -0
  91. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/agent.py +0 -0
  92. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/arrangement.py +0 -0
  93. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/artifact.py +0 -0
  94. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/attribute.py +0 -0
  95. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/composition.py +0 -0
  96. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/hash_value.py +0 -0
  97. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/performance.py +0 -0
  98. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/trs.py +0 -0
  99. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/tsa.py +0 -0
  100. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/replication_package.py +0 -0
  101. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils.egg-info/dependency_links.txt +0 -0
  102. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils.egg-info/entry_points.txt +0 -0
  103. {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils.egg-info/top_level.txt +0 -0
@@ -8,9 +8,9 @@ jobs:
8
8
  runs-on: ubuntu-latest
9
9
 
10
10
  steps:
11
- - uses: actions/checkout@v4
11
+ - uses: actions/checkout@v7
12
12
  - name: Set up Python
13
- uses: actions/setup-python@v5
13
+ uses: actions/setup-python@v7
14
14
  with:
15
15
  python-version: "3.x"
16
16
  - name: Install pypa/build
@@ -22,7 +22,7 @@ jobs:
22
22
  - name: Build a binary wheel and a source tarball
23
23
  run: python3 -m build
24
24
  - name: Store the distribution packages
25
- uses: actions/upload-artifact@v4
25
+ uses: actions/upload-artifact@v7
26
26
  with:
27
27
  name: python-package-distributions
28
28
  path: dist/
@@ -42,7 +42,7 @@ jobs:
42
42
 
43
43
  steps:
44
44
  - name: Download all the dists
45
- uses: actions/download-artifact@v4
45
+ uses: actions/download-artifact@v8
46
46
  with:
47
47
  name: python-package-distributions
48
48
  path: dist/
@@ -63,12 +63,12 @@ jobs:
63
63
 
64
64
  steps:
65
65
  - name: Download all the dists
66
- uses: actions/download-artifact@v4
66
+ uses: actions/download-artifact@v8
67
67
  with:
68
68
  name: python-package-distributions
69
69
  path: dist/
70
70
  - name: Sign the dists with Sigstore
71
- uses: sigstore/gh-action-sigstore-python@v3.0.0
71
+ uses: sigstore/gh-action-sigstore-python@v3.5.0
72
72
  with:
73
73
  inputs: >-
74
74
  ./dist/*.tar.gz
@@ -7,17 +7,33 @@ on:
7
7
  branches: [main]
8
8
 
9
9
  jobs:
10
+ lint:
11
+ runs-on: ubuntu-latest
12
+ steps:
13
+ - uses: actions/checkout@v7
14
+
15
+ - name: Set up Python
16
+ uses: actions/setup-python@v7
17
+ with:
18
+ python-version: '3.14'
19
+
20
+ - name: Check formatting with black
21
+ run: |
22
+ python -m pip install --upgrade pip
23
+ pip install "black==26.3.1"
24
+ black --check --diff .
25
+
10
26
  test:
11
27
  runs-on: ubuntu-latest
12
28
  strategy:
13
29
  matrix:
14
- python-version: ['3.10', '3.11', '3.12']
30
+ python-version: ['3.12', '3.13', '3.14', '3.15']
15
31
 
16
32
  steps:
17
- - uses: actions/checkout@v4
33
+ - uses: actions/checkout@v7
18
34
 
19
35
  - name: Set up Python ${{ matrix.python-version }}
20
- uses: actions/setup-python@v5
36
+ uses: actions/setup-python@v7
21
37
  with:
22
38
  python-version: ${{ matrix.python-version }}
23
39
 
@@ -27,7 +43,7 @@ jobs:
27
43
  sudo apt-get install -y gnupg graphviz libmagic1
28
44
 
29
45
  - name: Cache pip dependencies
30
- uses: actions/cache@v4
46
+ uses: actions/cache@v6
31
47
  with:
32
48
  path: ~/.cache/pip
33
49
  key: ${{ runner.os }}-py${{ matrix.python-version }}-pip-${{ hashFiles('**/pyproject.toml') }}
@@ -45,7 +61,7 @@ jobs:
45
61
 
46
62
  - name: Upload Coverage to Codecov
47
63
  if: matrix.python-version == '3.12'
48
- uses: codecov/codecov-action@v5
64
+ uses: codecov/codecov-action@v7
49
65
  with:
50
66
  token: ${{ secrets.CODECOV_TOKEN }}
51
67
  fail_ci_if_error: false
@@ -0,0 +1,8 @@
1
+ include LICENSE
2
+ include README.md
3
+
4
+ recursive-include tests *
5
+ recursive-exclude * __pycache__
6
+ recursive-exclude * *.py[co]
7
+
8
+ recursive-include docs *.md conf.py Makefile make.bat requirements.txt
@@ -42,7 +42,6 @@ clean-pyc: ## remove Python file artifacts
42
42
  find . -name '__pycache__' -exec rm -fr {} +
43
43
 
44
44
  clean-test: ## remove test and coverage artifacts
45
- rm -fr .tox/
46
45
  rm -f .coverage
47
46
  rm -fr htmlcov/
48
47
  rm -fr .pytest_cache
@@ -55,9 +54,6 @@ lint: lint/flake8 ## check style
55
54
  test: ## run tests quickly with the default Python
56
55
  pytest
57
56
 
58
- test-all: ## run tests on every Python version with tox
59
- tox
60
-
61
57
  coverage: ## check code coverage quickly with the default Python
62
58
  coverage run --source tro_utils -m pytest
63
59
  coverage report -m
@@ -0,0 +1,222 @@
1
+ Metadata-Version: 2.4
2
+ Name: tro-utils
3
+ Version: 0.5.4
4
+ Summary: Utilities for creating, editing and interacting with TROs
5
+ Author-email: Kacper Kowalik <xarthisius.kk@gmail.com>, Craig Willis <willis8@illinois.edu>
6
+ Maintainer-email: Kacper Kowalik <xarthisius.kk@gmail.com>
7
+ License-Expression: BSD-3-Clause
8
+ Classifier: Development Status :: 3 - Alpha
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Topic :: Software Development :: Libraries
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Classifier: Programming Language :: Python :: 3.13
14
+ Classifier: Programming Language :: Python :: 3.14
15
+ Classifier: Programming Language :: Python :: 3.15
16
+ Requires-Python: >=3.12
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Requires-Dist: Click>=7.0
20
+ Requires-Dist: jinja2
21
+ Requires-Dist: packaging
22
+ Requires-Dist: python-gnupg
23
+ Requires-Dist: python-magic
24
+ Requires-Dist: pyasn1
25
+ Requires-Dist: pyyaml
26
+ Requires-Dist: rfc3161ng
27
+ Requires-Dist: graphviz
28
+ Requires-Dist: rich
29
+ Provides-Extra: test
30
+ Requires-Dist: pytest>=6.2.4; extra == "test"
31
+ Requires-Dist: pytest-cov>=7.0.0; extra == "test"
32
+ Requires-Dist: coverage>=7.0; extra == "test"
33
+ Provides-Extra: dev
34
+ Requires-Dist: pytest>=6.2.4; extra == "dev"
35
+ Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
36
+ Requires-Dist: coverage>=7.0; extra == "dev"
37
+ Requires-Dist: setuptools-scm; extra == "dev"
38
+ Requires-Dist: black==26.3.1; extra == "dev"
39
+ Requires-Dist: wheel>=0.33.6; extra == "dev"
40
+ Requires-Dist: watchdog>=0.9.0; extra == "dev"
41
+ Requires-Dist: flake8>=3.7.8; extra == "dev"
42
+ Requires-Dist: Sphinx>=1.8.5; extra == "dev"
43
+ Requires-Dist: twine>=1.14.0; extra == "dev"
44
+ Dynamic: license-file
45
+
46
+ # Transparent Research Object utils
47
+
48
+ [![PyPI version](https://img.shields.io/pypi/v/tro_utils.svg)](https://pypi.python.org/pypi/tro-utils)
49
+ [![Zenodo](https://zenodo.org/badge/765298086.svg)](https://zenodo.org/doi/10.5281/zenodo.11130420)
50
+ [![Documentation Status](https://readthedocs.org/projects/tro-utils/badge/?version=latest)](https://tro-utils.readthedocs.io/en/latest/?version=latest)
51
+
52
+ This package provides a set of utilities for working with Transparent Research Objects (TROs). It is designed to be used in conjunction with the [TRO specification](https://transparency-certified.github.io/trace-specification/docs/specifications/tro/0.1/index.html).
53
+
54
+ **📚 [Read the Full Documentation](https://tro-utils.readthedocs.io/en/latest/?version=latest)**
55
+
56
+ It uses the `Click` library to define commands and options. Here's a summary of the main features:
57
+
58
+ 1. **Global Options**: The script defines several global options that can be used with any command, such as `--declaration`, `--profile`, `--gpg-fingerprint`, `--gpg-passphrase`, `--tro-creator`, `--tro-creator-type`, `--tro-name`, and `--tro-description`. These options can be used to specify various parameters for the TRO.
59
+
60
+ 2. **Commands**: The script defines several commands, each with its own set of options and arguments. The commands include:
61
+
62
+ - `verify-timestamp`: Verifies the RFC 3161 timestamp on the TRO.
63
+
64
+ - `verify-signature`: Verifies the TRS's GPG signature on the TRO against your keyring. Import the TRS's public key from a source you trust first, or pass the key file the TRS publishes with `--keyring`; `--fingerprint` requires a given signing key. `--trs-keys` checks the key against a list of the TRS's keys with their validity dates, at the time of the TRO's timestamp. `--use-embedded-key` alone only checks that the TRO is self-consistent.
65
+
66
+ - `verify-package`: Verifies a replication package (directory or `.zip`) against the hashes stored in an arrangement.
67
+
68
+ - `arrangement`: Manages arrangements in the TRO. An arrangement is a snapshot of where files sat at one point in time; adding one records a location per file and registers any file the TRO has not seen before in the composition. Subcommands: `add` (scans a directory, or replays a pre-computed snapshot with `--from-snapshot`), `snapshot` (computes a reusable snapshot file from a directory without touching a TRO, so an expensive scan can be done once and shared across runs — see [Arrangement snapshots](https://tro-utils.readthedocs.io/en/latest/usage.html#arrangement-snapshots)) and `list` (lists available arrangements in the TRO).
69
+
70
+ - `composition`: Manages compositions in the TRO. It has a subcommand `info` that gets info about the current composition.
71
+
72
+ - `performance`: Manages performances in the TRO. Subcommands: `add` (adds a performance to the TRO) and `list` (lists the performances recorded in the TRO; `-v` also shows start/end times, accessed and contributed arrangements with their mount paths, and performance attributes).
73
+
74
+ - `sign`: Signs the TRO. This records the public half of the signing key as `trov:publicKey` in the declaration, saves the declaration, and then produces the signature and the RFC 3161 timestamp over it.
75
+
76
+ - `report`: Generates a report of the TRO.
77
+
78
+ 3. **TRO Interaction**: The script interacts with the TRO using the `TRO` class from the `tro_utils` module. It uses this class to create a new TRO, add arrangements and performances to the TRO, verify the TRO, and generate a report of the TRO.
79
+
80
+ 4. **GPG is only used for signing**: `--gpg-fingerprint` and `--gpg-passphrase` are recorded but never resolved against a keyring until `sign` runs. Building, inspecting, reporting on and verifying a TRO therefore need no GPG key — and no `gpg` binary at all. As a consequence, `trov:publicKey` appears in the declaration only from `sign` onwards, and is by construction the public half of the key that produced the signature (a value supplied by a TRS profile acts as a default until then).
81
+
82
+ 5. **The TRS is identified by a stable IRI**: the `@id` of the TRS a declaration defines must be an absolute IRI, or a compact IRI whose prefix is not `trov`, so that the same TRS carries the same identifier in every document that mentions it. A bare `"trs"` does not qualify — it resolves against whichever document happens to contain it. The identifier is taken from the profile's `@id`, else its `schema:url`, else a placeholder saying the TRS is unidentified; a non-conforming `@id` is reported rather than quietly replaced, and a declaration carrying one cannot be saved. Whatever the TRS ends up with is also what `trov:wasConductedBy` and the default `schema:creator` reference.
83
+
84
+ 6. **Capabilities are named by an IRI too**: a capability belongs to the TRS, not to one declaration, so the `@id` a profile gives it — and therefore the `trov:warrantedBy` that each performance attribute points at — must be a compact or absolute IRI. The usual identifier is the capability's own term, so a profile may simply omit `@id` and let the `@type` serve. Unlike the TRS `@id`, the `trov` prefix is allowed here. A relative id such as `trs/capability/1` is reported rather than quietly rewritten, and a declaration carrying one cannot be saved.
85
+
86
+ 7. **`schema:creator` is a person or an organization**: it serialises as a `schema:Person` or `schema:Organization` node rather than a bare name, including for defaults. `--tro-creator` supplies the name and `--tro-creator-type` says which of the two it is (default: `organization`); with neither given, the TRO credits the TRS that assembled it, by the TRS's own `@id` and `schema:name`.
87
+
88
+ 8. **Timestamps are timezone-aware**: `trov:startedAtTime`, `trov:endedAtTime` and `schema:dateCreated` always carry a UTC offset. A value given without one — `--start 2024-03-01T09:22:01`, or an offset-less timestamp in an older declaration — is read as local wall-clock time and stamped with the local offset, preserving the instant rather than relabelling it. Pass an explicit offset when the recording host and the reading host may sit in different zones.
89
+
90
+ 9. **Declarations are reproducible**: artifacts and their locations are ordered by path, not by the order the filesystem happened to report them, so scanning the same tree twice — on two machines, or on two filesystems — yields the same artifact `@id`s and byte-identical output.
91
+
92
+ ## Installation
93
+
94
+ ### Pre-requisites
95
+ Before you begin, you need to have the following installed on your system:
96
+
97
+ - GPG (only needed to `sign` a TRO)
98
+ - OpenSSL
99
+ - Python 3.8+
100
+
101
+ You can do this by running the following commands:
102
+
103
+ ```bash
104
+ $ sudo apt-get install gnupg openssl python3 python3-pip # on Debian/Ubuntu
105
+ $ brew install gnupg openssl python3 # on macOS with Homebrew
106
+ ```
107
+
108
+ If you only consume TROs — building, inspecting, reporting or `verify-timestamp` —
109
+ GPG is not required; OpenSSL still is. `verify-signature` needs GPG.
110
+
111
+ ## Example Usage
112
+
113
+ Assumes that:
114
+
115
+ * this package is installed
116
+ * your GPG key is present (needed for the `sign` step only)
117
+ * `trs.jsonld` is available and defines TRS capabilities (see below for an example).
118
+ The TRS is a `schema:Organization`, so it is described with schema.org
119
+ properties — `schema:name`, `schema:description`, `schema:url`, `schema:email`,
120
+ `schema:owner` — rather than `trov:` terms, which the TROV vocabulary does not
121
+ define for it.
122
+
123
+ Example workflow:
124
+
125
+ ```bash
126
+ $ cd /tmp
127
+ $ cat trs.jsonld
128
+ {
129
+ "@id": "http://127.0.0.1/",
130
+ "rdfs:comment": "TRS that can monitor netowork accesses or provide Internet isolation",
131
+ "trov:hasCapability": [
132
+ {
133
+ "@id": "trov:CanRecordInternetAccess",
134
+ "@type": "trov:CanRecordInternetAccess"
135
+ },
136
+ {
137
+ "@id": "trov:CanProvideInternetIsolation",
138
+ "@type": "trov:CanProvideInternetIsolation"
139
+ }
140
+ ],
141
+ "schema:owner": {
142
+ "@id": "https://orcid.org/0000-0003-1709-3744",
143
+ "@type": "schema:Person",
144
+ "schema:name": "Kacper Kowalik"
145
+ },
146
+ "schema:description": "My local system",
147
+ "schema:email": "root@dev.null",
148
+ "schema:url": "http://127.0.0.1/",
149
+ "schema:name": "shakuras"
150
+ }
151
+ $ export GPG_FINGERPRINT=...
152
+ $ export GPG_PASSPHRASE=...
153
+ $ git clone https://github.com/transparency-certified/sample-trace-workflow /tmp/sample
154
+ # It's sufficient to pass the profile only once
155
+ $ tro-utils --declaration sample_tro.jsonld --profile trs.jsonld arrangement add /tmp/sample \
156
+ -m "Before executing workflow" -i .git
157
+ Loading profile from trs.jsonld
158
+ $ tro-utils --declaration sample_tro.jsonld arrangement list
159
+ Arrangement(id=arrangement/0): Before executing workflow
160
+ $ pushd /tmp/sample && \
161
+ docker build -t xarthisius/sample . && \
162
+ ./run_locally.sh latest xarthisius && \
163
+ popd
164
+ $ tro-utils --declaration sample_tro.jsonld arrangement add /tmp/sample \
165
+ -m "After executing workflow" -i .git
166
+ $ tro-utils --declaration sample_tro.jsonld arrangement list
167
+ Arrangement(id=arrangement/0): Before executing workflow
168
+ Arrangement(id=arrangement/1): After executing workflow
169
+ $ tro-utils --declaration sample_tro.jsonld performance add \
170
+ -m "My magic workflow" \
171
+ -s 2024-03-01T09:22:01+00:00 \
172
+ -e 2024-03-02T10:00:11+00:00 \
173
+ -a trov:InternetIsolation \
174
+ -a trov:InternetAccessRecording \
175
+ -A arrangement/0 \
176
+ -M arrangement/1
177
+ $ tro-utils --declaration sample_tro.jsonld performance list
178
+ Performance(id=trp/0): My magic workflow
179
+ $ tro-utils --declaration sample_tro.jsonld sign
180
+ $ tro-utils --declaration sample_tro.jsonld verify-timestamp
181
+ ...
182
+ Verification: OK
183
+ $ curl -LO https://raw.githubusercontent.com/craig-willis/trace-report/main/templates/tro.md.jinja2
184
+ $ tro-utils --declaration sample_tro.jsonld report --template tro.md.jinja2 -o report.md
185
+ ```
186
+
187
+ ## Upgrading to 0.5.0
188
+
189
+ Declarations written by 0.4.x still load, but three things changed in what gets
190
+ written, and a fourth in what is accepted:
191
+
192
+ - **A TRS profile's `@id` is now honoured.** 0.4.x discarded it and wrote a bare
193
+ `"trs"`; a profile that already declared a proper IRI silently lost it. If your
194
+ profile states an `@id`, it must now conform (see feature 5 above) — and if it
195
+ states none, the identifier comes from `schema:url`, which for most profiles
196
+ is the same string you would have chosen anyway.
197
+ - **An existing declaration whose TRS `@id` is `"trs"` cannot be saved.** It
198
+ loads fine, so reading, reporting and `verify-timestamp` keep working; writing
199
+ it back needs the identifier corrected first:
200
+
201
+ ```python
202
+ tro = TransparentResearchObject.load("old.jsonld")
203
+ tro.trs.trs_id = "https://example.org/trs"
204
+ tro.save("old.jsonld")
205
+ ```
206
+
207
+ - **`schema:creator` is a node, not a string**, so `tro.creator` is an `Agent`
208
+ with a `.name`, and anything reading the serialised value as text (a report
209
+ template, say) needs `["schema:name"]`.
210
+ - **A capability's `@id` must be an IRI.** 0.4.x profiles conventionally used
211
+ `trs/capability/{i}`, which `trov:warrantedBy` then copied into every
212
+ performance attribute. Drop the `@id` from each `trov:hasCapability` entry
213
+ and the capability's own term is used instead.
214
+ - **Serialised output differs even when nothing else changed**: timestamps gain
215
+ an offset and artifacts are path-ordered. Both change the bytes of a
216
+ re-serialised declaration, which matters because a signature covers those
217
+ bytes — re-saving a signed 0.4.x declaration invalidates its existing
218
+ signature, so sign again afterwards.
219
+
220
+ ## Credits
221
+
222
+ This package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) and the [audreyr/cookiecutter-pypackage](https://github.com/audreyr/cookiecutter-pypackage) project template.
@@ -14,7 +14,9 @@ It uses the `Click` library to define commands and options. Here's a summary of
14
14
 
15
15
  2. **Commands**: The script defines several commands, each with its own set of options and arguments. The commands include:
16
16
 
17
- - `verify-timestamp`: Verifies the RFC 3161 timestamp and GPG signature on the TRO.
17
+ - `verify-timestamp`: Verifies the RFC 3161 timestamp on the TRO.
18
+
19
+ - `verify-signature`: Verifies the TRS's GPG signature on the TRO against your keyring. Import the TRS's public key from a source you trust first, or pass the key file the TRS publishes with `--keyring`; `--fingerprint` requires a given signing key. `--trs-keys` checks the key against a list of the TRS's keys with their validity dates, at the time of the TRO's timestamp. `--use-embedded-key` alone only checks that the TRO is self-consistent.
18
20
 
19
21
  - `verify-package`: Verifies a replication package (directory or `.zip`) against the hashes stored in an arrangement.
20
22
 
@@ -22,7 +24,7 @@ It uses the `Click` library to define commands and options. Here's a summary of
22
24
 
23
25
  - `composition`: Manages compositions in the TRO. It has a subcommand `info` that gets info about the current composition.
24
26
 
25
- - `performance`: Manages performances in the TRO. It has a subcommand `add` that adds a performance to the TRO.
27
+ - `performance`: Manages performances in the TRO. Subcommands: `add` (adds a performance to the TRO) and `list` (lists the performances recorded in the TRO; `-v` also shows start/end times, accessed and contributed arrangements with their mount paths, and performance attributes).
26
28
 
27
29
  - `sign`: Signs the TRO. This records the public half of the signing key as `trov:publicKey` in the declaration, saves the declaration, and then produces the signature and the RFC 3161 timestamp over it.
28
30
 
@@ -59,7 +61,7 @@ $ brew install gnupg openssl python3 # on macOS with Home
59
61
  ```
60
62
 
61
63
  If you only consume TROs — building, inspecting, reporting or `verify-timestamp` —
62
- GPG is not required; OpenSSL still is.
64
+ GPG is not required; OpenSSL still is. `verify-signature` needs GPG.
63
65
 
64
66
  ## Example Usage
65
67
 
@@ -127,6 +129,8 @@ $ tro-utils --declaration sample_tro.jsonld performance add \
127
129
  -a trov:InternetAccessRecording \
128
130
  -A arrangement/0 \
129
131
  -M arrangement/1
132
+ $ tro-utils --declaration sample_tro.jsonld performance list
133
+ Performance(id=trp/0): My magic workflow
130
134
  $ tro-utils --declaration sample_tro.jsonld sign
131
135
  $ tro-utils --declaration sample_tro.jsonld verify-timestamp
132
136
  ...
@@ -19,7 +19,8 @@
19
19
  #
20
20
  import os
21
21
  import sys
22
- sys.path.insert(0, os.path.abspath('..'))
22
+
23
+ sys.path.insert(0, os.path.abspath(".."))
23
24
 
24
25
  import tro_utils
25
26
 
@@ -31,25 +32,25 @@ import tro_utils
31
32
 
32
33
  # Add any Sphinx extension module names here, as strings. They can be
33
34
  # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
34
- extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'myst_parser']
35
+ extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode", "myst_parser"]
35
36
 
36
37
  # Add any paths that contain templates here, relative to this directory.
37
- templates_path = ['_templates']
38
+ templates_path = ["_templates"]
38
39
 
39
40
  # The suffix(es) of source filenames.
40
41
  # You can specify multiple suffix as a list of string:
41
42
  #
42
43
  # source_suffix = ['.rst', '.md']
43
44
  source_suffix = {
44
- '.rst': 'restructuredtext',
45
- '.md': 'markdown',
45
+ ".rst": "restructuredtext",
46
+ ".md": "markdown",
46
47
  }
47
48
 
48
49
  # The master toctree document.
49
- master_doc = 'index'
50
+ master_doc = "index"
50
51
 
51
52
  # General information about the project.
52
- project = 'Transparent Research Object utils'
53
+ project = "Transparent Research Object utils"
53
54
  copyright = "2024, Kacper Kowalik"
54
55
  author = "Kacper Kowalik"
55
56
 
@@ -72,10 +73,10 @@ language = "en"
72
73
  # List of patterns, relative to source directory, that match files and
73
74
  # directories to ignore when looking for source files.
74
75
  # This patterns also effect to html_static_path and html_extra_path
75
- exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
76
+ exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
76
77
 
77
78
  # The name of the Pygments (syntax highlighting) style to use.
78
- pygments_style = 'sphinx'
79
+ pygments_style = "sphinx"
79
80
 
80
81
  # If true, `todo` and `todoList` produce output, else they produce nothing.
81
82
  todo_include_todos = False
@@ -86,7 +87,7 @@ todo_include_todos = False
86
87
  # The theme to use for HTML and HTML Help pages. See the documentation for
87
88
  # a list of builtin themes.
88
89
  #
89
- html_theme = 'alabaster'
90
+ html_theme = "alabaster"
90
91
 
91
92
  # Theme options are theme-specific and customize the look and feel of a
92
93
  # theme further. For a list of options available for each theme, see the
@@ -103,7 +104,7 @@ html_theme = 'alabaster'
103
104
  # -- Options for HTMLHelp output ---------------------------------------
104
105
 
105
106
  # Output file base name for HTML help builder.
106
- htmlhelp_basename = 'tro_utilsdoc'
107
+ htmlhelp_basename = "tro_utilsdoc"
107
108
 
108
109
 
109
110
  # -- Options for LaTeX output ------------------------------------------
@@ -112,15 +113,12 @@ latex_elements = {
112
113
  # The paper size ('letterpaper' or 'a4paper').
113
114
  #
114
115
  # 'papersize': 'letterpaper',
115
-
116
116
  # The font size ('10pt', '11pt' or '12pt').
117
117
  #
118
118
  # 'pointsize': '10pt',
119
-
120
119
  # Additional stuff for the LaTeX preamble.
121
120
  #
122
121
  # 'preamble': '',
123
-
124
122
  # Latex figure (float) alignment
125
123
  #
126
124
  # 'figure_align': 'htbp',
@@ -130,9 +128,13 @@ latex_elements = {
130
128
  # (source start file, target name, title, author, documentclass
131
129
  # [howto, manual, or own class]).
132
130
  latex_documents = [
133
- (master_doc, 'tro_utils.tex',
134
- 'Transparent Research Object utils Documentation',
135
- 'Kacper Kowalik', 'manual'),
131
+ (
132
+ master_doc,
133
+ "tro_utils.tex",
134
+ "Transparent Research Object utils Documentation",
135
+ "Kacper Kowalik",
136
+ "manual",
137
+ ),
136
138
  ]
137
139
 
138
140
 
@@ -141,9 +143,13 @@ latex_documents = [
141
143
  # One entry per manual page. List of tuples
142
144
  # (source start file, name, description, authors, manual section).
143
145
  man_pages = [
144
- (master_doc, 'tro_utils',
145
- 'Transparent Research Object utils Documentation',
146
- [author], 1)
146
+ (
147
+ master_doc,
148
+ "tro_utils",
149
+ "Transparent Research Object utils Documentation",
150
+ [author],
151
+ 1,
152
+ )
147
153
  ]
148
154
 
149
155
 
@@ -153,13 +159,13 @@ man_pages = [
153
159
  # (source start file, target name, title, author,
154
160
  # dir menu entry, description, category)
155
161
  texinfo_documents = [
156
- (master_doc, 'tro_utils',
157
- 'Transparent Research Object utils Documentation',
158
- author,
159
- 'tro_utils',
160
- 'One line description of project.',
161
- 'Miscellaneous'),
162
+ (
163
+ master_doc,
164
+ "tro_utils",
165
+ "Transparent Research Object utils Documentation",
166
+ author,
167
+ "tro_utils",
168
+ "One line description of project.",
169
+ "Miscellaneous",
170
+ ),
162
171
  ]
163
-
164
-
165
-
@@ -66,15 +66,14 @@ Ready to contribute? Here's how to set up `tro_utils` for local development.
66
66
 
67
67
  Now you can make your changes locally.
68
68
 
69
- 5. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:
69
+ 5. When you're done making changes, check that your changes are formatted with black and pass the tests:
70
70
 
71
71
  ```bash
72
- $ flake8 tro_utils tests
72
+ $ black --check .
73
73
  $ pytest
74
- $ tox
75
74
  ```
76
75
 
77
- To get flake8 and tox, just pip install them into your virtualenv.
76
+ To get black and pytest, install the dev extra into your virtualenv: `pip install -e ".[dev]"`.
78
77
 
79
78
  6. Commit your changes and push your branch to GitHub:
80
79
 
@@ -92,7 +91,7 @@ Before you submit a pull request, check that it meets these guidelines:
92
91
 
93
92
  1. The pull request should include tests.
94
93
  2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.md.
95
- 3. The pull request should work for Python 3.5, 3.6, 3.7 and 3.8, and for PyPy. Check https://travis-ci.com/Xarthisius/tro_utils/pull_requests and make sure that the tests pass for all supported Python versions.
94
+ 3. The pull request should work for all supported Python versions (3.12 and newer). Check the GitHub Actions results on the pull request and make sure that the tests pass for all of them.
96
95
 
97
96
  ## Tips
98
97
 
@@ -104,12 +103,11 @@ $ pytest tests.test_tro_utils
104
103
 
105
104
  ## Deploying
106
105
 
107
- A reminder for the maintainers on how to deploy. Make sure all your changes are committed (including an entry in HISTORY.md). Then run:
106
+ A reminder for the maintainers on how to deploy. Make sure all your changes are committed (including an entry in docs/history.md). The version is taken from the git tag by setuptools-scm, so tag the release and push the tag:
108
107
 
109
108
  ```bash
110
- $ bump2version patch # possible: major / minor / patch
111
- $ git push
112
- $ git push --tags
109
+ $ git tag v0.5.4
110
+ $ git push origin v0.5.4
113
111
  ```
114
112
 
115
- Travis will then deploy to PyPI if tests pass.
113
+ GitHub Actions will then publish the tagged release to PyPI.
@@ -15,7 +15,7 @@ $ brew install gnupg openssl python3 # on macOS with Home
15
15
  ```
16
16
 
17
17
  If you only consume TROs — building, inspecting, reporting or `verify-timestamp` —
18
- GPG is not required; OpenSSL still is.
18
+ GPG is not required; OpenSSL still is. `verify-signature` needs GPG.
19
19
 
20
20
  ## Stable release
21
21