Repository navigation
Description
Context
Follow-up to #4615 / #4617. That fix bounds remote JSON-LD context fetches with a timeout and a failure cache. This issue removes the reason those fetches happen in the first place: in non-strict mode, the node fetches any context URL a credential refers to.
Problem
jsonld/jsonld.go builds the loader with NewContextLoader(!serverConfig.Strictmode, ...). When strict mode is off, NewContextLoader (jsonld/ldutils.go) skips the filteredDocumentLoader, so jsonld.contexts.remoteallowlist has no effect and every unknown context is fetched from the internet while the credential is verified.
- Untrusted input drives outbound requests. Credentials from the network and presentations received over HTTP choose the URLs.
- Verification depends on third-party servers. A slow or dead server stalls processing (bounded to 5 s by JSON-LD: time out remote context fetches and remember failures #4617). A changed context silently changes how credentials expand.
- Unbounded caching. json-gold's
CachingDocumentLoaderkeeps every successfully fetched URL forever. - Little value in practice. All default contexts are embedded. In a production DAG dump, the only two contexts that need a remote fetch both fail: one returns 404, the other never answers Go clients.
| Mode | Unlisted context today | Proposed (v7) |
|---|---|---|
| strict | rejected: context not on the remoteallowlist |
unchanged |
| non-strict | fetched from the internet | rejected: context not on the remoteallowlist |
Proposal
v7: always apply the allow list
NewContextLoaderalways wraps the chain infilteredDocumentLoader. Drop theallowUnlistedExternalCallsparameter.jsonld.gono longer passes!Strictmode.- Unlisted contexts end with
jsonld.ContextURLNotAllowedErr.vcr/ambassador.gohandleErroralready treats that as "ignored, finished", so the event is not retried. - Flag help in
jsonld/cmd.gochanges from "In strict mode, fetching external JSON-LD contexts is not allowed except for context-URLs listed here." to "Fetching external JSON-LD contexts is not allowed except for context-URLs listed here." - Docs:
docs/pages/deployment/verifiable-credentials.rst(fetching section) and the strict mode list indocs/pages/deployment/configuration.rst. - Release notes: breaking change, with the migration step below.
Migration for operators that use custom contexts without listing them: add the URL to jsonld.contexts.remoteallowlist, or pin it with jsonld.contexts.localmapping. Setting either list replaces the defaults, so the default entries must be repeated (see the note in the docs).
v6.x minor: deprecation warning
Before v7, log a warning when a non-strict node fetches a context that is not on the allow list, naming the URL and stating that v7 will require it to be listed. Log once per URL, not per credential. Master only, not backported to patch releases.
Scope
jsonld/ldutils.go(NewContextLoader),jsonld/jsonld.go,jsonld/cmd.go- Tests in
jsonld/ldutils_test.gothat construct the loader withtrue - Docs, release notes, the generated options table
Considerations
- Developer experience: trying out a custom credential type now needs one config entry. The error message already names the setting.
- After this change, strict mode no longer influences JSON-LD loading. The strict mode docs should drop the JSON-LD line rather than keep a misleading one.
Backport
None, master only (v7). The deprecation warning goes into the next 6.x minor release from master.
Related
- JSON-LD: remote context fetch has no timeout and no failure cache, a dead context server stalls network sync #4615: remote context fetch without timeout
- JSON-LD: time out remote context fetches and remember failures #4617: timeout and failure cache
Metadata
Metadata
Assignees
Labels
Type
Fields
Priority
Activity