Promote using an allow list of pre-downloaded contexts

[BigBlueHat]

This is heavily promoted in the VC Data Model specification, but the hash information is provided "out of bound" (via human-readable spec text) with the expectation that implementers will download/cache/"install" contexts after verifying the hash from the specification and map the URIs for those contexts explicitly to those "canonical" values.

This is very effective in practice, but lacks a great deal in terms of "helpful plumbing" to make it a regular pattern to follow (i.e. creating, finding, curating hashes in specifications take effort that's not typically exerted by most communities--even where the safety/stability concerns exist).

Consequently, this can be (and should be) promoted as a best practice, but JSON-LD itself lacks the affordances for providing any cache related information (hashes, etc.) for later comparison/confirmation.

[BigBlueHat]

Caching: https://iolanta.tech/blog/remote-contexts-considered-harmful/#cache
Allowlist / Long-term storage: https://iolanta.tech/blog/remote-contexts-considered-harmful/#allowlist

[anatoly-scherbakov]

I would argue that 1) caching and 2) long term storage of pre-downloaded contexts might be different things. Example of the latter from pyld (currently in master, bound to be in 3.1.0 release):

from pathlib import Path

from pyld import FrozenDocumentLoader, jsonld

did_context_url = "https://www.w3.org/ns/did/v1"
did_context_file = Path("lib/pyld/documentloader/frozen/bundled/did-v1.jsonld")
loader = FrozenDocumentLoader(documents={did_context_url: did_context_file})

doc = {
    "@context": did_context_url,
    "id": "did:example:123",
    "authentication": ["did:example:123#key-1"],
}

expanded = jsonld.expand(doc, options={"documentLoader": loader})

Here, we assume that did-v1.jsonld is already downloaded and verified. Caching will be handled by a different DocumentLoader in pyld.

[BigBlueHat]

@anatoly-scherbakov for sure! Do you think a couple sub-issues off this one would be a good idea?

The "caching" one could center on updating the Best Practice that's there currently. The "Long term storage" one is net-new (for the Best Practices, at least), so we'd need to write that up.

If there's spec work to do here, it's probably around creating/defining a "URL | hash | document" storage/retrieval API for the documentLoader for use across remote and local "surfaces" with some guidance for when to pre-populate and update that local/long-term storage depending on various use cases.

However, most of what's missing looks to just be describing solutions already available and then seeing what we've missed or need to extend the @context value to contain.

[anatoly-scherbakov]

@BigBlueHat I have created a sibling sub-issue. I think it might help if we keep this structure flatter.

If there's spec work to do here, it's probably around creating/defining a "URL | hash | document" storage/retrieval API for the documentLoader for use across remote and local "surfaces" with some guidance for when to pre-populate and update that local/long-term storage depending on various use cases.

Do you think spec should cover this? In the pyld example above, we grant the user with full freedom as to how they want to pre-download contexts and vet them.

That's their security process, they might want to do, say, contexts audit and documentation before these contexts are allowed to be used in a control system governing a thermonuclear rocket engine of an interstellar space ship. ;)

[anatoly-scherbakov]

• Adding a PR
• Here is an example from pyld: https://digitalbazaar.github.io/pyld/document-loaders/frozen/

I think we cannot strictly exclude this particular alternative because air-gapped, highly secure systems exist and they have to work without any internet access at all. Bundled/vendored/vetted contexts will be the solution for them, I can see no other. Therefore, we should have such an alternative documented regardless of JSON-LD 1.2+ developments.