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.
- {tro_utils-0.5.2 → tro_utils-0.5.4}/.github/workflows/release.yml +6 -6
- {tro_utils-0.5.2 → tro_utils-0.5.4}/.github/workflows/test.yml +21 -5
- tro_utils-0.5.4/MANIFEST.in +8 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/Makefile +0 -4
- tro_utils-0.5.4/PKG-INFO +222 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/README.md +7 -3
- {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/conf.py +35 -29
- {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/contributing.md +8 -10
- {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/installation.md +1 -1
- {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/usage.md +97 -2
- {tro_utils-0.5.2 → tro_utils-0.5.4}/pyproject.toml +15 -10
- {tro_utils-0.5.2 → tro_utils-0.5.4}/setup.cfg +0 -3
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/conftest.py +3 -1
- tro_utils-0.5.4/tests/data/tsa/freetsa-2025.payload +4 -0
- tro_utils-0.5.4/tests/data/tsa/freetsa-2025.tsr +0 -0
- tro_utils-0.5.4/tests/data/tsa/freetsa-2026.payload +4 -0
- tro_utils-0.5.4/tests/data/tsa/freetsa-2026.tsr +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_cli.py +247 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_tro_performances.py +54 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_tro_reporting.py +90 -4
- tro_utils-0.5.4/tests/test_tro_signature_verification.py +871 -0
- tro_utils-0.5.4/tests/test_tro_timestamping.py +353 -0
- tro_utils-0.5.4/tests/test_trs_keys.py +207 -0
- tro_utils-0.5.4/tests/test_tsa.py +177 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/_version.py +3 -3
- tro_utils-0.5.4/tro_utils/certs/freetsa-root.pem +52 -0
- tro_utils-0.5.4/tro_utils/certs/freetsa-tsa.pem +100 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/cli.py +250 -25
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/default.jinja2 +12 -1
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/tro.py +3 -1
- tro_utils-0.5.4/tro_utils/static/trace-logo.png +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/tro_utils.py +320 -53
- tro_utils-0.5.4/tro_utils/trs_keys.py +251 -0
- tro_utils-0.5.4/tro_utils/tsa.py +149 -0
- tro_utils-0.5.4/tro_utils.egg-info/PKG-INFO +222 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils.egg-info/SOURCES.txt +13 -4
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils.egg-info/requires.txt +3 -2
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils.egg-info/scm_file_list.json +13 -4
- tro_utils-0.5.4/tro_utils.egg-info/scm_version.json +8 -0
- tro_utils-0.5.2/.travis.yml +0 -28
- tro_utils-0.5.2/MANIFEST.in +0 -11
- tro_utils-0.5.2/PKG-INFO +0 -75
- tro_utils-0.5.2/requirements_dev.txt +0 -13
- tro_utils-0.5.2/tests/test_tro_timestamping.py +0 -167
- tro_utils-0.5.2/tox.ini +0 -26
- tro_utils-0.5.2/tro_utils.egg-info/PKG-INFO +0 -75
- tro_utils-0.5.2/tro_utils.egg-info/scm_version.json +0 -8
- {tro_utils-0.5.2 → tro_utils-0.5.4}/.coveragerc +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/.editorconfig +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/.github/ISSUE_TEMPLATE.md +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/.gitignore +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/.readthedocs.yaml +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/LICENSE +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/Makefile +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/authors.md +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/history.md +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/index.md +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/make.bat +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/readme.md +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/docs/requirements.txt +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/pytest.ini +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/__init__.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/helpers.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_arrangement_determinism.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_extra_context.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_agent.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_artifact_arrangement.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_artifact_composition.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_artifact_location.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_composition_fingerprint.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_hash_value.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_performance.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_research_artifact.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_transparent_research_object.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_trs.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_models_tsa.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_replication_package_model.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_replication_package_verification.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_tro_arrangements.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_tro_creation.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_tro_hashing.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_tro_save_load.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_tro_signing.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_tro_utility_methods.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_tro_workflow.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_trs_identifier.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tests/test_version.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/__init__.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/__init__.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/_base.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/agent.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/arrangement.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/artifact.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/attribute.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/composition.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/hash_value.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/performance.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/trs.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/models/tsa.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils/replication_package.py +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils.egg-info/dependency_links.txt +0 -0
- {tro_utils-0.5.2 → tro_utils-0.5.4}/tro_utils.egg-info/entry_points.txt +0 -0
- {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@
|
|
11
|
+
- uses: actions/checkout@v7
|
|
12
12
|
- name: Set up Python
|
|
13
|
-
uses: actions/setup-python@
|
|
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@
|
|
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@
|
|
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@
|
|
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.
|
|
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.
|
|
30
|
+
python-version: ['3.12', '3.13', '3.14', '3.15']
|
|
15
31
|
|
|
16
32
|
steps:
|
|
17
|
-
- uses: actions/checkout@
|
|
33
|
+
- uses: actions/checkout@v7
|
|
18
34
|
|
|
19
35
|
- name: Set up Python ${{ matrix.python-version }}
|
|
20
|
-
uses: actions/setup-python@
|
|
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@
|
|
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@
|
|
64
|
+
uses: codecov/codecov-action@v7
|
|
49
65
|
with:
|
|
50
66
|
token: ${{ secrets.CODECOV_TOKEN }}
|
|
51
67
|
fail_ci_if_error: false
|
|
@@ -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
|
tro_utils-0.5.4/PKG-INFO
ADDED
|
@@ -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
|
+
[](https://pypi.python.org/pypi/tro-utils)
|
|
49
|
+
[](https://zenodo.org/doi/10.5281/zenodo.11130420)
|
|
50
|
+
[](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
|
|
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.
|
|
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
|
-
|
|
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 = [
|
|
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 = [
|
|
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
|
-
|
|
45
|
-
|
|
45
|
+
".rst": "restructuredtext",
|
|
46
|
+
".md": "markdown",
|
|
46
47
|
}
|
|
47
48
|
|
|
48
49
|
# The master toctree document.
|
|
49
|
-
master_doc =
|
|
50
|
+
master_doc = "index"
|
|
50
51
|
|
|
51
52
|
# General information about the project.
|
|
52
|
-
project =
|
|
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 = [
|
|
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 =
|
|
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 =
|
|
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 =
|
|
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
|
-
(
|
|
134
|
-
|
|
135
|
-
|
|
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
|
-
(
|
|
145
|
-
|
|
146
|
-
|
|
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
|
-
(
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
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
|
|
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
|
-
$
|
|
72
|
+
$ black --check .
|
|
73
73
|
$ pytest
|
|
74
|
-
$ tox
|
|
75
74
|
```
|
|
76
75
|
|
|
77
|
-
To get
|
|
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
|
|
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
|
|
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
|
-
$
|
|
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
|
-
|
|
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
|
|