tro-utils 0.5.4__py3-none-any.whl

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.
@@ -0,0 +1,329 @@
1
+ """TrustedResearchSystem and TRSCapability models."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+ from dataclasses import dataclass, field
7
+ from typing import Any
8
+
9
+ from ._base import TROVModel
10
+
11
+ # Profile keys that are handled as typed fields on TrustedResearchSystem;
12
+ # all other keys are stored verbatim in ``extra_fields``.
13
+ _KNOWN_TRS_KEYS = {
14
+ "@id",
15
+ "@type",
16
+ "schema:name",
17
+ "schema:description",
18
+ "trov:publicKey",
19
+ "trov:hasCapability",
20
+ }
21
+
22
+ #: Used when a profile identifies the TRS neither by ``@id`` nor by a URL.
23
+ UNIDENTIFIED_TRS_ID = "https://w3id.org/trace/tro-utils#unidentified-trs"
24
+
25
+ # An absolute IRI and a compact IRI share this shape: a scheme/prefix per
26
+ # RFC 3986, a colon, then a non-empty remainder. What this rules out is a
27
+ # bare relative reference such as "trs" or "trs/capability/1", which resolves
28
+ # against whatever document happens to contain it.
29
+ _IRI_RE = re.compile(r"^(?P<prefix>[A-Za-z][A-Za-z0-9+.\-]*):(?P<rest>.+)$")
30
+
31
+ # The trov prefix names the vocabulary itself, so a TRS minted under it would
32
+ # not be the same TRS wherever it is defined.
33
+ _RESERVED_PREFIX = "trov"
34
+
35
+
36
+ def iri_prefix(value: Any) -> str | None:
37
+ """Return the scheme/prefix of *value*, or ``None`` if it is not an IRI.
38
+
39
+ Args:
40
+ value: A candidate ``@id``.
41
+
42
+ Returns:
43
+ The part before the first colon, or ``None`` when *value* is a
44
+ relative reference, a blank node, or not a string at all.
45
+ """
46
+ if not isinstance(value, str):
47
+ return None
48
+ match = _IRI_RE.match(value)
49
+ return match.group("prefix") if match else None
50
+
51
+
52
+ def is_conforming_trs_id(value: Any) -> bool:
53
+ """Return whether *value* may identify a TRS.
54
+
55
+ A TRS ``@id`` must be an absolute IRI, or a compact IRI whose prefix is
56
+ not ``trov``, so that the same TRS carries the same identifier in every
57
+ document that mentions it.
58
+
59
+ Args:
60
+ value: A candidate ``@id``.
61
+
62
+ Returns:
63
+ ``True`` when *value* conforms.
64
+ """
65
+ prefix = iri_prefix(value)
66
+ return prefix is not None and prefix != _RESERVED_PREFIX
67
+
68
+
69
+ def is_conforming_capability_id(value: Any) -> bool:
70
+ """Return whether *value* may identify a TRS capability.
71
+
72
+ A capability belongs to the TRS rather than to any one declaration, so it
73
+ has to be named the same way everywhere: an absolute IRI or a compact IRI.
74
+ Unlike a TRS ``@id``, the ``trov`` prefix is allowed here -- the usual
75
+ identifier for a capability *is* its vocabulary term, e.g.
76
+ ``trov:CanRecordInternetAccess``.
77
+
78
+ Args:
79
+ value: A candidate ``@id``.
80
+
81
+ Returns:
82
+ ``True`` when *value* conforms.
83
+ """
84
+ return iri_prefix(value) is not None
85
+
86
+
87
+ def validate_capability_id(value: Any, source: str = "capability @id") -> str:
88
+ """Return *value* unchanged, or raise if it cannot identify a capability.
89
+
90
+ Args:
91
+ value: The candidate ``@id``.
92
+ source: Label for the error message.
93
+
94
+ Returns:
95
+ *value*.
96
+
97
+ Raises:
98
+ ValueError: If *value* does not conform. See
99
+ :func:`is_conforming_capability_id`.
100
+ """
101
+ if is_conforming_capability_id(value):
102
+ return value
103
+ raise ValueError(
104
+ f"{source} must be an absolute IRI or a compact IRI -- usually the "
105
+ f"capability's own term, e.g. 'trov:CanRecordInternetAccess' -- so "
106
+ f"that trov:warrantedBy refers to the same capability wherever it is "
107
+ f"mentioned; got {value!r}. A relative id such as 'trs/capability/1' "
108
+ f"resolves against whichever document contains it. Omit @id to use "
109
+ f"the capability's @type."
110
+ )
111
+
112
+
113
+ def validate_trs_id(value: Any, source: str = "TRS @id") -> str:
114
+ """Return *value* unchanged, or raise if it cannot identify a TRS.
115
+
116
+ Args:
117
+ value: The candidate ``@id``.
118
+ source: Label for the error message.
119
+
120
+ Returns:
121
+ *value*.
122
+
123
+ Raises:
124
+ ValueError: If *value* does not conform. See :func:`is_conforming_trs_id`.
125
+ """
126
+ if is_conforming_trs_id(value):
127
+ return value
128
+ raise ValueError(
129
+ f"{source} must be an absolute IRI (e.g. "
130
+ f"'https://example.org/trs') or a compact IRI whose prefix is not "
131
+ f"'{_RESERVED_PREFIX}' (e.g. 'ex:trs'), so that the TRS is the same "
132
+ f"wherever it is defined; got {value!r}"
133
+ )
134
+
135
+
136
+ @dataclass
137
+ class TRSCapability(TROVModel):
138
+ """A single capability declared by a :class:`TrustedResearchSystem`.
139
+
140
+ The ``@id`` is what ``trov:warrantedBy`` points at from a performance
141
+ attribute, so it has to name the same capability in every declaration --
142
+ see :func:`is_conforming_capability_id`. A profile that states no ``@id``
143
+ gets the capability's own term, which is the usual identifier for it.
144
+ """
145
+
146
+ capability_id: str
147
+ capability_type: str
148
+
149
+ # ------------------------------------------------------------------
150
+ # Convenience constructors
151
+ # ------------------------------------------------------------------
152
+
153
+ @classmethod
154
+ def from_profile_entry(cls, data: dict[str, Any]) -> "TRSCapability":
155
+ """Build a capability from one ``trov:hasCapability`` profile entry.
156
+
157
+ Args:
158
+ data: Dict with ``@type`` and an optional ``@id``.
159
+
160
+ Returns:
161
+ :class:`TRSCapability` identified by its stated ``@id``, or by its
162
+ ``@type`` when none is stated.
163
+
164
+ Raises:
165
+ ValueError: If a stated ``@id`` cannot identify a capability, or if
166
+ the entry has no usable ``@type``.
167
+ """
168
+ capability_type = data["@type"]
169
+ if "@id" in data:
170
+ capability_id = validate_capability_id(
171
+ data["@id"], "TRS profile capability @id"
172
+ )
173
+ else:
174
+ capability_id = validate_capability_id(
175
+ capability_type, "TRS profile capability @type"
176
+ )
177
+ return cls(capability_id=capability_id, capability_type=capability_type)
178
+
179
+ # ------------------------------------------------------------------
180
+ # JSON-LD serialisation
181
+ # ------------------------------------------------------------------
182
+
183
+ def to_jsonld(self) -> dict[str, Any]:
184
+ return {
185
+ "@id": self.capability_id,
186
+ "@type": self.capability_type,
187
+ }
188
+
189
+ @classmethod
190
+ def from_jsonld(cls, data: dict[str, Any]) -> "TRSCapability":
191
+ """Deserialise from a declaration, permissively.
192
+
193
+ Declarations written before capabilities were named by a conforming
194
+ IRI carry a relative ``@id``; they have to stay loadable, so nothing
195
+ is validated here. :meth:`from_profile_entry` is the checked path.
196
+ """
197
+ return cls(
198
+ capability_id=data["@id"],
199
+ capability_type=data["@type"],
200
+ )
201
+
202
+
203
+ @dataclass
204
+ class TrustedResearchSystem(TROVModel):
205
+ """A Trusted Research System (TRS) that assembled and/or ran a TRO.
206
+
207
+ The TRS is a ``schema:Organization``, so it is described with schema.org
208
+ properties: ``schema:name`` and ``schema:description`` are typed fields,
209
+ and the rest (``schema:url``, ``schema:email``, ``schema:owner``, plus any
210
+ vendor-specific keys) are stored in :attr:`extra_fields` and round-tripped
211
+ verbatim through ``to_jsonld()`` / ``from_jsonld()``.
212
+ """
213
+
214
+ trs_id: str = UNIDENTIFIED_TRS_ID
215
+ name: str = ""
216
+ description: str = ""
217
+ public_key: str | None = None
218
+ capabilities: list[TRSCapability] = field(default_factory=list)
219
+ extra_fields: dict[str, Any] = field(default_factory=dict)
220
+
221
+ # ------------------------------------------------------------------
222
+ # Convenience constructors
223
+ # ------------------------------------------------------------------
224
+
225
+ @classmethod
226
+ def from_profile(
227
+ cls, profile: dict[str, Any], trs_id: str | None = None
228
+ ) -> "TrustedResearchSystem":
229
+ """Load a TRS from the profile dict used by the existing CLI.
230
+
231
+ The profile format mirrors what is stored under ``trov:wasAssembledBy``
232
+ in a JSON-LD document. All unrecognised keys are preserved in
233
+ :attr:`extra_fields`.
234
+
235
+ The identifier is taken from *trs_id*, else the profile's ``@id``, else
236
+ its ``schema:url``, else :data:`UNIDENTIFIED_TRS_ID`. Whichever is
237
+ used must conform -- see :func:`validate_trs_id`.
238
+
239
+ Args:
240
+ profile: Dict with optional keys ``@id``, ``schema:name``,
241
+ ``schema:description``, ``trov:publicKey``,
242
+ ``trov:hasCapability``, plus any vendor-specific fields.
243
+ trs_id: Overrides the ``@id`` carried by *profile*.
244
+
245
+ Returns:
246
+ :class:`TrustedResearchSystem` instance.
247
+
248
+ Raises:
249
+ ValueError: If the resolved identifier does not conform.
250
+ """
251
+ capabilities = [
252
+ TRSCapability.from_profile_entry(cap)
253
+ for cap in profile.get("trov:hasCapability", [])
254
+ ]
255
+ extra = {k: v for k, v in profile.items() if k not in _KNOWN_TRS_KEYS}
256
+ return cls(
257
+ trs_id=cls._resolve_profile_id(profile, trs_id),
258
+ name=profile.get("schema:name", ""),
259
+ description=profile.get("schema:description", ""),
260
+ public_key=profile.get("trov:publicKey"),
261
+ capabilities=capabilities,
262
+ extra_fields=extra,
263
+ )
264
+
265
+ @staticmethod
266
+ def _resolve_profile_id(profile: dict[str, Any], trs_id: str | None) -> str:
267
+ """Pick the TRS ``@id`` for *profile* and check that it conforms.
268
+
269
+ An identifier the caller or profile states explicitly is validated
270
+ rather than quietly replaced, so a non-conforming one is reported
271
+ instead of being papered over by the fallback.
272
+ """
273
+ if trs_id is not None:
274
+ return validate_trs_id(trs_id, "TRS @id")
275
+ if "@id" in profile:
276
+ return validate_trs_id(profile["@id"], "TRS profile @id")
277
+ # A TRS's URL already identifies it globally. trov:url is read only
278
+ # for profiles written before the TRS was described with schema.org
279
+ # properties; the TROV vocabulary never defined that term.
280
+ for key in ("schema:url", "trov:url"):
281
+ url = profile.get(key)
282
+ if url is not None and is_conforming_trs_id(url):
283
+ return url
284
+ return UNIDENTIFIED_TRS_ID
285
+
286
+ # ------------------------------------------------------------------
287
+ # JSON-LD serialisation
288
+ # ------------------------------------------------------------------
289
+
290
+ def to_jsonld(self) -> dict[str, Any]:
291
+ result: dict[str, Any] = {
292
+ "@id": self.trs_id,
293
+ "@type": ["trov:TrustedResearchSystem", "schema:Organization"],
294
+ "trov:hasCapability": [cap.to_jsonld() for cap in self.capabilities],
295
+ }
296
+ # Merge extra (vendor) fields first so typed fields can override
297
+ result.update(self.extra_fields)
298
+ if self.name:
299
+ result["schema:name"] = self.name
300
+ if self.description:
301
+ result["schema:description"] = self.description
302
+ if self.public_key is not None:
303
+ result["trov:publicKey"] = self.public_key
304
+ return result
305
+
306
+ @classmethod
307
+ def from_jsonld(cls, data: dict[str, Any]) -> "TrustedResearchSystem":
308
+ """Deserialise from a JSON-LD TRS dict (``trov:wasAssembledBy`` value).
309
+
310
+ Args:
311
+ data: Dict with ``@id``, optional ``schema:name``, etc.
312
+
313
+ Returns:
314
+ :class:`TrustedResearchSystem` instance.
315
+ """
316
+ capabilities = [
317
+ TRSCapability.from_jsonld(cap) for cap in data.get("trov:hasCapability", [])
318
+ ]
319
+ extra = {k: v for k, v in data.items() if k not in _KNOWN_TRS_KEYS}
320
+ return cls(
321
+ # Read as-is: declarations predating this rule carry a bare
322
+ # "trs", and they must stay loadable.
323
+ trs_id=data.get("@id", UNIDENTIFIED_TRS_ID),
324
+ name=data.get("schema:name", ""),
325
+ description=data.get("schema:description", ""),
326
+ public_key=data.get("trov:publicKey"),
327
+ capabilities=capabilities,
328
+ extra_fields=extra,
329
+ )
@@ -0,0 +1,44 @@
1
+ """TimeStampingAuthority model."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass
6
+ from typing import Any
7
+
8
+ from ._base import TROVModel
9
+
10
+
11
+ @dataclass
12
+ class TimeStampingAuthority(TROVModel):
13
+ """A Time Stamping Authority (TSA) that signed a TRO timestamp."""
14
+
15
+ tsa_id: str = "tsa"
16
+ public_key: str | None = None
17
+
18
+ # ------------------------------------------------------------------
19
+ # JSON-LD serialisation
20
+ # ------------------------------------------------------------------
21
+
22
+ def to_jsonld(self) -> dict[str, Any]:
23
+ result: dict[str, Any] = {
24
+ "@id": self.tsa_id,
25
+ "@type": "trov:TimeStampingAuthority",
26
+ }
27
+ if self.public_key is not None:
28
+ result["trov:publicKey"] = self.public_key
29
+ return result
30
+
31
+ @classmethod
32
+ def from_jsonld(cls, data: dict[str, Any]) -> "TimeStampingAuthority":
33
+ """Deserialise from a JSON-LD TSA dict (``trov:wasTimestampedBy`` value).
34
+
35
+ Args:
36
+ data: Dict with ``@id`` and optional ``trov:publicKey``.
37
+
38
+ Returns:
39
+ :class:`TimeStampingAuthority` instance.
40
+ """
41
+ return cls(
42
+ tsa_id=data.get("@id", "tsa"),
43
+ public_key=data.get("trov:publicKey"),
44
+ )
@@ -0,0 +1,179 @@
1
+ """ReplicationPackage — verifies a research package against a TRO arrangement.
2
+
3
+ Provides a standalone :class:`ReplicationPackage` class for verifying that a
4
+ directory or zip archive matches the file-hash mapping recorded in an
5
+ :class:`~tro_utils.models.arrangement.ArtifactArrangement`.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import hashlib
11
+ import os
12
+ import pathlib
13
+ import zipfile
14
+ from dataclasses import dataclass, field
15
+ from typing import Iterator
16
+
17
+
18
+ @dataclass
19
+ class VerificationResult:
20
+ """Result of a :meth:`ReplicationPackage.verify` call."""
21
+
22
+ files_missing_in_arrangement: list[str] = field(default_factory=list)
23
+ mismatched_hashes: list[tuple[str, str | None, str]] = field(default_factory=list)
24
+ files_missing_in_package: list[str] = field(default_factory=list)
25
+
26
+ @property
27
+ def is_valid(self) -> bool:
28
+ """``True`` when all checks pass."""
29
+ return not (
30
+ self.files_missing_in_arrangement
31
+ or self.mismatched_hashes
32
+ or self.files_missing_in_package
33
+ )
34
+
35
+
36
+ class ReplicationPackage:
37
+ """Verify a research package (directory or zip) against an arrangement.
38
+
39
+ Example::
40
+
41
+ from tro_utils.models import TransparentResearchObject
42
+ from tro_utils.replication_package import ReplicationPackage
43
+
44
+ tro = TransparentResearchObject.load("my_tro.jsonld")
45
+ arrangement = tro.arrangements[1] # "after execution" snapshot
46
+ result = ReplicationPackage.verify(
47
+ arrangement, tro.composition, "path/to/package"
48
+ )
49
+ if result.is_valid:
50
+ print("Package matches arrangement.")
51
+ """
52
+
53
+ # ------------------------------------------------------------------
54
+ # Public API
55
+ # ------------------------------------------------------------------
56
+
57
+ @classmethod
58
+ def verify(
59
+ cls,
60
+ arrangement,
61
+ composition,
62
+ package: str | pathlib.Path,
63
+ subpath: str | None = None,
64
+ ) -> VerificationResult:
65
+ """Verify *package* against *arrangement*.
66
+
67
+ Args:
68
+ arrangement: :class:`~tro_utils.models.arrangement.ArtifactArrangement`
69
+ to compare against.
70
+ composition: :class:`~tro_utils.models.composition.ArtifactComposition`
71
+ that owns the artifact hashes.
72
+ package: Path to a directory or ``.zip`` file to inspect.
73
+ subpath: If set, only package entries whose path starts with
74
+ *subpath* are considered (relative to *subpath* after stripping).
75
+
76
+ Returns:
77
+ A :class:`VerificationResult` describing any discrepancies.
78
+ """
79
+ arrangement_map: dict[str, str] = arrangement.to_path_hash_map(composition)
80
+ result = VerificationResult()
81
+
82
+ for rel_filename, file_hash in cls._iterate_package_files(package, subpath):
83
+ if rel_filename not in arrangement_map:
84
+ result.files_missing_in_arrangement.append(rel_filename)
85
+
86
+ expected_hash = arrangement_map.pop(rel_filename, None)
87
+ if file_hash != expected_hash:
88
+ result.mismatched_hashes.append(
89
+ (rel_filename, expected_hash, file_hash)
90
+ )
91
+
92
+ # Files present in the arrangement but absent from the package
93
+ result.files_missing_in_package = sorted(arrangement_map.keys())
94
+ result.files_missing_in_arrangement.sort()
95
+ result.mismatched_hashes.sort()
96
+ return result
97
+
98
+ # ------------------------------------------------------------------
99
+ # Internal helpers
100
+ # ------------------------------------------------------------------
101
+
102
+ @staticmethod
103
+ def _iterate_package_files(
104
+ package: str | pathlib.Path,
105
+ subpath: str | None,
106
+ ) -> Iterator[tuple[str, str]]:
107
+ """Yield ``(relative_path, "sha256:<hex>")`` pairs from *package*.
108
+
109
+ Args:
110
+ package: Directory or zip archive path.
111
+ subpath: Optional path prefix to strip (directories inside zip).
112
+
113
+ Yields:
114
+ Tuples of ``(relative_filename, hash_string)``.
115
+ """
116
+ package = pathlib.Path(package)
117
+ if package.is_dir():
118
+ yield from ReplicationPackage._iter_directory(package, subpath)
119
+ else:
120
+ yield from ReplicationPackage._iter_zip(package, subpath)
121
+
122
+ @staticmethod
123
+ def _iter_directory(
124
+ root: pathlib.Path,
125
+ subpath: str | None,
126
+ ) -> Iterator[tuple[str, str]]:
127
+ # os.walk yields filesystem order, so sort to keep the reported
128
+ # discrepancy lists identical from one machine to the next.
129
+ discovered: list[pathlib.Path] = []
130
+ for dirpath, _dirs, files in os.walk(root):
131
+ for filename in files:
132
+ discovered.append(pathlib.Path(dirpath) / filename)
133
+ discovered.sort(key=lambda p: p.relative_to(root).as_posix())
134
+
135
+ for filepath in discovered:
136
+ original = filepath.relative_to(root).as_posix()
137
+ rel = ReplicationPackage._apply_subpath(original, subpath)
138
+ if rel is None:
139
+ continue
140
+ hash_str = ReplicationPackage._sha256_file(filepath)
141
+ yield rel, hash_str
142
+
143
+ @staticmethod
144
+ def _iter_zip(
145
+ zip_path: pathlib.Path,
146
+ subpath: str | None,
147
+ ) -> Iterator[tuple[str, str]]:
148
+ with zipfile.ZipFile(zip_path, "r") as zf:
149
+ for fileinfo in zf.infolist():
150
+ rel = ReplicationPackage._apply_subpath(fileinfo.filename, subpath)
151
+ if rel is None:
152
+ continue
153
+ sha256 = hashlib.sha256()
154
+ with zf.open(fileinfo.filename) as f:
155
+ for chunk in iter(lambda: f.read(4096), b""):
156
+ sha256.update(chunk)
157
+ yield rel, f"sha256:{sha256.hexdigest()}"
158
+
159
+ @staticmethod
160
+ def _apply_subpath(original: str, subpath: str | None) -> str | None:
161
+ """Strip *subpath* prefix from *original*, or return ``None`` to skip."""
162
+ if subpath is None:
163
+ return original
164
+ import pathlib as _pl
165
+
166
+ orig = _pl.PurePosixPath(original)
167
+ sub = _pl.PurePosixPath(subpath)
168
+ try:
169
+ return orig.relative_to(sub).as_posix()
170
+ except ValueError:
171
+ return None
172
+
173
+ @staticmethod
174
+ def _sha256_file(filepath: pathlib.Path) -> str:
175
+ sha256 = hashlib.sha256()
176
+ with open(filepath, "rb") as f:
177
+ for chunk in iter(lambda: f.read(4096), b""):
178
+ sha256.update(chunk)
179
+ return f"sha256:{sha256.hexdigest()}"
Binary file