Add FrozenDocumentLoader for offline / vetted JSON-LD contexts

[anatoly-scherbakov]

Why?

For tight security deployments, it might be necessary to:

• Ensure that the system does not require network access and does not download arbitrary data from the Web,
• But still make certain white listed contexts/remote documents available to JSON-LD processing.

Summary

• Adds pyld.DocumentLoader (ABC) + pyld.RemoteDocument (TypedDict) — the first class-based loader contract in PyLD; existing function-based loaders remain valid.
• Adds pyld.FrozenDocumentLoader: a class-based loader that serves only URLs in its documents allowlist and refuses everything else with JsonLdError(code='loading document failed'). Suitable for air-gapped runs, reproducible builds, and security-hardened deployments. Honors the W3C JSON-LD Best Practices recommendation that clients SHOULD attempt to use a locally cached version of contexts (§ Cache JSON-LD Contexts).
• Adds pyld.BUNDLED_CONTEXTS: 8 vendored W3C / W3ID JSON-LD contexts (ActivityStreams, DID v1, VC v1/v2, Linked Data Security v1/v2, Ed25519-2020, JWS-2020), refreshable with make download-bundled-contexts. With no arguments FrozenDocumentLoader() serves these; pass dict(BUNDLED_CONTEXTS, **extras) to extend.

Design notes

• documents: dict[str, dict | Path] — Path entries are read & parsed lazily on first request and cached in place. __post_init__ makes a defensive copy so the caller's mapping is never mutated.
• RemoteDocument is a real TypedDict (previously only a docstring word). Subclasses get a typed __call__ return.
• Bundled *.jsonld files ship via setup.py's package_data and MANIFEST.in's recursive-include.

Test plan

• pytest tests/test_frozen_document_loader.py -v — 8 new tests, all pass.
• Full non-network suite: pytest -m "not network" — 1477 passed, 43 skipped, 14 xfailed.
• make lint clean.
• End-to-end smoke: jsonld.expand(doc_with_did_v1_context, options={'documentLoader': FrozenDocumentLoader()}) resolves with no network.
• Refusal smoke: unknown URL raises JsonLdError(code='loading document failed', type='jsonld.LoadDocumentError').
• Bundle refresh: make download-bundled-contexts succeeds and is idempotent.

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
lib/pyld
canon.py	218	4	98%	27, 180, 565–566
context_resolver.py	102	8	92%	70, 129, 143, 189, 195–197, 221
iri_resolver.py	141	3	98%	307–308, 318
jsonld.py	2435	173	93%	274–278, 359, 396, 401, 411, 428–443, 479–480, 522, 530, 550, 558–559, 667–672, 752–753, 768–769, 829–834, 859–860, 875–876, 886–887, 912–913, 954, 964, 970–974, 985–986, 1019, 1028, 1035, 1100, 1123, 1145–1147, 1157–1160, 1175, 1198, 1210–1213, 1305, 1317–1320, 1340, 1369, 1402, 1406, 1443, 1486, 1504–1507, 1516, 1561, 1664–1671, 1698–1700, 1705, 1726–1729, 1905, 1926, 2354, 2363–2370, 2462, 2489, 2512, 2521, 3037, 3090, 3093, 3156, 3241, 3275, 3283, 3549, 3554, 3556, 3605, 3743–3747, 3813, 3850, 3913, 4133–4134, 4148, 4436, 4568, 4602, 4631–4634, 4660–4661, 4844, 4908, 4935, 5009, 5011, 5029, 5127, 5176, 5408, 5410, 5449, 5451, 5460, 5599, 5725, 5812, 5932–5946, 6005–6011, 6078, 6291, 6297–6301, 6340, 6343, 6433–6434, 6443
lib/pyld/documentloader
aiohttp.py	65	22	66%	28–38, 69, 75, 87, 99–107, 118–121, 138, 153–155
requests.py	41	5	88%	55, 69, 81–89
TOTAL	3188	215	93%

Tests	Skipped	Failures	Errors	Time
1664	59 💤	0 ❌	0 🔥	12.094s ⏱️

[mielvds]

Hi @anatoly-scherbakov , thanks for this. This is a useful feature. Before I review, two questions:

• it is necessary to have these local contexts in this repo? This seems difficult to maintain. Can't make download-bundled-contexts be part of the install procedure?
• do we need to revisit unittests that require network?

[anatoly-scherbakov]

@mielvds thanks for the review!

Can't make download-bundled-contexts be part of the install procedure?

I would advise against that.

• If pyld is being installed from a corporate PyPI mirror in a secure environment, Internet access might be restricted, and the installation will fail
• Or, network just might be glitchy

Developers who employ the new FrozenDocumentLoader will vendor in the contexts, — that's the whole point of it. It is expected that vendored contexts are:

• vetted,
• verified for security,
• and will not change.

This is the most straightforward way to avoid security vulnerabilities introduced by context spoofing.

For future versions of JSON-LD, the Working Group is going to work on security features that should reduce the possibility of context spoofing attacks.

Regardless of these developments, an air-gapped DocumentLoader that does not allow network access and whitelists remote documents is a solution already available to current JSON-LD systems.

cc @BigBlueHat what do you think?

[mielvds]

Looks good to me! But let's give the original maintainers a couple of days to comment